Module for decoding and handling ANSI escape sequences. More...

#include <b8/type.h>

Classes
struct	EscapeOut

class	CEscapeSeqDecoder

Enumerations
enum	EscapePAL { PAL_0 , PAL_1 , PAL_2 , PAL_3 }
	Enumeration for selecting a palette in the terminal. More...

enum	EscapeSeqOpe { ESO_ONE_CHAR , ESO_UP , ESO_DOWN , ESO_RIGHT , ESO_LEFT , ESO_DEL , ESO_MOVE_CURSOR , ESO_SEL_PAL , ESO_SET_COLOR , ESO_CLEAR_SCREEN_FROM_CURSOR_DOWN , ESO_CLEAR_SCREEN_FROM_CURSOR_UP , ESO_CLEAR_ENTIRE_SCREEN , ESO_CLEAR_LINE_FROM_CURSOR_RIGHT , ESO_CLEAR_LINE_FROM_CURSOR_LEFT , ESO_CLEAR_ENTIRE_LINE , ESO_ENABLE_SHADOW , ESO_DISABLE_SHADOW , ESO_SET_Z , ESO_NONE }
	Enumeration for escape sequence operations. More...

enum	AnsiColor { ANSI_NULL = 0 , ANSI_COLOR_BLACK = 30 , ANSI_COLOR_RED , ANSI_COLOR_GREEN , ANSI_COLOR_YELLOW , ANSI_COLOR_BLUE , ANSI_COLOR_MAGENTA , ANSI_COLOR_CYAN , ANSI_COLOR_WHITE , ANSI_COLOR_BLACK_BG = 40 , ANSI_COLOR_RED_BG , ANSI_COLOR_GREEN_BG , ANSI_COLOR_YELLOW_BG , ANSI_COLOR_BLUE_BG , ANSI_COLOR_MAGENTA_BG , ANSI_COLOR_CYAN_BG , ANSI_COLOR_WHITE_BG , ANSI_COLOR_B8_BLACK = 50 , ANSI_COLOR_B8_DARK_BLUE , ANSI_COLOR_B8_DARK_PURPLE , ANSI_COLOR_B8_DARK_GREEN , ANSI_COLOR_B8_BROWN , ANSI_COLOR_B8_DARK_GREY , ANSI_COLOR_B8_LIGHT_GREY , ANSI_COLOR_B8_WHITE , ANSI_COLOR_B8_RED , ANSI_COLOR_B8_ORANGE , ANSI_COLOR_B8_YELLOW , ANSI_COLOR_B8_GREEN , ANSI_COLOR_B8_BLUE , ANSI_COLOR_B8_LAVENDER , ANSI_COLOR_B8_PINK , ANSI_COLOR_B8_LIGHT_PEACH , ANSI_COLOR_B8_BLACK_BG = 70 , ANSI_COLOR_B8_DARK_BLUE_BG , ANSI_COLOR_B8_DARK_PURPLE_BG , ANSI_COLOR_B8_DARK_GREEN_BG , ANSI_COLOR_B8_BROWN_BG , ANSI_COLOR_B8_DARK_GREY_BG , ANSI_COLOR_B8_LIGHT_GREY_BG , ANSI_COLOR_B8_WHITE_BG , ANSI_COLOR_B8_RED_BG , ANSI_COLOR_B8_ORANGE_BG , ANSI_COLOR_B8_YELLOW_BG , ANSI_COLOR_B8_GREEN_BG , ANSI_COLOR_B8_BLUE_BG , ANSI_COLOR_B8_LAVENDER_BG , ANSI_COLOR_B8_PINK_BG , ANSI_COLOR_B8_LIGHT_PEACH_BG , ANSI_COLOR_BRIGHT_BLACK = 90 , ANSI_COLOR_BRIGHT_RED , ANSI_COLOR_BRIGHT_GREEN , ANSI_COLOR_BRIGHT_YELLOW , ANSI_COLOR_BRIGHT_BLUE , ANSI_COLOR_BRIGHT_MAGENTA , ANSI_COLOR_BRIGHT_CYAN , ANSI_COLOR_BRIGHT_WHITE , ANSI_COLOR_BRIGHT_BLACK_BG = 100 , ANSI_COLOR_BRIGHT_RED_BG , ANSI_COLOR_BRIGHT_GREEN_BG , ANSI_COLOR_BRIGHT_YELLOW_BG , ANSI_COLOR_BRIGHT_BLUE_BG , ANSI_COLOR_BRIGHT_MAGENTA_BG , ANSI_COLOR_BRIGHT_CYAN_BG , ANSI_COLOR_BRIGHT_WHITE_BG }
	Enumeration for ANSI color codes. More...

Functions
void	EscClearEntireScreen (FILE *fp)
	Clears the entire screen.

