USING: errors help kernel ;

HELP: >c "( continuation -- )"
{ $values { "continuation" "a continuation" } }
{ $description "Pushes an exception handler continuation on the catch stack. The continuation must have been reified by " { $link callcc1 } "." } ;

HELP: throw "( error -- )"
{ $values { "error" "an object" } }
{ $description "Saves the current continuation in the " { $link error-continuation } " global variable and throws an error. Execution does not continue at the point after the " { $link throw } " call. Rather, the innermost catch block is invoked, and execution continues at that point." }
{ $see-also rethrow } ;

HELP: catch "( try -- error/f )"
{ $values { "try" "a quotation" } { "error/f" "an object" } }
{ $description "Calls the " { $snippet "try" } " quotation. If an error is thrown in the dynamic extent of the quotation, restores the datastack and pushes the error. If the quotation returns successfully, outputs " { $link f } " without restoring the datastack." }
{ $notes "This word cannot differentiate between the case of " { $link f } " being thrown, and no error being thrown. You should never throw " { $link f } ", and you should also use other error handling combinators where possible." }
{ $see-also cleanup recover } ;

HELP: cleanup "( try cleanup -- )"
{ $values { "try" "a quotation" } { "cleanup" "a quotation" } }
{ $description "Calls the " { $snippet "try" } " quotation. If an exception is thrown in the dynamic extent of the " { $snippet "try" } " quotation, restores the datastack, calls the " { $snippet "cleanup" } " quotation, and rethrows the error. If the " { $snippet "try" } " quotation returns successfully, calls the " { $snippet "cleanup" } " quotation without restoring the datastack." }
{ $see-also catch recover } ;

HELP: recover "( try recovery -- )"
{ $values { "try" "a quotation" } { "recovery" "a quotation with stack effect " { $snippet "( error -- )" } } }
{ $description "Calls the " { $snippet "try" } " quotation. If an exception is thrown in the dynamic extent of the " { $snippet "try" } " quotation, restores the datastack and calls the " { $snippet "recovery" } " quotation to handle the error." } 
{ $see-also catch cleanup } ;

HELP: rethrow "( error -- )"
{ $values { "error" "an object" } }
{ $description "Throws an error without saving the current continuation in the " { $link error-continuation } " global variable. This is done so that inspecting the error stacks sheds light on the original cause of the exception, rather than the point where it was rethrown." }
{ $examples
    "This word definition attempts to convert a hexadecimal literal string to an integer, and outputs " { $link f } " if there is an error:"
    { $code
        ": catch-hex> ( str -- n/f )"
        "    [ hex> ] [ [ drop f ] when ] catch ;"
    }
} ;

HELP: error. "( error -- )"
{ $values { "error" "an object" } }
{ $contract "Prints an error in human-readable form." } ;