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 combinator or macro being applied to a value which is not known to be a literal, or constructed in a manner which can be analyzed statically. Such code needs changes before it can compile and run. See " { $link "inference-combinators" } " and " { $link "inference-escape" } " for details." }
   7 { $examples
   8     "In this example, words calling " { $snippet "literal-expected-example" } " will have a static stac keffect, even if " { $snippet "literal-expected-example" } " does not:"
   9     { $code
  10         ": literal-expected-example ( quot -- )"
  11         "    [ call ] [ call ] bi ; inline"
  12     }
  13 } ;
  14
  15 HELP: unbalanced-branches-error
  16 { $values { "in" "a sequence of integers" } { "out" "a sequence of integers" } }
  17 { $description "Throws an " { $link unbalanced-branches-error } "." }
  18 { $error-description "Thrown when inference encounters an " { $link if } " or " { $link dispatch } " where the branches do not all exit with the same stack height. See " { $link "inference-branches" } " for details." }
  19 { $notes "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." }
  20 { $examples
  21     { $code
  22         ": unbalanced-branches-example ( a b c -- )"
  23         "    [ + ] [ dup ] if ;"
  24     }
  25 } ;
  26
  27 HELP: too-many->r
  28 { $error-description "Thrown if inference notices a quotation pushing elements on the retain stack without popping them at the end." } ;
  29
  30 HELP: too-many-r>
  31 { $error-description "Thrown if inference notices a quotation popping elements from the return stack it did not place there." } ;
  32
  33 HELP: missing-effect
  34 { $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." }
  35 { $examples
  36     { $code
  37         ": missing-effect-example"
  38         "    + * ;"
  39     }
  40 } ;
  41
  42 HELP: effect-error
  43 { $values { "word" word } { "effect" "an instance of " { $link effect } } }
  44 { $description "Throws an " { $link effect-error } "." }
  45 { $error-description "Thrown when a word's inferred stack effect does not match its declared stack effect." } ;
  46
  47 HELP: recursive-quotation-error
  48 { $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." }
  49 { $examples
  50     "Here is an example of quotation recursion:"
  51     { $code "[ [ dup call ] dup call ] infer." }
  52 } ;
  53
  54 HELP: undeclared-recursion-error
  55 { $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." } ;
  56
  57 HELP: diverging-recursion-error
  58 { $error-description "Thrown when stack effect inference determines that a recursive word might take an arbitrary number of values from the stack." }
  59 { $notes "Such words do not have a static stack effect and most likely indicate programmer error." }
  60 { $examples
  61     { $code
  62         ": diverging-recursion-example ( -- )"
  63         "    [ diverging-recursion-example f ] when ; inline recursive"
  64     }
  65 } ;
  66
  67 HELP: unbalanced-recursion-error
  68 { $error-description "Thrown when stack effect inference determines that an inline recursive word has an incorrect stack effect declaration." }
  69 { $examples
  70     { $code
  71         ": unbalanced-recursion-example ( quot: ( -- ? ) -- b )"
  72         "    dup call [ unbalanced-recursion-example ] [ drop ] if ;"
  73         "    inline recursive"
  74     }
  75 } ;
  76
  77 HELP: inconsistent-recursive-call-error
  78 { $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." }
  79 { $examples
  80     { $code
  81         ": inconsistent-recursive-call-example ( quot: ( -- ? ) -- b )"
  82         "    [ not ] compose inconsistent-recursive-call-example ; inline recursive"
  83     }
  84 } ;
  85
  86 ARTICLE: "inference-errors" "Stack checker errors"
  87 "These " { $link "inference" } " failure conditions are reported in one of two ways:"
  88 { $list
  89     { { $link "tools.inference" } " throws them as errors" }
  90     { "The " { $link "compiler" } " reports them via " { $link "tools.errors" } }
  91 }
  92 "Error thrown when insufficient information is available to calculate the stack effect of a combinator call (see " { $link "inference-combinators" } "):"
  93 { $subsection literal-expected }
  94 "Error thrown when a word's stack effect declaration does not match the composition of the stack effects of its factors:"
  95 { $subsection effect-error }
  96 "Error thrown when branches have incompatible stack effects (see " { $link "inference-branches" } "):"
  97 { $subsection unbalanced-branches-error }
  98 "Inference errors for inline recursive words (see " { $link "inference-recursive-combinators" } "):"
  99 { $subsection undeclared-recursion-error }
 100 { $subsection diverging-recursion-error }
 101 { $subsection unbalanced-recursion-error }
 102 { $subsection inconsistent-recursive-call-error }
 103 "More obscure errors that are unlikely to arise in ordinary code:"
 104 { $subsection recursive-quotation-error }
 105 { $subsection too-many->r }
 106 { $subsection too-many-r> }
 107 { $subsection missing-effect } ;
 108
 109 ABOUT: "inference-errors"