NAME

Text::TreeFile - Reads a tree of text strings into a data structure

SYNOPSIS

  use Text::TreeFile;

  # need to set $filename, e.g.:  my $filename='treetest.tre';

  my $treeref=Text::TreeFile->new($filename);
  # or other option: my $treeref=Text::TreeFile->new($filename,'mult');

  die "TreeFile constructor failed to read file $filename\n"
    unless defined $treeref;

  my $topref=$treeref->{top}; # scalar or array for top-level tree(s)
  showlines($topref,0);            # see EXAMPLE, below

REQUIRES

TreeFile uses modules: FileHandle, Exporter and Autoloader.

DESCRIPTION

The TreeFile.pm module supports a simple ASCII text file format for representing tree structures. It loads the contents of such a file into a tree (or array of trees) of two-element array nodes, where the first element of each node is a text string and the second is an array of child nodes. It supports comments, continuation lines and include files, and uses a strict (two-space-per-level) indentation scheme in the file to indicate hierarchical nesting.

OPTIONS

TreeFile implements an option between single or multiple top-level trees per file. The option is exercised by the presence or absence of a second argument to new(), as demonstrated in the "SYNOPSIS" section, above (the two lines where "my $treeref=" occurs).

(default case)

If the new() constructor is not given a second argument, the default option occurs: A single top-level tree is read, per file. This leaves the remainder of each file's contents available for some other facility to use. In this case new() returns (a reference to) the top-level tree (node).

(optional case)

If the new() constructor is given a second argument, multiple top-level trees are read from each file (and the entire file needs to conform to the TreeFile syntax). In this case new() returns (a reference to) an array containing (references to) the top-level trees.

EXAMPLE

  use Text::TreeFile;

  sub showlines;

  # set $filename string and $wantmult boolean
  # my $filename='treetest.tre';
  # my $wantmult=1;   # or:  =0;  # or: omit from new() constructor;

  my $treeref;
  $treeref=Text::TreeFile->new($filename) if not $wantmult;
  $treeref=Text::TreeFile->new($filename,'mult') if $wantmult;
  die "TreeFile constructor returned undef\n" unless defined $treeref;

  my $topref=$treeref->{top}; # node or array of nodes for top-level tree(s)
  showlines($topref,0);

  sub showlines { my ($spec,$level)=@_;
    if(ref($$spec[0]) eq 'ARRAY') { #         want-mult case
      for my $item (@$spec) {
        print('  'x$level);print("$$item[0]\n");
        for(@{$$item[1]}) { showlines $_,$level; } } }
    else { # spec[0] is the top-level string: no-want-mult case
      print('  'x$level);print("$$spec[0]\n");
      for(@{$$spec[1]}) { showlines $_,$level+1; } } }

FILE FORMAT

The file format supported relies upon indentation of text strings, to indicate hierarchical nesting for the tree structure. Strict indentation (of two space characters per nesting level) is used to represent parent-child structure.

Comments

A line consisting exclusively of whitespace, or a line beginning with either the pound-sign ("#"), the semicolon (";"), or the forward slash ("/") character will be ignored as a comment. In the very first line of a file, the initial characters, "exec ", will indicate a comment line.

Continuation Lines

A line beginning with whitespace followed by three period (".") characters, will be concatenated to the previous line, as a continuation. The preceding end-of-line, the initial whitespace and the ellipsis ("...") will be removed and otherwise ignored, to allow long strings to be represented within line-length constraints.

As a rule, it's probably a good idea to make sure any line that is continued with a continuation line have no trailing spaces, and that any spaces that are desired in the resulting concatenation occur between the ellipsis ("...") and the remainder of the continuation line. Perhaps a later version of the module will remove trailing spaces on each line, to further reduce surprises.

Include Files

In addition, any line consisting of indentation followed by "include" will be interpreted as a file-include request. In this case, succeeding whitespace followed by a file specification will cause the contents of the named file to be substituted at that point in the tree. The remainder of the include-file line is ignored as commentary.

AUTHOR

John Kirk <johnkirk@dystanhays.com>

COPYRIGHT

Copyright (c) 2000 John Kirk. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

Text::TreeFile::details(3pm) - for precise definition of syntax,

Text::TreeFile::internals(3pm) - for implementation commentary,

and http://perl.dystanhays.com/jnk - for related material.