TRBotSyntaxLexer

An input syntax lexer and parser for TRBot written in Rust.

Several components make up this library:

• Scanner - given an input string, outputs tokens that match the input syntax
• Parser - given tokens from the scanner, validates the input syntax and outputs expressions
• Validator - processes the expressions, outputting a set of instructions which an input handler can use to execute said instructions on virtual input devices. The validator is what links the data to the instructions. For example, it uses data to map input names to input data and set the default input duration on instructions with a duration. The validator also expands macros and substitutes arguments in dynamic macros. Lastly, if specified, it ensures an input sequence doesn't exceed the maximum input duration.

See the design document for information about what this solves.

New Features

This library features new additions to the syntax not available in prior versions of TRBot.

Inputs can be grouped without a repetition count

• Ex. [a"34 ."34] - presses a very quickly and then waits very shortly.
  • Equivalent to [a"34 ."34]*1.

Linking grouped sequences

• Ex. up'1+[a"34 ."34]*40 - holds up for 1 second while repeatedly mashing a.
• Ex. up'1+[right down left] - holds up for 1 seconds while pressing right, down, and left in order.

Linking with macros

• Ex. if #macro = up down, left'1+#macro holds left for one second while pressing up and down in order.
  • Here, #macro is run simultaneously with left'1 and finishes before it.

Permanent holds

• Ex. ^up right - will keep up held even after the input sequence is completed.

Potential New Features

Here are some ideas for further additions to the syntax.

• Sequence durations - repeats a sequence for a given amount of time.
  • Internally expands out to repetition count, rounding up or down.
  • Ex. {a"34 ."34}*5' - mashes a for 5 seconds
    • Internally expands to [a"34 ."34]*73:
      • a"34 ."34 = 68 milliseconds --> 5' = 5 seconds = 5000 milliseconds. So 5000 / 68 = ~73.529 --> round down to 73.
  • Currently unclear how useful this would be, given how it may not always be accurate.

Legacy Parser

Enable the legacy feature in Cargo.toml to use the legacy parser. The legacy parser is a Rust implementation of the legacy TRBot parser that returns a Vec<Expression> to be fed into the Validator. The aim is to ease players into the new syntax by allowing them to use the familiar legacy syntax in the meantime. New code should always use the Scanner -> Parser -> Validator flow instead. The legacy parser will not receive updates nor new features, and it may be removed entirely in the future.

License

Copyright © 2025 Kimimaru

TRBotSyntaxLexer is free software; you are free to run, study, modify, and redistribute it. Specifically, you can modify and/or redistribute TRBotSyntaxLexer under the terms of the GNU Affero General Public License v3.0 or, at your option, a later version.