Constructor

new ($tree | $input)

The constructor is used primarily for creating an object instance. Initializing the object is done by the "_init" method (see below).

Input Processing

setInput ($input)

This method will take varios types of input, and pre-process them through the "prepareInput" method below.

prepareInput ($input)

The "prepareInput" method is used to pre-process certain types of $input. It accepts any of the follow types of arguments:

setFileEncoding($encoding)

This allows you to specify the $encoding that the file should be read using. This is only only applicable when your input is a file.

Filter Methods

useTabIndentedFilters

This will set the parse and deparse filters to handle tab indented content. This is for true tabs "\t" only. The parse and deparse filters this uses are compatible with one another so round-triping is possible.

Example:

  1.0
      1.1
      1.2
          1.2.1
  2.0
      2.1
  3.0
      3.1
          3.1.1
    

useSpaceIndentedFilters ($num_spaces)

This will set the parse and deparse filters to handle space indented content. The optional $num_spaces argument allows you to specify how many spaces are to be treated as a single indent, if this argument is not specified it will default to a 4 space indent. The parse and deparse filters this uses are compatible with one another so round-triping is possible.

Example:

  1.0
    1.1
    1.2
      1.2.1
  2.0
    2.1
  3.0
    3.1
      3.1.1
    

useDotSeparatedLevelFilters (@level_identifiers)

This will set the parse and deparse filters to handle trees which are described in the following format:

  1 First Child
  1.1 First Grandchild
  1.2 Second Grandchild
  1.2.1 First Child of the Second Grandchild
  1.3 Third Grandchild
  2 Second Child
    

There must be at least one space seperating the level identifier from the level name, all other spaces will be considered part of the name itself.

The parse and deparse filters this uses are compatible with one another so round-triping is possible.

The labels used are those specified in the @level_identifiers argument. The above code uses the default level identifiers ("1 .. 100"). But by passing the following as a set of level identifiers: 'a' .. 'z', you can successfully parse a format like this:

  a First Child
  a.a First Grandchild
  a.b Second Grandchild
  a.b.a First Child of the Second Grandchild
  a.c Third Grandchild
  b Second Child
    

Currently, you are restricted to only one set of level identifiers. Future plans include allowing each depth to have its own set of identifiers, therefore allowing formats like this: "1.a" or other such variations (see "TO DO" section for more info).

useDotSeperatedLevelFilters

This old mispelled method name is kept for backwards compat.

useNestedParensFilters

This will set the parse and deparse filters to handle trees which are described in the following format:

  (1 (1.1 1.2 (1.2.1) 1.3) 2 (2.1))
    

The parser will count the parentheses to determine the depth of the current node. This filter can also handle double quoted strings as values as well. So this would be valid input:

  (root ("tree 1" ("tree 1 1" "tree 1 2") "tree 2"))
    

This format is currently somewhat limited in that the input must all be on one line and not contain a trailing newline. It also does not handle embedded escaped double quotes. Further refinement and improvement of this filter format is to come (and patches are always welcome).

It should be noted that this filter also cannot perform a roundtrip operation where the deparsed output is the exact same as the parsed input because it does not treat whitespace as signifigant (unless it is within a double quoted string).

setParseFilter ($filter)

A parse filter is a subroutine reference which is used to process each element in the input. As the main parse loop runs, it calls this filter routine and passes it the Array::Iterator instance which represents the input. To get the next element/line/token in the iterator, the filter must call "next", the element should then be processed by the filter. A filter can if it wants advance the iterator further by calling "next" more than once if nessecary, there are no restrictions as to what it can do. However, the filter must return these two values in order to correctly construct the tree:

  $tree_parser->setParseFilter(sub {
      my ($iterator) = @_;
      my $line = $iterator->next();
      # match the tables and all that follows it
      my ($tabs, $node) = ($line =~ /(\t*)(.*)/);
      # calculate the depth by seeing how long
      # the tab string is.
      my $depth = length $tabs;
      # return the depth and the node value
      return ($depth, $node);
  });

setDeparseFilter ($filter)

The deparse filter is the opposite of the parse filter, it takes each element of the tree and returns a string representation of it. The filter routine gets passed a Tree::Simple instance and is expected to return a single string. However, this is not enforced we actually will gobble up all the filter returns, but keep in mind that each element returned is considered to be a single line in the output, so multiple elements will be treated as mutiple lines.

Here is an example of a deparse filter. This can be viewed as the inverse of the parse filter example above.

  $tp->setDeparseFilter(sub { 
      my ($tree) = @_;
      return ("\t" x $tree->getDepth()) . $tree->getNodeValue();
  });
    

Accessors

getTree

This method returns the tree held by the parser or set through the constructor.

Parse/Deparse

parse

Parsing is pretty automatic once everthing is set up. This routine will check to be sure you have all you need to proceed, and throw an execption if not. Once the parsing is complete, the tree will be stored interally as well as returned from this method.

deparse

This method too is pretty automatic, it verifies that it has all its needs, throwing an exception if it does not. It will return an array of lines in list context, or in scalar context it will join the array into a single string seperated by newlines.

Private Methods

_init ($tree | $input)

This will initialize the slots of the object. If given a $tree object, it will store it. This is currently the prefered way in which to use subclasses of Tree::Simple to build your tree with, as this object will be used to build any other trees (see "TO DO" for more information). If given some other kind of input, it will process this through the "prepareInput" method.

_parse

This is where all the parsing work is done. If you are truely interested in the inner workings of this method, I suggest you refer to the source. It is a very simple algorithm and should be easy to understand.

_deparse

This is where all the deparsing work is done. As with the "_parse" method, if you are interested in the inner workings, I suggest you refer to the source.