Deprecations for 5.x (#222)

* Several deprecations enforced, no additions

* added the new syntax naming for implicits

* Standarded while, when, guard, and if

* genericbridges -> generic

* Added state and deprecated registers

* Flattened lexer a bit

* PlatformSpecific to reduce io imports

* remove skip variants

* manyTill and someTill

* countMany and countSome

* Moved many and some

* verifiedUnexpected -> verifiedExplain

.codeclimate.yml

@@ -16,8 +16,12 @@ exclude_patterns:
 - "LICENSE"
 - "**/ap.scala"
 - "**/lift.scala"
+- "**/generic.scala"
 - "**/genericbridges.scala"
 - "**/implicits/zipped.scala"
+- "**/implicits/lift.scala"
+- "**/syntax/zipped.scala"
+- "**/syntax/lift.scala"
 plugins:
   scalastyle:
     enabled: true

README.md

@@ -9,15 +9,15 @@ Parsley is distributed on Maven Central, and can be added to your project via:
 
 ```scala
 // SBT
-libraryDependencies += "com.github.j-mie6" %% "parsley" % "4.4.0"
+libraryDependencies += "com.github.j-mie6" %% "parsley" % "4.5.0"
 
 // scala-cli
---dependency com.github.j-mie6::parsley:4.4.0
+--dependency com.github.j-mie6::parsley:4.5.0
 // or in file
-//> using dep com.github.j-mie6::parsley:4.4.0
+//> using dep com.github.j-mie6::parsley:4.5.0
 
 // mill
-ivy"com.github.j-mie6::parsley:4.4.0"
+ivy"com.github.j-mie6::parsley:4.5.0"
 ```
 
 Documentation can be found [**here**](https://javadoc.io/doc/com.github.j-mie6/parsley_2.13/latest/index.html)
@@ -33,7 +33,7 @@ libraryDependencies += "com.github.j-mie6" %% "parsley-cats" % "1.2.0"
 
 ```scala
 scala> import parsley.Parsley
-scala> import parsley.implicits.character.{charLift, stringLift}
+scala> import parsley.syntax.character.{charLift, stringLift}
 
 scala> val hello: Parsley[Unit] = ('h' ~> ("ello" | "i") ~> " world!").void
 scala> hello.parse("hello world!")
@@ -167,7 +167,8 @@ _An exception to this policy is made for any version `3.x.y`, which reaches EoL
 | `4.1.0` | 18th January 2023  | EoL reached (`4.1.8`)           |
 | `4.2.0` | 22nd January 2023  | EoL reached (`4.2.14`)          |
 | `4.3.0` | 8th July 2023      | EoL reached (`4.3.1`)           |
-| `4.4.0` | 6th October 2023   | Enjoying indefinite support     |
+| `4.4.0` | 6th October 2023   | Supported until 6th April 2024  |
+| `4.5.0` | 6th January 2023   | Enjoying indefinite support     |
 
 ## Bug Reports [![Percentage of issues still open](https://isitmaintained.com/badge/open/j-mie6/Parsley.svg)](https://isitmaintained.com/project/j-mie6/Parsley "Percentage of issues still open") [![Maintainability](https://img.shields.io/codeclimate/maintainability/j-mie6/parsley)](https://codeclimate.com/github/j-mie6/parsley) [![Test Coverage](https://img.shields.io/codeclimate/coverage-letter/j-mie6/parsley)](https://codeclimate.com/github/j-mie6/parsley)
 

docs/api-guide/Parsley.md

@@ -81,7 +81,7 @@ The `flatMap` combinator is another way of sequencing two parsers, but where
 the second depends on the result of the first. In `parsley`, this operation
 is **very** expensive, and it (and its derived `flatten` combinator) should
 be avoided. One way of avoiding the `flatMap` combinator is to use features
-found in [`parsley.registers`][Context-Sensitive Parsing (`parsley.registers`)],
+found in [`parsley.state`][Context-Sensitive Parsing (`parsley.state`)],
 or to use `lift` combinators instead.
 
 #### Choice
@@ -171,3 +171,26 @@ In addition to these, it also has `empty` and `empty(Int)`, which fail the parse
 immediately (but recoverably) and produces a given width of caret (and `0` in the case of `empty`); `lookAhead` and `notFollowedBy` for dealing with positive
 and negative lookahead; and `fresh`, which can be used like `pure` but evaluates
 its argument every time, which is useful in the presence of mutable values.
+
+### Iterative Combinators
+One of the main classes of combinator are the iterative combinators, which
+execute parsers multiple times until they cannot match any more; the results
+of these combinators vary. If the parser being repeated fails having consumed
+input, iterative combinators will fail; if no input was consumed on failure,
+the iteration will stop.
+
+The most commonly used of these are the `many` and `some` combinators, which
+return a list of the successful results:
+
+```scala mdoc:to-string
+import parsley.character.digit
+import parsley.Parsley.{many, some}
+
+many(digit.zip(digit)).parse("")
+many(digit.zip(digit)).parse("1234")
+many(digit.zip(digit)).parse("12345")
+
+some(digit.zip(digit)).parse("")
+some(digit.zip(digit)).parse("1234")
+some(digit.zip(digit)).parse("12345")
+```

docs/api-guide/README.md

@@ -23,7 +23,7 @@ There are a few modules of note:
 * [`parsley.character`](@:api(parsley.character$)):
   contains a variety of combinators which deal with characters, key ones include `char`,
   `satisfy` and `string`.
-* [`parsley.implicits`](@:api(parsley.implicits$)):
+* [`parsley.syntax`](@:api(parsley.syntax$)):
   contains the very useful implicit conversion combinators. In particular, importing `charLift`
   and `stringLift` allows you write character and string literals as if they were parsers
   themselves. There are also implicit classes here which extend functions of any arity with a

docs/api-guide/combinator.md

@@ -20,36 +20,22 @@ of these combinators vary. If the parser being repeated fails having consumed
 input, iterative combinators will fail; if no input was consumed on failure,
 the iteration will stop.
 
-The most commonly used of these are the `many` and `some` combinators, which
-return a list of the successful results:
-
-```scala mdoc:to-string
-import parsley.character.digit
-import parsley.combinator.{many, some}
-
-many(digit.zip(digit)).parse("")
-many(digit.zip(digit)).parse("1234")
-many(digit.zip(digit)).parse("12345")
-
-some(digit.zip(digit)).parse("")
-some(digit.zip(digit)).parse("1234")
-some(digit.zip(digit)).parse("12345")
-```
-
-While `some` will parse one or more times, `manyN` generalises to work for
+The most commonly used of these are the `many` and `some` combinators (see [Object `Parsley`]), which
+return a list of the successful results. While `some` will parse one or more times, `manyN`
+generalises to work for
 any minimum required parses `n`. When the results are not needed, `skipMany`,
 `skipSome`, and `skipManyN` can be used instead. To determine how many times
 the parse was successful, the `count` and `count1` can be used instead.
 
-The `manyUntil` and `someUntil` combinators can be used to parse iteratively
+The `manyTill` and `someTill` combinators can be used to parse iteratively
 until some other parse is successful: this can be used, for instance, to
 scan comments:
 
 ```scala mdoc:to-string
 import parsley.character.{string, item, endOfLine}
-import parsley.combinator.{manyUntil}
+import parsley.combinator.{manyTill}
 
-val comment = string("//") ~> manyUntil(item, endOfLine)
+val comment = string("//") ~> manyTill(item, endOfLine)
 comment.parse("// this is a comment\n")
 ```
 

docs/api-guide/debug.md

@@ -51,22 +51,22 @@ default. `FullBreak` has the effect of both `EntryBreak` and `ExitBreak` combine
 pause execution on the entry to the combinator, requiring input on the console to proceed, and `ExitBreak`
 will do the same during the exit.
 
-### Watching Registers
-The `debug` combinator takes a variadic number of register/name pairs as its last argument. These
-allow you to watch the values stored in registers as well during the debugging process. For instance:
+### Watching References
+The `debug` combinator takes a variadic number of reference/name pairs as its last argument. These
+allow you to watch the values stored in references as well during the debugging process. For instance:
 
 ```scala mdoc:to-string
 import parsley.Parsley.atomic
-import parsley.registers._
+import parsley.state._
 import parsley.character.string
 import parsley.debug._
 
-val p = 0.makeReg { r1 =>
-    false.makeReg { r2 =>
+val p = 0.makeRef { r1 =>
+    false.makeRef { r2 =>
         val p = (  string("hello")
-                ~> r1.modify(_ + 5)
+                ~> r1.update(_ + 5)
                 ~> ( string("!")
-                   | r2.put(true) ~> string("?")
+                   | r2.set(true) ~> string("?")
                    ).debug("punctuation", r2 -> "r2")
                 )
         r1.rollback(atomic(p).debug("hello!", r1 -> "r1", r2 -> "r2"))
@@ -83,7 +83,7 @@ insight into how an error message came to be. For instance:
 
 ```scala mdoc:to-string
 import parsley.character.{letter, digit, char}
-import parsley.combinator.many
+import parsley.Parsley.many
 import parsley.debug._
 
 val q = (many( ( digit.debugError("digit")

docs/api-guide/errors/combinator.md

@@ -176,7 +176,7 @@ Notice that the above error makes no sense. This is why `amend` is a precision
 tool: it should ideally be used in conjunction with other combinators. For instance:
 
 ```scala mdoc:silent
-import parsley.implicits.character.charLift
+import parsley.syntax.character.charLift
 import parsley.combinator.choice
 import parsley.character.{noneOf, stringOfMany}
 

docs/api-guide/errors/patterns.md

@@ -57,14 +57,14 @@ import parsley.errors.patterns.VerifiedErrors
 import parsley.character.char
 
 // assume that a `lexer` is available
-val float = lexer.nonlexeme.numeric.floating.decimal
+val float = lexer.nonlexeme.floating.decimal
 val _noFloat =
-    float.verifiedUnexpected("floating-point values may not be used as array indices")
+    float.verifiedExplain("floating-point values may not be used as array indices")
 
 _noFloat.parse("hello")
 _noFloat.parse("3.142")
 
-val int = lexer.nonlexeme.numeric.unsigned.decimal
+val int = lexer.nonlexeme.unsigned.decimal
 val _noPlus = (char('+') ~> int).verifiedFail { n =>
     Seq(s"the number $n may not be preceeded by \"+\"")
 }

docs/api-guide/errors/tokenextractors.md

@@ -176,7 +176,7 @@ import parsley.errors.tokenextractors.LexToken
 
 val builder = new DefaultErrorBuilder with LexToken {
     def tokens = Seq(
-        lexer.nonlexeme.numeric.integer.decimal.map(n => s"integer $n"),
+        lexer.nonlexeme.integer.decimal.map(n => s"integer $n"),
         lexer.nonlexeme.names.identifier.map(v => s"identifier $v")
     ) ++ desc.symbolDesc.hardKeywords.map { k =>
         lexer.nonlexeme.symbol(k).as(s"keyword $k")

docs/api-guide/expr/infix.md

@@ -46,7 +46,7 @@ As an example:
 ```scala mdoc:to-string:nest
 import parsley.character.digit
 import parsley.expr.infix
-import parsley.implicits.character.stringLift
+import parsley.syntax.character.stringLift
 
 sealed trait Expr
 case class Add(x: Expr, y: Num) extends Expr

docs/api-guide/expr/precedence.md

@@ -52,7 +52,7 @@ are assumed:
 ```scala mdoc:silent
 import parsley.Parsley
 import parsley.character.{letter, digit, stringOfSome}
-import parsley.implicits.character.stringLift
+import parsley.syntax.character.stringLift
 
 val int: Parsley[Int] = digit.foldLeft1(0)((n, d) => n * 10 + d.asDigit)
 val ident: Parsley[String] = stringOfSome(letter)

docs/api-guide/generic.md

@@ -1,22 +1,22 @@
 {%
 laika.versioned = true
-laika.title = "`parsley.genericbridges`"
-parsley.tabname = "Generic Bridges (parsley.genericbridges)"
+laika.title = "`parsley.generic`"
+parsley.tabname = "Generic Bridges (parsley.generic)"
 laika.site.metadata.description = "This page describes how to use generic bridges to factor code."
 %}
 
 ```scala mdoc:invisible
 import parsley.Parsley, Parsley._
-import parsley.genericbridges.ParserBridge1
+import parsley.generic.ParserBridge1
 ```
-# Generic Bridges (`parsley.genericbridges`)
+# Generic Bridges (`parsley.generic`)
 
 The *Parser Bridge* pattern is a technique for decoupling semantic actions from the parser itself.
-The `parsley.genericbridges` module contains 23 classes that allow
+The `parsley.generic` module contains 23 classes that allow
 you to get started using the technique straight away if you wish.
 
 @:callout(info)
-*The Scaladoc for this page can be found at [`parsley.genericbridges`](@:api(parsley.genericbridges$)).*
+*The Scaladoc for this page can be found at [`parsley.generic`](@:api(parsley.generic$)).*
 @:@
 
 ## What are *Parser Bridges*?
@@ -29,7 +29,7 @@ val py: Parsley[Int] = pure(6)
 ```
 
 ```scala mdoc
-import parsley.implicits.zipped.Zipped2
+import parsley.syntax.zipped.Zipped2
 case class Foo(x: Int, y: Int)
 // with px, py of type Parsley[Int]
 val p = (px, py).zipped(Foo(_, _))
@@ -72,7 +72,7 @@ templates (see [the associated tutorial](../tutorial/parser-bridge-pattern.md) f
 `parsley` provides some basic ones to get you started.
 
 ## How to use
-The [`parsley.genericbridges`](@:api(parsley.genericbridges$)) module contains `ParserBridge1` through
+The [`parsley.generic`](@:api(parsley.generic$)) module contains `ParserBridge1` through
 `ParserBridge22` as well as `ParserBridge0`; they all extend `ParserBridgeSingleton`, which provides
 some additional combinators.
 
@@ -82,7 +82,7 @@ For example, the `Foo` class above can have its companion object turned into a b
 `ParserBridge2` (which is for two argument bridges):
 
 ```scala mdoc
-import parsley.genericbridges.ParserBridge2
+import parsley.generic.ParserBridge2
 object Foo extends ParserBridge2[Int, Int, Foo]
 ```
 
@@ -129,7 +129,7 @@ like in [chain](expr/chain.md) or [precedence](expr/precedence.md) combinators:
 
 ```scala mdoc:silent
 import parsley.expr.chain
-import parsley.implicits.character.stringLift
+import parsley.syntax.character.stringLift
 
 val term = chain.left1(px, Add.from("+")) // or `Add <# "+"`
 ```
@@ -141,7 +141,7 @@ This trait is a special case for objects that should return themselves.
 As an example, here is an object which forms part of a larger AST, say:
 
 ```scala mdoc
-import parsley.genericbridges.ParserBridge0
+import parsley.generic.ParserBridge0
 trait Expr
 // rest of AST
 case object NullLit extends Expr with ParserBridge0[Expr]