*fireplace.txt*  Clojure REPL support

Author:  Tim Pope <http://tpo.pe/>
License: Same terms as Vim itself (see |license|)

This plugin is only available if 'compatible' is not set.

                                                *fireplace*
While not a hard dependency of Fireplace itself, many features require
<https://github.com/clojure-emacs/cider-nrepl> for full functionality.

CONNECTING TO A REPL                            *fireplace-connect*

Connecting to lein repl happens automatically.  If you have a different setup,
you can connect by hand.

                                                *fireplace-:Connect*
:Connect nrepl://{host}:{port} [path]
:Connect {port} [path]
                        Connect to a REPL server.  The path is the root of the
                        project that the REPL applies to (try ".").

The REPL is used for the commands below. If no REPL is found for the current
buffer and 'path' contains at least one jar file, java (or $JAVA_CMD) is
invoked directly, which can be quite slow depending on your setup.

The only adapter shipped with fireplace.vim is for nREPL.  You need either
`python` or `python3` in your path.

                        *fireplace-piggieback* *fireplace-clojurescript*
To use a ClojureScript, invoke |:CljEval| with the command you would normally
use to start a ClojureScript REPL.  For example:
>
        :CljEval (cider.piggieback/cljs-repl (cljs.repl.nashorn/repl-env))
<
Be aware that your ClojureScript files must be available on the classpath for
this to work properly, and that not all operations are supported.

The :Piggieback command is softly deprecated wrapper for invoking Piggieback.

                                                *fireplace-:Piggieback*
:Piggieback ({ns}/repl-env [...])
                        Create a new nREPL session and invoke
                        cider.piggieback/cljs-repl with the given environment.

:Piggieback ({ns}/cljs-repl [...])
                        If the argument is a call to a function not named
                        repl-env, it is invoked directly, without
                        cider.piggieback/cljs-repl.  This is useful for
                        (figwheel.main.api/cljs-repl) and similar functions.

:Piggieback {port}      If the argument looks like a port number,
                        weasel.repl.websocket (if available) or
                        cljs.repl.browser will be used to provide the REPL
                        environment.

:Piggieback             If no argument is given, :Piggieback defaults to
                        the ClojureScript environment specified in
                        *b:fireplace_cljs_repl* or *g:fireplace_cljs_repl* .
                        If projectionist.vim is installed, the "cljsRepl"
                        projectionist key is also checked.  This default will
                        be invoked automatically on first eval in a
                        ClojureScript buffer if :Piggieback is not invoked
                        explicitly.  To restore the old behavior of defaulting
                        to Nashorn, add this line to your vimrc:
>
        let g:fireplace_cljs_repl =
              \ '(cider.piggieback/cljs-repl (cljs.repl.nashorn/repl-env))'
<
:Piggieback!            Terminate the most recently created piggieback
                        session.

DOCUMENTATION                                   *fireplace-documentation*

                                                *fireplace-:Doc*
:Doc {symbol}           Show the docs for the given symbol.

                                                *fireplace-:Javadoc*
:Javadoc {class}        Open the java docs for the given class in a browser.

                                                *fireplace-K*
K                       Look up the doc, javadoc, or spec-form for the
                        identifier under the cursor.

                                                *fireplace-:FindDoc*
:FindDoc {arg}          Wrapper around (clojure.repl/find-doc ...).

                                                *fireplace-:SpecForm*
:SpecForm {keyword}     Show the form of the spec given.
                        Like (spec/form keyword).

                                                *fireplace-:SpecExample*
:SpecExample {keyword}  Generate one example for the spec given.
                        Like (gen/generate keyword).

                                                *fireplace-:Source*
