cullmann/cullmann.io
1
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity
cullmann.io/themes/blowfish/.vscode/codesnippets-doc.md

11 KiB
Raw Blame History

Making VSCode Snippets

This info sourced from: VSCode's docs

A useful bit of info is that VSCode Snippets are intended to be compatible with textmate code snippets

Creating your own

File template snippets

You can add the isFileTemplate attribute to your snippet's definition if the snippet is intended to populate or replace a file's contents. File template snippets are displayed in a dropdown when you run the Snippets: Populate File from Snippet command in a new or existing file.

Snippet scope

Snippets are scoped so that only relevant snippets are suggested. Snippets can be scoped by either:

  1. the language(s) to which snippets are scoped (possibly all)
  2. the project(s) to which snippets are scoped (probably all)

Language snippet scope

Every snippet is scoped to one, several, or all ("global") languages based on whether it is defined in:

  1. a language snippet file
  2. a global snippet file

Single-language user-defined snippets are defined in a specific language's snippet file (for example javascript.json), which you can access by language identifier through Snippets: Configure User Snippets. A snippet is only accessible when editing the language for which it is defined.

Multi-language and global user-defined snippets are all defined in "global" snippet files (JSON with the file suffix .code-snippets), which is also accessible through Snippets: Configure User Snippets. In a global snippets file, a snippet definition may have an additional scope property that takes one or more language identifiers, which makes the snippet available only for those specified languages. If no scopeproperty is given, then the global snippet is available in all languages.

Most user-defined snippets are scoped to a single language, and so are defined in a language-specific snippet file.

Project snippet scope

You can also have a global snippets file (JSON with file suffix .code-snippets) scoped to your project. Project-folder snippets are created with the New Snippets file for ''... option in the Snippets: Configure User Snippets dropdown menu and are located at the root of the project in a .vscode folder. Project snippet files are useful for sharing snippets with all users working in that project. Project-folder snippets are similar to global snippets and can be scoped to specific languages through the scope property.

Snippet syntax

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:

Tabstops

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 occurrences of the same tabstop are linked and updated in sync.

Placeholders

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}}.

Choice

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.

Variables

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.

The following variables can be used:

TM_SELECTED_TEXT
The currently selected text or the empty string
TM_CURRENT_LINE
The contents of the current line
TM_CURRENT_WORD
The contents of the word under cursor or the empty string
TM_LINE_INDEX
The zero-index based line number
TM_LINE_NUMBER
The one-index based line number
TM_FILENAME
The filename of the current document
TM_FILENAME_BASE
The filename of the current document without its extensions
TM_DIRECTORY
The directory of the current document
TM_FILEPATH
The full file path of the current document
RELATIVE_FILEPATH
The relative (to the opened workspace or folder) file path of the current document
CLIPBOARD
The contents of your clipboard
WORKSPACE_NAME
The name of the opened workspace or folder
WORKSPACE_FOLDER
The path of the opened workspace or folder
CURSOR_INDEX
The zero-index based cursor number
CURSOR_NUMBER
The one-index based cursor number

Inserting the current date and time:

CURRENT_YEAR
The current year
CURRENT_YEAR_SHORT
The current year's last two digits
CURRENT_MONTH
The month as two digits (example '02')
CURRENT_MONTH_NAME
The full name of the month (example 'July')
CURRENT_MONTH_NAME_SHORT
The short name of the month (example 'Jul')
CURRENT_DATE
The day of the month as two digits (example '08')
CURRENT_DAY_NAME
The name of day (example 'Monday')
CURRENT_DAY_NAME_SHORT
The short name of the day (example 'Mon')
CURRENT_HOUR
The current hour in 24-hour clock format
CURRENT_MINUTE
The current minute as two digits
CURRENT_SECOND
The current second as two digits
CURRENT_SECONDS_UNIX
The number of seconds since the Unix epoch
CURRENT_TIMEZONE_OFFSET
The current UTC time zone offset as +HH:MM or -HH:MM (example -07:00).

Inserting random values:

RANDOM 6 random Base-10 digits RANDOM_HEX 6 random Base-16 digits UUID A Version 4 UUID

Inserting line or block comments, honoring the current language:

BLOCK_COMMENT_START
Example output: in PHP /* or in HTML <!--
BLOCK_COMMENT_END
Example output: in PHP */ or in HTML -->
LINE_COMMENT
Example output: in PHP //

Variable transforms

Transformations allow you to modify the value of a variable before it is inserted. The definition of a transformation consists of three parts:

  1. A regular expression that is matched against the value of a variable, or the empty string when the variable cannot be resolved.
  2. A "format string" that allows to reference matching groups from the regular expression. The format string allows for conditional inserts and simple modifications.
  3. Options that are passed to the regular expression.

The following example inserts the name of the current file without its ending, so from foo.txt it makes foo.

${TM_FILENAME/(.*)\\..+$/$1/}
  |           |         |  |
  |           |         |  |-> no options
  |           |         |
  |           |         |-> references the contents of the first
  |           |             capture group
  |           |
  |           |-> regex to capture everything before
  |               the final `.suffix`
  |
  |-> resolves to the filename

Placeholder-Transform

Like a Variable-Transform, a transformation of a placeholder allows changing the inserted text for the placeholder when moving to the next tab stop. The inserted text is matched with the regular expression and the match or matches - depending on the options - are replaced with the specified replacement format text. Every occurrence of a placeholder can define its own transformation independently using the value of the first placeholder. The format for Placeholder-Transforms is the same as for Variable-Transforms.

Transform examples

The examples are shown within double quotes, as they would appear inside a snippet body, to illustrate the need to double escape certain characters. Sample transformations and the resulting output for the filename example-123.456-TEST.js.

Example Output Explanation
"${TM_FILENAME/[\\.]/_/}" example-123_456-TEST.js Replace the first . with _
"${TM_FILENAME/[\\.-]/_/g}" example_123_456_TEST_js Replace each . or -with _
"${TM_FILENAME/(.*)/${1:/upcase}/}" EXAMPLE-123.456-TEST.JS Change to all uppercase
"${TM_FILENAME/[^0-9^a-z]//gi}" example123456TESTjs Remove non-alphanumeric characters

Grammar

Below is the EBNF (extended Backus-Naur form) for snippets. With \ (backslash), you can escape $, }, and \. Within choice elements, the backslash also escapes comma and pipe characters.

any         ::= tabstop | placeholder | choice | variable | text
tabstop     ::= '$' int
                | '${' int '}'
                | '${' int  transform '}'
placeholder ::= '${' int ':' any '}'
choice      ::= '${' int '|' text (',' text)* '|}'
variable    ::= '$' var | '${' var '}'
                | '${' var ':' any '}'
                | '${' var transform '}'
transform   ::= '/' regex '/' (format | text)+ '/' options
format      ::= '$' int | '${' int '}'
                | '${' int ':' '/upcase' | '/downcase' | '/capitalize' | '/camelcase' | '/pascalcase' '}'
                | '${' int ':+' if '}'
                | '${' int ':?' if ':' else '}'
                | '${' int ':-' else '}' | '${' int ':' else '}'
regex       ::= JavaScript Regular Expression value (ctor-string)
options     ::= JavaScript Regular Expression option (ctor-options)
var         ::= [_a-zA-Z] [_a-zA-Z0-9]*
int         ::= [0-9]+
text        ::= .*
if          ::= text
else        ::= text