diff --git a/std/fmt/colors.ts b/std/fmt/colors.ts index c37f07d1bc..6c986711dc 100644 --- a/std/fmt/colors.ts +++ b/std/fmt/colors.ts @@ -29,7 +29,10 @@ interface Rgb { let enabled = !noColor; -/** Set changing text color to enabled or disabled */ +/** + * Set changing text color to enabled or disabled + * @param value + */ export function setColorEnabled(value: boolean): void { if (noColor) { return; @@ -38,11 +41,16 @@ export function setColorEnabled(value: boolean): void { enabled = value; } -/** Get wheather text color change is enabled or disabled. */ +/** Get whether text color change is enabled or disabled. */ export function getColorEnabled(): boolean { return enabled; } +/** + * Builds color code + * @param open + * @param close + */ function code(open: number[], close: number): Code { return { open: `\x1b[${open.join(";")}m`, @@ -51,236 +59,379 @@ function code(open: number[], close: number): Code { }; } +/** + * Applies color and background based on color code and its associated text + * @param str text to apply color settings to + * @param code color code to apply + */ function run(str: string, code: Code): string { return enabled ? `${code.open}${str.replace(code.regexp, code.open)}${code.close}` : str; } -/** Reset the text modified */ +/** + * Reset the text modified + * @param str text to reset + */ export function reset(str: string): string { return run(str, code([0], 0)); } -/** Make the text bold. */ +/** + * Make the text bold. + * @param str text to make bold + */ export function bold(str: string): string { return run(str, code([1], 22)); } -/** The text emits only a small amount of light. */ +/** + * The text emits only a small amount of light. + * @param str text to dim + */ export function dim(str: string): string { return run(str, code([2], 22)); } -/** Make the text italic. */ +/** + * Make the text italic. + * @param str text to make italic + */ export function italic(str: string): string { return run(str, code([3], 23)); } -/** Make the text underline. */ +/** + * Make the text underline. + * @param str text to underline + */ export function underline(str: string): string { return run(str, code([4], 24)); } -/** Invert background color and text color. */ +/** + * Invert background color and text color. + * @param str text to invert its color + */ export function inverse(str: string): string { return run(str, code([7], 27)); } -/** Make the text hidden. */ +/** + * Make the text hidden. + * @param str text to hide + */ export function hidden(str: string): string { return run(str, code([8], 28)); } -/** Put horizontal line throught the center of the text. */ +/** + * Put horizontal line through the center of the text. + * @param str text to strike through + */ export function strikethrough(str: string): string { return run(str, code([9], 29)); } -/** Set text color to black. */ +/** + * Set text color to black. + * @param str text to make black + */ export function black(str: string): string { return run(str, code([30], 39)); } -/** Set text color to red. */ +/** + * Set text color to red. + * @param str text to make red + */ export function red(str: string): string { return run(str, code([31], 39)); } -/** Set text color to green. */ +/** + * Set text color to green. + * @param str text to make green + */ export function green(str: string): string { return run(str, code([32], 39)); } -/** Set text color to yellow. */ +/** + * Set text color to yellow. + * @param str text to make yellow + */ export function yellow(str: string): string { return run(str, code([33], 39)); } -/** Set text color to blue. */ +/** + * Set text color to blue. + * @param str text to make blue + */ export function blue(str: string): string { return run(str, code([34], 39)); } -/** Set text color to magenta. */ +/** + * Set text color to magenta. + * @param str text to make magenta + */ export function magenta(str: string): string { return run(str, code([35], 39)); } -/** Set text color to cyan. */ +/** + * Set text color to cyan. + * @param str text to make cyan + */ export function cyan(str: string): string { return run(str, code([36], 39)); } -/** Set text color to white. */ +/** + * Set text color to white. + * @param str text to make white + */ export function white(str: string): string { return run(str, code([37], 39)); } -/** Set text color to gray. */ +/** + * Set text color to gray. + * @param str text to make gray + */ export function gray(str: string): string { return brightBlack(str); } -/** Set text color to bright black. */ +/** + * Set text color to bright black. + * @param str text to make bright-black + */ export function brightBlack(str: string): string { return run(str, code([90], 39)); } -/** Set text color to bright red. */ +/** + * Set text color to bright red. + * @param str text to make bright-red + */ export function brightRed(str: string): string { return run(str, code([91], 39)); } -/** Set text color to bright green. */ +/** + * Set text color to bright green. + * @param str text to make bright-green + */ export function brightGreen(str: string): string { return run(str, code([92], 39)); } -/** Set text color to bright yellow. */ +/** + * Set text color to bright yellow. + * @param str text to make bright-yellow + */ export function brightYellow(str: string): string { return run(str, code([93], 39)); } -/** Set text color to bright blue. */ +/** + * Set text color to bright blue. + * @param str text to make bright-blue + */ export function brightBlue(str: string): string { return run(str, code([94], 39)); } -/** Set text color to bright magenta. */ +/** + * Set text color to bright magenta. + * @param str text to make bright-magenta + */ export function brightMagenta(str: string): string { return run(str, code([95], 39)); } -/** Set text color to bright cyan. */ +/** + * Set text color to bright cyan. + * @param str text to make bright-cyan + */ export function brightCyan(str: string): string { return run(str, code([96], 39)); } -/** Set text color to bright white. */ +/** + * Set text color to bright white. + * @param str text to make bright-white + */ export function brightWhite(str: string): string { return run(str, code([97], 39)); } -/** Set background color to black. */ +/** + * Set background color to black. + * @param str text to make its background black + */ export function bgBlack(str: string): string { return run(str, code([40], 49)); } -/** Set background color to red. */ +/** + * Set background color to red. + * @param str text to make its background red + */ export function bgRed(str: string): string { return run(str, code([41], 49)); } -/** Set background color to green. */ +/** + * Set background color to green. + * @param str text to make its background green + */ export function bgGreen(str: string): string { return run(str, code([42], 49)); } -/** Set background color to yellow. */ +/** + * Set background color to yellow. + * @param str text to make its background yellow + */ export function bgYellow(str: string): string { return run(str, code([43], 49)); } -/** Set background color to blue. */ +/** + * Set background color to blue. + * @param str text to make its background blue + */ export function bgBlue(str: string): string { return run(str, code([44], 49)); } -/** Set background color to magenta. */ +/** + * Set background color to magenta. + * @param str text to make its background magenta + */ export function bgMagenta(str: string): string { return run(str, code([45], 49)); } -/** Set background color to cyan. */ +/** + * Set background color to cyan. + * @param str text to make its background cyan + */ export function bgCyan(str: string): string { return run(str, code([46], 49)); } -/** Set background color to white. */ +/** + * Set background color to white. + * @param str text to make its background white + */ export function bgWhite(str: string): string { return run(str, code([47], 49)); } -/** Set background color to bright black. */ +/** + * Set background color to bright black. + * @param str text to make its background bright-black + */ export function bgBrightBlack(str: string): string { return run(str, code([100], 49)); } -/** Set background color to bright red. */ +/** + * Set background color to bright red. + * @param str text to make its background bright-red + */ export function bgBrightRed(str: string): string { return run(str, code([101], 49)); } -/** Set background color to bright green. */ +/** + * Set background color to bright green. + * @param str text to make its background bright-green + */ export function bgBrightGreen(str: string): string { return run(str, code([102], 49)); } -/** Set background color to bright yellow. */ +/** + * Set background color to bright yellow. + * @param str text to make its background bright-yellow + */ export function bgBrightYellow(str: string): string { return run(str, code([103], 49)); } -/** Set background color to bright blue. */ +/** + * Set background color to bright blue. + * @param str text to make its background bright-blue + */ export function bgBrightBlue(str: string): string { return run(str, code([104], 49)); } -/** Set background color to bright magenta. */ +/** + * Set background color to bright magenta. + * @param str text to make its background bright-magenta + */ export function bgBrightMagenta(str: string): string { return run(str, code([105], 49)); } -/** Set background color to bright cyan. */ +/** + * Set background color to bright cyan. + * @param str text to make its background bright-cyan + */ export function bgBrightCyan(str: string): string { return run(str, code([106], 49)); } -/** Set background color to bright white. */ +/** + * Set background color to bright white. + * @param str text to make its background bright-white + */ export function bgBrightWhite(str: string): string { return run(str, code([107], 49)); } /* Special Color Sequences */ +/** + * Clam and truncate color codes + * @param n + * @param max number to truncate to + * @param min number to truncate from + */ function clampAndTruncate(n: number, max = 255, min = 0): number { return Math.trunc(Math.max(Math.min(n, max), min)); } -/** Set text color using paletted 8bit colors. - * https://en.wikipedia.org/wiki/ANSI_escape_code#8-bit */ +/** + * Set text color using paletted 8bit colors. + * https://en.wikipedia.org/wiki/ANSI_escape_code#8-bit + * @param str text color to apply paletted 8bit colors to + * @param color code + */ export function rgb8(str: string, color: number): string { return run(str, code([38, 5, clampAndTruncate(color)], 39)); } -/** Set background color using paletted 8bit colors. - * https://en.wikipedia.org/wiki/ANSI_escape_code#8-bit */ +/** + * Set background color using paletted 8bit colors. + * https://en.wikipedia.org/wiki/ANSI_escape_code#8-bit + * @param str text color to apply paletted 8bit background colors to + * @param color code + */ export function bgRgb8(str: string, color: number): string { return run(str, code([48, 5, clampAndTruncate(color)], 49)); } -/** Set text color using 24bit rgb. +/** + * Set text color using 24bit rgb. * `color` can be a number in range `0x000000` to `0xffffff` or * an `Rgb`. * @@ -288,6 +439,8 @@ export function bgRgb8(str: string, color: number): string { * * rgba24("foo", 0xff00ff); * rgba24("foo", {r: 255, g: 0, b: 255}); + * @param str text color to apply 24bit rgb to + * @param color code */ export function rgb24(str: string, color: number | Rgb): string { if (typeof color === "number") { @@ -314,7 +467,8 @@ export function rgb24(str: string, color: number | Rgb): string { ); } -/** Set background color using 24bit rgb. +/** + * Set background color using 24bit rgb. * `color` can be a number in range `0x000000` to `0xffffff` or * an `Rgb`. * @@ -322,6 +476,8 @@ export function rgb24(str: string, color: number | Rgb): string { * * bgRgba24("foo", 0xff00ff); * bgRgba24("foo", {r: 255, g: 0, b: 255}); + * @param str text color to apply 24bit rgb to + * @param color code */ export function bgRgb24(str: string, color: number | Rgb): string { if (typeof color === "number") { @@ -357,7 +513,10 @@ const ANSI_PATTERN = new RegExp( "g", ); -/** Remove ANSI escape codes from the string. */ +/** + * Remove ANSI escape codes from the string. + * @param string to remove ANSI escape codes from + */ export function stripColor(string: string): string { return string.replace(ANSI_PATTERN, ""); } diff --git a/std/fmt/printf.ts b/std/fmt/printf.ts index c4c8c8e5c9..27d4acca94 100644 --- a/std/fmt/printf.ts +++ b/std/fmt/printf.ts @@ -1,7 +1,7 @@ // Copyright 2018-2020 the Deno authors. All rights reserved. MIT license. -// -// This implementation is inspired by POSIX and Golang but does not port -// implementation code. +/** + * This implementation is inspired by POSIX and Golang but does not port + * implementation code. */ enum State { PASSTHROUGH, @@ -169,6 +169,10 @@ class Printf { } } + /** + * Handle width or precision + * @param wOrP + */ handleWidthOrPrecisionRef(wOrP: WorP): void { if (this.argNum >= this.args.length) { // handle Positional should have already taken care of it... @@ -191,6 +195,10 @@ class Printf { this.argNum++; } + /** + * Handle width and precision + * @param flags + */ handleWidthAndPrecision(flags: Flags): void { const fmt = this.format; for (; this.i !== this.format.length; ++this.i) { @@ -245,6 +253,7 @@ class Printf { } } + /** Handle positional */ handlePositional(): void { if (this.format[this.i] !== "[") { // sanity only @@ -277,6 +286,7 @@ class Printf { return; } + /** Handle less than */ handleLessThan(): string { // deno-lint-ignore no-explicit-any const arg = this.args[this.argNum] as any; @@ -291,6 +301,7 @@ class Printf { return str + " ]"; } + /** Handle verb */ handleVerb(): void { const verb = this.format[this.i]; this.verb = verb; @@ -356,6 +367,10 @@ class Printf { } } + /** + * Pad a string + * @param s text to pad + */ pad(s: string): string { const padding = this.flags.zero ? "0" : " "; @@ -365,6 +380,12 @@ class Printf { return s.padStart(this.flags.width, padding); } + + /** + * Pad a number + * @param nStr + * @param neg + */ padNum(nStr: string, neg: boolean): string { let sign: string; if (neg) { @@ -397,6 +418,12 @@ class Printf { return nStr; } + /** + * Format a number + * @param n + * @param radix + * @param upcase + */ fmtNumber(n: number, radix: number, upcase = false): string { let num = Math.abs(n).toString(radix); const prec = this.flags.precision; @@ -432,6 +459,10 @@ class Printf { return this.padNum(num, n < 0); } + /** + * Format number with code points + * @param n + */ fmtNumberCodePoint(n: number): string { let s = ""; try { @@ -442,6 +473,10 @@ class Printf { return this.pad(s); } + /** + * Format special float + * @param n + */ fmtFloatSpecial(n: number): string { // formatting of NaN and Inf are pants-on-head // stupid and more or less arbitrary. @@ -462,6 +497,11 @@ class Printf { return ""; } + /** + * Round fraction to precision + * @param fractional + * @param precision + */ roundFractionToPrecision(fractional: string, precision: number): string { if (fractional.length > precision) { fractional = "1" + fractional; // prepend a 1 in case of leading 0 @@ -477,6 +517,11 @@ class Printf { return fractional; } + /** + * Format float E + * @param n + * @param upcase + */ fmtFloatE(n: number, upcase = false): string { const special = this.fmtFloatSpecial(n); if (special !== "") { @@ -504,6 +549,10 @@ class Printf { return this.padNum(val, n < 0); } + /** + * Format float F + * @param n + */ fmtFloatF(n: number): string { const special = this.fmtFloatSpecial(n); if (special !== "") { @@ -548,6 +597,11 @@ class Printf { return this.padNum(`${dig}.${fractional}`, n < 0); } + /** + * Format float G + * @param n + * @param upcase + */ fmtFloatG(n: number, upcase = false): string { const special = this.fmtFloatSpecial(n); if (special !== "") { @@ -605,6 +659,10 @@ class Printf { return nStr; } + /** + * Format string + * @param s + */ fmtString(s: string): string { if (this.flags.precision !== -1) { s = s.substr(0, this.flags.precision); @@ -612,6 +670,11 @@ class Printf { return this.pad(s); } + /** + * Format hex + * @param val + * @param upper + */ fmtHex(val: string | number, upper = false): string { // allow others types ? switch (typeof val) { @@ -644,6 +707,10 @@ class Printf { } } + /** + * Format value + * @param val + */ fmtV(val: Record): string { if (this.flags.sharp) { const options = this.flags.precision !== -1 @@ -656,6 +723,10 @@ class Printf { } } + /** + * Format JSON + * @param val + */ fmtJ(val: unknown): string { return JSON.stringify(val); } @@ -664,6 +735,9 @@ class Printf { /** * Converts and format a variable number of `args` as is specified by `format`. * `sprintf` returns the formatted string. + * + * @param format + * @param args */ export function sprintf(format: string, ...args: unknown[]): string { const printf = new Printf(format, ...args); @@ -673,6 +747,8 @@ export function sprintf(format: string, ...args: unknown[]): string { /** * Converts and format a variable number of `args` as is specified by `format`. * `printf` writes the formatted string to standard output. + * @param format + * @param args */ export function printf(format: string, ...args: unknown[]): void { const s = sprintf(format, ...args);