/ 
Parse-StackTrace-0.01
River stage zero No dependents
/ Parse::StackTrace

NAME

Parse::StackTrace - Parse the text representation of a stack trace into an object.

SYNOPSIS

my $trace = Parse::StackTrace->parse(types => ['GDB', 'Python'],
                                     text => $text,
                                     debug => 1);
my $thread = $trace->thread_number(1);
my $frame = $thread->frame_number(0);

DESCRIPTION

This module parses stack traces thrown by different types of languages and converts them into an object that you can use to get information about the trace.

If the text you're parsing could contain different types of stack traces, then you should call "parse" in this module to parse your text. (So, you'd be calling Parse::StackTrace->parse.)

Alternately, if you know you just want to parse one type of trace (say, just GDB traces) you can call parse() on the Type class you want. For example, if you just want to parse GDB traces, you could call Parse::StackTrace::Type::GDB->parse. The only difference between the Type-specific parse methods and "parse" in this module is that the Type-specific parse methods don't take a types argument.

PARTS OF A STACK TRACE

Stack traces have two main components: Threads and Frames. A running program can have multiple threads, and then each thread has a "stack" of functions that were called. Each function is a single "frame". A frame also can contain other information, like what arguments were passed to the function, or what code file the frame's function is in.

You access Threads by calling methods on the returned StackTrace object you get from "parse".

You access Frames by calling methods on Threads.

EXCEPTIONS

Parse::StackTrace uses Exception::Class to throw errors. Each method will specify what exceptions it can throw.

CLASS METHODS

parse

Description

Takes a block of text, and if there are any valid stack traces in that block of text, it will find the first one and return it.

Parameters

This method takes the following named parameters:

text

A string. The block of text that you want to find a stack trace in.

types

An arrayref containing strings. These are the types of traces that you want to find in the block. Traces are searched for in the order specified, so if there is a trace of the first type in the list, inside the text, then the second type in the list will be ignored, and so on.

Currently valid types are: GDB, Python

Types are case-sensitive.

debug

Set to 1 if you want the method to output detailed information about its parsing.

Returns

An object that is a subclass of Parse::StackTrace, or undef if no traces of any of the specified types were found in the list.

Throws

Parse::StackTrace::Exception::NotAFrame - If there is an error during parsing.

Parse::StackTrace::Exception::NoTrace - Thrown by subclass implementations of parse when they don't detect any stack trace in the parsed text. However, when you call this implementation of parse (Parse::StackTrace->parse, not something like Parse::StackTrace::Type::GDB->parse), it doesn't throw this exception--it just returns undef when there are no traces of any type found.

INSTANCE ATTRIBUTES

These are methods of Parse::StackTrace objects that return data. You should always call them as methods (never like $object->{attribute}).

binary

Some stack traces contain information on what binary threw the stack trace. If the parsed trace had that information, this will be a string specifying the binary that threw the stack trace. If this information was not in the stack trace, then this will be undef.

threads

An arrayref of Parse::StackTrace::Thread objects, representing the threads in the trace. Sometimes traces have only one thread, in which case that will simply be threads->[0].

The threads will be in the array in the order that they were listed in the trace.

There is always at least one thread in every trace.

INSTANCE METHODS

These are additional methods to get information about the stacktrace.

thread_number

Takes a single integer argument. Returns the thread with that number, from the "threads" array. Thread numbering starts at 1, not at 0 (because this is how GDB does it, and GDB was our first implementation).

Note that if you want a particular-numbered thread, you should use this method, not "threads", because it's possible somebody could have a stack trace with the threads out of order, in which case threads->[0] would not be "Thread 1".

SEE ALSO

The various parts of a stack trace:

Parse::StackTrace::Thread
Parse::StackTrace::Frame

The different types of stack traces we can parse (which have special methods for the specific sort of data available in those traces that aren't available in all traces):

Parse::StackTrace::Type::GDB
Parse::StackTrace::Type::Python

TODO

Eventually we should be able to parse out multiple stack traces from one block of text. (This will be the list-context return of "parse".)

BUGS

This module has currently received only limited testing, so it might die or fail on certain unexpected input.

AUTHOR

Max Kanat-Alexander <mkanat@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2009 Canonical Ltd.

This library (the entirety of Parse-StackTrace) is free software; you can redistribute it and/or modify it under the same terms as Perl itself.