Mike Gerwitz

Activist for User Freedom

aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorMike Gerwitz <mike.gerwitz@rtspecialty.com>2018-01-09 14:56:21 -0500
committerMike Gerwitz <mike.gerwitz@rtspecialty.com>2018-09-11 09:30:52 -0400
commitc74333b1cef289765b9da56984550b1def22fe91 (patch)
tree80cbaad7757d6d0d3ba06bcf51f1eb271c5ef49f
parentadbf67abf3b6d076502060e3f4c96e960ae86452 (diff)
downloadtame-c74333b1cef289765b9da56984550b1def22fe91.tar.gz
tame-c74333b1cef289765b9da56984550b1def22fe91.tar.bz2
tame-c74333b1cef289765b9da56984550b1def22fe91.zip
[BC BREAK] assert: Correct behavior of _assert_
This completely breaks BC by completely reversing existing behavior. I'm not sure what I was thinking to begin with. Assertions are supposed to state an _expected_ condition and fail if they yield _false_; this is the opposite of what `_assert_' was doing before this change! To keep things simple, the template now requires a body and the extra `@when@' and `@class@' params have been removed (but are still available on `_fail-on-empty_'). * assert.xml (_assert_): Negate behavior. [@when@, @class@]: Remove params.
-rw-r--r--core/assert.xml98
1 files changed, 62 insertions, 36 deletions
diff --git a/core/assert.xml b/core/assert.xml
index 5f69d72..5532fff 100644
--- a/core/assert.xml
+++ b/core/assert.xml
@@ -1,6 +1,6 @@
<?xml version="1.0"?>
<!--
- Copyright (C) 2015 R-T Specialty, LLC.
+ Copyright (C) 2015, 2018 R-T Specialty, LLC.
This file is part of tame-core.
@@ -23,66 +23,81 @@
desc="Assertions">
<import package="base" />
+ <import package="vector/cmatch" />
- 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.
+
+ 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, 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.
+ 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="@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>
+ <text>Assertion</text>
</param>
- <param name="@__classyields@"
- desc="Classification yield to match on">
- <param-class-to-yields name="@class@" />
+
+ <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>
- <classify as="@as@"
- desc="@desc@"
- terminate="true">
- <if name="@when@">
- <match on="@when@" />
- </if>
+ <!-- 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>
- <if name="@class@">
- <match on="@__classyields@" />
- </if>
+ <!-- ...which is in turn negated for the terminating
+ classification. The reason for this is that terminating
+ classifications terminate on _match_. -->
- <!-- include any optional conditions -->
- <param-copy name="@values@" />
+ <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{_fail-on-empty_};
- more will appear in the future.
+ There is currently one standard assertion---\ref{_fail-on-empty_}.
\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.
+ is zero,
+ subject to \ref{_fail-on-empty_/@when@},
+ \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.
+ 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">
@@ -96,14 +111,25 @@
<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>
- <t:assert desc="@desc@"
- when="@when@"
- class="@class@">
<!-- include any optional conditions -->
<param-copy name="@values@" />
- <match on="@name@" value="ZERO" />
+ <t:match-ne on="@name@" value="ZERO" />
</t:assert>
</template>
</section>