Creating a Plugin

So you want to build an editor plugin! srclib can make your favorite editor more intelligent in a language-agnostic way -- which means that you only need to interface with srclib, and you'll get analysis for every language that srclib supports for free.

Disclaimer

Editor plugins are temporarily incompatible with srclib master. Please download an older version of srclib to use editor plugins.

Before You Start

Make sure you have srclib installed, along with the toolchains you want to use. It's also a good idea to be familiar with the srclib's api and data model.

Be aware that many API commands currently rely on an up-to-date build to function correctly. For example, srclib api describe takes --start-byte as one of its arguments, and gives you the information for the identifier that starts at start-byte. If you change a file, an identifier's byte offset may be out of sync with the analyzed version of the code. The srclib team is looking into this issue and we'll have a fix for it out soon, but for now, make sure to run srclib do-all before calling an API command to get accurate results.

There are a couple things a srclib-powered plugin can do:

• Analyze a Project
• Show Type Information
• Jump To Definition
• Show Documentation
• Get Examples

Analyze a Project

You can explicitly build a project by running srclib do-all at the top-level directory of a repository. srclib do-all is equivalent to running srclib config and then srclib make. srclib do-all will return 0 for it's error code if it completes correctly.

Analysis happens automatically when you call an API command on srclib if no builds exist for the vcs version (where a version is a commit id or HEAD) that is currently checked out.

Show Type Information

The srclib api describe command will give you an identifier's type information. If you only need the type information, you should pass --no-examples to the command.

The type information is part of the "Def.Data" property, and it is currently language-defined. Here is an example generated by the Go toolchain:

Example

{
    "Def":{
        "Data": {
            "PkgName": "main",
            "TypeString": "error",
            "UnderlyingTypeString": "interface{Error() string}",
            "Kind": "var",
            "PackageImportPath": "github.com/samertm/chompy"
        },
    },
}

Jump To Definition

The srclib api describe command will give you the location of an identifier's definition. If you only need the definition location, you should pass --no-examples to the command.

Example

The starting byte for an identifier's definition is "Def.DefStart", and the ending byte is "Def.DefEnd".

{
    "Def":{
        "DefStart":300,
        "DefEnd":330,
    },
}

Show Documentation

The srclib api describe command will give you an identifier's doc string, if it has one. If you only need the doc string, you should pass --no-examples to the command.

Example

The doc information is part of the "Def.Data" property, and it is currently language-defined. Here is an example generated by the Go toolchain:

{
    "Def":{
        "Data":{
            "DocHTML":"compile is a function with an awesome doc string.\n",
        },
    },
}

Get Examples

The srclib api describe command will give you an identifier's example information, if it has examples. This hits Sourcegraph's API, so it's speed will be affected by moving over the network.

Example

{
    "Examples":[
        {
            "DefRepo":"github.com/golang/go",
            "DefUnitType":"GoPackage",
            "DefUnit":"fmt",
            "DefPath":"Println",
            "Repo":"github.com/golang/go",
            "CommitID":"f58a5cb9e2d03ff1baa37cce63766cdb8cba7221",
            "UnitType":"GoPackage",
            "Unit":"go/printer",
            "File":"src/go/printer/printer.go",
            "Start":3392,
            "End":3399,
            "SrcHTML":"", /* SrcHTML omitted for brevity */
            "StartLine":278,
            "EndLine":286,
            "Error":false
        }
    ]
}