doc/clam.txt @ d44a1d7dfc34

*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.

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

    nnoremap ! :Clam<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'

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.1.0
    * Added the g:clam_autoreturn setting.
v1.0.0
    * Initial stable release.

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