Snippets

{"metadata":{"image":[],"title":"","description":""},"api":{"url":"","auth":"required","params":[],"results":{"codes":[]}},"next":{"description":"","pages":[]},"title":"Snippets","type":"basic","slug":"snippets","excerpt":"","body":"Snippets are small pieces of code that can be inserted via the completion box. Based on a *trigger* a piece of code is inserted that can have one or more areas that can be filled by the user using `[TAB]` to switch between them.\n\nThe following example shows a snippet that is triggered by typing `ife[TAB]`.\n```\nsnippet ife\n\tif (${1:true}) {\n\t\t${2}\n\t} else {\n\t\t${0}\n\t}\n```\nIt inserts the if else construct and starts by selecting the word `true`. After changing that and pressing `[TAB]` the cursor moves to the body of the if. The last `[TAB]` will move the cursor to the body of the else.\n\n# Creating a Snippets File\n\n*Snippets work in a similar way as those for TextMate and Sublime Text*\n\nA snippets file is a collection of multiple snippets for a specific mode. It consists of a header with some meta data and a list of snippets below that. Currently, the only way to add custom snippets to a project is to create a plugin (as described [here](#section-adding-snippets-to-a-bundle)).\n\n## Header\n\nThe header specifies the *scope* for the snippets. The scope is a string that specifies the name of the mode to which these snippets are applied.\n\n```\n# scope: javascript\n```\n\nUse `_` to specify snippets for all scopes. Use a comma separated list if these snippets apply to several modes.\n\n## Snippets\n\nThe rest of the file contains snippets. Snippets start with a list of variable definitions and then a list of lines that contain the code of the snippet itself.\n\n```\n# Comment\n<field> <value>\n<field> <value>\n<tab>snippetcontents\n<tab>snippetcontents\nsnippet ended\n```\n\nA file can contain any number of these underneath each other.\n\n# Creating a Snippet\n\n## Insertion Points\n\nAfter inserting the snippet text the cursor will move to the first position after the inserted text, when there are no insertion points specified. Specifying insertion points using the `$` character and a number to specify their sequence.\n\n```\n ${1}\n ${2}\n etc\n```\n\nThe `${0}` insertion point is always last in line. You can specify the text that is selected when jumping from one insertion point to the next one.\n\n```\n ${1:some_text}\n```\n\nIn addition, it's possible to reuse the same variable multiple times. All instances will be selected using multiple cursors and changed at the same time when the user types.\n\n```\n for (var ${1:i}=0; $1 < ${2}; $1++) {\n ${0}\n }\n```\n\n## Using Special Variables\n\nWhen triggering a snippet through a menu or command you can configure it to use the text selected prior to inserting the snippet in the resulting code.\n\n```\n\t(function(${1}) {\n\t\t${0:${SELECTED_TEXT:/* code */}}\n\t}(${1}));\n```\n\nSimilarly the following variables can be used to insert other special text.\n[block:html]\n{\n \"html\": \"<table>\\n<tr><th>CURRENT_WORD</th><td>The word at the cursor at the.</td></tr>\\n<tr><th>SELECTION</th><td>The selected text.</td></tr>\\n<tr><th>SELECTED_TEXT</th><td>The selected text.</td></tr>\\n<tr><th>CURRENT_LINE</th><td>The current line.</td></tr>\\n<tr><th>PREV_LINE</th><td>The previous line.</td></tr>\\n<tr><th>LINE_INDEX</th><td>The index of the current line.</td></tr>\\n<tr><th>LINE_NUMBER</th><td>The line number (index + 1).</td></tr>\\n<tr><th>SOFT_TABS</th><td>\\\"YES\\\" or \\\"NO\\\".</td></tr>\\n<tr><th>TAB_SIZE</th><td>The tab size.</td></tr>\\n</table>\"\n}\n[/block]\n## Formatting Strings\n\nVariables that are inserted can be formatted using the following command:\n\n```\n${«int»/«regexp»/«format»/«options»}\n```\n\nThe following example comes from the markdown snippets and takes the contents of the previous line transforming each character into a `=`. That results in a line full of `===` exactly matching the length of the line above it.\n```\nsnippet ===\nregex /^/=+/=*//\n\t${PREV_LINE/./=/g}\n\t\n\t${0}\n```\n\nIn addition the following characters can be used to toggle case.\n\n```\n\\u uppercase next letter\n\\l lowercase next letter\n\\U uppercase until \\ULE\n\\E ends \\U or \\L\n```\n\n## Triggers & Guards\n\nThe examples above used a simple string of characters to define how a snippet is triggered. The snippet definition allows for more control in triggering snippets, introducing two concepts; `triggers` and `guards`. Both have a beginning marker called `trigger` and `guard` and an end marker called `endTrigger` and `endGuard`. These are all optional.\n\nGuards are pieces of a regular expression (regex) that define the context in which a trigger is allowed. Whatever is matched by a guard remains after insertion of the snippet - guards are not replaced.\n\nTriggers are also pieces of a regex that define the start (before the cursor) and end (after the cursor) of the text that will be replaced by the snippet contents.\n\nLets start with a simple example.\n\n```\nsnippet for\n```\n\nThis can also be written like this.\n\n```\nguard \\b\ntrigger for\nendGuard\nendTrigger\n```\n\nOf course since the `endGuard` and `endTrigger` are empty they can be left out.\n\nHere's a more advanced example using a trigger to match `(f(|)` or `f(|)` or `f(|` where `|` is the cursor.\n\n```\n# Immediate function\ntrigger \$?f\\(\nendTrigger \$?\nsnippet f(\n (function(${1}) {\n ${0:${SELECTED_TEXT:/* code */}}\n }(${1}));\n```\n\n## Using a RegEx\n\nIt's possible to replace the guards and trigger fields with a single regex that describes each.\n\nThis regex below matches the start of a line (allowing white spaces) as a guard. It then is triggered by the `for` characters and `textafter` after the cursor, requiring at least 1 white space character, guarding the end of the sequence.\n```\nregex /^\\s*/for/textafter/\\s+/\n```\n\nUse the regex capture groups to allow variables inserted in snippets. The captured items are available as variables `M1`, `M2`, etc.\n\n```\n${M1?$M1: ${1:functionName}} \n```\n\nThis allows you to create snippets with arguments; `for 1 5|` -> `for (var i| = 1 i < 5; i++) {}`. (`|` is the cursor again).\n\n# Scope\n\nFinally it's possible to set a different scope for each snippet in a file, overwriting the main mode set in the header. Use the scope variable to do this.\n\n```\nscope markdown\n```\n\n# Adding Snippets to a Bundle\n\nA bundle can contain one or more snippet files. Each snippet file *must* be placed in the `snippets` directory. \n\nSuppose your snippets file is called `markdown.snippets`. Your file structure will look something like this:\n\n```\n└─ your.plugin\n ├─ snippets\n | └─ markdown.snippets\n ├─ package.json\n └─ README.md\n```\n\n## Using snippets inside a project\n\nTo load the snippets you created inside a project, add it's name to the `package.json.\n\npackage.json\n```json\n{\n \"name\":\"your.plugin\",\n \"plugins\": {}\n}\n```\n\nThen open the init script from the cloud9 menu and add `your.plugin` to the plugins loaded at startup. \n\n```javascript\n services.pluginManager.loadPackage([\n \"~/.c9/plugins/your.plugin/package.json\"\n ])\n```","updates":["59f3880072784a002462acf9"],"order":4,"isReference":false,"hidden":false,"sync_unique":"","link_url":"","link_external":false,"_id":"551df5fdfa7f722d00db21f3","category":{"sync":{"isSync":false,"url":""},"pages":["551df5bfa77fec1700f6f296","551df5c9fa7f722d00db21f0","551df5dfa77fec1700f6f298","551df5eca7e98017009e3ede","551df5f4a77fec1700f6f29a","551df5fdfa7f722d00db21f3","551df609a7e98017009e3ee0","551f3c0450a0fc210057968e","552836448962f339009a67ab"],"title":"Cloud9 Bundle","slug":"cloud9-bundle","order":3,"from_sync":false,"reference":false,"_id":"551df586e52a0b23000c62b6","__v":9,"createdAt":"2015-04-03T02:05:58.352Z","project":"54d53c7b23010a0d001aca0c","version":"54d5635532d98b0d00384afb"},"__v":51,"project":"54d53c7b23010a0d001aca0c","user":"54cfa8e1a8a4fd0d00b7fd1d","githubsync":"","createdAt":"2015-04-03T02:07:57.531Z","parentDoc":null,"version":{"version":"0.1","version_clean":"0.1.0","codename":"","is_stable":true,"is_beta":true,"is_hidden":false,"is_deprecated":false,"categories":["54d5635632d98b0d00384afc","54d5635632d98b0d00384afd","54d5635632d98b0d00384afe","54d5635632d98b0d00384aff","54d5635632d98b0d00384b00","54d5635632d98b0d00384b01","54d5635632d98b0d00384b02","54d652097e05890d006f153e","54dd1315ca1e5219007e9daa","54e21e2b22de1c230094b147","54e68e62a43fe13500db3879","54fa1d3fe7a0ba2f00306309","551c453a23a1ee190034d19a","551df586e52a0b23000c62b6","551f39be6886f8230055f02a","55a6720751457325000e4d97"],"_id":"54d5635532d98b0d00384afb","project":"54d53c7b23010a0d001aca0c","__v":10,"createdAt":"2015-02-07T00:59:01.934Z","forked_from":"54d53c7c23010a0d001aca0f","releaseDate":"2015-02-07T00:59:01.934Z"}}

