clam.vim / doc / clam.txt

*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

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

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

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:

6. Contributing                                             *ClamContributing*

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


7. Changelog                                                   *ClamChangelog*

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

Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.