vars

README

🌳 Go Bonzai™ Cached Variables

Install

This command can be installed as a standalone program or composed into a Bonzai command tree.

Standalone

go install github.com/rwxrob/vars/cmd/var@latest

Composed

package z

import (
	Z "github.com/rwxrob/bonzai/z"
	"github.com/rwxrob/vars"
)

var Cmd = &Z.Cmd{
	Name:     `z`,
	Commands: []*Z.Cmd{help.Cmd, vars.Cmd},
}

Tab Completion

To activate bash completion just use the complete -C option from your .bashrc or command line. There is no messy sourcing required. All the completion is done by the program itself.

complete -C var var

If you don't have bash or tab completion check use the shortcut commands instead.

Embedded Documentation

All documentation (like manual pages) has been embedded into the source code of the application. See the source or run the program with help to access it.

Documentation

Overview

Package vars provides the Bonzai command branch of the same name.

Package vars provides high-level functions that are called from the Go Bonzai branch of the same name providing universal access to the core functionality.

Index

• Variables
• type Map
  • func New() Map
  • func (m Map) Data() string
  • func (m Map) Del(key string) error
  • func (c Map) DirPath() string
  • func (c Map) Edit() error
  • func (c Map) Exists() bool
  • func (m Map) Get(key string) string
  • func (c Map) Init() error
  • func (m *Map) Load() error
  • func (c Map) MarshalText() ([]byte, error)
  • func (c Map) OverWrite(with string) error
  • func (c Map) Path() string
  • func (m Map) Print()
  • func (m *Map) Save() error
  • func (m Map) Set(key, val string) error
  • func (c Map) SoftInit() error
  • func (c *Map) UnmarshalText(in []byte) error

Variables

var BlankLine = regexp.MustCompile(`^[ \t\r\n]*$`)

var Cmd = &Z.Cmd{
	Name:        `var`,
	Summary:     `cache variables in {{ execachedir "vars"}}`,
	Description: helpDoc,
	Version:     `v0.6.4`,
	Copyright:   `Copyright 2021 Robert S Muhlestein`,
	License:     `Apache-2.0`,
	Source:      `git@github.com:rwxrob/vars.git`,
	Issues:      `https://github.com/rwxrob/vars/issues`,
	Commands: []*Z.Cmd{
		getCmd,
		help.Cmd, initCmd, setCmd, fileCmd, dataCmd, editCmd, deleteCmd,
	},
}

Types

type Map

type Map struct {
	sync.Mutex
	M    map[string]string
	Id   string // usually application name
	Dir  string // usually os.UserCacheDir
	File string // usually vars
}

func New

func New() Map

Map returns a Map with the M initialized. No other initialization is performed. See Init.

func (Map) Data

func (m Map) Data() string

Data returns the cache data in text marshaled format: k=v, no equal sign in key, carriage return and line returns escaped, terminated by line return on each line. Logs an error if source of data is unavailable. Fulfills the bonzai.Vars interface.

func (Map) Del

func (m Map) Del(key string) error

Del deletes an entry from the persistent cache. Fulfills the bonzai.Vars interface.

func (Map) DirPath

func (c Map) DirPath() string

DirPath is the Dir and Id joined.

func (Map) Edit

func (c Map) Edit() error

Edit opens the given cached variables files in the local editor. See fs/file.Edit for more.

func (Map) Exists

func (c Map) Exists() bool

Exists returns true if a configuration file exists at Path.

func (Map) Get

func (m Map) Get(key string) string

Get returns a value from the persisted cache (if it has one). No locking is done. Fulfills the bonzai.Vars interface.

func (Map) Init

func (c Map) Init() error

Init initializes the cache directory (Dir) for the current user and given application name (Id) using the standard os.UserCacheDir location. The directory is completely removed and new configuration file(s) are created.

Consider placing a confirmation prompt before calling this function when term.IsInteractive is true. Since Init uses fs/{dir,file}.Create you can set the file.DefaultPerms and dir.DefaultPerms if you prefer a different default for your permissions.

Permissions in the fs package are restrictive (0700/0600) by default to allow tokens to be stored within configuration files (as other applications are known to do). Still, saving of critical secrets is not encouraged within any flat file. But anything that a web browser would need to cache in order to operate is appropriate (cookies, session tokens, etc.).

Fulfills the bonzai.Vars interface.

func (*Map) Load

func (m *Map) Load() error

Loads the latest from File and Unmarshals into M.

func (Map) MarshalText

func (c Map) MarshalText() ([]byte, error)

MarshalText fulfills encoding.TextMarshaler interface

func (Map) OverWrite

func (c Map) OverWrite(with string) error

OverWrite overwrites the cache File in a way that is safe for all callers of OverWrite in this current system for any operating system using go-internal/lockedfile (taken from the to internal project itself, https://github.com/golang/go/issues/33974) but applying the file.DefaultPerms instead of the 0666 Go default. The format of the cache string must be key:value with carriage returns and line returns escaped. No colons are allowed in the key. Each line must be terminated with a single line return.

func (Map) Path

func (c Map) Path() string

Path returns the combined Dir and File.

func (Map) Print

func (m Map) Print()

Print prints the text version of the cache. See Data for format. Fulfills the bonzai.Vars interface.

func (*Map) Save

func (m *Map) Save() error

Save persists the current map to file. See OverWrite.

func (Map) Set

func (m Map) Set(key, val string) error

Set sets a persistent variable in the cache or returns an error if not. Fulfills the bonzai.Vars interface.

func (Map) SoftInit

func (c Map) SoftInit() error

SoftInit calls Init if not Exists.

func (*Map) UnmarshalText

func (c *Map) UnmarshalText(in []byte) error

UnmarshalText fulfills encoding.TextUnmarshaler interface