Skip to content

Deep editing pass on documentation. #2531

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Dec 2, 2018
Merged

Deep editing pass on documentation. #2531

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
142 changes: 77 additions & 65 deletions doc/clojurescript.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,30 +1,34 @@
## ClojureScript

CIDER works with ClojureScript, but you should keep in mind that not all
the functionality available with Clojure exists for ClojureScript (at least
not yet). To give you a concrete example - things like running tests and
the debugger are currently Clojure-only features.
CIDER works well with ClojureScript, but not all CIDER features are
available in ClojureScript (yet). For instance, the test runner and
debugger are currently Clojure-only features. Unlike the Clojure
ecosystem that is dominated by Leiningen and Boot, the ClojureScript
ecosystem has a number of different choices for REPLs. You'll have to
decide which one you want to run and how you want CIDER to interact
with it. This chapter describes some of the more common choices
and the configurations required to get them working.


### Piggieback

ClojureScript support relies on the [piggieback][] nREPL middleware
being present in your REPL session. There's one exception to this,
though - [shadow-cljs][]. It has its own nREPL middleware and doesn't rely
though: [shadow-cljs][]. It has its own nREPL middleware and doesn't rely
on piggieback at all.

If `cider-inject-dependencies-at-jack-in` is enabled (which is the default) then
piggieback will be automatically added and configured for your project when
doing `cider-jack-in-cljs`.
If `cider-inject-dependencies-at-jack-in` is enabled, which it is by
default, then piggieback will be automatically added and configured
for your project when doing `cider-jack-in-cljs`.

If this configuration option is disabled or you're going to connect to
an already running nREPL server using `cider-connect-cljs` - continue
reading ahead.
If `cider-inject-dependencies-at-jack-in` is disabled or you're going
to connect to an already running nREPL server using
`cider-connect-cljs`, use the configuration in the following section.

#### Manual Piggieback Setup

To setup piggieback add the following dependencies to your project
(`project.clj` in Leiningen based project or `build.boot` in Boot
To setup piggieback, add the following dependencies to your project
(`project.clj` in a Leiningen based project or `build.boot` in a Boot
project):

```clojure
Expand All @@ -50,32 +54,37 @@ or in `build.boot`:

### Starting a ClojureScript REPL

There are many ClojureScript REPLs out there and it's often hard to wrap your
head around them and the differences between them. You'd do well to read [this
awesome article](https://lambdaisland.com/guides/clojure-repls/clojurescript-repls)
before proceeding with the rest of the instructions listed here.
!!! Tip

Open a file in your project and issue <kbd>M-x</kbd>
There are many ClojureScript REPLs available, each offering a
different set of capabilities and features. As background for this
section, you might want to read [this awesome
article](https://lambdaisland.com/guides/clojure-repls/clojurescript-repls)
before proceeding.

Open a file in your project and type <kbd>M-x</kbd>
`cider-jack-in-cljs` <kbd>RET</kbd>. This will start up the nREPL
server, and then create a ClojureScript REPL buffer for you, one.
server and create a ClojureScript REPL buffer.

!!! Note

Prior to CIDER 0.18, `cider-jack-in-cljs` would create both a Clojure and
a ClojureScript REPL. In CIDER 0.18+ if you want to create both REPLs
you'll have to use `cider-jack-in-clj&cljs` instead.

When you have a combination of Clojure and ClojureScript REPLs all
usual CIDER commands will be automatically directed to the appropriate
REPL, depending on whether you're visiting a `.clj` or a `.cljs` file.
When you have a combination of Clojure and ClojureScript REPLs, CIDER
will automatically direct all the usual CIDER commands to the
appropriate REPL based on whether you're currently visitng a `.clj` or
`.cljs` file.

`cider-jack-in-cljs` will prompt you about the type of
ClojureScript to start. Keep in mind that some of the REPLs will
require some additional setup, before you can make use of them (e.g. you'll
need to have Node.js installed to be able to start a node REPL).
`cider-jack-in-cljs` will prompt you for the type of ClojureScript
REPL you want to start. Keep in mind that some of the REPLs will
require you to configure additional setup. For example, you'll need to
have Node.js installed to be able to start a Node REPL.

You can suppress the prompt the REPL to use by setting `cider-default-cljs-repl`.
Here's an example that will make Nashorn the default:
If you frequently use the same ClojureScript REPL, you can set
`cider-default-cljs-repl` and CIDER will skip the prompt and use this
instead. For example, the following will make Nashorn the default:

```el
(setq cider-default-cljs-repl 'nashorn)
Expand Down Expand Up @@ -106,20 +115,20 @@ You can also modify the known ClojureScript REPLs on a per-project basis using
(cider-default-cljs-repl . super-cljs)))
```

You can also create a ClojureScript REPL with the command
`cider-jack-in-sibling-clojurescript` in cases where you already have a
Clojure REPL running.
If you already have a Clojure REPL running and want to add a
ClojureScript REPL, you can invoke
`cider-jack-in-sibling-clojurescript` to add it.

Continue reading for the additional setup needed for the various ClojureScript
REPLs out there.
The following sections describe the configurations for several common
CloudScript REPL use cases.

### Browser-connected ClojureScript REPL
### Browser-Connected ClojureScript REPL

Using Weasel, you can also have a browser-connected REPL.

1. Add `[weasel "0.7.0"]` to your project's `:dependencies`.

2. Issue <kbd>M-x</kbd> `cider-jack-in-cljs` <kbd>RET</kbd> and choose
2. Type <kbd>M-x</kbd> `cider-jack-in-cljs` <kbd>RET</kbd> and choose
the `Weasel` option when prompted about the ClojureScript REPL type you want
to use.

Expand All @@ -131,15 +140,15 @@ Using Weasel, you can also have a browser-connected REPL.
(repl/connect "ws://localhost:9001")
```

