- fixed issue# 7 where long flags declared with '=' didn't work
- flag and non-flag arguments can now be mixed on the command-line
- removed setting and unsetting of '-u' to check for unset variables
- obsoleted FLAGS_ARGC and replaced with FLAGS_ARGV
diff --git a/source/1.0/doc/CHANGES-1.0.txt b/source/1.0/doc/CHANGES-1.0.txt
index 1eac214..f1375ac 100644
--- a/source/1.0/doc/CHANGES-1.0.txt
+++ b/source/1.0/doc/CHANGES-1.0.txt
@@ -1,6 +1,31 @@
Changes in shFlags 1.0.x
========================
+Changes with 1.0.3
+------------------
+
+MAJOR CHANGE! FLAGS_ARGC is now obsolete, and is replaced by FLAGS_ARGV.
+
+Fixed issue# 7 where long flags defined with '=' (e.g. --abc=123) made it
+impossible for the user to know how many non-flag command-line arguments were
+available because the value returned by FLAGS_ARGC was wrong. The FLAGS_ARGC
+value is now obsolete, but will be maintained for backwards compatibility. The
+new method of getting the non-flag arguments is by executing 'eval set --
+"${FLAGS_ARGV}"' after the FLAGS command. The arguments will then be available
+using the standard shell $#, $@, $*, $1, etc. variables.
+
+Due to above fix for issue# 7, there is now proper support for mixing flags
+with non-flag arguments on the command-line. Previously, all non-flag arguments
+had to be at the end of the command-line.
+
+Renamed _flags_standardGetopt() and _flags_enhancedGetopt() functions to
+_flags_getoptStandard() and _flags_getoptEnhanced().
+
+Took out the setting and restoration of the '-u' shell flag to treat unset
+variables as an error. No point in having it in this library as it is verified
+in the unit tests, and provides basically no benefit.
+
+
Changes with 1.0.2
------------------
diff --git a/source/1.0/doc/RELEASE_NOTES-1.0.3.txt b/source/1.0/doc/RELEASE_NOTES-1.0.3.txt
new file mode 100644
index 0000000..637a18d
--- /dev/null
+++ b/source/1.0/doc/RELEASE_NOTES-1.0.3.txt
@@ -0,0 +1,94 @@
+------------------------------
+shFlags.sh 1.0.3 Release Notes
+------------------------------
+
+Preface
+=======
+Copyright 2009 Kate Ward. All Rights Reserved.
+Released under the LGPL (GNU Lesser General Public License)
+Author: Kate Ward (kate.ward@forestent.com)
+
+This document covers any known issues and workarounds for the stated release of
+shFlags.
+
+Release info
+============
+
+This is a major bugfix release of shFlags. The biggest fix is in how non-flag
+arguments are made available to the script.
+
+Major changes
+-------------
+
+The use of the ``FLAGS_ARGC`` variable is now obsolete. It will be maintained
+for backwards compatibility with old scripts, but its value is known to be
+wrong when flag and non-flag arguments are mixed together on the command-line.
+
+To gain access to the non-flag arguments, replace the following snippet of code
+in your scripts with the updated version.
+
+:old: shift ${FLAGS_ARGC}
+:new: eval set -- "${FLAGS_ARGV}"
+
+Please see the CHANGES-1.0.txt file for a complete list of changes.
+
+Obsolete items
+--------------
+
+Bug fixes
+---------
+
+Issue# 7 Flags set with '=' result in off-by-one shifting error
+
+General info
+============
+
+The unit tests
+--------------
+
+shFlags is designed to work on as many environments as possible, but not all
+environments are created equal. As such, not all of the unit tests will succeed
+on every platform. The unit tests are therefore designed to fail, indicating to
+the tester that the supported functionality is not present, but an additional
+test is present to verify that shFlags properly caught the limitation and
+presented the user with an appropriate error message.
+
+shFlags tries to support both the standard and enhanced versions of ``getopt``.
+As each responds differently, and not everything is supported on the standard
+version, some unit tests will be skipped (i.e. ASSERTS will not be thrown) when
+the standard version of ``getopt`` is detected. The reason being that there is
+no point testing for functionality that is positively known not to exist. A
+tally of skipped tests will be kept for later reference.
+
+Standard vs Enhanced getopt
+---------------------------
+
+Here is a matrix of the supported features of the various **getopt** variants.
+
++-------------------------+---+---+
+|Feature |std|enh|
++=========================+===+===+
+|short option names | Y | Y |
+|long option names | N | Y |
+|spaces in string options | N | Y |
++-------------------------+---+---+
+
+Known Issues
+------------
+
+The **getopt** version provided by default with all versions of Mac OS X (up to
+and including 10.5.6) is the standard version. As such, only short flags are
+supported.
+
+The **getopt** version provided by default with all versions of Solaris (up to
+and including Solaris 10 and OpenSolaris) is the standard version. As such,
+only short flags are supported.
+
+Workarounds
+-----------
+
+The Zsh shell requires the ``shwordsplit`` option to be set, and the special
+``FLAGS_PARENT`` variable must be defined.
+
+
+.. vim:fileencoding=latin1:ft=rst:spell:tw=80
diff --git a/source/1.0/doc/contributors.txt b/source/1.0/doc/contributors.txt
index a097f78..146c0c0 100644
--- a/source/1.0/doc/contributors.txt
+++ b/source/1.0/doc/contributors.txt
@@ -1 +1,4 @@
-- Maciej Bliziński <blizinski@google.com> -- many code reviews
+I'd like to thank these people for their contributisons to shFlags.
+
+Maciej Bliziński <blizinski@google.com> -- _many_ code reviews
+Bjarni Einarsson <bre@google.com> -- bug reports
diff --git a/source/1.0/examples/debug_output.sh b/source/1.0/examples/debug_output.sh
index ed552ef..d54635f 100755
--- a/source/1.0/examples/debug_output.sh
+++ b/source/1.0/examples/debug_output.sh
@@ -10,17 +10,54 @@
#
# This script demonstrates the use of a boolean flag to enable custom
# functionality in a script.
+#
+# Try running these:
+# $ ./debug_output.sh speak
+# $ ./debug_output.sh sing
+# $ ./debug_output.sh --debug sing
# source shflags
. ../src/shflags
-debug() { [ ${FLAGS_debug} -eq ${FLAGS_TRUE} ] && echo "DEBUG: $@" >&2; }
-
# define flags
DEFINE_boolean 'debug' false 'enable debug mode' 'd'
+FLAGS_HELP=`cat <<EOF
+commands:
+ speak: say something
+ sing: sing something
+EOF`
+
+
+debug()
+{
+ [ ${FLAGS_debug} -eq ${FLAGS_TRUE} ] || return
+ echo "DEBUG: $@" >&2
+}
+
+die() {
+ [ $# -gt 0 ] && echo "error: $@" >&2
+ flags_help
+ exit 1
+}
+
# parse the command-line
-FLAGS "$@" || exit 1; shift ${FLAGS_ARGC}
+FLAGS "$@" || exit 1
+eval set -- "${FLAGS_ARGV}"
-debug 'debug mode enabled'
-echo 'something interesting'
+command=$1
+case ${command} in
+ '') die ;;
+
+ speak)
+ debug "I'm getting ready to say something..."
+ echo 'The answer to the question "What is the meaning of life?" is "42".'
+ ;;
+
+ sing)
+ debug "I'm getting ready to sing something..."
+ echo 'I love to sing! La diddy da dum!'
+ ;;
+
+ *) die "unrecognized command (${command})" ;;
+esac
diff --git a/source/1.0/examples/hello_world.sh b/source/1.0/examples/hello_world.sh
index d04a797..6fb2cb0 100755
--- a/source/1.0/examples/hello_world.sh
+++ b/source/1.0/examples/hello_world.sh
@@ -19,6 +19,7 @@
DEFINE_string 'name' 'world' 'name to say hello to' 'n'
# parse the command-line
-FLAGS "$@" || exit 1; shift ${FLAGS_ARGC}
+FLAGS "$@" || exit 1
+eval set -- "${FLAGS_ARGV}"
echo "Hello, ${FLAGS_name}!"
diff --git a/source/1.0/examples/write_date.sh b/source/1.0/examples/write_date.sh
index 0d9ccd0..85695cf 100755
--- a/source/1.0/examples/write_date.sh
+++ b/source/1.0/examples/write_date.sh
@@ -14,34 +14,46 @@
# - direct calling of the flags_help() function for script controlled usage
# output
# - handling of non-flag type command-line arguments that follow the flags
+#
+# Try the following:
+# $ ./write_date.sh now.out
+# $ cat now.out
+#
+# $ ./write_date.sh now.out
+# $ cat now.out
+#
+# $ ./write_date.sh -f now.out
+# $ cat now.out
# source shflags
. ../src/shflags
-write_date() { date >"$1"; }
-
# configure shflags
DEFINE_boolean 'force' false 'force overwriting' 'f'
FLAGS_HELP="USAGE: $0 [flags] filename"
-# parse the command-line
-FLAGS "$@" || exit 1; shift ${FLAGS_ARGC}
-# check for filename
-if [ $# -eq 0 ]; then
- echo 'error: filename missing' >&2
+write_date()
+{
+ date >"$1"
+}
+
+die()
+{
+ [ $# -gt 0 ] && echo "error: $@" >&2
flags_help
exit 1
-fi
+}
+
+
+# parse the command-line
+FLAGS "$@" || exit 1
+eval set -- "${FLAGS_ARGV}"
+
+# check for filename
+[ $# -gt 0 ] || die 'filename missing'
filename=$1
-if [ ! -f "${filename}" ]; then
- write_date "${filename}"
-else
- if [ ${FLAGS_force} -eq ${FLAGS_TRUE} ]; then
- write_date "${filename}"
- else
- echo 'warning: filename exists; not overwriting' >&2
- exit 2
- fi
-fi
+[ -f "${filename}" -a ${FLAGS_force} -eq ${FLAGS_FALSE} ] \
+ && die 'filename exists; not overwriting'
+write_date "${filename}"
diff --git a/source/1.0/src/shflags b/source/1.0/src/shflags
index 304e6db..805b07a 100644
--- a/source/1.0/src/shflags
+++ b/source/1.0/src/shflags
@@ -4,7 +4,8 @@
# Copyright 2008 Kate Ward. All Rights Reserved.
# Released under the LGPL (GNU Lesser General Public License)
#
-# shFlags -- Advanced command-line flag library for Unix shell scripts
+# shFlags -- Advanced command-line flag library for Unix shell scripts.
+# http://code.google.com/p/shflags/
#
# Author: kate.ward@forestent.com (Kate Ward)
#
@@ -37,12 +38,17 @@
#
# EXAMPLE USAGE:
#
+# -- begin hello.sh --
# #! /bin/sh
# . ./shflags
-#
-# DEFINE_string name 'world' "somebody's name"
-# FLAGS "$@" || exit $?; shift ${FLAGS_ARGC}
+# DEFINE_string name 'world' "somebody's name" n
+# FLAGS "$@" || exit $?
+# eval set -- "${FLAGS_ARGV}"
# echo "Hello, ${FLAGS_name}."
+# -- end hello.sh --
+#
+# $ ./hello.sh -n Kate
+# Hello, Kate.
#
# NOTE: Not all systems include a getopt version that supports long flags. On
# these systems, only short flags are recognized.
@@ -72,7 +78,7 @@
# return if FLAGS already loaded
[ -n "${FLAGS_VERSION:-}" ] && return 0
-FLAGS_VERSION='1.0.2'
+FLAGS_VERSION='1.0.3pre'
FLAGS_TRUE=0
FLAGS_FALSE=1
@@ -97,17 +103,6 @@
fi
fi
-# shell flags
-# u: treat unset variables as an error when performing parameter expansion
-__FLAGS_SHELL_FLAGS='u'
-
-# save the current set of shell flags, and then set some for ourself
-__flags_oldShellFlags=$-
-for __flags_shellFlag in `echo "${__FLAGS_SHELL_FLAGS}" |sed 's/\(.\)/\1 /g'`
-do
- set "-${__flags_shellFlag}"
-done
-
#
# constants
#
@@ -121,6 +116,7 @@
case $? in
0) __FLAGS_GETOPT_VERS=${__FLAGS_GETOPT_VERS_STD} ;; # bsd getopt
2)
+ # TODO(kward): look into '-T' option to test the internal getopt() version
if [ "`getopt --version`" = '-- ' ]; then
__FLAGS_GETOPT_VERS=${__FLAGS_GETOPT_VERS_STD}
else
@@ -183,16 +179,10 @@
__flags_longNames=' ' # space separated list of long flag names
__flags_shortNames=' ' # space separated list of short flag names
+__flags_argc=0 # count of non-flag arguments
__flags_columns='' # screen width in columns
__flags_opts='' # temporary storage for parsed getopt flags
-# restore the previous set of shell flags
-for __flags_shellFlag in ${__FLAGS_SHELL_FLAGS}; do
- echo ${__flags_oldShellFlags} \
- |grep ${__flags_shellFlag} >/dev/null || set +${__flags_shellFlag}
-done
-unset __flags_oldShellFlags __flags_shellFlag
-
#------------------------------------------------------------------------------
# private functions
#
@@ -357,7 +347,7 @@
${_flags_flag_} ${__FLAGS_INFO_SHORT_STR}`
if [ "${_flags_shortName_}" != "${__FLAGS_NULL}" ]; then
_flags_opts_="${_flags_opts_}${_flags_shortName_}"
- # getopt needs a trailing ':' to indicate a needed option
+ # getopt needs a trailing ':' to indicate a required argument
[ ${_flags_type_} -ne ${__FLAGS_TYPE_BOOLEAN} ] && \
_flags_opts_="${_flags_opts_}:"
fi
@@ -365,7 +355,7 @@
${__FLAGS_OPTSTR_LONG})
_flags_opts_="${_flags_opts_:+${_flags_opts_},}${_flags_flag_}"
- # getopt needs a trailing ':' to indicate a needed option
+ # getopt needs a trailing ':' to indicate a required argument
[ ${_flags_type_} -ne ${__FLAGS_TYPE_BOOLEAN} ] && \
_flags_opts_="${_flags_opts_}:"
;;
@@ -554,7 +544,7 @@
# @: varies: command-line options to parse
# Returns:
# integer: a FLAGS success condition
-_flags_standardGetopt()
+_flags_getoptStandard()
{
flags_return=${FLAGS_TRUE}
_flags_shortOpts_=`_flags_genOptStr ${__FLAGS_OPTSTR_SHORT}`
@@ -593,7 +583,7 @@
# @: varies: command-line options to parse
# Returns:
# integer: a FLAGS success condition
-_flags_enhancedGetopt()
+_flags_getoptEnhanced()
{
flags_return=${FLAGS_TRUE}
_flags_shortOpts_=`_flags_genOptStr ${__FLAGS_OPTSTR_SHORT}`
@@ -627,7 +617,6 @@
# integer: a FLAGS success condition
_flags_parseGetopt()
{
- FLAGS_ARGC=0
flags_return=${FLAGS_TRUE}
if [ ${__FLAGS_GETOPT_VERS} -ne ${__FLAGS_GETOPT_VERS_ENH} ]; then
@@ -637,6 +626,13 @@
eval set -- "$@"
fi
+ # provide user with number of arguments to shift by later
+ # NOTE: the FLAGS_ARGC variable is obsolete as of 1.0.3 because it does not
+ # properly give user access to non-flag arguments mixed in between flag
+ # arguments. Its usage was replaced by FLAGS_ARGV, and it is being kept only
+ # for backwards compatibility reasons.
+ FLAGS_ARGC=`expr $# - 1 - ${__flags_argc}`
+
# handle options. note options with values must do an additional shift
while true; do
_flags_opt_=$1
@@ -743,15 +739,16 @@
fi
fi
- # shift the option out
+ # shift the option and non-boolean arguements out.
shift
- FLAGS_ARGC=`expr ${FLAGS_ARGC} + 1`
+ [ ${_flags_type_} != ${__FLAGS_TYPE_BOOLEAN} ] && shift
+ done
- # additional shift for the argument
- if [ ${_flags_type_} != ${__FLAGS_TYPE_BOOLEAN} ]; then
- shift
- FLAGS_ARGC=`expr ${FLAGS_ARGC} + 1`
- fi
+ # give user back non-flag arguments
+ FLAGS_ARGV=''
+ while [ $# -gt 0 ]; do
+ FLAGS_ARGV="${FLAGS_ARGV:+${FLAGS_ARGV} }'$1'"
+ shift
done
unset _flags_arg_ _flags_len_ _flags_name_ _flags_opt_ _flags_pos_ \
@@ -795,12 +792,14 @@
[ -z "${__flags_help_type:-}" ] && \
DEFINE_boolean 'help' false 'show this help' 'h'
+ # record original number of args for use elsewhere
+ __flags_argc=$#
+
# parse options
- # TODO(kward): look into '-T' option to test the internal getopt() version
if [ ${__FLAGS_GETOPT_VERS} -ne ${__FLAGS_GETOPT_VERS_ENH} ]; then
- _flags_standardGetopt "$@"
+ _flags_getoptStandard "$@"
else
- _flags_enhancedGetopt "$@"
+ _flags_getoptEnhanced "$@"
fi
flags_return=$?
diff --git a/source/1.0/src/shflags_test_parsing.sh b/source/1.0/src/shflags_test_parsing.sh
index c027522..bc5e534 100755
--- a/source/1.0/src/shflags_test_parsing.sh
+++ b/source/1.0/src/shflags_test_parsing.sh
@@ -10,6 +10,7 @@
# shFlags unit test for the flag definition methods
#
# TODO(kward): assert on FLAGS errors
+# TODO(kward): testNonStandardIFS()
# load test helpers
. ./shflags_test_helpers
@@ -20,12 +21,12 @@
testStandardGetopt()
{
- _flags_standardGetopt '-b' >"${stdoutF}" 2>"${stderrF}"
+ _flags_getoptStandard '-b' >"${stdoutF}" 2>"${stderrF}"
rslt=$?
assertTrue "didn't parse valid flag 'b'" ${rslt}
th_showOutput ${rslt} "${stdoutF}" "${stderrF}"
- _flags_standardGetopt '-x' >"${stdoutF}" 2>"${stderrF}"
+ _flags_getoptStandard '-x' >"${stdoutF}" 2>"${stderrF}"
assertFalse "parsed invalid flag 'x'" $?
}
@@ -33,14 +34,14 @@
{
flags_getoptIsEnh || startSkipping
- _flags_enhancedGetopt '-b' >"${stdoutF}" 2>"${stderrF}"
+ _flags_getoptEnhanced '-b' >"${stdoutF}" 2>"${stderrF}"
assertTrue "didn't parse valid flag 'b'" $?
- _flags_enhancedGetopt '--bool' >"${stdoutF}" 2>"${stderrF}"
+ _flags_getoptEnhanced '--bool' >"${stdoutF}" 2>"${stderrF}"
assertTrue "didn't parse valid flag 'bool'" $?
- _flags_enhancedGetopt '-x' >"${stdoutF}" 2>"${stderrF}"
+ _flags_getoptEnhanced '-x' >"${stdoutF}" 2>"${stderrF}"
assertFalse "parsed invalid flag 'x'" $?
- _flags_enhancedGetopt '--xyz' >"${stdoutF}" 2>"${stderrF}"
+ _flags_getoptEnhanced '--xyz' >"${stdoutF}" 2>"${stderrF}"
assertFalse "parsed invalid flag 'xyz'" $?
}
@@ -231,15 +232,15 @@
_testNonFlagArgs()
{
- argc=$1
+ argv=$1
shift
- FLAGS $@
- assertTrue 'parse returned value.' $?
+ FLAGS "$@"
+ assertTrue 'parse returned non-zero value.' $?
- # shift out the parsed arguments to reach those that weren't parsed
- shift ${FLAGS_ARGC}
- assertSame 'wrong argc value.' ${argc} $#
+ eval set -- "${FLAGS_ARGV}"
+ assertEquals 'wrong count of argv arguments returned.' ${argv} $#
+ assertEquals 'wrong count of argc arguments returned.' 0 ${FLAGS_ARGC}
}
testSingleNonFlagArg()
@@ -254,10 +255,33 @@
testMultipleNonFlagStringArgsWithSpaces()
{
- _testNonFlagArgs 3 argOne 'arg #2' arg3
+ _testNonFlagArgs 3 argOne 'arg two' arg3
}
-# TODO(kward): testNonStandardIFS()
+testFlagsWithEquals()
+{
+ FLAGS --str='str_flag' 'non_flag' >"${stdoutF}" 2>"${stderrF}"
+ assertTrue 'FLAGS returned a non-zero result' $?
+ assertEquals 'string flag not set properly' 'str_flag' "${FLAGS_str}"
+ th_showOutput ${rtrn} "${stdoutF}" "${stderrF}"
+
+ eval set -- "${FLAGS_ARGV}"
+ assertEquals 'wrong count of argv arguments returned.' 1 $#
+ assertEquals 'wrong count of argc arguments returned.' 1 ${FLAGS_ARGC}
+}
+
+testComplicatedCommandLine()
+{
+ FLAGS -i 1 --str='two' non_flag_1 --float 3 non_flag_two 'non flag 3' \
+ >"${stdoutF}" 2>"${stderrF}"
+ assertTrue 'FLAGS returned a non-zero result' $?
+ assertEquals 1 ${FLAGS_int}
+ assertEquals 'two' "${FLAGS_str}"
+ assertEquals 3 ${FLAGS_float}
+
+ eval set -- "${FLAGS_ARGV}"
+ assertEquals $# 3
+}
#------------------------------------------------------------------------------
# suite functions