# NAME XML::Invisible - transform "invisible XML" documents into XML using a grammar # PROJECT STATUS | OS | Build status | |:-------:|--------------:| | Linux | [![Build Status](https://travis-ci.org/mohawk2/xml-invisible.svg?branch=master)](https://travis-ci.org/mohawk2/xml-invisible) | [![CPAN version](https://badge.fury.io/pl/XML-Invisible.svg)](https://metacpan.org/pod/XML::Invisible) [![Coverage Status](https://coveralls.io/repos/github/mohawk2/xml-invisible/badge.svg?branch=master)](https://coveralls.io/github/mohawk2/xml-invisible?branch=master) # SYNOPSIS use XML::Invisible qw(make_parser); my $transformer = make_parser(from_file($ixmlspec)); my $ast = $transformer->(from_file($ixml_input)); use XML::Invisible qw(make_parser ast2xml); my $transformer = make_parser(from_file($ixmlspec)); my $xmldoc = ast2xml($transformer->(from_file($ixml_input))); to_file($outputfile, $xmldoc->toStringC14N(1)); # or, with conventional pre-compiled Pegex grammar my $parser = Pegex::Parser->new( grammar => My::Thing::Grammar->new, receiver => XML::Invisible::Receiver->new, ); my $got = $parser->parse($input); # from command line cpanm XML::Invisible XML::Twig perl -MXML::Invisible=make_parser,ast2xml -e \ 'print ast2xml(make_parser(join "", <>)->("(a+b)"))->toStringC14N(1)' \ examples/arith-grammar.ixml | xml_pp # canonicalise a document use XML::Invisible qw(make_parser make_canonicaliser); my $ixml_grammar = from_file('examples/arith-grammar.ixml'); my $transformer = make_parser($ixml_grammar); my $ast = $transformer->(from_file($ixml_input)); my $canonicaliser = make_canonicaliser($ixml_grammar); my $canonical = $canonicaliser->($ast); # DESCRIPTION An implementation of Steven Pemberton's Invisible XML concept, using [Pegex](https://metacpan.org/pod/Pegex). Supply it with your grammar, in Pegex format (slightly different from Steven's specification due to differences between his notation and Pegex's), it returns you a function, which you can call to transform "invisible XML" documents into actual XML. This is largely a Pegex "receiver" class that exploits the `+` and `-` syntax in rules in slightly unintended ways, and a wrapper to make this operate. # GRAMMAR SYNTAX See [Pegex::Syntax](https://metacpan.org/pod/Pegex::Syntax). Generally, all rules will result in an XML element. All terminals will need to capture with `()` (see example below). However, if you specify a dependent token with `+` it will instead become an attribute (equivalent of Steven's `@`). If `-`, this will "flatten" (equivalent of Steven's `-`) - the children will be included without making an element of that node. Since in Pegex any element can be skipped entirely with `.`, you can use that instead of `-` to omit terminals. E.g. expr: +open -arith +close open: /( LPAREN )/ close: /( RPAREN )/ arith: left -op right left: +name right: -name name: /(a)/ | /(b)/ op: +sign sign: /( PLUS )/ When given `(a+b)` yields: b # FUNCTIONS ## make\_parser Exportable. Returns a function that when called with an "invisible XML" document, it will return an abstract syntax tree (AST), of the general form: { nodename => 'expr', attributes => { open => '(', sign => '+', close => ')' }, children => [ { nodename => 'left', attributes => { name => 'a' } }, { nodename => 'right', children => [ 'b' ] }, ], } Arguments: - an "invisible XML" Pegex grammar specification, OR a [Pegex::Grammar](https://metacpan.org/pod/Pegex::Grammar) object See [XML::Invisible::Receiver](https://metacpan.org/pod/XML::Invisible::Receiver) for more. ## ast2xml Exportable. Turns an AST, as output by ["make\_parser"](#make_parser), from [XML::Invisible::Receiver](https://metacpan.org/pod/XML::Invisible::Receiver) into an object of class [XML::LibXML::Document](https://metacpan.org/pod/XML::LibXML::Document). Needs [XML::LibXML](https://metacpan.org/pod/XML::LibXML) installed, which as of version 0.05 of this module is only a suggested dependency, not required. Arguments: - an AST from [XML::Invisible::Receiver](https://metacpan.org/pod/XML::Invisible::Receiver) ## make\_canonicaliser Exportable. Returns a function that when called with an AST as produced from a document by a ["make\_parser"](#make_parser), returns a canonical version of the original document, or `undef` if it failed. Arguments: - an XML::Invisible grammar It uses a few heuristics: - literals that are 0-1 (`?`) or any number (`*`) will be omitted - literals that are at least one (`+`) will be inserted once - if an "any" group is given, the first one that matches will be selected This last one means that if you want a canonical representation that is not the bare minimum, provide that as a literal first choice (see the `assign` rule below - while it will accept any or no whitespace, the "canonical" version is given): expr: target .assign source target: +name assign: ' = ' | (- EQUAL -) source: -name name: /( ALPHA (: ALPHA | DIGIT )* )/ # DEBUGGING To debug, set environment variable `XML_INVISIBLE_DEBUG` to a true value. # SEE ALSO [Pegex](https://metacpan.org/pod/Pegex) [https://homepages.cwi.nl/~steven/ixml/](https://homepages.cwi.nl/~steven/ixml/) - Steven Pemberton's Invisible XML page # AUTHOR Ed J, `` # BUGS Please report any bugs or feature requests on [https://github.com/mohawk2/xml-invisible/issues](https://github.com/mohawk2/xml-invisible/issues). Or, if you prefer email and/or RT: to `bug-xml-invisible at rt.cpan.org`, or through the web interface at [http://rt.cpan.org/NoAuth/ReportBug.html?Queue=XML-Invisible](http://rt.cpan.org/NoAuth/ReportBug.html?Queue=XML-Invisible). I will be notified, and then you'll automatically be notified of progress on your bug as I make changes. # LICENSE AND COPYRIGHT Copyright 2018 Ed J. This program is free software; you can redistribute it and/or modify it under the terms of the the Artistic License (2.0). You may obtain a copy of the full license at: [http://www.perlfoundation.org/artistic\_license\_2\_0](http://www.perlfoundation.org/artistic_license_2_0)