basis/listener/listener-docs.factor

   1 USING: help.markup help.syntax kernel io system prettyprint ;
   2 IN: listener
   3
   4 ARTICLE: "listener" "The listener"
   5 "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."
   6 $nl
   7 "The classical first program can be run in the listener:"
   8 { $example "\"Hello, world\" print" "Hello, world" }
   9 "Multi-line phrases are supported:"
  10 { $example "{ 1 2 3 } [\n    .\n] each" "1\n2\n3" }
  11 "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."
  12 $nl
  13 "A very common operation is to inspect the contents of the data stack in the listener:"
  14 { $subsection .s }
  15 "Note that calls to " { $link .s } " can also be included inside words as a debugging aid, however a more convenient way to achieve this is to use the annotation facility. See " { $link "tools.annotations" } "."
  16 $nl
  17 "You can start a nested listener or exit a listener using the following words:"
  18 { $subsection listener }
  19 { $subsection bye }
  20 "The following variables can be rebound inside a nested scope to customize the behavior of a listener; this can be done to create a development tool with a custom interaction loop:"
  21 { $subsection listener-hook }
  22 "Finally, the multi-line expression reading word can be used independently of the rest of the listener:"
  23 { $subsection read-quot } ;
  24
  25 ABOUT: "listener"
  26
  27 HELP: quit-flag
  28 { $var-description "Variable set to true by " { $link bye } " word; it forces the next iteration of the " { $link listener } " loop to end." } ;
  29
  30 HELP: listener-hook
  31 { $var-description "Variable holding a quotation called by the listener before reading an input expression. The UI sets this variable to a quotation which updates the stack display in a listener gadget." } ;
  32
  33 HELP: read-quot
  34 { $values { "quot/f" "a parsed quotation, or " { $link f } " indicating end of file" } }
  35 { $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." } ;
  36
  37 HELP: listen
  38 { $description "Prompts for an expression on " { $link input-stream } " and evaluates it. On end of file, " { $link quit-flag } " is set to terminate the listener loop." }
  39 { $errors "If the expression input by the user throws an error, the error is printed to " { $link output-stream } " and the word returns normally." } ;
  40
  41 HELP: listener
  42 { $description "Prompts for expressions on " { $link input-stream } " and evaluates them until end of file is reached." } ;
  43
  44 HELP: bye
  45 { $description "Exits the current listener." }
  46 { $notes "This word is for interactive use only. To exit the Factor runtime, use " { $link exit } "." } ;