final commit in branch before merge to master

TODO.md

@@ -14,6 +14,7 @@
 * ~~test python's version behavior with our input~~
 * ~~add example of usage for handling `-` (stdin argument)~~
 * ~~remove 100% compatible with python~~
+* ~~add documentation on how to add functional testing in bats~~
 
 ## better error handling
 
@@ -23,28 +24,50 @@ See also:
 
 PR: https://github.com/docopt/docopt.go/pull/65
 
+It probably needs to rewrite the docopt parser.
+
 ## --json output ?
 
 same as `--no-mangle` but json formated
 
 Somewhat discussed here: https://github.com/docopt/docopt/issues/174
 
+Trivial, could be implemented, even without embbeding JSON lib.
+See branch `json-api` too.
+
 ## functional testing for all options
 
 `./docopts --help`
+* `tests/functional_tests_docopts.bats` was introduced in PR #52
 
 ## return or kill for function instead of exit
 
 Add a parameter to handle return or kill instead of exit so it can be launched inside a function.
 
+See also: https://github.com/docopt/docopts/issues/43
+
 ## embeded JSON?
 
 See [API_proposal.md](API_proposal.md)
 
+Drop JSON but keep new command line action arguments option style?
+
+```
+docopts parse "$usage" : [<args>...]
+```
+
 ## generate bash completion from usage
 
+Would probably need a new docopt parser too.
+
+```
+docopts -h "$help" --generate-completion
+```
+
 ```
 docopts -h "$help" --generate-completion
+# or
+docopts completion "$usage"
 ```
 
 ## embed test routine (argument validation)?

docker/README.md

@@ -0,0 +1,23 @@
+# Some docker container with docopts installed
+
+No special purpose than to recreate an environment with `docopts`
+
+## Build the docker image
+
+The `--build-arg` is used to pass teh version of `docpots` to download pre-built binary.
+If you're publishing `docpots` the `../VERSION` may not yet reflect a published version.
+You can find previously published VERSION in `../tests/VERSION`.
+
+```
+docker build -f debian-docopts.Dockerfile --build-arg VERSION=$(cat ./VERSION) -t debian-docpots .
+```
+
+## Run interactive
+
+You will have latest python version 0.6.1 in PATH as `docopts` and Go version in PATH too as `docopts0`
+
+Golang work space will also be installed if you want to test something.
+
+```
+docker run -it debian-docpots:latest
+```

bug/double_dash_mangle/Dockerfile → docker/debian-docopts.Dockerfile

@@ -19,26 +19,19 @@ RUN apt-get install -y --no-install-recommends \
 WORKDIR /app
 COPY *.sh \
     /app/
-RUN chmod a+x test-docopts.sh
 
-# install precompiled binary publiished ==> docopts0
-RUN wget https://github.com/docopt/docopts/releases/download/v0.6.3-rc2/docopts_linux_amd64
+# install precompiled binary published ==> docopts0
+ARG VERSION
+RUN wget https://github.com/docopt/docopts/releases/download/$VERSION/docopts_linux_amd64
 RUN install -o root -g root -m a+x docopts_linux_amd64 /usr/local/bin/docopts0
 
 # install a golang build env
 # predownload the tgz so it get docker cached
-RUN wget --quiet https://dl.google.com/go/go1.14.1.linux-amd64.tar.gz
+RUN wget --quiet https://dl.google.com/go/go1.17.1.linux-amd64.tar.gz
 RUN ./update_go.sh
 ENV PATH=$PATH:/app:/usr/local/go/bin:/root/go/bin
 
-# clone patched version from contributor repository
-RUN git clone -b do-not-publish-double-dash https://github.com/DanaLacoste/docopts.git patched
-
-# prepare gobuilding pre-requisites
-WORKDIR /app/patched
 RUN go get github.com/docopt/docopt-go && go get github.com/docopt/docopts
-# build patched version
-RUN go build docopts.go
 
 # intall python version 0.6.1 ==> /usr/local/bin/docopts
 RUN pip3 install docopts

bug/double_dash_mangle/update_go.sh → docker/update_go.sh

@@ -17,7 +17,7 @@ set -e
 
 # change this go version for updating
 # can be copy/paste from the email announcing the version
-GOVER=go1.14.1
+GOVER=go1.17.1
 
 if [[ $actual_gover == $GOVER ]] ; then
   echo "$gobin version: $actual_gover is the same as $GOVER"

docopts.go

