basis/stack-checker/errors/errors-docs.factor

   1 USING: help.markup help.syntax kernel effects sequences
   2 sequences.private words ;
   3 IN: stack-checker.errors
   4
   5 HELP: literal-expected
   6 { $error-description "Thrown when inference encounters a " { $link call } " or " { $link if } " being applied to a value which is not known to be a literal. Such a form can have an arbitrary stack effect, and does not compile." }
   7 { $notes "This error will be thrown when compiling any combinator, such as " { $link each } ". However, words calling combinators can compile if the combinator is declared " { $link POSTPONE: inline } " and the quotation being passed in is a literal." }
   8 { $examples
   9     "In this example, words calling " { $snippet "literal-expected-example" } " will compile, even if " { $snippet "literal-expected-example" } " does not compile itself:"
  10     { $code
  11         ": literal-expected-example ( quot -- )"
  12         "    [ call ] [ call ] bi ; inline"
  13     }
  14 } ;
  15
  16 HELP: unbalanced-branches-error
  17 { $values { "in" "a sequence of integers" } { "out" "a sequence of integers" } }
  18 { $description "Throws an " { $link unbalanced-branches-error } "." }
  19 { $error-description "Thrown when inference encounters an " { $link if } " or " { $link dispatch } " where the branches do not all exit with the same stack height." }
  20 { $notes "Conditionals with variable stack effects are considered to be bad style and should be avoided since they do not compile."
  21 $nl
  22 "If this error comes up when inferring the stack effect of a recursive word, check the word's stack effect declaration; it might be wrong." }
  23 { $examples
  24     { $code
  25         ": unbalanced-branches-example ( a b c -- )"
  26         "    [ + ] [ dup ] if ;"
  27     }
  28 } ;
  29
  30 HELP: too-many->r
  31 { $error-description "Thrown if inference notices a quotation pushing elements on the retain stack without popping them at the end." }
  32 { $examples
  33     { $code
  34         ": too-many->r-example ( a b -- )"
  35         "    >r 3 + >r ;"
  36     }
  37 } ;
  38
  39 HELP: too-many-r>
  40 { $error-description "Thrown if inference notices a quotation popping elements from the return stack it did not place there." }
  41 { $examples
  42     { $code
  43         ": too-many-r>-example ( a b -- )"
  44         "    r> 3 + >r ;"
  45     }
  46 } ;
  47
  48 HELP: missing-effect
  49 { $error-description "Thrown when inference encounters a word lacking a stack effect declaration. Stack effects of words must be declared, with the exception of words which only push literals on the stack." }
  50 { $examples
  51     { $code
  52         ": missing-effect-example"
  53         "    + * ;"
  54     }
  55 } ;
  56
  57 HELP: effect-error
  58 { $values { "word" word } { "effect" "an instance of " { $link effect } } }
  59 { $description "Throws an " { $link effect-error } "." }
  60 { $error-description "Thrown when a word's inferred stack effect does not match its declared stack effect." } ;
  61
  62 HELP: recursive-quotation-error
  63 { $error-description "Thrown when a quotation calls itself, directly or indirectly, within the same word. Stack effect inference becomes equivalent to the halting problem if quotation recursion has to be taken into account, hence it is not permitted." }
  64 { $examples
  65     "Here is an example of quotation recursion:"
  66     { $code "[ [ dup call ] dup call ] infer." }
  67 } ;
  68
  69 HELP: undeclared-recursion-error
  70 { $error-description "Thrown when an " { $link POSTPONE: inline } " word which is not declared " { $link POSTPONE: recursive } " calls itself, directly or indirectly. The " { $link POSTPONE: recursive } " declaration is mandatory for such words." } ;
  71
  72 HELP: diverging-recursion-error
  73 { $error-description "Thrown when stack effect inference determines that a recursive word might take an arbitrary number of values from the stack." }
  74 { $notes "Such words do not have a static stack effect and most likely indicate programmer error." }
  75 { $examples
  76     { $code
  77         ": diverging-recursion-example ( -- )"
  78         "    [ diverging-recursion-example f ] when ; inline recursive"
  79     }
  80 } ;
  81
  82 HELP: unbalanced-recursion-error
  83 { $error-description "Thrown when stack effect inference determines that an inline recursive word has an incorrect stack effect declaration." }
  84 { $examples
  85     { $code
  86         ": unbalanced-recursion-example ( quot: ( -- ? ) -- b )"
  87         "    dup call [ unbalanced-recursion-example ] [ drop ] if ;"
  88         "    inline recursive"
  89     }
  90 } ;
  91
  92 HELP: inconsistent-recursive-call-error
  93 { $error-description "Thrown when stack effect inference determines that an inline recursive word calls itself with a different set of quotation parameters than were input." }
  94 { $examples
  95     { $code
  96         ": inconsistent-recursive-call-example ( quot: ( -- ? ) -- b )"
  97         "    [ not ] compose inconsistent-recursive-call-example ; inline recursive"
  98     }
  99 } ;
 100
 101 ARTICLE: "inference-errors" "Inference warnings and errors"
 102 "Main wrapper for all inference warnings and errors:"
 103 { $subsection inference-error }
 104 "Inference warnings:"
 105 { $subsection literal-expected }
 106 "Inference errors:"
 107 { $subsection recursive-quotation-error }
 108 { $subsection unbalanced-branches-error }
 109 { $subsection effect-error }
 110 { $subsection missing-effect }
 111 "Inference errors for inline recursive words:"
 112 { $subsection undeclared-recursion-error }
 113 { $subsection diverging-recursion-error }
 114 { $subsection unbalanced-recursion-error }
 115 { $subsection inconsistent-recursive-call-error }
 116 "Retain stack usage errors:"
 117 { $subsection too-many->r }
 118 { $subsection too-many-r> } ;
 119
 120 ABOUT: "inference-errors"