1 | # ansi-fragments
|
2 |
|
3 | [![Version][version]][package]
|
4 |
|
5 | [![PRs Welcome][prs-welcome-badge]][prs-welcome]
|
6 | [![MIT License][license-badge]][license]
|
7 | [![Chat][chat-badge]][chat]
|
8 | [![Code of Conduct][coc-badge]][coc]
|
9 |
|
10 | A tiny library with builders to help making logs/CLI pretty with a nice DX.
|
11 |
|
12 | - [ansi-fragments](#ansi-fragments)
|
13 | - [Installation](#installation)
|
14 | - [Usage](#usage)
|
15 | - [API](#api)
|
16 | - [`color`](#color)
|
17 | - [`modifier`](#modifier)
|
18 | - [`container`](#container)
|
19 | - [`pad`](#pad)
|
20 | - [`fixed`](#fixed)
|
21 | - [`ifElse`](#ifElse)
|
22 | - [`provide`](#provide)
|
23 |
|
24 | ## Installation
|
25 |
|
26 | ```bash
|
27 | yarn add ansi-fragments
|
28 | ```
|
29 |
|
30 | ## Usage
|
31 |
|
32 | ```js
|
33 | import { color, modifier, pad, container } from 'ansi-fragments';
|
34 |
|
35 | const prettyLog = (level, message) => container(
|
36 | color('green', modifier('italic', level)),
|
37 | pad(1),
|
38 | message
|
39 | ).build();
|
40 |
|
41 | console.log(prettyLog('success', 'Yay!'));
|
42 | ```
|
43 |
|
44 | ## API
|
45 |
|
46 | Each fragment implements `IFragment` interface:
|
47 |
|
48 | ```ts
|
49 | interface IFragment {
|
50 | build(): string;
|
51 | }
|
52 | ```
|
53 |
|
54 | The `build` method is responsible for traversing the tree of fragments and create a string representation with ANSI escape codes.
|
55 |
|
56 |
|
57 | #### `color`
|
58 |
|
59 | ```ts
|
60 | color(
|
61 | ansiColor: AnsiColor,
|
62 | ...children: Array<string | IFragment>
|
63 | ): IFragment
|
64 | ```
|
65 |
|
66 | Creates fragment for standard ANSI [colors](./src/fragments/Color.ts).
|
67 |
|
68 | ```js
|
69 | color('red', 'Oh no');
|
70 | color('bgBlue', color('brightBlue', 'Hey'));
|
71 | color('green', modifier('bold', 'Sup!'));
|
72 | ```
|
73 |
|
74 | #### `modifier`
|
75 |
|
76 | ```ts
|
77 | modifier(
|
78 | ansiModifier: AnsiModifier,
|
79 | ...children: Array<string | IFragment>
|
80 | ): IFragment
|
81 | ```
|
82 |
|
83 | Creates fragment for standard ANSI [modifiers](./src/fragments/Modifier.ts): `dim`, `bold`, `hidden`, `italic`, `underline`, `strikethrough`.
|
84 |
|
85 | ```js
|
86 | modifier('underline', 'Hello', 'World');
|
87 | modifier('italic', modifier('bold', 'Hey'));
|
88 | modifier('bold', color('green', 'Sup!'));
|
89 | ```
|
90 |
|
91 | #### `container`
|
92 |
|
93 | ```ts
|
94 | container(...children: Array<string | IFragment>): IFragment
|
95 | ```
|
96 |
|
97 | Creates fragment, which sole purpose is to hold and build nested fragments.
|
98 |
|
99 | ```js
|
100 | container(
|
101 | color('gray', '[08/01/18 12:00]'),
|
102 | pad(1),
|
103 | color('green', 'success'),
|
104 | pad(1),
|
105 | 'Some message'
|
106 | )
|
107 | ```
|
108 |
|
109 | #### `pad`
|
110 |
|
111 | ```ts
|
112 | pad(count: number, separator?: string): IFragment
|
113 | ```
|
114 |
|
115 | Creates fragment, which repeats given separator (default: ` `) given number of times.
|
116 |
|
117 | ```js
|
118 | pad(1);
|
119 | pad(2, '#')
|
120 | pad(1, '\n')
|
121 | ```
|
122 |
|
123 | #### `fixed`
|
124 |
|
125 | ```ts
|
126 | fixed(
|
127 | value: number,
|
128 | bias: 'start' | 'end',
|
129 | ...children: Array<string | IFragment>
|
130 | ): IFragment
|
131 | ```
|
132 |
|
133 | Creates fragment, which makes sure the children will always build to given number of non-ANSI characters. It will either trim the results or add necessary amount of spaces. The `bias` control if trimming/padding should be done at the start of the string representing built children or at the end.
|
134 |
|
135 | ```js
|
136 | fixed(5, 'start', 'ERR'); // => ' ERR'
|
137 | fixed(8, 'end', color('green', 'success')); // equals to color('green', 'success') + ' '
|
138 | fixed(10, 'end', 'Hello', pad(2), 'World') // => 'Hello Wor'
|
139 | ```
|
140 |
|
141 | #### `ifElse`
|
142 |
|
143 | ```ts
|
144 | ifElse(
|
145 | condition: Condition,
|
146 | ifTrueFragment: string | IFragment,
|
147 | elseFragment: string | IFragment
|
148 | ): IFragment
|
149 |
|
150 | type ConditionValue = boolean | string | number | null | undefined;
|
151 | type Condition = ConditionValue | (() => ConditionValue);
|
152 | ```
|
153 |
|
154 | Change the output based on condition. Condition can ba a primitive value, which can be casted to boolean or a function. If conation or return value of condition is evaluated to `true`, the first argument - `ifTrueFragment` will be used, otherwise `elseFragment`.
|
155 |
|
156 | ```js
|
157 | let condition = getConditionValue()
|
158 | ifElse(
|
159 | () => condition,
|
160 | color('red', 'ERROR'),
|
161 | color('yellow', 'WARNING')
|
162 | )
|
163 | ```
|
164 |
|
165 | #### `provide`
|
166 |
|
167 | ```ts
|
168 | provide<T>(
|
169 | value: T,
|
170 | builder: (value: T) => string | IFragment
|
171 | ): IFragment
|
172 | ```
|
173 |
|
174 | Provides given value to a builder function, which should return `string` or fragment. Useful in situations when the output is connected with some calculated value - using `provide` you only need to calculate final value once and forward it to custom styling logic.
|
175 |
|
176 | ```js
|
177 | provide(getMessageFromSomewhere(), value => {
|
178 | switch (value.level) {
|
179 | case 'error':
|
180 | return container(
|
181 | color('red', modifier('bold', value.level.toUpperCase())),
|
182 | pad(2),
|
183 | value.log
|
184 | );
|
185 | case 'info':
|
186 | return container(
|
187 | color('blue', value.level.toUpperCase()),
|
188 | pad(2),
|
189 | value.log
|
190 | );
|
191 | default:
|
192 | return container(value.level.toUpperCase(), pad(2), value.log);
|
193 | }
|
194 | })
|
195 | ```
|
196 |
|
197 |
|
198 |
|
199 |
|
200 | [license-badge]: https://img.shields.io/npm/l/ansi-fragments.svg?style=flat-square
|
201 | [license]: https://opensource.org/licenses/MIT
|
202 | [prs-welcome-badge]: https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square
|
203 | [prs-welcome]: http://makeapullrequest.com
|
204 | [coc-badge]: https://img.shields.io/badge/code%20of-conduct-ff69b4.svg?style=flat-square
|
205 | [coc]: https://github.com/zamotany/ansi-fragments/blob/master/CODE_OF_CONDUCT.md
|
206 | [chat-badge]: https://img.shields.io/badge/chat-discord-brightgreen.svg?style=flat-square&colorB=7289DA&logo=discord
|
207 | [chat]: https://discord.gg/zwR2Cdh
|
208 |
|
209 | [version]: https://img.shields.io/npm/v/ansi-fragments.svg?style=flat-square
|
210 | [package]: https://www.npmjs.com/package/ansi-fragments
|