============== Metadata Files ============== Overview ======== Metadata are parameters that can be assigned to certain text sections using scope selectors. .. XXX ref scope selectors These paremeters can be used for many purposes; for example: - specifying the current comment markers, even within embedded source code, so that you can toggle comments in any syntax, - defining rules for auto-indentation, - marking symbols that Sublime Text will allow you to :ref:`browse to quickly `. .. Link to the separate comment and symbol sections from here Furthermore, snippets can access metadata declared in the ``shellVariables`` setting, which allows you to create a snippet that has different contents depending on where it's used. File Format =========== Metadata files have the ``.tmPreferences`` extension and use the Property List format. The file name is ignored by Sublime Text. Metadata files are inherited from TextMate. Example ======= Here's an example of a metadata file: .. code-block:: xml name JavaScript Metadata scope source.js settings decreaseIndentPattern ^(.*\*/)?\s*\}.*$ increaseIndentPattern ^.*\{[^}"']*$ bracketIndentNextLinePattern (?x) ^ \s* \b(if|while|else)\b [^;]* $ | ^ \s* \b(for)\b .* $ shellVariables name TM_COMMENT_START value // name TM_COMMENT_START_2 value /* name TM_COMMENT_END_2 value */ uuid BC062860-3346-4D3B-8421-C5543F83D11F The example file combines several types of metadata. Structure of a Metadata File ============================ All metadata files share the same topmost structure, which is inherited from the Property List format. .. code-block:: xml ... Sublime Text uses the following topmost keys in metadata files; all others are ignored by default. ``name`` Optional. Name of the metadata. Ignored by Sublime Text. .. code-block:: xml name Shell Variables ``scope`` Required. Scope selector to determine in which context the metadata should be available. .. XXX: refer to scopes here .. code-block:: xml scope source.python ``settings`` Required. Container for settings. .. code-block:: xml settings ... ``uuid`` Optional. A unique identifier for the file. Ignored by Sublime Text. .. code-block:: xml uuid BC062860-3346-4D3B-8421-C5543F83D11F Subelements of ``settings`` =========================== The ``settings`` element can contain subelements for different purposes, which will be grouped in the following sections. Some subelements have certain functionality associated with them by default, while others can only be accessed via the :ref:`API `. Indentation Options (Children of ``settings``) ---------------------------------------------- Indentation options control aspects of the auto-indentation mechanism. ``increaseIndentPattern`` Regex. If it matches on the current line, the next line will be indented one level further. .. code-block:: xml increaseIndentPattern insert regex here ``decreaseIndentPattern`` Regex. If it matches on the current line, the next line will be unindented one level. .. code-block:: xml decreaseIndentPattern insert regex here ``bracketIndentNextLinePattern`` Regex. If it matches on the current line, only the next line will be indented one level further. .. code-block:: xml bracketIndentNextLinePattern insert regex here ``disableIndentNextLinePattern`` Regex. If it matches on the current line, the next line will not be indented further. .. code-block:: xml disableIndentNextLinePattern insert regex here ``unIndentedLinePattern`` Regex. The auto-indenter will ignore lines matching this regex when computing the next line's indentation level. .. code-block:: xml unIndentedLinePattern insert regex here Completions Options (Child of ``settings``) ------------------------------------------- Completion options control aspects of the completions mechanism. ``cancelCompletion`` Regex. If it matches on the current line, supresses the autocomplete popup. .. code-block:: xml cancelCompletion insert regex here Symbol Definitions (Child of ``settings``) ------------------------------------------ Documentation for symbol definitions was moved to a separate page: :ref:`Symbol Definition settings `. .. _md-shell-variables: Shell Variables (Child of ``settings``) --------------------------------------- Shell variables are used for different purposes and can be accessed from snippets. .. XXX: uncomment once reference exists .. .. seealso:: .. :doc:`snippets` Using shell variables in snippets. Note that shell variables are defined as dictionaries in an array, and thus have a different format from ``settings`` subelements. ``shellVariables`` Container for "shell variables". .. code-block:: xml shellVariables ... ``shellVariables`` Subelements ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Subelements of ``shellVariables`` are dictionaries with ``name`` and ``value`` keys. .. code-block:: xml name BOOK_OPENING value Once upon a time... .. seealso:: :ref:`Comments ` Shell variables defining comment markers. .. _md-api: Related API Functions ===================== To extract metadata information from plugin code, you can use the ``view.meta_info(key, point)`` API call. .. XXX: add reference to view.meta_info(key, point)