config

Documentation

Overview

The config package contains the API needed to make your plugin configurable.

Making your plugin available in the config file

To be used in the config file, your plugin must implement the Builder interface, where it will be provided a Config object, which allows the plugin programmer to load JSON into an annotated struct of their choice, using ConfigSet's ParseConfig() method. From there, you can configure your Producer as you see fit with your user-provided configuration.

I have followed an API similar to that of golang's own database/sql. When writing your plugin, you will need to register yourself in an init() method in your package, and then the ConfigSet object will be aware of your plugin and will use it when given the corresponding key.

After registering, you need to include your package as an anonymous import in the main function which parses the config file - you can find it in cmd/goi3bar

Builder

Build() is the method that is required to implement the Builder interface. It is provided a Config object, which offers ParseConfig() to cast the options subtree of your plugin's JSON block to a struct a-la json.Unmarshal. The Config object also has the raw interface{} of the options subtree, allowing you to inspect it manually, so you can provide a flexible API without the overhead of remarshalling through trial-and-error. See the network builders for an example of this.

I have defined an interface instead of a simple function typedef because there are some opportunities for code re-use. See the CPU builder for an example.

Get involved

If you write something you think is really nifty, you are of course welcome to submit a pull request to me for consideration to have it included in the default distribution.

Index

• func Register(key string, builder Builder)
• type Builder
• type Config
  • func (c Config) ParseConfig(i interface{}) error
• type ConfigSet
  • func ReadConfigSet(r io.Reader) (cs ConfigSet, err error)
  • func (c ConfigSet) Build() (bar *I3bar, err error)

Functions

func Register

func Register(key string, builder Builder)

Register is the registration point of your plugin to the Configuration namespace. Use a unique key, and your Builder will be called for entries with that package key

Types

type Builder

type Builder interface {
	Build(Config) (Producer, error)
}

Builder is the interface that must be implemented by plugins that wish to be configurable with I3bar's JSON configuration. Its' Build() method will be called exactly once on start with the given config. The Builder is strongly advised (though not required) to take advantage of the Config's ParseConfig() method, which parses the JSON options struct into a struct of their choosing. It behaves exactly like json.Unmarshal.

type Config

type Config struct {
	Package string          `json:"package"`
	Name    string          `json:"name"`
	Options json.RawMessage `json:"options"`
}

Config for one individual plugin instance

func (Config) ParseConfig

func (c Config) ParseConfig(i interface{}) error

ParseConfig is the point where your plugin's JSON config subtree will be parsed. Call this function with a pointer to your JSON-annotated config struct type in here, and it will behave as you expect it to.

type ConfigSet

type ConfigSet struct {
	Entries  []Config `json:"entries"`
	Interval string   `json:"interval"`
	Colors   Colors   `json:"colors"`
}

ConfigSet represents an entire JSON config file. If all goes well, it creates an I3bar.

func ReadConfigSet

func ReadConfigSet(r io.Reader) (cs ConfigSet, err error)

ReadConfigSet reads the JSON file referenced at path, and returns a ConfigSet representing that configuration

func (ConfigSet) Build

func (c ConfigSet) Build() (bar *I3bar, err error)

Build() constructs an I3bar from its internal configuration. The returned I3bar will not have had its' Start() method called.