NAME

Badger::Exception - structured exception for error handling

SYNOPSIS

    use Badger::Exception;
    
    # create exception object
    my $exception = Badger::Exception->new({
        type => $type,
        info => $info,
    });
    
    # query exception type and info fields
    $type = $exception->type();
    $info = $exception->info();
    ($type, $info) = $exception->type_info();
    
    # print string summarising exception
    print $exception->as_string();
    
    # use automagic stringification 
    print $exception;
    
    # throw exception
    die $exception;

DESCRIPTION

This module defines an object class for representing exceptions. An exception is a structured error with type and info fields. The type denotes what kind of error occurred (e.g. 'file', 'parser', 'database', etc.). The info field provides further information about the error (e.g. 'foo/bar.html not found', 'parser error at line 42', 'server is on fire', etc.)

METHODS

new()

Constructor method for creating a new exception.

    my $exception = Badger::Exception->new(
        type => 'database',
        info => 'could not connect',
        file => '/path/to/file.pm',
        line => 420,
    );

type()

When called without arguments, this method returns the exception type, as defined by the first argument passed to the new() constructor method.

    my $type = $exception->type();

It can also be called with an argument to set a new type for the exception.

    $exception->type('database');

info()

When called without arguments, this method returns the information field for the exception.

    my $info = $exception->info();

It can also be called with an argument to define new information for the exception.

    $exception->info('could not connect');

file()

Method to get or set the name of the file in which the exception was raised.

    $exception->file('path/to/file.pm');
    print $exception->file;                 # /path/to/file.pm

line()

Method to get or set the line number at which the exception was raised.

    $exception->line(420);
    print $exception->line;                 # 420

text()

This method returns a text representation of the exception object. The string returned is formatted as $type error - $info.

    print $exception->text();   # database error - could not connect

This method is also bound to the stringification operator, allowing you to simple print the exception object to get the same result as calling text() explicitly.

    print $exception;   # database error - could not connect

match_type()

This method selects and returns a type string from the arguments passed that is the nearest correct match for the current exception type. This is used to select the most appropriate handler for the exception.

    my $match = $exception->match_type('file', 'parser', 'database')
        || die "no match for exception\n";

In this example, the exception will return one of the values file, parser or database, if and only if its type is one of those values. Otherwise it will return undef;

Exception types can be organised into a hierarchical structure by delimiting each part of the type with a period. For example, the database exception type might be further divided into the more specific database.connection, database.query and database.server_on_fire exception types.

An exception of type database.connection will match a handler type of database.connection or more generally, database. The longer (more specific) handler name will always match in preference to a shorter (more general) handler as shown in the next example:

    $exception->type('database.connection');
    
    my $match = $exception->match_type('database', 'database.connection')
        || die "no match for exception\n";
        
    print $match;    # database.connection

When there is no exact match, the match_type() method will return something more general that matches. In the following example, there is no specific handler type for database.exploded, but the more general database type still matches.

    $exception->type('database.exploded');
    
    my $match = $exception->match_type('database', 'database.connection')
        || die "no match for exception\n";
        
    print $match;    # database

AUTHOR

Andy Wardley http://wardley.org/

COPYRIGHT

Copyright (C) 1996-2008 Andy Wardley. All Rights Reserved.

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

cpanm Badger

perl -MCPAN -e shell
install Badger