Burrito

Burrito is a Haskell library for parsing and rendering URI templates.

According to RFC 6570: "A URI Template is a compact sequence of characters for describing a range of Uniform Resource Identifiers through variable expansion." Burrito implements URI templates according to the specification in that RFC.

The term "uniform resource identifiers" (URI) is often used interchangeably with other related terms like "internationalized resource identifier" (IRI), "uniform resource locator" (URL), and "uniform resource name" (URN). Burrito can be used for all of these. If you want to get technical, its input must be a valid IRI and its output will be a valid URI or URN.

Although Burrito is primarily intended to be used with HTTP and HTTPS URIs, it should work with other schemes as well.

If you're not already familiar with URI templates, I recommend reading the overview of the RFC. It's short, to the point, and easy to understand.

Assuming you're familiar with URI templates, here's a simple example to show you how Burrito works:

>>> import Burrito
>>> let Just template = parse "http://example/search{?query}"
>>> expand [("query", stringValue "chorizo")] template
"http://example.com/search?query=chorizo"

In short, use parse to parse templates and expand to render them.

Documentation

parse :: String -> Maybe Template

Attempts to parse a string as a URI template. If parsing fails, this will return Nothing. Otherwise it will return Just the parsed template.

Parsing will usually succeed, but it can fail if the input string contains characters that are not valid in IRIs (like ^) or if the input string contains an invalid template expression (like {!}). To include characters that aren't valid in IRIs, percent encode them (like %5E).

render :: Template -> String

Renders a template back into a string. This is essentially the opposite of parse.

expand :: [(String, Value)] -> Template -> String

Expands a template using the given values. Unlike parsing, expansion always succeeds. If no value is given for a variable, it will simply not appear in the output.

uriTemplate :: QuasiQuoter

This can be used together with the QuasiQuotes language extension to parse a URI template at compile time. This is convenient because it allows you to verify the validity of the template when you compile your file as opposed to when you run it.

>>> :set -XQuasiQuotes
>>> import Burrito
>>> let template = [uriTemplate|http://example/search{?query}|]
>>> let values = [("query", stringValue "chorizo")]
>>> expand values template
"http://example/search?query=chorizo"

Note that you cannot use escape sequences in this quasi-quoter. For example, this is invalid: [uriTemplate|\xa0|]. You can however use percent encoded triples as normal. So this is valid: [uriTemplate|%c2%a0|].

data Template

Represents a URI template.

Instances

Eq Template

Defined in Burrito.Type.Template

Methods

(==) :: Template -> Template -> Bool

(/=) :: Template -> Template -> Bool

Show Template

Defined in Burrito.Type.Template

Methods

showsPrec :: Int -> Template -> ShowS

show :: Template -> String

showList :: [Template] -> ShowS

Lift Template

Defined in Burrito.Type.Template

Methods

lift :: Template -> Q Exp

data Value

Represents a value that can be substituted into a template. Can be a string, a list, or dictionary (which is called an associative array in the RFC).

Instances

Eq Value

Defined in Burrito.Type.Value

Methods

(==) :: Value -> Value -> Bool

(/=) :: Value -> Value -> Bool

Show Value

Defined in Burrito.Type.Value

Methods

showsPrec :: Int -> Value -> ShowS

show :: Value -> String

showList :: [Value] -> ShowS

stringValue :: String -> Value

Constructs a string value.

listValue :: [String] -> Value

Constructs a list value.

dictionaryValue :: [(String, String)] -> Value

Constructs a dictionary value.