void	EscMoveCursor (FILE *fp, s32 x_, s32 y_)
	Moves the cursor to a specific position.

Detailed Description

Module for decoding and handling ANSI escape sequences.

This module is intended for device driver developers and is not meant to be used directly by general users.

This module provides functionality for decoding escape sequences using the CEscapeSeqDecoder class and associated functions. Escape sequences are special strings used primarily for terminal display control, such as moving the cursor, clearing the screen, or modifying text appearance.

Overview of Features

Supported Escape Sequences:
Cursor movement: [H - Moves cursor to the home position (top-left corner). [x;yH - Moves cursor to position (x, y), where x and y are 1-based coordinates.
Screen clearing: [0J - Clears screen from the cursor down (ED0). [1J - Clears screen from the cursor up (ED1). [2J - Clears the entire screen (ED2).
Depth (Z-value) control: [3z - Sets the Z-value (depth) for subsequent text drawing operations only. This allows controlling the order of text rendering elements based on their depth. Higher Z-values are drawn behind lower Z-values. Note: This depth setting applies only to text and does not affect the depth of graphical elements. Example: [5z sets the text depth to 5 for future text operations.
Line clearing: [0K - Clears line from cursor to the right (EL0). [1K - Clears line from cursor to the left (EL1). [2K - Clears the entire line (EL2).
Text attributes and colors: [attr;fg;bgm - Sets text attributes, foreground color, and background color. Example: [1;37;40m - High brightness, white text on a black background. (attr: 0=Reset, 1=Bold/High intensity; fg=foreground color; bg=background color)
ANSI Standard Colors (Foreground and Background): [30m - Sets the foreground color to Black. [31m - Sets the foreground color to Red. [32m - Sets the foreground color to Green. [33m - Sets the foreground color to Yellow. [34m - Sets the foreground color to Blue. [35m - Sets the foreground color to Magenta (Purple). [36m - Sets the foreground color to Cyan. [37m - Sets the foreground color to White. [40m - Sets the background color to Black. [41m - Sets the background color to Red. [42m - Sets the background color to Green. [43m - Sets the background color to Yellow. [44m - Sets the background color to Blue. [45m - Sets the background color to Magenta (Purple). [46m - Sets the background color to Cyan. [47m - Sets the background color to White.
BEEP-8 Custom Colors (Foreground and Background): [50m - Sets the foreground color to BEEP-8 Black. [51m - Sets the foreground color to BEEP-8 Dark Blue. [52m - Sets the foreground color to BEEP-8 Dark Purple. [53m - Sets the foreground color to BEEP-8 Dark Green. [54m - Sets the foreground color to BEEP-8 Brown. [55m - Sets the foreground color to BEEP-8 Dark Grey. [56m - Sets the foreground color to BEEP-8 Light Grey. [57m - Sets the foreground color to BEEP-8 White. [58m - Sets the foreground color to BEEP-8 Red. [59m - Sets the foreground color to BEEP-8 Orange. [60m - Sets the foreground color to BEEP-8 Yellow. [61m - Sets the foreground color to BEEP-8 Green. [62m - Sets the foreground color to BEEP-8 Blue. [63m - Sets the foreground color to BEEP-8 Lavender. [64m - Sets the foreground color to BEEP-8 Pink. [65m - Sets the foreground color to BEEP-8 Light Peach. [70m - Sets the background color to BEEP-8 Black. [71m - Sets the background color to BEEP-8 Dark Blue. [72m - Sets the background color to BEEP-8 Dark Purple. [73m - Sets the background color to BEEP-8 Dark Green. [74m - Sets the background color to BEEP-8 Brown. [75m - Sets the background color to BEEP-8 Dark Grey. [76m - Sets the background color to BEEP-8 Light Grey. [77m - Sets the background color to BEEP-8 White. [78m - Sets the background color to BEEP-8 Red. [79m - Sets the background color to BEEP-8 Orange. [80m - Sets the background color to BEEP-8 Yellow. [81m - Sets the background color to BEEP-8 Green. [82m - Sets the background color to BEEP-8 Blue. [83m - Sets the background color to BEEP-8 Lavender. [84m - Sets the background color to BEEP-8 Pink. [85m - Sets the background color to BEEP-8 Light Peach.
Shadow control: [101m - Enables shadow effect. [100m - Disables shadow effect.
Custom palette selection: [nq - Selects palette n, where n is a value between 0 and 3.
Cursor visibility control: [> - Hides the cursor. [< - Shows the cursor.
Special cursor movement (custom sequences): [O - Custom escape sequence for cursor movement (defined in the code).
Delete: [~ - Deletes a character (DEL).

`CEscapeSeqDecoder` Class

The CEscapeSeqDecoder class contains an internal state machine that decodes escape sequences and outputs the resulting operation and parameters using the EscapeOut structure.

Sample Usage

Here is a comprehensive set of examples demonstrating the use of various escape sequences supported by this module:

#include "esc_decoder.h"
int main() {
    FILE* fp = stdout;
 
    // Cursor movement
    fprintf(fp, "\e[H");         // Move cursor to home (top-left)
    fprintf(fp, "\e[10;20H");    // Move cursor to position (10, 20)
 
    // Screen clearing
    fprintf(fp, "\e[2J");        // Clear the entire screen
    fprintf(fp, "\e[0J");        // Clear from cursor down
    fprintf(fp, "\e[1J");        // Clear from cursor up
 
    // Depth (Z-value) control
    fprintf(fp, "\e[5z");        // Set Z-value (depth) to 5
 
    // Line clearing
    fprintf(fp, "\e[2K");        // Clear entire line
    fprintf(fp, "\e[0K");        // Clear from cursor to right
    fprintf(fp, "\e[1K");        // Clear from cursor to left
 
    // Text attributes and colors
    fprintf(fp, "\e[1;37;40mBold white text on black background\n");
    fprintf(fp, "\e[0;33;41mYellow text on red background\n");
 
    // ANSI Standard Colors (Foreground and Background)
    fprintf(fp, "\e[31mRed foreground\n");
    fprintf(fp, "\e[44mBlue background\n");
    fprintf(fp, "\e[0mReset to default colors\n");
 
    // BEEP-8 Custom Colors (Foreground and Background)
    fprintf(fp, "\e[58;78mBEEP-8 Red foreground with BEEP-8 Red background\n");
    fprintf(fp, "\e[62;80mBEEP-8 Blue foreground with BEEP-8 Yellow background\n");
    fprintf(fp, "\e[0mReset to default colors\n");
    fprintf(fp, "\e[1;37;41mA_WHITE / A_RED\n");    // White text, red background
    fprintf(fp, "\e[1;30;47mA_BLACK / A_WHITE\n");  // Black text, white background
    fprintf(fp, "\e[1;31;40mA_RED / A_BLACK\n");    // Red text, black background
    fprintf(fp, "\e[1;32;44mA_GREEN / A_BLUE\n");   // Green text, blue background
    fprintf(fp, "\e[1;33;45mA_YELLOW / A_MAGENTA\n"); // Yellow text, magenta background
    fprintf(fp, "\e[1;34;43mA_BLUE / A_YELLOW\n");  // Blue text, yellow background
    fprintf(fp, "\e[1;35;42mA_MAGENTA / A_GREEN\n"); // Magenta text, green background
    fprintf(fp, "\e[1;36;46mA_CYAN / A_CYAN\n");    // Cyan text, cyan background
    fprintf(fp, "\e[1;90;41mA_BRIGHT_BLACK / A_RED\n"); // Bright black text, red background
    fprintf(fp, "\e[1;97;100mA_BRIGHT_WHITE / A_BRIGHT_BLACK\n"); // Bright white text, bright black background
 
    // Test combinations of foreground and background colors with shorthand notation
    fprintf(fp, "\e[57;72mWhite/Purple\n"); // Foreground: White, Background: Dark Purple
    fprintf(fp, "\e[59;73mOrange/Green\n"); // Foreground: Orange, Background: Dark Green
    fprintf(fp, "\e[60;74mYellow/Brown\n"); // Foreground: Yellow, Background: Brown
    fprintf(fp, "\e[61;75mGreen/DarkGrey\n"); // Foreground: Green, Background: Dark Grey
    fprintf(fp, "\e[62;76mBlue/LightGrey\n"); // Foreground: Blue, Background: Light Grey
    fprintf(fp, "\e[63;77mLavender/White\n"); // Foreground: Lavender, Background: White
    fprintf(fp, "\e[64;78mPink/Red\n"); // Foreground: Pink, Background: Red
    fprintf(fp, "\e[65;79mPeach/Orange\n"); // Foreground: Light Peach, Background: Orange
    fprintf(fp, "\e[50;71mBlack/Blue\n"); // Foreground: Black, Background: Dark Blue
    fprintf(fp, "\e[51;70mDarkBlue/Black\n"); // Foreground: Dark Blue, Background: Black
 
    // Shadow control
    fprintf(fp, "\e[101mShadow enabled\n");
    fprintf(fp, "\e[100mShadow disabled\n");
 
    // Custom palette selection
    fprintf(fp, "\e[2qSelected custom palette 2\n");
 
    // Cursor visibility control
    fprintf(fp, "\e[>Cursor hidden\n");
    fprintf(fp, "\e[<Cursor shown\n");
 
    // Special cursor movement
    fprintf(fp, "\e[OCustom cursor movement\n");
 
    // Delete character
    fprintf(fp, "\e[~Deleted character\n");
 
    return 0;
}

Escape Sequence Format

Cursor Movement: [x;yH moves the cursor to the specified position (x, y).
Screen and Line Clearing: Various J and K commands control clearing of the screen or lines.
Text Attributes: The m command modifies text attributes and colors (bold, foreground, background).

Detailed Description of `CEscapeSeqDecoder` Class

The CEscapeSeqDecoder class manages the decoding process through a state machine defined by the EscState enumeration. It tracks the current state of the decoder and processes each character in the escape sequence to determine the appropriate action. The parsed operations are stored in the EscapeOut structure.

State Machine Implementation: The Stream method processes each character and handles transition between states such as ES_0x1b (Escape), ES_0x5b (CSI), and other custom states for handling sequences like palette selection.
Color Handling: The decoder parses color codes in the format \e[attr;fg;bgm where:
- attr: Text attributes (e.g., 0=Reset, 1=Bold).
- fg: Foreground color (e.g., 37=White).
- bg: Background color (e.g., 44=Blue).
Cursor Movement: The decoder recognizes sequences like \e[x;yH for moving the cursor to a specific position.

Operations and Parameters (`EscapeOut`)

The EscapeOut structure stores the result of decoding an escape sequence:

_code: The last processed character.
_Ope: The operation determined by the escape sequence.
_fg: The foreground color.
_bg: The background color.
_x, _y: Cursor positions for movement commands.
_EscapePAL: The selected palette for custom palette handling.

Additional Helper Functions

EscClearEntireScreen: Clears the entire screen.
EscMoveCursor: Moves the cursor to a specific position (x, y).

Summary

This module provides a robust system for decoding and handling ANSI escape sequences in terminal environments. It supports cursor movement, text color and attribute manipulation, screen and line clearing, and custom palette selection. The state machine-based parser efficiently processes complex sequences and outputs the necessary operations in a structured format.

Version: 1.0

Date: 2024

Note: This module depends on the b8/type.h header for type definitions.

Enumeration Type Documentation

◆ AnsiColor

enum AnsiColor

Enumeration for ANSI color codes.

The AnsiColor enumeration defines the standard and high-intensity colors used in ANSI escape sequences. The values correspond to the codes used to set foreground and background colors in terminal environments.

◆ EscapePAL

enum EscapePAL

Enumeration for selecting a palette in the terminal.

The EscapePAL enumeration represents the available palettes that can be selected using escape sequences. The values range from PAL_0 to PAL_3, corresponding to different palettes in the system.

Enumerator
PAL_0	Palette 0.
PAL_1	Palette 1.
PAL_2	Palette 2.
PAL_3	Palette 3.

◆ EscapeSeqOpe

enum EscapeSeqOpe

Enumeration for escape sequence operations.

The EscapeSeqOpe enumeration defines the various operations that can be parsed and executed from escape sequences, such as moving the cursor, clearing the screen, or setting text colors and attributes.

Enumerator
ESO_ONE_CHAR	Processes a single character.
ESO_UP	Moves the cursor up.
ESO_DOWN	Moves the cursor down.
ESO_RIGHT	Moves the cursor right.
ESO_LEFT	Moves the cursor left.
ESO_DEL	Deletes a character.
ESO_MOVE_CURSOR	Moves the cursor to a specified position.
ESO_SEL_PAL	Selects a palette.
ESO_SET_COLOR	Sets the foreground and background color.
ESO_CLEAR_SCREEN_FROM_CURSOR_DOWN	Clears the screen from the cursor down.
ESO_CLEAR_SCREEN_FROM_CURSOR_UP	Clears the screen from the cursor up.
ESO_CLEAR_ENTIRE_SCREEN	Clears the entire screen.
ESO_CLEAR_LINE_FROM_CURSOR_RIGHT	Clears the line from the cursor to the right.
ESO_CLEAR_LINE_FROM_CURSOR_LEFT	Clears the line from the cursor to the left.
ESO_CLEAR_ENTIRE_LINE	Clears the entire line.
ESO_ENABLE_SHADOW	Enables the shadow effect.
ESO_DISABLE_SHADOW	Disables the shadow effect.
ESO_SET_Z	Sets the z value.
ESO_NONE	No operation.

Function Documentation

◆ EscClearEntireScreen()

void EscClearEntireScreen ( FILE * fp )

extern

Clears the entire screen.

This function sends an escape sequence to clear the entire screen in the terminal. It uses the \033[2J escape sequence to perform this operation.

Parameters

fp	A pointer to a FILE stream (typically stdout).

◆ EscMoveCursor()

void EscMoveCursor	(	FILE *	fp,
		s32	x_,
		s32	y_ )

extern

Moves the cursor to a specific position.

This function sends an escape sequence to move the cursor to a specific position in the terminal. It uses the \033[y;xH escape sequence where y and x are the row and column coordinates, respectively.