Add tutorial to readme by DenisNovac · Pull Request #299 · typelevel/cats-parse

DenisNovac · 2021-11-08T07:42:51Z

Fixed version of #298

zsluedem · 2021-11-08T08:42:24Z

Just want to say . This pr is great.

johnynek

This is really great and I want to merge it!

I did have a few suggestions, mostly around calling out the two kinds of conceptual errors: halting and epsilon, and making the distinction early to help understand orElse, backtrack and soft.

johnynek · 2021-11-09T02:15:48Z

+import cats.parse.Parser
+
+
+val p: Parser[String] = (sp.?.with1 *> alpha.rep <* sp.?).rep.map { words => 


should we mention the convenience method .between or .surroundedBy

(sp.?.with1 *> alpha.rep <* sp.?) == alpha.rep.surroundedBy(sp.?)

johnynek · 2021-11-09T02:20:33Z

+// res3 = Right((,(None,The Wind Has Risen)))
+```
+
+So when the *right side* throws an error the `soft` method allows us to rewind parsed input and try to proceed it's parsing with next parsers (without changing the parser itself!).


when the right side throws a non-halting error (which is to say epsilon error, or the right side did not consume any input).

regadas

This looks great! 👏

Besides @johnynek comments can we make the code blocks mdoc blocks? It will make sure the examples compile and eval result will always be accurate.

DenisNovac · 2021-11-10T13:19:06Z

@johnynek i've made some changes for every suggestion you give. Please resolve conversations which are not relevant anymore.

johnynek

I agree with @regadas we should use scala mdoc so we compile these docs to make sure the examples compile.

See for instance here:

cats-parse/docs/src/index.md

Line 39 in 714a9df

```scala mdoc

I am looking forward to publishing the next version of this library, but I'd love to merge this first so new users will see this tutorial if they see the announcement of a new version.

johnynek · 2021-11-10T18:34:48Z


+Parser might be interrupted by parsing error. There are two kinds of errors:
+ - an error that has consumed 0 characters (**epsilon failure**);
+ - an error that has consumer 1 or more characters (**halting failure**).


sorry for misleading you, let's stick to arresting used in the docs.

johnynek · 2021-11-10T18:35:07Z

 ### Backtrack

-Parser job might be interrupted by parsing error. This happens when input can't be parsed with this parser:
+Backtrack allows us to convert a *halting failure* to *epsilon failure*. It also rewinds the input to the offset to that used before parsing began. The resulting parser might still be combined with others. Let's look at the example:


johnynek · 2021-11-10T18:35:31Z

 ```

-The first parsing is interrupted by error since it *started* the parsing (one first space was correct on parser `p1`) so it won't work without `backtrack`. The second parsing works fine with `orElse` alone since it does not start in `p1` or `p2`.
+The first parser combination is interrupted by *halting error* and the second parsing combination will only suffer from *epsilon errors*. The second parser works because `orElse` and `|` operators actually allows recovering from epsilon errors, but not from halting errors.


johnynek · 2021-11-10T18:35:42Z

+The first parser combination is interrupted by *halting error* and the second parsing combination will only suffer from *epsilon errors*. The second parser works because `orElse` and `|` operators actually allows recovering from epsilon errors, but not from halting errors.

-So the `backtrack` helps us where the *left side* throws an error.
+So the `backtrack` helps us where the *left side* throws halting error.


johnynek · 2021-11-10T18:36:08Z

 ### Soft

-This method might look similar to `backtrack`, but it allows us to *proceed* the parsing when the *right side* is failed. It is really useful for ambiguous parsers when we can't really tell what exactly we are parsing before the end. Let's say we want to parse some input to the search engine which contains fields. This might look like "field:search_query". Let's try to write a parser for this:
+This method might look similar to `backtrack`, but it allows us to *proceed* the parsing when the *right side* is throwing an epsilon error. It is really useful for ambiguous parsers when we can't really tell what exactly we are parsing before the end. Let's say we want to parse some input to the search engine which contains fields. This might look like "field:search_query". Let's try to write a parser for this:


maybe returning than throwing which sounds like a jvm exception being thrown, which is not how it happens.

johnynek · 2021-11-10T18:36:25Z

 ```

-But this problem might be resolved with `soft` method:
+But this problem might be resolved with `soft` method inside the first parser since the right side of it actually throws an epsilon failure itself:


returns an epsilon

DenisNovac · 2021-11-11T06:12:10Z

Fixed the terminology. I'll check mdoc later today.

…eadme_2

DenisNovac · 2021-11-11T12:24:04Z

Added the mdoc and checked it compiles

codecov-commenter · 2021-11-11T16:54:32Z

Codecov Report

Merging #299 (af73caf) into main (714a9df) will decrease coverage by 0.09%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##             main     #299      +/-   ##
==========================================
- Coverage   96.43%   96.34%   -0.10%     
==========================================
  Files           8        8              
  Lines        1011     1011              
  Branches       81       81              
==========================================
- Hits          975      974       -1     
- Misses         36       37       +1

Impacted Files	Coverage Δ
core/shared/src/main/scala/cats/parse/Parser.scala	`96.20% <0.00%> (-0.12%)`	⬇️

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 714a9df...af73caf. Read the comment docs.

DenisNovac · 2021-11-11T16:58:12Z

Fixed the warning (through web-version, didn't compile it for other warnings)

johnynek · 2021-11-11T17:27:41Z

Thank you so much!

filosganga · 2021-11-12T16:51:52Z

It is just what I was looking for, thank you!

Add tutorial to readme

23b647e

johnynek reviewed Nov 9, 2021

View reviewed changes

regadas reviewed Nov 10, 2021

View reviewed changes

fix review

f5f551a

johnynek reviewed Nov 10, 2021

View reviewed changes

review: arresting failures and return instead of throw

6473701

DenisNovac added 2 commits November 11, 2021 17:10

Merge branch 'main' of github.com:DenisNovac/cats-parse into change_r…

9676542

…eadme_2

review: added mdoc examples

af73caf

fix warning

ff50289

johnynek merged commit a0ec067 into typelevel:main Nov 11, 2021

		import cats.parse.Parser


		val p: Parser[String] = (sp.?.with1 > alpha.rep < sp.?).rep.map { words =>

Uh oh!

Uh oh!

Conversation

DenisNovac commented Nov 8, 2021

Uh oh!

zsluedem commented Nov 8, 2021

Uh oh!

johnynek left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

regadas left a comment

Choose a reason for hiding this comment

Uh oh!

DenisNovac commented Nov 10, 2021

Uh oh!

johnynek left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

DenisNovac commented Nov 11, 2021

Uh oh!

DenisNovac commented Nov 11, 2021

Uh oh!

codecov-commenter commented Nov 11, 2021

Codecov Report

Uh oh!

DenisNovac commented Nov 11, 2021

Uh oh!

johnynek commented Nov 11, 2021

Uh oh!

filosganga commented Nov 12, 2021

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants