.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "XML::DT 3pm"
.TH XML::DT 3pm "2019-11-09" "perl v5.30.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
XML::DT \- a package for down translation of XML files
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use XML::DT;
\&
\& %xml=( \*(Aqmusic\*(Aq    => sub{"Music from: $c\en"},
\&        \*(Aqlyrics\*(Aq   => sub{"Lyrics from: $v{name}\en"},
\&        \*(Aqtitle\*(Aq    => sub{ uc($c) },
\&        \*(Aq\-userdata => { something => \*(AqI like\*(Aq },
\&        \*(Aq\-default\*(Aq => sub{"$q:$c"} );
\&
\& print dt($filename,%xml);
.Ve
.SH "ABSTRACT"
.IX Header "ABSTRACT"
This module is a \s-1XML\s0 down processor. It maps tag (element)
names to functions to process that element and respective
contents.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module processes \s-1XML\s0 files with an approach similar to
\&\s-1OMNIMARK.\s0 As \s-1XML\s0 parser it uses XML::LibXML module in an independent
way.
.PP
You can parse \s-1HTML\s0 files as if they were \s-1XML\s0 files. For this, you must
supply an extra option to the hash:
.PP
.Vb 3
\& %hander = ( \-html => 1,
\&             ...
\&           );
.Ve
.PP
You can also ask the parser to recover from \s-1XML\s0 errors:
.PP
.Vb 3
\& %hander = ( \-recover => 1,
\&             ...
\&           );
.Ve
.SH "Functions"
.IX Header "Functions"
.SS "dt"
.IX Subsection "dt"
Down translation function \f(CW\*(C`dt\*(C'\fR receives a filename and a set of
expressions (functions) defining the processing and associated values
for each element.
.SS "dtstring"
.IX Subsection "dtstring"
\&\f(CW\*(C`dtstring\*(C'\fR works in a similar way with \f(CW\*(C`dt\*(C'\fR but takes input from a
string instead of a file.
.SS "dturl"
.IX Subsection "dturl"
\&\f(CW\*(C`dturl\*(C'\fR works in a similar way with \f(CW\*(C`dt\*(C'\fR but takes input from an
Internet url instead of a file.
.SS "pathdt"
.IX Subsection "pathdt"
The \f(CW\*(C`pathdt\*(C'\fR function is a \f(CW\*(C`dt\*(C'\fR function which can handle a subset
of XPath on handler keys. Example:
.PP
.Vb 7
\& %handler = (
\&   "article/title"        => sub{ toxml("h1",{},$c) },
\&   "section/title"        => sub{ toxml("h2",{},$c) },
\&   "title"                => sub{ $c },
\&   "//image[@type=\*(Aqjpg\*(Aq]" => sub{ "JPEG: <img src=\e"$c\e">" },
\&   "//image[@type=\*(Aqbmp\*(Aq]" => sub{ "BMP: sorry, no bitmaps on the web" },
\& );
\&
\& pathdt($filename, %handler);
.Ve
.PP
Here are some examples of valid XPath expressions under \s-1XML::DT:\s0
.PP
.Vb 10
\& /aaa
\& /aaa/bbb
\& //ccc                           \- ccc somewhere (same as "ccc")
\& /*/aaa/*
\& //*                             \- same as "\-default"
\& /aaa[@id]                       \- aaa with an attribute id
\& /*[@*]                          \- root with an attribute
\& /aaa[not(@name)]                \- aaa with no attribute "name"
\& //bbb[@name=\*(Aqfoo\*(Aq]              \- ... attribute "name" = "foo"
\& /ccc[normalize\-space(@name)=\*(Aqbbb\*(Aq]
\& //*[name()=\*(Aqbbb\*(Aq]               \- complex way of saying "//bbb"
\& //*[starts\-with(name(),\*(Aqaa\*(Aq)]   \- an element named "aa.*"
\& //*[contains(name(),\*(Aqc\*(Aq)]       \- an element       ".*c.*"
\& //aaa[string\-length(name())=4]                     "...."
\& //aaa[string\-length(name())&lt;4]                  ".{1,4}"
\& //aaa[string\-length(name())&gt;5]                  ".{5,}"
.Ve
.PP
Note that not all XPath is currently handled by \s-1XML::DT. A\s0 lot of
XPath will never be added to \s-1XML::DT\s0 because is not in accordance with
the down translation model. For more documentation about XPath check
the specification at http://www.w3c.org or some tutorials under
http://www.zvon.org
.SS "pathdtstring"
.IX Subsection "pathdtstring"
Like the \f(CW\*(C`dtstring\*(C'\fR function but supporting XPath.
.SS "pathdturl"
.IX Subsection "pathdturl"
Like the \f(CW\*(C`dturl\*(C'\fR function but supporting XPath.
.SS "ctxt"
.IX Subsection "ctxt"
Returns the context element of the currently being processed
element. So, if you call \f(CWctxt(1)\fR you will get your father element,
and so on.
.SS "inpath"
.IX Subsection "inpath"
\&\f(CW\*(C`inpath(pattern)\*(C'\fR is true if the actual element path matches the
provided pattern. This function is meant to be used in the element
functions in order to achieve context dependent processing.
.SS "inctxt"
.IX Subsection "inctxt"
\&\f(CW\*(C`inctxt(pattern)\*(C'\fR is true if the actual element father matches the
provided pattern.
.SS "toxml"
.IX Subsection "toxml"
This is the default \*(L"\-default\*(R" function. It can be used to generate
\&\s-1XML\s0 based on \f(CW$c\fR \f(CW$q\fR and \f(CW%v\fR variables. Example: add a new
attribute to element \f(CW\*(C`ele1\*(C'\fR without changing it:
.PP
.Vb 3
\&   %handler=( ...
\&     ele1 => sub { $v{at1} = "v1"; toxml(); },
\&   )
.Ve
.PP
\&\f(CW\*(C`toxml\*(C'\fR can also be used with 3 arguments: tag, attributes and contents
.PP
.Vb 1
\&   toxml("a",{href=> "http://local/f.html"}, "example")
.Ve
.PP
returns:
.PP
.Vb 1
\& <a href=\*(Aqhttp://local/f.html\*(Aq>example</a>
.Ve
.PP
Empty tags are written as empty tags. If you want an empty tag with opening and
closing tags, then use the \f(CW\*(C`tohtml\*(C'\fR.
.SS "tohtml"
.IX Subsection "tohtml"
See \f(CW\*(C`toxml\*(C'\fR.
.SS "xmltree"
.IX Subsection "xmltree"
This simple function just makes a \s-1HASH\s0 reference:
.PP
.Vb 1
\& { \-c => $c, \-q => $q, all_the_other_attributes }
.Ve
.PP
The function \f(CW\*(C`toxml\*(C'\fR understands this structure and makes \s-1XML\s0 with it.
.SS "mkdtskel"
.IX Subsection "mkdtskel"
Used by the mkdtskel script to generate automatically a \s-1XML::DT\s0 perl
script file based on an \s-1XML\s0 file. Check \f(CW\*(C`mkdtskel\*(C'\fR manpage for
details.
.SS "mkdtskel_fromDTD"
.IX Subsection "mkdtskel_fromDTD"
Used by the mkdtskel script to generate automatically a \s-1XML::DT\s0 perl
script file based on an \s-1DTD\s0 file. Check \f(CW\*(C`mkdtskel\*(C'\fR manpage for
details.
.SS "mkdtdskel"
.IX Subsection "mkdtdskel"
Used by the mkdtskel script to generate automatically a \s-1XML::DT\s0 perl
script file based on a \s-1DTD\s0 file. Check \f(CW\*(C`mkdtdskel\*(C'\fR manpage for
details.
.SH "Accessing parents"
.IX Header "Accessing parents"
With \s-1XML::DT\s0 you can access an element parent (or grand-parent)
attributes, till the root of the \s-1XML\s0 document.
.PP
If you use c<$dtattributes[1]{foo} = 'bar'> on a processing function,
you are defining the attribute \f(CW\*(C`foo\*(C'\fR for that element parent.
.PP
In the same way, you can use \f(CW$dtattributes[2]\fR to access the
grand-parent. \f(CW$dtattributes[\-1]\fR is, as expected, the \s-1XML\s0 document
root element.
.PP
There are some shortcuts:
.ie n .IP """father""" 4
.el .IP "\f(CWfather\fR" 4
.IX Item "father"
.PD 0
.ie n .IP """gfather""" 4
.el .IP "\f(CWgfather\fR" 4
.IX Item "gfather"
.ie n .IP """ggfather""" 4
.el .IP "\f(CWggfather\fR" 4
.IX Item "ggfather"
.PD
You can use these functions to access to your \f(CW\*(C`father\*(C'\fR, grand-father
(\f(CW\*(C`gfather\*(C'\fR) or great-grand-father (\f(CW\*(C`ggfather\*(C'\fR):
.Sp
.Vb 3
\&   father("x"); # returns value for attribute "x" on father element
\&   father("x", "value"); # sets value for attribute "x" on father
\&                                 # element
.Ve
.Sp
You can also use it directly as a reference to \f(CW@dtattributes\fR:
.Sp
.Vb 3
\&   father\->{"x"};           # gets the attribute
\&   father\->{"x"} = "value"; # sets the attribute
\&   $attributes = father;            # gets all attributes reference
.Ve
.ie n .IP """root""" 4
.el .IP "\f(CWroot\fR" 4
.IX Item "root"
You can use it as a function to access to your tree root element.
.Sp
.Vb 2
\&   root("x");          # gets attribute C<x> on root element
\&   root("x", "value"); # sets value for attribute C<x> on root
.Ve
.Sp
You can also use it directly as a reference to \f(CW$dtattributes[\-1]\fR:
.Sp
.Vb 3
\&   root\->{"x"};           # gets the attribute x
\&   root\->{"x"} = "value"; # sets the attribute x
\&   $attributes = root;    # gets all attributes reference
.Ve
.SH "User provided element processing functions"
.IX Header "User provided element processing functions"
The user must provide an \s-1HASH\s0 with a function for each element, that
computes element output. Functions can use the element name \f(CW$q\fR, the
element content \f(CW$c\fR and the attribute values hash \f(CW%v\fR.
.PP
All those global variables are defined in \f(CW$CALLER::\fR.
.PP
Each time an element is find the associated function is called.
.PP
Content is calculated by concatenation of element contents strings and
interior elements return values.
.ie n .SS """\-default"" function"
.el .SS "\f(CW\-default\fP function"
.IX Subsection "-default function"
When a element has no associated function, the function associated
with \f(CW\*(C`\-default\*(C'\fR called. If no \f(CW\*(C`\-default\*(C'\fR function is defined the
default function returns a \s-1XML\s0 like string for the element.
.PP
When you use \f(CW\*(C`/\-type\*(C'\fR definitions, you often need do set \f(CW\*(C`\-default\*(C'\fR
function to return just the contents: \f(CW\*(C`sub{$c}\*(C'\fR.
.ie n .SS """\-outputenc"" option"
.el .SS "\f(CW\-outputenc\fP option"
.IX Subsection "-outputenc option"
\&\f(CW\*(C`\-outputenc\*(C'\fR defines the output encoding (default is Unicode \s-1UTF8\s0).
.ie n .SS """\-inputenc"" option"
.el .SS "\f(CW\-inputenc\fP option"
.IX Subsection "-inputenc option"
\&\f(CW\*(C`\-inputenc\*(C'\fR forces a input encoding type. Whenever that is possible,
define the input encoding in the \s-1XML\s0 file:
.PP
.Vb 1
\& <?xml version=\*(Aq1.0\*(Aq encoding=\*(AqISO\-8859\-1\*(Aq?>
.Ve
.ie n .SS """\-pcdata"" function"
.el .SS "\f(CW\-pcdata\fP function"
.IX Subsection "-pcdata function"
\&\f(CW\*(C`\-pcdata\*(C'\fR function is used to define transformation over the
contents.  Typically this function should look at context (see
\&\f(CW\*(C`inctxt\*(C'\fR function)
.PP
The default \f(CW\*(C`\-pcdata\*(C'\fR function is the identity
.ie n .SS """\-cdata"" function"
.el .SS "\f(CW\-cdata\fP function"
.IX Subsection "-cdata function"
You can process \f(CW\*(C`<CDATA\*(C'\fR> in a way different from pcdata. If you
define a \f(CW\*(C`\-cdata\*(C'\fR method, it will be used. Otherwise, the \f(CW\*(C`\-pcdata\*(C'\fR
method is called.
.ie n .SS """\-begin"" function"
.el .SS "\f(CW\-begin\fP function"
.IX Subsection "-begin function"
Function to be executed before processing \s-1XML\s0 file.
.PP
Example of use: initialization of side-effect variables
.ie n .SS """\-end"" function"
.el .SS "\f(CW\-end\fP function"
.IX Subsection "-end function"
Function to be executed after processing \s-1XML\s0 file.  I can use \f(CW$c\fR
content value.  The value returned by \f(CW\*(C`\-end\*(C'\fR will be the \f(CW\*(C`dt\*(C'\fR return
value.
.PP
Example of use: post-processing of returned contents
.ie n .SS """\-recover"" option"
.el .SS "\f(CW\-recover\fP option"
.IX Subsection "-recover option"
If set, the parser will try to recover in \s-1XML\s0 errors.
.ie n .SS """\-html"" option"
.el .SS "\f(CW\-html\fP option"
.IX Subsection "-html option"
If set, the parser will try to recover in errors. Note that this
differs from the previous one in the sense it uses some knowledge of
the \s-1HTML\s0 structure for the recovery.
.ie n .SS """\-userdata"" option"
.el .SS "\f(CW\-userdata\fP option"
.IX Subsection "-userdata option"
Use this to pass any information you like to your handlers. The data
structure you pass in this option will be available as \f(CW$u\fR in
your code. \*(-- New in 0.62.
.ie n .SH "Elements with values other than strings (""\-type"")"
.el .SH "Elements with values other than strings (\f(CW\-type\fP)"
.IX Header "Elements with values other than strings (-type)"
By default all elements return strings, and contents (\f(CW$c\fR) is the
concatenation of the strings returned by the sub-elements.
.PP
In some situations the \s-1XML\s0 text contains values that are better
processed as a structured type.
.PP
The following types (functors) are available:
.IP "\s-1THE_CHILD\s0" 4
.IX Item "THE_CHILD"
Return the result of processing the only child of the element.
.IP "\s-1LAST_CHILD\s0" 4
.IX Item "LAST_CHILD"
Returns the result of processing the last child of the element.
.IP "\s-1STR\s0" 4
.IX Item "STR"
concatenates all the sub-elements returned values (\s-1DEFAULT\s0) all the
sub-element should return strings to be concatenated;
.IP "\s-1SEQ\s0" 4
.IX Item "SEQ"
makes an \s-1ARRAY\s0 with all the sub elements contents; attributes are
ignored (they should be processed in the sub-element). (returns a ref)
If you have different types of sub-elements, you should use \s-1SEQH\s0
.IP "\s-1SEQH\s0" 4
.IX Item "SEQH"
makes an \s-1ARRAY\s0 of \s-1HASH\s0 with all the sub elements (returns a ref); for
each sub-element:
.Sp
.Vb 3
\& \-q  => element name
\& \-c  => contents
\& at1 => at value1    for each attribute
.Ve
.IP "\s-1MAP\s0" 4
.IX Item "MAP"
makes an \s-1HASH\s0 with the sub elements; keys are the sub-element names,
values are their contents. Attributes are ignored. (they should be
processed in the sub-element) (returns a ref)
.IP "\s-1MULTIMAP\s0" 4
.IX Item "MULTIMAP"
makes an \s-1HASH\s0 of \s-1ARRAY\s0; keys are the sub-element names; values are
lists of contents; attributes are ignored (they should be processed in
the sub-element); (returns a ref)
.IP "\s-1MMAPON\s0(element\-list)" 4
.IX Item "MMAPON(element-list)"
makes an \s-1HASH\s0 with the sub-elements; keys are the sub-element names,
values are their contents; attributes are ignored (they should be
processed in the sub-element); for all the elements contained in the
element-list, it is created an \s-1ARRAY\s0 with their contents. (returns a
ref)
.IP "\s-1XML\s0" 4
.IX Item "XML"
return a reference to an \s-1HASH\s0 with:
.Sp
.Vb 3
\& \-q  => element name
\& \-c  => contents
\& at1 => at value1    for each attribute
.Ve
.IP "\s-1ZERO\s0" 4
.IX Item "ZERO"
don't process the sub-elements; return ""
.PP
When you use \f(CW\*(C`/\-type\*(C'\fR definitions, you often need do set \f(CW\*(C`\-default\*(C'\fR
function returning just the contents \f(CW\*(C`sub{$id}\*(C'\fR.
.SS "An example:"
.IX Subsection "An example:"
.Vb 8
\& use XML::DT;
\& %handler = ( contacts => sub{ [ split(";",$c)] },
\&              \-default => sub{$c},
\&              \-type    => { institution => \*(AqMAP\*(Aq,
\&                            degrees     =>  MMAPON(\*(Aqname\*(Aq)
\&                            tels        => \*(AqSEQ\*(Aq }
\&            );
\& $a = dt ("f.xml", %handler);
.Ve
.PP
with the following f.xml
.PP
.Vb 10
\& <degrees>
\&    <institution>
\&       <id>U.M.</id>
\&       <name>University of Minho</name>
\&       <tels>
\&          <item>1111</item>
\&          <item>1112</item>
\&          <item>1113</item>
\&       </tels>
\&       <where>Portugal</where>
\&       <contacts>J.Joao; J.Rocha; J.Ramalho</contacts>
\&    </institution>
\&    <name>Computer science</name>
\&    <name>Informatica </name>
\&    <name> history </name>
\& </degrees>
.Ve
.PP
would make \f(CW$a\fR
.PP
.Vb 10
\& { \*(Aqname\*(Aq => [ \*(AqComputer science\*(Aq,
\&               \*(AqInformatica \*(Aq,
\&               \*(Aq history \*(Aq ],
\&   \*(Aqinstitution\*(Aq => { \*(Aqtels\*(Aq => [ 1111, 1112, 1113 ],
\&                      \*(Aqname\*(Aq => \*(AqUniversity of Minho\*(Aq,
\&                      \*(Aqwhere\*(Aq => \*(AqPortugal\*(Aq,
\&                      \*(Aqid\*(Aq => \*(AqU.M.\*(Aq,
\&                      \*(Aqcontacts\*(Aq => [ \*(AqJ.Joao\*(Aq,
\&                               \*(Aq J.Rocha\*(Aq,
\&                               \*(Aq J.Ramalho\*(Aq ] } };
.Ve
.SH "DT Skeleton generation"
.IX Header "DT Skeleton generation"
It is possible to build an initial processor program based on an example
.PP
To do this use the function \f(CW\*(C`mkdtskel(filename)\*(C'\fR.
.PP
Example:
.PP
.Vb 1
\& perl \-MXML::DT \-e \*(Aqmkdtskel "f.xml"\*(Aq > f.pl
.Ve
.SH "DTD skeleton generation"
.IX Header "DTD skeleton generation"
It makes a naive \s-1DTD\s0 based on an example(s).
.PP
To do this use the function \f(CW\*(C`mkdtdskel(filename*)\*(C'\fR.
.PP
Example:
.PP
.Vb 1
\& perl \-MXML::DT \-e \*(Aqmkdtdskel "f.xml"\*(Aq > f.dtd
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBmkdtskel\fR\|(1) and \fBmkdtdskel\fR\|(1)
.SH "AUTHORS"
.IX Header "AUTHORS"
Home for \s-1XML::DT\s0;
.PP
http://natura.di.uminho.pt/~jj/perl/XML/
.PP
Jose Joao Almeida, <jj@di.uminho.pt>
.PP
Alberto Manuel Simões, <albie@alfarrabio.di.uminho.pt>
.SH "ACKNOWLEDGEMENTS"
.IX Header "ACKNOWLEDGEMENTS"
Michel Rodriguez    <mrodrigu@ieee.org>
.PP
José Carlos Ramalho <jcr@di.uminho.pt>
.PP
Mark A. Hillebrand
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright 1999\-2012 Project Natura.
.PP
This library is free software; you can redistribute it
and/or modify it under the same terms as Perl itself.