|
| 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 | +CARBON?? |
| 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 is available (see [here](/docs/editor/extension-gallery.md#browse-and-install-extensions) for more instructions on installing an extension). |
| 28 | + |
| 29 | +The following popular extensions include snippets in their language support: |
| 30 | + |
| 31 | +<div class="marketplace-extensions-snippets"></div> |
| 32 | + |
| 33 | +> Tip: The preceding extensions 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 is inserted 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 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) article 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 invokes the 'Insert Snippet'-action but instead of letting you select a snippet it runs 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