+
+
+
+## Motivation
+
+Parsing is a surprisingly ubiquitous problem in programming. We can define parsing as trying to take a more nebulous blob of data and transform it into something more well-structured. The Swift standard library comes with a number of parsers that we reach for every day. For example, there are initializers on `Int`, `Double`, and even `Bool`, that attempt to parse numbers and booleans from strings:
+
+```swift
+Int("42") // 42
+Int("Hello") // nil
+
+Double("123.45") // 123.45
+Double("Goodbye") // nil
+
+Bool("true") // true
+Bool("0") // nil
+```
+
+And there are types like `JSONDecoder` and `PropertyListDecoder` that attempt to parse `Decodable`-conforming types from data:
+
+```swift
+try JSONDecoder().decode(User.self, from: data)
+try PropertyListDecoder().decode(Settings.self, from: data)
+```
+
+While parsers are everywhere in Swift, Swift has no holistic story _for_ parsing. Instead, we typically parse data in an ad hoc fashion using a number of unrelated initializers, methods, and other means. And this typically leads to less maintainable, less reusable code.
+
+This library aims to write such a story for parsing in Swift. It introduces a single unit of parsing that can be combined in interesting ways to form large, complex parsers that can tackle the programming problems you need to solve in a maintainable way.
+
+## Getting started
+
+Suppose you have a string that holds some user data that you want to parse into an array of `User`s:
+
+```swift
+var input = """
+1,Blob,true
+2,Blob Jr.,false
+3,Blob Sr.,true
+"""
+
+struct User {
+ var id: Int
+ var name: String
+ var isAdmin: Bool
+}
+```
+
+A naive approach to this would be a nested use of `.split(separator:)`, and then a little bit of extra work to convert strings into integers and booleans:
+
+```swift
+let users = input
+ .split(separator: "\n")
+ .compactMap { row -> User? in
+ let fields = row.split(separator: ",")
+ guard
+ fields.count == 3,
+ let id = Int(fields[0]),
+ let isAdmin = Bool(String(fields[2]))
+ else { return nil }
+
+ return User(id: id, name: String(fields[1]), isAdmin: isAdmin)
+ }
+```
+
+Not only is this code a little messy, but it is also inefficient since we are allocating arrays for the `.split` and then just immediately throwing away those values.
+
+It would be more straightforward and efficient to instead describe how to consume bits from the beginning of the input and convert that into users. This is what this parser library excels at 😄.
+
+We can start by describing what it means to parse a single row, first by parsing an integer off the front of the string, and then parsing a comma. We can do this by using the `Parse` type, which acts as an entry point into describing a list of parsers that you want to run one after the other to consume from an input:
+
+```swift
+let user = Parse {
+ Int.parser()
+ ","
+}
+```
+
+Already this can consume the beginning of the input:
+
+```swift
+user.parse(&input) // => 1
+input // => "Blob,true\n2,Blob Jr.,false\n3,Blob Sr.,true"
+```
+
+Next we want to take everything up until the next comma for the user's name, and then consume the comma:
+
+```swift
+let user = Parse {
+ Int.parser()
+ ","
+ Prefix { $0 != "," }
+ ","
+}
+```
+
+And then we want to take the boolean at the end of the row for the user's admin status:
+
+```swift
+let user = Parse {
+ Int.parser()
+ ","
+ Prefix { $0 != "," }
+ ","
+ Bool.parser()
+}
+```
+
+Currently this will parse a tuple `(Int, Substring, Bool)` from the input, and we can `.map` on that to turn it into a `User`:
+
+```swift
+let user = Parse {
+ Int.parser()
+ ","
+ Prefix { $0 != "," }
+ ","
+ Bool.parser()
+}
+.map { User(id: $0, name: String($1), isAdmin: $2) }
+```
+
+To make the data we are parsing to more prominent, we can instead pass the transform closure as the first argument to `Parse`:
+
+```swift
+let user = Parse {
+ User(id: $0, name: String($1), isAdmin: $2)
+} with: {
+ Int.parser()
+ ","
+ Prefix { $0 != "," }
+ ","
+ Bool.parser()
+}
+```
+
+Or we can pass the `User` initializer to `Parse` in a point-free style by transforming the `Prefix` parser's output from a `Substring` to ` String` first:
+
+```swift
+let user = Parse(User.init(id:name:isAdmin:)) {
+ Int.parser()
+ ","
+ Prefix { $0 != "," }.map(String.init)
+ ","
+ Bool.parser()
+}
+```
+
+That is enough to parse a single user from the input string, leaving behind a newline and the final two users:
+
+```swift
+user.parse(&input) // => User(id: 1, name: "Blob", isAdmin: true)
+input // => "\n2,Blob Jr.,false\n3,Blob Sr.,true"
+```
+
+To parse multiple users from the input we can use the `Many` parser to run the user parser many times:
+
+```swift
+let users = Many {
+ user
+} separator: {
+ "\n"
+}
+
+users.parse(&input) // => [User(id: 1, name: "Blob", isAdmin: true), ...]
+input // => ""
+```
+
+Now this parser can process an entire document of users, and the code is simpler and more straightforward than the version that uses `.split` and `.compactMap`.
+
+Even better, it's more performant. We've written [benchmarks](Sources/swift-parsing-benchmark/ReadmeExample.swift) for these two styles of parsing, and the `.split`-style of parsing is more than twice as slow:
+
+```
+name time std iterations
+------------------------------------------------------------------
+README Example.Parser: Substring 3426.000 ns ± 63.40 % 385395
+README Example.Adhoc 7631.000 ns ± 47.01 % 169332
+Program ended with exit code: 0
+```
+
+Further, if you are willing write your parsers against `UTF8View` instead of `Substring`, you can eke out even more performance, more than doubling the speed:
+
+```
+name time std iterations
+------------------------------------------------------------------
+README Example.Parser: Substring 3693.000 ns ± 81.76 % 349763
+README Example.Parser: UTF8 1272.000 ns ± 128.16 % 999150
+README Example.Adhoc 8504.000 ns ± 59.59 % 151417
+```
+
+We can also compare these times to a tool that Apple's Foundation gives us: `Scanner`. It's a type that allows you to consume from the beginning of strings in order to produce values, and provides a nicer API than using `.split`:
+
+```swift
+var users: [User] = []
+while scanner.currentIndex != input.endIndex {
+ guard
+ let id = scanner.scanInt(),
+ let _ = scanner.scanString(","),
+ let name = scanner.scanUpToString(","),
+ let _ = scanner.scanString(","),
+ let isAdmin = scanner.scanBool()
+ else { break }
+
+ users.append(User(id: id, name: name, isAdmin: isAdmin))
+ _ = scanner.scanString("\n")
+}
+```
+
+However, the `Scanner` style of parsing is more than 5 times as slow as the substring parser written above, and more than 15 times slower than the UTF-8 parser:
+
+```
+name time std iterations
+-------------------------------------------------------------------
+README Example.Parser: Substring 3481.000 ns ± 65.04 % 376525
+README Example.Parser: UTF8 1207.000 ns ± 110.96 % 1000000
+README Example.Adhoc 8029.000 ns ± 44.44 % 163719
+README Example.Scanner 19786.000 ns ± 35.26 % 62125
+```
+
+That's the basics of parsing a simple string format, but there's a lot more operators and tricks to learn in order to performantly parse larger inputs. View the [benchmarks](Sources/swift-parsing-benchmark) for examples of real life parsing scenarios.
+
+## Design
+
+### Protocol
+
+The design of the library is largely inspired by the Swift standard library and Apple's Combine framework. A parser is represented as a protocol that many types conform to, and then parser transformations (also known as "combinators") are methods that return concrete types conforming to the parser protocol.
+
+For example, to parse all the characters from the beginning of a substring until you encounter a comma you can use the `Prefix` parser:
+
+```swift
+let parser = Prefix { $0 != "," }
+
+var input = "Hello,World"[...]
+parser.parse(&input) // => "Hello"
+input // => ",World"
+```
+
+The type of this parser is:
+
+```swift
+Prefix(_ parsers: [P]) -> Parsers.OneOfMany
{ + .init(parsers) + } + + @inlinable + static public func buildBlock
(_ parser: P) -> P where P: Parser {
+ parser
+ }
+
+ @inlinable
+ public static func buildEither (_ parser: P?) -> Conditional (
+ _ parser: P?
+ ) -> Conditional (_ parser: P) -> P where P: Parser {
+ parser
+ }
+
+ @inlinable
+ public static func buildEither (_ parser: P?) -> P? where P: Parser {
+ parser
+ }
+
+ @inlinable
+ public static func buildIf (_ parser: P?) -> Parsers.OptionalVoid {
+ .init(wrapped: parser)
+ }
+
+ @inlinable
+ public static func buildLimitedAvailability (_ parser: P?) -> P? where P: Parser {
+ parser
+ }
+
+ @inlinable
+ public static func buildLimitedAvailability (_ parser: P?) -> Parsers.OptionalVoid {
+ .init(wrapped: parser)
+ }
+}
diff --git a/0176-parser-errors-pt1/swift-parsing/Sources/Parsing/Builders/Variadics.swift b/0176-parser-errors-pt1/swift-parsing/Sources/Parsing/Builders/Variadics.swift
new file mode 100644
index 00000000..068d3a3d
--- /dev/null
+++ b/0176-parser-errors-pt1/swift-parsing/Sources/Parsing/Builders/Variadics.swift
@@ -0,0 +1,7662 @@
+// BEGIN AUTO-GENERATED CONTENT
+
+extension Parsers {
+ public struct ZipOO