# XML Actions on every node
[![Build Status](https://travis-ci.org/MARTIMM/XmlActions.svg?branch=master)](https://travis-ci.org/MARTIMM/XmlActions) [![AppVeyor Build Status](https://ci.appveyor.com/api/projects/status/6yaqqq9lgbq6nqot?svg=true&branch=master&passingText=Windows%20-%20OK&failingText=Windows%20-%20FAIL&pendingText=Windows%20-%20pending)](https://ci.appveyor.com/project/MARTIMM/XmlActions/branch/master) [![License](http://martimm.github.io/label/License-label.svg)](http://www.perlfoundation.org/artistic_license_2_0)
## Synopsis
```
use Test;
use XML::Actions;
my Str $file = "a.xml";
$file.IO.spurt(Q:q:to/EOXML/);
EOXML
class A is XML::Actions::Work {
method final ( Array $parent-path, :$id ) {
is $id, 'hello', "final called: id = $id";
is $parent-path[*-1].name, 'final', 'this node is final';
is $parent-path[*-2].name, 'scxml', 'parent node is scxml';
method log ( Array $parent-path, :$expr ) {
is $expr, "'hello world'", "log called: expr = $expr";
is-deeply @$parent-path.map(*.name), ,
" found in parent array";
}
}
my XML::Actions $a .= new(:$file);
isa-ok $a, XML::Actions, 'type ok';
$a.process(:actions(A.new()));
```
Result would be like
```
ok 1 - type ok
ok 2 - final called: id = hello
ok 3 - this node is final
ok 4 - parent node is scxml
ok 5 - log called: expr = 'hello world'
ok 6 - found in parent array
```
## Documentation
Users who wish to process XML::Elements must provide an instantiated class which inherits from XML::Actions::Work. In that class, methods named after the elements can be defined. The `$parent-path` is an array holding the XML::Elements of the parent elements with the root on the first position and the current element on the last. The attributes are found on the XML element.
```
class A is XML::Actions::Work {
method someElement ( Array $parent-path, :$someAttribute ... ) {...}
method someOtherElement ( Array $parent-path, :$someAttribute ... ) {...}
}
```
### Note: clash with existing methods inherited from other classes.
There is an issue (#1) where an element triggered a call to a method from class **Any** and crashed. To prevent this, a method must be added explicitly overriding the method from the inherited class. In the meantime this call will be deprecated in favor of calling a method with `:start` attached to the element name as is done for processing the end tag. The above example would become;
```
class A is XML::Actions::Work {
method someElement:start ( Array $parent-path, :$someAttribute ... ) {...}
method someOtherElement:start ( Array $parent-path, :$someAttribute ... ) {...}
}
```
There are also text-, comment-, cdata- and pi-nodes. They can be defined as
```
method PROCESS-TEXT ( Array $parent-path, Str $text ) {...}
method PROCESS-COMMENT ( Array $parent-path, Str $comment ) {...}
method PROCESS-CDATA ( Array $parent-path, Str $cdata ) {...}
method PROCESS-PI ( Array $parent-path, Str $pi-target, Str $pi-content ) {...}
```
For uniformity these will also be renamed into `xml:text()`, `xml:comment()`, `xml:cdata()` and `xml:pi()` resp.
If you want to process an element after all children are processed, you can use the same element method with `-END` attached. It has the same number arguments.
```
method someElement-END ( Array $parent-path, :$someAttribute ... ) {...}
```
And this one will also be changed into `someElement:end()`.
### Changes
One can find the changes document [in ./doc/CHANGES.md][release]
## Installing
Use zef to install the package: `zef install XML::Actions`
## Versions of PERL, MOARVM
This project is tested against the newest perl6 version with Rakudo built on MoarVM implementing Perl v6.
## AUTHORS
Current maintainer **Marcel Timmerman** (MARTIMM on github)
## License
**Artistic-2.0**
[release]: https://github.com/MARTIMM/XmlActions/blob/master/doc/CHANGES.md