TX-Gram DSL Documentation

Welcome to the TX-Gram DSL repository! This project defines a domain-specific language (DSL) for creating Use Case Diagrams and Sequence Diagrams using a structured text format. Below, you'll find instructions to set up the project, an overview of the grammar, and examples to help you get started.

---

Table of Contents

1. Getting Started
2. Grammar Overview
   • Basic Tokens
   • Use Case Diagrams
   • Sequence Diagrams
3. Examples
4. Contributing

---

Getting Started

To set up and run the TX-Gram DSL project locally, follow these steps:

1. Clone the repository:

   git clone https://github.com/your-repo/tx-gram-dsl.git
   cd tx-gram-dsl

2. Install dependencies:

   npm install

3. Run the development server:

   npm run serve

4. Access the application: Open your browser and navigate to http://localhost:3000 to start using the TX-Gram DSL editor.

---

Grammar Overview

Basic Tokens

The grammar uses the following basic tokens:

• WS: Matches whitespace (hidden from parsing).
• ID: Matches alphanumeric names starting with a letter or underscore.
• STRING: Matches text enclosed in single or double quotes.
• INT: Matches integer values.
• ML_COMMENT: Matches multiline comments enclosed in /* ... */ (hidden from parsing).
• SL_COMMENT: Matches single-line comments starting with // (hidden from parsing).

---

Use Case Diagrams

Use Case Diagrams describe interactions between actors and systems. The structure is as follows:

useCaseDiagram <name>:
    actors: <Actor>, <Actor>, ...
    useCases: <UseCase>, <UseCase>, ...
    relationships: <Relation>, <Relation>, ...

Components:

• Actor: Represents a user or external entity.
• UseCase: Describes an action performed by an actor or system.
• Relation: Defines relationships between elements (e.g., actors, use cases).

Example:

type useCaseDiagram

useCaseDiagram OnlineShoppingSystem:
    actors: Customer, Admin

    useCases:
        useCase BrowseItems:
            description: "Browse the list of available items."
            extensionPoints: "search filter", "view item details"
        useCase AddToCart:
            description: "Add items to their shopping cart."
            extensionPoints: "item availability"
        useCase Checkout:
            description: "Complete their purchase."
            extensionPoints: "payment gateway", "shipping details"
        useCase ViewItemDetails:
            description: "Display detailed information about an item."
        useCase VerifyPayment:
            description: "Verify payment details during checkout."
        useCase ManageItems:
            description: "Add, update, or remove items from the store."
        useCase ProcessOrders:
            description: "Process customer orders."

    relationships:
        - from: Customer
          to: BrowseItems
          type: normal
          direction: up
          length: 2
        - from: Customer
          to: AddToCart
          type: normal
          direction: up
          length: 2
        - from: Customer
          to: Checkout
          type: normal
          direction: up
          length: 2
        - from: Admin
          to: ManageItems
          type: normal
          length: 2
        - from: Admin
          to: ProcessOrders
          type: normal
          length: 2
        - from: ViewItemDetails
          to: BrowseItems
          type: extension
          length: 2
        - from: VerifyPayment
          to: Checkout
          type: extension
          length: 2
        - from: Checkout
          to: AddToCart
          type: inclusion
          length: 2

---

Sequence Diagrams

Sequence Diagrams visualize the flow of messages between participants over time. The structure is as follows:

sequenceDiagram <name>:
    lifelines: <Lifeline>, <Lifeline>, ...
    interactions: <Interaction>, <Execution>, <Group>, ...

Components:

• Lifeline: Represents an entity in the sequence (e.g., participant, actor).
• Interaction: Represents a communication between lifelines.
• Execution: Represents the start or end of an execution block.
• Group: Groups related interactions (e.g., alternatives, loops).

Example:

type sequenceDiagram

sequenceDiagram test:
  lifelines:
    - name: User
      type: actor
    - name: System
      type: participant
    - name: Database
      type: database
  interactions:
    - from: User
      to: System
      type: synchronousCall
      message: "Login"
    - group alt:
      * label: "User data?"
        subInteractions:
          - from: System
            to: Database
            type: synchronousCall
            message: "SELECT * FROM users WHERE username = 'admin'"
          - execution Database: start
          - from: Database
            to: System
            type: asynchronousCall
            message: "User data"
          - execution Database: end
      * label: "No user data"
        subInteractions:
          - from: System
            to: Database
            type: synchronousCall
            message: "Failed to retrieve user data"
          - from: Database
            to: System
            type: asynchronousCall
            message: "Error"
          - group alt:
            * label: "User data?"
              subInteractions:
                - from: System
                  to: Database
                  type: synchronousCall
                  message: "SELECT * FROM users WHERE username = 'admin'"
                - execution Database: start
                - from: Database
                  to: System
                  type: asynchronousCall
                  message: "User data"
                - execution Database: end

---

Examples

Check out the examples/ directory for sample diagrams written in TX-Gram DSL. These examples demonstrate how to define Use Case and Sequence Diagrams.

---

Contributing

We welcome contributions! If you'd like to improve the grammar, add new features, or report issues, please follow these steps:

1. Fork the repository.
2. Create a new branch for your changes.
3. Submit a pull request with a detailed description of your changes.

---

Happy diagramming with TX-Gram DSL! 🚀