URITemplate - a uri template library
With URITemplate you can generate URIs based on templates. The template syntax is defined by the RFC 6570 spec.
This shard supports expansion and partial expansion (but not extraction).
Installation
-
Add the dependency to your
shard.yml
:dependencies: uri_template: github: nanobowers/uri_template
-
Run
shards install
Usage
require "uri_template"
tpl = URITemplate.new("http://{host}{/segments*}/{file}{.extensions*}")
# This will fuly expand the template:
tpl.expand(host: "www.host.com", segments: ["path","to","a"], file: "file", extensions: ["x","y"])
# => "http://www.host.com/path/to/a/file.x.y"
# This will give a new uri template with just the host expanded:
tpl.expand_partial(host: "www.host.com")
# => <URITemplate::Template:0x7fb7e1bb1e40 ...>
Keyword or Hash Arguments
expand
and expand_partial
can accept either keyword arguments or a Hash argument, or both. Keyword arguments have precedence over the hash argument.
Template vs URITemplate
The URITemplate
module has several convenience module methods that create an instance of URITemplate::Template
and then peform an operation on at constructed object (e.g. expand
, expand_partial
, variables
, etc.) Depending on the use model it may be more convenient or efficient to use the underlying URITemplate::Template class.
# equivalent approaches:
URITemplate::Template.new("{variable}").expand(variable: "value")
URITemplate.expand("{variable}", variable: "value")
RFC 6570 Syntax
The syntax defined by RFC 6570 has lots of features. Generally, anything surrounded by curly brackets is interpreted as variable.
URITemplate.new("{variable}").expand(variable: "value")
# => "value"
The way variables are inserted can be modified using operators. The operator is the first character between the curly brackets. There are seven operators de
fined #
, +
, ;
, ?
, &
, /
and .
. So if you want to create a form-style query do this:
URITemplate.new("{?variable}").expand(variable: "value")
# => "?variable=value"
Testing
This passes the rfc6570 test-suite provied by the uritemplate-test
suite which is included as a git submodule and used by other uritemplate packages for other programming languages. In addition to those tests, there are quite a few additional tests which are inspired by tests in some popular Ruby gems and Python packages. Please feel free to write some more tests and submit a PR.
git submodule init
git submodule update
crystal spec
Contributing
- Fork it (https://github.com/your-github-user/uri_template/fork)
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Add some feature'
) - Push to the branch (
git push origin my-new-feature
) - Create a new Pull Request
Contributors
- Ben Bowers - creator and maintainer
License
Note that the included uritemplate-test
submodule is Apache v2.0 licensed.