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. Currently, this is only supported for " { $snippet "standard-combination" } " and " { $snippet "hook-combination" } " generics." }
  25 { $heading "Example" }
  26 "The following code creates an " { $snippet "example-theme" } " that makes the status bar text green instead of white, and delegates all other " { $snippet "theme-protocol" } " words to " { $snippet "dark-theme" } "." $nl
  27 { $code "USING: delegate ui.theme ;" "" "SINGLETON: example-theme" "CONSULT: theme-protocol example-theme dark-theme ;" "" "M: example-theme status-bar-foreground COLOR: green ;" } ;
  28
  29 HELP: BROADCAST:
  30 { $syntax "BROADCAST: group class
  31     code ;" }
  32 { $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" } }
  33 { $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." } ;
  34
  35 HELP: SLOT-PROTOCOL:
  36 { $syntax "SLOT-PROTOCOL: protocol-name slots... ;" }
  37 { $description "Defines a protocol consisting of reader and writer words for the listed slot names." } ;
  38
  39 { define-protocol POSTPONE: PROTOCOL: } related-words
  40
  41 { define-consult POSTPONE: BROADCAST: POSTPONE: CONSULT: } related-words
  42
  43 HELP: group-words
  44 { $values { "group" "a group" } { "words" "an array of words" } }
  45 { $description "Given a protocol or tuple class, this returns the corresponding generic words that this group contains." } ;
  46
  47 ARTICLE: "delegate" "Delegation"
  48 "The " { $vocab-link "delegate" } " vocabulary implements run-time consultation for method dispatch."
  49 $nl
  50 "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."
  51 $nl
  52 "Using this vocabulary, protocols can be defined and consultation can be set up without any repetitive boilerplate."
  53 $nl
  54 "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."
  55 $nl
  56 "Defining new protocols:"
  57 { $subsections
  58     POSTPONE: PROTOCOL:
  59     define-protocol
  60 }
  61 "Defining new protocols consisting of slot accessors:"
  62 { $subsections POSTPONE: SLOT-PROTOCOL: }
  63 "Defining consultation:"
  64 { $subsections
  65     POSTPONE: BROADCAST:
  66     POSTPONE: CONSULT:
  67     define-consult
  68 }
  69 "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" } ". Other vocabularies, like " { $vocab-link "ui.theme" } " also declare protocols." ;
  70
  71 ABOUT: "delegate"