Skip to content

Latest commit

 

History

History
175 lines (137 loc) · 4.48 KB

0001-xgsl.md

File metadata and controls

175 lines (137 loc) · 4.48 KB

RFC 0001: XGSL (eXtensible Grid Sheet Language)

Author: Tales Marinho Godois
Status: Draft
Date: 2025-04-02

1. Summary

XGSL is a spreadsheet-as-code domain-specific language (DSL) designed to:

  • Declaratively define spreadsheets using code.
  • Export to Excel, Google Sheets, and LibreOffice with unified syntax.
  • Enhance collaboration via version control, templates, and dependency management.

2. Motivation

Spreadsheets are powerful but suffer from:

  • Fragility: Manual edits break complex formulas.
  • Versioning Issues: Git diffs for .xlsx files are unreadable.
  • Repetition: No reusable templates/styles across teams.

XGSL solves these by treating spreadsheets as code-first artifacts.

3. Syntax & Semantics

3.1 Core Syntax

Entities (Data Models)

// Define a data model  
entity Product {  
  id: int  
  name: string  
  price: double  
}

Tables (Spreadsheet Structure)

// Compose entities into a table  
@compose(Product, Sales)  
@style(theme: corporate)  
table ProductReport {  
  @label("Product ID")  
  id: Product.id  
  
  @label("Revenue") @style(currency)  
  revenue: Formula(Sales.units * Product.price)  
}

Formulas

// Relative references and virtual variables  
growth: Formula((.up.revenue - revenue) / .up.revenue)

3.2 Annotations

Annotation Purpose Example
@compose Merge entities/tables @compose(Product, Sales)
@style Apply formatting @style(currency, bold)
@label Customize column header @label("Total Revenue")
@import Import templates/data @import("github:user/report-templates")

3.3 Inheritance

// Inherit styles/structure  
table Q4Report extends Q3Report.style { ... }

4. Key Features

  1. Compiler: Transpiles .xgsl to Excel/Sheets/LibreOffice.
  2. Language Server (LSP): Autocomplete, diagnostics, hover docs.
  3. Formatter: Auto-format code with xgsl fmt.
  4. Dependency Management: 
    @import("github:org/templates@v1.2") // Git-based versioning
  5. Exporters:
    • Excel (.xlsx), Google Sheets (API), LibreOffice (.ods).

5. Architecture

5.1 Compiler Pipeline

.xgsl File → Parser → AST → Semantic Analyzer → IR → Exporter → .xlsx/.ods

Modules:

  1. Parser: PEG-based (using pest or nom).
  2. AST: Represents entities, tables, formulas.
  3. Semantic Analyzer: Validates types, resolves dependencies.
  4. IR: Platform-agnostic spreadsheet structure.
  5. Exporter: Generates platform-specific files.

5.2 Language Server

  • Built with tower-lsp for VS Code/IDE integration.
  • Features:
    • Autocomplete for annotations/entities.
    • Real-time error highlighting.

6. Error Handling & Validation

  • Type Checks: Ensure formulas resolve to valid types.
  • Circular References: Detect loops in formulas (e.g., A1 = B1 + A1).
  • Annotation Conflicts: Warn if @style overrides are ambiguous.

7. Dependency Management

  • Syntax: 
    @import("github:user/templates@v1.0.0")  
@import("./lib/utils.xgsl")
  • Resolver:
    • Fetch dependencies via Git.
    • Lock versions in xgsl.lock.

8. Roadmap

Phase 1: MVP

  • Parser + AST.
  • Excel exporter.
  • Basic CLI (compile, fmt).

Phase 2: LSP + Tooling

  • Language Server (autocomplete, diagnostics).
  • VS Code extension.

Phase 3: Advanced Features

  • Google Sheets API integration.
  • Dependency resolver.

9. Future Considerations

  1. Plugins: Custom exporters/formulas.
  2. Template Viewer: GUI to preview spreadsheets.
  3. Cloud Sync: Real-time collaboration.

10. Appendix

A. Example Workflow

# Install CLI  
cargo install xgsl  

# Compile to Excel  
xgsl compile report.xgsl --target excel

B. Glossary

  • IR: Intermediate Representation.
  • LSP: Language Server Protocol.

11. References

  • GitHub Repo: https://github.com/talesmgodois/xgsl
  • License: MIT/Apache 2.0

This RFC is a starting point—feedback and contributions are welcome!