Skip to content

0.1.0v

Latest
Latest
Compare
Choose a tag to compare
@tornikegomareli tornikegomareli released this 06 Oct 14:03
· 26 commits to main since this release
0.1.0
4444637

Release Notes Summary

General Overview

The ANSIKeyboard.swift file serves as a robust utility set for managing keyboard inputs in ANSI-compatible terminal environments. It offers support for non-printable ASCII characters, ANSI key codes, and ANSI meta codes.

Technical Details

  • NonPrintableChar Enum: Enumerates non-printable ASCII characters such as null, bell, backspace, etc.
  • ANSIKeyCode Enum: Enumerates ANSI key codes for various keyboard actions like up, down, left, right, function keys, etc.
  • ANSIMetaCode Enum: Enumerates ANSI meta codes for control, shift, and alt keys.
  • Public Functions: Includes isNonPrintable(), readKey(), and more to check character types and read key inputs.
  • Private Functions: Includes internal utilities like CSILetter(), SS3Letter(), etc., for internal mapping.

Functions:

  • isNonPrintable(char: Character) -> Bool: Checks if a character is non-printable.
  • readKey() -> (code: ANSIKeyCode, meta: [ANSIMetaCode]): Reads a key press and returns its ANSI key code and meta codes.

ANSIAttribute.swift

The ANSIAttribute.swift file provides comprehensive utilities for text styling and coloring in ANSI-compatible terminal environments. It offers a rich set of enums and functions to manage text attributes effectively. The suite also includes ANSIAttributeState.swift and ANSIAttributeUtilities.swift for state management and utility functions.

Technical Details

File: ANSIAttribute.swift

  • ANSIAttr Enum: Enumerates various ANSI attributes for text styling and coloring.
    • Text Styling: Includes styles like normal, bold, dim, italic, underline, etc.
    • Foreground Text Coloring: Offers text colors like black, red, green, blue, etc.
    • Background Text Coloring: Provides background colors like onBlack, onRed, etc.

File: ANSIAttributeState.swift

  • Internal Variables: isOpenedColor and isOpenedStyle for tracking the state of text attributes.

File: ANSIAttributeUtilities.swift

  • Public Functions: Offers functions like setStyle(), setColor(), setDefault() for applying text attributes.
  • Utility Functions: Includes utility functions to validate styles and colors.

Functions:

  • setStyle(_ style: ANSIAttr = .normal): Sets the text style.
  • isStyle(_ style: UInt8) -> Bool: Validates if a given value is a valid ANSI text style.
  • setColor(fore: ANSIAttr = .default, back: ANSIAttr = .onDefault): Sets foreground and background colors.
  • setDefault(color: Bool = true, style: Bool = false): Resets text attributes to default.
  • stripAttributes(from text: String) -> String: Removes all ANSI attributes from a text string.

ANSIScreen.swift

The ANSIScreen.swift file is designed to provide a collection of utilities for interacting with terminal screens compatible with ANSI escape codes. This file offers functionalities like cursor management, screen clearing, line manipulation, and terminal modes.

Technical Details

Variables

  • isReplacingMode: Indicates if the terminal is in replacing mode.
  • isCursorVisible: Indicates if the cursor is visible.

Enums

  • CursorStyle: Defines various cursor styles (block, line, bar).

Functions

  • setCursorStyle(_ style: CursorStyle, blinking: Bool = true): Sets the style and blinking state of the cursor.
  • storeCursorPosition(isANSI: Bool): Stores the current cursor position.
  • restoreCursorPosition(isANSI: Bool): Restores the cursor to its previously stored position.
  • clearBelow(): Clears the terminal screen below the cursor.
  • clearAbove(): Clears the terminal screen above the cursor.
  • clearScreen(): Clears the entire terminal screen.
  • clearToEndOfLine(): Clears from the cursor to the end of the line.
  • clearToStartOfLine(): Clears from the cursor to the start of the line.
  • clearLine(): Clears the entire line the cursor is on.
  • moveUp(_ row: Int = 1): Moves the cursor up by a given number of rows.
  • moveDown(_ row: Int = 1): Moves the cursor down by a given number of rows.
  • moveRight(_ col: Int = 1): Moves the cursor right by a given number of columns.
  • moveLeft(_ col: Int = 1): Moves the cursor left by a given number of columns.
  • moveTo(_ row: Int, _ col: Int): Moves the cursor to a specified row and column.
  • insertLine(_ row: Int = 1): Inserts a new line at the cursor position.
  • deleteLine(_ row: Int = 1): Deletes a line at the cursor position.
  • deleteChar(_ char: Int = 1): Deletes characters starting from the cursor position.
  • enableReplaceMode(): Enables replace mode in the terminal.
  • disableReplaceMode(): Disables replace mode in the terminal.
  • cursorOff(): Hides the cursor.
  • cursorOn(): Shows the cursor.
  • scrollRegion(top: Int, bottom: Int): Sets the scrolling region of the terminal.
  • readCursorPos() -> (row: Int, col: Int): Reads the current position of the cursor.
  • readScreenSize() -> (row: Int, col: Int): Reads the size of the terminal screen.

Platform Specifics

  • The functions for storing and restoring cursor positions have macOS-specific implementations, toggled by the isANSI flag.

ANSITerminal.swift

The ANSITerminal.swift file provides a set of utilities for terminal interactions, including ANSI escape codes, terminal settings, and buffer management.

Technical Details

Constants

  • Escape Codes: Definitions for escape characters (ESC, SS2, SS3, DCS, CSI, OSC).
  • Special Characters: Custom Unicode characters (RPT, LPT, RPA, LPA).

Variables

  • defaultTerminal: Holds the default terminal settings.
  • isNonBlockingMode: Indicates if the terminal is in non-blocking mode.

Functions

  • Utility Functions:

    • delay(_ ms: Int): Introduces a delay.
    • unicode(_ code: Int) -> Unicode.Scalar: Converts an integer to a Unicode character.
    • clearBuffer(isOut: Bool, isIn: Bool): Clears input/output buffers.

  • Terminal Mode Functions:

    • disableNonBlockingTerminal(): Restores default terminal settings.
    • enableNonBlockingTerminal(rawMode: Bool): Enables non-blocking terminal mode.

  • Key & Buffer Functions:

    • keyPressed() -> Bool: Checks if a key is pressed.
    • readChar() -> Character: Reads a character from stdin.
    • readCode() -> Int: Reads an ASCII code from stdin.
    • ansiRequest(_ command: String, endChar: Character) -> String: Sends a request to the terminal and reads the response.

  • Writing Functions:

    • write(_ text: String..., suspend: Int = 0): Writes text to stdout.
    • writeln(_ text: String..., suspend: Int = 0): Writes text followed by a new line to stdout.
    • writeAt(_ row: Int, _ col: Int, _ text: String..., suspend: Int = 0): Writes text at a specified row and column.
    • ask(_ q: String, cleanUp: Bool = false) -> String: Prompts the user with a question and returns the answer.

Platform Specifics

  • The file is compatible with both Linux (Glibc) and macOS (Darwin).
  • Terminal mode functions and ANSI request functions account for the non-blocking mode.
Assets 2