tern-closure is a plugin which adds support for Closure Compiler annotations and the Closure type system to the JavaSript code intelligence system Tern.
To use tern-closure, you need to install it and then configure Tern to load it.
tern-closure adds the following features to your Tern installation:
- Understanding of types in JSDoc type annotations (similar to the doc_comment plugin included with Tern).
- Understanding of inheritance and interfaces with
@extends
and@implements
. - Completion and go-to-definition support for type names in JSDoc comments and
in strings (e.g.
@type
annotations andgoog.require
arguments). - Automatic loading of the definitions for types, so that you get completion and type information from other files and can jump to definitions in those files. This requires enabling a finder. We consider access modifiers and how types are used in order to load only the types relevant the files you are editing, keeping this feature feasible even for large projects.
Currently, tern-closure only works with the NodeJS Tern Server, and not within a browser.
After installing Tern according the setup instructions of your desired editor plugin, go to the place where the Tern package was installed (or the Tern repo was cloned) and run
$ npm install tern-closure
Or, if you're not sure where Tern was installed, you can try
$ npm install -g tern-closure
See INSTALL.md for instructions tailored to each editor.
In order for Tern to load the tern-closure plugin once it is installed, you must
include closure
in the plugins
section of your Tern configuration
file. The configuration file can be either a file named
.tern-project
in your project's root directory, or .tern-config
in your home
directory.
You must also explicitly disable the default doc_comment
plugin, which will
interfere with tern-closure.
Here is a minimal example .tern-project
configuration file:
{
"plugins": {
"doc_comment": false,
"closure": {}
}
}
Tern looks for .tern-project
first, walking up the directory tree, and uses
its location as the "project directory". If no .tern-project
is found, your
.tern-config
is loaded instead, and the working directory of the Tern server
process is used as the "project directory".
Since Tern and tern-closure (including finders like grep) use the
"project directory" as the base for all relative paths, you should either use
.tern-project
or be careful about where you start your Tern server (or, where
your editor plugin starts your Tern server).
You can set the following options in the closure
section of your Tern
configuration file:
finder
Object. Configuration for finding the files that provide types. See Finders below. Optional. Default: None.debug
boolean. Whether tern-closure should print debug output. Optional. Default: Match Terndebug
option.noMinimalLoad
boolean. When a finder is active, this disables attempts to limit loaded files according to visibility. This is mostly for debugging - if setting this fixes an issue, file a bug. Optional. Default:false
.
tern-closure uses "finders" to find the files providing Closure names via
goog.provide
. Finders allow tern-closure to load and interpret the files
providing names required via goog.require
or referenced in JSDoc type strings
so it better understands the context of a given file.
The finder
section of the options object for closure
in your .tern-project
file specifies what finder implementation you want to use, and what options you
want to pass to the finder. By default, no finder is used, and files are not
automatically loaded. Currently, only one finder implementation is included with
tern-closure, grep.
Common finder options:
name
The name of the finder you want to use. Required.debug
Whether the finder should print debug output. Optional. Default: Match tern-closuredebug
option.
This is a basic finder which uses the grep
command-line utility (or findstr
in Windows) to search for goog.provide
statements at startup and create a map
of Closure names to providing files.
Options:
dirs
An array of path strings indicating which directories to search for files. Paths can either be absolute, or relative to the project directory. Optional. Default:['.']
(just the project directory).
Here is an example .tern-project
file using the grep finder:
{
"plugins": {
"doc_comment": false,
"closure": {
"finder": {
"name": "grep",
"dirs": [
"relevant/project/subdir",
"/absolute/path/to/library"
]
}
}
}
}
You can easily use a finder not included in this repository, or implement your own. This allows you to search for names in different ways, on demand, and to use existing indexes of your codebase.
Given a finder name name
, tern-closure first looks in its own lib/finder
directory, then attempts to load name
using require()
, so a third-party
finder module can be installed as an npm package.
A finder module must implement a simple interface:
-
It must export a constructor
function(projectDir: string, options: Object)
which takes the project directory and an options object as parameters. Options are specified in the Tern configuration file. -
Instances of that constructor must have a method
findFile(name: string, cb: function(file: string))
, which takes as arguments a Closure namename
to find and a callback functioncb
to call with the path to file providingname
.cb
should be called asynchronously, even if the providing file is known whenfindFile
is called. This allows finders to execute I/O operations to find files on demand.
Please note that while tern-closure is in a 0.X.X
release, the finder API may
be subject to breaking changes.
Please file bug reports and feature requests as issues on the issues page of the tern-closure repository.
Pull requests to tern-closure are welcome. Please see the CONTRIBUTING.md file for requirements and guidelines.
Disclaimer: tern-closure is not an official Google product, and is maintained on a best-effort basis.