Restore proper content

Author: amari-calipso

docs/docs/ast-representation.md

@@ -11,22 +11,24 @@ The Chisel method allows to build parsers consistently using the same approach w
 This method is called Chisel because building parsers is about getting the information out of the code, as when you use a chisel you "take" the statue out of the marble. Also, since Strumenta means tools in Latin, Chisel takes the place as one of the most important tool in the company's toolset.
 
 The Chisel method is based on the following principles:
+
 1. We define a clear goal, which is shared by the Client and the Language Engineering Team. This goal is objective, and it is not subject to interpretation.
 2. At each step, the Language Engineering Team should clearly understand where we are and what should be done next - parsing and then refining the produced AST. Tool support should facilitate each single step, removing friction due to repetitive tasks. For this the StarLasu Libraries can be used since it provides user-friendly APIs for seamless integration as well as cross-language integration.
 3. Ensure frictionless adoption by providing all support needed to facilitate the adoption of the parser inside a Language Engineering Pipeline. By automatically generating documentation and having a method that simplifies training processes.
-
-![The Chisel Method](/img/chiselMethod.png)
+   ![image.png](chiselMethod.png)
 
 The Chisel method is based on the following steps:
 
 1. Create a parser using the StarLasu Libraries and Starlasu Tools, for that you need to:
 
-  - Define a grammar;
-  - Use the starlasu libraries to generate the AST;
-  - Refine the AST;
-  - Have a testing strategy;
-  - Have a set of examples that can be used to measure the parser's progress;
+- Define a grammar;
+- Use the starlasu libraries to generate the AST;
+- Refine the AST;
+- Have a testing strategy;
+- Have a set of examples that can be used to measure the parser's progress;
+
 2. Write a semantics module for more advanced codebase analysis and symbol resolution (optional).
 3. Write a code generation module this if the final goal is to generate the code for a target language (optional).
 
-Chisel is a method and a transformative approach to parsers development, ensuring efficiency, adaptability, and sustainability. 
+Chisel is a method and a transformative approach to parsers development, ensuring efficiency, adaptability, and sustainability.
+development, ensuring efficiency, adaptability, and sustainability. 

docs/docs/ast-traversal-and-querying.md

@@ -10,12 +10,11 @@ Code Generation modules are useful to generate new files programmatically. This
 
 Currently, Code Generation modules can be written with Kolasu and SharpLasu.
 
-## Setup 
+## Setup
 
 The Code Generation implementation should be separated from any other modules and be called code-generation. This module will typically have as dependency an ast module. Next is presented an `build.gradle.kts` file example for a code generation module.
 Note that currently the gradle starlasu plugin is private.
