API

setup_input(input_path::AbstractString, verbose::Bool, ext::InputExt; paths::OrderedDict{String, Tuple{String, String}}=OrderedDict{String, Tuple{String, String}}(), log_path::String="output_path", custom_metadata::Vector{Tuple{String, String}}=Vector{Tuple{String, String}}())

Main BetterInputFiles function, given a path to an input file, this will preprocess, load, and postprocess the input file, including setting up paths and logging.

Arguments

• input_path::AbstractString: Path to input file
• verbose::Bool: Whether to log @debug messages
• ext::InputExt: Extension specifier
• paths::OrderedDict{String, Tuple{String, String}}=OrderedDict{String, Tuple{String, String}}: Paths to expand. paths will be merged with SetupModule.default_paths, with paths taking preference. See SetupModule.default_paths for the syntax of paths
• log_path::String="output_path": The "path_name" of the directory where logging should output. log_path must exist in paths or, be defined by SetupModule.default_paths
• custom_metadata::Vector{Tuple{String, String}}=Vector{Tuple{String, String}}(): Additonal metadata to include in the input file, in addition to creation date and input_path

setup_input(input_path::AbstractString, verbose::Bool, ext::String; paths::OrderedDict{String, Tuple{String, String}}=OrderedDict{String, Tuple{String, String}}(), log_path::String="output_path", custom_metadata::Vector{Tuple{String, String}}=Vector{Tuple{String, String}}())

Manually specify input file extension, then run setup_input(::AbstractString, ::Bool, ::InputExt, ::OrderedDict{String, Tuple{String, String}}, ::String, ::Vector{Tuple{String, String}})

Arguments

• input_path::AbstractString: Path to input file
• verbose::Bool: Whether to log @debug messages
• ext::String: Manual extension specifier
• paths::OrderedDict{String, Tuple{String, String}}=OrderedDict{String, Tuple{String, String}}: Paths to expand. paths will be merged with SetupModule.default_paths, with paths taking preference. See SetupModule.default_paths for the syntax of paths
• log_path::String="output_path": The "path_name" of the directory where logging should output. log_path must exist in paths or, be defined by SetupModule.default_paths
• custom_metadata::Vector{Tuple{String, String}}=Vector{Tuple{String, String}}(): Additonal metadata to include in the input file, in addition to creation date and input_path

setup_input(input_path::AbstractString, verbose::Bool; paths::OrderedDict{String, Tuple{String, String}}=OrderedDict{String, Tuple{String, String}}(), log_path::String="output_path", custom_metadata::Vector{Tuple{String, String}}=Vector{Tuple{String, String}}())

Automatically choose input file extension, then run setup_input(::AbstractString, ::Bool, ::InputExt, ::OrderedDict{String, Tuple{String, String}}, ::String, ::Vector{Tuple{String, String}})

Arguments

• input_path::AbstractString: Path to input file
• verbose::Bool: Whether to log @debug messages
• paths::OrderedDict{String, Tuple{String, String}}=OrderedDict{String, Tuple{String, String}}: Paths to expand. paths will be merged with SetupModule.default_paths, with paths taking preference. See SetupModule.default_paths for the syntax of paths
• log_path::String="output_path": The "path_name" of the directory where logging should output. log_path must exist in paths or, be defined by SetupModule.default_paths
• custom_metadata::Vector{Tuple{String, String}}=Vector{Tuple{String, String}}(): Additonal metadata to include in the input file, in addition to creation date and input_path

setup_global!(input::Dict, input_path::AbstractString, verbose::Bool, paths::OrderedDict{String, Tuple{String, String}}=OrderedDict{String, Tuple{String, String}}(), log_path::String="OUTPUT_PATH"; test::Bool=false)

Setup the "GLOBAL" information of input, including paths and logging.

Arguments

• input::Dict: The input file loaded into a Dict
• input_path::AbstractString: The path to the input .input file (from which input is loaded)
• verbose::Bool: Whether or not to display @debug calls
• paths::OrderedDict{String, Tuple{String, String}}: Paths to expand. paths will be merged with the following default_paths, with paths taking preference. See default_paths for the syntax of paths
• log_path::String: The "path_name" of the directory where logging should output
• test::Bool: Whether this run is a test or not. This will decide whether to actually create directories, or log anything

See also setup_paths!, and setup_logging!

default_paths::OrderedDict{String, Tuple{String, String}}

The default paths which will be expanded into absolute paths and used throughout the project.

