Corg

A cog-like tool, written in Rust.

Straight from Ned:

Cog is a file generation tool. It lets you use pieces of Python code as generators in your source files to generate whatever text you need.

Being written in python, Cog naturally executes python and integrates more deeply with it than is possible here.

Instead, Corg allows one to choose any executable (python, bash, etc) which accepts piped input. Shown below, Corg uses a shebang-looking mechanism instead.

Example

The most obvious motivating example which comes to mind for this tool is for keeping documentation up-to-date with their sources of truth. Be that, verifying CLI help text, or executing code examples.

This document is a great example. Embedded below at the CLI section is the following block.

<!-- [[[#!/usr/bin/env bash
cargo run --features cli -- --help
]]] -->

And as you can see below, it outputs the help text. See the raw README source, and you'll notice the invisible, commented out sections which are used to produce the output!

The CI for this repo then runs: cargo run --features cli -- README.md -r --check --checksum to verify that it remains in sync.

Installation

With Cargo

cargo install corg --features=cli

Download Release

• Download a pre-built binary from Releases

CLI

Using itself to produce output below!

corg 0.1.0
A cog-like tool

USAGE:
    corg [OPTIONS] <INPUT>

ARGS:
    <INPUT>    The input file

OPTIONS:
    -c, --checksum             Checksum the output to protect it against accidental change
        --check                Check that the files would not change if run again
    -d, --delete-blocks        Delete the generator code from the output file
    -e                         Warn if a file has no cog code in it
    -h, --help                 Print help information
        --markers <MARKERS>    The patterns surrounding cog inline instructions. Should include
                               three values separated by spaces, the start, end, and end-output
                               markers
    -o, --output <OUTPUT>      Write the output to a file instead of stdout
    -r, --replace              Write the output to the original input file, supercedes `--output`
    -V, --version              Print version information
    -x, --omit-output          Omit all the generated output without running the generators

Library

The above CLI is a thin wrapper over the corg internal structures. It's not entirely obvious whether this is useful or not, but it's available!