Config::Model::Iterator(3pm)				User Contributed Perl Documentation			      Config::Model::Iterator(3pm)

NAME

       Config::Model::Iterator - Iterates forward or backward a configuration tree

VERSION

       version 2.021

SYNOPSIS

	use Config::Model;
	use Log::Log4perl qw(:easy);
	Log::Log4perl->easy_init($WARN);

	# define configuration tree object
	my $model = Config::Model->new;
	$model->create_config_class(
	   name    => "Foo",
	   element => [
	       [qw/bar baz/] => {
		   type       => 'leaf',
		   value_type => 'string',
		   level => 'important' ,
	       },
	   ]
	);
	$model->create_config_class(
	   name    => "MyClass",
	   element => [
	       foo_nodes => {
		   type       => 'hash',     # hash id
		   index_type => 'string',
		   level => 'important' ,
		   cargo      => {
		       type		 => 'node',
		       config_class_name => 'Foo'
		   },
	       },
	   ],
	);

	my $inst = $model->instance( root_class_name => 'MyClass' );
	# create some Foo objects
	$inst->config_root->load("foo_nodes:foo1 - foo_nodes:foo2  ") ;

	my $my_leaf_cb = sub {
	   my ($iter, $data_r,$node,$element,$index, $leaf_object) = @_ ;
	   print "leaf_cb called for ",$leaf_object->location,"
" ;
	} ;
	my $my_hash_cb = sub {
	   my ($iter, $data_r,$node,$element,@keys) = @_ ;
	   print "hash_element_cb called for element $element with keys @keys
" ;
	} ;

	my $iterator = $inst -> iterator (
	   leaf_cb	   => $my_leaf_cb,
	   hash_element_cb => $my_hash_cb ,
	);

	$iterator->start ;
	### prints
	# hash_element_cb called for element foo_nodes with keys foo1 foo2
	# leaf_cb called for foo_nodes:foo1 bar
	# leaf_cb called for foo_nodes:foo1 baz
	# leaf_cb called for foo_nodes:foo2 bar
	# leaf_cb called for foo_nodes:foo2 baz

DESCRIPTION

       This module provides a class that is able to iterate forward or backward a configuration tree.  The iterator will stop and call back user
       defined subroutines on one of the following condition:

       o   A configuration item contains an error (mostly undefined mandatory values)

       o   A configuration item contains warnings and the constructor's argument "call_back_on_warning" was set.

       o   A configuration item has a "important" level and the constructor's argument "call_back_on_important" was set.. See level parameter for
	   details.

       By default, the iterator will only stop on element with an "intermediate" experience.

       The iterator supports going forward and backward (to support "back" and "next" buttons on a wizard widget).

CONSTRUCTOR

       The constructor should be used only by Config::Model::Instance with the iterator method.

Creating an iterator
       A iterator requires at least two kind of call-back: a call-back for leaf elements and a call-back for hash elements (which will be also
       used for list elements).

       These call-back must be passed when creating the iterator (the parameters are named "leaf_cb" and "hash_element_cb")

       Here are the the parameters accepted by "iterator":

   call_back_on_important
       Whether to call back when an important element is found (default 0).

   call_back_on_warning
       Whether to call back when an item with warnings is found (default 0).

   experience
       Specifies the experience of the element scanned by the wizard (default 'intermediate').

   status
       Specifies the status of the element scanned by the wizard (default 'standard').

   leaf_cb
       Subroutine called backed for leaf elements. See "Callback prototypes" in Config::Model::ObjTreeScanner for signature and details.
       (mandatory)

   hash_element_cb
       Subroutine called backed for hash elements. See "Callback prototypes" in Config::Model::ObjTreeScanner for signature and details.
       (mandatory)

Custom callbacks
       By default, "leaf_cb" will be called for all types of leaf elements (i.e enum. integer, strings, ...). But you can provide dedicated call-
       back for each type of leaf:

	enum_value_cb, integer_value_cb, number_value_cb, boolean_value_cb,
	uniline_value_cb, string_value_cb

       Likewise, you can also provide a call-back dedicated to list elements with "list_element_cb"

Methods
   start
       Start the scan and perform call-back when needed. This function will return when the scan is completely done.

   bail_out
       When called, a variable is set so that all call_backs will return as soon as possible. Used to abort wizard.

   go_forward
       Set wizard in forward (default) mode.

   go_backward
       Set wizard in backward mode.

AUTHOR

       Dominique Dumont, (ddumont at cpan dot org)

SEE ALSO

       Config::Model, Config::Model::Instance, Config::Model::Node, Config::Model::HashId, Config::Model::ListId, Config::Model::Value,
       Config::Model::CheckList, Config::Model::ObjTreeScanner,

perl v5.14.2							    2012-11-09					      Config::Model::Iterator(3pm)