Template::Plugin::StringTree - Access tree-like groups of strings naturally in code and Templates
use Template::Plugin::StringTree; # Create a StringTree and set some values my $Tree = Template::Plugin::StringTree->new; $Tree->set('foo', 'one'); $Tree->set('foo.bar', 'two'); $Tree->set('you.get.the.point' => 'right?'); # Get simple hash of these variables for the template my $vars = $Tree->variables; ####################################################### # Later that night in a Template After the number [% foo %] comes the number [% foo.bar %], [% you.get.the.point %] ####################################################### # Which of course produces After the number one comes the number two, right?
For a couple of months, I had found it really annoying that when I wanted to put a bunch of configuration options into a template, that I couldn't use a natural [% IF show.pictures %][% IF show.pictures.dropshadow %] ...etc... type of notation. Simply, to get "dot" formatting in template, you need hashes. Which means stupid notation like [% show.pictures.at_all %]. ugh...
As the size of the config tree I wanted to use grew and grew, it finally started getting totally out of control, so I've created Template::Plugin::StringTree, which lets you build tree structures in which every node can have a value. And you can get at these naturally in templates.
The new constructor simply creates a new ::StringTree object and returns it.
new
Taking a single "this.is.a.path" argument, the get method returns the value associated with the path, if there is one.
get
Returns the value for the path, if one exists. Returns undef if no value exists at that path.
undef
The set method takes a "this.is.a.path" style path and a value for that path. undef is valid as a value, erasing a single value at the node for the path. ( It does not remove children of that node ).
set
Returns true if the value is set correctly, or undef on error.
The add method is nearly identical to the normal set method, except that the it expects there NOT to be an existing value in place. Rather than overwrite an existing value, this method will return an error.
add
Returns true if there is no existing value, and it is successfully set, or undef if there is an existing value, or an error while setting.
The hash method produces a flat hash equivalent to the Template::Plugin::StringTree object, which can be passed to the template parser. You can manually add additional elements to the hash after it has been produced, but you should not attempt to add anything to a hash key the same as the first element in a path already added via the set method earlier.
hash
Returns a reference to a HASH containing the tree of strings.
Ever good structure can be serialized and deserialized, and this one is no exception. The freeze method takes a ::StringTree object and converts it into a string, which just so happens to be highly useful as a config file format!
freeze
foo: one foo.bar: two you.get.the.point: right?
So terribly simple. To make life just a LITTLE more complicated though, Template::Plugin::StringTree does a little bit of escaping if there's a newline in the string. But since you'll probably never DO that, it won't be a problem will it? :)
The thaw method is the reverse of the freeze method, taking the same format string turning it back into a Template::Plugin::StringTree object. THIS is where using this module as a config file -> template mechanism really comes into it's own. Each entry is the config file is available using the same path in Template Toolkit templates. Template::Plugin::StringTree takes care of all the details or making it work across the different models transparently.
thaw
If the string is formatted correctly, returns a new Template::Plugin::StringTree object. Returns undef on error, probably because the string wasn't formatted correctly.
The equal method provides a quick and convenient bit of shorthand to let you see if a particular path equals a particular value. And the method is totally undef-safe. You can test for a value of undef, and test a value against a path which returns undef quite safely.
equal
Returns true if the value matches the path, or false otherwise.
Bugs should be submitted via the CPAN bug tracker, located at
http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Template-Plugin-StringTree
For other issues, contact the author
Adam Kennedy <adamk@cpan.org>
Copyright 2004, 2008 Adam Kennedy.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
The full text of the license can be found in the LICENSE file included with this module.
To install Template::Plugin::StringTree, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Template::Plugin::StringTree
CPAN shell
perl -MCPAN -e shell install Template::Plugin::StringTree
For more information on module installation, please visit the detailed CPAN module installation guide.