basis/listener/listener-docs.factor

   1 USING: help.markup help.syntax kernel io system prettyprint continuations quotations ;
   2 IN: listener
   3
   4 ARTICLE: "listener-watch" "Watching variables in the listener"
   5 "The listener prints the concepts of the data and retain stacks after every expression. It can also print values of dynamic variables which are added to a watch list:"
   6 { $subsections visible-vars }
   7 "To add or remove a single variable:"
   8 { $subsections
   9     show-var
  10     hide-var
  11 }
  12 "To add and remove multiple variables:"
  13 { $subsections
  14     show-vars
  15     hide-vars
  16 }
  17 "Hiding all visible variables:"
  18 { $subsections hide-all-vars } ;
  19
  20 HELP: only-use-vocabs
  21 { $values { "vocabs" "a sequence of vocabulary specifiers" } }
  22 { $description "Replaces the current manifest's vocabulary search path with the given set of vocabularies." } ;
  23
  24 HELP: with-interactive-vocabs
  25 { $values { "quot" quotation } }
  26 { $description "Calls the quotation in a scope with an initial vocabulary search path consisting of all vocabularies from " { $link interactive-vocabs } ", and with the current vocabulary for new definitions set to " { $vocab-link "scratchpad" } "." }
  27 { $notes "This is the same initial search path as used by the " { $link "listener" } " tool." } ;
  28
  29 HELP: show-var
  30 { $values { "var" "a variable name" } }
  31 { $description "Adds a variable to the watch list; its value will be printed by the listener after every expression." } ;
  32
  33 HELP: show-vars
  34 { $values { "seq" "a sequence of variable names" } }
  35 { $description "Adds a sequence of variables to the watch list; their values will be printed by the listener after every expression." } ;
  36
  37 HELP: hide-var
  38 { $values { "var" "a variable name" } }
  39 { $description "Removes a variable from the watch list." } ;
  40
  41 HELP: hide-vars
  42 { $values { "seq" "a sequence of variable names" } }
  43 { $description "Removes a sequence of variables from the watch list." } ;
  44
  45 HELP: hide-all-vars
  46 { $description "Removes all variables from the watch list." } ;
  47
  48 ARTICLE: "listener" "The listener"
  49 "The listener evaluates Factor expressions read from a stream. The listener is the primary interface to the Factor runtime. Typically, you write Factor code in a text editor, then load it using the listener and test it."
  50 $nl
  51 "The classical first program can be run in the listener:"
  52 { $example "\"Hello, world\" print" "Hello, world" }
  53 "Multi-line expressions are supported:"
  54 { $example "{ 1 2 3 } [\n    .\n] each" "1\n2\n3" }
  55 "The listener knows when to expect more input by looking at the height of the stack. Parsing words such as " { $link POSTPONE: { } " leave elements on the parser stack, and corresponding words such as " { $link POSTPONE: } } " pop them."
  56 $nl
  57 "The listener will display the current contents of the datastack after every expression is evaluated. The listener can additionally watch dynamic variables:"
  58 { $subsections "listener-watch" }
  59 "To start a nested listener:"
  60 { $subsections listener }
  61 "To exit a listener, invoke the " { $link return } " word."
  62 $nl
  63 "Multi-line quotations can be read independently of the rest of the listener:"
  64 { $subsections read-quot } ;
  65
  66 ABOUT: "listener"
  67
  68 HELP: read-quot
  69 { $values { "quot/f" "a parsed quotation, or " { $link f } " indicating end of file" } }
  70 { $description "Reads a Factor expression which possibly spans more than one line from " { $link input-stream } ". Additional lines of input are read while the parser stack height is greater than one. Since structural parsing words push partial quotations on the stack, this will keep on reading input until all delimited parsing words are terminated." } ;
  71
  72 HELP: listener
  73 { $description "Prompts for expressions on " { $link input-stream } " and evaluates them until end of file is reached." } ;