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,
         # enable_expr         => 0,
     );
     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.

EXPRESSION

    Config::IOD::Reader 0.05 adds experimental support for expression. This
    allows you to do something like this:

     [section1]
     foo=1
     bar="monkey"
    
     [section2]
     baz =!e 1+1
     qux =!e "grease" . val("section1.bar")
     quux=!e val("qux") . " " . val('baz')

    And the result will be:

     {
         section1 => {foo=>1, bar=>"monkey"},
         section2 => {baz=>2, qux=>"greasemonkey", quux=>"greasemonkey 2"},
     }

    For safety, you'll need to set enable_expr to 1 first.

    The syntax of the expression (the expr encoding) is not officially
    specified yet in the IOD specification. It will probably be Expr (see
    Language::Expr::Manual::Syntax). At the moment, this module implements
    a very limited subset that is compatible (lowest common denominator)
    with Perl syntax and uses eval() to evaluate the expression. However,
    only the limited subset is allowed (checked by Perl 5.10 regular
    expression).

    The supported terms:

     number
     string (double-quoted and single-quoted)
     undef literal
     function call (only the 'val' function is supported)
     grouping (parenthesis)

    The supported operators are:

     + - .
     * / % x
     **
     unary -, unary +, !, ~

    The val() function refers to the configuration key. If the argument
    contains ".", it will be assumed as SECTIONNAME.KEYNAME, otherwise it
    will access the current section's key. Since parsing is done in a
    single pass, you can only refer to the already mentioned key.

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.

    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.

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.

SEE ALSO

    IOD, Config::IOD, IOD::Examples