configparser
This crate provides the Ini
struct which implements a basic configuration language which provides a structure similar to what’s found in Windows' ini
files. You can use this to write Rust programs which can be customized by end users easily.
This is a simple configuration parsing utility with no dependencies built on Rust. It is inspired by Python's configparser
.
The current release is stable and changes will take place at a slower pace. We'll be keeping semver in mind for future releases as well.
Quick Start
A basic ini
-syntax file (we say ini-syntax files because the files don't need to be necessarily *.ini
) looks like this:
[DEFAULT]
key1 = value1
pizzatime = yes
cost = 9
[topsecrets]
nuclear launch codes = topsecret
[github.com]
User = QEDK
Essentially, the syntax consists of sections, each of which can which contains keys with values. The Ini
struct can read and write such values to
strings as well as files.
Installation
You can install this easily via cargo
by including it in your Cargo.toml
file like:
[]
= "1.0.0"
Supported datatypes
configparser
does not guess the datatype of values in configuration files and stores everything as strings. However, some datatypes are so common
that it's a safe bet that some values need to be parsed in other types. For this, the Ini
struct provides easy functions like getint()
, getuint()
,
getfloat()
and getbool()
. The only bit of extra magic involved is that the getbool()
function will treat boolean values case-insensitively (so
true
is the same as True
just like TRUE
). The crate also provides a stronger getboolcoerce()
function that parses more values (such as T
, yes
and 0
, all case-insensitively), the function's documentation will give you the exact details.
use Ini;
let mut config = new;
config.read;
let my_value = config.getint.unwrap.unwrap;
assert_eq!; // value accessible!
//You can ofcourse just choose to parse the values yourself:
let my_string = String from;
let my_int = my_string..unwrap;
Supported ini
file structure
A configuration file can consist of sections, each led by a [section-name]
header, followed by key-value entries separated by a =
. By default, section names and key names are case-insensitive. All leading and trailing whitespace is removed from stored keys, values and section names.
Key values can be omitted, in which case the key-value delimiter (=
) may also be left out (but this is different from putting a delimiter, we'll
explain it later). You can use comment symbols (;
and #
to denote comments). This can be configured with the set_comment_symbols()
method in the
API. Keep in mind that key-value pairs or section headers cannot span multiple lines.
Owing to how ini files usually are, this means that [
, ]
, =
, ;
and #
are special symbols (this crate will allow you to use ]
sparingly).
Let's take for example:
[section headers are case-insensitive]
[ section headers are case-insensitive ]
are the section headers above same? = yes
sectionheaders_and_keysarestored_in_lowercase? = yes
keys_are_also_case_insensitive = Values are case sensitive
;anything after a comment symbol is ignored
#this is also a comment
spaces in keys=allowed ;and everything before this is still valid!
spaces in values=allowed as well
spaces around the delimiter = also OK
[All values are strings]
values like this= 0000
or this= 0.999
are they treated as numbers? = no
integers, floats and booleans are held as= strings
[value-less?]
a_valueless_key_has_None
this key has an empty string value has Some("") =
[indented sections]
can_values_be_as_well = True
purpose = formatting for readability
is_this_same = yes
is_this_same=yes
An important thing to note is that values with the same keys will get updated, this means that the last inserted key (whether that's a section header
or property key) is the one that remains in the HashMap
.
The only bit of magic the API does is the section-less properties are put in a section called "default". You can configure this variable via the API.
Keep in mind that a section named "default" is also treated as sectionless so the output files remains consistent with no section header.
Usage
Let's take another simple ini
file and talk about working with it:
[topsecret]
KFC = the secret herb is orega-
[values]
Uint = 31415
If you read the above sections carefully, you'll know that 1) all the keys are stored in lowercase, 2) get()
can make access in a case-insensitive
manner and 3) we can use getuint()
to parse the Uint
value into an u64
. Let's see that in action.
use Ini;
use Error;
The Ini
struct offers great support for type conversion and type setting safely, as well as map accesses. See the API for more verbose documentation.
License
Licensed under either of
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
- Lesser General Public license v3.0 or later (LICENSE-LGPL or https://www.gnu.org/licenses/lgpl-3.0.html)
at your option.
Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the LGPL-3.0 license, shall be dual licensed as above, without any additional terms or conditions.
Changelog
Old changelogs are in CHANGELOG.md.
- 0.12.0 (BETA 8)
- New function added,
writes()
to support writing configuration to a string. - More doctests passed.
- New function added,
- 0.13.0 (BETA 9)
- New functions added,
clear()
andremove_section()
to make handling similar to hashmaps. - Docs fixed. On track to stable.
- New functions added,
- 0.13.1 (yanked)
- New function added,
remove_key()
to remove a key from a section - All doctests passing!
- New function added,
- 0.13.2 (FINAL BETA)
- Erroneous docs fixed.
- Final release before stable.
- 1.0.0 (STABLE)
- Dropped support for
ini::load()
- Updated tests
- Dropped support for
Future plans
- Support for appending sections, coercing them as well.