ryg-rans-rs-cli

CLI tools for rANS encode, decode, inspect, trace, compare, and bench

Overview

This crate provides command-line tools for working with rANS entropy coding. It is currently a scaffold — the binary compiles and prints a usage message, but the subcommands are not yet implemented.

The CLI is designed around subcommands powered by the clap crate. When fully implemented, it will serve as both a developer utility for debugging and inspecting rANS streams and a benchmarking tool for evaluating encoding/decoding throughput.

Planned Commands

Encode

ryg-rans-rs encode --input file.bin --output file.rans --model model.json

Planned options: alphabet size, scale bits, interleave count, block size, verbosity.

Decode

ryg-rans-rs decode --input file.rans --output file.bin

Planned options: auto-detect scale bits and model from stream header.

Inspect

ryg-rans-rs inspect file.rans

Planned output: stream metadata (scale bits, symbol count, final state), per-block statistics, entropy analysis.

Trace

ryg-rans-rs trace --input file.bin --model model.json

Planned output: per-symbol state transitions (state values, emitted bytes, cumulative frequencies), useful for debugging encoder/decoder mismatches.

Compare

ryg-rans-rs compare --rust file.rans --oracle ./oracle_adapter --casefiles ./cases/

Planned behavior: invoke the oracle harness and display side-by-side diff of residuals.

Bench

ryg-rans-rs bench --size 1MB --iterations 100

Planned metrics: encode throughput (MB/s), decode throughput (MB/s), state throughput (Msym/s), cycle counts, branch mispredictions, cache misses.

Current Status

$ ryg-rans-rs
ryg-rans-rs-cli - rANS encoding tools
Usage: ryg-rans-rs encode|decode|inspect|trace|compare|bench

The binary currently prints a usage hint and exits. No subcommand dispatch, argument parsing, or actual rANS logic is wired up yet.

Cargo Features

The crate always depends on ryg-rans-rs (for the rANS implementation) and clap (for CLI argument parsing). The simd and alloc features of ryg-rans-rs are inherited transitively through the dependency.

Development

To run the scaffold binary:

cargo run --package ryg-rans-rs-cli

To add a new subcommand, follow the clap derive pattern in src/main.rs:

use clap::{Parser, Subcommand};

#[derive(Parser)]
struct Cli {
    #[command(subcommand)]
    command: Command,
}

#[derive(Subcommand)]
enum Command {
    Encode { /* ... */ },
    Decode { /* ... */ },
    // ...
}

Dependencies