An outline definition is a declarative file that describes how to recognize symbols in a file that become nodes in the outline tree. Items are recognized by simple regular expressions as outlined below. You can include an outline in a Cloud9 Bundle to share on c9.io.

Outline definitions are very powerful and can define a useful outline view with only a handful of regular expressions. Any outline items are also added automatically to the default list of code completions. Still, it is entirely possible to create a custom parser that does all the heavy lifting. See the language guide for more information on that.

Creating an Outline Definition

An outline definition is a simple JSON object with 5 supported properties; languages, extensions, guess_fargs, extract_docs and tags.

Languages & Extensions

These two arrays specify for which languages / extensions the outline document is used.

{
    languages: ["php"],
    extensions: ["php", "php3", "php4", "php5"]
}

Options

There are two options that can be set to true or false.

• guess_fargs sets whether to guess function arguments when showing outline items in code completion.
• extract_docs sets whether to extract documentation when showing outline items in code completion.\

Tags

The tags property is an array of rules that match symbols in the document. Each rule is an object with two fields; regex and kind. The kind determines the icon of the symbol and takes one of the following strings:

• "package"
• "method"
• "method2"
• "property"
• "property2"
• "import"

The regex property matches a symbol in a file and builds a tree based on that. Make sure to only capture the name of the symbol in the regular expressions. Use (?:) if you need to use parenthesis for any other reason.

The following tag finds a javascript function:

{ regex: /(?:^|\n)\s*function\s+([^ \(:]+)/g, kind: "method" },

Full Example

Here's a full example of the python outline definition.

{
    languages: ["py"],
    extensions: ["py"],
    
    guess_fargs: true,
    extract_docs: true,
    
    tags: [
        { regex: /(?:^|\n)\s*class\s+([^ \(:]+)/g, kind: "package" },
        { regex: /(?:^|\n)\s*def\s+(?!_)([^ \(:]+)/g, kind: "method" },
        { regex: /(?:^|\n)\s*def\s+(?!__[^ \(:]+__)(_[^ \(]*)/g, kind: "method2" },
        { regex: /(?:^|\n)\s*def\s+(__[^ \(:]+__)/g, kind: "property" },
        {
            regex: new RegExp(
                "(?:^|\\n)\\s*import\\s+([^ \\(]+)"
            ),
            kind: "import"
        }
    ]
}

Adding an Outline to a Bundle

A bundle can contain one or more outline definitions. Each outline definitions must be placed in the outline directory.

Suppose your outline definition is called python.outline. Your file structure will look something like this:

└─ your.plugin
    ├─ outline
    |    └─ python.outline
    ├─ package.json
    └─ README.md