*vimclojure.txt*                    *clojure.vim*

VimClojure - A Clojure Environment
==================================

Introduction
------------

VimClojure is a filetype plugin and development environment for Clojure. It
provides indenting, syntax highlighting and – if configured – interactive
features like omni completion, documentation lookup and a Repl running in a
Vim buffer.

Nailgun Server                      *clj-nailgun-server*
--------------

To use the interactive part you have to start the nailgun server via the jar
file. Make sure, that clojure and clojure-contrib are in your classpath and
start the com.martiansoftware.nailgun.NGServer class. Example invocation:
>
        java -cp clojure.jar:clojure-contrib.jar:vimclojure.jar com.martiansoftware.nailgun.NGServer 127.0.0.1
<
This may look different depending on your system.

You can stop the server by invoking the nailgun client with the ng-stop
argument.
>
        ng ng-stop
<
Set the clj_want_gorilla variable in your vimrc.
>
        let g:clj_want_gorilla = 1
<
Note: Should there be an error when executing an interactive command
and the error message goes away to quickly, you can use |:messages| to
recall the message and read it conveniently without time pressure.

Syntax Highlighting                 *ft-clj-syntax*
-------------------

The clojure syntax highlighting provides several options:
>
        g:clj_highlight_builtins
                If it exists and is nonzero, then Clojure's builtin functions
                are highlighted. This useful to distuingish macros and special
                forms from functions.

        g:clj_highlight_contrib
                If it exists and is nonzero, then Clojure-Contrib's functions
                are highlighted. (Currently incomplete)

        g:clj_paren_rainbow
                If it exists and is nonzero, then differing levels of
                parenthesisation will receive different highlighting.
<
The g:clj_paren_rainbow option provides 10 levels of individual colorisation
for the parentheses. Because of the quantity of colorisation levels, unlike
non-rainbow highlighting, the rainbow mode specifies its highlighting using
ctermfg and guifg, thereby bypassing the usual colorscheme control using
standard highlighting groups. The actual highlighting used depends on the
dark/bright setting (see |'bg'|).

Keybindings
-----------

Note: <LocalLeader> is a Vim feature. More information can be found
under the |maplocalleader| help topic.

You can redefine any key mapping using some autocommand in your .vimrc file.
All mappings use so-called Plugs. Simply prepend <Plug>Clojure to the given
Plug name and your setting will override the default mapping.
>
        aucmd BufRead,BufNewFile *.clj nmap xyz <Plug>ClojureEvalToplevel
<

<LocalLeader>et                                 *et* *EvalToplevel*
                        Send off the toplevel sexpression currently
                        containing the cursor to the Clojure server.

<LocalLeader>ef                                 *ef* *EvalFile*
                        Send off the current file to the Clojure Server.

<LocalLeader>eb                                 *eb* *EvalBlock*
                        Send off the the mark visual block to the
                        Clojure server. Obviously this mapping is only
                        active in visual mode.
                        Note: This does not check for structure.

<LocalLeader>el                                 *el* *EvalLine*
                        Send off the current line to the Clojure Server.
                        Note: This does not check for structure.

<LocalLeader>ep                                 *ep* *EvalParagraph*
                        Send off the current paragraph to the Clojure Server.
                        Note: This does not check for structure.

<LocalLeader>rf                                 *rf* *RequireFile*
                        Require the namespace of the current file with
                        the :reload flag. Note: For this to work with
                        a remote Clojure server, the files have to put in
                        place before issueing the command, eg. via scp
                        or NFS.

<LocalLeader>rF                                 *rF* *RequireFileAll*
                        Require the namespace of the current file with
                        the :reload-all flag. Note: For this to work with
                        a remote Clojure server, the files have to put in
                        place before issueing the command, eg. via scp
                        or NFS.

<LocalLeader>me                                 *me* *MacroExpand*
                        Expand the innermost sexpression currently
                        containing the cursor using macroexpand.

<LocalLeader>m1                                 *m1* *MacroExpand1*
                        Same as MacroExpand, but use macroexpand-1.


<LocalLeader>lw                                 *lw* *DocLookupWord*
                        Lookup up the word under the cursor and print
                        the documentation for it via (doc).

<LocalLeader>li                                 *li* *DocLookupInteractive*
                        Lookup the documentation of an arbitrary word.
                        The user is prompted for input.

<LocalLeader>fd                                 *fd* *FindDoc*
                        Find a the documentation for a given pattern
                        with (find-doc). The user is prompted for input.