default_paths::OrderedDict{String, Tuple{String, String}} = OrderedDict{String, Tuple{String, String}}(
    # Name => relative, default
    "BASE_PATH" => ("INPUT_PATH", ""),
    "OUTPUT_PATH" => ("BASE_PATH", "Output")
)

This dictionary maps ("path_name" => ("relative_name", "default_path")), where "path_name" is a human readable name for the path, "relative_name" is the name of the path which "path_name" is relative to, and "default_path" is the default value for the path (either absolute or relative). If "path_name" already exists inside input["GLOBAL"], then that path will be used either as is (if an absolute path) or relative to "relative_name", otherwise the "default_path" will be used

setup_logger(log_file::AbstractString, verbose::Bool)

Helper function which sets up Logger formating and log level

Arguments

• log_file::AbstractString: Path to log file
• verbose::Bool: Whether or not to display @debug calls

See also setup_logging! and setup_global!

setup_logging!(input::Dict, output_path::String="OUTPUT_PATH"; log::Bool=true)

Helper function which sets up log level, log files, etc... Assumes that setup_paths! has already been run on input

Arguments

• input::Dict: The input file we are modifying. This assumes that the input already has a "GLOBAL" key with value Dict{String, Any}("INPUT_PATH"=>"/path/to/input"), where"INPUT_PATH"` is the path to the input file
• output_path::String: The "path_name" of the output directory where log files should be written. See default_paths for more details

See also setup_global!

setup_paths!(input::Dict, paths::OrderedDict{String, Tuple{String, String}})

Helper function which sets up paths, expanding relative paths and ensuring all interim directories exist

Arguments

• input::Dict: The input file we are modifying. This assumes that the input already has a "GLOBAL" key with value Dict{String, Any}("INPUT_PATH"=>"/path/to/input"), where"INPUT_PATH"is the path to theinput` file
• paths::OrderedDict{String, Tuple{String, String}}: Paths to expand. paths will be merged with the following default_paths, with paths taking preference. See default_paths for a the syntax of paths

See also setup_global!

InputExt

Abstract type for input extensions. Extended by TOMLExt, JSONExt, and YAMLExt. Extend to add functionality for other input types. Names are assumed to be of the form EXTENSIONExt for .extension, i.e the extension in uppercase followed by Ext.

get_InputExt(ext::String)

Converts from '.extension' to InputExt subtype.

Arguments

• ext::String: '.extension' to convert to InputExt subtype

load_input(raw_input::String, ext::JSONExt)

Read .json file in to Dict

Arguments

• raw_input::String: Raw input to load
• ext::JSONExt: Extension specifier

load_input(raw_input::String, ext::TOMLExt)

Read raw .toml file in to Dict

Arguments

• raw_input::AbstractString: Raw input to load
• ext::TOMLExt: Extension specifier

load_input(raw_input::String, ext::YAMLExt)

Read .yaml file in to Dict

Arguments

• raw_input::String: Raw input to load
• ext::YAMLExt: Extension specifier

load_input(input_path::AbstractString, ext::JSONExt)

Read .json file in to Dict

Arguments

• input_path::AbstractString: Input path to load
• ext::JSONExt: Extension specifier

load_input(input_path::AbstractString, ext::TOMLExt)

Read .toml file in to Dict

Arguments

• input_path::AbstractString: Input path to load
• ext::TOMLExt: Extension specifier

load_input(input_path::AbstractString, ext::YAMLExt)

Read .yaml file in to Dict

Arguments

• input_path::AbstractString: Input path to load
• ext::YAMLExt: Extension specifier

load_input(input_path::AbstractString, ext::String)

Convert ext to InputExt, then attempt to load input into a dictionary

Arguments

• input_path::AbstractString: Input path to load
• ext::String: Extension string

load_input(input_path::AbstractString)

Automatically detect extension and attempt to load input into a dictionary

Arguments

• input_path::AbstractString: Input path to load

load_raw_inputfile(input_path::AbstractString)

Loads in the raw text in input_path

Arguments

• input_path::AbstractString: Input path to load

postprocess_input(input::Dict)

Run postprocessing on input

Arguments

• input::Dict: Input to postprocess

preprocess_input(input_path::AbstractString, ext::InputExt)

Preprocess the input path before running setup.

Arguments

• input_path::AbstractString: Input file to preprocess
• ext::InputExt: Extension type of input file

Preprocessing includes adding metadata comments at the top-level, including other files, inserting environmental variables, propegating default values, interpolating values, and ensuring all variables are upper-case.

preprocess_input(input_path::AbstractString, ext::String)

