| Crates.io | colap |
| lib.rs | colap |
| version | 0.1.0 |
| created_at | 2025-07-13 09:44:50.627176+00 |
| updated_at | 2025-07-13 09:44:50.627176+00 |
| description | A lightweight, human-friendly configuration language parser & code generator |
| homepage | https://github.com/a1v0lut10n/colap |
| repository | https://github.com/a1v0lut10n/colap.git |
| max_upload_size | |
| id | 1750254 |
| size | 410,106 |
Tired of fighting with your config files? So were we.
cola is a lightweight, human-friendly configuration language designed to avoid YAMLβs whitespace traps, JSONβs curly-brace fatigue, and TOMLβs dotted-key spaghetti. Itβs backed by colap, a Rust parser and code generator that makes working with configurations effortless.
Cola is:
β
Readable β Clean nesting with minimal punctuation.
β
Writable β No indentation anxiety. No trailing comma drama.
β
Composable β Works standalone or embedded in Markdown as fenced cola ... blocks.
Miss one indent, and your app silently loads nonsense.
Nested configs turn into a forest of {} and [].
Deep nesting forces verbose dotted keys or confusing table headers.
: for nesting and ; to end blocks.Here's a real-world configuration defining multiple LLM providers:
llm plural llms:
openai:
api:
type: "REST",
key: "some_api_key",
base_url: "some_base_url"
;
model plural models:
gpt-4.1:
name: "gpt-4.1",
max_input_tokens: 1048576,
output_price: 8.0,
supports_vision: true
;
gpt-4o:
name: "gpt-4o",
max_input_tokens: 1048576,
output_price: 8.0,
supports_vision: true
;
;
;
;
| Feature | YAML | JSON | TOML | cola |
|---|---|---|---|---|
| Whitespace sensitivity | π¬ Yes | π No | π No | β No |
| Curly brace clutter | π Minimal | π© Lots | π Minimal | β Minimal |
| Trailing commas allowed | β No | β No | β Yes | β Yes |
| Multi-line strings | π€ Hard | π Escapes | β Easy | β Easy |
| Collections (arrays/maps) | π Indents | π© [], {} |
π Mixed | β
Infix plural |
| Markdown embedding | β Awkward | β Awkward | β Awkward | β First-class |
Cola uses ; as a block terminator:
plural?model plural models:
gpt-4:
name: "gpt-4"
;
gpt-4o:
name: "gpt-4o"
;
;
sβ heuristics in code generation.person plural people)..cola files and Markdown files with embedded cola blocksHashMap) from cola modelstype to type_)Add colap to your Rust project:
[dependencies]
colap = "0.1"
The colap codebase is organized into the following modules:
parser: Handles parsing of Cola syntax using rustemo
cola.rs: Generated parser codecola_actions.rs: Parser actionsmodel: Contains the configuration model definitions
config_model.rs: Core configuration model and node typesmodel_builder.rs: Builds config model from parsed ASTsource_location.rs: Source location trackinggenerator: Code generation for Rust structs
generator_impl.rs: Main code generator implementationtemplates/: Handlebars templates for code generationgrammar: Contains the rustemo grammar definition
cola.rustemo: Grammar rules for the Cola languageUSAGE:
colap [OPTIONS] <input>
ARGS:
<input> Input .cola file or markdown containing Cola code blocks
OPTIONS:
-h, --help Print help information
-m, --mode <MODE> Generation mode: 'crate' or 'module' (default: crate)
-n, --crate-name <NAME> Name of the generated library crate (default: input-file-stem-config)
-o, --output <DIR> Base output directory (default: generated)
-V, --version Print version information
Generate a complete Rust crate from a cola file:
colap path/to/myconfig.cola
This will:
myconfig.colagenerated/myconfig-config/Cargo.toml with dependenciessrc/lib.rs with generated structstests/integration.rs with integration testsREADME.md with usage documentationGenerate a single Rust module file for embedding in your project:
colap path/to/myconfig.cola --mode module -o src -n config_parser
This will:
myconfig.colasrc/config_parser.rsmod config_parser; in your projectcolap path/to/myconfig.cola --crate-name my-custom-config --output custom/output/dir
This will:
myconfig.colacustom/output/dir/my-custom-config/custom/output/dir/my-custom-config/lib.rsThe code generator produces:
HashMap) for plural entitiesFor a configuration file with entities like Root, Llm, and Model, the generator produces:
// Root entity struct
pub struct Root {
llm: Llm,
// other fields...
}
// Singular entity
pub struct Llm {
provider: String,
models: Models, // plural entity reference
// other fields...
}
// Plural entity (collection)
pub struct Models {
entries: HashMap<String, Model>,
}
// Entity in a collection
pub struct Model {
name: String,
context_window: i64,
// other fields...
}
The generator maps Cola types to Rust types as follows:
| Cola Type | Rust Type |
|---|---|
| String | String |
| Integer | i64 |
| Float | f64 |
| Boolean | bool |
| Entity | Custom struct |
| Optional Entity | Option<CustomStruct> |
If the --crate-name option is not provided, the crate name is derived from the input file:
-config suffixFor example:
my_config.cola β my-config-configAPI_Model.md β api-model-configThe generated code includes integration tests that demonstrate how to parse configuration files:
use colap::cola::ColaParser;
use colap::model_builder::ModelBuilder;
use my_config::Root; // Generated crate name
// Load and parse a configuration file
fn parse_config_file(path: &str) -> Root {
// Read the file content
let content = std::fs::read_to_string(path).expect("Failed to read config file");
// Create a parser and parse the content
let parser = ColaParser::new();
let result = parser.parse(&content).expect("Failed to parse configuration");
// Build the configuration model
let model = ModelBuilder::build_config_model(&result).expect("Failed to build config model");
// Create the root entity from the model
Root::from_model(&model)
}
// Usage example
let config = parse_config_file("path/to/config.md");
The generated code provides accessor methods for retrieving values:
// Get the LLM configuration
let llm = config.llm();
// Access a singular entity's properties
let provider = llm.provider(); // Returns a &String
// Access a collection (plural entity)
let models = llm.models();
// Get a specific model from the collection
if let Some(gpt4) = models.get("gpt-4.1") {
let context_window = gpt4.context_window(); // Returns an i64
println!("GPT-4.1 context window: {}", context_window);
}
// Iterate through all models
for (name, model) in models.iter() {
println!("Model: {}, Context: {}", name, model.context_window());
}
Optional fields are represented as Option<T> types:
// Optional field access with safe pattern matching
if let Some(api) = llm.api() {
if let Some(key) = api.key() {
println!("API Key: {}", key);
}
}
// Using map() for clean optional chaining
let api_type = llm.api().and_then(|api| api.type_()).unwrap_or("No API type specified");
Colap parses configurations directly from Markdown. Any fenced block marked ```cola is automatically parsed, supporting documentation-driven development.
This project is licensed under the Apache License 2.0.
Copyright 2025 Aivolution GmbH