UNPKG

3.38 kBMarkdownView Raw
1
2# Node.js pad
3
4[![Build Status](https://secure.travis-ci.org/adaltas/node-pad.png)](http://travis-ci.org/adaltas/node-pad)
5
6Node Pad is a simple and elegant function to pad strings in both left and right directions.
7
8## Usage
9
10The API is quite simple:
11
12```javascript
13const pad = require('pad')
14pad('pad', 5) // "pad "
15pad(5, 'pad') // " pad"
16pad('pad', 5, '+') // "pad++"
17pad(5, 'pad', '+') // "++pad"
18```
19
20For TypeScript users, the type definition files are located in "./lib/index.d.ts" and declared inside the "package.json" file.
21
22## Bundles
23
24Node Pad comes in multiple flavours depending on your target environment:
25
26* CommonJS: `dist/pad.cjs.js`
27 Bundle used by Node.js and compatible with ES5. It is declared inside the `package.json` by the `main` property and used by default with `require("pad")` in a Node.js environment.
28* ES module: `dist/pad.esm.js`
29 Bundle using the ECMAScript standard defined in ES6 for working with modules. The path to the ES module is declared inside the `package.json` by the `module` property for ESM-aware tools like [Rollup](https://rollupjs.org) and [webpack 2+](https://webpack.js.org/).
30* UMD: `dis/pad.umd.js`
31 Bundle in the Universal Module Definition (UMD), a format compatible with both AMD and CommonJS.
32
33The CommonJS syntax to import Node Pad is:
34
35```js
36const pad = require("pad/dist/pad.cjs.js")
37// Or simply
38const pad = require("pad")
39```
40
41While the ES Modules syntax is:
42
43```js
44import pad from "pad/dist/pad.esm.js"
45// Or for ESM-aware tools
46import pad from "pad"
47```
48
49## Options
50
51Options are provided as a third argument and are all optional. A string argument
52it is interpreted as the "char" option. Accepted options include:
53
54* `char` (string)
55 The character used to fill the gap.
56* `colors` (boolean)
57 Ajust to hidden terminal color characters, you may also use `require 'pad/lib/colors'` to avoid passing this option.
58* `strip` (boolean)
59 Remove characters from text if length smaller than text length, default to "false".
60* `fixed_width` (boolean)
61 An optimization option to disable the usage of the wcwdith package to handle the discovery of characters using more than one column for display.
62 one column to display
63* `wcwidth_options` (object)
64 Options passed to the wcwidth package used to calculate the display width of
65 characters using more than one column.
66
67## Left padding: `pad(length, text, [options])`
68
69Left padding occurs when the first argument is a number and the second
70argument is a string.
71
72```javascript
73var pad = require('pad');
74pad(5, 'pad', '-').should.eql('--pad');
75```
76
77## Right padding: `pad(text, length, [options])`
78
79Right padding occurs when the first argument is a string and the second
80argument is a number.
81
82```javascript
83var pad = require('pad');
84pad('pad', 6).should.eql('pad ');
85```
86
87## Installing
88
89Starting with version 1.1.0, Node pad rely on Node.js 4.0.0 or more recent.
90Stick to version 1.0.x if using an older version of Node.js.
91
92Via [npm](http://github.com/isaacs/npm):
93
94```bash
95npm install pad
96```
97
98Via git (or downloaded tarball), copy or link the project from a discoverable
99Node.js directory:
100
101```bash
102git clone http://github.com/wdavidw/node-pad.git
103```
104
105## Testing
106
107Clone the repo, install the development dependencies and run the suite:
108
109```bash
110git clone http://github.com/wdavidw/node-pad.git .
111npm install
112make test
113```