The type source enumerates the two +possibilities where the document to parse comes from. + +
type source = + Entity of ((dtd -> Pxp_entity.entity) * Pxp_reader.resolver) + | ExtID of (ext_id * Pxp_reader.resolver)+ +You normally need not to worry about this type as there are convenience +functions that create source values: + + +
from_file s: The document is read from +file s; you may specify absolute or relative path names. +The file name must be encoded as UTF-8 string.
There is an optional argument ~system_encoding +specifying the character encoding which is used for the names of the file +system. For example, if this encoding is ISO-8859-1 and s is +also a ISO-8859-1 string, you can form the source: + +
let s_utf8 = recode_string ~in_enc:`Enc_iso88591 ~out_enc:`Enc_utf8 s in +from_file ~system_encoding:`Enc_iso88591 s_utf8
This source has the advantage that +it is able to resolve inner external entities; i.e. if your document includes +data from another file (using the SYSTEM attribute), this +mode will find that file. However, this mode cannot resolve +PUBLIC identifiers nor SYSTEM identifiers +other than "file:".
from_channel ch: The document is read +from the channel ch. 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: + +
from_channel ~id:(System "file:///dir/dir1/") ch+ +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): + +
let ch = open_in s in +let src = from_channel ~system_encoding:`Enc_iso88591 ch in +...; +close_in ch
from_string s: The string +s is the document to parse. This mode is not able to +interpret file names of SYSTEM clauses, nor it can look up +PUBLIC identifiers.
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: + +
let src = from_string ~fixenc:`ISO-8859-2 s
ExtID (id, r): The document to parse +is denoted by the identifier id (either a +SYSTEM or PUBLIC clause), and this +identifier is interpreted by the resolver r. Use this mode +if you have written your own resolver.
Which character sets are possible depends on the passed +resolver r.
Entity (get_entity, r): The document +to parse is returned by the function invocation get_entity +dtd, where dtd is the DTD object to use (it may be +empty). Inner external references occuring in this entity are resolved using +the resolver r.
Which character sets are possible depends on the passed +resolver r.
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 SYSTEM or PUBLIC +clause). When opened, the resolver must return the +Lexing.lexbuf 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: + +
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+ +The resolver object must work as follows:
When the parser is called, it tells the resolver the +warner object and the internal encoding by invoking +init_warner and init_rep_encoding. The +resolver should store these values. The method rep_encoding +should return the internal encoding.
If the parser wants to read from the resolver, it invokes +the method open_in. Either the resolver succeeds, in which +case the Lexing.lexbuf 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).
If the parser finishes reading, it calls the +close_in method.
If the parser finds a reference to another external +entity in the input stream, it calls clone to get a second +resolver which must be initially closed (not yet connected with an input +stream). The parser then invokes open_in and the other +methods as described.
If you already know the character set of the input +stream, you should recode it to the internal encoding, and define the method +change_encoding as an empty method.
If you want to support multiple external character sets, +the object must follow a much more complicated protocol. Directly after +open_in 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 Lexing.from_function; 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 +change_encoding 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 change_encoding 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.
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.
If you want automatic recognition of the character set, +it is up to the resolver object to implement this.
If an error occurs, the parser calls the method +close_all for the top-level resolver; this method should +close itself (if not already done) and all clones.
Exceptions. 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 open_in should raise the exception +Not_competent 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 Not_resolvable should be raised +to force that the chain breaks. +
Example: How to define a resolver that is equivalent to +from_string: ...
There are some classes in Pxp_reader that define common resolver behaviour. + +
class resolve_read_this_channel : + ?id:ext_id -> + ?fixenc:encoding -> + ?auto_close:bool -> + in_channel -> + resolver+ +Reads from the passed channel (it may be even a pipe). If the +~id 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 +~fixenc argument, the encoding of the channel is set to the +passed value, regardless of any auto-recognition or any XML declaration. - If +~auto_close = true (which is the default), the channel is +closed after use. If ~auto_close = false, the channel is +left open. +
class resolve_read_any_channel : + ?auto_close:bool -> + channel_of_id:(ext_id -> (in_channel * encoding option)) -> + resolver+ +This resolver calls the function ~channel_of_id to open a +new channel for the passed ext_id. This function must either +return the channel and the encoding, or it must fail with Not_competent. The +function must return None as encoding if the default +mechanism to recognize the encoding should be used. It must return +Some e if it is already known that the encoding of the +channel is e. If ~auto_close = true +(which is the default), the channel is closed after use. If +~auto_close = false, the channel is left open.
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+ +When this resolver gets an ID to read from, it calls the function +~url_of_id 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, ~channel_of_url, 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.
Both functions, ~url_of_id and +~channel_of_url, 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 ~url_of_id is left as it +is, but a Not_competent from ~channel_of_url is converted to +Not_resolvable. So only ~url_of_id decides which URLs are +accepted by the resolver and which not.
The function ~channel_of_url must return +None as encoding if the default mechanism to recognize the +encoding should be used. It must return Some e if it is +already known that the encoding of the channel is e.
If ~auto_close = true (which is the default), the channel is +closed after use. If ~auto_close = false, the channel is +left open.
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 ~base_url 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.
class resolve_read_this_string : + ?id:ext_id -> + ?fixenc:encoding -> + string -> + resolver+ +Reads from the passed string. If the ~id 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 ~fixenc argument, the encoding of +the string is set to the passed value, regardless of any auto-recognition or +any XML declaration.
class resolve_read_any_string : + string_of_id:(ext_id -> (string * encoding option)) -> + resolver+ +This resolver calls the function ~string_of_id to get the +string for the passed ext_id. This function must either +return the string and the encoding, or it must fail with Not_competent. The +function must return None as encoding if the default +mechanism to recognize the encoding should be used. It must return +Some e if it is already known that the encoding of the +string is e.
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+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.
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.
Option ~file_prefix: Specifies how the "file:" prefix of +file names is handled: +
`Not_recognized:The prefix is not +recognized.
`Allowed: The prefix is allowed but +not required (the default).
`Required: The prefix is +required.
Option ~host_prefix: Specifies how the "//host" phrase of +file names is handled: +
`Not_recognized:The prefix is not +recognized.
`Allowed: The prefix is allowed but +not required (the default).
`Required: The prefix is +required.
Option ~system_encoding: Specifies the encoding of file +names of the local file system. Default: UTF-8.
Options ~url_of_id, ~channel_of_url: Not +for the casual user!
class combine : + ?prefer:resolver -> + resolver list -> + resolver+ +Combines several resolver objects. If a concrete entity with an +ext_id 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).
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.