1
0
Fork 0
mirror of https://github.com/denoland/deno.git synced 2024-11-29 16:30:56 -05:00

docs(std/fmt): add JSDoc (#8278)

This commit is contained in:
Mo 2020-11-07 16:05:37 +02:00 committed by GitHub
parent 3bb5257e6d
commit bb1a673b21
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 288 additions and 53 deletions

View file

@ -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, "");
}

View file

@ -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, unknown>): 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);