fortplot_text_color Module

ANSI color-mode policy and SGR escape assembly for the text backend (issue #2062).

Color modes: never no ANSI escapes ansi16 SGR 30-37/90-97 foreground colors ansi256 SGR 38;5; foreground colors truecolor SGR 38;2;;; foreground colors auto color only for an interactive terminal that appears to support it; suppressed by NO_COLOR and TERM=dumb.

Saved .txt artifacts default to 'never' so bytes stay reproducible. The 'auto' mode is resolved conservatively at output time: file output never resolves to color, and terminal output resolves through the environment and a stdout TTY probe. All escape bytes are built with achar() so this source stays pure ASCII.


Uses


Variables

Type Visibility Attributes Name Initial
integer, public, parameter :: COLOR_NONE = -1

Functions

public function is_valid_text_color_mode(mode) result(valid)

True when mode names one of the five canonical color modes.

Arguments

Type IntentOptional Attributes Name
character(len=*), intent(in) :: mode

Return Value logical

public function normalize_text_color_mode(name) result(mode)

Canonicalize a user color-mode selection; unknown names fall back to 'never' so unexpected input can never leak escapes into output.

Arguments

Type IntentOptional Attributes Name
character(len=*), intent(in) :: name

Return Value character(len=:), allocatable

public function resolve_text_color_mode_file(mode) result(resolved)

Resolve the color mode for file output. Saved files must stay reproducible, so 'auto' always resolves to 'never'; explicit modes are honored because the caller asked for them.

Arguments

Type IntentOptional Attributes Name
character(len=*), intent(in) :: mode

Return Value character(len=:), allocatable

public function resolve_text_color_mode_terminal(mode) result(resolved)

Resolve the color mode for interactive terminal output. Explicit modes are honored; 'auto' is resolved from the environment and a stdout TTY probe.

Arguments

Type IntentOptional Attributes Name
character(len=*), intent(in) :: mode

Return Value character(len=:), allocatable

public function sgr_foreground(mode, r, g, b) result(seq)

SGR foreground escape for the given color mode and RGB (0..1). Returns an empty string for 'never'/unknown modes.

Arguments

Type IntentOptional Attributes Name
character(len=*), intent(in) :: mode
real(kind=wp), intent(in) :: r
real(kind=wp), intent(in) :: g
real(kind=wp), intent(in) :: b

Return Value character(len=:), allocatable

public function sgr_reset() result(seq)

The SGR reset escape emitted after a colored span and before every newline or frame boundary.

Arguments

None

Return Value character(len=:), allocatable

public pure function pack_rgb(r, g, b) result(packed)

Pack an RGB triple (0..1) into a single 24-bit integer for the per-cell color buffer.

Arguments

Type IntentOptional Attributes Name
real(kind=wp), intent(in) :: r
real(kind=wp), intent(in) :: g
real(kind=wp), intent(in) :: b

Return Value integer

public pure function color_to_ansi16(r, g, b) result(code)

Map an RGB triple to a standard (30-37) or bright (90-97) SGR foreground code by nearest 3-bit color plus a luminance-based bright bit.

Arguments

Type IntentOptional Attributes Name
real(kind=wp), intent(in) :: r
real(kind=wp), intent(in) :: g
real(kind=wp), intent(in) :: b

Return Value integer

public pure function color_to_ansi256(r, g, b) result(idx)

Map an RGB triple to a 6x6x6 color-cube index (16..231).

Arguments

Type IntentOptional Attributes Name
real(kind=wp), intent(in) :: r
real(kind=wp), intent(in) :: g
real(kind=wp), intent(in) :: b

Return Value integer


Subroutines

public pure subroutine unpack_rgb(packed, r, g, b)

Inverse of pack_rgb; returns channels in 0..1.

Arguments

Type IntentOptional Attributes Name
integer, intent(in) :: packed
real(kind=wp), intent(out) :: r
real(kind=wp), intent(out) :: g
real(kind=wp), intent(out) :: b