<type>documentation</type>
<domain>edit</domain>
<id>snippet-syntax</id>
<title>Snippet Syntax</title>
<date>$Date$</date>
<version>$Revision$</version>
<product>pro+</product>

Snippets are text files that contain the snippet text along with markup that indicates
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::
  
  %(varname|type|default)s

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

Each part is defined as follows:
  
**varname** is the name of the variable. 

  Since arguments are collected inline, this name is used internally only. If a variable
  name is used multiple times in a snippet, the value is collected where it first occurs and
  then inserted multiple times.

  **@** prepended to the variable name indicates that the value should be wrapped to
  the column specified with the `Editor > Line Wrapping > Reformat Wrap Column 
  <script:show_preferences_gui#prefname="edit.text-wrap-column">`__ preference.
  
  **!** prepended to the variable name indicates that the value should
  act as a tab stop even if its value is inserted from an earlier field with
  the same ``varname``.  This has no effect if the field name is unique.

**type** is the type of data to collect.  This is one of:

  **string(length)** expects a string with given maximum length (or 80 if length is omitted)
  
  **date** is the date in the Python's preferred format or in the ``time.strftime()`` style format 
    given in the environment variable ``__DATE_FORMAT__``.  This can be set in Wing's Project 
    Properties.  For example, to use day/month/year formatting for the date, set 
    ``__DATE_FORMAT=%d/%m/%Y`` in the ``Environment`` in ``Project Properties``.
  
  **datetime** is similarly the date and time in the Python's preferred format or in the
  ``time.strftime()`` style format given in the environment variable ``__DATETIME_FORMAT__``
  
  If the **type** field is omitted or empty, string is assumed.

**default** is the default value to use. 

  This may be the actual value, or may contain environment variable references in the form
  ``$(envname)`` or ``${envname}``.

  Environment variables can be specified in the environment that Wing inherits when it 
  is launched, in the ``Debug`` tab of Wing's `Project Properties 
  <script:view_project_properties#highlighted_attrib="proj.env-vars">`__, or may be
  selected from the set of special variables listed in `Environment Variable Expansion 
  <ref:proj/variable-expansion>`__.  Environment variables that are not found expand 
  to the empty string.
  
  When the ``default`` field is omitted, the field will start 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. The indentation style and size will be determined according to content of
the target file or for blank files by using the preferences `Editor > Indentation >
Default Indent Style <script:show_preferences_gui#prefname="edit.indent-style">`__ and
`Editor > Indentation > Default Indent Size
<script:show_preferences_gui#prefname="edit.indent-size">`__ .

Similarly, line endings in snippets will be replaced with the appropriate type to match
the file into which the snippet placed.

If the snippet starts with ``|x|`` then ``x`` is a specification of how all the
indents in the snippet should be converted. It can be one of:
  
  **The character 'm'** to re-indent as a block, so the first line is at the expected
  indent level for its context in the source.

  **An integer** to re-indent as a block, so the first line is at the given number 
  of indent levels.

  **The character 'm' followed by '+' or '-' and an integer** to 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 caret 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.
