NAME

Config::IOD::Document - Represent IOD document

VERSION

This document describes version 0.353 of Config::IOD::Document (from Perl distribution Config-IOD), released on 2022-05-02.

SYNOPSIS

Obtain a document object $doc from parsing an IOD document text using Config::IOD's read_file or read_string method. Or, to produce an empty document:

$doc = Config::IOD::Document->new;

Dump document as hash of hashes:

$hoh = $doc->dump;

Get a value:

$val = $doc->get_value('section', 'key');

Insert a section:

$doc->insert_section('name');

# no nothing (instead of die) if section already exists
$doc->insert_section({ignore=>1}, 'name');

# insert at the top of document instead of bottom
$doc->insert_section({top=>1}, 'name');

# insert at specific location (line number), add some comment
$doc->insert_section({linum=>12, comment=>"foo"}, 'name');

Insert a key:

$doc->insert_key('section', 'key', 'value');

# do nothing (instead of die) if key already exists
$doc->insert_key({ignore=>1}, 'section', 'key', 'value');

# add key anyway (creating multivalue key) if key already exists
$doc->insert_key({add=>1}, 'section', 'key', 'value');

# replace (delete all occurrences of previous key first) if key already exists
$doc->insert_key({replace=>1}, 'section', 'key', 'value');

# insert at the top of section, instead of at the bottom
$doc->insert_key({top=>1}, 'section', 'key', 'value');

# insert at specific location (line number)
$doc->insert_key({linum=>12}, 'section', 'name', 'value');

Delete a section (and all keys under it):

$doc->delete_section('name');

# delete all occurrences instead of just the first one
$doc->delete_section({all=>1}, 'name');

Delete a key:

$doc->delete_key('section', 'key');

# delete all occurrences instead of just the first one
$doc->delete_key({all=>1}, 'section', 'key');

Empty document:

$doc->empty;

Dump object as IOD document string:

print $doc->as_string;

# or just:
print $doc;

ATTRIBUTES

METHODS

new(%attrs) => obj

$doc->as_string => str

Return document object rendered as string. Automatically used for stringification.

$doc->delete_key([\%opts, ]$section, $name) => $num_deleted

Delete key named $name in section named $section.

Options:

all => bool

If set to 1, then will delete all occurrences. By default only delete the first occurrence.
cond => code

Will only delete key if cond returns true. cond will be called with ($self, %args) where the hash will contain these keys: linum (int, line number), parsed (array, parsed line), key (string, key name), value (NOT YET IMPLEMENTED), raw_value (str, raw/undecoded value).

$doc->delete_section([\%opts, ]$section) => $num_deleted

Delete section named $section.

Options:

all => bool

If set to 1, then will delete all occurrences. By default only delete the first occurrence.
cond => code

Will only delete section if cond returns true. cond will be called with ($self, %args) where the hash will contain these keys: linum_start (int, starting line number), linum_end (int, ending line number).

$doc->dump([ \%opts ]) => hoh

Return a hoh (hash of section names and hashes, where each of the second-level hash is of keys and values), Values will be decoded and merging will be done, but includes are not processed (even though include directive is active).

Options:

linum_start => int

Only dump beginning from this line number.
linum_end => int

Only dump until this line number.

$doc->each_key([ \%opts , ] $code) => LIST

Execute $code for each key found in document, in order of occurrence. $code will be called with arguments ($self, %args) where %args will contain these keys: section (str, current section name), key (str, key name), value (any, value, NOT YET IMPLEMENTED/AVAILABLE), raw_value (str, raw/undecoded value), linum (int, line number, 1-based), parsed (array, parsed line).

Options:

linum_start => int

Only dump beginning from this line number.
linum_end => int

Only dump until this line number.
unique_section => bool

If set to 1, will only list the first occurence of each section.
unique_key => bool

If set to 1, will only list the first occurence of each key in the same section.
early_exit => bool

If set to 1, then if coderef returns false will return early immediately and not continue to the next key.

$doc->each_section([ \%opts , ] $code) => LIST

Execute $code for each section found in document, in order of occurrence. $code will be called with arguments ($self, %args) where %args will contain these keys: section (str, section name), linum (int, line number, 1-based), linum_start (the same as linum), linum_end (int, line number of the last line of the section), parsed (array, parsed line).

