RSML as a Language¶
Note
To make RSML easier to understand for beginners, this page starts with the "easiest" details of the language.
Files¶
The official standard file extension for Red Sea Markup Language files is .rsea
, to avoid it being confused with other languages that also use the RSML abbreviation.
The .rsml
file extension is also fine, but .rsea
is preferred.
Evaluation¶
The "evaluation" is the act of going through every logic path and special action and evaluate the first, while running the second.
If an evaluation encounters a primary operator (see Operators) in a true logic path, its value is returned and evaluation ends there.
Use of MSBuild RIDs¶
MSBuild Runtime Identifiers are used for identifying systems and CPU architectures in Red Sea.
You'll need to know them in order to write RSML.
Here's a short example with common RIDs.
RID | Meaning | Example Usage in RSML (official-25 ) |
---|---|---|
win-x64 | Windows, 64-bit (based on x86) | win-x64 -> "Windows on x86-64" |
linux-x64 | Linux, 64-bit (based on x86) | linux-x64 || "Glad to see Linux getting love" |
linux-x86 | Linux, 32-bit (based on x86) | linux-x86 ^! "32-bit Linux not supported" |
osx-arm64 | macOS, ARM 64-bit (based on Apple Silicon) | osx-arm64 -> "An apple a day..." |
win-arm64 | Windows, ARM 64-bit | win-arm64 || "Windows on ARM... Interesting." |
linux-arm64 | Linux, ARM 64-bit | linux-arm64 -> "Tux is happy" |
linux-arm | Linux, ARM 32-bit | linux-arm || "Detected Linux on ARM32" |
Use of Regex in RSML¶
Tip
RSML uses Regex at its core, so it might be worth learning Regex first, even if only the basics.
RSML makes use of regular expressions to match MSBuild RIDs for different operating systems and CPU architectures.
This means you can write flexible patterns to match a wide range of platforms with few characters.
- Or, to be precise, this logic path matches
win-x86
,win-x64
,win-arm64
,win-arm
, etc.
Language Specification¶
Non-standardized
Red Sea is not a standardized language. For the sake of examplifying without getting too technical, we'll be using the official-25 standard in most of the documentation, as it's the closest to an official specification.
Red Sea is quite a simple language, but the lack of an official specification means behavior may vary across developer's implementations.
Static Functionality (Standardized
)¶
The following features are fully standardized and cannot be altered in any way by any language standards.
- The use of double quotes for enclosing values in logic path lines being mandatory and no standard being able to modify that.
- The use of MSBuild Runtime Identifiers.
- The use of standard Regex.
- Comment symbol (
#
). - Invalid lines being comments.
Extensible Functionality (Partially Standardized
)¶
The following features are partially standardized. For each feature, it's explained which part is standardized and which one isn't.
- Special Actions. Special actions can be added and customized by language standards, but the built-in one (
@EndAll
) cannot be removed or changed in any way. - Operators. Language standards can pick which tokens (including common words) they wish to use as operators, but operators are still partially standardized as there must always be three operators and only the behaviors for the secondary and tertiary can be altered - the primary operator will always be the return operator.
Implementation-specific Functionality (Non-Standardized
)¶
The following features are not standardized at all and can be customized at free will.
- Tokens used by operators. Each language standard can customize which tokens represent operators. Example:
official-25
uses operators->
,||
,^!
.
Operators¶
In RSML, there are always three operators, named primary, secondary and tertiary.
Below is a table with the operators, their tokens in official-25
and what they actually do. For all of these, consider val
as the argument they're passed.
Operator Name | Operator Token (according to official-25 ) |
Functionality | Functionality (according to official-25 ) |
---|---|---|---|
Primary | -> |
Returns val (standards can't change this operator's functionality). |
Returns val . |
Secondary | || |
Non-standardized. | Outputs val to the stdout . |
Tertiary | ^! |
Non-standardized. | Throws an error (error message set to val ) and ends evaluation. |
Evaluation Process Flow¶
Strictly markup
Despite the usage of wording such as "return" and "interpret", RSML is purely declarative - it can not execute, compile or transpile code.
RSML is evaluated from start to finish (see Advanced Representation of the Process Flow), meaning that the very first logic path with a primary operator in it that matches will be used and the evaluation ends there. All the logic beyond that point is ignored completely.
Simplified Representation¶
---
title: Simplified Representation of the Evaluation Process Flow
---
flowchart LR
A[Start] --> B[Next line];
B -->F{Match?};
F -->|No| B;
F -->|Yes| C{Primary operator?};
C -->|Yes| D[Return value + end];
C -->|No| E[Execute operator];
E -->B;
Advanced Representation¶
---
title: Advanced Representation of the Evaluation Process Flow
---
flowchart LR
A[Start] --> B[Next line];
B -->C{Valid?};
C -->|Yes| D{Type?};
C -->|No| B;
D -->|Logic| E{Match?};
D -->|Action| F{Ends eval?};
D -->|Comment| B;
E -->|Yes| G{Primary op?};
E -->|No| B;
F -->|Yes| H[Finish];
F -->|No| I[Run action];
I -->B;
G -->|Yes| J[Return + end];
G -->|No| K[Execute operator];
K -->B;
Return operator
Only the primary operator triggers the return of a logic path's value. The other operators, unless explicitly defined to do such, will never stop the evaluation.
Logic Paths¶
A logic path is the "interactive" part of RSML - the logic paths are what's evaluated.
The syntax for this is quite simple.
Things worth mentioning:
- The operator must be one of the 3 defined in the standard you're using (see Operators).
- The value (argument) must be enclosed in double quotes (
"
). - Spacing does not affect logic paths (
win.+ -> "hey"
is the same aswin.+ ->"hey"
).
- The line is valid, as long as the
->
operator is defined in the standard you're using. This will match all hosts with the Windows operating system.
- This will match Debian, Ubuntu and Arch Linux distributions, as long as the CPU architecture is
x86
based (x86
orx64
).
- Keep in mind return values must be enclosed in double quotes.
win.* -> "I can smell windows.h" # (1)!
osx.* || "An apple a day keeps the doctor away, I guess..." # (2)!
.+-x64 -> "64-bits is standard nowadays" # (3)!
- In
official-25
, this operator returns the logic path's value and ends evaluation (only if there's a match of course). - In
official-25
, this operator outputs the logic path's value and does NOT end evaluation (only if there's a match of course). - If one is on 64-bit Windows, this line wouldn't have been reached since the first line would have been a match and would've returned a value.
Special Actions¶
Special Actions (see Language Specification) are a partially-standardized feature of RSML, being responsible for evaluation-time modification to RSML aspects.
Built-in Special Action
As noted in the language specification section, @EndAll
is the only immutable, built-in special action in RSML:
- Name cannot be changed: Must always be
@EndAll
(case-sensitive) - Accepts no arguments:
@EndAll
is always argument-less, so any arguments given will be ignored. - Functionality: Terminates evaluation immediately.
- Standards compliance: All implementations support this, as it's built-in.
Special actions can change how the RSML parser behaves. Their usage varies with the programming language you're using for the RSML API. For that reason, in this page, we'll only talk about the syntax for these actions.
- The argument is optional, being an empty string if not specified. The argument must not contain any spaces and does not require enclosure.
- This is the only built-in standardized special action available. It'll be discussed later.
Comments¶
Comments are quite simple in RSML. If a #
character is at the start of a line, that line is considered a comment and will be fully ignored by the parser.
However, every single line that's considered invalid is also a comment. Here are some examples with reasons as of why the lines are invalid.
- Worth mentioning that a
#
in any other location other than the start of a line is not a comment, unless the line is invalid.
- According to
official-25
, this line does not contain any operators or special actions, so it is invalid; therefore, a comment.
- According to
official-25
, this line does not contain any operators or special actions, so it is invalid; therefore, a comment.
Syntax Reference¶
This is a quick reference sheet on RSML's syntax.