libEnv

Functions to manipulate environment PATH-like variables

Overview

Functions to manipulate shell environment PATH like variables with entries normally separated by “:” such as MANPATH and PATH itself.

Often these variables contain directory paths but they don’t have to, for example HISTCONTROL. Between each path element is a separator character, normally a colon “:” but this can be changed by setting envSep.

Contains the following:

  • ksl::envContains()

  • ksl::envAppend()

  • ksl::envPrepend()

  • ksl::envDelete()

  • ksl::envDeleteFirst()

  • ksl::envDeleteLast()

  • ksl::envSetSeparator()

The following is an example PATH setup using some of these functions. Note that no specific testing for OS is needed. Just relies on whether the element exists on the file space.

# Standard system path setup here

ksl::envAppend -f PATH "/bin"
ksl::envAppend -f PATH "/usr/bin"
ksl::envAppend -f PATH "/usr/local/bin"
ksl::envAppend -f PATH "/sbin"
ksl::envAppend -f PATH "/usr/sbin"
ksl::envAppend -f PATH "/usr/local/sbin"
ksl::envAppend -f PATH "${HOME}/.local/bin"
ksl::envAppend -f PATH "${HOME}/bin"
ksl::envDelete    PATH "/usr/games"
ksl::envDelete    PATH "/usr/local/games"

# Some platform specific setup

ksl::envPrepend -f PATH "/usr/local/opt/m4/bin"
ksl::envPrepend -f PATH "/usr/local/opt/openssl/bin"
ksl::envPrepend -f PATH "/usr/local/opt/findutils/libexec/gnubin"
ksl::envPrepend -f PATH "/usr/local/opt/coreutils/libexec/gnubin"
ksl::envPrepend -f PATH "/usr/local/opt/grep/libexec/gnubin"
ksl::envPrepend -f PATH "/usr/local/opt/make/libexec/gnubin"

Index

ksl::envContains

True if path style variable $1 contains the string in $2.

This is slightly different than just looking for a contained string as with ksl:contains(). Here the string to look for must exactly match between the surrounding “:” markers.

Example

if ksl::envContains PATH "/usr/bin"; then
    echo "Yes in PATH"
fi

Arguments

  • $1 (string): the name of a path style variable.

  • $2 (string): the element to look for.

Exit codes

  • 0: Success - was found

  • 1: not found, or missing args

Output on stdout

  • no output

Output on stderr

  • envContains() missing args

    image1

ksl::envAppend

Appends an element to a PATH-style variable.

Appends $2, in-place, to the end of the PATH-style variable named in $1, provided $2 is not already in there (options are available to control this).

ksl::envAppend [options…] PATH_VARIABLE ELEMENT

Options

  • -a | –allow-dups

  • -r | –reject-dups (default)

  • -s | –add-as-string (default)

  • -f | –file-must-exist

Option Descriptions

  • -a | –allow-dups: Adds to PATH_VARIABLE even if ELEMENT is already in there.

  • -r | –reject-dups: (default) Don’t add to PATH_VARIABLE if ELEMENT is already in there.

  • -s | –add-as-string: (default) Adds ELEMENT to the PATH_VARIABLE as a string - meaning do not check whether ELEMENT exists as a file.

  • -f | –file-must-exist: Adds ELEMENT, treated as a file/directory, to the PATH_VARIABLE, but only if ELEMENT exists on the file space.

  • If both -s and -f are given, last one wins.

  • If both -a and -r are given, last one wins.

Example

# Update MANPATH only if $HOME/man is not already in there
ksl::envAppend MANPATH $HOME/man
#
# Update MANPATH only if $HOME/man is not in there and it exists on file space
ksl::envAppend -r -f MANPATH $HOME/man # MANPATH is updated if $HOME/man exists

Arguments

  • $1 (VariableName): of a path style variable, such as PATH, with “:” separating individual elements.

  • $2 (Element): a string or directory or file name to append

Exit codes

  • 0: Success if element was appended

  • 1: Failed element was not appended

Output on stderr

  • ksl::_envXxpend(): missing args

  • ksl::_envXxpend(): requires two arguments got only…

  • ksl::_envXxpend(): invalid option…

    image2

ksl::envPrepend

Prepends $2, in-place, to the front of the PATH-style variable named in $1, provided $2 is not already in there (options are available to control this).

Same args and description as ksl::envAppend.

image3

ksl::envDelete

Deletes all occurrences of $2, in-place, from $1.

$1 is the name of a path style variable with “:” separating individual elements.

Example

ksl::envDelete MANPATH "$HOME/man"

Arguments

  • $1 (string): the name of a path style variable.

  • $2 (string): the element to delete.

Exit codes

  • 0: No error. Doesn’t mean something was deleted.

  • 1: Missing or empty args

Output on stdout

  • no output

Output on stderr

  • envDelete() missing args

    image4

ksl::envDeleteFirst

Deletes 1st element, in-place, from $1 where $1 is the name of a path style variable with “:” separating individual elements.

Returns 1 on an error otherwise 0.

Example

ksl::envDeleteFirst MANPATH

Arguments

  • $1 (VariableName): of a path style variable, such as PATH, with “:” separating individual elements.

Exit codes

  • 0: No error. Doesn’t mean anything was deleted.

  • 1: Missing or empty args

Output on stdout

  • no output

Output on stderr

  • envDeleteFirst() missing args

  • envDeleteFirst() empty arg

    image5

ksl::envDeleteLast

Deletes last element, in-place, from $1 where $1 is the name of a path style variable with “:” separating individual elements.

Example

ksl::envDeleteLast MANPATH

Arguments

  • $1 (VariableName): of a path style variable, such as PATH, with “:” separating individual elements.

Exit codes

  • 0: No error. Doesn’t mean anything was deleted.

  • 1: Missing or empty args

Output on stdout

  • no output

Output on stderr

  • envDeleteLast() missing args

  • envDeleteLast() empty arg

    image6

ksl::envSetSeparator

Use the given character as the separator between elements in a PATH-style variable.

Initialized to “:” at startup. Stays in effect until changed.

Example

ksl::envSetSeparator ";"

Arguments

  • $1 (character): the separator.

Exit codes

  • 0: In all cases