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

FreeBSD Manual Pages

  
 
  

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

NAME
       Config::Auto - Magical config file parser

SYNOPSIS
	   use Config::Auto;

	   ### Not very	magical	at all.
	   $config = Config::Auto::parse("myprogram.conf", format => "colon");

	   ### Considerably more magical.
	   $config = Config::Auto::parse("myprogram.conf");

	   ### Highly magical.
	   $config = Config::Auto::parse();

	   ### Using the OO interface
	   $ca	   = Config::Auto->new(	source => $text	);
	   $ca	   = Config::Auto->new(	source => $fh );
	   $ca	   = Config::Auto->new(	source => $filename );

	   $href   = $ca->score;	   # compute the score for various formats

	   $config = $ca->parse;	   # parse the config

	   $format = $ca->format;	   # detected (or provided) config format
	   $str	   = $ca->as_string;	   # config file stringified
	   $fh	   = $ca->fh;		   # config file handle
	   $file   = $ca->file;		   # config filename
	   $aref   = $ca->data;		   # data from your config, split by newlines

DESCRIPTION
       This module was written after having to write Yet Another Config	File
       Parser for some variety of colon-separated config. I decided "never
       again".

       Config::Auto aims to be the most	"DWIM" config parser available,	by
       detecting configuration styles, include paths and even config filenames
       automagically.

       See the "HOW IT WORKS" section below on implementation details.

ACCESSORS
   @formats = Config::Auto->formats
       Returns a list of supported formats for your config files. These
       formats are also	the keys as used by the	"score()" method.

       "Config::Auto" recognizes the following formats:

       o   perl	   => perl code

       o   colon   => colon separated (e.g., key:value)

       o   space   => space separated (e.g., key value)

       o   equal   => equal separated (e.g., key=value)

       o   bind	   => bind style (not available)

       o   irssi   => irssi style (not available)

       o   xml	   => xml (via XML::Simple)

       o   ini	   => .ini format (via Config::IniFiles)

       o   list	   => list (e.g., foo bar baz)

       o   yaml	   => yaml (via	YAML.pm)

METHODS
   $obj	= Config::Auto->new( [source =>	$text|$fh|$filename, path => \@paths,
       format => FORMAT_NAME] );
       Returns a "Config::Auto"	object based on	your configs source. This can
       either be:

       a filehandle
	   Any opened filehandle, or "IO::Handle"/"IO::String" object.

       a plain text string
	   Any plain string containing one or more newlines.

       a filename
	   Any plain string pointing to	a file on disk

       nothing
	   A heuristic will be applied to find your config file, based on the
	   name	of your	script;	$0.

       Although	"Config::Auto" is at its most magical when called with no
       parameters, its behavior	can be controlled explicitly by	using one or
       two arguments.

       If a filename is	passed as the "source" argument, the same paths	are
       checked,	but "Config::Auto" will	look for a file	with the passed	name
       instead of the $0-based names.

       Supplying the "path" parameter will add additional directories to the
       search paths. The current directory is searched first, then the paths
       specified with the path parameter. "path" can either be a scalar	or a
       reference to an array of	paths to check.

       The "format" parameters forces "Config::Auto" to	interpret the contents
       of the configuration file in the	given format without trying to guess.

   $rv = $obj->parse | Config::Auto::parse( [$text|$fh|$filename, path =>
       \@paths,	format => FORMAT_NAME] );
       Parses the source you provided in the "new()" call and returns a	data
       structure representing your configuration file.

       You can also call it in a procedural context ("Config::Auto::parse()"),
       where the first argument	is the source, and the following arguments are
       named. This function is provided	for backwards compatiblity with
       releases	prior to 0.29.

   $href = $obj->score;
       Takes a look at the contents of your configuration data and produces a
       'score' determining which format	it most	likely contains.

       They keys are equal to formats as returned by the
       "Config::Auto->formats" and their values	are a score between 1 and 100.
       The format with the highest score will be used to parse your
       configuration data, unless you provided the "format" option explicitly
       to the "new()" method.

   $aref = $obj->data;
       Returns an array	ref of your configuration data,	split by newlines.

   $fh = $obj->fh;
       Returns a filehandle, opened for	reading, containing your configuration
       data. This works	even if	you provided a plain text string or filename
       to parse.

   $filename = $obj->file;
       Returns a filename containing your configuration	data. This works even
       if you provided a plaintext string or filehandle	to parse. In that
       case, a temporary file will be written holding your configuration data.

   $str	= $obj->as_string;
       Returns a string	representation of your configuration data.

