improve examples

flier · flier · Apr 11, 2022 · Sep 23, 2021 · Sep 23, 2021 · Sep 23, 2021
commit 47d50184998a97baffc91bc6a3772a9b7a8baf50
diff --git a/chimera/block.go b/chimera/block.go
@@ -116,7 +116,7 @@ func (m *blockMatcher) OnMatch(id uint, from, to uint64, flags uint,
 		return Continue
 	}
 
-	if m.n < len(m.Events) {
+	if m.n <= len(m.Events) {
 		m.Events = m.Events[:m.n]
 
 		return Terminate

diff --git a/chimera/common.go b/chimera/common.go
@@ -37,14 +37,9 @@ const (
 	ErrScratchInUse Error = ch.ErrScratchInUse
 )
 
-// ModeFlag represents the compile mode flags.
-type ModeFlag = hyperscan.ModeFlag
-
-// BlockMode for the block scan (non-streaming) database.
-const BlockMode = hyperscan.BlockMode
-
 // DbInfo identify the version and platform information for the supplied database.
-type DbInfo string // nolint: stylecheck
+// nolint: stylecheck
+type DbInfo string
 
 // parse `Chimera Version: 5.4.0 Features: AVX2 Mode: BLOCK`.
 var regexDBInfo = regexp.MustCompile(`^Chimera Version: (\d+\.\d+\.\d+) Features: ([\w\s]+)? Mode: (\w+)$`)
@@ -76,7 +71,7 @@ func (i DbInfo) Version() (string, error) {
 }
 
 // Mode is the scanning mode for the supplied database.
-func (i DbInfo) Mode() (ModeFlag, error) {
+func (i DbInfo) Mode() (hyperscan.ModeFlag, error) {
 	_, _, mode, err := i.Parse()
 	if err != nil {
 		return 0, err
@@ -85,7 +80,7 @@ func (i DbInfo) Mode() (ModeFlag, error) {
 	return hyperscan.ParseModeFlag(mode) // nolint: wrapcheck
 }
 
-// Database is an immutable database that can be used by the Hyperscan scanning API.
+// Database is an immutable database that can be used by the Chimera scanning API.
 type Database interface {
 	// Provides information about a database.
 	Info() (DbInfo, error)

diff --git a/chimera/common_test.go b/chimera/common_test.go
@@ -6,6 +6,7 @@ import (
 	. "github.com/smartystreets/goconvey/convey"
 
 	"github.com/flier/gohs/chimera"
+	"github.com/flier/gohs/hyperscan"
 )
 
 func TestChimera(t *testing.T) {
@@ -16,7 +17,7 @@ func TestChimera(t *testing.T) {
 
 func TestBaseDatabase(t *testing.T) {
 	Convey("Given a block database", t, func() {
-		So(chimera.ValidPlatform(), ShouldBeNil)
+		So(hyperscan.ValidPlatform(), ShouldBeNil)
 
 		bdb, err := chimera.NewBlockDatabase(&chimera.Pattern{Expression: "test"})
 
@@ -50,7 +51,7 @@ func TestBaseDatabase(t *testing.T) {
 				mode, err := info.Mode()
 
 				So(err, ShouldBeNil)
-				So(mode, ShouldEqual, chimera.BlockMode)
+				So(mode, ShouldEqual, hyperscan.BlockMode)
 			})
 		})
 
@@ -78,7 +79,7 @@ func TestBlockDatabase(t *testing.T) {
 				mode, err := info.Mode()
 
 				So(err, ShouldBeNil)
-				So(mode, ShouldEqual, chimera.BlockMode)
+				So(mode, ShouldEqual, hyperscan.BlockMode)
 			})
 		})
 

diff --git a/chimera/compile.go b/chimera/compile.go
@@ -5,6 +5,7 @@ import (
 	"runtime"
 	"strconv"
 
+	"github.com/flier/gohs/hyperscan"
 	"github.com/flier/gohs/internal/ch"
 	"github.com/flier/gohs/internal/hs"
 )
@@ -67,31 +68,38 @@ const (
 	Groups CompileMode = ch.Groups
 )
 
+// Builder creates a database with the given mode and target platform.
 type Builder interface {
+	// Build the database with the given mode.
 	Build(mode CompileMode) (Database, error)
 
-	ForPlatform(mode CompileMode, platform Platform) (Database, error)
+	// ForPlatform determine the target platform for the database
+	ForPlatform(mode CompileMode, platform hyperscan.Platform) (Database, error)
 }
 
+// Build the database with the given mode.
 func (p *Pattern) Build(mode CompileMode) (Database, error) {
 	return p.ForPlatform(mode, nil)
 }
 
-func (p *Pattern) ForPlatform(mode CompileMode, platform Platform) (Database, error) {
+// ForPlatform determine the target platform for the database.
+func (p *Pattern) ForPlatform(mode CompileMode, platform hyperscan.Platform) (Database, error) {
 	b := DatabaseBuilder{Patterns: Patterns{p}, Mode: mode, Platform: platform}
 	return b.Build()
 }
 
+// Build the database with the given mode.
 func (p Patterns) Build(mode CompileMode) (Database, error) {
 	return p.ForPlatform(mode, nil)
 }
 
-func (p Patterns) ForPlatform(mode CompileMode, platform Platform) (Database, error) {
+// ForPlatform determine the target platform for the database.
+func (p Patterns) ForPlatform(mode CompileMode, platform hyperscan.Platform) (Database, error) {
 	b := DatabaseBuilder{Patterns: p, Mode: mode, Platform: platform}
 	return b.Build()
 }
 
-// DatabaseBuilder to help to build up a database.
+// DatabaseBuilder creates a database that will be used to matching the patterns.
 type DatabaseBuilder struct {
 	// Array of patterns to compile.
 	Patterns
@@ -101,7 +109,7 @@ type DatabaseBuilder struct {
 
 	// If not nil, the platform structure is used to determine the target platform for the database.
 	// If nil, a database suitable for running on the current host platform is produced.
-	Platform
+	hyperscan.Platform
 
 	// A limit from pcre_extra on the amount of match function called in PCRE to limit backtracking that can take place.
 	MatchLimit uint

diff --git a/chimera/compile_test.go b/chimera/compile_test.go
@@ -65,7 +65,7 @@ func TestDatabaseBuilder(t *testing.T) {
 			mode, err := info.Mode()
 
 			So(err, ShouldBeNil)
-			So(mode, ShouldEqual, chimera.BlockMode)
+			So(mode, ShouldEqual, hyperscan.BlockMode)
 
 			So(db.Close(), ShouldBeNil)
 		})

diff --git a/chimera/example_runtime_test.go b/chimera/example_runtime_test.go
@@ -40,7 +40,7 @@ func ExampleBlockScanner() {
 
 	var matches []Match
 
-	handler := chimera.MatchHandlerFunc(func(id uint, from, to uint64, flags uint,
+	handler := chimera.HandlerFunc(func(id uint, from, to uint64, flags uint,
 		captured []*chimera.Capture, ctx interface{}) chimera.Callback {
 		matches = append(matches, Match{from, to})
 		return chimera.Continue

diff --git a/chimera/runtime.go b/chimera/runtime.go
@@ -1,16 +1,9 @@
 package chimera
 
 import (
-	"github.com/flier/gohs/hyperscan"
 	"github.com/flier/gohs/internal/ch"
 )
 
-// Platform is a type containing information on the target platform.
-type Platform = hyperscan.Platform
-
-// ValidPlatform test the current system architecture.
-var ValidPlatform = hyperscan.ValidPlatform
-
 // Callback return value used to tell the Chimera matcher what to do after processing this match.
 type Callback = ch.Callback
 
@@ -43,12 +36,17 @@ type Handler interface {
 	OnError(event ErrorEvent, id uint, info, context interface{}) Callback
 }
 
-type MatchHandlerFunc func(id uint, from, to uint64, flags uint, captured []*Capture, context interface{}) Callback
+// HandlerFunc type is an adapter to allow the use of ordinary functions as Chimera handlers.
+// If f is a function with the appropriate signature, HandlerFunc(f) is a Handler that calls f.
+type HandlerFunc func(id uint, from, to uint64, flags uint, captured []*Capture, context interface{}) Callback
 
-func (f MatchHandlerFunc) OnMatch(id uint, from, to uint64, flags uint, captured []*Capture, ctx interface{}) Callback {
+// OnMatch will be invoked whenever a match is located in the target data during the execution of a scan.
+func (f HandlerFunc) OnMatch(id uint, from, to uint64, flags uint, captured []*Capture, ctx interface{}) Callback {
 	return f(id, from, to, flags, captured, ctx)
 }
 
-func (f MatchHandlerFunc) OnError(event ErrorEvent, id uint, info, context interface{}) Callback {
+// OnError will be invoked when an error event occurs during matching;
+// this indicates that some matches for a given expression may not be reported.
+func (f HandlerFunc) OnError(event ErrorEvent, id uint, info, context interface{}) Callback {
 	return Terminate
 }
diff --git a/chimera/runtime_test.go b/chimera/runtime_test.go
@@ -35,7 +35,7 @@ func TestBlockScanner(t *testing.T) {
 					return chimera.Continue
 				}
 
-				err = bdb.Scan([]byte("abc123def456"), nil, chimera.MatchHandlerFunc(matched), nil)
+				err = bdb.Scan([]byte("abc123def456"), nil, chimera.HandlerFunc(matched), nil)
 
 				So(err, ShouldBeNil)
 				So(matches, ShouldResemble, [][]uint64{{3, 6}, {9, 12}})

diff --git a/examples/pcapscan/main.go b/examples/pcapscan/main.go
@@ -33,6 +33,7 @@ import (
 	"io/ioutil"
 	"net"
 	"os"
+	"path/filepath"
 	"runtime/pprof"
 	"strconv"
 	"strings"
@@ -412,7 +413,8 @@ func main() {
 	flag.Parse()
 
 	if flag.NArg() != 2 {
-		fmt.Fprintf(os.Stderr, "Usage: %s [-n repeats] <pattern file> <pcap file>\n", os.Args[0])
+		_, prog := filepath.Split(os.Args[0])
+		fmt.Fprintf(os.Stderr, "Usage: %s [-n repeats] <pattern file> <pcap file>\n", prog)
 		os.Exit(-1)
 	}