Provided by: libxml-dt-perl_0.3-1.1_all bug

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) },
          '-default' => sub{"$q:$c"} );

       print dt($filename,%xml);

ABSTRACT

       This module is a XML down processor. It maps tag (element) names to functions to process
       that element and respective contents.

DESCRIPTION

       This module processes XML files with an approach similar to OMNIMARK. As XML parser it
       uses XML::Parser or XML::LibXML module in an independent way. At configure stage, you
       should choose one of the back-ends.

       If you use XML::LibXML module as backend, 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,
             ...
           );

       "dt" function

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

       "dtstring" function

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

       "dturl" function

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

       "pathdt" function

       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

       "pathdtstring" function

       Like the "dtstring" function but supporting XPath.

       "pathdturl" function

       Like the "dturl" function but supporting XPath.

       "inctxt" function

       "inctxt(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.

       "toxml" function

       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>

       "xmltree" function

       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.

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.

       "-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{$id}".

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

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

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

       By default all elements return strings, and contents ($c) is the concatenation of the
       strings returned by the sub-elements.

       In some situations the XML text contains values that are better processed as a structured
       type.

       The following types (functors) are available:

       STR concatenates all the sub-elements returned values (DEFAULT) all the sub-element should
           return strings to 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 do set "-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 Simo~es, <albie@alfarrabio.di.uminho.pt>

       thanks to

       Michel Rodriguez    <mrodrigu@ieee.org> Jose Carlos Ramalho <jcr@di.uminho.pt> Mark A.
       Hillebrand