More.FilepathFile paths.
A file path is a syntactic representation of a file or directory location on a file system. Functions of this module operate on this syntactic representation regardless of the file system and mostly regardless of the file path syntax mandated by the current platform.
For this module a file path is made of two parts:
C: in a DOS path, \\server\share in a Windows UNC path, \\.\UNC\server\share in a Windows DOS device path or //volume in a POSIX file path.A mandatory path which is made of:
/a versus a.a/b/ from syntactic file paths like a/b. These syntactic distinctions may not match the semantics that the file system attributes to a path.Platform-dependent behaviours. When we talk about POSIX it means any platform but Windows. This module parses and normalizes both POSIX and Windows file path syntaxes and preserves their semantics regardless of the current platform according to this strategy. Some values and function behaviours do however depend on the current platform.
Volume preservation. Unless indicated otherwise functions operating on the path of file paths preserve volumes and do not attribute any meaning to them.
Character encoding. The module operates only on US-ASCII code points and does not otherwise deal with character encoding issues. It will work with any character encoding compatible with US-ASCII, which pretty much means: UTF-8.
Directory separators are used to separate path segments.
Warning. Use the predicate functions to test for directory separators: for example on Windows there is more than one valid directory separator.
platform_sep is windows_sep if Sys.win32 is true and posix_sep otherwise.
platform_sep_str is platform_sep as a string.
is_posix_sep c is true iff c is posix_sep.
is_windows_sep c is true iff c is windows_sep or posix_sep.
is_platform_sep c is is_windows_sep if Sys.win32 is true and is_posix_sep otherwise.
is_any_sep is is_windows_sep (it includes is_posix_sep).
val fmt : ('a, Stdlib.Format.formatter, unit, t) Stdlib.format4 -> 'afmt … is Fmt.kstr make ….
append p q appends q to p as follows:
q is absolute or has a volume and the volume is different from p's volume then q is returned.q's segments to p using append_segment.See examples.
Most of the time, and especially for dealing with command line arguments, you should just use of_string and to_string. See the path syntax strategy.
val of_string : string -> (t, string) Stdlib.resultof_string s parses s as a path using of_windows_path except if s is prefixed by posix: in which case of_posix_path is used. See the path syntax strategy for the rationale and the table summary for a more visual account of what it entails.
val to_string : t -> stringto_string p converts p to a file path suitable for the platform's operating system function acting on files. This uses to_windows_path if Sys.win32 is true and to_posix_path otherwise.
Warning. Platform-dependent and potentially lossy, use to_preserved_path to preserve all the information.
val to_preserved_path : t -> stringto_preserved_path p renders the path using:
to_string if has_volume p is false.to_posix_path if has_posix_volume p is true.to_windows_path otherwiseval to_url_path : ?escape_space:bool -> t -> stringto_url_path ~escape_space p is the path p as an URL path. This is the segments of p separated by '/' and with the following characters percent encoded: '%', '?', '#', ' ' (if escape_space is true, default), and the US-ASCII control characters.
If Sys.win32 is true and p has a drive a '/' is prepended to the result. (TODO why?)
Note. In 2019, the standard definition of URLs is in a sorry state. Assuming p is UTF-8 encoded. It is believed the above function should lead to an URL path component that can be parsed by HTML5's definition of URL parsing.
val of_posix_path : string -> (t, string) Stdlib.resultof_posix_path s parses and normalizes s into a file path by assuming that s is a POSIX file path. The function errors if and only if s is "" or contains a null byte. The error message has the form Fmt.str "%s: <error>" s.
Normalization collapse any sequence of / to a single /. However if if the prefix of s has the exact form: //volume, the //volume substring is taken to be the volume and the rest is normalized. If there s end after the volume / is appended.
See these examples.
val to_posix_path : t -> stringto_posix_path p converts p to a POSIX path. If has_windows_drive p is true the volume is dropped.
Note. If p is the result of of_posix_path this results, modulo normalization, in a lossless roundtrip.
val of_windows_path : string -> (t, string) Stdlib.resultof_windows_path s parses and normalizes s into a file path by assuming that s is a Windows path. The function errors if and only if s is "" or contains a null bytes. The error message has the form Fmt.str "%s: <error>" s.
Conceptually normalization first converts any / to \, then collapses any sequence of \ to a single \, except two initial \\ are preserved.
After this if:
s is a traditional DOS path, the volume is the drive, for example: C: and if there is no path after that it defaults to .. A drive is an arbitrary non-empty segment followed by a :.s is an UNC path, the volume is the host name and the share name with the \\ prefix, for example: \\Server\share and if there is no path after that it defaults to \. If only a single segment is present the initial \\ is normalized to a single \ and the result treated as a regular path, \\Server is the path \Server.s is an DOS device path, the volume is the first two segments after \\ or four if the device is UNC. For example: \\?\C:, \\.\BootPartition, \\.\UNC\Server\Share and if there no path after that it default to \. If less than the number of required segments are provided the initial \\ is normalized to a single segment and the result treated as a regular path, for example \\.\UNC\ is \.\UNC.Note. If the function succeeds technically you may still have an illegal Windows path. For example hey: will parse as a drive but it's not a legal drive. There are also a couple of reserved characters that are disallowed in segments which are not checked for.
See these examples.
val to_windows_path : t -> stringto_windows_path p converts p to a Windows path. If has_posix_volume p is true the volume is dropped.
val to_shell_string : t -> stringto_shell_string p converts p to a file path suitable for specifying on the command line of the platform's operating system shell (understood as powershell on Windows not cmd.exe). is like to_string but uses to_shell_windows_path if Sys.win32 is true or to_shell_posix_path otherwise.
val to_shell_posix_path : t -> (string, string) Stdlib.resultto_shell_posix_path p is like to_posix_path but quotes the path if needed.
val to_shell_windows_path : t -> (string, string) Stdlib.resultto_shell_windows_path p is like to_windows_path but quotes
val take_volume : t -> stringtake_volume p is the volume of p or "" if there is no volume. Windows volumes are always given to you with \ separators regardless of the platform. POSIX volumes are always given to you with the leading // regardless of the platform.
with_volume vol p makes a path with volume vol and segments drop_volume p. If vol is "" behaves like drop_volume.
val has_volume : t -> boolhas_volume p is true if and only if p has a volume.
val has_posix_volume : t -> boolhas_posix_volume p is true if and only if p has a POSIX volume.
val has_windows_volume : t -> boolhas_windows_volume p is true if and only if p has a Windows volume.
val has_windows_drive : t -> boolhas_windows_drive p is true if and only if p has a Windows volume and it is a Windows drive (vs. an UNC path or a DOS device path).
is_posix_volume s is true iff s starts with // and has otherwise no null byte or /.
is_windows_volume s is true iff s is a Windows drive, an UNC path or a Windows device path.
is_windows_drive s is true iff s is a Windows drive, that is an alphabetical ASCII letter followed by ':'.
If you are looking for the predicate it is is_absolute or is_relative.
drop_root_sep p is the path of p without its root directory separator. To ensure that result is a relative path, this also drops the volume unless the volume is a windows drive. If the path of p is \ or /, the resulting path is ..
ensure_root_sep p is the path of p prefixed by a root directory separator unless it already has one. The result is guaranteed to be absolute and the volume of p is preserved. If the path of p is exactly . or .. the relative segment is dropped and the path is simply /.
append_segment p seg is:
p with the last segment replaced by seg, if the last segment is empty.p with segment seg added, otherwiseThis errors if is_segment seg is false. FIXME error format.
p / seg is append_segment p seg |> Result.get_ok'. Left associative. Warning. Use append_segment to deal with untrusted seg values.
val take_last_segment : t -> stringtake_last_segment p is the last segment of p, this is "" on syntactic directory paths or is_root paths. See also basename.
drop_last_segment p is p without it's last segment. This is p on is_root and "." on singleton paths. See also parent and syntactic directory paths.
cut_last_segment p is (drop_last_segment p, take_last_segment p).
val to_segments : t -> string listto_segments p is p's non-empty list of segments prefixed by an empty string in the front if p is absolute. This allows to recover the path's string with String.concat natural_dir_sep, note however that you may have lost the volume along the way. Also if you want to convert to an URL path rather use to_url_path.
val of_segments : ?volume:string -> string list -> tof_segments segs is a path from the given list of segments. Absolute paths are represented with an empty string in the front, see to_segments. The root is represented by ["";""]. volume if non-empty is used as the volume of the path, note that on POSIX this turns a relative list of segments into an absolute one. Spurious empty segments are dropped, except for the last one.
is_segment s is true iff s does not contain a null byte or a directory separator as asserted by is_sep.
Warning. Strictly speaking the function is wrong both POSIX or Windows file path segments. On POSIX \ can be part of a segment and on Windows there are a couple of reserved characters that this module does not bother to assert.
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 : ?drop_exts:bool -> t -> stringbasename 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. If drop_exts is true (default to false) the basename's multiple extension, if any, is removed from the segment.
The basename of a path is the last non-empty segment if it is not a relative segment. In the latter case the basename is the empty string "" for example on the paths / or a/...
basepath is like basename but returns a file path with the result or "." if the result is empty which can be detected by is_current_dir.
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 ".".
The file extension (resp. multiple file extensions) 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 a single one.
TODO In the fpath package we correct e.g. has_ext if the given ext has no ext. I think we should either check and raise Invalid_argument or correct.
val exists_ext : t -> boolexists_ext p is true iff p has a file or multiple file extension.
val exists_multi_ext : t -> boolexists_multi_ext p is true iff p has a multiple file extension.
has_ext ext p is true iff String.equal (take_ext n multi:false p) e || String.equal (take_ext ~multi:true p) e.
take_ext ~multi p is the file extension or multiple file extension if multi is true of the basename of p.
The empty string is returned if there is no extension. By definition this operates on the directory name of directory paths, not on the final empty segment.
drop_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.
append_ext p ext is p with ext concatenated to p's basename.
Note. ext is not required to start with a . it can be used for arbitrary basename extension.
with_ext ~multi ext p is append_ext ext (drop_ext ~multi p).
p + ext is append_ext p ext. Left associative.
A null file path represents a file on the current platform that discards all writes and returns end of file on reads.
Warning. Use the predicate functions to test for null paths. For example on Windows the test has to be made in a case insensitive manner.
val posix_null : tposix_null is the path /dev/null.
val windows_null : tnull_windows is the path NUL.
val platform_null : tplatform_null is windows_null if Sys.win32 is true and posix_null otherwise.
val is_posix_null : t -> boolis_null_posix p is equal p null_posix.
val is_windows_null : t -> boolis_windows_posix p tests that the last segment of p is windows_null in a case-insensitive manner (note, only approximates Windows' notion of null it seems).
val is_platform_null : t -> boolis_platform_null is is_posix_null if Sys.win32 is true and is_posix_null otherwise.
val is_any_null : t -> boolis_any_null p is is_posix_null p || is_windows_null p.
The - relative path is commonly used in command line interfaces to denote standard input or output.
val dash : tdash is the path -.
val is_dash : t -> boolis_dash p is equal p dash.
Warning. On Windows each volume maintains its own current directory so it is generaly not a good idea to assume there is a single path representing the current or parent directory, use is_current_dir or is_parent_dir to test them.
val is_current_dir : t -> boolis_current_dir p is true if the path of p is either . or ./.
val is_parent_dir : t -> boolis_parent_dir p is true if the path of p is either .. or ../.
try_drop_relative_dirs p is a path which points to the same object as p but which removes relative "." and ".." as much as possible. The volume and the syntactic directoryness of p is preserved. If:
p is absolute the result has no relative directory segments (".." going above the root are equated with the root).p is relative the result is either "." or has possibly only a sequence of parent segments at the start.See also Root separator.
Warning. Do not assume there is a single root path and that this root is /, use is_root to test for root paths. For example on Windows every volume has a root.
val is_root : t -> boolis_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_syntactic_dir : t -> boolis_syntactic_dir p is true iff p syntactically represents a directory. This means that p is ".", ".." or ends with "/", "/." or "/..".
Note. This a syntactic check, the file system may attribute different properties to these paths.
ensure_trailing_dir_sep p is add_segment p "". This ensures that p has a final empty segment and thus a trailing directory separator when converted to a string.
drop_trailing_dir_sep p ensures p has no final empty segment unless p is a root path. When p is not a root path this ensure that p has no trailing directory separator when converted to a string.
strictly_start_with ~prefix p is true iff p starts with prefix but is not prefix itself regardless of directoryness. Otherwise said if prefix is a strict prefix of p that respects path segments.
More formally the invocation returns true iff the following two conditions hold:
not Fpath.(equal (to_dir_path prefix) (to_dir_path p))Fpath.(String.starts_with ~prefix:(to_string (to_dir_path prefix) (to_string p))) is trueWarning. By definition stricty_starts_with ~prefix:p p is false. Note also that the prefix relation does not entail directory containement; for example stricly_starts_with ~prefix:(v "..") (v "../..") holds. It holds however if you Os.Path.realpath the paths.
drop_strict_prefix prefix p is:
None if strictly_starts_with ~prefix p is false.Some q otherwise where q is p without the string prefix Fpath.to_dir_path prefix. This means that q is always relative, that it preserves p's syntactic directoryness and that Fpath.(equal (prefix // q) p) holds.Warning. By definition strip_strict_prefix p p is None.
remove_strictly_prefixed ps is ps without elements that have a strict prefixes in ps. Basically if a path p strictly prefixes another in ps, only p is kept. The list order is preserved. Duplicates are not removed, use distinct for this.
reroot ~src_root ~dst_root p assumes src_root strictly prefixes p removes the prefix and prepends dst_root to the result.
Raises Invalid_argument if dst_root is not a strict prefix of src. In particular note that p cannot be src_root.
relative ~to_dir p is q such that to_dir // q represents the same path as p. Note that q is not necessarily relative: if to_dir is relative and p is absolute p is returned.
Warning. This function is mostly broken at the moment.
Raises Invalid_argument if path to_dir contains "..".
val is_relative : t -> boolis_relative p is true iff p is a relative path, i.e. the root directory separator is missing in p.
val is_absolute : t -> boolis_absolute p is true iff p is an absolute path, i.e. the root directory separator is present in p.
equal p0 p1 is true iff p0 and p1 are stringwise equal. If the function returns false this does not mean that p0 and p1 do not perhaps point to the same object on the file system. In general if you want to assert that use More.Os.Path.realpath on the paths before using equal.
equal_basename p0 p1 is String.equal (basename p0) (basename p1).
type path := tmodule Set : sig ... endPath sets.
module Map : sig ... endPath maps.
sort_by_parent ps maps elements of ps by their Fpath.parent.
val sort_by_ext : multi:bool -> Set.t -> Set.t String.Map.tsort_by_ext ~multi ps maps elements of ps by their extension as determined by Fpath.take_ext ~multi.
A search path is a list of paths separated by a designated separator in which elements are looked up in left to right priority order. A well known search path is PATH in which executable binaries are looked up.
search_path_sep is the default platform specific separator for search paths. This is ";" if Sys.win32 and ":" otherwise.
val list_of_search_path :
?sep:string ->
string ->
(t list, string) Stdlib.resultlist_of_search_path ~sep s splits s on sep (defaults to search_path_sep) and parses the result with of_string, ignoring empty strings.
This means that sep is not allowed to appear in the file paths, consecutive sep are ignored and the order in the resulting list matches the left-to-right order of paths in s.
If one of_string errors on a path p with e the function errors with the message:
Fmt.str "Illegal path %a in search path: %s" pp p epp ppf p prints path p on ppf. The path is quoted with Filename.quote if needed. For now this means if it contains spaces (U+0020).
val error :
t ->
('b, Stdlib.Format.formatter, unit, ('a, string) Stdlib.result)
Stdlib.format4 ->
'berror p fmt … is Fmt.error ("%a: " ^^ fmt) pp_unquoted p … .
val prefix_msg : t -> string -> stringprefix_msg p msg is Fmt.str "%a: %s" pp_unquoted msg.
Similar to newline handling, it is unrealistic to make path parsing and rendering dependent on the current platform. Once you have configuration files or scripts that are written on a platform and processed on another one, you immediately get foreign paths to process, foreign paths to render and file path command line arguments with mixed / and \ separators.
Therefore a goal of the design is that it should allow, on every platform, be able to handle all current platform paths according to their allowed syntax while accepting the occasional foreign path or the odd mixed separator path without having to invoke platform specific functions.
Trying to respond to these problems by adding types for platform dependent paths is inconvenient and does not solve the problem of paths with mixed separators. Instead we propose the following base strategy which is a tradeoff:
of_string parses a Windows path using of_windows_path. The reason is that Windows allows both / and \ separators and POSIX paths are almost (see below) a subset of Windows paths.to_string renders the volume and path using the current platform directory separator (even if that may end up being absurd).Now this approach suffers from these problems:
of_string unconditionally parses the string a\b to the path a/b and a first segment with a drive like C: to the path C:.. However these can be (rather rare) valid filenames on POSIX.of_string unconditionally parses file paths that starts with // as Windows UNC paths. This may not necessarily be a problem but it is incompatible with the (rarely used) notion of "POSIX volume" which treats only the first segment after a // in a platform dependent manner.of_posix_syntax will be interpreted as an UNC path if rendered with to_string.Given that in practice these problems occur with low probability, we stick to the base idea and let programs use of_string and to_string to get good all round cross-platform path handling but provide the following escape hatch for users that need to specify POSIX file paths that contain \ or : in files names:
of_string s, if s starts with posix: the prefix is dropped and the result is parsed with of_posix_path instead of of_windows_path.TODO. Now this means that of_string on Windows may render
to_string, on a path that has segments with backlashes is rendered with / separators and prefixed posix:. This results in errors if given to file system APIs but there's not much we can do anyways.In scenarios where the provenance of paths is known and more precise error the following lossless functions can be used. They will round trip paths (of_string/to_string does not).
of_posix_path, to_posix_path for explicit POSIX paths.of_windows_path, to_windows_path for explicit Windows paths.If you want to preserve path information as much as possible use of_string and render them with Filepath.to_preserved_path.
Finally here are ideas that we ended up not pursing:
Filepath.to_preserved_path. They are also hard to round-trip without introducing escaping mecanisms.file: URL protocol instead of the ad-hoc posix: escape hatch. Adding URL to the mix brings in a significant bagage with including new escaping mecanisms that are not needed by the simple prefixing scheme we propose.of_string using some sort of directory separator sniffing to trigger either of_posix_path or of_windows_path. That doesn't really work for the problem of paths with mixed directory separators.We think it's better not to try to be too smart about all this and allow to inject as much strings as possible into the representation and rather have the operating file system APIs generate the errors.
The table below indicates via the volume and segments columns how paths are parsed by of_string regardless of the platform. The to_posix_path and to_windows_path indicate how they are rendered on the given platform by to_string which simply selects these functions based on Sys.win32.
A few notes on the table:
posix: path separators can be specified as / or \ in the Path column and ? can be replaced by . to yield the same result.of_string succeeds neither to_posix_path nor to_windows_path is guaranted to be a valid path for the platform. For example a CC: drive can't exist on windows.to_windows_path conversion of posix:c:a/b. However doing syntactic security checks on filepaths without first Unix.realpathing them is wrong in the first place.TODO. I don't think it's a good idea in to_windows_path to render c:a without prefixing. Also it's
Path volume segments to_posix_path to_windows_path ---------------- ------------- -------- --------------- --------------- a/b a/b a/b a\b /a/b /a/b /a/b \a\b a/b:c a/b:c a/b:c a\b:c //v/a/b \\v\a /b //v/a/b \\v\a\b //v/a \\v\a / //v/a/ \\v\a\ //v /v /v \v // / / \ posix://v/a/b //v /a/b //v/a/b \a\b posix://v //v / //v/ \ posix:/a/b\c /a/b\c /a/b\c \a\b\c posix:c:a/b c:a/b c:a/b c:a/b a\b a/b a/b a\b \a\b /a/b /a/b \a\b C:a\b C: a/b a/b C:a\b C:\a\b C: /a/b /a/b C:\a\b C: C: . . C:. CC:a\b CC:a/b CC:a/b CC:a\b \\m\sh\a\b \\m\sh /a/b //m/sh/a/b \\m\sh\a\b \\m\sh\ \\m\sh / //m/sh/ \\m\sh\ \\m\sh \\m\sh / //m/sh/ \\m\sh\ \\m\ /m/ /m/ \m \\m /m /m \m \\ / / \ \\?\dev\a\b \\?\dev /a/b //?/dev/a/b \\?\dev\a\b \\?\dev\ \\?\dev / //?/dev/ \\?\dev\ \\?\dev \\?\dev / //?/dev/ \\?\dev\ \\?\UNC\m\sh\a\b \\?\UNC\m\sh /a/b //?/UNC/m/sh/a/b \\?\UNC\m\sh\a\b \\?\UNC\m\sh\ \\?\UNC\m\sh / //?/UNC/m/sh/ \\?\UNC\m\sh\ \\?\UNC\m\sh \\?\UNC\m\sh / //?/UNC/m/sh/ \\?\UNC\m\sh\ \\?\UNC\m\ /?/UNC/m/ /?/UNC/m/ \?\UNC\m\ \\?\UNC\m /?/UNC/m /?/UNC/m \?\UNC\m \\?\UNC /?/UNC /?/UNC \?\UNC \\?\ /?/ /?/ \?\ \\? /? /? \?
For reading clarity we avoid quoting and escaping so the examples are shown in pseudo code.
The presence of // on the right side of the equality means that a volume has been parsed.
Filepath.of_posix_path ///a/b = /a/b Filepath.of_posix_path //a/b = //a/b Filepath.of_posix_path //a/ = //a/ Filepath.of_posix_path //a = //a/ Filepath.of_posix_path // = / Filepath.of_posix_path /// = /
The presence of // on the right side of the equality means that a volume has been parsed. Any / can be replaced by a \ and vice-versa.
Filepath.of_windows_path ///a/b = //a/b/ Filepath.of_windows_path //a/b = //a/b/ Filepath.of_windows_path //a/ = //a/ Filepath.of_windows_path //a = //a/ Filepath.of_windows_path // = / Filepath.of_posix_path /// = /
Filepath.append /a/ b/c = /a/b/c Filepath.append /a /b/c = /b/c Filepath.append C:a \a\b = \a\b Filepath.append C:a C:b = C:a\b Filepath.append C:\a C:b = C:\a\b Filepath.append C:\a D:b = D:b Filepath.append \a C:b = C:b