basis/literals/literals-docs.factor

   1 ! Copyright (C) 2008 Joe Groff.
   2 ! See http://factorcode.org/license.txt for BSD license.
   3 USING: help.markup help.syntax kernel multiline sequences ;
   4 IN: literals
   5
   6 HELP: $
   7 { $syntax "$ word" }
   8 { $description "Executes " { $snippet "word" } " at parse time and adds the result(s) to the parser accumulator." }
   9 { $notes { $snippet "word" } "'s definition is looked up and " { $link call } "ed at parse time, so words that reference words in the current compilation unit cannot be used with " { $snippet "$" } "." }
  10 { $examples
  11     { $example
  12         "USING: kernel literals prettyprint ;"
  13         "IN: scratchpad"
  14         ""
  15         "CONSTANT: five 5"
  16         "{ $ five } ."
  17         "{ 5 }"
  18     }
  19     { $example
  20         "USING: kernel literals prettyprint ;"
  21         "IN: scratchpad"
  22         ""
  23         ": seven-eleven ( -- a b ) 7 11 ;"
  24         "{ $ seven-eleven } ."
  25         "{ 7 11 }"
  26     }
  27 } ;
  28
  29 HELP: $[
  30 { $syntax "$[ code ]" }
  31 { $description "Calls " { $snippet "code" } " at parse time and adds the result(s) to the parser accumulator." }
  32 { $notes "Since " { $snippet "code" } " is " { $link call } "ed at parse time, it cannot reference any words defined in the same compilation unit." }
  33 { $examples
  34     { $example
  35         "USING: kernel literals math prettyprint ;"
  36         "IN: scratchpad"
  37         ""
  38         "<< CONSTANT: five 5 >>"
  39         "{ $[ five dup 1 + dup 2 + ] } ."
  40         "{ 5 6 8 }"
  41     }
  42 } ;
  43
  44 HELP: ${
  45 { $syntax "${ code }" }
  46 { $description "Outputs an array containing the results of executing " { $snippet "code" } " at parse time." }
  47 { $notes { $snippet "code" } "'s definition is looked up and " { $link call } "ed at parse time, so words that reference words in the current compilation unit cannot be used with " { $snippet "$" } "." }
  48 { $examples
  49     { $example
  50         "USING: kernel literals math prettyprint ;"
  51         "IN: scratchpad"
  52         ""
  53         "CONSTANT: five 5"
  54         "CONSTANT: six 6"
  55         "${ five six 7 } ."
  56         "{ 5 6 7 }"
  57     }
  58 } ;
  59
  60 { POSTPONE: $ POSTPONE: $[ POSTPONE: ${ } related-words
  61
  62 HELP: flags{
  63 { $values { "values" sequence } }
  64 { $description "Constructs a constant flag value from a sequence of integers or words that output integers. The resulting constant is computed at parse-time, which makes this word as efficient as using a literal integer." }
  65 { $examples
  66     { $example
  67         "USING: literals kernel prettyprint ;"
  68         "IN: scratchpad"
  69         "CONSTANT: x 0x1"
  70         "flags{ 0x20 x 0b100 } .h"
  71         "25"
  72     }
  73 } ;
  74
  75
  76 ARTICLE: "literals" "Interpolating code results into literal values"
  77 "The " { $vocab-link "literals" } " vocabulary contains words to run code at parse time and insert the results into more complex literal values."
  78 { $example
  79     "USING: kernel literals math prettyprint ;"
  80     "IN: scratchpad"
  81     ""
  82     "<< CONSTANT: five 5 >>"
  83     "{ $ five $[ five dup 1 + dup 2 + ] } ."
  84     "{ 5 5 6 8 }"
  85 }
  86 { $subsections
  87     POSTPONE: $
  88     POSTPONE: $[
  89     POSTPONE: ${
  90 } ;
  91
  92 ABOUT: "literals"