-
-
16 May 2022 00:05:08 UTC
- Distribution: Config-IOD
- Module version: 0.353
- Source (raw)
- Browse (raw)
- Changes
- Homepage
- How to Contribute
- Repository
- Issues
- Testers (459 / 0 / 0)
- Kwalitee
Bus factor: 1- 86.73% Coverage
- License: perl_5
- Perl: v5.10.1
- Activity
24 month- Tools
- Download (32.68KB)
- MetaCPAN Explorer
- Permissions
- Subscribe to distribution
- Permalinks
- This version
- Latest version
- NAME
- VERSION
- SYNOPSIS
- DESCRIPTION
- ATTRIBUTES
- default_section => str (default: GLOBAL)
- enable_directive => bool (default: 1)
- enable_encoding => bool (default: 1)
- enable_quoting => bool (default: 1)
- enable_bracket => bool (default: 1)
- enable_brace => bool (default: 1)
- enable_tilde => bool (default: 1)
- allow_encodings => array
- disallow_encodings => array
- enable_expr => bool (default: 0)
- allow_directives => array
- disallow_directives => array
- allow_bang_only => bool (default: 1)
- allow_duplicate_key => bool (default: 1)
- ignore_unknown_directive => bool (default: 0)
- warn_perl => bool (default: 0)
- METHODS
- HOMEPAGE
- SOURCE
- SEE ALSO
- AUTHOR
- CONTRIBUTOR
- CONTRIBUTING
- COPYRIGHT AND LICENSE
- BUGS
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 setenable_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 setenable_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.
Module Install Instructions
To install Config::IOD, copy and paste the appropriate command in to your terminal.
cpanm Config::IOD
perl -MCPAN -e shell install Config::IOD
For more information on module installation, please visit the detailed CPAN module installation guide.