NAME
   Config::IOD - Read and write IOD/INI configuration files

VERSION
   This document describes version 0.350 of Config::IOD (from Perl
   distribution Config-IOD), released on 2019-01-17.

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 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]

   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.

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>.

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.

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 <[email protected]>

COPYRIGHT AND LICENSE
   This software is copyright (c) 2019, 2017, 2016, 2015, 2011 by
   [email protected].

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

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.