1 .\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10)
4 .\" ========================================================================
5 .de Sp \" Vertical space (when we can't use .PP)
9 .de Vb \" Begin verbatim text
14 .de Ve \" End verbatim text
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<>.
25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
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
43 .\" Escape single quotes in literal strings from groff's Unicode transform.
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.
53 . tm Index:\\$1\t\\n%\t"\\$2"
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
74 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
80 . \" simple accents for nroff and troff
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'
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 \
124 .\" ========================================================================
126 .IX Title "Config::GitLike 3"
127 .TH Config::GitLike 3 "2010-04-03" "perl v5.8.8" "User Contributed Perl Documentation"
128 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
129 .\" way too many mistakes in technical documents.
133 Config::GitLike \- git\-compatible config file parsing
135 .IX Header "SYNOPSIS"
136 This module parses git-style config files, which look like this:
140 \& repositoryformatversion = 0
143 \& logallrefupdates = true
145 \& url = spang.cc:/srv/git/home.git
146 \& fetch = +refs/heads/*:refs/remotes/origin/*
147 \& [another\-section "subsection"]
149 \& key = multiple values are OK
154 Code that uses this config module might look like:
157 \& use Config::GitLike;
159 \& my $c = Config::GitLike\->new(confname => \*(Aqconfig\*(Aq);
162 \& $c\->get( key => \*(Aqsection.name\*(Aq );
163 \& # make the return value a Perl true/false value
164 \& $c\->get( key => \*(Aqcore.filemode\*(Aq, as => \*(Aqbool\*(Aq );
166 \& # replace the old value
168 \& key => \*(Aqsection.name\*(Aq,
169 \& value => \*(Aqval1\*(Aq,
170 \& filename => \*(Aq/home/user/.config\*(Aq,
173 \& # make this key have multiple values rather than replacing the
176 \& key => \*(Aqsection.name\*(Aq,
177 \& value => \*(Aqval2\*(Aq,
178 \& filename => \*(Aq/home/user/.config\*(Aq,
182 \& # replace all occurrences of the old value for section.name with a new one
184 \& key => \*(Aqsection.name\*(Aq,
185 \& value => \*(Aqval3\*(Aq,
186 \& filename => \*(Aq/home/user/.config\*(Aq,
191 \& # make sure to reload the config files before reading if you\*(Aqve set
195 \& # get only the value of \*(Aqsection.name\*(Aq that matches \*(Aq2\*(Aq
196 \& $c\->get( key => \*(Aqsection.name\*(Aq, filter => \*(Aq2\*(Aq );
197 \& $c\->get_all( key => \*(Aqsection.name\*(Aq );
198 \& # prefixing a search regexp with a ! negates it
199 \& $c\->get_regexp( key => \*(Aq!na\*(Aq );
201 \& $c\->rename_section(
202 \& from => \*(Aqsection\*(Aq,
203 \& to => \*(Aqnew\-section\*(Aq,
204 \& filename => \*(Aq/home/user/.config\*(Aq
207 \& $c\->remove_section(
208 \& section => \*(Aqsection\*(Aq,
209 \& filename => \*(Aq/home/user/.config\*(Aq
212 \& # unsets all instances of the given key
213 \& $c\->set( key => \*(Aqsection.name\*(Aq, filename => \*(Aq/home/user/.config\*(Aq );
215 \& my %config_vals = $config\->dump;
216 \& # string representation of config data
217 \& my $str = $config\->dump;
218 \& # prints rather than returning
222 .IX Header "DESCRIPTION"
223 This module handles interaction with configuration files of the style used
224 by the version control system Git. It can both parse and modify these
225 files, as well as create entirely new ones.
227 You only need to know a few things about the configuration format in order
228 to use this module. First, a configuration file is made up of key/value
229 pairs. Every key must be contained in a section. Sections can have
230 subsections, but they don't have to. For the purposes of setting and
231 getting configuration variables, we join the section name,
232 subsection name, and variable name together with dots to get a key
233 name that looks like \*(L"section.subsection.variable\*(R". These are the
234 strings that you'll be passing in to \f(CW\*(C`key\*(C'\fR arguments.
236 Configuration files inherit from each other. By default, \f(CW\*(C`Config::GitLike\*(C'\fR
237 loads data from a system-wide configuration file, a per-user
238 configuration file, and a per-directory configuration file, but by
239 subclassing and overriding methods you can obtain any combination of
240 configuration files. By default, configuration files that don't
241 exist are just skipped.
244 <http://www.kernel.org/pub/software/scm/git/docs/git\-config.html#_configuration_file>
245 for details on the syntax of git configuration files. We won't waste pixels
246 on the nitty gritty here.
248 While the behaviour of a couple of this module's methods differ slightly
249 from the \f(CW\*(C`git config\*(C'\fR equivalents, this module can read any config file
250 written by git. The converse is usually true, but only if you don't take
251 advantage of this module's increased permissiveness when it comes to key
252 names. (See \*(L"\s-1DIFFERENCES\s0 \s-1FROM\s0 GIT-CONFIG\*(R" for details.)
254 This is an object-oriented module using Any::Moose. All
255 subroutines are object method calls.
257 A few methods have parameters that are always used for the same purpose:
259 .IX Subsection "Filenames"
260 All methods that change things in a configuration file require a filename to
261 write to, via the \f(CW\*(C`filename\*(C'\fR parameter. Since a \f(CW\*(C`Config::GitLike\*(C'\fR object can
262 be working with multiple config files that inherit from each other, we don't
263 try to figure out which one to write to automatically and let you specify
266 .IX Subsection "Casting"
267 All get and set methods can make sure the values they're returning or
268 setting are valid values of a certain type: \f(CW\*(C`bool\*(C'\fR, \f(CW\*(C`int\*(C'\fR,
269 \&\f(CW\*(C`num\*(C'\fR, or \f(CW\*(C`bool\-or\-int\*(C'\fR (or at least as close as Perl can get
270 to having these types). Do this by passing one of these types
271 in via the \f(CW\*(C`as\*(C'\fR parameter. The set method, if told to write
272 bools, will always write \*(L"true\*(R" or \*(L"false\*(R" (not anything else that
273 \&\f(CW\*(C`cast\*(C'\fR considers a valid bool).
275 Methods that are told to cast values will throw exceptions if
276 the values they're trying to cast aren't valid values of the
279 See the \*(L"cast\*(R" method documentation for more on what is considered valid
282 .IX Subsection "Filtering"
283 All get and set methods can filter what values they return via their
284 \&\f(CW\*(C`filter\*(C'\fR parameter, which is expected to be a string that is a valid
285 regex. If you want to filter items \s-1OUT\s0 instead of \s-1IN\s0, you can
286 prefix your regex with a ! and that'll do the trick.
288 Now, on the the methods!
290 .IX Header "MAIN METHODS"
291 There are the methods you're likely to use the most.
292 .SS "new( confname => 'config' )"
293 .IX Subsection "new( confname => 'config' )"
294 Create a new configuration object with the base config name \f(CW\*(C`confname\*(C'\fR.
296 \&\f(CW\*(C`confname\*(C'\fR is used to construct the filenames that will be loaded; by
297 default, these are \f(CW\*(C`/etc/confname\*(C'\fR (global configuration file),
298 \&\f(CW\*(C`~/.confname\*(C'\fR (user configuration file), and \f(CW\*(C`<Cwd\*(C'\fR/.confname> (directory
301 You can override these defaults by subclassing \f(CW\*(C`Config::GitLike\*(C'\fR and
302 overriding the methods \f(CW\*(C`global_file\*(C'\fR, \f(CW\*(C`user_file\*(C'\fR, and \f(CW\*(C`dir_file\*(C'\fR. (See
303 \&\*(L"\s-1METHODS\s0 \s-1YOU\s0 \s-1MAY\s0 \s-1WISH\s0 \s-1TO\s0 \s-1OVERRIDE\s0\*(R" for details.)
305 If you wish to enforce only being able to read/write config files that
306 git can read or write, pass in \f(CW\*(C`compatible => 1\*(C'\fR to this
307 constructor. The default rules for some components of the config
308 file are more permissive than git's (see \*(L"\s-1DIFFERENCES\s0 \s-1FROM\s0 GIT-CONFIG\*(R").
310 .IX Subsection "confname"
311 The configuration filename that you passed in when you created
312 the \f(CW\*(C`Config::GitLike\*(C'\fR object. You can change it if you want by
313 passing in a new name (and then reloading via \*(L"load\*(R").
315 .IX Subsection "load"
316 Load the global, local, and directory configuration file with the filename
317 \&\f(CW\*(C`confname\*(C'\fR(if they exist). Configuration variables loaded later
318 override those loaded earlier, so variables from the directory
319 configuration file have the highest precedence.
321 Pass in an optional path, and it will be passed on to \*(L"load_dirs\*(R" (which
322 loads the directory configuration file(s)).
324 Returns a hash copy of all loaded configuration data stored in the module
325 after the files have been loaded, or a hashref to this hash in
327 .SS "config_filenames"
328 .IX Subsection "config_filenames"
329 An array reference containing the absolute filenames of all config files
330 that are currently loaded, in the order they were loaded.
336 \& key => \*(Aqsect.subsect.key\*(Aq
337 \& as => \*(Aqint\*(Aq
338 \& filter => \*(Aq!foo
341 Return the config value associated with \f(CW\*(C`key\*(C'\fR cast as an \f(CW\*(C`as\*(C'\fR.
343 The \f(CW\*(C`key\*(C'\fR option is required (will return undef if unspecified); the \f(CW\*(C`as\*(C'\fR
344 option is not (will return a string by default). Sections and subsections
345 are specified in the key by separating them from the key name with a .
346 character. Sections, subsections, and keys may all be quoted (double or
349 If \f(CW\*(C`key\*(C'\fR doesn't exist in the config, undef is returned. Dies with
350 the exception \*(L"Multiple values\*(R" if the given key has more than one
351 value associated with it. (Use \*(L"get_all\*(R" to retrieve multiple values.)
353 Calls \*(L"load\*(R" if it hasn't been done already. Note that if you've run any
354 \&\f(CW\*(C`set\*(C'\fR calls to the loaded configuration files since the last time they were
355 loaded, you \s-1MUST\s0 call \*(L"load\*(R" again before getting, or the returned
356 configuration data may not match the configuration variables on-disk.
358 .IX Subsection "get_all"
362 \& key => \*(Aqsection.sub\*(Aq
363 \& filter => \*(Aqregex\*(Aq
364 \& as => \*(Aqint\*(Aq
367 Like \*(L"get\*(R" but does not fail if the number of values for the key is not
370 Returns a list of values (or an arrayref in scalar context).
372 .IX Subsection "get_regexp"
376 \& key => \*(Aqregex\*(Aq
377 \& filter => \*(Aqregex\*(Aq
378 \& as => \*(Aqbool\*(Aq
381 Similar to \*(L"get_all\*(R" but searches for values based on a key regex.
383 Returns a hash of name/value pairs (or a hashref in scalar context).
385 .IX Subsection "dump"
386 In scalar context, return a string containing all configuration data, sorted in
387 \&\s-1ASCII\s0 order, in the form:
391 \& section2.key=value
394 If called in void context, this string is printed instead.
396 In list context, returns a hash containing all the configuration data.
402 \& key => \*(Aqsection.name\*(Aq
403 \& value => \*(Aqbar\*(Aq
404 \& filename => File::Spec\->catfile(qw/home user/, \*(Aq.\*(Aq.$config\->confname)
405 \& filter => \*(Aqregex\*(Aq
406 \& as => \*(Aqbool\*(Aq
411 Set the key \f(CW\*(C`foo\*(C'\fR in the configuration section \f(CW\*(C`section\*(C'\fR to the value \f(CW\*(C`bar\*(C'\fR
412 in the given filename.
414 Replace \f(CW\*(C`key\*(C'\fR's value if \f(CW\*(C`key\*(C'\fR already exists.
416 To unset a key, pass in \f(CW\*(C`key\*(C'\fR but not \f(CW\*(C`value\*(C'\fR.
418 Returns true on success.
420 If you need to have a . character in your variable name, you can surround the
421 name with quotes (single or double): \f(CW\*(C`key => \*(Aqsection."foo.bar.com"\*(Aq\*(C'\fR
422 Don't do this unless you really have to.
424 \fImultiple values\fR
425 .IX Subsection "multiple values"
427 By default, set will replace the old value rather than giving a key multiple
428 values. To override this, pass in \f(CW\*(C`multiple => 1\*(C'\fR. If you want to replace
429 all instances of a multiple-valued key with a new value, you need to pass
430 in \f(CW\*(C`replace_all => 1\*(C'\fR as well.
432 .IX Subsection "group_set"
436 \& filename => \*(Aq/home/foo/.bar\*(Aq
440 Same as \*(L"set\*(R", but set a group of variables at the same time without
441 writing to disk separately for each.
443 \&\f(CW\*(C`args_ref\*(C'\fR is an array reference containing a list of hash references which
444 are essentially hashes of arguments to \f(CW\*(C`set\*(C'\fR, excluding the \f(CW\*(C`filename\*(C'\fR
445 argument since that is specified separately and the same file is used for all
446 variables to be set at once.
448 .IX Subsection "rename_section"
452 \& from => \*(Aqname.subname\*(Aq
453 \& to => \*(Aqnew.subname\*(Aq
454 \& filename => \*(Aq/file/to/edit\*(Aq
457 Rename the section existing in \f(CW\*(C`filename\*(C'\fR given by \f(CW\*(C`from\*(C'\fR to the section
458 given by \f(CW\*(C`to\*(C'\fR.
460 Throws an exception \f(CW\*(C`No such section\*(C'\fR if the section in \f(CW\*(C`from\*(C'\fR doesn't exist
461 in \f(CW\*(C`filename\*(C'\fR.
463 If no value is given for \f(CW\*(C`to\*(C'\fR, the section is removed instead of renamed.
465 Returns true on success, false if \f(CW\*(C`filename\*(C'\fR didn't exist and thus
466 the rename did nothing.
468 .IX Subsection "remove_section"
472 \& section => \*(Aqsection.subsection\*(Aq
473 \& filename => \*(Aq/file/to/edit\*(Aq
476 Just a convenience wrapper around \*(L"rename_section\*(R" for readability's sake.
477 Removes the given section (which you can do by renaming to nothing as well).
478 .ie n .SS "cascade( $bool )"
479 .el .SS "cascade( \f(CW$bool\fP )"
480 .IX Subsection "cascade( $bool )"
481 Gets or sets if only the \fBdeepest\fR configuration file in a directory
482 tree is loaded, or if all of them are loaded, shallowest to deepest.
483 Alternately, \f(CW\*(C`cascade => 1\*(C'\fR can be passed to \f(CW\*(C`new\*(C'\fR.
484 .SH "METHODS YOU MAY WISH TO OVERRIDE"
485 .IX Header "METHODS YOU MAY WISH TO OVERRIDE"
486 If your application's configuration layout is different from the default, e.g.
487 if its home directory config files are in a directory within the home
488 directory (like \f(CW\*(C`~/.git/config\*(C'\fR) instead of just dot-prefixed, override these
489 methods to return the right directory names. For fancier things like altering
490 precedence, you'll need to override \*(L"load\*(R" as well.
492 .IX Subsection "dir_file"
493 Return a string containing the path to a configuration file with the
494 name \f(CW\*(C`confname\*(C'\fR in a directory. The directory isn't specified here.
496 .IX Subsection "global_file"
497 Return the string \f(CW\*(C`/etc/confname\*(C'\fR, the absolute name of the system-wide
498 configuration file with name \f(CW\*(C`confname\*(C'\fR.
500 .IX Subsection "user_file"
501 Return a string containing the path to a configuration file
502 in the current user's home directory with filename \f(CW\*(C`confname\*(C'\fR.
504 .IX Subsection "load_dirs"
508 \& \*(Aq/path/to/look/in/\*(Aq
511 Load the configuration file with the filename \*(L"dir_file\*(R" in the current
512 working directory into the memory or, if there is no config matching
513 \&\f(CW\*(C`dir_file\*(C'\fR in the current working directory, walk up the directory tree until
514 one is found. (No error is thrown if none is found.) If an optional path
515 is passed in, that directory will be used as the base directory instead
516 of the working directory.
518 You'll want to use \*(L"load_file\*(R" to load config files from your overridden
519 version of this subroutine.
521 Returns nothing of note.
523 .IX Header "OTHER METHODS"
524 These are mostly used internally in other methods, but could be useful anyway.
526 .IX Subsection "load_global"
527 If a global configuration file with the absolute name given by
528 \&\*(L"global_file\*(R" exists, load its configuration variables into memory.
530 Returns the current contents of all the loaded configuration variables
531 after the file has been loaded, or undef if no global config file is found.
533 .IX Subsection "load_user"
534 If a configuration file with the absolute name given by
535 \&\*(L"user_file\*(R" exists, load its config variables into memory.
537 Returns the current contents of all the loaded configuration variables
538 after the file has been loaded, or undef if no user config file is found.
539 .ie n .SS "load_file( $filename )"
540 .el .SS "load_file( \f(CW$filename\fP )"
541 .IX Subsection "load_file( $filename )"
542 Takes a string containing the path to a file, opens it if it exists, loads its
543 config variables into memory, and returns the currently loaded config
544 variables (a hashref).
546 Note that you ought to only call this subroutine with an argument that you
547 know exists, otherwise config files that don't exist will be recorded as
550 .IX Subsection "parse_content"
554 \& content => \*(Aqstr\*(Aq
555 \& callback => sub {}
559 Parses the given content and runs callbacks as it finds valid information.
561 Returns undef on success and \f(CW\*(C`error($content)\*(C'\fR (the original content) on
564 \&\f(CW\*(C`callback\*(C'\fR is called like:
567 \& callback(section => $str, offset => $num, length => $num, name => $str, value => $str)
570 \&\f(CW\*(C`name\*(C'\fR and \f(CW\*(C`value\*(C'\fR may be omitted if the callback is not being called on a
571 key/value pair, or if it is being called on a key with no value.
573 \&\f(CW\*(C`error\*(C'\fR is called like:
576 \& error( content => $content, offset => $offset )
579 Where \f(CW\*(C`offset\*(C'\fR is the point in the content where the parse error occurred.
581 If you need to use this method, you might be interested in \*(L"error_callback\*(R"
584 .IX Subsection "error_callback"
588 \& content => \*(Aqstr\*(Aq
590 \& filename => \*(Aq/foo/bar/.baz\*(Aq
593 Made especially for passing to \*(L"parse_content\*(R", passed through the
594 \&\f(CW\*(C`error\*(C'\fR parameter like this:
598 \& error_callback( @_, filename => \*(Aq/file/you/were/parsing\*(Aq )
602 It's used internally wherever \*(L"parse_content\*(R" is used and will throw
603 an exception with a useful message detailing the line number, position on
604 the line, and contents of the bad line; if you find the need to use
605 \&\*(L"parse_content\*(R" elsewhere, you may find it useful as well.
606 .ie n .SS "set_multiple( $name )"
607 .el .SS "set_multiple( \f(CW$name\fP )"
608 .IX Subsection "set_multiple( $name )"
609 Mark the key string \f(CW$name\fR as containing multiple values.
612 .ie n .SS "is_multiple( $name )"
613 .el .SS "is_multiple( \f(CW$name\fP )"
614 .IX Subsection "is_multiple( $name )"
615 Return a true value if the key string \f(CW$name\fR contains multiple values; false
618 .IX Subsection "define"
622 \& section => \*(Aqstr\*(Aq
623 \& name => \*(Aqstr\*(Aq
624 \& value => \*(Aqstr\*(Aq
627 Given a section, a key name, and a valueA\*^X store this information
628 in memory in the config object.
630 Returns the value that was just defined on success, or undef
631 if no name is given and thus the key cannot be defined.
633 .IX Subsection "cast"
637 \& value => \*(Aqfoo\*(Aq
638 \& as => \*(Aqint\*(Aq
642 Return \f(CW\*(C`value\*(C'\fR cast into the type specified by \f(CW\*(C`as\*(C'\fR.
644 Valid values for \f(CW\*(C`as\*(C'\fR are \f(CW\*(C`bool\*(C'\fR, \f(CW\*(C`int\*(C'\fR, \f(CW\*(C`num\*(C'\fR, or \f(CW\*(C`bool\-or\-num\*(C'\fR. For
645 \&\f(CW\*(C`bool\*(C'\fR, \f(CW\*(C`true\*(C'\fR, \f(CW\*(C`yes\*(C'\fR, \f(CW\*(C`on\*(C'\fR, \f(CW1\fR, and undef are translated into a true
646 value (for Perl); anything else is false. Specifying a true value for the
647 \&\f(CW\*(C`human\*(C'\fR arg will get you a human-readable 'true' or 'false' rather than a
648 value that plays along with Perl's definition of truthiness (0 or 1).
650 For \f(CW\*(C`int\*(C'\fRs and \f(CW\*(C`num\*(C'\fRs, if \f(CW\*(C`value\*(C'\fR ends in \f(CW\*(C`k\*(C'\fR, \f(CW\*(C`m\*(C'\fR, or \f(CW\*(C`g\*(C'\fR, it will be
651 multiplied by 1024, 1048576, and 1073741824, respectively, before being
652 returned. \f(CW\*(C`int\*(C'\fRs are truncated after being multiplied, if they have
655 \&\f(CW\*(C`bool\-or\-int\*(C'\fR, as you might have guessed, gives you either
656 a bool or an int depending on which one applies.
658 If \f(CW\*(C`as\*(C'\fR is unspecified, \f(CW\*(C`value\*(C'\fR is returned unchanged.
660 .IX Subsection "format_section"
664 \& section => \*(Aqsection.subsection\*(Aq
668 Return a string containing the section/subsection header, formatted
669 as it should appear in a config file. If \f(CW\*(C`bare\*(C'\fR is true, the returned
670 value is not followed be a newline.
671 .SS "format_definition"
672 .IX Subsection "format_definition"
676 \& key => \*(Aqstr\*(Aq
677 \& value => \*(Aqstr\*(Aq
681 Return a string containing the key/value pair as they should be printed in the
682 config file. If \f(CW\*(C`bare\*(C'\fR is true, the returned value is not tab-indented nor
683 followed by a newline.
684 .SH "DIFFERENCES FROM GIT-CONFIG"
685 .IX Header "DIFFERENCES FROM GIT-CONFIG"
686 This module does the following things differently from git-config:
688 We are much more permissive about valid key names and section names.
689 For variables, instead of limiting variable names to alphanumeric characters
690 and \-, we allow any characters except for = and newlines, including spaces as
691 long as they are not leading or trailing, and . as long as the key name is
692 quoted. For sections, any characters but whitespace, [], and " are allowed.
693 You can enforce reading/writing only git-compatible variable names and section
694 headers by passing \f(CW\*(C`compatible => 1\*(C'\fR to the constructor.
696 When replacing variable values and renaming sections, we merely use
697 a substring replacement rather than writing out new lines formatted in the
698 default manner for new lines. Git's replacement/renaming (as of
699 1.6.3.2) is currently buggy and loses trailing comments and variables
700 that are defined on the same line as a section being renamed. Our
701 method preserves original formatting and surrounding information.
703 We also allow the 'num' type for casting, since in many cases we
704 might want to be more lenient on numbers.
706 We truncate decimal numbers that are cast to \f(CW\*(C`int\*(C'\fRs, whereas
707 Git just rejects them.
709 We don't support NUL-terminating output (the \-\-null flag to
710 git-config). Who needs it?
713 If you find any bugs in this module, report them at:
716 \& http://rt.cpan.org/
719 Include the version of the module you're using and any relevant problematic
720 configuration files or code snippets.
722 .IX Header "SEE ALSO"
723 <http://www.kernel.org/pub/software/scm/git/docs/git\-config.html#_configuration_file>,
724 Config::GitLike::Git, <http://syncwith.us/> (\f(CW\*(C`Config::GitLike\*(C'\fR is
725 used in Prophet/SD and provides a working example)
728 This program is free software; you may modify and/or redistribute it
729 under the same terms as Perl itself.
731 .IX Header "COPYRIGHT"
732 Copyright 2010 Best Practical Solutions, \s-1LLC\s0
735 Alex Vandiver <alexmv@bestpractical.com>,
736 Christine Spang <spang@bestpractical.com>
projects / catagits/Gitalist.git / blob