Crate easy_configuration_format

Easy Configuration Format

A settings format that strikes a great balance between usage simplicity and parsing simplicity, with aspects like:

• Support for strings, ints, float, bools, and comments
• Elegant error handling, an invalid line in the middle won’t ruin everything afterwards and loading then saving a file will always result in a valid ecf file (to see this in action, just run cargo run --example main)
• ‘Setting updater’ functions have built-in support and encouragement
• Almost no code (~500 sloc) and no dependencies (other than std)

Example settings file:

format 1
# This first line defines the version number of your settings file. If you want to update
# your program's settings, this will allow you to update users' settings file to your
# newer version
 
example key: "example value"
 
example blank: empty
example string: "not empty"
example int: 3
example float: 3.5
example bool: true
example multiline: "
"first line (#0)
"also, because of how strings are stored, you can have " characters inside a string with
"no escape codes needed
"last line (#3)
example string 2: "you can also put " chars in single-line strings"
 
example namespace.example key: "example value 2"
# "namespaces" are entirely made up, they're just fancy names but it's still the
# recommended way to structure settings
 
# example comment
 
##
example multiline comment
just like strings, you can have extra # chars anywhere you want (as long as you don't 
want one of the lines in a comment to just be "##")
##
 
example array.0: "value 0"
example array.1: "value 1"
example array.2: "value 2"
example array.3: "value 3"
 
example nested array.0.name: "person 0"
example nested array.0.age: "age 0"
example nested array.0.friends.0: "person 1"
example nested array.0.friends.1: "person 2"
 
example nested array.1.name: "person 1"
example nested array.1.age: "age 1"
example nested array.1.friends.0: "person 0"
example nested array.1.friends.1: "person 2"
 
 
 
# examples for error handling:
 
example duplicate key: "this key will be kept"
example duplicate key: "this key will be commented"
 
invalid key "doesn't have any colon"
invalid value 1: "missing an ending quote
invalid value 2: missing a starting quote"
invalid value 3: missing both quotes
# empty multiline strings aren't allowed:
invalid value 4: "
 
invalid value 6: .3
 
invalid entry: empty # inline comments aren't allowed
 
##
invalid multiline comment, only these two lines will be commented because of this
 
# single-line comments cannot be invalid!
 
working key: "and even after all that, it can still keep parsing settings!"
 

See the specification Here

A settings file is intended to be represented in code using two main values: the layout vec and the values hashmap. The layout vec describes the layout of the settings file according to how it was when it was parsed, and modifying it at runtime isn’t recommended (because there should no need to do so). The values hashmap simply stores the key-value (String, ecf::Value) pairs, and this is what your code will interact with.

Also, I strongly recommend using an automatic format upgrading system like what’s shown in the example.

Re-exports

pub use data::*;

pub use utils::*;

Modules

data

All the data types used by this crate

utils

Utility functions for easy value management

Macros

get_bool

Returns the value as an int or runs a block of code with err containing the error

get_bool_mut

Returns the value as an int or runs a block of code with err containing the error

get_float

Returns the value as an int or runs a block of code with err containing the error

get_float_mut

Returns the value as an int or runs a block of code with err containing the error

get_int

Returns the value as an int or runs a block of code with err containing the error

get_int_mut

Returns the value as an int or runs a block of code with err containing the error

get_str

Returns the value as an int or runs a block of code with err containing the error

get_string_mut

Returns the value as an int or runs a block of code with err containing the error

Enums

MergeOptions

Used with merge_values()

Functions

format_settings

Converts a layout plus values into a formatted settings file, opposite of parse_settings()

merge_values

Automatically merge new setting values with existing setting values

parse_settings

Converts a settings file into a layout + values, opposite of format_settings()