# 🛠️ rson-cli
**Command-line tools for RSON (Rust Serialized Object Notation)**
[](https://crates.io/crates/rson-cli)
[](https://docs.rs/rson-cli)
[](LICENSE)
---
## 🎯 **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**
```bash
cargo install rson-cli
```
### **From Source**
```bash
git clone https://github.com/RSON-Rust-Serialized-Object-Notation/RSON-core.git
cd RSON-core/rson-cli
cargo install --path .
```
### **Verify Installation**
```bash
rsonc --version
# rson-cli 0.1.0
```
---
## 📖 **Usage**
### **Basic Commands**
```bash
# 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.
```bash
# 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:**
```bash
# 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.
```bash
# 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:**
```bash
# 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.
```bash
# 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:**
```bash
$ rsonc validate broken.rson
❌ Error in broken.rson:3:15
Expected ':' after field name 'port'
| ^
$ rsonc validate good.rson
✅ good.rson is valid RSON
```
---
### **`rsonc minify`**
Remove comments, whitespace, and trailing commas to create compact RSON.
```bash
# 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:**
```bash
# 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.
```bash
# Basic file info
rsonc info config.rson
# Detailed analysis
rsonc info --detailed config.rson
# Statistics only
rsonc info --stats config.rson
```
**Example:**
```bash
$ rsonc info config.rson
📄 config.rson
Size: 342 bytes
Lines: 15
Type: Struct (Config)
Valid: ✅ Yes
Comments: 3
Fields: 8
```
---
## ⚙️ **Configuration**
### **Global Options**
```bash
# 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:
```toml
# .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**
```yaml
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**
```bash
#!/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:
| **Format** | ~50MB/s | Low |
| **Validate** | ~100MB/s | Minimal |
| **Convert** | ~30MB/s | Low |
| **Minify** | ~80MB/s | Minimal |
*Benchmarks on typical configuration files*
---
## 🎨 **Examples**
### **Batch Processing**
```bash
# 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**
```bash
# Watch for changes and auto-format
fswatch configs/*.rson | xargs -I {} rsonc format --in-place {}
# Convert JSON API response to RSON for inspection
# Quick validation with detailed output
### **Build Scripts**
```bash
#!/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:
```bash
$ rsonc validate broken.rson
❌ Error in broken.rson:5:12
Unexpected token '}'
Expected field name or closing parenthesis
5 | }
| ^
💡 Tip: RSON structs use parentheses (), not braces {}
```
---
## 📖 **Documentation**
- **[CLI Documentation](https://docs.rs/rson-cli)** - Complete API reference
- **[RSON Specification](https://rson.org/docs/spec)** - Language specification
- **[Examples](https://github.com/RSON-Rust-Serialized-Object-Notation/RSON-core/tree/main/rson-cli/examples)** - Usage examples
---
## 🤝 **Contributing**
We welcome contributions! Please see our [Contributing Guide](https://github.com/RSON-Rust-Serialized-Object-Notation/RSON-core/blob/main/CONTRIBUTING.md).
**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](LICENSE) file for details.
---
## 🔗 **Related Projects**
- **[rson-core](https://crates.io/crates/rson-core)** - Core RSON parsing library
- **[serde_rson](https://crates.io/crates/serde_rson)** - Serde integration for RSON
- **[rson-schema](https://crates.io/crates/rson-schema)** - Schema validation
- **[RSON Website](https://rson.org)** - Documentation and playground
---
**Made with 🛠️ by the RSON community**