@@ -183,7 +183,7 @@ func To_bash(v interface{}) string {
 	case []string:
 		arr := v.([]string)
 		if len(arr) == 0 {
-			// bash emtpy array
+			// bash empty array
 			s = "()"
 		} else {
 			// escape all strings

docs/developer.md

@@ -108,6 +108,43 @@ go test -v
 
 ### bats (functionnal testing) (bash)
 
+Most `.bats` files in `tests/` folder are test for bash code `docopts.sh` functions,
+and are more internal stuff, hack as you wish but it may be more complicated to
+handle at first.
+
+Functional tests are in [`tests/functional_tests_docopts.bats`](tests/functional_tests_docopts.bats).
+
+This this `bats` syntax test, this means almost bash.
+
+Add a new functional test:
+
+```
+@test "your comment describing the test here" {
+    # run is a bats helper that run a command catching all
+    # use the $DOCOPTS_BIN to ensure to point to the good binary
+    # pass any docopts argument to test, good or wrong
+    run $DOCOPTS_BIN -G ARGS -h 'Usage: prog dump [-]' : dump -
+
+    # output is caught by bats (stdout + stderr)
+    # and wont be displayed, unless a test fail: any non-0 bash code
+    echo "$output"
+
+    # test docopts return value 0 on success
+    [[ $status -eq 0 ]]
+
+    regexp='some bash regexp'
+    [[ "$output" =~  $regexp ]]
+}
+```
+
+run only functional test (`bats` in `PATH`):
+
+``` bash
+# test are ran from test folder only
+cd tests
+bats functional_tests_docopts.bats
+```
+
 ### `docopts_test.go` (unit testing) (golang + JSON)
 
 It uses standard `go test`. Some method are "exposed" with Capital name only for testing purpose.
@@ -119,14 +156,14 @@ Options loop test JSON: [`common_input_test.json`](../common_input_test.json)
 This is our input file for testing options parsed recieved from docopt lib. We emulate docopt parsed options and give
 them as input to our method.
 
-JSON tests are read as a list of test: (others json keys should be ignored and are used as comment)
+JSON tests are read as a list of test: (others JSON keys should be ignored and are used as comment)
 Our parser JSON parser / loader [`test_json_load.go`](../test_json_load/test_json_load.go), only used for testing.
 
 ```go
 type TestString struct {
-    Input map[string]interface{}
-    Expect_args []string
-    Expect_global  []string
+    Input                 map[string]interface{}
+    Expect_args           []string
+    Expect_global         []string
     Expect_global_prefix  []string // optional
 }
 ```
@@ -153,25 +190,29 @@ add a new bloc of JSON object (dict / hash / map):
     ],
     "expect_global": [
       "FILE=('pipo' 'molo' 'toto')"
+    ],
+    "expect_global_prefix": [
+      "ARGS_FILE=('pipo' 'molo' 'toto')"
     ]
   },
 ```
 
 * `description` a comment which is ignored
-* other extra JSON key that are not the 3 following will be ignored too.
+* other extra JSON key that are not the 4 following will be ignored too.
 * `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` + `_`.
+  So left hand values in `expect_global_prefix` the prefix must be `ARGS` + `_`.
 
 
 ### testcases.docopt (agnostic test universal to docopt parsing language)
 
-This file is still avaible from python docopt original repository too [testcases.docopt](https://github.com/docopt/docopt/blob/511d1c57b59cd2ed663a9f9e181b5160ce97e728/testcases.docopt)
+This file is still avaible from python docopt lib original repository
+too [testcases.docopt](https://github.com/docopt/docopt/blob/511d1c57b59cd2ed663a9f9e181b5160ce97e728/testcases.docopt)
 
 This is the input file used by `language_agnostic_tester.py`, which is a middleware originaly written to read
-`testcases.docopt` and to send it to ~> `testee.sh` ~> `docopts` ~> JSON ~> the result is the validated against the
+`testcases.docopt` and to send it to ~> `testee.sh` ~> `docopts -A` ~> JSON ~> the result is the validated against the
 embedded JSON expected result.
 
 Input file format is historically as follow:
@@ -191,7 +232,7 @@ $ prog -a
 
 ## Golang debugger
 
-Debugger is a must for any programming language. Go provide an extrenal debugger named [delve](https://github.com/go-delve/delve)
+Debugger is a must for any programming language. Go provides an extrenal debugger named [delve](https://github.com/go-delve/delve)
 
 https://github.com/go-delve/delve/tree/master/Documentation
 
@@ -215,6 +256,6 @@ s # for steping into the current function
 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:
+The debugger will then magically bring you, step after step, to the bug!
+Enjoy! and promote dubugger in every programming language and every programming course. :wink: