urn

README

A parser for URNs.

As seen on RFC 2141.

API documentation.

Installation

go get github.com/leodido/go-urn

Performances

This implementation results to be really fast.

Usually below ½ microsecond on my machine¹.

Notice it also performs, while parsing:

1. fine-grained and informative erroring
2. specific-string normalization

ok/00/urn:a:b______________________________________/-4      20000000      265 ns/op      182 B/op      6 allocs/op
ok/01/URN:foo:a123,456_____________________________/-4      30000000      296 ns/op      200 B/op      6 allocs/op
ok/02/urn:foo:a123%2c456___________________________/-4      20000000      331 ns/op      208 B/op      6 allocs/op
ok/03/urn:ietf:params:scim:schemas:core:2.0:User___/-4      20000000      430 ns/op      280 B/op      6 allocs/op
ok/04/urn:ietf:params:scim:schemas:extension:enterp/-4      20000000      411 ns/op      312 B/op      6 allocs/op
ok/05/urn:ietf:params:scim:schemas:extension:enterp/-4      20000000      472 ns/op      344 B/op      6 allocs/op
ok/06/urn:burnout:nss______________________________/-4      30000000      257 ns/op      192 B/op      6 allocs/op
ok/07/urn:abcdefghilmnopqrstuvzabcdefghilm:x_______/-4      20000000      375 ns/op      213 B/op      6 allocs/op
ok/08/urn:urnurnurn:urn____________________________/-4      30000000      265 ns/op      197 B/op      6 allocs/op
ok/09/urn:ciao:@!=%2c(xyz)+a,b.*@g=$_'_____________/-4      20000000      307 ns/op      248 B/op      6 allocs/op
ok/10/URN:x:abc%1dz%2f%3az_________________________/-4      30000000      259 ns/op      212 B/op      6 allocs/op
no/11/URN:-xxx:x___________________________________/-4      20000000      445 ns/op      320 B/op      6 allocs/op
no/12/urn::colon:nss_______________________________/-4      20000000      461 ns/op      320 B/op      6 allocs/op
no/13/urn:abcdefghilmnopqrstuvzabcdefghilmn:specifi/-4      10000000      660 ns/op      320 B/op      6 allocs/op
no/14/URN:a!?:x____________________________________/-4      20000000      507 ns/op      320 B/op      6 allocs/op
no/15/urn:urn:NSS__________________________________/-4      20000000      429 ns/op      288 B/op      6 allocs/op
no/16/urn:white_space:NSS__________________________/-4      20000000      482 ns/op      320 B/op      6 allocs/op
no/17/urn:concat:no_spaces_________________________/-4      20000000      539 ns/op      328 B/op      7 allocs/op
no/18/urn:a:/______________________________________/-4      20000000      470 ns/op      320 B/op      7 allocs/op
no/19/urn:UrN:NSS__________________________________/-4      20000000      399 ns/op      288 B/op      6 allocs/op

---

• [1]: Intel Core i7-7600U CPU @ 2.80GHz

---

Example

package main

import (
	"fmt"
	"github.com/leodido/go-urn"
)

func main() {
	var uid = "URN:foo:a123,456"

	u, ok := urn.Parse([]byte(uid))
	if !ok {
		panic("error parsing urn")
	}

	fmt.Println(u.ID)
	fmt.Println(u.SS)

	// Output:
	// foo
	// a123,456
}

Documentation

Index

• type Machine
  • func NewMachine() Machine
• type URN
  • func Parse(u []byte) (*URN, bool)
  • func (u *URN) Equal(x *URN) bool
  • func (u URN) MarshalJSON() ([]byte, error)
  • func (u *URN) Normalize() *URN
  • func (u *URN) String() string
  • func (u *URN) UnmarshalJSON(bytes []byte) error

Examples

• Parse
• URN.Equal
• URN.MarshalJSON

Types

type Machine

type Machine interface {
	Error() error
	Parse(input []byte) (*URN, error)
}

Machine is the interface representing the FSM

func NewMachine

func NewMachine() Machine

NewMachine creates a new FSM able to parse RFC 2141 strings.

type URN

type URN struct {
	ID string // Namespace identifier
	SS string // Namespace specific string
	// contains filtered or unexported fields
}

URN represents an Uniform Resource Name.

The general form represented is:

urn:<id>:<ss>

Details at https://tools.ietf.org/html/rfc2141.

func Parse

func Parse(u []byte) (*URN, bool)

Parse is responsible to create an URN instance from a byte array matching the correct URN syntax.

Example

package main

import (
	"fmt"
	"github.com/leodido/go-urn"
)

func main() {
	var uid = "URN:foo:a123,456"

	if u, ok := urn.Parse([]byte(uid)); ok {
		fmt.Println(u.ID)
		fmt.Println(u.SS)
	}

}

Output:
foo
a123,456

func (*URN) Equal

func (u *URN) Equal(x *URN) bool

Equal checks the lexical equivalence of the current URN with another one.

Example

package main

import (
	"fmt"
	"github.com/leodido/go-urn"
)

func main() {
	var uid1 = "URN:foo:a123,456"
	var uid2 = "URN:FOO:a123,456"

	u1, ok := urn.Parse([]byte(uid1))
	if !ok {
		panic("invalid urn")
	}

	u2, ok := urn.Parse([]byte(uid2))
	if !ok {
		panic("invalid urn")
	}

	if u1.Equal(u2) {
		fmt.Printf("%s equals %s", u1.String(), u2.String())
	}

}

Output:
URN:foo:a123,456 equals URN:FOO:a123,456

func (URN) MarshalJSON

func (u URN) MarshalJSON() ([]byte, error)

MarshalJSON marshals the URN to JSON string form (e.g. `"urn:oid:1.2.3.4"`).

Example

package main

import (
	"fmt"
	"github.com/leodido/go-urn"
)

func main() {
	var uid = "URN:foo:a123,456"

	if u, ok := urn.Parse([]byte(uid)); ok {
		json, err := u.MarshalJSON()
		if err != nil {
			panic("invalid urn")
		}
		fmt.Println(string(json))
	}

}

Output:
"URN:foo:a123,456"

func (*URN) Normalize

func (u *URN) Normalize() *URN

Normalize turns the receiving URN into its norm version.

Which means: lowercase prefix, lowercase namespace identifier, and immutate namespace specific string chars (except <hex> tokens which are lowercased).

func (*URN) String

func (u *URN) String() string

String reassembles the URN into a valid URN string.

This requires both ID and SS fields to be non-empty. Otherwise it returns an empty string.

Default URN prefix is "urn".

func (*URN) UnmarshalJSON

func (u *URN) UnmarshalJSON(bytes []byte) error

MarshalJSON unmarshals a URN from JSON string form (e.g. `"urn:oid:1.2.3.4"`).