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

.. note::

    RuleML v3 is now the officially supported RuleML version.

    Support for versions 1 and 2 is still present in ConE, but they will not

    be maintained anymore. If you have e.g. a RuleML v2 file and require some

    new functionality, the new functionality will be added to RuleML v3 and

    you will need to update your RuleML file to use version 3.

    Updating should be easy, since the biggest change is setting reference

    syntax. Simply add ``${}`` around all setting references in the rules.

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

This page describes how to use the ConE Rule plugin. The plug-in provides

support for RuleML files, which can be used to execute rules during output

generation. The main use for RuleML is modifying the values of ConfML settings

on run-time based on the values of other settings.

The rule plug-in registers the ImplML namespace for defining rules, and the

RuleML-specific file extension:

  * Namespace: ``http://www.s60.com/xml/ruleml/3``

  * File extension: ``ruleml``

.. note::

   More information about :ref:`file extensions <implml-file-extensions>`. 

Usage

-----

A RuleML file is simply an XML file that defines a set of rules. For example:

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

    <ruleml xmlns="http://www.s60.com/xml/ruleml/3">

        <rule>${SomeFeature.SomeSetting} == 'testing' configures ${SomeFeature.SomeOtherSetting} = 5</rule>

        <rule>${SomeFeature.SomeSetting} == 'xyz' configures ${SomeFeature.SomeOtherSetting} = 6</rule>

    </ruleml>

The above example sets the value of the setting ``SomeFeature.SomeOtherSetting``

to the integer value ``5`` or ``6`` if the value of ``SomeFeature.SomeSetting`` is

one of the strings ``testing`` or ``xyz``.

Rules can also contain multiple operations in a single rule, and can span

multiple lines to make the rule more readable. For example:

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

    <ruleml xmlns="http://www.s60.com/xml/ruleml/3">

        <rule>

            ${SomeFeature.SomeSetting} == 'testing' configures

                ${SomeFeature.SomeOtherSetting} = 5 and

                ${SomeFeature.SomeOtherSetting2} = 6 and

                ${SomeFeature.SomeOtherSetting3} = 7

        </rule>

    </ruleml>

Sometimes the case is that the rule should be executed always, regardless of

the values of any other settings. To do this you can simply specify ``True``

as the left-hand side expression:

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

    <ruleml xmlns="http://www.s60.com/xml/ruleml/3">

        <rule>True configures ${SomeFeature.SomeOtherSetting} = 'Hello!'</rule>

    </ruleml>

Python expressions in rules

^^^^^^^^^^^^^^^^^^^^^^^^^^^

RuleML has an extension to the basic rule syntax, which allows any `Python <http://www.python.org/doc/2.5/>`_

expressions to be used. These can be used to create more complex logic into

rules than is possible with standard rule expressions. The Python expressions

are defined between ``{%`` and ``%}``, and can be used in place of normal

value expressions.

You can access global ruleml namespace, from which you can find Configuration and Generation Context of the active execution.

 * ruleml.configuration - links to `Configuration <../../../docbuild/epydoc/cone.public.api.Configuration-class.html>`_ object.

 * ruleml.context - links to `Generation Context <../../../docbuild/epydoc/cone.public.plugin.GenerationContext-class.html>`_ object.

*Examples of using Python scripts inside ruleml files:*

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

    <ruleml xmlns="http://www.s60.com/xml/ruleml/3">

        <rule>

            True configures ${SomeFeature.SomeOtherSetting} = {% 2 ** 16 %}

        </rule>

    </ruleml>

This sets the value of ``SomeFeature.SomeOtherSetting`` to the evaluated value

of the Python expression ``2 ** 16``, which is 65536.

Obviously, simple expressions like this cannot do much, but an expression can

also be a function call, and functions can do almost anything. Functions (and 

also any other globals) can be specified using ``<eval_globals>`` elements.

For example:

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

    <ruleml xmlns="http://www.s60.com/xml/ruleml/3">

        <rule>

            True configures ${SomeFeature.SomeOtherSetting} = {% power(2, 16) %}

        </rule>

        <eval_globals>

    def power(x, y):

        result = 1

        for i in xrange(y):

            result *= x

        return result

        </eval_globals>

    </ruleml>

This does the same thing as the previous example, except that it uses a custom

