add Parse() & ParseFile() utility funcs

Author: markus-wa

README.md

@@ -80,39 +80,32 @@ Check out the [godoc of the `events` package](https://godoc.org/github.com/marku
 package main
 
 import (
-	"fmt"
 	"log"
-	"os"
 
-	dem "github.com/markus-wa/demoinfocs-golang/v5/pkg/demoinfocs"
+	demoinfocs "github.com/markus-wa/demoinfocs-golang/v5/pkg/demoinfocs"
 	events "github.com/markus-wa/demoinfocs-golang/v5/pkg/demoinfocs/events"
 )
 
 func main() {
-	f, err := os.Open("/path/to/demo.dem")
-	if err != nil {
-		log.Panic("failed to open demo file: ", err)
-	}
-	defer f.Close()
-
-	p := dem.NewParser(f)
-	defer p.Close()
-
-	// Register handler on kill events
-	p.RegisterEventHandler(func(e events.Kill) {
+	onKill := func(kill events.Kill) {
 		var hs string
-		if e.IsHeadshot {
+		if kill.IsHeadshot {
 			hs = " (HS)"
 		}
+
 		var wallBang string
-		if e.PenetratedObjects > 0 {
+		if kill.PenetratedObjects > 0 {
 			wallBang = " (WB)"
 		}
-		fmt.Printf("%s <%v%s%s> %s\n", e.Killer, e.Weapon, hs, wallBang, e.Victim)
-	})
 
-	// Parse to end
-	err = p.ParseToEnd()
+		log.Printf("%s <%v%s%s> %s\n", kill.Killer, kill.Weapon, hs, wallBang, kill.Victim)
+	}
+
+	err := demoinfocs.ParseFile("/path/to/demo.dem", func(p demoinfocs.Parser) error {
+		p.RegisterEventHandler(onKill)
+
+		return nil
+	})
 	if err != nil {
 		log.Panic("failed to parse demo: ", err)
 	}

pkg/demoinfocs/examples_test.go

@@ -1,9 +1,7 @@
 package demoinfocs_test
 
 import (
-	"fmt"
 	"log"
-	"os"
 	"testing"
 
 	demoinfocs "github.com/markus-wa/demoinfocs-golang/v5/pkg/demoinfocs"
@@ -15,33 +13,25 @@ This will print all kills of a demo in the format '[[killer]] <[[weapon]] [(HS)]
 */
 //noinspection GoUnhandledErrorResult
 func ExampleParser() {
-	f, err := os.Open("../../test/cs-demos/s2/s2.dem")
-	if err != nil {
-		log.Panic("failed to open demo file: ", err)
-	}
-
-	defer f.Close()
-
-	p := demoinfocs.NewParser(f)
-	defer p.Close()
-
-	// Register handler on kill events
-	p.RegisterEventHandler(func(e events.Kill) {
+	onKill := func(kill events.Kill) {
 		var hs string
-		if e.IsHeadshot {
+		if kill.IsHeadshot {
 			hs = " (HS)"
 		}
 
 		var wallBang string
-		if e.PenetratedObjects > 0 {
+		if kill.PenetratedObjects > 0 {
 			wallBang = " (WB)"
 		}
 
-		fmt.Printf("%s <%v%s%s> %s\n", e.Killer, e.Weapon, hs, wallBang, e.Victim)
-	})
+		log.Printf("%s <%v%s%s> %s\n", kill.Killer, kill.Weapon, hs, wallBang, kill.Victim)
+	}
 
-	// Parse to end
-	err = p.ParseToEnd()
+	err := demoinfocs.ParseFile("../../test/cs-demos/s2/s2.dem", func(p demoinfocs.Parser) error {
+		p.RegisterEventHandler(onKill)
+
+		return nil
+	})
 	if err != nil {
 		log.Panic("failed to parse demo: ", err)
 	}

pkg/demoinfocs/parser.go

@@ -4,6 +4,7 @@ import (
 	_ "embed"
 	"fmt"
 	"io"
+	"os"
 	"runtime/debug"
 	"sync"
 	"time"
@@ -350,6 +351,60 @@ func NewCSTVBroadcastParserWithConfig(baseUrl string, config ParserConfig) (Pars
 	return NewParserWithConfig(r, config), nil
 }
 
+type ConfigureParserCallback func(Parser) error
+
+// ParseWithConfig parses a demo from the given io.Reader with a custom configuration.
+// The handler is called with the Parser instance.
+//
+// Returns an error if the parser encounters an error.
+func ParseWithConfig(r io.Reader, config ParserConfig, configure ConfigureParserCallback) error {
+	p := NewParserWithConfig(r, config)
+	defer p.Close()
+
+	err := configure(p)
+	if err != nil {
+		return fmt.Errorf("failed to configure parser: %w", err)
+	}
+
+	err = p.ParseToEnd()
+	if err != nil {
+		return fmt.Errorf("failed to parse demo: %w", err)
+	}
+
+	return nil
+}
+
+// Parse parses a demo from the given io.Reader.
+// The handler is called with the Parser instance.
+//
+// Returns an error if the parser encounters an error.
+func Parse(r io.Reader, configure ConfigureParserCallback) error {
+	return ParseWithConfig(r, DefaultParserConfig, configure)
+}
+
+// ParseFileWithConfig parses a demo file at the given path with a custom configuration.
+// The handler is called with the Parser instance.
+//
+// Returns an error if the file can't be opened or if the parser encounters an error.
+func ParseFileWithConfig(path string, config ParserConfig, configure ConfigureParserCallback) error {
+	f, err := os.Open(path)
+	if err != nil {
+		return fmt.Errorf("failed to open file: %w", err)
+	}
+
+	defer f.Close()
+
+	return ParseWithConfig(f, config, configure)
+}
+
+// ParseFile parses a demo file at the given path.
+// The handler is called with the Parser instance.
+//
+// Returns an error if the file can't be opened or if the parser encounters an error.
+func ParseFile(path string, configure ConfigureParserCallback) error {
+	return ParseFileWithConfig(path, DefaultParserConfig, configure)
+}
+
 // ParserConfig contains the configuration for creating a new Parser.
 type ParserConfig struct {
 	// MsgQueueBufferSize defines the size of the internal net-message queue.