/ 
Gears-0.100
/ Gears::X

NAME

Gears::X - Base exception class

SYNOPSIS

use Gears::X;

# Raise an exception directly
Gears::X->raise("Something went wrong");

# Create and raise later
my $error = Gears::X->new(message => "Invalid input");
$error->raise;

# Catch and inspect
try {
	Gears::X->raise("Error occurred");
}
catch ($e) {
	say $e->message;                  # Error occurred
	say $e;                           # An error occured: Error occurred (raised at ...)
	my ($file, $line) = $e->caller->@*;
}

# Enable stack traces
try {
	Gears::X->raise("With trace");
}
catch ($e) {
	local $Gears::X::PRINT_TRACE = true;
	say $e;
}

# Create exception subclasses
package My::X::Database {
	use Mooish::Base;
	extends 'Gears::X';
}

DESCRIPTION

Gears::X is the base exception class for the Gears framework. It provides stack trace capture, string overloading, and a simple interface for creating and raising exceptions. Exceptions can be stringified for display and include information about where they were raised.

The exception class captures a stack trace when created, filtering out internal framework packages to show only relevant application code. Stack traces can be optionally printed by setting the "$PRINT_TRACE" package variable or setting GEARS_PRINT_TRACE environmental variable before the package is loaded.

INTERFACE

Package variables

$PRINT_TRACE

local $Gears::X::PRINT_TRACE = true;

When set to true, exceptions will include full stack traces in their string representation. By default the value of an environmental variable GEARS_PRINT_TRACE is used. If this is false, only the immediate caller location is shown.

This can be enabled temporarily for debugging.

{
	local $Gears::X::PRINT_TRACE = true;
	# Exceptions here will show full traces
}

Attributes

message

The error message string. This is the primary description of what went wrong.

Required in constructor

trace

An array reference containing the stack trace. Each element is an array reference of [$file, $line]. The trace is automatically generated when the exception is created.

Not available in constructor

Methods

new

$object = $class->new(%args)

A standard Mooish constructor. Consult "Attributes" section to learn what keys can key passed in %args.

raise

$exception->raise($message = undef)
$class->raise($message)

Raises an exception. Can be called as either an instance method or a class method. When called as a class method with a message, creates a new exception instance and raises it immediately.

caller

$array_ref = $exception->caller()

Returns the first element of the trace ([$file, $line]), representing where the exception was raised outside of the internal packages. Returns undef if no trace is available.

as_string

$string = $exception->as_string($include_trace = $PRINT_TRACE)

Returns a formatted string representation of the exception. If $include_trace is true, includes the full stack trace. Otherwise, includes only the file and line where the exception was raised.

This method is called automatically when the exception is stringified.

If the exception is a subclass, the class name is included:

An error occured: [HTTP] 404 - Not Found (raised at ...)

as_number

$number = $exception->as_number()

Returns the reference address of the exception object. This allows exceptions to be used in numeric contexts for comparison or identification.

add_ignored_namespace

$class->add_ignored_namespace($module)

Adds a module namespace to the list of packages that should be filtered from stack traces. This is useful when creating framework extensions that should not appear in application-level traces.

Stack traces automatically filter out packages matching certain patterns to show only relevant application code. By default, filtered packages include:

  • Gears::* - Framework-framework internals

  • Type::Coercion::* - Type coercion internals