URI Template Syntax for Mustermann

This gem implements the uri-template (or template) pattern type for Mustermann. It is compatible with RFC 6570 (level 4), JSON API, JSON Home Documents and many more

Overview

Supported options: capture, except, greedy, space_matches_plus, uri_decode, and ignore_unknown_options.

Please keep the following in mind:

"Some URI Templates can be used in reverse for the purpose of variable matching: comparing the template to a fully formed URI in order to extract the variable parts from that URI and assign them to the named variables. Variable matching only works well if the template expressions are delimited by the beginning or end of the URI or by characters that cannot be part of the expansion, such as reserved characters surrounding a simple string expression. In general, regular expression languages are better suited for variable matching." — RFC 6570, Sec 1.5: "Limitations"

require 'mustermann'

pattern = Mustermann.new('/{example}', type: :template)
pattern === "/foo.bar"     # => true
pattern === "/foo/bar"     # => false
pattern.params("/foo.bar") # => { "example" => "foo.bar" }
pattern.params("/foo/bar") # => nil

pattern = Mustermann.new("{/segments*}/{page}{.ext,cmpr:2}", type: :template)
pattern.params("/a/b/c.tar.gz") # => {"segments"=>["a","b"], "page"=>"c", "ext"=>"tar", "cmpr"=>"gz"}

Generating URI Templates

You do not need to use URI templates (and this gem) if all you want is reusing them for hypermedia links. Most other pattern types support generating these (via #to_pattern):

require 'mustermann'

Mustermann.new('/:name').to_templates # => ['/{name}']

Moreover, Mustermann's default pattern type implements a subset of URI templates ({capture} and {+capture}) and can therefore also be used for simple templates/

require 'mustermann'

Mustermann.new('/{name}').expand(name: "example") # => "/example"

Syntax

Syntax Element	Description
{o var m, var m, ...}	Captures expansion. Operator o: + # . / ; ? & or none. Modifier m: :num * or none.
/	Matches forward slash. Does not match URI encoded version of forward slash.
any other character	Matches exactly that character or a URI encoded version of it.

The operators + and # will always match non-greedy, whereas all other operators match semi-greedy by default. All modifiers and operators are supported. However, it does not parse lists as single values without the explode modifier (aka star). Parametric operators (;, ? and &) currently only match parameters in given order.

Note that it differs from URI templates in that it takes the unescaped version of special character instead of the escaped version.

If you reuse the exact same templates and expose them via an external API meant for expansion, you should set uri_decode to false in order to conform with the specification.