]> matita.cs.unibo.it Git - helm.git/blob - helm/DEVEL/pxp/pxp/doc/manual/html/x1818.html
Initial revision
[helm.git] / helm / DEVEL / pxp / pxp / doc / manual / html / x1818.html
1 <HTML
2 ><HEAD
3 ><TITLE
4 >Invoking the parser</TITLE
5 ><META
6 NAME="GENERATOR"
7 CONTENT="Modular DocBook HTML Stylesheet Version 1.46"><LINK
8 REL="HOME"
9 TITLE="The PXP user's guide"
10 HREF="index.html"><LINK
11 REL="UP"
12 TITLE="Configuring and calling the parser"
13 HREF="c1567.html"><LINK
14 REL="PREVIOUS"
15 TITLE="The DTD classes"
16 HREF="x1812.html"><LINK
17 REL="NEXT"
18 TITLE="Updates"
19 HREF="x1965.html"><LINK
20 REL="STYLESHEET"
21 TYPE="text/css"
22 HREF="markup.css"></HEAD
23 ><BODY
24 CLASS="SECT1"
25 BGCOLOR="#FFFFFF"
26 TEXT="#000000"
27 LINK="#0000FF"
28 VLINK="#840084"
29 ALINK="#0000FF"
30 ><DIV
31 CLASS="NAVHEADER"
32 ><TABLE
33 WIDTH="100%"
34 BORDER="0"
35 CELLPADDING="0"
36 CELLSPACING="0"
37 ><TR
38 ><TH
39 COLSPAN="3"
40 ALIGN="center"
41 >The PXP user's guide</TH
42 ></TR
43 ><TR
44 ><TD
45 WIDTH="10%"
46 ALIGN="left"
47 VALIGN="bottom"
48 ><A
49 HREF="x1812.html"
50 >Prev</A
51 ></TD
52 ><TD
53 WIDTH="80%"
54 ALIGN="center"
55 VALIGN="bottom"
56 >Chapter 4. Configuring and calling the parser</TD
57 ><TD
58 WIDTH="10%"
59 ALIGN="right"
60 VALIGN="bottom"
61 ><A
62 HREF="x1965.html"
63 >Next</A
64 ></TD
65 ></TR
66 ></TABLE
67 ><HR
68 ALIGN="LEFT"
69 WIDTH="100%"></DIV
70 ><DIV
71 CLASS="SECT1"
72 ><H1
73 CLASS="SECT1"
74 ><A
75 NAME="AEN1818"
76 >4.4. Invoking the parser</A
77 ></H1
78 ><P
79 >Here a description of Pxp_yacc.</P
80 ><DIV
81 CLASS="SECT2"
82 ><H2
83 CLASS="SECT2"
84 ><A
85 NAME="AEN1821"
86 >4.4.1. Defaults</A
87 ></H2
88 ><P
89 >The following defaults are available:
90
91 <PRE
92 CLASS="PROGRAMLISTING"
93 >val default_config : config
94 val default_extension : ('a node extension) as 'a
95 val default_spec : ('a node extension as 'a) spec</PRE
96 ></P
97 ></DIV
98 ><DIV
99 CLASS="SECT2"
100 ><H2
101 CLASS="SECT2"
102 ><A
103 NAME="AEN1825"
104 >4.4.2. Parsing functions</A
105 ></H2
106 ><P
107 >In the following, the term "closed document" refers to
108 an XML structure like
109
110 <PRE
111 CLASS="PROGRAMLISTING"
112 >&lt;!DOCTYPE ... [ <TT
113 CLASS="REPLACEABLE"
114 ><I
115 >declarations</I
116 ></TT
117 > ] &gt;
118 &lt;<TT
119 CLASS="REPLACEABLE"
120 ><I
121 >root</I
122 ></TT
123 >&gt;
124 ...
125 &lt;/<TT
126 CLASS="REPLACEABLE"
127 ><I
128 >root</I
129 ></TT
130 >&gt;</PRE
131 >
132
133 The term "fragment" refers to an XML structure like
134
135 <PRE
136 CLASS="PROGRAMLISTING"
137 >&lt;<TT
138 CLASS="REPLACEABLE"
139 ><I
140 >root</I
141 ></TT
142 >&gt;
143 ...
144 &lt;/<TT
145 CLASS="REPLACEABLE"
146 ><I
147 >root</I
148 ></TT
149 >&gt;</PRE
150 >
151
152 i.e. only to one isolated element instance.</P
153 ><P
154 ><PRE
155 CLASS="PROGRAMLISTING"
156 >val parse_dtd_entity : config -&#62; source -&#62; dtd</PRE
157 >
158
159 Parses the declarations which are contained in the entity, and returns them as
160 <TT
161 CLASS="LITERAL"
162 >dtd</TT
163 > object.</P
164 ><P
165 ><PRE
166 CLASS="PROGRAMLISTING"
167 >val extract_dtd_from_document_entity : config -&#62; source -&#62; dtd</PRE
168 >
169
170 Extracts the DTD from a closed document. Both the internal and the external
171 subsets are extracted and combined to one <TT
172 CLASS="LITERAL"
173 >dtd</TT
174 > object. This
175 function does not parse the whole document, but only the parts that are
176 necessary to extract the DTD.</P
177 ><P
178 ><PRE
179 CLASS="PROGRAMLISTING"
180 >val parse_document_entity : 
181     ?transform_dtd:(dtd -&#62; dtd) -&#62;
182     ?id_index:('ext index) -&#62;
183     config -&#62; 
184     source -&#62; 
185     'ext spec -&#62; 
186         'ext document</PRE
187 >
188
189 Parses a closed document and validates it against the DTD that is contained in
190 the document (internal and external subsets). The option
191 <TT
192 CLASS="LITERAL"
193 >~transform_dtd</TT
194 > can be used to transform the DTD in the
195 document, and to use the transformed DTD for validation. If
196 <TT
197 CLASS="LITERAL"
198 >~id_index</TT
199 > is specified, an index of all ID attributes is
200 created.</P
201 ><P
202 ><PRE
203 CLASS="PROGRAMLISTING"
204 >val parse_wfdocument_entity : 
205     config -&#62; 
206     source -&#62; 
207     'ext spec -&#62; 
208         'ext document</PRE
209 >
210
211 Parses a closed document, but checks it only on well-formedness.</P
212 ><P
213 ><PRE
214 CLASS="PROGRAMLISTING"
215 >val parse_content_entity  : 
216     ?id_index:('ext index) -&#62;
217     config -&#62;  
218     source -&#62; 
219     dtd -&#62; 
220     'ext spec -&#62; 
221         'ext node</PRE
222 >
223
224 Parses a fragment, and validates the element.</P
225 ><P
226 ><PRE
227 CLASS="PROGRAMLISTING"
228 >val parse_wfcontent_entity : 
229     config -&#62; 
230     source -&#62; 
231     'ext spec -&#62; 
232         'ext node</PRE
233 >
234
235 Parses a fragment, but checks it only on well-formedness.</P
236 ></DIV
237 ><DIV
238 CLASS="SECT2"
239 ><H2
240 CLASS="SECT2"
241 ><A
242 NAME="AEN1851"
243 >4.4.3. Configuration options</A
244 ></H2
245 ><P
246 >&#13;<PRE
247 CLASS="PROGRAMLISTING"
248 >type config =
249     { warner : collect_warnings;
250       errors_with_line_numbers : bool;
251       enable_pinstr_nodes : bool;
252       enable_super_root_node : bool;
253       enable_comment_nodes : bool;
254       encoding : rep_encoding;
255       recognize_standalone_declaration : bool;
256       store_element_positions : bool;
257       idref_pass : bool;
258       validate_by_dfa : bool;
259       accept_only_deterministic_models : bool;
260       ...
261     }</PRE
262 >
263
264 <P
265 ></P
266 ><UL
267 COMPACT="COMPACT"
268 ><LI
269 STYLE="list-style-type: disc"
270 ><P
271 ><TT
272 CLASS="LITERAL"
273 >warner:</TT
274 >The parser prints
275 warnings by invoking the method <TT
276 CLASS="LITERAL"
277 >warn</TT
278 > for this warner
279 object. (Default: all warnings are dropped)</P
280 ></LI
281 ><LI
282 STYLE="list-style-type: disc"
283 ><P
284 ><TT
285 CLASS="LITERAL"
286 >errors_with_line_numbers:</TT
287 >If
288 true, errors contain line numbers; if false, errors contain only byte
289 positions. The latter mode is faster. (Default: true)</P
290 ></LI
291 ><LI
292 STYLE="list-style-type: disc"
293 ><P
294 ><TT
295 CLASS="LITERAL"
296 >enable_pinstr_nodes:</TT
297 >If true,
298 the parser creates extra nodes for processing instructions. If false,
299 processing instructions are simply added to the element or document surrounding
300 the instructions. (Default: false)</P
301 ></LI
302 ><LI
303 STYLE="list-style-type: disc"
304 ><P
305 ><TT
306 CLASS="LITERAL"
307 >enable_super_root_node:</TT
308 >If
309 true, the parser creates an extra node which is the parent of the root of the
310 document tree. This node is called super root; it is an element with type
311 <TT
312 CLASS="LITERAL"
313 >T_super_root</TT
314 >. - If there are processing instructions outside
315 the root element and outside the DTD, they are added to the super root instead
316 of the document. - If false, the super root node is not created. (Default:
317 false)</P
318 ></LI
319 ><LI
320 STYLE="list-style-type: disc"
321 ><P
322 ><TT
323 CLASS="LITERAL"
324 >enable_comment_nodes:</TT
325 >If true,
326 the parser creates nodes for comments with type <TT
327 CLASS="LITERAL"
328 >T_comment</TT
329 >;
330 if false, such nodes are not created. (Default: false)</P
331 ></LI
332 ><LI
333 STYLE="list-style-type: disc"
334 ><P
335 ><TT
336 CLASS="LITERAL"
337 >encoding:</TT
338 >Specifies the
339 internal encoding of the parser. Most strings are then represented according to
340 this encoding; however there are some exceptions (especially
341 <TT
342 CLASS="LITERAL"
343 >ext_id</TT
344 > values which are always UTF-8 encoded).
345 (Default: `Enc_iso88591)</P
346 ></LI
347 ><LI
348 STYLE="list-style-type: disc"
349 ><P
350 ><TT
351 CLASS="LITERAL"
352 >recognize_standalone_declaration:</TT
353 > If true and if the parser is
354 validating, the <TT
355 CLASS="LITERAL"
356 >standalone="yes"</TT
357 > declaration forces that it
358 is checked whether the document is a standalone document. - If false, or if the
359 parser is in well-formedness mode, such declarations are ignored.
360 (Default: true)</P
361 ></LI
362 ><LI
363 STYLE="list-style-type: disc"
364 ><P
365 ><TT
366 CLASS="LITERAL"
367 >store_element_positions:</TT
368 > If
369 true, for every non-data node the source position is stored. If false, the
370 position information is lost. If available, you can get the positions of nodes
371 by invoking the <TT
372 CLASS="LITERAL"
373 >position</TT
374 > method.
375 (Default: true)</P
376 ></LI
377 ><LI
378 STYLE="list-style-type: disc"
379 ><P
380 ><TT
381 CLASS="LITERAL"
382 >idref_pass:</TT
383 >If true and if
384 there is an ID index, the parser checks whether every IDREF or IDREFS attribute
385 refer to an existing node; this requires that the parser traverses the whole
386 doument tree. If false, this check is left out. (Default: false)</P
387 ></LI
388 ><LI
389 STYLE="list-style-type: disc"
390 ><P
391 ><TT
392 CLASS="LITERAL"
393 >validate_by_dfa:</TT
394 >If true and if
395 the content model for an element type is deterministic, a deterministic finite
396 automaton is used to validate whether the element contents match the content
397 model of the type. If false, or if a DFA is not available, a backtracking
398 algorithm is used for validation. (Default: true)</P
399 ></LI
400 ><LI
401 STYLE="list-style-type: disc"
402 ><P
403 ><TT
404 CLASS="LITERAL"
405 >accept_only_deterministic_models:</TT
406 > If true, only deterministic content
407 models are accepted; if false, any syntactically correct content models can be
408 processed. (Default: true)</P
409 ></LI
410 ></UL
411 ></P
412 ></DIV
413 ><DIV
414 CLASS="SECT2"
415 ><H2
416 CLASS="SECT2"
417 ><A
418 NAME="AEN1895"
419 >4.4.4. Which configuration should I use?</A
420 ></H2
421 ><P
422 >First, I recommend to vary the default configuration instead of
423 creating a new configuration record. For instance, to set
424 <TT
425 CLASS="LITERAL"
426 >idref_pass</TT
427 > to <TT
428 CLASS="LITERAL"
429 >true</TT
430 >, change the default
431 as in:
432 <PRE
433 CLASS="PROGRAMLISTING"
434 >let config = { default_config with idref_pass = true }</PRE
435 >
436 The background is that I can add more options to the record in future versions
437 of the parser without breaking your programs.</P
438 ><DIV
439 CLASS="FORMALPARA"
440 ><P
441 ><B
442 >Do I need extra nodes for processing instructions? </B
443 >By default, such nodes are not created. This does not mean that the
444 processing instructions are lost; however, you cannot find out the exact
445 location where they occur. For example, the following XML text
446
447 <PRE
448 CLASS="PROGRAMLISTING"
449 >&#60;x&#62;&#60;?pi1?&#62;&#60;y/&#62;&#60;?pi2?&#62;&#60;/x&#62; </PRE
450
451
452 will normally create one element node for <TT
453 CLASS="LITERAL"
454 >x</TT
455 > containing
456 <I
457 CLASS="EMPHASIS"
458 >one</I
459 > subnode for <TT
460 CLASS="LITERAL"
461 >y</TT
462 >. The processing
463 instructions are attached to <TT
464 CLASS="LITERAL"
465 >x</TT
466 > in a separate hash table; you
467 can access them using <TT
468 CLASS="LITERAL"
469 >x # pinstr "pi1"</TT
470 > and <TT
471 CLASS="LITERAL"
472 >x #
473 pinstr "pi2"</TT
474 >, respectively. The information is lost where the
475 instructions occur within <TT
476 CLASS="LITERAL"
477 >x</TT
478 >.</P
479 ></DIV
480 ><P
481 >If the option <TT
482 CLASS="LITERAL"
483 >enable_pinstr_nodes</TT
484 > is
485 turned on, the parser creates extra nodes <TT
486 CLASS="LITERAL"
487 >pi1</TT
488 > and
489 <TT
490 CLASS="LITERAL"
491 >pi2</TT
492 > such that the subnodes of <TT
493 CLASS="LITERAL"
494 >x</TT
495 > are now: 
496
497 <PRE
498 CLASS="PROGRAMLISTING"
499 >x # sub_nodes = [ pi1; y; pi2 ]</PRE
500 >
501
502 The extra nodes contain the processing instructions in the usual way, i.e. you
503 can access them using <TT
504 CLASS="LITERAL"
505 >pi1 # pinstr "pi1"</TT
506 > and <TT
507 CLASS="LITERAL"
508 >pi2 #
509 pinstr "pi2"</TT
510 >, respectively.</P
511 ><P
512 >Note that you will need an exemplar for the PI nodes (see
513 <TT
514 CLASS="LITERAL"
515 >make_spec_from_alist</TT
516 >).</P
517 ><DIV
518 CLASS="FORMALPARA"
519 ><P
520 ><B
521 >Do I need a super root node? </B
522 >By default, there is no super root node. The
523 <TT
524 CLASS="LITERAL"
525 >document</TT
526 > object refers directly to the node representing the
527 root element of the document, i.e.
528
529 <PRE
530 CLASS="PROGRAMLISTING"
531 >doc # root = r</PRE
532 >
533
534 if <TT
535 CLASS="LITERAL"
536 >r</TT
537 > is the root node. This is sometimes inconvenient: (1)
538 Some algorithms become simpler if every node has a parent, even the root
539 node. (2) Some standards such as XPath call the "root node" the node whose
540 child represents the root of the document. (3) The super root node can serve
541 as a container for processing instructions outside the root element. Because of
542 these reasons, it is possible to create an extra super root node, whose child
543 is the root node:
544
545 <PRE
546 CLASS="PROGRAMLISTING"
547 >doc # root = sr         &#38;&#38;
548 sr # sub_nodes = [ r ]</PRE
549 >
550
551 When extra nodes are also created for processing instructions, these nodes can
552 be added to the super root node if they occur outside the root element (reason
553 (3)), and the order reflects the order in the source text.</P
554 ></DIV
555 ><P
556 >Note that you will need an exemplar for the super root node
557 (see <TT
558 CLASS="LITERAL"
559 >make_spec_from_alist</TT
560 >).</P
561 ><DIV
562 CLASS="FORMALPARA"
563 ><P
564 ><B
565 >What is the effect of the UTF-8 encoding? </B
566 >By default, the parser represents strings (with few
567 exceptions) as ISO-8859-1 strings. These are well-known, and there are tools
568 and fonts for this encoding.</P
569 ></DIV
570 ><P
571 >However, internationalization may require that you switch over
572 to UTF-8 encoding. In most environments, the immediate effect will be that you
573 cannot read strings with character codes &#62;= 160 any longer; your terminal will
574 only show funny glyph combinations. It is strongly recommended to install
575 Unicode fonts (<A
576 HREF="http://czyborra.com/unifont/"
577 TARGET="_top"
578 >GNU Unifont</A
579 >, 
580 <A
581 HREF="http://www.cl.cam.ac.uk/~mgk25/download/ucs-fonts.tar.gz"
582 TARGET="_top"
583 >Markus Kuhn's fonts</A
584 >) and <A
585 HREF="http://myweb.clark.net/pub/dickey/xterm/xterm.html"
586 TARGET="_top"
587 >terminal emulators
588 that can handle UTF-8 byte sequences</A
589 >. Furthermore, a Unicode editor may
590 be helpful (such as <A
591 HREF="ftp://metalab.unc.edu/pub/Linux/apps/editors/X/"
592 TARGET="_top"
593 >Yudit</A
594 >). There are
595 also <A
596 HREF="http://www.cl.cam.ac.uk/~mgk25/unicode.html"
597 TARGET="_top"
598 >FAQ</A
599 > by
600 Markus Kuhn.</P
601 ><P
602 >By setting <TT
603 CLASS="LITERAL"
604 >encoding</TT
605 > to
606 <TT
607 CLASS="LITERAL"
608 >`Enc_utf8</TT
609 > all strings originating from the parsed XML
610 document are represented as UTF-8 strings. This includes not only character
611 data and attribute values but also element names, attribute names and so on, as
612 it is possible to use any Unicode letter to form such names.  Strictly
613 speaking, PXP is only XML-compliant if the UTF-8 mode is used; otherwise it
614 will have difficulties when validating documents containing
615 non-ISO-8859-1-names.</P
616 ><P
617 >This mode does not have any impact on the external
618 representation of documents. The character set assumed when reading a document
619 is set in the XML declaration, and character set when writing a document must
620 be passed to the <TT
621 CLASS="LITERAL"
622 >write</TT
623 > method.</P
624 ><DIV
625 CLASS="FORMALPARA"
626 ><P
627 ><B
628 >How do I check that nodes exist which are referred by IDREF attributes? </B
629 >First, you must create an index of all occurring ID
630 attributes:
631
632 <PRE
633 CLASS="PROGRAMLISTING"
634 >let index = new hash_index</PRE
635 >
636
637 This index must be passed to the parsing function:
638
639 <PRE
640 CLASS="PROGRAMLISTING"
641 >parse_document_entity
642   ~id_index:(index :&#62; index)
643   config source spec</PRE
644 >
645
646 Next, you must turn on the <TT
647 CLASS="LITERAL"
648 >idref_pass</TT
649 > mode:
650
651 <PRE
652 CLASS="PROGRAMLISTING"
653 >let config = { default_config with idref_pass = true }</PRE
654 >
655
656 Note that now the whole document tree will be traversed, and every node will be
657 checked for IDREF and IDREFS attributes. If the tree is big, this may take some
658 time.</P
659 ></DIV
660 ><DIV
661 CLASS="FORMALPARA"
662 ><P
663 ><B
664 >What are deterministic content models? </B
665 >These type of models can speed up the validation checks;
666 furthermore they ensure SGML-compatibility. In particular, a content model is
667 deterministic if the parser can determine the actually used alternative by
668 inspecting only the current token. For example, this element has
669 non-deterministic contents:
670
671 <PRE
672 CLASS="PROGRAMLISTING"
673 >&#60;!ELEMENT x ((u,v) | (u,y+) | v)&#62;</PRE
674 >
675
676 If the first element in <TT
677 CLASS="LITERAL"
678 >x</TT
679 > is <TT
680 CLASS="LITERAL"
681 >u</TT
682 >, the
683 parser does not know which of the alternatives <TT
684 CLASS="LITERAL"
685 >(u,v)</TT
686 > or
687 <TT
688 CLASS="LITERAL"
689 >(u,y+)</TT
690 > will work; the parser must also inspect the second
691 element to be able to distinguish between the alternatives. Because such
692 look-ahead (or "guessing") is required, this example is
693 non-deterministic.</P
694 ></DIV
695 ><P
696 >The XML standard demands that content models must be
697 deterministic. So it is recommended to turn the option
698 <TT
699 CLASS="LITERAL"
700 >accept_only_deterministic_models</TT
701 > on; however, PXP can also
702 process non-deterministic models using a backtracking algorithm.</P
703 ><P
704 >Deterministic models ensure that validation can be performed in
705 linear time. In order to get the maximum benefits, PXP also implements a
706 special validator that profits from deterministic models; this is the
707 deterministic finite automaton (DFA). This validator is enabled per element
708 type if the element type has a deterministic model and if the option
709 <TT
710 CLASS="LITERAL"
711 >validate_by_dfa</TT
712 > is turned on.</P
713 ><P
714 >In general, I expect that the DFA method is faster than the
715 backtracking method; especially in the worst case the DFA takes only linear
716 time. However, if the content model has only few alternatives and the
717 alternatives do not nest, the backtracking algorithm may be better.</P
718 ></DIV
719 ></DIV
720 ><DIV
721 CLASS="NAVFOOTER"
722 ><HR
723 ALIGN="LEFT"
724 WIDTH="100%"><TABLE
725 WIDTH="100%"
726 BORDER="0"
727 CELLPADDING="0"
728 CELLSPACING="0"
729 ><TR
730 ><TD
731 WIDTH="33%"
732 ALIGN="left"
733 VALIGN="top"
734 ><A
735 HREF="x1812.html"
736 >Prev</A
737 ></TD
738 ><TD
739 WIDTH="34%"
740 ALIGN="center"
741 VALIGN="top"
742 ><A
743 HREF="index.html"
744 >Home</A
745 ></TD
746 ><TD
747 WIDTH="33%"
748 ALIGN="right"
749 VALIGN="top"
750 ><A
751 HREF="x1965.html"
752 >Next</A
753 ></TD
754 ></TR
755 ><TR
756 ><TD
757 WIDTH="33%"
758 ALIGN="left"
759 VALIGN="top"
760 >The DTD classes</TD
761 ><TD
762 WIDTH="34%"
763 ALIGN="center"
764 VALIGN="top"
765 ><A
766 HREF="c1567.html"
767 >Up</A
768 ></TD
769 ><TD
770 WIDTH="33%"
771 ALIGN="right"
772 VALIGN="top"
773 >Updates</TD
774 ></TR
775 ></TABLE
776 ></DIV
777 ></BODY
778 ></HTML
779 >