The function names are human readable which can result in cluttered code. Some people might prefer short-hand. For example:
some_var='happy go Lucky'
bla="$(string_Substring -i 1 "${some_var}")"

Shorter version:
some_var='happy go Lucky'
bla="$(s_sub -i 1 "${some_var}")"

This is extremely low on my priority list, but if people want to vote for it I'll try to come up with a standard and implement it.

If you call namespace.sh with no arguments, it exists silently with exit code 0.

$ ./namespace.sh
$ echo $?
0

It should return an error code and/or display help.

Yep

Docker regression test is failing.

After docker creates a YAML file, we should have a tool which will create HTML pages... or md files... or whatever is user-friendly.

1. The check for $4 to be empty is wrong. It should be [ ${#@} -lt 4] && bla...
2. If a positional is blank we should store it in __SBT_NONOPT_ARGS so long as OPTIND (internally _my_optind) is within the range of ${#@}.

A registry should be created by core which allows "events" (commands) to be registered for shutdown.

core__schedule_shutdown_event
core__process_shutdown_registry
etc

Need to register the removal of temporary directories
core__schedule_shutdown_event "rm -r ${__SBT_TMP_DIR}"

Docker has been stolen as a name and made big in the container world. Consider changing the name, and definitely finish the help/usage.

When using a heredoc, multiline string, or array notation, docker gets confused.

declare -A bob=(
                [one]=bob
                [two]=sally
               )

declare my_var='one
two
three'

declare my_var=<<EOF
  hello
  world
EOF

While the new core_getopts function is far superior to the built-in Bash getopts, it's still complicated for novice users of Bash. An easier function should be built. It should consist of 1 call, no more.

I will probably use Perl's getopts('bl:a') format as an example. It should look like so:
core_EasyGetOpts 'short options' 'long options' <positionals, like $@>

The output should be variables named $option_. Options that should take an argument will get OPTARG assigned. Others will get the string 'true' in them. Long options with hyphens in the names will be converted to underscores to prevent violating Bash's variable naming rules.

Example:
https://github.com/KyleJHarper./my_script.sh -a -b 'hello' -c --long --other-long-opt 'whee'
....
core_EasyGetOpts 'ab:c' ':long,other-long-opt:' "$@"

^ The above call will set the following variables like so:
$option_a == 'true'
$option_b == 'hello'
$option_c == 'true'
$option_long == 'true'
$option_other_long_opt == 'whee'

First of all, it's not terribly useful. Secondly, if a different version of a tool is required between two functions it could give a false positive.

From first glance it looks like the evals might fail in these functions if the value contains a double quote. Need a universal method for detecting and escaping safely.

Review the documentation to ensure no misleading phrasing. Specifically, ensure code-oriented semantics are being used.
"Thread safe" needs to be better worded. Obviously the intention was never to have a MT-safe library but rather to explain that a bash's dynamic scoping will bop you if you use subshells and/or try to set variables via functions...
"Functions" do not follow normal rules for functions in other languages. They cannot be nested to grant scoping, despite being able to declare a function in a function. Anonymous functions (lambdas) don't exist.
... probably more.

Functions that return values can specify a variable name to assign the output to, avoiding a subshell capture. But the name is whatever the user wants. This conflicts with local variables. ex:
function bla {
local temp=''
do some work and assign to temp for now
-R was sent, so use StoreByRef to save $temp to whatever use sent
....
}

But if the user does this:
bla -R 'temp'
We're screwed. StoreByRef will assign to the local temp variable, almost lexically.

Recommend prefixing all local variables in SBT functions with underscore padding.

I didn't want to support "stupid opts" but several programs use it and some people seem to genuinely prefer it. I don't. I call them stupid because -opt collides with compressed short options (e.g.): -opt could mean -o -p -t

However, adding support for this is possible at first glance. By checking for "stupid opts" first (before short) this can be done:

1. Is -opt a stupid opt? If not...
2. Is -opt (indexed at SHORT_OPTIND) a compressed short option? If not, failure.
3. If neither of the above (because it started with --), process as long option.

This will require changes to docker :(

Right now the check isn't very helpful. File must exist, be executable, and have the correct version switch ... any of those missing give a single generic error.

If $tool exists but isn't executable
If $tool exists but version switch isn't working
Others?

Currently docker isn't including any comments, it should.

Docker should use regular hashes rather than arrays-of-hashes... it's preferential (subjective) but it seems cleaner.

Docker tracks last_opt_name but doesn't take into consideration multiple options, which is supported by a bash case statement. This is mostly important because of long opts. Many times a named long_opt does the same thing as a short opt, and there won't be any implied documentation for the name(s) after the first case item.

In order to distinguish invocations of SBT (via core.sh) we should create a UUID. This will undoubtedly become useful to keep crap separate between invocations.

A keyword or flag of some sort should accompany getopts options to determine if they're compulsory or not (including variable tags for positional arguments). This would provide the information necessary to build an invocation syntax with accuracy:

core_SomeFunction [ -a -b -c ] [ -d ] [ --optional ] [ --file-path= ] -e <file [file...]>
where:
core_SomeFunction is the function name.
[ -a -b -c ] are optional short switches.
[ -d ] is an optional short switch that requires an argument.
[ --optional ] is an optional long switch.
[ --file-path= ] is an optional long switch with an argument.
-e is a mandatory short option with an argument (duh).
is a required positional argument ($1).
is a required positional argument ($2).
<file [file...]> is a required positional argument list ($@).

Fact: I have no idea how hard this would be to implement. But putting here so I can track it.

The Switch perl module is not supported anymore. It is recommended to use the "use feature 'Switch'" syntax. Will need to test to see if this is directly supported.

Bash supports a nameref feature via

declare -n local_var=other_var

This would allow us to remove virtually all of the evals we're currently using. It's also more secure than eval. Finally, even though it has security flaws it is the foreseen path for Bash to handle namerefs in the future.

One final benefit is it allows us to skip one more naming convention. Right now, name-ref variables in SBT are required to end in an underscore: _my_var_ This isn't true for arrays, which is one of the major areas we work in.
But the -n switch sets up a true reference, not a lexical look-up system.

#!/bin/bash

function hi {
  local -n _var="${1}"
  _var="set from hi"
}

declare _var="set from main"
hi '_var'
echo "${_var}"
exit 0

==> 'set from hi'

Note!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
This will push the bash requirement from 4.0+ to 4.3+. This will eliminate Ubuntu 12.04 as a target platform as well as others. We should research this to see what will be eliminated as a result.
The release date for Bash 4.3 was Feb 2014, as best I can tell. This would reduce the platform availability of SBT from 7 years old (2016 - 2009) to 2 years (2016 - 2014).

There are some basic tools that every OS should have. Rather than hard-code dependencies for the various flavors of cp, readlink, and so forth... simply require a few basics:

• GNU coreutils
• awk
• GNU grep (which supports -P)
• util-linux

Each namespace should contain a "header guard" to ensure the functions aren't re-imported and variables aren't re-set.

=== core.sh ===

!/bin/bash

if [ ! -z "${__SBT_NS_CORE}" ] ; then
echo "The 'core' namespace has already been loaded." >&2
exit 1
fi
__SBT_SOURCES_LOADED[core]='loaded'

All other namespaces should use a core function such as: core__source_guard 'namespace'
function core__source_guard {
if [ ! -z "${__SBT_SOURCES_LOADED[$1]}" ] ; then
core_LogError "Can't load '${1}' again, already loaded."
return 1
fi
}

A function for setting up traps should exist. This might be overkill but people seem to misunderstand traps anyway, so a cleaner/more intuitive way of scheduling signal events is probably warranted.

Right now docker looks for

while getopts
while core__getopts

But core__getopts can fail with code 2 (E_UHOH) which needs read like this.

while true ; do
  core__getopts ...bla...   (or getopts ...bla...)
  case $? in 1) break ;; 2) return 1 ;; esac
  <process option loop>
done

Docker stops looking for options when it sees 'done' which might also be a problem. Need to make sure it knows when to stop looking for options

doc_examples.sh should be updated to reflect this.

In rare cases we might need to explicitly tell core_getopts to quit processing options. This is especially true when one of the non-option tokens we're dealing with starts with a hyphen.

core_getopts --some-option -o "-27"

This will result in an error because negative 27 looks like option -2 and -7 (or -27 if we allow "stupid opts" later). This will be fixed by this enhancement:

core_getopts --some-option -o -- "-27"

1. Process --some-option
2. Process -o option
3. Set NO_MORE=true. Forcing all following getopts items to go into __SBT_NONOPT_ARGS for the user.
4. Add logic on reset (new getopts loop) to change flag back.

Namespace dependency might be a concern to others. A diagram or note in the README should make it clear.

Only core.sh is ever (and always) a prerequisite to other modules.

If a log variable is set then core_LogVerbose should output to a file. This needs to be a somewhat synchronizeable operation.

if $FUNCTION == 'main' ; then
log directly
else
log to /tmp/${__SBT_UNIQUE_INVOCATION}_loglevel${#FUNCTION[@]}
register log flushing... or something...
fi

With the introduction of __SBT_SOURCES_LOADED we can ensure core is loaded before any other namespaces.

=== array.sh ===

!/bin/bash

[ -z "${__SBT_SOURCES_LOADED[core]}" ] && echo "You must include core before other namespaces." >&2 && exit 1

Recent attempts to unify the core__log_error and core__log_verbose functions is causing an issue with tracing errors. It's also adding unnecessary complications. Remove it.

SBT currently has global dependencies such as awk, perl, etc. There needs to be a smarter way to do this...

Put all tool checks in core.sh?
Do one-off checks in core.sh and then use core__tool_exists ?
Something better????

The naming conventions were loosely based originally, this should be formalized.

Variables

1. All UPPERCASE and UPPER_CASE variables are off-limits; they are (potentially) bash internals. The only exception is for exit-variables; they always start with 'E_': declare -r E_GENERIC=1
2. Read-only variables should be all uppercase (not a conflict, see items 3 and 4).
3. Globals should be prefixed with '__SBT' for clarity of their scope.
4. Globals should be all upper case, even if they aren't read-only. This is to enforce consistent behavior. Hence all globals will look like '__SBT_SOME_VAR'.
5. Local variables (function scope vars) should be prefixed with an underscore to ensure they're never interpreted as commands or user variables from callers (see item 6 for SBT functions calling other functions):

local -i _my_var=1
local -i -r _MY_VAR=1 (readonly)

6. Local variables (function scope vars) which use assignment via eval should be suffixed with an underscore to avoid interpolation/indirection problems. This means a caller should NEVER send a variable like _my_var_ to a callee.

Function names

1. Should be lower case
2. Should have namespace separated by __ (double underscore): namespace__my_function
   [Another issue will address concerns about long function names]

Forgot to finish string array tests a while back. Making an issue to finish it.

Currently docker isn't picking up on all inferred tags properly. Need to find the edge case and clean it up.

Verbose output is handled with calls to core_LogVerbose. When verbosity is disabled it still requires invoking the function and checking the __SBT_VERBOSE flag (and executing a return).

In small scale it's almost imperceptible, but in larger tests I saw the following times:
No core_LogVerbose lines at all: 32s
core_LogVerbose in place, but disabled: 39s
core_LogVerbose in place, and enabled: 48s

As a performance feature, a script in bin should comment/uncomment these calls entirely.

Bash v3 support? No (associative arrays mostly, also bug fixes/security)

Portability? Yes, but within reason.

PURE SHELL!!!!???! No (right tool, right job). Link to general dependencies.

The easy getopts processor isn't strict enough. Right now it's just checking for a hyphen to decide if something is an option... this needs fixed.

I'm also not sure if the hyphen-to-underscore substitution is going to work for long options.