Home » Support » Index of All Documentation » Wing IDE Reference Manual » Source Code Editor »

Wing Professional provides support for defining and using code snippets for commonly reused bits of code and other text. Snippets might be used for standard file skeletons, comment formats, dividers, class definitions, function definitions, HTML tables, and much more. Variants of snippets may be defined for different contexts, for example to include or omit self in a def depending on whether or not it is a method in a class.

Wing's snippet functionality is implemented in the Snippets tool panel and by providing the snippets by name in the editor's auto-completer. Key bindings can be assigned to snippets so that the snippets tool does not have to be visible in order to use a snippet.

Although Wing comes with a few example snippets, in most cases users will want to define their own, to match their coding conventions and preferences.

User Interface

The Snippets tool panel provides the means for adding, editing, removing, and executing snippets, and also assigning key bindings for pasting selected snippets into the current editor. Most of the functionality is provided by the options menu in the top right and by right clicking on the snippet list. Note that some of the operations (those followed by ... in the menus) will prompt for input at the bottom of Wing IDE's window.

The option menu in the top right of the Snippets tool (also accessible by right-clicking on the tab area) provides items for adding, removing, and renaming file types into which to organize snippets. The name of the file type is the file extension that Wing should use by default when creating a new file based on a snippet. It is also used to look up the mime type of the file, so that the snippet can be made available within any file of that type, regardless of its actual name. The * file type, which is always present, allows defining snippets that can be applied to all file types.

To add, edit, renamed, copy, and remove snippets, use the items in the context menu that appears when you right-click on the surface of the snippet list in the Snippets tool. This menu also provides items for inserting the snippet into the current file or a new file.

Contexts

It is possible to specify the context within the file for which a snippet is appropriate. This allows, for example, the definition of a snippet def that varies to include or omit self depending on whether or not it is within a class. When available, this is done with items in the snippet list context menu. The snippet defined for context all will be used when no specific context match is made. The default set of snippets that ship with Wing illustrate this feature with the def and class snippet variants.

The set of valid contexts depends on file type. For Python files the valid context names are module, class, method, function, comment, string. For HTML and XML, files are divided into content, code (within < and >), comment, and string. Other files only distinguish code, comment, and string. Additionally, the context all is used for all file types to indicate any context.

To set the context for a snippet, click on the context name in the snippet lists's Context column, or use the items in the right-click context menu on the snippet list.

Key Bindings

The snippet list context menu menu also allows assigning key bindings to snippets, so they can be executed more easily. The key binding entry area is shown at the bottom of the IDE window, and Enter is pressed to accept the displayed binding. Note that bindings can be multi-key sequences such as Ctrl-Shift-H Ctrl-A. Pressing the keys in sufficiently rapid succession creates a sequence. Waiting a moment will start a new sequence when further keys are pressed. Clicking away from the entry area will abort the operation without assigning any key binding.

Note that key bindings are assigned to the snippet by name and not to a particular snippet file. If multiple like-named snippets exists for different file types or contexts, the appropriate snippet is chosen when the key binding is used.

Execution and Data Entry

When snippets are executed, Wing chooses the snippet by name and places the correct variant according to the file type and the context within the current editor. The caret position on the editor is used to determine the context, so altering the position of the caret within leading indentation may alter which snippet variant Wing selects.

When a snippet is used, Wing will place default arguments into the snippet, convert indentation and line endings to match the target file, paste it into the active editor, and place the editor into inline data entry mode to collect additional arguments for the snippet.

In data entry mode, Wing will move between the data entry fields in the snippet when Tab or BackTab are pressed. The position within the snippet's fields will be displayed in the status area at the bottom of the editor window.

In this mode, the Indent and Outdent commands in the Indentation sub-group of Wing's Source menu (and their key equivalents) can be used to increase or decrease the indentation of the whole snippet within the editor. However, the same snippet variant that was used initially will be used regardless of subsequent changes in indentation.

To exit data entry mode, press Esc (or Ctrl-G in emacs mode) or move the caret outside of the pasted snippet. To undo the snippet insertion, use Undo in the Edit menu or its key binding.

Auto-completion

Snippets are also listed in the editor's auto-completer and may be activated from there. To disable this feature, turn off the auto-completer preference Include Snippets in Completer.

Snippet Syntax

Snippets are text files that contain markers where user-provided values should be inserted. These markers are similar to Python's %(varname)s string substitution syntax but instead of containing only a variable name, the body of the marker contains richer argument collection information in the following format, with vertical bars dividing each value:

%(varname|type|default)s

