Support bash 3.2 and provide more examples

[rdonkin]

Fixes are useful since bash 3.2 is highest version on macOS (due to Apple's GPLv3 policy).

• updated - change how docopt_sh_me is computed - required for bats tests in submodule
• change one sed command to use POSIX regex for optional space
• highlight functions that require bash 4 - all other code should work on bash 3.2

Also updated legacy_bash directory to include more bash 3.x examples

• only changes to scripts copied from main dir are using -G with docopts
• the sshdiff.sh script depends on bash 4, so moved this to main examples dir.

[rdonkin]

Travis tests seem to be flaky - getting failures on PR #26 which is only updating README.

[rdonkin]

@Sylvain303 any comments on this?

Together with #15 (happy to do that one as it seems to be just changing shebang lines), this would give quite good bash 3.2 / Mac support.

[Sylvain303]

@rdonkin sorry, I'm quite busy for this Week End, I will come back at random time for the next 7 days.

[Sylvain303]

For readlink my goal is to find the path of the folder where the scripts is, in order to compute relative path to useful scripts if any. As you've seen is was not used in docopts.sh itself but in functional tests.

here they use the head -1 tricks.

expand_link() {
  readlink="$(type -p greadlink readlink | head -1)"
  "$readlink" -f "$1"
}

It was present is the code, does it fail? (was working in GNU/Linux)

 docopt_sh_me=$($(type -p greadlink readlink | head -1 ) -f "${BASH_SOURCE[0]}") 

We could add some similar function to docopts.sh because I not a big fan of using (cd, pushd, popd + using file descriptor for /dev/null etc.) just to read a fullpath from a file. May be stat --format='%N'?

I sometime use local symlink ~/bin/docopts -> ~/path/to/dev/copy/docopts/docopts and $PATH. That's why I'm resolving symlinks. But for now, I also use relative PATH ./docopts to be sure. Also in local repository code. But docopts.sh is an helper and it can be installed somewhere in $PATH. So relatives PATH is not an option here.

Thanks for your contribution.

[Sylvain303]

For sshdiff.sh it was supposed to be a legacy option parser, but was never finished. Even more, it was supposed to be an example showing rewrite from non-docopts script to docopts scripts on legacy scripts.

You are the first person who claim using legacy global variables, that why you have noticed this script using only docopt_print_ARGS (not compatible with masOS older bash 3.2 for now).

docopts.sh is an helper I introduced during the rewrite of docopts to golang. It's a share of my own usage, which may not satisfy users, in fact.

I probably should now develop an helper for displaying globals too. We should discuss it in another issue.

May be adding a new lazy autoparsing switch using -G ARGS:

source docopts.sh --auto-legacy "$@"                                                                                                                                                                 

[rdonkin]

@Sylvain303

On readlink, see this commit, which is quite simple and works whether your path to script is with or without symlinks. Probably works with non-bash shells and BSD Unix as well.

• Just tested this again with ~/docopts as symlink to project directory - so there's no need to use readlink in order to work with symlinks.
• without this commit, the -f option to readlink fails on macOS which doesn't have this (like other BSD Unixes).
• my gist linked in earlier comment has other options that do resolve symlinks, but they are much longer and this isn't necessary to get a working full path
• the bats tests do run OK with this commit (tested on Linux and would work on macOS with bash 4.x shebangs). bats uses readlink/greadlink without -f, which is portable.

On the legacy global variables, I find it easier to use a var like $args_force rather than $ARGS['--force'] - less to type and quite readable. Even on bash 4.x / Linux which is our main platform, I will be using this style.

docopts.sh is quite nice as a way of prototyping features that maybe later can go into docopts.go.

Let me know any changes you'd like in this PR, when you have some time.