Macro Support
Unlike most Clojure editors, Cursive works by analysing source code rather than introspecting a REPL for editor functionality. This has many advantages, but it has one major disadvantage - Cursive is generally unaware of which local bindings and vars are defined by macro forms. Cursive ships with built-in support for all core macro forms and for many popular libraries, but for in-house macros or open source libraries that Cursive doesn't yet support this can be annoying. It mostly manifests as false positive warnings about unresolved symbols and things like completions not working correctly, but it can also show up as incorrect arity warnings and so on.
Customising symbol resolution
Many custom macro forms are very similar to built-in forms. def-type macros are very common, as are forms that mostly
work like let. Cursive allows you to customise the symbol resolution for custom macros to mimic
these common forms. When the caret is the head symbol of a macro form which is not handling the symbol resolution
correctly, you'll see the intention lightbulb near the left margin and you can use Alt+Enter to
customise how that form is interpreted:
This UI can be confusing - make sure you select this option by pressing Enter, not by pressing right arrow - that arrow at the right of the menu item can be tempting. Pressing Enter allows you to choose which existing form the form you're customising should be interpreted as:
Note that this will only change how Cursive interprets the form, it has no effect on how your program actually runs.
Currently you can choose to interpret the form as def, defn, let, for, -> or ->>. Choosing def means that
Cursive will look for a name symbol as the second element in the form, and will create var metadata using that name.
It will also treat a string following that symbol as a docstring, if present. Choosing let or for will assume that
your form looks like the built-in equivalents, and will set up the local bindings in the corresponding way. Choosing
-> or ->> will prevent spurious arity warnings when creating custom threading forms. Your custom form will also
be formatted in the same way as the built-in form, but if you customise the formatting as described
here that will be overridden as normal.
If your form doesn't look like these but does look like another form that Cursive supports, you can customise further by choosing "Specify...". Then start entering the name of the form you'd like to customise as, and you'll get a list to choose from:
This support will work in a lot of cases, but we'll be adding more sophisticated support to allow users to help Cursive understand more complicated forms.
Stub generation
There are still some cases that are impossible for Cursive to analyse the source, for example when vars are dynamically created at runtime, or in cases such as Datomic which are distributed without source at all. For these cases, Cursive supports stub generation. This will run a process and load the problematic namespaces into it, introspect the var metadata and then generate source files containing empty function stubs which it can index for use in the editor.
Currently this is only supported for a hard-coded list of namespaces for projects which are known to be problematic. If your project uses one of these namespaces, Cursive will prompt you with a notification:
Click "Generate now" and after a short delay Cursive will reindex the new files, and then things should resolve correctly:
← Test Integration AOT Compilation →