commit c4c29a640dc78a9960448488c798c0b47e86e28d Author: Martino Ferrari Date: Mon Jan 19 23:03:12 2026 +0100 Specs diff --git a/specification.md b/specification.md new file mode 100644 index 0000000..2a93cce --- /dev/null +++ b/specification.md @@ -0,0 +1,152 @@ +# MARTe Development Tools + +## Project goal + +- A single portable executable named `mdt` (MARTe Development Tools) written in _Go_ +- It should parse and index a custom configuration language (MARTe) +- It should provide an LSP server for this language +- It should provide a build tool for unifying multi-file projects into a single configuration output + +## CLI Commands + +The executable should support the following subcommands: +- `lsp`: Starts the Language Server Protocol server. +- `build`: Merges files with the same base namespace into a single output. +- `check`: Runs diagnostics and validations on the configuration files. +- `fmt`: Formats the configuration files. + +## LSP Features + +The LSP server should provide the following capabilities: +- **Diagnostics**: Report syntax errors and validation issues. +- **Hover Documentation**: + - **Objects**: Display `CLASS::Name` and any associated docstrings. + - **Signals**: Display `DataSource.Name TYPE (SIZE) [IN/OUT/INOUT]` along with docstrings. + - **GAMs**: Show the list of States where the GAM is referenced. + - **Referenced Signals**: Show the list of GAMs where the signal is referenced. +- **Go to Definition**: Jump to the definition of a reference, supporting navigation across any file in the current project. +- **Go to References**: Find usages of a node or field, supporting navigation across any file in the current project. +- **Code Completion**: Autocomplete fields, values, and references. +- **Code Snippets**: Provide snippets for common patterns. + +## Build System & File Structure + +- **File Extension**: `.marte` +- **Project Structure**: Files can be distributed across sub-folders. +- **Namespaces**: The `#package` macro defines the namespace for the file. +- **Build Process**: + - The build tool merges all files sharing the same base namespace. + - The LSP indexes only files belonging to the same project/namespace scope. +- **Output**: The output format is the same as the input configuration but without the `#package` macro. + +## MARTe Configuration Language + +### Grammar + +- `comment` : `//.*` +- `configuration`: `definition+` +- `definition`: `field = value | node = subnode` +- `field`: `[a-zA-Z][a-zA-Z0-9_\-]*` +- `node`: `[+$][a-zA-Z][a-zA-Z0-9_\-]*` +- `subnode`: `{ definition+ }` +- `value`: `string|int|float|bool|reference|array` +- `int`: `/-?[0-9]+|0b[01]+|0x[0-9a-fA-F]+` +- `float`: `-?[0-9]+\.[0-9]+|-?[0-9]+\.?[0-9]*e\-?[0-9]+` +- `bool`: `true|false` +- `string`: `".*"` +- `reference` : `string|.*` +- `array`: `{ value }` + +#### Extended grammar + +- `package` : `#package URI` +- `URI`: `PROJECT | PROJECT.PRJ_SUB_URI` +- `PRJ_SUB_URI`: `NODE | NODE.PRJ_SUB_URI` +- `docstring` : `//#.*` +- `pragma`: `//!.*` + +### Semantics + +- **Nodes (`+` / `$`)**: The prefixes `+` and `$` indicate that the node represents an object. + - **Constraint**: These nodes *must* contain a field named `Class` within their subnode definition. +- **Pragmas (`//!`)**: Used to suppress specific diagnostics. The developer can use these to explain why a rule is being ignored. +- **Structure**: A configuration is composed by one or more definitions. + +### Core MARTe Classes + +MARTe configurations typically involve several main categories of objects: +- **State Machine (`StateMachine`)**: Defines state machines and transition logic. +- **Real-Time Application (`RealTimeApplication`)**: Defines a real-time application, including its data sources, functions, states, and scheduler. +- **Data Source**: Multiple classes used to define input and/or output signal sources. +- **GAM (Generic Application Module)**: Multiple classes used to process signals. + - **Constraint**: A GAM node must contain at least one `InputSignals` sub-node, one `OutputSignals` sub-node, or both. + +### Signals and Data Flow + +- **Signal Definition**: + - **Explicit**: Signals defined within the `DataSource` definition. + - **Implicit**: Signals defined only within a `GAM`, which are then automatically managed. + - **Requirements**: + - All signal definitions **must** include a `Type` field with a valid value. + - **Size Information**: Signals can optionally include `NumberOfDimensions` and `NumberOfElements` fields. If not explicitly defined, these default to `1`. + - **Extensibility**: Signal definitions can include additional fields as required by the specific application context. +- **Signal Reference Syntax**: + - Signals are referenced or defined in `InputSignals` or `OutputSignals` sub-nodes using one of the following formats: + 1. **Direct Reference**: + ``` + SIGNAL_NAME = { + DataSource = SIGNAL_DATASOURCE + // Other fields if necessary + } + ``` + 2. **Aliased Reference**: + ``` + NAME = { + Alias = SIGNAL_NAME + DataSource = SIGNAL_DATASOURCE + // ... + } + ``` + - **Implicit Definition Constraint**: If a signal is implicitly defined within a GAM, the `Type` field **must** be present in the reference block to define the signal's properties. +- **Directionality**: DataSources and their signals are directional: + - `Input`: Only providing data. + - `Output`: Only receiving data. + - `Inout`: Bidirectional data flow. + +### Object Indexing & References + +The tool must build an index of the configuration to support LSP features and validations: +- **GAMs**: Referenced in `$APPLICATION.States.$STATE_NAME.Threads.$THREAD_NAME.Functions` (where `$APPLICATION` is a `RealTimeApplication` node). +- **Signals**: Referenced within the `InputSignals` and `OutputSignals` sub-nodes of a GAM. +- **DataSources**: Referenced within the `DataSource` field of a signal reference/definition. +- **General References**: Objects can also be referenced in other fields (e.g., as targets for messages). + +### Validation Rules + +- **Consistency**: The `lsp`, `check`, and `build` commands **must share the same validation engine** to ensure consistent results across all tools. +- **Class Validation**: + - For each known `Class`, the validator checks: + - **Mandatory Fields**: Verification that all required fields are present. + - **Field Types**: Verification that values assigned to fields match the expected types (e.g., `int`, `string`, `bool`). + - **Field Order**: Verification that specific fields appear in a prescribed order when required by the class definition. + - **Conditional Fields**: Validation of fields whose presence or value depends on the values of other fields within the same node or context. + - **Schema Definition**: + - Class validation rules must be defined in a separate schema file. + - **Project-Specific Classes**: Developers can define their own project-specific classes and corresponding validation rules, expanding the validation capabilities for their specific needs. + +### Diagnostic Messages + +The LSP and `check` command should report the following: + +- **Warnings**: + - **Unused GAM**: A GAM is defined but not referenced in any thread or scheduler. + - **Unused Signal**: A signal is explicitly defined in a `DataSource` but never referenced in any `GAM`. + - **Implicitly Defined Signal**: A signal is defined only within a `GAM` and not in its parent `DataSource`. + +- **Errors**: + - **Type Inconsistency**: A signal is referenced with a type different from its definition. + - **Size Inconsistency**: A signal is referenced with a size (dimensions/elements) different from its definition. + - **Validation Errors**: + - Missing mandatory fields. + - Field type mismatches. + - Grammar errors (e.g., missing closing brackets).