# align

Simple unix filter to align text on specified substrings.

`align` can be run from inside Vim or other editors with custom key bindings to
align lines of code neatly on programming language operators like =>, ::, @=?,
=, +, etc.

## Installation

You must first have the Haskll platform installed on your system:

* [Haskell platform](https://www.haskell.org/platform)

```
cabal update
cabal install align-text
```

This will likely install the `align` executable in ~/.cabal/bin, which should be on your PATH.


## Usage

`align` has two modes: Serial mode and Alternative mode.

### Serial mode

Assume you want to align this text:

input.sample:
```
    "parseKeyExpr" ~: [ObjectKey "item"] @=? parseKeyExpr "item"
  , "ngEvalToString" ~: "apple" @=? ngEvalToString testContext1 "item" 
  , "ngEvalToString2" ~: "apple" @=? ngEvalToString testContext2 "item.name" 
```

You can do so with this command:

    align '~: @=?' < input.sample

which outputs:

```
    "parseKeyExpr"    ~: [ObjectKey "item"] @=? parseKeyExpr "item"
  , "ngEvalToString"  ~: "apple"            @=? ngEvalToString testContext1 "item"
  , "ngEvalToString2" ~: "apple"            @=? ngEvalToString testContext2 "item.name"
```

`align` takes an argument list of strings to align the text and performs
the alignment operation on the text it gets from STDIN.

`align` will only match each alignment string once, so if that string
occurs multiple times in a line, you need to specify it than many times 
in the argument.

### Alternative mode

Assume you want to align this text:

input2.sample:
```
sendmailCustom :: FilePath        -- ^ sendmail executable path
  -> [String]     -- ^ sendmail command-line options
  -> L.ByteString -- ^ mail message as lazy bytestring
   -> IO ()
```

Here you want to align `::` and `->` in the same column position. To
do this use the `-a` flag:

    align -a -- '-> ::' < input2.sample

(FYI you need to add the `--` argument to prevent the `->` string, which starts
with a dash, from being parsed as a command option.)

This outputs:

```
sendmailCustom :: FilePath        -- ^ sendmail executable path
               -> [String]     -- ^ sendmail command-line options
               -> L.ByteString -- ^ mail message as lazy bytestring
               -> IO ()
```

You can also align the comment (beginning with `--`) by using a pipeline:

    cat input2.sample | align -a -- '-> ::' | align -- '--'

which outputs:

```
sendmailCustom :: FilePath     -- ^ sendmail executable path
               -> [String]     -- ^ sendmail command-line options
               -> L.ByteString -- ^ mail message as lazy bytestring
               -> IO ()
```

## How to use align in Vim 

To use align from Vim, you can select some text, and then use a Vim
filter command:

    !align '~: @=?'

For common alignment operations, you can make Vim commands and put them
in your `.vimrc`, e.g.:

```vimscript
command! -range AlignHaskellTypeAnnotation :<line1>,<line2>!align '::'
vnoremap <leader>h :AlignHaskellTypeAnnotation<cr>

command! -range AlignHaskellTest :<line1>,<line2>!align '~: @=?'
vnoremap <leader>H :AlignHaskellTest<cr>

```


## Author

Daniel Choi <https://github.com/danchoi>