NAME
    XML::Simple::Sugar - Sugar sprinkled on XML::Simple

VERSION
    version 1.0.1

SYNOPSIS
        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);
    
        #Working with a specific element
        my $departments = $xs->company->departments;
    
        #Setting an attribute on the first element in a collection
        $departments->department([0])->xml_attr({ name => 'IT Department', manager => 'John Smith' });

        #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');
    
        #Setting an attribute with attr
        $person->xml_attr({ skills => 'Perl' });
    
        #Or optionally setting attributes with a hashref
        $xs->company->departments->department([0])->person([0])->salary({ 'jobgrade' => 10, 'exempt' => 1 });
    
        #Inspect the attributes of an element
        say Data::Dumper::Dumper($person->xml_attr);
    
        #Set and retrieve the string contents of an element
        $person->first_name->xml_content('John');
        say $person->first_name->xml_content;

        #Also...
        $person->first_name([0,'John']);
        #attributes, too...
        $person->first_name([0,'John',{'is_nice' => 'true'}]);
    
        #Write XML to a string
        say $xs->xml_write;
    
        #Write XML to a string from a child element (returns a string reflecting the root element's XML)
        say $person->xml_write;
    
        #A useful optional attribute
        my $xs_2 = XML::Simple::Sugar->new({ xml => '<your_xml>here</your_xml>' });
    
        #Or... (this is dumb, don't do it)
        my $xs_3 = XML::Simple::Sugar->new({ xml_data => { 'your_xml' => [{ 'content' => 'here' }] } });
 
        #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]);

  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/>.

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.

  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 particularly
    useful if you are working with an XML template.

  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.

Why this 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 probably
    should 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. :/

REPOSITORY
    <https://github.com/Camspi/XML-Simple-Sugar>

SEE ALSO
    *   XML::Simple

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.