-
-```kotlin
+``` kotlin
 import com.strumenta.starlasugradleplugin.addGitHubPackagesRepo
 
 plugins {
@@ -46,7 +45,7 @@ dependencies {
 
 The Code Generator class should be a subclass of `ASTCodeGenerator`, this class needs to override the `registerRecordPrinters` function. This function will contain a `recordPrinter` for each AST node, the implementation of the recordPrinter will determine the output generated for the node type.
 
-```kotlin
+``` kotlin
 class MyCodeGenerator : ASTCodeGenerator() {
     override fun registerRecordPrinters() {
         recordPrinter<MyNode> { 
@@ -66,30 +65,30 @@ The methods to generate code are quite simple and intuitive to use:
 - `println` is used to print a string followed by a new line;
 - `printList` is used to print a list of nodes; You can specify a prefix, suffix and separator;
 - `printFlag` is used to print a string if a condition (flag which is a boolean value) is true;
-- `indent` is used to increase the indentation level which will be checked by the `print` and `println` methods; 
+- `indent` is used to increase the indentation level which will be checked by the `print` and `println` methods;
 - `dedent` is used to decrease the indentation level which will be checked by the `print` and `println` methods.
 
 ## Testing
 
-There is the need to know how the generated code should look like. 
+There is the need to know how the generated code should look like.
 
 For that unit testing can be done by writing the expected output in a file/string and comparing the generated output with the expected output using as input a manually created AST.
 
 It is also a good practise to have end-to-end tests, and one can follow 2 methods:
 
-1. **AST to AST testing**:
+1. AST to AST testing:
 
-   - Parse an input file that contains the original code, obtaining a first AST;
-   - Generate the code from this first AST, obtaining the generated code;
-   - Reparse the generated code, obtaining a second AST;
-   - Compare the first and the second AST.
+    - Parse an input file that contains the original code, obtaining a first AST;
+    - Generate the code from this first AST, obtaining the generated code;
+    - Reparse the generated code, obtaining a second AST;
+    - Compare the first and the second AST.
 
 This testing method is useful to test large examples, where it is hard to write the expected output manually. It allows to test the code generation in a more abstract way, where we check that the produced AST matches the one we expect. Of course it lacks coverage for code styling and formatting.
 
-2. **AST to code testing**:
+2. AST to code testing:
 
-   - Parse a string that contains the original code to the target AST representation;
-   - Generate the code from the target AST;
-   - Compare the expected output with the generated output.
+    - Parse a string that contains the original code to the target AST representation;
+    - Generate the code from the target AST;
+    - Compare the expected output with the generated output.
 
-This testing method is useful to test smaller examples and cover styling and formatting of the code. It allows to test the code generation in a more concrete way, where we check that the produced code matches the one we expect. 
+This testing method is useful to test smaller examples and cover styling and formatting of the code. It allows to test the code generation in a more concrete way, where we check that the produced code matches the one we expect.

docs/docs/chisel-method.md

@@ -4,50 +4,16 @@ title: Common Elements
 sidebar_label: Common Elements
 ---
 
-# Common Elements
+# AST Common Elements
 
-Common elements in Starlasu provide shared functionality and utilities that are used across different language engineering tools.
+Most programming languages share some concepts. We identified these common concepts and defined marker types for them. In this way, we can treat these elements similary in all languages.
 
-## Core Components
+They are:
 
-### AST Nodes
-- **Base Classes**: Common functionality for all AST nodes
-- **Position Tracking**: Source location information
-- **Serialization**: Standard serialization support
-- **Validation**: Common validation rules
+* Statement: for example print statements, expression statements, or return statements
+* Expression: for example, literals, mathematical expressions, boolean expressions
+* Entity Declaration: for example, class declarations, top level function declarations
 
-### Utilities
-- **String Handling**: Text processing utilities
-- **File Operations**: File reading and writing
-- **Error Handling**: Standard error reporting
-- **Logging**: Logging and debugging support
+_See in [Kolasu](https://github.com/Strumenta/kolasu/blob/main/ast/src/commonMain/kotlin/com/strumenta/kolasu/model/CommonElements.kt)_
 
-## Shared Patterns
-
-### Design Patterns
-- **Visitor Pattern**: Standard AST traversal
-- **Builder Pattern**: AST construction utilities
-- **Factory Pattern**: Node creation helpers
-- **Observer Pattern**: Change notification
-
-### Common Operations
-- **AST Traversal**: Standard traversal algorithms
-- **Node Comparison**: AST comparison utilities
-- **Copy Operations**: Deep copying and cloning
-- **Merge Operations**: AST merging utilities
-
-## Benefits
-
-- **Code Reuse**: Share common functionality across tools
-- **Consistency**: Maintain consistent behavior
-- **Maintenance**: Centralize common code
-- **Testing**: Shared test utilities
-
-## Implementation
-
-Starlasu provides:
-
-- **Base Classes**: Common base classes for all implementations
-- **Utility Libraries**: Shared utility functions
-- **Standard Interfaces**: Common interfaces and contracts
-- **Testing Support**: Shared testing utilities 
+_This is not yet supported in other StarLasu libraries._

docs/docs/code-generation.md

@@ -4,51 +4,14 @@ title: Cross-Platform Parsers
 sidebar_label: Cross-Platform Parsers
 ---
 
-# Cross-Platform Parsers
+# Cross-platform parsers
 
-Cross-platform parsers in Starlasu enable you to build language tools that work across different programming environments and platforms.
+Different users may want to use our parsers from different platforms such as the browser, Python, the JVM, etc.
 
-## Platform Support
+On the other hand we want to avoid having to rewrite the parsers for the same languages across multiple platforms. For this reason we have developed an approach to use parsers across platforms. In essence, we write a parser for any platform we want, using Kolasu, Pylasu, or Tylasu. We then access the AST produced by such parsers on another platform by serializing the AST produced on one platform and unserializing it on another one. To make this possible we built tools to:
 
-### JVM Platform
-- **Java**: Native Java implementation
-- **Kotlin**: Kotlin-based implementation
-- **Scala**: Scala integration support
-- **Android**: Mobile development support
+- analyze the codebase of the original parser and extract a metamodel
+- generate AST classes on the other platforms from the metamodel
+- generate an AST unserializers from the metamodel
 
-### Web Platform
-- **Node.js**: Server-side JavaScript
-- **Browser**: Client-side JavaScript
-- **TypeScript**: Type-safe JavaScript
-- **WebAssembly**: High-performance web execution
-
-### Other Platforms
-- **Python**: Python implementation
-- **.NET**: C#, F#, VB.NET support
-- **Native**: C/C++ integration
-
-## Benefits
-
-- **Code Reuse**: Share parser logic across platforms
-- **Consistency**: Maintain consistent behavior across environments
-- **Flexibility**: Choose the best platform for each use case
-- **Ecosystem**: Leverage platform-specific tools and libraries
-
-## Implementation
-
-### Shared Components
-- **Grammar Definitions**: Platform-independent language specifications
-- **AST Models**: Common data structures across platforms
-- **Testing**: Shared test suites and validation
-
-### Platform-Specific Features
-- **Performance Optimization**: Platform-specific optimizations
-- **Tool Integration**: Native platform tool integration
-- **Library Ecosystem**: Platform-specific library usage
-
-## Use Cases
-
-- **Multi-Platform Tools**: Tools that work on multiple platforms
-- **Language Servers**: Cross-platform language intelligence
-- **Code Analysis**: Platform-independent code analysis
-- **Documentation**: Generate docs for multiple platforms 
+In this way we could write a parser for RPG in Kotlin, using Kolasu. We would then automatically generate equivalent AST classes in Pylasu, and code to unserialize an AST instantiating those AST classes. In the end, we would obtain a parser usable from Python, which expose AST classes in Python. The implementation would call the parser written in Kotlin, obtain the AST serialized and unserialize it behind the scenes.

docs/docs/common-elements.md

@@ -4,65 +4,21 @@ title: Dual Code Model APIs
 sidebar_label: Dual Code Model APIs
 ---
 
-# Dual Code Model APIs
+# The Dual Code Model APIs
 
-Starlasu provides two complementary APIs for working with ASTs: homogeneous and heterogeneous APIs.
+This segment is more theoretical than the others. It is meant to provide a high-level overview of the dual code model APIs and the approach followed in the development of the StarLasu libraries.
+It will approach the concepts of homogenous and heterogeneous APIs, and how to use and leveraged them in the StarLasu libraries.
 
-## Homogeneous API
+## Homogenous APIs
 
-The homogeneous API treats all AST nodes uniformly:
+In kolasu, [Nodes](https://github.com/Strumenta/kolasu/blob/main/core/src/main/kotlin/com/strumenta/kolasu/model/Node.kt) are the basic building blocks of an AST. They are used to represent the different elements of the language being parsed.
+All the instances of nodes are the same and have a defined set of properties and methods, such as the origin, parent, etc...
 
-- **Type Safety**: All nodes have the same interface
-- **Generic Operations**: Apply operations to any node type
-- **Reflection**: Access properties dynamically
-- **Flexibility**: Work with unknown node types
+There are also reflective capabilities: so that its possible to ask each node for its properties and for each property to have access to the name, type and multiplicity, which allows to write fully generic algorithms.
+This is what we call a homogenous API.
 
-## Heterogeneous API
+This homogenous APIs are important to develop generic tools, like interpreters or semantic enrichment modules. Using the homogenous API, we can develop a tool that can be used for any language that has an AST representation.
+## Heterogeneous APIs
 
-The heterogeneous API provides type-specific operations:
-
-- **Type-Specific Methods**: Access properties and methods specific to each node type
-- **Compile-Time Safety**: Catch errors at compile time
-- **IntelliSense**: Better IDE support and autocomplete
-- **Performance**: Optimized for specific node types
-
-## When to Use Each
-
-### Use Homogeneous API when:
-- Working with unknown or generic node types
-- Implementing generic algorithms
-- Building tools that work with any AST
-- Need for dynamic property access
-
-### Use Heterogeneous API when:
-- Working with known node types
-- Building type-specific functionality
-- Need for compile-time safety
-- Performance is critical
-
-## Implementation
-
-Starlasu libraries provide both APIs:
-
-- **Base Classes**: Common functionality for all nodes
-- **Type-Specific Classes**: Specialized behavior for each node type
-- **Conversion Methods**: Switch between API styles
-- **Hybrid Approaches**: Combine both APIs as needed
-
-## Example
-
-```kotlin
-// Homogeneous API
-val allNodes = ast.findAll<ASTNode>()
-allNodes.forEach { node ->
-    val name = node.getProperty("name")
-    // Work with any node type
-}
-
-// Heterogeneous API
-val functions = ast.findAll<FunctionDeclaration>()
-functions.forEach { func ->
-    val name = func.name // Type-safe access
-    val params = func.parameters // Type-specific property
-}
-``` 
+On the other hand, each Node can also have its own specific set of properties and methods. For instance a Node that represents an if statement can have the condition and the body properties.
+This is what we call a heterogeneous API.

docs/docs/cross-platform-parsers.md

@@ -6,32 +6,21 @@ sidebar_label: EMF Interoperability
 
 # EMF Interoperability
 
-EMF (Eclipse Modeling Framework) interoperability in Starlasu enables integration with the Eclipse ecosystem and EMF-based tools.
+The Eclipse Modeling Framework (EMF) has been very successful in the MDE world. It can be regarded as an exchange format supported by different tools.
 
-## EMF Integration
+For this reason we built support for exporting Metamodels and Models to EMF. We in particular support the serialization to EMF-JSON. EMF-JSON is not as
+well-defined and supported as XMI (based on XML), but the request for JSON-based formats on some of the platforms supported brought us to focus on it.
 
-### Model Exchange
-- **ECore Models**: Import and export EMF Ecore models
-- **XMI Serialization**: Exchange models in XMI format
-- **Model Validation**: Use EMF validation frameworks
+In our case, _metamodels_ are the definition of the node types. For example, they specify which properties each node has.
 
-### Tool Integration
-- **Eclipse Plugins**: Build Eclipse-based language tools
-- **EMF Editors**: Create visual model editors
-- **Model Transformations**: Use EMF transformation frameworks
+Instead, we can represent and serialize ASTs as _models_ (i.e., instances of metamodels). A model describes the value of each node's properties, and the
+relationships among the nodes.
 
-## Benefits
+In some of the StarLasu libraries, we can also _import_ EMF metamodels and models (generated with other StarLasu libraries)
+in order to _consume_ the results of a tool (e.g. a parser) from a different language. This is what the
+[Strumenta Playground](https://playground.strumenta.com/) web app does, for example. This is also useful for [cross-platform parsers](parsers-cross-platform.md).
 
-- **Eclipse Ecosystem**: Leverage existing Eclipse tools and plugins
-- **Visual Modeling**: Create graphical model editors
-- **Standards Compliance**: Follow EMF modeling standards
-- **Tool Integration**: Work with EMF-based development tools
-
-## Implementation
-
-Starlasu provides:
-
-- **ECore Adapters**: Convert between Starlasu and EMF models
-- **XMI Support**: Import/export models in XMI format
-- **Validation Integration**: Use EMF validation with Starlasu models
-- **Editor Support**: Create EMF-based visual editors 
+Read more about this topic in:
+- [Kolasu](https://javadoc.io/doc/com.strumenta.kolasu/kolasu-emf/latest/index.html) ([source code](https://github.com/Strumenta/kolasu/tree/master/emf))
+- [Pylasu](https://pylasu.readthedocs.io/en/latest/pylasu.emf.html) ([source code](https://github.com/Strumenta/pylasu/tree/master/pylasu/emf)) _note: support in Pylasu is a work in progress._
+- [Tylasu](https://strumenta.github.io/tylasu/modules/interop_ecore.html) ([source code](https://github.com/Strumenta/tylasu/blob/master/src/interop/ecore.ts))

docs/docs/dual-code-model-apis.md

@@ -0,0 +1,16 @@
+---
+id: naming
+title: Naming
+sidebar_label: Naming
+---
+
+# Naming
+
+Two interfaces are defined:
+
+- PossiblyNamed, which define an attribute name of type String with multiplicity 0..1
+- Named, which extends PossiblyNamed and define an attribute name of type String with multiplicity 1..1
+
+For example, a FunctionDeclaration will be PossiblyNamed in languages which permits anonymous functions.
+
+In the StarLasu libraries we provide special support for things which are Named or PossiblyNamed. We can used these interfaces in [Symbol Resolution](SymbolResolution.md), for example.