NAME

Text::NSR - Read "newline separated records" (NSR) structured text files

SYNOPSIS

        use Text::NSR;
        my $nsr = Text::NSR->new(
                filepath  => 't/test.nsr',
                fieldspec => ['f1','f2','f3','f4']
        );
        my $records = $nsr->read();

DESCRIPTION

There are a number of data exchange formats out there that strive to be structured in a way that is both, easily and intuitively editable by humans and reliably parseable by machines. This module here adds yet another structured file format, a file composed of "newline separated records".

The guiding principal here is that each line in a file represents a value. And that multiple lines form a single record. Multiple records then are separated by one empty line. Exactly one empty line. A second empty line will be interpreted as the first line of the next record. The only exception to this rule are leading or trailing newlines on the "whole file" scope. They are considered "padding" and are dropped.

Values may contain newlines (line feed). In a raw NSR file, newlines are represented literal chars "\n" ("backslash" plus "n"). After record-parsing, these chars are replaced by the newline char in the resulting data structure.

NSR files can be used to hold very simple human editable databases.

This module here helps with reading and parsing of such files.

FUNCTIONS

new()

filepath is mandatory. fieldspec is optional, an array of hash key names.

read()

Returns an array of arrayrefs when no fieldspec was given upon construction. Each element of the referenced array will hold a record's lines in the order they were found in the file.

When a fieldspec was provided to new(), read() will try to coerce record lines into a hash according to fieldspec. In case a record does not follow fieldspec and has more lines than expected, read() will add those lines with their zero-based line number as key to the resulting hashref. Fewer lines than in fieldspec will not create empty elements.

EXPORT

Nothing by default.

CAVEATS

Currently files are slurped completely and not streamed or read incrementally, so be careful with really large files.

As stated above, trailing newlines on the "whole file" scope are considered "padding" and are dropped. Having a fieldspec should probably allow to have an empty last line as part of a record but the current implementation would drop an empty last record line.

SEE ALSO

Any other file format that contains well readable (mostly) textual data in a structured manner. This here shares the "stanza" idea with, for example, Config::INI, and the readable approach with YAML and the line by line aspect with Text::FrontMatter::YAML. Give a shout if you can name another one.

AUTHOR

Clipland GmbH https://www.clipland.com/

This module was developed for live streaming infotainment website InStream.de.

COPYRIGHT & LICENSE

Copyright 2022 Clipland GmbH. All rights reserved.

This library is free software, dual-licensed under GPLv3/AL2. You can redistribute it and/or modify it under the same terms as Perl itself.