/lib/error.prototype.js

/*

////////////////////////////////////////////////////////////////////////////////

    ______                        ____             __        __

   / ____/_____________  _____   / __ \_________  / /_____  / /___  ______  ___  _____

  / __/ / ___/ ___/ __ \/ ___/  / /_/ / ___/ __ \/ __/ __ \/ __/ / / / __ \/ _ \/ ___/

 / /___/ /  / /  / /_/ / /     / ____/ /  / /_/ / /_/ /_/ / /_/ /_/ / /_/ /  __(__  )

/_____/_/  /_/   \____/_/     /_/   /_/   \____/\__/\____/\__/\__, / .___/\___/____/

                                                             /____/_/



////////////////////////////////////////////////////////////////////////////////

*/



(function() {



    Error.prototype.matches = function(err) {

        if (err.isNumber()) return this.number == err;

        if (err.isError()) return this.number == err.number;

    };



    Error.prototype.toString = function() {

        //Returns a better string representation of an error object

        //@todo: enhance logic for browser based stack traces and information.

        //@ref: https://github.com/occ/TraceKit

        //@note: this used to include a stack trace, but that spins JSON.stringify into an IL,

        //       if you'd like to view a stack trace, just use console.trace() instead

        return 'ERROR: ' + this.message;

    };



    Error.prototype.trace = function() {

        //@desc: returns the stack trace as an array of function names

        if (this.stack) {

            return this.stack.lines();

        }

        else {

            var cur = arguments.callee.caller;

            var stack = [];

            var i = 50;



            while(cur && i--) {

                stack.push(cur.id());

                cur = cur.caller;

            }



            return stack;

        }

    };



    Error.prototype.ignore = function() {

        //returns true for known "non-errors" used for workflow purposes

        if (this.description == "break" || this.exit == true) {

            return true;

        }

    };



    Error.prototype.debug = function(code) {

        //prompt user for debugger hook

        code = code || "[no code provided]";

        //@todo: need to implement with callback handler because that's how nodejs does confirms, until then I'm disabling it.

        if (false && confirm("An error has occurred:\n\n" + this.toString() + "\n\n" + code + "\n\nWould you like to debug?")) {

            //if the user clicks yes - hit debug statement

            debugger;

            return true;

        }



        return false;

    };



    Error.prototype.bubble = function() {

        if (this.bbl) {

            this.count--;

            if (this.count <= 0) {

                return true;

            }

            throw this;

        }

    };



    Error.prototype.handle = function() {

        //attempts to handle all errors

        //will return undefined if nothing further to do

        //will return a value if the error was intended to return a value (each iterators)

        //will rethrow the error if it was intended to be reported via the .report attribute

        if (this.ignore()) {

            return this.retval;

        }



        if (this.bubble()) {

            return this.retval;

        }



        if (this.debug()) return null;



        if (this.die) {

            throw this; //Keep throwing until we die!

        }



        if (this.report != null || this.die) {

            delete this.report;

            throw this;

        }

        else {

            if (gc.debug) {

                alert(this.toString());

            }

        }



        return true;

    };



    Error.toss = function(m) {

        //alias for throwing a new exception

        throw new Error(m);

    };



    Error.prototype.toss = function(m) {

        //A gentler type of throw

        //Designed to throw a newly defined Error inside things like var definitions or array indicies

        this.report = true;

        this.extra = m;

        this.handle();

    };



    Error.prototype.pass = function(f) {

        //pass an error to the provided error handling function {f}

        if (f) {

            f(this);

        }

    };



    Object.prototype.pass =

    Object.prototype.toss = function() {

        //noop: this is designed to reduce complexity of the node framework's error handling architecture

    };



    Error.prototype.print = function() {

        return "  ERROR: " + this.number + " - " + (this.description || this.message);

    };



    Error.notImplemented = function() {

        //helper error for functions yet to be implemented

        Error.toss("Function Not Implemented: " + closure().caller.id());

    };



    Error.invalidArgument = function() {

        Error.toss(

            "Function " + closure().caller.id() + " does not implement logic for parameters: " +

            arguments.ea(function(v) {

                return v.isa() + " : " + v.serialize();

            }).join("\r\n")

        );

    };



})();