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: my $treeref=Text::TreeFile->new($filename,'mult');

die "TreeFile constructor returned undef\n" if not 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

TreeFile.pm 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.

-head1 OPTIONS

TreeFile implements a two-choice option between:

  (1) A single top-level tree per file (leaving the tail end
        of each file available for supplementary data which
        TreeFile.pm does not, itself, support), in which case
        it makes reference for the top-level tree, or

  (2) Multiple top-level trees per file (or, put another way,
        the top-level of the tree represented by a file is
        implicit -- having no explicit text string in the file
        -- or is associated with only the filename as its
        content), in which case it makes an array of 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" if not defined $treeref;

my $topref=$treeref->{top}; # scalar or array 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 {                           # 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.

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.

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.

AUTHOR

John Kirk <johnkirk@dystanhays.com>

-head1 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

perl(1), FileHandle(3pm), Exporter(3pm), Autoloader(3pm) and http://perl.dystanhays.com/jnk -- for gory details and examples.