NAME
XML::Simple::Sugar - Sugar sprinkled on XML::Simple
VERSION
version v1.0.4
SYNOPSIS
The basics...
use Modern::Perl;
use Data::Dumper;
use XML::Simple::Sugar;
my $xs = XML::Simple::Sugar->new();
#Autovivify some elements nested within each other, and set the content of the salary element
$xs->company->departments->department([0])->person([0])->salary(60000);
my $departments = $xs->company->departments;
$departments->department([0])->xml_attr({ name => 'IT Department', manager => 'John Smith' });
say $xs->xml_write;
# Or from a child element... (returns a string reflecting the root element's XML)
say $departments->xml_write;Working with existing XML
my $xs = XML::Simple::Sugar->new({ xml => '<your_xml>here</your_xml>' });Setting and retrieving content/attributes
# Return all person elements in the first department element and say their first names
map{ say $_->first_name->xml_content; } $xs->company->departments->department([0])->person(['all']);
# Setting the content of elements
my $person = $xs->company->departments->department([0])->person([0]);
$person->first_name('John')->last_name('Smith')->email('jsmith@example.com');
# Or, using xml_content...
$person->first_name->xml_content('John');
say $person->first_name->xml_content;
# Setting attributes of an element
$xs->company->departments->department([0])->person([0])->salary({ 'jobgrade' => 10, 'exempt' => 1 });
# Or, using xml_attr...
$person->xml_attr({ skill => 'Perl', skill_level => 'intermediate' });
say Data::Dumper::Dumper($person->xml_attr);
# Or setting the string contents of an element and attribute values all at once...
$person->first_name([0,'John',{'is_nice' => 'true'}]);Composing larger documents from other XML::Simple::Sugar objects
my $xs=XML::Simple::Sugar->new();
my $xs2=XML::Simple::Sugar->new();
$xs2->table->tr->th([0,'First Name',{ style => 'text-align:left' }]);
$xs2->table->tr->th([1,'Last Name']);
$xs->html->body->div->h1('Page Title')->xml_attr({ style => 'font-weight:bold' });
$xs->html->body->div([1,$xs2]);DESCRIPTION
This module is a wrapper around XML::Simple to provide AUTOLOADed accessors to XML nodes.
WHY ANOTHER XML MODULE?
I wanted to write/manipulate simple XML payloads with more DWIMmery than what I found in modules available on CPAN (admittedly I didn't look very hard). If the above syntax doesn't accomplish that for you, you should probably use a different module.
Additionally, this package depends on XML::Simple, which currently has a "do not use this module in new code" notice. If you are cool with that, then so am I. :)
PLEASE BE ADVISED
Most of the automagic happens with AUTOLOAD. Accessors/mutators and method names in this package cannot be used as element names in the XML document. XML naming rules prohibit the use of elements starting with the string "xml", so I've used this string as a prefix to all accessors/mutators/methods to avoid potential conflicts with AUTOLOAD. Sorry for the extra characters. :/
ATTRIBUTES
xml_autovivify (bool)
This attribute determines on a per element basis whether new attributes or elements may be introduced. Child elements inherit this setting from their parent. Setting autovivify to false is useful when working with templates with a strict predefined XML structure. This attribute is true by default.
xml_data (XML::Simple compliant Perl representation of an XML document)
This is the Perl representation of the XML. This is ugly to work with directly (hence this module), but in lieu of methods yet unwritten there may be a use case for having direct access to this structure.
xml_index
The index number of an element in a collection
xml_node
The name of the current node
xml_parent
The parent XML::Simple::Sugar object to the current element
xml
This readonly attribute is only useful during instantiation (XML::Simple::Sugar->new({ xml => $xml_string })). This is primarily intended for working with XML templates, or XML service responses.
xml_xs
This is underlying XML::Simple object. If you need to adjust the XML declaration, you can do that by passing an an XML::Simple object with your preferred options to the constructor. Be wary of setting other XML::Simple options as this module will happily overwrite anything that conflicts with its assumptions.
xml_root
Returns the root element XML::Simple::Sugar object
xml_content (String)
Returns the content of the current element
METHODS
xml_read (XML String)
Parses an XML string and sets the data attribute
xml_write
Writes out an XML string
xml_attr (HashRef)
If passed a hash reference, this method will set the attributes of the current element. Otherwise, this method returns a hash reference representing the current element's attributes.
xml_rmattr (String)
This method removes the passed scalar argument from the element's list of attributes.
xml_nest (XML::Simple::Sugar)
Merges another XML::Simple::Sugar object as a child of the current node.
REPOSITORY
https://github.com/Camspi/XML-Simple-Sugar
MINIMUM PERL VERSION SUPPORTED
Perl 5.18.2 or later is required by this module. Lesser Perl versions struggle with deep recursion. Patches welcome.
VERSIONING
Semantic versioning is adopted by this module. See http://semver.org/.
SEE ALSO
CREDITS
Jonathan Cast for excellent critique.
Kyle Bolton for peeking over my shoulder and giving me pro tips.
eMortgage Logic, LLC., for allowing me to publish this module to CPAN
AUTHOR
Chris Tijerina
COPYRIGHT AND LICENSE
This software is copyright (c) 2014 by eMortgage Logic LLC.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.