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 "A word for getting very brief descriptions of words and general objects:"
  27 { $subsection summary } ;
  28
  29 ABOUT: "inspector"
  30
  31 HELP: value-editor
  32 { $values { "path" "a sequence of keys" } }
  33 { $description "Prettyprints the value at a path, and if the output stream supports it, a graphical gadget for editing the object." }
  34 { $notes "To learn about paths, see " { $link "mirrors" } "." } ;
  35
  36 { presented-path presented-printer value-editor } related-words
  37
  38 HELP: describe
  39 { $values { "obj" object } }
  40 { $description "Print a tabular overview of the object."
  41 $nl
  42 "For sequences and hashtables, this outputs the entries of the collection. For all other object types, slot names and values are shown." }
  43 { $examples { $code "global describe" } } ;
  44
  45 HELP: describe*
  46 { $values { "obj" object } { "flags" "an assoc" } }
  47 { $description "Print a tabular overview of the object."
  48 $nl
  49 "The assoc can contain any of the following keys:"
  50 { $list
  51     { { $link +number-rows+ } " - if set to a true value, every row of output will begin with a row number." }
  52     { { $link +editable+ } " - if set to a true value, keys and values will be editable in place, if the output stream supports it." }
  53     { { $link +sequence+ } " - if set to a true value, keys will not be printed, only values." }
  54 } }
  55 { $notes "This word is a factor of " { $link describe } " and " { $link inspect } "." } ;
  56
  57 HELP: summary
  58 { $values { "object" object } { "string" "a string" } }
  59 { $contract "Outputs a brief description of the object." } ;
  60
  61 HELP: inspector-stack
  62 { $var-description "If the inspector is running, this variable holds previously-inspected objects." } ;
  63
  64 HELP: &push
  65 { $values { "obj" object } }
  66 { $description "If the inspector is running, outputs the object currently being inspected." } ;
  67
  68 HELP: inspector
  69 { $values { "obj" object } }
  70 { $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 } "." } ;
  71
  72 HELP: inspect
  73 { $values { "obj" object } }
  74 { $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." } ;
  75
  76 HELP: &at
  77 { $values { "n" "a non-negative integer" } }
  78 { $description "Inspects the " { $snippet "n" } "th slot of the current object. Use " { $link &back } " to return." } ;
  79
  80 HELP: &put
  81 { $values { "value" object } { "n" "a non-negative integer" } }
  82 { $description "Sets the " { $snippet "n" } "th slot of the current object to the given value." }
  83 { $errors "Throws an error if the object does not support this operation." } ;
  84
  85 HELP: &add
  86 { $values { "value" object } { "key" object } }
  87 { $description "Adds a key/value pair to the current object." }
  88 { $errors "Throws an error if the object does not support this operation." } ;
  89
  90 HELP: &delete
  91 { $values { "n" "a non-negative integer" } }
  92 { $description "Deletes the " { $snippet "n" } "th slot from the current object." }
  93 { $errors "Throws an error if the object does not support this operation." } ;
  94
  95 HELP: &rename
  96 { $values { "key" object } { "n" "a non-negative integer" } }
  97 { $description "Changes the key of the " { $snippet "n" } "th slot of the current object." }
  98 { $errors "Throws an error if the object does not support this operation." } ;
  99
 100 HELP: &back
 101 { $description "Returns to the previously-inspected object." } ;
 102
 103 { &back &at &put &add &delete } related-words
 104
 105 HELP: me
 106 { $var-description "The currently inspected object." } ;
 107
 108 HELP: inspector-hook
 109 { $var-description "A quotation with stack effect " { $snippet "( obj -- )" } ", called by the inspector to display an overview of an object."
 110 $nl
 111 "The default implementation calls " { $link describe } " which outputs on the " { $link stdio } " stream, but the graphical listener sets this variable so that calling " { $link inspect } " in the UI opens the graphical inspector." } ;