extra/variants/variants-docs.factor

   1 ! (c)2009 Joe Groff bsd license
   2 USING: arrays classes classes.singleton classes.tuple help.markup
   3 help.syntax kernel multiline slots quotations ;
   4 IN: variants
   5
   6 HELP: VARIANT:
   7 { $syntax "
   8 VARIANT: class-name
   9     singleton
  10     singleton
  11     tuple: { slot slot slot ... }
  12     .
  13     .
  14     .
  15     ; " }
  16 { $description "Defines " { $snippet "class-name" } " as a union of the following " { $link singleton-class } " and " { $link tuple-class } " definitions. Each " { $snippet "singleton" } " word is defined as a " { $snippet "singleton-class" } ", and each " { $snippet "tuple" } " word is defined as a " { $snippet "tuple-class" } " with the given set of " { $snippet "slot" } "s, using the same syntax for slot specifiers as " { $link POSTPONE: TUPLE: } ". Typed tuple slots can recursively reference the variant " { $snippet "class-name" } " being defined. For " { $snippet "tuple" } " types, a " { $link boa } " constructor word " { $snippet "<tuple>" } " is defined as well." }
  17 { $examples { $code "
  18 USING: kernel variants ;
  19 IN: scratchpad
  20
  21 VARIANT: list
  22     nil
  23     cons: { { first object } { rest list } }
  24     ;
  25 " } } ;
  26
  27 HELP: VARIANT-MEMBER:
  28 { $description "Defines a new member of a variant class without restricting such definitions to a single statement or source file. The variant class should be listed first, and the class member should follow." }
  29 { $examples { $code "
  30 USING: kernel variants ;
  31 IN: scratchpad
  32
  33 VARIANT: list ;
  34
  35 VARIANT-MEMBER: list nil ;
  36 VARIANT-MEMBER: list cons: { { first object } { rest list } } ;
  37 " } } ;
  38
  39 HELP: match
  40 { $values { "branches" array } }
  41 { $description "Dispatches on the type of the value on the top of the stack. If the type is a " { $link singleton-class } ", the corresponding quotation is called with the underlying stack unchanged. If the type is a " { $link tuple-class } ", the tuple slots are pushed onto the stack by order of arguments." }
  42 { $examples { $example "
  43 USING: kernel math prettyprint variants ;
  44 IN: scratchpad
  45
  46 VARIANT: list
  47     nil
  48     cons: { { first object } { rest list } }
  49     ;
  50
  51 : list-length ( list -- length )
  52     {
  53         { nil [ 0 ] }
  54         { cons [ nip list-length 1 + ] }
  55     } match ;
  56
  57 1 2 3 4 nil <cons> <cons> <cons> <cons> list-length .
  58 " "4" } } ;
  59
  60 HELP: unboa
  61 { $values { "class" class } }
  62 { $description "Decomposes a tuple of type " { $snippet "class" } " into its component slot values by order of arguments. The inverse of " { $link boa } "." } ;
  63
  64 HELP: variant-class
  65 { $class-description "This class comprises class names that have been defined with " { $link POSTPONE: VARIANT: } ". When a " { $snippet "variant-class" } " is used as the type of a specialized " { $link tuple } " slot, the variant's first member type is used as the default " { $link initial-value } "." } ;
  66
  67 { POSTPONE: VARIANT: variant-class match } related-words
  68
  69 ARTICLE: "variants" "Algebraic data types"
  70 "The " { $vocab-link "variants" } " vocabulary provides syntax and combinators for defining and manipulating algebraic data types."
  71 { $subsections
  72     POSTPONE: VARIANT:
  73     POSTPONE: VARIANT-MEMBER:
  74     variant-class
  75     match
  76 } ;
  77
  78 ABOUT: "variants"