Skip to content

Latest commit

 

History

History
75 lines (54 loc) · 2.89 KB

Proposal.md

File metadata and controls

75 lines (54 loc) · 2.89 KB

nREPL Self-describing Op Proposal

Implementing a self-describing nREPL op consists of writing a defn with a map attached to its :nrepl/op metadata. Only one key is required: a :name string, which is used to generate the name of the corresponding command client side. It's strongly recommended that you include a :doc string which will be used client-side to describe the command corresponding to the op. This is distinct from regular Clojure docstrings since those describe server-side semantics.

The other supported yet optional key is :args, which describes what arguments the client should send when invoking the op. It should be a list of lists. Each list includes at least the name of the argument as a string in the first position. If the client can provide enhanced input (completion, etc) for an argument, you can place a type string in the second position of the list to indicate what kind of completion should be offered. If an argument needs prompting, the prompt string should be in the third position.

Argument Types

  • string - Enter a free-form string. This is the default.

  • ns - The argument should be a namespace. Note that all nREPL messages contain the namespace they're sent from, so ops don't need to explicitly ask for a namespace unless it's different from the current namespace.

  • region - a list of file name, start offset, and end offset of a selection.

  • var - Any var.

  • file - Any file.

  • position - A string including the filename followed by a colon and a character offset.

  • list - Choose from a list of predetermined strings. This list is in the fourth position of the argument vector.

  • eval - Evaluate the form in the fourth position and use the return value as the argument specification.

Responses

When an op is invoked, it can result in any number of response maps being sent asynchronously via clojure.tools.nrepl.transport/send. There are certain keys in response maps which clients should try to support.

  • message - A one- or two-line string to be displayed to the user in a transient way.

  • text - A longer string indicating textual content that should be displayed in its own window or pane.

  • url - A URL to either display directly or open in a browser.

  • position - A string including the filename followed by a colon and a character offset.

  • overlay - An indicator to mark a given line with a certain color. Should be a list consisting of a color, a line number, and optionally a file. If no file is given, it defaults to the file from which the operation was invoked.

  • clear-overlays - Remove all overlays currently shown. The value can be a file in which to remove overlays; if nil is given then it means use the file from which the operation was invoked.

  • edit - Perform edits on a file. TODO: details.

A single response map may contain any of these as well as standard nREPL keys like out, status, etc.