54.1.7 Components of Unix pathnames

The following functions accept as argument a string or bytevector representing a Unix pathname and return a string or bytevector; the returned value is not always a newly built object, so we must not mutate it.

The following bindings are exported by the library (vicare parser-tools unix-pathnames). Identifiers whose name is prefixed with $ are bound to unsafe operations which do not validate their arguments.

Function: extension obj

Function: $bytevector-extension bv

Function: $string-extension str

Return a string or bytevector representing the extension of obj, which must be a valid Unix pathname string or bytevector representation. The extension of a pathname is the sequence of characters from the end up to the first dot character before the first slash character; the returned value does not include the dot character and can be empty.

If the dot is the first character in the pathname’s last segment: return the empty bytevector because we interpret this pathname as representing a Unix–style “hidden” filename or dirname.

$bytevector-extension assumes that bv satisfies the predicate bytevector-pathname?. $string-extension assumes that str satisfies the predicate string-pathname?.

#!vicare
(import (vicare)
  (prefix (vicare parser-tools unix-pathnames) uxptn.))

(define-syntax-rule (doit ?pathname)
  (uxptn.extension ?pathname))

(doit "ciao.it")                ⇒ "it"
(doit "ciao")                   ⇒ ""
(doit "/path/to/file.ext")      ⇒ "ext"
(doit "/path/to/file.")         ⇒ ""
(doit "/path/to/file")          ⇒ ""
(doit "/path/to/file.ext/ab")   ⇒ ""
(doit "/path/to/some.file.ext") ⇒ "ext"
(doit "a/")                     ⇒ ""
(doit "a.")                     ⇒ ""
(doit ".")                      ⇒ ""
(doit "..")                     ⇒ ""
(doit "...")                    ⇒ ""
(doit ".a")                     ⇒ ""
(doit ".emacsrc")               ⇒ ""
(doit "..a")                    ⇒ "a"
(doit "...a")                   ⇒ "a"
(doit "..a.b")                  ⇒ "b"
(doit "~/.")                    ⇒ ""
(doit "~/..")                   ⇒ ""
(doit "~/...")                  ⇒ ""
(doit "~/.a")                   ⇒ ""
(doit "~/.emacsrc")             ⇒ ""
(doit "~/..a")                  ⇒ "a"
(doit "~/...a")                 ⇒ "a"
(doit "~/..a.b")                ⇒ "b"

