Rename CacheMap to Vars

README.md

@@ -378,10 +378,6 @@ want the specific reasons.
   builtins themselves can obviously be used immediately and has a much
   smaller chance of changing in the future.
 
-* **Force `bonzai` Dependency in CacheMap, Conf, and Completer**
-
-
-
 ## Style Guidelines
 
 * Use "deciduous tree" emoji 🌳 to mark Bonzai stuff

bonzai.go

@@ -1,22 +1,27 @@
 package bonzai
 
-// Configurer specifies how to configure a Bonzai Cmd. Configurations
-// must always be maintained in YAML (of which JSON is a subset) and be
-// fully compatible with gopkg.in/yaml.v3.
+// Configurer specifies the package configuration driver interface. One
+// (and only one) implementation will be assigned to Z.Conf. Every
+// implementation *must* assign itself to Z.Conf on init so that
+// Bonzai tree developers need only import the implementation package.
 //
-// The location where the YAML is persisted is not specified by this
-// interface. Implementations may use any persistence layer that
-// guarantees atomic OverWrites and can be edited with a local system
-// editor.
+// Furthermore, implementations must be maintained in YAML (of which
+// JSON is a subset) and be fully compatible with gopkg.in/yaml.v3.
 //
-// The id may be anything that can be a YAML key, but use of Unicode
-// Letter class runes is strongly recommended.  Usually, the id will be
-// derived from the name of the executable binary or root Bonzai node
+// The location to which YAML is to be persisted is not specified by
+// this interface. Most implementations will use a file in
+// os.UserConfigDir (see rwxrob/conf). Implementations may use any
+// persistence layer that guarantees atomic OverWrites and can be edited
+// with a local system editor.
+//
+// The Id may be anything that can be a YAML key, but use of Unicode
+// Letter class runes is strongly recommended. Usually, the id will be
+// derived from the name of the executable binary or Cmd.Root Bonzai node
 // command.
 //
 // Configuration data is designed to change less frequently than cache
-// data (see Cacher) and is always updated by editing the entire YAML
-// file (never through future Set methods). It is important that
+// data (see Vars) and is always updated by editing the entire YAML file
+// (never through future Set methods). It is important that
 // configuration data not be abused and unnecessarily bloated to remain
 // performant.
 //
@@ -39,13 +44,19 @@ type Configurer interface {
 	QueryPrint(q string)      // prints result to os.Stdout
 }
 
-// CacheMap specifies how to persist (cache) simple string key/value
-// data. Implementations of CacheMap can persist in different ways,
-// files, network storage, or cloud databases, etc. but must always
-// present the data in a .key=val format with \r and \n escaped and the
-// key never must contain an equal (=). (Equal signs in the value are
-// ignored.) This is by far the fastest format to read and parse.
-type CacheMap interface {
+// Vars specifies the package persistent variables driver interface. All
+// implementations must assign themselves to Z.Vars during init. One
+// (and only one) persistent variable driver is allowed per executable.
+//
+// Implementations must persist (cache) simple string key/value
+// variables Implementations of Vars can persist in different ways, but
+// most will write to os.UserCacheDir (see rwxrob/vars).  Files, network
+// storage, or cloud databases, etc. are all allowed and expected.
+// However, each must always present the data in a .key=val format with
+// \r and \n escaped and the key never must contain an equal (=). (Equal
+// signs in the value are ignored.) This is the fastest format to read
+// and parse.
+type Vars interface {
 	Init() error                 // initialize completely new cache
 	Data() string                // k=v with \r and \n escaped in v
 	Print()                      // (printed)

z/bonzai.go

@@ -92,22 +92,23 @@ var Comp = compcmd.New()
 // implementation to switch everything that depends on configuration.
 var Conf bonzai.Configurer
 
-// Vars may be optionally assigned any implementation of
-// a bonzai.CacheMap. Once assigned it should not be reassigned at any
-// later time during runtime. Certain Bonzai branches and commands may
-// require Z.Vars to be defined and those that do generally require the
-// same implementation throughout all of runtime. Commands that require
-// Z.Vars should set ReqVars to true. Other than the exceptional case
-// of configuration commands that fulfill bonzai.CacheMap (and usually
-// assign themselves to Z.Vars at init() time), commands must never
-// require a specific implementation of bonzai.CacheMap.  This
+// Vars may be optionally assigned any implementation of a bonzai.Vars
+// but this is normally assigned at init() time by a bonzai.Vars driver
+// module (see rwxrob/vars). Once assigned it should not be reassigned
+// at any later time during runtime. Certain Bonzai branches and
+// commands may require Z.Vars to be defined and those that do generally
+// require the same implementation throughout all of runtime. Commands
+// that require Z.Vars should set ReqVars to true. Other than the
+// exceptional case of configuration commands that fulfill bonzai.Vars
+// (and usually assign themselves to Z.Vars at init() time), commands
+// must never require a specific implementation of bonzai.Vars.  This
 // encourages command creators and Bonzai tree composers to centralize
-// on a single form of caching without creating brittle
-// dependencies and tight coupling. Caching persistence can be
-// implemented in any number of ways without a problem and Bonzai trees
-// simply need to be recompiled with a different bonzai.CacheMap
-// implementation to switch everything that depends on cached variables.
-var Vars bonzai.CacheMap
+// on a single form of caching without creating brittle dependencies and
+// tight coupling. Caching persistence can be implemented in any number
+// of ways without a problem and Bonzai trees simply need to be
+// recompiled with a different bonzai.Vars implementation to switch
+// everything that depends on cached variables.
+var Vars bonzai.Vars
 
 // UsageFunc is the default first-class function called if a Cmd that
 // does not already define its own when usage information is needed (see