Merge changes to system model generator to SF tip.
.. _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: