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 https://metacpan.org/release/Config-IOD.
SOURCE
Source repository is at https://github.com/perlancar/perl-Config-IOD.
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 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.