basis/delegate/delegate-docs.factor

   1 USING: help.syntax help.markup ;
   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 or mimicry." } ;
  12
  13 { define-protocol POSTPONE: PROTOCOL: } related-words
  14
  15 HELP: define-consult
  16 { $values { "class" "a class" } { "group" "a protocol, generic word or tuple class" } { "quot" "a quotation" } }
  17 { $description "Defines a class to consult, using the given 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 { define-consult POSTPONE: CONSULT: } related-words
  26
  27 HELP: group-words
  28 { $values { "group" "a group" } { "words" "an array of words" } }
  29 { $description "Given a protocol or tuple class, this returns the corresponding generic words that this group contains." } ;
  30
  31 ARTICLE: { "delegate" "intro" } "Delegation"
  32 "The " { $vocab-link "delegate" } " vocabulary implements run-time consultation for method dispatch."
  33 $nl
  34 "Fundamental to the concept of " { $emphasis "protocols" } ", which are groups of tuple slot accessors, or groups of arbtirary generic words."
  35 $nl
  36 "This allows an object to implement a certain protocol by passing the method calls to another object."
  37 $nl
  38 "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."
  39 $nl
  40 "Fundamentally, a protocol is a word which has a method for " { $link group-words } ". One type of protocol is a tuple, which consists of the slot accessors. To define a protocol as a set of words, use"
  41 { $subsection POSTPONE: PROTOCOL: }
  42 { $subsection define-protocol }
  43 "The literal syntax and defining word are:"
  44 { $subsection POSTPONE: CONSULT: }
  45 { $subsection define-consult }
  46 "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" } ;
  47
  48 IN: delegate
  49 ABOUT: { "delegate" "intro" }