.. default-domain:: chpl

.. module:: TerminalColors
   :synopsis: This module provides utilities for styling terminal output with colors and

TerminalColors
==============
**Usage**

.. code-block:: chapel

   use TerminalColors;


or

.. code-block:: chapel

   import TerminalColors;


This module provides utilities for styling terminal output with colors and
modifiers using ANSI escape codes.

The primary type is :type:`styledText`, which can be used with various
factory functions to create styled text with color and text modifiers
(e.g., bold, italic, underline).

:type:`color` defines various color options, including standard ANSI colors
and RGB colors for both 256 color terminals and truecolor (24-bit) terminals.

The :type:`modifiers` record defines a subset of widely supported ANSI text
modifiers, which can be combined together.

.. type:: styledText : writeSerializable

   
   The `styledTest` type contains all of the styling information for a piece of
   text, including the text itself.
   
   This type should not be instantiated
   directly, instead prefer the various factory functions like
   :proc:`style`, :proc:`red`, :proc:`bold`, etc.
   
   For example,
   
   .. code-block:: chapel
   
      writeln(red("Hello, world!").bold().underline());
   

.. type:: color : writeSerializable

   
   The `color` type represents a terminal color that can be applied to text.
   
   This type should not be instantiated directly, instead prefer the various
   factory functions like :proc:`red()`, :proc:`rgb256()`, etc.
   

.. type:: modifiers : writeSerializable

   
   The `modifiers` type represents various text modifiers that can be applied
   to styled text, such as bold, italic, underline, etc.
   
   This type should not be instantiated directly.
   If you just need the modifier, use a factory function like :proc:`bold()`
   or :proc:`italic()`.
   
   Modifiers can be combined together like ``bold() + italic()`` or
   ``bold() + underline()`` to apply multiple text modifiers.
   You can also apply these modifiers to existing styles like
   ``red("Hello") + bold() + italic()`` or
   ``red("Hello").mod(bold()).mod(italic())``.
   

.. function:: proc style(text = ""): styledText

   
   Creates a new :type:`styledText` with the given text. This serves as the 
   base for creating more complex styled text by applying colors and modifiers
   to it.
   
   For example, the following are all equivalent ways to create bold, red text
   using `style`.
   
   .. code-block:: chapel
   
      writeln(style().fg(red()).bold(), "Hello, world!", reset());
      writeln(style("Hello, world!").fg(red()).bold());
   

.. method:: proc styledText.fg(c: color, intense = false)

   
   Sets the foreground color (text color) of a :type:`styledText`.
   
   For example, to create blue text:
   
   .. code-block:: chapel
   
      writeln(style("Hello, world!").fg(blue()));
   

.. method:: proc styledText.bg(c: color, intense = false)

   
   Sets the background color of a :type:`styledText`.
   
   For example, to create text with a red background:
   
   .. code-block:: chapel
   
      writeln(style("Hello, world!").bg(red()));
   

.. method:: proc styledText.add(m: modifiers)

   
   Adds text modifiers (e.g., bold, italic, underline) to a :type:`styledText`.
   
   For example, to create bold and underlined text the following are all
   equivalent:
   
   .. code-block:: chapel
   
      writeln(style("Hello, world!").mod(bold() + underline()));
      writeln(style("Hello, world!").mod(bold()).mod(underline()));
   

.. method:: proc styledText.bold(): styledText

   
   This family of functions applies specific modifiers to a :type:`styledText`.
   These are convenience functions that call :proc:`add` with the appropriate
   modifier.
   
   For example, the following are equivalent ways to create bold text:
   
   .. code-block:: chapel
   
      writeln(style("Hello, world!").bold());
      writeln(style("Hello, world!").add(bold()));
   

.. method:: proc styledText.dim(): styledText

.. method:: proc styledText.italic(): styledText

.. method:: proc styledText.underline(): styledText

.. method:: proc styledText.blink()

.. method:: proc styledText.invert()

.. method:: proc styledText.hidden()

.. method:: proc styledText.strikethrough()

