XML::DT(3pm)

📦

version 0.69 · 2 versions

0.69 · debian bookworm, debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking (latest)
0.69 · ubuntu jammy

, in debian bookworm, debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking

XML::DT 💖 (the `XML::DT(3pm)` manual, bestie edition)

okay so. you found the perl docs for XML::DT, which lives in the User Contributed Perl Documentation section of your man pages, and honestly? it's giving quiet legend. it's a package for down translation of XML files, and by the end of this you're gonna be obsessed. no cap. 🦋

✨ NAME ✨

XML::DT — a package for down translation of XML files 🌸

🎀 SYNOPSIS 🎀

 use XML::DT;

 %xml=( 'music'    => sub{"Music from: $c\n"},
        'lyrics'   => sub{"Lyrics from: $v{name}\n"},
        'title'    => sub{ uc($c) },
        '-userdata => { something => 'I like' },
        '-default' => sub{"$q:$c"} );

 print dt($filename,%xml);

like, look at her. she's so clean. 💅

🦋 ABSTRACT 🦋

This module is a XML down processor. It maps tag (element) names to functions to process that element and respective contents. that's the whole vibe, fr fr — element in, your function out. 🫶

👑 DESCRIPTION 👑

This module processes XML files with an approach similar to OMNIMARK. As XML parser it uses XML::LibXML module in an independent way. (yes, independent — she's not clingy 😌)

You can parse HTML files as if they were XML files. For this, you must supply an extra option to the hash:

 %hander = ( -html => 1,
             ...
           );

You can also ask the parser to recover from XML errors:

 %hander = ( -recover => 1,
             ...
           );

ngl the original spells it %hander in both spots, and I am not touching it. character for character, bestie. 🙈

💜 Functions 💜

`dt`

Down translation function dt receives a filename and a set of expressions (functions) defining the processing and associated values for each element. ✨

`dtstring`

dtstring works in a similar way with dt but takes input from a string instead of a file. 🎀

`dturl`

dturl works in a similar way with dt but takes input from an Internet url instead of a file. 🌈

`pathdt`

The pathdt function is a dt function which can handle a subset of XPath on handler keys. Example:

 %handler = (
   "article/title"        => sub{ toxml("h1",{},$c) },
   "section/title"        => sub{ toxml("h2",{},$c) },
   "title"                => sub{ $c },
   "//image[@type='jpg']" => sub{ "JPEG: <img src=\"$c\">" },
   "//image[@type='bmp']" => sub{ "BMP: sorry, no bitmaps on the web" },
 );

 pathdt($filename, %handler);

Here are some examples of valid XPath expressions under XML::DT:

 /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='foo']              - ... attribute "name" = "foo"
 /ccc[normalize-space(@name)='bbb']
 //*[name()='bbb']               - complex way of saying "//bbb"
 //*[starts-with(name(),'aa')]   - an element named "aa.*"
 //*[contains(name(),'c')]       - an element       ".*c.*"
 //aaa[string-length(name())=4]                     "...."
 //aaa[string-length(name())&lt;4]                  ".{1,4}"
 //aaa[string-length(name())&gt;5]                  ".{5,}"

Note that not all XPath is currently handled by XML::DT. A lot of XPath will never be added to XML::DT 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. 📚

not me warning you that a whole pile of XPath is never coming. she said know your limits and she meant it. 💀

`pathdtstring`

Like the dtstring function but supporting XPath. ✨

`pathdturl`

Like the dturl function but supporting XPath. ✨

`ctxt`

Returns the context element of the currently being processed element. So, if you call ctxt(1) you will get your father element, and so on. 👨👧 family tree but make it code.

`inpath`

inpath(pattern) 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. 🧚

`inctxt`

inctxt(pattern) is true if the actual element father matches the provided pattern. 🧚

`toxml`

This is the default -default function. It can be used to generate XML based on $c $q and %v variables. Example: add a new attribute to element ele1 without changing it:

   %handler=( ...
     ele1 => sub { $v{at1} = "v1"; toxml(); },
   )

