The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
XML-Smart-1.1
River stage one • 9 direct dependents • 9 total dependents
4 ++
/ XML::Smart

NAME

XML::Smart - A smart, easy and powerful way to access/create XML files/data.

DESCRIPTION

This module has an easy way to access/create XML data. It's based on the HASH tree that is made of the XML data, and enable a dynamic access to it with the Perl syntax for Hashe and Array, without needing to care if you have a Hashe or an Array in the tree. In other words, each point in the tree work as a Hash and Array at the same time!

WHY AND HOW IT WORKS

Every one that have tried to use Perl HASH and ARRAY to access the XML data, like in XML::Simple, have some problems to add new nodes, or to access the node when the user doesn't know if it's inside an ARRAY, a HASH or a HASH key. XML::Smart create around it a very dynamic way to access the data, since at the same time any node/point in the tree can be a HASH and an ARRAY. You also can make a search for nodes that have some attibute:

  my $server = $XML->{server}('type','eq','suse') ; ## This syntax is not wrong! ;-)

  ## Instead of:
  my $server = $XML->{server}[1] ;
  
  __DATA__
  <hosts>
    <server os="linux" type="redhat" version="8.0">
    <server os="linux" type="suse" version="7.0">
  </hosts>

The idea for this module, came from the problem that it has to access a complex struture in XML, you need to know how is this structure, something that is generally made looking the XML file (what is wrong). But in the same time is hard to always check (by code) the struture, before access it. XML is a good and easy format to declare your data, but to extrac it in a tree way, at least in my opinion, isn't easy. To fix that, came to my mind a way to access the data with some query language, like SQL. The first idea was to access using something like:

  XML.foo.bar.baz{arg1}

  X = XML.foo.bar*
  X.baz{arg1}
  
  XML.hosts.server[0]{argx}

And saw that this is very similar to Hashes and Arrays in Perl:

  $XML->{foo}{bar}{baz}{arg1} ;
  
  $X = $XML->{foo}{bar} ;
  $X->{baz}{arg1} ;
  
  $XML->{hosts}{server}[0]{argx} ;

But the problem of Hash and Array, is not knowing when you have an Array reference or not. For example, in XML::Simple:

  ## This is very diffenrent
  $XML->{server}{address} ;
  ## ... of this:
  $XML->{server}{address}[0] ;

So, why don't make both ways work? Because you need to make something crazy!

To create XML::Smart, first I have created the module Object::MultiType. With it you can have an object that works at the same time as a HASH, ARRAY, SCALAR, CODE & GLOB. So you can do things like this with the same object:

  $obj = Object::MultiType->new() ;
  
  $obj->{key} ;
  $obj->[0] ;
  $obj->method ;  
  
  @l = @{$obj} ;
  %h = %{$obj} ;
  
  &$obj(args) ;
  
  print $obj "send data\n" ;

Seems be crazy, and can be more if you use tie() inside it, and this is what XML::Smart does.

For XML::Smart, the access in the Hash and Array way paste through tie(). In other words, you have a tied HASH and tied ARRAY inside it. This tied Hash and Array work together, soo you can access a Hash key as the index 0 of an Array, or access an index 0 as the Hash key:

  %hash = (
  key => ['a','b','c']
  ) ;
  
  $hash->{key}    ## return $hash{key}[0]
  $hash->{key}[0] ## return $hash{key}[0]  
  $hash->{key}[1] ## return $hash{key}[1]
  
  ## Inverse:
  
  %hash = ( key => 'a' ) ;
  
  $hash->{key}    ## return $hash{key}
  $hash->{key}[0] ## return $hash{key}
  $hash->{key}[1] ## return undef

The best thing of this new resource is to avoid wrong access to the data and warnings when you try to access a Hash having an Array (and the inverse). Thing that generally make the script die().

