Config::Ini::OnDrugs - Yet another INI reader/writer (round trip, includes, variables, nest)
version 0.08
# oo interface use Config::Ini::OnDrugs; my $ini = Config::Ini::OnDrugs->new(file => "file.ini"); my $section = $ini->get_section("Section"); # a hashref of param=>values my $val = $ini->get_value("Section", "Parameter"); # not yet implemented $ini->add_section("Section2"); # empty section $ini->add_section("Section3", {Param=>Value, ...}); # section with values $ini->delete_section("Section2"); $ini->set_value("Section", "Param", "New Value"); $ini->delete_value("Section", "Param"); $ini->as_tree; # dump back as string $ini->as_string; # procedural interface, Config::IOD is a shorter alias use Config::IOD qw( ini_get ini_get_section ini get_value ini_add_section ini_delete_section ini_add_value ini_set_value ini_delete_value ini_comment_value ini_uncomment_value ini_comment_section ini_uncomment_section ); my $ini = ini_get("file.ini"); my $section = ini_get_section("file.ini", "Section"); my $value = ini_get_value("file.ini", "Section", "Parameter"); ini_add_value("file.ini", , "Section", "Parameter", "Value"); ...
WARNING: THIS MODULE IS NOT FUNCTIONAL, PLEASE DO NOT USE IT. I AM STILL REVISING THE SPECIFICATION, IMPLEMENTATION IS STILL VERY MINIMAL/PARTIAL.
This module provides INI reading/writing class/functions. There are several other INI modules on CPAN; this one focuses on round trip parsing, includes, variables. The goal is to provide a usable format for configuration files suitable for automation (programatic modification) as well as editing by humans.
It means preserving everything in the file, including comments and formatting (indents, whitespaces). In other words, if you load the INI file and dump it again, the resulting dump will be identical to the original file. If you modify just one parameter, the rest will be identical to the original (including whitespaces).
Being round trip safe is useful for humans, because some of the things that are useful to humans are in the comments and whitespaces, which are not significant to machines.
Example:
; Important, only set between 2 and 40, otherwise it will explode!!! ; In fact, only set between 2 and 27.5, other values are bunk!! frob = 2.3 plunk = 20.1 thingamagic = 27.4
is much more useful than:
frob=2.3 plunk=20.1 thingamagic=2.5
Most other formats do not provide round trip parser, e.g. JSON, YAML, Config::General (Apache-style), XML; they all lose comments. They are good for automation but not ideal for humans. (Note: JSON documentation mentions the phrase "round trip", but it uses the phrase to mean integrity of values, not preserving comments/whitespaces.)
Since the INI format does not have any formal specification, here is the specification for INI as used by this module (from here on: IOD). IOD is an extended INI format. If you don't use any extended features, your IOD file is a plain INI file.
A configuration text file containing a sequence of lines, each line is either a blank line, a comment line, a directive line, a section line, or a parameter line. Parsing is done line-by-line and in one pass.
A blank line is a line containing zero or more whitespaces only. It is ignored.
A comment line begins with ; or # as it's first nonblank character (note that some INI parsers do not allow indented comment). The use of ; is preferred over #, as some INI parsers (like one in PHP 5.3+) do not recognize or warn comments using #.
A directive line is a special comment line, starting with an exclamation mark ("!") followed by a directive name and zero or more arguments. An invalid directive will be ignored and assumed to be a normal command (with warnings).
;!directivename arg ...
Directives influence parsing and turn on/off features.
Below is the list of known directives:
Include another file, as if the content of the included file is the next lines in the current file. If PATH is not absolute, it is assumed to be relative to the current file (or included file). A circular include will cause the parser to die with an error. Example:
File dir1/a.ini: [sectionA] [sub1] a=1 ;!include ../dir2/b.ini
File dir2/b.ini:
b=2 ;dedent
File dir2/b2.ini: c := 2+1
File dir2/b3.ini: c=4 [sectionB] c=1
Will parsed, will result in this configuration:
{ sectionA => { sub1 => { a => 1, b => 2, c => [3, 4], }, }, sectionB => { c => 1, }, }
Specify that from now on, when encountering a new section, fill it with values from SECTION (and then SECTION2, and so on) unless the values are already specified.
[sect1] a=1 b=2 ;!defaults sect1 [sect2] a=10 [sect3] c=1 [sect4] a=0 b:=undef
Will result in:
{sect1 => {a=>1, b=>2}, sect2 => {a=>10, b=>2}, sect3 => {a=>1, b=>2, c=>1}, sect4 => {a=>0, b=>undef},
Another, more meaty example:
[-defaults] quota=1000 ftp=1 shell=1 mysql=0 ;!defaults -defaults ; double quota for this user [user1] quota=2000 ; disable ftp for this user [user2] ftp=0 ; all admin users have unlimited quota [-admins] quota=-1 ;!defaults -admins [admin1] ; this admin cannot use shell [admin2] shell=0 ;no more defaults ;!defaults
Defaults to the same section is ignored.
Mode-merging using Data::ModeMerge. Details to be specified later.
A section line introduces a section:
[Section Name] ["quoted [] section name"] [] [""]
Comment is allowed at the end. To write a section name with problematic characters (like "\n", "\0", "]", etc.), use quotes.
To specify nested section, you indent the subsection line relative to section line (minimum is 1 whitespace):
[Outer] [Inner] [Further Inner] [a] val=1 [b] [c] val=2
will result in:
{Outer => { Inner => { "Further Inner" => { a => { val => 1, }, b => { }, }, }, c => { val => 1, }, },
Use of tab character is discouraged, but if exists as indentation it will be counted as 1 whitespace. Parameter line needs to be indented at least as its section:
[Section] [Subsection] a=1 b=2 c=3 d=4 e=5
In the above example, a, b, and c belong to Subsection will d and e belong to Section.
Non-contiguous sections are allowed, they will be assumed to be set/add parameters, e.g.:
[sect1] a=1 [sect2] a=1 [sect1] a=2 b=3
will result in sect1 containing a as [1, 2] and b as 3. However, note:
sect1
a
b
[sect1] a=1 ;!defaults sect1 [sect2] d=4 [sect1] b=2 [sect3] c=3
sect2 will contain {a=>1, d=>4} since at the point of parsing sect2, sect1 only contains {a=>1}. However, sect3 will contain {a=>1, b=>2, c=>3} since at the point of parsing sect3, sect1 already becomes {a=>1, b=>2}.
sect2
sect3
Parameter lines specify name value pairs:
Parameter name = value Parameter2=value ; this is not a comment and part of value
Parameter name and value can be quoted:
"Contains\nnewline" = "\0"
Whitespace before parameter name is allowed and can be used to enter/leave subsection (see "Subsection line"). Whitespaces between the "=" character are allowed and ignored. Trailing whitespace is allowed and ignored for quoted values but significant for unquoted values.
a=1<space> b="2"<space>
In the above example, value of a is "1" followed by a space, while value of b is just "2".
Note that some INI parsers forbid some/all of these whitespaces.
Instead of "=" you can use ":=" to specify expression instead of literal value. Expression is parsed by Language::Expr. Using expression, you can specify a null (undefined) value:
param1 := undef
or alternative of writing arrays. Instead of:
param=foo param=bar
you can write:
param := ["foo", "bar"]
Using expression you can also specify an array with a single value (not possible using "=").
param:=["foo"]
You can also specify an empty array using expression:
param:=[]
To escape ":" as part of parameter name, use quoting:
"param:"="literal, not expression"
Normally a parameter line should occur below section line, so that parameter belongs to the section. But a parameter line is also allowed before section line, in which it will belong to section called DEFAULT (configurable via the parser's default_section attribute).
DEFAULT
Quoting is done with the double-quote (") character. Known escapes are \', \", \\, \r (linefeed), \f (formfeed), \$ (literal $), \n (newline), \t (tab), \b (backspace), \a (bell), \0, octal form ("\0377"), hex form ("\xff") and wide-hex form (\x{263a}).
Quoting is allowed for section name in section line and for parameter name and value in parameter line.
You can include another file using the !include directive:
;!include "/My Home/foo.ini"
See the documentation of the !include directive for more details.
You can use variables and calculations using the expressions.
; param is 1+2+$a, literal param=1+2+$a ; param is 5 a=3 b=4 param := ($a**2 + $b**2) ** 0.5 ; to refer to sections [Section1] lang="Perl" [Section2] param:="I love " + $CONFIG['Section1']['lang']
Note: since parsing is done in 1-pass, make sure that you define a parameter first before using it in expressions.
To avoid repetition, you can specify defaults in a section and then use the values in that section for others. See documentation on the !defaults directive for more details.
To be specified later.
Below is a summary of extended features provided by IOD over "standard" INI format:
Round-trip parsing
Quoting
Indented section line, comments after section line
Indented comment line
Whitespaces before parameter name, between =, after parameter value
Some INI parsers do not allow whitespaces at all.
# as comment character
Some strict INI parsers only recognize ; as the comment starter. If in doubt, always use ;.
;
Directives (e.g. include, defaults, merging)
Other INI parsers will see directive line as regular comment line.
Expressions
Other INI parsers will see:
param:=value
as { "param:" => "value" }.
Some INI implementation support other features, and listed below are those unsupported by IOD, usually because the features are not popular:
Line continuation for multiline value
param=line 1 \ line 2\ line 3
Supported by Config::IniFiles. In IOD, use quoting:
param="line 1 \nline 2\nline 3"
Heredoc syntax for array
param=<<EOT value1 value2 EOT
Supported by Config::IniFiles. In IOD, use multiple assignment or expression:
param=value1 param=value2
or:
param:=["value1", "value2"]
None are exported by default, but they are exportable.
It is popular and familiar to many users. The format is simple to understand (this cannot be said of other formats like YAML). The simplicity of INI format also makes it easier to write round trip parser for.
IOD supports several useful (to me, at least) extended features over "standard" INI files, see "Summary of extended features".
Currently only has Perl parser
INI parsers exist everywhere though, so some of the time you can fallback to INI.
You need to learn another minilanguage for expressions
It's very similar to Perl though. See Language::Expr.
Expression parser is still slowish
I plan to fix this in the future (e.g. by switching parser to Marpa).
Sorry, no.
Other INI modules: Config::IniFiles, Config::INI, Config::INIPlus, etc.
Other alternative formats: YAML, JSON, Config::General, XML, etc.
The original blog post/discussion which leads to this module: http://blogs.perl.org/users/steven_haryanto/2011/09/yaml-vs-ini-again-and-the-plan-for-yet-another-ini-module.html
This module uses Log::Any logging framework.
This module's functions has Sub::Spec specs.
Steven Haryanto <stevenharyanto@gmail.com>
This software is copyright (c) 2011 by Steven Haryanto.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
1 POD Error
The following errors were encountered while parsing the POD:
You forgot a '=back' before '=head2'
To install Config::Ini::OnDrugs, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Config::Ini::OnDrugs
CPAN shell
perl -MCPAN -e shell install Config::Ini::OnDrugs
For more information on module installation, please visit the detailed CPAN module installation guide.