Path Manipulation

The following are simple functions to manipulate common PATH-like strings.

Warning

Throughout these examples, var is a symbol and so, in all probability, you will need to quote the name:

path-append 'PATH "/usr/local/bin"

function path-append var val [keyword arguments]

A wrapper to path-modify’s append function.

Param var:

the name of the path to be manipulated, eg. PATH, CLASSPATH

Type var:

symbol

Param val:

the path element(s) to be added, sep separated

Type val:

string

See path-modify for the keyword arguments :sep, :once and :test.

Example:

Append "/usr/local/bin" to PATH if it is a directory:

path-append 'PATH "/usr/local/bin" :test d?

function path-append-unique var val [keyword arguments]

A wrapper to path-modify’s append function with :once set to true.

Param var:

the name of the path to be manipulated, eg. PATH, CLASSPATH

Type var:

symbol

Param val:

the path element(s) to be added, sep separated

Type val:

string

See path-modify for the keyword arguments :sep and :test.

function path-prepend var val [keyword arguments]

A wrapper to path-modify’s prepend function.

Param var:

the name of the path to be manipulated, eg. PATH, CLASSPATH

Type var:

symbol

Param val:

the path element(s) to be added, sep separated

Type val:

string

See path-modify for the keyword arguments :sep, :once and :test.

Example:

Prepend "/usr/local/bin" to PATH if it is a directory:

path-prepend 'PATH "/usr/local/bin" :test d?

function path-prepend-unique var val [keyword arguments]

A wrapper to path-modify’s prepend function with :once set to true.

Param var:

the name of the path to be manipulated, eg. PATH, CLASSPATH

Type var:

symbol

Param val:

the path element(s) to be added, sep separated

Type val:

string

See path-modify for the keyword arguments :sep and :test.

function path-remove var old [keyword arguments]

A wrapper to path-modify’s remove function.

Param var:

the name of the path to be manipulated, eg. PATH, CLASSPATH

Type var:

symbol

Param old:

the path element to be removed

Type old:

string

See path-modify for the keyword arguments :sep and :once.

Example:

Remove "/usr/local/bin" from PATH:

path-remove 'PATH "/usr/local/bin"

function path-remove-first var old [keyword arguments]

A wrapper to path-modify’s remove function with :once set to true.

Param var:

the name of the path to be manipulated, eg. PATH, CLASSPATH

Type var:

symbol

Param old:

the path element to be removed

Type old:

string

See path-modify for the keyword argument :sep.

function path-replace var old new [keyword arguments]

A wrapper to path-modify’s replace function.

Param var:

the name of the path to be manipulated, eg. PATH, CLASSPATH

Type var:

symbol

Param old:

the path element to be replaced

Type old:

string

Param new:

the path element(s) to be substituted, sep separated

Type new:

string

See path-modify for the keyword arguments :sep, :once and :test.

Example:

Append "/usr/local/bin" to PATH if it is a directory:

path-append 'PATH "/usr/local/bin" :test d?

function path-replace-first var old new [keyword arguments]

A wrapper to path-modify’s replace function with :once set to true.

Param var:

the name of the path to be manipulated, eg. PATH, CLASSPATH

Type var:

symbol

Param old:

the path element to be replaced

Type old:

string

Param new:

the path element(s) to be substituted, sep separated

Type new:

string

See path-modify for the keyword arguments :sep and :test.

function trim-path val (:sep ":")

Returns a path value with duplicate elements removed after the first.

Param val:

the value of the path to be manipulated, eg. PATH, CLASSPATH

Type val:

string

Keyword :sep:

the element separator, defaults to :

Type :sep:

string, optional

