How arnavsurve/grace works
Project type and purpose
• Grace is a compiler + runtime / systems programming language toolchain implemented in Go.
• Purpose: parse “Grace” source (.grc), perform lexical analysis, parsing, semantic analysis, and emit modern COBOL code. It also provides a CLI for init, build, run, and log inspection.
File structure
• Top‐level Go modules:
• cmd/ – CLI entry points (built with Cobra: root, build, run, logs, init)
• internal/compiler/ – the compiler implementation, subdivided into:
· lexer
· parser
· ast
· symbols + scope
· emitter
· lib (runtime constants & utilities)
• main.go – glue to invoke cmd/root
• docs/ – grammar spec & demo parser
• tests/ + examples/ – regression suites of .grc inputs and expected .cbl outputs
• Build: Makefile, go.mod, go.sum
• No microservices—single monolithic CLI + compiler library.
README for additional insights
• Emphasis on language spec, EBNF grammar (docs/grammar.lark), Python demo (docs/parse_grammar.py).
• Features: fixed‐width files, VSAM, CSV, JSON, SQL, cloud services (these are runtime targets but not source‐controlled connectors).
a. Main components
1) CLI Layer (cmd/)
• Commands: init, build, run, logs
• Uses Cobra for parsing flags & subcommands
2) Compiler Pipeline (internal/compiler/)
• Lexer: reads source chars → tokens
• Parser: tokens → parse tree / AST
• Semantic Analyzer: symbol table, scope resolution, type checking
• Emitter/Codegen: AST → COBOL code
• Runtime Lib: constants & helper routines embedded in output
3) I/O / File System
• Reads .grc, writes .cbl, manages templates (cmd/templates/*.tpl)
4) Tests & Examples
• tests/good & tests/bad drive regression based on expected outputs
5) Docs / Grammar Specification (external reference)
b. Relationships & data flow
• CLI “build” invokes Driver → Source File
→ Lexer → Parser → AST → Semantic → Emitter → write COBOL file
• “run” may compile + invoke runtime (Go exec child process or embed the generated code in target environment)
• “init” scaffolds a new project directory using templates
• Tests harness (test/run.go) exercises CLI commands and verifies outputs
c. Architectural patterns & design principles
• Pipeline pattern in compiler front‐end
• Single responsibility per package (lexer, parser, ast, emitter, scope, symbols)
• Library vs. application separation: internal compiler API vs. CLI wrappers
d. Key technologies
• Go + Cobra CLI framework
• LALR(1) or recursive‐descent parser (in parser/parser.go)
• Templates for code scaffolding
• Python demo harness (docs/parse_grammar.py) — ancillary
Final advice
• Be very detailed: split the pipeline into its subcomponents.
• CLI layer, compiler core, I/O, and tests as separate zones.
• Use consistent visual notation so a reader immediately sees the data flow and module boundaries.