kvf

A minimal, spec-compliant Rust parser library for Kv Format 1.0.

About Kv Format

Kv Format is a minimal key-value file format designed for simplicity and correctness. This crate implements a parser fully compliant with the Kv Format 1.0 RC1 specification.

For full details on the format's syntax, error handling, and design rationale, see kvformat.org.

Add to your project

[dependencies]
kvf = "0.1.0"

Eager parsing

use kvf::{parse, Entry};

fn main() {
    let input = b"APP_NAME=My Application\nDEBUG=true\n";

    match parse(input) {
        Ok(entries) => {
            for entry in entries {
                if let Entry::Kv { key, value, .. } = entry {
                    println!("{key} = {value}");
                }
            }
        }
        Err(errors) => {
            for e in errors {
                eprintln!("Error: {e}");
            }
        }
    }
}

Streaming parsing

use kvf::{parse_iter, Entry};

fn main() {
    let input = b"KEY=value\n# a comment\n";

    for result in parse_iter(input) {
        match result {
            Ok(Entry::Kv { key, value, line }) => {
                println!("line {line}: {key} = {value}");
            }
            Ok(Entry::Comment { text, line }) => {
                println!("line {line}: # {text}");
            }
            Err(e) => eprintln!("parse error: {e}"),
            _ => {}
        }
    }
}

Custom configuration

use kvf::{parse_with_config, Entry, ParserConfig};

fn main() {
    let config = ParserConfig {
        emit_comments: false, // suppress comment entries
        emit_blanks: true,    // include blank-line entries
        emit_shebang: true,   // include the shebang entry (if present)
    };

    let input = b"#!/usr/bin/env kvf\n# ignored comment\nKEY=value\n\n";
    let entries = parse_with_config(input, &config).unwrap();

    for entry in &entries {
        println!("{entry:?}");
    }
}

Error types

All errors implement std::fmt::Display and std::error::Error. Error variants correspond to the error codes defined in Appendix B of the Kv Format 1.0 specification:

License

Licensed under either of Apache License, Version 2.0 or MIT license, at your option.