Config::IOD::Document - Represent IOD document
This document describes version 0.352 of Config::IOD::Document (from Perl distribution Config-IOD), released on 2021-06-23.
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
read_file
read_string
$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;
Return document object rendered as string. Automatically used for stringification.
Delete key named $name in section named $section.
$name
$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).
cond
($self, %args)
linum
parsed
key
value
raw_value
Delete section named $section.
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).
linum_start
linum_end
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).
include
linum_start => int
Only dump beginning from this line number.
linum_end => int
Only dump until this line number.
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).
$code
%args
section
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.
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).
unique => bool
If set to 1, then if coderef returns false will return early immediately and not continue to the next section.
Empty document.
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.
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.)
dump()
get_value()
delete_section()
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.
$value
ignore
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.
add
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.
top
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.
If set to 1, then if section already exists will do nothing instead of die.
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.
Optional. Insert at this specific line number. Ignores top.
List keys in the section named <$section>.
If set to 1, will only list the first occurrence of each key.
Check whether a key exists.
List sections in the document, in order of occurrence.
If set to 1, will only list the first occurrence of each section.
Check whether a section exists.
Set value of a key.
Please visit the project's homepage at https://metacpan.org/release/Config-IOD.
Source repository is at https://github.com/perlancar/perl-Config-IOD.
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.
Config::IOD
perlancar <perlancar@cpan.org>
This software is copyright (c) 2021, 2019, 2017, 2016, 2015, 2011 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.
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.