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 $nl
   8 "Printing messages when a word is called or returns:"
   9 { $subsection watch }
  10 { $subsection watch-vars }
  11 "Starting the walker when a word is called:"
  12 { $subsection breakpoint }
  13 { $subsection breakpoint-if }
  14 "Timing words:"
  15 { $subsection reset-word-timing }
  16 { $subsection add-timing }
  17 { $subsection word-timing. }
  18 "All of the above words are implemented using a single combinator which applies a quotation to a word definition to yield a new definition:"
  19 { $subsection annotate } ;
  20
  21 ABOUT: "tools.annotations"
  22
  23 HELP: annotate
  24 { $values { "word" "a word" } { "quot" { $quotation "( word def -- def )" } } }
  25 { $description "Changes a word definition to the result of applying a quotation to the old definition." }
  26 { $notes "This word is used to implement " { $link watch } "." } ;
  27
  28 HELP: watch
  29 { $values { "word" word } }
  30 { $description "Annotates a word definition to print the data stack on entry and exit." } ;
  31
  32 { watch watch-vars reset } related-words
  33
  34 HELP: breakpoint
  35 { $values { "word" word } }
  36 { $description "Annotates a word definition to enter the single stepper when executed." } ;
  37
  38 HELP: breakpoint-if
  39 { $values { "quot" { $quotation "( -- ? )" } } { "word" word } }
  40 { $description "Annotates a word definition to enter the single stepper if the quotation yields true." } ;
  41
  42 HELP: annotate-methods
  43 { $values
  44      { "word" word } { "quot" quotation } }
  45 { $description "Annotates the word -- for generic words, all its methods -- with the quotation." } ;
  46
  47 HELP: reset
  48 { $values
  49      { "word" word } }
  50 { $description "Resets any annotations on a word." }
  51 { $notes "This word will remove a " { $link watch } "." } ;
  52
  53 HELP: watch-vars
  54 { $values
  55      { "word" word } { "vars" "a sequence of symbols" } }
  56 { $description "Annotates a word definition to print the " { $snippet "vars" } " upon entering the word. This word is useful for debugging." } ;
  57
  58 HELP: add-timing
  59 { $values { "word" word } }
  60 { $description "Adds timing code to a word, which records its total running time, including that of words it calls, on every invocation." }
  61 { $see-also "timing" "profiling" } ;
  62
  63 HELP: reset-word-timing
  64 { $description "Resets the word timing table." } ;
  65
  66 HELP: word-timing.
  67 { $description "Prints the word timing table." } ;