NAME
    Config::IOD::Reader - Read IOD configuration files

VERSION
    This document describes version 0.04 of Config::IOD::Reader (from Perl
    distribution Config-IOD-Reader), released on 2014-08-28.

SYNOPSIS
     use Config::IOD::Reader;
     my $reader = Config::IOD::Reader->new(
         # list of known attributes, with their default values
         # default_section     => 'GLOBAL',
         # 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,
     );
     my $config_hash = $reader->read_file('config.iod');

DESCRIPTION
    This module reads IOD configuration files. It is a minimalist
    alternative to the more fully-featured Config::IOD. It cannot write IOD
    files and is optimized for low startup overhead.

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

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

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

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

  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.

  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.

  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.

METHODS
  new(%attrs) => obj
  $reader->read_file($filename) => hash
    Read IOD configuration from a file. Die on errors.

  $reader->read_string($str) => hash
    Read IOD configuration from a string. Die on errors.

TODO
    Add attribute: "allow_dupe_section" (default: 1).

    Add attribute to set behaviour when encountering duplicate key name?
    Default is create array, but we can also croak, replace, ignore.

SEE ALSO
    IOD, Config::IOD, IOD::Examples

HOMEPAGE
    Please visit the project's homepage at
    <https://metacpan.org/release/Config-IOD-Reader>.

SOURCE
    Source repository is at
    <https://github.com/perlancar/perl-Config-IOD-Reader>.

BUGS
    Please report any bugs or feature requests on the bugtracker website
    <https://rt.cpan.org/Public/Dist/Display.html?Name=Config-IOD-Reader>

    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.

AUTHOR
    perlancar <perlancar@cpan.org>

COPYRIGHT AND LICENSE
    This software is copyright (c) 2014 by 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.