Struct Config 

pub struct Config { /* private fields */ }

A libconfig configuration document.

Config wraps the root Value::Group of a document. Per the grammar, a configuration is a list of settings — the top level is never wrapped in braces; braces delimit nested groups only.

Create an empty config with Config::new, parse from a string with Config::from_str, or wrap an existing group Value with Config::try_from(value).

Config derefs to Value, so all Value methods (indexing, lookup, set, remove) work directly on a Config.

Examples

use libconfig::{Config, Value};

let mut config = Config::new();
config.set("name", Value::String("test".into()));
config.set("version", Value::Integer(42));

assert_eq!(config["name"], "test");
assert_eq!(config["version"], 42);

let output = config.to_string().unwrap();
assert_eq!(output, "name = \"test\";\nversion = 42;");

Implementations

impl Config

pub fn new() -> Self

Create a new empty Config.

pub fn into_value(self) -> Value

Consumes the config and returns its root value.

pub fn from_str(s: &str) -> Result<Config>

Parse a libconfig string into a Config.

The document root must be a setting list (or empty); wrapping the top level in braces is a syntax error per the grammar.

Examples

use libconfig::Config;

let config = Config::from_str("a = 1; b = 2;").unwrap();
assert_eq!(config["a"], 1);

// Braces around the top level are not part of the grammar
assert!(Config::from_str("{ a = 1; }").is_err());

pub fn from_str_with_include_dir<P: AsRef<Path>>( s: &str, include_dir: P, ) -> Result<Config>

Like Config::from_str, but relative paths in @include directives are resolved against include_dir (the equivalent of the C library’s config_set_include_dir()).

pub fn from_str_with_include_fn<F>(s: &str, resolver: F) -> Result<Config>

where F: Fn(&str) -> Result<Vec<PathBuf>>,

Like Config::from_str, but @include directives are resolved by resolver: it receives the directive’s path string and returns the ordered list of files to inline (the equivalent of the C library’s config_set_include_func()). This enables wildcard expansion, variable substitution, or search paths:

use libconfig::Config;

// Resolve includes against a search path
let dirs = ["/etc/myapp", "/usr/share/myapp"];
let config = Config::from_str_with_include_fn(
    "@include \"extra.cfg\"\n",
    |path| {
        dirs.iter()
            .map(|d| std::path::Path::new(d).join(path))
            .find(|p| p.exists())
            .map(|p| vec![p])
            .ok_or_else(|| {
                libconfig::ErrorKind::Include(format!("'{path}' not found")).into()
            })
    },
);

Files returned by the resolver are scanned for nested @include directives (resolved by the same function), up to the manual’s limit of 10 levels.

pub fn from_file<P: AsRef<Path>>(path: P) -> Result<Config>

Read and parse a libconfig file into a Config, automatically detecting whether the input uses an implicit or explicit group.

@include directives are processed while reading; as in the C library, relative include paths are resolved against the current working directory unless an include directory is set with Config::from_file_with_include_dir.

Examples

use libconfig::Config;

let config = Config::from_file("settings.cfg").unwrap();
println!("{}", config["name"]);

pub fn from_file_with_include_dir<P: AsRef<Path>, Q: AsRef<Path>>( path: P, include_dir: Q, ) -> Result<Config>

Like Config::from_file, but relative paths in @include directives are resolved against include_dir.

pub fn from_file_with_include_fn<P: AsRef<Path>, F>( path: P, resolver: F, ) -> Result<Config>

where F: Fn(&str) -> Result<Vec<PathBuf>>,

Like Config::from_file, but @include directives are resolved by resolver (see Config::from_str_with_include_fn).

pub fn to_string(&self) -> Result<String>

Serialize this config to a libconfig string. The top level is an implicit setting list; nested groups are brace-delimited.

Errors

Returns an error if the root is not a group (possible via DerefMut mutation), if a setting name is not grammar-valid, or if a value has no libconfig representation (e.g. a non-finite float).

pub fn to_string_with_options(&self, options: &WriteOptions) -> Result<String>

Like Config::to_string, but formatted per the given crate::WriteOptions.

pub fn to_file<P: AsRef<Path>>(&self, path: P) -> Result<()>

Serialize this config and write it to the file at path, replacing any existing contents. A trailing newline is appended.

Errors

Returns an error if serialization fails (see Config::to_string) or the file cannot be written (ErrorKind::Io).

pub fn to_file_with_options<P: AsRef<Path>>( &self, path: P, options: &WriteOptions, ) -> Result<()>

Like Config::to_file, but formatted per the given crate::WriteOptions.

Methods from Deref<Target = Value>

pub fn is_bool(&self) -> bool

Returns true if the value is a boolean

pub fn is_integer(&self) -> bool

Returns true if the value is an integer (32-bit or 64-bit)

pub fn is_i32(&self) -> bool

Returns true if the value is a 32-bit integer

pub fn is_i64(&self) -> bool

Returns true if the value is a 64-bit integer

pub fn is_float(&self) -> bool

Returns true if the value is a float

pub fn is_number(&self) -> bool

Returns true if the value is a number (integer or float)

pub fn is_string(&self) -> bool

Returns true if the value is a string

pub fn is_array(&self) -> bool

Returns true if the value is an array

pub fn is_list(&self) -> bool

Returns true if the value is a list

pub fn is_group(&self) -> bool

Returns true if the value is a group (object)

pub fn as_bool(&self) -> Option<bool>

