From a770d8250e1c191ddb79f3ae6ce6b220c40e1404 Mon Sep 17 00:00:00 2001 From: rwxrob Date: Tue, 12 Apr 2022 09:35:43 -0400 Subject: [PATCH] Rename CacheMap to Vars --- README.md | 4 ---- bonzai.go | 49 ++++++++++++++++++++++++++++++------------------- z/bonzai.go | 31 ++++++++++++++++--------------- 3 files changed, 46 insertions(+), 38 deletions(-) diff --git a/README.md b/README.md index 3a28696..771642a 100644 --- a/README.md +++ b/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 diff --git a/bonzai.go b/bonzai.go index 013e372..f1bcde6 100644 --- a/bonzai.go +++ b/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) diff --git a/z/bonzai.go b/z/bonzai.go index 34c2b05..7dafed6 100644 --- a/z/bonzai.go +++ b/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