basis/delegate/delegate-docs.factor

   1 USING: help.syntax help.markup delegate.private ;
   2 IN: delegate
   3
   4 HELP: define-protocol
   5 { $values { "wordlist" "a sequence of words" } { "protocol" "a word for the new protocol" } }
   6 { $description "Defines a symbol as a protocol." }
   7 { $notes "Usually, " { $link POSTPONE: PROTOCOL: } " should be used instead. This is only for runtime use." } ;
   8
   9 HELP: PROTOCOL:
  10 { $syntax "PROTOCOL: protocol-name words... ;" }
  11 { $description "Defines an explicit protocol, which can be used as a basis for delegation." } ;
  12
  13 { define-protocol POSTPONE: PROTOCOL: } related-words
  14
  15 HELP: define-consult
  16 { $values { "consultation" consultation } }
  17 { $description "Defines a class to consult, using the quotation, on the generic words contained in the group." }
  18 { $notes "Usually, " { $link POSTPONE: CONSULT: } " should be used instead. This is only for runtime use." } ;
  19
  20 HELP: CONSULT:
  21 { $syntax "CONSULT: group class getter... ;" }
  22 { $values { "group" "a protocol, generic word or tuple class" } { "class" "a class" } { "getter" "code to get where the method should be forwarded" } }
  23 { $description "Defines a class to consult, using the given code, on the generic words contained in the group. This means that, when one of the words in the group is called on an object of this class, the quotation will be called, and then the generic word called again. If the getter is empty, this will cause an infinite loop. Consultation overwrites the existing methods, but others can be defined afterwards." } ;
  24
  25 HELP: SLOT-PROTOCOL:
  26 { $syntax "SLOT-PROTOCOL: protocol-name slots... ;" }
  27 { $description "Defines a protocol consisting of reader and writer words for the listed slot names." } ;
  28
  29 { define-protocol POSTPONE: PROTOCOL: } related-words
  30
  31 { define-consult POSTPONE: CONSULT: } related-words
  32
  33 HELP: group-words
  34 { $values { "group" "a group" } { "words" "an array of words" } }
  35 { $description "Given a protocol or tuple class, this returns the corresponding generic words that this group contains." } ;
  36
  37 ARTICLE: "delegate" "Delegation"
  38 "The " { $vocab-link "delegate" } " vocabulary implements run-time consultation for method dispatch."
  39 $nl
  40 "A " { $emphasis "protocol" } " is a collection of related generic words. An object is said to " { $emphasis "consult" } " another object if it implements a protocol by forwarding all methods onto the other object."
  41 $nl
  42 "Using this vocabulary, protocols can be defined and consulation can be set up without any repetitive boilerplate."
  43 $nl
  44 "Unlike " { $link "tuple-subclassing" } ", which expresses " { $emphasis "is-a" } " relationships by statically including the methods and slots of the superclass in all subclasses, consultation forwards generic word calls to another distinct object."
  45 $nl
  46 "Defining new protocols:"
  47 { $subsection POSTPONE: PROTOCOL: }
  48 { $subsection define-protocol }
  49 "Defining new protocols consisting of slot accessors:"
  50 { $subsection POSTPONE: SLOT-PROTOCOL: }
  51 "Defining consultation:"
  52 { $subsection POSTPONE: CONSULT: }
  53 { $subsection define-consult }
  54 "Every tuple class has an associated protocol consisting of all of its slot accessor methods. The " { $vocab-link "delegate.protocols" } " vocabulary defines formal protocols for the various informal protocols used in the Factor core, such as " { $link "sequence-protocol" } ", " { $link "assocs-protocol" } " or " { $link "stream-protocol" } ;
  55
  56 ABOUT: "delegate"