==============================
PBDB - Primitive Bash Debugger
==============================

.. default-domain:: bash

.. file:: pdbd.bsh

A debugger written in bash with no extra requirements to debug bash scripts.

The debugger can be started via calling :func:`set_trace`

To get "dbstop if error" behavior (start the debugger automatically on an error)

.. rubric:: Debugger stop if error

.. code-block:: bash

  set -Ee # Preferably set -Eeu
  trap set_trace ERR

.. envvar:: _debug_prompt

The prompt the debugger shows, default ``$``

.. envvar:: _debug_L_file_color
.. envvar:: _debug_L_function_color
.. envvar:: _debug_L_line
.. envvar:: _debug_L_current_line

The default colors used when printing out lines of code (``l`` command)

.. envvar:: JUST_DEBUG_READ_METHOD

The method for reading from the keyboard. Three methods are supported.

- ``read`` - Using "readline" via ``read -e``, which includes its own separate history file. This is ok for single line entry only. Works using pure bash
- ``manual`` - A manual implementation of read that supports multiple lines (via ending a line with ``\`` and pressing enter), has a separate history (:envvar:`JUST_DEBUG_HISTORY`), and is *unfinished*. Also works using pure bash
- ``{python}`` - Given the name of a python executable (either full path or just ``python3``), runs ``debug_readline.py`` in python to get user input. This is the best option, but requires a python install with ``prompt_toolkit`` and ``pygments`` installed. The color scheme for python can be changed by setting the ``_debug_read_color_scheme`` environment variable (default ``vim``).

.. envvar:: JUST_DEBUG_HISTORY

The history file used for storing previous values. The ``read`` :envvar:`JUST_DEBUG_READ_METHOD` appends a 2 to the filename, and the ``python`` method appends a ``3``

.. envvar:: JUST_DEBUG_HISTORY_LENGTH

The ``manual`` :envvar:`JUST_DEBUG_READ_METHOD` will limit itself to :envvar:`JUST_DEBUG_HISTORY_LENGTH` unique entries, default ``1000``.

.. function:: set_trace

:Arguments: [``$1``] - Number of stacks to skip
:Output: By default outputs to stderr(2), but if you redirect stderr, you can
         redirect :func:`set_trace` to another stream (3 for example) using
         ``2>&3``.

Starts the debugger