+++ /dev/null
-(* $Id$
- * ----------------------------------------------------------------------
- *
- *)
-
-(* This module applies already O'Caml-3 features. *)
-
-(* Uniform Resource Locators (URLs):
- *
- * This module provides functions to parse URLs, to print URLs, to
- * store URLs, to modify URLs, and to apply relative URLs.
- *
- * URLs are strings formed according to pattern (1) or (2):
- *
- * (1) scheme://user:password@host:port/path;params?query#fragment
- * (2) scheme:other;params?query#fragment
- *
- * The word at the beginning of the URL identifies the URL scheme
- * (such as "http" or "file"). Depending on the scheme, not all of the
- * parts are allowed, or parts may be omitted. This module defines the
- * type 'url_syntax' whose values describe which parts are allowed/required/
- * not allowed for a concrete URL scheme (see below).
- *
- * Not all characters are allowed in a URL. Some characters are allowed,
- * but have the special task to separate the various parts of the URL
- * (reserved characters).
- * However, it is possible to include even invalid or reserved characters
- * as normal content by applying the '%'-encoding on these characters:
- * A '%' indicates that an encoded character follows, and the character
- * is denoted by a two-digit hexadecimal number (e.g. %2f for '/').
- * In the following descriptions, the term "encoded string" means a string
- * containing such %-encoded characters, and the "decoded string" means a
- * string not containing such characters.
- * See the module Netencoding.Url for functions encoding or decoding
- * strings.
- *
- * The type 'url' describes values storing the components of a URL,
- * and the 'url_syntax' for the URL. In general, the components are
- * stored as encoded strings; however, not for all components the
- * '%'-encoding is applicable.
- * For convenience, the functions creating, modifying, and accessing
- * URLs can handle both encoded and decoded strings. In order to
- * avoid errors, the functions pass strings even in their decoded form.
- *
- * Note that there is currently no function to compare URLs. The
- * canoncical comparison ( = ) is not applicable because the same URL
- * may be written differently.
- *
- * Note that nothing is said about the character set/encoding of URLs.
- * Some protocols and standards prefer UTF-8 as fundamental encoding
- * and apply the '%'-encoding on top of it; i.e. the byte sequence
- * representing a character in UTF-8 is '%'-encoded. There is no special
- * support for this technique.
- *
- * For more information about URLs, see RFCs 1738 and 1808.
- *)
-
-exception Malformed_URL
-(* Is raised by a number of functions when encountering a badly formed
- * URL.
- *)
-
-val extract_url_scheme : string -> string
- (* Returns the URL scheme from the string representation of an URL.
- * E.g. extract_url_scheme "http://host/path" = "http".
- * The scheme name is always converted to lowercase characters.
- * Raises Malformed_URL if the scheme name is not found.
- *)
-
-type url_syntax_option =
- Url_part_not_recognized
- | Url_part_allowed
- | Url_part_required
-
-
-type url_syntax =
- { url_enable_scheme : url_syntax_option;
- url_enable_user : url_syntax_option;
- url_enable_password : url_syntax_option;
- url_enable_host : url_syntax_option;
- url_enable_port : url_syntax_option;
- url_enable_path : url_syntax_option;
- url_enable_param : url_syntax_option;
- url_enable_query : url_syntax_option;
- url_enable_fragment : url_syntax_option;
- url_enable_other : url_syntax_option;
- url_accepts_8bits : bool;
- url_is_valid : url -> bool;
- }
-
-and url
-;;
-
-(* Values of type 'url_syntax' describe which components of an URL are
- * recognized, which are allowed (and optional), and which are required.
- * Not all combinations are valid; the predicate expressed by the
- * function 'url_syntax_is_valid' must hold.
- * The function 'url_is_valid' is applied when a fresh URL is created
- * and must return 'true'. This function allows it to add an arbitrary
- * validity criterion to 'url_syntax'. (Note that the URL passed to
- * this function is not fully working; you can safely assume that the
- * accessor functions url_scheme etc. can be applied to it.)
- *
- * Switch 'url_accepts_8bit': If 'true', the bytes with code 128 to
- * 255 are treated like alphanumeric characters; if 'false' these bytes
- * are illegal (but it is still possible to include such byte in their
- * encoded form: %80 to %FF).
- *
- * Values of type 'url' describe concrete URLs. Every URL must have
- * a fundamental 'url_syntax', and it is only possible to create URLs
- * conforming to the syntax. See 'make_url' for further information.
- *)
-
-
-val url_syntax_is_valid : url_syntax -> bool
- (* Checks whether the passed url_syntax is valid. This means:
- *
- * - If passwords are recognized, users (and hosts) must be recognized, too
- * - If ports are recognized, hosts must be recognized, too
- * - If users are recognized, hosts must be recognized, too
- * - Either the syntax recognizes one of the phrases
- * { user, password, host, port, path }, or the syntax recognized
- * the phrase 'other'.
- *)
-
-
-val partial_url_syntax : url_syntax -> url_syntax
- (* Transforms the syntax into another syntax where all required parts are
- * changed into optional parts.
- *)
-
-
-(* Note that all following url_syntaxes do not allow 8bit bytes. *)
-
-val null_url_syntax : url_syntax
-
-val ip_url_syntax : url_syntax
- (* Maximum syntax for IP based protocols *)
-
-val common_url_syntax : (string, url_syntax) Hashtbl.t
- (* Syntax descriptions for common URL schemes:
- *
- * null_url_syntax: nothing is recognized
- *
- * common_url_syntax: Hashtable mapping from URL scheme names to
- * definitions of syntaxes:
- *
- * "file": scheme, host?, path
- * "ftp": scheme, user?, password?, host, port?, path?, param?
- * "http": scheme, user?, password?, host, port?, path?, query?
- * "mailto": scheme, other
- *
- * Notes:
- * (1) These syntax descriptions can be weakened for partial/relative URLs
- * by changing the required parts to optional parts: See the function
- * 'partial_url_syntax'.
- * (2) None of the descriptions allows fragments. These can be enabled by
- * setting 'url_enable_fragment' to Url_part_allowed. E.g.
- * { file_url_syntax with url_enable_fragment = Url_part_allowed }
- *)
-
-val null_url : url
- (* A URL without any component and 'null_url_syntax'
- *)
-
-val make_url :
- ?encoded:bool ->
- ?scheme:string ->
- ?user:string ->
- ?password:string ->
- ?host:string ->
- ?port:int ->
- ?path:string list ->
- ?param:string list ->
- ?query:string ->
- ?fragment:string ->
- ?other:string ->
- url_syntax ->
- url
- (* Creates a URL from components:
- *
- * - The components "scheme" and "host" are simple strings to which the
- * '%'-encoding is not applicable.
- * - The component "port" is a simple number. Of course, the '%'-encoding
- * is not applicable, too.
- * - The components "user", "password", "query", "fragment", and "other"
- * are strings which may contains '%'-encoded characters. By default,
- * you can pass any string for these components, and problematic characters
- * are automatically encoded. If you set ~encoded:true, the passed
- * strings must already be encoded, but the function checks whether
- * the encoding is correct.
- * Note that for "query" even the characters '?' and '=' are encoded
- * by default, so you need to set ~encoded:true to pass a reasonable
- * query string.
- * - The components "path" and "param" are lists of strings which may
- * contain '%'-encoded characters. Again, the default is to pass
- * decoded strings to the function, and the function encodes them
- * automatically, and by setting ~encoded:true the caller is responsible
- * for encoding the strings.
- * path = [] and params = [] mean that no path and no parameters are
- * specified, respectively.
- * See below for the respresentation of these components.
- *
- * Except of "path", the strings representing the components do not
- * contain the characters separating the components from each other.
- * The "path" component includes the '/' at the beginning of the path
- * (if present).
- *
- * The created URL must conform to the 'url_syntax', i.e.
- * - The URL must only contain components which are recognized by the
- * syntax
- * - The URL must contain components which are required by the syntax
- * - The URL must fulfill the predicate expressed by the 'url_is_valid'
- * function of the syntax.
- *
- * The path of a URL is represented as a list of '/'-separated path
- * components. i.e.
- * [ s1; s2; ...; sN ] represents the path
- * s1 ^ "/" ^ s2 ^ "/" ^ ... ^ "/" ^ sN
- * As special cases:
- * [] is the non-existing path
- * [ "" ] is "/"
- * [ "";"" ] is illegal
- *
- * Except of s1 and sN, the path components must not be empty strings.
- *
- * To avoid ambiguities, it is illegal to create URLs with both relative
- * paths (s1 <> "") and host components.
- *
- * Parameters of URLs are components beginning with ';'. The list
- * of parameters is represented as list of strings where the strings
- * contain the value following ';'.
- *)
-
-val modify_url :
- ?syntax:url_syntax ->
- ?encoded:bool ->
- ?scheme:string ->
- ?user:string ->
- ?password:string ->
- ?host:string ->
- ?port:int ->
- ?path:string list ->
- ?param:string list ->
- ?query:string ->
- ?fragment:string ->
- ?other:string ->
- url ->
- url
- (* Modifies the passed components and returns the modified URL.
- * The modfied URL shares unmodified components with the original
- * URL.
- *)
-
-val remove_from_url :
- ?scheme:bool ->
- ?user:bool ->
- ?password:bool ->
- ?host:bool ->
- ?port:bool ->
- ?path:bool ->
- ?param:bool ->
- ?query:bool ->
- ?fragment:bool ->
- ?other:bool ->
- url ->
- url
- (* Removes the 'true' components from the URL, and returns the modified
- * URL.
- * The modfied URL shares unmodified components with the original
- * URL.
- *)
-
-val default_url :
- ?encoded:bool ->
- ?scheme:string ->
- ?user:string ->
- ?password:string ->
- ?host:string ->
- ?port:int ->
- ?path:string list ->
- ?param:string list ->
- ?query:string ->
- ?fragment:string ->
- ?other:string ->
- url ->
- url
- (* Adds missing components and returns the modified URL.
- * The modfied URL shares unmodified components with the original
- * URL.
- *)
-
-val undefault_url :
- ?scheme:string ->
- ?user:string ->
- ?password:string ->
- ?host:string ->
- ?port:int ->
- ?path:string list ->
- ?param:string list ->
- ?query:string ->
- ?fragment:string ->
- ?other:string ->
- url ->
- url
- (* Removes components from the URL if they have the passed value, and
- * returns the modified URL.
- * Note: The values must always be passed in _encoded_ form!
- * The modfied URL shares unmodified components with the original
- * URL.
- *)
-
-val url_syntax_of_url : url -> url_syntax
- (* Returns the 'url_syntax' record of a URL. *)
-
-val url_of_string : url_syntax -> string -> url
- (* Parses the passed string according to the passed url_syntax. *)
-
-val string_of_url : url -> string
- (* Returns the URL as string *)
-
-val url_provides :
- ?scheme:bool ->
- ?user:bool ->
- ?password:bool ->
- ?host:bool ->
- ?port:bool ->
- ?path:bool ->
- ?param:bool ->
- ?query:bool ->
- ?fragment:bool ->
- ?other:bool ->
- url ->
- bool
- (* Returns 'true' iff the URL has all of the components passed with
- * 'true' value.
- *)
-
-val url_scheme : url -> string
-val url_user : ?encoded:bool -> url -> string
-val url_password : ?encoded:bool -> url -> string
-val url_host : url -> string
-val url_port : url -> int
-val url_path : ?encoded:bool -> url -> string list
-val url_param : ?encoded:bool -> url -> string list
-val url_query : ?encoded:bool -> url -> string
-val url_fragment : ?encoded:bool -> url -> string
-val url_other : ?encoded:bool -> url -> string
- (* Return components of the URL. The functions return decoded strings
- * unless ~encoded:true is set.
- * If the component does not exist, the exception Not_found
- * is raised.
- *)
-
-val split_path : string -> string list
- (* Splits a '/'-separated path into components (e.g. to set up the
- * ~path argument of make_url).
- * E.g. split_path "a/b/c" = [ "a"; "b"; "c" ],
- * split_path "/a/b" = [ ""; "a"; "b" ],
- * split_path "a/b/" = [ "a"; "b"; "" ]
- *)
-
-val join_path : string list -> string
- (* Concatenates the path components (reverse function of split_path).
- *)
-
-val norm_path : string list -> string list
- (* Removes "." and ".." from the path if possible. Deletes double slashes.
- *
- * EXAMPLES:
- *
- * norm_path ["."] = []
- * means: "." = ""
- * norm_path ["."; ""] = []
- * means: "./" = ""
- * norm_path ["a"; "."] = ["a"; ""]
- * means: "a/." = "a/"
- * norm_path ["a"; "b"; "."] = ["a"; "b"; ""]
- * means: "a/b/." = "a/b/"
- * norm_path ["a"; "."; "b"; "."] = ["a"; "b"; ""]
- * means: "a/./b/." = "a/b/"
- * norm_path [".."] = [".."; ""]
- * means: ".." = "../"
- * norm_path [".."; ""] = [".."; ""]
- * means: "../" = "../"
- * norm_path ["a"; "b"; ".."; "c" ] = ["a"; "c"]
- * means: "a/b/../c" = "a/c"
- * norm_path ["a"; "b"; ".."; "c"; ""] = ["a"; "c"; ""]
- * means: "a/b/../c/" = "a/c/"
- * norm_path ["";"";"a";"";"b"] = [""; "a"; "b"]
- * means: "//a//b" = "/a/b"
- * norm_path ["a"; "b"; ""; ".."; "c"; ""] = ["a"; "c"; ""]
- * means: "a/b//../c/" = "a/c/"
- * norm_path ["a"; ".."] = []
- * means: "a/.." = ""
- *)
-
-
-val apply_relative_url : url -> url -> url
- (* apply_relative_url base rel:
- * Interprets 'rel' relative to 'base' and returns the new URL. This
- * function implements RFC 1808.
- *)
-
-val print_url : url -> unit
- (* Printer for the toploop. *)
-
-(* ---------------------------------------------------------------------- *)
-
-(* EXAMPLES:
- *
- * let http = Hashtbl.find common_url_syntax "http";;
- * let u = url_of_string http "http://g:pw@host/a/%62/";;
- * string_of_url u;;
- * --> "http://g:pw@host/a/%62/"
- * url_scheme u;;
- * --> "http"
- * url_user u;;
- * --> "g"
- * url_password u;;
- * --> "pw"
- * url_host u;;
- * --> "host"
- * url_path u;;
- * --> [ ""; "a"; "b"; "" ] (* sic! *)
- * url_path ~encoded:true u;;
- * --> [ ""; "a"; "%62"; "" ]
- * let v = make_url
- * ~path:[ ".."; "c" ]
- * ~fragment:"near-the-#-character"
- * { (partial_url_syntax http) with url_enable_fragment = Url_part_allowed };;
- * string_of_url v;;
- * --> "../c#near-the-%23-character"
- * let u' = modify_url ~syntax:(url_syntax_of_url v) u;;
- * (* u does not permit fragments *)
- * let w = apply_relative_url u' v;;
- * string_of_url w;;
- * --> "http://g:pw@host/c#near-the-%23-character"
- *)
-
-(* ======================================================================
- * History:
- *
- * $Log$
- * Revision 1.1 2000/11/17 09:57:27 lpadovan
- * Initial revision
- *
- * Revision 1.3 2000/06/26 22:57:49 gerd
- * Change: The record 'url_syntax' has an additional component
- * 'url_accepts_8bits'. Setting this option to 'true' causes that
- * the bytes >= 0x80 are no longer rejected.
- *
- * Revision 1.2 2000/06/25 22:55:47 gerd
- * Doc update.
- *
- * Revision 1.1 2000/06/24 20:19:59 gerd
- * Initial revision.
- *
- *
- *)
projects / helm.git / blobdiff