Module Superbol_cache.Canon

Canonicalisation of the paths that appear in witnesses.

Witnesses only ever need to match on the machine that recorded them, so this performs no portable normalisation: it applies the conventions of the running system. What it must guarantee is that two spellings of one path that the same system considers equal --- notably differing only in case on Windows and macOS, or in separators, or in redundant . and .. components --- canonicalise to one string.

Symbolic links are deliberately left unresolved: doing so requires I/O outside the cache directory, which this library does not perform.

val strip_extraneous_components : string -> string

strip_extraneous_components p removes redundant . and .. components from a path.

val path : case_insensitive:bool -> string -> string

path ~case_insensitive p is the canonical form of p.

Separators are normalised to '/', repeated separators are collapsed, . components are dropped, and .. components are resolved lexically against the preceding one. Leading .. components of a relative path are kept, as there is nothing to resolve them against. A trailing separator is dropped, except on a root. When case_insensitive holds, the result is lowercased.

Note that a lexical .. resolution is only sound in the absence of symbolic links; it matches the behaviour callers already get from the paths they build for copybook lookup.

val listing : case_insensitive:bool -> Stdlib.String.t list -> string

listing ~case_insensitive names is the canonical rendering of a list of strings (like a directory listing), suitable for digesting. Entries are canonicalised as single path components, deduplicated, and sorted, so that the digest does not depend on the order in which the underlying system happened to report them.