sublime-hooks

Run Sublime commands on common event hooks (e.g. on_new, on_post_save).

This was designed to give event level bindings to other Sublime plugins.

My use case was to make a request (via sublime-request to a server when a save occurs. The result was:

"on_post_save_user": [
  {
    "command": "request",
    "args": {
      "open_args": ["http://localhost:7060/"]
    },
    "scope": "window"
  }
]

Getting started

Installation

This package is available under hooks inside of Package Control, a Sublime Text plugin that allows for easy management of other plugins.

If you prefer the manual route, you can install the script via the following command in the Sublime Text terminal (ctrl+` ) which utilizes git clone.

import os; path=sublime.packages_path(); (os.makedirs(path) if not os.path.exists(path) else None); window.run_command('exec', {'cmd': ['git', 'clone', 'https://github.com/twolfson/sublime-hooks', 'hooks'], 'working_dir': path})

Packages can be uninstalled via "Package Control: Remove Package" via the command pallete, ctrl+shift+p on Windows/Linux, command+shift+p on Mac.

Creating a new hook

For this exercise, we will be creating a binding that selects all text after a save occurs.

A hook can be added at the User, Project, or Language level. We will add a User level hook.

To edit User settings, open the command pallete, and select "Preferences: Settings - User".

In the opened preferences, create a new key/value pair for on_post_save_user with the following:

"on_post_save_user": [
  {
    "command": "select_all"
  }
]

Then, save twice (once to save settings, another to trigger the plugin).

At this step, all text will be selected, demonstrating the hook and command were run.

Examples of user, project, and language hooks can be found below.

Documentation

Hooks are stored in the User, Project, or Language settings. Each of these expects a list of dictionaries. Each of those dictionaries satisfies the following:

command (required), Command for Sublime to run via run_command at the listed scope.
args (optional), Dictionary of arguments to be passed to . Comparable to args in "Key Bindings".
scope (optional), String indicating where to run command. By default, commands are run in the view. Other options are window and app which run at the window and sublime levels respectively.

"on_post_save_user": [
  {
    // Runs `request` command
    "command": "request",

    // Invokes `request` with `open_args=["http://...:7060/"]`
    "args": {
      "open_args": ["http://localhost:7060/"]
    },

    // Runs `request` via `window.run_command`
    "scope": "window"
  }
]

Accessing settings

User settings are accessed via "Preferences: Settings - User" in the command pallete.

Project settings are accessed via "Project -> Edit Project" from the menu bar. You must be in a saved project for this option to be accessible.

Language settings are accessed via "Preferences -> Settings - More -> Syntax Specific - User". This will open settings specifically for the language in the open file.

Namespacing

Hooks are required to be namespaced at the User, Project, or Language level. The key will be the event_name followed by its _level.

The namespaces are _user, _project, and _language.

For demonstration:

An on_new hook at the Project level will be on_new_project
An on_load at the Language level will be on_load_language

Events

For both Sublime Text 2 and 3, you will have access to the following events:

on_new
on_clone
on_load
on_close
on_pre_save
on_post_save
on_activated
on_deactivated

For Sublime Text 3, you gain access to:

on_new_async
on_clone_async
on_load_async
on_pre_close
on_pre_save_async
on_post_save_async
on_activated_async
on_deactivated_async

Documentation on each hook can be found in the Sublime Text documentation:

Sublime Text 2 - http://www.sublimetext.com/docs/2/api_reference.html#sublime_plugin.EventListener

Sublime Text 3 - http://www.sublimetext.com/docs/3/api_reference.html#sublime_plugin.EventListener

The events not on these lists were excluded due to potential performance issues (e.g. on_modified, on_text_command).

Examples

User

User settings should be defined at the top level in your user's .sublime-settings. This can be accessed either via the Preferences: Settings - User command palette or Preferences -> Settings - User in the menu.

// Inside Packages/User/Preferences.sublime-settings
{
  "ignored_packages": [
  // ...
  ],
  "on_post_save_user": [
    {
      "command": "select_all"
    }
  ]
}

Project

Project settings should be defined under a settings in your current .sublime-project. This can be accessed either via the Project: Edit command palette or Project -> Edit in the menu.

// Inside my-project.sublime-project
{
  "folders": [
  // ...
  ],
  "settings": {
    "on_post_save_project": [
      {
        "command": "select_all"
      }
    ]
  }
}

Language

Language settings should be defined at the top level in your language's .sublime-settings. This can be accessed via Preferences -> Settings - More -> Syntax Specific - User in the menu.

// Inside my-language.sublime-settings
{
  "extensions": [
  // ...
  ],
  "on_post_save_language": [
    {
      "command": "select_all"
    }
  ]
}

Donating

Support this project and others by twolfson via gittip.

Unlicense

As of Sep 04 2013, Todd Wolfson has released this repository and its contents to the public domain.

It has been released under the UNLICENSE.