If the value is a boolean, returns it. Returns None otherwise.

pub fn as_i32(&self) -> Option<i32>

If the value is an integer, returns it as i32. Returns None otherwise.

pub fn as_i64(&self) -> Option<i64>

If the value is an integer, returns it as i64. Returns None otherwise.

pub fn as_f64(&self) -> Option<f64>

If the value is a float, returns it. Integers are converted to their float value (a lossless promotion for Integer; Integer64 values beyond 2^53 lose precision). Returns None for non-numeric values.

pub fn as_str(&self) -> Option<&str>

If the value is a string, returns a reference to it. Returns None otherwise.

pub fn as_array(&self) -> Option<&Vec<Value>>

If the value is an array or a list, returns a reference to its elements. Use Value::is_array/Value::is_list to distinguish the two aggregate kinds. Returns None otherwise.

pub fn as_array_mut(&mut self) -> Option<&mut Vec<Value>>

If the value is an array or a list, returns a mutable reference to its elements. Returns None otherwise.

pub fn as_group(&self) -> Option<&Map>

If the value is a group, returns a reference to the map. Returns None otherwise.

pub fn as_group_mut(&mut self) -> Option<&mut Map>

If the value is a group, returns a mutable reference to the map. Returns None otherwise.

Note: keys inserted directly into the map are not validated; keys that are not grammar-valid setting names will fail at serialization time. Prefer Value::set, which validates.

pub fn get<S: AsRef<str>>(&self, key: S) -> Option<&Value>

Gets a reference to a value in a group by key

Returns None if the value is not a group or the key doesn’t exist.

pub fn get_mut<S: AsRef<str>>(&mut self, key: S) -> Option<&mut Value>

Gets a mutable reference to a value in a group by key

Returns None if the value is not a group or the key doesn’t exist.

pub fn get_index(&self, index: usize) -> Option<&Value>

Gets a reference to a value in an array/list by index

Returns None if the value is not an array/list or the index is out of bounds.

pub fn get_index_mut(&mut self, index: usize) -> Option<&mut Value>

Gets a mutable reference to a value in an array/list by index

Returns None if the value is not an array/list or the index is out of bounds.

pub fn lookup(&self, path: &str) -> Option<&Value>

Looks up a value by a dotted path like “application.window.title”

Returns None if any part of the path doesn’t exist.

Examples

use libconfig::Value;

let config = r#"
    application = {
        window = {
            title = "My App";
        };
    };
"#;

let v = Value::from_str(config).unwrap();
assert_eq!(v.lookup("application.window.title").and_then(|v| v.as_str()), Some("My App"));

pub fn lookup_mut(&mut self, path: &str) -> Option<&mut Value>

Looks up a mutable reference to a value by a dotted path like “application.window.title”

Returns None if any part of the path doesn’t exist. Supports both bracket notation (items.[0]) and bare numeric (items.0).

Examples

use libconfig::Value;

let config = r#"
    ports = [80, 443];
"#;

let mut v = Value::from_str(config).unwrap();
*v.lookup_mut("ports.[0]").unwrap() = Value::Integer(8080);
assert_eq!(v["ports.0"], 8080);

pub fn set(&mut self, path: &str, value: impl Into<Value>) -> Result<()>

Sets a value at the given path, creating intermediate Group nodes as needed.

The value may be anything convertible into a Value (integers, floats, booleans, strings, or a Value itself). Array/list indices must refer to existing elements (no auto-extension).

Errors

• ErrorKind::InvalidPath if the path is malformed
• ErrorKind::InvalidSettingName if a key segment is not a valid setting name ([A-Za-z*][-A-Za-z0-9_*]*)
• ErrorKind::PathTraversal if an intermediate value has the wrong type or an index is out of bounds

Examples

use libconfig::{Map, Value};

let mut v = Value::Group(Map::new());
v.set("a.b.c", 42).unwrap();
assert_eq!(v.lookup("a.b.c").unwrap().as_i32(), Some(42));

pub fn remove(&mut self, path: &str) -> Option<Value>

Removes a value at the given path and returns it.

For group members, the key-value pair is removed. For array/list elements, the element is removed and subsequent elements shift down.

Returns None if the path is invalid or the target doesn’t exist.

Examples

use libconfig::Value;

let mut v = Value::from_str(r#"a = 1; b = 2; c = 3;"#).unwrap();
let removed = v.remove("b");
assert_eq!(removed, Some(Value::Integer(2)));
assert!(v.lookup("b").is_none());

Trait Implementations

impl Clone for Config

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Config

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Config

fn default() -> Self

Returns the “default value” for a type.

impl Deref for Config

type Target = Value

The resulting type after dereferencing.

fn deref(&self) -> &Value

Dereferences the value.

impl DerefMut for Config

fn deref_mut(&mut self) -> &mut Value

Mutably dereferences the value.

impl<'de> Deserialize<'de> for Config

fn deserialize<D>(deserializer: D) -> Result<Config, D::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for Config

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl FromStr for Config

type Err = Error

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Config>

Parses a string s to return a value of this type.

impl PartialEq for Config

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl Serialize for Config

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for Config

impl TryFrom<Value> for Config

fn try_from(value: Value) -> Result<Config>

Wraps a Value as a configuration document.

Errors

Returns ErrorKind::ExpectedGroup if the value is not a Value::Group — a configuration document is a group of settings.

type Error = Error

The type returned in the event of a conversion error.