jcl 1.0.0

Jack-of-All Configuration Language - A general-purpose configuration language with powerful built-in functions
Documentation

JCL - Jack-of-All Configuration Language

A modern, safe, and flexible general-purpose configuration language with powerful built-in functions, written in Rust.

Vision

JCL is a general-purpose configuration language designed to be human-readable, type-safe, and powerful. It provides a rich standard library of functions for data manipulation, encoding/decoding (YAML, JSON, Base64), templating, string operations, and more. Built in Rust for performance and safety, JCL can be embedded in other tools (like Hemmer for IaC) or used standalone for configuration management.

Installation

Via Cargo (Rust)

cargo install jcl

Via Binary Download

Download pre-built binaries from the releases page.

From Source

git clone https://github.com/turner-hemmer/jcl.git
cd jcl
cargo build --release

Quick Start

# Run the interactive REPL
jcl

# Evaluate a JCL file
jcl eval config.jcl

# Format JCL files
jcl-fmt config.jcl

# Validate against a schema
jcl-validate --schema schema.jcl config.jcl

# Migrate from other formats
jcl-migrate config.json --from json

Documentation

Key Features

🎯 General-Purpose Configuration

  • Clean, human-readable syntax with minimal punctuation
  • Rich standard library of 70+ built-in functions
  • Can be embedded or used standalone

🔒 Type Safety

  • Advanced static type inference catches errors before runtime
  • Expression-level type checking with Hindley-Milner style inference
  • Runtime type validation with annotations
  • Immutability by default

🚀 Powerful Built-in Functions

  • String operations: upper, lower, trim, replace, split, join, format
  • Encoding/Decoding: JSON, YAML, TOML, Base64, URL encoding
  • Collections: merge, lookup, keys, values, sort, distinct, flatten
  • Numeric: min, max, sum, avg, abs, ceil, floor, round
  • Hashing: MD5, SHA1, SHA256, SHA512
  • Templating: String interpolation, conditional content, loops in templates
  • Filesystem: file, fileexists, dirname, basename
  • Type conversion: tostring, tonumber, tobool
  • And more...

🏗️ Flexible Syntax

  • Parentheses-based grouping (not braces)
  • Dot notation for namespacing
  • No quotes needed for simple values
  • String interpolation: "Hello, ${name}!"
  • Progressive disclosure: can be concise or explicit

Example

# Simple, readable configuration
environments = (prod, dev, staging)

env.prod = (
  region = us-west-2

  vars (
    app_name = myapp
    version = 1.2.3
    replicas = 3
  )

  tags (
    team = platform
    cost_center = engineering
  )
)

# String interpolation
greeting = "Hello, ${env.prod.vars.app_name}!"

# Built-in functions
uppercased = upper(env.prod.vars.app_name)
config_json = jsonencode(env.prod.vars)
config_yaml = yamlencode(env.prod.vars)

# Collections and data manipulation
regions = (us-west-2, us-east-1, eu-west-1)
region_count = length(regions)
merged_tags = merge(env.prod.tags, (environment=prod managed_by=jcl))

# List comprehensions and pipelines
formatted_regions = regions
  | map r => upper(r)
  | sort
  | join ", "

# Template rendering
nginx_config = templatefile(nginx.conf.tpl, (
  port = 8080
  server_name = env.prod.vars.app_name
))

Features

Core Language

  • Type System: Advanced static type inference with expression-level checking
  • Collections: Lists [] and maps () with comprehensive manipulation functions
  • String Interpolation: "Hello, ${name}!" syntax for dynamic strings
  • Null Safety: ?. optional chaining and ?? null coalescing operators
  • Functions: Lambda expressions (x => x * 2) and named functions (fn double(x) = x * 2)
  • Control Flow: Ternary operators, if/then/else, when expressions
  • List Comprehensions: [x * 2 for x in numbers if x > 0]
  • Error Handling: try() for graceful error recovery
  • Import System: Modular configuration files

Tooling Ecosystem

  • REPL: Interactive shell with history and state management
  • Formatter (jcl-fmt): Automatic code formatting with configurable style
  • Linter: 9 comprehensive lint rules for code quality
  • LSP: Full Language Server Protocol support (diagnostics, autocomplete, go-to-definition, rename)
  • Validator (jcl-validate): Schema-based validation
  • Migrator (jcl-migrate): Convert from JSON, YAML, TOML to JCL
  • Watcher (jcl-watch): Auto-format on file changes
  • Benchmarking (jcl-bench): Performance measurement tools

Multi-Language Support

  • Rust: Native implementation (crate available on crates.io)
  • Python: PyO3 bindings for Python integration
  • Node.js: Neon bindings for JavaScript/TypeScript
  • Go: cgo bindings for Go projects
  • Java: JNI bindings for Java applications
  • Ruby: Magnus bindings for Ruby gems
  • WebAssembly: Browser and serverless support
  • C FFI: Embed in any language with C interop

Editor Support

  • VSCode: Full syntax highlighting and LSP integration
  • Vim/Neovim: Syntax files and LSP support
  • Any LSP-compatible editor: Diagnostics, autocomplete, formatting

Architecture

Parser → Type Checker → Evaluator (with Functions) → Output

Built in Rust for:

  • Memory safety and performance
  • Strong type system
  • Fast parsing and evaluation
  • Easy embedding in other tools
  • Cross-platform support

Project Status

JCL v1.0.0 is production-ready! ✅

  • 144 tests passing (117 unit + 18 CLI + 9 integration)
  • Zero compiler warnings
  • Complete documentation with interactive examples
  • Multi-language bindings for Python, Node.js, Go, Java, Ruby
  • Full LSP support for modern editors
  • CI/CD pipeline with automated testing and releases

See CHANGELOG.md for version history.

Why JCL?

vs. HCL (HashiCorp Configuration Language):

  • More human-readable syntax (less verbose, no braces)
  • Richer built-in function library (70+ functions including higher-order functions)
  • Advanced static type inference catches errors before runtime
  • Runtime type validation with annotations
  • Cleaner string interpolation
  • Built-in code formatter and linter

vs. YAML:

  • Type-safe with validation
  • Powerful built-in functions
  • String interpolation and templates
  • Better error messages

vs. JSON:

  • Human-readable (comments, no quotes required)
  • Computed values and expressions
  • Functions and data transformation
  • Variables and references

vs. Full Programming Languages (Python, TypeScript):

  • Purpose-built for configuration
  • Simpler and more constrained
  • Easier to learn and audit
  • Can't execute arbitrary code (safer)

Contributing

We welcome contributions! Please see CONTRIBUTING.md for:

  • Code of conduct
  • Development setup
  • Testing requirements
  • Pull request process
  • Coding standards

For bugs, feature requests, or questions:

Security

Found a security vulnerability? Please see SECURITY.md for responsible disclosure guidelines.

License

Licensed under either of:

at your option.

Community

Built with ❤️ in Rust