Parsley 4.4.0

[j-mie6]

Parsley 4.4.0 Staging PR

This is the PR encompassing all changes for version 4.4.0. As this is substantial new functionality, it will be previewed incrementally starting with 4.4.0-M1. When the API is completed and seems reasonable, 4.4.0-RC1 will be released to allow for testing of the release, full documentation, and ironing out of bugs. When the release is stable enough, it will be merged into master and 4.4.0 will be officially released.

High-Level Changes

This release aims to add in all the minor functionality ahead of the Parsley 5 milestone start and the final deprecation run in September.

Low-Level Changes

Minor Changes

• Add satisfyAs/satisfyMap/mapSatisfy combinator (closes Satisfy that maps #186)
• Add support for explicit register tracking in debug (closes Debug registers #182)
• Add profile combinator for light-weight analysis of what parsers take up the most time.
• Expose partialAmend and partialAmendThenDislodge (closes Partial amendment #152)
• Expose range combinators (closes Combinator for reading between two amounts #183)
• Expose more unicode compliant combinators (closes Unicode Handling character Combinators #130)
• Generalise stringOfMany and stringOfSome to take character predicates (closes Megaparsec style takeWhileP #185)
• Add the preventative combinators as per thesis
• Add a filterWith, verifiedErrorWith and preventWith builder combinators? (requires generalised machinery to be exposed as ErrGen)
• New empty combinator, but need to find a way to integrate it without clashing with the default in Parsley
• Expose multi-labels (closes Multiple labels with .label? #193)
• Introduce atomic alias for attempt (no deprecation until 4.5)
• Add configuration to TillNextWhitespace and helpers for specifying what whitespace is.
• Add the span combinator

Patch Changes

• Added unsafe() in various places that now need it

Internal Changes

• Generalise the filtering internals to accommodate filter-like, verified-like, and prevent-like uniformly
• Merge the Hint, Check, and Hander stacks together, with some simplifications.
• Introduced full result analysis, allowing for redundant parsed values to not be computed
• Char and String do not push results to the stack, the combinators are implemented with an as. AST nodes return Nothing to reflect this, and assumptions have been added.

Release Checklist

4.4.0-M1

• Expose partialAmend and partialAmendThenDislodge
• Expose label overloading that allows for multi-label support (no empty labels, since this is banned in Parsley 5)
• Expose dislodge(n) combinator (and corresponding amendAndDislodge etc)

4.4.0-M2

• Expose new unicode combinators under unicode
  • tests required?
• Expose new stringOfMany/stringOfSome overloads for predicates
• Expose new satisfyMap combinator

4.4.0-M3

• Expose the atomic combinator
• Expose the count, count1 combinators
• Expose the range, range_ and range count combinators
• TillNextWhitespace configuration
• empty(n) combinator exposed
• guard combinator exposed

4.4.0-M4

• Generalise infrastructure for verified errors and filters.
• Allow for better jump-table factoring on tokens.

4.4.0-M5

• remove hint and check stacks, merging them into the handler
• perform handler replacement instead of pop/push

4.4.0-M6

• Added preventativeFail and preventativeExplain combinators.
  • testing
• Added span combinator

4.4.0-M7

• Better overloading of label with only one required label and varargs replaces the one introduced in M1, and the original label without varargs is hidden from source API
• Exposed the ErrorGen functionality to allow for custom description of various combinators (may have to review things for 5.0.0)
  • testing
• profile combinator added to debug.DebugMethods

4.4.0-M8

• added x: A parameter to adjustWidth method of ErrorGen, allowing for a tiny bit finer control.
• added withWidth combinator

4.4.0-RC1

• alias for unsafe() called impure.
• all new functionality has partial documentation

4.4.0

• all methods have completed documentation
• wiki updated to reflect changes
  • need to be clear on the role of unsafe(), since it is now necessary if doing dodgy things with mutation
• new functionality is well tested
• README.md updated to reflect new version
• build.sbt updated to disable snapshots on this branch
• documentation checked to ensure no leakage of private [parsley] members or parsley.internal.
• turn back on the githubWorkflowConcurrency

Milestone Migration Guide

As each milestone release may choose to make binary incompatible changes, any necessary migration required to get from one milestone to the next will be tracked here.

From	To	Necessary Changes
4.3.0	4.4.0-M1	No changes required
4.4.0-M1	4.4.0-M2	No changes required
4.4.0-M2	4.4.0-M3	No changes required
4.4.0-M3	4.4.0-M4	No changes required
4.4.0-M4	4.4.0-M5	No changes required
4.4.0-M5	4.4.0-M6	May need to use unsafe() combinator when doing any mutable parsing
4.4.0-M6	4.4.0-M7	May require code re-compile, as label introduced in M1 is removed
4.4.0-M7	4.4.0-M8	Added an x: A parameter to the ErrorGen[A] adjustWidth method
4.4.0-M8	4.4.0-RC1	Moved UnexpectedItem into VanillaGen, each having Item at the end now.

[codeclimate]

The PR diff size of 5431 lines exceeds the maximum allowed for the inline comments feature.

[codeclimate]

Code Climate has analyzed commit b4e252e and detected 16 issues on this pull request.

Here's the issue category breakdown:

Category	Count
Complexity	3
Duplication	12
Style	1

The test coverage on the diff in this pull request is 94.8% (50% is the threshold).

This pull request will bring the total coverage in the repository to 92.4% (0.5% change).

View more on Code Climate.

[codeclimate]

The PR diff size of 5428 lines exceeds the maximum allowed for the inline comments feature.