--- /dev/null
+<HTML
+><HEAD
+><TITLE
+>Configuring and calling the parser</TITLE
+><META
+NAME="GENERATOR"
+CONTENT="Modular DocBook HTML Stylesheet Version 1.46"><LINK
+REL="HOME"
+TITLE="The PXP user's guide"
+HREF="index.html"><LINK
+REL="UP"
+TITLE="User's guide"
+HREF="p34.html"><LINK
+REL="PREVIOUS"
+TITLE="Details of the mapping from XML text to the tree representation"
+HREF="x1496.html"><LINK
+REL="NEXT"
+TITLE="Resolvers and sources"
+HREF="x1629.html"><LINK
+REL="STYLESHEET"
+TYPE="text/css"
+HREF="markup.css"></HEAD
+><BODY
+CLASS="CHAPTER"
+BGCOLOR="#FFFFFF"
+TEXT="#000000"
+LINK="#0000FF"
+VLINK="#840084"
+ALINK="#0000FF"
+><DIV
+CLASS="NAVHEADER"
+><TABLE
+WIDTH="100%"
+BORDER="0"
+CELLPADDING="0"
+CELLSPACING="0"
+><TR
+><TH
+COLSPAN="3"
+ALIGN="center"
+>The PXP user's guide</TH
+></TR
+><TR
+><TD
+WIDTH="10%"
+ALIGN="left"
+VALIGN="bottom"
+><A
+HREF="x1496.html"
+>Prev</A
+></TD
+><TD
+WIDTH="80%"
+ALIGN="center"
+VALIGN="bottom"
+></TD
+><TD
+WIDTH="10%"
+ALIGN="right"
+VALIGN="bottom"
+><A
+HREF="x1629.html"
+>Next</A
+></TD
+></TR
+></TABLE
+><HR
+ALIGN="LEFT"
+WIDTH="100%"></DIV
+><DIV
+CLASS="CHAPTER"
+><H1
+><A
+NAME="AEN1567"
+>Chapter 4. Configuring and calling the parser</A
+></H1
+><DIV
+CLASS="TOC"
+><DL
+><DT
+><B
+>Table of Contents</B
+></DT
+><DT
+>4.1. <A
+HREF="c1567.html#AEN1569"
+>Overview</A
+></DT
+><DT
+>4.2. <A
+HREF="x1629.html"
+>Resolvers and sources</A
+></DT
+><DT
+>4.3. <A
+HREF="x1812.html"
+>The DTD classes</A
+></DT
+><DT
+>4.4. <A
+HREF="x1818.html"
+>Invoking the parser</A
+></DT
+><DT
+>4.5. <A
+HREF="x1965.html"
+>Updates</A
+></DT
+></DL
+></DIV
+><DIV
+CLASS="SECT1"
+><H1
+CLASS="SECT1"
+><A
+NAME="AEN1569"
+>4.1. Overview</A
+></H1
+><P
+>There are the following main functions invoking the parser (in Pxp_yacc):
+
+ <P
+></P
+><UL
+COMPACT="COMPACT"
+><LI
+STYLE="list-style-type: disc"
+><P
+><I
+CLASS="EMPHASIS"
+>parse_document_entity:</I
+> You want to
+parse a complete and closed document consisting of a DTD and the document body;
+the body is validated against the DTD. This mode is interesting if you have a
+file
+
+<PRE
+CLASS="PROGRAMLISTING"
+><!DOCTYPE root ... [ ... ] > <root> ... </root></PRE
+>
+
+and you can accept any DTD that is included in the file (e.g. because the file
+is under your control).</P
+></LI
+><LI
+STYLE="list-style-type: disc"
+><P
+><I
+CLASS="EMPHASIS"
+>parse_wfdocument_entity:</I
+> You want to
+parse a complete and closed document consisting of a DTD and the document body;
+but the body is not validated, only checked for well-formedness. This mode is
+preferred if validation costs too much time or if the DTD is missing.</P
+></LI
+><LI
+STYLE="list-style-type: disc"
+><P
+><I
+CLASS="EMPHASIS"
+>parse_dtd_entity:</I
+> You want only to
+parse an entity (file) containing the external subset of a DTD. Sometimes it is
+interesting to read such a DTD, for example to compare it with the DTD included
+in a document, or to apply the next mode:</P
+></LI
+><LI
+STYLE="list-style-type: disc"
+><P
+><I
+CLASS="EMPHASIS"
+>parse_content_entity:</I
+> You want only to
+parse an entity (file) containing a fragment of a document body; this fragment
+is validated against the DTD you pass to the function. Especially, the fragment
+must not have a <TT
+CLASS="LITERAL"
+> <!DOCTYPE></TT
+> clause, and must directly
+begin with an element. The element is validated against the DTD. This mode is
+interesting if you want to check documents against a fixed, immutable DTD.</P
+></LI
+><LI
+STYLE="list-style-type: disc"
+><P
+><I
+CLASS="EMPHASIS"
+>parse_wfcontent_entity:</I
+> This function
+also parses a single element without DTD, but does not validate it.</P
+></LI
+><LI
+STYLE="list-style-type: disc"
+><P
+><I
+CLASS="EMPHASIS"
+>extract_dtd_from_document_entity:</I
+> This
+function extracts the DTD from a closed document consisting of a DTD and a
+document body. Both the internal and the external subsets are extracted.</P
+></LI
+></UL
+></P
+><P
+>In many cases, <TT
+CLASS="LITERAL"
+>parse_document_entity</TT
+> is the preferred mode
+to parse a document in a validating way, and
+<TT
+CLASS="LITERAL"
+>parse_wfdocument_entity</TT
+> is the mode of choice to parse a
+file while only checking for well-formedness.</P
+><P
+>There are a number of variations of these modes. One important application of a
+parser is to check documents of an untrusted source against a fixed DTD. One
+solution is to not allow the <TT
+CLASS="LITERAL"
+><!DOCTYPE></TT
+> clause in
+these documents, and treat the document like a fragment (using mode
+<I
+CLASS="EMPHASIS"
+>parse_content_entity</I
+>). This is very simple, but
+inflexible; users of such a system cannot even define additional entities to
+abbreviate frequent phrases of their text.</P
+><P
+>It may be necessary to have a more intelligent checker. For example, it is also
+possible to parse the document to check fully, i.e. with DTD, and to compare
+this DTD with the prescribed one. In order to fully parse the document, mode
+<I
+CLASS="EMPHASIS"
+>parse_document_entity</I
+> is applied, and to get the DTD to
+compare with mode <I
+CLASS="EMPHASIS"
+>parse_dtd_entity</I
+> can be used.</P
+><P
+>There is another very important configurable aspect of the parser: the
+so-called resolver. The task of the resolver is to locate the contents of an
+(external) entity for a given entity name, and to make the contents accessible
+as a character stream. (Furthermore, it also normalizes the character set;
+but this is a detail we can ignore here.) Consider you have a file called
+<TT
+CLASS="LITERAL"
+>"main.xml"</TT
+> containing
+
+<PRE
+CLASS="PROGRAMLISTING"
+><!ENTITY % sub SYSTEM "sub/sub.xml">
+%sub;</PRE
+>
+
+and a file stored in the subdirectory <TT
+CLASS="LITERAL"
+>"sub"</TT
+> with name
+<TT
+CLASS="LITERAL"
+>"sub.xml"</TT
+> containing
+
+<PRE
+CLASS="PROGRAMLISTING"
+><!ENTITY % subsub SYSTEM "subsub/subsub.xml">
+%subsub;</PRE
+>
+
+and a file stored in the subdirectory <TT
+CLASS="LITERAL"
+>"subsub"</TT
+> of
+<TT
+CLASS="LITERAL"
+>"sub"</TT
+> with name <TT
+CLASS="LITERAL"
+>"subsub.xml"</TT
+> (the
+contents of this file do not matter). Here, the resolver must track that
+the second entity <TT
+CLASS="LITERAL"
+>subsub</TT
+> is located in the directory
+<TT
+CLASS="LITERAL"
+>"sub/subsub"</TT
+>, i.e. the difficulty is to interpret the
+system (file) names of entities relative to the entities containing them,
+even if the entities are deeply nested.</P
+><P
+>There is not a fixed resolver already doing everything right - resolving entity
+names is a task that highly depends on the environment. The XML specification
+only demands that <TT
+CLASS="LITERAL"
+>SYSTEM</TT
+> entities are interpreted like URLs
+(which is not very precise, as there are lots of URL schemes in use), hoping
+that this helps overcoming the local peculiarities of the environment; the idea
+is that if you do not know your environment you can refer to other entities by
+denoting URLs for them. I think that this interpretation of
+<TT
+CLASS="LITERAL"
+>SYSTEM</TT
+> names may have some applications in the internet, but
+it is not the first choice in general. Because of this, the resolver is a
+separate module of the parser that can be exchanged by another one if
+necessary; more precisely, the parser already defines several resolvers.</P
+><P
+>The following resolvers do already exist:
+
+ <P
+></P
+><UL
+COMPACT="COMPACT"
+><LI
+STYLE="list-style-type: disc"
+><P
+>Resolvers reading from arbitrary input channels. These
+can be configured such that a certain ID is associated with the channel; in
+this case inner references to external entities can be resolved. There is also
+a special resolver that interprets SYSTEM IDs as URLs; this resolver can
+process relative SYSTEM names and determine the corresponding absolute URL.</P
+></LI
+><LI
+STYLE="list-style-type: disc"
+><P
+>A resolver that reads always from a given O'Caml
+string. This resolver is not able to resolve further names unless the string is
+not associated with any name, i.e. if the document contained in the string
+refers to an external entity, this reference cannot be followed in this
+case.</P
+></LI
+><LI
+STYLE="list-style-type: disc"
+><P
+>A resolver for file names. The <TT
+CLASS="LITERAL"
+>SYSTEM</TT
+>
+name is interpreted as file URL with the slash "/" as separator for
+directories. - This resolver is derived from the generic URL resolver.</P
+></LI
+></UL
+>
+
+The interface a resolver must have is documented, so it is possible to write
+your own resolver. For example, you could connect the parser with an HTTP
+client, and resolve URLs of the HTTP namespace. The resolver classes support
+that several independent resolvers are combined to one more powerful resolver;
+thus it is possible to combine a self-written resolver with the already
+existing resolvers.</P
+><P
+>Note that the existing resolvers only interpret <TT
+CLASS="LITERAL"
+>SYSTEM</TT
+>
+names, not <TT
+CLASS="LITERAL"
+>PUBLIC</TT
+> names. If it helps you, it is possible to
+define resolvers for <TT
+CLASS="LITERAL"
+>PUBLIC</TT
+> names, too; for example, such a
+resolver could look up the public name in a hash table, and map it to a system
+name which is passed over to the existing resolver for system names. It is
+relatively simple to provide such a resolver.</P
+></DIV
+></DIV
+><DIV
+CLASS="NAVFOOTER"
+><HR
+ALIGN="LEFT"
+WIDTH="100%"><TABLE
+WIDTH="100%"
+BORDER="0"
+CELLPADDING="0"
+CELLSPACING="0"
+><TR
+><TD
+WIDTH="33%"
+ALIGN="left"
+VALIGN="top"
+><A
+HREF="x1496.html"
+>Prev</A
+></TD
+><TD
+WIDTH="34%"
+ALIGN="center"
+VALIGN="top"
+><A
+HREF="index.html"
+>Home</A
+></TD
+><TD
+WIDTH="33%"
+ALIGN="right"
+VALIGN="top"
+><A
+HREF="x1629.html"
+>Next</A
+></TD
+></TR
+><TR
+><TD
+WIDTH="33%"
+ALIGN="left"
+VALIGN="top"
+>Details of the mapping from XML text to the tree representation</TD
+><TD
+WIDTH="34%"
+ALIGN="center"
+VALIGN="top"
+><A
+HREF="p34.html"
+>Up</A
+></TD
+><TD
+WIDTH="33%"
+ALIGN="right"
+VALIGN="top"
+>Resolvers and sources</TD
+></TR
+></TABLE
+></DIV
+></BODY
+></HTML
+>
\ No newline at end of file
projects / helm.git / blobdiff