feat(opts): marshal options (#191)

.github/workflows/ci-workflow.yml

@@ -43,7 +43,7 @@ jobs:
         run: go install github.com/mattn/goveralls@latest
 
       - name: Install ginkgo
-        run: go install github.com/onsi/ginkgo/v2/[email protected].0
+        run: go install github.com/onsi/ginkgo/v2/[email protected].2
 
       - name: Checkout code
         uses: actions/checkout@v4

.gitignore

@@ -22,6 +22,7 @@ report.json
 coverage.html
 
 .task/
+test/json/marshal/
 
 i18n/out/en-US/active.en-GB.json
 

.vscode/settings.json

@@ -25,6 +25,7 @@
     "dogsled",
     "dotenv",
     "dupl",
+    "ejson",
     "ents",
     "Ephidrina",
     "errcheck",
@@ -59,7 +60,9 @@
     "icase",
     "ineffassign",
     "Innerworld",
+    "jdef",
     "jibberjabber",
+    "jroot",
     "Kontroller",
     "leaktest",
     "linecomment",
@@ -107,12 +110,15 @@
     "thelper",
     "toplevel",
     "tparallel",
+    "tpers",
+    "tpref",
     "trimprefix",
     "tsys",
     "Turan",
     "typecheck",
     "unconvert",
     "unlambda",
+    "Unmarshall",
     "unparam",
     "usys",
     "vals",

Taskfile.yml

@@ -100,10 +100,14 @@ tasks:
     cmds:
       - go test ./collections
 
-  tp:
+  tpref:
     cmds:
       - go test ./pref
 
+  tpers:
+    cmds:
+      - go test ./internal/persist
+
   tt:
     cmds:
       - go test

director.go

@@ -99,7 +99,7 @@ func Prime(using *pref.Using, settings ...pref.Option) *Builders {
 			ve := using.Validate()
 
 			if using.O != nil {
-				return using.O, opts.GetWith(using.O), ve
+				return using.O, opts.Push(using.O), ve
 			}
 
 			o, binder, err := ext.options(settings...)

internal/laboratory/traverse-fs.go

@@ -1,45 +1,87 @@
 package lab
 
 import (
+	"io/fs"
 	"os"
+	"strings"
 	"testing/fstest"
+
+	"github.com/snivilised/traverse/internal/third/lo"
+	"github.com/snivilised/traverse/locale"
+)
+
+const (
+	permFile = 0o666
 )
 
+type testMapFile struct {
+	f fstest.MapFile
+}
+
 type TestTraverseFS struct {
 	fstest.MapFS
 }
 
-func (f *TestTraverseFS) FileExists(path string) bool {
-	if mapFile, found := f.MapFS[path]; found && !mapFile.Mode.IsDir() {
+func (f *TestTraverseFS) FileExists(name string) bool {
+	if mapFile, found := f.MapFS[name]; found && !mapFile.Mode.IsDir() {
 		return true
 	}
 
 	return false
 }
 
-func (f *TestTraverseFS) DirectoryExists(path string) bool {
-	if mapFile, found := f.MapFS[path]; found && mapFile.Mode.IsDir() {
+func (f *TestTraverseFS) DirectoryExists(name string) bool {
+	if mapFile, found := f.MapFS[name]; found && mapFile.Mode.IsDir() {
 		return true
 	}
 
 	return false
 }
 
 func (f *TestTraverseFS) Create(name string) (*os.File, error) {
-	_ = name
-	panic("NOT-IMPL: TestTraverseFS.Create")
+	if _, err := f.Stat(name); err == nil {
+		return nil, fs.ErrExist
+	}
+
+	file := &fstest.MapFile{
+		Mode: permFile,
+	}
+
+	f.MapFS[name] = file
+	dummy := &os.File{}
+	return dummy, nil
 }
 
-func (f *TestTraverseFS) MkDirAll(path string, perm os.FileMode) error {
-	_ = path
-	_ = perm
-	panic("NOT-IMPL: TestTraverseFS.MkDirAll")
+func (f *TestTraverseFS) MkDirAll(name string, perm os.FileMode) error {
+	if !fs.ValidPath(name) {
+		return locale.NewInvalidPathError(name)
+	}
+
+	segments := strings.Split(name, "/")
+
+	_ = lo.Reduce(segments,
+		func(acc []string, s string, _ int) []string {
+			acc = append(acc, s)
+			path := strings.Join(acc, "/")
+			f.MapFS[path] = &fstest.MapFile{
+				Mode: perm | os.ModeDir,
+			}
+			return acc
+		}, []string{},
+	)
+
+	return nil
 }
 
 func (f *TestTraverseFS) WriteFile(name string, data []byte, perm os.FileMode) error {
-	_ = name
-	_ = data
-	_ = perm
+	if _, err := f.Stat(name); err == nil {
+		return fs.ErrExist
+	}
+
+	f.MapFS[name] = &fstest.MapFile{
+		Data: data,
+		Mode: perm,
+	}
 
-	panic("NOT-IMPL: TestTraverseFS.WriteFile")
+	return nil
 }

internal/opts/get.go → internal/opts/get-push.go

@@ -29,7 +29,7 @@ func apply(o *pref.Options, settings ...pref.Option) (err error) {
 	return err
 }
 
-func GetWith(o *pref.Options) *Binder {
+func Push(o *pref.Options) *Binder {
 	binder := NewBinder()
 	o.Events.Bind(&binder.Controls)
 

internal/opts/json/concurrency-options.go

@@ -0,0 +1,15 @@
+package json
+
+// TODO: can't have package name that is json as that clashes
+// with the one in standard library at encoding/json, so need
+// to rename; perhaps to js.
+
+type (
+	// ConcurrencyOptions specifies options used for current traversal sessions
+	ConcurrencyOptions struct {
+		// NoW specifies the number of go-routines to use in the worker
+		// pool used for concurrent traversal sessions requested by using
+		// the Run function.
+		NoW uint `json:"no-of-workers"`
+	}
+)

internal/opts/json/filter-options.go

@@ -0,0 +1,94 @@
+package json
+
+import (
+	"github.com/snivilised/traverse/enums"
+)
+
+type (
+	PolyFilterDef struct {
+		File   FilterDef
+		Folder FilterDef
+	}
+
+	FilterDef struct {
+		// Type specifies the type of filter (mandatory)
+		Type enums.FilterType `json:"filter-type"`
+
+		// Description describes filter (optional)
+		Description string `json:"filter-description"`
+
+		// Pattern filter definition (mandatory)
+		Pattern string `json:"pattern"`
+
+		// Scope which file system entries this filter applies to (defaults
+		// to ScopeAllEn)
+		Scope enums.FilterScope `json:"filter-scope"`
+
+		// Negate, reverses the applicability of the filter (Defaults to false)
+		Negate bool `json:"negate"`
+
+		// IfNotApplicable, when the filter does not apply to a directory entry,
+		// this value determines whether the callback is invoked for this entry
+		// or not (defaults to true).
+		IfNotApplicable enums.TriStateBool `json:"if-not-applicable"`
+
+		// Poly allows for the definition of a PolyFilter which contains separate
+		// filters that target files and folders separately. If present, then
+		// all other fields are redundant, since the filter definitions inside
+		// Poly should be referred to instead.
+		Poly *PolyFilterDef
+	}
+
+	ChildFilterDef struct {
+		// Type specifies the type of filter (mandatory)
+		Type enums.FilterType `json:"child-filter-type"`
+
+		// Description describes filter (optional)
+		Description string `json:"child-filter-description"`
+
+		// Pattern filter definition (mandatory)
+		Pattern string `json:"child-pattern"`
+
+		// Negate, reverses the applicability of the filter (Defaults to false)
+		Negate bool `json:"negate"`
+	}
+
+	SampleFilterDef struct {
+		// Type specifies the type of filter (mandatory)
+		Type enums.FilterType `json:"sample-filter-type"`
+
+		// Description describes filter (optional)
+		Description string `json:"sample-description"`
+
+		// Pattern filter definition (mandatory except if using Custom)
+		Pattern string `json:"sample-filter"`
+
+		// Scope which file system entries this filter applies to;
+		// for sampling, only ScopeFile and ScopeFolder are valid.
+		Scope enums.FilterScope `json:"sample-filter-scope"`
+
+		// Negate, reverses the applicability of the filter (Defaults to false)
+		Negate bool `json:"negate"`
+
+		// Poly allows for the definition of a PolyFilter which contains separate
+		// filters that target files and folders separately. If present, then
+		// all other fields are redundant, since the filter definitions inside
+		// Poly should be referred to instead.
+		Poly *PolyFilterDef
+	}
+
+	FilterOptions struct {
+		// Node filter definitions that applies to the current file system node
+		//
+		Node *FilterDef
+
+		// Child denotes the Child filter that is applied to the files which
+		// are direct descendants of the current directory node being visited.
+		//
+		Child *ChildFilterDef
+
+		// Sample is the filter used for sampling
+		//
+		Sample *SampleFilterDef
+	}
+)

internal/opts/json/hibernate-options.go

@@ -0,0 +1,34 @@
+package json
+
+import "fmt"
+
+type (
+	// HibernationBehaviour
+	HibernationBehaviour struct {
+		// InclusiveWake when wake occurs, permit client callback to
+		// be invoked for the current node. Inclusive, true by default
+		InclusiveWake bool `json:"hibernate-inclusive-wake"`
+
+		// InclusiveSleep when sleep occurs, permit client callback to
+		// be invoked for the current node. Exclusive, false by default.
+		InclusiveSleep bool `json:"hibernate-inclusive-sleep"`
+	}
+
+	// HibernateOptions
+	HibernateOptions struct {
+		// WakeAt defines a filter for hibernation wake condition
+		WakeAt *FilterDef
+
+		// SleepAt defines a filter for hibernation sleep condition
+		SleepAt *FilterDef
+
+		// Behaviour contains hibernation behavioural aspects
+		Behaviour HibernationBehaviour
+	}
+)
+
+func (b *HibernationBehaviour) String() string {
+	return fmt.Sprintf("[HibernationBehaviour] inclusive wake: %v, inclusive sleep: %v",
+		b.InclusiveWake, b.InclusiveSleep,
+	)
+}

internal/opts/json/navigation-behaviours.go

@@ -0,0 +1,47 @@
+package json
+
+type (
+	SubPathBehaviour struct {
+		KeepTrailingSep bool
+	}
+
+	SortBehaviour struct {
+		// case sensitive traversal order
+		//
+		IsCaseSensitive bool
+
+		// SortFilesFirst defines whether a folder's files or directories
+		// should be navigated first.
+		//
+		SortFilesFirst bool
+	}
+
+	CascadeBehaviour struct {
+		// Depth sets a maximum traversal depth
+		//
+		Depth uint
+
+		// NoRecurse is an alternative to using Depth, but limits the traversal
+		// to just the path specified by the user. Since the raison d'etre
+		// of the navigator is to recursively process a directory tree, using
+		// NoRecurse would appear to be contrary to its natural behaviour. However
+		// there are clear usage scenarios where a client needs to process
+		// only the files in a specified directory.
+		//
+		NoRecurse bool
+	}
+
+	NavigationBehaviours struct {
+		// SubPath, behaviours relating to handling of sub-path calculation
+		//
+		SubPath SubPathBehaviour
+
+		// Sort, behaviours relating to sorting of a folder's directory entries.
+		//
+		Sort SortBehaviour
+
+		// Cascade controls how deep to navigate
+		//
+		Cascade CascadeBehaviour
+	}
+)