NAME
C<LibXML::Class::ItemDescriptor> - XML sequence item descriptor


head

This role consumes L<C<LibXML::Class::Descriptor>|Descriptor.md>.


item

See the L<I<LICENSE>|../../../../LICENSE> file in this distribution.


root

para

L<Examples| file:../examples/index.podlite>


L<Download |file:../download/index.podlite>


React

=begin React :component<HeaderCol> :id<menu> 
=para L<Documentation|/doc/introduction>
=para L<Modules| /mods>
=para L<Examples| file:../examples/index.podlite>
=para L<Download |file:../download/index.podlite>
=para L<About|file:../about/index.podlite>
=para 🔍 K<⌘K>/K<ctrl-K>
=end React


HEADER

FOOTER

ItemDescriptor

The fastest way to start using C<LibXML::Class> is to apply bare C<xml-element> trait to a class or role:


code

=begin code :lang<raku>
class Record is xml-elemnt {
    has Int:D $.id is required;
    has Str:D $.comment is required;
    has Num $.amount;
}
=end code


And you're all set! Now, at anytime an instance C<$record> of C<Record> can be serialized into C<LibXML::Document> by
calling C<to-xml> method on it:


=begin code :lang<raku>
say $record.to-xml;
=end code


In a slightly more complex case a class attribute can store an instance of another C<xml-element> class:


=begin code :lang<raku>
class Root is xml-element {
    has Record:D $.record is required;
}
=end code


See L<I<manual01.raku>|../../../../examples/manual01.raku> in the L<I<examples>|../../../../examples> directory.


Not only classes but roles too can be declared as C<xml-element>. Depending on the way a role is used the effect could
differ.


Consuming an C<xml-element> role by a plain class turns it into a serializable explicit class. See more in the
L<Implicit Or Explicit Declarations|#implicit-or-explicit-declarations> section about explicitness.


Consuming such role by a C<xml-element> class would simply extend it with role's functionality while allowing the role
to maintain control over some serialization aspects like, for example, namespaces.


See L<I<manual02.raku>|../../../../examples/manual02.raku> and L<I<manual03.raku>|../../../../examples/manual03.raku>.


The way L<C<LibXML::Class>|../Class.md> works in the above example is by adding a role to the type object C<xml-element>
trait is used with. With the role a parent class C<LibXML::Class::XMLObject> is added too. Normally these implementation
details must not bother you, but they worth mentioning from the point of view that a lot of extra methods become
available on the instances of C<xml-element> classes.


In order to minimize possible conflicts or side effects, it's been taken into account that the XML standard forbids node
names that start with C<xml> prefix. Therefore nearly every method or attribute name, would it be public or private,
declared by C<LibXML::Class> classes or roles, are starting with C<xml->. Moreover, in some cases of implicit actions
taken by C<LibXML::Class> user attributes, starting same C<xml-> prefix, are skipped and wouldn't be de-/serialized.


There are only two exceptions: methods C<to-xml> and C<from-xml>, but these are rather part of more common convention
within Raku ecosystem. Besides, it'd be ugly to have a call like C<$obj.xml-to>.


L<C<LibXML::Class>|../Class.md> exports three traits to mark Raku objects as XML-serializable:


I<Note> that an C<xml-text> Raku attribute is not limited to stringy types only. It can be of any type for each either
coercion from L<C<Str>|https://docs.raku.org/type/Str> is implemented or custom de-/serializers are defined.


=begin code :lang<raku>
class Record is xml-element {
    has Str $.attr is xml-attribute;
    has Str $.content is xml-text;
}

say Record.new(:attr<something>, :content("line1\nline2")).to-xml;
# <?xml version="1.0" encoding="UTF-8"?>
# <Record attr="something">line1
# line2</Record>
=end code


Both C<xml-element> and C<xml-attribute> traits share similar signatures: C«:(Str:D $name?, *%named)» – where C<$name>
is element/attribute name to be used for XML representation. If omitted then see the section L<XML Nodes Naming
Conventions|#xml-nodes-naming-convention> below. The allowed named arguments vary depending on the context and object
the trait is applied to.


C<xml-text> doesn't take any positional argument but also shares a few named ones with the other two traits.


The order in which a XML node gets its name is defined by the rules in this section. The rules differ for each of
C<xml-attribute> and C<xml-element> traits.


For C<xml-attribute> everything is simple:


Things are somewhat less simple for C<xml-element>. First of all, looking ahead, let's mention that when serializaing
an attribute as XML element it is possible to specifiy that we want it to be wrapped into a special tag we call
'container'. L<Containerization|#Containers> will have its own section down below in this manual, so for now we
just need to know about it.


