ConfigParser (ConfigParser for Elixir v4.0.0) View Source
The ConfigParser library implements a parser for config files in the style of Windows INI, as parsed by the Python configparser library.
A note about Mix.Config
This library is intended for compatibility in environments that are already
using config files in the format described above. If you are working in a
pure Elixir environment, please consider using Mix.Config
instead as it is
part of the core library and provides similar functionality.
Basic Usage
The ConfigParser
module includes routines that can parse a file, the contents of a string, or from a stream of lines.
To parse the content of a config file call the parse_file
function and pass the file's path:
{:ok, parse_result} = ConfigParser.parse_file("/path/to/file")
To parse config information out of a string, call the parse_string
method:
{:ok, parse_result} = ConfigParser.parse_string("""
[interesting_config]
config_key = some interesting value
""")
Given a stream whose elements represent the successive lines of a config file, the library can parse the content of the stream:
fake_stream = ["[section]", "key1 = value2", "key2:value2"]
|> Stream.map(&(&1))
{:ok, parse_result} = ConfigParser.parse_stream(fake_stream)
As shown, the result of doing the parsing is a tuple. If successful, the first element of the tuple is :ok
and the second element is the parsed result.
If the parser encounters an error, then the first part of the tuple will be the atom :error
and the second element will be a string describing the error that was encountered:
{:error, "Syntax Error on line 3"}
Parser Options
Starting with Version 3 of the library, it is possible to pass options to the parser:
Option | Value | Effect |
---|---|---|
join_continuations | :with_newline | The parser joins the lines of multi-line values with a newline. This is the default and matches the behavior of Python ConfigParser. |
join_continuations | :with_space | The parser joins the lines of multi-line values with a space. This is the default behavior of the library prior to version 3. |
You may add options as keyword arguments to the end of the parse_file
, parse_string
, or parse_stream
functions
{:ok, parse_result} = ConfigParser.parse_file("/path/to/file", join_continuations: :with_newline)
Link to this section Summary
Functions
Return the value for the configuration option with the given key
.
This is a convenience routine which calls ConfigParser.get
then tries to construct a boolean value from the result.
This is a convenience routine which calls ConfigParser.get
then tries to construct a float value from the result.
This is a convenience routine which calls ConfigParser.get
then tries to construct a integer value from the result.
returns true if the parse results define the given option in the section provided
Returns true
if the named section is found in the config parser results
Returns a List with the options, the keys, defined in the given section. If the section is not found, returns an empty List
Accepts config_file_path
, a file system path to a config file.
Attempts to opens and parses the contents of that file.
Parses a stream whose elements should be strings representing the individual lines of a config file.
Parse a string as if it was the content of a config file.
Return a list of sections in the given config parser state
Link to this section Functions
Return the value for the configuration option with the given key
.
You can change the way values are looked up using the search_options
map.
The following keys are recognized:
:raw
- reserved for future enhancements:vars
- a map of keys and values.:fallback
- a value to return if the option given bykey
is not found
The routine searches for a value with the given key
in the :vars
map
if provided, then in the given section from the parse result.
If no value is found, and the options
map has a :fallback
key, the
value associated with that key will be returned.
If all else fails, the routine returns nil
This is a convenience routine which calls ConfigParser.get
then tries to construct a boolean value from the result.
An option value of "true", "1", "yes", or "on" evaluates to true An options value of "false", "0", "no", or "off" evaluates to false
See ConfigParser.get
for explanations of the options.
This is a convenience routine which calls ConfigParser.get
then tries to construct a float value from the result.
See ConfigParser.get
for explanations of the options.
This is a convenience routine which calls ConfigParser.get
then tries to construct a integer value from the result.
See ConfigParser.get
for explanations of the options.
returns true if the parse results define the given option in the section provided
Returns true
if the named section is found in the config parser results
Returns a List with the options, the keys, defined in the given section. If the section is not found, returns an empty List
Accepts config_file_path
, a file system path to a config file.
Attempts to opens and parses the contents of that file.
Parses a stream whose elements should be strings representing the individual lines of a config file.
Parse a string as if it was the content of a config file.
Return a list of sections in the given config parser state