feat(clasp-rs): parse flags, options, and values against the C corpus

CHANGES.md

@@ -1,6 +1,13 @@
 # CLASP.Rust - Changes <!-- omit in toc -->
 
 
+## 0.1.0 - 28th October 2026
+
+* added the parse core (`parse`, specifications, arguments, and used-tracking queries) with an empty `[dependencies]` table;
+* added the in-tree conformance snapshot, local cases, **scripts/sync_conformance.sh**, and the conformance runner;
+* added the **minimal-usage** example and the conformance notes in **README.md**;
+
+
 ## 0.0.1 - 28th October 2026
 
 * added the initial **CLASP.Rust** crate and Cargo package metadata;

Cargo.toml

@@ -21,6 +21,8 @@ exclude = [
 	".vscode",
 	"scripts",
 	"target",
+	"test/conformance/local",
+	"test/conformance/shared",
 ]
 homepage = "https://github.com/synesissoftware/CLASP.Rust"
 keywords = [
@@ -34,7 +36,7 @@ name = "clasp-rs"
 readme = "README.md"
 repository = "https://github.com/synesissoftware/CLASP.Rust"
 rust-version = "1.74"
-version = "0.0.1"
+version = "0.1.0"
 
 
 # ##########################################################
@@ -44,10 +46,22 @@ version = "0.0.1"
 name = "clasp_rs"
 path = "src/lib.rs"
 
+[[example]]
+name = "minimal-usage"
+path = "examples/minimal-usage/main.rs"
+
 [[example]]
 name = "versions"
 path = "examples/versions/main.rs"
 
+[[test]]
+name = "conformance"
+path = "test/conformance/main.rs"
+
+[[test]]
+name = "unit"
+path = "test/unit/main.rs"
+
 
 # ##########################################################
 # Features
@@ -77,10 +91,20 @@ null-feature = []
 
 [dependencies]
 
+base-traits = { version = "0.2", default-features = false, features = [
+]}
+
+
 [dev-dependencies]
 
+serde_json = { version = "1", default-features = false, features = [
+	"std",
+]}
 test_help-rs = { version = "0.2", default-features = false, features = [
 ]}
+woad = { version = "0", default-features = false, features = [
+]}
+
 
 
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html

EXAMPLES.md

@@ -1,9 +1,10 @@
 # CLASP.Rust - Examples <!-- omit in toc -->
 
 
-| Name         | Source                                | Summary                            |
-| ------------ | ------------------------------------- | ---------------------------------- |
-| **versions** | [Source](./examples/versions/main.rs) | Prints the crate name and version. |
+| Name              | Source                                     | Summary                                                          |
+| ----------------- | ------------------------------------------ | ---------------------------------------------------------------- |
+| **minimal-usage** | [Source](./examples/minimal-usage/main.rs) | Parses arguments and prints flags, options, values, and unused. |
+| **versions**      | [Source](./examples/versions/main.rs)      | Prints the crate name and version.                               |
 
 
 <!-- ########################### end of file ########################### -->

README.md

@@ -25,6 +25,7 @@ Command-Line Argument Sorting and Parsing (for Rust)
   - [Structures](#structures)
   - [Traits](#traits)
 - [Examples](#examples)
+- [Conformance](#conformance)
 - [Project Information](#project-information)
   - [Where to get help](#where-to-get-help)
   - [Contribution guidelines](#contribution-guidelines)
@@ -40,7 +41,7 @@ Command-Line Argument Sorting and Parsing (for Rust)
 
 ## Introduction
 
-**CLASP** stands for **C**ommand-**L**ine **A**rgument **S**orting and **P**arsing. **CLASP.Rust** is an initial published scaffold with no supported public API. The reference implementation is the C/C++ [**CLASP**](https://github.com/synesissoftware/CLASP) library. The other implementations are listed under [Related projects](#related-projects).
+**CLASP** stands for **C**ommand-**L**ine **A**rgument **S**orting and **P**arsing. **CLASP.Rust** parses a command line into flags, options, and values, using the same rules as the C/C++ [**CLASP**](https://github.com/synesissoftware/CLASP) library. The other implementations are listed under [Related projects](#related-projects).
 
 
 ## Developer Experience
@@ -53,28 +54,69 @@ cargo test
 ./scripts/fmt
 ```
 
-**scripts/fmt** runs the pinned nightly **rustfmt** described in **rustfmt.toml**. The stock example is **examples/versions/main.rs**.
+**scripts/fmt** runs the pinned nightly **rustfmt** described in **rustfmt.toml**. The stock example is **examples/versions/main.rs**. The smallest parse is **examples/minimal-usage/main.rs**:
+
+```rust
+use clasp_rs::{
+    parse,
+    ParseFlags,
+    Specification,
+};
+
+fn main() {
+    let specifications = [
+        Specification::flag(Some("-v"), Some("--verbose"), None),
+        Specification::option(Some("-n"), Some("--name"), Some("a name"), None),
+    ];
+    let argv = std::env::args().collect::<Vec<_>>();
+    let parsed = parse(ParseFlags::empty(), &argv, Some(&specifications));
+
+    println!("{}", parsed.program_name());
+
+    for argument in parsed.flags() {
+        println!("  {argument}");
+    }
+    for argument in parsed.options() {
+        println!("  {argument}");
+    }
+    for argument in parsed.values() {
+        println!("  {argument}");
+    }
+    for argument in parsed.unused_arguments() {
+        println!("  {argument}");
+    }
+}
+```
+
+That call sorts flags, then options, then values. Marking queries such as `flag_is_specified` set the used bit; printing the partitions does not. See [Conformance](#conformance) for the C corpus.
 
 
 ## Installation
 
 Reference in **Cargo.toml** in the usual way:
 
 ```toml
-clasp-rs = { version = "0.0.1" }
+clasp-rs = { version = "0.1.0" }
 ```
 
 
 ## Components
 
 ### Constants
 
-None defined at this time.
+Parse flags, on [`ParseFlags`](https://docs.rs/clasp-rs/latest/clasp_rs/struct.ParseFlags.html). The values match the C header:
+
+* `DONT_EXPAND_WILDCARDS_ON_WINDOWS` — accepted, and it has no effect (version 1 does not expand wildcards);
+* `DONT_RECOGNISE_DOUBLEHYPHEN_TO_START_VALUES`;
+* `DO_EXPAND_WILDCARDS_IN_APOSQUOTES_ON_WINDOWS` — accepted, and it has no effect;
+* `PRESERVE_ORIGINAL_ARGUMENT_ORDER` — the result stays in `argv` order and the three partitions are empty;
+* `TREAT_SINGLEHYPHEN_AS_VALUE`;
 
 
 ### Enumerations
 
-None defined at this time.
+* [`ArgumentKind`](https://docs.rs/clasp-rs/latest/clasp_rs/enum.ArgumentKind.html) — `Flag`, `Option`, `Value`;
+* [`SpecificationType`](https://docs.rs/clasp-rs/latest/clasp_rs/enum.SpecificationType.html) — `Flag`, `Gap`, `Option`, `Section`, `Tacit`;
 
 
 ### Features
@@ -86,7 +128,7 @@ The following crate features are defined:
 
 ### Functions
 
-None defined at this time.
+* [`parse`](https://docs.rs/clasp-rs/latest/clasp_rs/fn.parse.html) — sort `argv` into flags, options, and values;
 
 
 ### Macros
@@ -96,21 +138,44 @@ None defined at this time.
 
 ### Structures
 
-None defined at this time.
+* [`Argument`](https://docs.rs/clasp-rs/latest/clasp_rs/struct.Argument.html) — one parsed flag, option, or value, including the used bit;
+* [`Arguments`](https://docs.rs/clasp-rs/latest/clasp_rs/struct.Arguments.html) — the program name, the sorted arguments, and the three partitions;
+* [`ParseFlags`](https://docs.rs/clasp-rs/latest/clasp_rs/struct.ParseFlags.html) — the C parse-flag bit set;
+* [`Report`](https://docs.rs/clasp-rs/latest/clasp_rs/struct.Report.html) — one hit from a nonmutating report query;
+* [`Specification`](https://docs.rs/clasp-rs/latest/clasp_rs/struct.Specification.html) — one alias, mapped argument, help string, value set, bit value, or section;
 
 
 ### Traits
 
-None defined at this time.
+* [`Display`](https://doc.rust-lang.org/std/fmt/trait.Display.html) for [`Argument`](https://docs.rs/clasp-rs/latest/clasp_rs/struct.Argument.html) and [`ArgumentKind`](https://docs.rs/clasp-rs/latest/clasp_rs/enum.ArgumentKind.html);
 
 
 ## Examples
 
 Examples can be found in `examples/`:
 
+* `examples/minimal-usage/main.rs` — parses the process arguments and prints flags, options, values, and unused arguments;
 * `examples/versions/main.rs` — prints the crate name and version;
 
 
+## Conformance
+
+The crate carries its own corpus and does not read a sibling checkout at test time.
+
+* **test/conformance/shared/** is a byte-for-byte snapshot of the shared corpus (`cases/*.json`, **schema.md**, **schema.json**) plus **MANIFEST**. The current snapshot is revision `ba102d36eb29398a643002d57702e3d3729dcbc4`. Do not edit those files by hand;
+* **test/conformance/local/** holds cases whose ids start with `rust.`. Each has `"verified": false`. They are Rust-authored, derived from named C lines, and candidates to contribute back to the shared corpus;
+* **scripts/sync_conformance.sh** refreshes **shared/** from a committed revision of **CLASP-conformance** (`git archive`, default `HEAD`). It refuses a revision that does not resolve, rewrites **MANIFEST**, prints the revision, and warns when that working tree is dirty. It does not copy uncommitted files;
+
+The runner skips a case when **CLASP.Rust** does not implement every listed capability, and it skips `expected.status` of `undefined` with the reason `undefined in C contract`. Implemented capabilities are `bit-flags`, `dont-recognise-doublehyphen`, and `single-hyphen-as-value`. `preserve-original-order` and the two wildcard capabilities are not claimed. The core (no capability tag) is always run.
+
+`CLASP_CONFORMANCE_DIR` may point at a live corpus root for a developer check. The runner says so, and it still prints the in-tree snapshot revision. The test directories are listed in **Cargo.toml** `exclude`, so they are not part of the published package.
+
+```bash
+cargo test --test conformance -- --nocapture
+cargo test --test unit -- --nocapture
+```
+
+
 ## Project Information
 
 ### Where to get help
@@ -129,7 +194,7 @@ The declared Minimum Supported Rust Version (MSRV) for **CLASP.Rust** is **1.74*
 
 This MSRV guarantee applies to the library crate itself, its runtime dependencies (`[dependencies]`), and its build dependencies (`[build-dependencies]`). Downstream consumers compiling this crate as a dependency are guaranteed that it builds cleanly on the declared MSRV toolchain.
 
-Development dependencies (`[dev-dependencies]`, such as benchmarking frameworks like **criterion**) may require newer Rust toolchains for local development or performance testing. These dev-dependencies are never fetched or compiled by downstream consumers and do not affect the library's MSRV guarantee.
+Development dependencies (`[dev-dependencies]`) may require newer Rust toolchains for local development or performance testing. **serde_json**, used only by the conformance runner, is in that class. These dev-dependencies are never fetched or compiled by downstream consumers and do not affect the library's MSRV guarantee.
 
 
 ### Dependencies
@@ -148,6 +213,7 @@ None currently.
 
 #### Development Dependencies
 
+* [**serde_json**](https://github.com/serde-rs/json) — loads conformance case files. `default-features = false`, feature `std` only. It is not a library dependency;
 * [**test_help-rs**](https://github.com/synesissoftware/test_help-rs) — test helpers for unit tests;