Type and default are optional but the vertical bars must be present if omitting type but including a default. To write a snippet that includes Python style string formats, escape each % by writing %% instead.

Each part is defined as follows:

varname -- The name of the variable. Since arguments are collected inline, this name is used internally only. Future extensions may display this name to the user, by replacing underscores with spaces and capitalizing words (for example "user_name" would be rendered "User Name"). If a variable name is used multiple times in a snippet, the same value will be inserted multiple times.

An @ prepended to the variable name indicates that the value should be wrapped if it exceeds the configured text wrap line column.

type -- The type of data to collect. Currently this is one of:

string(length) -- a string with given maximum length (uses default 80 chars if length is omitted)

date -- current date in locale's preferred format or in the time.strftime() format given in the environment variable __DATE_FORMAT__

datetime -- current date+time in locale's preferred format or in the time.strftime() format given in the environment variable __DATETIME_FORMAT__

If this field is omitted or empty, string is assumed.

default -- The default value to use. This may be the actual value, or may contain environment variable references in the form $(envname) or ${envname} to attempt to read all or part of the value from the named environment variable or one of the special variables enumerated in Environment Variable Expansion.

Environment variables can be specified either in the Debug tab of Wing's Project Properties or in the environment that exists before Wing is launched. Values in the Project Properties override any values set before starting Wing.

When this field is omitted, or when no default environment value can be found, the field will be left blank .

Indentation and Line Endings

Snippets should always use one tab for each level of indentation. Tabs will be replaced with the appropriate indentation type and size when the snippet is used in a new or existing file (either according to content of the target file or using the configured indent style and indent size for new files). Wing will force tab indentation in all newly created snippet files.

Similarly, line endings in snippets will be replaced with the appropriate type to match the file to which the snippet is applied. However, there is no requirement for snippet files to contain any particular kind of line ending.

If the snippet starts with |x| then x is a specification of how the indents in the snippet should be converted. It can be one of:

  • An integer: Re-indent as a block, like Wing's indent-region command, so the first line is at the given number of indent levels.
  • The character 'm': Re-indent as a block, like Wing's indent-to-match command, so the first line is at the expected indent level according to context in the source.
  • The character 'm' followed by '+' or '-' and an integer: Re-indent as for 'm' and then shift left or right by the given number of indents.

Any |x| at the start of a snippet file will be removed before the snippet is inserted into an editor.

Cursor Placement

Snippets can contain |!| to indicate the final resting position of the cursor after all other fields have been filled. When this is present, inline data entry mode is terminated automatically when this position is reached (after all other fields have been entered). The mark will be removed before snippets are inserted into an editor.

Snippet Directory Layout

Snippets are stored in the snippets directory in the user settings directory. The first time the Snippets tool is used, this directory is populated by making a copy of the default set of snippets that ship with Wing (these can be found in snippets within your Wing IDE installation).

File Types

This directory is organized by the file type to which they apply. Snippets stored at the top level of this directory can be used with any file in the editor and are shown in the * tab in the Snippets tool. Those stored in sub-directories are used only for files of a particular type. The name of the sub-directories is the file extension for that file type (for example py for Python). This is converted to a mime type so that the snippets are available for all files of that type, regardless of their naming. The name of the file type directory also provides the file extension to use for new untitled files when a snippet is pasted into a new file.

Contexts

When snippets are defined for a particular context within a file, they are stored in a sub-directory named context.ctx where context is replaced with the context name (see above). When a snippet is defined as the default, or without a particular context, it is stored in the top level of the file type directory.

Configuration

Wing also stores a configuration file in the user's snippets directory. This file is named .config and is used for internal book keeping. It should not be altered or removed, as this may cause the loss of your snippet files.

Commands

The following commands are available for invoking snippets:

snippet -- This will insert a snippet (selected by name) at the cursor in the current editor. If there is a non-empty selection on the editor, it will replace the selection. The editor will be placed into data entry mode for the collection of the snippet arguments.

snippet-file -- This will create a new file of the type specified by the snippet file's extension and insert the selected snippet into it before entering data entry mode in the editor for the collection of the snippet arguments.

In most cases, you will use the Assign Key Binding item in the Snippets tool's context menu to invoke these commands for a particular snippet.

Scripting Snippets

Wing's extension scripting API exposes the editor's data entry mode and snippet processing capabilities. This can be used to write scripts that generate snippets and paste them into the editor for user data entry. This approach may be preferable when the snippet markup language described above is not sufficient.

For details, see the PasteSnippet and StartDataEntry methods in wingapi.py and refer to Scripting and Extending Wing IDE.

« 4.9. File SetsTable of Contents4.11. Indentation »

Code Snippets