The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Nile-0.40
River stage zero No dependents
2 ++
/ Nile::XML

NAME

Nile::XML - XML file manager.

SYNOPSIS

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

        # get a reference to a new xml object.
        $xml = $self->me->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->me->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');

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.

object()

        # get a new xml object
        #my $xml_other = $xml->object;
        
        # load and manage xml files separately
        #$xml_other->load("xmlfile");

Returns a new xml object. This allows to load individual xml files and work with them.

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.