basis/delegate/delegate-docs.factor

   1 USING: help.syntax help.markup delegate.private ;
   2 IN: delegate
   3
   4 HELP: define-protocol
   5 { $values { "protocol" "a word for the new protocol" } { "wordlist" "a sequence of words" } }
   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
  22     code ;" }
  23 { $values { "group" "a protocol, generic word or tuple class" } { "class" "a class" } { "code" "code to get the object to which the method should be forwarded" } }
  24 { $description "Declares that objects of " { $snippet "class" } " will delegate the generic words contained in " { $snippet "group" } " to the object returned by executing " { $snippet "code" } " with the original object as an input. " { $snippet "CONSULT:" } " will overwrite any existing methods on " { $snippet "class" } " for the members of " { $snippet "group" } ", but new methods can be added after the " { $snippet "CONSULT:" } " to override the delegation." } ;
  25
  26 HELP: BROADCAST:
  27 { $syntax "BROADCAST: group class
  28     code ;" }
  29 { $values { "group" "a protocol, generic word or tuple class" } { "class" "a class" } { "code" "code to get the sequence of objects to all of which the method should be forwarded" } }
  30 { $description "Declares that objects of " { $snippet "class" } " will delegate the generic words contained in " { $snippet "group" } " to every object in the sequence returned by executing " { $snippet "code" } " with the original object as an input. " { $snippet "BROADCAST:" } " will overwrite any existing methods on " { $snippet "class" } " for the members of " { $snippet "group" } ", but new methods can be added after the " { $snippet "BROADCAST:" } " to override the delegation. Every generic word in " { $snippet "group" } " must return no outputs; otherwise, a " { $link broadcast-words-must-have-no-outputs } " error will be raised." } ;
  31
  32 HELP: SLOT-PROTOCOL:
  33 { $syntax "SLOT-PROTOCOL: protocol-name slots... ;" }
  34 { $description "Defines a protocol consisting of reader and writer words for the listed slot names." } ;
  35
  36 { define-protocol POSTPONE: PROTOCOL: } related-words
  37
  38 { define-consult POSTPONE: BROADCAST: POSTPONE: CONSULT: } related-words
  39
  40 HELP: group-words
  41 { $values { "group" "a group" } { "words" "an array of words" } }
  42 { $description "Given a protocol or tuple class, this returns the corresponding generic words that this group contains." } ;
  43
  44 ARTICLE: "delegate" "Delegation"
  45 "The " { $vocab-link "delegate" } " vocabulary implements run-time consultation for method dispatch."
  46 $nl
  47 "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."
  48 $nl
  49 "Using this vocabulary, protocols can be defined and consultation can be set up without any repetitive boilerplate."
  50 $nl
  51 "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."
  52 $nl
  53 "Defining new protocols:"
  54 { $subsections
  55     POSTPONE: PROTOCOL:
  56     define-protocol
  57 }
  58 "Defining new protocols consisting of slot accessors:"
  59 { $subsections POSTPONE: SLOT-PROTOCOL: }
  60 "Defining consultation:"
  61 { $subsections
  62     POSTPONE: BROADCAST:
  63     POSTPONE: CONSULT:
  64     define-consult
  65 }
  66 "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" } ;
  67
  68 ABOUT: "delegate"