# align-text

> Align the text in a string.

**Examples**

Align text values in an array:

```javascript
align([1, 2, 3, 100]);
//=> ['  1', '  2', '  3', '100']
```

Or [do stuff like this](https://github.com/Canardoux/tau/tree/b8046e7b1cae9de264c9b7cc8c23d8d30e5cd94a/tau_core/web/node_modules/align-text/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)](https://github.com/Canardoux/tau/tree/b8046e7b1cae9de264c9b7cc8c23d8d30e5cd94a/tau_core/web/node_modules/align-text/example.js)

Visit [the example](https://github.com/Canardoux/tau/tree/b8046e7b1cae9de264c9b7cc8c23d8d30e5cd94a/tau_core/web/node_modules/align-text/example.js) to see how this works.

## Install

Install with [npm](https://www.npmjs.com/)

```bash
$ npm i align-text --save
```

## Usage

```javascript
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**

```javascript
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:**

```javascript
// 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:**

```javascript
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:

```javascript
align(text, centerAlign);
```

Would align this text:

```javascript
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:

```javascript
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

```javascript
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

```javascript
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:

```bash
$ 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.*


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://canardoux.gitbook.io/tau/tau_core/web/node_modules/align-text.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.