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

FreeBSD Manual Pages

  
 
  

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

NAME
       Config::JSON - A	JSON based config file system.

VERSION
       version 1.5202

SYNOPSIS
	use Config::JSON;

	my $config = Config::JSON->create($pathToFile);
	my $config = Config::JSON->new($pathToFile);
	my $config = Config::JSON->new(pathToFile=>$pathToFile);

	my $element = $config->get($directive);

	$config->set($directive,$value);

	$config->delete($directive);
	$config->deleteFromHash($directive, $key);
	$config->deleteFromArray($directive, $value);

	$config->addToHash($directive, $key, $value);
	$config->addToArray($directive,	$value);

	my $path = $config->pathToFile;
	my $filename = $config->getFilename;

   Example Config File
	# config-file-type: JSON 1
	{
	   "dsn" : "DBI:mysql:test",
	   "user" : "tester",
	   "password" :	"xxxxxx",

	   # some colors to choose from
	   "colors" : [	"red", "green",	"blue" ],

	   # some statistics
	   "stats" : {
		   "health" : 32,
		   "vitality" :	11
	   },

	   # including another file
	   "includes" :	["macros.conf"]
	}

DESCRIPTION
       This package parses the config files written in JSON. It	also does some
       non-JSON	stuff, like allowing for comments in the files.

       If you want to see it in	action,	it is used as the config file system
       in WebGUI <http://www.webgui.org/>.

   Why?
       Why build yet another config file system? Well there are	a number of
       reasons:	We used	to use other config file parsers, but we kept running
       into limitations. We already use	JSON in	our app, so using JSON to
       store config files means	using less memory because we already have the
       JSON parser in memory. In addition, with	JSON we	can have any number of
       hierarchcal data	structures represented in the config file, whereas
       most config files will give you only one	level of hierarchy, if any at
       all. JSON parses	faster than XML	and YAML.  JSON	is easier to read and
       edit than XML. Many other config	file systems allow you to read a
       config file, but	they don't provide any mechanism or utilities to write
       back to it. JSON	is taint safe.	JSON is	easily parsed by languages
       other than Perl when we need to do that.

   Multi-level Directives
       You may of course access	a directive called "foo", but since the	config
       is basically a hash you can traverse multiple elements of the hash when
       specifying a directive name by simply delimiting	each level with	a
       slash, like "foo/bar". For example you may:

	my $vitality = $config->get("stats/vitality");
	$config->set("stats/vitality", 15);

       You may do this wherever	you specify a directive	name.

   Comments
       You can put comments in the config file as long as # is the first non-
       space character on the line. However, if	you use	this API to write to
       the config file,	your comments will be eliminated.

   Includes
       There is	a special directive called "includes", which is	an array of
       include files that may be brought in to the config. Even	the files you
       include can have	an "includes" directive, so you	can do hierarchical
       includes.

       Any directive in	the main file will take	precedence over	the directives
       in the includes.	Likewise the files listed first	in the "includes"
       directive will have precedence over the files that come after it. When
       writing to the files, the same precedence is followed.

       If you're setting a new directive that doesn't currently	exist, it will
       only be written to the main file.

       If a directive is deleted, it will be deleted from all files, including
       the includes.

INTERFACE
   addToArray (	directive, value )
       Adds a value to an array	directive in the config	file.

       directive

       The name	of the array.

       value

       The value to add.

   addToArrayBefore ( directive, insertBefore, value )
       Inserts a value into an array immediately before	another	item.  If that
       item can't be found, inserts at the beginning on	the array.

       directive

       The name	of the array.

       insertBefore

       The value to search for and base	the positioning	on.

       value

       The value to insert.

   addToArrayAfter ( directive,	insertAfter, value )
       Inserts a value into an array immediately after another item.  If that
       item can't be found, inserts at the end on the array.

       directive

       The name	of the array.

       insertAfter

       The value to search for and base	the positioning	on.

       value

       The value to insert.

   addToHash ( directive, key, value )
       Adds a value to a hash directive	in the config file. NOTE: This is
       really the same as $config->set("directive/key",	$value);

       directive

       The name	of the hash.

       key

       The key to add.

       value

       The value to add.

   create ( pathToFile )
       Constructor. Creates a new empty	config file.

       pathToFile

       The path	and filename of	the file to create.

   delete ( directive )
       Deletes a key from the config file.

       directive

       The name	of the directive to delete.

   deleteFromArray ( directive,	value )
       Deletes a value from an array directive in the config file.

       directive

       The name	of the array.

       value

       The value to delete.

   deleteFromHash ( directive, key )
       Delete a	key from a hash	directive in the config	file. NOTE: This is
       really just the same as doing $config->delete("directive/key");

       directive

       The name	of the hash.

       key

       The key to delete.

   get ( directive )
       Returns the value of a particular directive from	the config file.

       directive

       The name	of the directive to return.

   getFilename ( )
       Returns the filename for	this config.

   pathToFile (	)
       Returns the filename and	path for this config. May also be called as
       "getFilePath" for backward campatibility	sake.

   includes ( )
       Returns an array	reference of Config::JSON objects that are files
       included	by this	config.	May also be called as "getIncludes" for
       backward	compatibility sake.

   new ( pathToFile )
       Constructor. Builds an object around a config file.

       pathToFile

       A string	representing a path such as "/etc/my-cool-config.conf".

   set ( directive, value )
       Creates a new or	updates	an existing directive in the config file.

       directive

       A directive name.

       value

       The value to set	the paraemter to. Can be a scalar, hash	reference, or
       array reference.

   splitKeyParts ( key )
       Returns an array	of key parts.

       key

       A key string. Could be 'foo' (simple key), 'foo/bar' (a multilevel key
       referring to the	bar key	as a child of foo), or 'foo\/bar' (a simple
       key that	contains a slash in the	key). Don't forget to double escape in
       your perl code if you have a slash in your key parts like this:

	$config->get('foo\\/bar');

   write ( )
       Writes the file to the filesystem. Normally you'd never need to call
       this as it's called automatically by the	other methods when a change
       occurs.

DIAGNOSTICS
       "Couldn't parse JSON in config file"
	   This	means that the config file does	not appear to be formatted
	   properly as a JSON file. Common mistakes are	missing	commas or
	   trailing commas on the end of a list.

       "Cannot read config file"
	   We couldn't read the	config file. This usually means	that the path
	   specified in	the constructor	is incorrect.

       "Can't write to config file"
	   We couldn't write to	the config file. This usually means that the
	   file	system is full,	or the that the	file is	write protected.

PREREQS
       JSON Moo	List::Util Test::More Test::Deep

SUPPORT
       Repository
	   <http://github.com/plainblack/Config-JSON>

       Bug Reports
	   <http://rt.cpan.org/Public/Dist/Display.html?Name=Config-JSON>

AUTHOR
       JT Smith	 <jt-at-plainblack-dot-com>

LEGAL
       Config::JSON is Copyright 2009 Plain Black Corporation
       (<http://www.plainblack.com/>) and is licensed under the	same terms as
       Perl itself.

perl v5.32.0			  2014-12-25		       Config::JSON(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | INTERFACE | DIAGNOSTICS | PREREQS | SUPPORT | AUTHOR | LEGAL

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

home | help