core/effects/effects-docs.factor

   1 USING: help.markup help.syntax math strings words kernel ;
   2 IN: effects
   3
   4 ARTICLE: "effect-declaration" "Stack effect declaration"
   5 "Stack effects of words must be declared, with the exception of words which only push literals on the stack."
   6 $nl
   7 "A stack effect declaration is written in parentheses and lists word inputs and outputs, separated by " { $snippet "--" } ". Here is an example:"
   8 { $synopsis sq }
   9 "Parameters which are quotations can be declared by suffixing the parameter name with " { $snippet ":" } " and then writing a nested stack effect declaration:"
  10 { $synopsis while }
  11 "Stack effect declarations are read in using a parsing word:"
  12 { $subsection POSTPONE: ( }
  13 "Stack elements in a stack effect are ordered so that the top of the stack is on the right side. Each value can be named by a data type or description. The following are some examples of value names:"
  14 { $table
  15     { { { $snippet "?" } } "a boolean" }
  16     { { { $snippet "<=>" } } { "an ordering sepcifier; see " { $link "order-specifiers" } } }
  17     { { { $snippet "elt" } } "an object which is an element of a sequence" }
  18     { { { $snippet "m" } ", " { $snippet "n" } } "an integer" }
  19     { { { $snippet "obj" } } "an object" }
  20     { { { $snippet "quot" } } "a quotation" }
  21     { { { $snippet "seq" } } "a sequence" }
  22     { { { $snippet "assoc" } } "an associative mapping" }
  23     { { { $snippet "str" } } "a string" }
  24     { { { $snippet "x" } ", " { $snippet "y" } ", " { $snippet "z" } } "a number" }
  25     { { $snippet "loc" } "a screen location specified as a two-element array holding x and y co-ordinates" }
  26     { { $snippet "dim" } "a screen dimension specified as a two-element array holding width and height values" }
  27     { { $snippet "*" } "when this symbol appears by itself in the list of outputs, it means the word unconditionally throws an error" }
  28 }
  29 "The stack effect inferencer verifies stack effect comments to ensure the correct number of inputs and outputs is listed. Value names are ignored; only their number matters. An error is thrown if a word's declared stack effect does not match its inferred stack effect. See " { $link "inference" } "." ;
  30
  31 ARTICLE: "effects" "Stack effects"
  32 "A " { $emphasis "stack effect declaration" } ", for example " { $snippet "( x y -- z )" } " denotes that an operation takes two inputs, with " { $snippet "y" } " at the top of the stack, and returns one output."
  33 $nl
  34 "Stack effects of words can be declared."
  35 { $subsection "effect-declaration" }
  36 "Stack effects are first-class, and words for working with them are found in the " { $vocab-link "effects" } " vocabulary."
  37 { $subsection effect }
  38 { $subsection effect? }
  39 "There is a literal syntax for stack objects. It is most often used with " { $link define-declared } "."
  40 { $subsection POSTPONE: (( }
  41 "Getting a word's declared stack effect:"
  42 { $subsection stack-effect }
  43 "Converting a stack effect to a string form:"
  44 { $subsection effect>string }
  45 "Comparing effects:"
  46 { $subsection effect-height }
  47 { $subsection effect<= }
  48 { $see-also "inference" } ;
  49
  50 ABOUT: "effects"
  51
  52 HELP: effect
  53 { $class-description "An object representing a stack effect. Holds a sequence of inputs, a sequence of outputs and a flag indicating if an error is thrown unconditionally." } ;
  54
  55 HELP: effect-height
  56 { $values { "effect" effect } { "n" integer } }
  57 { $description "Outputs the number of objects added to the data stack by the stack effect. This will be negative if the stack effect only removes objects from the stack." } ;
  58
  59 HELP: effect<=
  60 { $values { "eff1" effect } { "eff2" effect } { "?" "a boolean" } }
  61 { $description "Tests if " { $snippet "eff1" } " is substitutable for " { $snippet "eff2" } ". What this means is that both stack effects change the stack height by the same amount, the first takes a smaller or equal number of inputs as the second, and either both or neither one terminate execution by throwing an error." } ;
  62
  63 HELP: effect>string
  64 { $values { "obj" object } { "str" string } }
  65 { $description "Turns a stack effect object into a string mnemonic." }
  66 { $examples
  67     { $example "USING: effects io ;" "1 2 <effect> effect>string print" "( object -- object object )" }
  68 } ;
  69
  70 HELP: stack-effect
  71 { $values { "word" word } { "effect/f" { $maybe effect } } }
  72 { $description "Outputs the stack effect of a word; either a stack effect declared with " { $link POSTPONE: ( } ", or an inferred stack effect (see " { $link "inference" } "." } ;