.. ComfyParse documentation master file, created by
   sphinx-quickstart on Tue May 28 21:53:19 2024.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

ComfyParse: A more comfy configuration system
=============================================

ComfyParse provides a simple, declarative interface for defining the structure,
parsing, and validation of your project's configuration files. Its interface
design and functionality are intentionally similar to and inspired by that of
the ``argparse`` standard library. It provides built-in as well as custom
validation, hooks for converting settings values from text, and automatic help
documentation generation. Parsed configurations are returned as a dictionary-like
namespace object which mirrors the defined schema and supports both attribute as
well as index-based access.

::

    >>> import comfyparse
    >>> parser = comfyparse.ComfyParser()
    >>> parser.add_setting("myint", required=True, convert=int)
    >>> parser.add_setting("mystr", required=False, default="abc")
    >>> parser.parse_from_string("myint=10; mystr='foo';")
    Namespace{"myint": 10, "mystr": "foo"}
    >>> parser.parse_from_string("myint=10;")
    Namespace{"myint": 10, "mystr": "abc"}

ComfyParse uses its own syntax inspired by the syntax used by Nginx for its
configurations, resulting in a minimal but high expressive grammar. 
Like ``argparse``, ComfyParse automatically validates the configuration and can
be directed to convert the settings values from strings, returning a 
dictionary-like namespace object mirroring the structure of the configuration.

::

    group servers {
        hosts = [ # end of line comments work
            "node01", "node02"
        ] % multiple flavors too
        timeout = 30.0
    }
    log_path=/var/log/my.log

The configuration language consists of statements and blocks of statements. 
Statements assign a string or list value to a setting name, and can either be
terminated with a newline or a ``;``. Lists can be nested within lists, and
string values can use ``'`` and ``"`` as quotes for values or settings names
containing literal quotes, escape characters, or whitespace, or just for visual
differentiation.

Blocks have a type or "kind", and uses braces to encapsulate a set of statements.
Blocks can also contain sub-blocks, defined using the ``ConfigBlock.add_block()``
method. Blocks can also be defined to expect an additional name parameter to
differentiate between multiple blocks of the same kind such as the ``group`` block
named ``servers`` in the above example. Block kinds and names can optionally be
quoted if needed or desired.

Comments can be made using ``#`` or ``%`` characters which treats the rest of the
line as a comment. Either comment marker can be used interchangably within the
same document. Aside from newlines ending a comment or terminating a statement,
all whitespace is ignored and arbitrary.

The example below sets up ComfyParse to handle a document such as the example above.

::

    parser = comfyparse.ComfyParser("demoapp")
    parser.add_setting("log_path", desc="The path where logs go.", required=True)
    parser.add_setting("log_level", default=1, choices=[1,2,3,4,5], convert=int)
    group_block = parser.add_block("group", named=True)
    group_block.add_setting("hosts", required=True)
    group_block.add_setting("timeout", default=5.0, convert=float)


Once a schema such as this has been defined, configuration strings can be parsed as follows

::

    # Directly from a string
    config = parser.parse_config_string(confstr)
    # Alternatively, from a file path
    config = parser.parse_config_file("/path/to/file")

Lastly, the parser can generate a reStructuredText string outlining the schema for automatic documentation purposes, or just to provide a starting point when writing your own documentation.

::

    parser.generate_docs()


Installation
============

ComfyParse is available on PyPI:

::

    pip install comfyparse

Or, you can find it on Github at https://github.com/Elemnir/comfyparse.

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   API Reference <apiref>


Indices and tables
==================

* :ref:`genindex`
* :ref:`search`