Debian Codegraph @

README

raw
1 =head1 XML::DT a Perl XML down translate module
2
3 With XML::DT, I think that:
4
5 . it is simple to do simple XML processing tasks :)
6 . it is simple to have the XML processor stored in a single variable
7 (see example 4)
8 . it is simple to translate XML -> Perl user controlled complex structure
9 with a compact "-type" definition (see last section)
10
11 Feedback welcome -> [email protected]
12
13 =head1 XML::DT a Perl XML down translate module
14
15 This document is also available in HTML (pod2html'ized):
16 http://www.di.uminho.pt/~jj/perl/XML/XML-DT.readme.html
17
18 . design to do simple and compact translation/processing of XML document
19 . it includes some features of omnimark and sgmls.pm; functional approach
20 . it includes functions to automatic build user controlled complex Perl
21 structures (see "working with structures" section)
22 . it was build to show my NLP Perl students that it is easy to work with XML
23 . home page and download: http://www.di.uminho.pt/~jj/perl/XML/DT.html
24
25 =head1 HOW IT WORKS:
26
27 . the user must define a handler and call the basic function :
28 dt($filename,%handler) or dtstring($string,%handler)
29 . the handler is a HASH mapping element names to functions. Handlers can
30 have a "-default" function , and a "-end" function
31 . in order to make it smaller each function receives 3 args as global variables
32 $c - contents
33 $q - element name
34 %v - attribute values
35 . the default "-default" function is the identity. The function "toxml" makes
36 the original XML text based on $c, $q and %v values.
37 . see some advanced features in the last examples
38
39 =head1 SOME simple (naive) examples:
40
41 INDEX:
42 1. change to lowercase attribute named "a" in element "e"
43 2. better solution
44 3. make some statistics and output results in HTML (using side effects)
45 4. In a HTML like XML document, substitute <contents/>...<contents> by the
46 real table of contents (a dirty solution...)
47 5. a more realistic example: from XML gcapaper DTD to latex
48
49 WORKING WITH STRUCTURES INSTEAD OF STRINGS...
50
51 6. Build the natural Perl structure of the following document (ARRAY,HASH)
52 7. Multi map on...
53
54 =head2 1. change to lowercase the contents of the attribute named "a" in element "e"
55
56 use XML::DT ;
57 my $filename = shift;
58
59 print dt($filename,
60 ( e => sub{ "<e a='". lc($v{a}). "'>$c</e>" }));
61
62 =head2 2. A better solution of the previous example
63
64 Ex.1 wouldn't work if we have more attributes in element e.
65 A better solution is
66
67 print dt($filename,
68 ( e => sub{ $v{a} = lc($v{a});
69 toxml();}));
70
71 =head2 3. make some statistics and output results in HTML (using side effects)
72
73 use XML::DT ;
74 my $filename = shift;
75
76 %handler=( -default => sub{$elem_counter++;
77 $elem_table{$q}++;"";} # $q -> element name
78 );
79
80 dt($filename,%handler);
81
82 print "<H3>We have found $elem_counter elements in document</H3>";
83 print "<TABLE><TH>ELEMENT<TH>OCCURS\n";
84 foreach $elem (sort keys %elem_table)
85 {print "<TR><TD>$elem<TD>$elem_table{$elem}\n";}
86 print "</TABLE>";
87
88 =head2 4. In a HTML like XML document, substitute <contents/>...<contents> by the real table of contents (a dirty solution...)
89
90 %handler=( h1 => sub{ $index .= "\n$c"; toxml();},
91 h2 => sub{ $index .= "\n\t$c"; toxml();},
92 h3 => sub{ $index .= "\n\t\t$c"; toxml();},
93 contents => sub{ $c="__CLEAN__"; toxml();},
94 -end => sub{ $c =~ s/__CLEAN__/$index/; $c});
95
96 print dt($filename,%handler)
97
98 =head2 5. a more realistic example: from XML gcapaper DTD to latex
99
100 notes:
101
102 . "TITLE" is processed in context dependent way!
103 . output in ISOLATIN1 (this is dirty but my LaTeX doesn't support UNICODE)
104 . a stack of authors was necessary because LaTeX structure was different
105 from input structure...
106 . this example was partially created by the function mkdtskel
107 Perl -MXML::DT -e 'mkdtskel "f.xml"' > f.pl
108 and took me about one hour to tune to real LaTeX/XML example.
109
110 NAME gcapaper2tex.pl - a Perl script to translate XML gcapaper DTD to latex
111
112 SYNOPSIS gcapaper2tex.pl mypaper.xml > mupaper.tex
113
114 use XML::DT ;
115 my $filename = shift;
116 my $beginLatex = '\documentclass{article} \begin{document} ';
117 my $endLatex = '\end{document}';
118
119 %handler=(
120 '-outputenc' => 'ISO-8859-1',
121 '-default' => sub{"$c"},
122 'RANDLIST' => sub{"\\begin{itemize}$c\\end{itemize}"},
123 'AFFIL' => sub{""}, # delete affiliation
124 'TITLE' => sub{
125 if(inctxt('SECTION')){"\\section{$c}"}
126 elsif(inctxt('SUBSEC1')){"\\subsection{$c}"}
127 else {"\\title{$c}"}
128 },
129 'GCAPAPER' => sub{"$beginLatex $c $endLatex"},
130 'PARA' => sub{"$c\n\n"},
131 'ADDRESS' => sub{"\\thanks{$c}"},
132 'PUB' => sub{"} $c"},
133 'EMAIL' => sub{"(\\texttt{$c}) "},
134 'FRONT' => sub{"$c\n"},
135 'AUTHOR' => sub{ push @aut, $c ; ""},
136 'ABSTRACT' => sub{
137 sprintf('\author{%s}\maketitle\begin{abstract}%s\end{abstract}',
138 join ('\and', @aut) ,
139 $c) },
140 'CODE.BLOCK' => sub{"\\begin{verbatim}\n$c\\end{verbatim}\n"},
141 'XREF' => sub{"\\cite{$v{REFLOC}}"},
142 'LI' => sub{"\\item $c"},
143 'BIBLIOG' =>sub{"\\begin{thebibliography}{1}$c\\end{thebibliography}\n"},
144 'HIGHLIGHT' => sub{" \\emph{$c} "},
145 'BIO' => sub{""}, #delete biography
146 'SURNAME' => sub{" $c "},
147 'CODE' => sub{"\\verb!$c!"},
148 'BIBITEM' => sub{"\n\\bibitem{$c"},
149 );
150 print dt($filename,%handler);
151
152 =head1 WORKING WITH STRUCTURES INSTEAD OF STRINGS...
153
154 the "-type" definition defines the way to build structures in each case:
155
156 . "HASH" or "MAP" -> make an hash with the sub-elements;
157 keys are the sub-element names; warn on repetitions;
158 returns the hash reference.
159 . "ARRAY" or "SEQ" -> make an ARRAY with the sub-elements
160 returns an array reference.
161 . "MULTIMAP" -> makes an HASH of ARRAY; keys are the sub-element
162 . MMAPON(name1, ...) -> similar to HASH but accepts repetitions of
163 the sub-elements "name1"... (and makes an array with them)
164 . STR ->(DEFAULT) concatenates all the sub-elements returned values
165 all the sub-element should return strings to be concatenated
166
167
168 =head2 6. Build the natural Perl structure of the following document
169
170 <institution>
171 <id>U.M.</id>
172 <name>University of Minho</name>
173 <tels>
174 <item>1111</item>
175 <item>1112</item>
176 <item>1113</item>
177 </tels>
178 <where>Portugal</where>
179 <contacts>J.Joao; J.Rocha; J.Ramalho</contacts>
180 </institution>
181
182 use XML::DT;
183 %handler = ( -default => sub{$c},
184 -type => { institution => 'HASH',
185 tels => 'ARRAY' },
186 contacts => sub{ [ split(";",$c)] },
187 );
188
189 $a = dt("ex10.2.xml", %handler);
190
191
192 $a is a reference to an HASH:
193
194 { 'tels' => [ 1111, 1112, 1113 ],
195 'name' => 'University of Minho',
196 'where' => 'Portugal',
197 'id' => 'U.M.',
198 'contacts' => [ 'J.Joao', ' J.Rocha', ' J.Ramalho' ] };
199
200 =head2 7. Christmas card...
201
202 We have the following address book:
203
204 <people>
205 <person>
206 <name> name0 </name>
207 <address> address00 </address>
208 <address> address01 </address>
209 </person>
210 <person>
211 <name> name1 </name>
212 <address> address10 </address>
213 <address> address11 </address>
214 </person>
215 </people>
216
217 Now we are going to build a structure to store the address book and write a
218 Christmas card to the first address of everyone
219
220 #!/usr/bin/perl
221 use XML::DT;
222 %handler = ( -default => sub{$c},
223 person => sub{ mkchristmascard($c); $c},
224 -type => { people => 'ARRAY',
225 person => MMAPON('address')});
226
227 $people = dt("ex11.1.xml", %handler);
228
229 print $people->[0]{address}[1]; # prints address01
230
231 sub mkchristmascard{ my $x=shift;
232 open(A,"|lpr") or die;
233 print A <<".";
234 $x->{name}
235 $x->{address}[0]
236
237 Dear $x->{name}
238 Merry Christmas from Braga Perl mongers\n
239 .
240
241 close A;
242 }