helm/DEVEL/pxp/pxp/compatibility/markup_reader.mli

   1 (* $Id$
   2  * ----------------------------------------------------------------------
   3  * Markup! The validating XML parser for Objective Caml.
   4  * Copyright by Gerd Stolpmann. See LICENSE for details.
   5  *
   6  * THIS IS THE markup-0.2.10 COMPATIBLE INTERFACE TO markup_reader.mli.
   7  * It corresponds to revision 1.3 of markup_reader.mli.
   8  *)
   9
  10 open Markup_types;;
  11
  12
  13 (* The class type resolver is the official type of all "resolvers".
  14  * Resolvers get file names (or better, external identifiers) and
  15  * return lexbufs, scanning the file for tokens. Resolvers may be
  16  * cloned, and clones can interpret relative file names relative to
  17  * their creator.
  18  *)
  19
  20 class type resolver =
  21   object
  22     (* A resolver can open a character source, and returns this source as
  23      * Lexing.lexbuf.
  24      * The resolver should recode the source into ISO-8859-1. By default,
  25      * a resolver should assume UTF-8 or UTF-16 encoding. Before
  26      * 'change_encoding' is invoked, the resolver should only return
  27      * lexbufs with one character. After 'change_encoding' has been invoked,
  28      * there is no character limit anymore.
  29      * 'change_encoding' can only be invoked once. This method is usually
  30      * called after the <? ... ?> prolog of the entity has been read.
  31      * If this method is not called, it is up to the resolver to find out
  32      * if UTF-8 or UTF-16 is used. It is recommended to invoke this method
  33      * with an empty string to indicate this situation.
  34      *)
  35     method open_in : ext_id -> Lexing.lexbuf
  36     method close_in : unit
  37     method change_encoding : string -> unit
  38
  39
  40     (* Every resolver can be cloned. The clone does not inherit the connection
  41      * with the external object, i.e. it is closed.
  42      *)
  43     method clone : resolver
  44
  45   end
  46 ;;
  47
  48
  49 (* The following class is the current main implementation of resolvers.
  50  * It fetches strings from an arbitrary source (by calling init_in, and
  51  * then repeatedly next_string), recodes them to ISO-8859-1, and creates
  52  * lexbufs for them.
  53  * It is not complete, as the source is missing.
  54  *
  55  * Note that 'resolve_general' may change in future revisions; it is ugly.
  56  *)
  57
  58 (* -- This API simulation does not provide 'resolve_general' any longer
  59
  60 class virtual resolve_general :
  61   collect_warnings ->
  62   object
  63     val mutable encoding : string
  64     val mutable encoding_requested : bool
  65     val warner : collect_warnings
  66
  67     method clone : resolver
  68
  69     method private warn : int -> unit
  70     method private autodetect : string -> unit
  71
  72     method private virtual next_string : string -> int -> int -> int
  73     method private virtual init_in : ext_id -> unit
  74     method virtual close_in : unit
  75
  76     method open_in : ext_id -> Lexing.lexbuf
  77
  78     method change_encoding : string -> unit
  79   end
  80 *)
  81
  82
  83 (* The next classes are resolvers for concrete input sources. *)
  84
  85 class resolve_read_channel :
  86   in_channel -> collect_warnings -> resolver;;
  87
  88   (* Reads from the passed channel (it may be even a pipe). Note that this
  89    * resolver cannot handle file inclusions, as it is pre-bound to a
  90    * specific channel and is not able to interpret file names.
  91    * That means, if there is a entity reference (something like &name; or
  92    * %name;) to parse, and the definition points to another file, the
  93    * resolver will fail.
  94    *)
  95
  96
  97 class resolve_read_string :
  98   string -> resolver;;
  99
 100   (* Reads from the passed string. As 'resolver_read_channel', this
 101    * resolver cannot handle file inclusions.
 102    *)
 103
 104
 105 class resolve_as_file :
 106   collect_warnings -> resolver;;
 107
 108   (* Reads from the local file system. Every file name is interpreted as
 109    * file name of the local file system, and the referred file is read.
 110    * This resolver can handle file inclusions as long as they do not
 111    * exceed the scope of the local file system (i.e. no URLs).
 112    *)
 113
 114 (* ======================================================================
 115  * History:
 116  *
 117  * $Log$
 118  * Revision 1.1  2000/11/17 09:57:30  lpadovan
 119  * Initial revision
 120  *
 121  * Revision 1.2  2000/07/08 17:40:50  gerd
 122  *      Updated the simulation.
 123  *
 124  * Revision 1.1  2000/05/29 23:43:51  gerd
 125  *      Initial compatibility revision.
 126  *
 127  * ======================================================================
 128  * OLD LOGS:
 129  *
 130  * Revision 1.3  2000/05/29 21:14:57  gerd
 131  *      Changed the type 'encoding' into a polymorphic variant.
 132  *
 133  * Revision 1.2  2000/05/20 20:31:40  gerd
 134  *      Big change: Added support for various encodings of the
 135  * internal representation.
 136  *
 137  * Revision 1.1  2000/03/13 23:41:54  gerd
 138  *      Initial revision.
 139  *
 140  *
 141  *)