/ 
Nile-0.55
River stage zero No dependents
/ Nile::XML

NAME

Nile::XML - XML file manager.

SYNOPSIS

# get a reference to the framework xml object.
$xml = $self->app->xml;

# get a reference to a new xml object.
$xml = $self->app->xml->new;

# keep sort order when reading and writing the xml file data. default is off.
#$xml->keep_order(1);

# load xml file
$xml->load("path/to/xml/file.xml");

# load and append another xml file to the same object
$xml->load("path/to/xml/another.xml");

# get value of email tag <email>ahmed@mewsoft.com</email>
say $xml->get('email');

# get tag value, if not found return the provided default value.
$var = $xml->get($name, $default);

# get tag attribute of email tag <email status='expired'>ahmed@mewsoft.com</email>
# The prefix '-' is added on every attribute's name.
say $xml->get('email')->{'-status'};

# if an element has both of a text node and attributes or both of a text node and other child nodes,
# value of a text node is moved to #text like child nodes.
say $xml->get('email')->{'#text'};

# get value of email tag inside other tags
# <users><user><contact><email>ahmed@mewsoft.com</email></contact></user></users>
say $xml->get('users/user/contact/email');

# automatic getter support
$email = $xml->email; # same as $xml->get('email');

# automatic setter support
$xml->email('ahmed@mewsoft.com'); # $xml->set('email', 'ahmed@mewsoft.com');

# set value of email tag <email></email>
$xml->set('email', 'ahmed@mewsoft.com');

# set value of email tag inside other tags
# <users><user><contact><email></email></contact></user></users>
$xml->set('users/user/contact/email', 'ahmed@mewsoft.com');

# access variables as a hash tree
$xml->var->{accounts}->{users}->{admin}->{username} = 'admin';

# get a list of tags values.
($users, $views, $items) = $xml->list( qw( users views items ) );

# delete xml tags by names
$xml->delete(@names);

# delete entire xml object contents in memory
$xml->clear();

# load and append another xml file to the object
$xml->add_file($another_file);

# updated the provided tags and save changes to the file
$xml->update(%tags);

# Save changes to the output file. If no file name just update the loaded file name.
$xml->save($file);

# load xml file content and return it as a hash, not added to the object
%xml_hash = $xml->get_file($file);
say $xml_hash{root}{config}{database}{user};

# load xml file content and return it as a hash ref, not added to the object
$xml_hash_ref = $xml->get_file($file);
say $xml_hash_ref->{root}->{config}->{database}->{user};

# get a new xml object
#my $xml_other = $xml->object;
#my $xml_other = $xml->new;

# load and manage another xml files separately
#$xml_other->load("xmlfile");

DESCRIPTION

Nile::XML - XML file manager.

Parsing and writing XML files into a hash tree object supports sorted order and build on the module XML::TreePP.

xml()

# get a new XML::TreePP object.
$xml_obj = $xml->xml(@names);
# then you can use $xml_obj as XML::TreePP object.

Returns a new XML::TreePP object.

file()

# set output file name for saving
$xml->file($file);

# get output file name
$file = $xml->file();

Get and set the output xml file name used when saving or updating.

encoding()

# get encoding used to read/write the file, default is 'UTF-8'.
$encoding = $xml->encoding();

# set encoding used to read/write the file, default is 'UTF-8'.
$xml->encoding('UTF-8');

Get and set encoding used to read/write the xml file The default encoding is 'UTF-8'.

indent()

# get indent, default 4.
$indent = $xml->indent();

# set indent.
$xml->indent(6);

This makes the output more human readable by indenting appropriately.

load()

# get xml object
$xml = $self->app->xml->new;

# load xml file
$xml->load($file);

# load and append another xml file
$xml->load($another);

Loads xml files to the object in memory. This will not clear any previously loaded files. To will add files. This method can be chained $xml-load($file)->add_file($another_file)>;

keep_order()

# keep sort order when loading and saving the file. default is off.
$xml->keep_order(1);

# turn it off
$xml->keep_order(0);

This option keeps the order for each element appeared in XML. Tie::IxHash module is required. This makes parsing performance slow (about 100% slower than default). But sometimes it is required for example when loading url routes files, it is important to keep routes in the same sorted order in the files.

get()

# get value of email tag <email>ahmed@mewsoft.com</email>
say $xml->get('email'); # returns ahmed@mewsoft.com

# get tag value, if not found return the optional provided default value.
$var = $xml->get($name, $default);

# get value of email tag inside other tags
# <users><user><contact><email>ahmed@mewsoft.com</email></contact></user></users>
say $xml->get('users/user/contact/email'); # returns ahmed@mewsoft.com

# automatic getter support
$email = $xml->email; # same as $xml->get('email');

# get list
# <lang><file>general</file><file>contact</file><file>register</file></lang>
@files = $xml->get("lang/file");

Returns xml tag value, if not found returns the optional provided default value.

set()

# set tag value
$xml->set('email', 'ahmed@mewsoft.com');

# set a group of tags
$xml->set(%tags);

# set value of nested tags
# <users><user><contact><email>ahmed@mewsoft.com</email></contact></user></users>
$xml->set('users/user/contact/email', 'ahmed@mewsoft.com');

Sets tags values.

list()

# get a list of tags values.
@values = $xml->list(@names);
($users, $views, $items) = $xml->list( qw( users views items ) );

Returns a list of tags values.

var()

# get a hash ref to the xml data for direct access.
$xml_ref = $xml->var();
$xml_ref->{root}->{users}->{user}->{admin} = 'username';
say $xml_ref->{root}->{users}->{user}->{admin};

Returns a hash reference to the in memory xml data.

delete()

# delete tags from memory, changes will apply when saving file.
$xml->delete(@names);

Delete a list of tags. Tags will be deleted from the object and memory only and will apply when updating or saving the file.

clear()

# delete entire xml object data.
$xml->clear();

Completely clears all loaded xml data from memory. This does not apply to the file until file is updated or saved.

update()

# save a list of variables and update the file.
$xml->update(%vars);

Set list of variables and save to the output file immediately.

save()

# write the output file.
$xml->save($file);

Save changes to the output file. If no file name just update the loaded file name.

get_file()

# load xml file content and return it as a hash, not added to the object
%xml_hash = $xml->get_file($file);
say $xml_hash{root}{config}{database}{user};

# load xml file content and return it as a hash ref, not added to the object
$xml_hash_ref = $xml->get_file($file);
say $xml_hash_ref->{root}->{config}->{database}->{user};

Load xml file content and return it as a hash or hash ref, not added to the object.

add_file()

# load and append another xml file to the object
$xml->add_file($another_file);

Load and append another xml file to the object.

Bugs

This project is available on github at https://github.com/mewsoft/Nile.

HOMEPAGE

Please visit the project's homepage at https://metacpan.org/release/Nile.

SOURCE

Source repository is at https://github.com/mewsoft/Nile.

SEE ALSO

See Nile for details about the complete framework.

AUTHOR

Ahmed Amin Elsheshtawy, احمد امين الششتاوى <mewsoft@cpan.org> Website: http://www.mewsoft.com

COPYRIGHT AND LICENSE

Copyright (C) 2014-2015 by Dr. Ahmed Amin Elsheshtawy احمد امين الششتاوى mewsoft@cpan.org, support@mewsoft.com, https://github.com/mewsoft/Nile, http://www.mewsoft.com

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