Crate libconfig [−] [src]

A library to parse and load configuration files.

This library parses and loads configuration files in much the same way as C/C++'s libconfig. At this time, it can only read and load configurations, but future plans include a much richer user API to allow other forms of interaction, such as manipulating values, writing the current configuration to a file, etc.

Getting started

A configuration file consists of a group of settings. A setting is a key/value pair, where the key is a string of the form [a-zA-Z][-a-zA-Z0-9_]*, and the value is anything represented by types::Value. In a configuration file, setting/value pairs are written as setting_name = value;. Possible values include primitive integer and floating point types, strings, arrays, lists, etc.

The library provides a bunch of methods to read the configuration data in the reader module. The possibilities include reading from a string, from a file, or from anything that implements the Read trait.

As of now, every reader will first attempt to read the whole configuration into memory, and only begins parsing once everything was read.

In case of error, the parser returns a config::error. On success, the parser returns a Config, which can then be used to browse the loaded data.

Browsing is typically done with the lookup_* methods implemented by Config. The lookup methods work with paths. Essentially, a path unambiguously describes the location of a setting.

For example, consider this input configuration file:

title = "My HTTP server";
 listen_ports = [ 80, 443 ];
 misc = {
     owner = "Chuck Norris";
     location = "CA";
     contact = {
         phone = "415-256-9999";
         // This is an array. Arrays start with `[` and end with `]`
         // Arrays are homogeneous and can only hold scalar data types.
         // See types::ScalarValue for further information
         emails = ["chuck@norris.com", "chuck.norris@gmail.com"];
     };
 };

At the top level, we have 3 settings: title, listen_ports and misc. misc is itself a group of settings. Each value in this configuration is reachable by a unique path of settings to follow. Each setting in a path is separated by .

Example: The path misc.contact.phone identifies the setting with value 415-256-9999.

Array and list types are indexed using [i] in a path.

Example: The path listen_ports.[1] identifies the setting with value 443.

Example: The path misc.contact.emails.[0] identifies the setting with value chuck@norris.com

Lists, as opposed to arrays, are heterogeneous and can store any data type, including other lists. Here's a setting consisting of a heterogeneous list:

// This is a list. Lists start with `(` and end with `)`
 // Lists are heterogeneous and can store any data type, including other lists
 a_setting = ("a string", // The first element is a string
              ((1, 2, 3)), // The 2nd element is a list storing a list of 3 integers
              misc = { x = 4; y = 3; } // 3rd element: a group
             );

Here are some valid paths for this example:

a_setting.[0] - returns the string a string

a_setting.[1].[0].[2] - returns the integer 3

a_setting.[2].misc.x - returns the integer 4

Adjacent string literals separated by whitespace, newlines and / or comments are automatically concatenated.

Example:

"a"/* a comment */" string"    " liter"

 // This is a commment

    "al"

is equivalent to:

"a string literal"

See the integration tests (in the tests/ directory) for sample use cases and more complex examples.

Environment variables

The crate has an ability to inject environment variables into the configuration file. That becomes possible using special syntax:

$"SOME_ENV_VAR_NAME"::str to inject the environment variables SOME_ENV_VAR_NAME as the string value. No additiocal changes are made ot the value.
$"SOME_ENV_VAR_NAME"::bool to inject the environment variable SOME_ENV_VAR_NAME as the boolean value. The value true or yes or on or 1 are converted into true otherwise into false.
$"SOME_ENV_VAR_NAME"::int to inject the environment variable SOME_ENV_VAR_NAME as the integer value. The successfully parsed value is injected as i32 or i64, depending on the format, otherwise 0i32 is injected.
$"SOME_ENV_VAR_NAME"::flt to inject the environment variable SOME_ENV_VAR_NAME as the floating value. The successfully parsed value is injected as f32 or f64, depending on the format, otherwise 0f32 is injected.
$"SOME_ENV_VAR_NAME"::auto or $"SOME_ENV_VAR_NAME" to inject the environment variable SOME_ENV_VAR_NAME and resolve the type automatically. Rules of the type auto-resolution:
- If the value is True or Yes or On then the result type is boolean True;
- If the value is False or No or Off then the result type is boolean False;
- If the value is floating then the result type is floating;
- If the value is integer then the result type is integer;
- Otherwise the result is string value.

