Merge pull request #96: feat!: Introduce New function with functional options pattern

Today, we have separate functions for creating the Parser - NewFromSaved for using the built-in yaml definitions, NewFromBytes for providing your own regexes as bytes of a yaml file, and NewWithOptions for providing a path to a yaml file with various options from the library selected - e.g. configuring the LRU cache size, turning on the (unsafe) sorting mode, and options related to that.

This PR implements a New function that using the function options pattern. So instead of using any of the old interfaces, you can now New(WithRegexDefinitions(...)) to provide your own regexes, New(WithCacheSize(...)) to customize the cache size, or any combination of our new With* functions - the full list added here is: WithMode, WithDebug, WithSort, WithCacheSize, WithMissesThreshold, WithMatchIdxNotOk, and WithRegexDefinitions

Author: dgoldstein0

README.md

@@ -42,14 +42,29 @@ package main
 import (
   "fmt"
   "log"
+  "os"
 
   "github.com/ua-parser/uap-go/uaparser"
+  "gopkg.in/yaml.v3"
 )
 
 func main() {
   uagent := "Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10_6_3; en-us; Silk/1.1.0-80) AppleWebKit/533.16 (KHTML, like Gecko) Version/5.0 Safari/533.16 Silk-Accelerated=true"
 
-  parser, err := uaparser.New("./regexes.yaml")
+
+  regexes, err := os.ReadFile("./regexes.yaml")
+  if err != nil {
+	  log.Fatal(err)
+  }
+
+  var def *uaparser.RegexesDefinitions
+
+  if err := yaml.Unmarshal(regexes, def); err != nil {
+    fmt.Printf("error parsing regexes definitions. Error: %s\n", err.Error())
+    return
+  }
+  
+  parser, err := uaparser.New(uaparser.WithRegexesDefinitions(def))
   if err != nil {
     log.Fatal(err)
   }

test.go

@@ -9,19 +9,41 @@ import (
 	"time"
 
 	"github.com/ua-parser/uap-go/uaparser"
+	"gopkg.in/yaml.v3"
 )
 
 func main() {
 	if len(os.Args) < 3 {
 		fmt.Printf("Usage: %s [old|new|both] [concurrency level]\n", os.Args[0])
 		return
 	}
+
+	regexes, err := os.ReadFile("./uap-core/regexes.yaml")
+	if err != nil {
+		fmt.Printf("Failed to read regexes file. Error: %s\n", err.Error())
+		return
+	}
+
+	var def uaparser.RegexDefinitions
+
+	if err := yaml.Unmarshal(regexes, &def); err != nil {
+		fmt.Printf("error parsing regexes definitions. Error: %s\n", err.Error())
+		return
+	}
+
 	var wg sync.WaitGroup
 	cLevel, _ := strconv.Atoi(os.Args[2])
 	switch os.Args[1] {
 	case "new":
 		fmt.Println("Running new version of uap...")
-		uaParser, _ := uaparser.NewWithOptions("./uap-core/regexes.yaml", (uaparser.EOsLookUpMode | uaparser.EUserAgentLookUpMode), 100, 20, true, true, 1024)
+		uaParser, _ := uaparser.New(
+			uaparser.WithRegexDefinitions(def),
+			uaparser.WithMode(uaparser.EOsLookUpMode|uaparser.EUserAgentLookUpMode),
+			uaparser.WithMatchIdxNotOk(20),
+			uaparser.WithSort(true, uaparser.WithMissesThreshold(100)),
+			uaparser.WithDebug(true),
+			uaparser.WithCacheSize(1024),
+		)
 		for i := 0; i < cLevel; i++ {
 			wg.Add(1)
 			go runTest(uaParser, i, &wg)
@@ -30,7 +52,7 @@ func main() {
 		return
 	case "old":
 		fmt.Println("Running old version of uap...")
-		uaParser, _ := uaparser.New("./uap-core/regexes.yaml")
+		uaParser, _ := uaparser.New(uaparser.WithRegexDefinitions(def))
 		for i := 0; i < cLevel; i++ {
 			wg.Add(1)
 			go runTest(uaParser, i, &wg)
@@ -39,13 +61,20 @@ func main() {
 		return
 	case "both":
 		fmt.Println("Running new version of uap...")
-		uaParser, _ := uaparser.NewWithOptions("./uap-core/regexes.yaml", (uaparser.EOsLookUpMode | uaparser.EUserAgentLookUpMode), 100, 20, true, true, 1024)
+		uaParser, _ := uaparser.New(
+			uaparser.WithRegexDefinitions(def),
+			uaparser.WithMode(uaparser.EOsLookUpMode|uaparser.EUserAgentLookUpMode),
+			uaparser.WithMatchIdxNotOk(20),
+			uaparser.WithSort(true, uaparser.WithMissesThreshold(100)),
+			uaparser.WithDebug(true),
+			uaparser.WithCacheSize(1024),
+		)
 		for i := 0; i < cLevel; i++ {
 			wg.Add(1)
 			runTest(uaParser, i, &wg)
 		}
 		fmt.Println("Running old version of uap...")
-		uaParser, _ = uaparser.New("./uap-core/regexes.yaml")
+		uaParser, _ = uaparser.New(uaparser.WithRegexDefinitions(def))
 		for i := 0; i < cLevel; i++ {
 			wg.Add(1)
 			runTest(uaParser, i, &wg)

uaparser/benchmark_test.go

@@ -7,6 +7,8 @@ import (
 	"os"
 	"strings"
 	"testing"
+
+	"gopkg.in/yaml.v3"
 )
 
 var benchedParser *Parser
@@ -15,11 +17,30 @@ var largeUasSample []string
 
 func init() {
 	var err error
-	benchedParser, err = New("../uap-core/regexes.yaml")
+
+	regexes, err := os.ReadFile("../uap-core/regexes.yaml")
 	if err != nil {
 		log.Fatal(err)
 	}
-	benchedParserWithOptions, err = NewWithOptions("../uap-core/regexes.yaml", (EOsLookUpMode | EUserAgentLookUpMode), 100, 20, true, true, cDefaultCacheSize)
+
+	var def RegexDefinitions
+
+	if err := yaml.Unmarshal(regexes, &def); err != nil {
+		log.Fatal(err)
+	}
+
+	benchedParser, err = New(WithRegexDefinitions(def))
+	if err != nil {
+		log.Fatal(err)
+	}
+	benchedParserWithOptions, err = New(WithRegexDefinitions(def),
+		WithMode(EOsLookUpMode|EUserAgentLookUpMode),
+		WithMatchIdxNotOk(20),
+		WithSort(true, WithMissesThreshold(100)),
+		WithDebug(true),
+		WithCacheSize(cDefaultCacheSize),
+	)
+
 	if err != nil {
 		log.Fatal(err)
 	}
@@ -48,17 +69,27 @@ func BenchmarkParserWithOptions(b *testing.B) {
 }
 
 func BenchmarkParserWithDifferentCacheSize(b *testing.B) {
-	sizes := []int{cDefaultCacheSize, cDefaultCacheSize*2, cDefaultCacheSize*3, cDefaultCacheSize*4}
+	sizes := []int{cDefaultCacheSize, cDefaultCacheSize * 2, cDefaultCacheSize * 3, cDefaultCacheSize * 4}
+
+	regexes, err := os.ReadFile("../uap-core/regexes.yaml")
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	var def RegexDefinitions
+
+	if err := yaml.Unmarshal(regexes, &def); err != nil {
+		log.Fatal(err)
+	}
 
 	for _, size := range sizes {
-		parser, err := NewWithOptions(
-			"../uap-core/regexes.yaml",
-			EOsLookUpMode | EUserAgentLookUpMode | EDeviceLookUpMode,
-			cDefaultMissesTreshold,
-			cDefaultMatchIdxNotOk,
-			false,
-			false,
-			size)
+		parser, err := New(WithRegexDefinitions(def),
+			WithMode(EOsLookUpMode|EUserAgentLookUpMode|EDeviceLookUpMode),
+			WithMatchIdxNotOk(cDefaultMatchIdxNotOk),
+			WithSort(false, WithMissesThreshold(cDefaultMissesTreshold)),
+			WithDebug(false),
+			WithCacheSize(size),
+		)
 		if err != nil {
 			log.Fatal(err)
 		}

uaparser/deprecated.go

@@ -0,0 +1,56 @@
+package uaparser
+
+import (
+	"os"
+
+	"gopkg.in/yaml.v3"
+)
+
+// NewWithOptions is deprecated.
+// Deprecated: Use New and option functions instead.
+func NewWithOptions(regexFile string, mode, treshold, topCnt int, useSort, debugMode bool, cacheSize int) (*Parser, error) {
+	uaRegexes, err := os.ReadFile(regexFile)
+	if err != nil {
+		return nil, err
+	}
+
+	var def RegexDefinitions
+
+	if err := yaml.Unmarshal(uaRegexes, &def); err != nil {
+		return nil, err
+	}
+
+	return New(
+		WithRegexDefinitions(def),
+		WithMode(LookupMode(mode)),
+		WithMatchIdxNotOk(topCnt),
+		WithSort(useSort, WithMissesThreshold(uint64(treshold))),
+		WithDebug(debugMode),
+		WithCacheSize(cacheSize),
+	)
+}
+
+// NewFromSaved is deprecated.
+// Deprecated: Use New() instead.
+func NewFromSaved() *Parser {
+	parser, err := New()
+	if err != nil {
+		// if the YAML is malformed, it's a programmatic error inside what
+		// we've statically-compiled in our binary. Panic!
+		panic(err.Error())
+	}
+
+	return parser
+}
+
+// NewFromBytes is deprecated.
+// Deprecated: Use New(WithRegexDefinitions(...)) instead
+func NewFromBytes(data []byte) (*Parser, error) {
+	var def RegexDefinitions
+
+	if err := yaml.Unmarshal(data, &def); err != nil {
+		return nil, err
+	}
+
+	return New(WithRegexDefinitions(def))
+}

uaparser/device.go

@@ -8,20 +8,20 @@ type Device struct {
 	Model  string
 }
 
-func (parser *deviceParser) Match(line string, dvc *Device) {
-	matches := parser.Reg.FindStringSubmatchIndex(line)
+func (dp *deviceParser) Match(line string, dvc *Device) {
+	matches := dp.Reg.FindStringSubmatchIndex(line)
 
 	if len(matches) == 0 {
 		return
 	}
 
-	dvc.Family = string(parser.Reg.ExpandString(nil, parser.DeviceReplacement, line, matches))
+	dvc.Family = string(dp.Reg.ExpandString(nil, dp.DeviceReplacement, line, matches))
 	dvc.Family = strings.TrimSpace(dvc.Family)
 
-	dvc.Brand = string(parser.Reg.ExpandString(nil, parser.BrandReplacement, line, matches))
+	dvc.Brand = string(dp.Reg.ExpandString(nil, dp.BrandReplacement, line, matches))
 	dvc.Brand = strings.TrimSpace(dvc.Brand)
 
-	dvc.Model = string(parser.Reg.ExpandString(nil, parser.ModelReplacement, line, matches))
+	dvc.Model = string(dp.Reg.ExpandString(nil, dp.ModelReplacement, line, matches))
 	dvc.Model = strings.TrimSpace(dvc.Model)
 }
 

uaparser/options.go

@@ -0,0 +1,51 @@
+package uaparser
+
+type Option func(*Parser)
+
+func WithMode(mode LookupMode) Option {
+	return func(s *Parser) {
+		s.config.Mode = mode
+	}
+}
+
+func WithSort(useSort bool, options ...SortOption) Option {
+	return func(s *Parser) {
+		s.config.UseSort = useSort
+
+		for _, o := range options {
+			o(s)
+		}
+	}
+}
+
+func WithDebug(debug bool) Option {
+	return func(s *Parser) {
+		s.config.DebugMode = debug
+	}
+}
+
+func WithCacheSize(size int) Option {
+	return func(s *Parser) {
+		s.config.CacheSize = size
+	}
+}
+
+func WithMatchIdxNotOk(idx int) Option {
+	return func(s *Parser) {
+		s.config.MatchIdxNotOk = idx
+	}
+}
+
+func WithRegexDefinitions(def RegexDefinitions) Option {
+	return func(s *Parser) {
+		s.RegexDefinitions = &def
+	}
+}
+
+type SortOption func(*Parser)
+
+func WithMissesThreshold(threshold uint64) SortOption {
+	return func(s *Parser) {
+		s.config.MissesThreshold = threshold
+	}
+}

uaparser/os.go

@@ -8,14 +8,14 @@ type Os struct {
 	PatchMinor string `yaml:"patch_minor"`
 }
 
-func (parser *osParser) Match(line string, os *Os) {
-	matches := parser.Reg.FindStringSubmatchIndex(line)
+func (osp *osParser) Match(line string, os *Os) {
+	matches := osp.Reg.FindStringSubmatchIndex(line)
 	if len(matches) > 0 {
-		os.Family = string(parser.Reg.ExpandString(nil, parser.OSReplacement, line, matches))
-		os.Major = string(parser.Reg.ExpandString(nil, parser.V1Replacement, line, matches))
-		os.Minor = string(parser.Reg.ExpandString(nil, parser.V2Replacement, line, matches))
-		os.Patch = string(parser.Reg.ExpandString(nil, parser.V3Replacement, line, matches))
-		os.PatchMinor = string(parser.Reg.ExpandString(nil, parser.V4Replacement, line, matches))
+		os.Family = string(osp.Reg.ExpandString(nil, osp.OSReplacement, line, matches))
+		os.Major = string(osp.Reg.ExpandString(nil, osp.V1Replacement, line, matches))
+		os.Minor = string(osp.Reg.ExpandString(nil, osp.V2Replacement, line, matches))
+		os.Patch = string(osp.Reg.ExpandString(nil, osp.V3Replacement, line, matches))
+		os.PatchMinor = string(osp.Reg.ExpandString(nil, osp.V4Replacement, line, matches))
 	}
 }