Module B0_std.Fpath

module Fpath: sig .. end
File paths.

A file system path specifies a file or a directory in a file system hierarchy. It is made of three parts:

  1. An optional, platform-dependent, volume.
  2. An optional root directory separator B0_std.Fpath.dir_sep whose presence distiguishes absolute paths ("/a") from relative ones ("a")
  3. A non-empty list of B0_std.Fpath.dir_sep separated segments. Segments are non empty strings except for maybe the last one. The latter syntactically distiguishes directory paths ("a/b/") from file paths ("a/b").

The paths segments "." and ".." are relative path segments that respectively denote the current and parent directory. The basename of a path is its last non-empty segment if it is not a relative path segment or the empty string otherwise (e.g. on "/").

Separators and segments

val dir_sep_char : char
dir_sep_char is the platform dependent natural directory separator. This is / on POSIX and \ on Windows.
val dir_sep : string
dir_sep is B0_std.Fpath.dir_sep_char as a string.
val is_seg : string -> bool
is_seg s is true iff s does not contain a B0_std.Fpath.dir_sep or a null byte.
val is_rel_seg : string -> bool
is_rel_seg s is true iff s is a relative segment in other words either "." or "..".


type t 
The type for paths
val v : string -> t
v s is the string s as a path.

Warning. In code only use "/" as the directory separator even on Windows platforms (don't be upset, the module gives them back to you with backslashes).
Raises Invalid_argument if s is not a valid path. Use B0_std.Fpath.of_string to deal with untrusted input.

val add_seg : t -> string -> t
add_seg p seg if p's last segment is non-empty this is p with seg added. If p's last segment is empty, this is p with the empty segment replaced by seg.
Raises Invalid_argument if is_seg seg is false.
val append : t -> t -> t
append p q appends q to p as follows:
val (/) : t -> string -> t
p / seg is add_seg p seg. Left associative.
val (//) : t -> t -> t
p // p' is append p p'. Left associative.

Directory paths

Note. The following functions use syntactic semantic properties of paths. Given a path, these properties can be different from the ones your file system attributes to it.

val is_dir_path : t -> bool
is_dir_path p is true iff p syntactically represents a directory. This means that p is ., .. or ends with /, /. or /...
val to_dir_path : t -> t
to_dir_path p is add_seg p "". It ensures that the resulting path represents a directory and, if converted to a string, that it ends with a B0_std.Fpath.dir_sep.

Basename and parent directory

Note. The following functions use syntactic semantic properties of paths. Given a path, these properties can be different from the ones your file system attributes to it.

val basename : t -> string
basename p is the last non-empty segment of p or the empty string otherwise. The latter occurs only on root paths and on paths whose last non-empty segment is a relative segment.
val parent : t -> t
parent p is a directory path that contains p. If p is a root path this is p itself. If p is in the current directory this is ./.

Predicates and comparison

val is_rel : t -> bool
is_rel p is true iff p is a relative path, i.e. the root directory separator is missing in p.
val is_abs : t -> bool
is_abs p is true iff p is an absolute path, i.e. the root directory separator is present in p.
val is_root : t -> bool
is_root p is true iff p is a root directory, i.e. p has the root directory separator and a single, empty, segment.
val is_current_dir : t -> bool
is_current_dir p is true iff p is either "." or "./".
val is_parent_dir : t -> bool
is_parent_dir p is true iff p is either ".." or "../".
val equal : t -> t -> bool
equal p0 p1 is true iff p0 and p1 are stringwise equal.
val equal_basename : t -> t -> bool
equal_basename p0 p1 is String.equal (basename p0) (basename p1).
val compare : t -> t -> int
compare p0 p1 is a total order on paths compatible with B0_std.Fpath.equal.

File extensions

The file extension (resp. multiple file extension) of a path segment is the suffix that starts at the last (resp. first) occurence of a '.' that is preceeded by at least one non '.' character. If there is no such occurence in the segment, the extension is empty. With these definitions, ".", "..", "..." and dot files like ".ocamlinit" or "..ocamlinit" have no extension, but ".emacs.d" and "..emacs.d" do have one.

type ext = string 
The type for file extensions, '.' separator included.
val get_ext : ?multi:bool -> t -> ext
get_ext p is p's basename file extension or the empty string if there is no extension. If multi is true (defaults to false), returns the multiple file extension.
val has_ext : ext -> t -> bool
has_ext ext p is true iff String.equal (get_ext p) e || String.equal (get_ext ~multi:true p) e.
val mem_ext : ext list -> t -> bool
mem_ext exts p is List.exists (fun e -> has_ext e p) exts
val add_ext : ext -> t -> t
add_ext ext p is p with ext concatenated to p's basename.
val rem_ext : ?multi:bool -> t -> t
rem_ext ?multi p is p with the extension of p's basename removed. If multi is true (defaults to false), the multiple file extension is removed.
val set_ext : ?multi:bool -> ext -> t -> t
set_ext ?multi p is add_ext ext (rem_ext ?multi p).
val cut_ext : ?multi:bool -> t -> t * ext
cut_ext ?multi p is (rem_ext ?multi p, get_ext ?multi p).
val (+) : t -> ext -> t
p + ext is add_ext p ext. Left associative.
val (-+) : t -> ext -> t
p -+ ext is set_ext p ext. Left associative.


val of_string : string -> (t, string) Pervasives.result
of_string s is the string s as a path. The following transformations are performed on the string: An error returned if s is "" or if it contains a null byte. The error string mentions s.
val to_string : t -> string
to_string p is the path p as a string. The result can be safely converted back with B0_std.Fpath.v.
val conv : t B0_std.Conv.t
conv converts file paths. The textual representation uses non-empty atoms. See also B0_std.Fpath.conv_only.
val conv_only : t B0_std.Conv.t
conv_only converts file paths. Textual conversion is not composable, use B0_std.Fpath.conv instead. Textual encoding pass the string as is and decoding ignores the initial starting point and parses the whole input string into a file path.
val pp : t B0_std.Fmt.t
pp ppf p prints path p on ppf using B0_std.Fpath.to_string.
val pp_quoted : t B0_std.Fmt.t
pp_quoted p prints path p on ppf using Filename.quote.
val dump : t B0_std.Fmt.t
dump ppf p prints path p on ppf using B0_std.String.dump.


val uniquify : t list -> t list
uniquify ps is ps without duplicates, the list order is preserved.

Paths map and sets

type path = t 
module Set: sig .. end
Path sets.
module Map: sig .. end
Path maps.

Search paths

A search path is a list of paths separated by a designated separator. A well known search path is PATH in which executable binaries are looked up.

val search_path_sep : string
search_path_sep is the default platform specific separator for search paths, this is ";" if Sys.win32 is true and ":" otherwise.
val list_of_search_path : ?sep:string -> string -> (t list, string) Pervasives.result
list_of_search_path ~sep s parses sep separated file paths from s. sep is not allowed to appear in the file paths, it defaults to B0_std.Fpath.search_path_sep. The order in the list matches the order from left to right in s.