.. method:: proc styledText.finish(): string

   
   Returns the final styled string with all ANSI escape codes applied. This is
   called automatically when a :type:`styledText` is passed to an output
   statement like ``writeln`` or ``write``.
   
   For example, the following will print bold, red text to the terminal:
   
   .. code-block:: chapel
   
      writeln(red("Hello, world!").bold());
   
   If you need to manually get the styled string (e.g., to concatenate it with
   other strings), you can call this method directly:
   
   .. code-block:: chapel
   
      var styled = red("Hello, world!").bold().finish();
      writeln("Styled message: " + styled);
   

.. function:: proc reset(): string

   
   Returns a string that resets the terminal styling back to the default.
   This only needs to be used when manually constructing ANSI escape codes,
   when using the :type:`styledText` type and its associated factory functions
   it is unnecessary.
   

.. function:: proc bold(): modifiers

   
   This family of functions return the standalone modifiers. These modifiers
   can be passed to the :proc:`styledText.add` method or used standalone.
   
   For example, the following are all equivalent ways to create bold text:
   
   .. code-block:: chapel
   
      writeln(bold() + "Hello, world!" + reset()); // this method
      writeln(style("Hello, world!").add(bold())); // this method
      writeln(style("Hello, world!").bold());
      writeln(bold("Hello, world!"));
   

.. function:: proc dim(): modifiers

.. function:: proc italic(): modifiers

.. function:: proc underline(): modifiers

.. function:: proc blink(): modifiers

.. function:: proc invert(): modifiers

.. function:: proc hidden(): modifiers

.. function:: proc strikethrough(): modifiers

.. function:: proc bold(text: string): styledText

   
   This family of functions applies specific modifiers to a string by creating
   a :type:`styledText` with the given string and applying the appropriate
   modifier. These are shortcuts for common use cases where you just want to
   apply a single modifier.
   
   For example, the following are all equivalent ways to create bold text:
   
   .. code-block:: chapel
   
      writeln(bold() + "Hello, world!" + reset());
      writeln(style("Hello, world!").add(bold()));
      writeln(style("Hello, world!").bold());
      writeln(bold("Hello, world!")); // this method
   

.. function:: proc dim(text: string): styledText

.. function:: proc italic(text: string): styledText

.. function:: proc underline(text: string): styledText

.. function:: proc blink(text: string): styledText

.. function:: proc invert(text: string): styledText

.. function:: proc hidden(text: string): styledText

.. function:: proc strikethrough(text: string): styledText

.. function:: proc black(): color

   
   This family of functions return the standalone colors. These can be passed
   to the :proc:`styledText.fg` or :proc:`styledText.bg` methods or used
   standalone.
   
   When used standalone, it is assumed that the color is a foreground color.
   
   For example, the following are all equivalent ways to create red text:
   
   .. code-block:: chapel
   
      writeln(red() + "Hello, world!" + reset()); // this method
      writeln(style("Hello, world!").fg(red())); // this method
      writeln(red("Hello, world!"));
   

.. function:: proc red(): color

.. function:: proc green(): color

.. function:: proc yellow(): color

.. function:: proc blue(): color

.. function:: proc magenta(): color

.. function:: proc cyan(): color

.. function:: proc white(): color

.. function:: proc rgb256(n: int): color

.. function:: proc rgb24(r: int, g: int, b: int): color

.. function:: proc black(text: string): styledText

   
   This family of functions applies specific colors to a string by creating a
   :type:`styledText` with the given string and applying the appropriate color.
   These are shortcuts for common use cases where you just want to apply a
   single color.
   
   These functions assume you want to set the foreground color.
   If you want to set the background color, you can use the
   :proc:`styledText.bg` method with the standalone color functions.
   
   For example, the following are all equivalent ways to create red text:
   
   .. code-block:: chapel
   
      writeln(red() + "Hello, world!" + reset());
      writeln(style("Hello, world!").fg(red()));
      writeln(red("Hello, world!")); // this method
   

.. function:: proc red(text: string): styledText

.. function:: proc green(text: string): styledText

.. function:: proc yellow(text: string): styledText

.. function:: proc blue(text: string): styledText

.. function:: proc magenta(text: string): styledText

.. function:: proc cyan(text: string): styledText

.. function:: proc white(text: string): styledText

.. function:: proc rgb256(n: int, text: string): styledText

.. function:: proc rgb24(r: int, g: int, b: int, text: string): styledText