libStdOut
=========

Functions to help print messages.

Overview
--------

Functions to help print consistent messages.

Contains the following:

- ksl::stdOut()
- ksl::stdErr()
- ksl::stdTrace() - prepends [TRACE] to the message
- ksl::stdDebug() - prepends [DEBUG] to the message
- ksl::stdInfo() - prepends [INFO] to the message
- ksl::stdWarn() - prepends [WARN] to the message
- ksl::stdError() - prepends [ERROR] to the message
- ksl::stdFatal() - prepends [FATAL] to the message

|image1|

**Colors**

Colors can be changed and applied to the introducer string as well as
the text of the message itself. So for example, ``[TRACE]`` would be
displayed in the ``COLOR_TRACE_INTRO`` color and the text of the trace
message would be displayed in the ``COLOR_TRACE_TEXT`` color. If
ksl::useColor()\` is true, then the following colors are applied to
introducers and text.

- ``COLOR_TRACE_INTRO=${FG_MAGENTA}``

- ``COLOR_DEBUG_INTRO=${FG_MAGENTA}``

- ``COLOR_INFO_INTRO=${FG_GREEN}``

- ``COLOR_WARN_INTRO=${FG_YELLOW}``

- ``COLOR_ERROR_INTRO=${FG_RED}``

- ``COLOR_FATAL_INTRO=${BOLD}${FG_RED}``

- ``COLOR_TRACE_TEXT=`` # default is terminal color

- ``COLOR_DEBUG_TEXT=`` # default is terminal color

- ``COLOR_INFO_TEXT=`` # default is terminal color

- ``COLOR_WARN_TEXT=${FG_YELLOW}``

- ``COLOR_ERROR_TEXT=${FG_RED}``

- ``COLOR_FATAL_TEXT=${FG_RED}``

An application can modify these colors as desired. See
`libColors <libColors.html>`__ for color setup.

--------------

Index
-----

- `ksl::stdOut <#kslstdout>`__
- `ksl::stdErr <#kslstderr>`__
- `ksl::stdTrace <#kslstdtrace>`__
- `ksl::stdDebug <#kslstddebug>`__
- `ksl::stdInfo <#kslstdinfo>`__
- `ksl::stdWarn <#kslstdwarn>`__
- `ksl::stdError <#kslstderror>`__
- `ksl::stdFatal <#kslstdfatal>`__

ksl::stdOut
~~~~~~~~~~~

Output text to standard out.

Does not embelish text with any introducer or color.

Example
^^^^^^^

.. code:: bash

   ksl::stdOut "${scriptName} v${scriptVersion}"

Arguments
^^^^^^^^^

- **$1** (…): all args are printed to stdout

Exit codes
^^^^^^^^^^

- **0**: in all cases

Output on stdout
^^^^^^^^^^^^^^^^

- all the args

  .. raw:: html

     <p>

  .. raw:: html

     <p>

  |image2|

ksl::stdErr
~~~~~~~~~~~

Output text to standard error.

Does not embelish text with any introducer or color.

.. _example-1:

Example
^^^^^^^

.. code:: bash

   ksl::stdErr "${scriptName} v${scriptVersion}"

.. _arguments-1:

Arguments
^^^^^^^^^

- **$1** (…): all args are printed to stdout

.. _exit-codes-1:

Exit codes
^^^^^^^^^^

- **0**: in all cases

Output on stderr
^^^^^^^^^^^^^^^^

- all the args

  .. raw:: html

     <p>

  .. raw:: html

     <p>

  |image3|

ksl::stdTrace
~~~~~~~~~~~~~

Output message to standard out prefaced by ``[TRACE]``.

If `ksl::useColor <libColor.html#kslusecolor>`__ is true then colors are
applied.

.. _example-2:

Example
^^^^^^^

.. code:: bash

   ksl::stdTrace "Entered: showConfig()"
   outputs: [TRACE] Entered: showConfig()

.. _arguments-2:

Arguments
^^^^^^^^^

- **$1** (…): all args are printed to stdout

Variables set
^^^^^^^^^^^^^

- **COLOR_TRACE_INTRO** (string): the color to use for the introducer
- **COLOR_TRACE_TEXT** (string): the color to use for the text following
  the introducer

.. _exit-codes-2:

Exit codes
^^^^^^^^^^

- **0**: in all cases

.. _output-on-stdout-1:

Output on stdout
^^^^^^^^^^^^^^^^

- [TRACE] followed by all the args

  .. raw:: html

     <p>

  .. raw:: html

     <p>

  |image4|

ksl::stdDebug
~~~~~~~~~~~~~

Output message to standard out prefaced by ``[DEBUG]``.

If `ksl::useColor <libColor.html#kslusecolor>`__ is true then colors are
applied.

.. _example-3:

Example
^^^^^^^

.. code:: bash

   ksl::stdDebug "Entered: showConfig()"
   outputs: [DEBUG] Entered: showConfig()

.. _arguments-3:

Arguments
^^^^^^^^^

- **$1** (…): all args are printed to stdout

.. _variables-set-1:

Variables set
^^^^^^^^^^^^^

