=head1 NAME

XML::Compile::SOAP::Encoding - SOAP encoding

=head1 SYNOPSIS

 # see t/13enc11.t in the distribution for complex examples

 my $client = XML::Compile::SOAP11::Client->new();
 $client->startEncoding(...);  # loads this module

 # create: <SOAP-ENC:int>41</SOAP-ENC:int>
 my $xml = $client->enc(int => 41);

 # create: <SOAP-ENC:int id="hhtg">42</SOAP-ENC:int>
 my $xml = $client->enc(int => 42, 'hhtg');

 # create: <code xsi:type="xsd:int">43</code>
 my $int = pack_type SCHEMA2001, 'int';
 my $xml = $client->typed(code => $int, 43);

 # create: <ref href="#id-1"/>  (xyz get's id if it hasn't)
 my $xml = $client->href('ref', $xyz);
 my $xml = $client->href('ref', $xyz, 'id-1');  # explicit label
 
 # create: <number>3</number>   (gets validated as well!)
 my $xml = $client->element(number => $int, 3);

 # create one-dimensional array of ints
 my $xml = $client->array(undef, $int, \@xml);
 my $xml = $client->array('{myns}mylocal', $int, \@xml);

 # create multi-dimensional array
 my $xml = $client->multidim(undef, $int, $matrix);
 my $xml = $client->multidim('{myns}mylocal', $int, $matrix);

 # decode an incoming encoded structure (as far as possible)
 my $hash = $client->dec($xml);

=head1 DESCRIPTION

This module loads extra functionality into the L<XML::Compile::SOAP|XML::Compile::SOAP>
namespace: all kinds of methods which are used to SOAP-encode data.

The loading is triggered by calling L<startEncoding()|XML::Compile::SOAP::Encoding/"Encoding">.  In threaded
applications, you may wish to call that method once before the fork(),
such that not each threads or forked process needs to compile the
code again.  Of course, you can also C<use> this package explicitly.

=head1 METHODS

=head2 Transcoding

SOAP defines encodings, especially for XML-RPC.

=head3 Encoding

$obj-E<gt>B<array>((NAME|undef), ITEM_TYPE, ARRAY-of-ELEMENTS, OPTIONS)

=over 4

Arrays can be a mess: a mixture of anything and nothing.  Therefore,
you have to help the generation more than you may wish for.  This
method produces an one dimensional array, L<multidim()|XML::Compile::SOAP::Encoding/"Encoding"> is used for
multi-dimensional arrays.

The NAME is the packed type of the array itself.  When undef,
the C<< {soap-enc-ns}Array >> will be used (the action soap
encoding namespace will be used).

The ITEM_TYPE specifies the type of each element within the array.
This type is used to create the C<arrayType> attribute, however
doesn't tell enough about the items themselves: they may be
extensions to that type.

Each of the ELEMENTS must be an XML::LibXML::Node, either
self-constructed, or produced by one of the builder methods in
this class, like L<enc()|XML::Compile::SOAP::Encoding/"Encoding"> or L<typed()|XML::Compile::SOAP::Encoding/"Encoding">.

Returned is the XML::LibXML::Element which represents the
array.

 Option      --Default
 id            undef
 nested_array  ''
 offset        0
 slice         <all remaining>

. id => STRING

=over 4

Assign an id to the array.

=back

. nested_array => STRING

=over 4

The ARRAY type should reflect nested array structures if they are
homogeneous.  This is a really silly part of the specs, because there
is no need for it on any other comparible place in the specs... but ala.

For instance: C<< nested_array => '[,]' >>, means that this array
contains two-dimensional arrays.

=back

. offset => INTEGER

=over 4

When a partial array is to be transmitted, the number of the base
element.

=back

. slice => INTEGER

=over 4

When a partial array is to be transmitted, this is the length of
the slice to be sent (the number of elements starting with the C<offset>
element)

=back

=back

$obj-E<gt>B<element>(NAME, TYPE, VALUE)

=over 4

Create an element.  The NAME is for node, where a namespace component
is translated into a prefix.

