NAME
Config::IOD - Read and write IOD/INI configuration files
VERSION
This document describes version 0.353 of Config::IOD (from Perl
distribution Config-IOD), released on 2022-05-02.
SYNOPSIS
use Config::IOD;
my $iod = Config::IOD->new(
# list of known attributes, with their default values
# default_section => 'GLOBAL',
# enable_directive => 1,
# 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,
# allow_duplicate_key => 1,
# ignore_unknown_directive => 0,
);
Read IOD/INI 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 (IOD is
an INI-like format with more precise specification, some extra features,
and 99% compatible with typical INI 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_directive => bool (default: 1)
If set to false, then directives will not be parsed. Lines such as below
will be considered a regular comment:
;!include foo.ini
and lines such as below will be considered a syntax error (regardless of
the "allow_bang_only" setting):
!include foo.ini
NOTE: Turning this setting off violates IOD specification.
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".
NOTE: Turning this setting off violates IOD specification.
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".
NOTE: Turning this setting off violates IOD specification.
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]".
NOTE: Turning this setting off violates IOD specification.
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}'.
NOTE: Turning this setting off violates IOD specification.
enable_tilde => bool (default: 1)
If set to true (the default), then value that starts with "~" (tilde)
will be assumed to use !path encoding, unless an explicit encoding has
been otherwise specified.
Example:
log_dir = ~/logs ; ~ will be resolved to current user's home directory
With "enable_tilde" turned off, value will still be literally "~/logs".
NOTE: Turning this setting off violates IOD specification.
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 off, 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]
NOTE: Turning this setting off violates IOD specification.
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.
NOTE: Turning this setting on violates IOD specification.
warn_perl => bool (default: 0)
Emit warning if configuration contains key line like these:
foo=>"bar"
foo => bar,
which suggest user is assuming configuration is in Perl format instead
of INI.
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.
HOMEPAGE
Please visit the project's homepage at
SOURCE
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
AUTHOR
perlancar <perlancar@cpan.org>
CONTRIBUTOR
Steven Haryanto <stevenharyanto@gmail.com>
CONTRIBUTING
To contribute, you can send patches by email/via RT, or send pull
requests on GitHub.
Most of the time, you don't need to build the distribution yourself. You
can simply modify the code, then test via:
% prove -l
If you want to build the distribution (e.g. to try to install it locally
on your system), you can install Dist::Zilla,
Dist::Zilla::PluginBundle::Author::PERLANCAR, and sometimes one or two
other Dist::Zilla plugin and/or Pod::Weaver::Plugin. Any additional
steps required beyond that are considered a bug and can be reported to
me.
COPYRIGHT AND LICENSE
This software is copyright (c) 2022, 2021, 2019, 2017, 2016, 2015, 2011
by perlancar <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.
BUGS
Please report any bugs or feature requests on the bugtracker website
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.