.. include:: /include/substitutions.txt
.. include:: /include/external_links.txt
.. include:: /include/custom_roles.txt
.. _commands:

********
Commands
********

Commands are found throughout Sublime |nbsp| Text.  Almost all actions are carried out by
Commands.  Commands are connected to:

- menu options
- :term:`Key Bindings <Key Binding>`
- :term:`Command Palette` items

Plus you can run commands directly by calling: ``view.run_command('<command_name>',
{args})`` (e.g. in the :term:`Console` or from within a :term:`Plugin`).

Commands are also used by many types of Sublime |nbsp| Text resource files.  In essence,
Commands are the bread-and-butter of getting things done within Sublime |nbsp| Text.

You can see (and execute) most of the publicly-accessible Commands via the
Command Palette:  ``Tools > Command Palette...`` (normally ``ctrl+shift+p``).

You can also :ref:`create your own commands <creating new commands>` using Plugins.

See also https://docs.sublimetext.io/reference/commands.html .



Adding Existing Commands to Command Palette
*******************************************

When a packages implement new Commands that should also be available in the Command
Palette, they are added to it using a ``.sublime-commands`` file.



Variables Available in ``.sublime-commands`` Args
=================================================

Some commands take paths as parameters.  Among these, some commands
(e.g. ``open_file``) support variables passed in strings like
``${packages}/path/to/file.ext``.  These commands appear to not be preprocessed, but
instead are passed verbatim into the command and the command itself converts them.  So
what variables may be passed is up to the command.

Commands expect forward-slash directory separators in paths if not otherwise noted,
including on Windows (for example, ``/C/Program Files/Sublime Text/sublime_plugin.py``).

Often, relative paths in arguments to commands are assumed to start at the
:term:`<data_path>`.

A few commands

"${var_name}"  <-- from within a string, and
$var_name      <-- outside of a string

Variables currently known:

:$project:       path to project?
:$packages:      path
:$0:             specifies where cursor should go when inserting a snippet
:$platform:      (Windows|Linux|OSX)

Examples:

``Preferences > Settings`` uses the ``edit_settings`` command.

.. code-block:: json

    {
        "caption": "Preferences: Settings",
        "command": "edit_settings",
        "args":
        {
            "base_file": "${packages}/Default/Preferences.sublime-settings",
            "default": "// Settings in here override those in \"Default/Preferences.sublime-settings\",\n// and are overridden in turn by syntax-specific settings.\n{\n\t$0\n}\n"
        }
    },

When command-logging via ``sublime.log_commands(True)`` is turned on in the Console,
and ``Preferences: Settings`` is executed via the Command Palette, it results in the
following logged in the Console before opening the read-only version from with
Sublime |nbsp| Text's core.(This was when the new Settings window had not already been
opened previously.)

.. code-block:: text

    command: edit_settings {
        "base_file": "${packages}/Default/Preferences.sublime-settings",
        "default": "// Settings in here override those in \"Default/Preferences.sublime-settings\",\n// and are overridden in turn by syntax-specific settings.\n{\n\t$0\n}\n"
    }
    command: new_window
    command: set_layout {
        "cells": [[0, 0, 1, 1], [1, 0, 2, 1]], "cols": [0.0, 0.5, 1.0], "rows": [0.0, 1.0]
    }
    command: open_file {
        "file": "${packages}/Default/Preferences.sublime-settings"
    }
    command: open_file {
        "contents": "// Settings in here override those in \"Default/Preferences.sublime-settings\",\n// and are overridden in turn by syntax-specific settings.\n{\n\t$0\n}\n",
        "file": "C:\\Users\\Vic\\AppData\\Roaming\\Sublime Text\\Packages\\User\\Preferences.sublime-settings"
    }
    Unable to open /C/Users/Vic/AppData/Roaming/Sublime Text/Packages/Default/Preferences.sublime-settings
    command: exec {"update_annotations_only": true}
    command: exec {"update_annotations_only": true}

So it can be seen that the ``edit_settings`` command uses the ``open_file`` command
internally.

Note also the function of the ``$0`` variable in the "default" element.  It marks
where the cursor will be placed once the text is inserted.  When the user has not
created any custom settings, there is no
:term:`<data_path>`/Packages/User/Preferences.sublime-settings file so Sublime |nbsp| Text
creates one and places this as its content:

.. code-block:: text

    // Settings in here override those in "Default/Preferences.sublime-settings",
    // and are overridden in turn by syntax-specific settings.
    {
        |  <-- cursor is placed here
    }

which does not get written to disk until the user saves it.

----

This is found in ``Context.sublime-menu`` (context menu within an open file), creating
the "Open Containing Folder…" option:

.. code-block:: json

    { "command": "open_dir", "args": {"dir": "$file_path", "file": "$file_name"}, "caption": "Open Containing Folder…" },

passing the above strings into the "dir" and "file" arguments.  It causes the OS's
File Explorer to open and focus placed upon the target file.  Nice touch.

----

The following is from ``Main.sublime-menu`` in the Preferences menu:

.. code-block:: json


            {
                "command": "edit_settings", "args":
                {
                    "base_file": "${packages}/Default/Default ($platform).sublime-keymap",
                    "default": "[\n\t$0\n]\n"
                },
                "caption": "Key Bindings"
            },
            {
                "command": "edit_settings", "args":
                {
                    "base_file": "${packages}/Default/Default ($platform).sublime-mousemap",
                    "default": "[\n\t$0\n]\n"
                },
                "caption": "Mouse Bindings"
            },

It is clear that these are used in a variety of ways:  ``${packages}`` and
bare ``$platform``, both inside a string.



Further Reading
***************

A relatively-complete list of commands exists in the `Unofficial Documentation
Commands Page <https://docs.sublimetext.io/reference/commands.html>`__.