A Book for Nom #1525

tfpk · 2022-05-02T14:13:34Z

Hi,

I'm a newbie to Nom (and I'm probably only an intermediate Rust programmer), and I have personally found that this project lacks documentation for newcomers. I thought that it would be valuable to have a "book" for Nom, in the vein of the Rust Book or the many other excellent books that projects around the Rust ecosystem have.

Based on my limited experience, I've written about a quarter of a short book. This is a book I think would have helped me, had I had access to it a few weeks ago.

I'm posting it here for a few reasons:

Whether it's useful enough to continue working on, and whether the Nom project would be interested in accepting it.
If I've put in any significant (or even minor) mistakes that could be corrected.
If the order and plan for content is reasonable.

I'm happy to move this to an issue if that's the right place to discuss, though I suppose a useful issue to reference is #1506 .

I'd welcome any and all feedback!

Thanks :)

Xiretza

This is great, thanks a lot! I found a few nits, but overall this seems like a great start for a tutorial-style introduction to nom! Props for the name of the book, too.

Xiretza · 2022-05-02T15:26:56Z

doc/nom-guide/src/chapter_1.md

+   ahead and start parsing the middle of the line.
+
+
+To represent this model of the world, nom uses the `IResult<(I, O)>` type.


This should be IResult<I, O>.

Xiretza · 2022-05-02T15:28:42Z

doc/nom-guide/src/chapter_2.md

+these are so common, there already exists a function called `tag()`.
+This function returns a parser for a given string.
+
+<div class="example-wrap" style="display:inline-block"><pre class="compile_fail" style="white-space:normal;font:inherit;">


Not sure what's up with this HTML, it breaks the markdown in the contents.

Xiretza · 2022-05-02T15:30:16Z

doc/nom-guide/src/chapter_2.md

