Module Core_extended.Std.Filename

include Core.Filename

Warning! this library assumes we are in a POSIX compliant OS.

val root : string

The path of the root.

Pathname resolution

val realpath : string ‑> string

realpath path returns the canonicalized absolute pathname of path.

  • Raises Unix_error: on errors.
val is_posix_pathname_component : string ‑> bool

is_posix_pathname_component f

  • Returns true if f is a valid path component on a POSIX compliant OS

    Note that this checks a path component, and not a full path.

    http://www.opengroup.org/onlinepubs/000095399/basedefs/xbd_chap03.html#tag_03_169

temp_file ?perm ?in_dir_name prefix suffix

Returns the name of a fresh temporary file in the temporary directory. The base name of the temporary file is formed by concatenating prefix, then .tmp., then a 6-digit hex number, then suffix. The temporary file is created empty. The file is guaranteed to be fresh, i.e. not already existing in the directory.

val temp_file : ?⁠perm:int ‑> ?⁠in_dir:string ‑> string ‑> string ‑> string
val temp_dir : ?⁠perm:int ‑> ?⁠in_dir:string ‑> string ‑> string ‑> string
val temp_dir_name : string

The name of the temporary directory:

Under Unix, the value of the TMPDIR environment variable, or "/tmp" if the variable is not set.

Under Windows, the value of the TEMP environment variable, or "." if the variable is not set.

val open_temp_file : ?⁠perm:int ‑> ?⁠in_dir:string ‑> string ‑> string ‑> string * Core__.Import.Out_channel.t

Same as Core_filename.temp_file, but returns both the name of a fresh temporary file, and an output channel opened (atomically) on this file. This function is more secure than temp_file: there is no risk that the temporary file will be modified (e.g. replaced by a symbolic link) before the program opens it.

val current_dir_name : string

The conventional name for the current directory (e.g. . in Unix).

val parent_dir_name : string

The conventional name for the parent of the current directory (e.g. .. in Unix).

val dir_sep : string

The directory separator (e.g. / in Unix).

val concat : string ‑> string ‑> string

concat p1 p2 returns a path equivalent to p1 ^ "/" ^ p2. In the resulting path p1 (resp. p2) has all its trailing (resp. leading) "." and "/" removed. eg: concat "a/." ".//b" => "a/b" concat "." "b" => "./b" concat "a" "." => "a/." concat "a" "/b" => "a/b"

  • Raises Failure: if p1 is empty.
val is_relative : string ‑> bool

Return true if the file name is relative to the current directory, false if it is absolute (i.e. in Unix, starts with /).

val is_absolute : string ‑> bool
val is_implicit : string ‑> bool

Return true if the file name is relative and does not start with an explicit reference to the current directory (./ or ../ in Unix), false if it starts with an explicit reference to the root directory or the current directory.

val check_suffix : string ‑> string ‑> bool

check_suffix name suff returns true if the filename name ends with the suffix suff.

val chop_suffix : string ‑> string ‑> string

chop_suffix name suff removes the suffix suff from the filename name. The behavior is undefined if name does not end with the suffix suff.

val chop_extension : string ‑> string

Return the given file name without its extension. The extension is the shortest suffix starting with a period and not including a directory separator, .xyz for instance.

Raise Invalid_argument if the given name does not contain an extension.

val split_extension : string ‑> string * string option

split_extension fn return the portion of the filename before the extension and the (optional) extension. Example: split_extension "/foo/my_file" = ("/foo/my_file", None) split_extension "/foo/my_file.txt" = ("/foo/my_file", Some "txt") split_extension "/home/c.falls/my_file" = ("/home/c.falls/my_file", None)

val basename : string ‑> string

Respects the posix semantic.

Split a file name into directory name / base file name. concat (dirname name) (basename name) returns a file name which is equivalent to name. Moreover, after setting the current directory to dirname name (with Sys.chdir), references to basename name (which is a relative file name) designate the same file as name before the call to Sys.chdir.

The result is not specified if the argument is not a valid file name (for example, under Unix if there is a NUL character in the string).

val dirname : string ‑> string

See Filename.basename.

val split : string ‑> string * string

split filename returns (dirname filename, basename filename)

val parts : string ‑> string list

parts filename returns a list of path components in order. For instance: /tmp/foo/bar/baz -> "/"; "tmp"; "foo"; "bar"; "baz". The first component is always either "." for relative paths or "/" for absolute ones.

val of_parts : string list ‑> string

of_parts parts joins a list of path components into a path. It does roughly the opposite of parts, but they fail to be precisely mutually inverse because of ambiguities like multiple consecutive slashes and . components.

Raises an error if given an empty list.

val quote : string ‑> string

Return a quoted version of a file name, suitable for use as one argument in a command line, escaping all meta-characters. Warning: under Windows, the output is only suitable for use with programs that follow the standard Windows quoting conventions.

See Sys.quote for an alternative implementation that is more human readable but less portable.

include Extended_filename

Extensions to Core.Core_filename.

val normalize : string ‑> string

normalize path Removes as much "." and ".." from the path as possible. If the path is absolute they will all be removed.

val parent : string ‑> string

parent path The parent of the root directory is the root directory returns the path to the parent of path.

val make_relative : ?⁠to_:string ‑> string ‑> string

make_relative ~to_:src f returns f relative to src.

  • Raises Failure: if is_relative f <> is_relative src
val make_absolute : string ‑> string

make_absolute src Turn src into an absolute path expanded from the current working directory.

val expand : ?⁠from:string ‑> string ‑> string

expand Makes a path absolute and expands ~~username to home directories. In case of error (e.g.: path home of a none existing user) raises Failure with a (hopefully) helpful message.

val explode : string ‑> string list

Splits a given path into a list of strings.

val implode : string list ‑> string

dual to explode

val compare : string ‑> string ‑> int

Filename.compare is a comparison that normalizes filenames ("./a" = "a"), uses a more human ready algorithm based on String.collate ("rfc02.txt > rfc1.txt") and extenstions ("a.c" > "a.h").

It is a total comparison on normalized filenames.

val with_open_temp_file : ?⁠in_dir:string ‑> ?⁠write:(Pervasives.out_channel ‑> unit) ‑> f:(string ‑> 'a) ‑> string ‑> string ‑> 'a

with_open_temp_file ~write ~f prefix suffix create a temporary file; runs write on its out_channel and then f on the resulting file. The file is removed once f is done running.

val with_temp_dir : ?⁠in_dir:string ‑> string ‑> string ‑> f:(string ‑> 'a) ‑> 'a

Runs f with a temporary dir as option and removes the directory afterwards.

val is_parent : string ‑> string ‑> bool

is_parent dir1 dir2 returns true if dir1 is a parent of dir2

Note: This function is context independent, use expand if you want to consider relatives paths from a given point.

In particular:

  • A directory is always the parent of itself.
  • The root is the parent of any directory
  • An absolute path is never the parent of relative one and vice versa.
  • "../../a" is never the parent of "." even if this could be true given form the current working directory.