CLI Guide

The JSSON CLI is your gateway to transpiling JSSON files into JSON. Let’s master it! 🚀

Basic Usage

The simplest way to use JSSON:

jsson -i input.jsson -o output.json

This reads input.jsson and writes the transpiled JSON to output.json.

Command-Line Flags

Input/Output

Flag	Short	Description	Example
--input	-i	Input JSSON file (required)	-i config.jsson
--output	-o	Output file (optional)	-o config.json

Without -o: Output is printed to stdout (terminal)

# Print to terminal
jsson -i config.jsson

# Save to file
jsson -i config.jsson -o config.json

# Pipe to another command
jsson -i config.jsson | jq '.app.name'

Format Options

Flag	Description	Example
--format	Output format: json (default)	--format json
--pretty	Pretty-print JSON output	--pretty
--compact	Compact JSON (no whitespace)	--compact

# Pretty-printed JSON (default)
jsson -i config.jsson -o config.json --pretty

# Compact JSON (one line)
jsson -i config.jsson -o config.json --compact

Help & Version

# Show help
jsson --help
jsson -h

# Show version
jsson --version
jsson -v

Common Workflows

1. Quick Transpilation

jsson -i config.jsson -o config.json

2. Check Output Without Saving

jsson -i config.jsson

Perfect for testing your JSSON before committing!

3. Pipe to Other Tools

# Use with jq
jsson -i config.jsson | jq '.database.host'

# Count lines
jsson -i config.jsson | wc -l

# Search for a value
jsson -i config.jsson | grep "localhost"

4. Batch Processing

PowerShell:

# Convert all .jsson files in a directory
Get-ChildItem *.jsson | ForEach-Object {
    $output = $_.BaseName + ".json"
    jsson -i $_.Name -o $output
}

Bash:

# Convert all .jsson files
for file in *.jsson; do
    jsson -i "$file" -o "${file%.jsson}.json"
done

5. Watch for Changes

PowerShell:

# Simple watch loop
while ($true) {
    jsson -i config.jsson -o config.json
    Start-Sleep -Seconds 2
}

Bash with entr:

# Auto-transpile on file change
ls *.jsson | entr jsson -i config.jsson -o config.json

Integration Examples

NPM Scripts

package.json:

{
  "scripts": {
    "build:config": "jsson -i config.jsson -o dist/config.json",
    "watch:config": "nodemon --watch config.jsson --exec 'npm run build:config'"
  }
}

Makefile

# Makefile
.PHONY: build clean

build: config.json

config.json: config.jsson
\tjsson -i config.jsson -o config.json

clean:
\trm -f config.json

GitHub Actions

.github/workflows/build.yml:

name: Build Config

on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2

      - name: Download JSSON
        run: |
          wget https://github.com/carlosedujs/jsson/releases/latest/download/jsson-linux
          chmod +x jsson-linux

      - name: Transpile JSSON
        run: ./jsson-linux -i config.jsson -o config.json

      - name: Upload artifact
        uses: actions/upload-artifact@v2
        with:
          name: config
          path: config.json

Docker

Dockerfile:

FROM golang:1.21-alpine AS builder

WORKDIR /build
COPY . .
RUN go build -o jsson cmd/jsson/main.go

FROM alpine:latest
COPY --from=builder /build/jsson /usr/local/bin/
COPY config.jsson /app/

WORKDIR /app
RUN jsson -i config.jsson -o config.json

CMD ["cat", "config.json"]

Error Handling

Exit Codes

Code	Meaning
0	Success
1	Error (lex, parse, or transpile error)
2	Invalid arguments

Example:

jsson -i config.jsson -o config.json
if [ $? -eq 0 ]; then
    echo "Success!"
else
    echo "Error transpiling JSSON"
    exit 1
fi

Capturing Errors

PowerShell:

try {
    jsson -i config.jsson -o config.json
    if ($LASTEXITCODE -ne 0) {
        throw "JSSON transpilation failed"
    }
} catch {
    Write-Error $_
    exit 1
}

Bash:

if ! jsson -i config.jsson -o config.json 2> errors.log; then
    echo "Error: $(cat errors.log)"
    exit 1
fi

Tips & Tricks

1. Validate Without Output

# Just check if JSSON is valid
jsson -i config.jsson > /dev/null
echo $?  # 0 = valid, 1 = error

2. Compare Before/After

# See what changed
jsson -i old.jsson > old.json
jsson -i new.jsson > new.json
diff old.json new.json

3. Format Existing JSON

# Re-format JSON using JSSON
jsson -i config.jsson --pretty > formatted.json

4. Environment-Specific Configs

# Development
jsson -i config/dev.jsson -o dist/config.json

# Production
jsson -i config/prod.jsson -o dist/config.json

5. Pre-commit Hook

.git/hooks/pre-commit:

#!/bin/bash
# Transpile JSSON files before commit

for file in $(git diff --cached --name-only | grep '\.jsson$'); do
    output="${file%.jsson}.json"
    jsson -i "$file" -o "$output"
    git add "$output"
done

Troubleshooting

Command Not Found

bash: jsson: command not found

Solution: Add JSSON to your PATH or use the full path:

# Use full path
/path/to/jsson -i config.jsson

# Or add to PATH
export PATH=$PATH:/path/to/jsson

Permission Denied

Permission denied: jsson

Solution: Make it executable:

chmod +x jsson

File Not Found

Error: cannot read file: config.jsson

Solution: Check the file exists and path is correct:

ls -la config.jsson  # Verify file exists
jsson -i ./config.jsson  # Try with ./

Programmatic Usage (Go)

You can also use JSSON as a Go library:

package main

import (
    "fmt"
    "jsson/internal/lexer"
    "jsson/internal/parser"
    "jsson/internal/transpiler"
)

func main() {
    input := `
    user {
        name = João
        age = 25
    }
    `

    // Lex
    l := lexer.New(input)

    // Parse
    p := parser.New(l)
    program := p.ParseProgram()

    // Transpile
    t := transpiler.New()
    json, err := t.Transpile(program)
    if err != nil {
        panic(err)
    }

    fmt.Println(json)
}

What’s Next?

• Getting Started — New to JSSON? Start here
• Syntax Reference — Complete syntax guide
• Errors & Debugging — Troubleshooting help

Master the CLI and integrate JSSON into your workflow! 🎯