+```
+
+If you'd like to, you can also check case insensitive `/tag/i`
+with the `tag_case_insensitive`.


tag_no_case

Xiretza · 2022-05-02T15:34:23Z

doc/nom-guide/src/chapter_3.md

+```rust
+# extern crate nom;
+use nom::branch::alt;
+use nom::bytes::complete::{tag};
+use nom::character::complete::{digit1};
+use nom::IResult;
+
+fn parse_numbers_or_abc(input: &str) -> IResult<&str, &str> {
+    alt((
+        tag("abc"),
+        digit1
+    ))(input)
+}
+
+
+    let input = "abc";
+    let parsed_input = parse_numbers_or_abc(input);
+    match parsed_input {
+        Ok((_, matched_str)) => assert_eq!(matched_str, "abc"),
+        Err(_) => unreachable!()
+    }
+
+
+    let input = "def";
+    let parsed_input = parse_numbers_or_abc(input);
+    match parsed_input {
+        Ok(_) => unreachable!(),
+        Err(_) => assert!(true)
+    }
+```


Example seems to be mismatched (does not contain tuple() at all)?

tfpk · 2022-05-02T21:36:35Z

Thank you for the feedback! I'll fix those nits up.

Did you have any broader feedback on the structure I'm planning in SUMMARY.md? And if I kept working on this is it something you'd be interested in integrating?

I'm new enough to the project I don't know if there are things I should be explaining!

Xiretza · 2022-05-03T17:47:04Z

The overall structure looks great for a comprehensive tutorial, which is something that nom kind of lacks right now (there is some tutorial-style documentation in docs/, but it's not as coherent as an mdbook).

if I kept working on this is it something you'd be interested in integrating?

Well, you'll have to ask @Geal about that, I'm not a maintainer, but personally I'd gladly accept it ;)

I'm new enough to the project I don't know if there are things I should be explaining!

I hang out in #geal_nom:gitter.im, and while it's hard to find a most common issue, error handling is definitely something a lot of users struggle with. There are just a lot of levels to the current IResult, and it takes a while to dig through them to understand it.

Geal

I think this is a great idea, a comprehensive suite of small examples from the ground up will really help in understanding nom!

I am not sure about requiring knowledge of regular expressions, parser combinators should be able to stand by themselves. But keeping the regex equivalent with the examples can help some readers.

I'd be happy to merge this after a few fixes. I'm not sure I'll have the time to write a lot in it, but I'll make sure to help and review

doc/nom-guide/book.toml

doc/nom-guide/src/chapter_1.md

Geal · 2022-05-21T14:26:40Z

doc/nom-guide/src/chapter_2.md

+This function returns a parser for a given string.
+
+<div class="example-wrap" style="display:inline-block"><pre class="compile_fail" style="white-space:normal;font:inherit;">
+ **Warning**: `nom` has multiple different definitions of `tag`, make sure you use this one for the


that will need a link to the future chapter about parsers of complete VS streaming inputs

Agreed; I'll add it in when that chapter is written.

Geal · 2022-05-21T14:30:32Z

doc/nom-guide/src/chapter_2.md

+
+    let err_input = "defWorld";
+    match parse_input(err_input) {
+        Ok((leftover_input, output)) => unreachable!(),


if all those examples are only looking at one branch, they should use unwrap and unwrap_err instead of a match with one branch using unreachable!(), that will make them shorter

I've chosen to go with returning a Box<dyn Error>, so that I can use Try. I've done this because (from my limited understanding) the Rust guide to writing documentation suggests avoiding unwrap in documentation examples.

Happy to change this if you think it's the wrong direction.

doc/nom-guide/src/chapter_3.md

doc/nom-guide/src/introduction.md

tfpk · 2022-07-01T12:36:39Z

@Xiretza + @Geal -- I've updated this PR with the next section of the book.

Particularly curious if there's anything major that needs changing in the order or in topics covered.

I'm also blocked on the last three chapters:

Re Streaming -- I couldn't find an easy to grok example of how they are used. Is there an up-to-date one? My thinking is that the best "simple" example would be reading in from stdin; and doing something like bracket-matching; but I don't know if that plays to nom's strengths.
Re bytes + bits -- again, I don't know the area well enough to have a good example; and I don't know what's worth covering.
Re Exercises, is this worth having? I come from a teaching background, so having exercises is the norm for me, but I'm not sure if it's the done thing in Rust projects. I could also go through and add one or two per chapter?

One other thought -- some of the other documentation in docs/ would fit well in the book (I haven't written an errors chapter, because the errors document that exists is great!) Is it worth moving some/all of the documentation into the book? I've borrowed particularly heavily from the list of parsers/combinators -- I'm not sure if duplicating them was the best idea, so maybe references to them either by link; or as an appendix might be helpful?

Keen to hear your thoughts/feedback!

Initial commit for feedback.

424e397

Xiretza reviewed May 2, 2022

View reviewed changes

Geal requested changes May 21, 2022

View reviewed changes

tfpk added 2 commits July 1, 2022 21:07

Add chapters 4 thru 7

fd4a9d3

Update Xiretza's tuple issue

94252a4

epage mentioned this pull request Jan 30, 2023

Pull in a full tutorial winnow-rs/winnow#101

Closed

2 tasks

epage mentioned this pull request Feb 20, 2023

docs(tutorial): Integrate a full tutorial winnow-rs/winnow#185

Merged

tfpk mentioned this pull request Apr 6, 2023

Add Nominomicon link to README #1654

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

A Book for Nom #1525

A Book for Nom #1525

tfpk commented May 2, 2022

Xiretza left a comment •

edited

Xiretza May 2, 2022

Xiretza May 2, 2022

Xiretza May 2, 2022

Xiretza May 2, 2022

tfpk commented May 2, 2022

Xiretza commented May 3, 2022 •

edited

Geal left a comment

Geal May 21, 2022

tfpk Jul 1, 2022

Geal May 21, 2022

tfpk Jul 1, 2022

tfpk commented Jul 1, 2022

		ahead and start parsing the middle of the line.


		To represent this model of the world, nom uses the `IResult<(I, O)>` type.

A Book for Nom #1525

Are you sure you want to change the base?

A Book for Nom #1525

Conversation

tfpk commented May 2, 2022

Xiretza left a comment • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tfpk commented May 2, 2022

Xiretza commented May 3, 2022 • edited

Geal left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tfpk commented Jul 1, 2022

Xiretza left a comment •

edited

Xiretza commented May 3, 2022 •

edited