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