basis/fry/fry-docs.factor

   1 USING: help.markup help.syntax quotations kernel ;\r
   2 IN: fry\r
   3 \r
   4 HELP: ,\r
   5 { $description "Fry specifier. Inserts a literal value into the fried quotation." } ;\r
   6 \r
   7 HELP: @\r
   8 { $description "Fry specifier. Splices a quotation into the fried quotation." } ;\r
   9 \r
  10 HELP: _\r
  11 { $description "Fry specifier. Shifts all fry specifiers to the left down by one stack position." } ;\r
  12 \r
  13 HELP: fry\r
  14 { $values { "quot" quotation } { "quot'" quotation } }\r
  15 { $description "Outputs a quotation that when called, fries " { $snippet "quot" } " by taking values from the stack and substituting them in." }\r
  16 { $notes "This word is used to implement " { $link POSTPONE: '[ } "; the following two lines are equivalent:"\r
  17     { $code "[ X ] fry call" "'[ X ]" }\r
  18 } ;\r
  19 \r
  20 HELP: '[\r
  21 { $syntax "code... ]" }\r
  22 { $description "Literal fried quotation. Expands into code which takes values from the stack and substitutes them in place of the fry specifiers " { $link , } " and " { $link @ } "." }\r
  23 { $examples "See " { $link "fry.examples" } "." } ;\r
  24 \r
  25 ARTICLE: "fry.examples" "Examples of fried quotations"\r
  26 "The easiest way to understand fried quotations is to look at some examples."\r
  27 $nl\r
  28 "If a quotation does not contain any fry specifiers, then " { $link POSTPONE: '[ } " behaves just like " { $link POSTPONE: [ } ":"\r
  29 { $code "{ 10 20 30 } '[ . ] each" }\r
  30 "Occurrences of " { $link , } " on the left map directly to " { $link curry } ". That is, the following three lines are equivalent:"\r
  31 { $code \r
  32     "{ 10 20 30 } 5 '[ , + ] map"\r
  33     "{ 10 20 30 } 5 [ + ] curry map"\r
  34     "{ 10 20 30 } [ 5 + ] map"\r
  35 }\r
  36 "Occurrences of " { $link , } " in the middle of a quotation map to more complex quotation composition patterns. The following three lines are equivalent:"\r
  37 { $code \r
  38     "{ 10 20 30 } 5 '[ 3 , / ] map"\r
  39     "{ 10 20 30 } 5 [ 3 ] swap [ / ] curry compose map"\r
  40     "{ 10 20 30 } [ 3 5 / ] map"\r
  41 }\r
  42 "Occurrences of " { $link @ } " are simply syntax sugar for " { $snippet ", call" } ". The following four lines are equivalent:"\r
  43 { $code \r
  44     "{ 10 20 30 } [ sq ] '[ @ . ] each"\r
  45     "{ 10 20 30 } [ sq ] [ call . ] curry each"\r
  46     "{ 10 20 30 } [ sq ] [ . ] compose each"\r
  47     "{ 10 20 30 } [ sq . ] each"\r
  48 }\r
  49 "The " { $link , } " and " { $link @ } " specifiers may be freely mixed:"\r
  50 { $code\r
  51     "{ 8 13 14 27 } [ even? ] 5 '[ @ dup , ? ] map"\r
  52     "{ 8 13 14 27 } [ even? ] 5 [ dup ] swap [ ? ] curry 3compose map"\r
  53     "{ 8 13 14 27 } [ even? dup 5 ? ] map"\r
  54 }\r
  55 "Occurrences of " { $link _ } " have the effect of enclosing all code to their left in a quotation passed to " { $link dip } ". The following four lines are equivalent:"\r
  56 { $code \r
  57     "{ 10 20 30 } 1 '[ , _ / ] map"\r
  58     "{ 10 20 30 } 1 [ [ ] curry dip / ] curry map"\r
  59     "{ 10 20 30 } 1 [ swap / ] curry map"\r
  60     "{ 10 20 30 } [ 1 swap / ] map"\r
  61 }\r
  62 "For any quotation body " { $snippet "X" } ", the following two are equivalent:"\r
  63 { $code\r
  64     "[ [ X ] dip ]"\r
  65     "'[ X _ ]"\r
  66 }\r
  67 "Here are some built-in combinators rewritten in terms of fried quotations:"\r
  68 { $table\r
  69     { { $link literalize } { $snippet ": literalize '[ , ] ;" } }\r
  70     { { $link slip } { $snippet ": slip '[ @ , ] call ;" } }\r
  71     { { $link dip } { $snippet ": dip '[ @ _ ] call ;" } }\r
  72     { { $link curry } { $snippet ": curry '[ , @ ] ;" } }\r
  73     { { $link with } { $snippet ": with swapd '[ , _ @ ] ;" } }\r
  74     { { $link compose } { $snippet ": compose '[ @ @ ] ;" } }\r
  75     { { $link bi@ } { $snippet ": bi@ tuck '[ , @ , @ ] call ;" } }\r
  76 } ;\r
  77 \r
  78 ARTICLE: "fry.philosophy" "Fried quotation philosophy"\r
  79 "Fried quotations generalize quotation-building words such as " { $link curry } " and " { $link compose } ". They can clean up code with lots of currying and composition, particularly when quotations are nested:"\r
  80 { $code\r
  81     "'[ [ , key? ] all? ] filter"\r
  82     "[ [ key? ] curry all? ] curry filter"\r
  83 }\r
  84 "There is a mapping from fried quotations to lexical closures as defined in the " { $vocab-link "locals" } " vocabulary. Namely, a fried quotation is equivalent to a ``let'' form where each local binding is only used once, and bindings are used in the same order in which they are defined. The following two lines are equivalent:"\r
  85 { $code\r
  86     "'[ 3 , + 4 , / ]"\r
  87     "[let | a [ ] b [ ] | [ 3 a + 4 b / ] ]"\r
  88 }\r
  89 "The " { $link _ } " fry specifier has no direct analogue in " { $vocab-link "locals" } ", however closure conversion together with the " { $link dip } " combinator achieve the same effect:"\r
  90 { $code\r
  91     "'[ , 2 + , * _ / ]"\r
  92     "[let | a [ ] b [ ] | [ [ a 2 + b * ] dip / ] ]"\r
  93 } ;\r
  94 \r
  95 ARTICLE: "fry.limitations" "Fried quotation limitations"\r
  96 "As with " { $vocab-link "locals" } ", fried quotations cannot contain " { $link >r } " and " { $link r> } ". This is not a real limitation in practice, since " { $link dip } " can be used instead." ;\r
  97 \r
  98 ARTICLE: "fry" "Fried quotations"\r
  99 "A " { $emphasis "fried quotation" } " differs from a literal quotation in that when it is evaluated, instead of just pushing itself on the stack, it consumes zero or more stack values and inserts them into the quotation."\r
 100 $nl\r
 101 "Fried quotations are denoted with a special parsing word:"\r
 102 { $subsection POSTPONE: '[ }\r
 103 "Fried quotations contain zero or more " { $emphasis "fry specifiers" } ":"\r
 104 { $subsection , }\r
 105 { $subsection @ }\r
 106 { $subsection _ }\r
 107 "When a fried quotation is being evaluated, values are consumed from the stack and spliced into the quotation from right to left."\r
 108 { $subsection "fry.examples" }\r
 109 { $subsection "fry.philosophy" }\r
 110 { $subsection "fry.limitations" }\r
 111 "Quotations can also be fried without using a parsing word:"\r
 112 { $subsection fry } ;\r
 113 \r
 114 ABOUT: "fry"\r