let formats: URLFormat =
scheme("https") > host("me.com") > [
// matches URLs with "/echo" path
path("echo"),
// matches URLs with "/hello" path
path("hello")
].reduce(.empty, <|>)

formats.match(URLComponents(string: "https://me.com/echo")!) // Prelude.unit
formats.match(URLComponents(string: "https://me.com/hello")!) // Prelude.unit
formats.match(URLComponents(string: "https://me.com/echo/hello")!) // nil
```

> Note: you can create same `FormatType` from array literal of `FormatType` elements.

This works well when all formats have the same type, i.e. `URLFormat` or `URLFormat`, but it's not possible to combine `URLFormat` with `URLFormat`. For that you can define a sum type (in Swift it's an `enum`) for such formatter use `<¢>` operator.

```swift
enum Routes {
case echo
case hello(String)
}

let formats: URLFormat =
scheme("https") > host("me.com") > [
// matches URLs with "/echo" path
iso(Routes.echo) <¢> path("echo"),
// matches URLs with "/hello/:string" path
iso(Routes.hello) <¢> path("hello") > path(.string)
].reduce(.empty, <|>)

formats.match(URLComponents(string: "https://me.com/echo")!) // Routes.echo
formats.match(URLComponents(string: "https://me.com/hello/world")!) // Routes.hello("world")
```

`iso` here is a helper function that can be used on types that implement `Matchable` protocol. Alternatively you can define partial isomorphisms for your sum type like this:

```swift
extension Routes {
enum iso {
static let echo = PartialIso(
apply: { (_: Prelude.Unit) -> Routes? in
return .echo
},
unapply: { (r: Routes) -> Prelude.Unit? in
return Prelude.unit
})

static let hello = PartialIso(
apply: { (s: String) -> Routes? in
return .hello(s)
},
unapply: { (r: Routes) -> String? in
guard case let .hello(str) = r else { return nil }
return str
})
}
}

let formats: URLFormat =
scheme("https") > host("me.com") > [
// matches URLs with "/echo" path
Routes.iso.echo <¢> path("echo"),
// matches URLs with "/hello/:string" path
Routes.iso.hello <¢> path("hello") > path(.string)
].reduce(.empty, <|>)
```

### Matchable

`Matchable` protocol is a helper protocol that simplifies defining partial isomoprhisms for your sum types. Instead of implementing partial isomorphis for each case you can implement as single method where you can use simple pattern matching. Then you can use `iso` functions with enum case constructors to create partial isomorphism for these enum cases.

let formats: URLFormat =
scheme("https") > host("me.com") > [
// matches URLs with "echo/" path
iso(Routes.echo) <¢> path("echo"),
// matches URLs with "hello/:string" path
iso(Routes.hello) <¢> path("hello") > path(.string)
].reduce(.empty, <|>)
```

> Note: you can generate code for either `Matchable` implementation or for separate `iso`s for each case using Sourcery or SwiftSyntax.

### `print` and `template`

`Parser` can not only parse arbitrary inputs into arbitrary output types but can also be used to produce input based on output. For example with `URLFormat` we can print URLs for arbitrary routes:

```swift
try formats.print(.echo)!.render() // "https://me.com/echo"
try formats.print(.hello("world"))!.render() // "https://me.com/hello/world"
```

This can be helpful when you need to provide an input required to get particular output, i.e. in case of URLs you can use it to render URLs leading to particular content.

You can also use `template` function to get a template-like input:

```swift
try formats.template(.echo)!.render() // "https://me.com/echo"
try formats.template(.hello("world"))!.render() // "https://me.com/hello/:string"
```

This can be useful for things like documentation, logs or error messages.

## Installation

```swift
import PackageDescription