https://github.com/airsequel/oclis

The obvious CLI specification format. You define the spec, Oclis generates the code! Support for PureScript so far. PRs for more languages appreciated!
https://github.com/airsequel/oclis

argparse cli cli-spec docopt elm haskell nickel optparse optparse-applicative polyglot purescript rust specification

Last synced: 2 months ago
JSON representation

The obvious CLI specification format. You define the spec, Oclis generates the code! Support for PureScript so far. PRs for more languages appreciated!

• Host: GitHub
• URL: https://github.com/airsequel/oclis
• Owner: Airsequel
• License: isc
• Created: 2024-02-03T13:55:19.000Z (11 months ago)
• Default Branch: main
• Last Pushed: 2024-02-22T14:24:29.000Z (10 months ago)
• Last Synced: 2024-10-12T20:02:14.642Z (2 months ago)
• Topics: argparse, cli, cli-spec, docopt, elm, haskell, nickel, optparse, optparse-applicative, polyglot, purescript, rust, specification
• Language: Rust
• Homepage:
• Size: 176 KB
• Stars: 5
• Watchers: 2
• Forks: 0
• Open Issues: 11
• Metadata Files:
  • Readme: readme.md
  • Changelog: changelog.md
  • License: license.txt

Awesome Lists containing this project

README

        
# Oclis

CLI (Command Line Interface) app builder

based on a simple, obvious specification file.

## Motivation

Building a CLI application is a repetitive task.

The same code is written over and over again.

But fear not, Oclis is here to help you out!

## Usage

1. `cargo install oclis`

1. `oclis init` - Creates an `oclis.ncl` specifcation file.

1. Adapt the specification file to your liking. \

   (Check out the [examples directory](./examples) for inspiration.)

1. Run `oclis build` to generate the CLI parsing code \

   (It automatically detects the main repo language,

   but only PureScript is supported at the moment.)

1. Add missing dependencies to your project. \

   (E.g. for PureScript check out the

   [spago.yaml](./purescript/spago.yaml) file.)

1. Define the handler functions for your commands. \

   (Check out the [main function of Transity][tr-main] for an example.)

1. Commit the generated code to the repository.

[tr-main]: https://github.com/feramhq/Transity/blob/master/src/Main.purs#L332

## How It Works

### Processing Pipeline of the Generated CLI App

![Processing Pipeline](./processing-pipeline.svg)

### Unsupported CLI designs

Some features of other CLI frameworks are deliberately not supported:

- Specifying a flag several times. (e.g. `tar -v -v -v`)

   This is error prone as it's easy to accidentally add it several times.

   Use a numerical verbosity flag instead (e.g. `tar -v=3`)

   or define your own counting system (e.g. `tar -v=xxx`)

- Specifying flags/options after the arguments.

   (e.g. `pandoc in.md --output=out.pdf`)

   Disallowing this helps to prevent errors from accidentally providing

   an argument which is understood as a flag/option.

   Suggested alternatives:

   - Sub-command: `pandoc convert in.md out.pdf`

   - Option first: `pandoc --output=out.pdf in.md`

   - Extra option: `pandoc --input=in.md --output=out.pdf`

## Related

### Other CLI Builders

- [CLI Definition Language] - DSL for defining command line interfaces

    of C++ programs.

- [Decli] - Declarative CLI tool builder.

- [docopt] - Command-line interface description language.

- [make-cli] - Declarative CLI framework for Node.js.

[CLI Definition Language]: https://www.codesynthesis.com/projects/cli/

[Decli]: https://github.com/woile/decli

[docopt]: http://docopt.org/

[make-cli]: https://github.com/dword-design/make-cli

### Manual CLI Frameworks

Check out the repo

[awesome-cli-frameworks](https://github.com/shadawck/awesome-cli-frameworks)

for a full overview.

### Specifications

- [clig.dev] - Command Line Interface Guidelines.

- [GNU Table of Long Options][gtolo]

- [Heroku CLI Style Guide][hcsg]

- [OpenAutoComplete] - CLI autocomplete specification.

- [POSIX Utility Conventions][puc]

[clig.dev]: https://clig.dev

[gtolo]:

  https://www.gnu.org/prep/standards/html_node/Option-Table.html#Option-Table

[hcsg]: https://devcenter.heroku.com/articles/cli-style-guide

[OpenAutoComplete]: https://github.com/openautocomplete/openautocomplete

[puc]: https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap12.html

### Generate GUIs From CLI

- [Claui] - A GUI generator for [clap] using [egui].

- [Gooey] - Turn CLI programs into a full GUI application.

- [Klask] - Automatically create GUI applications from [clap] apps.

[clap]: https://github.com/clap-rs/clap

[Claui]: https://github.com/grantshandy/claui

[egui]: https://github.com/emilk/egui

[Gooey]: https://github.com/chriskiehl/Gooey

[Klask]: https://github.com/MichalGniadek/klask

### Generate GUIs From Simple Code

- [Sparkle] - Infer user interfaces from type signatures.

- [Streamlit] - Turns data scripts into shareable web apps.

[Sparkle]: https://github.com/sharkdp/purescript-sparkle

[Streamlit]: https://github.com/streamlit/streamlit