Dynamic Sublime Commands

This package enables you to add dynamic sublime configurations. Dynamic means, that you do not have to put this configurations into packages folder, but you can manage it with your project. Dynamic commands are active for views of files, which are in same folder like configurations or subfolder of configurations.

You can add commands using following filetypes:

• python file named sublime_commands.py
• sublime-commands file named local.sublime-commands
• a local directory named sublime or .sublime, containing any sublime configurations (snippets, keymaps, etc.)

If you have opened a view, there is looked for these files in the current view's file folder and each parent folder stopping at opened folders (or root folder). Additionally there are added all commands from command files found in opened folders of this windows. All commands found are joined and made available as commands in current view.

This way you can add project specific commands as you like.

You may use following variables in command captions (in example, we have command file /path/to/sublime_commands.py):

Variable	Description	Example
${cmdfile}	full path of command file	/path/to/sublime_commands.py
${cmdfilename}	filename of commandfile	sublime_commands.py
${cmddir}	path of directory of command file	/path/to
${cmddirname}	name of directory of command file	to

Local Configuration Directories

You can add directories named sublime or .sublime at any place. If you edit a file lower in directory tree, all configurations set up in these folders will be available. This way you can create local or project-specific keymaps, snippets, etc.

Sublime Commands Files

This mechanism enables you to add sublime command file containing sublime commands outside of package dir and create project specific or folder specific commands.

These are most portable files, but also not so flexible.

You have to name such a file local.sublime-commands or .sublime-commands

Python files

If you create a file named sublime_commands.py it will be interpreted as sublime commands. This means there is looked for all global instances of SublimeCommands class provided by sublime_commands module. Please use decorator and factory function sublime_command for creating sublime commands.

You should start your sublime_commands.py with following preamble:

from sublime_commands import *

Create a command displayed as "hello_world" in Command Palette:

@sublime_command
def hello_world(output):
    output.write("hello world")

Create a command displayed as "Hello World" in Command Palette:

@sublime_command("Hello World")
def hello_world2(output):
    output.write("Hello World.")

Create a command, which asks user to input "user":

@sublime_command("Hello ??")
def greetings_to(output, user="Mr. Snicket"):
    output.write("Hello %s" % user)

Create a command, which executes a little shell script:

shell_command1 = sublime_command("Hello World", """
    echo "Hello World"
    echo "Hello outside"
    """)

Same with an input, which defaults to "Mr. Snicket":

shell_command2 = sublime_command("Hello World", """
    echo "Hello World"
    echo "Hello ${user}"
    """,
    input = dict(user = "Mr. Snicket")
    )

You can create a factory function, which adds a symbol to your globals:

def shell_factory(name, *args, **kargs):
    G = globals()
    G[make_symbol(name)] = sublime_command(name, *args, **kargs)

Then it becomes easier to create a shell command:

shell_factory("Hello World 2", """
    echo "Hello World"
    echo "Hello outside"
    """)

Apart from variables taken from input, you can use following variables :hidden: shell commands:

• ${filename} - filename of current view
• ${filedir} - directory of file in current view
• ${filedirname} - directory of file in current view
• ${cmdfile} - directory of command file, where this command is from
• ${cmddir} - directory of dir of command file
• ${cmddirname} - directory of dir of command file
• ${cwd} - current working directory

Here some command, which has special behaviour on windows:

shell_command2 = sublime_command("Platform Specific", """
    echo "this is done on all non-windows platforms"
    """,
    windows = """
        echo "this is displayed on windows platform"
    """,
    )

In same way you can add commands which are osx- or linux-specific.

You can use following variables as non-keyword arguments for your command functions:

• output, a file-like object, which you can use to write to output panel.
• filename, the filename of currend view
• cmdfile, the filename of command file
• window, window object of current window
• command_object, current SublimeCommand object

The user will be prompted for values for all keyword arguments.

sublime_command itself accepts following keyword arguments, if used for creating shell commands (first two arguments are strings):

• workdir, either a concrete working directory, or a function expecting cmdfile and filename as input and calculates the workdir.

  Defaults to directory of command file.

• input, a dictionary, which is used for user input.

• shell, defaults true, if shell shall be invoked to run given command.

• windows, specify windows specific command

• osx, specify osx-specific command

• linux, specify linux-specific command

• executable may be either a string for specifying the shell executable to invoke, or a dictionary of platform names specifying shells for special platforms:

  x = sublime_command("My Command", """
    echo "unix like code"
    """,
    executable = dict(windows = "path/to/powershell"),
    windows = """
       powershell code
    """
    )
  

  Note

  it is intended to be able to use it as above, but it may be that there is little tweaking needed in windows to do it like this (maybe write code into temporary file before executing).

local_config

Having sublime_commands.py file, you can also add any other local configuration file:

from sublime_commands import *
import os

mydir = os.path.dirname(__file__)
local_config(os.path.join(mydir, "my.sublime-snippet"))

This would add my.sublime-snippet file if sublime_commands.py gets active.

You can do more with local config command:

for file in os.listdir(mydir):
    local_config(file, pattern=r"\.sublime-")

This will add all files which match regular expression \.sublime-.

You can use a shortcut for this:

local_config(mydir, pattern=r"\.sublime-", recurse=False)

If you want to walk a directory tree, finding all files matching some pattern:

local_config(mydir, pattern=r"\.sublime-")

If you want to add all files under some special sublime-config files folder:

local_config(mydir+"/sublime")

There are following arguments for local_config:

- ``path`` - path of either a directory or a file
- ``pattern`` - if path does not match pattern (if given), nothing happens
- ``recurse`` - if path specifies a directory, there will be taken all

files in directory.

• dest - if given use this as destination filename (path must specify a file)

Contributions

There are following modules contributed:

sublime_commands.mercurial_view

This module provides some Mercurial commands refering to the nearest mercurial repository of this file (so closest parent folder containg a .hg folder). In your sublime_commands.py write:

from sublime_commands.mercurial_view import *

sublime_commands.mercurial

This module provides Mercurial commands referring to repository, where your sublime_commands.py is in:

from sublime_commands.mercurial import *

sublime_commands.mercurial_subrepos

Basically same like sublime_commands.mercurial, but it includes Subrepository flag, such that commands handle repository trees:

from sublime_commands.mercurial_subrepos import *

Future

• Add hotkeys to commands
• Support any language using a simple protocol to get commands from a script
• provide variables in environment
• test PowerShell