commandLine.functions

# This file is part of shellfire core. It is subject to the licence terms in the COPYRIGHT file found in the top-level directory of this distribution and at https://raw.githubusercontent.com/shellfire-dev/core/master/COPYRIGHT. No part of shellfire core, including this file, may be copied, modified, propagated, or distributed except according to the terms contained in the COPYRIGHT file.
# Copyright © 2014-2015 The developers of shellfire core. See the COPYRIGHT file in the top-level directory of this distribution and at https://raw.githubusercontent.com/shellfire-dev/core/master/COPYRIGHT.


# Based on sysexits.h (refer to FreeBSD man pages at http://www.gsp.com/cgi-bin/man.cgi?topic=sysexits)

# successful termination (aka EXIT_SUCCESS in stdlib.h)
core_commandLine_exitCode_OK=0
core_dependency_declares core_commandLine_exitCode_OK

# Not in sysexit, but so commonly used (aka EXIT_FAILURE in stdlib.h)
core_commandLine_exitCode_FAILURE=1
core_dependency_declares core_commandLine_exitCode_FAILURE

# Not in sysexit, misuse of builtin
core_commandLine_exitCode_MISUSEBUILTIN=2
core_dependency_declares core_commandLine_exitCode_MISUSEBUILTIN

# command line usage error
core_commandLine_exitCode_USAGE=64
core_dependency_declares core_commandLine_exitCode_USAGE

# data format error
core_commandLine_exitCode_DATAERR=65
core_dependency_declares core_commandLine_exitCode_DATAERR

# cannot open input
core_commandLine_exitCode_NOINPUT=66
core_dependency_declares core_commandLine_exitCode_NOINPUT

# addressee unknown
core_commandLine_exitCode_NOUSER=67
core_dependency_declares core_commandLine_exitCode_NOUSER

# host name unknown
core_commandLine_exitCode_NOHOST=68
core_dependency_declares core_commandLine_exitCode_NOHOST

# service unavailable
core_commandLine_exitCode_UNAVAILABLE=69
core_dependency_declares core_commandLine_exitCode_UNAVAILABLE

# internal software error
core_commandLine_exitCode_SOFTWARE=70
core_dependency_declares core_commandLine_exitCode_SOFTWARE

# system error (e.g., can't fork)
core_commandLine_exitCode_OSERR=71
core_dependency_declares core_commandLine_exitCode_OSERR

# critical OS file missing
core_commandLine_exitCode_OSFILE=72
core_dependency_declares core_commandLine_exitCode_OSFILE

# can't create (user) output file
core_commandLine_exitCode_CANTCREAT=73
core_dependency_declares core_commandLine_exitCode_CANTCREAT

# input/output error
core_commandLine_exitCode_IOERR=74
core_dependency_declares core_commandLine_exitCode_IOERR

# temp failure; user is invited to retry
core_commandLine_exitCode_TEMPFAIL=75
core_dependency_declares core_commandLine_exitCode_TEMPFAIL

# remote error in protocol
core_commandLine_exitCode_PROTOCOL=76
core_dependency_declares core_commandLine_exitCode_PROTOCOL

# permission denied
core_commandLine_exitCode_NOPERM=77
core_dependency_declares core_commandLine_exitCode_NOPERM

# configuration error
core_commandLine_exitCode_CONFIG=78
core_dependency_declares core_commandLine_exitCode_CONFIG

if ! core_functions_exists _program_commandLine_helpMessage; then
	_program_commandLine_helpMessage()
	{
		:
	}
fi

