convar

README

convar - A Quake-like console implementation for games

Features

• Type-safe
• int, bool, float64, string primitive types
• Special func type that accepts a single argument of any primitive type
• Variables can trigger a callback function when set/updated
• Everything is concurrent safe
• Case insensitive variable names
• Helper functions (see docs)
• Saving/loading variables to/from a file
• Simple command evaluation/execution
• Simple autocomplete

Installation

go get -u github.com/tapir/convar

Examples

Check out the _examples folder.

Documentation

Index

• type ConVar
  • func NewConVar(varName string, varType reflect.Kind, isFunc bool, varDesc string, ...) *ConVar
  • func (cv *ConVar) Bool() (bool, error)
  • func (cv *ConVar) Desc() string
  • func (cv *ConVar) Float64() (float64, error)
  • func (cv *ConVar) Int() (int, error)
  • func (cv *ConVar) Interface() (interface{}, error)
  • func (cv *ConVar) IsFunc() bool
  • func (cv *ConVar) Name() string
  • func (cv *ConVar) Reset()
  • func (cv *ConVar) SetBool(value bool) error
  • func (cv *ConVar) SetFloat64(value float64) error
  • func (cv *ConVar) SetInt(value int) error
  • func (cv *ConVar) SetString(value string) error
  • func (cv *ConVar) String() (string, error)
  • func (cv *ConVar) Type() reflect.Kind
• type Console
  • func NewConsole(bufMaxLines int, logLevel LogLevel, logInfoPrefix string, logWarnPrefix string, ...) *Console
  • func (c *Console) Buffer() string
  • func (c *Console) BufferRaw() []string
  • func (c *Console) BufferWrapped(maxWidth int) string
  • func (c *Console) BufferWrappedRaw(maxWidth int) []string
  • func (c *Console) ClearBuffer()
  • func (c *Console) ConVar(varName string) *ConVar
  • func (c *Console) ConVars() []*ConVar
  • func (c *Console) DumpBuffer(filePath string) error
  • func (c *Console) ExecCmd(cmd string) (*ConVar, error)
  • func (c *Console) Load(filePath string) error
  • func (c *Console) LogErrorf(format string, a ...interface{})
  • func (c *Console) LogInfof(format string, a ...interface{})
  • func (c *Console) LogPrintf(format string, a ...interface{})
  • func (c *Console) LogWarningf(format string, a ...interface{})
  • func (c *Console) RegConVar(cv *ConVar)
  • func (c *Console) RegDefaultConVars()
  • func (c *Console) ResetAllVar()
  • func (c *Console) Save(filePath string) error
  • func (c *Console) SetLogLevel(level LogLevel)
  • func (c *Console) Suggest(str string, n int) []*ConVar
• type LogLevel
• type ValSetFunc

Types

type ConVar

type ConVar struct {
	// contains filtered or unexported fields
}

ConVar represents a console variable.

func NewConVar

func NewConVar(varName string, varType reflect.Kind, isFunc bool, varDesc string, valDefault interface{}, valSet ValSetFunc) *ConVar

NewConVar returns a convar of the given name and type. Convar names are case insensitive. varDefault is the default value. varDesc is the description of the convar. valSet is a callback function that is triggered everytime the convar's value is changed.

NewConVar will panic if there are any errors. NewConVar should ideally be called for each convar at the begging of the application and before loading a config file. A convar cannot be safely used if it's not registered to a console instance via RegVar.

When isFunc is true, a convar is treated in a special way:

Convar is not saved to or loaded from the config file. This can be used to protect users from doing things like cyclic loading.
SetInt, SetBool, SetFloat64, SetString functions do not change the value but instead trigger the callback with the given value.
Value is always equal to default value.

func (*ConVar) Bool

func (cv *ConVar) Bool() (bool, error)

Bool returns the value of the convar as a boolean. The underlying type for a boolean is integer.

func (*ConVar) Desc

func (cv *ConVar) Desc() string

Desc returns the description of the convar.

func (*ConVar) Float64

func (cv *ConVar) Float64() (float64, error)

Float64 returns the value of the convar as a float64.

func (*ConVar) Int

func (cv *ConVar) Int() (int, error)

Int returns the value of the convar as an integer.

func (*ConVar) Interface

func (cv *ConVar) Interface() (interface{}, error)

Interface returns the value of the convar as an interface which is the underlying data type for all convars. Interface will never return an error.

func (*ConVar) IsFunc

func (cv *ConVar) IsFunc() bool

IsFunc returns true if the convar is set as a function.

func (*ConVar) Name

func (cv *ConVar) Name() string

Name returns the name of the convar.

func (*ConVar) Reset

func (cv *ConVar) Reset()

Reset resets a convar to its default value. Value set/update callback function is not triggered.

func (*ConVar) SetBool

func (cv *ConVar) SetBool(value bool) error

SetBool sets the value of an integer convar from a boolean. true means 1 and false means 0.

func (*ConVar) SetFloat64

func (cv *ConVar) SetFloat64(value float64) error

SetFloat64 sets the convar to the given float64 value.

func (*ConVar) SetInt

