Sublime Forum

General questions re: syntax definitions

#1

I have some probably basic questions regarding the development of syntax definitions for new languages (.sublime-syntax files)

1: whhat’s the name, and where is located, the syntax used in .sublime-syntax files? It seems to be a variant of the yaml syntax,but while I can locate the basic yaml syntax, I cannot find the specialised one. I ask because I’d want to tweak the specialised syntax to suit my workflow better.

2: I understand that push: and set: actions can be given a list of contexts. Does the list need to be given in the “one liner” format e.g. push: [a,b,c] or can it be given as in

[code]push:

  • a
  • b
  • c
    [/code]
    2.1: if I can use the second format to push or set a list of contexts, can one of the items in the list be an annonymous context defined in-place, e.g.

[code]push:

  • a
  • b
    • match ‘something’
      scope: newscope
      [/code]
      3: I understand that in any case, when pushing or setting a list of contexts, the last one in the list is processed first. Is there a way to reverse that behaviour? Specially if I can do as illustrated in 2.1 it’d help readability if the first element in the list (a) was processed first and it went top-down

4: What are the valid characters for contexts and variables names?

5: I understand that in standard yaml, when the value associated with a key is a list or dictionary NOT given in a single line, the leading whitespace to the first entry define the indentation for all the entries. Does this hold true for sublime-syntax format? Or do I need to stick to the two space of indentations always.
I want to do something like this:

variables:
  #comment explaining first batch of variables 
    var1: text1
    var2: text2
  #comment explaining second batch of variables
    var3: text3
    var4: text4

in this way, I can fold and unfold different parts of the list of variables as I need.

Thanks you in advance for any answer you may provide!

0 Likes
#2

Syntax definition documentation.

I understand that push: and set: actions can be given a list of contexts. Does the list need to be given in the “one liner” format…

The block style (- a) and the flow style ([a, b, c]) are equivalent.

When you push/set a list of contexts, the list may include anonymous contexts only if the first context on the list is anonymous. I have no idea why this is the case.

I understand that in any case, when pushing or setting a list of contexts, the last one in the list is processed first. Is there a way to reverse that behaviour? Specially if I can do as illustrated in 2.1 it’d help readability if the first element in the list (a) was processed first and it went top-down

The current context is always the last one pushed to the stack. I’ve experimented with ways to write lists of contexts in reverse order (using YAML Macros) and it’s always made the syntax harder to read in the end. However, you might have better luck.

What are the valid characters for contexts and variables names?

The standard convention is to use alphanumeric characters, plus hyphens for context names and plus underscores for variable names. I don’t know what the complete set of valid characters is. For context names, it’s probably any valid YAML string. For variable names, you’re also limited by the variable substitution logic that Sublime uses when processing syntax definitions; I’ve never had reason to explore the possibilities there.

I understand that in standard yaml, when the value associated with a key is a list or dictionary NOT given in a single line, the leading whitespace to the first entry define the indentation for all the entries. Does this hold true for sublime-syntax format?

Sublime syntax definitions are parsed as YAML before Sublime does any additional processing, so any valid YAML syntax should work fine – for the most part. The caveat is that Sublime uses its own custom YAML engine that omits support for YAML tags, dictionary merges, ID references, and some other stuff (more or less anything with semantics that wouldn’t translate to JSON). It is possible that this parser might have other quirks that differ slightly from (say) pyyaml.

3 Likes
#3

Just a minor nitpick, but we currently use yaml-cpp. We may at some point swap out engines, but in general I would say that most YAML parsers seem to have their quirks.

In general, I would recommend sticking to fairly sane, human-readable YAML, and you should be in a good place for the parser and other humans.

1 Like