Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Config::GitLike(3)    User Contributed Perl Documentation   Config::GitLike(3)

NAME
       Config::GitLike - git-compatible	config file parsing

SYNOPSIS
       This module parses git-style config files, which	look like this:

	   [core]
	       repositoryformatversion = 0
	       filemode	= true
	       bare = false
	       logallrefupdates	= true
	   [remote "origin"]
	       url = spang.cc:/srv/git/home.git
	       fetch = +refs/heads/*:refs/remotes/origin/*
	   [another-section "subsection"]
	       key = test
	       key = multiple values are OK
	       emptyvalue =
	       novalue

       Code that uses this config module might look like:

	   use Config::GitLike;

	   # just load a specific file
	   my $data = Config::GitLike->load_file("~/.fooconf");

	   # or	use the	object interface to load /etc/config, ~/.config, and
	   # `pwd`/.config
	   my $c = Config::GitLike->new(confname => 'config');

	   $c->get( key	=> 'section.name' );
	   # make the return value a Perl true/false value
	   $c->get( key	=> 'core.filemode', as => 'bool' );

	   # replace the old value
	   $c->set(
	       key => 'section.name',
	       value =>	'val1',
	       filename	=> '/home/user/.config',
	   );

	   # make this key have	multiple values	rather than replacing the
	   # old value
	   $c->set(
	       key => 'section.name',
	       value =>	'val2',
	       filename	=> '/home/user/.config',
	       multiple	=> 1,
	   );

	   # replace all occurrences of	the old	value for section.name with a new one
	   $c->set(
	       key => 'section.name',
	       value =>	'val3',
	       filename	=> '/home/user/.config',
	       multiple	=> 1,
	       replace_all => 1,
	   );

	   # make sure to reload the config files before reading if you've set
	   # any variables!
	   $c->load;

	   # get only the value	of 'section.name' that matches '2'
	   $c->get( key	=> 'section.name', filter => '2' );
	   $c->get_all(	key => 'section.name' );
	   # prefixing a search	regexp with a !	negates	it
	   $c->get_regexp( key => '!na'	);

	   $c->rename_section(
	       from => 'section',
	       to => 'new-section',
	       filename	=> '/home/user/.config'
	   );

	   $c->remove_section(
	       section => 'section',
	       filename	=> '/home/user/.config'
	   );

	   # unsets all	instances of the given key
	   $c->set( key	=> 'section.name', filename => '/home/user/.config' );

	   my %config_vals = $config->dump;
	   # string representation of config data
	   my $str = $config->dump;
	   # prints rather than	returning
	   $config->dump;

DESCRIPTION
       This module handles interaction with configuration files	of the style
       used by the version control system Git. It can both parse and modify
       these files, as well as create entirely new ones.

       You only	need to	know a few things about	the configuration format in
       order to	use this module. First,	a configuration	file is	made up	of
       key/value pairs.	Every key must be contained in a section. Sections can
       have subsections, but they don't	have to. For the purposes of setting
       and getting configuration variables, we join the	section	name,
       subsection name,	and variable name together with	dots to	get a key name
       that looks like "section.subsection.variable". These are	the strings
       that you'll be passing in to "key" arguments.

       Configuration files inherit from	each other. By default,
       "Config::GitLike" loads data from a system-wide configuration file, a
       per-user	configuration file, and	a per-directory	configuration file,
       but by subclassing and overriding methods you can obtain	any
       combination of configuration files. By default, configuration files
       that don't exist	are just skipped.

       See
       <http://www.kernel.org/pub/software/scm/git/docs/git-config.html#_configuration_file>
       for details on the syntax of git	configuration files. We	won't waste
       pixels on the nitty gritty here.

       While the behavior of a couple of this module's methods differ slightly
       from the	"git config" equivalents, this module can read any config file
       written by git. The converse is usually true, but only if you don't
       take advantage of this module's increased permissiveness	when it	comes
       to key names. (See "DIFFERENCES FROM GIT-CONFIG"	for details.)

       This is an object-oriented module using Moo. All	subroutines are	object
       method calls.

       A few methods have parameters that are always used for the same
       purpose:

   Filenames
       All methods that	change things in a configuration file require a
       filename	to write to, via the "filename"	parameter. Since a
       "Config::GitLike" object	can be working with multiple config files that
       inherit from each other,	we don't try to	figure out which one to	write
       to automatically	and let	you specify instead.

   Casting
       All get and set methods can make	sure the values	they're	returning or
       setting are valid values	of a certain type: "bool", "int", "num", or
       "bool-or-int" (or at least as close as Perl can get to having these
       types). Do this by passing one of these types in	via the	"as"
       parameter. The set method, if told to write bools, will always write
       "true" or "false" (not anything else that "cast"	considers a valid
       bool).

       Methods that are	told to	cast values will throw exceptions if the
       values they're trying to	cast aren't valid values of the	given type.

       See the "cast" method documentation for more on what is considered
       valid for each type.

   Filtering
       All get and set methods can filter what values they return via their
       "filter"	parameter, which is expected to	be a string that is a valid
       regex. If you want to filter items OUT instead of IN, you can prefix
       your regex with a ! and that will do the	trick.

       Now, on the the methods!

MAIN METHODS
       There are the methods you're likely to use the most.

   new(	confname => 'config', encoding => 'UTF-8' )
       Create a	new configuration object with the base config name "confname".
       If you are interested simply in loading one specific file, and not in
       automatically loading a global file, a per-user file, and a per-
       directory file, see "load_file",	below.

       "confname" is used to construct the filenames that will be loaded; by
       default,	these are "/etc/confname" (global configuration	file),
       "~/.confname" (user configuration file),	and "<Cwd"/.confname>
       (directory configuration	file).

       You can override	these defaults by subclassing "Config::GitLike"	and
       overriding the methods "global_file", "user_file", and "dir_file". (See
       "METHODS	YOU MAY	WISH TO	OVERRIDE" for details.)

       If you wish to enforce only being able to read/write config files that
       git can read or write, pass in "compatible => 1"	to this	constructor.
       The default rules for some components of	the config file	are more
       permissive than git's (see "DIFFERENCES FROM GIT-CONFIG").

       If you know that	your Git config	files are encoded with a known
       character encoding, pass	in "encoding =>	$encoding" to specify the name
       of the encoding.	Config::GitLike	will then properly serialize and
       deserialize the files with that encoding.  Note that configutation
       files written with "git config" are usually, but	are not	required to
       be, in UTF-8.

   confname
       The configuration filename that you passed in when you created the
       "Config::GitLike" object. You can change	it if you want by passing in a
       new name	(and then reloading via	"load").

   load
       This method is usually called implicitly	on the first "get", "get_all",
       "get_regex", or "dump" call used, and is	only necessary if you want to
       explicitly reload the data.

       Load the	global,	local, and directory configuration file	with the
       filename	"confname"(if they exist). Configuration variables loaded
       later override those loaded earlier, so variables from the directory
       configuration file have the highest precedence.

       Pass in an optional path, and it	will be	passed on to "load_dirs"
       (which loads the	directory configuration	file(s)).

       Returns a hash copy of all loaded configuration data stored in the
       module after the	files have been	loaded,	or a hashref to	this hash in
       scalar context.

   config_files
       An array	reference containing the absolute filenames of all config
       files that are currently	loaded,	in the order they were loaded.

   get
       Parameters:

	   key => 'sect.subsect.key'
	   as => 'int'
	   human => 1
	   filter => '!foo'

       Return the config value associated with "key" cast as an	"as".

       The "key" option	is required (will return undef if unspecified);	the
       "as" amd	"human"	options	are not	(see cast for their meaning). Sections
       and subsections are specified in	the key	by separating them from	the
       key name	with a "." character. Sections,	subsections, and keys may all
       be quoted (double or single quotes).

       If "key"	doesn't	exist in the config, or	has no values which match the
       filter, undef is	returned. Dies with the	exception "Multiple values" if
       the given key has more than one value associated	with it	which match
       the filter. (Use	"get_all" to retrieve multiple values.)

       Calls "load" if it hasn't been done already. Note that if you've	run
       any "set" calls to the loaded configuration files since the last	time
       they were loaded, you MUST call "load" again before getting, or the
       returned	configuration data may not match the configuration variables
       on-disk.

   get_all
       Parameters:

	   key => 'section.sub'
	   as => 'int'
	   human => 1
	   filter => 'regex'

       Like "get" but does not fail if the number of values for	the key	is not
       exactly one.

       Returns a list of values	(or an arrayref	in scalar context).

   get_regexp
       Parameters:

	   key => 'regex'
	   as => 'bool'
	   human => 1
	   filter => 'regex'

       Similar to "get_all" but	searches for values based on a key regex.

       Returns a hash of name/value pairs (or a	hashref	in scalar context).

   dump
       In scalar context, return a string containing all configuration data,
       sorted in ASCII order, in the form:

	   section.key=value
	   section2.key=value

       If called in void context, this string is printed instead.

       In list context,	returns	a hash containing all the configuration	data.

   set
       Parameters:

	   key => 'section.name'
	   value => 'bar'
	   filename => File::Spec->catfile(qw/home user/, '.'.$config->confname)
	   filter => 'regex'
	   as => 'bool'
	   multiple => 1
	   replace_all => 1

       Set the key "foo" in the	configuration section "section"	to the value
       "bar" in	the given filename.

       Replace "key"'s value if	"key" already exists.

       To unset	a key, pass in "key" but not "value".

       Returns true on success.

       If you need to have a . character in your variable name,	you can
       surround	the name with quotes (single or	double): "key =&gt
       'section."foo.bar.com"'"	Don't do this unless you really	have to.

       multiple	values

       By default, set will replace the	old value rather than giving a key
       multiple	values.	To override this, pass in "multiple => 1". If you want
       to replace all instances	of a multiple-valued key with a	new value, you
       need to pass in "replace_all => 1" as well.

   group_set( $filename, $array_ref )
       Same as "set", but set a	group of variables at the same time without
       writing to disk separately for each.

       $array_ref contains a list of hash references which are essentially
       hashes of arguments to "set", excluding the $filename argument since
       that is specified separately and	the same file is used for all
       variables to be set at once.

   rename_section
       Parameters:

	   from	=> 'name.subname'
	   to => 'new.subname'
	   filename => '/file/to/edit'

       Rename the section existing in "filename" given by "from" to the
       section given by	"to".

       Throws an exception "No such section" if	the section in "from" doesn't
       exist in	"filename".

       If no value is given for	"to", the section is removed instead of
       renamed.

       Returns true on success,	false if "filename" didn't exist and thus the
       rename did nothing.

   remove_section
       Parameters:

	   section => 'section.subsection'
	   filename => '/file/to/edit'

       Just a convenience wrapper around "rename_section" for readability's
       sake.  Removes the given	section	(which you can do by renaming to
       nothing as well).

   add_comment
       Parameters:

	    comment   => "Begin	editing	here\n and then	stop",
	    filename  => '/file/to/edit'
	    indented  => 1,
	    semicolon => 0,

       Add a comment to	the specified configuration file. The "comment"	and
       "filename" parameters are required. Comments will be added to the file
       with "# " at the	begnning of each line of the comment. Pass a true
       value to	"semicolon" if you'd rather they start with "; ". If your
       comments	are indented with leading white	space, and you want that white
       space to	appear in front	of the comment character, rather than after,
       pass a true value to "indented".

   cascade( $bool )
       Gets or sets if only the	deepest	configuration file in a	directory tree
       is loaded, or if	all of them are	loaded,	shallowest to deepest.
       Alternately, "cascade =>	1" can be passed to "new".

   origins
       Returns a hash mapping each config key with the file it was loaded
       from.

METHODS	YOU MAY	WISH TO	OVERRIDE
       If your application's configuration layout is different from the
       default,	e.g.  if its home directory config files are in	a directory
       within the home directory (like "~/.git/config")	instead	of just	dot-
       prefixed, override these	methods	to return the right directory names.
       For fancier things like altering	precedence, you'll need	to override
       "load" as well.

   dir_file
       Return a	string containing the path to a	configuration file with	the
       name "confname" in a directory.	Called with no arguments, returns the
       path for	a generic directory; if	called with a directory	as an
       argument, returns the path for that directory.

   global_file
       Return the string "/etc/confname", the absolute name of the system-wide
       configuration file with name "confname".

   user_file
       Return a	string containing the path to a	configuration file in the
       current user's home directory with filename "confname".

   load_dirs
       Parameters:

	   '/path/to/look/in/'

       Load the	configuration file with	the filename "dir_file"	in the current
       working directory into the memory or, if	there is no config matching
       "dir_file" in the current working directory, walk up the	directory tree
       until one is found. (No error is	thrown if none is found.) If an
       optional	path is	passed in, that	directory will be used as the base
       directory instead of the	working	directory.

       You'll want to use "load_file" to load config files from	your
       overridden version of this subroutine.

       Returns nothing of note.

OTHER METHODS
       These are mostly	used internally	in other methods, but could be useful
       anyway.

   load_global
       If a global configuration file with the absolute	name given by
       "global_file" exists, load its configuration variables into memory.

       Returns the current contents of all the loaded configuration variables
       after the file has been loaded, or undef	if no global config file is
       found.

   load_user
       If a configuration file with the	absolute name given by "user_file"
       exists, load its	config variables into memory.

       Returns the current contents of all the loaded configuration variables
       after the file has been loaded, or undef	if no user config file is
       found.

   load_file( $filename	)
       Takes a string containing the path to a file, opens it if it exists,
       loads its config	variables into memory, and returns the currently
       loaded config variables (a hashref).

       This method can also be called as a class method, which will die	if the
       file cannot be read.  If	called as an instance method, returns undef on
       failure.

       This method may also be passed additional key-value parameters which
       control how the file is loaded:

       silent
	   Defaults to off; if set, merely returns instead of die'ing if the
	   file	cannot be found	or read.

       includes
	   Defaults to on; if passed a false value, ignores the	"include"
	   directive.

       force
	   Defaults to off; if set, will re-load a file	even if	it was
	   previously loaded.

   parse_content
       Parameters:

	   content => 'str'
	   callback => sub {}
	   error => sub	{}

       Parses the given	content	and runs callbacks as it finds valid
       information.

       Returns undef on	success	and "error($content)" (the original content)
       on failure.

       "callback" is called like:

	   callback(section => $str, offset => $num, length => $num, name => $str, value => $str)

       "name" and "value" may be omitted if the	callback is not	being called
       on a key/value pair, or if it is	being called on	a key with no value.

       "error" is called like:

	   error( content => $content, offset => $offset )

       Where "offset" is the point in the content where	the parse error
       occurred.

       If you need to use this method, you might be interested in
       "error_callback"	as well.

   error_callback
       Parameters:

	   content => 'str'
	   offset => 45
	   filename => '/foo/bar/.baz'

       Made especially for passing to "parse_content", passed through the
       "error" parameter like this:

	   error => sub	{
	       error_callback( @_, filename => '/file/you/were/parsing'	)
	   }

       It's used internally wherever "parse_content" is	used and will throw an
       exception with a	useful message detailing the line number, position on
       the line, and contents of the bad line; if you find the need to use
       "parse_content" elsewhere, you may find it useful as well.

   include ( $name )
       When reading configuration files, Git versions 1.7.10 and later parse
       the "include.path" key as a directive to	include	an additional
       configuration file.  This option	controls the equivalent	behavior;
       setting it to a false value will	disable	inclusion, and any true	value
       will be taken as	the name of the	configuration parameter	which controls
       inclusion.  Defaults to "include.path", as Git does.

   set_multiple( $name )
       Mark the	key string $name as containing multiple	values.

       Returns nothing.

   is_multiple(	$name )
       Return a	true value if the key string $name contains multiple values;
       false otherwise.

   define
       Parameters:

	   section => 'str'
	   name	=> 'str'
	   value => 'str'

       Given a section,	a key name, and	a value, store this information	in
       memory in the config object.

       Returns the value that was just defined on success, or undef if no name
       and section were	given and thus the key cannot be defined.

   cast
       Parameters:

	   value => 'foo'
	   as => 'int'
	   human => 1

       Return "value" cast into	the type specified by "as".

       Valid values for	"as" are "bool", "int",	"num", or "bool-or-num". For
       "bool", "true", "yes", "on", 1, and undef are translated	into a true
       value (for Perl); anything else is false. Specifying a true value for
       the "human" argument will get you a human-readable 'true' or 'false'
       rather than a value that	plays along with Perl's	definition of
       truthiness (0 or	1).

       For "int"s and "num"s, if "value" ends in "k", "m", or "g", it will be
       multiplied by 1024, 1048576, and	1073741824, respectively, before being
       returned. "int"s	are truncated after being multiplied, if they have a
       decimal portion.

       "bool-or-int", as you might have	guessed, gives you either a bool or an
       int depending on	which one applies.

       If "as" is unspecified, "value" is returned unchanged.

   format_section
       Parameters:

	   section => 'section.subsection'
	   base	=> 1

       Return a	string containing the section/subsection header, formatted as
       it should appear	in a config file. If "bare" is true, the returned
       value is	not followed be	a newline.

   format_definition
       Parameters:

	   key => 'str'
	   value => 'str'
	   bare	=> 1

       Return a	string containing the key/value	pair as	they should be printed
       in the config file. If "bare" is	true, the returned value is not	tab-
       indented	nor followed by	a newline.

   canonical_case( $name )
       Given a full key	name, returns the canonical name of the	key; this is
       the key with the	section	and name lower-cased; the subsection is	left
       as-is.

   original_key( $name )
       Given a full key	name, returns the key as it was	last loaded from the
       file, retaining what ever upper/lower case was used.  Note that for
       multiple-valued keys, this returns an array reference of	key names, as
       each definition may have	been provided in a different choice of case.

DIFFERENCES FROM GIT-CONFIG
       This module does	the following things differently from git-config:

       We are much more	permissive about valid key names and section names.
       For variables, instead of limiting variable names to alphanumeric
       characters and -, we allow any characters except	for = and newlines,
       including spaces	as long	as they	are not	leading	or trailing, and . as
       long as the key name is quoted. For sections, any characters but
       whitespace, [], and " are allowed.  You can enforce reading/writing
       only git-compatible variable names and section headers by passing
       "compatible => 1" to the	constructor.

       When replacing variable values and renaming sections, we	merely use a
       substring replacement rather than writing out new lines formatted in
       the default manner for new lines. Git's replacement/renaming (as	of
       1.6.3.2)	is currently buggy and loses trailing comments and variables
       that are	defined	on the same line as a section being renamed. Our
       method preserves	original formatting and	surrounding information.

       We also allow the 'num' type for	casting, since in many cases we	might
       want to be more lenient on numbers.

       We truncate decimal numbers that	are cast to "int"s, whereas Git	just
       rejects them.

       We don't	support	NUL-terminating	output (the --null flag	to git-
       config).	Who needs it?

       Git only	supports reading UNIX- and DOS-style newlines ("\n" and
       "\r\n"),	and always uses	"\n" when modifying files.  We also support
       reading Mac-style newlines ("\r"), and write updates to files using the
       same newlines as	they were read with.

BUGS
       If you find any bugs in this module, report them	at:

	 http://rt.cpan.org/

       Include the version of the module you're	using and any relevant
       problematic configuration files or code snippets.

SEE ALSO
       <http://www.kernel.org/pub/software/scm/git/docs/git-config.html#_configuration_file>,
       Config::GitLike::Git, <http://syncwith.us/> ("Config::GitLike" is used
       in Prophet/SD and provides a working example)

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

COPYRIGHT
       Copyright 2010 Best Practical Solutions,	LLC

AUTHORS
       Alex Vandiver <alexmv@bestpractical.com>, Christine Spang
       <spang@bestpractical.com>

perl v5.32.0			  2020-03-13		    Config::GitLike(3)

NAME | SYNOPSIS | DESCRIPTION | MAIN METHODS | METHODS YOU MAY WISH TO OVERRIDE | OTHER METHODS | DIFFERENCES FROM GIT-CONFIG | BUGS | SEE ALSO | LICENSE | COPYRIGHT | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Config::GitLike&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help