NAME

Business::cXML::Object - Generic cXML object

SYNOPSIS

        package Business::cXML::YourPackage;
        use base qw(Business::cXML::Object);

        use constant NODENAME => 'XMLNodeName';

        use constant PROPERTIES => (
                first_name => '',
                last_name  => undef,
                emails     => [],
                phone      => undef,
        );
        # new(), first_name(), last_name() and emails() get/set methods will be provided automatically

        # Optionally: an e-mail is actually a Something::Email object
        # Even more optional: a phone is actually a Something::Number with "Phone" argument
        use constant OBJ_PROPERTIES => (
                emails => 'Something::Email',
                phone  => [ 'Something::Number', 'Phone' ],
        );

DESCRIPTION

Base class for cXML objects which represent useful data (pretty much every module except Business::cXML and Business::cXML::Transmission).

Declarations in PROPERTIES represent property names to create in new instances along with their default value. A default value of undef is acceptable: every possible property must be explicitly declared. A default value of [] indicates that the property is a list instead of a single value. can() will behave as expected, recognizing your methods and automatic property methods.

Declare those properties which should be objects (or lists of objects) of a specific class in optional OBJ_PROPERTIES (in addition to PROPERTIES) to specify which class (see example in "SYNOPSIS"). If the class is actually an arrayref, the first element will be considered the class name and all other elements will be passed as arguments to the class' new() after the value hashref argument.

NODENAME will be used in cases where _nodeName cannot be inferred from context.

COMMON METHODS

The following methods are automatically available in all objects which inherit from this one.

new( [$nodename], [$node], [$properties] )

In some cases, specifying $nodename is necessary, such as when creating a new multi-name object like Business::cXML::Amount without a source $node. This sets property _nodeName. Alternatively, $properties can also contain a _nodeName, which is writeable during object creation.

XML::LibXML::Element $node is passed to "from_node()".

Hashref $properties is passed to "set()".

set( %properties )

Batch sets all known read-write properties, safely ignoring any unknown keys.

copy( $object )

Copy data from another cXML object into our own, only considering known properties. It is thus theoretically safe to copy from an object of a different class. Deep structures (hashes, arrays, other objects) are cloned into new copies.

The following methods are required to be provided by classes which inherit from this one.

from_node( $node )

Overwrite our internal data from what is found by traversing $node, a XML::LibXML::Element.

to_node( $doc )

Returns an XML::LibXML::Element constructed from our internal data. $doc can be any existing XML::LibXML::Element so that this method can return a new detached element within the same existing document.

can( $methodname )

UNIVERSAL::can() is properly overloaded according to "PROPERTIES" so it can still safely be used.

PROPERTY METHODS

Each property declared in PROPERTIES of classes which inherit from this one, can be read from and written to by invoking a method of the same name.

Calling with no arguments (perhaps not even parenthesis) returns the current value.

Calling with an argument overwrites the property and returns the new value. For arrayref properties (documented with a [] suffix), setting a new value actually pushes a new one into the list. For properties which are objects of a specific class, passing a hashref argument automatically creates a new object of that class with that hashref.

Example:

        my $addr = new Business::cXML::Contact;

        $addr->name('John Smith');
        print $addr->name;  # Prints: John Smith

        $addr->emails('john1@');
        $addr->emails('john2@');
        print join(' ', @{ $addr->emails });  # Prints: john1@ john2@

The following properties are automatically available in all objects which inherit from this one:

_nodeName

Read-only name of the current cXML node.

AUTHOR

Stéphane Lavergne https://github.com/vphantom

ACKNOWLEDGEMENTS

Graph X Design Inc. https://www.gxd.ca/ sponsored this project.

COPYRIGHT & LICENSE

Copyright (c) 2017-2018 Stéphane Lavergne https://github.com/vphantom

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

cpanm Business::cXML

perl -MCPAN -e shell
install Business::cXML