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 Source repository is at . 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 CONTRIBUTOR Steven Haryanto 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 . 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.