Commit 003a0997 authored by gerd's avatar gerd

ocamldoc documentation


git-svn-id: https://godirepo.camlcity.org/svn/lib-pxp/trunk@732 dbe99aee-44db-0310-b2b3-d33182c8eb97
parent 7a10fa6c
......@@ -51,8 +51,7 @@ div.h9 { font-size : 20pt ; border: 1px solid #000000; margin-top: 5px; margin-b
.indextable { border-style : hidden }
.paramstable { border-style : hidden ; padding: 5pt 5pt}
body { background-color : White }
tr { background-color : White }
td.typefieldcomment { background-color : #FFFFFF ; font-size: smaller ;}
td.typefieldcomment { font-size: smaller ;}
pre { margin-bottom: 4px }
div.sig_block {margin-left: 1cm}
......@@ -63,3 +62,11 @@ div.sig_block {margin-left: 1cm}
font-weight: bold;
padding-bottom: 10px;
}
.included-module-type {
margin-left: 1cm;
background-color: #EEE;
}
.included-module {
margin-left: 1cm;
background-color: #EEE;
}
......@@ -15,8 +15,12 @@ OBJ = pxp_lexing.cmo pxp_type_anchor.cmo \
pxp_dtd_parser.cmo \
pxp_yacc.cmo pxp_marshal.cmo pxp_codewriter.cmo
DOC = pxp_document.mli pxp_dtd.mli \
intro_trees.txt intro_extensions.txt intro_namespaces.txt
DOC = pxp_types.mli pxp_document.mli pxp_dtd.mli pxp_tree_parser.mli \
pxp_core_types_type.mli pxp_ev_parser.mli \
pxp_event.mli pxp_dtd_parser.mli pxp_codewriter.mli \
pxp_marshal.mli pxp_yacc.mli pxp_reader.mli \
intro_trees.txt intro_extensions.txt intro_namespaces.txt \
intro_events.txt intro_resolution.txt
XOBJ = $(OBJ:.cmo=.cmx)
......@@ -32,7 +36,7 @@ pxp_engine.cmxa: $(XOBJ)
pxp_engine.dump: $(DOC)
if [ ! -f pxp_engine.cma ]; then $(MAKE) -f Makefile.code pxp_engine.cma; fi
ocamldoc -stars -dump pxp_engine.dump \
ocamlfind ocamldoc -package "$(PACKAGES)" -stars -dump pxp_engine.dump \
$(DOC)
......
{1 XML data as stream of events}
XXX
{b Editorial note:} The PXP tree API has some complexity. The
definition in {!Pxp_document} is hard to read without some background
information. This introduction is supposed to give it. However, it
is not a tutorial, and the reader won't find easy recipes in it.
information. This introduction is supposed to provide this information.
Also note that there is also a stream representation of XML. See
{!Intro_events} for more about this.
{1 The structure of document trees}
......@@ -229,7 +231,7 @@ whole tree.
called on an element node, this method creates a new tree only
consisting of an element, and the only node of the tree is an
object of the same class as this node}
{- [create_data] ({!Pxp_document.node.create_date}): same for data
{- [create_data] ({!Pxp_document.node.create_data}): same for data
nodes }
{- [orphaned_clone] ({!Pxp_document.node.orphaned_clone}):
creates a copy of the subtree starting at this node }
......
......@@ -4,17 +4,22 @@
* Copyright by Gerd Stolpmann. See LICENSE for details.
*)
(** Generate O'Caml code for creating large constant XML trees *)
open Pxp_document
open Pxp_yacc
open Pxp_dtd
(** See also {!Pxp_marshal} for direct marshalling functions. *)
val write_document : out_channel -> 'ext document -> unit
(* Writes O'Caml code to the out_channel that is a top-level function
* creating a fresh document which is equal to the passed document:
(** Writes O'Caml code to the [out_channel] so that when the code
* is compiled and executed, a fresh document is created with the
* same contents as the passed document:
*
* "let create_document ?enable_namespace_processing config spec = ...;;"
* {[ "let create_document ?enable_namespace_processing config spec = ...;;" ]}
*
* If you compile the code and call "create_document config spec" the
* If you compile the code and call [create_document config spec] the
* function creates a document tree which is (almost) equal to the
* passed document.
*
......@@ -22,33 +27,25 @@ val write_document : out_channel -> 'ext document -> unit
* - Parsed entities
* - Whether a declaration occurs in an external entity or not
*
* 'config': a Pxp_yacc.config
* 'spec': a Pxp_document.spec
* enable_namespace_processing: You can pass here a namespace_manager
* - [config]: The configuration to assume for re-creating the tree
* - [spec]: a {!Pxp_document.spec}
* - [enable_namespace_processing]: You can pass here a namespace_manager
* to enable the namespace code (default: no namespace processing)
*
* NOTE: The signature of the generated function has changed from
* PXP 1.0 to PXP 1.1; the first argument is now 'config' and not
* 'warner'
*)
val write_subtree : out_channel -> 'ext node -> unit
(* Writes O'Caml code to the out_channel that is a top-level function
* creating a fresh node tree which is equal to the passed tree:
(** Writes O'Caml code to the [out_channel] so that when the code
* is compiled and executed, a fresh tree is created with the
* same contents as the passed tree:
*
* "let create_subtree dtd spec = ...;;"
* {[ "let create_subtree dtd spec = ...;;" ]}
*
* If you compile the code and call "create_subtree dtd spec" the
* If you compile the code and call [create_subtree dtd spec] the
* function creates a DTD object which is equal to the passed object.
*
* 'dtd': a DTD object
* 'spec': a Pxp_document.spec
* - [dtd]: a DTD object
* - [spec]: a Pxp_document.spec
*)
(* write_dtd: this method is deprecated! *)
This diff is collapsed.
......@@ -1030,7 +1030,7 @@ class type [ 'ext ] node =
* The optional arguments have the following defaults:
* - [~name_pool_for_attribute_values]: No pool is used
* - [~position]: The position is not available in the copy
* - [~valcheck]: false
* - [~valcheck]: true
* - [~att_values]: empty
*
* {b Domain.} Elements.
......@@ -1896,7 +1896,6 @@ val map_tree_sibl :
* raised.
*
* Attribute and namespace nodes are ignored.
* </ID>
*)
val iter_tree : ?pre:('ext node -> unit) ->
......@@ -2227,11 +2226,11 @@ val solidify :
*
* The data nodes are not normalized unless the arriving data events
* are already normalized. To get this effect, filter the stream
* with {!Pxp_ev_parser.norm_cdata_filter} before calling solidify.
* with {!Pxp_event.norm_cdata_filter} before calling solidify.
*
* Ignorable whitespace is not automatically removed. To get this
* effect, filter the stream with
* {!Pxp_ev_parser.drop_ignorable_whitespace_filter} before calling solidify.
* {!Pxp_event.drop_ignorable_whitespace_filter} before calling solidify.
*
* The uniqueness of ID attributes is not checked.
*)
......
This diff is collapsed.
......@@ -4,20 +4,20 @@
* Copyright by Gerd Stolpmann. See LICENSE for details.
*)
(** Calling the parser to read DTDs *)
open Pxp_types
open Pxp_dtd
val create_empty_dtd : config -> dtd
(* Create an empty DTD *)
(** Create an empty DTD *)
val parse_dtd_entity : config -> source -> dtd
(* Parse an entity containing a DTD (external subset), and return this DTD. *)
val parse_dtd_entity : config -> Pxp_types.source -> dtd
(** Parse an entity containing a DTD (external subset), and return this DTD. *)
val extract_dtd_from_document_entity : config -> source -> dtd
(* Parses a closed document, i.e. a document beginning with <!DOCTYPE...>,
val extract_dtd_from_document_entity : config -> Pxp_types.source -> dtd
(** Parses a closed document, i.e. a document beginning with [<!DOCTYPE...>],
* and returns the DTD contained in the document.
* The parts of the document outside the DTD are actually not parsed,
* i.e. parsing stops when all declarations of the DTD have been read.
*)
......@@ -4,30 +4,46 @@
* Copyright by Gerd Stolpmann. See LICENSE for details.
*)
(** Calling the parser in event mode *)
(** In event parsing, the parser generates a stream of events while reading
XML text (one or several files). In "push mode" the user provides
a callback function, and the parser invokes this function for every
event. In "pull mode", the parser creates a function that fetches
the next event of the stream, and that can be repeatedly be called
by the user to get one event after the other.
For an introduction into this type of parsing, see {!Intro_events}.
In {!Pxp_event} you find functions for composing, analyzing and
transforming streams of events (for pull mode). For converting a
stream of events into a tree, see {!Pxp_document.solidify}. For
converting a tree into a stream of events, see
{!Pxp_document.liquefy}.
*)
open Pxp_types
open Pxp_dtd
(******************* Event-based interface **************************)
val create_entity_manager :
?is_document:bool -> (* default: true *)
config ->
source ->
Pxp_entity_manager.entity_manager
(* Creates an entity manager that is initialized with the toplevel
(** Creates an entity manager that is initialized with the toplevel
* entity referenced by the source argument. The entity manager
* can be used by [process_entity] below.
*
* The following configuration options are used:
* - warner
* - encoding
* - debugging_mode
* The following configuration options are interpreted:
* - [warner]
* - [encoding]
* - [debugging_mode]
*
* ~is_document: Pass [true] if the entity to read is a complete
* [is_document]: Pass [true] if the entity to read is a complete
* document, and [false] otherwise. The value [true] enforces
* several restrictions on document entities, e.g. that
* <![INCLUDE[..]> and <![IGNORE[..]> are not allowed and that additional
* nesting rules are respected by parameter entities.
* [<![INCLUDE[..]]>] and [<![IGNORE[..]]>] are not allowed and that
* additional nesting rules are respected by parameter entities.
*)
......@@ -38,7 +54,8 @@ val process_entity :
Pxp_entity_manager.entity_manager ->
(event -> unit) ->
unit
(* Parses a document or a document fragment. At least the well-formedness
(** Parses a document or a document fragment in push mode. At least the
* well-formedness
* of the document is checked, but the flags of the [entry] argument
* may specify more.
*
......@@ -47,50 +64,50 @@ val process_entity :
* current entity of the entity manager. It is allowed that the
* current entity is open or closed.
*
* The entry point to the parsing rules can be specified.
* Notes to entry points:
* - `Entry_document:
* The first generated event is always E_start_doc,
* The entry point to the parsing rules can be specified as follows:
* - [`Entry_document]:
* The first generated event is always [E_start_doc],
* it contains the whole DTD as object (no events are generated
* during DTD parsing, only the result is passed back). The
* events for the contents follow, terminated by E_end_doc and
* E_end_of_stream.
* - `Entry_content:
* during DTD parsing, only the wholly parsed DTD is passed back). The
* events for the contents follow, terminated by [E_end_doc] and then
* [E_end_of_stream].
* - [`Entry_content]:
* Only events for contents are generated. They are terminated
* by E_end_of_stream.
* - `Entry_declaration:
* Currently not supported. (But see Pxp_dtd_parser for functions
* by [E_end_of_stream].
* - [`Entry_declaration]:
* Currently not supported. (But see {!Pxp_dtd_parser} for functions
* parsing DTDs.)
*
* The entry points have options, see [Pxp_types] for explanations.
* The entry points have options, see {!Pxp_types.entry} for explanations.
*
* It may happen that several adjacent [E_char_data] events are
* emitted for the same character data section.
*
* The generated events are not normalized with respect to:
* - Several E_char_data events may be generated for the same
* character data section
* There are filter functions that apply normalization routines
* to the events, see below.
*
* Only the following config options have an effect:
* - warner
* - encoding
* - enable_pinstr_nodes
* - enable_comment_nodes
* - enable_super_root_node
* - store_element_positions
* - name_pool and all name pool options
* - enable_namespace_processing
* - [warner]
* - [encoding]
* - [enable_pinstr_nodes]
* - [enable_comment_nodes]
* - [enable_super_root_node]
* - [store_element_positions]
* - [name_pool] and all name pool options
* - [enable_namespace_processing]
*
* If an error happens, the callback function is invoked exactly once
* with the E_error event. The error is additionally passed to the caller
* with the [E_error] event. The error is additionally passed to the caller
* by letting the exception fall through to the caller. It is not possible
* to resume parsing after an error.
*
* The idea behind this special error handling is that the callback
* function should always be notified when the parser stops, no matter
* whether it is successful or not. So the last event passed to the
* callback function is either E_end_of_stream or E_error. You can
* imagine that process_entity follows this scheme:
* callback function is either [E_end_of_stream] or [E_error]. You can
* imagine that [process_entity] follows this scheme:
*
* {[
* try
* "parse";
* eh E_end_of_stream (* eh is the callback function *)
......@@ -101,8 +118,9 @@ val process_entity :
* let e = At(pos, error) in
* eh (E_error e);
* raise e
* ]}
*
* Note that there is always an At(_,_) exception that wraps the exception
* Note that there is always an [At(_,_)] exception that wraps the exception
* that originally occurred. - This style of exception handling applies
* to exceptions generated by the parser as well as to exceptions raised
* by the callback function.
......@@ -116,18 +134,18 @@ val process_expr :
Pxp_entity_manager.entity_manager ->
(event -> unit) ->
unit
(* This is a special parsing function that corresponds to the entry
* Entry_expr, i.e. it parses a single element, processing instruction,
(** This is a special parsing function that corresponds to the entry
* [`Entry_expr], i.e. it parses a single element, processing instruction,
* or comment. In contrast to [process_entity], the current entity
* is not opened, but it is expected that the entity is already open.
* Of course, the entity is not closed after parsing (except an error
* happens).
*
* ~first_token: This token is prepended to the tokens read from the
* - [first_token]: This token is prepended to the tokens read from the
* entity manager.
* ~following_token: The token following the last parsed token is
* - [following_token]: The token following the last parsed token is
* optionally stored into this variable.
* Note: By design the parser _always_ reads the following token.
* Note: By design the parser {b always} reads the following token.
* I know that this may lead to serious problems when it is tried
* to integrate this parser with another parser. It is currently
* hard to change!
......@@ -138,26 +156,25 @@ val create_pull_parser :
entry ->
Pxp_entity_manager.entity_manager ->
(unit -> event option)
(* let next_event = create_pull_parser cfg entry mng in
(** Invoke the event parser using the pull model. It is used as:
* {[
* let next_event = create_pull_parser cfg entry mng in
* let ev = next_event()
* ]}
*
* This function parses the XML document in "pull mode". [next_event]
* Now [next_event]
* should be invoked repeatedly until it returns [None], indicating the
* end of the document. The events are encoded as [Some ev].
*
* The function returns exactly the same events as [process_entity].
*
* In contrast to [process_entity], no exception is raised when an
* error happens. Only the E_error event is generated (as last event).
* error happens. Only the [E_error] event is generated (as last event
* before [None]).
*
* To create a stream of events, just do:
* {[
* let next = create_pull_parser cfg entry mng in
* let stream = Stream.from(fun _ -> next())
* ]}
*)
(* Filters have been moved to Pxp_event! *)
(* For conversions from trees to event streams, and vice versa,
* see Pxp_document.
*)
......@@ -7,39 +7,53 @@
open Pxp_types
open Pxp_dtd
(** Dealing with events (for pull parsing) *)
(**********************************************************************)
(* Event streams and lists *)
(**********************************************************************)
(** {2 Events as lists} *)
val to_list : (unit -> event option) -> event list
(* Fetch all events from the event stream, and return the corresponding
(** Fetch all events from the pull function, and return the corresponding
* list of events.
*)
val of_list : event list -> (unit -> event option)
(* Pull the events from the input list *)
(** [of_list l]: Create a pull function fetching the events from [l] *)
val concat : (unit -> event option) list ->
(unit -> event option)
(* Pull the events from the streams in turn *)
(** [let p = concat l]: The pull functions contained in the list [l] are
concatenated, and a new pull function [p] is created that pulls from
the functions of the list in turn (when one function indicates
the end of the events, it is continued with the next function in the
list).
*)
val iter : (event -> unit) -> (unit -> event option) -> unit
(* Iterates over the events of the stream and calls the function *)
(** [iter f p]: The pull function [p] is repeatedly called to get a
stream of events [e]. For each event the function [f] is called.
*)
(* Missing: map, fold, ... *)
val extract : event -> (unit -> event option) -> (unit -> event option)
(* let next' = extract e next:
* Extracts a subexpression from the stream [next] prepended by [e].
(** [let next' = extract e next]:
* Extracts a subexpression from the pull function [next] prepended by [e].
* A subexpression consists of either
* - a single data, comment, PI, or error event
* - a start tag, either of an element, a super root, or a document,
* until the corresponding end tag
* - a position event followed by a subexpression
* The returned stream contains all events of the subexpression.
*
* The returned pull function contains all events of the subexpression.
* When the extracted stream is read, the original stream is read, too.
*
* Example:
* {[
* let l = [ E_pinstr; E_start_tag; E_data; E_start_tag; E_end_tag;
* E_comment; E_end_tag; E_data ];;
* let g = of_list l;;
......@@ -52,6 +66,7 @@ val extract : event -> (unit -> event option) -> (unit -> event option)
* g'();; (* returns None, end of subexpression *)
* g();; (* returns Some E_data *)
* g();; (* returns None *)
* ]}
*)
......@@ -59,37 +74,42 @@ val extract : event -> (unit -> event option) -> (unit -> event option)
(* Filters *)
(**********************************************************************)
(** {2 Filters} *)
type filter = (unit -> event option) -> (unit -> event option)
(** A filter transforms a pull function into another pull function *)
val norm_cdata_filter : filter
(* This filter
* - removes empty E_char_data events
* - concatenates adjacent E_char_data events
(** This filter
* - removes empty [E_char_data] events
* - concatenates adjacent [E_char_data] events
*
* but does not touch any other parts of the event stream.
*)
val drop_ignorable_whitespace_filter : filter
(* This filter
(** This filter
* - checks whether character data between elements in a
* "regexp" or "non-PCDATA mixed" content model consists
* only of whitespace, and
* - removes these whitespace characters from the event stream.
* If the check fails, a WF_Error will be raised.
*
* If the check fails, a [WF_Error] will be raised.
*
* This filter works only if the DTD found in the event stream
* actually contains element declarations. This is usually enabled
* by including the `Extend_dtd_fully or `Val_mode_dtd options to
* by including the [`Extend_dtd_fully] or [`Val_mode_dtd] options to
* the [entry] passed to the [create_pull_parser] call. Furthermore,
* there must be an E_start_doc event.
* there must be an [E_start_doc] event.
*
* This filter does not perform any other validation checks.
*)
val pfilter : (event -> bool) -> filter
(* Filters an event stream by a predicate
(** Filters an event stream by a predicate
*
* Example: Remove comments:
* pfilter (function E_comment _ -> false | _ -> true) g
* {[ pfilter (function E_comment _ -> false | _ -> true) g ]}
*)
......@@ -99,6 +119,8 @@ val pfilter : (event -> bool) -> filter
(* Printing *)
(**********************************************************************)
(** {2 Printing event streams} *)
type dtd_style =
[ `Ignore
| `Include
......@@ -114,7 +136,7 @@ val write_events :
rep_encoding ->
(unit -> event option) ->
unit
(* Writes the events to the [output_stream]. The events must be encoded
(** Writes the events to the [output_stream]. The events must be encoded
* as indicated by the [rep_encoding] argument, but the output is written
* as specified by the [encoding] argument.
*
......@@ -122,16 +144,16 @@ val write_events :
* one can set the default namespace by passing [default], which must be
* the normalized prefix of the default namespace.
*
* For E_doc_start events, the DTD may be written. This is controlled by
* For [E_doc_start] events, the DTD may be written. This is controlled by
* [dtd_style]:
* - `Ignore: No DOCTYPE clause is written
* - `Include: The DOCTYPE clause is written, and the DTD is included
* in the internal subset
* - `Reference: The DOCTYPE clause is written as a reference to an
* - [`Ignore]: No [DOCTYPE] clause is written
* - [`Include]: The [DOCTYPE] clause is written, and the DTD is included
* in the internal subset (the default)
* - [`Reference]: The [DOCTYPE] clause is written as a reference to an
* external DTD
*
* Option [~minimization]: How to write out empty elements. [`AllEmpty]
* means that all empty elements are minimized (using the <name/>
* Option [minimization]: How to write out empty elements. [`AllEmpty]
* means that all empty elements are minimized (using the [<name/>]
* form). [`None] does not minimize at all and is the default.
*)
......@@ -143,7 +165,7 @@ val display_events :
rep_encoding ->
(unit -> event option) ->
unit
(* Writes the events to the [output_stream]. The events must be encoded
(** Writes the events to the [output_stream]. The events must be encoded
* as indicated by the [rep_encoding] argument, but the output is written
* as specified by the [encoding] argument.
*
......
......@@ -3,17 +3,20 @@
*
*)
(** Marshalling of XML trees *)
(* TODO:
* - namespace_info
*)
(* This module allows fast marshalling of subtrees. The standard marshalling
(** This module allows fast marshalling of subtrees. The standard O'Caml marshalling
* implementation does not work because O'Caml does not support marshalling
* of objects. Because of this, the objects must be transformed into a
* representation for which no marshalling restriction applies.
*
* The subtree is converted into a sequence of reconstruction_cmd values
* The subtree is converted into a sequence of [reconstruction_cmd] values
* which can be marshaled using the standard implementation.
*
* While the tree is written or read it is possible to change the character
......@@ -22,6 +25,12 @@
*)
type reconstruction_cmd
(** A tree is translated into a sequence of [reconstrucion_cmd] tokens.
These tokens can be subsequently translated into byte strings using
the standard [Marshal] module.
*)
(** {2 Marshalling} *)
val subtree_to_cmd_sequence :
?omit_positions:bool ->
......@@ -29,20 +38,19 @@ val subtree_to_cmd_sequence :
(reconstruction_cmd -> unit) ->
'ext Pxp_document.node ->
unit
(* The passed node is the root of the subtree to be marshaled. The function
* is called several times with the reconstruction_cmd values which
* contain the contents of the subtree.
(** [subtree_to_cmd_sequence f n]:
* The passed node [n] is the root of the subtree to be marshaled. The function
* [f] is called several times with the sequence of [reconstruction_cmd] values
* that contain the contents of the subtree.
*
* If the subtree has a namespace manager, the information contained
* in this object is marshaled, too. However, the namespace_info object
* is not represented in the output stream (if any). This means that
* the stream contains all namespace URIs, but not the original prefixes
* (source prefixes). This limitation is practically meaningless
* (who wants to know source prefixes?).
* in this object is marshaled, too. The namespace scope objects are lost,
* however.
*
* ~omit_positions: If true, the position strings of the nodes which contain
* [omit_positions]: If true, the position strings of the nodes which contain
* line numbers are omitted. Default: false
*
* ~enc: if passed, the character encoding is changed to this type. If
* [enc]: if passed, the character encoding is changed to this type. If
* omitted, the written sequence is encoded in the same manner as the
* node tree.
*)
......@@ -53,15 +61,16 @@ val subtree_to_channel :
out_channel ->
'ext Pxp_document.node ->
unit
(* The passed node is the root of the subtree to be marshaled; the external
* representation is written to the out_channel (which must have been opened
(** [subtree_to_channel ch n]:
* The node [n] is the root of the subtree to be marshaled; the external
* representation is written to [ch] (which must have been opened
* in binary mode).
* (Info about namespaces: see subtree_to_cmd_sequence.)
*
* ~omit_positions: If true, the position strings of the nodes which contain
* [omit_positions]: If true, the position strings of the nodes which contain
* line numbers are omitted. Default: false
*
* ~enc: if passed, the character encoding is changed to this type. If
* [enc]: if passed, the character encoding is changed to this type. If
* omitted, the written sequence is encoded in the same manner as the
* node tree.
*)
......@@ -72,21 +81,26 @@ val document_to_cmd_sequence :
(reconstruction_cmd -> unit) ->
'ext Pxp_document.document ->
unit
(** The same for documents *)
val document_to_channel :
?omit_positions:bool ->
?enc:Netconversion.encoding ->
out_channel ->
'ext Pxp_document.document ->
unit
(* The same for documents. *)
(** The same for documents. *)
(** {2 Unmarshalling} *)
val subtree_from_cmd_sequence :
(unit -> reconstruction_cmd) ->
Pxp_dtd.dtd ->
'ext Pxp_document.spec ->
'ext Pxp_document.node
(* Reconstructs the subtree from a sequence of reconstruction_cmd values.
* The passed function is called to get the next reconstruction_cmd.
(** Reconstructs the subtree from a sequence of [reconstruction_cmd] values.
* The passed function is called repeatedly to get the stream of
* [reconstruction_cmd].
*
* If the DTD contains a namespace_manager:
* You must pass a namespace_manager to enable the namespace code.
......@@ -107,34 +121,49 @@ val subtree_from_channel :
Pxp_dtd.dtd ->
'ext Pxp_document.spec ->
'ext Pxp_document.node
(* Reconstructs the subtree from an in_channel. *)
(** Reconstructs the subtree from an [in_channel]. *)
val document_from_cmd_sequence :
(unit -> reconstruction_cmd) ->
Pxp_yacc.config ->
'ext Pxp_document.spec ->
'ext Pxp_document.document
(** The same for documents *)
val document_from_channel :
in_channel ->
Pxp_yacc.config ->
'ext Pxp_document.spec ->
'ext Pxp_document.document
(* The same for documents.
(** The same for documents.
*
* The character encoding of the node tree is set to the encoding of the
* configuration. If necessary, the read strings are recoded.
*)
(** {2 Relocation} *)
(** The term "relocation" is here used for creating a copy of a tree or
document by printing and reparsing. This can be useful, because other
model specifications can be used while building the copy (i.e. a different
set of classes is instantiated for the same elements).
The following functions avoid expensive reparsing, but take the shortcut
of decomposing the original tree into [reconstruction_cmd] sequences and
recombining them afterwards to create the copy.
*)
val relocate_subtree :
'ext_a Pxp_document.node ->
Pxp_dtd.dtd ->
'ext_b Pxp_document.spec ->
'ext_b Pxp_document.node
(* Creates a copy of the passed subtree by marshalling the tree, and
(** Creates a copy of the passed subtree by marshalling the tree, and
* restoring the marshaled tree. The new tree will have the passed DTD
* and the passed spec, i.e. this function can _change_ the DTD and the
* spec of an existing tree. Note that you can also change the type of
* and the passed spec, i.e. {b this function can change the DTD and the
* spec while copying a tree}. Note that you can also change the type of
* the extensions.