.. _validation-plugin-howto-example-plugin:

Example ConfML validation plug-in

=================================

The example plug-in implements a simple ConfML validator class, and so demostrates

how ConfML validation can be extended by plug-ins.

The extra validation in this case is as follows: we have a requirement that if

a string-type ConfML setting's reference starts with ``FOO_``, its value

should also contain the string ``foo``. For example, consider the following

file:

.. code-block :: xml

    :linenos:

    <?xml version="1.0" encoding="UTF-8"?>

    <configuration xmlns="http://www.s60.com/xml/confml/1" name="ExampleValidatorTest">

        <feature ref="ExampleValidatorTest" name="Settings for example validator testing">

            <setting ref="SomeSetting" name="Some setting" type="string"/>

            <setting ref="FOO_SomeSetting1" name="FOO - Some setting 1" type="string"/>

            <setting ref="FOO_SomeSetting2" name="FOO - Some setting 2" type="string"/>

        </feature>

        <data>

            <ExampleValidatorTest>

                <SomeSetting>foo bar</SomeSetting>

                <FOO_SomeSetting1>abc foo</FOO_SomeSetting1>

                <FOO_SomeSetting2>abc123</FOO_SomeSetting2>

            </ExampleValidatorTest>

        </data>

    </configuration>

Here two settings are prefixed with ``FOO_``, but only one of them has ``foo``

in its value, thus our custom validator should report a warning for the value

on line 12.

Directory structure

-------------------

- ``plugins/`` - Root directory for all ConE plug-in sources

    - ``example/`` - Example plug-in package directory

        - ``ConeExampleValidatorPlugin/`` - Source for the example validator plug-in

            - ``examplevalidatorplugin/`` - Module directory containing all plug-in code

                - ``tests/`` - Unit tests and test data for the plug-in

                    - ``testdata/`` - Directory containing all test data needed by the test cases

                    - ``__init__.py`` - Test module initialization file

                    - ``runtests.py`` - Script for running all test cases

                    - ``unittest_validation.py`` - File containing test cases

                - ``__init__.py`` - Plug-in module initialization file

                - ``validators.py`` - Plug-in source file

            - ``setup.py`` - Setup script for packaging the plug-in into an .egg file

            - ``setup.cfg`` - Configuration file for ``setup.py``

Plug-in code

------------

validators.py

.............

This file defines the validator class. The validator simply goes through all

``ConfmlStringSetting`` instances in the configuration and checks their values.

.. literalinclude:: /../source/plugins/example/ConeExampleValidatorPlugin/examplevalidatorplugin/validators.py

   :linenos:

unittest_validation.py

......................

The tests for the plug-in simply contain one test case that tests the validator

with the example ConfML file shown earlier, using the ``assert_problem_list_equals_expected()``

method provided by the ``testautomation`` module.

.. literalinclude:: /../source/plugins/example/ConeExampleValidatorPlugin/examplevalidatorplugin/tests/unittest_validation.py

   :linenos:

Plug-in packaging

-----------------

The file ``setup.py`` handles the packaging of the plug-in into an egg file.

The most important thing here is the plug-in's entry point info. The list

of validator classes provided by the plug-in must be specified as an entry

point. The entry point group in this case is ``cone.plugins.confmlvalidators``.

.. literalinclude:: /../source/plugins/example/ConeExampleValidatorPlugin/setup.py

   :linenos: