basis/ui/tools/walker/walker-docs.factor

   1 IN: ui.tools.walker\r
   2 USING: help.markup help.syntax ui.commands ui.operations\r
   3 ui.render tools.walker sequences ;\r
   4 \r
   5 ARTICLE: "ui-walker-step" "Stepping through code"\r
   6 "If the current position points to a word, the various stepping commands behave as follows:"\r
   7 { $list\r
   8     { { $link com-step } " executes the word and moves the current position one word further." }\r
   9     { { $link com-into } " enters the word's definition, unless it is a primitive, in which case it behaves like " { $link com-step } "." }\r
  10     { { $link com-out } " executes until the end of the current quotation." }\r
  11 }\r
  12 "If the current position points to a literal, the various stepping commands behave as follows:"\r
  13 { $list\r
  14     { { $link com-step } " pushes the literal on the data stack." }\r
  15     { { $link com-into } " pushes the literal. If it is a quotation, a breakpoint is inserted at the beginning of the quotation, and if it is an array of quotations, a breakpoint is inserted at the beginning of each quotation element." }\r
  16     { { $link com-out } " executes until the end of the current quotation." }\r
  17 }\r
  18 "The behavior of the " { $link com-into } " command is useful when debugging code using combinators. Instead of stepping into the definition of a combinator, which may be quite complex, you can set a breakpoint on the quotation and continue. For example, suppose the following quotation is being walked:"\r
  19 { $code "{ 10 20 30 } [ 3 + . ] each" }\r
  20 "If the current position is on the quotation and " { $link com-into } " is invoked, the following quotation is pushed on the stack:"\r
  21 { $code "[ break 3 + . ]" }\r
  22 "Invoking " { $link com-continue } " will continue execution until the breakpoint is hit, which in this case happens immediately. The stack can then be inspected to verify that the first element of the array, 10, was pushed. Invoking " { $link com-continue } " proceeds until the breakpoint is hit on the second iteration, at which time the top of the stack will contain the value 20. Invoking " { $link com-continue } " a third time will proceed on to the final iteration where 30 is at the top of the stack. Invoking " { $link com-continue } " again will end the walk of this code snippet, since no more iterations remain the quotation will never be called again and the breakpoint will not be hit."\r
  23 $nl\r
  24 "The " { $link com-back } " command travels backwards through time, and restore stacks. This does not undo side effects (modifying array entries, writing to files, formatting the hard drive, etc) and therefore can only be used reliably on referentially transparent code." ;\r
  25 \r
  26 ARTICLE: "breakpoints" "Setting breakpoints"\r
  27 "In addition to invoking the walker explicitly through the UI, it is possible to set breakpoints on words. See " { $link "tools.annotations" } "."\r
  28 $nl\r
  29 "Breakpoints can be inserted directly into code:"\r
  30 { $subsection break }\r
  31 "Note that because the walker calls various core library and UI words while rendering its own user interface, setting a breakpoint on a word such as " { $link append } " or " { $link draw-gadget } " will hang the UI." ;\r
  32 \r
  33 ARTICLE: "ui-walker" "UI walker"\r
  34 "The walker single-steps through quotations. To use the walker, enter a piece of code in the listener's input area and press " { $operation walk } "."\r
  35 $nl\r
  36 "Walkers are instances of " { $link walker-gadget } "."\r
  37 { $subsection "ui-walker-step" }\r
  38 { $subsection "breakpoints" }\r
  39 { $command-map walker-gadget "toolbar" } ;\r
  40 \r
  41 ABOUT: "ui-walker"\r