`(sigil path)`

(sigil path) - Path Manipulation

Manipulate file paths as strings without touching the filesystem. Extract components, join paths, normalize . and .., and work with extensions. For operations that access the filesystem, see (sigil fs).

(import (sigil path))

(path-join "src" "lib" "utils.sgl")  ; => "src/lib/utils.sgl"
(path-dirname "/home/user/file.txt") ; => "/home/user"
(path-extname "document.pdf")        ; => ".pdf"
(path-stem "archive.tar.gz")         ; => "archive.tar"

Exports

path-absolute?procedure

Test if a path is absolute.

On Unix, absolute paths start with /. On Windows, absolute paths start with a drive letter or \\.

(path-absolute? "/home/user")    ; => #t
(path-absolute? "relative/path") ; => #f
(path-absolute? "./here")        ; => #f

path-relative?procedure

Test if a path is relative (not absolute).

A relative path does not start with a root (/ on Unix, drive letter on Windows). This is the complement of path-absolute?.

(path-relative? "src/main.sgl")  ; => #t
(path-relative? "./here")        ; => #t
(path-relative? "../parent")     ; => #t
(path-relative? "/home/user")    ; => #f

path-hidden?procedure

Test if a path refers to a hidden file.

On Unix-like systems, hidden files start with a dot. This checks the filename component, not the full path.

(path-hidden? ".gitignore")           ; => #t
(path-hidden? "/home/user/.bashrc")   ; => #t
(path-hidden? "visible.txt")          ; => #f
(path-hidden? "/home/.config/app")    ; => #f (app is not hidden)

path-dirnameprocedure

Get the directory portion of a path.

Returns everything before the final path separator. If there's no separator, returns . (current directory).

(path-dirname "/home/user/file.txt")  ; => "/home/user"
(path-dirname "src/main.sgl")         ; => "src"
(path-dirname "file.txt")             ; => "."
(path-dirname "/")                    ; => "/"

path-basenameprocedure

Get the last component of a path (the filename).

With an optional suffix argument, removes that suffix from the result.

(path-basename "/home/user/file.txt")         ; => "file.txt"
(path-basename "/home/user/file.txt" ".txt")  ; => "file"
(path-basename "src/lib/")                    ; => "lib"
(path-basename "foo")                         ; => "foo"

path-extnameprocedure

Get the file extension including the dot.

Returns the portion from the last . to the end. Returns an empty string if there's no extension.

(path-extname "document.pdf")    ; => ".pdf"
(path-extname "archive.tar.gz")  ; => ".gz"
(path-extname "Makefile")        ; => ""
(path-extname ".gitignore")      ; => ""
(path-extname "src/main.sgl")    ; => ".sgl"

path-joinprocedure

Join path components with the platform separator.

Handles multiple arguments and normalizes redundant separators.

(path-join "src" "lib" "utils.sgl")  ; => "src/lib/utils.sgl"
(path-join "/home" "user" "docs")    ; => "/home/user/docs"
(path-join "a" "" "b")               ; => "a/b"

path-splitprocedure

Split a path into its components.

Returns a list of path segments.

(path-split "/home/user/file.txt")  ; => ("/" "home" "user" "file.txt")
(path-split "src/lib/utils.sgl")    ; => ("src" "lib" "utils.sgl")
(path-split "file.txt")             ; => ("file.txt")

path-normalizeprocedure

Normalize a path by resolving . and .. components.

Does not access the filesystem—purely string manipulation. Collapses redundant separators and resolves relative components.

(path-normalize "src/../lib/./utils.sgl")  ; => "lib/utils.sgl"
(path-normalize "/home/user/../other")     ; => "/home/other"
(path-normalize "a//b///c")                ; => "a/b/c"

path-relativeprocedure

Compute a relative path from one location to another.

Returns a path that, when joined with from, would reach to.

(path-relative "/home/user/src" "/home/user/lib")
; => "../lib"

(path-relative "/a/b/c" "/a/b/c/d/e")
; => "d/e"

(path-relative "/a/b" "/x/y")
; => "../../x/y"

path-filenameprocedure

Get the filename portion of a path.

Alias for path-basename without suffix removal.

(path-filename "/home/user/document.pdf")  ; => "document.pdf"
(path-filename "src/main.sgl")             ; => "main.sgl"

path-stemprocedure

Get the filename without its extension.

Returns the base name with the extension stripped off.

(path-stem "/home/user/report.pdf")  ; => "report"
(path-stem "archive.tar.gz")         ; => "archive.tar"
(path-stem "Makefile")               ; => "Makefile"
(path-stem ".gitignore")             ; => ".gitignore"

path-replace-extnameprocedure

Replace a path's extension with a new one.

The new extension should include the leading dot.

(path-replace-extname "doc.txt" ".md")        ; => "doc.md"
(path-replace-extname "/src/main.sgl" ".sgb") ; => "/src/main.sgb"
(path-replace-extname "README" ".md")         ; => "README.md"

path-with-extnameprocedure

Ensure a path has the specified extension.

If the path already has the desired extension, returns it unchanged. Otherwise replaces any existing extension with the new one.

(path-with-extname "script" ".sgl")      ; => "script.sgl"
(path-with-extname "script.sgl" ".sgl")  ; => "script.sgl"
(path-with-extname "notes.txt" ".md")    ; => "notes.md"