NAME

App::Followme::NestedText - Read a file or string using a subset of yaml or xml

SYNOPSIS

        use App::Followme::NestedText
    my %config = nt_parse_almost_yaml_file($filename);
    %config = nt_parse_almost_yaml_string($str);
        nt_write_almost_yaml_file($filename, %config);

    my %rss = nt_parse_almost_xml_file($filename);
    %rss = nt_parse_almost_xml_string($str);
        nt_write_almost_xml_file($filename, %rss);

DESCRIPTION

This module reads configuration data from either a file or string. The data is a hash whose values are strings, arrays, or other hashes. Because of the loose typing of Perl, numbers can be represted as strings. It supports two formats. The first is a subset of yaml, called "almost yaml." This format is used to read the configuration files and metadata text files that are oing to be converted to web pages. In this format a hash is a list of name value pairs separated by a colon and a space:

    name1: value1
    name2: value2
    name3: value3

In the above example all the values are short strings and fit on a line. Longer values can be split across several lines by starting each line sith a greater than sign and space indented beneath the name:

    name1: value1
    name2:
        > A longer value
        > split across lines
        > however many you need
        > for your application.
    name3: value3

The lines are joined with spaces into a single string.

Array values are formatted one element per line with each line indented beneath the name starting with a dash and space

    name1: value1
        array_name: 
            - subvalue1
        - subvalue2
        - subvalue3

Hash values are indented from the field containg them, each field in the hash on a separate line.

    name1: value1
    hash_name:
        subname1: subvalue1
        subname2: subvalue2
        subname3: subvalue3

Hashes, arrays, and strings can be nested to any depth, but the top level must be a hash. Values may contain any character except a newline. Quotes are not needed around values. Leading and trailing spaces are trimmed from values, interior spaces are unchanged. Values can be the empty string. Names can contain any non-whitespace character. The amount of indentation is arbitrary, but must be consistent for all values in a string, array, or hash. The three special characters which indicate the field type (:, -, and > ) must be followed by at least one space unless they are the last character on the line.

The other format is a subset of xml, called "almost xml." This format is used for rss files. In this format a hash is represented by a sequence of values enclosed by tags in angle brackets. The tag names in the angle brackets are the hash field names.

    <title>Liftoff News</title>
    <link>http://liftoff.msfc.nasa.gov/</link>
    <description>Liftoff to Space Exploration.</description>
    <language>en-us</language>

if a tag name is repeated the values in those tags are treated as an array:

    <item>first</item>
    <item>second</item>
    <item>third</item>

A hash can also be contained in a value by placing a list of tags within another pair of tags:

    <item>
        <title>The Engine That Does More</title>
        <link>http://liftoff.msfc.nasa.gov/news/2003/news-VASIMR.asp</link>
    </item>
    <item>
        <title>Astronauts' Dirty Laundry</title>
        <link>http://liftoff.msfc.nasa.gov/news/2003/news-laundry.asp</link>
    </item>

Indentation is nice for anyone looking at the file, but is not required by the format.

SUBROUTINES

The following subroutines can be use to read nested text. Subroutine names are exported when you use this module.

my %config = nt_parse_almost_yaml_file($filename);

Load a configuration from an almost yaml file into a hash.

my %config = nt_parse_almost_yaml_string($string);

Load a configuration from an almost yaml string into a hash.

nt_write_almost_yaml_file($filename, %config);

Write a configuration back to an almost yaml file

my %rss = nt_parse_almost_xml_file($filename);

Load a rss file into a hash.

my %rss = nt_parse_almost_xml_string($string);

Load a rss file from a string into a hash.

nt_write_almost_xml_file($filename, %rss);

Write rss back to an almost xml file

LICENSE

Copyright (C) Bernie Simon.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHOR

Bernie Simon <bernie.simon@gmail.com>