tame/core/assert.xml

<?xml version="1.0"?>
<!--
  Copyright (C) 2015, 2018 R-T Specialty, LLC.

  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" />
  <import package="vector/cmatch" />


  This package is young;
    the intent is to provide basic assertions to ensure data
    integrity.

  \emph{N.B. The behavior of this package changed in version 1.0.0---%
          \ref{_assert_} now properly fails on non-match,
            not match.}

  The \ref{_assert_} template generates a~generic assertion using the
    provided predicates.
  If the predicates provided to the assertion fail (yields $\bot$),
    the system immediately terminates.\footnote{
      Beacuse the system stops processing once a terminating classification
        yields~$\top$,
          only one assertion will ever match,
            even if others would match if execution were to continue.}

  \ref{_assert_} implements assertions by genearting two classifications---%
    one to perform the actual assertion,
      and a terminating classification to ensure that the assertion
        yields~$\top$.

  <template name="_assert_"
            desc="Terminate on predicate failure">
    <param name="@values@" desc="Predicates" />

    <param name="@as@" desc="Generated classification name">
      <text unique="true">-assert-</text>
    </param>

    <param name="@desc@" desc="Description">
      <text>Assertion</text>
    </param>


    <param name="@neg_as@"
           desc="Generated name for classification to be negated">
      <text unique="true">-nassert-</text>
    </param>
    <param name="@neg_yields@"
           desc="Generated yield for classification to be negated">
      <text unique="true">_nassert</text>
    </param>


    <!-- The actual assertion will be performed by one classification... -->
    <classify as="@neg_as@" yields="@neg_yields@"
              desc="{@desc@} (assertion result)">
      <param-copy name="@values@" />
    </classify>

    <!-- ...which is in turn negated for the terminating
         classification.  The reason for this is that terminating
         classifications terminate on _match_. -->

    <classify as="@as@" desc="@desc@" terminate="true">
      <match on="@neg_yields@" value="FALSE" />
    </classify>
  </template>



  <section title="Standard Assertions">
    There is currently one standard assertion---
      \ref{_assert-nonzero_} (also called \ref{_fail-on-empty_}.

    \ref{_assert-nonzero_} terminates if \tt{@name@} is zero,
      subject to \tt{@when@},
        \tt{@class@},
        and any other provided predicates.

    <template name="_assert-nonzero_"
              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>

      <param name="@__classyields@"
             desc="Classification yield to match on">
        <param-class-to-yields name="@class@" />
      </param>


      <t:assert desc="@desc@">
        <if name="@when@">
          <match on="@when@" />
        </if>

        <if name="@class@">
          <match on="@__classyields@" />
        </if>

        <!-- include any optional conditions -->
        <param-copy name="@values@" />

        <t:match-ne on="@name@" value="ZERO" />
      </t:assert>
    </template>


    This template was previously named \ref{_fail-on-empty_},
      so an alias is provided for backwards-compatibility.
    Note that it will display a deprecation warning.

    <template name="_fail-on-empty_"
              desc="Fail when a value is zero (alias for _assert-nonzero_)">
      <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>


      <warning>deprecated; use _assert-nonzero_ instead.</warning>

      <t:assert-nonzero name="@name@" when="@when@" class="@class@"
                        desc="@desc@">
        <param-copy name="@values@" />
      </t:assert-nonzero>
    </template>
  </section>
</package>