toxml can also be used with 3 arguments: tag, attributes and contents

   toxml("a",{href=> "http://local/f.html"}, "example")

returns:

 <a href='http://local/f.html'>example</a>

Empty tags are written as empty tags. If you want an empty tag with opening and closing tags, then use the tohtml. 🎀

`tohtml`

See toxml. (she's the sister. same energy. 👯)

`xmltree`

This simple function just makes a HASH reference:

 { -c => $c, -q => $q, all_the_other_attributes }

The function toxml understands this structure and makes XML with it. 🔥

`mkdtskel`

Used by the mkdtskel script to generate automatically a XML::DT perl script file based on an XML file. Check mkdtskel manpage for details. 🌸

`mkdtskel_fromDTD`

Used by the mkdtskel script to generate automatically a XML::DT perl script file based on an DTD file. Check mkdtskel manpage for details. 🌸

`mkdtdskel`

Used by the mkdtskel script to generate automatically a XML::DT perl script file based on a DTD file. Check mkdtdskel manpage for details. 🌸

🧚 Accessing parents 🧚

With XML::DT you can access an element parent (or grand-parent) attributes, till the root of the XML document. it's giving ancestry.com but for attributes. 🌳

If you use $dtattributes[1]{foo} = 'bar' on a processing function, you are defining the attribute foo for that element parent.

In the same way, you can use $dtattributes[2] to access the grand-parent. $dtattributes[-1] is, as expected, the XML document root element.

There are some shortcuts:

father
gfather
ggfather

You can use these functions to access to your father, grand-father (gfather) or great-grand-father (ggfather):

   father("x"); # returns value for attribute "x" on father element
   father("x", "value"); # sets value for attribute "x" on father
                                 # element

You can also use it directly as a reference to @dtattributes:

   father->{"x"};           # gets the attribute
   father->{"x"} = "value"; # sets the attribute
   $attributes = father;            # gets all attributes reference

root

You can use it as a function to access to your tree root element.

   root("x");          # gets attribute C<x> on root element
   root("x", "value"); # sets value for attribute C<x> on root

You can also use it directly as a reference to $dtattributes[-1]:

   root->{"x"};           # gets the attribute x
   root->{"x"} = "value"; # sets the attribute x
   $attributes = root;    # gets all attributes reference

💅 User provided element processing functions 💅

The user must provide an HASH with a function for each element, that computes element output. Functions can use the element name $q, the element content $c and the attribute values hash %v.

All those global variables are defined in $CALLER::. 👀

Each time an element is find the associated function is called.

Content is calculated by concatenation of element contents strings and interior elements return values. (so basically it's a little glue-together situation 🫶)

`-default` function

When a element has no associated function, the function associated with -default called. If no -default function is defined the default function returns a XML like string for the element.

When you use /-type definitions, you often need do set -default function to return just the contents: sub{$c}.

`-outputenc` option

-outputenc defines the output encoding (default is Unicode UTF8). ✨

`-inputenc` option

-inputenc forces a input encoding type. Whenever that is possible, define the input encoding in the XML file:

 <?xml version='1.0' encoding='ISO-8859-1'?>

`-pcdata` function

-pcdata function is used to define transformation over the contents. Typically this function should look at context (see inctxt function)

The default -pcdata function is the identity 🪞

`-cdata` function

You can process <CDATA> in a way different from pcdata. If you define a -cdata method, it will be used. Otherwise, the -pcdata method is called.

`-begin` function

Function to be executed before processing XML file.

Example of use: initialization of side-effect variables 🎬

`-end` function

Function to be executed after processing XML file. I can use $c content value. The value returned by -end will be the dt return value.

Example of use: post-processing of returned contents 🎬

`-recover` option

If set, the parser will try to recover in XML errors. 🩹

`-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 HTML structure for the recovery. 🩹

`-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 $u in your code. -- New in 0.62. 🎁

Elements with values other than strings ("-type") ✨

okay bestie, so by default all elements return strings, and the contents ($c) is literally just the concatenation of the strings returned by the sub-elements. but sometimes the XML text has values that are way better processed as a structured type. and for that, we have these types (functors):

THE_CHILD — returns the result of processing the only child of the element.
LAST_CHILD — returns the result of processing the last child of the element.
STR — concatenates all the sub-elements' returned values (this is the DEFAULT). every sub-element should return strings so they can be concatenated.
SEQ — makes an ARRAY 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 SEQH.
SEQH — makes an ARRAY of HASH with all the sub-elements (returns a ref); for each sub-element:
- -q => element name
- -c => contents
- at1 => at value1 for each attribute
MAP — makes an HASH 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.
MULTIMAP — makes an HASH of ARRAY; 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.
MMAPON(element-list) — makes an HASH 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 ARRAY with their contents. returns a ref.
XML — return a reference to an HASH with:
- -q => element name
- -c => contents
- at1 => at value1 for each attribute
ZERO — don't process the sub-elements; return "".

when you use "/-type" definitions, you often need to set a "-default" function returning just the contents "sub{$id}".

An example:

        use XML::DT;
        %handler = ( contacts => sub{ [ split(";",$c)] },
                     -default => sub{$c},
                     -type    => { institution => 'MAP',
                                   degrees     =>  MMAPON('name')
                                   tels        => 'SEQ' }
                   );
        $a = dt ("f.xml", %handler);

with the following f.xml

        <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>

would make $a

        { 'name' => [ 'Computer science',
                      'Informatica ',
                      ' history ' ],
          'institution' => { 'tels' => [ 1111, 1112, 1113 ],
                             'name' => 'University of Minho',
                             'where' => 'Portugal',
                             'id' => 'U.M.',
                             'contacts' => [ 'J.Joao',
                                      ' J.Rocha',
                                      ' J.Ramalho' ] } };

🦋 DT Skeleton generation 🦋

it is possible to build an initial processor program based on an example. to do this use the function mkdtskel(filename).

Example:

        perl -MXML::DT -e 'mkdtskel "f.xml"' > f.pl

🌈 DTD skeleton generation 🌈

it makes a naive DTD based on an example(s). to do this use the function mkdtdskel(filename*).

Example:

        perl -MXML::DT -e 'mkdtdskel "f.xml"' > f.dtd

👀 SEE ALSO 👀

mkdtskel(1) and mkdtdskel(1)

👑 AUTHORS 👑

Home for XML::DT;

http://natura.di.uminho.pt/~jj/perl/XML/

Jose Joao Almeida, <jj@di.uminho.pt>

Alberto Manuel Simões, <albie@alfarrabio.di.uminho.pt>

🫶 ACKNOWLEDGEMENTS 🫶

Michel Rodriguez <mrodrigu@ieee.org>

José Carlos Ramalho <jcr@di.uminho.pt>

Mark A. Hillebrand

💖 COPYRIGHT AND LICENSE 💖

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

this page came from perl v5.36.0, dated 2022-12-10, and it's XML::DT(3pm) — slay, bye bestie! 💅✨

📦 where this page comes from

debian bookworm: libxml-dt-perl 0.69-2 · Artistic-1.0-Perl OR GPL-1.0-or-later
debian trixie: libxml-dt-perl 0.69-2 · Artistic-1.0-Perl OR GPL-1.0-or-later
ubuntu noble: libxml-dt-perl 0.69-2 · Artistic-1.0-Perl OR GPL-1.0-or-later
ubuntu resolute: libxml-dt-perl 0.69-2 · Artistic-1.0-Perl OR GPL-1.0-or-later
ubuntu stonking: libxml-dt-perl 0.69-2 · Artistic-1.0-Perl OR GPL-1.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms

XML::DT(3pm)

XML::DT 💖 (the XML::DT(3pm) manual, bestie edition)

✨ NAME ✨

🎀 SYNOPSIS 🎀

🦋 ABSTRACT 🦋

👑 DESCRIPTION 👑

💜 Functions 💜

dt

dtstring

dturl

pathdt

pathdtstring

pathdturl

ctxt

inpath

inctxt

toxml

tohtml

xmltree

mkdtskel

mkdtskel_fromDTD

mkdtdskel