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 { $warning
  21     "Certain internal words, such as words in the " { $vocab-link "math" } ", " { $vocab-link "sequences" } " and UI vocabularies, cannot be annotated, since the annotated code may end up recursively invoking the word in question. This may crash or hang Factor. It is safest to only define annotations on your own words."
  22 } ;
  23
  24 ABOUT: "tools.annotations"
  25
  26 HELP: annotate
  27 { $values { "word" "a word" } { "quot" { $quotation "( old-def -- new-def )" } } }
  28 { $description "Changes a word definition to the result of applying a quotation to the old definition." }
  29 { $notes "This word is used to implement " { $link watch } "." } ;
  30
  31 HELP: watch
  32 { $values { "word" word } }
  33 { $description "Annotates a word definition to print the data stack on entry and exit." } ;
  34
  35 { watch watch-vars reset } related-words
  36
  37 HELP: breakpoint
  38 { $values { "word" word } }
  39 { $description "Annotates a word definition to enter the single stepper when executed." } ;
  40
  41 HELP: breakpoint-if
  42 { $values { "quot" { $quotation "( -- ? )" } } { "word" word } }
  43 { $description "Annotates a word definition to enter the single stepper if the quotation yields true." } ;
  44
  45 HELP: reset
  46 { $values
  47      { "word" word } }
  48 { $description "Resets any annotations on a word." }
  49 { $notes "This word will remove a " { $link watch } "." } ;
  50
  51 HELP: watch-vars
  52 { $values
  53      { "word" word } { "vars" "a sequence of symbols" } }
  54 { $description "Annotates a word definition to print the " { $snippet "vars" } " upon entering the word. This word is useful for debugging." } ;
  55
  56 HELP: add-timing
  57 { $values { "word" word } }
  58 { $description "Adds timing code to a word, which records its total running time, including that of words it calls, on every invocation." }
  59 { $see-also "timing" "profiling" } ;
  60
  61 HELP: reset-word-timing
  62 { $description "Resets the word timing table." } ;
  63
  64 HELP: word-timing.
  65 { $description "Prints the word timing table." } ;
  66
  67 HELP: cannot-annotate-twice
  68 { $error-description "Thrown when attempting to annotate a word that's already been annotated. If a word already has an annotation such as a watch or a breakpoint, you must first " { $link reset } " the word before adding another annotation." } ;