/ 
Toss-0.0.1
/ Toss

NAME

Toss - Error or Warning management without eval

VERSION

Version 0.01

SYNOPSIS

Toss is for people who hate littering their code with eval blocks to capture errors. The idea is that your code becomes easier to read without them.

NOTE: This concept goes against the typical design of how to manage failures inside perl. This module is here t Quick summary of what the module does.

WARNING: This code is experimental and the interface may change between versions without warning. Comments are welcome at http://github.com/toddr/perl-Toss

Examples:

package User;
use Toss;

sub get_user_info {
    $toss = 'Other Message";
    my $user_id = shift
        or return toss("Need a user ID to get you any information!");
   ...
}

package main;
use User;

my $id = '';
my $user = User->get_user_info($id);
if(!$user) {
    print "No user: $toss";    # 'No user: Need a user ID to get you any information!'
    print $toss->stack;        # Returns The stack trace from the first time the stack was called.
    print $toss->developer(1); # Returns developer message from the second time toss was called.
    print $toss->time_stamp;   # Returns DateTime object from when the toss event happened
}

EXPORT

toss is exported by default. Everything else is an object sub called by the generated object.

FUNCTIONS

toss

Not a object function. Syntactic sugar that allows you to return undef, while setting an error and possibly a developer message at the same time.

my $user = shift or return toss("Cannot login without a valid user name");
my $pass = shift or return toss("password cannot be blank", "Developer level message here");

or if the sub your calling sets $toss...

$toss = "Some ugly message from a module we user but don't want the user to see";
my $dbh = $owned_module->get_something() or return toss ("The module didn't like me") # $toss automatically becomes the developer message

DON'T DO this:
$toss = "Some ugly message from a module we user but don't want the user to see";
my $dbh = $owned_module->get_something() or return toss ("The module didn't like me", $toss) # $toss will be in the developer message twice if you do this.

tossdie

Quick workaround for loss of toss information across eval boundaries. passes @_ to toss, so has same api as toss.

TODO: could we have toss() detect that it is inside a die/eval context and change it's return convention accordingly? Right now I don't know how to do this. Ideas are welcome.

message

Called with a number to specify which user message to display in the toss stack

$toss->message(3) # Displays the user message from the third time toss was called when being passed down the stack.

These 2 are equivalent:

$toss->message(0) eq $toss->message;

stack

Same calling protocol as message but returns the call stack from where toss was called

developer

Same calling protocol as message but returns the developer message from that paticular toss

time_stamp

Same calling protocol as message but returns a DateTime object from that paticular toss.

_stringify

Called when you do "$toss". It appends all user messages from tosses into 1 string.

NOTE: There is no good reason to call this: "$toss" eq $toss->_stringify

_retoss (private sub)

Called by toss whenever $toss is already a Toss object. It appends a toss hash onto the object's array to trap additional information

NOTE: There is no reason I can think of to call this. If you can think of one, please open a ticket (see below) so we can consider making the interface public.

AUTHOR

Todd Rinaldo, <toddr at null.net>

BUGS

TODO: Need to document how to gen github tickets by email and/or web.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Toss

You can also look for information at:

ACKNOWLEDGEMENTS

COPYRIGHT & LICENSE

Copyright 2009 Todd Rinaldo, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.