shell-array

#!/bin/sh -efu
### This file is covered by the GNU General Public License,
### which should be included with the file LICENSE.
### All copyright information are listed in the COPYING.

if [ -z "${__included_shell_array-}" ]; then
__included_shell_array=1

. shell-error

### Arrays implemented on plain shell variables.
###
### An array named 'myarr' is the element count variable 'myarr'
### plus the zero-based element variables 'myarr0', 'myarr1', and
### so on. Elements are dense and may hold arbitrary values,
### including spaces, quotes and newlines.
###
### Note on naming: an array name must not be a prefix of another
### array name immediately followed by a digit (arrays 'x' and 'x1'
### collide on the slot variable 'x1'), and both the array name and
### the caller's out-variables must not use the internal
### '__shell_array_' prefix.
###
### Usage errors (bad arguments, invalid names or indices, out of
### bounds) are fatal.

### Check that $1 may be used as a variable name.
__shell_array_name()
{
	case "$1" in
	''|[!a-zA-Z_]*|*[!a-zA-Z0-9_]*)
		fatal "Invalid variable name: $1"
		;;
	esac
}

### Check that $1 is a non-negative decimal integer without leading
### zeros (so it is safe in arithmetic expressions).
__shell_array_index()
{
	case "$1" in
	0|[1-9]|[1-9][0-9]*)
		: ;;
	*)
		fatal "Invalid array index: $1"
		;;
	esac
}

### Assign $2 to the variable named $1.
### $1 must have been checked by __shell_array_name; the value is
### assigned in a quoted context, so arbitrary values are safe.
__shell_array_set()
{
	eval "$1=\"\$2\""
}

### Append a value to the end of an array.
### Usage: shell_array_append array value
shell_array_append()
{
	[ "$#" -eq 2 ] ||
		fatal "Usage: shell_array_append array value"
	local __shell_array_n
	__shell_array_name "$1"
	eval "__shell_array_n=\${$1:-0}"
	__shell_array_set "$1$__shell_array_n" "$2"
	eval "$1=$(( __shell_array_n + 1 ))"
	return 0
}

### Set a value in an array at the given index, growing the array
### with empty elements as needed; with no index the value is
### appended.
### Usage: shell_array_set array value [index]
shell_array_set()
{
	[ "$#" -eq 2 ] || [ "$#" -eq 3 ] ||
		fatal "Usage: shell_array_set array value [index]"
	local __shell_array_sz __shell_array_i
	__shell_array_name "$1"
	eval "__shell_array_sz=\${$1:-0}"
	__shell_array_i="${3:-$__shell_array_sz}"
	__shell_array_index "$__shell_array_i"
	while [ "$__shell_array_sz" -lt "$__shell_array_i" ]; do
		__shell_array_set "$1$__shell_array_sz" ''
		__shell_array_sz=$(( __shell_array_sz + 1 ))
	done
	__shell_array_set "$1$__shell_array_i" "$2"
	if [ "$__shell_array_sz" -eq "$__shell_array_i" ]; then
		__shell_array_sz=$(( __shell_array_i + 1 ))
	fi
	eval "$1=$__shell_array_sz"
	return 0
}

### Store the element at index in the caller's variable.
### Usage: shell_array_get array index variable
shell_array_get()
{
	[ "$#" -eq 3 ] ||
		fatal "Usage: shell_array_get array index variable"
	local __shell_array_n
	__shell_array_name "$1"
	__shell_array_name "$3"
	__shell_array_index "$2"
	eval "__shell_array_n=\${$1:-0}"
	[ "$2" -lt "$__shell_array_n" ] ||
		fatal "Index $2 out of bounds (size $__shell_array_n)"
	eval "$3=\"\${$1$2-}\""
	return 0
}

### Remove the last element of the array; with a second argument its
### value is stored in the caller's variable.
### Usage: shell_array_pop array [variable]
shell_array_pop()
{
	[ "$#" -eq 1 ] || [ "$#" -eq 2 ] ||
		fatal "Usage: shell_array_pop array [variable]"
	local __shell_array_n
	__shell_array_name "$1"
	eval "__shell_array_n=\${$1:-0}"
	[ "$__shell_array_n" -gt 0 ] ||
		fatal "Array $1 is empty"
	__shell_array_n=$(( __shell_array_n - 1 ))
	if [ "$#" -eq 2 ]; then
		__shell_array_name "$2"
		eval "$2=\${$1$__shell_array_n-}"
	fi
	eval "$1=$__shell_array_n"
	return 0
}

### Destroy the whole array, or remove the element at index
### compacting the elements that follow.
### Usage: shell_array_unset array [index]
shell_array_unset()
{
	[ "$#" -eq 1 ] || [ "$#" -eq 2 ] ||
		fatal "Usage: shell_array_unset array [index]"
	local __shell_array_n
	__shell_array_name "$1"
	eval "__shell_array_n=\${$1:-0}"
	[ "$__shell_array_n" -gt 0 ] ||
		fatal "Array $1 is empty"
	if [ "$#" -eq 1 ]; then
		local __shell_array_i
		__shell_array_i=0
		while [ "$__shell_array_i" -lt "$__shell_array_n" ]; do
			unset "$1$__shell_array_i"
			__shell_array_i=$(( __shell_array_i + 1 ))
		done
		unset "$1"
		return 0
	fi
	local __shell_array_i __shell_array_v
	__shell_array_i=$2
	__shell_array_index "$__shell_array_i"
	[ "$__shell_array_i" -lt "$__shell_array_n" ] ||
		fatal "Index $2 out of bounds (size $__shell_array_n)"
	__shell_array_i=$(( __shell_array_i + 1 ))
	while [ "$__shell_array_i" -lt "$__shell_array_n" ]; do
		eval "__shell_array_v=\${$1$__shell_array_i-}"
		__shell_array_set "$1$(( __shell_array_i - 1 ))" "$__shell_array_v"
		__shell_array_i=$(( __shell_array_i + 1 ))
	done
	unset "$1$(( __shell_array_n - 1 ))"
	eval "$1=$(( __shell_array_n - 1 ))"
	return 0
}

fi #__included_shell_array