perlancar > Config-IOD-0.15 > Config::IOD

Download:
Config-IOD-0.15.tar.gz

Dependencies

Annotate this POD

Website

View/Report Bugs
Module Version: 0.15   Source  

NAME ^

Config::IOD - Read and write IOD configuration files

VERSION ^

This document describes version 0.15 of Config::IOD (from Perl distribution Config-IOD), released on 2015-03-27.

SYNOPSIS ^

 use Config::IOD;
 my $iod = Config::IOD->new(
     # list of known attributes, with their default values
     # default_section     => 'GLOBAL',
     # enable_encoding     => 1,
     # enable_quoting      => 1,
     # enable_backet       => 1,
     # enable_brace        => 1,
     # allow_encodings     => undef, # or ['base64','json',...]
     # disallow_encodings  => undef, # or ['base64','json',...]
     # allow_directives    => undef, # or ['include','merge',...]
     # disallow_directives => undef, # or ['include','merge',...]
     # allow_bang_only     => 1,
     # enable_expr         => 0,
 );

Read IOD document from a file or string, return Config::IOD::Document object:

 my $doc = $iod->read_file("/path/to/some.iod");
 my $doc = $iod->read_string("...");

See Config::IOD::Document for methods available for $doc.

DESCRIPTION ^

This module is a round-trip parser for IOD configuration format. Round-trip means all whitespaces and comments are preserved, so you get byte-by-byte equivalence if you dump back the parsed document into string.

Aside from parsing, methods for modifying IOD documents (add/delete sections & keys, etc) are also provided.

If you only need to read IOD configuration files, you might want to use Config::IOD::Reader instead.

ATTRIBUTES ^

default_section => str (default: GLOBAL)

If a key line is specified before any section line, this is the section that the key will be put in.

enable_encoding => bool (default: 1)

If set to false, then encoding notation will be ignored and key value will be parsed as verbatim. Example:

 name = !json null

With enable_encoding turned off, value will not be undef but will be string with the value of (as Perl literal) "!json null".

enable_quoting => bool (default: 1)

If set to false, then quotes on key value will be ignored and key value will be parsed as verbatim. Example:

 name = "line 1\nline2"

With enable_quoting turned off, value will not be a two-line string, but will be a one line string with the value of (as Perl literal) "line 1\\nline2".

enable_bracket => bool (default: 1)

If set to false, then JSON literal array will be parsed as verbatim. Example:

 name = [1,2,3]

With enable_bracket turned off, value will not be a three-element array, but will be a string with the value of (as Perl literal) "[1,2,3]".

enable_brace => bool (default: 1)

If set to false, then JSON literal object (hash) will be parsed as verbatim. Example:

 name = {"a":1,"b":2}

With enable_brace turned off, value will not be a hash with two pairs, but will be a string with the value of (as Perl literal) '{"a":1,"b":2}'.

allow_encodings => array

If defined, set list of allowed encodings. Note that if disallow_encodings is also set, an encoding must also not be in that list.

Also note that, for safety reason, if you want to enable expr encoding, you'll also need to set enable_expr to 1.

disallow_encodings => array

If defined, set list of disallowed encodings. Note that if allow_encodings is also set, an encoding must also be in that list.

Also note that, for safety reason, if you want to enable expr encoding, you'll also need to set enable_expr to 1.

enable_expr => bool (default: 0)

Whether to enable expr encoding. By default this is turned on, for safety. Please see "EXPRESSION" for more details.

allow_directives => array

If defined, only directives listed here are allowed. Note that if disallow_directives is also set, a directive must also not be in that list.

disallow_directives => array

If defined, directives listed here are not allowed. Note that if allow_directives is also set, a directive must also be in that list.

allow_bang_only => bool (default: 1)

Since the mistake of specifying a directive like this:

 !foo

instead of the correct:

 ;!foo

is very common, the spec allows it. This reader, however, can be configured to be more strict.

allow_duplicate_key => bool (default: 1)

If set to 0, you can forbid duplicate key, e.g.:

 [section]
 a=1
 a=2

or:

 [section]
 a=1
 b=2
 c=3
 a=10

In traditional INI file, to specify an array you specify multiple keys. But when there is only a single key, it is unclear if the value is a single-element array or a scalar. You can use this setting to avoid this array/scalar ambiguity in config file and force user to use JSON encoding or bracket to specify array:

 [section]
 a=[1,2]

ignore_unknown_directive => bool (default: 0)

If set to true, will not die if an unknown directive is encountered. It will simply be ignored as a regular comment.

METHODS ^

new(%attrs) => obj

$reader->read_file($filename) => obj

Read IOD configuration from a file. Return Config::IOD::Document instance. Die on errors.

$reader->read_string($str) => obj

Read IOD configuration from a string. Return Config::IOD::Document instance. Die on errors.

SEE ALSO ^

IOD - specification

Config::IOD::Reader - if you just need to read a configuration file, you should probably use this module instead. It's lighter, faster, and has a simpler interface.

IOD::Examples - sample documents

HOMEPAGE ^

Please visit the project's homepage at https://metacpan.org/release/Config-IOD.

SOURCE ^

Source repository is at https://github.com/perlancar/perl-Config-IOD.

BUGS ^

Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=Config-IOD

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.

AUTHOR ^

perlancar <perlancar@cpan.org>

COPYRIGHT AND LICENSE ^

This software is copyright (c) 2015 by perlancar@cpan.org.

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

syntax highlighting: