Consider putting more parsers in the Parsers namespace

[mayoff]

This is just a humble suggestion from a fan.

I see that you have an public enum Parsers { } to use as a namespace, like Combine does with the Publishers type. But you've still defined several parser types (like Lazy, Prefix, and First) at module scope, to make it more convenient to use them. But this is likely, particularly in the case of Lazy, to conflict with names from other modules.

Here's an alternative to consider: put all the parser types in the Parsers namespace. Then define a protocol ParserUsing that “imports” those names as type aliases. Example:

// ---- ParserUsing.swift
public protocol ParserUsing { }

extension Parsers: ParserUsing { }

// ---- Parser.swift
public protocol Parser: ParserUsing {
...
}

// ---- First.swift
...
extension ParserUsing {
    public typealias First = Parsers.First
}

// ---- Lazy.swift
...
extension ParserUsing {
    public typealias Lazy = Parsers.Lazy
}

// ---- Prefix.swift
...
extension ParserUsing {
    public typealias Prefix = Parsers.Prefix
}

Since Parser is a subprotocol of ParserUsing, every Parser automatically conforms to ParserUsing and has access to the type aliases. And since Parsers conforms to ParserUsing, the same is true in every extension of Parsers.

Further, any type that builds a parser can add a conformance to ParserUsing to import the type aliases. Example:

final class PrefixTests: XCTestCase, ParserUsing {
...
}

[mbrandonw]

Hey @mayoff, thanks for bringing this up! It's actually something @stephencelis and I discussed quite a bit before open sourcing. We're still not sure where to draw the line. We're kinda following Combine's lead here.

Your suggestion is interesting, but unfortunately would only work when implementing a parser by conforming a type to the Parser protocol. If you were to use the Prefix parser at the top level (as we do in our benchmark case studies) you would have to use it as Parsers.Prefix, which would be pretty verbose.

We're happy to discuss this more, but it might be better to do so in the discussions tab. This is our first time using this GitHub feature.

[mayoff]

Yes, it doesn't help for top-level parsers. I sometimes do typealias P = Parsers for that but usually I just put my parsers in either the Parsers namespace or in the type I'm parsing to (e.g. Recipe.parser if I'm parsing to make a Recipe).

Anyway, I don't really have anything else to add. Thanks for letting me know you've considered it.

[stephencelis]

@mayoff Thanks for starting the discussion! We're definitely open to refine the ergonomics of the library. As far as our mentality has been with what we've shipped so far, @mbrandonw pointed out that we've mostly tried to follow Combine's lead. This means establishing a few loose rules:

1. If the parser is primarily vended from the method of another parser, the type should be nested in Parsers. (Like many publishers in Combine: Publishers.Map, Publishers.FlatMap, etc.)
2. If the parser is only meant to be used at the start of a chain, like Prefix and StartsWith, the type should be at the module level. (Like the Just, Fail, Future, Deferred Combine publishers, and more.) A sub-rule is that these "free" parsers should try not to collide with Combine publishers. It's idealistic, of course, and we have one exception with the Fail parser (if you have other name ideas that don't collide, let us know!), but generally we've found appropriate alternatives (Just→Always, Deferred→Lazy, etc.).
3. If it's a parser of a specific type as output, it should be exposed as a static member on that type, like Int.parser(), Bool.parser(), etc. This is a nod to Combine, which exposes publisher properties and methods on optionals, sequences, and URL sessions, but isn't quite the same.

One other thing we do for 2. and 3. is add a convenience type alias to them inside the Parsers namespace, so you can explore all of the publishers the library contains via autocomplete. (This is an experiment that we hope is helpful, but if it's the opposite we'll probably remove them.)

While we have established these rules, the reality is that they are loose and could be refined. For example:

• Optional.parser(of: anotherParser) could be a method, like anotherParser.optional(), but we found that "optional parser of another parser" reads better than "another parser, optional". This could probably be bike-shed to something just as nice or nicer, though? Like maybe anotherParser.optionally(), anotherParser.orNil(), etc.
• I think Combine still nests some publishers that are meant to be used at the start of the chain, like Publishers.MergeMany, So maybe we should do the same with OneOfMany (especially since Parsers.OneOf via orElse should be preferred unless you're really given the opportunity to improve performance with OneOfMany, and maybe that opportunity is narrow enough that we should remove it from the core library entirely, and instead let performance-critical users to define it, or that kind of branching, from scratch?).
• We should also maybe tighten up the number of module-"free" parsers defined when possible, like removing or nesting OneOfMany, and folding PrefixThrough and PrefixUpTo into the Prefix parser.
• We also deviate a bit from Combine's practice of namespacing publishers like DataTaskPublisher inside URLSession, not sure if it makes sense to move IntParser into the Int type, etc.

If you have any specific ideas we'd love to hear them! We'd also love to hear of any specific instances in which having top-level parser types interferes with your workflow. Are you having a conflict in a particular code base because of our Prefix type, or our StartsWith type, etc.?

[ollitapa]

My main gripe with using only the Parsers namespace is that it is pretty poor for discoverability. One really does not know what parser works with my current Input-Output combo. I'd rather see more of extension methods for Parser protocol, so that .take(.someParser()) would autocomplete better. I see this approach in Combine where most of the stuff I usually write is a protocol extension method chaining. Only the start of chain is plain type like Just and Future. In SwiftUI it seems that all the ViewModifier conformances are usually conveniently added to View protocol as extension methods, like .backgroud().

Maybe consider adding more of these convenience methods for types that are somehow more like modifiers to an existing parser? For example with OptionalParser, I like the anotherParser.orNil() approach, because the OptionalParser is really nothing by itself, it always modifies some other parser.

Then again, Prefix parsers would also be nice to have as an extension methods like they are in Combine, although they do not "modify" anything in this parser context. 😅