项目作者: roblox-aurora

项目描述 :
AST parser for the Zirconium DSL for Roblox
高级语言: TypeScript
项目地址: git://github.com/roblox-aurora/zirconium-ast.git
创建时间: 2020-07-03T01:52:40Z
项目社区:https://github.com/roblox-aurora/zirconium-ast

开源协议:

下载


Zirconium AST

Abstract Syntax Tree parser for the Zirconium DSL (Domain-specific Language) for Roblox.
More information in the Zirconium project.

Supported Syntaxes

  • Comments
    1. # example comment
  • Basic commands -

    1. cmd hello world
    2. cmd "Hello, World!"
  • Multiple commands

    1. cmd one
    2. cmd two
    3. cmd three
    1. cmd one; cmd two; cmd three
  • Multi-line commands

    1. cmd one \
    2. two \
    3. three
  • Options

    1. cmd -kEwL --options yes
  • Variables
    1. cmd $var
  • String Interpolation
    1. cmd "Interpolated $value string"
  • Synchronous Execution
    1. cmd1 arg && cmd2 arg
  • Pipes
    1. cmd1 | cmd2
  • Prefixes
    1. cmd1 ~value @value %value ^value *value`
  • Variable Declarations

    1. $var = 10
    2. $var = string
    3. $var = "a string"
    4. $var = $anotherVar
    5. $var = "Interpolated $value string"
  • Nested Expressions

    1. cmd $(cmd2 -k xyz)
    2. $var = $(cmd2 -k xyz)

Validation

Validation is done via CommmandAstParser.validate - and returns an object, depending on the value of success.

  1. type ValidationSuccess = { success: true }
  2. type ValidationError = { success: false, errorNodes: NodeError[] }

errorNodes is an array of errors, which are

  1. interface NodeError {
  2. node: Node;
  3. message: string;
  4. }

Through this, you can get information about what nodes are causing errors, by using node.startPos and node.endPos for the position of the offending text, and message for the error message.

Inside CommandAstParser there is a simple assert function that is like the following:

  1. assert(node: Node) {
  2. const result = this.validate(node);
  3. if (!result.success) {
  4. const firstNode = result.errorNodes[0];
  5. throw `[CmdParser] [${firstNode.node.startPos ?? 0}:${firstNode.node.endPos ?? 0}] ${firstNode.message}`;
  6. }
  7. }

Which will, for example in the case of

  1. $x =

will give

  1. - [CmdParser] [3:3] Expression expected: '$x ='

Which means at character 3, (=) there is an error - in this case, there is no expression.

Ast Examples

Simplified via CommandAstParser.prettyPrint

  • Regular commands:

    cmd hello world

    1. CommandStatement {
    2. CommandName cmd
    3. String `hello`
    4. String `world`
    5. }

    cmd "Hello, World!"

    1. CommandStatement {
    2. CommandName cmd
    3. String "Hello, World!"
    4. }
  • Options

    cmd -kEwL --options yes

    1. CommandStatement {
    2. CommandName cmd
    3. Option k
    4. Option E
    5. Option w
    6. Option L
    7. Option options
    8. String `yes`
    9. }
  • Synchronous binary expression

    cmd one && cmd --number two

    1. BinaryExpression {
    2. CommandStatement {
    3. CommandName cmd
    4. String `one`
    5. }
    6. OperatorToken "&&"
    7. CommandStatement {
    8. CommandName cmd
    9. Option number
    10. String `two`
    11. }
    12. }
  • Pipe binary expression

    cmd one | cmd --number two

    1. BinaryExpression {
    2. CommandStatement {
    3. CommandName cmd
    4. String `one`
    5. }
    6. OperatorToken "|"
    7. CommandStatement {
    8. CommandName cmd
    9. Option number
    10. String `two`
    11. }
    12. }
  • Variable usage

    cmd $variable

    1. CommandStatement {
    2. CommandName cmd
    3. Identifier variable
    4. }

    cmd "string interpolation $ohYeaaah!"

    1. CommandStatement {
    2. CommandName cmd
    3. InterpolatedString {
    4. String "string interpolation "
    5. Identifier ohYeaaah
    6. String "!"
    7. }
    8. }
  • Prefix expressions

    cmd @special

    1. CommandStatement {
    2. CommandName cmd
    3. PrefixExpression {
    4. Prefix "@"
    5. String `special`
    6. }
    7. }
  • Variable declarations

    $var = 10

    1. VariableDeclarationStatement {
    2. VariableDeclaration {
    3. Identifier var
    4. NumberLiteral 10
    5. }
    6. }

    $var = "Hello, World!"

    1. VariableDeclarationStatement {
    2. VariableDeclaration {
    3. Identifier var
    4. String "Hello, World!"
    5. }
    6. }

    $var = "Hello $otherVar!"

    1. VariableDeclarationStatement {
    2. VariableDeclaration {
    3. Identifier var
    4. InterpolatedString {
    5. String "Hello "
    6. Identifier otherVar
    7. String "!"
    8. }
    9. }
    10. }
  • Inner Expressions

    cmd $(cmd2 --something else)

    1. CommandStatement {
    2. CommandName cmd
    3. InnerExpression {
    4. CommandStatement {
    5. CommandName cmd2
    6. Option something
    7. String else
    8. }
    9. }
    10. }

    $var = $(cmd xyz)

    1. VariableDeclarationStatement {
    2. VariableDeclaration {
    3. Identifier var
    4. InnerExpression {
    5. CommandStatement {
    6. CommandName cmd
    7. String `xyz`
    8. }
    9. }
    10. }
    11. }