- **COLOR_DEBUG_INTRO** (string): the color to use for the introducer
- **COLOR_DEBUG_TEXT** (string): the color to use for the text following
  the introducer

.. _exit-codes-3:

Exit codes
^^^^^^^^^^

- **0**: in all cases

.. _output-on-stdout-2:

Output on stdout
^^^^^^^^^^^^^^^^

- [DEBUG] followed by all the args

  .. raw:: html

     <p>

  .. raw:: html

     <p>

  |image5|

ksl::stdInfo
~~~~~~~~~~~~

Output message to standard out prefaced by ``[INFO]``.

If `ksl::useColor <libColor.html#kslusecolor>`__ is true then colors are
applied.

.. _example-4:

Example
^^^^^^^

.. code:: bash

   ksl::stdInfo "Entered: showConfig()"
   outputs: [INFO] Entered: showConfig()

.. _arguments-4:

Arguments
^^^^^^^^^

- **$1** (…): all args are printed to stdout

.. _variables-set-2:

Variables set
^^^^^^^^^^^^^

- **COLOR_INFO_INTRO** (string): the color to use for the introducer
- **COLOR_INFO_TEXT** (string): the color to use for the text following
  the introducer

.. _exit-codes-4:

Exit codes
^^^^^^^^^^

- **0**: in all cases

.. _output-on-stdout-3:

Output on stdout
^^^^^^^^^^^^^^^^

- [INFO] followed by all the args

  .. raw:: html

     <p>

  .. raw:: html

     <p>

  |image6|

ksl::stdWarn
~~~~~~~~~~~~

Output message to standard out prefaced by ``[WARN]``.

If `ksl::useColor <libColor.html#kslusecolor>`__ is true then colors are
applied.

.. _example-5:

Example
^^^^^^^

.. code:: bash

   ksl::stdWarn "Entered: showConfig()"
   outputs: [WARN] Entered: showConfig()

.. _arguments-5:

Arguments
^^^^^^^^^

- **$1** (…): all args are printed to stdout

.. _variables-set-3:

Variables set
^^^^^^^^^^^^^

- **COLOR_WARN_INTRO** (string): the color to use for the introducer
- **COLOR_WARN_TEXT** (string): the color to use for the text following
  the introducer

.. _exit-codes-5:

Exit codes
^^^^^^^^^^

- **0**: in all cases

.. _output-on-stdout-4:

Output on stdout
^^^^^^^^^^^^^^^^

- [WARN] followed by all the args

  .. raw:: html

     <p>

  .. raw:: html

     <p>

  |image7|

ksl::stdError
~~~~~~~~~~~~~

Output message to standard error prefaced by ``[ERROR]``.

If `ksl::useColor <libColor.html#kslusecolor>`__ is true then colors are
applied.

.. _example-6:

Example
^^^^^^^

.. code:: bash

   ksl::stdError "Entered: showConfig()"
   outputs: [ERROR] Entered: showConfig()

.. _arguments-6:

Arguments
^^^^^^^^^

- **$1** (…): all args are printed to stderr

.. _variables-set-4:

Variables set
^^^^^^^^^^^^^

- **COLOR_ERROR_INTRO** (string): the color to use for the introducer
- **COLOR_ERROR_TEXT** (string): the color to use for the text following
  the introducer

.. _exit-codes-6:

Exit codes
^^^^^^^^^^

- **0**: in all cases

.. _output-on-stderr-1:

Output on stderr
^^^^^^^^^^^^^^^^

- [ERROR] followed by all the args

  .. raw:: html

     <p>

  .. raw:: html

     <p>

  |image8|

ksl::stdFatal
~~~~~~~~~~~~~

Output message to standard error prefaced by ``[FATAL]``.

If `ksl::useColor <libColor.html#kslusecolor>`__ is true then colors are
applied.

.. _example-7:

Example
^^^^^^^

.. code:: bash

   ksl::stdFatal "Entered: showConfig()"
   outputs: [FATAL] Entered: showConfig()

.. _arguments-7:

Arguments
^^^^^^^^^

- **$1** (…): all args are printed to stderr

.. _variables-set-5:

Variables set
^^^^^^^^^^^^^

- **COLOR_FATAL_INTRO** (string): the color to use for the introducer
- **COLOR_FATAL_TEXT** (string): the color to use for the text following
  the introducer

.. _exit-codes-7:

Exit codes
^^^^^^^^^^

- **0**: in all cases

.. _output-on-stderr-2:

Output on stderr
^^^^^^^^^^^^^^^^

- [FATAL] followed by all the args

  .. raw:: html

     <p>

  .. raw:: html

     <p>

  |image9|

.. |image1| image:: ../images/pub/stdout-example.png
.. |image2| image:: ../images/pub/divider-line.png
.. |image3| image:: ../images/pub/divider-line.png
.. |image4| image:: ../images/pub/divider-line.png
.. |image5| image:: ../images/pub/divider-line.png
.. |image6| image:: ../images/pub/divider-line.png
.. |image7| image:: ../images/pub/divider-line.png
.. |image8| image:: ../images/pub/divider-line.png
.. |image9| image:: ../images/pub/divider-line.png