Version bump to 4.2

[j-mie6]

Parsley 4.2.0 Staging PR

This is the PR encompassing all changes for version 4.2.0. As this is substantial new functionality, it will be previewed incrementally starting with 4.2.0-M1. When the API is completed and seems reasonable, 4.2.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.2.0 will be officially released.

High-Level Changes

This release aims to do small improvements to two areas of the API: positions and error combinators. New position functionality will be added to a parsley.position module, and old functionality will be moved there with deprecation in place for 5.0.0 removal. Some functionality within parsley.errors.combinator.ErrorMethods will be deprecated, as it has not been particularly useful in its current form. New functionality will be introduced into a separate class to replace this, with semantics that aid in the creation of Verified Errors. New filtering combinators will also be added, along with some missing functionality to do with amend and entrench.

Low-Level Changes

Deprecations

• Parsley.line, Parsley.col, Parsley.pos deprecated in favour of position.line, position.col, position.pos (to be removed in 5.0.0)
• Inheritance of the Lexer class is deprecated, class will be final in 5.0.0
• ErrorMethods.! and ErrorMethods.unexpected deprecated without one-to-one replacement.
• Deprecated the use of the fullAmend flag/constructor for the FilterConfig subclasses: this was erroneously added, as filtering combinators always use full-amend semantics anyway. These will be removed in 5.0.0

Minor Changes

• Added position object with line, col, pos, and new offset.
• Added parsley.errors.patterns.VerifiedErrors extension class, exposing verifiedFail and verifiedUnexpected combinators.
• Added parsley.errors.combinator.ErrorMethods.unexpectedWithReasonWhen combinator.

Patch Changes

None.

Release Checklist

4.2.0-Mn

• Expose position object with existing pos, line, col (4.2.0-M1)
• Deprecate pos, line, and col from Parsley: new home position (removal in 5.0.0, no maintenance burden for keeping them public, just simplify the docs) (4.2.0-M1
• Deprecate ErrorMethods.unexpected (no direct equivalent moving forward, can retain public API till 5.0.0) (4.2.0-M1)
• Deprecate ErrorMethods.! (no direct equivalent moving forward, can retain public API till 5.0.0) (4.2.0-M1)
• Deprecate inheritance of Lexer (for enforcement in 5.0.0) (4.2.0-M1)
• Expose dislodge
• Expose amendThenDislodge
• Create new errors.patterns.VerifiedErrors extension class (4.2.0-M2)
  • Add verifiedFail(A => Seq[String]) and fail(String, String*) (4.2.0-M2)
  • Add verifiedUnexpected, verifiedUnexpected(String), and verifiedUnexpected(A => String) (4.2.0-M2)
• Add offset: Parsley[Int] to position: in 5.0.0 the underlying offset may be changed to Long, but this is fine for now (4.2.0-M1)
• Add unexpectedWithReasonWhen combinator (4.2.0-M3)
• Document the 1-offset position semantics of Parsley (4.2.0-M3)

4.2.0-RC1

• all new functionality has partial documentation

4.2.0

• all methods have completed documentation
• 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.
• ensure EoL policy in README reflects the EoL support of the defunc 4.1 series

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	Suggested Changes
4.1.x	4.2.0-M1	None required	Move from Parsley to position for any position related combinators. Stop using ! and .unexpected combinators with immediate effect.
4.2.0-M1	4.2.0-M2	legacyUnexpected was removed as no longer needed, unexpected will not be source removed in 4.3	Remove the fullAmend flag on FilterConfig implementations: it doesn't do anything.
4.2.0-M2	4.2.0-M3	None required	None required.

[codeclimate]

Code Climate has analyzed commit 5a0de3b and detected 0 issues on this pull request.

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

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

View more on Code Climate.