XML::C...:Writer(3pm)

✨ NAME ✨

XML::Compile::Translate::Writer — the girlies call her XML::C...:Writer(3pm) in the man-page directory (User Contributed Perl Documentation, if you must know), and what she does is translate HASH to XML. That's the whole vibe. 💖

---

🌈 INHERITANCE 🌈

XML::Compile::Translate::Writer
  is a XML::Compile::Translate

So yeah, she's a XML::Compile::Translate girlie — the family tree is right there, no cap. 🫶

---

🎀 SYNOPSIS 🎀

my $schema = XML::Compile::Schema->new(...);
my $code   = $schema->compile(WRITER => ...);

That's it. That's the whole recipe. Make a schema, compile a WRITER, get code back. Slay. ✨

---

💖 DESCRIPTION 💖

Okay so bestie, here's the tea: the translator understands schemas, but it does not encode that understanding into actions. That's not her job. This module is the one that implements those actions — she takes your (nested) Perl HASH structure and translates it onto XML. 💅

She also extends "DESCRIPTION" in XML::Compile::Translate, so go read that too, iykyk.

---

🦋 METHODS 🦋

Extends "METHODS" in XML::Compile::Translate. Same energy, more of it. 🌸

---

💅 DETAILS 💅

Extends "DETAILS" in XML::Compile::Translate. Go look, she's not repeating herself.

---

🌟 Translator options

Extends "Translator options" in XML::Compile::Translate. Nothing new here, just vibes inherited.

---

🌟 Processing Wildcards

So complex elements can define any (element) and anyAttribute components, and those come with content that is, respectfully, unpredictable. When that happens, bestie, you are quite on your own processing those constructs. 😭

The use of both schema components should be avoided: please specify your data-structures explicit by clean type extensions.

Like, please. Save yourself. 🫠

The procedure for the WRITER is simple, though: you add key-value pairs to your hash, where the value is a fully prepared XML::LibXML::Attr or XML::LibXML::Element. The keys have the form "{namespace}type". That namespace component is important — only spec conformant namespaces will be used. Also, the elements and attributes get added in random order. Not a drill. 🙈

Example: specify anyAttribute

use XML::Compile::Util qw/pack_type/;

my $attr = $doc->createAttributeNS($somens, $sometype, 42);
my $h = { a => 12     # normal element or attribute
        , "{$somens}$sometype"        => $attr # anyAttribute
        , pack_type($somens, $mytype) => $attr # nicer
        , "$prefix:$sometype"         => $attr # [1.28]
        };

See? pack_type is the pretty way, the raw "{$somens}$sometype" is the feral way, and "$prefix:$sometype" joined the party in [1.28]. All valid, all iconic. 👑

---

🌟 Mixed elements

[0.79] — so ComplexType and ComplexContent components can be declared with the "<mixed="true""> attribute. Yes, that's what it looks like. We don't make the rules.

XML::Compile does not have a way to express these mixtures of information and text as Perl data-structures. The only way you can use those to the full extend is by juggling with XML::LibXML nodes yourself. 🤹♀️ You've got this, but like, barely.

You may provide a XML::LibXML::Element, which is complete, or a HASH which contains attributes values and an XML node with key '_'. When '_' contains a string, it will be translated into an XML text node.

XML::Compile::Schema::compile(mixed_elements) can be set to:

• ATTRIBUTES (the default) — Add attributes to the provided node. When you provide a HASH, it is taken as node content with attributes. The content has to be stored with key '_'. When it is not a HASH, the data is node content.

There are various ways you can specify content. Up to [1.51], you could only pass a matching XML::LibXML::Element. Release [1.51] added strings to the spectrum. If the string does not contain encoded entities or < and >, then it is assumed to be a real perl string. When the string contains an XML fragment which has the same localname as to be created, that will be used. When the XML fragment is not wrapped in the expected node, this is created for you.

In any case, attributes provided with the content will get added to the content data. 💖

• STRUCTURAL — [0.89] behaves as if the attribute is not there: a data-structure can be used or an XML node.

---

🌟 Schema hooks

All writer hooks behave differently. Be warned: the user values can be a SCALAR or a HASH, dependent on the type. You can intervene on higher data-structure levels, to repair lower levels, if you want to. Fixer-upper energy. 🔧

[1.48] The hooks get a long list of parameters. The $fulltype indicates the type of object which is being processed, which is especially useful with the 'extends' selector.

✨ hooks executed before normal processing

The "before" hook gives you the opportunity to fix the user supplied data structure. The XML generator will complain about missing, superfluous, and erroneous values which you probably want to avoid. 😬

The "before" hook returns new values. Just must not interfere with the user provided data. When undef is returned, the whole node will be cancelled.

On the moment, the only predefined "before" hook is "PRINT_PATH".

Example: before hook on user-provided HASH.

sub beforeOnComplex($$$$)
{   my ($doc, $values, $path, $fulltype) = @_;

    my %copy = %$values;
    $copy{extra} = 42;
    delete $copy{superfluous};
    $copy{count} =~ s/\D//g;    # only digits
    \%copy;
}