Example:

#!/bin/sh
 export LOG_LEVEL=debug

// Configuration file
 log = {
       // Inject (use) the value of the environment variable LOG_LEVEL
       level = $"LOG_LEVEL"::str;
 }

Grammar

This section describes the configuration input format. The starting rule is conf.

 conf -> __ settings_list __

 settings_list -> // empty
                | setting settings_list
 setting -> __ name __ (":"|"=") __ value __ ";" __

 name -> [a-zA-Z][-a-zA-Z0-9_]*

 value -> scalar_value
        | array_value
        | list_value
        | group_value

 scalar_value -> boolean_scalar_value
               | floating64_scalar_value
               | floating32_scalar_value
               | integer64_scalar_value
               | integer32_scalar_value
               | str_scalar_value
               | auto_env_scalar_value

 boolean_scalar_value -> [Tt][Rr][Uu][Ee]
                       | [Yy][Ee][Ss]
                       | [Oo][Nn]
                       | [Ff][Aa][Ll][Ss][Ee]
                       | [Nn][Oo]
                       | [Oo][Ff][Ff]
                       | $"ENV_VAR_NAME"::bool

 floating64_scalar_value -> [+-]?([0-9]+\.[0-9]*|\.[0-9]+)([eE][+-]?[0-9]+)?"L"
                          | $"ENV_VAR_NAME"::flt

 floating32_scalar_value -> [+-]?([0-9]+\.[0-9]*|\.[0-9]+)([eE][+-]?[0-9]+)?
                          | $"ENV_VAR_NAME"::flt

 integer32_scalar_value -> [+-]?[0-9]+
                         | $"ENV_VAR_NAME"::int

 integer64_scalar_value -> [+-]?[0-9]+"L"
                         | $"ENV_VAR_NAME"::int

 str_scalar_value -> __ str_literal __
                   | __ str_literal __ str_scalar_value
                   | $"ENV_VAR_NAME"::str

 auto_env_scalar_value -> $"ENV_VAR_NAME"::auto
                        | $"ENV_VAR_NAME"

 str_literal -> "\"" ([^\"\\]|(("\\r"|"\\n"|"\\t"|"\\\""|"\\\\")))* "\""

 array_value -> "["
                (bool_array |
                 flt64_array | flt32_array |
                 int64_array | int32_array |
                 str_array)
                "]"
              | "[" __ "]"

 bool_array -> __ boolean_scalar_value __
             | __ boolean_scalar_value __ "," __ bool_array

 flt64_array -> __ floating64_scalar_value __
              | __ floating64_scalar_value __ "," __ flt64_array

 flt32_array -> __ floating32_scalar_value __
              | __ floating32_scalar_value __ "," __ flt32_array
 int64_array -> __ integer64_scalar_value __
              | __ integer64_scalar_value __ "," __ int64_array

 int32_array -> __ integer32_scalar_value __
              | __ integer32_scalar_value __ "," __ int32_array

 str_array -> __ str_scalar_value __
            | __ str_scalar_value __ "," __ str_array

 list_value -> "(" __ ")"
             | "(" list_elements ")"

 list_elements -> __ value __
                | __ value __ "," __ list_elements

 group_value -> "{" settings_list "}"

 __ -> // empty
     | whitespace __
     | eol __
     | comment __

 whitespace -> [\s\t]

 eol -> "\r\n"
      | "\n"

 comment -> single_line_comment
          | multi_line_comment

 single_line_comment -> ("//"|"#")[^\n]*"\n"?

 multi_line_comment -> "/*"([^*]|"*"[^/])*"*/"

Modules

error	Errors that can occur while parsing a configuration
reader	Reader types to parse a configuration.
types	Internal types used to represent a configuration and corresponding primitives to browse it