lib/sh/util.sh: command(): made usage message an end-of-line comment

lib/sh/util.sh: inlined limit_log_fd into command() since it's only used once

lib/sh/util.sh: log_err(), log_info(): use bolder symbols (*, #) to make the symbol stand out visually from the line of | above and below it

lib/sh/util.sh: $verbosity: lowered the default from 3 to 2 because level 3 output (vars, etc.) is too verbose for the default output and is only needed for debugging

lib/sh/util.sh: $log_level_indent: added space after | to visually separate the nesting levels and make the output look like an expandable tree (similar to a filesystem browser tree)

lib/sh/util.sh: log_custom(): replace every non-whitespace character of $log_indent, and the first character of PS4, with the symbol, to make the symbol stand out on the line instead of the |||... before it

lib/sh/util.sh: removed no longer used stdout2log_fd(). set $cmd_log_fd instead.

lib/sh/util.sh: set $log_level_indent to | because this visually connects commands at the same indent by effectively connecting their + prefixes with a line of |

lib/sh/archives.sh: zip(), unzip(): added missing echo_func

lib/sh/util.sh: command(): use just one control var $cmd_log_fd instead of three flags (limit_log_fd, limit_stdout, stderr_is_errors) that indicated various common fd configurations. this is much clearer (you state which fd the common uses as its logging fd), more configurable (the logging fd can be any fd, not just 1 or 2), and more automatic (redirecting fd 2 to err_fd happens automatically if it isn't used for logging).

bugfix: lib/sh/local.sh: psql(): need to use limit_stdout=1 instead of stderr_is_errors=1 because logging info is output to stdout, not stderr, in spite of the >&2 redirection, since the >&2 is applied after command()'s logging redirects. note that the >&2 can now be removed, because it will be performed by command().

lib/sh/util.sh: added $log_fd and use it instead of 2 where the log_fd is intended

lib/sh/util.sh: moved stdout2log_fd() to command verbose output subsection of verbose output since it is primarily intended for use with external commands

lib/sh/util.sh: renamed limit_stderr to limit_log_fd, stdout2stderr to stdout2log_fd to clarify their purpose. log_fd is currently assumed to be 2.

lib/sh/util.sh: added disable_logging() and use it instead of `exec 2>/dev/null`

lib/sh/util.sh: added $err_fd global var and use it instead of the 22 magic value. it starts out at 2 until fd 22 has been set up, so commands that required 22 will now work before set_global_fds() is called.

lib/sh/util.sh: shadow_fd(): don't require it to be run with log++ and instead let callers apply log++ if needed. in set_global_fds(), log++ can just be applied once for all the shadow_fd() calls.

lib/sh/util.sh: shadow_fd(): instead of applying minor=1 (i.e. an additional log++) to echo_func and then log++ again separately to set_fd, just apply it to the entire function

lib/sh/util.sh: set_fd(): don't increase the log_level for this function, and instead let callers increase it if needed

lib/sh/util.sh: limit_stderr(): inlined log++ with the can_log call because it should only apply to it. this also makes it obvious that log++ should not apply outside of this function. this also enables the contents of this function to be used in an alias.

lib/sh/util.sh: command(): use exec instead of `builtin command` to avoid spawning an extra process (since a subshell is already open)

bugfix: lib/sh/util.sh: command(): only indent if command was logged

bugfix: lib/sh/util.sh: .(): only indent if include statement was logged

lib/sh/util.sh: limit_stderr(): moved $stdout2stderr to command() so that limit_stderr()'s only purpose is to log-limit stderr

bugfix: lib/sh/util.sh: limit_stderr(): moved $stderr_is_errors default to command() where it's used

lib/sh/util.sh: limit_stderr(): do stdout2stderr after limit_stderr to avoid having two similar `can_log ... >/dev/null` commands

lib/sh/util.sh: echo_cmd(): removed no longer used removal of first builtin or command arg

lib/sh/util.sh: inlined echo_run_prep into command() since it's now only used once

lib/sh/util.sh: command(): removed no longer used $cmd_echoed flag

*{.sh,run}: use new limit_stdout=1 instead of stdout2stderr=1 limit_stderr=1

lib/sh/util.sh: command(): added limit_stdout=1 flag which implies stdout2stderr=1 limit_stderr=1

lib/sh/util.sh: merged limit_stderr_cmd/limit_stdout_cmd into command(), using flag vars to control what limiting actions it needs to perform. in command invocations, this involves setting the appropriate flag vars instead of using a limit_std*_cmd alias.

lib/sh/util.sh: added run_cmd

lib/sh/util.sh: limit_stderr(): moved before command echoing because it does not depend on it and is a separate feature

lib/sh/util.sh: run_args_cmd(): use $top_script instead of `"$(canon_rel_path "$0")"`

lib/sh/util.sh: $top_script: run canon_rel_path on $0

lib/sh/util.sh: use `minor=1 echo_func` instead of echo_minor_func because the syntax is simple enough that you don't need a separate alias for it

lib/sh/util.sh: echo_func: support using minor=1 to increase the log_level that the function call is echoed at. use this in echo_minor_func.

lib/sh/util.sh: echo_*func aliases: use simpler && syntax (with `|| true` to prevent errexit if the condition is false) instead of an if statement. this also allows prefixing the alias with var definitions.

lib/sh/util.sh: echo_*func aliases: use simpler && syntax (with `|| true` to prevent errexit if the condition is false) instead of an if statement. this also allows prefixing the alias with var definitions.

lib/sh/util.sh: echo_func: only indent if the function call was displayed. this avoids confusing extra whitespace when a function call causes an indent but the function call itself isn't printed.

bugfix: lib/sh/util.sh: echo_minor_func: need to include "$@" in echo_func() call

lib/sh/util.sh: echo_func(): added usage

lib/sh/util.sh: echo_func: added usage

lib/sh/util.sh: $log_level_indent: changed to a single space rather than two, to avoid very deep indents as the call tree becomes more deeply nested. due to the + at the beginning of every line, a single space is enough to visualize the structure of the call tree (unlike source code, which requires more whitespace because it doesn't have a call tree structure).

lib/sh/util.sh: echo_*func aliases: increase the indent for the duration of the function call. this causes function calls to be displayed in an indented call-tree structure, which makes the verbose output much easier to understand.

bugfix: lib/sh/util.sh: recursive aliases (i.e. aliases that call a command of the same name): use "" around the command name so it isn't reexpanded if the function using the alias is copied using copy_func(). (aliases will be reexpanded every time a function is redeclared since they appear unquoted in the function definition.) this is a bug in `declare -f` for which there is no fix, necessitating the "" alias workaround instead.

lib/sh/util.sh: moved log-indent-related vars/aliases before they are first used (by log())

lib/sh/util.sh: renamed inc_log_level/dec_log_level to shorter log++/log--

lib/sh/util.sh: renamed inc_log_level/dec_log_level to shorter log++/log--

lib/sh/util.sh: renamed cmd_indent to just indent now that indent is not being used for the PS4 level

*{.sh,run}: multi-command aliases: enclose in {} so the alias can be used after ||

lib/sh/util.sh: renamed indent->PS4++ , outdent->PS4-- because these relate just to the PS4 length, not to the (whitespace-based) log_indent

lib/sh/util.sh: removed no longer used echo_run(). use command() instead.

*{.sh,run}: use command instead of deprecated echo_run (don't prepend anything when the command is already aliased with `command`)

lib/sh/util.sh: command(): perform echo_run_prep itself instead of requiring echo_run to be added in an alias. echo_run_prep will not be performed if limit_stderr_cmd() has performed it already outside the limit_stderr section. this requires using `builtin command` instead of "command" when you don't want the echoing (such as in include_guard_var()).

*{.sh,run}: multi-command aliases: enclose in {} so the alias can be used after ||

bugfix: lib/sh/util.sh: .(): also need to echo the . before the included file

lib/sh/util.sh: added echo_params alias and use it instead of `log "$*"`

lib/sh/util.sh: .(): echo the include at log_level 2 because it's an internal command

lib/sh/util.sh: echo_cmd(): also remove `builtin` before the command name

lib/sh/util.sh: echo_cmd(): don't remove -- after command, because it is added by the command() function instead and does not appear in the command sent to echo_run()

lib/sh/util.sh: command alias: don't alias-expand next word, because the next word should only be interpreted as a command (part of the effect of the `command` builtin)

lib/sh/util.sh: external commands: always use command rather than echo_run to indicate that a command is external, because command() ensures that what it invokes is not a shell function, and sets 2>&22 where needed

lib/sh/util.sh: .(): use echo_run so that included files are echoed as they are included. note that echo_run uses cmd_indent, so the included files' load-time logging output will be indented according to the nesting level of the include.

lib/sh/util.sh: moved .() command echoing > internal commands section

lib/sh/util.sh: moved echo_run() to general command echoing section because it can also be used for internal commands

removed no longer used inputs/GBIF/MySQL_export. use lib/sh/local.sh mysql_export_local() instead.

inputs/GBIF/raw_occurrence_record/run: override table.tsv/make() instead of export_mysql()

inputs/GBIF/table.run: table.tsv/make(): use new mysql_export_local instead of ./MySQL_export

lib/sh/local.sh: added mysql_export_local()

lib/sh/db.sh: added mysql_export(). documented that mysql_export_outfile() supports CSV, but requires the FILE privilege.

lib/sh/db.sh: mysql(): use --column-names to ensure the output is formatted appropriately. note that --column-names is the default, but better to specify it to be sure.

lib/sh/db.sh: mysql(): output_data mode: use --batch to ensure the output is formatted appropriately. note that --batch is the default when stdin is from a pipe, but better to specify it to be sure.

*{.sh,run}: use new limit_stdout_cmd instead of `stdout2stderr=1 limit_stderr_cmd`

lib/sh/util.sh: added limit_stdout_cmd alias

lib/sh/make.sh: added $rm short var for $remake

lib/sh/util.sh: verbosity: removed `declare -i verbosity` because this does not actually ensure that $verbosity is an integer; it only has "arithmetic evaluation [...] done when the variable is assigned to" (`help declare`)

lib/sh/util.sh: verbosity: support setting this in alternate short-name var $vb

lib/sh/util.sh: override the `.` builtin (a.k.a. `source`) and run canon_rel_path on the included script. this removes .. in the path when it's displayed in bash error messages.

lib/sh/util.sh: log_err(): ensure errors are visible by using 2>&22. since this is uses log(), verbosity=1 also needs to be set.

lib/sh/util.sh: $explicit_errors_only: explicitly set verbosity=0 to hide startup logging

lib/sh/util.sh: limit_stderr(): if stdout goes to stderr (i.e. is logging info), assume that stderr_is_errors

lib/sh/util.sh: $explicit_errors_only: documented that this option should only be used for testing the explicit error displaying, as otherwise, important output may be missed

lib/sh/util.sh: $explicit_errors_only: added usage

bugfix: lib/sh/util.sh: command(): updated $errors_only var name to $explicit_errors_only

lib/sh/util.sh: $explicit_errors_only: noted that verbosity=0 displays everything that isn't explicitly hidden

lib/sh/local.sh: psql(): use new stderr_is_errors=1 since psql's logging output comes on stdout, so stderr contains only errors. (the caveat of this is that the query output is normally mixed with logging info on stdout, and needs to be separated out to a different file descriptor using --output.)

lib/sh/util.sh: added $explicit_errors_only env var which shows only explicitly-displayed errors (those which have been redirected to fd 22). note that most of the time, this has the same effect as `verbosity=0 script...`.

lib/sh/util.sh: command(): support ensuring errors are visible by redirecting them to fd 22 (global stderr) when $stderr_is_errors is set

lib/sh/util.sh: `command`: always prepend -- to the args list (to ensure that the command name is not interpreted as a `command` option), not just when the command alias is used

lib/sh/util.sh: set_global_fds(): increase the log_level so the shadow_fd()/set_fd() function names aren't output at the default verbosity (3), and the redirection commands themselves aren't output at verbosity <= 2. set_global_fds() happens at the beginning of every script that uses util.sh, and is fairly predictable, so it isn't necessary to always echo these commands.

lib/sh/local.sh: psql(): use new convention for command-specific alternate stdout

lib/sh/make.sh: inline_make: use new convention for command-specific alternate stdin

*{.sh,run}: removed extra space between function name and ()

lib/sh/util.sh: streams: moved setting of global stdin/stdout/stderr into set_global_fds () function

lib/sh/util.sh: streams: allow commands to access global stdin/stdout/stderr using fd 20/21/22. this works even when /dev/tty isn't available.

lib/sh/util.sh: streams: added convention that fd 10/11/12 should be used for command-specific alternate stdin/stdout/stderr

lib/sh/util.sh: added streams functions fd_exists, set_fd, shadow_fd, and helpers

lib/sh/util.sh: added echo_minor_func alias