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

FreeBSD Manual Pages

  
 
  

home | help
AppConfig::File(3)    User Contributed Perl Documentation   AppConfig::File(3)

NAME
       AppConfig::File - Perl5 module for reading configuration	files.

SYNOPSIS
	   use AppConfig::File;

	   my $state   = AppConfig::State->new(\%cfg1);
	   my $cfgfile = AppConfig::File->new($state, $file);

	   $cfgfile->parse($file);	      #	read config file

OVERVIEW
       AppConfig::File is a Perl5 module which reads configuration files and
       use the contents	therein	to update variable values in an
       AppConfig::State	object.

       AppConfig::File is distributed as part of the AppConfig bundle.

DESCRIPTION
   USING THE AppConfig::File MODULE
       To import and use the AppConfig::File module the	following line should
       appear in your Perl script:

	   use AppConfig::File;

       AppConfig::File is used automatically if	you use	the AppConfig module
       and create an AppConfig::File object through the	file() method.

       AppConfig::File is implemented using object-oriented methods.  A	new
       AppConfig::File object is created and initialised using the
       AppConfig::File->new() method.  This returns a reference	to a new
       AppConfig::File object.	A reference to an AppConfig::State object
       should be passed	in as the first	parameter:

	   my $state   = AppConfig::State->new();
	   my $cfgfile = AppConfig::File->new($state);

       This will create	and return a reference to a new	AppConfig::File
       object.

   READING CONFIGURATION FILES
       The "parse()" method is used to read a configuration file and have the
       contents	update the STATE accordingly.

	   $cfgfile->parse($file);

       Multiple	files maye be specified	and will be read in turn.

	   $cfgfile->parse($file1, $file2, $file3);

       The method will return an undef value if	it encounters any errors
       opening the files.  It will return immediately without processing any
       further files.  By default, the PEDANTIC	option in the AppConfig::State
       object, $self->{	STATE }, is turned off and any parsing errors (invalid
       variables, unvalidated values, etc) will	generated warnings, but	not
       cause the method	to return.  Having processed all files,	the method
       will return 1 if	all files were processed without warning or 0 if one
       or more warnings	were raised.  When the PEDANTIC	option is turned on,
       the method generates a warning and immediately returns a	value of 0 as
       soon as it encounters any parsing error.

       Variables values	in the configuration files may be expanded depending
       on the value of their EXPAND option, as determined from the App::State
       object.	See AppConfig::State for more information on variable
       expansion.

   CONFIGURATION FILE FORMAT
       A configuration file may	contain	blank lines and	comments which are
       ignored.	 Comments begin	with a '#' as the first	character on a line or
       following one or	more whitespace	tokens,	and continue to	the end	of the
       line.

	   # this is a comment
	   foo = bar		   # so	is this
	   url = index.html#hello  # this too, but not the '#welcome'

       Notice how the '#welcome' part of the URL is not	treated	as a comment
       because a whitespace character doesn't precede it.

       Long lines can be continued onto	the next line by ending	the first line
       with a '\'.

	   callsign = alpha bravo camel	delta echo foxtrot golf	hipowls	\
		      india juliet kilo	llama mike november oscar papa	\
		      quebec romeo sierra tango	umbrella victor	whiskey	\
		      x-ray yankee zebra

       Variables that are simple flags and do not expect an argument (ARGCOUNT
       = ARGCOUNT_NONE)	can be specified without any value.  They will be set
       with the	value 1, with any value	explicitly specified (except "0" and
       "off") being ignored.  The variable may also be specified with a	"no"
       prefix to implicitly set	the variable to	0.

	   verbose				# on  (1)
	   verbose = 1				# on  (1)
	   verbose = 0				# off (0)
	   verbose off				# off (0)
	   verbose on				# on  (1)
	   verbose mumble			# on  (1)
	   noverbose				# off (0)

       Variables that expect an	argument (ARGCOUNT = ARGCOUNT_ONE) will	be set
       to whatever follows the variable	name, up to the	end of the current
       line.  An equals	sign may be inserted between the variable and value
       for clarity.

	   room	= /home/kitchen
	   room	  /home/bedroom

       Each subsequent re-definition of	the variable value overwrites the
       previous	value.

	   print $config->room();		# prints "/home/bedroom"

       Variables may be	defined	to accept multiple values (ARGCOUNT =
       ARGCOUNT_LIST).	Each subsequent	definition of the variable adds	the
       value to	the list of previously set values for the variable.

	   drink = coffee
	   drink = tea

       A reference to a	list of	values is returned when	the variable is
       requested.

	   my $beverages = $config->drinks();
	   print join(", ", @$beverages);      # prints	"coffee, tea"

       Variables may also be defined as	hash lists (ARGCOUNT = ARGCOUNT_HASH).
       Each subsequent definition creates a new	key and	value in the hash
       array.

	   alias l="ls -CF"
	   alias h="history"

       A reference to the hash is returned when	the variable is	requested.

	   my $aliases = $config->alias();
	   foreach my $k (keys %$aliases) {
	       print "$k => $aliases->{	$k }\n";
	   }

       A large chunk of	text can be defined using Perl's "heredoc" quoting
       style.

	  scalar = <<BOUNDARY_STRING
	  line 1
	  line 2: Space/linebreaks within a HERE document are kept.
	  line 3: The last linebreak (\n) is stripped.
	  BOUNDARY_STRING

	  hash	 key1 =	<<'FOO'
	    * Quotes (['"]) around the boundary	string are simply ignored.
	    * Whether the variables in HERE document are expanded depends on
	      the EXPAND option	of the variable	or global setting.
	  FOO

	  hash = key2 =	<<"_bar_"
	  Text within HERE document are	kept as	is.
	  # comments are treated as a normal text.
	  The same applies to line continuation. \
	  _bar_

       Note that you cannot use	HERE document as a key in a hash or a name of
       a variable.

       The '-' prefix can be used to reset a variable to its default value and
       the '+' prefix can be used to set it to 1

	   -verbose
	   +debug

       Variable, environment variable and tilde	(home directory) expansions
       Variable	values may contain references to other AppConfig variables,
       environment variables and/or users' home	directories.  These will be
       expanded	depending on the EXPAND	value for each variable	or the GLOBAL
       EXPAND value.

       Three different expansion types may be applied:

	   bin = ~/bin		# expand '~' to	home dir if EXPAND_UID
	   tmp = ~abw/tmp	# as above, but	home dir for user 'abw'

	   perl	= $bin/perl	# expand value of 'bin'	variable if EXPAND_VAR
	   ripl	= $(bin)/ripl	# as above with	explicit parens

	   home	= ${HOME}	# expand HOME environment var if EXPAND_ENV

       See AppConfig::State for	more information on expanding variable values.

       The configuration files may have	variables arranged in blocks.  A block
       header, consisting of the block name in square brackets,	introduces a
       configuration block.  The block name and	an underscore are then
       prefixed	to the names of	all variables subsequently referenced in that
       block.  The block continues until the next block	definition or to the
       end of the current file.

	   [block1]
	   foo = 10		# block1_foo = 10

	   [block2]
	   foo = 20		# block2_foo = 20

AUTHOR
       Andy Wardley, <abw@wardley.org>

COPYRIGHT
       Copyright (C) 1997-2007 Andy Wardley.  All Rights Reserved.

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

SEE ALSO
       AppConfig, AppConfig::State

perl v5.32.0			  2015-03-01		    AppConfig::File(3)

NAME | SYNOPSIS | OVERVIEW | DESCRIPTION | AUTHOR | COPYRIGHT | SEE ALSO

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

home | help