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
@extendsand@implements. - Completion and go-to-definition support for type names in JSDoc comments and
in strings (e.g.
@typeannotations andgoog.requirearguments). - 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:
finderObject. Configuration for finding the files that provide types. See Finders below. Optional. Default: None.debugboolean. Whether tern-closure should print debug output. Optional. Default: Match Terndebugoption.noMinimalLoadboolean. 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:
nameThe name of the finder you want to use. Required.debugWhether the finder should print debug output. Optional. Default: Match tern-closuredebugoption.
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:
dirsAn 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 namenameto find and a callback functioncbto call with the path to file providingname.cbshould be called asynchronously, even if the providing file is known whenfindFileis 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.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent