IN: inference
USING: compiler help kernel sequences ;

HELP: inference-error
{ $values { "msg" "an object" } }
{ $description "Throws an " { $link inference-error } "." }
{ $error-description
    "Thrown by " { $link infer } ", " { $link dataflow } " and " { $link compile } " when the stack effect of a quotation cannot be inferred."
    $terpri
    "This error always delegates to one of the following classes of errors, which indicate the specific issue preventing a stack effect from being inferred:"
    { $list
        { $link no-effect }
        { $link literal-expected }
        { $link too-many->r }
        { $link too-many-r> }
        { $link unbalanced-branches-error }
        { $link effect-error }
        { $link recursive-declare-error }
    }
} ;

HELP: literal-expected
{ $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." }
{ $notes "This error will be thrown when compiling any combinator, such as " { $link each } ". However, words calling combinators can compile of the combinator is declared " { $link POSTPONE: inline } " and the quotation being passed in is a literal." } ;

HELP: terminated?
{ $var-description "During inference, a flag set to " { $link t } " if the current control flow path unconditionally throws an error." } ;

HELP: too-many->r
{ $error-description "Thrown if inference notices a quotation pushing elements on the retain stack without popping them at the end." }
{ $notes "See " { $link "shuffle-words" } " for retain stack usage conventions." } ;

HELP: too-many-r>
{ $error-description "Thrown if inference notices a quotation popping elements from the return stack it did not place there." }
{ $notes "See " { $link "shuffle-words" } " for retain stack usage conventions." } ;

HELP: infer
{ $values { "quot" "a quotation" } { "effect" "a pair of integers" } }
{ $description "Attempts to infer the quotation's stack effect, and outputs a pair holding the correct of data stack inputs and outputs for the quotation." }
{ $errors "Throws an " { $link inference-error } " if stack effect inference fails." } ;

HELP: dataflow
{ $values { "quot" "a quotation" } { "dataflow" "a dataflow node" } }
{ $description "Attempts to construct a dataflow graph showing stack flow in the quotation." }
{ $notes "This is the first stage of the compiler." }
{ $errors "Throws an " { $link inference-error } " if stack effect inference fails." } ;

HELP: dataflow-with
{ $values { "quot" "a quotation" } { "stack" "a vector" } { "dataflow" "a dataflow node" } }
{ $description "Attempts to construct a dataflow graph showing stack flow in the quotation, starting with an initial data stack of values." }
{ $errors "Throws an " { $link inference-error } " if stack effect inference fails." } ;