function to do it.

It is also possible to use standard Python libraries or the

`ConE API <../../epydoc/index.html>`_ from ``<eval_globals>``, and also

some RuleML-specific things. Ruleml has all data from 

Configuration and Generation Context classes of the active execution. For example:

.. code-block:: xml

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

    <ruleml xmlns="http://www.s60.com/xml/ruleml/3">

        <rule>

            True configures ${SomeFeature.SomeOtherSetting} = {% power(2, 16) %}

        </rule>

        <eval_globals>

    # Import the standard library urllib2 to do operations on URLs

    import urllib2

    # Import the ConE API

    from cone.public import api

    def get_project_path():

        # The current configuration is available in ruleml.configuration

        config = ruleml.configuration

        # Return the path of the storage the current project is in

        project = config.get_project()

        return project.storage.get_path()

        </eval_globals>

    </ruleml>

In this example configuration is got from ruleml. Generation Context can be 

accessed in the same way, ruleml.context will have all data stored in the 

Generation Context object.

Generation Context values can be accessed inside the Python expressions using the

ruleml.context like ruleml.context.output.

This example uses the Generation Context to get defined output folder. 

See how to access the data from the code example below.

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

    <ruleml xmlns="http://www.s60.com/xml/ruleml/3">

        <rule>

            True configures ${SomeFeature.output} = {% get_output_folder() %}

        </rule>

        <eval_globals>

    def get_output_folder():

        output = ruleml.context.output

        return output

        </eval_globals>

    </ruleml>

Accessing ConfML values inside Python expressions

'''''''''''''''''''''''''''''''''''''''''''''''''

ConfML setting values can be accessed inside the Python expressions using the

same notation as elsewhere in the rules, i.e. using ``${`` and ``}``.

For example:

.. code-block:: xml

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

    <ruleml xmlns="http://www.s60.com/xml/ruleml/3">

        <rule>

            ${SomeFeature.SomeSetting} == 'testing' configures ${SomeFeature.SomeOtherSetting} = {% ${SomeFeature.SomeSetting}.upper() %}

        </rule>

    </ruleml>

This sets the value of ``SomeFeature.SomeOtherSetting`` to 'TESTING'.

Accessing feature objects inside Python expressions

'''''''''''''''''''''''''''''''''''''''''''''''''''

Sometimes it is necessary to access the actual feature (or setting) object that

ConE uses internally to perform more complex operations. This can be done

similarly to accessing the setting values, the only difference is that the

setting reference needs to be surrounded by ``@{}``. For example:

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

    <ruleml xmlns="http://www.s60.com/xml/ruleml/3">

        <rule>

            True configures ${SomeFeature.SomeOtherSetting} = {% get_location(@{SomeFeature.SomeSetting}) %}

        </rule>

        <eval_globals>

    from cone.public import api

    def get_location(setting):

        parent_config = setting._find_parent(type=api.Configuration)

        return parent_config.get_path()

        </eval_globals>

    </ruleml>

This example uses the ConE API to find the location (ConfML file) where the

given setting is defined.

Defining functions in a separate .py file

'''''''''''''''''''''''''''''''''''''''''

Defining the Python functions used in the rules in an ``<eval_globals>`` element

can quickly become unwieldy for larger functions:

- Things like ``<`` need to escaped using the corresponding XML entity references

- Syntax highlighting is not available

- Writing and running unit tests for the functions is not possible

For these reasons, the code of an ``<eval_globals>`` element can also be

specified in a separate Python file using the ``file`` attribute. For example:

.. code-block:: xml

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

    <ruleml xmlns="http://www.s60.com/xml/ruleml/3">

        <rule>

            True configures ${SomeFeature.SomeOtherSetting} = {% some_very_complex_operation(

                @{SomeFeature.SomeSetting1},

                ${SomeFeature.SomeSetting2},

                ${SomeFeature.SomeSetting3}) %}

        </rule>

        <eval_globals file="scripts/complex_function.py"/>

    </ruleml>

The path specified in the ``file`` attribute is relative to the implementation

file where the rule is specified, so if the RuleML file in this example was

located in ``assets/example/implml/some_rule.ruleml``, the referenced Python

file would be ``assets/example/implml/scripts/complex_function.py``.

---

This will be updated based on any questions.