https://github.com/parasyte/onlyargs

Only argument parsing! Nothing more.
https://github.com/parasyte/onlyargs

Last synced: 10 months ago
JSON representation

Only argument parsing! Nothing more.

• Host: GitHub
• URL: https://github.com/parasyte/onlyargs
• Owner: parasyte
• License: mit
• Created: 2023-03-23T04:46:44.000Z (almost 3 years ago)
• Default Branch: main
• Last Pushed: 2024-02-22T17:05:32.000Z (almost 2 years ago)
• Last Synced: 2024-05-02T01:22:46.835Z (over 1 year ago)
• Language: Rust
• Size: 94.7 KB
• Stars: 13
• Watchers: 1
• Forks: 2
• Open Issues: 5
• Metadata Files:
  • Readme: README.md
  • Funding: .github/FUNDING.yml
  • License: LICENSE

Awesome Lists containing this project

README

          
[![Crates.io](https://img.shields.io/crates/v/onlyargs)](https://crates.io/crates/onlyargs "Crates.io version")

[![Documentation](https://img.shields.io/docsrs/onlyargs)](https://docs.rs/onlyargs "Documentation")

[![unsafe forbidden](https://img.shields.io/badge/unsafe-forbidden-success.svg)](https://github.com/rust-secure-code/safety-dance/)

[![GitHub actions](https://img.shields.io/github/actions/workflow/status/parasyte/onlyargs/ci.yml?branch=main)](https://github.com/parasyte/onlyargs/actions "CI")

[![GitHub activity](https://img.shields.io/github/last-commit/parasyte/onlyargs)](https://github.com/parasyte/onlyargs/commits "Commit activity")

[![GitHub Sponsors](https://img.shields.io/github/sponsors/parasyte)](https://github.com/sponsors/parasyte "Sponsors")

Only argument parsing! Nothing more.

# Why?

- 100% safe Rust 🦀.

- Correctness: Paths with invalid UTF-8 work correctly on all platforms.

- Fast compile times.

- Convenience: `#[derive(OnlyArgs)]` on a struct and parse CLI arguments from the environment into it with minimal boilerplate.

## MSRV Policy

The Minimum Supported Rust Version for `onlyargs` will always be made available in the [MSRV.md](./MSRV.md) file on GitHub.

# Rationale

There's an [argument parsing crate for everyone](https://github.com/rosetta-rs/argparse-rosetta-rs). So why write another?

`onlyargs` is an example of extreme minimalism! The only thing it provides is a trait and some utility functions; you're expected to do the actual work to implement it for your CLI argument struct. But don't let that scare you away! The parser implementation in the ["full" example](./examples/full/src/main.rs) is only around 50 lines! (Most of the file is boilerplate.)

The goals of this parser are correctness, fast compile times, and convenience.

## 100% safe Rust

No shenanigans! The only `unsafe` code is abstracted away in the standard library.

## Correctness

- The main parsing loop uses `OsString` so that invalid UTF-8 can be accepted as an argument.

- Arguments can either be stored directly as an `OsString` or converted to a `PathBuf` with no extra cost. Easily access your [mojibake](https://en.wikipedia.org/wiki/Mojibake) file systems!

- Conversions from `OsString` are handled by your parser implementation. It's only as correct as you want it to be!

- Play with the examples. Try to break it. Have fun!

## Fast compile times

See [`myn` benchmark results](https://github.com/parasyte/myn/blob/main/benchmarks.md).

## Convenience

Argument parsing is dead simple (assuming your preferred DSL is opinionated and no-nonsense). There is no reason to overcomplicate it by supporting multiple forms like `--argument 123` and `--argument=123` or `-a 123` and `-a123`. _Just pick one!_

The provided examples use the former in both cases: `--argument 123` and `-a 123` are accepted for arguments with a value. Supporting both long and short argument names is just a pattern!

```rust

Some("--argument") | Some("-a")

```

It is fairly straightforward to derive an implementation with a proc_macro. Compare the ["full-derive" example](./examples/full-derive/src/main.rs) to the "full" example.