basis/fry/fry-docs.factor

   1 USING: help.markup help.syntax quotations kernel ;
   2 IN: fry
   3
   4 HELP: _
   5 { $description "Fry specifier. Inserts a literal value into the fried quotation." }
   6 { $examples "See " { $link "fry.examples" } "." } ;
   7
   8 HELP: @
   9 { $description "Fry specifier. Splices a quotation into the fried quotation." }
  10 { $examples "See " { $link "fry.examples" } "." } ;
  11
  12 HELP: fry
  13 { $values { "quot" quotation } { "quot'" quotation } }
  14 { $description "Outputs a quotation that when called, fries " { $snippet "quot" } " by taking values from the stack and substituting them in." }
  15 { $notes "This word is used to implement " { $link POSTPONE: '[ } "; the following two lines are equivalent:"
  16     { $code "[ X ] fry call" "'[ X ]" }
  17 }
  18 { $examples "See " { $link "fry.examples" } "." } ;
  19
  20 HELP: '[
  21 { $syntax "'[ code... ]" }
  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 @ } "." }
  23 { $examples "See " { $link "fry.examples" } "." } ;
  24
  25 HELP: >r/r>-in-fry-error
  26 { $error-description "Thrown by " { $link POSTPONE: '[ } " if the fried quotation contains calls to retain stack manipulation primitives." } ;
  27
  28 ARTICLE: "fry.examples" "Examples of fried quotations"
  29 "The easiest way to understand fried quotations is to look at some examples."
  30 $nl
  31 "If a quotation does not contain any fry specifiers, then " { $link POSTPONE: '[ } " behaves just like " { $link POSTPONE: [ } ":"
  32 { $code "{ 10 20 30 } '[ . ] each" }
  33 "Occurrences of " { $link _ } " on the left map directly to " { $link curry } ". That is, the following three lines are equivalent:"
  34 { $code
  35     "{ 10 20 30 } 5 '[ _ + ] map"
  36     "{ 10 20 30 } 5 [ + ] curry map"
  37     "{ 10 20 30 } [ 5 + ] map"
  38 }
  39 "Occurrences of " { $link _ } " in the middle of a quotation map to more complex quotation composition patterns. The following three lines are equivalent:"
  40 { $code
  41     "{ 10 20 30 } 5 '[ 3 _ / ] map"
  42     "{ 10 20 30 } 5 [ 3 ] swap [ / ] curry compose map"
  43     "{ 10 20 30 } [ 3 5 / ] map"
  44 }
  45 "Occurrences of " { $link @ } " are simply syntax sugar for " { $snippet "_ call" } ". The following four lines are equivalent:"
  46 { $code
  47     "{ 10 20 30 } [ sq ] '[ @ . ] each"
  48     "{ 10 20 30 } [ sq ] [ call . ] curry each"
  49     "{ 10 20 30 } [ sq ] [ . ] compose each"
  50     "{ 10 20 30 } [ sq . ] each"
  51 }
  52 "The " { $link _ } " and " { $link @ } " specifiers may be freely mixed, and the result is considerably more concise and readable than the version using " { $link curry } " and " { $link compose } " directly:"
  53 { $code
  54     "{ 8 13 14 27 } [ even? ] 5 '[ @ dup _ ? ] map"
  55     "{ 8 13 14 27 } [ even? ] 5 [ dup ] swap [ ? ] curry compose compose map"
  56     "{ 8 13 14 27 } [ even? dup 5 ? ] map"
  57 }
  58 "The following is a no-op:"
  59 { $code "'[ @ ]" }
  60 "Here are some built-in combinators rewritten in terms of fried quotations:"
  61 { $table
  62     { { $link literalize } { $snippet ": literalize '[ _ ] ;" } }
  63     { { $link curry } { $snippet ": curry '[ _ @ ] ;" } }
  64     { { $link compose } { $snippet ": compose '[ @ @ ] ;" } }
  65 } ;
  66
  67 ARTICLE: "fry.philosophy" "Fried quotation philosophy"
  68 "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:"
  69 { $code
  70     "'[ [ _ key? ] all? ] filter"
  71     "[ [ key? ] curry all? ] curry filter"
  72 }
  73 "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 " { $snippet "[| | ]" } " 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:"
  74 { $code
  75     "'[ 3 _ + 4 _ / ]"
  76     "[| a b | 3 a + 4 b / ]"
  77 } ;
  78
  79 ARTICLE: "fry" "Fried quotations"
  80 "The " { $vocab-link "fry" } " vocabulary implements " { $emphasis "fried quotation" } ". Conceptually, fried quotations are quotations with “holes” (more formally, " { $emphasis "fry specifiers" } "), and the holes are filled in when the fried quotation is pushed on the stack."
  81 $nl
  82 "Fried quotations are started by a special parsing word:"
  83 { $subsections POSTPONE: '[ }
  84 "There are two types of fry specifiers; the first can hold a value, and the second “splices” a quotation, as if it were inserted without surrounding brackets:"
  85 { $subsections
  86     _
  87     @
  88 }
  89 "The holes are filled in with the top of stack going in the rightmost hole, the second item on the stack going in the second hole from the right, and so on."
  90 { $subsections
  91     "fry.examples"
  92     "fry.philosophy"
  93 }
  94 "Fry is implemented as a parsing word which reads a quotation and scans for occurrences of " { $link _ } " and " { $link @ } "; these words are not actually executed, and doing so raises an error (this can happen if they're accidentally used outside of a fry)."
  95 $nl
  96 "Fried quotations can also be constructed without using a parsing word; this is useful when meta-programming:"
  97 { $subsections fry }
  98 "Fried quotations are an abstraction on top of the " { $link "compositional-combinators" } "; their use is encouraged over the combinators, because often the fry form is shorter and clearer than the combinator form." ;
  99
 100 ABOUT: "fry"