file:   Text-TreeFile-0.39.readme

  The Perl module, Text::TreeFile supports reading a simple ASCII
text file format for representing tree structures.  It loads the
contents of such a file into a tree (or array of several 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-spaces-per-level) indentation scheme in the
file to indicate hierarchical nesting.

  This module has been helpful for a dozen applications or so,
which were simplified by having this functionality abstracted out.
The most generally useful such application is a tool that simplifies
the use of perl-tk (modules in the Tk:: namespace) for building
GUI-based application programs (see an example data file, mentioned
below).

DOCUMENTATION

  There are man pages for Text::TreeFile(3pm) which introduces the
functions and use of the modele, Text::TreeFile::details(3pm) which
gives exhaustive specification of alternatives and features for use,
and Text::TreeFile::internals(3pm) which documents the code itself.
Another module: Qtk::QuickTk(3pm) uses TreeFile by default and, thus,
is a significant application demonstrating TreeFile's features.

AVAILABILITY

  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.

  The latest version of this module should always be available
at any CPAN (http://www.cpan.org) mirror, or from the author:
             http://perl.dystanhays.com/jnk

INSTALLATION

  I usually install modules using the CPAN.pm module, invoked as:

       perl -MCPAN -e shell

It can be run by an ordinary user, or root (to install system-wide),
and asks a few configuration questions the first ime it's run.

  The *.tar.gz file, after being uncompressed and unarchived, expects
to be installed with the following commands:

       perl Makefile.PL
       make
       make test

  This creates and installs man pages, generated from *.pm and *.pod
files, among other things.

SYNOPSIS

  use Text::TreeFile;
  my $filename='treetest.tre';
  my $treeref=Text::TreeFile->new($filename)
    or die "TreeFile couldn't read file: $filename\n";
  my $topref=$treeref->{top};
  showlines($topref,0);       # see EXAMPLES, for def. of showlines()

REQUIRES

  TreeFile uses modules:  Exporter, Autoloader and FileHandle

CONTENTS

  This distribution provides the following:

TreeFile.pm  -- the code for the module, which your program will
  access with a "use Text::Treefile;" statement, typically.  Pod
  documentation is embedded in this file, from which the man page,
  Text::TreeFile(3pm) is generated.

details.pod  -- plain old documentation exhausively specifying
  the options for use of the module, from which the man page,
  Text::TreeFile::details(3pm) is generated.

internals.pod  -- plain old documentation of the module code
  itself, from which the man page, Text::TreeFile::internals(3pm)
  is generated.

test.pl  -- a small program which contains hand-coded copies of
  the data structures that should result from using the module
  to read the treetest.tre and testfile.tre example files, which
  are shown below.  The program reads these data files and
  reports whether the resulting internal tree structure matches
  the hand-coded versions.

demodata/treetest.tre  -- a small example data file, which has
  some comment lines, and contains two top-level trees, so that
  it can be used to test TreeFile's option for reading either
  a single tree only, or multiple trees (into an array of trees).
  the content of this file (between the dotted lines) is:

  --------------------------- snip, snip ---------------------------------
  #  file:  treetst.tre

  # this tree will be read in any case
  I. Top node in first (or only) tree
    A. first child of top node in first tree
      1. first child of first child of top node in first tree
    B. second child of top node in first tree

  # the first tree has ended, because this next line has zero indentation
  II. Top node in second tree, if in "mult" mode
    A. first child of top node in second tree
    B. second child of top node in second tree
      1. first child of second child of top node in second tree
      2. second child of second child of top node in second tree
    C. third child of top node in second tree
  --------------------------- snip, snip ---------------------------------

demodata/testfile.tre  -- a second small example data file, which
  demonstrates the include-file facility and commentary that can
  appear following the included file's name.  Its content:

  --------------------------- snip, snip ---------------------------------
  line 01, level 0, yyyyy
    line 02, level 1, yyyyy
      line 03, level 2, yyyyy
      line 04, level 2, yyyyy
    line 05, level 1, yyyyy
    line 06, level 1, yyyyy
      include inclfile.tre all the rest of this line is commentary
      line 13, level 2, yyyyy
    line 14, level 1, yyyyy
  --------------------------- snip, snip ---------------------------------

demodata/inclfile.tre  -- the third file, which is included into
  the one above.  Note that it contains a complete tree which is
  at the top level (i.e. no indentation, to begin with) but, that
  when it gets included in the file above, it will appear three
  levels deep in that tree's structure.  Its content:

  --------------------------- snip, snip ---------------------------------
  line 07, level 2, locallevel 0, xxxxx
    line 08, level 3, locallevel 1, xxxxx
    line 09, level 3, locallevel 1, xxxxx
      line 10, level 4, locallevel 2, xxxxx
      line 11, level 4, locallevel 2, xxxxx
    line 12, level 3, locallevel 1, xxxxx
  --------------------------- snip, snip ---------------------------------

pickhues.tre  -- a file specifying a GUI (graphical user interface)
  from a color-picker program, implemented using the TreeFile module.
  This file demonstrates a practical application of the module.

demodata/ftp_cpan_org.tre and demodata/cpan_mjd.tre  -- another, even
  bigger, file which shows use of this module for storing indexes of
  disk files such as backups on offline media or contents of remote
  ftp sites.  This one is a partial listing of a CPAN site, in unix's
  long "ls -aF" format.  It also shows TreeFile's convention for
  allowing long lines to be broken to accomodate narrower margins,
  using ellipsis ("...") to mark continuation lines.  The second file
  is included into the first using TreeFile's include-file facility.

EXAMPLES

  In addition to the test.pl code example and the six files of
sample data in the demodata directory, the following example of
a program which reads and prints a treefile, may be helpful:

---------------------- file:  treetest ---------------------------
#!/usr/bin/perl -w

use strict;
use Text::TreeFile;

sub showlines;

# set $filename string and $wantmult boolean
my $filename=(defined $ARGV[1])?$ARGV[1]:'demodata/treetest.tre';
my $wantmult=(defined $ARGV[0] and $ARGV[0] eq 'mult');
print "want mult: ",$wantmult?'yes':'no',"\n";

my $treeref;
$treeref=Text::TreeFile->new($filename) if not $wantmult;
$treeref=Text::TreeFile->new($filename,'mult') if $wantmult;
die if not defined $treeref;

my $topref=$treeref->{top};
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+1; } } }
  else {                           # no-want-mult case
    print('  'x$level);print("$$spec[0]\n");
    for(@{$$spec[1]}) { showlines $_,$level+1; } } }

1;
__END__
------------------- end of file:  treetest -----------------------