Move "params" from "modules" to "utils" and rename "keyvalue" (#354)

These keyvalue structs act as the interface between amod and actr when setting module params.

.vscode/cspell.json

@@ -33,6 +33,7 @@
     "gosec",
     "Infof",
     "Infoln",
+    "keyvalue",
     "Naur",
     "productionstring",
     "pyactr",

actr/actr.go

@@ -5,8 +5,9 @@ package actr
 import (
 	"github.com/asmaloney/gactar/actr/buffer"
 	"github.com/asmaloney/gactar/actr/modules"
-	"github.com/asmaloney/gactar/actr/params"
+
 	"github.com/asmaloney/gactar/util/container"
+	"github.com/asmaloney/gactar/util/keyvalue"
 )
 
 type Options struct {
@@ -250,13 +251,13 @@ func (model Model) LookupBuffer(bufferName string) buffer.Interface {
 	return nil
 }
 
-func (model *Model) SetParam(param *params.Param) (err error) {
+func (model *Model) SetParam(param *keyvalue.KeyValue) (err error) {
 	value := param.Value
 
 	switch param.Key {
 	case "log_level":
 		if (value.Str == nil) || !ValidLogLevel(*value.Str) {
-			return params.ErrInvalidOption{Expected: ACTRLoggingLevels}
+			return modules.ErrInvalidValue{Expected: ACTRLoggingLevels}
 		}
 
 		model.LogLevel = ACTRLogLevel(*value.Str)
@@ -271,15 +272,15 @@ func (model *Model) SetParam(param *params.Param) (err error) {
 
 	case "random_seed":
 		if value.Number == nil {
-			return params.ErrInvalidType{ExpectedType: params.Number}
+			return keyvalue.ErrInvalidType{ExpectedType: keyvalue.Number}
 		}
 
 		seed := uint32(*value.Number)
 
 		model.RandomSeed = &seed
 
 	default:
-		return params.ErrUnrecognizedParam
+		return modules.ErrUnrecognizedOption{Option: param.Key}
 	}
 
 	return

actr/modules/declarative_memory.go

@@ -7,7 +7,8 @@ import (
 	"golang.org/x/exp/slices"
 
 	"github.com/asmaloney/gactar/actr/buffer"
-	"github.com/asmaloney/gactar/actr/params"
+
+	"github.com/asmaloney/gactar/util/keyvalue"
 )
 
 type RetrievalTimeParams struct {
@@ -209,7 +210,7 @@ func (d DeclarativeMemory) BufferName() string {
 }
 
 // SetParam is called to set our module's parameter from the parameter in the code ("param")
-func (d *DeclarativeMemory) SetParam(param *params.Param) (err error) {
+func (d *DeclarativeMemory) SetParam(param *keyvalue.KeyValue) (err error) {
 	err = d.ValidateParam(param)
 	if err != nil {
 		return

actr/modules/extra_buffers.go

@@ -2,7 +2,8 @@ package modules
 
 import (
 	"github.com/asmaloney/gactar/actr/buffer"
-	"github.com/asmaloney/gactar/actr/params"
+
+	"github.com/asmaloney/gactar/util/keyvalue"
 )
 
 // ExtraBuffers module is used to declare one or more extra goal-style buffers in the model.
@@ -23,7 +24,7 @@ func NewExtraBuffers() *ExtraBuffers {
 }
 
 // SetParam is called to set our module's parameter from the parameter in the code ("param")
-func (eb *ExtraBuffers) SetParam(param *params.Param) (err error) {
+func (eb *ExtraBuffers) SetParam(param *keyvalue.KeyValue) (err error) {
 	newBuffer := goalBuffer{
 		buffer.Buffer{
 			Name: param.Key,

actr/modules/goal.go

@@ -2,7 +2,8 @@ package modules
 
 import (
 	"github.com/asmaloney/gactar/actr/buffer"
-	"github.com/asmaloney/gactar/actr/params"
+
+	"github.com/asmaloney/gactar/util/keyvalue"
 )
 
 // Goal is a module which provides the ACT-R "goal" buffer.
@@ -49,7 +50,7 @@ func NewGoal() *Goal {
 }
 
 // SetParam is called to set our module's parameter from the parameter in the code ("param")
-func (g *Goal) SetParam(param *params.Param) (err error) {
+func (g *Goal) SetParam(param *keyvalue.KeyValue) (err error) {
 	err = g.ValidateParam(param)
 	if err != nil {
 		return

actr/modules/imaginal.go

@@ -2,7 +2,8 @@ package modules
 
 import (
 	"github.com/asmaloney/gactar/actr/buffer"
-	"github.com/asmaloney/gactar/actr/params"
+
+	"github.com/asmaloney/gactar/util/keyvalue"
 )
 
 // Imaginal is a module which provides the ACT-R "imaginal" buffer.
@@ -45,7 +46,7 @@ func NewImaginal() *Imaginal {
 }
 
 // SetParam is called to set our module's parameter from the parameter in the code ("param")
-func (i *Imaginal) SetParam(param *params.Param) (err error) {
+func (i *Imaginal) SetParam(param *keyvalue.KeyValue) (err error) {
 	err = i.ValidateParam(param)
 	if err != nil {
 		return

actr/modules/modules.go

@@ -8,7 +8,8 @@ import (
 	"golang.org/x/exp/slices"
 
 	"github.com/asmaloney/gactar/actr/buffer"
-	"github.com/asmaloney/gactar/actr/params"
+
+	"github.com/asmaloney/gactar/util/keyvalue"
 )
 
 const BuiltIn = "built-in"
@@ -45,8 +46,8 @@ type Interface interface {
 	Parameters() []ParamInterface
 	ParameterInfo(name string) ParamInterface
 
-	ValidateParam(param *params.Param) error
-	SetParam(param *params.Param) error
+	ValidateParam(param *keyvalue.KeyValue) error
+	SetParam(param *keyvalue.KeyValue) error
 
 	AllowsMultipleInit() bool
 }
@@ -95,11 +96,10 @@ func (m Module) Parameters() []ParamInterface {
 }
 
 // ValidateParam given an actr param will validate it against our modules parameters
-func (m Module) ValidateParam(param *params.Param) (err error) {
-
+func (m Module) ValidateParam(param *keyvalue.KeyValue) (err error) {
 	paramInfo := m.ParameterInfo(param.Key)
 	if paramInfo == nil {
-		return params.ErrUnrecognizedParam
+		return ErrUnrecognizedOption{Option: param.Key}
 	}
 
 	min := paramInfo.GetMin()
@@ -109,25 +109,25 @@ func (m Module) ValidateParam(param *params.Param) (err error) {
 
 	// we currently only have numbers
 	if value.Number == nil {
-		return params.ErrInvalidType{ExpectedType: params.Number}
+		return keyvalue.ErrInvalidType{ExpectedType: keyvalue.Number}
 	}
 
 	if (min != nil) && (max != nil) &&
 		((*value.Number < *min) || (*value.Number > *max)) {
-		return params.ErrOutOfRange{
+		return ErrValueOutOfRange{
 			Min: min,
 			Max: max,
 		}
 	}
 
 	if min != nil && (*value.Number < *min) {
-		return params.ErrOutOfRange{
+		return ErrValueOutOfRange{
 			Min: min,
 		}
 	}
 
 	if max != nil && (*value.Number > *max) {
-		return params.ErrOutOfRange{
+		return ErrValueOutOfRange{
 			Max: max,
 		}
 	}

actr/modules/params.go

@@ -1,5 +1,45 @@
 package modules
 
+import (
+	"fmt"
+	"strings"
+
+	"github.com/asmaloney/gactar/util/numbers"
+)
+
+type ErrUnrecognizedOption struct {
+	Option string
+}
+
+func (e ErrUnrecognizedOption) Error() string {
+	return fmt.Sprintf("unrecognized option %q", e.Option)
+}
+
+type ErrValueOutOfRange struct {
+	Min *float64
+	Max *float64
+}
+
+func (e ErrValueOutOfRange) Error() string {
+	if e.Min != nil && e.Max == nil {
+		return fmt.Sprintf("is out of range (minimum %s)", numbers.Float64Str(*e.Min))
+	}
+
+	if e.Min == nil && e.Max != nil {
+		return fmt.Sprintf("is out of range (maximum %s)", numbers.Float64Str(*e.Max))
+	}
+
+	return fmt.Sprintf("is out of range (%s-%s)", numbers.Float64Str(*e.Min), numbers.Float64Str(*e.Max))
+}
+
+type ErrInvalidValue struct {
+	Expected []string
+}
+
+func (e ErrInvalidValue) Error() string {
+	return fmt.Sprintf("must be must be one of %q", strings.Join(e.Expected, ", "))
+}
+
 // Ptr simply returns a pointer to a literal. e.g. Ptr(0.5)
 // This is useful when passing literals to functions which require pointers to basic types.
 func Ptr[T any](v T) *T {

actr/modules/procedural.go

@@ -1,7 +1,7 @@
 package modules
 
 import (
-	"github.com/asmaloney/gactar/actr/params"
+	"github.com/asmaloney/gactar/util/keyvalue"
 )
 
 type Procedural struct {
@@ -35,7 +35,7 @@ func NewProcedural() *Procedural {
 }
 
 // SetParam is called to set our module's parameter from the parameter in the code ("param")
-func (p *Procedural) SetParam(param *params.Param) (err error) {
+func (p *Procedural) SetParam(param *keyvalue.KeyValue) (err error) {
 	err = p.ValidateParam(param)
 	if err != nil {
 		return