func (cv *ConVar) SetInt(value int) error

SetInt sets the convar to the given int value.

func (*ConVar) SetString

func (cv *ConVar) SetString(value string) error

SetString sets the convar to the given string value.

func (*ConVar) String

func (cv *ConVar) String() (string, error)

String returns the value of the convar as a string.

func (*ConVar) Type

func (cv *ConVar) Type() reflect.Kind

Type returns the type of the convar.

type Console

type Console struct {
	// contains filtered or unexported fields
}

Console is a Quake-like console implementation for games.

func NewConsole

func NewConsole(bufMaxLines int, logLevel LogLevel, logInfoPrefix string, logWarnPrefix string, logErrPrefix string) *Console

NewConsole creates a new console instance with the given settings. If buffer size reaches bufMaxLines, old lines will be discarded. Only logs that are of smaller level than logLevel will be written to the buffer.

func (*Console) Buffer

func (c *Console) Buffer() string

Buffer returns the console buffer as a string.

func (*Console) BufferRaw

func (c *Console) BufferRaw() []string

BufferRaw returns the copy of the underlying raw buffer slice. Each element represents a line.

func (*Console) BufferWrapped

func (c *Console) BufferWrapped(maxWidth int) string

BufferWrapped returns the console buffer with each line wrapped to a new line. maxWidth is the maximum number of runes allowed before wrapping it to a new line.

Note that this method doesn't take into account the rare cases of where a single character might be represented by multiple runes (ex: 'é́́'). Use https://pkg.go.dev/golang.org/x/text/unicode/norm together with Buffer() to handle such cases.

func (*Console) BufferWrappedRaw

func (c *Console) BufferWrappedRaw(maxWidth int) []string

BufferWrappedRaw returns the console buffer with each line wrapped to a new line as a slice. maxWidth is the maximum number of runes allowed before wrapping it to a new line.

func (*Console) ClearBuffer

func (c *Console) ClearBuffer()

ClearBuffer clears the console buffer.

func (*Console) ConVar

func (c *Console) ConVar(varName string) *ConVar

ConVar returns the convar with the given name. Returns nil if it doesn't exist.

func (*Console) ConVars

func (c *Console) ConVars() []*ConVar

ConVars returns a slice of all registered convars.

func (*Console) DumpBuffer

func (c *Console) DumpBuffer(filePath string) error

DumpBuffer saves the console buffer to the given file.

func (*Console) ExecCmd

func (c *Console) ExecCmd(cmd string) (*ConVar, error)

ExecCmd parses and executes a console command string.

func (*Console) Load

func (c *Console) Load(filePath string) error

Load executes each line in the given config file. If the any convars in the file are not registered with RegVar before calling this method, they will be ignored.

func (*Console) LogErrorf

func (c *Console) LogErrorf(format string, a ...interface{})

LogErrorf prints an error message to the console.

func (*Console) LogInfof

func (c *Console) LogInfof(format string, a ...interface{})

LogInfof prints an information message to the console.

func (*Console) LogPrintf

func (c *Console) LogPrintf(format string, a ...interface{})

LogPrintf prints a message to the console without a prefix, regardless of the log level.

func (*Console) LogWarningf

func (c *Console) LogWarningf(format string, a ...interface{})

LogWarningf prints a warning message to the console.

func (*Console) RegConVar

func (c *Console) RegConVar(cv *ConVar)

RegConVar registers a new convar to be used in the console.

func (*Console) RegDefaultConVars

func (c *Console) RegDefaultConVars()

RegDefaultConVars registers an assortment of useful convars.

con_dump:		Saves the console buffer to a file.
con_clear:		Clears the console buffer.
var_reset:		Resets given convar to its default value without triggering its callback.
var_reset_all:	Resets all convars to their default values without triggering their callbacks.
var_load:		Loads convars from a file, overwriting the ones that are already in the memory.
var_save:		Saves convars to a file.
var_list:		Lists all convars with their description.

func (*Console) ResetAllVar

func (c *Console) ResetAllVar()

ResetAllVar resets all convars to their default values. It doesn't trigger the set/update callback.

func (*Console) Save

func (c *Console) Save(filePath string) error

Save saves all convars to the given config file. Only non-default values are saved.

func (*Console) SetLogLevel

func (c *Console) SetLogLevel(level LogLevel)

SetLogLevel changes the log level that will be written to the console buffer.

func (*Console) Suggest

func (c *Console) Suggest(str string, n int) []*ConVar

Suggest suggests a list of size n, populated with the convars that have the substring str in their names.

type LogLevel

type LogLevel int32

LogLevel is the type for the log level.

const (
	// LogNone means no message will be printed to the console buffer.
	LogNone LogLevel = iota
	// LogInfo means only information messages will be printed to the console buffer.
	LogInfo
	// LogWarning means information and warning messages will be printed to the console buffer.
	LogWarning
	// LogError means information, warning and error messages will be printed to the console buffer.
	LogError
)

type ValSetFunc

type ValSetFunc func(con *Console, oldVal, newVal interface{})

ValSetFunc is the function signature of the value set/update callback.