The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

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.