You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
236 lines
5.4 KiB
236 lines
5.4 KiB
# align-text [![NPM version](https://badge.fury.io/js/align-text.svg)](http://badge.fury.io/js/align-text) [![Build Status](https://travis-ci.org/jonschlinkert/align-text.svg)](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): |
|
|
|
[![screen shot 2015-06-09 at 2 08 34 am](https://cloud.githubusercontent.com/assets/383994/8051597/7b716fbc-0e4c-11e5-9aef-4493fd22db58.png)](./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._
|
|
|