https://github.com/dancardin/corg

A cog-like tool, written in Rust.
https://github.com/dancardin/corg

Last synced: over 1 year ago
JSON representation

A cog-like tool, written in Rust.

• Host: GitHub
• URL: https://github.com/dancardin/corg
• Owner: DanCardin
• License: apache-2.0
• Created: 2022-01-16T04:26:27.000Z (over 4 years ago)
• Default Branch: main
• Last Pushed: 2022-01-23T13:42:01.000Z (over 4 years ago)
• Last Synced: 2025-01-29T17:44:40.635Z (over 1 year ago)
• Language: Rust
• Size: 27.3 KB
• Stars: 1
• Watchers: 3
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

          
# Corg















 








A [cog](https://nedbatchelder.com/code/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.

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](#CLI) section

is the following block.

```md

```

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

```bash

cargo install corg --features=cli

```

#### Download Release

- Download a pre-built binary from [Releases](https://github.com/DanCardin/corg/releases)

## CLI

The CLI maintains CLI compatibility with `cog` to the extent which makes sense.

Cog exposes a number of options which are only applicable for to its python

implementation, which `corg` does not currently implement.

As mentioned above, `corg` itself, is used to produce output below!

```

corg 0.1.0

A cog-like tool

USAGE:

    corg [OPTIONS] 

ARGS:

        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     The patterns surrounding cog inline instructions. Should include

                               three values separated by spaces, the start, end, and end-output

                               markers

    -o, --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!