:Source {symbol}        Show the source for the given symbol.

                                                *fireplace-[d*
[d                      Show source for symbol under cursor.
]d

NAVIGATING                                      *fireplace-navigating*

These commands will never use a remote REPL, only a local one, as file paths
on a remote server wouldn't be very useful locally.

                                                *fireplace-[_CTRL-D*
[<C-D>                  Jump to the source of the symbol under the cursor.
]<C-D>

                                                *fireplace-CTRL-W_CTRL-D*
<C-W><C-D>              Jump to the source of the symbol under the cursor in
<C-W>d                  a split.

                                                *fireplace-gf*
gf                      Go to the file for the namespace under the cursor.

                                                *fireplace-CTRL-]*
<C-]>                   Jump to the source of the symbol under the cursor
g]                      and put the symbol on the tag stack.  See the help for
g<C-]>                  the built-in |CTRL-]|.  All other tag maps are provided
<C-W>]                  as well.
<C-W>g]
<C-W>g<C-]>

                                                *fireplace-:Djump*
:Djump {symbol}         Jump to the definition for the given symbol.

                                                *fireplace-:Dsplit*
:Dsplit {symbol}        Jump to the definition for the given symbol in a
                        split.

EVALUATING CODE                                 *fireplace-eval*

All code is evaluated in the namespace of the current file, requiring it if
necessary.  If the current file sits outside the class path (project.clj, for
example), the user namespace is used instead.  ClojureScript is used for .cljs
files always and for .cljc files if a ClojureScript repl has already been
initialized.

Evaluation happens in the foreground and blocks Vim by default.  Press <C-D>
during a prolonged execution to detach from it and return Vim.  When
evaluation is complete, results will load into the preview window.

                                                *fireplace-:Require*
:Require [ns]           Require :reload the given/current namespace.

                                                *fireplace-:Require!*
:Require! [ns]          Require :reload-all the given/current namespace.

                                                *fireplace-:Eval*
:Eval                   Eval/print the outermost form for the current line.

:{range}Eval            Eval/print the given range.

:Eval {expr}            Eval/print the given expression.

                                                *fireplace-:Eval!*
:[range]Eval!           Eval the given range or outermost expression and
                        replace it with its result.

:[range]Eval! {expr}    Eval the given expression and insert it after
                        the given range or current line.

                                                *fireplace-:CljEval*
:CljEval [...]          Like :Eval, but always use the user namespace and
                        Clojure platform.  This command is available globally.

                                                *fireplace-:CljsEval*
:CljsEval [...]         Like :Eval, but always use the cljs.user namespace and
                        ClojureScript platform.  This command is available
                        globally.

                                                *fireplace-:RunTests*
:RunTests [ns] [...]    Call clojure.test/run-tests on the given namespaces
                        and load the results into the quickfix list.

:[range]RunTests        Call clojure.test/test-var on the var defined at or
                        above the specified line and load the results into the
                        quickfix list.  Typically invoked as :.RunTests to run
                        the test under the cursor.

:0RunTests [pattern]    Call clojure.test/run-all-tests with the given pattern
                        and load the results into the quickfix list.

                                                *fireplace-cp*
cp{motion}              Eval/print the code indicated by {motion}.

cpp                     Eval/print the innermost form at the cursor.

                                                *fireplace-cpr*
cpr                     :Require|RunTests

                                                *fireplace-c!*
c!{motion}              Eval/replace the code indicated by {motion}.

c!!                     Eval/replace the innermost form at the cursor.

                                                *fireplace-cm*
cm{motion}              Fully macroexpand the code indicated by {motion}.

                                                *fireplace-cmm*
cmm                     Fully macroexpand the innermost form at the cursor.

                                                *fireplace-c1m*
c1m{motion}             Macroexpand the code indicated by {motion} once.

                                                *fireplace-c1mm*
c1mm                    Macroexpand the innermost form at the cursor once.

                                                *fireplace-cqp*
cqp                     Bring up a prompt for code to eval/print.

                                                *fireplace-cqq*
cqq                     Bring up a |command-line-window| with innermost form
                        at the cursor prepopulated.

                                                *fireplace-cqc*
cqc                     Bring up a |command-line-window| for code to
                        eval/print.  Equivalent to cqp<C-F>i.

                                                *fireplace-cq*
cq{motion}              Bring up a |command-line-window| with text indicated
                        by {motion} prepopulated.

                                                *fireplace-:Last*
