uritemplate

README

uritemplate
===========

`uritemplate`_ is a Go implementation of `URI Template`_ [RFC6570] with
full functionality of URI Template Level 4.

uritemplate can also generate a regexp that matches expansion of the
URI Template from a URI Template.

Getting Started
---------------

Installation
~~~~~~~~~~~~

.. code-block:: sh

   $ go get -u github.com/yosida95/uritemplate/v3

Documentation
~~~~~~~~~~~~~

The documentation is available on GoDoc_.

Examples
--------

See `examples on GoDoc`_.

License
-------

`uritemplate`_ is distributed under the BSD 3-Clause license.
PLEASE READ ./LICENSE carefully and follow its clauses to use this software.

Author
------

yosida95_


.. _`URI Template`: https://tools.ietf.org/html/rfc6570
.. _Godoc: https://godoc.org/github.com/yosida95/uritemplate
.. _`examples on GoDoc`: https://godoc.org/github.com/yosida95/uritemplate#pkg-examples
.. _yosida95: https://yosida95.com/
.. _uritemplate: https://github.com/yosida95/uritemplate

Documentation

Index

• Constants
• func Equals(t1 *Template, t2 *Template, flags CompareFlags) bool
• type CompareFlags
• type Template
  • func MustNew(template string) *Template
  • func New(template string) (*Template, error)
  • func (t *Template) Expand(vars Values) (string, error)
  • func (tmpl *Template) Match(expansion string) Values
  • func (t *Template) Raw() string
  • func (t *Template) Regexp() *regexp.Regexp
  • func (t *Template) Varnames() []string
• type Value
  • func KV(kv ...string) Value
  • func List(v ...string) Value
  • func String(v string) Value
  • func (v Value) KV() []string
  • func (v Value) List() []string
  • func (v Value) String() string
  • func (v Value) Valid() bool
• type ValueType
  • func (vt ValueType) String() string
• type Values
  • func (v Values) Get(name string) Value
  • func (v Values) Set(name string, value Value)

Examples

• Template.Expand
• Template.Match
• Template.Regexp

Constants

const (
	ValueTypeString = iota
	ValueTypeList
	ValueTypeKV
)

Functions

func Equals

func Equals(t1 *Template, t2 *Template, flags CompareFlags) bool

Equals reports whether or not two URI Templates t1 and t2 are equivalent.

Types

type CompareFlags

type CompareFlags uint8

const (
	CompareVarname CompareFlags = 1 << iota
)

type Template

type Template struct {
	// contains filtered or unexported fields
}

Template represents a URI Template.

func MustNew

func MustNew(template string) *Template

MustNew panics if the template cannot be recognized.

func New

func New(template string) (*Template, error)

New parses and constructs a new Template instance based on the template. New returns an error if the template cannot be recognized.

func (*Template) Expand

func (t *Template) Expand(vars Values) (string, error)

Expand returns a URI reference corresponding to the template expanded using the passed variables.

Example

tmpl := MustNew("https://example.com/dictionary/{term:1}/{term}")

vars := Values{}
vars.Set("term", String("cat"))
ret, err := tmpl.Expand(vars)
if err != nil {
	fmt.Println(err)
	return
}
fmt.Println(ret)

Output:

https://example.com/dictionary/c/cat

func (*Template) Match

func (tmpl *Template) Match(expansion string) Values

Example

tmpl := MustNew("https://example.com/dictionary/{term:1}/{term}")
match := tmpl.Match("https://example.com/dictionary/c/cat")
if match == nil {
	fmt.Println("not matched")
	return
}

fmt.Printf("term:1 is %q\n", match.Get("term:1").String())
fmt.Printf("term is %q\n", match.Get("term").String())

Output:

term:1 is "c"
term is "cat"

func (*Template) Raw

func (t *Template) Raw() string

Raw returns a raw URI template passed to New in string.

func (*Template) Regexp

func (t *Template) Regexp() *regexp.Regexp

Regexp converts the template to regexp and returns compiled *regexp.Regexp.

Example

tmpl := MustNew("https://example.com/dictionary/{term:1}/{term}")
re := tmpl.Regexp()

fmt.Println(re.MatchString("https://example.com/dictionary/c/cat"))
fmt.Println(re.MatchString("https://example.com/dictionary/c/a/cat"))

Output:

true
false

func (*Template) Varnames

func (t *Template) Varnames() []string

Varnames returns variable names used in the template.

type Value

type Value struct {
	T ValueType
	V []string
}

func KV

func KV(kv ...string) Value

KV returns Value that represents associative list. KV panics if len(kv) is not even.

func List

func List(v ...string) Value

List returns Value that represents list.

func String

func String(v string) Value

String returns Value that represents string.

func (Value) KV

func (v Value) KV() []string

func (Value) List

func (v Value) List() []string

func (Value) String

func (v Value) String() string

func (Value) Valid

func (v Value) Valid() bool

type ValueType

type ValueType uint8

func (ValueType) String

func (vt ValueType) String() string

type Values

type Values map[string]Value

A varname containing pct-encoded characters is not the same variable as a varname with those same characters decoded.

-- https://tools.ietf.org/html/rfc6570#section-2.3

func (Values) Get

func (v Values) Get(name string) Value

func (Values) Set

func (v Values) Set(name string, value Value)