4. Open a file in your project and issue <kbd>M-x</kbd> `cider-jack-in-cljs`.
4. Open a file in your project and type <kbd>M-x</kbd> `cider-jack-in-cljs`.

Provided that a Piggieback-enabled ClojureScript environment is active in your
REPL session, code loading and evaluation will work seamlessly regardless of the
presence of the `cider-nrepl` middleware. If the middleware is present then most
other features of CIDER will also be enabled (including code completion,
documentation lookup, the namespace browser, and macroexpansion).

### Browser-connected ClojureScript REPL in Boot project
### Browser-Connected ClojureScript REPL in Boot Projects

1. Add this to your dependencies in `build.boot`:

Expand All @@ -166,10 +175,10 @@ and this at the end of `build.boot`:
(cljs)))
```

2. Issue <kbd>M-x</kbd> `customize-variable` <kbd>RET</kbd> `cider-boot-parameters`
2. Type <kbd>M-x</kbd> `customize-variable` <kbd>RET</kbd> `cider-boot-parameters`
and insert `dev`.

3. Open a file in your project and issue <kbd>M-x</kbd> `cider-jack-in-cljs`.
3. Open a file in your project and type <kbd>M-x</kbd> `cider-jack-in-cljs`.

5. Connect to the running server with your browser. The address is printed on the terminal, but it's probably `http://localhost:3000`.

