Parse::StackTrace - Parse the text representation of a stack trace into an object.
my $trace = Parse::StackTrace->parse(types => ['GDB', 'Python'], text => $text, debug => 1); my $thread = $trace->thread_number(1); my $frame = $thread->frame_number(0);
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
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
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.
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.
This method takes the following named parameters:
A string. The block of text that you want to find a stack trace in.
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:
Types are case-sensitive.
Set to 1 if you want the method to output detailed information about its parsing.
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.
These are methods of Parse::StackTrace objects that return data. You should always call them as methods (never like
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
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
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.
Returns the text of just the trace, with line endings converted to just CR. (That is, just
An arrayref containining the lines of just the trace, without line endings.
These are additional methods to get information about the stacktrace.
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-> would not be "Thread 1".
Returns the first thread where
Parse::StackTrace::Thread/frame_with_crash is defined, or
undef if no threads contain a
The various parts of a stack trace:
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):
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".)
There are no known issues with this module. It has received extensive testing, and it should be considered stable.
Any bugs found should be reported to the author by email.
Max Kanat-Alexander <email@example.com>
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.