/AAAPackageDev

Tools to ease the creation of snippets, syntax definitions, etc. for Sublime Text.

Primary LanguagePythonOtherNOASSERTION

AAAPackageDev

status: beta

Overview

AAAPackageDev helps create and edit snippets, completions files, build systems and other Sublime Text extensions.

The general workflow looks like this:

  • run new_* command (new_raw_snippet, new_completions, new_syntax_def...)
  • edit file (with specific snippets, completions, higlighting, build systems...)
  • save file

AAAPackageDev new_* commands are typically accessible through the Command Palette (Ctrl+Shift+P).

Getting Started

  1. Download and install AAAPackageDev. (See installation instructions for .sublime-package files.)
  2. Access commands from Tools | Packages | Package Development or the Command Palette (Ctrl+Shift+P).

Syntax Definition Development

In AAAPackageDev, syntax definitions are written in JSON. Because Sublime Text uses .tmLanguage files, though, they need to be converted before use. The conversion is done through the included build system JSON to Property List.

Creating a New Syntax Definition

  1. Create new template (through Tools | Packages | Package Development) or the Command Palette
  2. Select JSON to Property List build system from Tools | Build System or leave as Automatic
  3. Press F7

Other included resources for syntax definition development:

  • Snippets

Package Development

Resources for package development are in a very early stage.

Commands

new_package
Window command. Prompts for a name and creates a new package skeleton in Packages.
delete_package
Window command. Opens file browser at Packages.

Build System Development

  • Syntax definition for .build-system files.

Key Map Development

  • Syntax definition for .sublime-keymap files.
  • Completions
  • Snippets

Snippet Development

AAAPackageDev provides a means to edit snippets using snippets. These snippets are called raw snippets. You can use snippets and snippet-like syntax in many files, but if you want to create .sublime-snippet files, you need to convert raw snippets first. This converion is done with a command.

Inside AAAPackageDev/Support you will find a .sublime-keymap file. The key bindings in it are included for reference. If you want them to work, you need to copy the contents over to your personal .sublime-keymap file under Packages/User.

Creating Snippets

  1. Create new raw snippet with included commands (Tools | Packages | Package Development or Command Palette)
  2. Edit snippet
  3. If needed, convert to .sublime-snippet with included command

You can use raw snippets directly in some files, like .sublime-completions files.

Completions Development

  • Syntax definition for .sublime-completions files
  • Snippets

You can use raw snippets directly in the contents element of a trigger-based completion.

Settings File Development

  • Syntax definition for .sublime-settings files
  • Snippets

JSON and Property List Conversion

If you need to parse a .plist into a .json file or vice versa AAAPackageDev can also be of help.

Commands

json_to_plist (Palette: JSON to Property List)

This command has already been mentioned in the Syntax Definition section, but it is not stated that this command in fact works for almost any JSON file you can imagine.

It considers the current file's filename and adjusts the target filename accordingly.

  • I am json.json will be parsed into I am json.plist.
  • I am json.JSON-propertyList will be parsed into I am json.propertyList.
plist_to_json (Palette: Property List to JSON)

This command is just the reverse of the above. Considers the current file's filename similarly and adjusts the target filename. However, if your file's extension is not .plist you need the doctype <!DOCTYPE plist at the beginning in one of the first two lines in order to use this command, otherwise it will assume that you don't have a Property List open.

Please note:
Non-native JSON data types (such as <date> or <data>) result in unpredictable behavior. Floats types (<float> or <real>) tend to lose precision when being cast into Python data types.
  • I am json.plist will be parsed into I am json.json.
  • I am json.propertyList will be parsed into I am json.JSON-propertyList only if the doctype <!DOCTYPE plist is specified.

About Snippets in AAAPackageDev

The AAAPackageDev/Snippets folder contains many snippets for all kinds of development mentioned above. These snippets follow memorable rules to make their use easy.

The snippets used more often have short tab triggers like f (field), c (completion), k (key binding), etc. In cases where increasingly complex items of a similar kind might exist (numbered fields, fields with place holders and fields with substitutions in the case of snippets), their tab triggers will consist in a repeated character, like f, ff and fff.

As a rule of thumb, the more complex the snippet, the longer its tab trigger.

Also, i (for item) is often a generic synonym for the most common snippet

in a type of file. In such cases, ii and even longer tab triggers might work too for consistency.

Sublime Library

AAAPackageDev includes sublime_lib, a Python package with utilities for plugin developers. Once AAAPackageDev is installed, sublime_lib will be importable from any plugin residing in Packages.