# flood-tide
[![crate][crate-image]][crate-link]
[![Docs][docs-image]][docs-link]
![Rust Version][rustc-image]
![Apache2/MIT licensed][license-image]
[![Test ubu][test-ubuntu-image]][test-ubuntu-link]
[![Test mac][test-windows-image]][test-windows-link]
[![Test win][test-macos-image]][test-macos-link]
Command line flag and option parse utilities.
## Features
- `no_std` and `std` are supported.
- flags, options, subcommand and free arguments
- short flags and options (like `-a`)
- long flags and options (like `--long`)
- combined short flags (like `-abc` ::= `-a` `-b` `-c`)
- single long options (like `-long`)
- abbreviate long options (like `--abbr` ::= `--abbreviate`)
- single error or multiple errors
- only UTF-8 arguments
- it can be used optimally by a compile switch with many features.
- minimum support rustc 1.60.0 (7737e0b5c 2022-04-04)
## Todos
- [x] multiple errors
- [x] `no_std`
- [ ] option suggestion (do you mean? '--abc')
- [ ] windows style (like `/a`)
- [ ] source code generator support tools
- [ ] more easy use
## Non-Supports
- procedural macro style
- traditional macro style
- non UTF-8 arguments, multibyte or wide charactor
## Examples
in [examples](https://github.com/aki-akaguma/flood-tide/tree/main/examples) directory.
- manual coding style: bsd-sed.rs, gnu-cat.rs
- single long options: ffmpeg.rs
- source code generating by xtask and parse_simple_gnu_style(): curl.rs
## Supports
- [flood-tide-gen](https://crates.io/crates/flood-tide-gen) - the generating *flood-tide* tables
- [aki-gsub](https://crates.io/crates/aki-gsub) - the sample used *flood-tide*
## Alternatives
This parser is *not* a new special idea. It's just comparing characters one by one.
Is there anything simpler than this?
- [clap](https://crates.io/crates/clap) - is the most popular and complete one
- [structopt](https://crates.io/crates/structopt) - clap parser that uses procedural macros
- [gumdrop](https://crates.io/crates/gumdrop) - a simple parser that uses procedural macros
- [argh](https://crates.io/crates/argh) - procedural macros
- [rustop](https://crates.io/crates/rustop) - traditional macro
- [pico-args](https://crates.io/crates/pico-args) - a simple use
- [getopts](https://crates.io/crates/getopts) - a simple use
- [docopt](https://crates.io/crates/docopt) - a simple use
## Benchmarks
The comparing performance and .text size.
- compiled by rustc 1.66.0 (69f9c33d7 2022-12-12)
| cmp_null_void | 1.327 kc | 316 kib | 0.000 kc | 0 kib |
| **cmp_flood_tide** | 6.315 kc | 356 kib | 4.988 kc | 40 kib |
| cmp_pure_rust | 7.951 kc | 368 kib | 6.624 kc | 52 kib |
| cmp_gumdrop | 11.346 kc | 432 kib | 10.019 kc | 116 kib |
| cmp_argh | 20.851 kc | 385 kib | 19.524 kc | 69 kib |
| cmp_pico_args | 39.187 kc | 393 kib | 37.860 kc | 77 kib |
| cmp_rustop | 379.726 kc | 465 kib | 378.399 kc | 149 kib |
| cmp_clap | 415.422 kc | 988 kib | 414.095 kc | 671 kib |
| cmp_clap3 | 495.219 kc | 840 kib | 493.893 kc | 524 kib |
| cmp_structopt | 553.679 kc | 862 kib | 552.352 kc | 546 kib |
| cmp_getopts | 637.986 kc | 395 kib | 636.659 kc | 78 kib |
| cmp_commander | 665.407 kc | 412 kib | 664.080 kc | 95 kib |
| cmp_lapp | 1115.093 kc | 451 kib | 1113.766 kc | 135 kib |
| cmp_args | 2101.706 kc | 427 kib | 2100.379 kc | 110 kib |
| cmp_app | 2192.245 kc | 630 kib | 2190.918 kc | 313 kib |
- compiled by rustc 1.57.0 (f1edd0429 2021-11-29)
| cmp_null_void | 1.405 kc | 316 kib | 0.000 kc | 0 kib |
| **cmp_flood_tide** | 5.603 kc | 356 kib | 4.197 kc | 40 kib |
| cmp_pure_rust | 7.845 kc | 368 kib | 6.439 kc | 52 kib |
| cmp_gumdrop | 8.737 kc | 432 kib | 7.332 kc | 116 kib |
| cmp_argh | 23.114 kc | 385 kib | 21.708 kc | 69 kib |
| cmp_pico_args | 41.325 kc | 393 kib | 39.920 kc | 77 kib |
| cmp_rustop | 394.432 kc | 465 kib | 393.026 kc | 149 kib |
| cmp_clap | 426.678 kc | 988 kib | 425.273 kc | 671 kib |
| cmp_clap3 | 495.857 kc | 840 kib | 494.452 kc | 524 kib |
| cmp_structopt | 576.224 kc | 862 kib | 574.818 kc | 546 kib |
| cmp_getopts | 657.353 kc | 395 kib | 655.948 kc | 78 kib |
| cmp_commander | 673.761 kc | 412 kib | 672.356 kc | 95 kib |
| cmp_lapp | 1089.452 kc | 451 kib | 1088.047 kc | 135 kib |
| cmp_args | 2066.320 kc | 427 kib | 2064.915 kc | 110 kib |
| cmp_app | 2171.903 kc | 630 kib | 2170.498 kc | 313 kib |
- `us` is micro seconds
- `.text` is elf .text section size
- `Δ`(delta) is the difference from cmp_null_void
- `cmp_null_void` is non parser, support only `--help` and `--version`
- `cmp_pure_rust` is newly written with sting match
- bench on intel Q6600 @ 2.40GHz
- refer [comparison of various parsers](https://github.com/aki-akaguma/cmp_cmdopts_parsing)
# Changelogs
[This crate's changelog here.](https://github.com/aki-akaguma/flood-tide/blob/main/CHANGELOG.md)
# License
This project is licensed under either of
* Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or
https://www.apache.org/licenses/LICENSE-2.0)
* MIT license ([LICENSE-MIT](LICENSE-MIT) or
https://opensource.org/licenses/MIT)
at your option.
[//]: # (badges)
[crate-image]: https://img.shields.io/crates/v/flood-tide.svg
[crate-link]: https://crates.io/crates/flood-tide
[docs-image]: https://docs.rs/flood-tide/badge.svg
[docs-link]: https://docs.rs/flood-tide/
[rustc-image]: https://img.shields.io/badge/rustc-1.60+-blue.svg
[license-image]: https://img.shields.io/badge/license-Apache2.0/MIT-blue.svg
[test-ubuntu-image]: https://github.com/aki-akaguma/flood-tide/actions/workflows/test-ubuntu.yml/badge.svg
[test-ubuntu-link]: https://github.com/aki-akaguma/flood-tide/actions/workflows/test-ubuntu.yml
[test-macos-image]: https://github.com/aki-akaguma/flood-tide/actions/workflows/test-macos.yml/badge.svg
[test-macos-link]: https://github.com/aki-akaguma/flood-tide/actions/workflows/test-macos.yml
[test-windows-image]: https://github.com/aki-akaguma/flood-tide/actions/workflows/test-windows.yml/badge.svg
[test-windows-link]: https://github.com/aki-akaguma/flood-tide/actions/workflows/test-windows.yml