/*!
    \page rules.html
    \title Rules

    \annotatedlist rules

    \section1 Introduction

    Rules define all the logic in nymea.
    A rule is composed by a set of \l{Event}{Events}, \l{State}{States} and \l{Action}{Actions}.

    This diagram shows how rules are composed and interpreted by
    the \l{nymeaserver::RuleEngine}.

    \image Rules_definition.svg "Rules definition"

    A basic concept of a \l{nymeaserver::Rule} is the trigger path. This is the path that defines when a \l{nymeaserver::Rule}
    is triggered for evaluation. Each element added on a trigger path (either red or blue) has the possibility to trigger the
    \l{nymeaserver::RuleEngine} to evaluate the complete rule and ultimately execute the defined \l{Action}{Actions} if the
    whole rule evaluates to true. Once the trigger path has been left (i.e. a black arrow is followed),
    subsequent elements will still be evaluated when the rule is triggered, but they won't trigger the
    evaluation themselves.

    There are two mechanisms that can trigger a rule, described by the two trigger paths in the Rules definition figure.
    \list
        \li State bindings based
        \li Event based
    \endlist

    \section2 Event based rules

    Event based rules (trigger path 1) contain either one or more \l{Event}{Events} or are triggered by a \l{State} change (disregarding what
    the changed State's value actually is). Such rules may still evaluate \l{State}{States} for a certain value (leaving
    Trigger path 1 and re-entering Trigger path 2), however, unless
    otherwise explicitly defined, the Rule is not evaluated when such a State change happens (given the Trigger path has been
    left by crossing a black arrow). Those rules are only executed for items on trigger path 1.

    \section3 Examples

    \list
        \li This rule will be evaluated and executed whenever Remote_button1 is pressed:

            \tt {\span {id="color-blue"} {Event<Remote_button1_pressed>}} \tt {\span {id="color-black"} {-> Action<Toggle_Light>}}

        \li This rule will be evaluated and executed whenever Remote_button1 is pressed or or Motion sensor 1 triggers.

            \tt {\span {id="color-blue"} {Event<Remote_button1_pressed> | Event<Motion_sensor1_triggered>}} \tt {\span {id="color-black"} {-> Action<Turn_on_Light>}}

        \li This rule will be evaluated and executed whenever Remote_button1 is pressed or the temperature changes.

            \tt {\span {id="color-blue"} {Event<Remote_button1_pressed> | State<Temperature_changed>}} \tt {\span {id="color-black"} {-> Action<Turn_on_Light>}}
    \endlist

    \section2 State bindings based rules

    State binding rules (Trigger path 2) are rules which only contains \l{State}{States} and \l{Action}{Actions}. Each time
    a \l{State} on that path changes, the rule is evaluated. That means, all the States in the Rule are examined. If all
    evaluations are fulfilled, the Rule's \l{Action}{Actions} are executed. Please note, that such Rules may only check
    if states are equal to, unequal, less than or greater then some value.

    \section3 Examples

    \list
        \li This rule will be evaluated whenever the temperature changes and executed when the temperature equals 10.

            \tt {\span {id="color-red"} {State<Temperature>==10}} \tt {\span {id="color-black"} {-> Action<Toggle_Light>}}

        \li This rule will be evaluated whenever the temperature changes or the Light sensor changes and executed when the temperature is greater 20 and the light sensor reports values greater 10.

            \tt {\span {id="color-blue"} {State<Temperature> >20 & State<Light> >10}} \tt {\span {id="color-black"} {-> Action<OpenWindow>}}

        \li This rule will be evaluated whenever the temperature changes or the Light sensor changes and executed when the temperature is greater 20 or the light sensor reports values greater 10..

            \tt {\span {id="color-blue"} {State<Temperature> >20 | State<Light> >10}} \tt {\span {id="color-black"} {-> Action<OpenWindow>}}
    \endlist

    \section2 Mixing rules types

    Having both types of triggers in a single rule is only possible by leaving the trigger path 1, crossing a black arrow and
    re-entering trigger path 2. This however, converts the rule to an Event based rule which means, only the elements
    on trigger path 1 will be able to trigger the rule evaluation.

    \section3 Examples

    \list
        \li This rule will be evaluated whenever the remote button1 is pressed and executed only if the temperature is greater 10.

            \tt {\span {id="color-blue"} {Event<Button1_pressed>==10}} \tt {\span {id="color-black"} {->}} \tt {\span {id="color-red"} {State<Temperature> >10}} \tt {\span {id="color-black"} {-> Action<Toggle_Light>}}

    \endlist


*/