Zsh support for LS_COLORS

A zsh library to use LS_COLORS in scripts or other plugins.

For a simple demo, see the zstyle-demo script in this repo.

If a use case isn't adequately covered, please open an issue!

Finally, if you are making use of this plugin, add it to the wiki!

Using zsh-ls-colors in a plugin

You can use this as a submodule or a subtree.

submodule:

# Add (only once)
git submodule add git://github.com/xPMo/zsh-ls-colors.git ls-colors
git commit -m 'Add ls-colors as submodule'

# Update
cd ls-colors
git fetch
git checkout origin/master
cd ..
git commit ls-colors -m 'Update ls-colors to latest'

Subtree:

# Initial add
git subtree add --prefix=ls-colors/ --squash -m 'Add ls-colors as a subtree' \
	git://github.com/xPMo/zsh-ls-colors.git master

# Update
git subtree pull --prefix=ls-colors/ --squash -m 'Update ls-colors to latest' \
	git://github.com/xPMo/zsh-ls-colors.git master 


# Or, after adding a remote:
git remote add ls-colors git://github.com/xPMo/zsh-ls-colors.git

# Initial add
git subtree add --prefix=ls-colors/ --squash -m 'Add ls-colors as a subtree' ls-colors master

# Update
git subtree pull --prefix=ls-colors/ --squash -m 'Update ls-colors to latest' ls-colors master 

API v2:

This function takes a context and a list of files as input, and returns a list of colored strings, formatted according to $format.

${prefix}::fmt [ -f $format | -F $format ] [ -o | -0 | -a | -A ] $context $files[@]

Loading the library

Since functions are a public namespace, This library allows you to customize the preifix for your plugin:

# load function as my-lscolors::fmt
# The remaining arguments to source determines which lib/ files you want to load.
# If no arguments are provided, then all lib/*.zsh are loaded.
source ${0:h}/ls-colors/ls-colors.zsh my-lscolors fmt

Customizing Colors with styles

The ::fmt function uses the usual list-colors style to determine how to color the results. Set the style as follows:

# Uses LS_COLORS format
zstyle $pattern list-colors ${(s[:])LS_COLORS} '*.ext=1'

In addition, you can enable extendedglob for certain contexts:

zstyle $pattern list-colors-extended true
zstyle $pattern list-colors ${(s[:])LS_COLORS} '(#i).ext=1'

Personally, I like this method for dynamically getting LS_COLORS for all contexts:

zstyle -e '*' list-colors 'reply=(${(s[:])LS_COLORS})'

Customizing format with styles

The ::fmt function uses the list-format style to determine how to format the results. Set the style as follows:

zstyle $pattern list-format '%F%P%r%(h.%I%i. -> %L%l%r)'

Format specifier	Meaning	Example (PWD=/usr, ./bin/sh symlinked to dash)
%F	The color/console codes which match the file	\e[0m\01;36m
%f	The file basename	sh
%P	The file path provided	./bin/sh
%p	The fully-qualified path	/usr/bin/sh
%L	The color/console codes which match the target of the symlink	\e[0m\e[01;32m
%l	The target of the symlink	dash
%h	1 if this file is a symlink, otherwise empty (useful to conditionally output the link target)	1
%r	The color/console codes normally used to reset the terminal style	\e[0m
%I	The color for filetype indicators	\e[0m
%i	The single-character filetype indicator the given file	@
%j	The single-character filetype indicator for the target of the symlink	*

For more information on using these codes, see the section on zformat in man zshmodules.

More format specifiers may be added in the future, probably based on GNU find's -printf formats.

Customizing format at runtime

There are two flags to the ::fmt function which change how list-format is used:

${prefix}::fmt -f $format     # use $format if no list-format is specified for the current style
${prefix}::fmt -F $format     # force $format, ignore the list-format specified for the current style

Output method

There are four ways ::fmt can return its results:

${prefix}::fmt -a ...     # [default] assign results to $reply as an array
${prefix}::fmt -A ...     # assign results to $reply as an associative array, with filenames as keys
${prefix}::fmt -o ...     # print results to stdout separated by newlines
${prefix}::fmt -0 ...     # print results to stdout separated by NUL characters

Legacy API:

For more advanced usage, instructions are located at top of the source files for from-mode and from-name.

Function namespacing

Since functions are a public namespace, this plugin allows you to customize the preifix for your plugin:

# load functions as my-lscolors::{init,match-by,from-name,from-mode}
# The remaining arguments to source determines which lib/ files you want to load.
# If no arguments are provided, then all lib/*.zsh are loaded.
source ${0:h}/ls-colors/ls-colors.zsh my-lscolors legacy

Parameter namespacing

While indirect parameter expansion exists with ${(P)var}, it doesn't play nicely with array parameters, and especially not with associative arrays.

There are multiple strategies to prevent unnecessary re-parsing:

Call init in global scope. This pollutes global namespace but prevents re-parsing $LS_COLORS on every function call.

ls-color::init

Don't call init at all: This is only compatible with ::match-by, and reparses LS_COLORS each time, but it doesn't pollute global namespace.

ls-color::match-by $file lstat

Initialize within a scope with local parameters. Best for not polluting global namespace when multiple filenames need to be parsed.

(){
	local -A namecolors modecolors
	ls-color::init

	for arg; do
		...
	done
}

Custom parameter: Save the array value as your own custom parameter to copy back.

(){ # initially
	local -A namecolors modecolors
	ls-color::init
	typeset -ga _my_modecolors=("${(@kv)modecolors}")    # you MUST use (@kv) to avoid losing empty entries
	typeset -ga _my_namecolors=("${(kv)namecolors[@]}")  # alternatively, use bash-style [@]
}

my-function(){
	local -A modecolors=("${(@)_my_modecolors}")         # you MUST use (@) to avoid losing empty entries
	local -A namecolors=("${_my_namecolors[@]}")         # alternatively, use bash-style [@]

	...
}

About the plugin:

You can find the plugin at xPMo/zsh-ls-colors.