Once having an easy access to the data, you can use the same resource to create data! For example:

  ## Previous data:
  <hosts>
    <server address="192.168.2.100" os="linux" type="conectiva" version="9.0"/>
  </hosts>
  
  ## Now you have {address} as a normal key with a string inside:
  $XML->{hosts}{server}{address}
  
  ## And to add a new address, the key {address} need to be an ARRAY ref!
  ## So, XML::Smart make the convertion: ;-P
  $XML->{hosts}{server}{address}[1] = '192.168.2.101' ;
  
  ## Adding to a list that you don't know the size:
  push(@{$XML->{hosts}{server}{address}} , '192.168.2.102') ;
  
  ## The data now:
  <hosts>
    <server os="linux" type="conectiva" version="9.0"/>
      <address>192.168.2.100</address>
      <address>192.168.2.101</address>
      <address>192.168.2.102</address>
    </server>
  </hosts>

Than after changing your XML tree using the Hash and Array resources you just get the data remade (through the Hash tree inside the object):

  my $xmldata = $XML->data ;

But note that XML::Smart always return an object! Even when you get a final key. So this actually returns another object, pointhing (inside it) to the key:

  $addr = $XML->{hosts}{server}{address}[0] ;
  
  ## Since $addr is an object you can TRY to access more data:
  $addr->{foo}{bar} ; ## This doens't make warnings! just return UNDEF.

  ## But you can use like a normal SCALAR too:
  
  print "$addr\n" ;
  
  $addr .= ':80' ; ## After this $addr isn't an object any more, just a SCALAR!

USAGE

  ## Create the object and load the file:
  my $XML = XML::Smart->new('file.xml') ;
  
  ## Force the use of the parser 'XML::Smart::Parser'.
  my $XML = XML::Smart->new('file.xml' , 'XML::Smart::Parser') ;

  ## Change the root:
  $XML = $XML->{hosts} ;

  ## Get the address [0] of server [0]:
  my $srv0_addr0 = $XML->{server}[0]{address}[0] ;
  ## ...or...
  my $srv0_addr0 = $XML->{server}{address} ;
  
  ## Get the server where the attibute 'type' eq 'suse':
  my $server = $XML->{server}('type','eq','suse') ;
  
  ## Get the address again:
  my $addr1 = $server->{address}[1] ;
  ## ...or...
  my $addr1 = $XML->{server}('type','eq','suse'){address}[1] ;
  
  ## Get all the addresses:
  my @addrs = @{$XML->{server}{address}} ;
  
  ## Add a new server node:
  my $newsrv = {
  os      => 'Linux' ,
  type    => 'Mandrake' ,
  version => 8.9 ,
  address => [qw(192.168.3.201 192.168.3.202)]
  } ;
  
  push(@{$XML->{server}} , $newsrv) ;

  ## Get/rebuild the XML data:
  my $xmldata = $XML->data ;
  
  ## Save in some file:
  $XML->save('newfile.xml') ;
  
  ## Send through a socket:
  print $socket $XML->data(length => 1) ; ## show the 'length' in the XML header to the
                                          ## socket know the amount of data to read.
  
  __DATA__
  <?xml version="1.0" encoding="iso-8859-1"?>
  <hosts>
    <server os="linux" type="redhat" version="8.0">
      <address>192.168.0.1</address>
      <address>192.168.0.2</address>
    </server>
    <server os="linux" type="suse" version="7.0">
      <address>192.168.1.10</address>
      <address>192.168.1.20</address>
    </server>
    <server address="192.168.2.100" os="linux" type="conectiva" version="9.0"/>
  </hosts>

METHODS

new (FILE|DATA , PARSER)

Create a XML object.

Arguments:

FILE|DATA

The first argument can be:

  - XML data as string.
  - File path.
  - File Handle (GLOB).
PARSER (optional)

Set the XML parser to use. Options:

  XML::Parser
  XML::Smart::Parser

If not set it will look for XML::Parser and load it. If XML::Parser can't be loaded it will use XML::Smart::Parser, that actually is a clone of XML::Parser::Lite.

XML::Smart::Parser can only handle basic XML data, but is a good choice when you don't want to install big modules to parse XML, since it comes with the main module.

content

Return the content of a node:

  ## Data:
  <foo>my content</foo>
  
  ## Access:
  
  my $content = $XML->{foo}->content ;
  print "<<$content>>\n" ; ## show: <<my content>>
  
  ## or just:
  my $content = $XML->{foo} ;

tree

