README
¶
context - the weaving together of data in structure
This package primarily provides a simple map type, called "Context":
type Context map[string]interface{}
The Context can be used like a normal map type, which also means that these sorts of things are not concurrecy-safe. The purpose of these structures are intended for ephemeral cases such as the unmarshalling of JSON data and accessing the information as conveniently as possible.
Like most Go-CoreLibs, Go-Curses and Go-Enjin projects, Context follows a developer-focused design - "make it nice to work with". However we need to define what "nice" means in this context because of the limitations of human language.
A project is defined as "nice to work with" when (in no particular order):
- it works well with the Go standard library
- it does not make decisions for the developer
- it is convenient to type into any text editor
- it is convenient to conceptualize it's use cases
- it is designed with a balance of security and convenience
- it does not require arcane, occult or estoric knowledge to use effectively
What is a Context anyways?
Merriam-Webster has a lovely blurb on the meaning of the word "context", copied here (without permission) because of it's relevance and because I love their work:
Did you know?
In its earliest uses (documented in the 15th century), context meant "the
weaving together of words in language." This sense, now obsolete, developed
logically from the word's source in Latin, contexere "to weave or join
together." Context now most commonly refers to the environment or setting in
which something (whether words or events) exists. When we say that something
is contextualized, we mean that it is placed in an appropriate setting, one in
which it may be properly considered.
-- https://www.merriam-webster.com/dictionary/context -- please support your favorite dictionary, even if it's not Merriam-Webster -- the languages we use in life defines the limits of what can be thought of
For this project in specific, the meaning of the word "context" is actually both the obsolete and modern meanings.
Within the Go-Enjin project, where this package manifested first, there are a number of use cases:
- it is the front-matter portion of any parsed page
- it is the means for parsing page editor form submissions
- it is a type used for unmarshalling JSON data
- it is a type used for scanning DB query rows
Now that this project has been migrated from it's original home at:
github.com/go-enjin/be/pkg/context to this new home as a formal Go-CoreLibs
project, this package will end up being used anytime a type for managing the
weaving together of data in structure makes sense.
Installation
> go get github.com/go-corelibs/context@latest
Go-CoreLibs
Go-CoreLibs is a repository of shared code between the Go-Curses and Go-Enjin projects.
License
Copyright 2024 The Go-CoreLibs Authors
Licensed under the Apache License, Version 2.0 (the "License");
you may not use file except in compliance with the License.
You may obtain a copy of the license at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
Documentation
¶
Overview ¶
Package context provides a means for the weaving together of data in structure
Index ¶
- type Context
- func (c Context) Apply(contexts ...Context)
- func (c Context) ApplySpecific(contexts ...Context)
- func (c Context) AsDeepKeyed() (out Context)
- func (c Context) Bool(key string, def ...bool) bool
- func (c Context) Boolean(key string) (value, ok bool)
- func (c Context) Bytes(key string, def ...[]byte) []byte
- func (c Context) CamelizeKeys()
- func (c Context) Context(key string) (ctx Context)
- func (c Context) Copy() (ctx Context)
- func (c Context) DeepKeys() (keys []string)
- func (c Context) DefaultStrings(key string, def ...[]string) []string
- func (c Context) Delete(key string) (deleted bool)
- func (c Context) DeleteKeys(keys ...string)
- func (c Context) Empty() (empty bool)
- func (c Context) FirstString(key string) (value string, ok bool)
- func (c Context) Float64(key string, def ...float64) float64
- func (c Context) Get(key string) (value interface{})
- func (c Context) GetKV(key string) (k string, v interface{})
- func (c Context) Has(key string) (present bool)
- func (c Context) HasExact(key string) (present bool)
- func (c Context) Int(key string, def ...int) int
- func (c Context) Int64(key string, def ...int64) int64
- func (c Context) KebabKeys()
- func (c Context) Keys() (keys []string)
- func (c Context) Len() (count int)
- func (c Context) LowerCamelizeKeys()
- func (c Context) MatchQL(query string) (matched bool, err error)
- func (c Context) PruneEmpty() (pruned Context)
- func (c Context) Select(keys ...string) (selected map[string]interface{})
- func (c Context) SelectStringValues(keys ...string) (selected []string)
- func (c Context) SelectValues(keys ...string) (selected []interface{})
- func (c Context) Set(key string, value interface{}) Context
- func (c Context) SetKV(key string, value interface{}) (err error)
- func (c Context) SetSpecific(key string, value interface{}) Context
- func (c Context) Slice(key string) (list []interface{}, ok bool)
- func (c Context) String(key string, def ...string) string
- func (c Context) StringOrStrings(key string) (values []string)
- func (c Context) Strings(key string) (values []string)
- func (c Context) Time(key string, def ...time.Time) time.Time
- func (c Context) TimeDuration(key string, def ...time.Duration) time.Duration
- func (c Context) ToEnviron() (out []string)
- func (c Context) ToJSON() (data []byte, err error)
- func (c Context) ToMap() (out map[string]interface{})
- func (c Context) ToStringMap() (out map[string]string)
- func (c Context) ToTOML() (data []byte, err error)
- func (c Context) ToYAML() (data []byte, err error)
- func (c Context) Uint(key string, def ...uint) uint
- func (c Context) Uint64(key string, def ...uint64) uint64
- func (c Context) ValueAsInt(key string, def ...int) int
- func (c Context) ValueAsInt64(key string, def ...int64) int64
- type Contexts
- func (c Contexts) FindQL(query string) (found Contexts)
- func (c Contexts) FirstInt64Value(key string) int64
- func (c Contexts) FirstIntValue(key string) int
- func (c Contexts) FirstStringValue(key string) string
- func (c Contexts) FirstValue(key string) interface{}
- func (c Contexts) Int64Values(key string) (values []int64)
- func (c Contexts) IntValues(key string) (values []int)
- func (c Contexts) Len() (count int)
- func (c Contexts) SelectStringValues(keys ...string) (values [][]string)
- func (c Contexts) SelectValues(keys ...string) (values [][]interface{})
- func (c Contexts) StringValues(key string) (values []string)
- func (c Contexts) Values(key string) (values []interface{})
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Context ¶
type Context map[string]interface{}
Context is a convenient map[string]interface{} type, used by Go-Enjin for representing page front-matter and other contextual cases
Context is not a replacement for the standard Go context library
func NewFromMap ¶
NewFromMap deep copies and transforms the given map into a Context with all values converted to Context types
func NewFromOsEnviron ¶
NewFromOsEnviron constructs a new Context from os.Environ() string K=V slices, unquoting any quoted values, all the keys will be exactly as present in the input environ strings
func (Context) ApplySpecific ¶
ApplySpecific takes a list of contexts and merges their contents into this one, keeping the keys specifically
func (Context) AsDeepKeyed ¶
AsDeepKeyed returns a deep-key flattened version of this context
Examples:
Input Context{"one": map[string]interface{}{"two": "deep"}}
Output Context{".one.two": "deep"}
Input Context{"one": Contexts{{"two": "deep"}}}
Output Context{".one[0].two": "deep"}
func (Context) Bytes ¶
Bytes returns the key's value as a byte slice, returning the given default if not found or not actually a byte slice value.
func (Context) CamelizeKeys ¶
func (c Context) CamelizeKeys()
CamelizeKeys transforms all keys within the Context to be of CamelCased form
func (Context) Context ¶
Context looks for the given key and if the value is of Context type, returns it
func (Context) Copy ¶
Copy returns a deep-copy of this Context using values.DeepCopy
For problematic type cases, implementing the [deepcopy.Copyable] interface will enable the correct behaviour
func (Context) DeepKeys ¶
DeepKeys returns a natural sorted list of .deep.keys representing the entire context
func (Context) DefaultStrings ¶
DefaultStrings is a wrapper around Strings() and returns the given default list of strings if the key is not found
func (Context) DeleteKeys ¶
DeleteKeys is a batch wrapper around Delete()
func (Context) HasExact ¶
HasExact returns true if the specific Context key given exists and is not nil
func (Context) KebabKeys ¶
func (c Context) KebabKeys()
KebabKeys transforms all keys within the Context to be of kebab-cased form
func (Context) Keys ¶
Keys is a convenience wrapper around maps.SortedKeys
func (Context) LowerCamelizeKeys ¶
func (c Context) LowerCamelizeKeys()
LowerCamelizeKeys transforms all keys within the Context to be of lowerCamelCased form
func (Context) PruneEmpty ¶
func (Context) SelectStringValues ¶
func (Context) SelectValues ¶
func (Context) SetSpecific ¶
SetSpecific is like Set(), without CamelCasing the key
func (Context) String ¶
String returns the key's value as a string, returning the given default if not found or not actually a string value.
func (Context) StringOrStrings ¶
StringOrStrings returns the key's value as a list of strings and if the key's actual value is not a list of strings, return that as a list of one string
func (Context) Strings ¶
Strings returns the key's value as a list of strings, returning an empty list if not found or not actually a list of strings
func (Context) TimeDuration ¶
func (Context) ToEnviron ¶
ToEnviron returns this Context as a transformed []string slice where each key is converted to SCREAMING_SNAKE_CASE and the value is converted to a string (similarly to ToStringMap) and the key/value pair is concatenated into a single "K=V" string and appended to the output slice, sorted by key in natural order, suitable for use in os.Environ cases.
func (Context) ToJSON ¶
ToJSON is a convenience wrapper around json.MarshalIndent, indented with two spaces and no prefix
func (Context) ToMap ¶
ToMap returns a values.DeepCopy of this Context, transformed to a standard map[string]interface{} type, recursively (the output map has no references to the Context or Contexts types)
func (Context) ToStringMap ¶
ToStringMap returns this Context as a transformed map[string]string structure, where each key's value is checked and if it's a string, use it as-is and if it's anything else, run it through fmt.Sprintf("%v") to make it a string
func (Context) ToYAML ¶
ToYAML is a convenience wrapper around yaml.Marshal
type Contexts ¶
type Contexts []Context
Source Files
Directories