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

FreeBSD Manual Pages

  
 
  

home | help
Config::INI::Writer(3)User Contributed Perl DocumentatioConfig::INI::Writer(3)

NAME
       Config::INI::Writer - a subclassable .ini-file emitter

VERSION
       version 0.025

SYNOPSIS
       If <$hash> contains:

	 {
	   '_'	=> { admin => 'rjbs' },
	   rjbs	=> {
	     awesome =>	'yes',
	     height  =>	q{5' 10"},
	   },
	   mj	=> {
	     awesome =>	'totally',
	     height  =>	'23"',
	   },
	 }

       Then when your program contains:

	 Config::INI::Writer->write_file($hash,	'family.ini');

       family.ini will contains:

	 admin = rjbs

	 [rjbs]
	 awesome = yes
	 height	= 5' 10"

	 [mj]
	 awesome = totally
	 height	= 23"

DESCRIPTION
       Config::INI::Writer is yet another config module	implementing yet
       another slightly	different take on the undeniably easy to read ".ini"
       file format.  Its default behavior is quite similar to that of
       Config::Tiny, on	which it is based.

       The chief difference is that Config::INI::Writer	is designed to be
       subclassed to allow for side-effects and	self-reconfiguration to	occur
       during the course of reading its	input.

METHODS	FOR WRITING CONFIG
       There are three writer methods, "write_string", "write_file", and
       "write_handle".	The first two are implemented in terms of the third.
       It iterates over	a collection of	data, emitting lines to	the filehandle
       as it goes.  The	lines are generated by events produced by iterating
       over the	data.  Those events are	detailed below in the "METHODS FOR
       SUBCLASSING" section.

       The given data should be	a hashref of hashrefs:

	 {
	   section_name_1 => { prop1 =>	'value1', prop2	=> 'value2' },
	   section_name_2 => ...
	 }

       ...or an	arrayref of section name and arrayref pairs:

	 [
	   section_name_1 => [ prop1 =>	'value1', prop2	=> 'value2' ],
	   section_name_2 => ...
	 ]

       ...or a combination of those:

	 [
	   section_name_1 => { prop1 =>	'value1', prop2	=> 'value2' },
	   section_name_2 => [ prop3 =>	'value3', prop4	=> 'value4' ],
	   section_name_3 => ...
	 ]

       All the reader methods throw an exception when they encounter an	error.

   write_file
	 Config::INI::Writer->write_file($input, $filename);

       This method writes out the configuration	represented by $data to	the
       file named by $filename.	 If a file by that name	exists,	it is
       overwritten.

       This method will	either succeed or raise	an exception.  (Its return
       value is	not defined.)

   write_string
	 my $string = Config::INI::Writer->write_string($input);

       This method returns a string containing the INI content describing the
       given data.

   write_handle
	 Config::INI::Writer->write_handle($input, $handle);

       This method writes the data in $data to the IO::Handle-like object in
       $handle.	 This method should either succeed or throw an exception.

METHODS	FOR SUBCLASSING
       These are the methods you need to understand and	possibly change	when
       subclassing Config::INI::Reader to handle a different format of input.

   preprocess_input
	 my $processed_input = $writer->preprocess_input($input_data);

       This method is called to	ensure that the	data given to the "write_*"
       methods are in a	canonical form for processing and emitting.  The
       default implementation converts hashrefs	to arrayrefs and, if the input
       is a hashref, moves the "starting_section" to the beginning of the
       produced	arrayref.

       In other	words, given:

	 {
	   section_1 =>	{ a => 1, b => 2 },
	   section_2 =>	{ c => 3, c => 4 },
	   _	     =>	{ d => 5, e => 6 },
	 }

       This method will	return:

	 [
	   _	     =>	[ d => 5, e => 6 ],
	   section_2 =>	[ c => 3, c => 4 ],
	   section_1 =>	[ a => 1, b => 2 ],
	 ]

       The only	guaranteed ordering when hashes	are provided as	input is that
       the starting section will appear	first.

   validate_section_name
	 Carp::croak "section name contains illegal character"
	   if not $writer->is_valid_section_name($name);

   is_valid_property_name
	 Carp::croak "property name contains illegal character"
	   if not $writer->is_valid_property_name($name);

   is_valid_value
	 Carp::croak "value contains illegal character"
	   if not $writer->is_valid_value($name);

   validate_input
	 $writer->validate_input($input);

       This method is called on	the input data once they've been preprocessed
       by "preprocess_input".

       It ensures that the processed input is structurally sound before
       beginning to output it.	For example, it	ensures	that no	property is
       ever assigned more than once in a given section.

       This method either raises an exception or it doesn't.

   change_section
	 $writer->change_section($section_name);

       This method is called each time a new section is	going to be written
       out.  If	the same section appears twice in a row	in the input, this
       method will still be called between instances of	that section.

       In other	words, given this input:

	 [
	   section_1 =>	[ a => 1 ],
	   section_1 =>	[ b => 2 ],
	 ]

       "change_section"	will be	called twice: once before the first
       "section_1" and once before the second "section_1".

   current_section
	 $writer->current_section

       This method returns the section currently being written out.

   finish_section
	 $writer->finish_section

       This method is called after all of the current section's	properties
       have been written.

   done_sections
	 my @names = $writer->done_sections;

       This method returns a list of all sections that have been written out
       and finished.  The fact that a section name is returned by
       "done_sections" does not	mean that there	will be	no more	data for that
       section,	but that at least one entire set of data has been written out
       for it.

   stringify_section
	 my $string = $writer->stringify_section($props);

       This method returns a string assigning all the properties set in	the
       given data.  This still will include the	section	header,	if needed.
       (The only case in which it is not needed	is when	the
       "explicit_starting_header" method returns false,	no other sections have
       been done, and the section about	to be stringified is the
       "starting_section".

       This method is implemented in terms of "stringify_section_header" and
       "stringify_section_data".

   stringify_section_data
	 my $string = $writer->stringify_section_data($props)

       This method returns a string containing a series	of lines, each
       containing a value assignment for the given properties.

   stringify_value_assignment
	 my $string = $writer->stringify_value_assignment($name	=> $value);

       This method returns a string that assigns a value to a named property.
       If the value is undefined, an empty string is returned.

   stringify_value
	 my $string = $writer->stringify_value($value);

       This method returns the string that will	represent the given value in a
       property	assignment.

   stringify_section_header
	 my $string = $writer->stringify_section_header($section_name);

       This method returns the string (a line) that represents the given
       section name.  Basically, this returns:

	 [section_name]

   starting_section
       This method returns the name of the starting section.  If this section
       appears first (as it will, when given a hashref as input) and if
       "explicit_starting_header" returns false, its section header can	be
       omitted.

   explicit_starting_header
       If this method returns true (which it does not, by default), then the
       section header for the starting section will be emitted,	even if	it
       appears first.

   new
	 my $reader = Config::INI::Writer->new;

       This method returns a new writer.  This generally does not need to be
       called by anything but the various "write_*" methods, which create a
       writer object only ephemerally.

AUTHOR
       Ricardo Signes <rjbs@cpan.org>

COPYRIGHT AND LICENSE
       This software is	copyright (c) 2007 by Ricardo Signes.

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

perl v5.32.0			  2014-11-16		Config::INI::Writer(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | METHODS FOR WRITING CONFIG | METHODS FOR SUBCLASSING | AUTHOR | COPYRIGHT AND LICENSE

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

home | help