FAQ

:::::::::::::::::::::::::
::  Table of Contents  ::
:::::::::::::::::::::::::
  1.  How do I send data to functions for input?
  2.  How are globals/consts defined so I don't conflict with them?
  3.  Are there any universal options in SBT functions?
  4.  What keywords are reserved by SBT?
  5.  Why do SBT functions seem to fail when piping to loops?
  6.  Does SBT support Bash 2.x or 3.x?
  7.  How portable is SBT to other platforms and shells?
  8.  What are SBT's dependencies?  Is SBT a PURE shell/bash system?
xxx.
100.  How should functions and variables be named?



:::::::::::::::::::
::  FAQ Answers  ::
:::::::::::::::::::
  1.  How do I send data to functions for input?
      The standard is for SBT functions to accept data via positional arguments, files, and STDIN; in that order.
      - Positional arguments always get read first, if they exist, they go into a DATA variable and no further processing happens.
      - Files, if passed via -f '/some/file' or --file '/some/file', will be slurped into a DATA variable if no positionals are found, and no further processing happens.
      - STDIN will be slurped into a DATA variable if no positionals or files are sent.  A function expecting data will hang if nothing is found by this point (just like any program waiting forever on a non-existent STDIN pipe).

  2.  How are globals/consts defined so I don't conflict with them?
      All SBT-specific variables start with __SBT_ prefix to avoid conflict.

  3.  Are there any universal options in SBT functions?
      Yes, they are:
      -R 'variable_name'      This is used by functions that return a value.  You can assign the output to variabled named whatever you specify.
      -f --file '/some/file'  When a function accepts input, this is how you specify file(s) to read.

  4.  What keywords are reserved by SBT?
      Functions and variable names are generally distinguished by unique prefixes.  They are as follows:
      Functions are grouped into namespaces such as 'core', 'string', 'io'.  They will always be preceeded with their namespace: core_SomeFunction, string_IndexOf, io_MakeRAMDrive.  As long as you don't write functions matching an imported 'namespace_' you will never conflict with SBT functions.
      Variables come in three groups:
        Bash Internals      SBT will never unset or mutilate Bash internal variables.  It does have to use them at times, such as reading $BASH_SOURCE or similar.  The biggest use of internals is core_getopts which uses/modifies OPTIND/OPTERR/OPTARG to AVOID conflict rather than create it.
        Globals             While Bash is (basically) dynamically scoped, SBT needs to ensure certain variables exist when a given namespace is included.  A namespace will include an initialization block near each top, to set these values.  All globals have '__SBT_' prefixed to the name, e.g.:  __SBT_VERBOSE
        Function Lexicals   SBT functions use locally-scoped variable almost exclusively, which combined with Bash's natural scoping rules allows SBT to be essentially lexically scoped.  All function variables will be prefixed with a single underscore, e.g.:  _some_var
      So in short, try to avoid naming any thing prefixed by '__SBT_' or a single underscore like '_bla'.

  5.  Why do SBT functions seem to fail when piping to loops?
      This bites most people at one point or another but it is NOT a problem with SBT, or Bash.  Here's a trivial example assuming some_Function outputs three lines to merge:
        merged=''
        some_Function | while IFS=$'\n' read -r line ; do merged+="${line}" ; done
        !!! The $merged variable is STILL blank
      This is becuse commands in a pipeline operate in their own subshell; they have to.  So when we concatinated the $line variable, we did it in a process that is inaccessible to the program on the left of the pipe.  In fact, the process dies at the end of the loop.
      How do we fix this?  We use an input method that allows the logic we want to keep alive in the main process:  Process substitution to the rescue!!!
        merged=''
        while IFS=$'\n' read -r line ; do merged+="${line}" ; done < <(some_Function)
        !!! The $merged variable is now what we expect
      This problem can also be solved with a here-string:
        merged=''
        mydata="$(someFunction)"
        while IFS=$'\n' read -r line ; do merged+="${line}" ; done <<<"${mydata}"
  6.  Does SBT support Bash 2.x or 3.x?
      No, and it never will.  SBT relies on associative arrays (declare -A) which only exist in 4.x+.
  7.  How portable is SBT to other platforms, shells, and versions?
      As long as Bash compiles and runs on a platform, SBT should work.  Make sure to read the dependencies in item #8 below.
      Currently, testing of all known versions of Bash 4.x is NOT being done.  Assuming no bugs exist in the version you're running, SBT should work.
      Officially, Bash is the only shell supported.  However, ksh will probably be able to source and use SBT.  Future tests might be built to add official support for other shells.
  8.  What are SBT's dependencies?  Is SBT a PURE shell/bash system?
      No, SBT is not a pure shell solution because shell isn't always a reasonable tool for a given job.
      See README for the full list of dependencies.

100.  How should functions and variables be named inside SBT.
      Functions should be all lower case and led with 'namespace__'.
        For example:  string__index_of
      Variables should follow these conventions:
        1) Use of the keyword 'local' should be used to keep dynamic scope.
        2) All variables should be prefixed with an underscore: local _my_var
        3) Variables should be typed when possible:  local -i _my_var
        4) Read-only variables should be upper-case and declared properly:  local -r _MY_VAR="something"
        5) Variables used for indirection (eval-ing) should end in an underscore: local _my_var_
        6) All exit code variables should be prefixed with E_:  local -i -r E_BAD_INPUT=10