kate.ward | c521068 | 2009-03-30 18:54:36 +0000 | [diff] [blame] | 1 | ------------------------------ |
| 2 | shFlags.sh 1.0.3 Release Notes |
| 3 | ------------------------------ |
| 4 | |
| 5 | Preface |
| 6 | ======= |
kate.ward | b117191 | 2009-05-10 18:00:48 +0000 | [diff] [blame] | 7 | Copyright 2008-2009 Kate Ward. All Rights Reserved. |
kate.ward | c521068 | 2009-03-30 18:54:36 +0000 | [diff] [blame] | 8 | Released under the LGPL (GNU Lesser General Public License) |
kate.ward | b117191 | 2009-05-10 18:00:48 +0000 | [diff] [blame] | 9 | Author: kate.ward@forestent.com (Kate Ward) |
kate.ward | c521068 | 2009-03-30 18:54:36 +0000 | [diff] [blame] | 10 | |
| 11 | This document covers any known issues and workarounds for the stated release of |
| 12 | shFlags. |
| 13 | |
| 14 | Release info |
| 15 | ============ |
| 16 | |
kate.ward | b117191 | 2009-05-10 18:00:48 +0000 | [diff] [blame] | 17 | This is a major bug fix release. The biggest fix is in how non-flag arguments are |
kate.ward | 4fdd0c8 | 2009-04-24 00:12:43 +0000 | [diff] [blame] | 18 | made available to the script. |
kate.ward | c521068 | 2009-03-30 18:54:36 +0000 | [diff] [blame] | 19 | |
| 20 | Major changes |
| 21 | ------------- |
| 22 | |
| 23 | The use of the ``FLAGS_ARGC`` variable is now obsolete. It will be maintained |
| 24 | for backwards compatibility with old scripts, but its value is known to be |
| 25 | wrong when flag and non-flag arguments are mixed together on the command-line. |
| 26 | |
| 27 | To gain access to the non-flag arguments, replace the following snippet of code |
| 28 | in your scripts with the updated version. |
| 29 | |
kate.ward | 812aeae | 2009-04-01 02:49:51 +0000 | [diff] [blame] | 30 | old :: |
| 31 | shift ${FLAGS_ARGC} |
| 32 | |
| 33 | new :: |
| 34 | eval set -- "${FLAGS_ARGV}" |
kate.ward | c521068 | 2009-03-30 18:54:36 +0000 | [diff] [blame] | 35 | |
| 36 | Please see the CHANGES-1.0.txt file for a complete list of changes. |
| 37 | |
| 38 | Obsolete items |
| 39 | -------------- |
| 40 | |
| 41 | Bug fixes |
| 42 | --------- |
| 43 | |
| 44 | Issue# 7 Flags set with '=' result in off-by-one shifting error |
| 45 | |
| 46 | General info |
| 47 | ============ |
| 48 | |
| 49 | The unit tests |
| 50 | -------------- |
| 51 | |
| 52 | shFlags is designed to work on as many environments as possible, but not all |
| 53 | environments are created equal. As such, not all of the unit tests will succeed |
| 54 | on every platform. The unit tests are therefore designed to fail, indicating to |
| 55 | the tester that the supported functionality is not present, but an additional |
| 56 | test is present to verify that shFlags properly caught the limitation and |
| 57 | presented the user with an appropriate error message. |
| 58 | |
| 59 | shFlags tries to support both the standard and enhanced versions of ``getopt``. |
| 60 | As each responds differently, and not everything is supported on the standard |
| 61 | version, some unit tests will be skipped (i.e. ASSERTS will not be thrown) when |
| 62 | the standard version of ``getopt`` is detected. The reason being that there is |
| 63 | no point testing for functionality that is positively known not to exist. A |
| 64 | tally of skipped tests will be kept for later reference. |
| 65 | |
| 66 | Standard vs Enhanced getopt |
| 67 | --------------------------- |
| 68 | |
| 69 | Here is a matrix of the supported features of the various **getopt** variants. |
| 70 | |
kate.ward | 4fdd0c8 | 2009-04-24 00:12:43 +0000 | [diff] [blame] | 71 | +=========================================+=====+=====+ |
| 72 | | Feature | std | enh | |
| 73 | +-----------------------------------------+-----+-----+ |
| 74 | | short option names | Y | Y | |
| 75 | | long option names | N | Y | |
| 76 | | spaces in string options | N | Y | |
| 77 | | intermixing of flag and non-flag values | N | Y | |
| 78 | +=========================================+=====+=====+ |
kate.ward | c521068 | 2009-03-30 18:54:36 +0000 | [diff] [blame] | 79 | |
| 80 | Known Issues |
| 81 | ------------ |
| 82 | |
| 83 | The **getopt** version provided by default with all versions of Mac OS X (up to |
kate.ward | ccb66b4 | 2009-04-01 14:08:44 +0000 | [diff] [blame] | 84 | and including 10.5.6) and Solaris (up to and including Solaris 10 and |
kate.ward | 4fdd0c8 | 2009-04-24 00:12:43 +0000 | [diff] [blame] | 85 | OpenSolaris) is the standard version. |
kate.ward | c521068 | 2009-03-30 18:54:36 +0000 | [diff] [blame] | 86 | |
| 87 | Workarounds |
| 88 | ----------- |
| 89 | |
kate.ward | 4fdd0c8 | 2009-04-24 00:12:43 +0000 | [diff] [blame] | 90 | The Zsh shell requires the ``shwordsplit`` option to be set and the special |
| 91 | ``FLAGS_PARENT`` variable must be defined. See ``src/shflags_test_helpers`` to |
| 92 | see how the unit tests do this. |
kate.ward | c521068 | 2009-03-30 18:54:36 +0000 | [diff] [blame] | 93 | |
| 94 | .. vim:fileencoding=latin1:ft=rst:spell:tw=80 |