Specify the extension type of input_path manually, then preprocess the ipnut.

Arguments

• input_path::AbstractString: Input file to preprocess
• ext::String: Manually selected extension. Must be part of exts

If the extension of input_path is not defined by BetterInputFiles, but acts like a defined extension, you can specify which extension to use via this function, which will then run preprocess_input(::AbstractString, ::String)

preprocess_input(input_path::AbstractString)

Automatically detect extension type of input_path, then preprocess the input.

Arguments

• input_path::AbstractString: Input file to preprocess

Will error if the extension of input_path is not part of exts. If you wish to manually specify the extension, use [preprocess_input(::AbstractString, ::String)](@ref). After the extension is found, will run [preprocess_input(::AbstractString, ::String)](@ref)

save_input(input::Dict, output_file::AbstractString, ext::JSONExt)

Save input to output_file, as a .json file

Arguments

• input::Dict: Input to save
• output_file::AbstractString: Path to save
• ext::JSONExt: Extension specifier

save_input(input::Dict, output_file::AbstractString, ext::TOMLExt)

Save input to output_file, as a .toml file

Arguments

• input::Dict: Input to save
• output_file::AbstractString: Path to save
• ext::TOMLExt: Extension specifier

save_input(input::Dict, output_file::AbstractString, ext::YAMLExt)

Save input to output_file, as a .yaml file

Arguments

• input::Dict: Input to save
• output_file::AbstractString: Path to save
• ext::YAMLExt: Extension specifier

save_input(input::Dict, log_path::String, input_path::AbstractString, ext::InputExt)

Save input to the same directory that logging is being saved.

Arguments

• input::Dict: Input to save
• log_path::String: Directory to save input to
• input_path::AbstractString: Original path of input
• ext::InputExt: Extension specifier

exts::Vector{String}

Convencience list of all '.extension' file extensions for each defined subtype of InputExt.

input_exts::Vector{InputExt}

Convenience list of all InputExt subtypes defined.

JSONExt <: InputExt

InputExt subtype for .json files.

TOMLExt <: InputExt

InputExt subtype for .toml files.

YAMLExt <: InputExt

[InputExt] for .yaml files.

add_metadata(raw::String, ext::JSONExt, input_path::AbstractString)

Add metadata comment to top-level of .json file

Arguments

• raw::String: Raw text of input file
• ext::JSONExt: Extension of input file
• input_path::AbstractString: Path to input file

Adds a new "METADATA" key, containing the date of creation and input_path

add_metadata(raw::String, ext::YAMLExt, input_path::AbstractString)

Add metadata comment to top-level of .yaml file

Arguments

• raw::String: Raw text of input file
• ext::YAMLExt: Extension of input file
• input_path::AbstractString: Path to input file

Adds a new "METADATA" key, containing the date of creation and input_path

add_metadata(raw::String, ext::TOMLExt, input_path::AbstractString)

Add metadata comment to top-level of .toml file

Arguments

• raw::String: Raw text of input file
• ext::TOMLExt: Extension of input file
• input_path::AbstractString: Path to input file

Adds a new "METADATA" key, containing the date of creation and input_path

fix_dict_type(input::Dict)

Ensure dictionary is of type Dict{String, Any}

Arguments

• input::Dict: Input to fix

get_ext(ext::InputExt)

Convert from the InputExt type to the '.extension' file extension.

Arguments

• ext::InputExt: The InputExt subtype to convert into a file extension

process_env_vars(raw::String)

Interpolate environmental variables into raw, specified via <$ENV>

Arguments

• raw::String: Raw file to process

process_includes(raw::String, input_path::AbstractString)

Copy include files specified via <include path/to/include.file> into raw

Arguments

• raw::String: Raw file to provess
• input_path::AbstractString: Path to input file

process_interpolation(input::Dict)

Process interpolations for input

Arguments

• input::Dict The input to process

process_interpolation(raw::String, ext::InputExt)

Given the raw string for an input, load the input (load_input), and process all interpolations (process_interpolation(::Dict)), respecting defaults

Arguments

• raw::String: The raw input file to process
• ext::InputExt: Extension specifier

update_case(input::AbstractArray)

Updated the case of every element in input.

Arguments

• input::AbstractArray: Input to process

update_case(input::Any)

Stopping condition of postprocess_input(::Dict), when a value is reached

Arguments

• input::Any: Return input

update_case(input::Dict)

Recursively ensure every key in input is uppercase

Arguments

• input::Dict: The input to update