README
¶
config
Contains functions for loading configurations and handling data.
data encapsulation
Substation encapsulates data during ingest and decapsulates it during load; data in transit is stored in "capsules." Capsules contain two fields:
- data: stores structured or unstructured data
- metadata: stores structured metadata that describes the data
The metadata field is accessed through a special JSON key named "!metadata", any references to this key will get or set the structured data stored in the field. JSON values can be freely moved between the data and metadata fields.
Capsules can be created and initialized using this pattern, where b is a []byte and v is an interface{}:
cap := NewCapsule()
cap.SetData(b).SetMetadata(v)
Substation applications follow these rules when handling capsules:
- Sources set the initial metadata, but this can be modified in transit by applying processors
- Sinks only output data, but metadata can be retained by copying it from metadata into data
Documentation
¶
Overview ¶
package config provides capabilities for managing configurations and handling data in Substation applications.
Index ¶
- func Decode(input, output interface{}) error
- func Get() string
- type Capsule
- func (c *Capsule) Data() []byte
- func (c *Capsule) Delete(key string) (err error)
- func (c *Capsule) Get(key string) json.Result
- func (c *Capsule) Metadata() []byte
- func (c *Capsule) Set(key string, value interface{}) (err error)
- func (c *Capsule) SetData(b []byte) *Capsule
- func (c *Capsule) SetMetadata(i interface{}) (*Capsule, error)
- func (c *Capsule) SetRaw(key string, value interface{}) (err error)
- type Channel
- type Config
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Decode ¶
func Decode(input, output interface{}) error
Decode marshals and unmarshals an input interface into the output interface using the standard library's json package. This should be used when decoding JSON configurations (i.e., Config) in Substation interface factories.
func Get ¶
func Get() string
Get retrieves a configuration location from the SUBSTATION_CONFIG environment variable.
Example (File) ¶
package main
import (
"os"
"github.com/jshlbrd/substation/cmd"
"github.com/jshlbrd/substation/config"
)
func main() {
// cfg is the location of a file on-disk
cfg := config.Get()
f, err := os.Open(cfg)
if err != nil {
// handle err
panic(err)
}
defer f.Close()
sub := cmd.New()
if err := sub.SetConfig(f); err != nil {
// handle err
panic(err)
}
}
Output:
Types ¶
type Capsule ¶
type Capsule struct {
// contains filtered or unexported fields
}
Capsule stores encapsulated data that is used throughout the package's data handling and processing functions.
Each capsule contains two unexported fields that are accessed by getters and setters:
- data: stores structured or unstructured data
- metadata: stores structured metadata that describes the data
Values in the metadata field are accessed using the pattern "!metadata [key]". JSON values can be freely moved between the data and metadata fields.
Substation applications follow these rules when handling capsules:
- Sources set the initial metadata, but this can be modified in transit by applying processors
- Sinks only output data, but metadata can be retained by copying it from metadata into data
func (*Capsule) Delete ¶
Delete removes a key from a JSON object stored in the capsule's data or metadata fields.
func (*Capsule) Get ¶
Get retrieves a value from a JSON object stored in the capsule's data or metadata fields.
func (*Capsule) Set ¶
Set writes a value to a JSON object stored in the capsule's data or metadata fields.
Example ¶
package main
import (
"fmt"
"github.com/jshlbrd/substation/config"
)
func main() {
data := []byte(`{"foo":"bar"}`)
capsule := config.NewCapsule()
capsule.SetData(data)
if err := capsule.Set("baz", "qux"); err != nil {
// handler error
panic(err)
}
d := capsule.Data()
fmt.Println(string(d))
}
Output: {"foo":"bar","baz":"qux"}
func (*Capsule) SetData ¶
SetData writes data to the capsule's data field.
Example ¶
package main
import (
"github.com/jshlbrd/substation/config"
)
func main() {
data := []byte(`{"foo":"bar"}`)
capsule := config.NewCapsule()
capsule.SetData(data)
}
Output:
func (*Capsule) SetMetadata ¶
SetMetadata writes data to the capsule's metadata field. Metadata must be an interface that can marshal to a JSON object.
Example ¶
package main
import (
"github.com/jshlbrd/substation/config"
)
func main() {
metadata := struct {
baz string
}{
baz: "qux",
}
capsule := config.NewCapsule()
if _, err := capsule.SetMetadata(metadata); err != nil {
// handle err
panic(err)
}
}
Output:
Example (Chaining) ¶
package main
import (
"github.com/jshlbrd/substation/config"
)
func main() {
metadata := struct {
baz string
}{
baz: "qux",
}
data := []byte(`{"foo":"bar"}`)
capsule := config.NewCapsule()
if _, err := capsule.SetData(data).SetMetadata(metadata); err != nil {
// handle err
panic(err)
}
}
Output:
type Channel ¶
type Channel struct {
C chan Capsule
// contains filtered or unexported fields
}
Channel provides methods for safely writing capsule data to and closing channels. Data should be read directly from the channel (e.g., ch.C).
func (*Channel) Close ¶
func (c *Channel) Close()
Close closes a channel and relies on a mutex to prevent panicking if the channel is closed by multiple goroutines.
func (*Channel) Send ¶
Send writes capsule data to a channel and relies on goroutine recovery to prevent panicking if writes are attempted on a closed channel. Read more about recovery here: https://go.dev/blog/defer-panic-and-recover.
Source Files