Snippets are small pieces of code that can be inserted via the completion box. Based on a *trigger* a piece of code is inserted that can have one or more areas that can be filled by the user using `[TAB]` to switch between them. The following example shows a snippet that is triggered by typing `ife[TAB]`. ``` snippet ife if (${1:true}) { ${2} } else { ${0} } ``` It inserts the if else construct and starts by selecting the word `true`. After changing that and pressing `[TAB]` the cursor moves to the body of the if. The last `[TAB]` will move the cursor to the body of the else. # Creating a Snippets File *Snippets work in a similar way as those for TextMate and Sublime Text* A snippets file is a collection of multiple snippets for a specific mode. It consists of a header with some meta data and a list of snippets below that. Currently, the only way to add custom snippets to a project is to create a plugin (as described [here](#section-adding-snippets-to-a-bundle)). ## Header The header specifies the *scope* for the snippets. The scope is a string that specifies the name of the mode to which these snippets are applied. ``` # scope: javascript ``` Use `_` to specify snippets for all scopes. Use a comma separated list if these snippets apply to several modes. ## Snippets The rest of the file contains snippets. Snippets start with a list of variable definitions and then a list of lines that contain the code of the snippet itself. ``` # Comment <field> <value> <field> <value> <tab>snippetcontents <tab>snippetcontents snippet ended ``` A file can contain any number of these underneath each other. # Creating a Snippet ## Insertion Points After inserting the snippet text the cursor will move to the first position after the inserted text, when there are no insertion points specified. Specifying insertion points using the `$` character and a number to specify their sequence. ``` ${1} ${2} etc ``` The `${0}` insertion point is always last in line. You can specify the text that is selected when jumping from one insertion point to the next one. ``` ${1:some_text} ``` In addition, it's possible to reuse the same variable multiple times. All instances will be selected using multiple cursors and changed at the same time when the user types. ``` for (var ${1:i}=0; $1 < ${2}; $1++) { ${0} } ``` ## Using Special Variables When triggering a snippet through a menu or command you can configure it to use the text selected prior to inserting the snippet in the resulting code. ``` (function(${1}) { ${0:${SELECTED_TEXT:/* code */}} }(${1})); ``` Similarly the following variables can be used to insert other special text. [block:html] { "html": "<table>\n<tr><th>CURRENT_WORD</th><td>The word at the cursor at the.</td></tr>\n<tr><th>SELECTION</th><td>The selected text.</td></tr>\n<tr><th>SELECTED_TEXT</th><td>The selected text.</td></tr>\n<tr><th>CURRENT_LINE</th><td>The current line.</td></tr>\n<tr><th>PREV_LINE</th><td>The previous line.</td></tr>\n<tr><th>LINE_INDEX</th><td>The index of the current line.</td></tr>\n<tr><th>LINE_NUMBER</th><td>The line number (index + 1).</td></tr>\n<tr><th>SOFT_TABS</th><td>\"YES\" or \"NO\".</td></tr>\n<tr><th>TAB_SIZE</th><td>The tab size.</td></tr>\n</table>" } [/block] ## Formatting Strings Variables that are inserted can be formatted using the following command: ``` ${«int»/«regexp»/«format»/«options»} ``` The following example comes from the markdown snippets and takes the contents of the previous line transforming each character into a `=`. That results in a line full of `===` exactly matching the length of the line above it. ``` snippet === regex /^/=+/=*// ${PREV_LINE/./=/g} ${0} ``` In addition the following characters can be used to toggle case. ``` \u uppercase next letter \l lowercase next letter \U uppercase until \ULE \E ends \U or \L ``` ## Triggers & Guards The examples above used a simple string of characters to define how a snippet is triggered. The snippet definition allows for more control in triggering snippets, introducing two concepts; `triggers` and `guards`. Both have a beginning marker called `trigger` and `guard` and an end marker called `endTrigger` and `endGuard`. These are all optional. Guards are pieces of a regular expression (regex) that define the context in which a trigger is allowed. Whatever is matched by a guard remains after insertion of the snippet - guards are not replaced. Triggers are also pieces of a regex that define the start (before the cursor) and end (after the cursor) of the text that will be replaced by the snippet contents. Lets start with a simple example. ``` snippet for ``` This can also be written like this. ``` guard \b trigger for endGuard endTrigger ``` Of course since the `endGuard` and `endTrigger` are empty they can be left out. Here's a more advanced example using a trigger to match `(f(|)` or `f(|)` or `f(|` where `|` is the cursor. ``` # Immediate function trigger $?f\( endTrigger $? snippet f( (function(${1}) { ${0:${SELECTED_TEXT:/* code */}} }(${1})); ``` ## Using a RegEx It's possible to replace the guards and trigger fields with a single regex that describes each. This regex below matches the start of a line (allowing white spaces) as a guard. It then is triggered by the `for` characters and `textafter` after the cursor, requiring at least 1 white space character, guarding the end of the sequence. ``` regex /^\s*/for/textafter/\s+/ ``` Use the regex capture groups to allow variables inserted in snippets. The captured items are available as variables `M1`, `M2`, etc. ``` ${M1?$M1: ${1:functionName}} ``` This allows you to create snippets with arguments; `for 1 5|` -> `for (var i| = 1 i < 5; i++) {}`. (`|` is the cursor again). # Scope Finally it's possible to set a different scope for each snippet in a file, overwriting the main mode set in the header. Use the scope variable to do this. ``` scope markdown ``` # Adding Snippets to a Bundle A bundle can contain one or more snippet files. Each snippet file *must* be placed in the `snippets` directory. Suppose your snippets file is called `markdown.snippets`. Your file structure will look something like this: ``` └─ your.plugin ├─ snippets | └─ markdown.snippets ├─ package.json └─ README.md ``` ## Using snippets inside a project To load the snippets you created inside a project, add it's name to the `package.json. package.json ```json { "name":"your.plugin", "plugins": {} } ``` Then open the init script from the cloud9 menu and add `your.plugin` to the plugins loaded at startup. ```javascript services.pluginManager.loadPackage([ "~/.c9/plugins/your.plugin/package.json" ]) ```

Cloud9 SDK

Getting Started

Development Workflow

License

Cloud9 Bundle

API Plugins

Editor Plugins

Runners & Debuggers

Plugin Base Classes

User Interface

Ace (text editor)

Language Modes

Language Tooling

Installer

Other