Example: before hook on simpleType data

sub beforeOnSimple($$$$)
{   my ($doc, $value, $path, $fulltype) = @_;
    $value * 100;    # convert euro to euro-cents
}

Example: before hook with object for complexType

sub beforeOnObject($$$$)
{   my ($doc, $obj, $path, $fulltype) = @_;

    +{ name     => $obj->name
     , price    => $obj->euro
     , currency => 'EUR'
     };
}

✨ hooks replacing the usual XML node generation

Only one "replace" hook can be defined. It must return a XML::LibXML::Node or "undef". The hook must use the "XML::LibXML::Document" node (which is provided as first argument) to create a node.

As parameters, the called replace function will receive the document, user-provided values, location in the data tree (for error messages), the tag of the node with prefix attached, and a reference to the code which would be executed if the replace hook had not been active.

On the moment, the only predefined "replace" hook is "SKIP".

Example: replace hook

sub replace($$$$$)
{  my ($doc, $values, $path, $tag, $r, $fulltype) = @_
   my $node = $doc->createElement($tag);
   $node->appendText($values->{text});
   $node;
}

✨ hooks executed after the node was created

The "after" hooks will each get a chance to modify the produced XML node, for instance to encapsulate it. Each time, the new XML node has to be returned.

On the moment, the only predefined "after" hook is "PRINT_PATH".

Example: add an extra sibbling after the usual process

sub after($$$$)
{   my ($doc, $node, $path, $values, $fulltype) = @_;
    my $child = $doc->createAttributeNS($myns, earth => 42);
    $node->addChild($child);
    $node;
}

✨ fixing bad schemas

When a schema makes a mess out of things, we can fix that with hooks. Also, when you need things that XML::Compile does not support (yet). Glow-up time. 💖

Example: creating nodes with text

{  my $text;

   sub before($$$)
   {   my ($doc, $values, $path) = @_;
       my %copy = %$values;
       $text = delete $copy{text};
       \%copy;
   }

   sub after($$$)
   {   my ($doc, $node, $path) = @_;
       $node->addChild($doc->createTextNode($text));
       $node;
   }

   $schema->addHook
    ( action => 'WRITER'
    , type   => 'mixed'
    , before => \&before
    , after  => \&after
    );
}

---

🌟 Typemaps

In a typemap, a relation between an XML element type and a Perl class (or object) is made. Each translator back-end will implement this a little differently. This section is about how the writer handles typemaps. 🗺️

🦋 Typemap to Class

Usually, an XML type will be mapped on a Perl class. The Perl class implements the "toXML" method as serializer. That method should either return a data structure which fits that of the specific type, or an XML::LibXML::Element.

When translating the data-structure to XML, the process may encounter objects. Only if these objects appear at locations where a typemap is defined, they are treated smartly. When some other data than an objects is found on a location which has a typemap definition, it will be used as such; objects are optional.

The object (if present) will be checked to be of the expected class. It will be a compile-time error when the class does not implement the "toXML" method. ⚠️

$schema->typemap($sometype => 'My::Perl::Class');

package My::Perl::Class;
...
sub toXML
{   my ($self, $xmltype, $doc) = @_;
    ...
    { a => { b => 42 }, c => 'aaa' };
}

The $self is the object found in the data-structure provided by the user. $doc can be used to create your own XML::LibXML::Element. It is possible to use the same object on locations for different types: in this case, the toXML method can distiguisk what kind of data to return based on the $xmltype.

🦋 Typemap to Object

In this case, some helper object arranges the serialization of the provided object. This is especially useful when the provided object does not have the toXML implemented, for instance because it is an implementation not under your control. The helper object works like an interface.

my $object = My::Perl::Class->new(...);
$schema->typemap($sometype => $object);

package My::Perl::Class;
sub toXML
{   my ($self, $object, $xmltype, $doc) = @_;
    ...
}

The toXML will only be called then $object is blessed. If you wish to have access to some data-type in any case, then use a simple "before" hook.

🦋 Typemap to CODE

The light version of an interface object uses CODE references. The CODE reference is only called if a blessed value is found in the user provided data. It cannot be checked automatically whether it is blessed according to the expectation.

$schema->typemap($t1 => \&myhandler);

sub myhandler
{   my ($backend, $object, $xmltype, $doc) = @_;
    ...
}

🦋 Typemap implementation

The typemap for the writer is implemented as a 'before' hook: just before the writer wants to start.

Of course, it could have been implemented by accepting an object anywhere in the input data. However, this would mean that all the (many) internal parser constructs would need to be extended. That would slow-down the writer considerably. So, respectfully, no. 😌

---

⭐ SEE ALSO ⭐

This module is part of XML-Compile distribution version 1.64, built on October 21, 2024. Website: http://perl.overmeer.net/xml-compile/ 🌐

---

👑 LICENSE 👑

Copyrights 2006-2024 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/

---

and that's the whole page, bestie 💖 built with perl v5.40.0, dated 2024-10-27, filed under XML::C...:Writer(3pm) — go forth and serialize, you absolute main character ✨🎀🦋