Module Volgo_stdlib.Relative_pathSource

include module type of struct include Fpath_sexp0.Relative_path end
Sourcetype t = Fpath.t

The type of relative paths that never escape upward.

Note: Some versions of odoc may display this as type t = Fpath.t, but the actual definition is type t = private Fpath.t, which enforces the following invariants:

  • The path is relative (does not start with "/")
  • The path is normalized via Fpath.normalize
  • The normalized path does not contain leading ".." segments (does not escape upward)

This invariant is enforced at construction time: all functions that create values of type t (such as of_fpath, of_string, v, extend) will raise Invalid_argument if the resuling path would violate this property.

Examples:

  • v "a/b/c" ✓ (descends only)
  • v "a/../b" ✓ (normalizes to "b", no escaping)
  • v "./" ✓ (the empty path, stays at current level)
  • v ".." ✗ (escapes upward, raises Invalid_argument)
  • v "../a" ✗ (escapes then descends, raises Invalid_argument)
  • v "a/../.." ✗ (normalizes to "..", raises Invalid_argument)
Sourceval sexp_of_t : t -> Sexplib0.Sexp.t
Sourceval compare : t -> t -> int
Sourceval equal : t -> t -> bool
Sourceval hash : t -> int
Sourceval seeded_hash : int -> t -> int
Sourceval to_fpath : t -> Fpath.t
Sourceval to_string : t -> string
Sourceval of_fpath : Fpath.t -> t option

of_fpath p returns p normalized via Fpath.normalize and classified as a relative path. Returns None if p is not a relative path.

Raises Invalid_argument if the normalized path contains leading ".." segments (escapes upward).

Sourceval of_string : string -> (t, [ `Msg of string ]) Result.t

This is a convenient wrapper to compose Fpath.of_string and of_fpath.

Sourceval v : string -> t

v str returns a t or raises Invalid_argument.

Sourceval empty : t

The empty relative path "./".

Sourceval append : t -> t -> t

append t1 t2 appends relative path t2 to relative path t1 and normalizes the result via Fpath.normalize.

Raises Invalid_argument if the normalized result would escape upward (contains leading ".." segments).

Sourceval extend : t -> Fpath_sexp0.Fsegment.t -> t

extend t seg appends filesystem segment seg to path t and normalizes the result via Fpath.normalize.

Raises Invalid_argument if the normalized result would escape upward (contains leading ".." segments).

For example, extend empty (Fsegment.v "..") raises because it would create "../" which escapes upward.

Sourceval parent : t -> t option

parent t returns the parent directory of path t, or None if t has no parent.

Returns None when t is the empty relative path "./".

Raises Invalid_argument if t is an escaping path (contains leading ".." segments) (this should not occur for paths constructed through this module's API).

Sourceval of_list : Fpath_sexp0.Fsegment.t list -> t

of_list segments constructs a path from a list of filesystem segments by folding extend over the list starting from empty.

Raises Invalid_argument if any intermediate step during the fold would produce a path that escapes upward.

For example:

  of_list [ Fsegment.v "a"; Fsegment.v ".."; Fsegment.v ".." ]

raises because the second ".." would require going from "./" to "../". See extend for details.

Sourceval chop_prefix : t -> prefix:t -> t option

chop_prefix t ~prefix removes prefix prefix from path t.

Returns Some result where result is t with prefix removed, or None if prefix is not actually a prefix of t. When prefix is empty ("./"), returns Some t unchanged.

Sourceval chop_suffix : t -> suffix:t -> t option

chop_suffix t ~suffix removes suffix suffix from path t.

Returns Some result where result is t with suffix removed, or None if suffix is not actually a suffix of t. When suffix is empty ("./"), returns Some t unchanged.

When a non-empty suffix is successfully removed, the result is a directory path.

Sourceval is_dir_path : t -> bool
Sourceval to_dir_path : t -> t
Sourceval rem_empty_seg : t -> t
Sourceval to_dyn : t -> Dyn.t