(doit '#ve(ascii "/path/to/file.ext"))
⇒ #ve(ascii "ext")

Function: dirname obj

Function: $bytevector-dirname bv

Function: $string-dirname str

Return a string or bytevector representing the dirname of obj, which must be a valid Unix pathname string or bytevector representation. The dirname of a pathname is the sequence of characters from the beginning up to the last slash character; the returned value does not include the slash character and is never empty: when there is no directory part in the pathname, the returned value represents the current directory as single dot. Notice that contiguous slashses are “collapsed” into one slash.

$bytevector-dirname assumes that bv satisfies the predicate bytevector-pathname?. $string-dirname assumes that str satisfies the predicate string-pathname?.

#!vicare
(import (vicare)
  (prefix (vicare parser-tools unix-pathnames) uxptn.))

(define-syntax-rule (doit ?pathname)
  (uxptn.dirname ?pathname))

(doit "/path/to/file.ext")      ⇒ "/path/to"
(doit "file.ext")               ⇒ "."
(doit "/file.ext")              ⇒ "/"
(doit "//file.ext")             ⇒ "/"
(doit "/path/to///file.ext")    ⇒ "/path/to"
(doit "//////file.ext")         ⇒ "/"
(doit "a/b")                    ⇒ "a"
(doit "a")                      ⇒ "."
(doit "../a")                   ⇒ ".."
(doit "./a")                    ⇒ "."
(doit "../abcd")                ⇒ ".."
(doit "./abcd")                 ⇒ "."
(doit "../abcd/efgh")           ⇒ "../abcd"
(doit "./abcd/efgh")            ⇒ "./abcd"
(doit "/ciao/")                 ⇒ "/"
(doit "ciao/")                  ⇒ "."
(doit "./ciao/")                ⇒ "."
(doit "hello/ciao/")            ⇒ "hello"
(doit "//////")                 ⇒ "/"
(doit "ciao//////")             ⇒ "."

(doit '#ve(ascii "/path/to/file.ext"))
⇒ #ve(ascii "/path/to")

Function: tailname obj

Function: $bytevector-tailname bv

Function: $string-tailname str

Return a string or bytevector representing the tailname of obj, which must be a valid Unix pathname string or bytevector representation. The tailname of a pathname is its last segment; the returned value does not include the leading slash character, if any, and it cannot be empty; the only exception is when the argument represents the root directory, in which case the returned value is the dot segment. When the whole obj is the tailname: the returned value is obj itself.

$bytevector-tailname assumes that bv satisfies the predicate bytevector-pathname?. $string-tailname assumes that str satisfies the predicate string-pathname?.

#!vicare
(import (vicare)
  (prefix (vicare parser-tools unix-pathnames) uxptn.))

(define-syntax-rule (doit ?pathname)
  (uxptn.tailname ?pathname))

(doit "/path/to/file.ext")      ⇒ "file.ext"
(doit "file.ext")               ⇒ "file.ext"
(doit "/file.ext")              ⇒ "file.ext"
(doit "//file.ext")             ⇒ "file.ext"
(doit "/path/to///file.ext")    ⇒ "file.ext"
(doit "//////file.ext")         ⇒ "file.ext"
(doit "a/b")                    ⇒ "b"
(doit "a")                      ⇒ "a"
(doit "../a")                   ⇒ "a"
(doit "./a")                    ⇒ "a"
(doit "../abcd")                ⇒ "abcd"
(doit "./abcd")                 ⇒ "abcd"
(doit "../abcd/efgh")           ⇒ "efgh"
(doit "./abcd/efgh")            ⇒ "efgh"
(doit "/ciao/")                 ⇒ "ciao"
(doit "ciao/")                  ⇒ "ciao"
(doit "./ciao/")                ⇒ "ciao"
(doit "hello/ciao/")            ⇒ "ciao"
(doit "ciao//////")             ⇒ "ciao"
(doit "/")                      ⇒ "."
(doit "//////")                 ⇒ "."

Function: rootname obj

Function: $bytevector-rootname bv

Function: $string-rootname str

Return a string or bytevector representing the rootname of obj, which must be a valid Unix pathname string or bytevector representation. The rootname of a pathname is the sequence of characters from the beginning up to the last dot character before the extension, in other words: everything but the extension; the returned value does not include the dot character and cannot be empty.

If the dot is the first character in the pathname’s last segment: return the whole bytevector because we interpret such pathname as representing a Unix–style “hidden” filename or dirname. If the last segment represents the uplevel directory (it is the double–dot): return the full pathname. The return value can be the argument itself.

$bytevector-rootname assumes that bv satisfies the predicate bytevector-pathname?. $string-rootname assumes that str satisfies the predicate string-pathname?.

#!vicare
(import (vicare)
  (prefix (vicare parser-tools unix-pathnames) uxptn.))

(define-syntax-rule (doit ?pathname)
  (uxptn.rootname ?pathname))

(doit "ciao.it")                ⇒ "ciao"
(doit "ciao")                   ⇒ "ciao"
(doit "/path/to/file.ext")      ⇒ "/path/to/file"
(doit "/path/to/file.")         ⇒ "/path/to/file"
(doit "/path/to/file")          ⇒ "/path/to/file"
(doit "/path/to/file.ext/ab")   ⇒ "/path/to/file.ext/ab"
(doit "/path/to/some.file.ext") ⇒ "/path/to/some.file"
(doit "a/")                     ⇒ "a"
(doit "a.")                     ⇒ "a"
(doit ".")                      ⇒ "."
(doit "..")                     ⇒ ".."
(doit "...")                    ⇒ ".."
(doit ".a")                     ⇒ ".a"
(doit ".emacsrc")               ⇒ ".emacsrc"
(doit "..a")                    ⇒ "."
(doit "...a")                   ⇒ ".."
(doit "..a.b")                  ⇒ "..a"
(doit "~/.")                    ⇒ "~/."
(doit "~/..")                   ⇒ "~/.."
(doit "~/...")                  ⇒ "~/.."
(doit "~/.a")                   ⇒ "~/.a"
(doit "~/.emacsrc")             ⇒ "~/.emacsrc"
(doit "~/..a")                  ⇒ "~/."
(doit "~/...a")                 ⇒ "~/.."
(doit "~/..a.b")                ⇒ "~/..a"
(doit "///")                    ⇒ "/"
(doit "ciao///")                ⇒ "ciao"
(doit "ciao.it///")             ⇒ "ciao"
(doit "ciao.it.en///")          ⇒ "ciao.it"

Function: strip-trailing-slashes obj

Function: $bytevector-strip-trailing-slashes bv

Function: $string-strip-trailing-slashes str

Return a string or bytevector representing the argument with the trailing slashes stripped, if any. If there are no trailing slashes: return obj itself.

$bytevector-strip-trailing-slashes assumes that bv satisfies the predicate bytevector-pathname?. $string-strip-trailing-slashes assumes that str satisfies the predicate string-pathname?.

#!vicare
(import (vicare)
  (prefix (vicare parser-tools unix-pathnames) uxptn.))

(define-syntax-rule (doit ?pathname)
  (uxptn.strip-trailing-slashes ?pathname))

(doit "/path/to/file.ext")      ⇒ "/path/to/file.ext"
(doit "/path/to/file.ext///")   ⇒ "/path/to/file.ext"
(doit "/")                      ⇒ "/"
(doit "///")                    ⇒ "/"

Function: split obj

Function: $bytevector-split bv

Function: $string-split str

Split into segments the argument obj, which must be a valid Unix pathname string or bytevector representation. Return 2 values: a boolean, true if the pathname is absolute; null or a proper list of bytevectors representing the segments. The returned segments are normalised by removing, when possible, segments representing the current directory and segments representing the uplevel directory.

$bytevector-split assumes that bv satisfies the predicate bytevector-pathname?. $string-split assumes that str satisfies the predicate string-pathname?.

#!vicare
(import (vicare)
  (prefix (vicare parser-tools unix-pathnames) uxptn.))

(define-syntax-rule (doit ?pathname)
  (uxptn.split ?pathname))

(doit "/path/to/file.ext")
⇒ #t (#ve(ascii "path")
       #ve(ascii "to")
       #ve(ascii "file.ext"))

(doit "path/to/file.ext")
⇒ #f (#ve(ascii "path")
       #ve(ascii "to")
       #ve(ascii "file.ext"))

(doit "ciao//")         ⇒ #f (#ve(ascii "ciao"))
(doit "/")              ⇒ #t ()
(doit ".")              ⇒ #f ()
(doit "..")             ⇒ #f (#ve(ascii ".."))
(doit "ciao/..")        ⇒ #f ()
(doit "/.")             ⇒ #t ()
(doit "/..")            ⇒ #t ()
(doit "/ciao/..")       ⇒ #t ()

Function: normalise obj

Function: $bytevector-normalise bv

Function: $string-normalise str

Normalise the argument obj, which must be a valid Unix pathname string or bytevector representation, by removing, when possible, segments representing the current directory and segments representing the uplevel directory. The result of this function is not a full canonicalisation as can be performed by a system function like the POSIX realpath().

$bytevector-normalise assumes that bv satisfies the predicate bytevector-pathname?. $string-normalise assumes that str satisfies the predicate string-pathname?.

#!vicare
(import (vicare)
  (normalise (vicare parser-tools unix-pathnames) uxptn.))

(define-syntax-rule (doit ?pathname)
  (uxptn.normalise ?pathname))

(doit "/path/to/file.ext")      ⇒ "/path/to/file.ext"
(doit "path/to/file.ext")       ⇒ "path/to/file.ext"
(doit "ciao//")                 ⇒ "ciao"
(doit "/")                      ⇒ "/"
(doit ".")                      ⇒ "."
(doit "..")                     ⇒ ".."
(doit "ciao/..")                ⇒ "."
(doit "/.")                     ⇒ "/"
(doit "/..")                    ⇒ "/"
(doit "/ciao/..")               ⇒ "/"

Function: prefix? obj1 obj2

Function: $bytevector-prefix? bv1 bv2

Function: $string-prefix? str1 str2

Given two strings or two bytevectors representing valid and normalised Unix pathname representations: return #t if the first is the prefix of the second, otherwise return #f. The result of this function is fully reliable only if the arguments are absolute pathnames resulting from the canonicalisation performed by a system function like the POSIX realpath().

$bytevector-prefix? assumes that bv1 and bv2 satisfy the predicate bytevector-pathname?. $string-prefix? assumes that str1 and str2 satisfy the predicate string-pathname?.

#!vicare
(import (vicare)
  (prefix (vicare parser-tools unix-pathnames) uxptn.))

(define-syntax-rule (doit ?pathname)
  (uxptn.prefix? ?pathname))

(doit "/path/to/file.ext" "/path/to/file.ext") ⇒ #t
(doit "/path/to/"         "/path/to/file.ext") ⇒ #t
(doit "/path/from"        "/path/to/file.ext") ⇒ #f

Function: suffix? obj1 obj2

Function: $bytevector-suffix? bv1 bv2

Function: $string-suffix? str1 str2

Given two strings or two bytevectors representing valid and normalised Unix pathname representations: return #t if the first is the suffix of the second, otherwise return #f. The result of this function is fully reliable only if the arguments are absolute pathnames resulting from the canonicalisation performed by a system function like the POSIX realpath().

$bytevector-suffix? assumes that bv1 and bv2 satisfy the predicate bytevector-pathname?. $string-suffix? assumes that str1 and str2 satisfy the predicate string-pathname?.

#!vicare
(import (vicare)
  (suffix (vicare parser-tools unix-pathnames) uxptn.))

(define-syntax-rule (doit ?pathname)
  (uxptn.suffix? ?pathname))

(doit "/path/to/file.ext" "/path/to/file.ext") ⇒ #t
(doit "/to/file.ext"      "/path/to/file.ext") ⇒ #t
(doit "/from/file.ext"    "/path/to/file.ext") ⇒ #f

Function: prepend obj1 obj2

Function: $bytevector-prepend bv1 bv2

Function: $string-prepend str1 str2

Given two strings or two bytevectors representing valid Unix pathnames: prepend the first to the second and return the result.

$bytevector-prepend assumes that bv1 and bv2 satisfy the predicate bytevector-pathname?. $string-prepend assumes that str1 and str2 satisfy the predicate string-pathname?.

#!vicare
(import (vicare)
  (suffix (vicare parser-tools unix-pathnames) uxptn.))

(define-syntax-rule (doit ?pathname)
  (uxptn.prepend ?pathname))

(doit "/path/to" "file.ext")    ⇒ "/path/to/file.ext"
(doit "/" "path/to/file.ext")   ⇒ "/path/to/file.ext"
(doit "." "path/to/file.ext")   ⇒ "./path/to/file.ext"
(doit ".." "path/to/file.ext")  ⇒ "../path/to/file.ext"

Function: append obj1 obj2

Function: $bytevector-append bv1 bv2

Function: $string-append str1 str2

Given two strings or two bytevectors representing valid Unix pathnames: append the first to the second and return the result.

$bytevector-append assumes that bv1 and bv2 satisfy the predicate bytevector-pathname?. $string-append assumes that str1 and str2 satisfy the predicate string-pathname?.

#!vicare
(import (vicare)
  (suffix (vicare parser-tools unix-pathnames) uxptn.))

(define-syntax-rule (doit ?pathname)
  (uxptn.append ?pathname))

(doit "file.ext" "/path/to")    ⇒ "/path/to/file.ext"
(doit "path/to/file.ext" "/")   ⇒ "/path/to/file.ext"
(doit "path/to/file.ext" ".")   ⇒ "./path/to/file.ext"
(doit "path/to/file.ext" "..")  ⇒ "../path/to/file.ext"

Function: replace-extension ptn ext

Function: $bytevector-replace-extension ptn-bv ext-bv

Function: $string-replace-extension ptn-str ext-str

Given a string representing a valid Unix pathname and a string representing a valid Unix pathname segment, or a bytevector representing a valid Unix pathname and a bytevector representing a valid Unix pathname segment: strip the extension from the pathname and append the segment to the result as new extension.

$bytevector-replace-extension assumes that ptn-bv satisfies the predicate bytevector-pathname? and that ext-bv satisfies the predicate bytevector-segment?. $string-replace-extension assumes that ptn-str satisfies the predicate string-pathname? and that ext-str satisfies the predicate string-segment?.

#!vicare
(import (vicare)
  (suffix (vicare parser-tools unix-pathnames) uxptn.))

(define-syntax-rule (doit ?pathname ?extension)
  (uxptn.replace-extension ?pathname ?extension))

(doit "file.one"          "two") ⇒ "file.two"
(doit "/path/to/file.one" "two") ⇒ "/path/to/file.two"
(doit ".emacs"            "elc") ⇒ ".emacs.elc"
(doit "/path/to/.emacs"   "elc") ⇒ "/path/to/.emacs.elc"

(doit "/"   "ext")
error→ &unix-pathname-normalisation-error

(doit "///" "ext")
error→ &unix-pathname-normalisation-error

(doit "."   "ext")
error→ &unix-pathname-normalisation-error

(doit ".."  "ext")
error→ &unix-pathname-normalisation-error

Function: uri-representation obj

Function: $bytevector-uri-representation bv

Function: $string-uri-representation str

Return a string or bytevector being the URI representation of obj, which must be a valid Unix pathname string or bytevector representation.

$bytevector-uri-representation assumes that bv satisfies the predicate bytevector-pathname?. $string-uri-representation assumes that str satisfies the predicate string-pathname?.

#!vicare
(import (vicare)
  (suffix (vicare parser-tools unix-pathnames) uxptn.))

(define-syntax-rule (doit ?pathname)
  (uxptn.uri-representation ?pathname))

(doit "/path/to/file.ext")      ⇒ "file:///path/to/file.ext"
(doit "path/to/file.ext")       ⇒ "file:path/to/file.ext"