gabr 2.0.13 → 2.1.1

package/README.md

@@ -23,12 +23,12 @@ $ npm link gabr
 > If you want to run `gabr` as a local function, try `. gabr`
 
 ## What is gabr.sh
-Gabr is a Bash function designed to call other Bash functions.
+Gabr is a Bash-function designed to call other Bash-functions.
 Gabr takes arguments and will try to turn that in to a function call.
 Gabr takes the path of least resistance towards a function call.
 Let's illustrate that with a flowchart.
 
-![Alt text](./Gabr.sh.svg)
+![Happy Flowchart](https://raw.githubusercontent.com/nicobrinkkemper/gabr.sh/master/Gabr.sh.svg?sanitize=true)
 
 > This flowchart doesn't show error cases. These cases are mostly when the last argument did not result
 > in the execution of a real function.
@@ -36,52 +36,32 @@ Let's illustrate that with a flowchart.
 Let's illustrate further with a code example. 
 ```shell
 $ echo "\
-function hello() {
-  printf '%s\n' 'Usage: gabr hello world' >&2
-}
-function world() {
-  printf '%s\n' 'Hello World.' >&2
-}
-" > ./hello.sh
-$ gabr hello
-Usage: gabr hello world
-$ gabr hello world
-Hello World.
-```
-> By naming the file and the function hello,
-> a tiny API emerged to call the function.
-
-A different approach would be:
-```shell
-$ echo "\
 if [ \$# -eq 0 ]; then
-    set -- usage
+  printf '%s\n' 'Usage: gabr hello world' >&2
 fi
-function usage() {
-  printf '%s' 'Usage: gabr hello world'
-}
 function world() {
   printf '%s\n' 'Hello World.' >&2
 }
 " > ./hello.sh
 $ gabr hello
 Usage: gabr hello world
-$ gabr hello usage
-Usage: gabr hello world
 $ gabr hello world
 Hello World.
 ```
-> See [functions](#Functions) for a different variation of this
+
+And there you have it. That's all it does. But it is deceptively useful.
 
 ## Why use gabr.sh?
+Use it when you want to make a simple API to automate stuff *you* care about.
 Consider the following commands to delete a tag with git:
 ```shell
 git tag -d 1.0.1
 git push origin :refs/tags/1.0.1
 ```
-I'll be honest to myself and say I won't remember this next time.
-Besides I have a lot of tags to delete.
-I can just write a quick function.
+This is hard to remember next time you'd need it.
+It's also hard to delete multiple tags because you'd need
+to shift your cursor around to change the tags.
+Now consider the following function.
 ```bash
 set -eu
 function deleteTag() {
@@ -91,18 +71,35 @@ function deleteTag() {
 ```
 > Let's say it's saved in `./git.sh`
 
-To run this like `gabr` would, one could simply write:
+This is easy to forget too, but one can refresh memory by looking at the file.
+
+To run this function like `gabr` would, one could simply write:
 ```shell
 $ (. git.sh; deleteTag 1.0.1)
 ```
-But doing it like this is hard to communicate and prone to human error. With `gabr` a more direct API emerges to do these kind of things:
+But doing it like this is hard to communicate and prone to human error.
+With `gabr` a more direct api emerges to do these kind of things:
 ```
 $ gabr git deleteTag 1.0.1
 ```
+With this basic concept, all functions you see in .sh files
+will be available through a simple api that is easy to communicate.
+Just type in what you see.
+
+## Sourcing `gabr` vs running `gabr`
+For normal use I recommend running `gabr` as a file. This is default behavior when running `npm link`.
+If you've forked the repo and npm-linked from there then any changes will update the linked file.
+
+It is also possible to source `gabr`. This can be used in scripts or a shell-terminal.
+By running `. gabr`, gabr will not run as a file but instead as a function. For example:
+```shell
+$ . gabr
+$ GABR_DEBUG_MODE=1 # we do not need to export this
+$ gabr example human
+``` 
 
 ## Variables
 
-### Variables
 ### GABR_STRICT_MODE (default:true)
 A variable called `GABR_STRICT_MODE` may be used to toggle the following snippet:
 ```bash
@@ -110,7 +107,7 @@ set -eEuo pipefail
 local IFS=$'\n\t'
 trap 'return $?' ERR SIGINT
 ```
-This snippet will run once inside the subshell where the function is called and the file is sourced.
+This snippet will run once inside the function's subshell clause.
 Let's go over the three lines:
 
 1)
@@ -133,7 +130,6 @@ To opt-out of strict-mode:
 ```shell
 $ export GABR_STRICT_MODE=off
 ```
-> export is not needed when running as a local function
 
 ### GABR_DEBUG_MODE
 Setting this variable to a value will turn on debug mode for files and functions.
@@ -143,11 +139,11 @@ file source and function call.
 $ export GABR_DEBUG_MODE=true
 ```
 
-This variable is useful, because it omits `gabr` debug info from polluting a users code.
+This variable is useful, because just using `set -x` might also output `gabr`'s internal code.
 
-### GABR_ROOT / root
+### GABR_ROOT
 If `GABR_ROOT` is set to a value the `gabr` function will change directory
-to this location on every invocation.
+to this value on every invocation.
 ```shell
 $ export GABR_ROOT=$(git rev-parse --show-toplevel)
 ```
@@ -158,35 +154,28 @@ in the same output. Keep in mind that the `gabr` function will lose it's flexibi
 it will always run from a fixed location.
 
 ### GABR_DEFAULT
-A global variable called `GABR_DEFAULT` may be used to influence the default namespace. 
-By default this namespace is `usage`. The default namespace is consulted when no other options are found. 
-If neither a default function nor a default file is found, a default function will be generated. (see [functions](#Functions))
+A global variable called `GABR_DEFAULT` may be used to influence the exit condition.
+`gabr` will exit it's internal loop when it finds a function it can call.
+The argument `usage` always results in a function call and thus can be used as a means to exit.
+A second option may be added by setting `GABR_DEFAULT` (global) or `default` (local) to a value.
 
 ```shell
 $ export GABR_DEFAULT=index
 ```
-> This will make `index.sh` behave similar to index-files in other programming languages
-
-This variable is useful, but the default value `usage` is probably the way to go. 
+> This will make `index.sh` behave similar to index-files in other programming languages.
+> But `usage` makes more sense for Bash IMO
 
 ### GABR_EXT
-`GABR_EXT` may be used to alter the value of `ext`. Files with a `.sh` extension are
-sourced, files without are ran with `exec`
+`GABR_EXT` may be used to alter the value of `ext`. The default value is `.sh`.
+Files with this extension are sourced, files without are ran with `exec`.
 
 ```shell
 $ export GABR_EXT=.bash
 ```
 
 With the right shebang, any programming language can be called. However, keep in mind
-that `gabr` also looks for files without a extension. These files will always run with
-`exec`. For example, see `./example/javascript`
-```shell
-$ gabr example javascript hello
-Arguments received: 3
-0 -> .../node/v11.7.0/bin/node
-1 -> .../gabr/example/javascript
-2 -> hello
-```
+that `gabr` also looks for files without an extension. These files will always run with
+`exec`.
 
 ### Local variables
 Gabr defines the following local variables. These will be defined in sourced files.
@@ -205,9 +194,15 @@ Gabr defines the following local variables. These will be defined in sourced fil
 | FUNCNEST     	|       	| See manual ([reference](https://www.gnu.org/software/bash/manual/html_node/Bash-Variables.html)) | 50 | Prohibits overly recursive function calls |
 
 ## Functions
+A default function will be generated that prints usage information about `gabr` when:
+
+- No argument are given
+- The argument is `usage`
+- The argument is the value of `GABR_DEFAULT` and `GABR_DEFAULT` is set
+
 ### function usage ()
-By default `usage` is a important namespace for the `gabr` function. `usage` behaves
-like a exit condition. The argument will always result in a function call, and thus
+By default `usage` is an important namespace for the `gabr` function. `usage` behaves
+like an exit condition. The argument will always result in a function call, and thus
 exit the interal loop. The following snippet shows the last-resort function that will be generated when a `usage` function or file is not available.
 
 ```bash
@@ -240,16 +235,16 @@ usage(){
 }
 ```
 
-Finally, a default file may be consulted when the
-a argument is a directory but not a file. For a example of this, see `./test/usage.sh`
+Finally, a default file may be consulted. This is applicable when the
+argument is only a directory. For an example of this, see `./test/usage.sh`
 or run `gabr test` to see it in action.
 
 ### function $default ()
-The namespace for `usage` may be altered with `GABR_DEFAULT` or simply `default`.
+The name of the `usage` function may be altered with `GABR_DEFAULT` or simply `default`.
 A last-resort function and variable will be made for this name instead.
+The usage namespace will keep functioning.
 This is done through variable indirection. ([reference](https://www.gnu.org/software/bash/manual/html_node/Shell-Parameter-Expansion.html))
-To generate a function with a dynamic name a small eval trick is used. For this reason
-the `default` variable may not contain special-characters.
+To generate a function with a dynamic name a small eval trick is used.
 
 ```bash
 default=help
@@ -263,7 +258,7 @@ help(){
 
 The internal loop wil error at any argument that starts with a dash (-).
 Any argument that comes behind the dash will be printed as
-a warning to the user.
-```
+a warning to the user. The return code will be 1.
+```bash
 set -- '-' 'Error, something went wrong'
 ```

package/bin/bats-exec-suite

@@ -40,7 +40,7 @@ elif [[ "$num_jobs" != 1 ]]; then
   exit 1
 fi
 
-trap 'kill 0; exit 1' int
+trap 'kill 0; exit 1' INT
 
 all_tests=()
 for filename in "$@"; do
@@ -71,16 +71,18 @@ for filename in "$@"; do
   fi
 done
 
+test_count="${#all_tests[@]}"
+
 if [[ -n "$count_only_flag" ]]; then
-  printf '%d\n' "${#all_tests[@]}"
+  printf '%d\n' "${test_count}"
   exit
 fi
 
 status=0
-printf '1..%d\n' "${#all_tests[@]}"
+printf '1..%d\n' "${test_count}"
 
 # No point on continuing if there's no tests.
-if [[ "${#all_tests[@]}" == 0 ]]; then
+if [[ "${test_count}" == 0 ]]; then
   exit
 fi
 
@@ -92,10 +94,19 @@ if [[ "$num_jobs" != 1 ]]; then
     parallel -qk -j "$num_jobs" --colsep="\t" -- bats-exec-test "${flags[@]}" '{1}' '{2}' '{#}' || status=1
 else
   # Just do it serially.
-  test_number=1
-  while IFS=$'\t' read -r filename test_name; do
-    bats-exec-test "${flags[@]}" "$filename" "$test_name" "$test_number" || status=1
-    ((++test_number))
-  done < <(printf '%s\n' "${all_tests[@]}" | grep -v '^$')
+  test_number=0
+  for test_line in "${all_tests[@]}"; do
+    # Only handle non-empty lines
+    if [[ $test_line ]]; then
+      filename="${test_line%%$'\t'*}"
+      test_name="${test_line##*$'\t'}"
+      ((++test_number))
+      bats-exec-test "${flags[@]}" "$filename" "$test_name" "$test_number" || status=1
+    fi
+  done
+  if [[ "${test_number}" != "${test_count}" ]]; then
+    printf '# bats warning: Only executed %s of %s tests\n' "$test_number" "$test_count"
+    status=1
+  fi
 fi
 exit "$status"

package/bin/bats-exec-test

@@ -212,9 +212,13 @@ bats_trim_filename() {
 
 bats_debug_trap() {
   if [[ "$BASH_SOURCE" != "$1" ]]; then
+    # The last entry in the stack trace is not useful when en error occured:
+    # It is either duplicated (kinda correct) or has wrong line number (Bash < 4.4)
+    # Therefore we capture the stacktrace but use it only after the next debug
+    # trap fired.
+    # Expansion is required for empty arrays which otherwise error
+    BATS_CURRENT_STACK_TRACE=( "${BATS_STACK_TRACE[@]+"${BATS_STACK_TRACE[@]}"}" )
     bats_capture_stack_trace
-    BATS_LINENO="$BATS_CURRENT_LINENO"
-    BATS_CURRENT_LINENO="${BASH_LINENO[0]}"
   fi
 }
 
@@ -223,10 +227,9 @@ bats_debug_trap() {
 # set `$?` properly. See #72 and #81 for details.
 #
 # For this reason, we call `bats_error_trap` at the very beginning of
-# `bats_teardown_trap` (the `DEBUG` trap for the call will move
-# `BATS_CURRENT_LINENO` to `BATS_LINENO`) and check the value of
-# `$BATS_TEST_COMPLETED` before taking other actions. We also adjust the exit
-# status value if needed.
+# `bats_teardown_trap` (the `DEBUG` trap for the call will fix the stack trace)
+# and check the value of `$BATS_TEST_COMPLETED` before taking other actions.
+# We also adjust the exit status value if needed.
 #
 # See `bats_exit_trap` for an additional EXIT error handling case when `$?`
 # isn't set properly during `teardown()` errors.
@@ -237,8 +240,8 @@ bats_error_trap() {
     if [[ "$BATS_ERROR_STATUS" -eq 0 ]]; then
       BATS_ERROR_STATUS=1
     fi
-    BATS_STACK_TRACE[0]="$BATS_LINENO ${BATS_STACK_TRACE[0]#* }"
-    trap - debug
+    BATS_STACK_TRACE=( "${BATS_CURRENT_STACK_TRACE[@]}" )
+    trap - DEBUG
   fi
 }
 
@@ -260,7 +263,7 @@ bats_exit_trap() {
   local line
   local status
   local skipped=''
-  trap - err exit
+  trap - ERR EXIT
 
   if [[ -n "$BATS_TEST_SKIPPED" ]]; then
     skipped=' # skip'
@@ -280,7 +283,7 @@ bats_exit_trap() {
       # If instead the test fails, and the `teardown()` error happens while
       # `bats_teardown_trap` runs as the EXIT trap, the test will fail with no
       # output, since there's no way to reach the `bats_exit_trap` call.
-      BATS_STACK_TRACE[0]="$BATS_LINENO ${BATS_STACK_TRACE[0]#* }"
+      BATS_STACK_TRACE=( "${BATS_CURRENT_STACK_TRACE[@]}" )
       BATS_ERROR_STATUS=1
     fi
     printf 'not ok %d %s\n' "$BATS_TEST_NUMBER" "$BATS_TEST_DESCRIPTION" >&3
@@ -301,6 +304,7 @@ bats_exit_trap() {
   fi
 
   rm -f "$BATS_OUT"
+  bats_cleanup_preprocessed_source
   exit "$status"
 }
 
@@ -317,23 +321,22 @@ bats_perform_test() {
   # function when the ERR trap fires. All versions of Bash appear to reset it
   # on an unbound variable access error. bats_debug_trap will fire both before
   # the offending line is executed, and when the error is triggered.
-  # Consequently, we use `BATS_LINENO` to point to the line number seen by the
+  # Consequently, we use `BATS_CURRENT_STACK_TRACE` recorded by the
   # first call to bats_debug_trap, _before_ the ERR trap or unbound variable
   # access fires.
-  BATS_CURRENT_LINENO=0
-  BATS_LINENO=0
   BATS_STACK_TRACE=()
+  BATS_CURRENT_STACK_TRACE=()
 
   BATS_TEST_COMPLETED=
   BATS_TEST_SKIPPED=
   BATS_TEARDOWN_COMPLETED=
   BATS_ERROR_STATUS=
-  trap "bats_debug_trap \"\$BASH_SOURCE\"" debug
-  trap 'bats_error_trap' err
-  trap 'bats_teardown_trap' exit
+  trap 'bats_debug_trap "$BASH_SOURCE"' DEBUG
+  trap 'bats_error_trap' ERR
+  trap 'bats_teardown_trap' EXIT
   "$BATS_TEST_NAME" >>"$BATS_OUT" 2>&1
   BATS_TEST_COMPLETED=1
-  trap 'bats_exit_trap' exit
+  trap 'bats_exit_trap' EXIT
   bats_teardown_trap
 }
 
@@ -350,8 +353,8 @@ BATS_OUT="${BATS_TMPNAME}.out"
 bats_preprocess_source() {
   BATS_TEST_SOURCE="${BATS_TMPNAME}.src"
   bats-preprocess "$BATS_TEST_FILENAME" >"$BATS_TEST_SOURCE"
-  trap 'bats_cleanup_preprocessed_source' err exit
-  trap 'bats_cleanup_preprocessed_source; exit 1' int
+  trap 'bats_cleanup_preprocessed_source' ERR EXIT
+  trap 'bats_cleanup_preprocessed_source; exit 1' INT
 }
 
 bats_cleanup_preprocessed_source() {

package/bin/bats-format-tap-stream

@@ -7,6 +7,7 @@ IFS= read -r header
 if [[ "$header" =~ $header_pattern ]]; then
   count="${header:3}"
   index=0
+  passed=0
   failures=0
   skipped=0
   name=
@@ -78,6 +79,11 @@ summary() {
     buffer ', %d skipped' "$skipped"
   fi
 
+  not_run=$((count - passed - failures - skipped))
+  if [[ "$not_run" -gt 0 ]]; then
+    buffer ', %d not run' "$not_run"
+  fi
+
   buffer '\n'
 }
 
@@ -158,6 +164,7 @@ while IFS= read -r line; do
       ((++skipped))
       skip "${BASH_REMATCH[2]}"
     else
+      ((++passed))
       pass
     fi
     ;;

package/example/GIT.md

@@ -1,8 +1,11 @@
 # git.sh
 
- Git.sh contains some one-off git functions. To serve as example.
+ Git.sh contains some one-off git functions. To serve as example and to help with maintanance on this repo.
 
+* [pullSubmodules()](#pullSubmodules)
+* [updateSubmodules()](#updateSubmodules)
 * [currentBranch()](#currentBranch)
+* [root()](#root)
 * [deleteBranch()](#deleteBranch)
 * [upstream()](#upstream)
 * [deleteStale()](#deleteStale)
@@ -11,6 +14,26 @@
 * [renameTag()](#renameTag)
 
 
+## pullSubmodules()
+
+Inits content of /modules
+### Example
+
+```bash
+$ gabr example git pullSubmodules
+master
+```
+
+## updateSubmodules()
+
+Updates content of /modules
+### Example
+
+```bash
+$ gabr example git updateSubmodules
+master
+```
+
 ## currentBranch()
 
 Gets the current branch
@@ -21,6 +44,16 @@ $ gabr example git currentBranch
 master
 ```
 
+## root()
+
+Returns root of git repository
+### Example
+
+```bash
+$ gabr example git root
+~/Code/your/project
+```
+
 ## deleteBranch()
 
 Deletes a local branch
@@ -68,7 +101,6 @@ $ gabr example git deleteLocalBranch feature-branch
 
 * string [ $1 | $branch ]  to-delete-branch-name (default:current) -- e.g. feature-branch
 * string [ $2 ]            existing-checkout-branch (default:master) -- e.g. develop
-* string [ $3 | $remote ]  to-delete-remote (default:current) -- e.g. origin
 
 ## deleteTag()
 
@@ -89,7 +121,7 @@ Rename a tag
 ### Example
 
 ```bash
-    gabr example git deleteTag some-feature
+    gabr example git renameTag some-feature
 ```
 
 ### Arguments

package/example/IFS.sh

@@ -0,0 +1,3 @@
+function IFS(){ # displays current IFS
+    printf '%q\n' "${IFS}"
+}

package/example/clang.c

@@ -0,0 +1,17 @@
+#!/usr/bin/c
+#include <stdio.h>
+
+int main(int args, char *argv[]) {
+printf("Arguments received: %d", args);
+int i = 0;
+for (i = 0; i < args; i++){
+        printf("\n%s", argv[i]);
+}
+printf("\n");
+return 0;
+}
+
+/*  Sidenote:
+        for shebang support
+        https://github.com/ryanmjacobs/c
+*/

package/example/git.sh

@@ -1,21 +1,14 @@
 #!/usr/bin/env bash
 # @file git.sh
 #
-# @brief  Git.sh contains some one-off git functions. To serve as example.
+# @brief  Git.sh contains some one-off git functions. To serve as example and to help with maintanance on this repo.
 
-if ! [ "${1:-usage}" = 'usage' ]; then
-    cd $(git rev-parse --show-toplevel) # functions target root directory
-fi
-if [ -z "${remote:-}" ]; then
-    declare remote="$(git remote)"
-fi
-if [ -z "${branch:-}" ]; then
-    declare branch
-    branch="$(git symbolic-ref HEAD 2>/dev/null)" || branch="undefined"
-    branch=${branch##refs/heads/}
-fi
+declare remote="$(git remote)"
+declare branch
+branch="$(git symbolic-ref HEAD 2>/dev/null)" || branch="undefined"
+branch=${branch##refs/heads/}
 
-# @description Updates content of /modules
+# @description Inits content of /modules
 # @example
 #   $ gabr example git pullSubmodules
 #   master
@@ -23,6 +16,13 @@ function pullSubmodules() {
     git submodule update --init --recursive
 }
 
+# @description Updates content of /modules
+# @example
+#   $ gabr example git updateSubmodules
+#   master
+function updateSubmodules() {
+    git submodule update --remote --merge
+}
 
 # @description Gets the current branch
 # @example
@@ -36,7 +36,7 @@ function currentBranch() {
 # @example
 #   $ gabr example git root
 #   ~/Code/your/project
-function root(){
+function root() {
     command git rev-parse --show-toplevel;
 }
 
@@ -72,18 +72,16 @@ function deleteStale() {
 #   $ gabr example git deleteLocalBranch feature-branch
 # @arg string [ $1 | $branch ]  to-delete-branch-name (default:current) -- e.g. feature-branch
 # @arg string [ $2 ]            existing-checkout-branch (default:master) -- e.g. develop
-# @arg string [ $3 | $remote ]  to-delete-remote (default:current) -- e.g. origin
 function deleteBranch() {
     local branch=${1:-$branch}
     local checkout=${2:-master}
-    local remote=${3:-remote}
     if [ "${checkout}" = "${branch}" ]; then
         echo "Checkout branch may not be the same as deleted branch" 1>&2
         return 1
     fi
     git checkout $checkout
     git branch -d $branch || echo "Already deleted"
-    git push --delete $(git config --get remote.origin.url) $branch || echo "Already deleted"
+    git push --delete $(git config --get remote.origin.url) $branch || echo "Already deleted remote"
 }
 
 # @description Delete a remote branch
@@ -97,7 +95,7 @@ function deleteTag() {
 
 # @description Rename a tag
 # @example
-#       gabr example git deleteTag some-feature
+#       gabr example git renameTag some-feature
 # @arg $1 old version
 # @arg $2 new version
 function renameTag() {

package/example/npm.sh

@@ -1,15 +1,24 @@
 #!/usr/bin/env bash
-if ! whereis git; then
+if ! command -v git >/dev/null; then
     echo "Warning: git is not available" 1>&2
     return 1
 fi
-if ! whereis node; then
+if ! command -v node >/dev/null; then
     echo "Warning: node is not available" 1>&2
     return 1
 fi
 declare npmRoot="$(git rev-parse --show-toplevel)"
-declare name="$(node -p -e "require('${npmRoot}/package.json').name")"
-declare version="$(node -p -e "require('${npmRoot}/package.json').version")"
+declare -a data=(
+    $(node -p -e "\
+const data=require('${npmRoot}/package.json');
+[
+    data.name,
+    data.version
+].join('\n')
+") 
+)
+declare name=${data[0]}
+declare version=${data[1]}
 function release() { # [ message ] - Release with a message
     cd $npmRoot
     git add . || 'Nothing to add'
@@ -23,8 +32,8 @@ function deprecate() { # [version] -- deprecate a version
     cd $npmRoot
     if [[ $# -eq 0 ]]; then
         echo "\
-Usage: deprecate [version] [message] -- e.g. deprecate 0.0.2 no long need it
-    -- \$1 string   version number          (default:current)     
+Usage: deprecate [version] [message] -- e.g. deprecate 0.0.2 \"This version is too old\"
+    -- \$1 string   version number          (default:current)
     -- \$2 string   reason of deprecation   (default:'x.x.x is no longer supported')"
         return
     fi