• NAME
• SYNOPSIS
• DESCRIPTION
• new
• Search for single node
• Search for lists of nodes
• searchById
• searchByTypeAndId
• treewalk
• toxml
• hide
• value
• typeof
• kids
• nodedict
• valuedict
• makeConfig
• substvalues
• pushkids
• checkimmutable

---

NAME

Communiware::Config - API to Communiware XML config file

---

SYNOPSIS

  use Communiware::Config;
  $c = new Communiware::Config('/somewhere/cmw.conf');
  $p = $c->package('chat');
  @lf = @{$p->logfiles};
  $s = $c->option('grace');

---

DESCRIPTION

Package prowides interface to information in XML files corresponding to config.dtd. It helps to find list of nodes or simple nodes in parsed document tree as well as some other tools.

new

  my $c = new Communiware::Config('filename', $procpe)

Constructor for this class. It reads 'filename', parses it and returns object of Communiware::Config class.

If optional parameter $procpe is given, and is false, then external dtd-s are not processed, and parameter entities are not substituted. Default (when parameter is absent) - do process parameter entities.

Search for single node

 $n = $c->tagtype('tagid');
 $n = $c->tagtype('tagid', 'object');
 $n = $c->tagtype('tagid', 'string');

This construction is used to look for node in document tree $c with type 'tagtype' and id attribute equals to 'tagid'. Tagtype can be name of any tag in parsed XML document. I.e.: $c->package('chat'), $c->logfile('frontendaccesslog'). Method returns undef if there are no node with these parameters. On success it returns object of Communiware::Config class, which corresponds to found node OR the string, which represents the node.

String is returned if

second argument of the method is present, and is equal to 'string'
or if found node and its only descendant has 'value' and / or 'base' attributes.

In other cases object is returned. Subsequent calls may be applied to such object:

 $p = $c->package('chat')->logfile('chatlogfile')

Search for lists of nodes

 @p = @{$c->packages};
 @o = @{$c->package('chat')->logfiles};

If you use as method name any of XML tags in document plus 's' character on the end, then this method returns reference to list of all nodes (Communiware::Config objects!) which are belong to this tree. Suppose we want to get names of all logfiles:

 for (@{$c->logfiles}) {
   print $_->value, "\n";
 }

searchById

 $a = $node->searchById($id);

Method looks for node with id $id in the whole tree to which $node belongs. Type of found node does not matter.

searchByTypeAndId

        $a = $node->searchByTypeAndId($type, $id);

Method looks for node with id $id and type $type in the whole tree to which $node belongs.

treewalk

        $node->treewalk($node, sub {... do something ...}, @args);

Method calls subroutine sub for each node in $node tree. Arguments of sub are childnode and @args - as is. If sub returns false then treewalk breakes.

toxml

 $c->toxml($filename, $pubid, $systemid, $cmts)

All attributes are optional, and may be 'undef'. If filename is given method prints to $filename XML text, which represents Communiware::Config object $c. Otherwise returns string, which contains XML-text.

$pubid and $systemid are arguments of XML::Writer->doctype (see it).

$cmts - hash reference which contains comments for some $c nodes, it maps node ids to comment texts.

hide

 $c->hide

Sets 'noprint' tag for node c, and this node wount output during 'toxml'.

value

 $v = $n->value(%params)

Method converts node to its string representation and returns this string. Converting is possible in such cases only:

Node has 'value' and / or 'base' attributes
Or node has the only subnode, which has 'value' and / or 'base' attributes.

There is one possible key in %params - nonstrict. If value method is called with nonstrict => 1 then it returns undef when cannot determine value of node. Without nonstrict => 1 method dies in this case.

typeof

 $c->typeof

Return string - type name of node $c.

kids

 $n =  $c->kids(0);
 $n =  $c->kids;    # The same
 @nn = $c->kids(1, 2);
 @nn = $c->kids;

Returns list of node kids with given indexes (all if indexes are absent),

nodedict

 %d = %{$c->nodedict}

Method returns hash reference. This hash maps node ids to nodes, which keep value. By example, if we have such piece of XML text:

 <option id="i"><data value="123"></option>
 <option id="j"><data id="k" value="456"></option>

then $c->nodedict->{i} will refer to inner data node, {j} and {k} - to data node with id 'k'.

Result contains only nodes having such value.

valuedict

 %d = %{$c->valuedict(%params)}

This method is similar to the nodedict manpage, but maps node ids to thiers values. Call of this method is usual way to build 'raw' config hash from XML-config file.

Hash %params may have following keys:

mutableonly

If this key is true then method returns values for nodes with mutableonly=``yes'' attribute.

nonstrict

If it is true, then method just ignores nodes for which it cannot determine value. Usual behaviour is to die in such case.

tags

Value is reference to list of node types to include into dictonary. Default - ['option'].

makeConfig

  $c->makeConfig()

Returns all the configuration options from current config object in the form suitable for inclusion into Makefiles and shell scripts.

substvalues

 $c->substvalues(\%values)

This method 'normalyzes' the parsed tree. It sets / clears right values for base attributes and marks as non-printable options, which must be set, but have no value as well as empty optionsets.

pushkids

  $k = new Communiware::Config('kid.xml');
  $p = new Communiware::Config('parent.xml');
  $p->pushkids($k);

Just add Communiware::Config object to end of callers kids without (almost) any check.

checkimmutable

 $c->checkimmutable(\%oldvals)

Method compares number and values of immutable options into parsed tree and the ones given in hash %oldvals. On success it returns empty string, otherwise - error message.