.. _lblExamples:

Examples
========
This page contains the raw code + output of our examples.
For detailed explanations of what is going on please see
the :ref:`Quick Start<lblQuickStart>` guide.

.. contents::
   :depth: 1
   :local:
   :backlinks: none


.. _lblExample1:

Example 1 - Basic Example
-------------------------
See :ref:`Example: Basic Usage<lblQuickStartExampleBasic>`
in the QuickStart guide for a detailed explanation of this example.

Input File Listing: Example 1
+++++++++++++++++++++++++++++
.. literalinclude:: ../examples/ActiveConfigParser-example-01.ini
    :language: ini
    :linenos:

Code Listing: Example 1
+++++++++++++++++++++++
.. literalinclude:: ../examples/ActiveConfigParser-example-01.py
    :language: python
    :linenos:

Output: Example 1
+++++++++++++++++

Program execution output:

.. literalinclude:: ../examples/_ActiveConfigParser-example-01.log
    :linenos:

Parsed output file:

.. literalinclude:: ../examples/_ActiveConfigParser-example-01-parsed.ini
    :language: ini
    :linenos:


.. _lblExample2:

Example 2 - Cyclic Dependency
-----------------------------
In this example we add a cyclic dependency into the .ini file.
Generally this is a bad idea because a dependency graph of the
sections should createa  DAG but we try and handle it.

The default behaviour is to treat this as an accident that should
be noted so we generate a warning and we don't follow the back-edge
in our DFS traversal. This warning can be changed to an exception
by changing the ``exception_control_level`` parameter to **5**.

Input File Listing: Example 2
+++++++++++++++++++++++++++++
We add the ``use SECCTION-B`` operation into **SECTION-A** on line 4.

.. literalinclude:: ../examples/ActiveConfigParser-example-02.ini
    :language: ini
    :linenos:

Code Listing: Example 2
+++++++++++++++++++++++
.. literalinclude:: ../examples/ActiveConfigParser-example-02.py
    :language: python
    :linenos:

Output: Example 2
+++++++++++++++++
Here we see the output with the warning generated. The general format
of the warnings is controled by *ExceptionControl* but the general
format is to prefix the warning message lines with a ``!!`` to allow
easy searching in large log files.

.. literalinclude:: ../examples/_ActiveConfigParser-example-02.log
    :linenos:

The same as in Example 01, we also save out the *unrolled* version of the
parsed file. This differs from Example 01 in that we have ``key B1`` inserted
into *SECTION-A* on line 4.

.. literalinclude:: ../examples/_ActiveConfigParser-example-02-parsed.ini
    :language: ini
    :linenos:


.. _lblExample3:

Example 3 - Add Custom Operations
---------------------------------
See :ref:`Example: Add Custom Operations<lblQuickStartExampleAddCustomOperation>`
in the QuickStart guide for a detailed explanation of this example.

Input File Listing: Example 3
+++++++++++++++++++++++++++++

This .ini files includes the custom operation ``hello`` that we will create
in a custom class that extends ActiveConfigParser.

.. literalinclude:: ../examples/ActiveConfigParser-example-03.ini
    :language: ini
    :linenos:

Code Listing: Example 3
+++++++++++++++++++++++
The source code:

.. literalinclude:: ../examples/ActiveConfigParser-example-03.py
    :language: python
    :linenos:

The custom class ``MyActiveConfigParser`` is created to extend
ActiveConfigParser and we add our custom handler for the ``hello``
operation in the ``_handler_hello`` method.


Output: Example 3
+++++++++++++++++

.. literalinclude:: ../examples/_ActiveConfigParser-example-03.log
    :linenos: