1Config::Tiny(3)       User Contributed Perl Documentation      Config::Tiny(3)
2
3
4

NAME

6       Config::Tiny - Read/Write .ini style files with as little code as
7       possible
8

SYNOPSIS

10               # In your configuration file
11               rootproperty=blah
12
13               [section]
14               one=twp
15               three= four
16               Foo =Bar
17               empty=
18
19               # In your program
20               use Config::Tiny;
21
22               # Create a config
23               my $Config = Config::Tiny->new;
24
25               # Open the config
26               $Config = Config::Tiny->read( 'file.conf' );
27               $Config = Config::Tiny->read( 'file.conf', 'utf8' ); # Neither ':' nor '<:' prefix!
28               $Config = Config::Tiny->read( 'file.conf', 'encoding(iso-8859-1)');
29
30               # Reading properties
31               my $rootproperty = $Config->{_}->{rootproperty};
32               my $one = $Config->{section}->{one};
33               my $Foo = $Config->{section}->{Foo};
34
35               # Changing data
36               $Config->{newsection} = { this => 'that' }; # Add a section
37               $Config->{section}->{Foo} = 'Not Bar!';     # Change a value
38               delete $Config->{_};                        # Delete a value or section
39
40               # Save a config
41               $Config->write( 'file.conf' );
42               $Config->write( 'file.conf', 'utf8' ); # Neither ':' nor '>:' prefix!
43
44               # Shortcuts
45               my($rootproperty) = $$Config{_}{rootproperty};
46
47               my($config) = Config::Tiny -> read_string('alpha=bet');
48               my($value)  = $$config{_}{alpha}; # $value is 'bet'.
49
50               my($config) = Config::Tiny -> read_string("[init]\nalpha=bet");
51               my($value)  = $$config{init}{alpha}; # $value is 'bet'.
52

DESCRIPTION

54       "Config::Tiny" is a Perl class to read and write .ini style
55       configuration files with as little code as possible, reducing load time
56       and memory overhead.
57
58       Most of the time it is accepted that Perl applications use a lot of
59       memory and modules.
60
61       The *::Tiny family of modules is specifically intended to provide an
62       ultralight alternative to the standard modules.
63
64       This module is primarily for reading human written files, and anything
65       we write shouldn't need to have documentation/comments. If you need
66       something with more power move up to Config::Simple, Config::General or
67       one of the many other "Config::*" modules.
68
69       Lastly, Config::Tiny does not preserve your comments, whitespace, or
70       the order of your config file.
71
72       See Config::Tiny::Ordered (and possibly others) for the preservation of
73       the order of the entries in the file.
74

CONFIGURATION FILE SYNTAX

76       Files are the same format as for MS Windows "*.ini" files. For example:
77
78               [section]
79               var1=value1
80               var2=value2
81
82       If a property is outside of a section at the beginning of a file, it
83       will be assigned to the "root section", available at "$Config->{_}".
84
85       Lines starting with '#' or ';' are considered comments and ignored, as
86       are blank lines.
87
88       When writing back to the config file, all comments, custom whitespace,
89       and the ordering of your config file elements is discarded. If you need
90       to keep the human elements of a config when writing back, upgrade to
91       something better, this module is not for you.
92

METHODS

94   errstr()
95       Returns a string representing the most recent error, or the empty
96       string.
97
98       You can also retrieve the error message from the $Config::Tiny::errstr
99       variable.
100
101   new()
102       The constructor "new" creates and returns an empty "Config::Tiny"
103       object.
104
105   read($filename, [$encoding])
106       Here, the [] indicate an optional parameter.
107
108       The "read" constructor reads a config file, $filename, and returns a
109       new "Config::Tiny" object containing the properties in the file.
110
111       $encoding may be used to indicate the encoding of the file, e.g. 'utf8'
112       or 'encoding(iso-8859-1)'.
113
114       Do not add a prefix to $encoding, such as '<' or '<:'.
115
116       Returns the object on success, or "undef" on error.
117
118       When "read" fails, "Config::Tiny" sets an error message internally you
119       can recover via "Config::Tiny->errstr". Although in some cases a failed
120       "read" will also set the operating system error variable $!, not all
121       errors do and you should not rely on using the $! variable.
122
123       See t/04.utf8.t and t/04.utf8.txt.
124
125   read_string($string)
126       The "read_string" method takes as argument the contents of a config
127       file as a string and returns the "Config::Tiny" object for it.
128
129   write($filename, [$encoding])
130       Here, the [] indicate an optional parameter.
131
132       The "write" method generates the file content for the properties, and
133       writes it to disk to the filename specified.
134
135       $encoding may be used to indicate the encoding of the file, e.g. 'utf8'
136       or 'encoding(iso-8859-1)'.
137
138       Do not add a prefix to $encoding, such as '>' or '>:'.
139
140       Returns true on success or "undef" on error.
141
142       See t/04.utf8.t and t/04.utf8.txt.
143
144   write_string()
145       Generates the file content for the object and returns it as a string.
146