=back

$obj-E<gt>B<enc>(LOCAL, VALUE, [ID])

=over 4

In the SOAP specification, encoding types are defined: elements
which do not have a distinguishable name but use the type of the
data as name.  Yep, ugly!

example: 

  my $xml = $soap->enc('int', 43);
  my $xml = $soap->enc(int => 43);
  print $xml->toString;
    # <SOAP-ENC:int>43</SOAP-ENC:int>

  my $xml = $soap->enc('int', 42, id => 'me');
  my $xml = $soap->enc(int => 42, id => 'me');
  print $xml->toString;
    # <SOAP-ENC:int id="me">42</SOAP-ENC:int>

=back

$obj-E<gt>B<href>(NAME, ELEMENT, [ID])

=over 4

Create a reference element with NAME to the existing ELEMENT.  When the
ELEMENT does not have an "id" attribute yet, then ID will be used.  In
case not ID was specified, then one is generated.

=back

$obj-E<gt>B<multidim>((NAME|undef), ITEM_TYPE, ARRAY-of-ELEMENTS, OPTIONS)

=over 4

A multi-dimensional array, less flexible than a single dimensional
array, which can be created with L<array()|XML::Compile::SOAP::Encoding/"Encoding">.

The array must be square: in each of the dimensions, the length of
each row must be the same.  On the other hand, it may be sparse
(contain undefs).  The size of each dimension is determined by the
length of its first element.

 Option--Default
 id      undef

. id => STRING

=back

$obj-E<gt>B<prefixed>(TYPE|(NAMESPACE,LOCAL))

=over 4

Translate a NAMESPACE-LOCAL combination (which may be represented as
a packed TYPE) into a prefixed notation.

The complication is that the NAMESPACE may not naturally have a prefixed
assigned to it: the produced SOAP message is the result of compilation,
and only the namespaces which are registered to be used during compile-time
are added to the list on the top-level.  See XML::Compile::SOAP subroutine compileMessage option prefix_table.

=back

$obj-E<gt>B<startEncoding>(OPTIONS)

=over 4

This needs to be called before any encoding routine, because it
initializes the internals.  Each call will reset all compiled
cached translator routines.

 Option    --Default
 doc         <required>
 namespaces  <required>

. doc => XML::LibXML::Document

. namespaces => HASH

=back

$obj-E<gt>B<typed>(NAME, TYPE, VALUE)

=over 4

A "typed" element shows its type explicitly, via the "xsi:type" attribute.
The VALUE will get processed via an auto-generated XML::Compile writer,
so validated.  The processing is cashed.  When VALUE already is an
XML::LibXML::Element, then no processing nor value checking will be
performed.

=back

=head3 Decoding

$obj-E<gt>B<dec>(XMLNODES)

=over 4

Decode the XMLNODES (list of XML::LibXML::Element objects).  Use
Data::Dumper to figure-out what the produced output is: it is a guess,
so may not be perfect (do not use XML-RPC but document style soap for
good results).

In LIST context, the HASH with decoded data and a HASH with the
id index are returned.  In SCALAR context, only the decoded data is
returned.

=back

$obj-E<gt>B<startDecoding>(OPTIONS)

=over 4

Each call to this method will restart the cache of the decoding
internals.

Currently B<not supported>, is the automatic decoding of:

=over 4

=item elements which inherit from SOAP-ENC:Array.

=back

 Option     --Default
 reader_opts  {}

. reader_opts => HASH

=over 4

Extend or overrule the default reader options.  Available options
are shown in L<XML::Compile::Schema::compile()|XML::Compile::Schema/"Compilers">.

=back

=back

=head1 SEE ALSO

This module is part of XML-Compile-SOAP distribution version 0.59,
built on November 05, 2007. Website: F<http://perl.overmeer.net/xml-compile/>

=head1 LICENSE

Copyrights 2007 by Mark Overmeer. For other contributors see ChangeLog.

This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
See F<http://www.perl.com/perl/misc/Artistic.html>

