ctrl+shift+p filters: :st2 :st3 :win :osx :linux
Browse

YAML Macros

by Thom1729 ST2/ST3 New

A macro system for YAML files powered by Python. Intended for Sublime Text development.

Details

Installs

  • Total 37
  • Win 16
  • OS X 10
  • Linux 11
Jun 27 Jun 26 Jun 25 Jun 24 Jun 23 Jun 22 Jun 21 Jun 20 Jun 19 Jun 18 Jun 17 Jun 16 Jun 15 Jun 14 Jun 13 Jun 12 Jun 11 Jun 10 Jun 9 Jun 8 Jun 7 Jun 6 Jun 5 Jun 4 Jun 3 Jun 2 Jun 1 May 31 May 30 May 29 May 28 May 27 May 26 May 25 May 24 May 23 May 22 May 21 May 20 May 19 May 18 May 17 May 16 May 15 May 14
Windows 1 1 2 2 3 3 1 1 1 0 0 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
OS X 0 1 0 0 3 1 1 0 1 1 0 1 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
Linux 1 1 0 1 1 0 1 1 0 2 1 3 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0

Readme

Source
raw.​githubusercontent.​com

YAML Macros

A macro system for YAML files powered by Python. Designed for Sublime Text syntax development.

Installation

YAML Macros can be installed via Package Control. You can also git clone this repository into your packages directory.

Overview

Sublime Text syntax definitions can often have a lot of boilerplate and repeated code. Consider this simple syntax that highlights SQL keywords:

%YAML 1.2
---
name: SQL Simple (YAML Macros example)
scope: source.sql
contexts:
  main:
  - match: \b(?i:select|from|where)\b
    scope: keyword.control.sql

  - match: \b(?i:distinct|as)\b
    scope: keyword.operator.word.sql

  - match: \b(?i:dual)\b
    scope: constant.language.sql

The same construct \b(?i:…)\b is repeated over and over. This can be tedious to write and annoying to read, and in a full, complex SQL syntax with a dozen or more similar matches, it's not unlikely that a hard-to-spot typo will lead to a hard-to-detect bug, such as a keyword only working in lowercase. With YAML Macros, you can DRY up your syntax by factoring out common idioms:

%YAML 1.2
%TAG ! tag:yaml-macros:sql_simple_macros/
---
name: SQL Simple (YAML Macros example)
scope: source.sql
contexts:
  main:
    - match: !word select|from|where
      scope: keyword.control.sql

    - match: !word distinct|as
      scope: keyword.operator.word.sql

    - match: !word dual
      scope: constant.language.sql

Then, in sql_simple_macros.py:

def word(str):
    return r'\b(?i:%s)\b' % str

It's as simple as that! For a more complex use case that uses a number of macros, see the full SQL example.

Usage

Importing macros

To import macros into your YAML file, add a %TAG directive at the top referencing the file containing your macros. The syntax is as follows:

%TAG <tag handle> tag:taml-macros:<macro definitions file>

<tag handle> is the prefix you will use to invoke your macros. It must begin with an exclamation point. <macro definitions file> is the local path from this file to your macro file. You can use multiple macro definitions files; simply write two %TAG directives with different tag handles.

Invoking macros

You may invoke a macro anywhere in your YAML file a value is expected:

<tag handle><macro name> <value>

Examples:

!word select
!expect [ ';', 'punctuation.terminator.statement.sql' ]

Note that there is no space between the tag handle and the name of a macro.

Defining macros

A macro definitions file is any Python module. It may be as simple as a single function definition or as complex as you like. If Python can do it, you can put it in a macro.

If a macro is applied to a YAML list, each list item will be passed as an argument. If a macro is applied to a YAML dictionary, each item will be passed as a keyword argument. Otherwise, the macro will receive a single value.

Applying your macros

If you have named your file with a .yaml-macros extension, simply select the “YAML Macros” build system. Running the build will create a compiled YAML file at the same location without the extra .yaml-macros suffix.

Command line interface

There is a basic command line interface. The CLI expects your YAML Macros file as standard input and will send the compiled YAML file to standard output. Optionally, you can specify a custom path as a base to search for your macro definitions file.

usage: cli.py [-h] [-m MACROS_PATH]

optional arguments:
  -h, --help            show this help message and exit
  -m MACROS_PATH, --macros-path MACROS_PATH
                        path to search for macro definitions