<align="center">
<img src="https://raw.githubusercontent.com/yatki/vscode-surround/master/images/logo.png">
<align="center">
A simple yet powerful extension to add wrapper snippets around your code blocks.
</align=>
## Features
- Now works on [VSCode for Web](https://code.visualstudio.com/docs/editor/vscode-web) π**New!**
- Supports **language identifiers**
- Supports **multi** selections
- Fully **customizable**
- **Custom** wrapper snippets
- You can assign **shortcuts** for _each_ wrapper snippets separately
- Nicely formatted (Preserves indentations)
- Sorts recently used snippets on top
### Demo 1: Choosing a wrapper snippet from quick pick menu
### Demo 2: Wrapping multi selections
## How To Use
After selecting the code block, you can
- **right click** on selected code
- OR press (ctrl+shift+T) or (cmd+shift+T)
to get list of commands and pick one of them.
> Hint
>
> Each wrapper has a **separate command** so you can define keybindings for your favorite wrappers by searching `surround.with.commandName` in the 'Keyboard Shortcuts' section.
### List of commands
| Command | Snippet |
| -------------------------------------------------- | --------------------------------------------------------------- |
| `surround.with` (ctrl+shift+T) | List of all the enabled commands below |
| `surround.with.if` | if ($condition) { ... } |
| `surround.with.ifElse` | if ($condition) { ... } else { $else } |
| `surround.with.tryCatch` | try { ... } catch (err) { $catchBlock } |
| `surround.with.tryFinally` | try { ... } finally { $finalBlock } |
| `surround.with.tryCatchFinally` | try { ... } catch (err) {$catchBlock} finally { $finalBlock } |
| `surround.with.for` | for ($1) { ... } |
| `surround.with.fori` | for (let i = 0; ... ; i = i + 1) { ... } |
| `surround.with.forEach` | items.forEach((item) => { ... }) |
| `surround.with.forEachAsync` | items.forEach(async (item) => { ... }) |
| `surround.with.forEachFn` | items.forEach(function (item) { ... }) |
| `surround.with.forEachAsyncFn` | items.forEach(async function (item) { ... }) |
| `surround.with.arrowFunction` | const $name = ($params) => { ... } |
| `surround.with.asyncArrowFunction` | const $name = async ($params) => { ... } |
| `surround.with.functionDeclaration` | function $name ($params) { ... } |
| `surround.with.asyncFunctionDeclaration` | async function $name ($params) { ... } |
| `surround.with.functionExpression` | const $name = function ($params) { ... } |
| `surround.with.asyncFunctionExpression` | const $name = async function ($params) { ... } |
| `surround.with.element` | \<element\>...\</element\> |
| `surround.with.comment` | /\*\* ... \*/ |
| `surround.with.region` | #region $regionName ... #endregion |
| `surround.with.templateLiteral` π**New!** | `...` (Also replaces single and double quotes with backtick) |
| `surround.with.templateLiteralVariable` π**New!** | `${...}` (Also replaces single and double quotes with backtick) |
| `surround.with.iife` π**New!** | (function $name($params){ ... })($arguments); |
## Options
- `showOnlyUserDefinedSnippets` (boolean): Disables default snippets that comes with the extension and shows only used defined snippets.
- `showRecentlyUsedFirst` (boolean): Recently used snippets will be displayed on top.
- `showUpdateNotifications` (boolean): Shows notification when there is a new version of the extension.
## Configuration
Each wrapper snippet config object is defined as `ISurroundItem` like below:
```ts
interface ISurroundItem {
label: string; // must be unique
description?: string;
detail?: string;
snippet: string; // must be valid SnippetString
disabled?: boolean; // default: false
languageIds?: string[];
}
Go to "Settings" and search for "surround.with.commandName".
Example surround.with.if:
{
"label": "if",
"description": "if ($condition) { ... }",
"disabled": false,
"snippet": "if(${1:condition}) {\n\t$TM_SELECTED_TEXT\n}$0"
}Go to "Settings" and search for surround.custom and edit it like below.
{
"surround.custom": {
// command name must be unique
"yourCommandName": {
// label must be unique
"label": "Your Snippet Label",
"description": "Your Snippet Description",
"snippet": "burrito { $TM_SELECTED_TEXT }$0", // <-- snippet goes here.
"languageIds": ["html", "javascript", "typescript", "markdown"]
},
// You can add more ...
}
}With version 1.1.0, you can define snippets based on the document type by using languageIds option.
Visit VSCode docs the full list of language identifiers.
If you want to allow a snippet to work for all document types, simply REMOVE languageIds option.
OR set it to ["*"] as below:
{
"label": "if",
"description": "if ($condition) { ... }",
"disabled": false,
"snippet": "if(${1:condition}) {\n\t$TM_SELECTED_TEXT\n}$0",
"languageIds": ["*"] // Wildcard allows snippet to work with all languages
}If you want to allow a snippet to work with html, typescript and typescriptreact documents, you can use the example below.
{
"label": "if",
"description": "if ($condition) { ... }",
"disabled": false,
"snippet": "if(${1:condition}) {\n\t$TM_SELECTED_TEXT\n}$0",
"languageIds": ["html", "typescript", "typescriptreact"]
}If you want to allow a snippet to work with all document types EXCEPT html, typescript and typescriptreact documents,
you can add - (MINUS) sign as a prefix to the language identifiers (without a whitespace).
{
"label": "if",
"description": "if ($condition) { ... }",
"disabled": false,
"snippet": "if(${1:condition}) {\n\t$TM_SELECTED_TEXT\n}$0",
"languageIds": ["*", "-html", "-typescript", "-typescriptreact"]
}- All command names and labels must be unique. If you do not provide a unique command name or label, your custom wrapper functions will override existing ones.
- You can redefine all snippets as long as you provide a valid
SnippetString. Read More
As always, I'm open to any contribution and would like to hear your feedback.
PS: Guide for running @vscode/test-web on WSL 2
If you are planning to contribute to any open source project, before starting development, please always open an issue and make a proposal first. This will save you from working on features that are eventually going to be rejected for some reason.
I designed the logo on canva.com and inspired by one of their free templates.
MIT (c) 2021 Mehmet YatkΔ±
Enjoy!