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

CAVEATS

231       Some edge cases in section headers are not supported, and additionally
232       may not be detected when writing the config file.
233
234       Specifically, section headers with leading whitespace, trailing
235       whitespace, or newlines anywhere in the section header, will not be
236       written correctly to the file and may cause file corruption.
237

Repository

239       <https://github.com/ronsavage/Config-Tiny.git>
240

SUPPORT

242       Bugs should be reported via the CPAN bug tracker at
243
244       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Config-Tiny>
245
246       For other issues, or commercial enhancement or support, contact the
247       author.
248

AUTHOR

250       Adam Kennedy <adamk@cpan.org>
251
252       Maintanence from V 2.15: Ron Savage <http://savage.net.au/>.
253

ACKNOWLEGEMENTS

255       Thanks to Sherzod Ruzmetov <sherzodr@cpan.org> for Config::Simple,
256       which inspired this module by being not quite "simple" enough for me
257       :).
258

COPYRIGHT

294       Copyright 2002 - 2011 Adam Kennedy.
295
296       This program is free software; you can redistribute it and/or modify it
297       under the same terms as Perl itself.
298
299       The full text of the license can be found in the LICENSE file included
300       with this module.
301
302
303
304perl v5.32.0                      2020-07-28                   Config::Tiny(3)