InstrumentConfig.jl

This package contains an interface for saving and reading configuration options from a YAML file. It's especially useful for instrument interface packages.
Author Orchard-Ultrasound-Innovation
Popularity
0 Stars
Updated Last
2 Years Ago
Started In
March 2021

InstrumentConfig

Stable Dev Build Status Build Status Coverage Code Style: Blue ColPrac: Contributor's Guide on Collaborative Practices for Community Packages

This package contains an interface for saving and reading configuration options from a YAML file. It's especially useful for instrument interface packages.

Inspired by unix config-file/dotfile style configuration.

Your current working directory (normally your julia project root) is first searched for a config file. If no config is found, your home directory is then searched for a config file.

Installation

TcpInstruments can be installed using the Julia package manager. From the Julia REPL, type ] to enter the Pkg REPL mode and run

pkg> add InstrumentConfig

Usage

Instrument Functions

This library exports the initialize and terminate functions so that they can be overridden and implemented in other packages.

Configuration

Create a new configuration


```julia
const myPkg_config = InstrumentConfig.Config(
    "{desired-name-of-configuration-file}",
)

If you want to automatically package an example/default config you can do so like this:

julia>touch "desired-name.yml"
shell>const myPkg_config = InstrumentConfig.Config(
    "desired-name.yml",
    @__MODULE__
)

Your config must be in the root folder and have the same config name.

If your config is not in the root of your project but in say your src folder or somewhere else:

julia>touch "src/desired-name.yml"
shell>const myPkg_config = InstrumentConfig.Config(
    "desired-name.yml",
    @__MODULE__;
    example="src/desired-name.yml"
)

Or you might want to have your default config file have a different name:

julia>touch "example_desired_config.yml"
shell>const myPkg_config = InstrumentConfig.Config(
    "desired-name.yml",
    @__MODULE__;
    example="src/my-example-desired-name.yml"
)

Or if your config is hosted somewhere on the internet

const EXAMPLE_FILE = "https://raw.githubusercontent.com/Orchard-Ultrasound-Innovation/TcpInstruments.jl/master/.tcp_instruments.yml" 

const tcp_config = InstrumentConfig.Config(
    ".tcp_instruments.yml";
    example = EXAMPLE_FILE
)

Implement the four main functions

# A getter function to be used in your code. Returns a dictionary of the
# loaded config file or loads the config if it has not yet been loaded
get_config() = InstrumentConfig.get_config(myPkg_config)

# If a location for the example/default file is specified
# users can create a global one in their home directory or they can call
# create_config(;dir=pwd()) to load the default config in their
# current working directory (normally the root of their julia project)
create_config(;dir=homedir()) = InstrumentConfig.create_config(myPkg_config; dir=dir)

# Will open the currently loaded config file in the users preferred
# editor( Uses the $EDITOR ENV variable)
edit_config() = InstrumentConfig.edit_config(myPkg_config)

# Loads your specified config file
load_config() = InstrumentConfig.load_config(myPkg_config)

Your package can now be used as follows:

using YourPackageName; YourPackageName.load_config()

Example

The .tcp_instruments.yml file in your project root will be used as the default. So create_config() will create that file instead of an empty file.

const tcp_config = InstrumentConfig.Config(
    ".tcp_instruments.yml",
    @__MODULE__
)

Implement these default functions for your package

Following the tcp_config example created above:

function get_config()
    return InstrumentConfig.get_config(tcp_config)
end

function create_config(;dir=homedir())
    InstrumentConfig.create_config(tcp_config; dir=dir)
end

function edit_config()
    InstrumentConfig.edit_config(tcp_config)
end

function load_config()
    InstrumentConfig.load_config(tcp_config)
end

You can add additional functionality to the default functions:

Lets say you want to validate the user's config whenever you load config

function my_validation_function(tcp_config)
    ....
end

function load_config()
    InstrumentConfig.load_config(tcp_config)
    my_validation_function(tcp_config)
    @info "My super friendly message"
    additional_malicious_malware_function()
    .... (etc)
end

Packages that use this library