#!/usr/bin/env bash

#
# ## timestamp_set()
#
# Sets the variable named 'timestamp' to the current timestamp.
#
# ### Input Parameters
#
# None.
#
# ### Stream Outputs
#
# None.
#
# ### Environmental effects
#
# Sets the variable named 'timestamp' to the current timestamp.
#
# ### Return Codes
#
# 0 for success
#
# ### Failure Scenarios
#
# No failure scenarios currently.
#
# ### Usage Examples
#
#     user$ cat ./test
#     #!/usr/bin/env bash
#     source "/usr/local/bdsm/extensions/builtin/core/modules/shell/core/initialize" # Load BDSM framework core.
#     modules trace time # Load the trace module.
#
#     timestamp_set
#     echo $timestamp
#
#     user$ $PWD/test
#     2011-04-24T22:28:16
#
# ### Code Walkthrough
timestamp_set()
{
  # Set the timestamp variable to the STDOUT of the timestamp function call.
  timestamp="$(timestamp)"
}

#
# ## timestamp()
#
# Prints out the current timestamp.
#
# ### Input Parameters
#
# None required. The first parameter may optionally specify the format to output
# the time string in. See 'man 1 date' for formatting options.
#
# ### Stream Outputs
#
# Prints the current timestamp as a formatted datetime string to the STDOUT of
# the calling environment.
#
# ### Environmental effects
#
# None.
#
# ### Return Codes
#
# 0 for success.
#
# ### Failure Scenarios
#
# No failure conditions currently.
#
# ### Usage Examples
#
#     user$ cat ./test
#     #!/usr/bin/env bash
#     source "/usr/local/bdsm/extensions/builtin/core/modules/shell/core/initialize" # Load BDSM framework core.
#     modules trace time # Load the trace module.
#
#     timestamp
#     echo
#
#     user$ $PWD/test
#     2011-04-24T22:31:54
#
# ### Code Walkthrough
timestamp()
{
  # Set the format to either the first parameter, if nonempty or to the
  # iso-something format ;) otherwise. Use the date command with the format
  # string and print the result to the STDOUT of the calling environment.
  local _format="${1:-"%Y-%m-%dT%H:%M:%S"}"
  date +"${_format}"
}

