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

FreeBSD Manual Pages

  
 
  

home | help
Badger::Config::FilesyUser(Contributed Perl DocumBadger::Config::Filesystem(3)

NAME
       Badger::Config::Filesystem - reads configuration	files in a directory

SYNOPSIS
	   use Badger::Config::Filesystem;

	   my $config =	Badger::Config::Filesystem->new(
	       root => 'path/to/some/dir'
	   );

	   # Fetch the data in user.[yaml|json]	in above dir
	   my $user = $config->get('user')
	       || die "user: not found";

	   # Fetch sub-data items using	dotted syntax
	   print $config->get('user.name');
	   print $config->get('user.emails.0');

DESCRIPTION
       This module is a	subclass of Badger::Config for reading data from
       configuration files in a	directory.

       Consider	a directory that contains the following	files and sub-
       directories:

	   config/
	       site.yaml
	       style.yaml
	       pages.yaml
	       pages/
		   admin.yaml
		   developer.yaml

       We can create a Badger::Config::Filesystem object to read the
       configuration data from the files in this directory like	so:

	   my $config =	Badger::Config::Filesystem->new(
	       root => 'config'
	   );

       Reading the data	from "site.yaml" is as simple as this:

	   my $site = $config->get('site');

       Note that the file extension is not required.  You can have either a
       "site.yaml" or a	"site.json" file in the	directory and the module will
       load whichever one it finds first.  It's	possible to add	other data
       codecs if you want to use something other than YAML or JSON.

       You can also access data	from within a configuration file.  If the
       "site.yaml" file	contains the following:

	   name:    My Site
	   version: 314
	   author:
	     name:  Andy Wardley
	     email: abw@wardley.org

       Then we can read	the version and	author name like so:

	   print $config->get('site.version');
	   print $config->get('author.name');

       If the configuration directory contains a sub-directory with the	same
       name as the data	file being loaded (minus the extension)	then any files
       under that directory will also be loaded.  Going	back to	our earlier
       example,	the "pages" item is such a case:

	   config/
	       site.yaml
	       style.yaml
	       pages.yaml
	       pages/
		   admin.yaml
		   developer.yaml

       There are three files relevant to "pages" here.	Let's assume the
       content of each is as follow:

       pages.yaml:

	   one:	       Page One
	   two:	       Page Two

       pages/admin.yaml:

	   three:      Page Three
	   four:       Page Four

       pages/developer.yaml:

	   five:       Page Five

       When we load the	"pages"	data like so:

	   my $pages = $config->get('pages');

       We end up with a	data structure like this:

	   {
	       one   =>	'Page One',
	       two   =>	'Page Two',
	       admin =>	{
		   three => 'Page Three',
		   four	 => 'Page Four',
	       },
	       developer => {
		   five	 => 'Page Five',
	       },
	   }

       Note how	the "admin" and	"developer" items have been nested into	the
       data.  The filename base	(e.g. "admin", "developer") is used to define
       an entry	in the "parent"	hash array containing the data in the "child"
       data file.

       The "tree_type" option can be used to change the	way that this data is
       merged.	To use this option, put	it in a	"schema" section in the	top
       level configuration file, e.g. the "pages.yaml":

       pages.yaml:

	   one:	       Page One
	   two:	       Page Two
	   schema:
	     tree_type:	flat

       If you don't want the data nested at all	then specify a "flat" value
       for "tree_type".	 This would return the following data:

	   {
	       one   =>	'Page One',
	       two   =>	'Page Two',
	       three =>	'Page Three',
	       four  =>	'Page Four',
	       five  =>	'Page Five',
	   }

       The "join" type collapses the nested data files by joining the file
       path (without extension)	onto the data items contain therein. e.g.

	   {
	       one	       => 'Page	One',
	       two	       => 'Page	Two',
	       admin_three     => 'Page	Three',
	       admin_four      => 'Page	Four',
	       developer_five  => 'Page	Five',
	   }

       You can specify a different character sequence to join paths via	the
       "tree_joint" option, e.g.

	   schema:
	     tree_type:	 join
	     tree_joint: '-'

       That would producing this data structure:

	   {
	       one	       => 'Page	One',
	       two	       => 'Page	Two',
	       admin-three     => 'Page	Three',
	       admin-four      => 'Page	Four',
	       developer-five  => 'Page	Five',
	   }

       The "uri" type is a slightly smarter version of the "join" type.	 It
       joins path elements with	the "/"	character to create URI	paths.

	   {
	       one	       => 'Page	One',
	       two	       => 'Page	Two',
	       admin/three     => 'Page	Three',
	       admin/four      => 'Page	Four',
	       developer/five  => 'Page	Five',
	   }

       What makes it special is	that it	follows	the standard rules for URI
       resolution and recognises a path	with a leading slash to	be absolute
       rather than relative to the current location.

       For example, the	pages/admin.yaml file could contain something like
       this:

       pages/admin.yaml:

	   three:      Page Three
	   /four:      Page Four

       The "three" entry is considered to be relative to the "admin" file so
       results in a final path of "admin/three"	as before.  However, "/four"
       is an absolute path so the "admin" path is ignored.  The	end result is
       a data structure	like this:

	   {
	       one	       => 'Page	One',
	       two	       => 'Page	Two',
	       admin/three     => 'Page	Three',
	       /four	       => 'Page	Four',
	       developer/five  => 'Page	Five',
	   }

       In this example we've ended up with an annoying inconsistency in	that
       our "/four" path	has a leading slash when the other items don't.	 The
       "uri_paths" option can be set to	"relative" or "absolute" to remove or
       add leading slashes respectively, effectively standardising all paths
       as one or the other.

	   schema:
	     tree_type:	 uri
	     uri_paths:	 absolute

       The data	would then be returned like so:

	   {
	       /one	       => 'Page	One',
	       /two	       => 'Page	Two',
	       /admin/three    => 'Page	Three',
	       /four	       => 'Page	Four',
	       /developer/five => 'Page	Five',
	   }

CONFIGURATION OPTIONS
   root	/ directory / dir
       The "root" (or "directory" or "dir" if you prefer) option must be
       provided	to specify the directory that the module should	load
       configuration files from.  Directories can be specified as absolute
       paths or	relative to the	current	working	directory.

	   my $config =	Badger::Config::Filesystem->new(
	       dir => 'path/to/config/dir'
	   );

   data
       Any additional configuration data can be	provided via the "data"	named
       parameter:

	   my $config =	Badger::Config::Filesystem->new(
	       dir  => 'path/to/config/dir'
	       data => {
		   name	 => 'Arthur Dent',
		   email => 'arthur@dent.org',
	       },
	   );

   encoding
       The character encoding of the configuration files.  Defaults to "utf8".

   extensions
       A list of file extensions to try	in addition to "yaml" and "json".
       Note that you may also need to define a "codecs"	entry to map the file
       extension to a data encoder/decoder module.

	   my $config =	Badger::Config::Filesystem->new(
	       dir	  => 'path/to/config/dir'
	       extensions => ['str'],
	       codecs	  => {
		   str	  => 'storable',
	       }
	   );

   codecs
       File extensions like ".yaml" and	".json"	are recognised by
       Badger::Codecs which can	then provide the appropriate Badger::Codec
       module to handle	the encoding and decoding of data in the file.	The
       codecs options can be used to provide mapping from other	file
       extensions to Badger::Codec modules.

	   my $config =	Badger::Config::Filesystem->new(
	       dir	  => 'path/to/config/dir'
	       extensions => ['str'],
	       codecs	  => {
		   str	  => 'storable',   # *.str files loaded	via storable codec
	       }
	   );

       You may need to write a simple codec module yourself if there isn't one
       for the data format you want, but it's usually just a few lines of code
       that are	required to provide the	Badger::Codec wrapper module around
       whatever	other Perl module or custom code you've	using to load and save
       the data	format.

   schemas
       TODO: document specification of item schemas.  The items	below
       (tree_type through uri_paths) must now be defined in a schema.  Support
       for a default schema has	temporarily been disabled/broken.

   tree_type
       This option can be used to sets the default tree	type for any
       configuration items that	don't explicitly declare it by other means.
       The default tree	type is	"nest".

       NOTE: this has been changed.  Don't trust these docs.

       The following tree types	are supported:

       nest

       This is the default tree	type, creating nested hash arrays of data.

       flat

       Creates a flat hash array by merging all	nested hash array of data into
       one.

       join

       Joins data paths	together using the "tree_joint"	string which is	"_" by
       default.

       uri

       Joins data paths	together using slash characters	to create URI paths.
       An item in a sub-directory can have a leading slash (i.e. an absolute
       path) and it will be promoted to	the top-level data hash.

       e.g.

	   foo/bar + baz  = foo/bar/baz
	   foo/bar + /bam = /bam

       none

       No tree is created.  No sub-directories are scanned.   You never	saw
       me.  I wasn't here.

   tree_joint
       This option can be used to set the default character sequence for
       joining paths

   uri_paths
       This option can be used to set the default "uri_paths" option for
       joining paths as	URIs.  It should be set	to "relative" or "absolute".
       It can be over-ridden in	a "schema" section of a	top-level
       configuration file.

METHODS
       The module inherits all methods defined in the Badger::Config and
       Badger::Workplace base classes.

INTERNAL METHODS
       The following methods are defined for internal use.

   init($config)
       This overrides the default initialisation method	inherited from
       Badger::Config.	It calls the init_config() method to perform the base
       class Badger::Config initialisation and then the	init_filesystem()
       method to perform initialisation	specific to the
       Badger::Config::Filesystem module.

   init_filesystem($config)
       This performs the initialisation	of the object specific to the
       filesystem object.

   head($item)
       This redefines the head() method	in the Badger::Config base class.  The
       method is called	by get() to fetch a top-level data item	(e.g. "user"
       in "$config->get('user.name')").	 This implementation looks for
       existing	data items as usual, but additionally falls back on a call to
       fetch($item) to load additional data (or	attempt	to load	it).

   tail($item, $data)
       This is a do-nothing stub for subclasses	to redefine.  It is called
       after a successful call to fetch().

   fetch($item)
       This is the main	method called to load a	configuration file (or tree of
       files) from the filesystem.  It looks to	see if a configuration file
       (with one of the	known extensions appended, e.g.	"$item.yaml",
       "$item.json", etc) exists and/or	a directory named $item.

       If the file exists but the directory doesn't then the configuration
       data is read from the file.  If the directory exists

   config_tree($item, $file, $dir)
       This scans a configuration tree comprising of a configuration file
       and/or a	directory.  The	$file and $dir arguments are optional and are
       only supported as an internal optimisation.  The	method can safely be
       called with a single $item argument and the relevant file and directory
       will be determined automatically.

       The configuration file is loaded	(via scan_config_file()).  If the
       directory exists	then it	is also	scanned	(via scan_config_dir())	and
       the files contained therein are loaded.

   scan_config_file($file, $data, $path, $schema, $binder)
       Loads the data in a configuration $file and merges it into the common
       $data hash under	the $path prefix (a reference to an array).  The
       $schema contains	any schema rules for this data item.  The $binder is a
       reference to a tree_binder() method to handle the data merge.

   scan_config_dir($dir, $data,	$path, $schema,	$binder)
       Scans the diles in a configuration directory, $dir and recursively
       calls scan_config_dir() for each	sub-directory found, and
       scan_config_file() for each file.

   tree_binder($name)
       This method returns a reference to one of the binder methods below
       based on	the $name parameter provided.

	   # returns a reference to the	nest_binder() method
	   my $binder =	$config->tree_binder('nest');

       If no $name is specified	then it	uses the default "tree_type" of
       "nest".	This can be changed via	the tree_type configuration option.

   nest_tree_binder($parent, $path, $child, $schema)
       This handles the	merging	of data	for the	nest tree_type.

   flat_tree_binder($parent, $path, $child, $schema)
       This handles the	merging	of data	for the	flat tree_type.

   uri_tree_binder($parent, $path, $child, $schema)
       This handles the	merging	of data	for the	uri tree_type.

   join_tree_binder($parent, $path, $child, $schema)
       This handles the	merging	of data	for the	join tree_type.

   config_file($name)
       This method returns a Badger::Filesystem::File object representing a
       configuration file in the configuration directory.  It will
       automatically have the correct filename extension added (via a call to
       config_filename)	and the	correct	"codec"	and "encoding" parameters set
       (via a call to config_filespec) so that the data	in the configuration
       file can	be automatically loaded	(see config_data($name)).

   config_file_data($name)
       This method fetches a configuration file	via a call to config_file()
       and then	returns	the data contained therein.

   config_filespec($params)
       Returns a reference to a	hash array containing appropriate
       initialisation parameters for Badger::Filesystem::File objects created
       to read general and resource-specific configuration files.  The
       parameters are  constructed from	the "codecs" (default: "yaml") and
       "encoding" (default: "utf8") configuration options.  These can be
       overridden or augmented by extra	parameters passed as arguments.

AUTHOR
       Andy Wardley <http://wardley.org/>

COPYRIGHT
       Copyright (C) 2008-2014 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.

perl v5.32.0			  2016-12-12	 Badger::Config::Filesystem(3)

NAME | SYNOPSIS | DESCRIPTION | CONFIGURATION OPTIONS | METHODS | INTERNAL METHODS | AUTHOR | COPYRIGHT

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

home | help