Adds custom error codes

[nkakouros]

• [x] I have reviewed the contributor guidelines.
• [x] I have reviewed the code of conduct.
• [x] Per GitHub's Terms of Service, I am aware that I license my contribution under the same terms as this project's license, and that I have the right to license my contribution under those terms.

cc: @mbland

This PR is an approach to introducing custom exit codes. This is in relation to #234.

Some notes

• I used the following to pinpoint the lines I needed to edit:

grep -R -E "^[ ]*(return ?[0-9])|(return$)|(exit$)|([^a-zA-Z0-9_-]exit ?[0-9]?$)" . | grep -v './.git'

• There are return x commands that are used by functions to signal either an error or one of two or more possible outcomes. There are also exit x commands to stop script execution. I rewrite both of these.
• Simple return, exit, return 0 or exit 0 commands are rewritten as return "$_GO_EC_OK", etc, where the return code will not be but 0. Although adding nothing in functionality, this is done to be consistent.
• When a function may return with more than one possible return codes or when it is not obvious by the name of the function what its single return code would be, then other functions that call it catch its return code and return with that. Eg, @go() may return with $_GO_EC_CONFIG or $_GO_EC_USAGE. If @go() were to be called by another function, eg @go.for_lack_of_better_example() then it would be called like this:

@go "$@" && ec=0 || ec="$?"
if [[ "$ec" -ne 0 ]]; then
  return "$ec"
fi

• In cases like this:

@go.example_func() {
  ...
   @go.another_func arg1 arg2
  return
}

return will return with the return code of @go.another_func. Assuming that, as a go function, @go.another_func will return using the custom codes, no change is performed in the code.

• When builtins or external commands are called and there is a reasonable chance of sth going wrong, then I catch the return code and return an appropriate custom one. Eg

printf "%s" "$var"
return

is rewritten to

printf "%s" "$var" && ec=0 || ec="$?"
if [[ "$ec" -ne 0 ]]; then
  return $((_GO_EC_GENERR+ec))
fi

Here, printf may exit with 2 if there are wrong arguments used and 1 for other errors. _GO_EC_GENERR+1 corresponds to _GO_EC_EXT1 and _GO_EC_GENERR+2 to _GO_EC_EXT2. But, for instance:

echo "$var"
return

is left as is, since echo will fail only when a write error occurs, which would mean bigger problems anyway.

• Bats stuff is left untouched. This means that even calls to bats_restore_shell_options are left as is. Should these be changed as well?

[coveralls]

Coverage decreased (-22.2%) to 72.844% when pulling 470239bb7d923d3e012c7ed5563d9d53c596a997 on tterranigma:return_codes into b8d71406075bed5eea9ea575ec9547c7a4505d1a on mbland:master.

[coveralls]

Coverage decreased (-22.2%) to 72.862% when pulling 74c09b110f41159bb0d3c1f2c1640f37ec0957f0 on tterranigma:return_codes into b8d71406075bed5eea9ea575ec9547c7a4505d1a on mbland:master.

[coveralls]

Coverage decreased (-22.3%) to 72.779% when pulling fbfc8bee13fe630a63b5efa489c530bb441cfb1a on tterranigma:return_codes into b8d71406075bed5eea9ea575ec9547c7a4505d1a on mbland:master.

[coveralls]

Coverage decreased (-22.05%) to 72.999% when pulling 769ee6bdc8cf00505ed9bd7059e0894fd39a5d6c on tterranigma:return_codes into b8d71406075bed5eea9ea575ec9547c7a4505d1a on mbland:master.

[nkakouros]

I have now finished work on this. Waiting for feedback.

[nkakouros]

Is there interest in this PR? Would it be worth spending more time on this?