function path-verify val (:sep ":") (:test #f)

A wrapper to path-modify’s verify function.

Param var:

the name of the path to be manipulated, eg. PATH, CLASSPATH

Type var:

symbol

Keyword :sep:

the element separator, defaults to :

Type :sep:

string, optional

Keyword :test:

apply the predicate on the path segment

Type :test:

predicate (function), required

Note

The :test keyword argument is required. It uses the :test style for consistency.

Example:

Reduce PATH to those elements that are directories:

path-verify 'PATH :test d?

function std-paths act val [keyword arguments]

Call path-act for

• PATH with val/bin

• MANPATH with val/share/man or val/man if either exists

Param act:

an act for path-modify

Type act:

symbol

Param val:

the top of the standard hierarchy tree

Type val:

string

See path-modify for the keyword arguments :sep, :once and :test.

Example:

Append "/usr/local/bin" to PATH and one of "/usr/local/share/bin" or "/usr/local/man" (if they exist) to MANPATH:

std-paths 'append "/usr/local"

function std-paths-unique act val [keyword arguments]

Call path-act with :once set to true for

• PATH with val/bin

• MANPATH with val/share/man or val/man if either exists

Param act:

an act for path-modify

Type act:

symbol

Param val:

the top of the standard hierarchy tree

Type val:

string

See path-modify for the keyword arguments :sep and :test.

Example:

Append "/usr/local/bin" to PATH and one of "/usr/local/share/bin" or "/usr/local/man" (if they exist) to MANPATH:

std-paths 'append "/usr/local"

function all-paths act val [keyword arguments]

Call path-act for

• PATH with val/bin

• LD_LIBRARY_PATH with val/lib

• MANPATH with val/share/man or val/man if either exists

Param act:

an act for path-modify

Type act:

symbol

Param val:

the top of the standard hierarchy tree

Type val:

string

See path-modify for the keyword arguments :sep, :once and :test.

Example:

Append "/usr/local/bin" to PATH, "/usr/local/lib" to LI_LIBRARY_PATH and one of "/usr/local/share/bin" or "/usr/local/man" (if they exist) to MANPATH:

all-paths 'append "/usr/local"

function all-paths-unique act val [keyword arguments]

Call path-act with :once set to true for

• PATH with val/bin

• LD_LIBRARY_PATH with val/lib

• MANPATH with val/share/man or val/man if either exists

Param act:

an act for path-modify

Type act:

symbol

Param val:

the top of the standard hierarchy tree

Type val:

string

See path-modify for the keyword arguments :sep and :test.

Example:

Append "/usr/local/bin" to PATH, "/usr/local/lib" to LI_LIBRARY_PATH and one of "/usr/local/share/bin" or "/usr/local/man" (if they exist) to MANPATH:

all-paths 'append "/usr/local"

function reduce-pathname val (:sep "/")

Reduce pathname val by:

• removing . and .. elements as appropriate

Param val:

the pathname to be normalized

Type val:

string

Keyword :sep:

the element separator, defaults to #\/

Type :sep:

unicode, optional

function normalize-pathname val (:sep "/")

Normalize pathname val by:

• prefixing with PWD, if not an absolute pathname

• calling reduce-pathname

Param val:

the pathname to be normalized

Type val:

string

Keyword :sep:

the element separator, defaults to #\/

Type :sep:

unicode, optional

function dirname-pathname val (:sep "/")

Return the dirname of pathname val

Param val:

the pathname to be examined

Type val:

string

Keyword :sep:

the element separator, defaults to #\/

Type :sep:

unicode, optional

function basename-pathname val (:sep "/")

Return the basename of pathname val

Param val:

the pathname to be examined

Type val:

string

Keyword :sep:

the element separator, defaults to #\/

Type :sep:

unicode, optional

function path-modify var val act wrt (:sep ":") (:once #f) (:test #f)

Modify path var in various ways (append, prepend, remove, replace, etc.). It handles paths with whitespace and various kinds of separators (Unix’s :, Windows’ ;, Tcl’s – see note).

Param var:

the name of the path to be manipulated, eg. PATH, CLASSPATH

Type var:

symbol

Param val:

the path element(s) to be added, sep separated

Type val:

string

Param act:

the action to be performed

Param wrt:

the element in the path to be operated on

Type wrt:

string

Keyword :sep:

the element separator, defaults to :

Type :sep:

string, optional

Keyword :once:

do the operation once (see below), defaults to #f

Type :once:

boolean, optional

Keyword :test:

apply the predicate on the path segment

Type :test:

predicate (function), optional

act can be:

first start	prepend val
last end	append val
verify	apply the conditional operator
after before	insert val after/before wrt
replace	replace wrt with val
remove	remove wrt

If :once is true then

• if act is replace or remove perform the action once

• if act is one of first, last, before, after ensure that val appears once in the result

  In particular, subsequent instances of val may be removed or val may not be appended depending on the current elements of var.

The :test flag might be one of the standard predicates, d?, e? or f?, or something bespoke.

Note

Technically, TCLLIBPATH is a Tcl list which can, presumably, be whitespace separated. path-modify uses split-string-exactly to retain adjacent separators which will do the wrong thing here with adjacent whitespace code points.

You may want to construct a normalized value with something like:

TCLLIBPATH = join-string " " (split-string TCLLIBPATH " \t")

Last built at 2025-10-29T07:10:38Z+0000 from 3d9f9d3 (dev) for Idio 0.3.b.6