1*63d4e48fSSadaf Ebrahimi------------------------------ 2*63d4e48fSSadaf EbrahimishFlags.sh 1.0.3 Release Notes 3*63d4e48fSSadaf Ebrahimi------------------------------ 4*63d4e48fSSadaf Ebrahimi 5*63d4e48fSSadaf EbrahimiPreface 6*63d4e48fSSadaf Ebrahimi======= 7*63d4e48fSSadaf EbrahimiCopyright 2008-2009 Kate Ward. All Rights Reserved. 8*63d4e48fSSadaf EbrahimiReleased under the LGPL (GNU Lesser General Public License) 9*63d4e48fSSadaf EbrahimiAuthor: [email protected] (Kate Ward) 10*63d4e48fSSadaf Ebrahimi 11*63d4e48fSSadaf EbrahimiThis document covers any known issues and workarounds for the stated release of 12*63d4e48fSSadaf EbrahimishFlags. 13*63d4e48fSSadaf Ebrahimi 14*63d4e48fSSadaf EbrahimiRelease info 15*63d4e48fSSadaf Ebrahimi============ 16*63d4e48fSSadaf Ebrahimi 17*63d4e48fSSadaf EbrahimiThis is a major bug fix release. The biggest fix is in how non-flag arguments are 18*63d4e48fSSadaf Ebrahimimade available to the script. 19*63d4e48fSSadaf Ebrahimi 20*63d4e48fSSadaf EbrahimiMajor changes 21*63d4e48fSSadaf Ebrahimi------------- 22*63d4e48fSSadaf Ebrahimi 23*63d4e48fSSadaf EbrahimiThe use of the ``FLAGS_ARGC`` variable is now obsolete. It will be maintained 24*63d4e48fSSadaf Ebrahimifor backwards compatibility with old scripts, but its value is known to be 25*63d4e48fSSadaf Ebrahimiwrong when flag and non-flag arguments are mixed together on the command-line. 26*63d4e48fSSadaf Ebrahimi 27*63d4e48fSSadaf EbrahimiTo gain access to the non-flag arguments, replace the following snippet of code 28*63d4e48fSSadaf Ebrahimiin your scripts with the updated version. 29*63d4e48fSSadaf Ebrahimi 30*63d4e48fSSadaf Ebrahimiold :: 31*63d4e48fSSadaf Ebrahimi shift ${FLAGS_ARGC} 32*63d4e48fSSadaf Ebrahimi 33*63d4e48fSSadaf Ebrahiminew :: 34*63d4e48fSSadaf Ebrahimi eval set -- "${FLAGS_ARGV}" 35*63d4e48fSSadaf Ebrahimi 36*63d4e48fSSadaf EbrahimiPlease see the CHANGES-1.0.txt file for a complete list of changes. 37*63d4e48fSSadaf Ebrahimi 38*63d4e48fSSadaf EbrahimiObsolete items 39*63d4e48fSSadaf Ebrahimi-------------- 40*63d4e48fSSadaf Ebrahimi 41*63d4e48fSSadaf EbrahimiBug fixes 42*63d4e48fSSadaf Ebrahimi--------- 43*63d4e48fSSadaf Ebrahimi 44*63d4e48fSSadaf EbrahimiIssue# 7 Flags set with '=' result in off-by-one shifting error 45*63d4e48fSSadaf Ebrahimi 46*63d4e48fSSadaf EbrahimiGeneral info 47*63d4e48fSSadaf Ebrahimi============ 48*63d4e48fSSadaf Ebrahimi 49*63d4e48fSSadaf EbrahimiThe unit tests 50*63d4e48fSSadaf Ebrahimi-------------- 51*63d4e48fSSadaf Ebrahimi 52*63d4e48fSSadaf EbrahimishFlags is designed to work on as many environments as possible, but not all 53*63d4e48fSSadaf Ebrahimienvironments are created equal. As such, not all of the unit tests will succeed 54*63d4e48fSSadaf Ebrahimion every platform. The unit tests are therefore designed to fail, indicating to 55*63d4e48fSSadaf Ebrahimithe tester that the supported functionality is not present, but an additional 56*63d4e48fSSadaf Ebrahimitest is present to verify that shFlags properly caught the limitation and 57*63d4e48fSSadaf Ebrahimipresented the user with an appropriate error message. 58*63d4e48fSSadaf Ebrahimi 59*63d4e48fSSadaf EbrahimishFlags tries to support both the standard and enhanced versions of ``getopt``. 60*63d4e48fSSadaf EbrahimiAs each responds differently, and not everything is supported on the standard 61*63d4e48fSSadaf Ebrahimiversion, some unit tests will be skipped (i.e. ASSERTS will not be thrown) when 62*63d4e48fSSadaf Ebrahimithe standard version of ``getopt`` is detected. The reason being that there is 63*63d4e48fSSadaf Ebrahimino point testing for functionality that is positively known not to exist. A 64*63d4e48fSSadaf Ebrahimitally of skipped tests will be kept for later reference. 65*63d4e48fSSadaf Ebrahimi 66*63d4e48fSSadaf EbrahimiStandard vs Enhanced getopt 67*63d4e48fSSadaf Ebrahimi--------------------------- 68*63d4e48fSSadaf Ebrahimi 69*63d4e48fSSadaf EbrahimiHere is a matrix of the supported features of the various **getopt** variants. 70*63d4e48fSSadaf Ebrahimi 71*63d4e48fSSadaf Ebrahimi+=========================================+=====+=====+ 72*63d4e48fSSadaf Ebrahimi| Feature | std | enh | 73*63d4e48fSSadaf Ebrahimi+-----------------------------------------+-----+-----+ 74*63d4e48fSSadaf Ebrahimi| short option names | Y | Y | 75*63d4e48fSSadaf Ebrahimi| long option names | N | Y | 76*63d4e48fSSadaf Ebrahimi| spaces in string options | N | Y | 77*63d4e48fSSadaf Ebrahimi| intermixing of flag and non-flag values | N | Y | 78*63d4e48fSSadaf Ebrahimi+=========================================+=====+=====+ 79*63d4e48fSSadaf Ebrahimi 80*63d4e48fSSadaf EbrahimiKnown Issues 81*63d4e48fSSadaf Ebrahimi------------ 82*63d4e48fSSadaf Ebrahimi 83*63d4e48fSSadaf EbrahimiThe **getopt** version provided by default with all versions of Mac OS X (up to 84*63d4e48fSSadaf Ebrahimiand including 10.5.6) and Solaris (up to and including Solaris 10 and 85*63d4e48fSSadaf EbrahimiOpenSolaris) is the standard version. 86*63d4e48fSSadaf Ebrahimi 87*63d4e48fSSadaf EbrahimiWorkarounds 88*63d4e48fSSadaf Ebrahimi----------- 89*63d4e48fSSadaf Ebrahimi 90*63d4e48fSSadaf EbrahimiThe Zsh shell requires the ``shwordsplit`` option to be set and the special 91*63d4e48fSSadaf Ebrahimi``FLAGS_PARENT`` variable must be defined. See ``src/shflags_test_helpers`` to 92*63d4e48fSSadaf Ebrahimisee how the unit tests do this. 93*63d4e48fSSadaf Ebrahimi 94*63d4e48fSSadaf Ebrahimi.. vim:fileencoding=latin1:ft=rst:spell:tw=80 95