doc/clam.txt @ 5bf26d7a0c8a

*clam.txt*   easily work with shell commands

                         ___  __      __    __  __
                        / __)(  )    /__\  (  \/  )
                       ( (__  )(__  /(__)\  )    (
                        \___)(____)(__)(__)(_/\/\_)

          A lightweight Vim plugin for working with shell commands.

==============================================================================
CONTENTS                                                       *clam-contents*

    1. Usage ........................... |ClamUsage|
    2. Mappings ........................ |ClamMappings|
        2.1 Refresh .................... |ClamRefresh|
        2.2 Pipe ....................... |ClamPipe|
    3. Configuration ................... |ClamConfiguration|
        3.1 g:clam_autoreturn .......... |ClamConfiguration_autoreturn|
    4. License ......................... |ClamLicense|
    5. Bugs ............................ |ClamBugs|
    6. Contributing .................... |ClamContributing|
    7. Changelog ....................... |ClamChangelog|

==============================================================================
1. Usage                                                           *ClamUsage*

The :Clam command is your point of entry to Clam.  Use it to run a shell
command like this: >

    :Clam ls -l

This will open up a new vertical split with the results of the command in it.
You can edit the text in this split like any other buffer.

When you close the buffer with :quit or something similar Clam will place your
cursor back in the split you came from.

The :Clam command can take a range.  If given, the lines will be passed to the
command on standard input.  For example, this will open a Clam output window
with the contents of the current buffer sorted: >

    :%Clam sort

This will pipe the first ten lines of the file into the python command: >

    :1,10Clam python

To pipe visually selected text you can use the :ClamVisual command: >

    :ClamVisual sort | uniq -c | sort -n

When you've got some text visually selected and hit : to enter the command,
Vim will add the '<,'> range by default.  You can backspace it out if you want
(or use <c-u>), but you don't have to: ClamVisual will work fine with or
without it.

In other words, the following commands do the same thing: >

    :ClamVisual wc -c
    :'<,'>ClamVisual wc -c

You might want to set up your own mappings to make Clam easier to use.  The
author has something like this in his .vimrc: >

    nnoremap ! :Clam<space>
    vnoremap ! :ClamVisual<space>

That's Clam in a nutclamshell.

==============================================================================
2. Mappings                                                     *ClamMappings*

Clam also defines two special mappings in the command output window for your
convenience.

------------------------------------------------------------------------------
2.1 Refresh                                                      *ClamRefresh*

Bound to: <localleader>r

"Refresh" the output by running the command again.

This is useful for commands where the output might change frequently and you
want to watch it in real time.

------------------------------------------------------------------------------
2.2 Pipe                                                            *ClamPipe*

Bound to: <localleader>p

"Pipe" the buffer through another command and replace the contents with its
result.

This allows you to run a shell pipeline where you can manually inspect and
massage the intermediate results.

==============================================================================
3. Configuration                                           *ClamConfiguration*

You can configure the following settings to change how Clam works.

------------------------------------------------------------------------------
3.1 g:clam_autoreturn                           *ClamConfiguration_autoreturn*

Set this to 0 to disable the "return to the last buffer you were in on closing
the output window" behavior: >

    let g:clam_autoreturn = 0

This can be useful if you use :bprevious (which can cause Vim to crash when
autoreturning).

Default: 1 (autoreturn is on)

------------------------------------------------------------------------------
3.2 g:clam_winpos                                   *ClamConfiguration_winpos*

This option control where to open output window: >

    let g:clam_autoreturn = 'topleft'

See the following topics for more information: |:vertical|, |:aboveleft|,
|:belowright|, |:topleft|, and |:botright|.

Default: 'vertical botright' (split vertical, open at far right)

==============================================================================
4. License                                                       *ClamLicense*

Clam is MIT/X11 licensed.

==============================================================================
5. Bugs                                                             *ClamBugs*

If you find a bug please post it on the issue tracker:
http://github.com/sjl/clam.vim/issues/

==============================================================================
6. Contributing                                             *ClamContributing*

Think you can make this plugin better?  Awesome!  Fork it on BitBucket or
GitHub and send a pull request.

BitBucket: http://bitbucket.org/sjl/clam.vim/
GitHub: http://github.com/sjl/clam.vim/

==============================================================================
7. Changelog                                                   *ClamChangelog*

v1.2.0
    * Added support for ranges in the :Clam command.
    * Added the :ClamVisual command.
    * Added the g:clam_winpos option.
v1.1.0
    * Added the g:clam_autoreturn setting.
v1.0.0
    * Initial stable release.

==============================================================================