=========
Set Flags
=========

.. default-domain:: bash

.. file:: set_flags.bsh

Functions to make settings/clearing ``bash`` flags easy

Sometimes a flag needs to be set locally for a piece of code, and should be reset if and only if it wasn't set before. These functions do remember the original state so that it can be reset with a simple call

.. rubric:: Example

.. code-block:: bash

  set_flag u
  # <code here>
  reset_flag u

  set_flag e
  unset_flag E
  set_flags xv
  # <code here>
  reset_flags

.. seealso::
  :func:`set_flag` :func:`unset_flag` :func:`reset_flag` :func:`set_flags` :func:`unset_flags` :func:`reset_flags` :func:`set_optflag` :func:`unset_optflag` :func:`reset_optflag` :func:`set_optflags` :func:`unset_optflags` :func:`reset_optflags` :func:`set_oflag` :func:`unset_oflag` :func:`reset_oflag` :func:`set_oflags` :func:`unset_oflags` :func:`reset_oflags`

.. function:: _save_flag

:Arguments: ``$1`` - Single letter flag to save
:Output: Stores original state in ``VSI_COMMON_SET_FLAG_<flag>``.

Saves the previous state of a flag

.. note::
  The original state is smart enough to not be overridden by multiple calls to :func:`set_flag`/:func:`unset_flag`. The original state means the state before ALL :func:`set_flag` and :func:`unset_flags` were made. And is remembered until :func:`reset_flag` is called.

.. function:: set_flag

:Arguments: ``$1`` - Single letter flag to set
:Output: Stores original state in ``VSI_COMMON_SET_FLAG_<flag>``

Turns on a ``bash`` option, remembers the previous state

.. note::
  The original state is smart enough to not be overridden by multiple calls to :func:`set_flag`/:func:`unset_flag`. The original state is the state before ALL :func:`set_flag` and unset_flag` calls were made, and is remembered until :func:`reset_flag` is called.

.. rubric:: Bugs

Doesn't support o flag. The only options that are not duplicated are: vi, emacs, history, pipefail, and posix. Only pipefail and posix would be of interest, and are stored in SHELLOPTS.

.. function:: unset_flag

Same as :func:`set_flag`, but unsets the flag

.. function:: reset_flag

Resets the flag to the previous state

Sets (or unsets) the flag to the state before the very first call to :func:`set_flag`/:func:`unset_flag`. Also clears the variable ``VSI_COMMON_SET_FLAG_<flag>``

.. function:: set_flags

:Arguments: ``$1`` - Multiple letters allowed

Same as :func:`set_flag`, but sets multiple flags at once

.. function:: unset_flags

:Arguments: ``$1`` - Multiple letters allowed

Same as :func:`unset_flag`, but unsets multiple flags at once

.. function:: reset_flags

:Arguments: ``$1`` - Multiple letters allowed

Same as :func:`reset_flag`, but resets multiple flags at once

.. note::
  If no arguments are given, all flags are reset

.. function:: _save_optflag

:Output: Stores original state in ``VSI_COMMON_SET_OPTFLAG_<flag>``.

shopt version of :func:`_save_flag`

.. function:: set_optflag

shopt version of :func:`set_flag`

.. function:: unset_optflag

shopt version of :func:`unset_flag`

.. function:: reset_optflag

shopt version of :func:`reset_flag`

.. function:: set_optflags

:Arguments: ``$1[...]`` - Multiple arguments allowed

Same as :func:`set_optflag`, but set multiple opt flags at once

.. function:: unset_optflags

:Arguments: ``$1[...]`` - Multiple arguments allowed

Same as :func:`unset_optflag`, but unsets multiple opt flags at once

.. function:: reset_optflags

:Arguments: ``$1[...]`` - Multiple arguments allowed

Same as :func:`reset_optflag`, but unsets multiple opt flags at once

.. note::
  If no arguments are given, all opt flags are reset

.. function:: _save_oflag

:Output: Stores original state in ``VSI_COMMON_SET_OFLAG_<flag>``.

set -o version of :func:`_save_flag`

.. rubric:: Bugs

Since so many of the set flags overlap with "set -o" flags, these two features should not be mixed together and used simultaneously. The only exceptions are the "set -o" flags with no equivalent single letter representation, mainly pipefail and posix

.. function:: set_oflag

set -o version of :func:`set_flag`

.. function:: unset_oflag

set -o version of :func:`unset_flag`

.. function:: reset_oflag

set -o version of :func:`reset_flag`

.. rubric:: Bugs

Resetting certain flags does not return everything to status quo. For example, setting vi mode, and then resetting does not restore emacs mode. This is the only known bug, and is not important from a scripting point of view.

.. function:: set_oflags

:Arguments: ``$1[...]`` - Multiple arguments allowed

Same as :func:`set_oflag`, but sets multiple opt flags at once

.. function:: unset_oflags

Same as :func:`unset_oflag`, but unsets multiple opt flags at once

.. function:: reset_oflags

Same as :func:`reset_oflag`, but reset multiple flags at once

.. note::
  If no arguments are given, all opt flags are reset