core/make/make-docs.factor

   1 IN: make
   2 USING: help.markup help.syntax quotations sequences math.parser
   3 kernel ;
   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, oftena 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 suffix } " 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 an arbitrary-looking string or " { $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 sequences by holding an accumulator sequence in a variable. Storing the accumulator sequence in a variable rather than the stack may allow code to be written with less stack manipulation."
  41 $nl
  42 "Sequence construction is wrapped in a combinator:"
  43 { $subsection make }
  44 "Inside the quotation passed to " { $link make } ", several words accumulate values:"
  45 { $subsection , }
  46 { $subsection % }
  47 { $subsection # }
  48 "The accumulator sequence can be accessed directly from inside a " { $link make } ":"
  49 { $subsection building }
  50 { $example
  51   "USING: make math.parser ;"
  52   "[ \"Language #\" % CHAR: \\s , 5 # ] \"\" make print"
  53   "Language # 5"
  54 }
  55 { $subsection "make-philosophy" } ;
  56
  57 ABOUT: "namespaces-make"
  58
  59 HELP: building
  60 { $var-description "Temporary mutable growable sequence holding elements accumulated so far by " { $link make } "." } ;
  61
  62 HELP: make
  63 { $values { "quot" quotation } { "exemplar" sequence } { "seq" "a new sequence" } }
  64 { $description "Calls the quotation in a new " { $emphasis "dynamic scope" } ". The quotation and any words it calls can execute the " { $link , } " and " { $link % } " words to accumulate elements. When the quotation returns, all accumulated elements are collected into a sequence with the same type as " { $snippet "exemplar" } "." }
  65 { $examples { $example "USING: make prettyprint ;" "[ 1 , 2 , 3 , ] { } make ." "{ 1 2 3 }" } } ;
  66
  67 HELP: ,
  68 { $values { "elt" object } }
  69 { $description "Adds an element to the end of the sequence being constructed by " { $link make } "." } ;
  70
  71 HELP: %
  72 { $values { "seq" sequence } }
  73 { $description "Appends a sequence to the end of the sequence being constructed by " { $link make } "." } ;