XML::DT - a package for down translation of XML to strings

- NAME
- SYNOPSIS
- DESCRIPTION
  - `inctxt` function
  - User provided element processing functions
  - `-default` function
  - `-outputenc` option
  - `-inputenc` option
  - `-pcdata` function
  - `-begin` function
  - `-end` function
  - `toxml` function
- Elements with values other than strings (C<-type))
  - An example:
- Skeleton generation
- BUGS
- Author
- NAME
- SYNOPSIS
- Bugs

# NAME

        XML::DT - a package for down translation of XML to strings

# SYNOPSIS

        use XML::DT;

        %xml=( 'music'    => sub{"Music from: $c\n"},
               'lyrics'   => sub{"Lyrics from:$c\n (the value of attribute
                                   IN is:$v{IN}\n)"},
               'title'    => sub{ uc($c) },
               '-default' => sub{"$q:$c"},
               '-outputenc' => 'ISO-8859-1');

        print dt($filename,%xml);

        print dtstring("<arq>
                        <title>Vejam Bem</title>
                        <music>Zeca Afonso</music>
                        </arq>",%xml);

        inctxt('music/lyrics')
        inctxt('music.*')

# DESCRIPTION

This module processes XML files with an approach similar to OMNIMARK.

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

`dtstring` is similar but takes input from a string instead of a file.

## `inctxt` function

`inctxt(pattern)` is true if the actual element path matches the provided pattern. This function is ment to be used in the element functions in order to achive context dependent processing.

## 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 atribute values hash `%v`.

All those global variables are defined in `$main::`.

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

## `-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 tranformation 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: inicialization of sife-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

## `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(); },
               )

# Elements with values other than strings (C<-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:

         MAP  -> makes an HASH with the sub elements; keys are the sub-element
              names (returns a ref)
         SEQ  -> makes an ARRAY with all the sub elements (returns a ref)
         MULTIMAP -> makes an HASH of ARRAY; keys are the sub-element
         STR  -> concatenates all the subelements returned values (DEFAULT)
              all the subelement sould return strings to be concatenated
         MMAPON(elementlist) -> makes an HASH with the subelements; tor elements
              contained in the elementelist, ARRAYs are created;
              keys are the sub-element

## 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>informatic </name>
         <name> history </name>
        </degrees>

would make `$a`

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

# 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

# BUGS

The global variables `$q %v $c` are defined in main. So you may have to write `$::c` ... if you are outside main.

# Author

Jose Joao, jj@di.uminho.pt

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

# NAME

`lat1.pm` - module for unicode utf8 to latin1 translation

# SYNOPSIS

       $latin1string = lat1::utf8($utf8string)

# Bugs

Translating the laint1 subset of unicode utf8 is very simples and needs no tables.

If you need more complex translation, see the perl modules about unicode and the `recode` command.