Config::Tiny(3pm)

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 an empty config
23               my $Config = Config::Tiny->new;
24
25               # Create a config with data
26               my $config = Config::Tiny->new({
27                       _ => { rootproperty => "Bar" },
28                       section => { one => "value", Foo => 42 } });
29
30               # Open the config
31               $Config = Config::Tiny->read( 'file.conf' );
32               $Config = Config::Tiny->read( 'file.conf', 'utf8' ); # Neither ':' nor '<:' prefix!
33               $Config = Config::Tiny->read( 'file.conf', 'encoding(iso-8859-1)');
34
35               # Reading properties
36               my $rootproperty = $Config->{_}->{rootproperty};
37               my $one = $Config->{section}->{one};
38               my $Foo = $Config->{section}->{Foo};
39
40               # Changing data
41               $Config->{newsection} = { this => 'that' }; # Add a section
42               $Config->{section}->{Foo} = 'Not Bar!';     # Change a value
43               delete $Config->{_};                        # Delete a value or section
44
45               # Save a config
46               $Config->write( 'file.conf' );
47               $Config->write( 'file.conf', 'utf8' ); # Neither ':' nor '>:' prefix!
48
49               # Shortcuts
50               my($rootproperty) = $$Config{_}{rootproperty};
51
52               my($config) = Config::Tiny -> read_string('alpha=bet');
53               my($value)  = $$config{_}{alpha}; # $value is 'bet'.
54
55               my($config) = Config::Tiny -> read_string("[init]\nalpha=bet");
56               my($value)  = $$config{init}{alpha}; # $value is 'bet'.
57

DESCRIPTION

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

CONFIGURATION FILE SYNTAX

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

METHODS

99   errstr()
100       Returns a string representing the most recent error, or the empty
101       string.
102
103       You can also retrieve the error message from the $Config::Tiny::errstr
104       variable.
105
106   new([$config])
107       Here, the [] indicate an optional parameter.
108
109       The constructor "new" creates and returns a "Config::Tiny" object.
110
111       This will normally be a new, empty configuration, but you may also pass
112       a hashref here which will be turned into an object of this class. This
113       hashref should have a structure suitable for a configuration file, that
114       is, a hash of hashes where the key "_" is treated specially as the root
115       section.
116
117   read($filename, [$encoding])
118       Here, the [] indicate an optional parameter.
119
120       The "read" constructor reads a config file, $filename, and returns a
121       new "Config::Tiny" object containing the properties in the file.
122
123       $encoding may be used to indicate the encoding of the file, e.g. 'utf8'
124       or 'encoding(iso-8859-1)'.
125
126       Do not add a prefix to $encoding, such as '<' or '<:'.
127
128       Returns the object on success, or "undef" on error.
129
130       When "read" fails, "Config::Tiny" sets an error message internally you
131       can recover via "Config::Tiny->errstr". Although in some cases a failed
132       "read" will also set the operating system error variable $!, not all
133       errors do and you should not rely on using the $! variable.
134
135       See t/04.utf8.t and t/04.utf8.txt.
136
137   read_string($string)
138       The "read_string" method takes as argument the contents of a config
139       file as a string and returns the "Config::Tiny" object for it.
140
141   write($filename, [$encoding])
142       Here, the [] indicate an optional parameter.
143
144       The "write" method generates the file content for the properties, and
145       writes it to disk to the filename specified.
146
147       $encoding may be used to indicate the encoding of the file, e.g. 'utf8'
148       or 'encoding(iso-8859-1)'.
149
150       Do not add a prefix to $encoding, such as '>' or '>:'.
151
152       Returns true on success or "undef" on error.
153
154       See t/04.utf8.t and t/04.utf8.txt.
155
156   write_string()
157       Generates the file content for the object and returns it as a string.
158

FAQ

160   What happens if a key is repeated?
161       The last value is retained, overwriting any previous values.
162
163       See t/06.repeat.key.t.
164
165   Why can't I put comments at the ends of lines?
166       o The # char is only introduces a comment when it's at the start of a
167       line.
168           So a line like:
169
170                   key=value # A comment
171
172           Sets key to 'value # A comment', which, presumably, you did not
173           intend.
174
175           This conforms to the syntax discussed in "CONFIGURATION FILE
176           SYNTAX".
177
178       o Comments matching /\s\;\s.+$//g; are ignored.
179           This means you can't preserve the suffix using:
180
181                   key = Prefix ; Suffix
182
183           Result: key is now 'Prefix'.
184
185           But you can do this:
186
187                   key = Prefix;Suffix
188
189           Result: key is now 'Prefix;Suffix'.
190
191           Or this:
192
193                   key = Prefix; Suffix
194
195           Result: key is now 'Prefix; Suffix'.
196
197       See t/07.trailing.comment.t.
198
199   Why can't I omit the '=' signs?
200       E.g.:
201
202               [Things]
203               my =
204               list =
205               of =
206               things =
207
208       Instead of:
209
210               [Things]
211               my
212               list
213               of
214               things
215
216       Because the use of '=' signs is a type of mandatory documentation. It
217       indicates that that section contains 4 items, and not 1 odd item split
218       over 4 lines.
219
220   Why do I have to assign the result of a method call to a variable?
221       This question comes from RT#85386.
222
223       Yes, the syntax may seem odd, but you don't have to call both new() and
224       read_string().
225
226       Try:
227
228               perl -MData::Dumper -MConfig::Tiny -E 'my $c=Config::Tiny->read_string("one=s"); say Dumper $c'
229
230       Or:
231
232               my($config) = Config::Tiny -> read_string('alpha=bet');
233               my($value)  = $$config{_}{alpha}; # $value is 'bet'.
234
235       Or even, a bit ridiculously:
236
237               my($value) = ${Config::Tiny -> read_string('alpha=bet')}{_}{alpha}; # $value is 'bet'.
238
239   Can I use a file called '0' (zero)?
240       Yes. See t/05.zero.t (test code) and t/0 (test data).
241

CAVEATS

243       Some edge cases in section headers are not supported, and additionally
244       may not be detected when writing the config file.
245
246       Specifically, section headers with leading whitespace, trailing
247       whitespace, or newlines anywhere in the section header, will not be
248       written correctly to the file and may cause file corruption.
249

Repository

251       <https://github.com/ronsavage/Config-Tiny.git>
252

SUPPORT

254       Bugs should be reported via the CPAN bug tracker at
255
256       <https://github.com/ronsavage/Config-Tiny/issues>
257
258       For other issues, or commercial enhancement or support, contact the
259       author.
260

AUTHOR

262       Adam Kennedy <adamk@cpan.org>
263
264       Maintanence from V 2.15: Ron Savage <http://savage.net.au/>.
265

ACKNOWLEGEMENTS

267       Thanks to Sherzod Ruzmetov <sherzodr@cpan.org> for Config::Simple,
268       which inspired this module by being not quite "simple" enough for me
269       :).
270

COPYRIGHT

306       Copyright 2002 - 2011 Adam Kennedy.
307
308       This program is free software; you can redistribute it and/or modify it
309       under the same terms as Perl itself.
310
311       The full text of the license can be found in the LICENSE file included
312       with this module.
313
314
315
316perl v5.34.0                      2021-09-22                   Config::Tiny(3)