basis/eval/eval-docs.factor

   1 IN: eval
   2 USING: help.markup help.syntax strings io effects parser
   3 listener vocabs.parser debugger combinators ;
   4
   5 HELP: (eval)
   6 { $values { "str" string } { "effect" effect } }
   7 { $description "Parses Factor source code from a string, and calls the resulting quotation, which must have the given stack effect." }
   8 { $notes "This word must be wrapped within " { $link with-file-vocabs } " or " { $link with-interactive-vocabs } ", since it assumes that the " { $link manifest } " variable is set in the current dynamic scope." }
   9 { $errors "Throws an error if the input is malformed, or if the evaluation itself throws an error." } ;
  10
  11 HELP: eval
  12 { $values { "str" string } { "effect" effect } }
  13 { $description "Parses Factor source code from a string, and calls the resulting quotation, which must have the given stack effect." }
  14 { $notes "The code string is parsed and called in a new dynamic scope with an initial vocabulary search path consisting of just the " { $snippet "syntax" } " vocabulary. The evaluated code can use " { $link "word-search-syntax" } " to alter the search path." }
  15 { $errors "Throws an error if the input is malformed, or if the evaluation itself throws an error." } ;
  16
  17 HELP: eval(
  18 { $syntax "eval( inputs -- outputs )" }
  19 { $description "Parses Factor source code from the string at the top of the stack, and calls the resulting quotation, which must have the given stack effect." }
  20 { $notes
  21     "This parsing word is just a slightly nicer syntax for " { $link eval } ". The following are equivalent:"
  22     { $code
  23         "eval( inputs -- outputs )"
  24         "( inputs -- outputs ) eval"
  25     }
  26 }
  27 { $errors "Throws an error if the input is malformed, or if the evaluation itself throws an error." } ;
  28
  29 HELP: eval-with-stack
  30 { $values { "str" string } }
  31 { $description "Parses Factor source code from " { $snippet "str" } ", and then calls the resulting quotation, printing the data stack if any objects are left." } ;
  32
  33 HELP: eval-with-stack>string
  34 { $values { "str" string } { "output" string } }
  35 { $description "Evaluates the Factor code in " { $snippet "str" } " with " { $link output-stream } " rebound to a string output stream, printing the data stack if any objects are left, then outputs the resulting string." } ;
  36
  37 HELP: eval>string
  38 { $values { "str" string } { "output" string } }
  39 { $description "Evaluates the Factor code in " { $snippet "str" } " with " { $link output-stream } " rebound to a string output stream, then outputs the resulting string. The code in the string must not take or leave any values on the stack." }
  40 { $errors "If the code throws an error, the error is caught, and the result of calling " { $link print-error } " on the error is returned." } ;
  41
  42 ARTICLE: "eval-vocabs" "Evaluating strings with a different vocabulary search path"
  43 "Strings passed to " { $link eval } " are always evaluated with an initial vocabulary search path consisting of just the " { $snippet "syntax" } " vocabulary. This is the same search path that source files start out with. This behavior can be customized by taking advantage of the fact that " { $link eval } " is composed from two simpler words:"
  44 { $subsections
  45     (eval)
  46     with-file-vocabs
  47 }
  48 "Code in the listener tool starts out with a different initial search path, with more vocabularies available by default. Strings of code can be evaluated in this search path by using " { $link (eval) } " with a different combinator:"
  49 { $subsections
  50     with-interactive-vocabs
  51 }
  52 "When using " { $link (eval) } ", the quotation passed to " { $link with-file-vocabs } " and " { $link with-interactive-vocabs } " can also make specific vocabularies available to the evaluated string. This is done by having the quotation change the run-time vocabulary search path prior to calling " { $link (eval) } ". For run-time analogues of the parse-time " { $link "word-search-syntax" } " see " { $link "word-search-parsing" } "."
  53 $nl
  54 "The vocabulary set used by " { $link with-interactive-vocabs } " can be altered by rebinding a dynamic variable:"
  55 { $subsections interactive-vocabs }
  56 { $heading "Example" }
  57 "In this example, a string is evaluated with a fictional " { $snippet "cad.objects" } " vocabulary in the search path by default, together with the listener's " { $link interactive-vocabs } "; the quotation is expected to produce a sequence on the stack:"
  58 { $code
  59     "USING: eval listener vocabs.parser ;
  60 [
  61     \"cad.objects\" use-vocab
  62     ( -- seq ) (eval)
  63 ] with-interactive-vocabs"
  64 }
  65 "Note that the search path in the outer code (set by the " { $link POSTPONE: USING: } " form) has no relation to the search path used when parsing the string parameter (this is determined by " { $link with-interactive-vocabs } " and " { $link use-vocab } ")." ;
  66
  67 ARTICLE: "eval" "Evaluating strings at run time"
  68 "The " { $vocab-link "eval" } " vocabulary implements support for evaluating strings of code dynamically."
  69 $nl
  70 "The main entry point is a parsing word, which wraps a library word:"
  71 { $subsections
  72     POSTPONE: eval(
  73     eval
  74 }
  75 "This pairing is analogous to that of " { $link POSTPONE: call( } " with " { $link call-effect } "."
  76 $nl
  77 "Advanced features:"
  78 { $subsections "eval-vocabs" eval>string }
  79 ;
  80
  81 ABOUT: "eval"