Text::Templar::Exceptions - runtime exception classes for Text::Templar
use Text::Templar::Exceptions qw{:syntax};
my $result = try {
$t = Text::Templar->new( "main.tmpl" );
} catch Text::Templar::Exception with {
my $e = shift;
print STDERR "Failed to load template 'main.tmpl': $e";
};
Nothing by default.
If used with the :syntax tag, the functions try(), with(), finally(), except(), and otherwise() will be imported into your package. See PROCEDURAL INTERFACE for more about what they do and how to use them.
This module provides runtime exception classes for Text::Templar, and also provides methods and syntax for handling them which can be imported in your own classes.
This code is mostly a hacked-up version of the Error.pm module by Graham Barr <gbarr@ti.com>. Sections which have been copied from or are modified versions of synonymous sections of that module are annotated accordingly.
Text::Templar::Exceptions can export subroutines to use for exception handling. The following functions can be imported into your package with the :syntax tag.
try BLOCK CLAUSEStry is the main subroutine called by the user. All other subroutines exported are clauses to the try subroutine.
The BLOCK will be evaluated and if no error is thrown, it will return the result of the block.
CLAUSES are the subroutines below, which describe what to do in the event of an error being thrown within BLOCK.
Try works a bit like eval <BLOCK> in regards to return value -- it evaluates to the value of the last statement executed by any of its clauses (including catch, otherwise, or finally clauses), or may be influenced by a return within any clause. This allows statements like the following:
### Try to get the result of executing the code, ignoring any errors that
### happen within.
my $result = try { <unsafe code> };
or
### Get the result of the unsafe code if it executed successfully, or 0 if it
### errors for any reason.
my $result = try { <unsafe code> } catch Exception with { return 0 };
catch CLASS with BLOCKThis clause will cause all errors that satisfy $err->isa(CLASS) to be caught and handled by evaluating BLOCK.
BLOCK will be passed two arguments. The first will be the exception object being thrown, and the second is a reference to a scalar variable. If this variable is set by the catch block, then on return from the catch block, try will continue processing as if the catch block was never found. This can be used to propagate an exception to a later catch, for example.
Another way of propagating the error is to call $err->throw from within the catch block.
If the scalar referenced by the second argument is not set, and the error is not re-thrown, then the current try block will return with the result from the catch block.
except BLOCKWhen try is looking for a handler, if an except clause is found, BLOCK is evaluated. The return value from this block should be a HASH reference or a list of key-value pairs, where the keys are class names and the values are CODE references for the handler of errors of that type.
This is useful for defining handlers on the fly.
For example:
try {
somethingDangerous();
}
# Handle IO errors
catch Exception::IOError with {
<do something>
}
# Build a handler for other errors
except {
my $handler = sub { print STDERR shift()->message };
return {
Exception::Custom1 => $handler,
Exception::Custom2 => $handler,
};
};
otherwise BLOCKCatch any error by executing the code in BLOCK
When evaluated, BLOCK will be passed one argument, which will be the error being processed.
Only one otherwise block may be specified per try block. Additional otherwise blocks will be ignored.
finally BLOCKThe code in BLOCK will be executed after all other clauses have executed. If the try block throws an exception then BLOCK will be executed after any handlers have been executed. If a handler throws an exception, then the exception will be caught, the finally block will be executed and the exception will be re-thrown.
Only one finally block may be specified per try block. Additional ones will result in a syntax error.
The following methods are methods on the base exception class, from which all exceptions classes defined herein inherit.
Returns a new Text::Templar::Exception object with the error message specified, or 'Unspecified error' if none is specified.
A wrapper for stringify()
Adds a catch clause with the specified handler code for the specified package onto the array of 'catch' clauses in the clauses given. If the clauses hashref is omitted, one is created. Returns the new or given clauses hashref with the new catch clause added.
Returns the stack frame from frameNumber levels deep in the call stack. The frame is a hash (or hashref if called in scalar context) of the form:
{
'package' => The caller's package
'filename' => The filename of the code being executed
'line' => The line number being executed
'subroutine' => The name of the function or method being executed
'hasargs' => True if the sub was passed arguments from its caller
'wantarray' => True if the sub was called in a list context
'evaltext' => If 'subroutine' is '(eval)', this is the EXPR of the eval block
'is_require' => True if the frame was created from a 'require' or 'use'
}
Returns an array of stack frames of the format returned by stackframe() that describe the stack trace at the moment the exception was thrown.
Returns the stacktrace and error message of the exception as a human-readable string.
Create a new Exception object with errmsg and die with it. This will be caught by any enclosing try() blocks. If not enclosed by atry(), calling this method will cause a fatal exception. This method is a modified version of the synonymous one in Error.pm.
Method invocation error. Used when a method is invoked as a function, or vice-versa.
File Input/Output error.
Evaluation error. Used when evaluated code fails to evaluated successfully.
Too deep recursion error.
Generic internal template error.
Parameter error. Used when a method is called with missing or illegal parameters.
If this exception is thrown with two arguments, and the first argument is a integer number, an error message is built of the form: "Missing or undefined argument $_[0]: $_[1]".
$Exception::TERSE flag.$Id: Exceptions.pm,v 1.9 2003/01/05 17:17:21 deveiant Exp $
Michael Granger <ged@FaerieMUD.org>
Copyright (c) 1999-2001 The FaerieMUD Consortium. All rights reserved.
This module is free software. You may use, modify, and/or redistribute this software under the terms of the Perl Artistic License. (See http://language.perl.com/misc/Artistic.html)
THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
Portions of this file are also borrowed from Error.pm, which has the following copyright information:
Copyright (c) 1997-8 Graham Barr <gbarr@ti.com>. All rights reserved. This
program is free software; you can redistribute it and/or modify it under the
same terms as Perl itself.
Error.pm by Graham Barr
