core/inspector/inspector-docs.factor

   1 USING: help.markup help.syntax kernel classes io io.styles ;
   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 } { "flags" "an assoc" } }
  45 { $description "Print a tabular overview of the object."
  46 $nl
  47 "The assoc can contain any of the following keys:"
  48 { $list
  49     { { $link +number-rows+ } " - if set to a true value, every row of output will begin with a row number." }
  50     { { $link +editable+ } " - if set to a true value, keys and values will be editable in place, if the output stream supports it." }
  51     { { $link +sequence+ } " - if set to a true value, keys will not be printed, only values." }
  52 } }
  53 { $notes "This word is a factor of " { $link describe } " and " { $link inspect } "." } ;
  54
  55 HELP: inspector-stack
  56 { $var-description "If the inspector is running, this variable holds previously-inspected objects." } ;
  57
  58 HELP: &push
  59 { $values { "obj" object } }
  60 { $description "If the inspector is running, outputs the object currently being inspected." } ;
  61
  62 HELP: inspector
  63 { $values { "obj" object } }
  64 { $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 } "." } ;
  65
  66 HELP: inspect
  67 { $values { "obj" object } }
  68 { $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." } ;
  69
  70 HELP: &at
  71 { $values { "n" "a non-negative integer" } }
  72 { $description "Inspects the " { $snippet "n" } "th slot of the current object. Use " { $link &back } " to return." } ;
  73
  74 HELP: &put
  75 { $values { "value" object } { "n" "a non-negative integer" } }
  76 { $description "Sets the " { $snippet "n" } "th slot of the current object to the given value." }
  77 { $errors "Throws an error if the object does not support this operation." } ;
  78
  79 HELP: &add
  80 { $values { "value" object } { "key" object } }
  81 { $description "Adds a key/value pair to the current object." }
  82 { $errors "Throws an error if the object does not support this operation." } ;
  83
  84 HELP: &delete
  85 { $values { "n" "a non-negative integer" } }
  86 { $description "Deletes the " { $snippet "n" } "th slot from the current object." }
  87 { $errors "Throws an error if the object does not support this operation." } ;
  88
  89 HELP: &rename
  90 { $values { "key" object } { "n" "a non-negative integer" } }
  91 { $description "Changes the key of the " { $snippet "n" } "th slot of the current object." }
  92 { $errors "Throws an error if the object does not support this operation." } ;
  93
  94 HELP: &back
  95 { $description "Returns to the previously-inspected object." } ;
  96
  97 { &back &at &put &add &delete } related-words
  98
  99 HELP: me
 100 { $var-description "The currently inspected object." } ;
 101
 102 HELP: inspector-hook
 103 { $var-description "A quotation with stack effect " { $snippet "( obj -- )" } ", called by the inspector to display an overview of an object."
 104 $nl
 105 "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." } ;