Help-Site Computer Manuals
Software
Hardware
Programming
Networking
  Algorithms & Data Structures   Programming Languages   Revision Control
  Protocols
  Cameras   Computers   Displays   Keyboards & Mice   Motherboards   Networking   Printers & Scanners   Storage
  Windows   Linux & Unix   Mac

Jabber::NodeFactory
Simple XML Node Factory for Jabber

Jabber::NodeFactory - Simple XML Node Factory for Jabber


NAME

Jabber::NodeFactory - Simple XML Node Factory for Jabber


SYNOPSIS


  my $nf = new Jabber::NodeFactory(fromstr => 1);

  print $nf->newNode('presence')->toStr;

  -> <presence/>

  my $tag1 = $nf->newNode('iq');

  $tag1->attr('type', 'get');

  my $query = $tag1->insertTag('query', 'jabber:iq:auth');

  $query->insertTag('username')->data('qmacro');

  print $tag1->toStr;

  -> <iq type='get'><query xmlns='jabber:iq:auth'>

          <username>qmacro</username></query></iq>

  my $tag2 = $nf->newNodeFromStr("<message><body>hi</body></message>");

  $tag2->attr('to','qmacro@jabber.org');

  my $msg = $tag2->getTag('body')->data;

  print $tag2->toStr, "\n";

  print $msg;

  -> <message to='qmacro@jabber.org'><body>hi</body></message>

  -> hi


DESCRIPTION

Jabber::NodeFactory is a library for creating and manipulating XML nodes. It was created to offer similar functions to the xmlnode library in the Jabber server implementation.

It provides enough functions to create and manipulate XML fragments (nodes) in the Jabber XML stream world. The functions are low level, RISC-style :-)


ORGANISATION

There are two packages - Jabber::NodeFactory and Jabber::NodeFactory::Node. The former is a wrapper which offers two node construction methods; the latter is the package that represents the actual node objects that are created and manipulated.

Use Jabber::NodeFactory to contruct new nodes (which will be Jabber::NodeFactory::Node objects) and Jabber::NodeFactory::Node to manipulate those nodes.

The Connection package will present stream fragments received in the form of Jabber::NodeFactory::Node objects; use Jabber::NodeFactory::Node to parse and manipulate these fragments.


METHODS in Jabber::NodeFactory

new()
The Jabber::NodeFactory constructor. Call this to create a new Jabber::NodeFactory, with which you can build nodes.

You can create nodes in one of two ways - building them up starting from the tagname (newNode()), or creating them from a string (newNodeFromStr()). If you want to be able to do the latter, you need to specify the flag


  fromstr => 1

like this


  my $nf = new Jabber::NodeFactory(fromstr => 1)

Creating nodes from strings requires the strings to be parsed; an XML parser is only created as part of the Jabber::NodeFactory object being constructed if you set this flag. If you don't set the flag and subsequently try to call newNodeFromStr(), you'll get an error.

newNode()
Call this to create a new node. This will return a new Jabber::NodeFactory::Node object. There is one mandatory argument to this call - the name of the tag for the node being created.

  my $node = $nf->newNode('tag');

will create a node that looks like this:


  <tag/>

If you want to create a node like this, by specifying a tag name, you can also use the new method in Jabber::NodeFactory::Node to achieve the same thing; the newNode method has been made available here just to have some consistency with newNodeFromStr.

newNodeFromStr()
Like newNode, this also returns a new Jabber::NodeFactory::Node object. The single argument to be passed is a string. The NodeFactory will use an XML parser to parse this string and create a node or hierarchy of nodes.

  my $node =

    $nf->newNodeFromStr(qq[<test><child attr1='a'/></test>]);

will create a node object that represents the <test> node having a child node as shown.


METHODS in Jabber::NodeFactory::Node

new()
Construct a new node. Returns a Jabber::NodeFactory::Node object. You must specify a tag name for the node.

Example:


  my $tag1 = new Jabber::NodeFactory::Node('tag1');

$tag1 represents a node that looks like this:


  <tag1/>

name()
Returns the name (the tag name) of the node, in the form of a string.

parent()
Returns the node's parent. This will be a node object or undef (if it doesn't have a parent).

attr()
Sets or gets a node attribute. Pass one argument - an attribute name - to get the value, or two arguments - the name and a value - to set the value. In both cases the value is returned.

Example:


  $tag1->attr('colour' => 'red');

  print $tag1->attr('colour');

prints


  red

insertTag()
This will insert a tag - with the name given in the first (mandatory) argument - into the node object on which the method call is made.

A namespace can be specified in an optional second argument.

Example:


  my $tag2 = new Jabber::NodeFactory::Node('tag2');

  $tag2->insertTag('a');

  $tag2->insertTag('b', 'fish:face');

  $tag2->insertTag('c')->data('hello');

results in $tag2 looking like this:


  <tag2><a/><b xmlns='fish:face'/><c>hello</c></tag2>

toStr()
Returns a string representation of the node (and all its children).

Example:


  my $x = new Jabber::NodeFactory::Node('tag');

  my $y = $x->insertTag('anothertag');

  $y->attr('number',3);

  print $x->toStr, "\n";

  print $y->toStr, "\n";

results in:


  <tag><anothertag number='3'/></tag>

  <anothertag number='3'/>

getTag()
Retrieves a child tag and returns it as a node. Specify the name of the tag to retrieve, and an optional namespace attribute (that must be explicitly specified as an xmlns attribute in the child tag you want) to distinguish it from other tags of the same name.

If you don't know the tagname but know what namespace you want (common in Jabber), then specify an empty string for the tagname.

Example:


  $node->getTag('x','jabber:x:event');

Will return the <x> tag(s) that have xmlns='jabber:x:event'. If you only want the first one, make the call in scalar context:


  my $event = $node->getTag('x','jabber:x:event');

otherwise make it in array context:


  my @xtags = $node->getTag('x');

to get multiple tags (node objects).

Another example:


  my $query = $node->getTag('', 'jabber:iq:version');

This gets a 'query' node that's qualified by the iq:version namespace.

hide()
Use this method to remove a child tag. Use getTag to identify the tag to remove.

Example:


  my $tag = $nf->newNodeFromStr(qq[<a><b fruit='banana'>yellow</b></a>]);

  $tag->getTag('b')->hide;

  print $tag->toStr;

outputs this:


  <a/>

getChildren()
This returns a list (array) of the direct child tags of the tag on which the method is called.

Example:


  my $node = $nf->newNodeFromStr(qq[<a><a1/><a2/><a3><a31/></a3></a>]);

  print $_->name, "\n" foreach $


SEE ALSO

Jabber::Connection, Jabber::NS


AUTHOR

DJ Adams


VERSION

early


COPYRIGHT

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

Programminig
Wy
Wy
yW
Wy
Programming
Wy
Wy
Wy
Wy