Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ApplicationConfigI ¶
type ApplicationConfigI interface {
Initialize() error
}
When implementing your own configuration struct for a Tympan application, you must include a method to set default values for your own configuration. This is called by tympan.InitializeConfig().
If you have no initialization steps or important default values, you can implement your configuration like this:
type Configuration struct {
tympan.SharedConfig `mapstructure:",squash" tympanconfig:"ignore"`
MyAppSetting string `mapstructure:"my_app_setting"`
}
func (config *Configuration) Initialize() error {
return nil
}
type Configurable ¶
type Configurable interface {
// The general configuration of a Tympan application.
SharedConfigI
// The configuration specific to a particular Tympan application as defined by the application developer.
ApplicationConfigI
}
This interface is a type constraint because Tympan leverages go's generics. To be a valid struct which Tympan will know how to use for configuring an application, your struct must match the ApplicationConfigI interface and embed Tympan's own SharedConfig struct *or* a valid reimplementation of that struct.
For example:
type Configuration struct {
tympan.SharedConfig `mapstructure:",squash" tympanconfig:"ignore"`
MyAppSetting string `mapstructure:"my_app_setting"`
}
func (config *Configuration) Initialize() error {
return nil
}
A few things to note about this example:
- The SharedConfig is an embedded struct and uses two tags: `mapstructure:",squash"` and `tympanconfig:"ignore"`. Both of these are necessary for your configuration to be read correctly from disk. Combined, they tell Tympan: All of the values for this struct should be merged into the top-level of the struct and do not attempt to write this field name to the configuration file. Both are required for an embedded struct in a state file.
- The MyAppSetting field has a mapstructure tag of "my_app_setting". This will cause Tympan to save this field's value into the config under the "my_app_setting" key instead of "myappsetting". We strongly encourage using snake- cased mapstructure definitions for complex field names as viper/mapstructure will merely downcase by default, which can be difficult for users to read/understand.
type Folders ¶
type Folders struct {
// This is where the application's binary is stored.
Application string
// This is where the application's configuration is stored by default. Other configurations may be placed
// in this folder.
Configuration string
// This is where the application's state is stored by default. If using modules, plugins, or updateable documentation,
// the files and folders for those items are stored in this folder as well.
Cache string
}
The folders where the application may place files and folders of its own.
type Metadata ¶
type Metadata struct {
// The short name of the application - the name of the *binary* itself without any file extensions.
Name string
// The name of the application when being displayed. So for the "myapp" binary, it might be "My Application"
DisplayName string
// The description of the application to be displayed in the help for the root command and elsewhere.
Description string
// Where the application's files should be stored when using the configuration or cache folders.
FolderName string
// The name of the application's config file; defaults to "{name}-config.yaml"
ConfigFileName string
// The permissions that the app should use when creating new files and folders; defaults to 0755.
DefaultPermissions fs.FileMode
// The URL where the application's source code can be found.
SourceUrl string
// The URL where the application's website (including docs) can be found.
ProjectUrl string
}
Metadata is set by the Tympan application developer, not the end user. These values are held for reuse in messaging, finding/setting defaults, and more.
type SharedConfig ¶
type SharedConfig struct {
FolderPaths Folders `mapstructure:"folder_paths"`
DefaultLogLevel string `mapstructure:"default_log_level"`
DefaultOutputFormat string `mapstructure:"default_output_format"`
// to the configuration file on disk, as it represents that file for the application to find.
ConfigurationFilePath string `tympanconfig:"ignore"`
}
The SharedConfig is used by all Tympan applications (those which utilize the root forme). The SharedConfig must be embedded in the application's own configuration struct.
func (*SharedConfig) GetFolderPath ¶
func (config *SharedConfig) GetFolderPath(folder string) string
This method returns one of the folder paths from the shared configuration; because the Tympan library itself has to reference the application configuration by its type constraint it cannot use the values from the SharedConfig struct directly (at least not at the time of this writing and using go 1.18).
Examples:
myConfiguration.GetFolderPath("configuration") // returns myConfiguration.FolderPaths.Configuration
myConfiguration.GetFolderPath("application") // returns myConfiguration.FolderPaths.Application
myConfiguration.GetFolderPath("cache") // returns myConfiguration.FolderPaths.Cache
myConfiguration.GetFolderPath("does not exist") // returns ""
func (*SharedConfig) InitializeSharedConfig ¶
func (config *SharedConfig) InitializeSharedConfig(metadata Metadata, afs *afero.Afero) error
The InitializeSharedConfig() method sets the defaults for the SharedConfig struct which is always embedded in a Tympan application's own configuration struct. You must pass it the metadata for your Tympan application and a valid implementation of an Afero filesystem. This method:
1. Sets FolderPaths.Application to the parent folder containing the application's binary, returning an error if the location cannot be discovered or does not exist.
2. Sets FolderPaths.Configuration to the joined path of the current user's configuration directory per their operating system's file and folder layout standards with the application's FolderName (as defined in the Metadata) as the child folder. If needed, creates this folder and any missing parent folders, specifying the default permissions from the Metadata. It returns an error if the user configuration directory cannot be determined or an error occurs when ensuring the folder exists.
3. Sets FolderPaths.Cache to the joined path of the current user's cache directory per their operating system's file and folder layout standards with the application's FolderName (as defined in the Metadata) as the child folder. If needed, it creates this folder and any missing parent folders, specifying the default permissions from the Metadata. It returns an error if the user cache directory cannot be determined or an error occurs when ensuring the folder exists.
type SharedConfigI ¶
type SharedConfigI interface {
InitializeSharedConfig(metadata Metadata, afs *afero.Afero) error
GetFolderPath(folder string) string
}
Reimplementing the SharedConfig requires a small subset of functions that Tympan expects to use.
type Tympan ¶
type Tympan[Config Configurable] struct { // Handles calls to read to/write from the filesystem. Using Afero enables easier testing and numerous alternate file // systems without requiring additional coding, including an in-memory FS, Google Cloud Storage, and more. AFS *afero.Afero // Configuration holds the merged configuration items from Tympan's SharedConfig and an applications own Configuration // struct. For more information, see the Configurable interface. Configuration Config // Metadata holds information about the application itself as set by the developer. Metadata Metadata // ConfigHandler utilizes state.Handle to read and write the configuration file for the application. ConfigHandler *state.Handle }
The main entrypoint to using Tympan in an application, this struct handles the file system interactions, the configuration of the application itself, and stores the metadata for the application.
func (*Tympan[config]) DefaultConfigFile ¶
Returns the path to the default configuration file. A user may specify their own alternate configuration file when calling the application, but this returns where the app should look by default.
func (*Tympan[Config]) InitializeConfig ¶
The InitializeConfig() method handles setting default values, creating required folders, instantiating the state handler for the application configuration, and creating the configuration file with default values (if it does not already exist) or loading the configuration file's current values (if it does). It returns an error if any step of the process fails.
func (*Tympan[Config]) LoadConfig ¶
The LoadConfig() method reads the Tympan application's configuration file and updates the in-memory representation of the configuration used in the application. It expects that the configuration has already been loaded. It returns an error if any step of the process fails.
func (*Tympan[Config]) SaveConfig ¶
The LoadConfig() method writes the current in-memory configuration of the Tympan application to disk. It expects that the configuration has already been loaded. It returns an error if any step of the process fails.
Source Files
Directories