local-lib5/man/man3/Config::Tiny.3pm

   1 .\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 'br\}
  42 .\"
  43 .\" Escape single quotes in literal strings from groff's Unicode transform.
  44 .ie \n(.g .ds Aq \(aq
  45 .el       .ds Aq '
  46 .\"
  47 .\" If the F register is turned on, we'll generate index entries on stderr for
  48 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  49 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  50 .\" output yourself in some meaningful fashion.
  51 .ie \nF \{\
  52 .    de IX
  53 .    tm Index:\\$1\t\\n%\t"\\$2"
  54 ..
  55 .    nr % 0
  56 .    rr F
  57 .\}
  58 .el \{\
  59 .    de IX
  60 ..
  61 .\}
  62 .\"
  63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  64 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  65 .    \" fudge factors for nroff and troff
  66 .if n \{\
  67 .    ds #H 0
  68 .    ds #V .8m
  69 .    ds #F .3m
  70 .    ds #[ \f1
  71 .    ds #] \fP
  72 .\}
  73 .if t \{\
  74 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  75 .    ds #V .6m
  76 .    ds #F 0
  77 .    ds #[ \&
  78 .    ds #] \&
  79 .\}
  80 .    \" simple accents for nroff and troff
  81 .if n \{\
  82 .    ds ' \&
  83 .    ds ` \&
  84 .    ds ^ \&
  85 .    ds , \&
  86 .    ds ~ ~
  87 .    ds /
  88 .\}
  89 .if t \{\
  90 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  91 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  92 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  93 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  94 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
  95 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
  96 .\}
  97 .    \" troff and (daisy-wheel) nroff accents
  98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
  99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 105 .ds ae a\h'-(\w'a'u*4/10)'e
 106 .ds Ae A\h'-(\w'A'u*4/10)'E
 107 .    \" corrections for vroff
 108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 110 .    \" for low resolution devices (crt and lpr)
 111 .if \n(.H>23 .if \n(.V>19 \
 112 \{\
 113 .    ds : e
 114 .    ds 8 ss
 115 .    ds o a
 116 .    ds d- d\h'-1'\(ga
 117 .    ds D- D\h'-1'\(hy
 118 .    ds th \o'bp'
 119 .    ds Th \o'LP'
 120 .    ds ae ae
 121 .    ds Ae AE
 122 .\}
 123 .rm #[ #] #H #V #F C
 124 .\" ========================================================================
 125 .\"
 126 .IX Title "Config::Tiny 3"
 127 .TH Config::Tiny 3 "2007-11-02" "perl v5.8.7" "User Contributed Perl Documentation"
 128 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 129 .\" way too many mistakes in technical documents.
 130 .if n .ad l
 131 .nh
 132 .SH "NAME"
 133 Config::Tiny \- Read/Write .ini style files with as little code as possible
 134 .SH "SYNOPSIS"
 135 .IX Header "SYNOPSIS"
 136 .Vb 2
 137 \&    # In your configuration file
 138 \&    rootproperty=blah
 139 \&
 140 \&    [section]
 141 \&    one=twp
 142 \&    three= four
 143 \&    Foo =Bar
 144 \&    empty=
 145 \&
 146 \&    # In your program
 147 \&    use Config::Tiny;
 148 \&
 149 \&    # Create a config
 150 \&    my $Config = Config::Tiny\->new();
 151 \&
 152 \&    # Open the config
 153 \&    $Config = Config::Tiny\->read( \*(Aqfile.conf\*(Aq );
 154 \&
 155 \&    # Reading properties
 156 \&    my $rootproperty = $Config\->{_}\->{rootproperty};
 157 \&    my $one = $Config\->{section}\->{one};
 158 \&    my $Foo = $Config\->{section}\->{Foo};
 159 \&
 160 \&    # Changing data
 161 \&    $Config\->{newsection} = { this => \*(Aqthat\*(Aq }; # Add a section
 162 \&    $Config\->{section}\->{Foo} = \*(AqNot Bar!\*(Aq;     # Change a value
 163 \&    delete $Config\->{_};                        # Delete a value or section
 164 \&
 165 \&    # Save a config
 166 \&    $Config\->write( \*(Aqfile.conf\*(Aq );
 167 .Ve
 168 .SH "DESCRIPTION"
 169 .IX Header "DESCRIPTION"
 170 \&\f(CW\*(C`Config::Tiny\*(C'\fR is a perl class to read and write .ini style configuration
 171 files with as little code as possible, reducing load time and memory
 172 overhead. Most of the time it is accepted that Perl applications use a lot
 173 of memory and modules. The \f(CW\*(C`::Tiny\*(C'\fR family of modules is specifically
 174 intended to provide an ultralight alternative to the standard modules.
 175 .PP
 176 This module is primarily for reading human written files, and anything we
 177 write shouldn't need to have documentation/comments. If you need something
 178 with more power move up to Config::Simple, Config::General or one of
 179 the many other \f(CW\*(C`Config::\*(C'\fR modules. To rephrase, Config::Tiny does \fBnot\fR
 180 preserve your comments, whitespace, or the order of your config file.
 181 .SH "CONFIGURATION FILE SYNTAX"
 182 .IX Header "CONFIGURATION FILE SYNTAX"
 183 Files are the same format as for windows .ini files. For example:
 184 .PP
 185 .Vb 3
 186 \&        [section]
 187 \&        var1=value1
 188 \&        var2=value2
 189 .Ve
 190 .PP
 191 If a property is outside of a section at the beginning of a file, it will
 192 be assigned to the \f(CW"root section"\fR, available at \f(CW\*(C`$Config\->{_}\*(C'\fR.
 193 .PP
 194 Lines starting with \f(CW\*(Aq#\*(Aq\fR or \f(CW\*(Aq;\*(Aq\fR are considered comments and ignored,
 195 as are blank lines.
 196 .PP
 197 When writing back to the config file, all comments, custom whitespace,
 198 and the ordering of your config file elements is discarded. If you need
 199 to keep the human elements of a config when writing back, upgrade to
 200 something better, this module is not for you.
 201 .SH "METHODS"
 202 .IX Header "METHODS"
 203 .SS "new"
 204 .IX Subsection "new"
 205 The constructor \f(CW\*(C`new\*(C'\fR creates and returns an empty \f(CW\*(C`Config::Tiny\*(C'\fR object.
 206 .ie n .SS "read $filename"
 207 .el .SS "read \f(CW$filename\fP"
 208 .IX Subsection "read $filename"
 209 The \f(CW\*(C`read\*(C'\fR constructor reads a config file, and returns a new
 210 \&\f(CW\*(C`Config::Tiny\*(C'\fR object containing the properties in the file.
 211 .PP
 212 Returns the object on success, or \f(CW\*(C`undef\*(C'\fR on error.
 213 .PP
 214 When \f(CW\*(C`read\*(C'\fR fails, \f(CW\*(C`Config::Tiny\*(C'\fR sets an error message internally
 215 you can recover via \f(CW\*(C`<Config::Tiny\-\*(C'\fRerrstr>>. Although in \fBsome\fR
 216 cases a failed \f(CW\*(C`read\*(C'\fR will also set the operating system error
 217 variable \f(CW$!\fR, not all errors do and you should not rely on using
 218 the \f(CW$!\fR variable.
 219 .ie n .SS "read_string $string;"
 220 .el .SS "read_string \f(CW$string\fP;"
 221 .IX Subsection "read_string $string;"
 222 The \f(CW\*(C`read_string\*(C'\fR method takes as argument the contents of a config file
 223 as a string and returns the \f(CW\*(C`Config::Tiny\*(C'\fR object for it.
 224 .ie n .SS "write $filename"
 225 .el .SS "write \f(CW$filename\fP"
 226 .IX Subsection "write $filename"
 227 The \f(CW\*(C`write\*(C'\fR method generates the file content for the properties, and
 228 writes it to disk to the filename specified.
 229 .PP
 230 Returns true on success or \f(CW\*(C`undef\*(C'\fR on error.
 231 .SS "write_string"
 232 .IX Subsection "write_string"
 233 Generates the file content for the object and returns it as a string.
 234 .SS "errstr"
 235 .IX Subsection "errstr"
 236 When an error occurs, you can retrieve the error message either from the
 237 \&\f(CW$Config::Tiny::errstr\fR variable, or using the \f(CW\*(C`errstr()\*(C'\fR method.
 238 .SS "property_string"
 239 .IX Subsection "property_string"
 240 This method is called to produce the string used to represent the property in a
 241 section.  It is passed the section name and property name.
 242 .SS "set"
 243 .IX Subsection "set"
 244 This is a convenience is called to set a value found in the parsed config string.  It is
 245 passed the section name, property name, and value.
 246 .SH "SUPPORT"
 247 .IX Header "SUPPORT"
 248 Bugs should be reported via the \s-1CPAN\s0 bug tracker at
 249 .PP
 250 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Config\-Tiny>
 251 .PP
 252 For other issues, or commercial enhancement or support, contact the author.
 253 .SH "AUTHOR"
 254 .IX Header "AUTHOR"
 255 Adam Kennedy <adamk@cpan.org>
 256 .SH "ACKNOWLEGEMENTS"
 257 .IX Header "ACKNOWLEGEMENTS"
 258 Thanks to Sherzod Ruzmetov <sherzodr@cpan.org> for
 259 Config::Simple, which inspired this module by being not quite
 260 \&\*(L"simple\*(R" enough for me :)
 261 .SH "SEE ALSO"
 262 .IX Header "SEE ALSO"
 263 Config::Simple, Config::General, ali.as
 264 .SH "COPYRIGHT"
 265 .IX Header "COPYRIGHT"
 266 Copyright 2002 \- 2007 Adam Kennedy.
 267 .PP
 268 This program is free software; you can redistribute
 269 it and/or modify it under the same terms as Perl itself.
 270 .PP
 271 The full text of the license can be found in the
 272 \&\s-1LICENSE\s0 file included with this module.