Return the HASH tree of the XML data.

** Note that the real HASH tree is returned here. All the other ways return an object that works like a HASH/ARRAY through tie.

data (OPTIONS)

Return the data of the XML object (rebuilding it).

Options:

noident

If set to true the data isn't idented.

nospace

If set to true the data isn't idented and doesn't have space between the tags (unless the CONTENT have).

lowtag

Make the tags lower case.

lowarg

Make the arguments lower case.

upertag

Make the tags uper case.

uperarg

Make the arguments uper case.

length

If set true, add the attribute 'length' with the size of the data to the xml header (<?xml ...?>). This is useful when you send the data through a socket, since the socket can know the total amount of data to read.

save (FILEPATH , OPTIONS)

Save the XML data inside a file.

Accept the same OPTIONS of the method data.

ACCESS

To access the data you use the object in a way similar to HASH and ARRAY:

  my $XML = XML::Smart->new('file.xml') ;
  
  my $server = $XML->{server} ;

But when you get a key {server}, you are actually accessing the data through tie(), not directly to the HASH tree inside the object, (This will fix wrong accesses):

  ## {server} is a normal key, not an ARRAY ref:

  my $server = $XML->{server}[0] ; ## return $XML->{server}
  my $server = $XML->{server}[1] ; ## return UNDEF
  
  ## {server} has an ARRAY with 2 items:

  my $server = $XML->{server} ;    ## return $XML->{server}[0]
  my $server = $XML->{server}[0] ; ## return $XML->{server}[0]
  my $server = $XML->{server}[1] ; ## return $XML->{server}[1]

To get all the values of a multiple attribute:

  ## This work having only a string inside {address}, or with an ARRAY ref:
  my @addrsses = @{$XML->{server}{address}} ;

When you don't know the position of the nodes, you can select it by some attribute value:

  my $server = $XML->{server}('type','eq','suse') ; ## return $XML->{server}[1]

Syntax for the select search:

  (NAME, CONDITION , VALUE)
NAME

The attribute name in the node (tag).

CONDITION

Can be

  eq  ne  ==  !=  <=  >=  <  >

For REGEX:

  =~  !~
  
  ## Case insensitive:
  =~i !~i
VALUE

The value.

For REGEX use like this:

  $XML->{server}('type','=~','^s\w+$') ;

CONTENT

But if {server} has a content you can access it directly from the variable or from the method:

  print "Content: $server\n" ;
  ## ...or...
  print "Content: ". $server->content ."\n" ;

So, if you use the object as a string it works as a string! ;-P

CREATE XML DATA

To create XML data is easy, you just use as a normal HASH, but you don't need to care with multiple nodes, and ARRAY creation/convertion!

  ## Create a null XML object:
  my $XML = XML::Smart->new() ;
  
  ## Add a server to the list:
  $XML->{server} = {
  os => 'Linux' ,
  type => 'mandrake' ,
  version => 8.9 ,
  address => '192.168.3.201' ,
  } ;
  
  ## The data now:
  <server address="192.168.3.201" os="Linux" type="mandrake" version="8.9"/>
  
  ## Add a new address to the server. Have an ARRAY creation, convertion
  ## of the previous key to ARRAY:
  $XML->{server}{address}[1] = '192.168.3.202' ;
  
  ## The data now:
  <server os="Linux" type="mandrake" version="8.9">
    <address>192.168.3.201</address>
    <address>192.168.3.202</address>
  </server>ok 19

After create your XML tree you just save it or get the data:

  ## Get the data:
  my $data = $XML->data ;
  
  ## Or save it directly:
  $XML->save('newfile.xml') ;
  
  ## Or send to a socket:
  print $socket $XML->data(length => 1) ;

SEE ALSO

XML::Parser, XML::Parser::Lite, XML.

Object::MultiType - This is the module that make everything possible, and was created specially for XML::Smart. ;-P

AUTHOR

Graciliano M. P. <gm@virtuasites.com.br>

I will appreciate any type of feedback (include your opinions and/or suggestions). ;-P

Before make this module I dislike to use XML, and made everything to avoid it. Now I can use XML fine! ;-P

COPYRIGHT

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