:Last                   Open the result of the last evaluation in the preview
                        window.  Use :2Last to get the next-to-last result,
                        and so on.  Once the window is open, cycle to older
                        and newer entries with |:lprevious| and |:lnext|.

                                                *fireplace-:Stacktrace*
:Stacktrace             Retrieve the most recent Clojure error and load the
                        stacktrace into the quickfix list.  By default this is
                        filtered to exclude duplicates and tooling (e.g.,
                        nREPL internals).  Use :Stacktrace! to get an
                        unfiltered version.

And insert mode:

                                                *fireplace-i_CTRL-R_(*
<C-R>(                  Evaluate the given expression and insert the result.

There's omnicomplete on |CTRL-X_CTRL-O|, which works in Clojure buffers and
in the |command-line-window|, and tab complete at the cqp prompt.

API                                             *fireplace-api*

Use fireplace#clj() or fireplace#cljs() to get a "platform" object for Clojure
or ClojureScript, or fireplace#platform() to pick automatically for the
current buffer.  The following instance methods are available:
>
        let ext = platform.Ext()
<
Retrieve the appropriate file extension, either "clj" or "cljs".
>
        let user_ns = platform.UserNs()
<
Retrieve the user namespace, either "user" or "cljs.user".
>
        let ns = platform.BufferNs()
        let ns = platform.BufferNs(bufnr(''))
<
Retrieve the namespace for the current or given buffer number, determined by
looking for a (ns) declaration and falling back to a using the class path
relative filename.  This is the same namespace used by operations like :Eval.
>
        call platform.Message({"op": "some-op"})
        call platform.Message({"op": "some-op"}, function("Callback"))
<
Send an nREPL message asynchronously.  If given, invoke the callback on each
message.
>
        let list = platform.Message({"op": "..."}, v:t_list)
        let list = platform.Message({"op": "..."}, v:t_list,
              \ function("Callback"))
<
Send an nREPL message and return all response messages as a list.  If given,
invoke the callback on each message.
>
        let dict = platform.Message({"op": "some-op"}, v:t_dict)
        let dict = platform.Message({"op": "some-op"}, v:t_dict,
              \ function("Callback"))
<
Send an nREPL message and return all response messages as a single combined
dictionary.  If given, invoke the callback on each message.
>
        let list = platform.Message({"op": "some-op", "ns": bufnr('')})
<
If a buffer number is given as an "ns" parameter, it is replaced with the
namespace for that buffer, as retrieved by platform.BufferNs().
>
        let list = platform.Message({"op": "some-op", "session": v:true})
<
If v:true is given as "session", the current session is cloned for the given
operation, and closed when the operation completes.  Use this to do an
arbitrary eval without tainting *1, etc.  (Although platform.Query() is
generally a better choice for such operations.)
>
        if platform.HasOp("some-op")
<
Check for the presence of an nREPL op.  Always returns false if no live
connection is available.
>
        let msg1 = platform.Message({"op": "some-op"})
        let msg2 = platform.Message({"op": "other-op"}, function("Callback"))
        call fireplace#wait([msg1, msg2])
<
Wait on one or more asynchronous messages to finish.  If CTRL-C is pressed by
the user, all messages will be interrupted with {"op": "interrupt"}.
>
        let classpath = platform.Path()
<
Retrieve the class path, either from a REPL connection or from 'path' as set
by classpath.vim or salve.vim.
>
        let data = platform.Query("code")
        let data = platform.Query("code", {"ns": bufnr('')})
<
Evaluate the given code on the REPL and return it as a Vim data structure.
Works offline if a class path is available.
>
        let msg = platform.Query("code", function("Callback"))
<
Evaluate the given code on the REPL and pass it to the callback as a Vim data
structure.  Works offline if a class path is available.

ABOUT                                           *fireplace-about*

Grab the latest version or report a bug on GitHub:

http://github.com/tpope/vim-fireplace

 vim:tw=78:et:ft=help:norl:
