🛠️ rson-cli

Command-line tools for RSON (Rust Serialized Object Notation)

🎯 What is rson-cli?

rson-cli provides powerful command-line tools for working with RSON files:

• rsonc - The main RSON compiler/converter tool
• Format and lint RSON files
• Convert between RSON and JSON
• Validate RSON syntax and structure
• Minify and pretty-print RSON data

Perfect for CI/CD pipelines, development workflows, and automation!

🚀 Installation

From Crates.io

cargo install rson-cli

From Source

git clone https://github.com/RSON-Rust-Serialized-Object-Notation/RSON-core.git
cd RSON-core/rson-cli
cargo install --path .

Verify Installation

rsonc --version
# rson-cli 0.1.0

📖 Usage

Basic Commands

# Format an RSON file
rsonc format config.rson

# Convert RSON to JSON
rsonc convert --to json config.rson

# Convert JSON to RSON  
rsonc convert --to rson config.json

# Validate RSON syntax
rsonc validate config.rson

# Minify RSON (remove comments, whitespace)
rsonc minify config.rson

🔧 Commands Reference

rsonc format

Pretty-print and format RSON files with consistent style.

# Format a single file
rsonc format config.rson

# Format multiple files
rsonc format *.rson

# Format in-place (overwrite original)
rsonc format --in-place config.rson

# Custom indentation
rsonc format --indent 4 config.rson

# Output to stdout
rsonc format --stdout config.rson

Example:

# Before formatting
$ cat messy.rson
Config(name:"my-app",version:"1.0",debug:true,features:["auth","logging"])

# After formatting
$ rsonc format messy.rson
Config(
    name: "my-app",
    version: "1.0", 
    debug: true,
    features: ["auth", "logging"],
)

rsonc convert

Convert between RSON and JSON formats.

# RSON to JSON
rsonc convert --to json config.rson
rsonc convert --to json --output config.json config.rson

# JSON to RSON
rsonc convert --to rson config.json
rsonc convert --to rson --output config.rson config.json

# Pretty-print output
rsonc convert --to json --pretty config.rson

# Minify output
rsonc convert --to rson --minify config.json

Example:

# Convert RSON with comments to JSON
$ cat config.rson
// Database configuration
Config(
    host: "localhost",
    port: Some(5432),
    ssl: true,
)

$ rsonc convert --to json config.rson
{
  "host": "localhost",
  "port": 5432,
  "ssl": true
}

rsonc validate

Validate RSON files for syntax errors and structural issues.

# Validate single file
rsonc validate config.rson

# Validate multiple files
rsonc validate *.rson

# Strict validation (no warnings)
rsonc validate --strict config.rson

# Show detailed errors
rsonc validate --verbose config.rson

Example:

$ rsonc validate broken.rson
❌ Error in broken.rson:3:15
   Expected ':' after field name 'port'
   
   2 |     host: "localhost",
   3 |     port Some(5432),
     |             ^
   4 |     ssl: true,

$ rsonc validate good.rson  
✅ good.rson is valid RSON

rsonc minify

Remove comments, whitespace, and trailing commas to create compact RSON.

# Minify file
rsonc minify config.rson

# Minify to specific output
rsonc minify --output config.min.rson config.rson

# Minify multiple files
rsonc minify --suffix .min *.rson

Example:

# Before minifying
$ cat config.rson
// Application config
Config(
    name: "my-app",       // App name
    version: "1.0.0",     // Current version
    debug: true,          // Enable debug mode
)

# After minifying  
$ rsonc minify config.rson
Config(name:"my-app",version:"1.0.0",debug:true)

rsonc info

Show information about RSON files.

# Basic file info
rsonc info config.rson

# Detailed analysis
rsonc info --detailed config.rson

# Statistics only
rsonc info --stats config.rson

Example:

$ rsonc info config.rson
📄 config.rson
   Size: 342 bytes
   Lines: 15
   Type: Struct (Config)
   Valid: ✅ Yes
   Comments: 3
   Fields: 8

⚙️ Configuration

Global Options

# Verbose output
rsonc --verbose format config.rson

# Quiet mode (suppress non-error output)
rsonc --quiet validate *.rson

# Custom config file
rsonc --config .rsonc.toml format config.rson

# Force operation (ignore warnings)
rsonc --force convert --to json invalid.rson

Configuration File

Create .rsonc.toml in your project root:

# .rsonc.toml
[format]
indent = 2
trailing_commas = true
sort_keys = false
max_width = 100

[validate] 
strict = false
allow_comments = true
allow_trailing_commas = true

[convert]
pretty = true
preserve_order = true

🔄 CI/CD Integration

GitHub Actions

name: RSON Validation
on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Install rson-cli
        run: cargo install rson-cli
        
      - name: Validate RSON files
        run: rsonc validate --strict config/*.rson
        
      - name: Check formatting
        run: |
          rsonc format --check config/*.rson
          if [ $? -ne 0 ]; then
            echo "RSON files need formatting. Run: rsonc format config/*.rson"
            exit 1
          fi

Pre-commit Hook

#!/bin/bash
# .git/hooks/pre-commit

# Validate all RSON files
rsonc validate $(find . -name "*.rson")
if [ $? -ne 0 ]; then
    echo "❌ RSON validation failed"
    exit 1
fi

# Auto-format RSON files
rsonc format --in-place $(find . -name "*.rson")
git add $(find . -name "*.rson")

echo "✅ RSON files validated and formatted"

📊 Performance

rson-cli is built for speed:

Benchmarks on typical configuration files

🎨 Examples

Batch Processing

# Format all RSON files in a directory
find ./configs -name "*.rson" -exec rsonc format --in-place {} \;

# Convert all JSON configs to RSON
for file in configs/*.json; do
    rsonc convert --to rson --output "${file%.json}.rson" "$file"
done

# Validate all RSON files and collect errors
rsonc validate configs/*.rson 2> validation_errors.log

Development Workflow

# Watch for changes and auto-format
fswatch configs/*.rson | xargs -I {} rsonc format --in-place {}

# Convert JSON API response to RSON for inspection
curl https://api.example.com/config | rsonc convert --to rson --stdin

# Quick validation with detailed output
rsonc validate --verbose config.rson || echo "Fix errors before commit"

Build Scripts

#!/bin/bash
# build.sh

echo "🔍 Validating RSON configurations..."
rsonc validate config/*.rson || exit 1

echo "📄 Converting RSON to JSON for deployment..."
mkdir -p dist/config
for rson_file in config/*.rson; do
    json_file="dist/config/$(basename "${rson_file%.rson}").json"
    rsonc convert --to json --output "$json_file" "$rson_file"
done

echo "✅ Configuration processing complete"

🐛 Error Handling

rson-cli provides clear, actionable error messages:

$ rsonc validate broken.rson
❌ Error in broken.rson:5:12
   Unexpected token '}'
   Expected field name or closing parenthesis
   
   3 |     name: "test",
   4 |     version: "1.0",
   5 |     }
     |            ^
   6 | )
   
💡 Tip: RSON structs use parentheses (), not braces {}

📖 Documentation

• CLI Documentation - Complete API reference
• RSON Specification - Language specification
• Examples - Usage examples

🤝 Contributing

We welcome contributions! Please see our Contributing Guide.

Areas we need help with:

• Additional CLI commands
• Performance optimizations
• Better error messages
• Shell completion scripts

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Related Projects

• rson-core - Core RSON parsing library
• serde_rson - Serde integration for RSON
• rson-schema - Schema validation
• RSON Website - Documentation and playground

Made with 🛠️ by the RSON community