Docs: add note on how to 'negate' rule

[dvdsk]

Context

I am writing a basic latex parser. For this I need to parse patterns such as: \textit{some text \texbft{some other text}}. I decided to recognize text by matching any character that is not syntax. With syntax I mean: \textit{ \textbf{and}`.

"Problem"

I was stuck on how to collect characters that are not syntax. Eventually I realized that putting a negative non consuming look-ahead in front of a match anything would get me any char that did not follow the rule.

I now use:

rule char() 
= !(syntax() / eof()) c:[_] { c }

This might be obvious to most users of rust-peg, I have limited exposure writing parsers.

Solution

I think a short example on how to match characters that do not follow some rule could be added to the docs under Pattern expressions. It would fit nicely after the idiom on matching <eof>

Alternatively a dedicated test/example could work. I prefer the first as I think this is an idiom. I am not a domain expert however. I can imagine you want to keep the docs as short as possible. In that case a clearly named test could be a good alternative.

Next steps

Let me know what you think, I am more then happy to open a draft PR for one or both of these options. I will probably need some help to get the terminology correct.

[kevinmehall]

Yeah, I'd accept a PR adding a note there, though I might move it -- I'm thinking of adding a "cookbook"-style set of examples to the documentation, including idioms like this that don't necessarily belong in the reference documentation for a single expression type (does it go under !? under []?)

Also if your syntax() is a single character, note that there is the [^ '\\' | '}'] syntax to match any single character that is not \ or }

[dvdsk]

I think thats a great idea!

mdbook (used by the rust cookbook) has a page regarding continues integration with github pages: https://rust-lang.github.io/mdBook/continuous-integration.html.

Rust-peg could add a cookbook folder (thats excluded from the cargo package) containing markdown in cookbook/src. A github action could compile that to html/css using mdbook and place that in cookbook/html.

You can configure the repository to host a static html site: https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-from-a-branch pointing the root to cookbook/html.

Updates to the cookbook should then be as easy as accepting a PR.