Batteries user guide : BatPathGen.OfString

# Module BatPathGen.OfString

    module OfString: PathType  with type ustring = string and type uchar = char

This implementation can be used with UTF-8, but encoding of used strings is not verified.

    type ustring

Type of strings used. In case of `Path.OfRope` it is `Rope.t` and in `Path.OfString` module it is `string`.

    type uchar

Type of characters. It corresponds to `ustring` type.

    module OperatorLift: sig .. end

Convenience operator for lifting primitive strings to `ustring` type.

    type t = ustring list

A type for storing paths. It is reversed list of names. In case of absolute path, the last element of the list is empty string (Windows: empty or letter-colon; details below). Empty list represents empty relative path.

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"

In principle the first type of paths has broader range of allowed characters, but this implementation applies more strict rules to both (`BatPathGen.PathType.default_validator`).

    val is_relative : t -> bool

    val is_absolute : t -> bool

###### Construction

    val root : t

Root of the filesystem (`[""]`). 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 -> t

Alternative name for `BatPathGen.PathType.Operators.(/:)`

    val concat : t -> t -> t

Alternative name for `BatPathGen.PathType.Operators.(//@)`

    module Operators: sig .. end

Infix operators for path construction.

    module Infix: sig .. end

As other Operators modules in batteries are named "Infix" we provide Infix as well.

    exception Malformed_path

    val normalize_filepath : t -> t

Consumes single dots where possible, e.g.:

`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 -> t

Another name for `normalize_filepath`.

    val normalize_in_tree : t -> t

Consumes single dots and applies double dots where possible, e.g.:

`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 -> t

Deprecated name for `normalize_in_tree`

    val parent : t -> t

Returns parent path, i.e. immediate ancestor: `parent (foo/:bar) = foo`
Raises `Invalid_argument` if empty path (relative `[]` or absolute `[""]`) is given

    val belongs : t -> t -> bool

`belongs 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 -> t

`relative_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 path
- `Malformed_path` if normalization fails (see `BatPathGen.PathType.normalize`)

See also `relative_to_parent` may be sometimes more suitable

    exception Not_parent

    val relative_to_parent : t -> t -> t

`relative_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 `parent`
- `Invalid_argument` if exactly one of given arguments is absolute path
- `Malformed_path` if normalization fails (see `BatPathGen.PathType.normalize`)

###### Validation

    exception Illegal_char

Raised by `BatPathGen.PathType.of_string`, `BatPathGen.PathType.append` and `BatPathGen.PathType.Operators.(/:)` when used validator finds illegal character.

    type validator = ustring -> bool

Validators should check if all characters of given string can be used in a name (path component). Return true if the name is valid. Return false if illegal character is found.

If a name should be rejected for some other reason, user defined validator may raise an exception.

    val default_validator : validator Pervasives.ref

Forward slash and code zero are considered invalid.

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.

###### Conversions

    val to_ustring : t -> ustring

Convert to the chosen `ustring` 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 -> string

Convert to type primitive string with UTF-8 content. The string is built in the same way as by `to_ustring` function.

    val of_string : ustring -> t

Parse path in a given string. Any number of consecutive separators collapse ("a//b" becomes "a/b"). `Path.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.

Convenience aliases

    val s : t -> string

= `BatPathGen.PathType.to_string`

    val p : ustring -> t

= `BatPathGen.PathType.of_string`

###### Name related functions

These funtions do not accept empty paths, i.e. `[]`, `[""]` or `["C:"]`.

    val name : t -> ustring

Returns name of the object the pathname points to, i.e. `name (foo/:bar) = bar`
Raises `Invalid_argument` if empty path (relative `[]` or absolute `[""]`) is given

    val map_name : (ustring -> ustring) ->
           t -> t

`map_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

Returns extension of the name of the object the pathname points to. Examples:

`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 -> t

`map_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).
Raises

- `Illegal_char` (raised by validator if any bad character is found)
- `Invalid_argument` if empty path (relative `[]` or absolute `[""]`) is given

    val name_core : t -> ustring

Returns part of the name to the left of rightmost dot. Returns empty string if the name starts with a dot.
Raises `Invalid_argument` if empty path (relative `[]` or absolute `[""]`) is given

    type components = t * ustring *
           ustring option

A `path` can be represented by the following triple: `(Path.parent path, Path.name_core path, Path.ext path)`

    val split : t -> components

Dissect the path to its components (parent path, core part of name and possibly an extension).

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 -> t

Create a path from given components.
Raises `Illegal_char` (raised by validator on any bad character)

    val map : (components -> components) ->
           t -> t

Map a path through a function that operates on separate components.
Raises

- `Illegal_char` (raised by validator on any bad character)
- `Invalid_argument` if empty path (relative `[]` or absolute `[""]`) is given

###### Supplementary functions

    val drive_letter : t -> uchar option

Return drive letter of the given absolute path.

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