1 ------------------------------ 2 shFlags.sh 1.0.3 Release Notes 3 ------------------------------ 4 5 Preface 6 ======= 7 Copyright 2008-2009 Kate Ward. All Rights Reserved. 8 Released under the LGPL (GNU Lesser General Public License) 9 Author: kate.ward (a] forestent.com (Kate Ward) 10 11 This document covers any known issues and workarounds for the stated release of 12 shFlags. 13 14 Release info 15 ============ 16 17 This is a major bug fix release. The biggest fix is in how non-flag arguments are 18 made available to the script. 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 30 old :: 31 shift ${FLAGS_ARGC} 32 33 new :: 34 eval set -- "${FLAGS_ARGV}" 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 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 80 Known Issues 81 ------------ 82 83 The **getopt** version provided by default with all versions of Mac OS X (up to 84 and including 10.5.6) and Solaris (up to and including Solaris 10 and 85 OpenSolaris) is the standard version. 86 87 Workarounds 88 ----------- 89 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. 93 94 .. vim:fileencoding=latin1:ft=rst:spell:tw=80 95
