INI
===

A simple INI parser and emitter.

.. admonition:: Info

   To use declarations from this page, include the ``<essence/ini.hpp>`` header.

.. cpp:namespace-push:: essence

.. cpp:class:: ini::exception: public std::exception

   Exception type for INI parsing.

.. cpp:class:: ini::field

   Represents a single key-value pair.

   .. cpp:member:: std::string key

      The key part of the key-value pair.

   .. cpp:member:: std::string value

      The value part of the key-value pair.

   .. cpp:function:: field::field(std::string k, std::string v)

      Default constructor, accepting two strings.

   .. cpp:function:: field::field(std::pair<std::string, std::string>)

      Alternative constructor, accepting a ``std::pair`` of strings.

   .. cpp:function:: std::string field::string() const

      Get a string representation of the field.

   .. cpp:function:: std::string field::pretty() const

      Get a colorized string representation of the field.

   .. cpp:function:: template<typename T> \
                     requires anyof<T, i64, f64, bool, null>
                     std::optional<T> as()

      Attempt to parse the field's value as ``T``.

.. cpp:class:: ini::section: public std::vector<ini::field>

   Represents a named list of key-value pairs.

   .. cpp:member:: std::string name

      The section's name.

   .. cpp:function:: section::section(std::string pname)

      Default constructor, accepting the section name as a string.

   .. cpp:function:: std::string string() const

      Get a string representation of the section.

   .. cpp:function:: std::string pretty() const

      Get a colorized string representation of the section.

.. cpp:class:: ini::document: public std::vector<ini::section>

   Represents the entirety of an INI file.

   .. cpp:member:: ini::section top = ini::section("__TOP_LEVEL__")

      The outer, pseudo-unnamed section of the INI file.

   .. cpp:function:: ini::section& operator[](std::string_view name)

      Get a section by name.

   .. cpp:function:: std::string string() const

      Get a string representation of the document.

   .. cpp:function:: std::string pretty() const

      Get a colorized string representation of the document.

.. cpp:class:: ini::parser

   A proxy object for parsing an input file.

   .. cpp:function:: ini::document parse(const fs::path& path)

      Parse the file at ``path``

   .. cpp:function:: ini::document parse(std::istream& is)

      Parse input from stream ``is``.

.. cpp:class:: ini::writer

   A proxy object for emitting INI documents.

   .. cpp:function:: writer::writer(const document& doc)

   .. cpp:function:: ini::writer& write(const fs::path& path)

      Write the INI document to file ``path``.

   .. cpp:function:: ini::writer& write(std::ostream& os)

      Write the INI document to stream ``os``.