|
6 | 6 |
|
7 | 7 |
|
8 | 8 | # RSML as a Language |
9 | | -??? note |
10 | | - To make RSML easier to understand for beginners, this page starts with the _"easiest"_ details of the language. |
11 | 9 |
|
12 | | -## Files |
13 | | -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. |
| 10 | +## Abstract |
| 11 | +**Red Sea Markup Language** (RSML) is a simple declarative markup language created for the purpose of following logic paths based on the host's operating system and CPU architecture. |
14 | 12 |
|
15 | | -The `.rsml` file extension is also fine, but `.rsea` is preferred. |
| 13 | +It is a better altenative to scripting languages because of its simplicity, ease of use, and the fact it's not necessary to package a whole interpreter. |
16 | 14 |
|
17 | 15 | ## Evaluation |
18 | | -The _"evaluation"_ is the act of going through every **logic path** and **special action** and evaluate the first, while running the second. |
| 16 | +The __"evaluation"__ is the act of going through every line of RSML and evaluating the ones that match the **logic path** syntax, while running the ones that match the **special action** syntax. |
19 | 17 |
|
20 | | -If an evaluation encounters a **primary operator** _([see Operators](#operators))_ in a true logic path, its value is returned and evaluation ends there. |
| 18 | +If an evaluation encounters the **return operator** _([see Operators](#operators))_ in a logic path that evaluates as `true`, its value is returned and evaluation ends there. |
21 | 19 |
|
22 | | -## Use of MSBuild RIDs |
23 | | -[MSBuild Runtime Identifiers](https://learn.microsoft.com/en-us/dotnet/core/rid-catalog) are used for identifying systems and CPU architectures in Red Sea. |
| 20 | +## Language Specification |
| 21 | +!!! note |
| 22 | + Starting with version <!-- md:version 2.0.0 -->, RSML is a standardized language, in order to ensure consistency across different implementations. This also allows for less confusion when it comes to the language's features and syntax. |
24 | 23 |
|
25 | | -You'll need to know them in order to write RSML. |
| 24 | +Below are the main concepts of RSML as a language. |
| 25 | +- **Logic Path:** The interactive part of RSML, responsible for returning values based on machine matches. |
| 26 | +- **Special Action:** Actions that are executed during evaluation, responsible for modifying real-time aspects of how RSML is evaluated. There are only 3 as of now. |
| 27 | +- **Comments:** Lines that are ignored by the parser. |
26 | 28 |
|
27 | | -Here's a short example with common RIDs. |
| 29 | +## Logic Path |
| 30 | +A logic path is a line in RSML that contains several expressions, an operator and a value to return. If the expression matches the host's OS/architecture, the evaluator returns the value (if the operator is the return operator) or executes the operator's functionality. |
28 | 31 |
|
29 | | -| RID | Meaning | Example Usage in RSML (`official-25`) | |
30 | | -| ----------- | --------------------------------------------------------------------- | ----------------------------------------------- | |
31 | | -| win-x64 | :fontawesome-brands-windows: Windows, 64-bit (based on x86) | `win-x64 -> "Windows on x86-64"` | |
32 | | -| linux-x64 | :fontawesome-brands-linux: Linux, 64-bit (based on x86) | `linux-x64 || "Glad to see Linux getting love"` | |
33 | | -| linux-x86 | :fontawesome-brands-linux: Linux, 32-bit (based on x86) | `linux-x86 ^! "32-bit Linux not supported"` | |
34 | | -| osx-arm64 | :fontawesome-brands-apple: macOS, ARM 64-bit (based on Apple Silicon) | `osx-arm64 -> "An apple a day..."` | |
35 | | -| win-arm64 | :fontawesome-brands-windows: Windows, ARM 64-bit | `win-arm64 || "Windows on ARM... Interesting."` | |
36 | | -| linux-arm64 | :fontawesome-brands-linux: Linux, ARM 64-bit | `linux-arm64 -> "Tux is happy"` | |
37 | | -| linux-arm | :fontawesome-brands-linux: Linux, ARM 32-bit | `linux-arm || "Detected Linux on ARM32"` | |
| 32 | +### Operators |
| 33 | +In RSML, there are two operators, named **return** and **throw-error**. |
38 | 34 |
|
39 | | -## Use of Regex in RSML |
40 | | -!!! tip |
41 | | - RSML uses Regex at its core, so it might be worth learning Regex first, even if only the basics. |
| 35 | +Below is a table with the operators, their tokens and what they actually do. |
42 | 36 |
|
43 | | -RSML makes use of **regular expressions** to match [MSBuild RIDs](https://learn.microsoft.com/en-us/dotnet/core/rid-catalog) for different operating systems and CPU architectures. |
| 37 | +| Operator Name | Operator Token | Functionality _(triggered if the logic path matches the machine)_ | |
| 38 | +| ------------- | -------------- | ---------------------------------------------------------------------------------- | |
| 39 | +| Return | `->` | Returns the logic path's value and ends evaluation. | |
| 40 | +| Throw-Error | `!>` | Throws an error (error message set to the logic path's value) and ends evaluation. | |
44 | 41 |
|
45 | | -This means you can write flexible patterns to match a wide range of platforms with few characters. |
| 42 | +### Syntax |
| 43 | +The syntax for logic paths is extremely simple. |
| 44 | +It has **two** overloads: one where you can't specify a version and one where you can. |
46 | 45 |
|
47 | | -```python title="Usage of Regex in RSML" |
48 | | -win.+ -> "This logic path matches any Windows system" # (1)! |
49 | | -``` |
| 46 | +=== "Without version specification" |
| 47 | + ```rsea |
| 48 | + <operator> [<system-name>] [<system-major-version> = any] [<cpu-architecture>] <value> |
| 49 | + ``` |
| 50 | + |
| 51 | +=== "With version specification" |
| 52 | + ```rsea |
| 53 | + <operator> [<system-name>] [<system-major-version-comparison-symbol>] [<system-major-version>] [<cpu-architecture>] <value> |
| 54 | + ``` |
50 | 55 |
|
51 | | -1. Or, to be precise, this logic path matches `win-x86`, `win-x64`, `win-arm64`, `win-arm`, etc. |
| 56 | +#### Parameters |
| 57 | +The parameters in the syntax, although complex at first glance, are quite simple. However, they must appear in the exact order shown above (depending on the overload used). |
52 | 58 |
|
53 | | -## Language Specification |
54 | | -!!! warning "Non-standardized" |
55 | | - Red Sea is **not** a [standardized](standards/index.md) language. **For the sake of examplifying without getting too technical**, **we'll be using the [**official-25**](standards/official-25.md) standard** in most of the documentation, as it's the closest to an official specification. |
| 59 | +`operator` |
| 60 | + |
| 61 | +: The operator to use. This is **mandatory**. |
| 62 | + |
| 63 | +`system-name` |
56 | 64 |
|
57 | | -**Red Sea** is quite a simple language, **but the lack of an official specification** means behavior may vary across developer's implementations. |
| 65 | +: The operating system name to match against. This is **optional**; but must be specified if you want to specify the argument that comes next in order. Can be set to `any` to match all operating systems as well. Can, additionally, be set to `defined` to match all operating systems as long as the OS is recognized by the RSML implementation. |
58 | 66 |
|
59 | | -### Static Functionality (Standardized :green_circle:) |
60 | | -The following features are fully standardized and ==cannot be altered in any way by any language standards==. |
| 67 | +`system-major-version-comparison-symbol` |
61 | 68 |
|
62 | | -* The use of **double quotes** for **enclosing values in logic path lines** being **mandatory** and no standard being able to modify that. |
63 | | -* The use of MSBuild **Runtime Identifiers**. |
64 | | -* The use of **standard Regex**. |
65 | | -* **Comment symbol** (`#!python #`). |
66 | | -* **Invalid lines** being **comments**. |
| 69 | +: The comparison symbol to use for the system major version. This is **optional**; but must be specified if you want to specify the argument that comes next in order; if not specified, it defaults to `==`. Can be one of the following: `==`, `!=`, `<`, `>`, `<=`, `>=`. It cannot be set to `any` or `defined`. If not specified, `system-major-version` must also not be specified (or set to `any`). |
67 | 70 |
|
68 | | -### Extensible Functionality (Partially Standardized :yellow_circle:) |
69 | | -The following features are partially standardized. For each feature, it's explained which part is standardized and which one isn't. |
| 71 | +`system-major-version` |
70 | 72 |
|
71 | | -* **[Special Actions.](#special-actions)** Special actions can be added and customized by language standards, but the built-in one (`#!python @EndAll`) cannot be removed or changed in *any* way. |
72 | | -* **[Operators](#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. |
| 73 | +: The major version of the operating system to match against. This is **optional**; but must be specified if you want to specify the argument that comes next in order; if not specified, it matches all versions. Can be set to `any` to match all versions as well. Can, additionally, be set to `defined` to match all versions as long as the OS version is recognized by the RSML implementation. If `system-major-version-comparison-symbol` is specified, this parameter must also be specified (and vice-versa). |
73 | 74 |
|
74 | | -### Implementation-specific Functionality (Non-Standardized :red_circle:) |
75 | | -The following features are not standardized at all and can be customized at free will. |
| 75 | +`cpu-architecture` |
76 | 76 |
|
77 | | -* **Tokens used by operators.** Each language standard can customize which tokens represent operators. **Example:** `official-25` uses operators `->`, `||`, `^!`. |
| 77 | +: The CPU architecture to match against. This is **optional**. Can be set to `any` to match all CPU architectures as well. Can, additionally, be set to `defined` to match all CPU architectures as long as the architecture is recognized by the RSML implementation. |
78 | 78 |
|
79 | | -## Operators |
80 | | -In RSML, there are always **three operators**, named **primary**, **secondary** and **tertiary**. |
| 79 | +`value` |
81 | 80 |
|
82 | | -Below is a table with the operators, their [tokens](#extensible-functionality-partially-standardized) in `official-25` and what they actually do. For all of these, consider `val` as the argument they're passed. |
| 81 | +: The value to return or use as an error message, depending on the operator used. This is **mandatory** and **must** be enclosed in double quotes (`"`). |
83 | 82 |
|
84 | | -| Operator Name | Operator Token (according to `official-25`) | Functionality | Functionality (according to `official-25`) | |
85 | | -| ------------- | ------------------------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------- | |
86 | | -| Primary | `->` | Returns `val` _(standards can't change this operator's functionality)_. | Returns `val`. | |
87 | | -| Secondary | `||` | Non-standardized. | Outputs `val` to the `stdout`. | |
88 | | -| Tertiary | `^!` | Non-standardized. | Throws an error _(error message set to `val`)_ and ends evaluation. | |
| 83 | +<!-- todo: keep working on this --> |
89 | 84 |
|
90 | 85 | ## Evaluation Process Flow |
91 | 86 | !!! tip "See also" |
|
0 commit comments