<LocalLeader>jw                                 *jw* *JavadocLookupWord*
                        Open the javadoc for the word under the cursor
                        in an external browser.

<LocalLeader>ji                                 *ji* *JavadocLookupInteractive*
                        Open the javadoc for an arbitrary word in an
                        external browser. The user is prompted for input.

<LocalLeader>sw                                 *sw* *SourceLookupWord*
                        Show a read-only view of the source the word under
                        the cursor. For this to work, the source must be
                        available in the Classpath or as a file (depending
                        on how the source was loaded).

<LocalLeader>si                                 *si* *SourceLookupInteractive*
                        Show a read-only view of the source of an arbitrary
                        word. For this to work, the source must be available
                        in the Classpath or as a file (depending on how the
                        source was loaded).

<LocalLeader>gw                                 *gw* *GotoSourceWord*
                        Goto the source of the word under the cursor. For this
                        to work, the source must be available in a directory
                        of the |'path'| option. The directories in the
                        CLOJURE_SOURCE_DIRS environment variable will be added
                        to the |'path'| setting.

<LocalLeader>gi                                 *gi* *GotoSourceInteractive*
                        Goto the source of an arbitrary word. For this to work,
                        the source must be available in a directory of the
                        |'path'| option. The directories in the
                        CLOJURE_SOURCE_DIRS environment variable will be added
                        to the |'path'| setting.

<LocalLeader>mw                                 *mw* *MetaLookupWord*
                        Lookup the meta data of the word under the cursor.

<LocalLeader>mi                                 *mi* *MetaLookupInteractive*
                        Lookup the meta data of an arbitrary word. The
                        user is prompted for input.

<LocalLeader>sr                                 *sr* *StartRepl*
                        Start a new Vim Repl in a fresh buffer. There
                        might be multiple Repls at the same time.

Vim Repl
--------

Start a Repl via the |sr| shortcut. At the prompt just type expressions.
Hitting enter will determine, whether the expression is complete and
will send it to the Clojure instance. In case the expression is incomplete,
eg. after "(defn foo" will result in a newline for multiline expressions.

Previously sent expressions may be recalled via <C-Up> and <C-Down>.
Note: sending multiple expressions will save them in the same history
entry. So playing back with <C-Up> will again send all of the contained
expressions.

The Plugs are:
 - <Plug>ClojureReplEnterHook for the enter key
 - <Plug>ClojureReplUpHistory for going backwards in history (<C-Up>)
 - <Plug>ClojureReplDownHistory for going forwards in history (<C-Down>)

The following convenience commands are provided:

 - ,close - close the Repl and free the Repl resources in the server process
 - ,st - print a stack trace of *e as with clojure.contrib.stacktrace
 - ,ct - print a cause trace of *e as with clojure.contrib.stacktrace

Pretty Printing
---------------

In case Tom Faulhaber's cl-format package is available in the Classpath
it will be used for pretty printing, eg. of macroexpansions. The Repl
can be told to use pretty printing via a global Var.
>
        (set! de.kotka.vimclojure.repl/*print-pretty* true)
<

Omni Completion
---------------

VimClojure supports omni completion for Clojure code. Hitting <C-X><C-O> in
insert mode will try to provide completions for the item in front of the
cursor.

The completion tries to be somewhat intelligent in what it completes.

 - a word starting with an upper case letter will be completed to an
   imported class.
     Str<C-x><C-o> => String, StringBuilder, ...

 - a word containing dots will be completed to a namespace.
     c.c<C-x><C-o> => clojure.core, clojure.contrib.repl-utils, ...

 - everything else will be completed to a Var, an alias or namespace.

 - a word containing a slash will be handled differently
   - if the word starts with an upper case letter, will complete
     static fields of the given class
       String/va<C-x><C-o> => String/valueOf

   - otherwise it is treated as a namespace or alias
       clojure.core/re<C-x><C-o> => clojure.core/read, ...

The completion uses certain characters to split the matching. This are
hyphens and (for namespaces) dots. So r-s<C-x><C-o> matches read-string.

Note: Completion of symbols and keywords is also provided via the <C-N>
functionality of Vim.

License
-------

Copyright (c) 2008,2009 Meikel Brandmeyer, Frankfurt am Main
All rights reserved.

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.
==============================================================================
.. vim: set ft=help norl ts=8 tw=78 et :