NAME

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

SYNOPSIS

        ### This module may work for you... but may also
        ### not work.  Progress has been made, but the
        ### implementation is not complete and not well tested.

        # Add this to load the logic
        use XML::Compile::SOAP11::Encoding simplify => 1;

        # The internals are used by the ::SOAP11 module, and
        # probably should not be called by yourself.

DESCRIPTION

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

METHODS

   Transcoding
       SOAP defines encodings, especially for SOAP-RPC.

       Encoding

       $obj->array( <$name|undef>, $item_type, $elements, %options )
           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, multidim()  is  used  for
           multi-dimensional arrays.

           The  $name is the packed type of the array itself.  When undef, the "{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
           "arrayType" attribute, however doesn't tell enough about the items themselves: they may be extensions
           to that type.

           Each  of  the  $elements  (passed as ARRAY) must be an XML::LibXML::Node, either self-constructed, or
           produced by one of the builder methods in this class, like enc() or typed().

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

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

           array_type => STRING
             The arrayType attribute content.  When explicitly set to undef, the attribute is not created.

           id => STRING
             Assign an id to the array.  If not defined, than no id attribute is added.

           nested_array => STRING
             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: "nested_array => '[,]'", means that this array contains two-dimensional arrays.

           offset => INTEGER
             When a partial array is to be transmitted, the number of the base element.

           slice => INTEGER
             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 "offset" element)

       $obj->element($type, $name, $value)
           Create  an  element.  The $name is for node, where a namespace component is translated into a prefix.
           When you wish for a "type" attribute, use typed().

           When the $type does not contain a namespace indication, it is taken in the selected schema namespace.
           If the $value already is a XML::LibXML::Element, then that one is used (and the $name ignored).

       $obj->enc( $local, $value, [$id] )
           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>

       $obj->href( $name, $element, [$id] )
           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.

       $obj->multidim( <$name|undef>, $item_type, $elements, %options )
           A multi-dimensional array, less flexible than a single dimensional array, which can be  created  with
           array().

           The  table of $elements (ARRAY of ARRAYs) must be full: 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
       $obj->nil( [$type], $name )
           Create an element with $name which explicitly has the "xsi:nil" attribute.  If the $name is full (has
           a  namespace  to  it),  it will be translated into a QNAME, otherwise, it is considered not namespace
           qualified.

           If a $type is given, then an explicit type parameter is added.

       $obj->prefixed( $type|<$ns,$local> )
           Translate a $ns-$local combination (which may be represented as  a  packed  $type)  into  a  prefixed
           notation.

       $obj->startEncoding(%options)
            -Option--Default
             doc     <created internally with utf8>

           doc => XML::LibXML::Document node
       $obj->struct($type, $childs)
           Create   a   structure,   an   element   with   children.    The   $childs  must  be  fully  prepared
           XML::LibXML::Element objects.

       $obj->typed($type, $name, $value)
           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.  The $name will be ignored.

           If the $type is not qualified, then it is interpreted as basic  type,  as  defined  by  the  selected
           schema.   If  you  explicitly  need  a non-namespace typed item, then use an empty namespace.  In any
           case, the type must be defined and the value is validated.

           example:

            my $xml = $soap->typed(int => count => 5);
            my $xml = $soap->typed(pack_type(SCHEMA1999, 'int'), count => 5);

            my $xml = $soap->typed(pack_type('', 'mine'), a => 1);
            my $xml = $soap->typed('{}mine'), a => 1); #same

       Decoding

       $obj->rpcDecode($xmlnodes)
           Decode the elements found in the $xmlnodes (list of XML::LibXML::Node objects).  Use Data::Dumper  to
           figure-out  what  the  produced  output  is: it is a guess, so may not be perfect (do not use RPC but
           document style soap for good results).

           The decoded data is returned.  When "simplify" is set, then the returned data is compact but  may  be
           sloppy.  Otherwise, a HASH is returned containing as much info as could be extracted from the tree.

SEE ALSO

       This  module  is  part  of XML-Compile-SOAP distribution version 3.28, built on August 01, 2022. Website:
       http://perl.overmeer.net/CPAN/

LICENSE

       Copyrights 2007-2022 by [Mark Overmeer <markov@cpan.org>]. 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 http://dev.perl.org/licenses/

perl v5.34.0                                       2022-08-04                XML::Compile::SOAP11::Encoding(3pm)