267 lines
12 KiB
Plaintext
267 lines
12 KiB
Plaintext
*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 :
|