tame/core/assert.xml

111 lines
3.6 KiB
XML

<?xml version="1.0"?>
<!--
Copyright (C) 2015 LoVullo Associates, Inc.
This file is part of tame-core.
tame-core is free software: you can redistribute it and/or modify it
under the terms of the GNU Lesser General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.
-->
<package xmlns="http://www.lovullo.com/rater"
xmlns:t="http://www.lovullo.com/rater/apply-template"
core="true"
desc="Assertions">
<import package="base" />
This package is young; the intent is to provide basic assertions to
ensure data integrity. Failure will result in a~truthful value of
a~terminating classification.
The \ref{_assert_} template generates a~generic assertion using the
provided predicates, causing termination on match. For convenience,
it accepts variable or classification-name conditions as arguments,
which are included with whatever predicates are provided in its
body.
<template name="_assert_"
desc="Terminate on predicate failure">
<param name="@values@" desc="Predicates" />
<param name="@when@" desc="Conditional check (optional)" />
<param name="@class@" desc="Conditional class check (optional)" />
<param name="@as@" desc="Generated classification name">
<text unique="true">-assert-</text>
</param>
<param name="@desc@" desc="Description">
<text>Assertion failure</text>
</param>
<param name="@__classyields@"
desc="Classification yield to match on">
<param-class-to-yields name="@class@" />
</param>
<classify as="@as@"
desc="@desc@"
terminate="true">
<if name="@when@">
<match on="@when@" />
</if>
<if name="@class@">
<match on="@__classyields@" />
</if>
<!-- include any optional conditions -->
<param-copy name="@values@" />
</classify>
</template>
<section title="Standard Assertions">
There is currently one standard assertion---\ref{_fail-on-empty_};
more will appear in the future.
\ref{_fail-on-empty_} terminates if \ref{_fail-on-empty_/@name@}
is zero, subject to \ref{_fail-on-empty_/@when@} and
\ref{_fail-on-empty_/@class@} and any other provided
predicates.
The name of this assertion is likely to change in the future, but
a~template will be added in its place providing deprecation notices.
<template name="_fail-on-empty_"
desc="Fail when a value is zero">
<param name="@values@" desc="Optional predicates to include in match" />
<param name="@name@" desc="Data to check (scalar, vector or otherwise)" />
<param name="@when@" desc="Conditional check (optional)" />
<param name="@class@" desc="Conditional class check" />
<param name="@desc@" desc="Description">
<param-value name="@name@" />
<text> is empty</text>
</param>
<t:assert desc="@desc@"
when="@when@"
class="@class@">
<!-- include any optional conditions -->
<param-copy name="@values@" />
<match on="@name@" value="ZERO" />
</t:assert>
</template>
</section>
</package>