|
| 1 | +--- |
| 2 | +title: Code snippets in Carbon | Microsoft Docs |
| 3 | +description: Learn how to add code snippets to Carbon, for your own use or to share. |
| 4 | +services: sql-database |
| 5 | +author: stevestein |
| 6 | +ms.author: sstein |
| 7 | +manager: craigg |
| 8 | +ms.reviewer: achatter, alayu, erickang, sanagama, sstein |
| 9 | +ms.service: data-tools |
| 10 | +ms.workload: data-tools |
| 11 | +ms.prod: NEEDED |
| 12 | +ms.topic: article |
| 13 | +ms.date: 10/08/2017 |
| 14 | +--- |
| 15 | +# Create code snippets to easily reuse in Carbon |
| 16 | + |
| 17 | +Code snippets are templates that make it easier to enter repeating code patterns, such as loops or conditional-statements. |
| 18 | + |
| 19 | +Snippets show in IntelliSense (`kb(editor.action.triggerSuggest)`) mixed with other suggestions as well as in a dedicated snippet picker (**Insert Snippet** in the Command Palette). There is also support for tab-completion: Enable it with `"editor.tabCompletion": true`, type a *snippet prefix*, and press `kb(insertSnippet)` to insert a snippet. |
| 20 | + |
| 21 | +The snippet syntax follows the [TextMate snippet syntax](https://manual.macromates.com/en/snippets) with the exception of 'interpolated shell code', which is not supported. |
| 22 | + |
| 23 | + |
| 24 | + |
| 25 | +## Add Snippets from the Marketplace |
| 26 | + |
| 27 | +Many [extensions](/docs/editor/extension-gallery.md) on the VS Code [Marketplace](https://marketplace.visualstudio.com/vscode) include snippets. If you find one you want to use, install it and restart VS Code and the new snippet will be available (see [here](/docs/editor/extension-gallery.md#browse-and-install-extensions) for more instructions on installing an extension). |
| 28 | + |
| 29 | +Below are some popular extensions which include snippets in their language support: |
| 30 | + |
| 31 | +<div class="marketplace-extensions-snippets"></div> |
| 32 | + |
| 33 | +> Tip: The extensions shown above are dynamically queried. Click on an extension tile above to read the description and reviews to decide which extension is best for you. See more in the [Marketplace](https://marketplace.visualstudio.com/vscode). |
| 34 | +
|
| 35 | +## Creating your Own Snippets |
| 36 | + |
| 37 | +You can define your own snippets for specific languages. To open up a snippet file for editing, open **User Snippets** under **File** > **Preferences** (**Code** > **Preferences** on Mac) and select the language for which the snippets should appear. |
| 38 | + |
| 39 | +Snippets are defined in a JSON format and stored in a per user `(languageId).json` file. For example, Markdown snippets go in a `markdown.json` file. |
| 40 | + |
| 41 | +The example below is a `For Loop` snippet for `JavaScript`. |
| 42 | + |
| 43 | +```json |
| 44 | + "For Loop": { |
| 45 | + "prefix": "for", |
| 46 | + "body": [ |
| 47 | + "for (var ${1:index} = 0; ${1:index} < ${2:array}.length; ${1:index}++) {", |
| 48 | + "\tvar ${3:element} = ${2:array}[${1:index}];", |
| 49 | + "\t$0", |
| 50 | + "}" |
| 51 | + ], |
| 52 | + "description": "For Loop" |
| 53 | + }, |
| 54 | +``` |
| 55 | + |
| 56 | +In the example above: |
| 57 | + |
| 58 | +* `For Loop` is the snippet name |
| 59 | +* `prefix` defines how this snippet is selected from IntelliSense and tab completion. In this case `for`. |
| 60 | +* `body` is the content and either a single string or an array of strings of which each element will be inserted as separate line. |
| 61 | +* `description` is the description used in the IntelliSense drop down |
| 62 | + |
| 63 | +The example above has three placeholders, `${1:index}`, `${2:array}`, and `${3:element}`. You can quickly traverse them in the order of their number. The string after the number and colon is filled in as default. |
| 64 | + |
| 65 | +Once you have added a new snippet, you can try it out right away, no restart needed. |
| 66 | + |
| 67 | +## Snippet Syntax |
| 68 | + |
| 69 | +The `body` of a snippet can use special constructs to control cursors and the text being inserted. The following are supported features and their syntaxes: |
| 70 | + |
| 71 | +### Tabstops |
| 72 | + |
| 73 | +With tabstops, you can make the editor cursor move inside a snippet. Use `$1`, `$2` to specify cursor locations. The number is the order in which tabstops will be visited, whereas `$0` denotes the final cursor position. Multiple tabstops are linked and updated in sync. |
| 74 | + |
| 75 | +### Placeholders |
| 76 | + |
| 77 | +Placeholders are tabstops with values, like `${1:foo}`. The placeholder text will be inserted and selected such that it can be easily changed. Placeholders can be nested, like `${1:another ${2:placeholder}}`. |
| 78 | + |
| 79 | +### Choice |
| 80 | + |
| 81 | +Placeholders can have choices as values. The syntax is a comma separated enumeration of values, enclosed with the pipe-character, for example `${1|one,two,three|}`. When the snippet is inserted and the placeholder selected, choices will prompt the user to pick one of the values. |
| 82 | + |
| 83 | +### Variables |
| 84 | + |
| 85 | +With `$name` or `${name:default}` you can insert the value of a variable. When a variable isn’t set, its *default* or the empty string is inserted. When a variable is unknown (that is, its name isn’t defined) the name of the variable is inserted and it is transformed into a placeholder. |
| 86 | + |
| 87 | +The following variables can be used: |
| 88 | + |
| 89 | +* `TM_SELECTED_TEXT` The currently selected text or the empty string |
| 90 | +* `TM_CURRENT_LINE` The contents of the current line |
| 91 | +* `TM_CURRENT_WORD` The contents of the word under cursor or the empty string |
| 92 | +* `TM_LINE_INDEX` The zero-index based line number |
| 93 | +* `TM_LINE_NUMBER` The one-index based line number |
| 94 | +* `TM_FILENAME` The filename of the current document |
| 95 | +* `TM_FILENAME_BASE` The filename of the current document without its extensions |
| 96 | +* `TM_DIRECTORY` The directory of the current document |
| 97 | +* `TM_FILEPATH` The full file path of the current document |
| 98 | + |
| 99 | +### Variable Transforms |
| 100 | + |
| 101 | +Transformations allow you to modify the value of a variable before it is inserted. The definition of a transformation consists of three parts: |
| 102 | + |
| 103 | +1. A regular expression that is matched against the value of a variable, or the empty string when the variable cannot be resolved. |
| 104 | +2. A "format string" that allows to reference matching groups from the regular expression. The format string allows for conditional inserts and simple modifications. |
| 105 | +3. Options that are passed to the regular expression. |
| 106 | + |
| 107 | +The following example inserts the name of the current file without its ending, so from `foo.txt` it makes `foo`. |
| 108 | + |
| 109 | +``` |
| 110 | +${TM_FILENAME/(.*)\..+$/$1/} |
| 111 | + | | | | |
| 112 | + | | | |-> no options |
| 113 | + | | | |
| 114 | + | | |-> references the contents of the first |
| 115 | + | | capture group |
| 116 | + | | |
| 117 | + | |-> regex to capture everything before |
| 118 | + | the final `.suffix` |
| 119 | + | |
| 120 | + |-> resolves to the filename |
| 121 | +``` |
| 122 | + |
| 123 | +### Grammar |
| 124 | + |
| 125 | +Below is the EBNF ([extended Backus-Naur form](https://en.wikipedia.org/wiki/Extended_Backus-Naur_form)) for snippets. With `\` (backslash), you can escape `$`, `}` and `\`. Within choice elements, the backslash also escapes comma and pipe characters. |
| 126 | + |
| 127 | +``` |
| 128 | +any ::= tabstop | placeholder | choice | variable | text |
| 129 | +tabstop ::= '$' int | '${' int '}' |
| 130 | +placeholder ::= '${' int ':' any '}' |
| 131 | +choice ::= '${' int '|' text (',' text)* '|}' |
| 132 | +variable ::= '$' var | '${' var }' |
| 133 | + | '${' var ':' any '}' |
| 134 | + | '${' var '/' regex '/' (format | text)+ '/' options '}' |
| 135 | +format ::= '$' int | '${' int '}' |
| 136 | + | '${' int ':' '/upcase' | '/downcase' | '/capitalize' '}' |
| 137 | + | '${' int ':+' if '}' |
| 138 | + | '${' int ':?' if ':' else '}' |
| 139 | + | '${' int ':-' else '}' | '${' int ':' else '}' |
| 140 | +regex ::= JavaScript Regular Expression value (ctor-string) |
| 141 | +options ::= JavaScript Regular Expression option (ctor-options) |
| 142 | +var ::= [_a-zA-Z] [_a-zA-Z0-9]* |
| 143 | +int ::= [0-9]+ |
| 144 | +text ::= .* |
| 145 | +``` |
| 146 | + |
| 147 | +## Using TextMate snippets |
| 148 | + |
| 149 | +You can also use existing TextMate snippets (.tmSnippets) with VS Code. See the [Using TextMate Snippets](/docs/extensions/themes-snippets-colorizers.md#using-textmate-snippets) topic in our Extension Authoring section to learn more. |
| 150 | + |
| 151 | +## Assign keybindings to snippets |
| 152 | + |
| 153 | +We already know that snippets can be inserted via IntelliSense, the 'Insert Snippet'-action, or via tab-completion. That's not all. You can create custom keybindings to insert specific snippets. Open `keybindings.json`, which defines all your keybindings, and something add this: |
| 154 | + |
| 155 | +```json |
| 156 | +{ |
| 157 | + "key": "cmd+k 1", |
| 158 | + "command": "editor.action.insertSnippet", |
| 159 | + "when": "editorTextFocus", |
| 160 | + "args": { |
| 161 | + "snippet": "console.log($1)$0" |
| 162 | + } |
| 163 | +} |
| 164 | +``` |
| 165 | + |
| 166 | +It will invoke the 'Insert Snippet'-action but instead of letting you select a snippet it will run on the provided snippet. Also, instead of `snippet` you can have `langId` and `name` arguments to reference an existing snippet: `{ "langId": "csharp", "name": "myFavSnippet" }` |
| 167 | + |
| 168 | + |
| 169 | +## Next Steps |
| 170 | + |
| 171 | +* [Command Line](/docs/editor/command-line.md) - VS Code has a rich command line interface to open or diff files and install extensions. |
| 172 | +* [Extending Visual Studio Code](/docs/extensions/overview.md) - Learn about other ways to extend VS Code. |
| 173 | +* [Themes, Snippets, and Colorizers](/docs/extensions/themes-snippets-colorizers.md) - You can package themes, snippets and language colorizers for use in VS Code. |
| 174 | + |
| 175 | +## Common Questions |
| 176 | + |
| 177 | +**Q: What if I want to use existing TextMate snippets from a .tmSnippet file?** |
| 178 | + |
| 179 | +**A:** You can easily package TextMate snippets files for use in VS Code. See [Using TextMate Snippets](/docs/extensions/themes-snippets-colorizers.md#using-textmate-snippets) in our Extension Authoring documentation. |
0 commit comments