Factory Iteration (#258)

This PR, which closes #141, introduces `Factory`-forms for all iterative
combinators. These allow them to return any arbitrary type `C` (not
limited to sequences, `String` is possible, as are `Set`s and `Map`s).
This is done by including a `Factory[A, C]` into these combinators.

Such factories can be obtained by implicit conversion from
`IterableFactory` etc, which are the base types for the companion
objects of various collections. For instance `many(p)` is equivalent to
`many(p, List)`. In Scala 2, the inference for these can be a bit shaky,
and full type ascription may be required (unfortunately). In Scala 3
this is not an issue. To improve the situation on Scala 2, additional
overloads could be added to take explicitly `IterableFactory` (this is
done for some combinators anyway, as they would otherwise always need
the ascription even in Scala 3); however, this would increase API noise
and doesn't account for other special cases like
`EvidenceIterableFactory`, which allows for the construction of `Array`
and `SortedSet`s, say.

One fix to this problem would be to bite the bullet and move the
combinators to suffix-form:

```scala
p.many, p.many(List)
p.sepBy(sep), p.sepBy(sep, List)
...
```

The question would be where to draw the line. This would have the
advantage of improving the autocompletion of combinators!

Author: j-mie6

parsley/shared/src/main/scala/parsley/Parsley.scala

@@ -396,7 +396,7 @@ final class Parsley[+A] private [parsley] (private [parsley] val internal: front
       */
     def <**>[B](pf: =>Parsley[A => B]): Parsley[B] = lift.lift2[A, A=>B, B]((x, f) => f(x), this, pf).uo("<**>")
 
-    // FIXME: move into nodes
+    // FIXME: names move into nodes
     @inline private def lseq[B](q: =>Parsley[B], name: String): Parsley[A] = new Parsley(new frontend.<*(this.internal, q.internal)).uo(name)
     @inline private def rseq[B](q: =>Parsley[B], name: String): Parsley[B] = new Parsley(new frontend.*>(this.internal, q.internal)).uo(name)
 
@@ -1020,7 +1020,7 @@ object Parsley extends ParsleyImpl with PlatformSpecific {
           * problem: a recursion point inside one of these strict fields
           * will cause an infinite loop at runtime! This can be fixed by
           * ensuring that this becomes part of a lazy argument. This is
-          * a solution described by the [[combinator$.sequence `sequence`]]
+          * a solution described by the [[combinator$.sequence[A]* `sequence`]]
           * combinator, for instance: `p <::> sequence(q, .., r)` will ensure
           * that the `sequence` is in a lazy position in `<::>` meaning that
           * even if any of `q` to `r` must be lazy, they can go in the strict
@@ -1097,6 +1097,7 @@ private [parsley] abstract class ParsleyImpl {
       * @group basic
       */
     final def fresh[A](x: =>A): Parsley[A] = new Parsley(new singletons.Fresh(x))
+    @inline private [parsley] final def transFresh[A](x: =>A) = fresh(x).ut() // FIXME: switch round?
 
     /** This combinator parses its first argument `either`, and then parses either `left` or `right` depending on its result.
       *
@@ -1306,12 +1307,40 @@ private [parsley] abstract class ParsleyImpl {
       * @group iter
       */
     final def many[A](p: Parsley[A]): Parsley[List[A]] = many(p, List)
+    /** This combinator repeatedly parses a given parser '''zero''' or more times, collecting the results into a type `C` via a `Factory[A, C]`.
+      *
+      * Parses a given parser, `p`, repeatedly until it fails. If `p` failed having consumed input,
+      * this combinator fails. Otherwise when `p` fails '''without consuming input''', this combinator
+      * will return all of the results, `x,,1,,` through `x,,n,,` (with `n >= 0`), in a structure: `C(x,,1,,, .., x,,n,,)`.
+      * If `p` was never successful, an empty `C` is returned.
+      *
+      * @example {{{
+      * scala> import parsley.character.string
+      * scala> import parsley.Parsley.many
+      * scala> val p = many(string("ab"), Vector)
+      * scala> p.parse("")
+      * val res0 = Success(Vector.empty)
+      * scala> p.parse("ab")
+      * val res1 = Success(Vector("ab"))
+      * scala> p.parse("abababab")
+      * val res2 = Success(Vector("ab", "ab", "ab", "ab"))
+      * scala> p.parse("aba")
+      * val res3 = Failure(..)
+      * }}}
+      *
+      * @param p the parser to execute multiple times.
+      * @param factory a way to construct the result type `C`
+      * @tparam C a structure that can store `A`s inside it.
+      * @return a parser that parses `p` until it fails, returning all of all the successful results.
+      * @since 5.0.0
+      * @group iter
+      */
+    final def many[A, C](p: Parsley[A], factory: Factory[A, C]): Parsley[C] = secretSome(fresh(factory.newBuilder), p, "many")
     // this is needed for Scala 2 to avoid manual ascription (and ascribes cleaner), but isn't really needed for Scala 3 and increases doc/API footprint
-    // we can add them later if we really wanted to
+    // we can add them later if we really wanted to. Alternatively, p.many(factory) would remove this problem entirely and provide better intellisense.
     //final private [parsley] def many[A, CC[_]](p: Parsley[A], factory: IterableFactory[CC]): Parsley[CC[A]] = many[A, CC[A]](p, factory)
     // this is needed for Scala 2 (or manual ascription on A+C) for ArraySeq, but isn't really needed for Scala 3, and saves 2.12 work
     //final def many[Ev[_], A: Ev, CC[_]](p: Parsley[A], factory: EvidenceIterableFactory[CC, Ev]): Parsley[CC[A]] = many[A, CC[A]](p, factory)
-    final private [parsley] def many[A, C](p: Parsley[A], factory: Factory[A, C]): Parsley[C] = new Parsley(new frontend.Many(p.internal, factory))
 
     /** This combinator repeatedly parses a given parser '''one''' or more times, collecting the results into a list.
       *
@@ -1339,15 +1368,40 @@ private [parsley] abstract class ParsleyImpl {
       * @since 4.5.0
       * @group iter
       */
-    final def some[A](p: Parsley[A]): Parsley[List[A]] = (p <::> many(p).ut()).uo("some")
-    private [parsley] final def some[A, C](p: Parsley[A], factory: Factory[A, C]): Parsley[C] = secretSome(p, p, factory).uo("some")
-    // This could be generalised to be the new many, where many(p, factory) = secretSome(fresh(factory.newBuilder), p, factory)
-    private [parsley] final def secretSome[A, C](init: Parsley[A], p: Parsley[A], factory: Factory[A, C]): Parsley[C] = {
-        secretSome(init.map(factory.newBuilder += _).ut(), p)
+    final def some[A](p: Parsley[A]): Parsley[List[A]] = some(p, List)
+    /** This combinator repeatedly parses a given parser '''one''' or more times, collecting the results into a type `C` via a `Factory[A, C]`.
+      *
+      * Parses a given parser, `p`, repeatedly until it fails. If `p` failed having consumed input,
+      * this combinator fails. Otherwise when `p` fails '''without consuming input''', this combinator
+      * will return all of the results, `x,,1,,` through `x,,n,,` (with `n >= 1`), in a structure: `C(x,,1,,, .., x,,n,,)`.
+      * If `p` was not successful at least one time, this combinator fails.
+      *
+      * @example {{{
+      * scala> import parsley.character.string
+      * scala> import parsley.Parsley.some
+      * scala> val p = some(string("ab"), Vector)
+      * scala> p.parse("")
+      * val res0 = Failure(..)
+      * scala> p.parse("ab")
+      * val res1 = Success(Vector("ab"))
+      * scala> p.parse("abababab")
+      * val res2 = Success(Vector("ab", "ab", "ab", "ab"))
+      * scala> p.parse("aba")
+      * val res3 = Failure(..)
+      * }}}
+      *
+      * @param p the parser to execute multiple times.
+      * @param factory a way to construct the result type `C`.
+      * @tparam C a structure that can store `A`s inside it.
+      * @return a parser that parses `p` until it fails, returning all of all the successful results.
+      * @since 5.0.0
+      * @group iter
+      */
+    final def some[A, C](p: Parsley[A], factory: Factory[A, C]): Parsley[C] = secretSome(p, p, factory, "some")
+    private [parsley] final def secretSome[A, C](init: Parsley[A], p: Parsley[A], factory: Factory[A, C], debugName: String): Parsley[C] = {
+        secretSome(init.map(factory.newBuilder += _).ut(), p, debugName)
     }
-    private [parsley] final def secretSome[A, C](init: Parsley[mutable.Builder[A, C]], p: Parsley[A]): Parsley[C] = {
-        val pf = transPure[(mutable.Builder[A, C], A) => mutable.Builder[A, C]](_ += _)
-        // Can't use the regular foldLeft1 here, because we need a fresh Builder each time.
-        expr.infix.secretLeft1(init, p, pf, null).map(_.result())
+    private [parsley] final def secretSome[A, C](init: Parsley[mutable.Builder[A, C]], p: Parsley[A], debugName: String): Parsley[C] = {
+        new Parsley(new frontend.Many(init.internal, p.internal, debugName))
     }
 }

parsley/shared/src/main/scala/parsley/character.scala

@@ -507,7 +507,7 @@ private [parsley] trait character {
       * @since 4.0.0
       * @group string
       */
-    final def strings(str0: String, strs: String*): Parsley[String] = strings(str0 -> pure(str0), strs.map(s => s -> pure(s)): _*)
+    final def strings(str0: String, strs: String*): Parsley[String] = strings(str0 -> pure(str0), strs.map(s => s -> pure(s))*)
 
     /** This combinator tries to parse each of the key-value pairs `kvs` (and `kv0`), until one of them succeeds.
       *
@@ -552,7 +552,7 @@ private [parsley] trait character {
         choice(ss.groupBy(_._1.head).toList.sortBy(_._1).view.map(_._2).flatMap { s =>
             val (sLast, pLast) :: rest = s.toList.sortBy(_._1.length): @unchecked
             ((string(sLast).ut() ~> pLast.ut()).ut() :: rest.map { case (s, p) => (atomic(string(s).ut()).ut() ~> p).ut() }).reverse
-        }.toSeq: _*).uo((kv0._1 +: kvs.map(_._1)).mkString("strings(", ", ", ")"))
+        }.toSeq*).uo((kv0._1 +: kvs.map(_._1)).mkString("strings(", ", ", ")"))
     }
 
     /** This parser will parse '''any''' single character from the input, failing if there is no input remaining.