Options:

unique => bool

If set to 1, will only list the first occurence of each section.
early_exit => bool

If set to 1, then if coderef returns false will return early immediately and not continue to the next section.

$doc->empty()

Empty document.

$doc->get_directive_before_key($section, $key) => array

Find directive right before a key. Directive must directly precede key line without any blank line, e.g.:

;!lint_prereqs assume-used "undetected, used via Riap"
App::MyApp=0

If found, will return an arrayref containing directive name and arguments. Otherwise, will return undef.

$doc->get_value($section, $key) => $value

Get value. Values are decoded and section merging is respected, but includes are not processed.

Internally, will do a dump() and cache the result so subsequent get_value() will avoid re-parsing the whole document. (The cache will automatically be discarded is one of document-modifying methods like delete_section() is called.)

$doc->insert_key([\%opts, ]$section, $key, $value) => int

Insert a key named $name with value $value under $section. Return line number where the key is inserted, or undef if nothing is inserted (e.g. when ignore option is set to true). Die on failure.

Options:

create_section => bool

If set to 1, will create section (at the end of document) if it doesn't exist.
add => bool

If set to 1, will add another key if key with the same name already exists. Conflicts with ignore and <replace>.
ignore => bool

If set to 1, will do nothing if key already exists. Conflicts with add and replace.
replace => bool

If set to 1, will delete (all) previous keys first. Conflicts with add and ignore.
top => bool

If set to 1, will insert at the top of section before other keys. By default will add at the end of section.
linum => posint

Optional. Insert at this specific line number. Line number must fall within section. Ignores top.

$doc->insert_section([\%opts, ]$name) => int

Insert empty section named $name. Return line number where the section is inserted, or undef if nothing is inserted (e.g. when ignore option is set to true). Die on failure.

Options:

ignore => bool

If set to 1, then if section already exists will do nothing instead of die.
top => bool

If set to 1, will insert before any other section. By default will insert at the end of document. See also: linum.
comment => str

Optional. Comment to add at the end of section line.
linum => posint

Optional. Insert at this specific line number. Ignores top.

$doc->list_keys([ \%opts ], $section) => LIST

List keys in the section named <$section>.

Options:

unique => bool

If set to 1, will only list the first occurrence of each key.

$doc->key_exists([ \%opts ], $section, $key) => bool

Check whether a key exists.

Options:

$doc->list_sections([ \%opts ]) => LIST

List sections in the document, in order of occurrence.

Options:

unique => bool

If set to 1, will only list the first occurrence of each section.

$doc->section_exists([ \%opts ], $section) => bool

Check whether a section exists.

Options:

$doc->set_value([ \%opts ], $section, $key, $new_value)

Set value of a key.

Options:

all => bool

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.

AUTHOR

perlancar <perlancar@cpan.org>

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

To install Config::IOD, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Config::IOD

CPAN shell

perl -MCPAN -e shell
install Config::IOD

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

VERSION

SYNOPSIS

ATTRIBUTES

METHODS

new(%attrs) => obj

$doc->as_string => str

$doc->delete_key([\%opts, ]$section, $name) => $num_deleted

$doc->delete_section([\%opts, ]$section) => $num_deleted

$doc->dump([ \%opts ]) => hoh

$doc->each_key([ \%opts , ] $code) => LIST

$doc->each_section([ \%opts , ] $code) => LIST

$doc->empty()

$doc->get_directive_before_key($section, $key) => array

$doc->get_value($section, $key) => $value

$doc->insert_key([\%opts, ]$section, $key, $value) => int

$doc->insert_section([\%opts, ]$name) => int

$doc->list_keys([ \%opts ], $section) => LIST

$doc->key_exists([ \%opts ], $section, $key) => bool

$doc->list_sections([ \%opts ]) => LIST

$doc->section_exists([ \%opts ], $section) => bool

$doc->set_value([ \%opts ], $section, $key, $new_value)

HOMEPAGE

SOURCE

SEE ALSO

AUTHOR

CONTRIBUTING

COPYRIGHT AND LICENSE

BUGS

Module Install Instructions