basis/inspector/inspector-docs.factor

   1 USING: help.markup help.syntax kernel classes io io.styles mirrors ;
   2 IN: inspector
   3
   4 ARTICLE: "inspector" "The inspector"
   5 "The inspector displays a tabular view of an object and adds navigation and editing features. Inspector words are found in the " { $vocab-link "inspector" } " vocabulary."
   6 $nl
   7 "Starting the inspector:"
   8 { $subsection inspect }
   9 "The inspector supports a number of commands which operate on the most recently inspected object:"
  10 { $subsection &push }
  11 { $subsection &back }
  12 { $subsection &at }
  13 { $subsection &put }
  14 { $subsection &add }
  15 { $subsection &rename }
  16 { $subsection &delete }
  17 "A variable holding the current object:"
  18 { $subsection me }
  19 "A variable holding inspector history:"
  20 { $subsection inspector-stack }
  21 "A customization hook:"
  22 { $subsection inspector-hook }
  23 "A description of an object can be printed without starting the inspector:"
  24 { $subsection describe }
  25 { $subsection describe* } ;
  26
  27 ABOUT: "inspector"
  28
  29 HELP: value-editor
  30 { $values { "path" "a sequence of keys" } }
  31 { $description "Prettyprints the value at a path, and if the output stream supports it, a graphical gadget for editing the object." }
  32 { $notes "To learn about paths, see " { $link "mirrors" } "." } ;
  33
  34 { presented-path presented-printer value-editor } related-words
  35
  36 HELP: describe
  37 { $values { "obj" object } }
  38 { $description "Print a tabular overview of the object."
  39 $nl
  40 "For sequences and hashtables, this outputs the entries of the collection. For all other object types, slot names and values are shown." }
  41 { $examples { $code "global describe" } } ;
  42
  43 HELP: describe*
  44 { $values { "obj" object } { "mirror" mirror } { "keys" "a sequence of objects" } }
  45 { $description "Print a tabular overview of the object." }
  46 { $notes "This word is a factor of " { $link describe } " and " { $link inspect } "." } ;
  47
  48 HELP: inspector-stack
  49 { $var-description "If the inspector is running, this variable holds previously-inspected objects." } ;
  50
  51 HELP: &push
  52 { $values { "obj" object } }
  53 { $description "If the inspector is running, outputs the object currently being inspected." } ;
  54
  55 HELP: inspector
  56 { $values { "obj" object } }
  57 { $description "Starts a new inspector and prints a brief help message. If an inspector is already running, this starts a nested inspector. An alternative word that reuses the current inspector instance is " { $link inspect } "." } ;
  58
  59 HELP: inspect
  60 { $values { "obj" object } }
  61 { $description "If an inspector is already running, displays the slots of the object in the current inspector. If an inspector is not running, starts a new inspector." } ;
  62
  63 HELP: &at
  64 { $values { "n" "a non-negative integer" } }
  65 { $description "Inspects the " { $snippet "n" } "th slot of the current object. Use " { $link &back } " to return." } ;
  66
  67 HELP: &put
  68 { $values { "value" object } { "n" "a non-negative integer" } }
  69 { $description "Sets the " { $snippet "n" } "th slot of the current object to the given value." }
  70 { $errors "Throws an error if the object does not support this operation." } ;
  71
  72 HELP: &add
  73 { $values { "value" object } { "key" object } }
  74 { $description "Adds a key/value pair to the current object." }
  75 { $errors "Throws an error if the object does not support this operation." } ;
  76
  77 HELP: &delete
  78 { $values { "n" "a non-negative integer" } }
  79 { $description "Deletes the " { $snippet "n" } "th slot from the current object." }
  80 { $errors "Throws an error if the object does not support this operation." } ;
  81
  82 HELP: &rename
  83 { $values { "key" object } { "n" "a non-negative integer" } }
  84 { $description "Changes the key of the " { $snippet "n" } "th slot of the current object." }
  85 { $errors "Throws an error if the object does not support this operation." } ;
  86
  87 HELP: &back
  88 { $description "Returns to the previously-inspected object." } ;
  89
  90 { &back &at &put &add &delete } related-words
  91
  92 HELP: me
  93 { $var-description "The currently inspected object." } ;
  94
  95 HELP: inspector-hook
  96 { $var-description "A quotation with stack effect " { $snippet "( obj -- )" } ", called by the inspector to display an overview of an object."
  97 $nl
  98 "The default implementation calls " { $link describe } " which outputs on " { $link output-stream } ", but the graphical listener sets this variable so that calling " { $link inspect } " in the UI opens the graphical inspector." } ;