When an C<xml-element> type object is an XML sequence we would also need to give names to its items. The rules for them
are basically the same as for attributes with the only exception that items cannot be containerized.


Type Object C<xml-element> Named Arguments


When C<xml-element> is used with a class or a role the following named arguments can be used:


When C<xml-element> is used with a class more named arguments become available:


All three attribute traits: C<xml-element>, C<xml-attribute>, and C<xml-text> – share a few named arguments:


The following arguments are shared by C<xml-element> and C<xml-attribute>:


The following arguments are specific to C<xml-element>:


Since some of trait parameters are overlapping the question of priorities arises. There is nothing complex here as the
rule of thumb says: attribute or sequence item is the head of its all. So, if in doubt – set it on the attribute/item.


If a parameter is not explicitly specified for the attribute/item the module check up with either its declarant or its
target type, if the target is an C<xml-element>. Which one is used depends on the particular parameter and mostly it's
rather intuitive to guess.


The configuration's advise could be used when none of the above provides a concrete answer. For example, when finding
out about lazy deserialization C<LibXML::Class> may refer to config's C<eager> parameter.


When C<xml-element> trait is applied to a type object by default it tries to use I<implicit> mode meaning that all
attributes of the object are marked as serializable. A typical example of implicit class is the example in the
L<Kick-start> section above.


Manual

NAME
C<LibXML::Class::Document> - document object


The concept of C<LibXML::Class> document is mostly covered in L<C<LibXML::Class::Manual>|Manual.md>.


Document

The Raku Knowledge Base


=begin React :component<HeaderCol> :id<footer>  
=begin nested :!nested
=item1 B<Language>
    =item2 L<Get started|file:../getting-started/getting-started.podlite>
    =item2 L<Why Raku?|/doc/language/faq#Why-should-I-learn-Raku-What's-so-great-about-it>
    =item2 L<Try Raku|https://glot.io/new/raku>
    =item2 L<Raku cheat sheet|https://github.com/Raku/mu/blob/master/docs/Perl6/Cheatsheet/cheatsheet.txt>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<Raku on Exercism|https://exercism.org/tracks/raku>
    =item2 L<Wikipedia|https://en.wikipedia.org/wiki/Raku_(programming_language)>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>

=end nested
=begin nested :!nested

=item1 B<L<Documentation|/doc>>
    =item2 L<Getting started, Migration guides from other languages, & Tutorials | file:../doc/introduction.podlite>
    =item2 L<Language References|file:../doc/reference.podlite>
    =item2 L<Type Reference| file:../doc/types.podlite>
    =item2 L<Miscellaneous| file:../doc/miscellaneous.podlite>
    =item2 L<FAQs (Frequently Asked Questions)|/doc/language/faq>
    =item2 L<Community|/doc/language/community>
    =item2 L<The list of all documents|file:../doc/index.podlite>

=item1 B<Resources>
    =item2 L<The Raku Guide|https://raku.guide/>
    =item2 L<Books |https://perl6book.com/>
    =item2 L<Rosetta Code | https://www.raku.org/community/rosettacode>

=end nested
=begin nested :!nested

=item1 B<Resoures>
    =item2 L<Download | file:../download/index.podlite>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>

=item1 B<Learning>
    =item2 L<The Raku Guide|https://raku.guide/>
    =item2 L<Wikibook |https://en.wikibooks.org/wiki/Raku_Programming>
    =item2 L<Books |https://perl6book.com/>
    =item2 L<Rosetta Code | https://www.raku.org/community/rosettacode>
    =item2 L<Learn Raku in Y minutes|https://learnxinyminutes.com/docs/raku/>
    =item2 L<Golfing |https://github.com/AlexDaniel/raku-golf-cheatsheet>
=end nested
=begin nested :!nested

=item1 B<Explore>
    =item2 L<Raku Blog Aggregator|https://planet.raku.org/>
    =item2 L<Rakudo Weekly|https://rakudoweekly.blog/>
    =item2 L<The Weekly Challenge |https://perlweeklychallenge.org/>
    =item2 L<Raku Advent Calendar|https://raku-advent.blog/>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>

=end nested
=end React


=begin React :component<CookieConsent> :id<CookieConsent> :buttonCaption("Got it!")
=para
This website uses cookies for analytics.
=end React


ItemDescriptor

NAME `LibXML::Class::ItemDescriptor` - XML sequence item descriptor

DESCRIPTION

Attributes

SEE ALSO

COPYRIGHT

LICENSE

LibXML::Class v0.0.1

Authors

License

Dependencies

Test Dependencies

Provides

Documentation

NAME LibXML::Class::ItemDescriptor - XML sequence item descriptor