Syntax patterns

The real power of Skript comes from its intuitive design, mainly featuring the feature-rich syntax that feels really close to plain English. To achieve this, skript-parser has a lot of functionalities in place to create 'syntax patterns'. Each pattern can consist of multiple elements that interact with each other. The user will make the final decision on how he will use the different patterns in his code.

This means that the developer can create multiple possibilities, while the user can choose which to use and how to use it. Both parties are happy!

If you want to learn how the patterns are actually matched against each other, together with a briefer explanation of the different pattern elements, refer to 'Pattern matching'.

Creating syntax patterns

Developers can choose between multiple types of elements. These elements together will form the pattern. The user input will be matched, line by line, against the stored elements. Each element has its own strategy when matching. If a match fails, the parser moves on to the next pattern.

Text elements

Text elements consist of a plain text instance. The matched string must contain every character of this text instance, otherwise, the match will fail.

Suppose we have the following inputs with the pattern attacker:

attcker     # fail
attacker    # success

Optional groups

An optional group consists of a simple element, or multiple, that can be omitted if desired by the user. It usually serves as a way to give more variety to the syntax, though it can be used to add optional parameters. It is indicated by square brackets (ex: [optional]) around the optional elements.

Suppose we have the following inputs with the pattern [the] attacker:

the attacker    # success
attacker        # success
the attcker     # fail

As one can see, a popular use is the addition of optional definite and indefinite articles as a cosmetic feature to the code. Users writing an application can opt for the more English-friendly syntax with articles.

Choice groups

Choice groups are indicated by two parentheses, and each choice is separated by a pipe | (ex: (choice|option)). When writing an application, either choice can be written. It also usually serves as a way to give more variety to the syntax.

Suppose we have the following inputs with the pattern [the] (attack|strike) damage:

the attack damage    # success
strike damage        # success

Note that developers have the option to use optional and choice groups mixed together. The following patterns are all valid:

• [the] [(attack|strike)] damage
• [the] ([absolute] attack|strike) damage

Thus, elements are quite flexible and allow developers to gain a lot of interaction with the user.

Regex elements

Regex elements are indicated by angled brackets (ex: <regex>). The enclosed text must represent a regex pattern that will be tested at parse time. This is useful when the other pattern elements can't represent the desired syntax properly (usually when the desired result can only be modelled by regex quantifiers). This should only be used if it must be, as skript-parser handles the other pattern elements much more efficiently.

Especially be careful when using all-around regex patterns like <.+> at the start of your syntax pattern. Make sure to design the other elements around your regex pattern, and not vice-versa. The parser especially likes text elements as a reference point!

Expression elements

These are indicated by a pair of per cent signs (ex: %type%). An expression element represents, well, an expression of a given type that will act as input when writing an application. The possible types are also only registered at registration time (the types guaranteed by skript-parser can be found further in the document). Yet, additional restrictions can be applied to expression elements:

• %*type%: the application must use a literal in place of the element.
• %~type%: the application must not use a literal in place of the element.
• %^type%: the application must use a variable in place of the element.
• %=boolean%: the application can use a conditional expression in place of this element.
• %type?%: if this element is omitted in the application (due to an optional group for example), skript-parser will use the default expression provided by the given type. It will always do that.
• %type1/type2%: allows the application to use an expression of either type. This can be combined with the previous restrictions, which would apply to all types indiscriminately. The only restriction that cannot be used with multiple type possibilities is the nullable restriction (the ? flag) because skript-parser would not know which default expression to pick for you.

Additional remarks

The parser also provides a set of additional features and functionalities to extend the possibilities of the developers even further.

Parse marks

Parse marks are marks that can be put before any so-called option elements. Option elements are the instances used in the optional group and the choice group. As one could already guess, the optional group always has one option element, the choice group can have multiple separated by a pipe.

Parse marks can be numbers or strings, followed by a semicolon (ex: [mark:option]) that mark the option elements. They are not required and absent by default, but if provided, the parser will correctly deliver the chosen option elements to the developer.

The pattern [the] (first|last) element out of %~objects% provides an excellent example. The developer needs to know whether the user employed 'first' or 'last' in his application, to correctly implement the expression. One can add parse marks to correctly demarcate the difference between the two options, like [the] (0:first|1:last) element out of %~objects%.