.. _stdlib_tty:

==========================
Terminal capability probes
==========================

.. das:module:: tty

The TTY module answers whether a stream is attached to a real terminal, and how
wide that terminal is.

This is the gate for anything that redraws itself with a carriage return: a
progress bar written to a pipe, a redirect, or a supervising process is garbage
in the resulting log. Checking ``TERM`` is not a substitute — it stays set when
standard output is redirected. ``daslib/ansi_colors`` handles styling; this
module answers the capability question underneath it.

All functions and symbols are in "tty" module, use require to get access to it.

.. code-block:: das

    require daslib/tty

Example:

.. code-block:: das

    require daslib/tty

    [export]
    def main() {
        if (is_stdout_terminal()) {
            print("drawing a {terminal_columns()}-column progress bar\n")
        } else {
            print("output is captured — emitting plain lines instead\n")
        }
    }



+++++++++
Constants
+++++++++

.. _global-tty-TTY_STDIN:

.. das:attribute:: TTY_STDIN = 0

TTY_STDIN:int const

.. _global-tty-TTY_STDOUT:

.. das:attribute:: TTY_STDOUT = 1

TTY_STDOUT:int const

.. _global-tty-TTY_STDERR:

.. das:attribute:: TTY_STDERR = 2

TTY_STDERR:int const

.. _global-tty-TTY_DEFAULT_WIDTH:

.. das:attribute:: TTY_DEFAULT_WIDTH = 80

TTY_DEFAULT_WIDTH:int const


++++++++++++++++++
Terminal detection
++++++++++++++++++

  *  :ref:`is_stderr_terminal () : bool <function-tty_is_stderr_terminal>`
  *  :ref:`is_stdin_terminal () : bool <function-tty_is_stdin_terminal>`
  *  :ref:`is_stdout_terminal () : bool <function-tty_is_stdout_terminal>`
  *  :ref:`is_stream_terminal (fd: int) : bool <function-tty_is_stream_terminal_int>`

.. _function-tty_is_stderr_terminal:

.. das:function:: is_stderr_terminal() : bool

True when standard error is attached to a terminal.


.. _function-tty_is_stdin_terminal:

.. das:function:: is_stdin_terminal() : bool

True when standard input is attached to a terminal.


.. _function-tty_is_stdout_terminal:

.. das:function:: is_stdout_terminal() : bool

True when standard output is attached to a terminal. This is the gate for a redrawn
progress display — false under a pipe, a redirect, or a supervising process.


.. _function-tty_is_stream_terminal_int:

.. das:function:: is_stream_terminal(fd: int) : bool

True when the standard stream `fd` (`TTY_STDIN` / `TTY_STDOUT` / `TTY_STDERR`) is
attached to a terminal. Any other descriptor is false.


:Arguments: * **fd** : int


+++++++++++++++++
Terminal geometry
+++++++++++++++++

  *  :ref:`terminal_columns (fallback: int = TTY_DEFAULT_WIDTH) : int <function-tty_terminal_columns_int>`

.. _function-tty_terminal_columns_int:

.. das:function:: terminal_columns(fallback: int = TTY_DEFAULT_WIDTH) : int

def terminal_columns (fallback: int = TTY_DEFAULT_WIDTH) : int

:Arguments: * **fallback** : int