#yxl

• Diffable & reviewable — a workbook is text under Git.
• DRY / single-source-of-truth — a value, formula, or style written once and referenced many times is managed in one place, and compiles down to Excel's native sharing (shared strings, defined names, shared formulas, a single style id). Change it once, it changes everywhere.
• Flexible structure — split data and formatting across files with $include, feed a region straight from a CSV or JSON table, or inline everything in one file. Same result either way.
• One spec, many workbooks — declare params: and override them per build with --set region=EMEA.
• A single native command — yxl init for a first spec, then yxl build in its directory.

⚠️ Status: pre-release, schema not yet frozen. yxl build works today — values, formulas, dates, durations, rich text, styles, layout, print setup, multi-file specs, external CSV/JSON data, parameters, one-off overrides, validations, conditional formatting, hyperlinks, notes, protection, Excel tables, charts, images, shapes, sheet backgrounds, sparklines, form controls, table slicers, and pivot tables all compile, and the CLI has init, --check, --set, and stable exit codes. Still ahead: performance work, import, and the schema freeze — the schema may change until v1.0. See ROADMAP.md for the phase plan and the living changelog.

#A taste

# report.yxl.yaml
params:                      # overridable per build with --set
  region: APAC
  quarter: Q3

defs:                        # declared once, referenced by name
  styles:
    base:   { font: { name: Calibri, size: 11 } }
    title:  { extends: base, font: { bold: true, size: 16 } }
    header: { extends: base, font: { bold: true, color: "FFFFFF" }, fill: "1F3864" }
    total:  { extends: base, font: { bold: true } }

sheets:
  - name: "${region}"
    freeze: A4               # the header rows stay put while the data scrolls
    merges: [A1:B1]
    columns:
      - at: A
        width: 18
      - at: B
        width: 14
        format: "#,##0"      # a whole-column default format
    cells:
      A1: { value: "${quarter} ${region} sales", style: title }
      A3: { value: Region, style: header }
      B3: { value: Revenue, style: header }
      A7: { value: Total, style: total }
      B7: { formula: "SUM(B4:B6)", style: total }
    data:
      - at: A4
        csv: data/sales.csv  # rows from a file the spec never restates —
                             # or write them here with `values:` instead
    print:
      area: A1:B7
      orientation: landscape
      fit: { width: 1 }      # shrink to one page across

yxl build report.yxl.yaml -o q3-apac.xlsx
yxl build report.yxl.yaml -o q4-emea.xlsx --set region=EMEA --set quarter=Q4

#Install

curl -fsSL https://raw.githubusercontent.com/t-ujiie-g/yxl/main/install.sh | sh

irm https://raw.githubusercontent.com/t-ujiie-g/yxl/main/install.ps1 | iex

YXL_VERSION=0.1.0 YXL_INSTALL_DIR=/usr/local/bin \
  curl -fsSL https://raw.githubusercontent.com/t-ujiie-g/yxl/main/install.sh | sh

#Without installing: moonx

moonx t-ujiie-g/yxl/cmd/main@0.6.1 build report.yxl.yaml
moonx t-ujiie-g/yxl/cmd/main@0.6.1 extract existing.xlsx -o spec.yxl.yaml

#As a MoonBit library

moon add t-ujiie-g/yxl

// spec text -> .xlsx bytes
let bytes = @cli.compile(spec_text, file="report.yxl.yaml")
// .xlsx bytes -> spec text, plus what could not be carried
let result = @cli.extract(bytes, file="existing.xlsx")
println(result.spec)

#From source

git clone https://github.com/t-ujiie-g/yxl.git
cd yxl
moon build --target native --release
install -m 755 _build/native/release/build/cmd/main/main.exe ~/.local/bin/yxl

#Using it

yxl init -o sheet.yxl.yaml                   # a first spec: one empty sheet
yxl build                                    # compile the one *.yxl.yaml here
yxl build report.yxl.yaml                    # compile → report.xlsx
yxl build report.yxl.yaml -o out.xlsx        # … to a path of your choosing
yxl build report.yxl.yaml --check            # validate, write nothing
yxl build report.yxl.yaml -o r.xlsx --set region=EMEA
yxl extract legacy.xlsx -o legacy.yxl.yaml   # existing workbook → starting spec
yxl version                                  # print the version
yxl help                                     # full usage

code --install-extension redhat.vscode-yaml

# yaml-language-server: $schema=https://raw.githubusercontent.com/t-ujiie-g/yxl/main/docs/yxl.schema.json

{
  "yaml.schemas": {
    "https://raw.githubusercontent.com/t-ujiie-g/yxl/main/docs/yxl.schema.json": "*.yxl.yaml"
  }
}

#Examples

yxl build examples/quickstart.yxl.yaml -o quickstart.xlsx

#AI skills

npx skills add t-ujiie-g/yxl        # any agent — installs from skills/

#How it works

report.yxl.yaml
   → parse (YAML → document tree)
   → load + validate + resolve references (typed model, diagnostics naming the file)
   → emit: intern shared styles, strings, and defined names   ← the DRY engine
     via a swappable backend (moonbitlang/mbtexcel)
   → report.xlsx

#Packages

#Development

moon check --deny-warn      # type check
moon test                   # tests
moon fmt                    # format
moon info                   # regenerate the .mbti interface files
moon build --target native  # build the CLI

#License