From 3313242bdf885be712be72642c9e328a783ccc83 Mon Sep 17 00:00:00 2001 From: Mike Foster Date: Tue, 2 Jun 2026 09:19:11 +0000 Subject: [PATCH] add README to each crate --- crates/try_v2/README.md | 114 +++++++++++++++++++++++++++++++++ crates/try_v2_derive/README.md | 114 +++++++++++++++++++++++++++++++++ 2 files changed, 228 insertions(+) create mode 100644 crates/try_v2/README.md create mode 100644 crates/try_v2_derive/README.md diff --git a/crates/try_v2/README.md b/crates/try_v2/README.md new file mode 100644 index 0000000..8c78cd3 --- /dev/null +++ b/crates/try_v2/README.md @@ -0,0 +1,114 @@ +# Try_v2 + + Provides: + +- a derive macro for `Try` +- traits with standard methods to make TryTypes usable (e.g. `trait Transform` provides `.map()`) +- derive `Try_ConvertResult` for interconversion with `std::result::Result` +- derive `Try_Iterator` for iterating over `IntoIterator` and collecting from `FromIterator` analogous to how `Result` & `Option` do this. + +See ([try_trait_v2](https://rust-lang.github.io/rfcs/3058-try-trait-v2.html)) for more details of the underlying trait. + +## Requires + +- nightly +- `#![feature(never_type)]` +- `#![feature(try_trait_v2)]` +- `#![feature(try_trait_v2_residual)]` +- optionally: `#![feature(iterator_try_collect)]` (if using Try_Iterator) + +## Limitations on the annotated type + +- must be an `enum` +- must have _at least one_ generic type +- the _first_ generic type must be the `Output` type (produced when not short-circuiting) +- the output variant (does not short-circuit) must be the _first_ variant and store the output type as the _only unnamed_ field +- no other variant can store the Output type (TODO #72 add a nice error message) + +See the [full documentation](https://docs.rs/try_v2/latest/try_v2/) for specifics on the generated code. + +## Example Usage + +```rust +#![feature(never_type)] +#![feature(try_trait_v2)] +#![feature(try_trait_v2_residual)] +use try_v2::{Try, Try_ConvertResult}; + +#[derive(Try, Try_ConvertResult)] +enum TestResult { + Ok(T), + TestsFailed, + OtherError(String) +} + +// Basic short-circuiting thanks to `#[derive(Try)]` +fn run_tests() -> TestResult<()> { + TestResult::OtherError("oops!".to_string())?; // <- Function short-circuits here ... + TestResult::TestsFailed?; + TestResult::Ok(()) +} + +assert!(matches!(run_tests(), TestResult::OtherError(msg) if msg == "oops!")); + + +// Conversion from std::result::Result thanks to `#[derive(Try_ConvertResult)]` +struct TestFailure {} + +impl From for TestResult { + fn from(err: TestFailure) -> Self { + TestResult::TestsFailed + } +} + +fn run_more_tests() -> TestResult<()> { + std::result::Result::Err(TestFailure{})?; // <- Function short-circuits here & converts to a TestResult... + TestResult::Ok(()) +} + +assert!(matches!(run_more_tests(), TestResult::TestsFailed)); +``` + +## Stability & MSRV + +Given that this crate exposes an experimental API from std it makes use of experimental +features which require a nightly toolchain. + +In order to use this crate you must enable the features which it exposes: + +> 🔬 **Required Experimental Features** +> +> - [`#![feature(never_type)]`](https://github.com/rust-lang/rust/issues/35121) +> - [`#![feature(try_trait_v2)]`](https://github.com/rust-lang/rust/issues/84277) +> - [`#![feature(try_trait_v2_residual)]`](https://github.com/rust-lang/rust/issues/91285) +> - optionally: [`#![feature(iterator_try_collect)]`](https://github.com/rust-lang/rust/issues/94047) (if using `Try_Iterator`) + +This crate makes use of the following experimental features in addition to those which it directly supports: + +> 🔬 **Additional Experimental Features** +> +> - [`#![feature(if_let_guard)]`](https://github.com/rust-lang/rust/issues/51114) (stable since 1.95.0) +> - [`#![feature(let_chains)]`](https://github.com/rust-lang/rust/issues/53667) (stable since 1.88.0 on 2024 only) +> +> This list includes any unstable features used by direct & transitive dependencies (currently, none). +> +> You do not need to enable these in your own code, the list is for information only. + +### Stability guarantees + + We run automated tests **every month** to ensure no fundamental changes affect this crate and + test every PR against the current nightly, as well as the current equivalent beta & stable. + If you find an issue before we do, please + [raise an issue on github](https://github.com/MusicalNinjaDad/try_v2/issues). + +### MSRV + + For those of you working with a pinned nightly (etc.) this crate supports every version of + edition 2024 (rust 1.85.1 onwards, released as stable on 2025-03-18). We use + [autocfg](https://crates.io/crates/autocfg/) to seamlessly handle features which have been + stabilised since then. + +## Currently untested (may work, may not ...) + +- `where` clauses +- storing `Fn`s in variants diff --git a/crates/try_v2_derive/README.md b/crates/try_v2_derive/README.md new file mode 100644 index 0000000..8c78cd3 --- /dev/null +++ b/crates/try_v2_derive/README.md @@ -0,0 +1,114 @@ +# Try_v2 + + Provides: + +- a derive macro for `Try` +- traits with standard methods to make TryTypes usable (e.g. `trait Transform` provides `.map()`) +- derive `Try_ConvertResult` for interconversion with `std::result::Result` +- derive `Try_Iterator` for iterating over `IntoIterator` and collecting from `FromIterator` analogous to how `Result` & `Option` do this. + +See ([try_trait_v2](https://rust-lang.github.io/rfcs/3058-try-trait-v2.html)) for more details of the underlying trait. + +## Requires + +- nightly +- `#![feature(never_type)]` +- `#![feature(try_trait_v2)]` +- `#![feature(try_trait_v2_residual)]` +- optionally: `#![feature(iterator_try_collect)]` (if using Try_Iterator) + +## Limitations on the annotated type + +- must be an `enum` +- must have _at least one_ generic type +- the _first_ generic type must be the `Output` type (produced when not short-circuiting) +- the output variant (does not short-circuit) must be the _first_ variant and store the output type as the _only unnamed_ field +- no other variant can store the Output type (TODO #72 add a nice error message) + +See the [full documentation](https://docs.rs/try_v2/latest/try_v2/) for specifics on the generated code. + +## Example Usage + +```rust +#![feature(never_type)] +#![feature(try_trait_v2)] +#![feature(try_trait_v2_residual)] +use try_v2::{Try, Try_ConvertResult}; + +#[derive(Try, Try_ConvertResult)] +enum TestResult { + Ok(T), + TestsFailed, + OtherError(String) +} + +// Basic short-circuiting thanks to `#[derive(Try)]` +fn run_tests() -> TestResult<()> { + TestResult::OtherError("oops!".to_string())?; // <- Function short-circuits here ... + TestResult::TestsFailed?; + TestResult::Ok(()) +} + +assert!(matches!(run_tests(), TestResult::OtherError(msg) if msg == "oops!")); + + +// Conversion from std::result::Result thanks to `#[derive(Try_ConvertResult)]` +struct TestFailure {} + +impl From for TestResult { + fn from(err: TestFailure) -> Self { + TestResult::TestsFailed + } +} + +fn run_more_tests() -> TestResult<()> { + std::result::Result::Err(TestFailure{})?; // <- Function short-circuits here & converts to a TestResult... + TestResult::Ok(()) +} + +assert!(matches!(run_more_tests(), TestResult::TestsFailed)); +``` + +## Stability & MSRV + +Given that this crate exposes an experimental API from std it makes use of experimental +features which require a nightly toolchain. + +In order to use this crate you must enable the features which it exposes: + +> 🔬 **Required Experimental Features** +> +> - [`#![feature(never_type)]`](https://github.com/rust-lang/rust/issues/35121) +> - [`#![feature(try_trait_v2)]`](https://github.com/rust-lang/rust/issues/84277) +> - [`#![feature(try_trait_v2_residual)]`](https://github.com/rust-lang/rust/issues/91285) +> - optionally: [`#![feature(iterator_try_collect)]`](https://github.com/rust-lang/rust/issues/94047) (if using `Try_Iterator`) + +This crate makes use of the following experimental features in addition to those which it directly supports: + +> 🔬 **Additional Experimental Features** +> +> - [`#![feature(if_let_guard)]`](https://github.com/rust-lang/rust/issues/51114) (stable since 1.95.0) +> - [`#![feature(let_chains)]`](https://github.com/rust-lang/rust/issues/53667) (stable since 1.88.0 on 2024 only) +> +> This list includes any unstable features used by direct & transitive dependencies (currently, none). +> +> You do not need to enable these in your own code, the list is for information only. + +### Stability guarantees + + We run automated tests **every month** to ensure no fundamental changes affect this crate and + test every PR against the current nightly, as well as the current equivalent beta & stable. + If you find an issue before we do, please + [raise an issue on github](https://github.com/MusicalNinjaDad/try_v2/issues). + +### MSRV + + For those of you working with a pinned nightly (etc.) this crate supports every version of + edition 2024 (rust 1.85.1 onwards, released as stable on 2025-03-18). We use + [autocfg](https://crates.io/crates/autocfg/) to seamlessly handle features which have been + stabilised since then. + +## Currently untested (may work, may not ...) + +- `where` clauses +- storing `Fn`s in variants