# Width is 80 cols; standard Parallels VM is 100 cols
core_commandLine_helpMessage()
{
	# Defaults
	_program_commandLine_helpMessage_usage="[OPTION]..."
	_program_commandLine_helpMessage_description="Does nothing."
	_program_commandLine_helpMessage_options=""
    _program_commandLine_helpMessage_optionsSpacing='     '
	_program_commandLine_helpMessage_configurationKeys=""
	_program_commandLine_helpMessage_examples=""
	
	_program_commandLine_helpMessage
	
	printf '%s' Usage: "${_program_name} ${_program_commandLine_helpMessage_usage}
${_program_commandLine_helpMessage_description}

  -h, --help             ${_program_commandLine_helpMessage_optionsSpacing}display this help and exit
  -v, --verbose [LEVEL]  ${_program_commandLine_helpMessage_optionsSpacing}specify more than once to increase verbosity or
                         ${_program_commandLine_helpMessage_optionsSpacing}optionally set LEVEL to 0 - 2. Defaults to 0.
  -q, --quiet            ${_program_commandLine_helpMessage_optionsSpacing}specify to reduce verbosity
      --version          ${_program_commandLine_helpMessage_optionsSpacing}output version information and exit${_program_commandLine_helpMessage_options}
      --                 ${_program_commandLine_helpMessage_optionsSpacing}end of options

Notes
Long options with values may also be specified with '=', eg --verbose=2 as well
as --verbose 2. Separate options from operands (non-options) by using '--'.
This prevents interpretation of non-options as options. Concatenating short
options with arguments (eg -v2) is not supported.

Configuration
This program can be configured by creating files in the form 'key=value' in the
files and folders:-
  
  ${_program_etcPath}/${_program_name}/rc
  ${_program_etcPath}/${_program_name}/rc.d
  HOME/.${_program_name}/rc
  HOME/.${_program_name}/rc.d
  ${_program_namespace}_RC
  ${_program_namespace}_RC_D

Locations ending '.d' are folders which are searched for files. All files in a
folder are used in shell glob-expansion order. HOME, ${_program_namespace}_RC and
${_program_namespace}_RC_D are environment variables. If the variable
does not exist, or is blacklisted, the location is ignored.
Blacklisting is done by specifying:-

  core_configuration_blacklist  VARIABLE_NAME
  
in a configuration file. This allows the system administrator to prevent
overridding.

Files are used in the order above. If a file does not exist, it is ignored.
Those under a 'etc' folder must have the following permissions set:-

  * They are owned by root.
  * They are not group writable.
  * They are not world writable.
  * They do not reside in a group writable directory.
  * They do not reside in a world writable directory.
  * They are not a symbolic link to a file residing in a group or world
    writable directory. 

If the permissions are not set, the file is ignored.

Configuration Keys
  
  ${_program_namespace}_verbose   $(core_init_verbosity)  Controls message logging on stderr
  ${_program_namespace}_language  $(core_init_language)  Controls sort language${_program_commandLine_helpMessage_configurationKeys}
Values should be single or double-quoted if they contain whitespace.

Examples
${_program_commandLine_helpMessage_examples}
Path Files
A path file is used to define the location of essential programs used during
initial bootstrapping. It also defines a packageManager to automatically
install any missing dependencies.
"
}

core_commandLine_defaultLicenseMessage()
{
	printf '%s' "LICENSE terms are documented in the COPYRIGHT file at the top-level directory of this distribution."
}

core_commandLine_versionMessage()
{
	if [ -z "$_program_package_or_build" ]; then
		local _program_package_or_build_x=''
	else
		local _program_package_or_build_x="($_program_package_or_build) "
	fi
	
	if core_variable_isSet _program_copyrightAndLicenseStatement; then
		local copyrightAndLicenseStatement="$_program_copyrightAndLicenseStatement"
	else
		local copyrightAndLicenseStatement="$(core_commandLine_defaultLicenseMessage)"
	fi
	
	printf '%s' \
"$_program_name ${_program_package_or_build_x}$_program_version
Created using shellfire (https://github.com/shellfire-dev/shellfire)
$copyrightAndLicenseStatement"
}

core_commandLine_exitVersion()
{
	core_commandLine_versionMessage 1>&2
	exit $core_commandLine_exitCode_OK
}

core_commandLine_exitHelp()
{
	core_commandLine_helpMessage 1>&2
	exit $core_commandLine_exitCode_OK
}

core_commandLine_exitBadCommandLine()
{
	core_commandLine_helpMessage 1>&2
	core_message FAIL "$1"
	exit $core_commandLine_exitCode_USAGE
}

core_commandLine_setLanguageDefaults()
{
	core_variable_unset LANG
	core_variable_unset LC_COLLATE
	core_variable_unset LC_CTYPE
	core_variable_unset LC_MESSAGES
	core_variable_unset LC_MONETARY
	core_variable_unset LC_NUMERIC
	core_variable_unset LC_TIME
	core_variable_unset LC_ALL
	
	local language="$(core_init_language)"
	
	export LANG="$language"
	export LC_COLLATE="$language"
	export LC_CTYPE="$language"
	export LC_MESSAGES="$language"
	export LC_MONETARY="$language"
	export LC_NUMERIC="$language"
	export LC_TIME="$language"
	export LC_ALL=""
	
	# ? Also LANGUAGE, a GNU gettext extension?
	# ignored if locale is set to 'C'
	# pt is same as pt_PT for this variable
	# export LANGUAGE=sv:de  for swedish then german
}

# yes-argumentless
# yes-argumented
# yes-optionally-argumented
# no
core_commandLine_optionExists()
{
	local optionName="$1"
	
	case "$optionName" in
		
		h|help)
			echo yes-argumentless
		;;
	
		v|verbose)
			echo yes-optionally-argumented
		;;
		
		q|quiet)
			echo yes-argumentless
		;;
		
		version)
			echo yes-argumentless
		;;
		
		*)
			_program_commandLine_optionExists
		;;
		
	esac
}