GLOBAL VARIABLES
       $DisablePerl

       Set this	variable to true if you	do not wish to "eval" perl style
       configuration files.

       Default is "false"

       $Untaint

       Set this	variable to true if you	automatically want to untaint values
       obtained	from a perl style configuration. See "perldoc perlsec" for
       details on tainting.

       Default is "false"

       $Debug

       Set this	variable to true to get	extra debug information	from
       "Config::Auto" when finding and/or parsing config files fails.

       Default is "false"

HOW IT WORKS
       When you	call "Config::Auto->new" or "Config::Auto::parse" with no
       arguments, we first look	at $0 to determine the program's name. Let's
       assume that's "snerk". We look for the following	files:

	   snerkconfig
	   ~/snerkconfig
	   /etc/snerkconfig
	   /usr/local/etc/snerkconfig

	   snerk.config
	   ~/snerk.config
	   /etc/snerk.config
	   /usr/local/etc/snerk.config

	   snerkrc
	   ~/snerkrc
	   /etc/snerkrc
	   /usr/local/etc/snerkrc

	   .snerkrc
	   ~/.snerkrc
	   /etc/.snerkrc
	   /usr/local/etc/.snerkrc

       Additional search paths can be specified	with the "path"	option.

       We take the first one we	find, and examine it to	determine what format
       it's in.	The algorithm used is a	heuristic "which is a fancy way	of
       saying that it doesn't work." (Mark Dominus.) We	know about colon
       separated, space	separated, equals separated, XML, Perl code, Windows
       INI, BIND9 and irssi style config files.	If it chooses the wrong	one,
       you can force it	with the "format" option.

       If you don't want it ever to detect and execute config files which are
       made up of Perl code, set "$Config::Auto::DisablePerl = 1".

       When using the perl format, your	configuration file will	be eval'd.
       This will cause taint errors. To	avoid these warnings, set
       "$Config::Auto::Untaint = 1".  This setting will	not untaint the	data
       in your configuration file and should only be used if you trust the
       source of the filename.

       Then the	file is	parsed and a data structure is returned. Since we're
       working magic, we have to do the	best we	can under the circumstances -
       "You rush a miracle man,	you get	rotten miracles." (Miracle Max)	So
       there are no guarantees about the structure that's returned. If you
       have a fairly regular config file format, you'll	get a regular data
       structure back. If your config file is confusing, so will the return
       structure be. Isn't life	tragic?

EXAMPLES
       Here's what we make of some common Unix config files:

       /etc/resolv.conf:

	   $VAR1 = {
	       'nameserver' => [ '163.1.2.1', '129.67.1.1', '129.67.1.180' ],
	       'search'	=> [ 'oucs.ox.ac.uk', 'ox.ac.uk' ]
	   };

       /etc/passwd:

	   $VAR1 = {
	       'root' => [ 'x',	'0', '0', 'root', '/root', '/bin/bash' ],
	       ...
	   };

       /etc/gpm.conf:

	   $VAR1 = {
	       'append'	=> '""',
	       'responsiveness'	=> '',
	       'device'	=> '/dev/psaux',
	       'type' => 'ps2',
	       'repeat_type' =>	'ms3'
	   };

       /etc/nsswitch.conf:

	   $VAR1 = {
	       'netgroup' => 'nis',
	       'passwd'	=> 'compat',
	       'hosts' => [ 'files', 'dns' ],
	       ...
	   };

MEMORY USAGE
       This module is as light as possible on memory, only using modules when
       they are	absolutely needed for configuration file parsing.

TROUBLESHOOTING
       When using a Perl config	file, the configuration	is borked
	   Give	"Config::Auto" more hints (e.g., add #!/usr/bin/perl to
	   beginning of	file) or indicate the format in	the "new"/"parse()"
	   command.

TODO
       BIND9 and irssi file format parsers currently don't exist. It would be
       good to add support for "mutt" and "vim"	style "set"-based RCs.

BUG REPORTS
       Please report bugs or other issues to <bug-config-auto@rt.cpan.org>.

AUTHOR
       Versions	0.04 and higher	of this	module by Jos Boumans <kane@cpan.org>.

       This module originally by Simon Cozens.

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

perl v5.32.0			  2014-03-01		       Config::Auto(3)

NAME | SYNOPSIS | DESCRIPTION | ACCESSORS | METHODS | GLOBAL VARIABLES | HOW IT WORKS | EXAMPLES | MEMORY USAGE | TROUBLESHOOTING | TODO | BUG REPORTS | AUTHOR | COPYRIGHT

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

home | help