237 lines
5.4 KiB
Markdown
237 lines
5.4 KiB
Markdown
# align-text [](http://badge.fury.io/js/align-text) [](https://travis-ci.org/jonschlinkert/align-text)
|
|
|
|
> Align the text in a string.
|
|
|
|
**Examples**
|
|
|
|
Align text values in an array:
|
|
|
|
```js
|
|
align([1, 2, 3, 100]);
|
|
//=> [' 1', ' 2', ' 3', '100']
|
|
```
|
|
|
|
Or [do stuff like this](./example.js):
|
|
|
|
[](./example.js)
|
|
|
|
Visit [the example](./example.js) to see how this works.
|
|
|
|
## Install
|
|
|
|
Install with [npm](https://www.npmjs.com/)
|
|
|
|
```sh
|
|
$ npm i align-text --save
|
|
```
|
|
|
|
## Usage
|
|
|
|
```js
|
|
var align = require('align-text');
|
|
align(text, callback_function_or_integer);
|
|
```
|
|
|
|
**Params**
|
|
|
|
* `text` can be a **string or array**. If a string is passed, a string will be returned. If an array is passed, an array will be returned.
|
|
* `callback|integer`: if an integer, the text will be indented by that amount. If a function, it must return an integer representing the amount of leading indentation to use as `align` loops over each line.
|
|
|
|
**Example**
|
|
|
|
```js
|
|
align(text, 4);
|
|
```
|
|
|
|
Would align:
|
|
|
|
```
|
|
abc
|
|
abc
|
|
abc
|
|
```
|
|
|
|
To:
|
|
|
|
```
|
|
abc
|
|
abc
|
|
abc
|
|
```
|
|
|
|
## callback
|
|
|
|
### params
|
|
|
|
The callback is used to determine the indentation of each line and gets the following params:
|
|
|
|
* `len` the length of the "current" line
|
|
* `longest` the length of the longest line
|
|
* `line` the current line (string) being aligned
|
|
* `lines` the array of all lines
|
|
|
|
### return
|
|
|
|
The callback may return:
|
|
|
|
* an integer that represents the number of spaces to use for padding,
|
|
* or an object with the following properties:
|
|
- `indent`: **{Number}** the amount of indentation to use. Default is `0` when an object is returned.
|
|
- `character`: **{String}** the character to use for indentation. Default is `''` (empty string) when an object is returned.
|
|
- `prefix`: **{String}** leading characters to use at the beginning of each line. `''` (empty string) when an object is returned.
|
|
|
|
**Integer example:**
|
|
|
|
```js
|
|
// calculate half the difference between the length
|
|
// of the current line and the longest line
|
|
function centerAlign(len, longest, line, lines) {
|
|
return Math.floor((longest - len) / 2);
|
|
}
|
|
```
|
|
|
|
**Object example:**
|
|
|
|
```js
|
|
function centerAlign(len, longest, line, lines) {
|
|
return {
|
|
character: '\t',
|
|
indent: Math.floor((longest - len) / 2),
|
|
prefix: '~ ',
|
|
}
|
|
}
|
|
```
|
|
|
|
## Usage examples
|
|
|
|
### Center align
|
|
|
|
Using the `centerAlign` function from above:
|
|
|
|
```js
|
|
align(text, centerAlign);
|
|
```
|
|
|
|
Would align this text:
|
|
|
|
```js
|
|
Lorem ipsum dolor sit amet
|
|
consectetur adipiscin
|
|
elit, sed do eiusmod tempor incididun
|
|
ut labore et dolor
|
|
magna aliqua. Ut enim ad mini
|
|
veniam, quis
|
|
```
|
|
|
|
Resulting in this:
|
|
|
|
```
|
|
Lorem ipsum dolor sit amet,
|
|
consectetur adipiscing
|
|
elit, sed do eiusmod tempor incididunt
|
|
ut labore et dolore
|
|
magna aliqua. Ut enim ad minim
|
|
veniam, quis
|
|
```
|
|
|
|
**Customize**
|
|
|
|
If you wanted to add more padding on the left, just pass the number in the callback.
|
|
|
|
For example, to add 4 spaces before every line:
|
|
|
|
```js
|
|
function centerAlign(len, longest, line, lines) {
|
|
return 4 + Math.floor((longest - len) / 2);
|
|
}
|
|
```
|
|
|
|
Would result in:
|
|
|
|
```
|
|
Lorem ipsum dolor sit amet,
|
|
consectetur adipiscing
|
|
elit, sed do eiusmod tempor incididunt
|
|
ut labore et dolore
|
|
magna aliqua. Ut enim ad minim
|
|
veniam, quis
|
|
```
|
|
|
|
### Bullets
|
|
|
|
```js
|
|
align(text, function (len, max, line, lines) {
|
|
return {prefix: ' - '};
|
|
});
|
|
```
|
|
|
|
Would return:
|
|
|
|
```
|
|
- Lorem ipsum dolor sit amet,
|
|
- consectetur adipiscing
|
|
- elit, sed do eiusmod tempor incididunt
|
|
- ut labore et dolore
|
|
- magna aliqua. Ut enim ad minim
|
|
- veniam, quis
|
|
```
|
|
|
|
### Different indent character
|
|
|
|
```js
|
|
align(text, function (len, max, line, lines) {
|
|
return {
|
|
indent: Math.floor((max - len) / 2),
|
|
character: '~',
|
|
};
|
|
});
|
|
```
|
|
|
|
Would return
|
|
|
|
```
|
|
~~~~~Lorem ipsum dolor sit amet,
|
|
~~~~~~~~consectetur adipiscing
|
|
elit, sed do eiusmod tempor incididunt
|
|
~~~~~~~~~ut labore et dolore
|
|
~~~~magna aliqua. Ut enim ad minim
|
|
~~~~~~~~~~~~~veniam, quis
|
|
```
|
|
|
|
## Related projects
|
|
|
|
* [center-align](https://github.com/jonschlinkert/center-align): Center-align the text in a string.
|
|
* [justify](https://github.com/bahamas10/node-justify): Left or right (or both) justify text using a custom width and character
|
|
* [longest](https://github.com/jonschlinkert/longest): Get the longest item in an array.
|
|
* [right-align](https://github.com/jonschlinkert/right-align): Right-align the text in a string.
|
|
* [repeat-string](https://github.com/jonschlinkert/repeat-string): Repeat the given string n times. Fastest implementation for repeating a string.
|
|
* [word-wrap](https://github.com/jonschlinkert/word-wrap): Wrap words to a specified length.
|
|
|
|
## Running tests
|
|
|
|
Install dev dependencies:
|
|
|
|
```sh
|
|
$ npm i -d && npm test
|
|
```
|
|
|
|
## Contributing
|
|
|
|
Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](https://github.com/jonschlinkert/align-text/issues/new)
|
|
|
|
## Author
|
|
|
|
**Jon Schlinkert**
|
|
|
|
+ [github/jonschlinkert](https://github.com/jonschlinkert)
|
|
+ [twitter/jonschlinkert](http://twitter.com/jonschlinkert)
|
|
|
|
## License
|
|
|
|
Copyright © 2015 [Jon Schlinkert](https://github.com/jonschlinkert)
|
|
Released under the MIT license.
|
|
|
|
***
|
|
|
|
_This file was generated by [verb-cli](https://github.com/assemble/verb-cli) on June 09, 2015._
|