if ! core_functions_exists _program_commandLine_optionExists; then
	_program_commandLine_optionExists()
	{
		echo 'no'
	}
fi

core_commandLine_processOptionWithoutArgument()
{
	case "$optionName" in
		
		h|help)
			core_commandLine_exitHelp
		;;
	
		v|verbose)
			local currentVerbosity=$(core_init_verbosity)
			core_variable_setVariable ${_program_namespace}_verbose $((currentVerbosity+1))
		;;
		
		q|quiet)
			local currentVerbosity=$(core_init_verbosity)
			if [ $currentVerbosity -gt 0 ]; then
				core_variable_setVariable ${_program_namespace}_verbose $((currentVerbosity-1))
			fi
		;;
		
		version)
			core_commandLine_exitVersion
		;;
	
		*)
			_program_commandLine_processOptionWithoutArgument
		;;
		
	esac
}

if ! core_functions_exists _program_commandLine_processOptionWithoutArgument; then
	_program_commandLine_processOptionWithoutArgument()
	{
		:
	}
fi

core_commandLine_processOptionWithArgument()
{
	case "$optionName" in
		
		v|verbose)
			core_validate_isUnsignedInteger $core_commandLine_exitCode_USAGE 'option' "$optionNameIncludingHyphens" "$optionValue"
			
			core_variable_setVariable ${_program_namespace}_verbose "$optionValue"
		;;
		
		*)
			_program_commandLine_processOptionWithArgument
		;;
		
	esac
}

if ! core_functions_exists _program_commandLine_processOptionWithArgument; then
	_program_commandLine_processOptionWithArgument()
	{
		:
	}
fi

# This can be confused with XF86-style long options (eg -find)
core_commandLine_parseConcatenatedOptionsWithoutEquals()
{	
	local arguments="-${optionName}"
	local optstring=":${optionName}"
	local lastOption=${#optionName}
	local OPTARG
	local OPTERR
	local OPTIND=1
	
	# Is this is a conjoined -o<argument> option? [Note we do not support -ab2, where a is optionless but b takes an argument, eg tar -xvfmytar.tar does not pass mytar.tar to the -f option]
	local possibleOptionName="$(core_variable_firstCharacter "${optionName}")"
	local possibleOptionValue="$(core_variable_allButFirst "${optionName}")"
	
	case "$(core_commandLine_optionExists "$possibleOptionName")" in
		
		yes-argumented|yes-optionally-argumented)
			optionName="$possibleOptionName"
			optionValue="$possibleOptionValue"
			core_commandLine_processOptionWithArgument
			shouldContinueAfterParsingConcatenatedOptions=1
			return
		;;
		
	esac
	
	while getopts "$optstring" optionName "$arguments"
	do
		optionNameIncludingHyphens="-${optionName}"
		argument="$optionNameIncludingHyphens"
		
		if [ $OPTIND -eq $lastOption ]; then
			return 0
		fi

		case "$(core_commandLine_optionExists "$optionName")" in
			
			yes-argumentless|yes-optionally-argumented)
				core_commandLine_processOptionWithoutArgument
			;;
			
			yes-argumented)
				core_commandLine_exitBadCommandLine "The option '${optionNameIncludingHyphens}' requires an argument which could not be specified"
			;;
			
			no|'')
				core_commandLine_exitBadCommandLine "The short option (concatenated with others) '${optionNameIncludingHyphens}' is not known"
			;;
			
			*)
				core_exitError $core_commandLine_exitCode_SOFTWARE "Please implement yes-argumented, yes-argumentless, yes-optionally-argumented or no for option '$optionName' in _program_commandLine_optionExists()"
			;;
			
		esac
		
	done
}

