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 experimental, this means that future releases will be swift until we reach stable
(1.0.0).
The codebase is thus subject to change for now.
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.
Supported datatypes
configparser
does not guess the datatype of values in configuration files and stores everything as strings. If you need other datatypes, you should
parse them yourself. It's planned to implement getters for primitive datatypes in the future.
let my_int = my_string..unwrap;
let my_str = my_string.as_str;
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). 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:
[Basic Values is the same thing]
[ Basic Values is the same thing ]
key1=value1
spaces in keys=allowed
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 like 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
.
Installation
You can install this easily via cargo
by including it in your Cargo.toml
file like:
[]
= "0.5.0"
Usage
You can load an ini
-file easily and parse it like:
use Ini;
use HashMap;
The Ini
struct is the way to go forward and will soon have more features, such as reading from a string, insertion, deletion, index access
as well as support for comments.
License
Licensed under either of
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
- Lesser General Public license v3.0 (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.3.0
- Added
get()
for getting values from the map directly. Docs expanded as well. - Mark
ini::load()
for deprecation.
- Added
- 0.3.1
- Updated docs.
- All parameters now trimmed before insertion.
- Converted
ini::load()
into a wrapper aroundIni
.
- 0.4.0
- Changed
Ini::load()
to return anOk(map)
with a clone of the storedHashMap
.
- Changed
- 0.4.1
- Fixed and added docs.
- 0.5.0 (BETA)
- Changelog added.
- Support for value-less keys.
HashMap
values are nowOption<String>
instead ofString
to denote empty values vs. no values.- Documentation greatly improved.
- Syntax docs provided.
new()
andget()
methods are simplified.
Future plans
- Support for
ini::load()
will be dropped in the next major releaser per SemVer (i.e. 1.0.0)- It will be replaced with a macro for a similar functionality.
- It has been marked as deprecated.
- More functions for
Ini
struct, such as reading from a string, insertion and deletion. - Support for comments
- Support for value-parsing
- Index access