ENSIME User Manual
Aemon Cannon
Contents
1 Introduction1.1 What is ENSIME?
2 Installation
2.1 System Requirements
2.2 Getting Started
3 Creating a Project
3.1 Generating a Config File
3.1.1 Using sbt to Generate a Config File
3.1.2 Generating Configs for Other Project Types
3.2 Notes on Specific Project Types
3.2.1 SBT
3.2.2 Maven
3.2.3 Other + Ivy
3.2.4 Other
3.3 Config File Format
4 Usage
4.1 Startup
4.2 Symbol and Member Completion
4.3 Type/Package Inspector
4.4 The Scala REPL
4.5 Incremental Building
4.6 Debugging
4.7 Refactoring
4.8 Global Type and Method Search
4.9 Source Formatting
4.10 Semantic Highlighting
4.11 Scaladoc and Javadoc Browsing (customizing)
4.12 Command Reference
5 Troubleshooting
5.1 Diagnosing Issues
5.2 Emacs Binary Search Path
5.3 Custom JVM Options
A Installation from Git Clone
B Running the End-to-End ENSIME Tests
C Using the ENSIME Server with Other Editors
C.1 Starting the Server
C.2 The Swank Protocol
C.3 ENSIME Swank RPC: Version 0.7.2
C.3.1 Protocol Change Log
C.3.2 Important Datastructures
C.3.3 RPC Calls
C.3.4 Events
C.4 Other Protocols
1 Introduction
1.1 What is ENSIME?
ENSIME is the ENhanced Scala Interaction Mode for Emacs. It provides many features that are commonly found only in IDEs, such as live error-checking, symbol inspection, package/type browsing, and basic refactorings. ENSIME's architecture is client/server: a thin Emacs client communicates with an analysis server written in Scala. The client component is based heavily on the SLIME environment for Common Lisp - using the same Swank RPC protocol. The server component services these calls using an instance of the official Scala compiler, so the results should always be consistent with the commandline compiler.2 Installation
2.1 System Requirements
- Emacs 22 or later (23 is recommended)
- Linux, Mac OSX, Windows
- JVM Version 6
- Scala 2.8.x or 2.9.x compatible project
2.2 Getting Started
scala-mode:Although it's not required, ENSIME is designed to compliment scala-mode. scala-mode can be found in the Scala distribution under misc/scala-tool-support/emacs/
ensime-mode:
Download the latest ENSIME distribution from github.com at
http://github.com/aemoncannon/ensime/downloadsMake sure you get the version that is appropriate for your Scala version. Unpack the ENSIME distribution into a directory of your choosing, and add the following lines to your .emacs file:
-
;; Load the ensime lisp code... (add-to-list 'load-path "ENSIME_ROOT/elisp/") (require 'ensime) ;; This step causes the ensime-mode to be started whenever ;; scala-mode is started for a buffer. You may have to customize this step ;; if you're not using the standard scala mode. (add-hook 'scala-mode-hook 'ensime-scala-mode-hook)
See section 3.1.
Finally...
Execute M-x ensime from Emacs. Follow the instructions in the minibuffer to select your project. If you encounter any problems, see section 5 for troubleshooting.
3 Creating a Project
3.1 Generating a Config File
3.1.1 Using sbt to Generate a Config File
First, you need to install the ENSIME sbt plugin. Add the following lines to your project/plugins.sbt:-
resolvers += "Scala-Tools Maven2 Snapshots Repository" at "http://scala-tools.org/repo-snapshots" addSbtPlugin("org.ensime" % "ensime-sbt-cmd" % "VERSION")
-
ensime generate
-
import org.ensime.sbt.Plugin.Settings.ensimeConfig import org.ensime.sbt.util.SExp._ ensimeConfig := sexp( key(":compiler-args"), sexp("-Ywarn-dead-code", "-Ywarn-shadowing"), key(":formatting-prefs"), sexp( key(":alignParameters"), true ) )
3.1.2 Generating Configs for Other Project Types
ENSIME includes a wizard for automatically generating configuration files. In Emacs, execute M-x ensime-config-gen. Then simply follow the directions in the mini-buffer to create a .ensime file for your project. ENSIME will try to guess the type(mvn, custom, etc) of your project, based on the files and directory structure. If the config generator does a poor job for your project, please let us know so we can improve it. And of course you can still create the .ensime file for your project manually. See the section on the .ensime format below.3.2 Notes on Specific Project Types
3.2.1 SBT
Inferior SBT:The keystrokes C-c C-v s will launch (or switch to an existing) inferior sbt session.
Compile-on-Save:
If the configuration directive :sbt-compile-on-save is set to 't', ENSIME will invoke the 'compile' task in the inferior sbt process whenever you save a Scala buffer. Warning: This can eat up a lot of CPU.
3.2.2 Maven
Dependencies:Dependencies are discovered using the maven ant task. In debugging dependency resolution issues, it may be helpful to look at the contents of the *inferior-ensime-server* buffer.
3.2.3 Other + Ivy
Dependencies:Dependencies are discovered using the ivy ant task. In debugging dependency resolution issues, it may be helpful to look at the contents of the *inferior-ensime-server* buffer. If you've defined ivy configurations that you'd like to map to the compile and runtime modes in ENSIME, see the :ivy-*-conf directives in section 3.3. If your ivy.xml file is in a non-standard location, see the :ivy-file directive .
3.2.4 Other
Your project doesn't fit into one of the given categories? No problem. See section 3.3 for how to specify dependency, source, and class-output locations.3.3 Config File Format
Each project must have a .ensime file. The .ensime file contains the configuration for your project, and must be located in your project's root directory.The contents of the file must be a valid Emacs-Lisp S-Expression. Here's a quick primer on ELisp values.| "..." | A String |
| t | True |
| nil | False, null, or opposite of t. |
| (...) | A literal list. |
| :abcd123 | A keyword |
| (:key1 val1 :key2 val2) | An indexed property-list. |
What follows is a description of all available configuration options. Required options are marked as 'Required'. Any filename or directory paths may be relative to the project root.
:root-dir a filename
The root directory of your project. This option should be filled in by your editor.
:name a string
The short identifier for your project. Should be the same that you use when publishing. Will be displayed in the Emacs mode-line when connected to an ENSIME server.
:package a string
The main package for your project. Used by ENSIME to populate the project outline view.
:version a string
The current, working version of your project.
:use-maven [t or nil]
Use an existing pom.xml to determine the dependencies for the project. A Maven-style directory structure is assumed.
:use-ivy [t or nil]
Use an existing ivy.xml to determine the dependencies for the project. A Maven-style directory structure is assumed.
:ivy-file a filename
Override the default ivy.xml location.
:ivy-runtime-conf a string
Specify the names of dependency profiles to be used for runtime scenarios.
:ivy-compile-conf a string
Specify the names of dependency profiles to be used for compile scenarios.
:ivy-test-conf a string
Specify the names of dependency profiles to be used for test scenarios.
:compile-deps ([directory or filename]*)
A list of jar files and class directories to include on the compilation classpath. No recursive expansion will be done.
:compile-jars ([directory or filename]*)
A list of jar files and directories to search for jar files to include on the compilation classpath.
:runtime-deps ([directory or filename]*)
A list of jar files and class directories to include on the runtime classpath. No recursive expansion will be done.
:runtime-jars ([directory or filename]*)
A list of jar files and directories to search for jar files to include on the runtime classpath.
:test-deps ([directory or filename]*)
A list of jar files and class directories to include on the test classpath. No recursive expansion will be done.
:source-roots (directory*)
A list of directories in which to start searching for source files.
:target filename
The root of the class output directory.
:disable-index-on-startup [t or nil]
Disable the classpath indexing process that happens at startup. This will speed up the loading process significantly, at the cost of breaking some functionality.
:only-include-in-index (regex*)
Only classes that match one of the given regular expressions will be added to the index. If this is omitted, all classes will be added. This can be used to reduce memory usage and speed up loading. For example:
-
:only-include-in-index ("my\\.project\\.packages\\.\*" "important\\.dependency\\..\*")
:exclude-from-index (regex*)
Classes that match one of the excluded regular expressions will not be added to the index. This can be used to reduce memory usage and speed up loading. For example:
-
:exclude-from-index ("com\\.sun\\..\*" "com\\.apple\\..\*")
:compiler-args (string*)
Specify arguments that should be passed to ENSIME's internal compiler. For example, to enable two warnings in the compiler, you might use:
-
:compiler-args ("-Ywarn-dead-code" "-Ywarn-shadowing")
:builder-args (string*)
Specify arguments that should be passed to ENSIME's internal builder.
:formatting-prefs ([keyword value]*)
Customize the behavior of the source formatter. All Scalariform preferences are supported:
| :alignParameters | t or nil |
| :alignSingleLineCaseStatements | t or nil |
| :alignSingleLineCaseStatements_maxArrowIndent | 1-100 |
| :compactStringConcatenation | t or nil |
| :doubleIndentClassDeclaration | t or nil |
| :indentLocalDefs | t or nil |
| :indentPackageBlocks | t or nil |
| :indentSpaces | 1-10 |
| :indentWithTabs | t or nil |
| :multilineScaladocCommentsStartOnFirstLine | t or nil |
| :preserveDanglingCloseParenthesis | t or nil |
| :preserveSpaceBeforeArguments | t or nil |
| :rewriteArrowSymbols | t or nil |
| :spaceBeforeColon | t or nil |
| :spaceInsideBrackets | t or nil |
| :spaceInsideParentheses | t or nil |
| :spacesWithinPatternBinders | t or nil |
4 Usage
4.1 Startup
To start ensime type M-x ensime. You only need to do this once per project session. Follow the minibuffer instructions to specify the location of your .ensime project file. Bear in mind that the server may take several seconds to finish loading and analyzing your project's sources. To watch the progress of the ENSIME startup, switch to the *inferior-ensime-server* buffer.4.2 Symbol and Member Completion
ENSIME completion is initiated by pressing the TAB key. To complete a symbol, type the first couple characters, then press TAB. Currently this works for local variables, method parameters, unqualified method names, and type names. To complete a type member, type '.' or SPACE followed by TAB.Completion menu key commands:
Candidates can be scrolled with M-n and M-p or UP and DOWN. Candidates can be searched by typing C-s. Press TAB again to complete a common prefix. To cancel completion, type C-g. Finally, if you've selected the completion you want, press ENTER. If the selected completion was a method name, the minibuffer will display help for the method parameters.
4.3 Type/Package Inspector
Invocation:Control+Right-Clicking on a symbol in a Scala buffer, or typing C-c C-v i while the point is over a symbol will launch the type inspector. Typing C-c C-v o will open the inspector on the current project's main package. C-c C-v p will inspect the package of the current source file. Use the command M-x ensime-inspect-by-path to inspect an arbitrary type or package.
Package Inspector:
Displays a hierarchical view of a package, including all top-level types. Select a type to open the Type Inspector.
Type Inspector:
Lists the interfaces that contribute members to the inspected type. List each interface's methods, with full type signatures. If the type has a companion object/class, a link to the companion will appear under the heading.
Navigation:
Most things in the inspector are hyper-linked. You can click these links with the mouse or position your cursor over them and press ENTER. A history is kept of all the pages you view in the inspector. Go back in this history by typing ',' and forward by typing '.'.
4.4 The Scala REPL
First, ensure that you've set the :target directive in your config file. The REPL will load your project classes from the :target directory. Then, type C-c C-v z to launch the embedded Scala REPL. The REPL should be launched with all your project classes loaded and available. Please note that the Scala 2.8 REPL tab-completion does not currently work under ENSIME.4.5 Incremental Building
Incremental building allows for fast turn-around in the running/testing of your application. The building/rebuilding support in ENSIME is intended for those who are not already using the sbt build system, as sbt users will probably wish to continue using the sbt shell's support for incremental building (it may still be worth a try though, as the build-manager included in ENSIME uses a finer grained check for modifications). First, ensure that you've set the :target directive in your config file. The :target directory is where the classes will be written by the incremental builder. Then, type C-c C-b b to start building your project. When the build is finished, a window will appear listing the result of the build. After subsequent source changes, you may type C-c C-b r to rebuild only those parts of the project that depend on things you've changed.4.6 Debugging
Debugging support in ENSIME is provided by running an instance of jdb under Emacs, sending it commands, and parsing its output. As such, in addition to the graphical tools provided by ENSIME, you also have full access to the jdb command line.Launching the Debugger:
First, ensure that you've set the :target directive in your config file. The debugger needs these classes to run your application. Then, type C-c C-d d to launch the embedded Scala Debugger.
Break Points:
With your cursor on a line of Scala source, type C-c C-d b to set a breakpoint. Type C-c C-d u to remove the breakpoint.
Run Control:
Once you've set your breakpoints, type C-c C-d r to run the program. Type C-c C-d c to continue after hitting a breakpoint, or C-c C-d s to step into the current line, or C-c C-d n to step to the next line.
Value Inspection:
When stopped at a breakpoint, switch to the debug buffer *ensime-db*. Type 'locals' ENTER to see a list of all the local variables in the current runtime context. Use 'dump X" to dump the fields of an object X. Or 'print X' to print the value of an arbitrary expression X. To get help on more jdb commands, type 'help'.
4.7 Refactoring
Rename:Place your cursor over the symbol you'd like to rename. Type M-x ensime-refactor-rename and follow the minibuffer instructions.
Organize Imports:
Type M-x ensime-refactor-organize-imports in a Scala source buffer. Follow the minibuffer instructions.
Extract Method:
Select a region by setting the mark using C-SPACE and then placing the point at the end of the region. All selected code will be extracted into a helper method. Type M-x ensime-refactor-extract-method and follow the minibuffer instructions.
Inline Local:
Place your cursor over the local val who's value you'd like to inline. Type M-x ensime-refactor-inline-local and follow the minibuffer instructions.
4.8 Global Type and Method Search
Type C-c C-v v to start a global search. Type space separated keywords to filter the results of the search. For example, if I wanted to find java.util.Vector, I might start by typing 'vector', which would list all symbols containing the word 'vector'(case-insensitive), and then I would type 'java' to further refine the search. C-p and C-n move the selection up and down, respectively, and ENTER will jump to the source or definition of the selected symbol. Note that typing a keyword with a capital letter will automatically enable case-sensitivity.4.9 Source Formatting
ENSIME uses the Scalariform library to format Scala sources. Type C-c C-v f to format the current buffer. See section 3.3 for instructions on how to customize the formatting preferences.4.10 Semantic Highlighting
Normally syntax highlighting is based on the syntactic aspects of the source code. Semantic Highlighting adds color-coding based on semantic properties of the source. For example: a syntax highlighter can't tell whether a given identifier is a var or a val or a method call. Semantic Highlighting on the other hand can color vars differently to warn of their mutability. Semantic Highlighting is disabled by default. People use a wide variety of color schemes in Emacs; it would have been difficult to arrive at coloring scheme that worked well for everyone. Enabling Semantic Highlighting is as simple as changing the value of the variable ensime-sem-high-faces, which stores a list of (symbolType . face) associations. A `face' can be a reference to an existing Emacs face, such as font-lock-keyword-face, or a list of the form (:foreground `color'), where `color' is either a standard Emacs color (such as `slate gray') or a hex value like `#ff0000'. For example, you might add the following to your .emacs file:-
(setq ensime-sem-high-faces '( (var . (:foreground "#ff2222")) (val . (:foreground "#dddddd")) (varField . (:foreground "#ff3333")) (valField . (:foreground "#dddddd")) (functionCall . (:foreground "#84BEE3")) (param . (:foreground "#ffffff")) (class . font-lock-type-face) (trait . (:foreground "#084EA8")) (object . (:foreground "#026DF7")) (package . font-lock-preprocessor-face) ))
4.11 Scaladoc and Javadoc Browsing (customizing)
If ENSIME cannot find the source for a type or member, it will instead try to browse to the www documentation. Support is included for the java and scala standard libraries, as well as the android class library. To add your own doc library, you need to add a handler to the ensime-doc-lookup-map. This handler list is made up of (regex . handler) pairs, where regex is a regular expression string that will be matched against the fully qualified type name, and handler is a function that will be applied to the requested type and member and should return a url. Here's an example of how you might add new java docs for classes in com.example:-
(defun make-example-doc-url (type &optional member) (ensime-make-java-doc-url-helper "http://developer.example.com/apidocs/" type member)) (add-to-list 'ensime-doc-lookup-map '("^com\\.example\\." . make-example-doc-url))
4.12 Command Reference
TAB
Start completing a method/variable.
C-c C-v i or Control+Right-Click
Inspect the type of the expression under the cursor.
M-. or Control+Left-Click
Jump to definition of symbol under cursor.
M-,
Pop back to previously visited position.
C-c C-v .
Select the surrounding syntactic context. Subsequent taps of '.' and ',' will grow and shrink the selection, respectively.
C-c C-v v
Search globally for methods or types.
Control+Right-Click(on an imported package)
Inspect the package under cursor.
Mouse Hover
Echo the type of the expression under the cursor.
C-c C-v p
Inspect the package of the current source file.
C-c C-v o
Inspect the package specified in .ensime as :package.
C-c C-v r
List all references to the symbol under the cursor.
.
Forward one page in the inspector history.
,
Backward one page in the inspector history.
C-n or TAB
Forward one link in the inspector.
C-p
Backward one link in the inspector.
C-c C-v s
Switch to the sbt command-line (works for sbt projects only)
C-c C-v z
Switch to the scala interpreter, with project classes in the classpath.
C-c C-v c
Typecheck the current file.
C-c C-v a
Typecheck all files in the project.
C-c C-v e
Show all errors and warnings in the project.
C-c C-v f
Format the current Scala source file.
C-c C-v u
Undo a refactoring or formatting change.
M-n
Go to the next compilation note in the current buffer.
M-p
Go to the previous compilation note in the current buffer.
C-c C-d x
Where x is one of:
- d Start the debugger.
- b Set a breakpoint.
- u Clear a breakpoint.
- r Run the debugged class.
- s Step.
- n Step over.
- c Continue from a breakpoint.
- q Kill the debug session.
- l List the local variables at current line.
C-c C-r x
Where x is one of:
- r Rename the symbol at point.
- o Organize imports.
- l Extract local.
- m Extract method.
- i Inline local.
- t Add import for type at point.
C-c C-b x
Where x is one of:
- b Build the entire project.
- r Rebuild the project, incrementally.
M-x ensime-reload
Reload the .ensime file and recompile the project. Useful if you hit a server bug.
M-x ensime-config-get
Start the automatic configuration file generator.
5 Troubleshooting
5.1 Diagnosing Issues
You may want to examine the contents of the *inferior-ensime-server* buffer. This buffer collects the stdout and stderr of the server process, which is useful for debugging. If the compiler is in a broken state, you can restart it with M-x ensime-reload. Otherwise, if things are irreparably b0rked, you can always kill the *inferior-ensime-server* buffer (which kills the server process) and restart ensime with M-x ensime. If you've hit a recurring bug, please post an issue to github.com/aemoncannon/ensime. Please include your OS, Emacs version, ENSIME version, and the contents of *inferior-ensime-server*.5.2 Emacs Binary Search Path
When launching the embedded sbt shell, or the Scala repl, ENSIME uses the Emacs start-process command. Rather than using the value of the PATH environment variable, this command searches for binaries using the paths stored at the Emacs variable exec-path. On some Windows and OSX machines, exec-path will not by default contain the value of PATH. Seehttp://xahlee.org/emacs/emacs_env_var_paths.htmlfor more details. For example, the following Emacs Lisp could be used to manually add a Scala binary directory to the exec-path:
-
(setq exec-path (append exec-path (list "/home/aemon/scala/bin" )))
5.3 Custom JVM Options
If you're having problems with the default arguments (max heap, initial heap) that ENSIME uses in its startup script, you can modify the environment variable ENSIME_JVM_ARGS to override the arguments that are passed to the ENSIME Server JVM.A Installation from Git Clone
Note: This section is for people who want to hack on ENSIME itself.After cloning, run 'sbt update'. Then run 'sbt stage' to create the deployment directories underneath the root clone directory. Then follow the install instructions in section 2.2 above, substituting CLONE_DIR/dist as the root of your ENSIME distribution.
A common work-flow when hacking ENSIME:
- Edit source files
- 'sbt stage'
- Stop ENSIME server by killing *inferior-ensime-server* buffer
- Restart ENSIME with M-x ensime
B Running the End-to-End ENSIME Tests
- 'sbt stage'
- 'cd etc'
- 'bash run_emacs_tests.sh'
- Please be patient. These tests take a few mins to run. If all goes well you should see a buffer with a long list of 'ok's.
C Using the ENSIME Server with Other Editors
The ENSIME server is intentionally editor agnostic. It is our hope that it may be used to provide semantic information to Scala modes in other text editors. In order to interact with the ENSIME server, your editor's extension mechanism should ideally be able to open a persistent socket connection and respond to asynchronous events on that socket. Otherwise it may be difficult to interact with some of the long-running calls.C.1 Starting the Server
Emacs starts the ENSIME server using the server.sh script in the bin folder of the ENSIME distribution. Rather than tell the server explicitely what tcp port it should bind to,we instead pass the filename of a temporary file to the script. The first thing the server does on startup is choose a random, open port, and write the number to the given file. Emacs then reads this file and connects to the server.C.2 The Swank Protocol
The Emacs ENSIME client communicates with the server using the Swank protocol. This protocol was originally developed for the SLIME lisp environment for Emacs. A socket connection is maintained for the duration of the session. The client and server exchange s-expressions. At the wire level, these messages are encoded as sequences of ASCII bytes. Each message is prepended with a fixed-size header denoting its length. To send an s-expression, determine its ASCII length and then encode that integer as a padded six-digit hexadecimal value. Write this value to the output socket first, then followed by the ASCII form of the s-expression. On the receiving side, the reader loop should read six ASCII characters into a buffer and convert that into an integer, then read that number of ASCII characters from the socket, parsing the result into an s-expression.
See the E-Lisp function ensime-net-send in ensime.el for details on how messages are sent from Emacs, and the function ensime-net-encode-length for the implementation of the header encoding. See the functions readMessage and writeMessage in org.ensime.protocol.SwankProtocol to see how the messaging is handled in Scala. At the application level, the s-expressions encode RPC calls, RPC responses, and events. RPC calls are used to make requests of the server. Events are generally used for the server to communicate un-prompted, asynchronous activity to the client - such as an error or warning generated during compilation. What follows is a commented excerpt from the initialization of an ENSIME session. These s-expressions were copied from the *ensime-events* buffer in Emacs which logs all protocol events (useful for learning the application protocol!). Server messages are indented. Comments prefixed with #.
-
# The client requests information about the server (:swank-rpc (swank:connection-info) 1) # Server responds. Note the numbering scheme for RPC calls: call & response # have the same call id (1 in this case). (:return (:ok (:pid nil :server-implementation (:name "ENSIMEserver") :machine nil :features nil :version "0.0.1")) 1) # The client initializes the session by sending the configuration. # This is read from the .ensime file. (:swank-rpc (swank:init-project (:package "org.ensime" :root-dir "/home/aemon/src/misc/ensime/")) 2) # The acknowledges the message and sends some useful project info # back to the client. (:return (:ok (:name "ensime" :source-roots ("/home/aemon/src/misc/ensime/src/main/scala" "/home/aemon/src/misc/ensime/src/main/java" "/home/aemon/src/misc/ensime/src/test/scala"))) 2) # Server asks client to display a user message. # Note: this is not part of any RPC call - it's just an event from the server. (:background-message "Initializing Analyzer. Please wait...") # Server alerts client that the analyzer is now ready for RPC requests. (:compiler-ready t) # Server tells client the result of the last full compilation # (nil means 0 notes (errors or warnings)) (:typecheck-result (:lang :scala :is-full t :notes nil))
C.3 ENSIME Swank RPC: Version 0.7.2
C.3.1 Protocol Change Log
0.7.2 Get rid of scope and type completion in favor of unified swank:completions call. Wrap completion result in CompletionInfoList. 0.7.1 Remove superfluous status values for events such as :compiler-ready, :clear-scala-notes, etc. 0.7 Rename swank:perform-refactor to swank:prepare-refactor. Include status flag in return of swank:exec-refactor.
C.3.2 Important Datastructures
Certain datastructures, such as the position structure used to describe a source position, are re-used in many RPC calls. Implementors may wish to factor these structures out as classes or utility functions. PositionA source position.
RangePosition
A source position that describes a range of characters in a file.
Change
Describes a change to a source code file.
SymbolSearchResult
Describes a symbol found in a search operation.
ParamSectionInfo
Description of one of a method's parameter sections.
CallCompletionInfo
Description of a Scala method's type
TypeMemberInfo
Description of a type member
TypeInfo
Description of a Scala type.
InterfaceInfo
Describes an inteface that a type supports
TypeInspectInfo
Detailed description of a Scala type.
SymbolInfo
Description of a Scala symbol.
CompletionInfo
An abbreviated symbol description.
CompletionInfoList
An annotated collection of CompletionInfo structures.
PackageInfo
A description of a package and all its members.
SymbolDesignations
Describe the symbol classes in a given textual range.
PackageMemberInfoLight
An abbreviated package member description.
RefactorFailure
Notification that a refactoring has failed in some way.
RefactorEffect
A description of the effects a proposed refactoring would have.
RefactorResult
A description of the effects a refactoring has effected.
Note
Describes a note generated by the compiler.
Notes
Describes a set of notes generated by the compiler.
C.3.3 RPC Calls
The ENSIME server understands all of the following RPC calls: swank:connection-infoRequest connection information.
Arguments: None
Return:Example Call:
Example Return:
swank:init-project
Initialize the server with a project configuration. The server returns it's own knowledge about the project, including source roots which can be used by clients to determine whether a given source file belongs to this project.
Arguments:Return:
Example Call:
Example Return:
(:return (:ok (:project-name "ensime" :source-roots ("/Users/aemon/projects/ensime/src/main/scala" "/Users/aemon/projects/ensime/src/test/scala" "/Users/aemon/projects/ensime/src/main/java"))) 42)
swank:peek-undo
The intention of this call is to preview the effect of an undo before executing it.
Arguments: None
Return:Example Call:
Example Return:
swank:exec-undo
Execute a specific, server-side undo operation.
Arguments:Return:
Example Call:
Example Return:
(:return (:ok (:id 1 :touched-files ("/src/main/scala/org/ensime/server/RPCTarget.scala"))) 42)
swank:repl-config
Get information necessary to launch a scala repl for this project.
Arguments: None
Return:Example Call:
Example Return:
swank:builder-init
Initialize the incremental builder and kick off a full rebuild.
Arguments: None
Return: None
Example Call:Example Return:
swank:builder-update-files
Signal to the incremental builder that the given files have changed and must be rebuilt. Triggers rebuild.
Arguments:Return: None
Example Call:Example Return:
(:swank-rpc (swank:builder-update-files ("/ensime/src/main/scala/org/ensime/server/Analyzer.scala")) 42)
swank:builder-add-files
Signal to the incremental builder that the given files should be added to the build. Triggers rebuild.
Arguments:Return: None
Example Call:Example Return:
(:swank-rpc (swank:builder-add-files ("/ensime/src/main/scala/org/ensime/server/Analyzer.scala")) 42)
swank:builder-remove-files
Signal to the incremental builder that the given files should be removed from the build. Triggers rebuild.
Arguments:Return: None
Example Call:Example Return:
(:swank-rpc (swank:builder-remove-files ("/ensime/src/main/scala/org/ensime/server/Analyzer.scala")) 42)
swank:debug-config
Retrieve information necessary for starting a debugger. Also triggers the creation of internal debug datastructures (mappings between Scala source locations and mangled Java names)
Arguments: None
Return:Example Call:
Example Return:
swank:debug-unit-info
Request the mangled Java name of the compilation unit that results from the Scala code at the given source location.
Arguments:Return:
Example Call:
Example Return:
swank:debug-class-locs-to-source-locs
Map from a Java location that the debugger refers to, to a Scala source location.
Arguments:Return:
Example Call:
Example Return:
(:swank-rpc (swank:debug-class-locs-to-source-locs (("org.ensime.server.Server$" 49))) 42)
(:return (:ok (("Server.scala" 49))) 42)
swank:remove-file
Remove a file from consideration by the ENSIME analyzer.
Arguments:Return: None
Example Call:Example Return:
swank:typecheck-file
Request immediate load and check the given source file.
Arguments:Return: None
Example Call:Example Return:
swank:typecheck-all
Request immediate load and typecheck of all known sources.
Arguments: None
Return: None
Example Call:Example Return:
swank:format-source
Run the source formatter the given source files. Writes the formatted sources to the disk. Note: the client is responsible for reloading the files from disk to display to user.
Arguments:Return: None
Example Call:Example Return:
(:swank-rpc (swank:format-source ("/ensime/src/Test.scala")) 42)
swank:public-symbol-search
Search top-level symbols (types and methods) for names that contain ALL the given search keywords.
Arguments:Return:
Example Call:
Example Return:
(:swank-rpc (swank:public-symbol-search ("java" "io" "File") 50) 42)
swank:import-suggestions
Search top-level types for qualified names similar to the given type names. This call can service requests for many typenames at once, but this isn't currently used in ENSIME.
Arguments:Return:
Example Call:
Example Return:
swank:completions
Find viable completions at given point.
Arguments:Return:
Example Call:
Example Return:
swank:package-member-completion
Find possible completions for a given package path.
Arguments:Return:
Example Call:
Example Return:
swank:call-completion
Lookup the type information of a specific method or function type. This is used by ENSIME to retrieve detailed parameter and return type information after the user has selected a method or function completion.
Arguments:Return:
Example Call:
Example Return:
(:return (:ok (:result-type (:name "Unit" :type-id 7 :full-name "scala.Unit" :decl-as class) :param-sections ((:params (("id" (:name "Int" :type-id 74 :full-name "scala.Int" :decl-as class)) ("callId" (:name "Int" :type-id 74 :full-name "scala.Int" :decl-as class))))))) 42)
swank:uses-of-symbol-at-point
Request all source locations where indicated symbol is used in this project.
Arguments:Return:
Example Call:
Example Return:
swank:type-by-id
Request description of the type with given type id.
Arguments:Return:
Example Call:
Example Return:
swank:type-by-name
Lookup a type description by name.
Arguments:Return:
Example Call:
Example Return:
swank:type-by-name-at-point
Lookup a type by name, in a specific source context.
Arguments:Return:
Example Call:
Example Return:
swank:type-at-point
Lookup type of thing at given position.
Arguments:Return:
Example Call:
Example Return:
swank:inspect-type-at-point
Lookup detailed type of thing at given position.
Arguments:Return:
Example Call:
Example Return:
swank:inspect-type-by-id
Lookup detailed type description by id
Arguments:Return:
Example Call:
Example Return:
swank:symbol-at-point
Get a description of the symbol at given location.
Arguments:Return:
Example Call:
Example Return:
swank:inspect-package-by-path
Get a detailed description of the given package.
Arguments:Return:
Example Call:
Example Return:
swank:prepare-refactor
Initiate a refactoring. The server will respond with a summary of what the refactoring *would* do, were it executed.This call does not effect any changes unless the 4th argument is nil.
Arguments:Return:
Example Call:
Example Return:
swank:exec-refactor
Execute a refactoring, usually after user confirmation.
Arguments:Return:
Example Call:
Example Return:
(:return (:ok (:procedure-id 7 :refactor-type rename :touched-files ("SwankProtocol.scala"))) 42)
swank:cancel-refactor
Cancel a refactor that's been performed but not executed.
Arguments:Return: None
Example Call:Example Return:
swank:symbol-designations
Request the semantic classes of symbols in the given range. These classes are intended to be used for semantic highlighting.
Arguments:Return:
Example Call:
Example Return:
swank:expand-selection
Given a start and end point in a file, expand the selection so that it spans the smallest syntactic scope that contains start and end.
Arguments:Return:
Example Call:
Example Return:
swank:shutdown-server
Politely ask the server to shutdown.
Arguments: None
Return: None
Example Call:Example Return:
C.3.4 Events
The ENSIME server will dispatch the following types of events: :compiler-readySignal that the compiler has finished its initial compilation and the server is ready to accept RPC calls.
:full-typecheck-finished
Signal that the compiler has finished compilation of the entire project.
:indexer-ready
Signal that the indexer has finished indexing the classpath.
:scala-notes
Notify client when Scala compiler generates errors,warnings or other notes.
:java-notes
Notify client when Java compiler generates errors,warnings or other notes.
:clear-all-scala-notes
Notify client when Scala notes have become invalidated. Editor should consider all Scala related notes to be stale at this point.
:clear-all-java-notes
Notify client when Java notes have become invalidated. Editor should consider all Java related notes to be stale at this point.