John Kirk > Text-TreeFile-0.39 > Text::TreeFile

Download:
Text-TreeFile-0.39.tar.gz

Dependencies

Annotate this POD

Related Modules

XML::Parser
Parse::RecDescent
Data::Dumper
more...
By perlmonks.org
View/Report Bugs
Module Version: 0.39   Source  

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.

syntax highlighting: