prepare release v0.6.4-with-no-mangle-double-dash

Author: Sylvain Viart

README.md

@@ -8,7 +8,7 @@ Status: working.
 
 Most concepts are documented in the `docopt` (without S) manual - see [docopt.org](http://docopt.org/).
 
-Many examples use associative arrays in bash 4.x, but there is legacy support for bash 3.2 on macOS (OS X) or legacy
+Many examples use associative arrays in Bash 4+, but there is legacy support for Bash 3.2 on macOS (OS X) or legacy
 GNU/Linux OS.
 
 [make README.md]: # (./docopts --version | get_version "This is a bug fix release:")
@@ -68,18 +68,24 @@ code. Double-dash `--` will be kept.
 `<prefix>` + `_` + `Mangled_name`.
 
 * `--Long-Option` ==> `prefix_Long_Option`
+* etc.
 
-Which makes it easy to filter variable with `grep` or such or to avoid globals
-name collision.
+Note that prefixed invalid mangled names still raise an error, if they resolve to
+invalid bash identifier.
+
+Prefix gobals variable makes it easy to filter variable with `grep` or such or to
+avoid globals name collision.
 
 Handling `[-]` in global mode is not supported and raises an error when trying to mangle `-`.
-But works for any other modes including `-G`.
+But works for any other modes including `-G`. This behavior differs from python's version of
+`docopts` which would have skiped the positional `-` without error.
+
 ```
 ./docopts -h 'Usage: dump [-]' : -
 docopts:error: Print_bash_global:Mangling not supported for: '-'
 ```
 
-Single-dash can be catch easily by reading it in `FILENAME` parameter:
+Single-dash can be catch easily by reading it into a `FILENAME` parameter:
 
 ```bash
 ./docopts  -h 'Usage: prog parse FILENAME' : parse -
@@ -96,10 +102,12 @@ if [[ $f == '-' ]] ; then
 fi
 ```
 
+A working example is provided in [examples/legacy_bash/cat-n_wrapper_example.sh](examples/legacy_bash/cat-n_wrapper_example.sh)
+
 ### Associative Array mode
 
 Alternatively, `docopts` can be invoked with the `-A <name>` option, which
-stores the parsed arguments as fields of a Bash 4 associative array called
+stores the parsed arguments as fields of a Bash 4+ associative array called
 `<name>` instead.  However, as Bash does not natively support nested arrays,
 they are faked for repeatable arguments with the following access syntax:
 
@@ -171,7 +179,7 @@ Options:
                                 first one that does not begin with a dash will
                                 be treated as positional arguments.
   -H, --no-help                 Don't handle --help and --version specially.
-  -A <name>                     Export the arguments as a Bash 4.x associative
+  -A <name>                     Export the arguments as a Bash 4+ associative
                                 array called <name>.
   -G <prefix>                   Don't use associative array but output
                                 Bash 3.2 compatible GLOBAL variables assignment:
@@ -189,9 +197,9 @@ Options:
 
 ## COMPATIBILITY
 
-Bash 4.x and higher is the main target.
+Bash 4+ and higher is the main target.
 
-In order to use `docopts` with bash 3.2 (for macOS and old GNU/Linux versions) by avoiding bash >4.x associative arrays,
+In order to use `docopts` with Bash 3.2 (for macOS and old GNU/Linux versions) by avoiding bash >4.x associative arrays,
 you can:
 
 * don't use the `-A` option
@@ -280,7 +288,7 @@ for arg in "${argv[@]}"; do
 done
 ```
 
-The next example shows how using the Bash 4.x associative array with `-A`:
+The next example shows how using the Bash 4+ associative array with `-A`:
 
 ```bash
 help="
@@ -310,7 +318,9 @@ done
 `docopts` was first developed by Lari Rasku <rasku@lavabit.com> and was written in Python based on the
 [docopt Python parser](https://github.com/docopt/docopt).
 
-The current version is written in [go](https://golang.org/) and is 100% compatible with previous Python-based `docopts`.
+The current version is written in [go](https://golang.org/) and is almost 100% compatible with previous Python-based `docopts`.
+See section `Global mode` for incompatibly details and provided work around.
+
 Please report any non working code with [issue](https://github.com/docopt/docopts/issues) and examples.
 
 ## Roadmap: A new shell API is proposed
@@ -392,7 +402,7 @@ Tested builds are built on:
 [make README.md]: # (go version)
 
 ```
-go version go1.14.1 linux/amd64
+go version go1.17.1 linux/amd64
 ```
 
 ## Features
@@ -405,9 +415,9 @@ documentation](docs/README.md).
 
 `docopts` doesn't need a python interpreter anymore, so it works on any legacy system too.
 
-As of 2019-05-18
+As of 2021-09-15
 
-* `docopts` is able to reproduce 100% of the python version.
+* `docopts` is able to reproduce almost 100% of the python version.
 * unit tests for Go are provided, so hack as you wish.
 * 100% of `language_agnostic_tester.py` tests pass (GNU/Linux 64bits).
 * `bats-core` unittests and functional testing are provided too.

TODO.md

@@ -2,18 +2,18 @@
 
 ## PR52
 
-
 * ~~add unit test for corner case (`mangle_name` removes option `[--]`)~~
 * ~~document how to add unittest in Go~~
 * ~~document behavior parsing `--` `[--]` in global mode~~
 * ~~add examples of `[--]` usage in global mode~~
 * ~~add `language_agnostic_tester.py` input test~~
 * ~~better error message from `docopts`~~ no so better
-* also document `delv` debugger usage in delevopper's doc
+* ~~also document `delve` debugger usage in delevopper's doc~~
 * ~~update comment about version 0.6.3 and python compatibility~~
-* test python've version behavior with our input
-* add example of usage for handling `-` (stdin argument)
-* add functional testcase in bats with corner case `--no-mangle` `-G` etc.
+* ~~add functional testcase in bats with corner case `--no-mangle` `-G` etc.~~
+* ~~test python's version behavior with our input~~
+* ~~add example of usage for handling `-` (stdin argument)~~
+* ~~remove 100% compatible with python~~
 
 ## better error handling
 

common_input_test.json

@@ -97,6 +97,13 @@
       "p=false",
       "unparsed_option=('one' '-p' '-auto-approve' 'two')",
       "double_dash=true"
+    ],
+    "expect_global_prefix": [
+      "ARGS___=true",
+      "ARGS_o=false",
+      "ARGS_p=false",
+      "ARGS_unparsed_option=('one' '-p' '-auto-approve' 'two')",
+      "ARGS_double_dash=true"
     ]
   }
 ]

deployment.yml

@@ -23,17 +23,19 @@ releases:
 
       features changes:
         - fix error refusing mangling double dash in global mode [#52]
-        - still refuse to mangle single dash `[-]` in global mode
-        - now can mangle single dash in `-G` mode
+        - still refuse to mangle single dash `[-]` in global mode (not compatible with v0.6.1)
+        - now can mangle single-dash and double-dash in `-G` mode
 
       internal changes:
+        - use Go 1.17.1 for compiling
         - `language_agnostic_tester.py` re-write for python3
         - sort argument key in `Print_bash_args()` `Print_bash_global()`
         - sort input keys in `docopts_test.go`
-        - add PR52 test to `testcases.docopt`
+        - add PR #52 test to `testcases.docopt`
         - completed developper's documentation
         - #52 ignore `[--]` double-dash option in `Print_bash_global()`
         - reformat of Go code with gofmt indent change Space ==> Tab
+        - add `tests/functional_tests_docopts.bats`
 
   v0.6.3-rc2:
     name: "docopts binary transitional v0.6.3-rc2"

docopts.go

@@ -26,14 +26,14 @@ var (
 )
 
 var copyleft = `
-Copyright (C) 2013 Vladimir Keleshev, Lari Rasku.
 Copyleft (Ɔ)  2021 Sylvain Viart (golang version).
+Copyright (C) 2013 Vladimir Keleshev, Lari Rasku.
 License MIT <http://opensource.org/licenses/MIT>.
 This is free software: you are free to change and redistribute it.
 There is NO WARRANTY, to the extent permitted by law.
 `
 
-// Version will be build by main
+// Version will be build by main() function
 var Docopts_Version string
 
 var Usage string = `Shell interface for docopt, the CLI description language.
@@ -65,7 +65,7 @@ Options:
                                 first one that does not begin with a dash will
                                 be treated as positional arguments.
   -H, --no-help                 Don't handle --help and --version specially.
-  -A <name>                     Export the arguments as a Bash 4.x associative
+  -A <name>                     Export the arguments as a Bash 4+ associative
                                 array called <name>.
   -G <prefix>                   Don't use associative array but output
                                 Bash 3.2 compatible GLOBAL variables assignment:
@@ -112,7 +112,7 @@ type Docopts struct {
 	Exit_function  bool
 }
 
-// output bash 4 compatible assoc array, suitable for eval.
+// output bash 4+ compatible assoc array, suitable for eval.
 func (d *Docopts) Print_bash_args(bash_assoc string, args docopt.Opts) {
 	// Reuse python's fake nested Bash arrays for repeatable arguments with values.
 	// The structure is:
@@ -197,7 +197,7 @@ func To_bash(v interface{}) string {
 	return s
 }
 
-// Performs output for bash Globals (not bash 4 assoc) Names are mangled to become
+// Performs output for bash Globals (not bash 4+ assoc) Names are mangled to become
 // suitable for bash eval.
 // If Docopts.Mangle_key is false: simply print left-hand side assignment verbatim.
 // used for --no-mangle

docopts_test.go

@@ -270,7 +270,14 @@ func TestPrint_bash_global(t *testing.T) {
 			t.Errorf("Print_bash_global doesn't return nil for err: %v\n", err)
 		}
 		res := out.(*bytes.Buffer).String()
-		expect := rewrite_prefix("ARGS", table.Expect_global)
+
+		var expect string
+		if len(table.Expect_global_prefix) > 0 {
+			// if special case was provided
+			expect = strings.Join(table.Expect_global_prefix[:], "\n") + "\n"
+		} else {
+			expect = rewrite_prefix("ARGS", table.Expect_global)
+		}
 		if res != expect {
 			t.Errorf("with prefix: Print_bash_global for '%v'\ngot: '%v'\nwant: '%v'\n", table.Input, res, expect)
 		}

docs/developer.md

@@ -127,6 +127,7 @@ type TestString struct {
     Input map[string]interface{}
     Expect_args []string
     Expect_global  []string
+    Expect_global_prefix  []string // optional
 }
 ```
 
@@ -161,6 +162,8 @@ add a new bloc of JSON object (dict / hash / map):
 * `input` correspond to the `map[string]interface{}` of docopt parsed options.
 * `expect_args` the text rows of the associative array code for bash4 that is outputed by `Print_bash_args()` matched in order.
 * `expect_global` the text definition of the bash global vars that is outputed by `Print_bash_global()` matched in order.
+* `expect_global_prefix` [optional] if present will be used for testing `Mangle_key` + `Global_prefix` instead of [`rewrite_prefix("ARGS",)`](../docopts_test.go)
+  So in `expect_global_prefix` the prefix must be `ARGS` + `_`.
 
 
 ### testcases.docopt (agnostic test universal to docopt parsing language)
@@ -185,3 +188,33 @@ $ prog -a
 ```
   * followed with the exptected output in JSON format (single ligne) (no empty line between `prog` call and expected JSON)
   * `\n` newline separator if some other call are added for the same `Usage:` definition
+
+## Golang debugger
+
+Debugger is a must for any programming language. Go provide an extrenal debugger named [delve](https://github.com/go-delve/delve)
+
+https://github.com/go-delve/delve/tree/master/Documentation
+
+In order to debug `docopts` you obviously need to pass command line argument to our program:
+Our arguments start after the first `--` which is `delve` argument stopper.
+
+```
+cd path/to/docopts/source
+dlv debug -- -h 'Usage: prog dump [--] <unparsed_arguments>...' : dump -- -some -auto-approve FILENAME
+```
+
+The as usual in debugger:
+
+```
+# put break point in main function
+b main.main
+continue
+n
+s # for steping into the current function
+# printing some value
+p some_varialbles
+```
+
+The debugger will then magically bring you step after step to the bug!
+Enjoy! and promote dubugger in evrery programming language and every programming course. :wink:
+

docs/release.md

@@ -4,16 +4,16 @@ Step to produce a release.
 
 ## 1. prepare the release
 
-copy the previous ./VERSION to ./tests/VERSION
+copy the previous `./VERSION` to `./tests/VERSION`
 
 ```
 cp ./VERSION ./tests/VERSION
 git add ./tests/VERSION
 ```
 
-Increment the ./VERSION number
+Increment the `./VERSION` number
 
-edit ./deployment.yml
+edit `./deployment.yml`
 
 - add the new tag name release matching ./VERSION
 - the description you want, changes etc.
@@ -30,6 +30,7 @@ make test
 Ensure README.md is commited and rebuild it too
 
 ```
+touch build_doc.sh
 make README.md
 ```
 

examples/legacy_bash/cat-n_wrapper_example.sh

@@ -5,7 +5,7 @@
 # Usage: cat-n_wrapper_example.sh [--count=N] FILE...
 #
 # Arguments:
-#   FILE     input file
+#   FILE     input file, if FILLE equal - stdin is used instead.
 #
 # Options:
 #   --count=N   limit the number of line to display