Expand All @@ -195,7 +204,7 @@ You can also use [Figwheel](https://github.com/bhauman/lein-figwheel) with CIDER
```

Keep in mind that figwheel 0.5.16 is the first to support piggieback
0.3. If you're using an older figwheel you should stick to piggieback
0.3. If you're using an older figwheel, you should stick to piggieback
0.2.2 (which uses the old `com.cemerick/piggieback` package coordinates).

3. Add this to your dev `:repl-options` (not needed for `cider-jack-in-cljs`):
Expand All @@ -205,7 +214,7 @@ Keep in mind that figwheel 0.5.16 is the first to support piggieback
```

4. Start the REPL with `cider-jack-in-cljs` (<kbd>C-c C-x (C-)j (C-)s</kbd>). Select
`figwheel` when prompted about the ClojureScript REPL type.
`figwheel` when prompted for the ClojureScript REPL type.

5. Open a browser to the Figwheel URL so that it can connect to your application.

Expand All @@ -221,10 +230,10 @@ You should also check out

You can also use [Figwheel-main](https://github.com/bhauman/figwheel-main) with CIDER.

1. Add this to your dev `:dependencies`:
1. Add this to your dev `:dependencies` (not needed for `cider-jack-in-cljs`):

```clojure
[cider/piggieback "0.3.10"] ; not needed for cider-jack-in-cljs
[cider/piggieback "0.3.10"]
```

2. Add this to your dev `:repl-options` (not needed for `cider-jack-in-cljs`):
Expand All @@ -233,30 +242,31 @@ You can also use [Figwheel-main](https://github.com/bhauman/figwheel-main) with
:nrepl-middleware [cider.piggieback/wrap-cljs-repl]
```

3. Start the REPL with `cider-jack-in-cljs` (<kbd>C-c C-x (C-)j (C-)s</kbd>). Select
`figwheel-main` when prompted about the ClojureScript REPL type.
3. Start the REPL with `cider-jack-in-cljs` (<kbd>C-c C-x (C-)j
(C-)s</kbd>). When CIDER prompts about the ClojureScript REPL type,
type `figwheel-main`.

4. Select the Figwheel build to run when prompted for it. (e.g. `:dev`).

### Using shadow-cljs

Provided you've configured your project correctly you can simply use
`cider-jack-in-cljs` to use `shadow-cljs`.
Provided you've configured your project correctly, you can simply use
`cider-jack-in-cljs` for `shadow-cljs`.

This will automatically start the shadow-cljs server and connect to it. You'll also
be prompted for the build to use.
This will automatically start the shadow-cljs server and connect to
it. You'll also be prompted for the build to use.

Alternatively you can start the server manually with something like:

```
npx shadow-cljs server
```sh
$ npx shadow-cljs server
```

And connect to it with `cider-connect`.

Lastly, if you already have a running server watching a build, for instance you
have already run `npx shadow-cljs watch :dev`, you can use the `shadow-select`
CLJS REPL and specify `:dev` when prompted.
If you already have a running server watching a build (for instance
you have already run `npx shadow-cljs watch :dev`), you can use the
`shadow-select` CLJS REPL and specify `:dev` when prompted.

[leiningen]: http://leiningen.org/
[boot]: http://boot-clj.com/
Expand All @@ -265,14 +275,16 @@ CLJS REPL and specify `:dev` when prompted.

## Working with `.cljc` files

Ordinarily, CIDER dispatches code from `clj` files to Clojure REPLs and `cljs`
files to ClojureScript REPLs. However, `cljc` files have two possible connection
targets. By default, CIDER tries to evaluate `cljc` files in all matching
connection buffers, both `clj` and `cljs` (if present).

Simply put - if you're evaluating the code `(+ 2 2)` in a `cljc` file and you
have an active Clojure and and active ClojureScript REPL, then the code is going
to be evaluated twice - once for each of the REPLs. In fact, you can create
multiple clj and cljs sibling connections (<kbd>C-c C-x C-s C-s/j</kbd>) within
Cider session and evaluation will be directed into all REPLs simultaneously. See
[Managing Connections](managing_connections.md) for more details.
Ordinarily, CIDER dispatches code from `clj` files to Clojure REPLs
and `cljs` files to ClojureScript REPLs. But`cljc` files have two
possible connection targets, both of which are valid. So, by default,
CIDER tries to evaluate `cljc` files in all matching connection
buffers, both `clj` and `cljs`, if present.

Thus, if you're evaluating the code `(+ 2 2)` in a `cljc` file and you
have both an active Clojure and ClojureScript REPL then the code is
going to be evaluated twice, once in each of the REPLs. In fact, you
can create multiple clj and cljs sibling connections (<kbd>C-c C-x C-s
C-s/j</kbd>) within a CIDER session and evaluation will be directed
into all REPLs simultaneously. See [Managing
Connections](managing_connections.md) for more details.
41 changes: 23 additions & 18 deletions doc/code_completion.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,29 +18,31 @@ dedicated buffer.

## Auto-completion

CIDER users are advised to use [`company-mode`](http://company-mode.github.io/)
to enable auto-completion inside of source code and REPL buffers. To install
`company-mode` do:
While the standard Emacs tooling works just fine, we suggest that
CIDER users consider using
[`company-mode`](http://company-mode.github.io/) instead. Company mode
can be used for auto-completion for both source code and REPL buffers.
To install `company-mode`:

<kbd>M-x</kbd> `package-install` <kbd>RET</kbd> `company` <kbd>RET</kbd>

After installation, company can be turned on globally, like so --
After installation, you can turn on `company-mode` globally:

```el
(global-company-mode)
```

-- or through mode-specific hooks:
or through mode-specific hooks:

```el
(add-hook 'cider-repl-mode-hook #'company-mode)
(add-hook 'cider-mode-hook #'company-mode)
```

When `company-mode` is thus enabled, it will receive completion information
from `cider-complete-at-point`, and requires no additional setup or plugins.
When `company-mode` is enabled, it will receive completion information
from `cider-complete-at-point` and requires no additional setup or plugins.

If you'd prefer to trigger completions manually you can add this to you config:
If you'd prefer to trigger completions manually you can add this to your config:

```el
(setq company-idle-delay nil) ; never start completions automatically
Expand All @@ -56,22 +58,25 @@ you can add this to your config:

### Fuzzy candidate matching

By default `company-mode` will provide completion candidates with the assumption
that whatever you've typed so far (e.g. `map-`) is a completion prefix (meaning
you'd get only candidates that have `map-` in the beginnings of their names).
You can get enhanced fuzzy completion with the CIDER-specific completion style
by adding:
By default `company-mode` will provide completion candidates with the
assumption that whatever you've typed so far is a prefix of what
you're really trying to type. For example, if you type `map-` then
you'll only get completion candidates that have `map-` as the
beginning of their names. Sometimes, you don't know the exact prefix
for the item you want to type. In this case, you can get
CIDER-specific "fuzzy completion" by adding:

```el
(add-hook 'cider-repl-mode-hook #'cider-company-enable-fuzzy-completion)
(add-hook 'cider-mode-hook #'cider-company-enable-fuzzy-completion)
```

Now `company-mode` will accept certain fuzziness when matching candidates
against the prefix. For example, typing `mp` will show you `map-indexed` as one
of the possible completion candidates, `cji` will complete to `clojure.java.io`,
etc. Different completion examples are
listed [here](https://github.com/alexander-yakushev/compliment/wiki/Examples).
Now, `company-mode` will accept certain fuzziness when matching
candidates against the prefix. For example, typing `mp` will show you
`map-indexed` as one of the possible completion candidates and `cji`
will complete to `clojure.java.io`. Different completion examples are
shown
[here](https://github.com/alexander-yakushev/compliment/wiki/Examples).

### Completion annotations

Expand Down
Loading