Config::GitLike(3pm)

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

NAME

6       Config::GitLike - git-compatible config file parsing
7

SYNOPSIS

9       This module parses git-style config files, which look like this:
10
11           [core]
12               repositoryformatversion = 0
13               filemode = true
14               bare = false
15               logallrefupdates = true
16           [remote "origin"]
17               url = spang.cc:/srv/git/home.git
18               fetch = +refs/heads/*:refs/remotes/origin/*
19           [another-section "subsection"]
20               key = test
21               key = multiple values are OK
22               emptyvalue =
23               novalue
24
25       Code that uses this config module might look like:
26
27           use Config::GitLike;
28
29           my $c = Config::GitLike->new(confname => 'config');
30           $c->load;
31
32           $c->get( key => 'section.name' );
33           # make the return value a Perl true/false value
34           $c->get( key => 'core.filemode', as => 'bool' );
35
36           # replace the old value
37           $c->set(
38               key => 'section.name',
39               value => 'val1',
40               filename => '/home/user/.config',
41           );
42
43           # make this key have multiple values rather than replacing the
44           # old value
45           $c->set(
46               key => 'section.name',
47               value => 'val2',
48               filename => '/home/user/.config',
49               multiple => 1,
50           );
51
52           # replace all occurrences of the old value for section.name with a new one
53           $c->set(
54               key => 'section.name',
55               value => 'val3',
56               filename => '/home/user/.config',
57               multiple => 1,
58               replace_all => 1,
59           );
60
61           # make sure to reload the config files before reading if you've set
62           # any variables!
63           $c->load;
64
65           # get only the value of 'section.name' that matches '2'
66           $c->get( key => 'section.name', filter => '2' );
67           $c->get_all( key => 'section.name' );
68           # prefixing a search regexp with a ! negates it
69           $c->get_regexp( key => '!na' );
70
71           $c->rename_section(
72               from => 'section',
73               to => 'new-section',
74               filename => '/home/user/.config'
75           );
76
77           $c->remove_section(
78               section => 'section',
79               filename => '/home/user/.config'
80           );
81
82           # unsets all instances of the given key
83           $c->set( key => 'section.name', filename => '/home/user/.config' );
84
85           my %config_vals = $config->dump;
86           # string representation of config data
87           my $str = $config->dump;
88           # prints rather than returning
89           $config->dump;
90

DESCRIPTION

92       This module handles interaction with configuration files of the style
93       used by the version control system Git. It can both parse and modify
94       these files, as well as create entirely new ones.
95
96       You only need to know a few things about the configuration format in
97       order to use this module. First, a configuration file is made up of
98       key/value pairs. Every key must be contained in a section. Sections can
99       have subsections, but they don't have to. For the purposes of setting
100       and getting configuration variables, we join the section name,
101       subsection name, and variable name together with dots to get a key name
102       that looks like "section.subsection.variable". These are the strings
103       that you'll be passing in to "key" arguments.
104
105       Configuration files inherit from each other. By default,
106       "Config::GitLike" loads data from a system-wide configuration file, a
107       per-user configuration file, and a per-directory configuration file,
108       but by subclassing and overriding methods you can obtain any
109       combination of configuration files. By default, configuration files
110       that don't exist are just skipped.
111
112       See
113       http://www.kernel.org/pub/software/scm/git/docs/git-config.html#_configuration_file
114       <http://www.kernel.org/pub/software/scm/git/docs/git-
115       config.html#_configuration_file> for details on the syntax of git
116       configuration files. We won't waste pixels on the nitty gritty here.
117
118       While the behaviour of a couple of this module's methods differ
119       slightly from the "git config" equivalents, this module can read any
120       config file written by git. The converse is usually true, but only if
121       you don't take advantage of this module's increased permissiveness when
122       it comes to key names. (See "DIFFERENCES FROM GIT-CONFIG" for details.)
123
124       This is an object-oriented module using Any::Moose. All subroutines are
125       object method calls.
126
127       A few methods have parameters that are always used for the same
128       purpose:
129
130   Filenames
131       All methods that change things in a configuration file require a
132       filename to write to, via the "filename" parameter. Since a
133       "Config::GitLike" object can be working with multiple config files that
134       inherit from each other, we don't try to figure out which one to write
135       to automatically and let you specify instead.
136
137   Casting
138       All get and set methods can make sure the values they're returning or
139       setting are valid values of a certain type: "bool", "int", "num", or
140       "bool-or-int" (or at least as close as Perl can get to having these
141       types). Do this by passing one of these types in via the "as"
142       parameter. The set method, if told to write bools, will always write
143       "true" or "false" (not anything else that "cast" considers a valid
144       bool).
145
146       Methods that are told to cast values will throw exceptions if the
147       values they're trying to cast aren't valid values of the given type.
148
149       See the "cast" method documentation for more on what is considered
150       valid for each type.
151
152   Filtering
153       All get and set methods can filter what values they return via their
154       "filter" parameter, which is expected to be a string that is a valid
155       regex. If you want to filter items OUT instead of IN, you can prefix
156       your regex with a ! and that'll do the trick.
157
158       Now, on the the methods!
159

MAIN METHODS

161       There are the methods you're likely to use the most.
162
163   new( confname => 'config' )
164       Create a new configuration object with the base config name "confname".
165
166       "confname" is used to construct the filenames that will be loaded; by
167       default, these are "/etc/confname" (global configuration file),
168       "~/.confname" (user configuration file), and "<Cwd"/.confname>
169       (directory configuration file).
170
171       You can override these defaults by subclassing "Config::GitLike" and
172       overriding the methods "global_file", "user_file", and "dir_file". (See
173       "METHODS YOU MAY WISH TO OVERRIDE" for details.)
174
175       If you wish to enforce only being able to read/write config files that
176       git can read or write, pass in "compatible => 1" to this constructor.
177       The default rules for some components of the config file are more
178       permissive than git's (see "DIFFERENCES FROM GIT-CONFIG").
179
180   confname
181       The configuration filename that you passed in when you created the
182       "Config::GitLike" object. You can change it if you want by passing in a
183       new name (and then reloading via "load").
184
185   load
186       Load the global, local, and directory configuration file with the
187       filename "confname"(if they exist). Configuration variables loaded
188       later override those loaded earlier, so variables from the directory
189       configuration file have the highest precedence.
190
191       Pass in an optional path, and it will be passed on to "load_dirs"
192       (which loads the directory configuration file(s)).
193
194       Returns a hash copy of all loaded configuration data stored in the
195       module after the files have been loaded, or a hashref to this hash in
196       scalar context.
197
198   config_filenames
199       An array reference containing the absolute filenames of all config
200       files that are currently loaded, in the order they were loaded.
201
202   get
203       Parameters:
204
205           key => 'sect.subsect.key'
206           as => 'int'
207           filter => '!foo
208
209       Return the config value associated with "key" cast as an "as".
210
211       The "key" option is required (will return undef if unspecified); the
212       "as" option is not (will return a string by default). Sections and
213       subsections are specified in the key by separating them from the key
214       name with a .  character. Sections, subsections, and keys may all be
215       quoted (double or single quotes).
216
217       If "key" doesn't exist in the config, undef is returned. Dies with the
218       exception "Multiple values" if the given key has more than one value
219       associated with it. (Use "get_all" to retrieve multiple values.)
220
221       Calls "load" if it hasn't been done already. Note that if you've run
222       any "set" calls to the loaded configuration files since the last time
223       they were loaded, you MUST call "load" again before getting, or the
224       returned configuration data may not match the configuration variables
225       on-disk.
226
227   get_all
228       Parameters:
229
230           key => 'section.sub'
231           filter => 'regex'
232           as => 'int'
233
234       Like "get" but does not fail if the number of values for the key is not
235       exactly one.
236
237       Returns a list of values (or an arrayref in scalar context).
238
239   get_regexp
240       Parameters:
241
242           key => 'regex'
243           filter => 'regex'
244           as => 'bool'
245
246       Similar to "get_all" but searches for values based on a key regex.
247
248       Returns a hash of name/value pairs (or a hashref in scalar context).
249
250   dump
251       In scalar context, return a string containing all configuration data,
252       sorted in ASCII order, in the form:
253
254           section.key=value
255           section2.key=value
256
257       If called in void context, this string is printed instead.
258
259       In list context, returns a hash containing all the configuration data.
260
261   set
262       Parameters:
263
264           key => 'section.name'
265           value => 'bar'
266           filename => File::Spec->catfile(qw/home user/, '.'.$config->confname)
267           filter => 'regex'
268           as => 'bool'
269           multiple => 1
270           replace_all => 1
271
272       Set the key "foo" in the configuration section "section" to the value
273       "bar" in the given filename.
274
275       Replace "key"'s value if "key" already exists.
276
277       To unset a key, pass in "key" but not "value".
278
279       Returns true on success.
280
281       If you need to have a . character in your variable name, you can
282       surround the name with quotes (single or double): "key =&gt
283       'section."foo.bar.com"'" Don't do this unless you really have to.
284
285       multiple values
286
287       By default, set will replace the old value rather than giving a key
288       multiple values. To override this, pass in "multiple => 1". If you want
289       to replace all instances of a multiple-valued key with a new value, you
290       need to pass in "replace_all => 1" as well.
291
292   group_set
293       Parameters:
294
295           filename => '/home/foo/.bar'
296           args_ref => $ref
297
298       Same as "set", but set a group of variables at the same time without
299       writing to disk separately for each.
300
301       "args_ref" is an array reference containing a list of hash references
302       which are essentially hashes of arguments to "set", excluding the
303       "filename" argument since that is specified separately and the same
304       file is used for all variables to be set at once.
305
306   rename_section
307       Parameters:
308
309           from => 'name.subname'
310           to => 'new.subname'
311           filename => '/file/to/edit'
312
313       Rename the section existing in "filename" given by "from" to the
314       section given by "to".
315
316       Throws an exception "No such section" if the section in "from" doesn't
317       exist in "filename".
318
319       If no value is given for "to", the section is removed instead of
320       renamed.
321
322       Returns true on success, false if "filename" didn't exist and thus the
323       rename did nothing.
324
325   remove_section
326       Parameters:
327
328           section => 'section.subsection'
329           filename => '/file/to/edit'
330
331       Just a convenience wrapper around "rename_section" for readability's
332       sake.  Removes the given section (which you can do by renaming to
333       nothing as well).
334
335   cascade( $bool )
336       Gets or sets if only the deepest configuration file in a directory tree
337       is loaded, or if all of them are loaded, shallowest to deepest.
338       Alternately, "cascade => 1" can be passed to "new".
339

METHODS YOU MAY WISH TO OVERRIDE

341       If your application's configuration layout is different from the
342       default, e.g.  if its home directory config files are in a directory
343       within the home directory (like "~/.git/config") instead of just dot-
344       prefixed, override these methods to return the right directory names.
345       For fancier things like altering precedence, you'll need to override
346       "load" as well.
347
348   dir_file
349       Return a string containing the path to a configuration file with the
350       name "confname" in a directory. The directory isn't specified here.
351
352   global_file
353       Return the string "/etc/confname", the absolute name of the system-wide
354       configuration file with name "confname".
355
356   user_file
357       Return a string containing the path to a configuration file in the
358       current user's home directory with filename "confname".
359
360   load_dirs
361       Parameters:
362
363           '/path/to/look/in/'
364
365       Load the configuration file with the filename "dir_file" in the current
366       working directory into the memory or, if there is no config matching
367       "dir_file" in the current working directory, walk up the directory tree
368       until one is found. (No error is thrown if none is found.) If an
369       optional path is passed in, that directory will be used as the base
370       directory instead of the working directory.
371
372       You'll want to use "load_file" to load config files from your
373       overridden version of this subroutine.
374
375       Returns nothing of note.
376

OTHER METHODS

378       These are mostly used internally in other methods, but could be useful
379       anyway.
380
381   load_global
382       If a global configuration file with the absolute name given by
383       "global_file" exists, load its configuration variables into memory.
384
385       Returns the current contents of all the loaded configuration variables
386       after the file has been loaded, or undef if no global config file is
387       found.
388
389   load_user
390       If a configuration file with the absolute name given by "user_file"
391       exists, load its config variables into memory.
392
393       Returns the current contents of all the loaded configuration variables
394       after the file has been loaded, or undef if no user config file is
395       found.
396
397   load_file( $filename )
398       Takes a string containing the path to a file, opens it if it exists,
399       loads its config variables into memory, and returns the currently
400       loaded config variables (a hashref).
401
402       Note that you ought to only call this subroutine with an argument that
403       you know exists, otherwise config files that don't exist will be
404       recorded as havind been loaded.
405
406   parse_content
407       Parameters:
408
409           content => 'str'
410           callback => sub {}
411           error => sub {}
412
413       Parses the given content and runs callbacks as it finds valid
414       information.
415
416       Returns undef on success and "error($content)" (the original content)
417       on failure.
418
419       "callback" is called like:
420
421           callback(section => $str, offset => $num, length => $num, name => $str, value => $str)
422
423       "name" and "value" may be omitted if the callback is not being called
424       on a key/value pair, or if it is being called on a key with no value.
425
426       "error" is called like:
427
428           error( content => $content, offset => $offset )
429
430       Where "offset" is the point in the content where the parse error
431       occurred.
432
433       If you need to use this method, you might be interested in
434       "error_callback" as well.
435
436   error_callback
437       Parameters:
438
439           content => 'str'
440           offset => 45
441           filename => '/foo/bar/.baz'
442
443       Made especially for passing to "parse_content", passed through the
444       "error" parameter like this:
445
446           error => sub {
447               error_callback( @_, filename => '/file/you/were/parsing' )
448           }
449
450       It's used internally wherever "parse_content" is used and will throw an
451       exception with a useful message detailing the line number, position on
452       the line, and contents of the bad line; if you find the need to use
453       "parse_content" elsewhere, you may find it useful as well.
454
455   set_multiple( $name )
456       Mark the key string $name as containing multiple values.
457
458       Returns nothing.
459
460   is_multiple( $name )
461       Return a true value if the key string $name contains multiple values;
462       false otherwise.
463
464   define
465       Parameters:
466
467           section => 'str'
468           name => 'str'
469           value => 'str'
470
471       Given a section, a key name, and a valueAX store this information in
472       memory in the config object.
473
474       Returns the value that was just defined on success, or undef if no name
475       is given and thus the key cannot be defined.
476
477   cast
478       Parameters:
479
480           value => 'foo'
481           as => 'int'
482           human => 1
483
484       Return "value" cast into the type specified by "as".
485
486       Valid values for "as" are "bool", "int", "num", or "bool-or-num". For
487       "bool", "true", "yes", "on", 1, and undef are translated into a true
488       value (for Perl); anything else is false. Specifying a true value for
489       the "human" arg will get you a human-readable 'true' or 'false' rather
490       than a value that plays along with Perl's definition of truthiness (0
491       or 1).
492
493       For "int"s and "num"s, if "value" ends in "k", "m", or "g", it will be
494       multiplied by 1024, 1048576, and 1073741824, respectively, before being
495       returned. "int"s are truncated after being multiplied, if they have a
496       decimal portion.
497
498       "bool-or-int", as you might have guessed, gives you either a bool or an
499       int depending on which one applies.
500
501       If "as" is unspecified, "value" is returned unchanged.
502
503   format_section
504       Parameters:
505
506           section => 'section.subsection'
507           base => 1
508
509       Return a string containing the section/subsection header, formatted as
510       it should appear in a config file. If "bare" is true, the returned
511       value is not followed be a newline.
512
513   format_definition
514       Parameters:
515
516           key => 'str'
517           value => 'str'
518           bare => 1
519
520       Return a string containing the key/value pair as they should be printed
521       in the config file. If "bare" is true, the returned value is not tab-
522       indented nor followed by a newline.
523

DIFFERENCES FROM GIT-CONFIG

525       This module does the following things differently from git-config:
526
527       We are much more permissive about valid key names and section names.
528       For variables, instead of limiting variable names to alphanumeric
529       characters and -, we allow any characters except for = and newlines,
530       including spaces as long as they are not leading or trailing, and . as
531       long as the key name is quoted. For sections, any characters but
532       whitespace, [], and " are allowed.  You can enforce reading/writing
533       only git-compatible variable names and section headers by passing
534       "compatible => 1" to the constructor.
535
536       When replacing variable values and renaming sections, we merely use a
537       substring replacement rather than writing out new lines formatted in
538       the default manner for new lines. Git's replacement/renaming (as of
539       1.6.3.2) is currently buggy and loses trailing comments and variables
540       that are defined on the same line as a section being renamed. Our
541       method preserves original formatting and surrounding information.
542
543       We also allow the 'num' type for casting, since in many cases we might
544       want to be more lenient on numbers.
545
546       We truncate decimal numbers that are cast to "int"s, whereas Git just
547       rejects them.
548
549       We don't support NUL-terminating output (the --null flag to git-
550       config). Who needs it?
551

BUGS

553       If you find any bugs in this module, report them at:
554
555         http://rt.cpan.org/
556
557       Include the version of the module you're using and any relevant
558       problematic configuration files or code snippets.
559

LICENSE

568       This program is free software; you may modify and/or redistribute it
569       under the same terms as Perl itself.
570

COPYRIGHT

572       Copyright 2010 Best Practical Solutions, LLC
573

AUTHORS

575       Alex Vandiver <alexmv@bestpractical.com>, Christine Spang
576       <spang@bestpractical.com>
577
578
579
580perl v5.12.1                      2010-06-28                Config::GitLike(3)