basis/tools/annotations/annotations-docs.factor

   1 USING: help.markup help.syntax words parser quotations strings
   2 system sequences ;
   3 IN: tools.annotations
   4
   5 ARTICLE: "tools.annotations" "Word annotations"
   6 "The word annotation feature modifies word definitions to add debugging code. You can restore the old definition by calling " { $link reset } " on the word in question."
   7 { $subsection watch }
   8 { $subsection breakpoint }
   9 { $subsection breakpoint-if }
  10 "All of the above words are implemented using a single combinator which applies a quotation to a word definition to yield a new definition:"
  11 { $subsection annotate } ;
  12
  13 ABOUT: "tools.annotations"
  14
  15 HELP: annotate
  16 { $values { "word" "a word" } { "quot" "a quotation with stack effect " { $snippet "( word def -- def )" } } }
  17 { $description "Changes a word definition to the result of applying a quotation to the old definition." }
  18 { $notes "This word is used to implement " { $link watch } "." } ;
  19
  20 HELP: watch
  21 { $values { "word" word } }
  22 { $description "Annotates a word definition to print the data stack on entry and exit." } ;
  23
  24 { watch watch-vars reset } related-words
  25
  26 HELP: breakpoint
  27 { $values { "word" word } }
  28 { $description "Annotates a word definition to enter the single stepper when executed." } ;
  29
  30 HELP: breakpoint-if
  31 { $values { "quot" "a quotation with stack effect" { $snippet "( -- ? )" } } { "word" word } }
  32 { $description "Annotates a word definition to enter the single stepper if the quotation yields true." } ;
  33
  34 HELP: annotate-methods
  35 { $values
  36      { "word" word } { "quot" quotation } }
  37 { $description "Annotates the word -- for generic words, all its methods -- with the quotation." } ;
  38
  39 HELP: entering
  40 { $values
  41      { "str" string } }
  42 { $description "Prints a message and the inputs to the word before the word has been called." } ;
  43
  44 HELP: leaving
  45 { $values
  46      { "str" string } }
  47 { $description "Prints a message and the outputs from a word after a word has been called." } ;
  48
  49 HELP: reset
  50 { $values
  51      { "word" word } }
  52 { $description "Resets any annotations on a word." }
  53 { $notes "This word will remove a " { $link watch } "." } ;
  54
  55 HELP: watch-vars
  56 { $values
  57      { "word" word } { "vars" "a sequence of symbols" } }
  58 { $description "Annotates a word definition to print the " { $snippet "vars" } " upon entering the word. This word is useful for debugging." } ;
  59
  60 HELP: word-inputs
  61 { $values
  62      { "word" word }
  63      { "seq" sequence } }
  64 { $description "Makes a sequence of the inputs to a word by counting the number of inputs in the stack effect and saving that many items from the datastack." } ;
  65