core/make/make-docs.factor

   1 IN: make
   2 USING: assocs help.markup help.syntax kernel math.parser
   3 quotations sequences ;
   4
   5 ARTICLE: "make-philosophy" "Make philosophy"
   6 { $heading "When to use make" }
   7 "Make is useful for complex sequence construction which is hard to express with sequence combinators and various combinations of utility words."
   8 $nl
   9 "For example, this example uses " { $link make } " and reads better than a version using utility words:"
  10 { $code "[ [ left>> , ] [ \"+\" % center>> % \"-\" % ] [ right>> , ] tri ] { } make" }
  11 "compare the above to"
  12 { $code "[ center>> \"+\" \"-\" surround ] [ left>> prefix ] [ right>> suffix ] tri" }
  13 "The first one has a similar shape to the eventual output array. The second one has an arbitrary structure and uses three different utilities. Furthermore, the second version also constructs two redundant intermediate sequences, and for longer sequences, this extra copying will outweigh any overhead " { $link make } " has due to its use of a dynamic variable to store the sequence being built."
  14 $nl
  15 "On the other hand, using " { $link make } " instead of a single call to " { $link surround } " is overkill. The below headings summarize the most important cases where other idioms are more appropriate than " { $link make } "."
  16 { $heading "Make versus combinators" }
  17 "Sometimes, usages of " { $link make } " are better expressed with " { $link "sequences-combinators" } ". For example, instead of calling a combinator with a quotation which executes " { $link , } " exactly once on each iteration, often a combinator encapsulating that specific idiom exists and can be used."
  18 $nl
  19 "For example,"
  20 { $code "[ [ 42 * , ] each ] { } make" }
  21 "is equivalent to"
  22 { $code "[ 42 * ] map" }
  23 "and"
  24 { $code "[ [ reverse % ] each ] \"\" make" }
  25 "is equivalent to"
  26 { $code "[ reverse ] map concat" }
  27 { $heading "Utilities for simple make patterns" }
  28 "Sometimes, an existing word already implements a specific " { $link make } " usage. For example, " { $link prefix } " is equivalent to the following, with the added caveat that the below example always outputs an array:"
  29 { $code "[ , % ] { } make" }
  30 "The existing utility words can in some cases express intent better than a bunch of " { $link , } " and " { $link % } "."
  31 { $heading "Constructing quotations" }
  32 "Simple quotation construction can often be accomplished using " { $link "fry" } " and " { $link "compositional-combinators" } "."
  33 $nl
  34 "For example,"
  35 { $code "[ 2 , , \\ + , ] [ ] make" }
  36 "is better expressed as"
  37 { $code "'[ 2 _ + ]" } ;
  38
  39 ARTICLE: "namespaces-make" "Making sequences with variables"
  40 "The " { $vocab-link "make" } " vocabulary implements a facility for constructing " { $link sequence } "s and " { $link assoc } "s by holding a collector object in a variable. Storing the collector object in a variable rather than the stack may allow code to be written with less stack manipulation."
  41 $nl
  42 "Object construction is wrapped in a combinator:"
  43 { $subsections make }
  44 "Inside the quotation passed to " { $link make } ", several words accumulate values:"
  45 { $subsections
  46     ,
  47     %
  48     #
  49 }
  50 "When making an " { $link assoc } ", you can use these words to add key/value pairs:"
  51 { $subsections
  52     ,,
  53     %%
  54 }
  55 "The collector object can be accessed directly from inside a " { $link make } ":"
  56 { $subsections building }
  57 { $example
  58   "USING: make math.parser ;"
  59   "[ \"Language #\" % CHAR: \\s , 5 # ] \"\" make print"
  60   "Language # 5"
  61 }
  62 { $subsections "make-philosophy" } ;
  63
  64 ABOUT: "namespaces-make"
  65
  66 HELP: building
  67 { $var-description "Temporary mutable growable sequence (or assoc) holding elements accumulated so far by " { $link make } "." } ;
  68
  69 HELP: make
  70 { $values { "quot" quotation } { "exemplar" sequence } { "seq" "a new sequence" } }
  71 { $description "Calls the quotation in a new dynamic scope with the " { $link building } " variable bound to a new resizable mutable sequence. The quotation and any words it calls can execute the " { $link , } " and " { $link % } " words to accumulate elements into a sequence (or " { $link ,, } " and " { $link %% } " into an assoc). When the quotation returns, all accumulated elements are collected into an object with the same type as " { $snippet "exemplar" } "." }
  72 { $examples
  73     { $example "USING: make prettyprint ;" "[ 1 , 2 , 3 , ] { } make ." "{ 1 2 3 }" }
  74     { $example "USING: make prettyprint ;" "[ 2 1 ,, 4 3 ,, ] H{ } make ." "H{ { 1 2 } { 3 4 } }" }
  75 } ;
  76
  77 HELP: ,
  78 { $values { "elt" object } }
  79 { $description "Adds an element to the end of the sequence being constructed by " { $link make } "." } ;
  80
  81 HELP: %
  82 { $values { "seq" sequence } }
  83 { $description "Appends a sequence to the end of the sequence being constructed by " { $link make } "." } ;
  84
  85 HELP: ,,
  86 { $values { "value" object } { "key" object } }
  87 { $description "Stores the key/value pair into the assoc being constructed by " { $link make } "." } ;
  88
  89 HELP: %%
  90 { $values { "assoc" assoc } }
  91 { $description "Adds all entries from " { $snippet "assoc" } " to the assoc being constructed by " { $link make } "." } ;