npm package: @haydenhigg/pastel
Description: A lightweight package to simplify complex terminal coloring.
Author: Hayden Higginbotham
Latest version: 1.0.4

# @haydenhigg/pastel

A small library for simplifying terminal coloring in NodeJS (but this one uses templating for succinct and powerful effects).

## Usage

There are a few ways to use this package. You can use the escape characters directly:

```javascript
const pastel = require("@haydenhigg/pastel");

console.log(pastel.meta.bold + pastel.meta.italic + pastel.bg.green + pastel.fg.red + "Hello world!" + pastel.meta.reset); // red, bold, and italic on green background
```

but that's not recommended (unless you want to create multi-line effects without a reset). Even easier is to use the `convert` function:

```javascript
console.log(pastel.convert("Hello world!", { color: "red", background: "green", decoration: ["bold", "italic"] }));
```

Sometimes that might be a litte more than you need, though. In that case, just use some of the shortened helper functions:

```javascript
console.log(pastel.red("Hello world!")); // of course these can be use within each-other...
console.log(pastel.bold(pastel.italic(pastel.greenBackground(pastel.red("Hello world!")))));
```

Are these not expressive enough for you? There is also a `parse` function:

```javascript
console.log(pastel.parse("*$<gn>rdHello world^!$*")); // the same as all of the other examples!
```

The syntax for this is short and sweet, and the actual function is quite powerful, so the strings it takes in can look quite obscure. To break it down quickly:

```javascript
// these characters go around the text to be altered, and they don't touch the rest of the string or interfere with other effects
'*some text*' // bold
'$some text$' // italic
'_some text_' // underline
'!some text!' // blink

// these characters are meant to be used alone, without a matching character
'>color' // sets color to 'color', where 'color' is a 2-letter code of the possible colors (the first and last letter, like 'rd' for red or "ma" for magenta)
'<color' // sets background color to 'color', see above for limits on what 'color' must be
'|' // a manual reset character (pastel.meta.reset), but it's almost never necessary (the other characters use their own reset characters internally)

// the escape character
'^' // used if you want to use a control character (*, $, _, !, >, <, |, ^) in the string. you have to escape this character to use it in a string as well
```

All of this means that we can get complex combinations with far less typing:

```javascript
console.log(pastel.parse(">rd_!This! is red $and$ underlined *($and$ bold)*.>bk This is black $and$ underlined^!_"));

// is the same as

console.log(
    pastel.convert("This", { color: "red", decoration: ["blink", "underline"] }) +
    pastel.convert(" is red ", { color: "red", decoration: ["underline"] }) +
    pastel.convert("and", { color: "red", decoration: ["italic", "underline"] }) +
    pastel.convert(" underlined ", { color: "red", decoration: ["underline"] }) +
    pastel.convert("(", { color: "red", decoration: ["bold", "underline"] }) +
    pastel.convert("and", { color: "red", decoration: ["bold", "italic", "underline"] }) +
    pastel.convert(" bold)", { color: "red", decoration: ["bold", "underline"] }) +
    pastel.convert(".", { color: "red", decoration: ["underline"] }) +
    pastel.convert(" This is black ", { color: "black", decoration: ["underline"] }) +
    pastel.convert("and", { color: "black", decoration: ["italic", "underline"] }) +
    pastel.convert(" underlined!", { color: "black", decoration: ["underline"] }));
```

## Other functions

- There are shorthand functions for `rainbow` and `rainbowBackground` -styled text, and those are valid options for `convert` too.
- There are shorthand functions for `success`, `warning`, and `error` that provide the expected functionality, and you can provide your own label if you want (`success(message, label)` = `label: message`, `success(message) = `success: message`).