diff --git a/packages/parser/README.md b/packages/parser/README.md new file mode 100644 index 0000000..9abc9fd --- /dev/null +++ b/packages/parser/README.md @@ -0,0 +1,3 @@ +# `@ansi-escape-code/parser` + +Utilities for parsing strings that contain ANSI escape sequences. diff --git a/packages/parser/src/index.ts b/packages/parser/src/index.ts index 969bbfd..a0c770a 100644 --- a/packages/parser/src/index.ts +++ b/packages/parser/src/index.ts @@ -1,5 +1,6 @@ import { AnsiColor, AnsiString } from "@ansi-escape-code/type"; +/** Options controlling how ANSI strings are parsed. */ export interface ParseAnsiStringOptions { flags?: number; underlineColor?: AnsiColor; @@ -7,6 +8,7 @@ export interface ParseAnsiStringOptions { backgroundColor?: AnsiColor; } +/** Successful result returned from {@link parseAnsiString}. */ export interface ParseAnsiStringResultOk { success: true; ansiString: AnsiString[]; @@ -16,6 +18,7 @@ export interface ParseAnsiStringResultOk { remainBackgroundColor: AnsiColor; } +/** Error result returned from {@link parseAnsiString}. */ export interface ParseAnsiStringResultError { success: false; error: "unclosed-escape-sequence" | ParseAnsiStringFlagsResultError["error"]; @@ -25,6 +28,9 @@ export type ParseAnsiStringResult = | ParseAnsiStringResultOk | ParseAnsiStringResultError; +/** + * Parses a string containing ANSI escape sequences. + */ export function parseAnsiString( input: string, { @@ -100,6 +106,7 @@ export function parseAnsiString( }; } +/** Successful result returned from {@link parseAnsiStringFlags}. */ export interface ParseAnsiStringFlagsResultOk { success: true; flags: number; @@ -108,6 +115,7 @@ export interface ParseAnsiStringFlagsResultOk { backgroundColor: AnsiColor; } +/** Error result returned from {@link parseAnsiStringFlags}. */ export interface ParseAnsiStringFlagsResultError { success: false; error: "invalid-flags"; @@ -117,6 +125,9 @@ export type ParseAnsiStringFlagsResult = | ParseAnsiStringFlagsResultOk | ParseAnsiStringFlagsResultError; +/** + * Parses an array of numeric SGR codes. + */ export function parseAnsiStringFlags( input: number[], { diff --git a/packages/type/README.md b/packages/type/README.md new file mode 100644 index 0000000..9abd14f --- /dev/null +++ b/packages/type/README.md @@ -0,0 +1,3 @@ +# `@ansi-escape-code/type` + +Type definitions used across the ansi-escape-code packages. diff --git a/packages/type/src/index.ts b/packages/type/src/index.ts index 3d0ff13..67b1a8c 100644 --- a/packages/type/src/index.ts +++ b/packages/type/src/index.ts @@ -43,6 +43,9 @@ export class AnsiString { static readonly UNKNOWN_BIT = 16384; // 1 << 14 + /** + * Creates a new {@link AnsiString} instance. + */ constructor( public readonly content: string, public readonly attributeFlags: number, diff --git a/src/NoopAnsi.ts b/src/NoopAnsi.ts index 7231d45..4f59480 100644 --- a/src/NoopAnsi.ts +++ b/src/NoopAnsi.ts @@ -1,9 +1,20 @@ import { AnsiOptions, AnsiPart, Ansi as DefaultAnsi } from "."; +/** + * Variant of {@link DefaultAnsi} that ignores all styling and simply + * concatenates the contained parts. + */ export class NoopAnsi extends DefaultAnsi { + /** + * @param _unusedOptions - Ignored styling options. + * @param parts - Content parts to combine. + */ constructor(_unusedOptions: Partial, ...parts: AnsiPart[]) { super({}, ...parts); } + /** + * Renders contained parts without escape sequences. + */ public toString(_unusedResolvedOuterOptions?: AnsiOptions): string { return NoopAnsi.toStringInternal(this.parts); diff --git a/src/index.ts b/src/index.ts index 4dac421..d0c01a7 100644 --- a/src/index.ts +++ b/src/index.ts @@ -1,7 +1,12 @@ import type { AnsiColor } from "@ansi-escape-code/type"; +/** + * Union of parts that can make up an ANSI string. A part can be another + * {@link Ansi} instance or any object with a `toString()` method. + */ export type AnsiPart = Ansi | { toString(): string }; +/** Options describing how text should be styled. */ export interface AnsiOptions { weight: "normal" | "bold" | "dim"; italic: boolean; @@ -15,11 +20,20 @@ export interface AnsiOptions { backgroundColor: AnsiColor; } +/** + * Template tag used to produce nested {@link Ansi} instances. + * + * @param strings - Raw template string segments. + * @param values - Interpolated values to embed. + */ export type AnsiTemplateTag = ( strings: TemplateStringsArray, ...values: readonly AnsiPart[] ) => Ansi; +/** + * Represents a styled string that can contain nested {@link Ansi} parts. + */ export class Ansi { public static readonly defaultOptions: AnsiOptions = { weight: "normal", @@ -36,6 +50,12 @@ export class Ansi { public readonly parts: AnsiPart[]; + /** + * Creates a new instance. + * + * @param options - Styling options to apply to the contents. + * @param parts - Parts that make up the styled output. + */ constructor( public readonly options: Partial, ...parts: AnsiPart[] @@ -43,6 +63,11 @@ export class Ansi { this.parts = parts; } + /** + * Renders this instance and all nested parts to a string. + * + * @param resolvedOuterOptions - Active options of the parent context. + */ public toString( resolvedOuterOptions: AnsiOptions = Ansi.defaultOptions ): string { @@ -236,10 +261,20 @@ export class Ansi { return [5, 16 + r * 36 + g * 6 + b]; } + /** + * Creates a 24 bit true color value. + * + * @param r - Red component (0-255) + * @param g - Green component (0-255) + * @param b - Blue component (0-255) + */ public static TRUE_COLOR(r: number, g: number, b: number): AnsiColor { return [2, r, g, b]; } + /** + * Returns a template tag preconfigured with the provided options. + */ public static tt(oprions: Partial): AnsiTemplateTag { const options = (oprions ?? {}) as Partial; return (strings: TemplateStringsArray, ...values: AnsiPart[]) => { @@ -249,6 +284,9 @@ export class Ansi { } } +/** + * Interleaves template string segments with their interpolated values. + */ function interleave( strings: TemplateStringsArray, values: readonly AnsiPart[]