core_commandLine_parse()
{
	if core_functions_exists _program_commandLine_parse; then
		_program_commandLine_parse "$@"
	else
		core_commandLine_parsePosix "$@"
	fi	
}

# POSIX: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap12.html
# We support combined options, eg -xvf TAR.tar, including those with an argument
# We partly support concatenated arguments (ie instead -o arg, -oarg, but not -xvfTAR.tar for example)
# We do not support XF86-style options such as '-find', although we could (but it seems a little odd)
# An argument of '-' is treated as the first of the non-option arguments, NOT as delimiting the start of the non-options (we use -- for that)
core_commandLine_parsePosix()
{
	_program_commandLine_parseInitialise

	local argument
	local parsingOptionArguments=0
	while [ $# -ne 0 ]
	do
		local argument="$1"

		if core_variable_startsWith "$argument" '--' ; then
	
			shift 1

			if [ "$argument" = '--' ]; then
				break
			fi
	
			# Parse GNU-style long options
			case "$argument" in
		
				# eg --log-level=debug (handles spaces and multiple = signs correctly)
				--*=*)
					local optionNameIncludingHyphens="${argument%%=*}"
					local optionName="${optionNameIncludingHyphens##--}"
					local optionValue="${argument#*=}"
			
					case "$(core_commandLine_optionExists "$optionName")" in
				
						yes-argumentless)
							core_commandLine_exitBadCommandLine "The option '${optionNameIncludingHyphens}' does not take values (such as '$optionValue')"
						;;
				
						yes-argumented|yes-optionally-argumented)
							core_commandLine_processOptionWithArgument
						;;
				
						no|'')
							core_commandLine_exitBadCommandLine "The long option (with =value) '${optionNameIncludingHyphens}' does not exist"
						;;
				
						*)
							core_exitError $core_commandLine_exitCode_SOFTWARE "Please implement yes-argumented, yes-argumentless, yes-optionally-argumented or no for option '$optionName' in _program_commandLine_optionExists()"
						;;
					esac
				;;
		
				# eg --help and --verbose [level]
				--*)
					local optionNameIncludingHyphens="$argument"
					local optionName="${argument##--}"

					case "$(core_commandLine_optionExists "$optionName")" in
				
						yes-argumentless)
							core_commandLine_processOptionWithoutArgument
						;;
				
						yes-argumented)
							if [ $# -eq 0 ]; then
								core_commandLine_exitBadCommandLine "The option '${optionNameIncludingHyphens}' requires an argument which was not specified"
							fi
							local optionValue="$1"
							shift 1
							core_commandLine_processOptionWithArgument
						;;
				
						yes-optionally-argumented)
							if [ $# -eq 0 ]; then
								core_commandLine_processOptionWithoutArgument
								break
							fi
							local optionValue="$1"
							if core_variable_startsWith "$optionValue" '--' ; then
								core_commandLine_processOptionWithoutArgument
							else
								shift 1
								core_commandLine_processOptionWithArgument
							fi
						;;
				
						no|'')
							core_commandLine_exitBadCommandLine "The long option '${optionNameIncludingHyphens}' is not known"
						;;
				
						*)
							core_exitError $core_commandLine_exitCode_SOFTWARE "Please implement yes-argumented, yes-argumentless, yes-optionally-argumented or no for option '$optionName' in _program_commandLine_optionExists()"
						;;
				
					esac
				;;
		
				*)
					core_exitError $core_commandLine_exitCode_SOFTWARE "The function core_commandLine_parse failed on argument '$argument', the line was '$@'"
				;;
			esac
	
		elif core_variable_startsWith "$argument" '-' ; then

			# In some legacy programs, this is equivalent to '--'. It can also be a valid non-option argument (eg stdin). We treat it as the latter.
			if [ "$argument" = '-' ]; then
				break
			fi
	
			shift 1
	
			# Processing short options (-t, -v, etc)
	
			case "$argument" in
		
				# eg -l='debug'
				-*=*)
					local optionNameIncludingHyphens="${argument%%=*}"
					local optionName="${optionNameIncludingHyphens##-}"
					local optionValue="${argument#*=}"
					if [ ${#optionNameIncludingHyphens} -gt 2 ]; then
						# When this returns, all options will have been consumed apart from the last one, and optionName/optionNameIncludingHyphens will be a single option
						core_commandLine_parseConcatenatedOptionsWithoutEquals
					fi
			
					case "$(core_commandLine_optionExists "$optionName")" in
				
						yes-argumentless)
							core_commandLine_exitBadCommandLine "The option '$optionNameIncludingHyphens' does not take values (such as '$optionValue')"
						;;
				
						yes-argumented|yes-optionally-argumented)
							core_commandLine_processOptionWithArgument
						;;
				
						no|'')
							core_commandLine_exitBadCommandLine "The short option '$optionNameIncludingHyphens' is not known"
						;;
				
						*)
							core_exitError $core_commandLine_exitCode_SOFTWARE "Please implement yes-argumented, yes-argumentless, yes-optionally-argumented or no for option '$optionName' in _program_commandLine_optionExists()"
						;;
				
					esac
			
				;;
		
				# eg -h, -hv, -v2
				-*)
					local optionNameIncludingHyphens="$argument"
					local optionName="${argument##-}"
					if [ ${#optionNameIncludingHyphens} -gt 2 ]; then

						# Is this is a conjoined -o<argument> option? [Note we do not support -ab2, where a is optionless but b takes an argument]
						local possibleOptionName="$(core_variable_firstCharacter "${optionName}")"
						local possibleOptionValue="$(core_variable_allButFirst "${optionName}")"
				
						case "$(core_commandLine_optionExists "$possibleOptionName")" in
					
							yes-argumented|yes-optionally-argumented)
								optionName="$possibleOptionName"
								optionValue="$possibleOptionValue"
								core_commandLine_processOptionWithArgument
								continue
							;;
					
						esac
				
						# When this returns, all options will have been consumed apart from the last one, and optionName/optionNameIncludingHyphens will be a single option
						local shouldContinueAfterParsingConcatenatedOptions=0
						core_commandLine_parseConcatenatedOptionsWithoutEquals
						if [ $shouldContinueAfterParsingConcatenatedOptions ]; then
							continue
						fi
					fi

					case "$(core_commandLine_optionExists "$optionName")" in
				
						yes-argumentless)
							core_commandLine_processOptionWithoutArgument
						;;
				
						yes-argumented)
							if [ $# -eq 0 ]; then
								core_commandLine_exitBadCommandLine "The option '${optionNameIncludingHyphens}' requires an argument which was not specified"
							fi
							local optionValue="$1"
							shift 1
							core_commandLine_processOptionWithArgument
						;;
				
						yes-optionally-argumented)
							if [ $# -eq 0 ]; then
								core_commandLine_processOptionWithoutArgument
								break
							fi
							local optionValue="$1"
							if core_variable_startsWith "$optionValue" '--' ; then
								core_commandLine_processOptionWithoutArgument
							else
								shift 1
								core_commandLine_processOptionWithArgument
							fi
						;;
				
						no|'')
							core_commandLine_exitBadCommandLine "The short option '${optionNameIncludingHyphens}' is not known"
						;;
				
						*)
							core_exitError $core_commandLine_exitCode_SOFTWARE "Please implement yes-argumented, yes-argumentless, yes-optionally-argumented or no for option '$optionName' in _program_commandLine_optionExists()"
						;;
				
					esac
				;;
		
				*)
					core_exitError $core_commandLine_exitCode_SOFTWARE "The function core_commandLine_parse failed on argument '$argument', the line was '$@'"
				;;
		
			esac
		else
			# start of non-options
			break
		fi
	done

	_program_commandLine_handleNonOptions "$@"

	_program_commandLine_validate
}

if ! core_functions_exists _program_commandLine_parseInitialise; then
	_program_commandLine_parseInitialise()
	{
		:
	}
fi

if ! core_functions_exists _program_commandLine_handleNonOptions; then
	_program_commandLine_handleNonOptions()
	{
		if [ $# -ne 0 ]; then
			core_commandLine_exitBadCommandLine "Non-options are not accepted"
		fi
	}
fi

if ! core_functions_exists _program_commandLine_validate; then
	_program_commandLine_validate()
	{
		:
	}
fi