FAQ

148   Why can't I put comments at the ends of lines?
149       Because a line like:
150
151               key=value # A comment
152
153       Sets key to 'value # A comment' :-(.
154
155       This conforms to the syntax discussed in "CONFIGURATION FILE SYNTAX".
156
157   Why can't I omit the '=' signs?
158       E.g.:
159
160               [Things]
161               my =
162               list =
163               of =
164               things =
165
166       Instead of:
167
168               [Things]
169               my
170               list
171               of
172               things
173
174       Because the use of '=' signs is a type of mandatory documentation. It
175       indicates that that section contains 4 items, and not 1 odd item split
176       over 4 lines.
177
178   Why do I have to assign the result of a method call to a variable?
179       This question comes from RT#85386.
180
181       Yes, the syntax may seem odd, but you don't have to call both new() and
182       read_string().
183
184       Try:
185
186               perl -MData::Dumper -MConfig::Tiny -E 'my $c=Config::Tiny->read_string("one=s"); say Dumper $c'
187
188       Or:
189
190               my($config) = Config::Tiny -> read_string('alpha=bet');
191               my($value)  = $$config{_}{alpha}; # $value is 'bet'.
192
193       Or even, a bit ridiculously:
194
195               my($value) = ${Config::Tiny -> read_string('alpha=bet')}{_}{alpha}; # $value is 'bet'.
196
197   Can I use a file called '0' (zero)?
198       Yes. See t/05.zero.t (test code) and t/0 (test data).
199

CAVEATS

201   Unsupported Section Headers
202       Some edge cases in section headers are not supported, and additionally
203       may not be detected when writing the config file.
204
205       Specifically, section headers with leading whitespace, trailing
206       whitespace, or newlines anywhere in the section header, will not be
207       written correctly to the file and may cause file corruption.
208
209   Setting an option more than once
210       "Config::Tiny" will only recognize the first time an option is set in a
211       config file. Any further attempts to set the same option later in the
212       config file are ignored.
213

SUPPORT

215       Bugs should be reported via the CPAN bug tracker at
216
217       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Config-Tiny>
218
219       For other issues, or commercial enhancement or support, contact the
220       author.
221

AUTHOR

223       Adam Kennedy <adamk@cpan.org>
224
225       Maintanence from V 2.15: Ron Savage <http://savage.net.au/>.
226

ACKNOWLEGEMENTS

228       Thanks to Sherzod Ruzmetov <sherzodr@cpan.org> for Config::Simple,
229       which inspired this module by being not quite "simple" enough for me
230       :).
231

SEE ALSO

233       See, amongst many: Config::Simple and Config::General.
234
235       See Config::Tiny::Ordered (and possibly others) for the preservation of
236       the order of the entries in the file.
237
238       IOD. Ini On Drugs.
239
240       IOD::Examples
241
242       App::IODUtils
243
244       Config::IOD::Reader
245
246       Config::Perl::V. Config data from Perl itself.
247
248       Config::Onion
249
250       Config::IniFiles
251
252       Config::INIPlus
253
254       Config::Hash. Allows nested data.
255
256       Config::MVP. Author: RJBS. Uses Moose. Extremely complex.
257
258       Config::TOML. See next few lines:
259
260       <https://github.com/dlc/toml>
261
262       <https://github.com/alexkalderimis/config-toml.pl>. 1 Star rating.
263
264       <https://github.com/toml-lang/toml>
265

COPYRIGHT

267       Copyright 2002 - 2011 Adam Kennedy.
268
269       This program is free software; you can redistribute it and/or modify it
270       under the same terms as Perl itself.
271
272       The full text of the license can be found in the LICENSE file included
273       with this module.
274
275
276
277perl v5.28.0                      2015-10-13                   Config::Tiny(3)