basis/tools/walker/walker-docs.factor

   1 IN: tools.walker
   2 USING: help.syntax help.markup tools.continuations sequences math words ;
   3
   4 HELP: breakpoint
   5 { $values { "word" word } }
   6 { $description "Annotates a word definition to enter the single stepper when executed." }
   7 { $examples
   8     { $unchecked-example "USE: tools.walker \\ sq breakpoint"
   9         ""
  10     }
  11 } ;
  12
  13 HELP: breakpoint-if
  14 { $values { "word" word } { "quot" { $quotation ( -- ? ) } } }
  15 { $description "Annotates a word definition to enter the single stepper if the quotation yields true. The quotation has access to the datastack as it exists just before " { $snippet "word" } " is called." }
  16 { $examples
  17     "Break if the input to sq is 3:"
  18     { $unchecked-example
  19         "USE: tools.walker \\ sq [ dup 3 = ] breakpoint-if"
  20         ""
  21     }
  22 } ;
  23
  24 HELP: B
  25 { $description "An alias for " { $link break } ", defined in the " { $vocab-link "syntax" } " vocabulary so that it is always available." } ;
  26
  27 HELP: B:
  28 { $description "A breakpoint for parsing words. When this word is executed, it copies the definition of the following parsing word, prepends a " { $link break } " to it so that it is the first word to be executed when the definition is called, and calls this new definition.\n\nWhen the walker tool opens, execution will still be inside " { $link POSTPONE: B: } ". To step out of B: and into the parsing word, do just that: jump out with O, then into with I." } ;
  29
  30 ARTICLE: "breakpoints" "Setting breakpoints"
  31 "In addition to invoking the walker explicitly through the UI, it is possible to set breakpoints on words using words in the " { $vocab-link "tools.walker" } " vocabulary."
  32 $nl
  33 "Annotating a word with a breakpoint (see " { $link "tools.annotations" } "):"
  34 { $subsections
  35     breakpoint
  36     breakpoint-if
  37 }
  38 "Breakpoints can be inserted directly into code:"
  39 { $subsections
  40     break
  41     POSTPONE: B
  42     POSTPONE: B:
  43 }
  44 "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 + } " will hang the UI." ;
  45
  46 ABOUT: "breakpoints"