# `ConfigParser`
[🔗](https://github.com/easco/configparser_ex/blob/main/lib/configparser.ex#L1)

  The ConfigParser library implements a parser for config files in the style of Windows INI,
  as parsed by the Python [configparser](https://docs.python.org/3/library/configparser.html) library.

  A note about `Config`
  ---------------------------

  This library is intended for compatibility in environments that are already
  using ini-style files in the format described above. If you are working in a
  pure Elixir environment, please consider using Elixir's built-in `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)

# `get`

  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 by `key` 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`

# `getboolean`

  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.

# `getfloat`

  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.

# `getint`

  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.

# `has_option?`

  returns true if the parse results define the given option in the
  section provided

# `has_section?`

  Returns `true` if the named section is found in the config parser results

# `options`

  Returns a List with the options, the keys, defined in the given section. If the
  section is not found, returns an empty List

# `parse_file`

  Accepts `config_file_path`, a file system path to a config file.
  Attempts to opens and parses the contents of that file.

# `parse_stream`

  Parses a stream whose elements should be strings representing the
  individual lines of a config file.

# `parse_string`

  Parse a string as if it was the content of a config file.

# `sections`

  Return a list of sections in the given config parser state

---

*Consult [api-reference.md](api-reference.md) for complete listing*