module type PathType =sig..end
Path functionality have this module type.type ustring
Path.OfRope it is Rope.t and in Path.OfString module it is string.type uchar
ustring type.module OperatorLift:sig..end
ustring type.
typet =ustring list
Examples: ["a";"b";"c"] is c/b/a (relative path); ["d";"e";""] stays for /e/d (absolute path).
All examples here and below are given for ustring=string case for clarity. To have the code working with other string types, one should prepend the !! operator (BatPathGen.PathType.OperatorLift.(!!)) to all string literals.
There are two infix operators provided to allow to write expressions in natural order. For example, to build a path using BatPathGen.PathType.Operators.(/:) one can write:
base_dir/:"bar" instead of "bar"::base_dir
However it may be sometimes inevitable to write components in reverse, for example:
let whose_readme = function "README"::app::"doc"::"share"::_ -> Some app | _ -> None
Windows: Windows absolute paths start with "\\" or with drive letter. Use following representation:
Path.root/:"."/:"pipe" = ["pipe";".";""] for "\\.\pipe"["C:"]/:"foo" = ["foo";"C:"] for "C:\foo"BatPathGen.PathType.default_validator).val is_relative : t -> bool
val is_absolute : t -> boolval root : t[""]). It is minimal absolute path. Below it is called 'empty'. However it yields "/" or "\\" when converted to a string.
Windows: This path (root and nothing more) is meaningless, but for simplicity it is considered valid here. To create absolute path starting with drive letter, construct the list explicitly (as in ["C:"]/:"foo").
A path consisting of drive letter only is also called 'empty' here.
val append : t -> ustring -> tBatPathGen.PathType.Operators.(/:)val concat : t -> t -> tBatPathGen.PathType.Operators.(//@)module Operators:sig..end
module Infix:sig..end
exception Malformed_path
val normalize_filepath : t -> t
normalize ([".."]/:"foo"/:"."/:"bar"/:"sub1"/:".."/:"sub2") = [".."]/:"foo"/:"bar"/:"sub1"/:".."/:"sub2"
When a directory structure contains links, it can be not pefectly pure tree. Then meaing of the ".." symbol depends on the real nature of parent of what is denoted by the name that preceded the ".." symbol. This symbol cannot be resolved for a graph traversal case when dealing with abstract paths only.
Windows: If single dot is next to root, it is preserved.
val normalize_in_graph : t -> tnormalize_filepath.val normalize_in_tree : t -> t
normalize ([".."]/:"foo"/:"."/:"bar"/:"sub1"/:".."/:"sub2") = [".."]/:"foo"/:"bar"/:"sub2"
This normalization is useful when dealing with paths that describe locations in a tree and the ".." symbol always points to the only parent of what precedes this symbol.
Windows: If single dot is next to root, it is preserved.
Raises Malformed_path when absolute path is given that contains double dots that would be applied to the root.
val normalize : t -> tnormalize_in_treeval parent : t -> tparent (foo/:bar) = fooInvalid_argument if empty path (relative [] or absolute [""]) is givenval belongs : t -> t -> boolbelongs base sub is true when sub descends from base, i.e. base is a prefix of sub. If base=sub the function returns true. It is otherwise false.
Both arguments must be absolute paths or both relative.
If both arguments have a root portion with drive letter and these letters are different, belongs base sub returns false.
Raises Invalid_argument if exactly one of given arguments is absolute path
val relative_to_any : t -> t -> trelative_to_any base sub returns relative path rel such that
normalize (base/:rel) = normalize sub, i.e. common base is stripped and ".." are added if necessary.
Both arguments must be absolute paths or both relative.
This function normalizes base and sub before calculation of the relative path.
Windows: If base and sub are absolute, they must have the same root element: have the same drive letter or both starting with BatPathGen.PathType.root (i.e. "" is the last element of the list).
Exceptionally it is possible to get an absolute path as a result if drive letter is in sub but not as a root element (e .g. base = root/:"bar" and sub = root/:bar//@(["C:"]/:"foo").
Raises
Invalid_argument if exactly one of given arguments is an absolute pathMalformed_path if normalization fails (see BatPathGen.PathType.normalize)relative_to_parent may be sometimes more suitableexception Not_parent
val relative_to_parent : t -> t -> trelative_to_parent parent sub returns relative path rel such that
(normalize parent)/:rel = normalize sub. It is checked if sub is really a descendant of parent.
Both arguments must be absolute paths or both relative.
This function normalizes base and sub before calculation of the relative path.
Windows: Exceptionally it is possible to get an absolute path as a result if drive letter is in sub but not as a root element (e .g. base = root/:"bar" and sub = root/:bar//@(["C:"]/:"foo")).
Raises
Not_parent if sub is not descendant of parentInvalid_argument if exactly one of given arguments is absolute pathMalformed_path if normalization fails (see BatPathGen.PathType.normalize)exception Illegal_char
BatPathGen.PathType.of_string, BatPathGen.PathType.append and BatPathGen.PathType.Operators.(/:) when used validator finds illegal character.typevalidator =ustring -> bool
If a name should be rejected for some other reason, user defined validator may raise an exception.
val default_validator : validator Pervasives.ref
Windows: Invalid characters are *?:\/<> and all with code <32. Exception: the function BatPathGen.PathType.of_string doesn't use validator against drive letter with colon.
val to_ustring : t -> ustringustring type. Empty relative path is converted to "." (single dot).
Windows: backslash is used as a separator and double backslash for root. If the path is only a drive letter (empty absolute path) trailing backslash is added (e.g. to_string ["C:"] = "C:\").
See also to_string is likely to bo more useful
"
val to_string : t -> stringto_ustring function.val of_string : ustring -> tPath.default_validator is applied to each resulting name.
Windows: both slashes '\' and '/' are accepted as separators. Paths of the 'semi-relative' form "C:foo\bar" are not recognized. For example "C:" string is parsed as ["C:"] which has different meaning (see BatPathGen.PathType.to_string).
Raises Illegal_char when a character not allowed in paths is found.
val s : t -> string
val p : ustring -> t
[], [""] or ["C:"].val name : t -> ustringname (foo/:bar) = barInvalid_argument if empty path (relative [] or absolute [""]) is givenval map_name : (ustring -> ustring) ->
t -> tmap_name fu path returns path with the name replaced by fu (BatPathGen.PathType.name path).
Example: map_name (fun nn -> nn ^ ".backup") (["foo"]/:"bar") = ["foo"]/:"bar.backup"
BatPathGen.PathType.default_validator is applied to new name.
Raises Illegal_char (raised by validator if any bad character is found)
val ext : t -> ustring option
ext ["aa.bb"] = Some "bb"
ext ["aa."] = Some ""
ext ["aa"] = None
ext [".hidden"] = Some "hidden" (!)
Extension begins where the rightmost dot in the name is found. If the name ends with a dot, the extension is empty and Some "" is returned. If there is no extension (no dot) the function returns None.
Raises Invalid_argument if empty path (relative [] or absolute [""]) is given
val map_ext : (ustring option -> ustring option) ->
t -> tmap_ext fu path returns path but with the name with extension given by fu (BatPathGen.PathType.ext path). If fu returns Some _, the original extension may be replaced (when Some ext is passed to fu) or new added (when fu gets None). In case fu returns None, the extension is removed (if exists).Illegal_char (raised by validator if any bad character is found)Invalid_argument if empty path (relative [] or absolute [""]) is givenval name_core : t -> ustringInvalid_argument if empty path (relative [] or absolute [""]) is giventypecomponents =t * ustring *
ustring option
path can be represented by the following triple:
(Path.parent path, Path.name_core path, Path.ext path)val split : t -> components
Resulting name_core string can be empty. For example,
Path.split (Path.root/:"home"/:"user"/:".bashrc") equals (Path.root/:"home"/:"user", "", Some "bashrc").
Raises Invalid_argument if empty path (relative [] or absolute [""]) is given
val join : components -> tIllegal_char (raised by validator on any bad character)val map : (components -> components) ->
t -> tIllegal_char (raised by validator on any bad character)Invalid_argument if empty path (relative [] or absolute [""]) is givenval drive_letter : t -> uchar option
Windows: drive_letter abs returns None if abs is simple absolute path (i.e. begins with a separator), otherwise the root element of abs consists of a letter ch with a colon - in this case Some ch is returned.
Other systems: Returns None on all absolute paths.
Raises Invalid_argument if relative path is given