extra/locals/locals-docs.factor

   1 USING: help.syntax help.markup kernel macros prettyprint
   2 memoize ;
   3 IN: locals
   4
   5 HELP: [|
   6 { $syntax "[| bindings... | body... ]" }
   7 { $description "A lambda abstraction. When called, reads stack values into the bindings from left to right; the body may then refer to these bindings." }
   8 { $examples
   9     { $example
  10         "USING: kernel locals math prettyprint ;"
  11         "IN: scratchpad"
  12         ":: adder ( n -- quot ) [| m | m n + ] ;"
  13         "3 5 adder call ."
  14         "8"
  15     }
  16 } ;
  17
  18 HELP: [let
  19 { $syntax "[let | binding1 [ value1... ]\n       binding2 [ value2... ]\n       ... |\n    body... ]" }
  20 { $description "Introduces a set of lexical bindings and evaluates the body. The values are evaluated in parallel, and may not refer to other bindings within the same " { $link POSTPONE: [let } " form; for Lisp programmers, this means that " { $link POSTPONE: [let } " is equivalent to the Lisp " { $snippet "let" } ", not " { $snippet "let*" } "." }
  21 { $examples
  22     { $example
  23         "USING: kernel locals math math.functions prettyprint sequences ;"
  24         "IN: scratchpad"
  25         ":: frobnicate ( n seq -- newseq )"
  26         "    [let | n' [ n 6 * ] |"
  27         "        seq [ n' gcd nip ] map ] ;"
  28         "6 { 36 14 } frobnicate ."
  29         "{ 36 2 }"
  30     }
  31 } ;
  32
  33 HELP: [let*
  34 { $syntax "[let* | binding1 [ value1... ]\n       binding2 [ value2... ]\n       ... |\n    body... ]" }
  35 { $description "Introduces a set of lexical bindings and evaluates the body. The values are evaluated sequentially, and may refer to previous bindings from the same " { $link POSTPONE: [let* } " form; for Lisp programmers, this means that " { $link POSTPONE: [let* } " is equivalent to the Lisp " { $snippet "let*" } ", not " { $snippet "let" } "." }
  36 { $examples
  37     { $example
  38         "USING: kernel locals math math.functions prettyprint sequences ;"
  39         "IN: scratchpad"
  40         ":: frobnicate ( n seq -- newseq )"
  41         "    [let* | a [ n 3 + ]"
  42         "            b [ a 4 * ] |"
  43         "        seq [ b / ] map ] ;"
  44         "1 { 32 48 } frobnicate ."
  45         "{ 2 3 }"
  46     }
  47 } ;
  48
  49 { POSTPONE: [let POSTPONE: [let* } related-words
  50
  51 HELP: [wlet
  52 { $syntax "[wlet | binding1 [ body1... ]\n        binding2 [ body2... ]\n        ... |\n     body... ]" }
  53 { $description "Introduces a set of lexically-scoped non-recursive local functions. The bodies may not refer to other bindings within the same " { $link POSTPONE: [wlet } " form; for Lisp programmers, this means that Factor's " { $link POSTPONE: [wlet } " is equivalent to the Lisp " { $snippet "flet" } ", not " { $snippet "labels" } "." }
  54 { $examples
  55     { $example
  56         "USING: locals math prettyprint sequences ;"
  57         "IN: scratchpad"
  58         ":: quuxify ( n seq -- newseq )"
  59         "    [wlet | add-n [| m | m n + ] |"
  60         "        seq [ add-n ] map ] ;"
  61         "2 { 1 2 3 } quuxify ."
  62         "{ 3 4 5 }"
  63     }
  64 } ;
  65
  66 HELP: ::
  67 { $syntax ":: word ( bindings... -- outputs... ) body... ;" }
  68 { $description "Defines a word with named inputs; it reads stack values into bindings from left to right, then executes the body with those bindings in lexical scope. Any " { $link POSTPONE: [| } ", " { $link POSTPONE: [let } " or " { $link POSTPONE: [wlet } " forms used in the body of the word definition are automatically closure-converted." }
  69 { $notes "The output names do not affect the word's behavior, however the compiler attempts to check the stack effect as with other definitions." }
  70 { $examples "See " { $link POSTPONE: [| } ", " { $link POSTPONE: [let } " and " { $link POSTPONE: [wlet } "." } ;
  71
  72 { POSTPONE: : POSTPONE: :: } related-words
  73
  74 HELP: MACRO::
  75 { $syntax "MACRO:: word ( bindings... -- outputs... ) body... ;" }
  76 { $description "Defines a macro with named inputs; it reads stack values into bindings from left to right, then executes the body with those bindings in lexical scope." }
  77 { $notes "The output names do not affect the word's behavior, however the compiler attempts to check the stack effect as with other definitions." } ;
  78
  79 { POSTPONE: MACRO: POSTPONE: MACRO:: } related-words
  80
  81 HELP: MEMO::
  82 { $syntax "MEMO:: word ( bindings... -- outputs... ) body... ;" }
  83 { $description "Defines a memoized word with named inputs; it reads stack values into bindings from left to right, then executes the body with those bindings in lexical scope." } ;
  84
  85 { POSTPONE: MEMO: POSTPONE: MEMO:: } related-words
  86
  87 ARTICLE: "locals-mutable" "Mutable locals"
  88 "In the list of bindings supplied to " { $link POSTPONE: :: } ", " { $link POSTPONE: [let } " or " { $link POSTPONE: [| } ", a mutable binding may be introduced by suffixing its named with " { $snippet "!" } ". Mutable bindings are read by giving their name as usual; the suffix is not part of the binding's name. To write to a mutable binding, use the binding's with the " { $snippet "!" } " suffix."
  89 $nl
  90 "Here is a example word which outputs a pair of quotations which increment and decrement an internal counter, and then return the new value. The quotations are closed over the counter and each invocation of the word yields new quotations with their unique internal counter:"
  91 { $code
  92     ":: counter ( -- )"
  93     "    [let | value! [ 0 ] |"
  94     "        [ value 1+ dup value! ]"
  95     "        [ value 1- dup value! ] ] ;"
  96 }
  97 "Mutable bindings are implemented in a manner similar to the ML language; each mutable binding is actually an immutable binding of a mutable cell (in Factor's case, a 1-element array); reading the binding automatically dereferences the array, and writing to the binding stores into the array."
  98 $nl
  99 "Unlike some languages such as Python and Java, writing to mutable locals in outer scopes is fully supported and has the expected semantics." ;
 100
 101 ARTICLE: "locals-limitations" "Limitations of locals"
 102 "The first limitation is that the " { $link >r } " and " { $link r> } " words may not be used together with locals. Instead, use the " { $link dip } " combinator."
 103 $nl
 104 "Another limitation is that closure conversion does not descend into arrays, hashtables or other types of literals. For example, the following does not work:"
 105 { $code
 106     ":: bad-cond-usage ( a -- ... )"
 107     "    {"
 108     "        { [ a 0 < ] [ ... ] }"
 109     "        { [ a 0 > ] [ ... ] }"
 110     "        { [ a 0 = ] [ ... ] }"
 111     "    } cond ;"
 112 } ;
 113
 114 ARTICLE: "locals" "Local variables and lexical closures"
 115 "The " { $vocab-link "locals" } " vocabulary implements lexical scope with full closures, both downward and upward. Mutable bindings are supported, including assignment to bindings in outer scope."
 116 $nl
 117 "Compile-time transformation is used to compile local variables to efficient code; prettyprinter extensions are defined so that " { $link see } " can display original word definitions with local variables and not the closure-converted concatenative code which results."
 118 $nl
 119 "Applicative word definitions where the inputs are named local variables:"
 120 { $subsection POSTPONE: :: }
 121 { $subsection POSTPONE: MEMO:: }
 122 { $subsection POSTPONE: MACRO:: }
 123 "Lexical binding forms:"
 124 { $subsection POSTPONE: [let }
 125 { $subsection POSTPONE: [let* }
 126 { $subsection POSTPONE: [wlet }
 127 "Lambda abstractions:"
 128 { $subsection POSTPONE: [| }
 129 "Additional topics:"
 130 { $subsection "locals-mutable" }
 131 { $subsection "locals-limitations" }
 132 "Locals complement dynamically scoped variables implemented in the " { $vocab-link "namespaces" } " vocabulary." ;
 133
 134 ABOUT: "locals"