basis/listener/listener-docs.factor

   1 USING: continuations help.markup help.syntax io kernel parser
   2 prettyprint quotations system threads vocabs vocabs.loader ;
   3 IN: listener
   4
   5 ARTICLE: "listener-watch" "Watching variables in the listener"
   6 "The listener prints values of dynamic variables which are added to a watch list:"
   7 { $subsections visible-vars }
   8 "To add or remove a single variable:"
   9 { $subsections
  10     show-var
  11     hide-var
  12 }
  13 "To add and remove multiple variables:"
  14 { $subsections
  15     show-vars
  16     hide-vars
  17 }
  18 "Clearing the watch list:"
  19 { $subsections hide-all-vars } ;
  20
  21 HELP: use-loaded-vocabs
  22 { $values { "vocabs" "a sequence of vocabulary specifiers" } }
  23 { $description "Adds to the search path only those vocabularies which are loaded." } ;
  24
  25 HELP: with-interactive-vocabs
  26 { $values { "quot" quotation } }
  27 { $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" } "." }
  28 { $notes "This is the same initial search path as used by the " { $link "listener" } " tool." } ;
  29
  30 HELP: show-var
  31 { $values { "var" "a variable name" } }
  32 { $description "Adds a variable to the watch list; its value will be printed by the listener after every expression." } ;
  33
  34 HELP: show-vars
  35 { $values { "seq" "a sequence of variable names" } }
  36 { $description "Adds a sequence of variables to the watch list; their values will be printed by the listener after every expression." } ;
  37
  38 HELP: hide-var
  39 { $values { "var" "a variable name" } }
  40 { $description "Removes a variable from the watch list." } ;
  41
  42 HELP: hide-vars
  43 { $values { "seq" "a sequence of variable names" } }
  44 { $description "Removes a sequence of variables from the watch list." } ;
  45
  46 HELP: hide-all-vars
  47 { $description "Removes all variables from the watch list." } ;
  48
  49 ARTICLE: "listener" "The listener"
  50 "The listener evaluates Factor expressions read from the input stream. Typically, you write Factor code in a text editor, load it from the listener by calling " { $link require } ", " { $link reload } " or " { $link run-file } ", and then test it interactively."
  51 $nl
  52 "The classical first program can be run in the listener:"
  53 { $example "\"Hello, world\" print" "Hello, world" }
  54 "New words can also be defined in the listener:"
  55 { $example
  56     "USE: math.functions"
  57     ": twice ( word -- ) [ execute ] [ execute ] bi ; inline"
  58     "81 \\ sqrt twice ."
  59     "3.0"
  60 }
  61 "Multi-line expressions are supported:"
  62 { $example "{ 1 2 3 } [\n    .\n] each" "1\n2\n3" }
  63 "The listener will display the current contents of the datastack after every line of input."
  64 $nl
  65 "If your code runs too long, you can press C-Break to interrupt it (works only on Windows). To enable this feature, run the following code, or add it to your " { $link ".factor-rc" } ":"
  66 { $code
  67     "USING: listener namespaces ;"
  68     "t handle-ctrl-break set-global"
  69 }
  70 $nl
  71 "The listener can watch dynamic variables:"
  72 { $subsections "listener-watch" }
  73 "Nested listeners can be useful for testing code in other dynamic scopes. For example, when doing database maintenance using the " { $vocab-link "db.tuples" } " vocabulary, it can be useful to start a listener with a database connection:"
  74 { $code
  75     "USING: db db.sqlite listener ;"
  76     "\"data.db\" <sqlite-db> [ listener ] with-db"
  77 }
  78 "Starting a nested listener:"
  79 { $subsections listener }
  80 "To exit a listener, invoke the " { $link return } " word."
  81 $nl
  82 "The listener's mechanism for reading multi-line expressions from the input stream can be called from user code:"
  83 { $subsections read-quot } ;
  84
  85 HELP: handle-ctrl-break
  86 { $description "If this variable is " { $link t } ", the listener will wrap the user code with calls to " { $link enable-ctrl-break } " and " { $link disable-ctrl-break } " to make it interruptible with C-Break. This includes both compilation and execution phases, so circular vocab import can be interrupted as well as infinite loops."
  87 $nl
  88 "This only works on Windows, and has no effect on other platforms."
  89 { $warning "If user code " { $link yield } "s or gets stuck on an asynchronous I/O operation, pressing C-Break will most likely crash the Factor VM." } } ;
  90
  91 ABOUT: "listener"
  92
  93 HELP: read-quot
  94 { $values { "quot/f" "a parsed quotation, or " { $link f } " indicating end of file" } }
  95 { $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." } ;
  96
  97 HELP: listener
  98 { $description "Prompts for expressions on " { $link input-stream } " and evaluates them until end of file is reached." } ;