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