+++ /dev/null
-<HTML
-><HEAD
-><TITLE
->Resolvers and sources</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="Configuring and calling the parser"
-HREF="c1567.html"><LINK
-REL="PREVIOUS"
-TITLE="Configuring and calling the parser"
-HREF="c1567.html"><LINK
-REL="NEXT"
-TITLE="The DTD classes"
-HREF="x1812.html"><LINK
-REL="STYLESHEET"
-TYPE="text/css"
-HREF="markup.css"></HEAD
-><BODY
-CLASS="SECT1"
-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="c1567.html"
->Prev</A
-></TD
-><TD
-WIDTH="80%"
-ALIGN="center"
-VALIGN="bottom"
->Chapter 4. Configuring and calling the parser</TD
-><TD
-WIDTH="10%"
-ALIGN="right"
-VALIGN="bottom"
-><A
-HREF="x1812.html"
->Next</A
-></TD
-></TR
-></TABLE
-><HR
-ALIGN="LEFT"
-WIDTH="100%"></DIV
-><DIV
-CLASS="SECT1"
-><H1
-CLASS="SECT1"
-><A
-NAME="AEN1629"
->4.2. Resolvers and sources</A
-></H1
-><DIV
-CLASS="SECT2"
-><H2
-CLASS="SECT2"
-><A
-NAME="AEN1631"
->4.2.1. Using the built-in resolvers (called sources)</A
-></H2
-><P
->The type <TT
-CLASS="LITERAL"
->source</TT
-> enumerates the two
-possibilities where the document to parse comes from.
-
-<PRE
-CLASS="PROGRAMLISTING"
->type source =
- Entity of ((dtd -> Pxp_entity.entity) * Pxp_reader.resolver)
- | ExtID of (ext_id * Pxp_reader.resolver)</PRE
->
-
-You normally need not to worry about this type as there are convenience
-functions that create <TT
-CLASS="LITERAL"
->source</TT
-> values:
-
-
- <P
-></P
-><UL
-COMPACT="COMPACT"
-><LI
-STYLE="list-style-type: disc"
-><P
-><TT
-CLASS="LITERAL"
->from_file s</TT
->: The document is read from
-file <TT
-CLASS="LITERAL"
->s</TT
->; you may specify absolute or relative path names.
-The file name must be encoded as UTF-8 string.</P
-><P
->There is an optional argument <TT
-CLASS="LITERAL"
->~system_encoding</TT
->
-specifying the character encoding which is used for the names of the file
-system. For example, if this encoding is ISO-8859-1 and <TT
-CLASS="LITERAL"
->s</TT
-> is
-also a ISO-8859-1 string, you can form the source:
-
-<PRE
-CLASS="PROGRAMLISTING"
->let s_utf8 = recode_string ~in_enc:`Enc_iso88591 ~out_enc:`Enc_utf8 s in
-from_file ~system_encoding:`Enc_iso88591 s_utf8</PRE
-></P
-><P
->This <TT
-CLASS="LITERAL"
->source</TT
-> has the advantage that
-it is able to resolve inner external entities; i.e. if your document includes
-data from another file (using the <TT
-CLASS="LITERAL"
->SYSTEM</TT
-> attribute), this
-mode will find that file. However, this mode cannot resolve
-<TT
-CLASS="LITERAL"
->PUBLIC</TT
-> identifiers nor <TT
-CLASS="LITERAL"
->SYSTEM</TT
-> identifiers
-other than "file:".</P
-></LI
-><LI
-STYLE="list-style-type: disc"
-><P
-><TT
-CLASS="LITERAL"
->from_channel ch</TT
->: The document is read
-from the channel <TT
-CLASS="LITERAL"
->ch</TT
->. In general, this source also supports
-file URLs found in the document; however, by default only absolute URLs are
-understood. It is possible to associate an ID with the channel such that the
-resolver knows how to interpret relative URLs:
-
-<PRE
-CLASS="PROGRAMLISTING"
->from_channel ~id:(System "file:///dir/dir1/") ch</PRE
->
-
-There is also the ~system_encoding argument specifying how file names are
-encoded. - The example from above can also be written (but it is no
-longer possible to interpret relative URLs because there is no ~id argument,
-and computing this argument is relatively complicated because it must
-be a valid URL):
-
-<PRE
-CLASS="PROGRAMLISTING"
->let ch = open_in s in
-let src = from_channel ~system_encoding:`Enc_iso88591 ch in
-...;
-close_in ch</PRE
-></P
-></LI
-><LI
-STYLE="list-style-type: disc"
-><P
-><TT
-CLASS="LITERAL"
->from_string s</TT
->: The string
-<TT
-CLASS="LITERAL"
->s</TT
-> is the document to parse. This mode is not able to
-interpret file names of <TT
-CLASS="LITERAL"
->SYSTEM</TT
-> clauses, nor it can look up
-<TT
-CLASS="LITERAL"
->PUBLIC</TT
-> identifiers. </P
-><P
->Normally, the encoding of the string is detected as usual
-by analyzing the XML declaration, if any. However, it is also possible to
-specify the encoding directly:
-
-<PRE
-CLASS="PROGRAMLISTING"
->let src = from_string ~fixenc:`ISO-8859-2 s</PRE
-></P
-></LI
-><LI
-STYLE="list-style-type: disc"
-><P
-><TT
-CLASS="LITERAL"
->ExtID (id, r)</TT
->: The document to parse
-is denoted by the identifier <TT
-CLASS="LITERAL"
->id</TT
-> (either a
-<TT
-CLASS="LITERAL"
->SYSTEM</TT
-> or <TT
-CLASS="LITERAL"
->PUBLIC</TT
-> clause), and this
-identifier is interpreted by the resolver <TT
-CLASS="LITERAL"
->r</TT
->. Use this mode
-if you have written your own resolver.</P
-><P
->Which character sets are possible depends on the passed
-resolver <TT
-CLASS="LITERAL"
->r</TT
->.</P
-></LI
-><LI
-STYLE="list-style-type: disc"
-><P
-><TT
-CLASS="LITERAL"
->Entity (get_entity, r)</TT
->: The document
-to parse is returned by the function invocation <TT
-CLASS="LITERAL"
->get_entity
-dtd</TT
->, where <TT
-CLASS="LITERAL"
->dtd</TT
-> is the DTD object to use (it may be
-empty). Inner external references occuring in this entity are resolved using
-the resolver <TT
-CLASS="LITERAL"
->r</TT
->.</P
-><P
->Which character sets are possible depends on the passed
-resolver <TT
-CLASS="LITERAL"
->r</TT
->.</P
-></LI
-></UL
-></P
-></DIV
-><DIV
-CLASS="SECT2"
-><H2
-CLASS="SECT2"
-><A
-NAME="AEN1682"
->4.2.2. The resolver API</A
-></H2
-><P
->A resolver is an object that can be opened like a file, but you
-do not pass the file name to the resolver, but the XML identifier of the entity
-to read from (either a <TT
-CLASS="LITERAL"
->SYSTEM</TT
-> or <TT
-CLASS="LITERAL"
->PUBLIC</TT
->
-clause). When opened, the resolver must return the
-<TT
-CLASS="LITERAL"
->Lexing.lexbuf</TT
-> that reads the characters. The resolver can
-be closed, and it can be cloned. Furthermore, it is possible to tell the
-resolver which character set it should assume. - The following from Pxp_reader:
-
-<PRE
-CLASS="PROGRAMLISTING"
->exception Not_competent
-exception Not_resolvable of exn
-
-class type resolver =
- object
- method init_rep_encoding : rep_encoding -> unit
- method init_warner : collect_warnings -> unit
- method rep_encoding : rep_encoding
- method open_in : ext_id -> Lexing.lexbuf
- method close_in : unit
- method change_encoding : string -> unit
- method clone : resolver
- method close_all : unit
- end</PRE
->
-
-The resolver object must work as follows:</P
-><P
-> <P
-></P
-><UL
-COMPACT="COMPACT"
-><LI
-STYLE="list-style-type: disc"
-><P
->When the parser is called, it tells the resolver the
-warner object and the internal encoding by invoking
-<TT
-CLASS="LITERAL"
->init_warner</TT
-> and <TT
-CLASS="LITERAL"
->init_rep_encoding</TT
->. The
-resolver should store these values. The method <TT
-CLASS="LITERAL"
->rep_encoding</TT
->
-should return the internal encoding.</P
-></LI
-><LI
-STYLE="list-style-type: disc"
-><P
->If the parser wants to read from the resolver, it invokes
-the method <TT
-CLASS="LITERAL"
->open_in</TT
->. Either the resolver succeeds, in which
-case the <TT
-CLASS="LITERAL"
->Lexing.lexbuf</TT
-> reading from the file or stream must
-be returned, or opening fails. In the latter case the method implementation
-should raise an exception (see below).</P
-></LI
-><LI
-STYLE="list-style-type: disc"
-><P
->If the parser finishes reading, it calls the
-<TT
-CLASS="LITERAL"
->close_in</TT
-> method.</P
-></LI
-><LI
-STYLE="list-style-type: disc"
-><P
->If the parser finds a reference to another external
-entity in the input stream, it calls <TT
-CLASS="LITERAL"
->clone</TT
-> to get a second
-resolver which must be initially closed (not yet connected with an input
-stream). The parser then invokes <TT
-CLASS="LITERAL"
->open_in</TT
-> and the other
-methods as described.</P
-></LI
-><LI
-STYLE="list-style-type: disc"
-><P
->If you already know the character set of the input
-stream, you should recode it to the internal encoding, and define the method
-<TT
-CLASS="LITERAL"
->change_encoding</TT
-> as an empty method.</P
-></LI
-><LI
-STYLE="list-style-type: disc"
-><P
->If you want to support multiple external character sets,
-the object must follow a much more complicated protocol. Directly after
-<TT
-CLASS="LITERAL"
->open_in</TT
-> has been called, the resolver must return a lexical
-buffer that only reads one byte at a time. This is only possible if you create
-the lexical buffer with <TT
-CLASS="LITERAL"
->Lexing.from_function</TT
->; the function
-must then always return 1 if the EOF is not yet reached, and 0 if EOF is
-reached. If the parser has read the first line of the document, it will invoke
-<TT
-CLASS="LITERAL"
->change_encoding</TT
-> to tell the resolver which character set to
-assume. From this moment, the object can return more than one byte at once. The
-argument of <TT
-CLASS="LITERAL"
->change_encoding</TT
-> is either the parameter of the
-"encoding" attribute of the XML declaration, or the empty string if there is
-not any XML declaration or if the declaration does not contain an encoding
-attribute. </P
-><P
->At the beginning the resolver must only return one
-character every time something is read from the lexical buffer. The reason for
-this is that you otherwise would not exactly know at which position in the
-input stream the character set changes.</P
-><P
->If you want automatic recognition of the character set,
-it is up to the resolver object to implement this.</P
-></LI
-><LI
-STYLE="list-style-type: disc"
-><P
->If an error occurs, the parser calls the method
-<TT
-CLASS="LITERAL"
->close_all</TT
-> for the top-level resolver; this method should
-close itself (if not already done) and all clones.</P
-></LI
-></UL
-></P
-><DIV
-CLASS="FORMALPARA"
-><P
-><B
->Exceptions. </B
->It is possible to chain resolvers such that when the first resolver is not able
-to open the entity, the other resolvers of the chain are tried in turn. The
-method <TT
-CLASS="LITERAL"
->open_in</TT
-> should raise the exception
-<TT
-CLASS="LITERAL"
->Not_competent</TT
-> to indicate that the next resolver should try
-to open the entity. If the resolver is able to handle the ID, but some other
-error occurs, the exception <TT
-CLASS="LITERAL"
->Not_resolvable</TT
-> should be raised
-to force that the chain breaks.
- </P
-></DIV
-><P
->Example: How to define a resolver that is equivalent to
-from_string: ...</P
-></DIV
-><DIV
-CLASS="SECT2"
-><H2
-CLASS="SECT2"
-><A
-NAME="AEN1728"
->4.2.3. Predefined resolver components</A
-></H2
-><P
->There are some classes in Pxp_reader that define common resolver behaviour.
-
-<PRE
-CLASS="PROGRAMLISTING"
->class resolve_read_this_channel :
- ?id:ext_id ->
- ?fixenc:encoding ->
- ?auto_close:bool ->
- in_channel ->
- resolver</PRE
->
-
-Reads from the passed channel (it may be even a pipe). If the
-<TT
-CLASS="LITERAL"
->~id</TT
-> argument is passed to the object, the created resolver
-accepts only this ID. Otherwise all IDs are accepted. - Once the resolver has
-been cloned, it does not accept any ID. This means that this resolver cannot
-handle inner references to external entities. Note that you can combine this
-resolver with another resolver that can handle inner references (such as
-resolve_as_file); see class 'combine' below. - If you pass the
-<TT
-CLASS="LITERAL"
->~fixenc</TT
-> argument, the encoding of the channel is set to the
-passed value, regardless of any auto-recognition or any XML declaration. - If
-<TT
-CLASS="LITERAL"
->~auto_close = true</TT
-> (which is the default), the channel is
-closed after use. If <TT
-CLASS="LITERAL"
->~auto_close = false</TT
->, the channel is
-left open.
- </P
-><P
-><PRE
-CLASS="PROGRAMLISTING"
->class resolve_read_any_channel :
- ?auto_close:bool ->
- channel_of_id:(ext_id -> (in_channel * encoding option)) ->
- resolver</PRE
->
-
-This resolver calls the function <TT
-CLASS="LITERAL"
->~channel_of_id</TT
-> to open a
-new channel for the passed <TT
-CLASS="LITERAL"
->ext_id</TT
->. This function must either
-return the channel and the encoding, or it must fail with Not_competent. The
-function must return <TT
-CLASS="LITERAL"
->None</TT
-> as encoding if the default
-mechanism to recognize the encoding should be used. It must return
-<TT
-CLASS="LITERAL"
->Some e</TT
-> if it is already known that the encoding of the
-channel is <TT
-CLASS="LITERAL"
->e</TT
->. If <TT
-CLASS="LITERAL"
->~auto_close = true</TT
->
-(which is the default), the channel is closed after use. If
-<TT
-CLASS="LITERAL"
->~auto_close = false</TT
->, the channel is left open.</P
-><P
-><PRE
-CLASS="PROGRAMLISTING"
->class resolve_read_url_channel :
- ?base_url:Neturl.url ->
- ?auto_close:bool ->
- url_of_id:(ext_id -> Neturl.url) ->
- channel_of_url:(Neturl.url -> (in_channel * encoding option)) ->
- resolver</PRE
->
-
-When this resolver gets an ID to read from, it calls the function
-<TT
-CLASS="LITERAL"
->~url_of_id</TT
-> to get the corresponding URL. This URL may be a
-relative URL; however, a URL scheme must be used which contains a path. The
-resolver converts the URL to an absolute URL if necessary. The second
-function, <TT
-CLASS="LITERAL"
->~channel_of_url</TT
->, is fed with the absolute URL as
-input. This function opens the resource to read from, and returns the channel
-and the encoding of the resource.</P
-><P
->Both functions, <TT
-CLASS="LITERAL"
->~url_of_id</TT
-> and
-<TT
-CLASS="LITERAL"
->~channel_of_url</TT
->, can raise Not_competent to indicate that
-the object is not able to read from the specified resource. However, there is a
-difference: A Not_competent from <TT
-CLASS="LITERAL"
->~url_of_id</TT
-> is left as it
-is, but a Not_competent from <TT
-CLASS="LITERAL"
->~channel_of_url</TT
-> is converted to
-Not_resolvable. So only <TT
-CLASS="LITERAL"
->~url_of_id</TT
-> decides which URLs are
-accepted by the resolver and which not.</P
-><P
->The function <TT
-CLASS="LITERAL"
->~channel_of_url</TT
-> must return
-<TT
-CLASS="LITERAL"
->None</TT
-> as encoding if the default mechanism to recognize the
-encoding should be used. It must return <TT
-CLASS="LITERAL"
->Some e</TT
-> if it is
-already known that the encoding of the channel is <TT
-CLASS="LITERAL"
->e</TT
->.</P
-><P
->If <TT
-CLASS="LITERAL"
->~auto_close = true</TT
-> (which is the default), the channel is
-closed after use. If <TT
-CLASS="LITERAL"
->~auto_close = false</TT
->, the channel is
-left open.</P
-><P
->Objects of this class contain a base URL relative to which relative URLs are
-interpreted. When creating a new object, you can specify the base URL by
-passing it as <TT
-CLASS="LITERAL"
->~base_url</TT
-> argument. When an existing object is
-cloned, the base URL of the clone is the URL of the original object. - Note
-that the term "base URL" has a strict definition in RFC 1808.</P
-><P
-><PRE
-CLASS="PROGRAMLISTING"
->class resolve_read_this_string :
- ?id:ext_id ->
- ?fixenc:encoding ->
- string ->
- resolver</PRE
->
-
-Reads from the passed string. If the <TT
-CLASS="LITERAL"
->~id</TT
-> argument is passed
-to the object, the created resolver accepts only this ID. Otherwise all IDs are
-accepted. - Once the resolver has been cloned, it does not accept any ID. This
-means that this resolver cannot handle inner references to external
-entities. Note that you can combine this resolver with another resolver that
-can handle inner references (such as resolve_as_file); see class 'combine'
-below. - If you pass the <TT
-CLASS="LITERAL"
->~fixenc</TT
-> argument, the encoding of
-the string is set to the passed value, regardless of any auto-recognition or
-any XML declaration.</P
-><P
-><PRE
-CLASS="PROGRAMLISTING"
->class resolve_read_any_string :
- string_of_id:(ext_id -> (string * encoding option)) ->
- resolver</PRE
->
-
-This resolver calls the function <TT
-CLASS="LITERAL"
->~string_of_id</TT
-> to get the
-string for the passed <TT
-CLASS="LITERAL"
->ext_id</TT
->. This function must either
-return the string and the encoding, or it must fail with Not_competent. The
-function must return <TT
-CLASS="LITERAL"
->None</TT
-> as encoding if the default
-mechanism to recognize the encoding should be used. It must return
-<TT
-CLASS="LITERAL"
->Some e</TT
-> if it is already known that the encoding of the
-string is <TT
-CLASS="LITERAL"
->e</TT
->.</P
-><P
-><PRE
-CLASS="PROGRAMLISTING"
->class resolve_as_file :
- ?file_prefix:[ `Not_recognized | `Allowed | `Required ] ->
- ?host_prefix:[ `Not_recognized | `Allowed | `Required ] ->
- ?system_encoding:encoding ->
- ?url_of_id:(ext_id -> Neturl.url) ->
- ?channel_of_url: (Neturl.url -> (in_channel * encoding option)) ->
- unit ->
- resolver</PRE
->
-Reads from the local file system. Every file name is interpreted as
-file name of the local file system, and the referred file is read.</P
-><P
->The full form of a file URL is: file://host/path, where
-'host' specifies the host system where the file identified 'path'
-resides. host = "" or host = "localhost" are accepted; other values
-will raise Not_competent. The standard for file URLs is
-defined in RFC 1738.</P
-><P
->Option <TT
-CLASS="LITERAL"
->~file_prefix</TT
->: Specifies how the "file:" prefix of
-file names is handled:
- <P
-></P
-><UL
-COMPACT="COMPACT"
-><LI
-STYLE="list-style-type: disc"
-><P
-><TT
-CLASS="LITERAL"
->`Not_recognized:</TT
->The prefix is not
-recognized.</P
-></LI
-><LI
-STYLE="list-style-type: disc"
-><P
-><TT
-CLASS="LITERAL"
->`Allowed:</TT
-> The prefix is allowed but
-not required (the default).</P
-></LI
-><LI
-STYLE="list-style-type: disc"
-><P
-><TT
-CLASS="LITERAL"
->`Required:</TT
-> The prefix is
-required.</P
-></LI
-></UL
-></P
-><P
->Option <TT
-CLASS="LITERAL"
->~host_prefix:</TT
-> Specifies how the "//host" phrase of
-file names is handled:
- <P
-></P
-><UL
-COMPACT="COMPACT"
-><LI
-STYLE="list-style-type: disc"
-><P
-><TT
-CLASS="LITERAL"
->`Not_recognized:</TT
->The prefix is not
-recognized.</P
-></LI
-><LI
-STYLE="list-style-type: disc"
-><P
-><TT
-CLASS="LITERAL"
->`Allowed:</TT
-> The prefix is allowed but
-not required (the default).</P
-></LI
-><LI
-STYLE="list-style-type: disc"
-><P
-><TT
-CLASS="LITERAL"
->`Required:</TT
-> The prefix is
-required.</P
-></LI
-></UL
-></P
-><P
->Option <TT
-CLASS="LITERAL"
->~system_encoding:</TT
-> Specifies the encoding of file
-names of the local file system. Default: UTF-8.</P
-><P
->Options <TT
-CLASS="LITERAL"
->~url_of_id</TT
->, <TT
-CLASS="LITERAL"
->~channel_of_url</TT
->: Not
-for the casual user!</P
-><P
-><PRE
-CLASS="PROGRAMLISTING"
->class combine :
- ?prefer:resolver ->
- resolver list ->
- resolver</PRE
->
-
-Combines several resolver objects. If a concrete entity with an
-<TT
-CLASS="LITERAL"
->ext_id</TT
-> is to be opened, the combined resolver tries the
-contained resolvers in turn until a resolver accepts opening the entity
-(i.e. it does not raise Not_competent on open_in).</P
-><P
->Clones: If the 'clone' method is invoked before 'open_in', all contained
-resolvers are cloned separately and again combined. If the 'clone' method is
-invoked after 'open_in' (i.e. while the resolver is open), additionally the
-clone of the active resolver is flagged as being preferred, i.e. it is tried
-first. </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="c1567.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="x1812.html"
->Next</A
-></TD
-></TR
-><TR
-><TD
-WIDTH="33%"
-ALIGN="left"
-VALIGN="top"
->Configuring and calling the parser</TD
-><TD
-WIDTH="34%"
-ALIGN="center"
-VALIGN="top"
-><A
-HREF="c1567.html"
->Up</A
-></TD
-><TD
-WIDTH="33%"
-ALIGN="right"
-VALIGN="top"
->The DTD classes</TD
-></TR
-></TABLE
-></DIV
-></BODY
-></HTML
->
\ No newline at end of file
projects / helm.git / blobdiff