From 283d0ad598d31f77d2ed8671e831978476ff7851 Mon Sep 17 00:00:00 2001 From: Leonardo Di Donato Date: Fri, 26 Jan 2024 15:18:10 +0100 Subject: [PATCH] docs: update README Signed-off-by: Leonardo Di Donato --- README.md | 120 ++++++++++++++++++++++++++++++++++++++---------- parsing_mode.go | 2 +- 2 files changed, 96 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index 731eecb..5430e63 100644 --- a/README.md +++ b/README.md @@ -6,12 +6,23 @@ [API documentation](https://godoc.org/github.com/leodido/go-urn). +Starting with version 1.3 this library also supports [RFC 7643 SCIM URNs](https://datatracker.ietf.org/doc/html/rfc7643#section-10). + ## Installation ``` go get github.com/leodido/go-urn ``` +## Features + +1. RFC 2141 URNs parsing (default) +2. RFC 7643 SCIM URNs parsing +3. Fallback mode: first try to parse the input as a RFC 7643 SCIM URN, then fallback to RFC 2141 URN generic format. +4. Normalization as per RFC 2141 +4. Lexical equivalence as per RFC 2141 +5. Precise, fine-grained errors + ## Performances This implementation results to be really fast. @@ -24,35 +35,36 @@ Notice it also performs, while parsing: 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 +Parse/ok/00/urn:a:b______________________________________/-10 71113568 84.88 ns/op 211 B/op 3 allocs/op +Parse/ok/01/URN:foo:a123,456_____________________________/-10 49303754 126.1 ns/op 232 B/op 6 allocs/op +Parse/ok/02/urn:foo:a123%2c456___________________________/-10 46723497 122.1 ns/op 240 B/op 6 allocs/op +Parse/ok/03/urn:ietf:params:scim:schemas:core:2.0:User___/-10 34231863 175.1 ns/op 312 B/op 6 allocs/op +Parse/ok/04/urn:ietf:params:scim:schemas:extension:enterp/-10 25406808 233.6 ns/op 344 B/op 6 allocs/op +Parse/ok/05/urn:ietf:params:scim:schemas:extension:enterp/-10 22353264 265.6 ns/op 376 B/op 6 allocs/op +Parse/ok/06/urn:burnout:nss______________________________/-10 52932087 112.9 ns/op 224 B/op 6 allocs/op +Parse/ok/07/urn:abcdefghilmnopqrstuvzabcdefghilm:x_______/-10 45005554 134.3 ns/op 243 B/op 4 allocs/op +Parse/ok/08/urn:urnurnurn:urn____________________________/-10 46788519 124.7 ns/op 229 B/op 6 allocs/op +Parse/ok/09/urn:ciao:@!=%2c(xyz)+a,b.*@g=$_'_____________/-10 39037539 153.8 ns/op 264 B/op 6 allocs/op +Parse/ok/10/URN:x:abc%1dz%2f%3az_________________________/-10 45692990 121.4 ns/op 243 B/op 5 allocs/op +Parse/no/11/URN:-xxx:x___________________________________/-10 26935477 221.1 ns/op 355 B/op 5 allocs/op +Parse/no/12/urn::colon:nss_______________________________/-10 25088925 232.4 ns/op 355 B/op 5 allocs/op +Parse/no/13/urn:abcdefghilmnopqrstuvzabcdefghilmn:specifi/-10 21206989 295.1 ns/op 355 B/op 5 allocs/op +Parse/no/14/URN:a!?:x____________________________________/-10 26705482 223.5 ns/op 355 B/op 5 allocs/op +Parse/no/15/urn:urn:NSS__________________________________/-10 31609467 202.1 ns/op 307 B/op 5 allocs/op +Parse/no/16/urn:white_space:NSS__________________________/-10 26144792 232.2 ns/op 355 B/op 5 allocs/op +Parse/no/17/urn:concat:no_spaces_________________________/-10 23717426 251.1 ns/op 346 B/op 6 allocs/op +Parse/no/18/urn:a:/______________________________________/-10 27442077 221.9 ns/op 339 B/op 5 allocs/op +Parse/no/19/urn:UrN:NSS__________________________________/-10 32096002 187.4 ns/op 307 B/op 5 allocs/op ``` ---- +* [1]: Apple M1 Pro -* [1]: Intel Core i7-7600U CPU @ 2.80GHz - ---- ## Example + +For more examples take a look at the [examples file](examples_test.go). + + ```go package main @@ -64,6 +76,35 @@ import ( func main() { var uid = "URN:foo:a123,456" + // Parse the input string as a RFC 2141 URN only + u, e := urn.NewMachine().Parse(uid) + if e != nil { + fmt.Errorf(err) + + return + } + + fmt.Println(u.ID) + fmt.Println(u.SS) + + // Output: + // foo + // a123,456 +} +``` + +```go +package main + +import ( + "fmt" + "github.com/leodido/go-urn" +) + +func main() { + var uid = "URN:foo:a123,456" + + // Parse the input string as a RFC 2141 URN only u, ok := urn.Parse([]byte(uid)) if !ok { panic("error parsing urn") @@ -78,4 +119,33 @@ func main() { } ``` -[![Analytics](https://ga-beacon.appspot.com/UA-49657176-1/go-urn?flat)](https://github.com/igrigorik/ga-beacon) \ No newline at end of file +```go +package main + +import ( + "fmt" + "github.com/leodido/go-urn" +) + +func main() { + input := "urn:ietf:params:scim:api:messages:2.0:ListResponse" + + // Parsing the input string as a RFC 7643 SCIM URN + u, ok := urn.Parse([]byte(input), urn.WithParsingMode(urn.RFC7643Only)) + if !ok { + panic("error parsing urn") + } + + fmt.Println(u.IsSCIM()) + scim := u.SCIM() + fmt.Println(scim.Type.String()) + fmt.Println(scim.Name) + fmt.Println(scim.Other) + + // Output: + // true + // api + // messages + // 2.0:ListResponse +} +``` \ No newline at end of file diff --git a/parsing_mode.go b/parsing_mode.go index a05f41b..a7f7004 100644 --- a/parsing_mode.go +++ b/parsing_mode.go @@ -3,7 +3,7 @@ package urn type ParsingMode int const ( - All ParsingMode = iota + All ParsingMode = iota // Fallback mode RFC2141Only RFC7643Only )