snapbox VS regex-automata

If needed, here is an example of per-word diffing and highlighting of trailing newline differences.

I see. I would try writing the same name as in your Cargo.toml. For example, if yours was toml [package] name = "caesor_cipher" I would try bin.name = "caesor_cipher" It seems that trycmd might ignore a test if the bin.name field is incorrect: https://github.com/assert-rs/trycmd/issues/105

I find rustdoc lacking for clap. rustdoc does a good job with API reference documentation and is improving in its handling of examples but derive reference and tutorial documentation are a weak point.

For examples, its improving with the example scraping work (e.g. https://docs.rs/clap/latest/clap/struct.ArgMatches.html#meth...) but testing of example is still lacking. I've written trycmd to help (https://github.com/assert-rs/trycmd).

For derive reference and tutorial documentation, your choices are

- A very long, hard to navigate top-level documentation, see https://docs.rs/structopt/latest/structopt/

- External documentation, see https://serde.rs/

- Dummy modules to store your documentation (I've seen this used but can't remember one off the top of my head)

For clap, my documentation examples are best served as programs and we've had a problem with these being broken. The Rust CLI book has a decent strategy for this by pulling in code from external files (https://rust-cli.github.io/book/index.html). I was tempted to do that for clap where example code and output (all verified via trycmd) are pulled into an mdbook site but I've stopped short and just have a README that links out to everything (https://github.com/clap-rs/clap/blob/master/examples/tutoria...). Its not great.

Another problem we found in clap was it was easy for our examples to build but harder to make sure they worked. This is why I wrote trycmd (example "tests").

Would love feedback on on some of the known questions or whatever else is on your mind!

The design is inspired by trybuild with thought given to how mdBook books could pull in content so you can verify a code sample, the command for running it, and the output. In considering how to keep clap's website up-to-date, I had this idea and threw it together to see how well it works. Overall, seems good with room for improvement. I'll have to give this a try on a real world program soon.

I believe you're the second person to tell me they were confused by this, so there are probably several others confused but didn't say anything. I've added a warning to the top of regex-automata's README.

For anyone following along at home, we're having a very helpful discussion about the implementation I posted in my sibling comment here: https://github.com/BurntSushi/regex-automata/issues/30

My current technique only gets applied to alternations of simple literals. But the idea is generalizeable and I speculate that it is actually impactful to generalize it.

(I could use '_ => {}' instead of 'None' to save a few more.)

I do find the 'if let' variant to be a bit easier to read. It's optimizing for a particular and somewhat common case, so it does of course overlap with 'match'. But I don't find this particular overlap to be too bad. It's usually pretty clear when to use one vs the other.

But like I said, I could live without 'if let'. It is not a major quality of life enhancement to me. Neither will its impending extensions. i.e., 'if let pattern = foo && some_booolean_condition {'.

[1]: https://github.com/BurntSushi/regex-automata/blob/fbae906823...

[2]: https://github.com/BurntSushi/regex-automata/blob/fbae906823...

(The work on regex-automata 0.2 has been underway for over a year now.](https://github.com/BurntSushi/regex-automata/tree/ag/work) There's a lot done, but still a lot more to go. Once that's done, regex proper should be pretty close to a thin layer that glues regex-syntax, regex-automata, memchr and aho-corasick together. I don't currently expect regex to grow any more dependencies than that. And as it is, aho-corasick and memchr are both optional dependencies. Right now, regex-syntax is the only required dependency, but regex-automata will be added to that list.