tame/core/vector/cmatch.xml

282 lines
9.0 KiB
XML

<?xml version="1.0" encoding="utf-8"?>
<!--
Copyright (C) 2014-2022 Ryan Specialty Group, 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 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:c="http://www.lovullo.com/calc"
xmlns:t="http://www.lovullo.com/rater/apply-template"
core="true"
desc="Vector operations on classification matches">
<import package="../base" />
<import package="arithmetic" export="true" />
<import package="minmax" export="true" />
<!--
This wonderful little gem takes a classification match and stores it in a
vector, allowing for hassle-free use in calculations without awkward
hasany() calls on classification matrices (where a classification yields a
matrix, that is). This is useless for classifications that yield vectors,
since the result will be the same.
This template is also useful for combining various classification vectors
and matrices, whoose reduction would otherwise be a bit complicated. Of
course, the alternative there is also to create a classification that
relies on other classifications; use your best judgement.
This exploits the fact that _CMATCH_'s are always vectors, even if we are
matching on a matrix. As such, the system has already gone through the
trouble of reducing the matrix into a vector for us, so all we need to do
is store each value into a vector, which can be easily accomplished using a
generator.
This is an excellent example of building a feature atop of the DSL without
having to add a new language feature.
-->
<template name="_cmatch-to-vector_" desc="Vectorizes a classification match">
<param name="@class@" desc="Classification match string" />
<param name="@generates@" desc="Variable to yield generates (will yield a vector)" />
<param name="@yields@" desc="Dummy variable to yield generates (useless, but required)">
<text>__</text>
<param-value name="@generates@" />
</param>
<param name="@gendesc@" desc="Generator description">
<text>Vector containing boolean </text>
<param-value name="@class@" />
<text> classification matches</text>
</param>
<param name="@sym@" desc="Generator symbol (corresponds to @generates@)">
<!-- defaults to nothing -->
<text></text>
</param>
<!-- this conversion is as simple as using a generator to yield the value
of _CMATCH_ for each index -->
<rate class="@class@" yields="@yields@">
<c:sum of="_CMATCH_" index="k" generates="@generates@" desc="@gendesc@" sym="@sym@">
<c:value-of name="_CMATCH_" index="k" />
</c:sum>
</rate>
</template>
<template name="_cmatch-to-scalar_" desc="Reduces a classification match into a scalar">
<param name="@class@" desc="Classification match string" />
<param name="@yields@" desc="Variable to yield into" />
<param name="@sym@" desc="Yield symbol (defaults to nothing)">
<!-- defaults to nothing -->
<text></text>
</param>
<rate class="@class@" yields="@yields@" sym="@sym@">
<!-- if any single one matches, then we want to yield a 1 -->
<c:apply name="maxreduce" maxreduce_set="_CMATCH_" />
</rate>
</template>
In cases where a classification needs to be based on a result that
has been reduced to a scalar, \ref{_cmatch_to-scalar_} does not
solve the whole problem: for this, \ref{_classify-scalar_} may be
used. In addition to performing the action of the former (if {\tt
@yields} is provided), the resulting classification itself will
match on the scalar result. While this is not strictly
necessary---the predicate itself is already scalar---this is
important for systems or templates that derive the classification
result from the name of the classification.
<template name="_classify-scalar_"
desc="Classification with a forced-scalar result">
<param name="@values@" desc="Predicates" />
<param name="@as@" desc="Classification name" />
<param name="@desc@" desc="Classification description" />
<param name="@yields@" desc="Scalar result name">
<text>__</text>
<param-value snake="true" name="@as@" />
</param>
<param name="@sym@" desc="Optional yield symbol">
<text></text>
</param>
<classify as="--{@as@}-pre"
yields="__{@yields@}Pre"
desc="{@desc@}, pre-scalar">
<param-copy name="@values@" />
</classify>
<t:cmatch-to-scalar class="--{@as@}-pre"
yields="__{@yields@}Scalar"
sym="@sym@" />
<classify as="@as@" yields="@yields@"
desc="@desc@"
sym="@sym@">
<match on="__{@yields@}Scalar" />
</classify>
</template>
The vector analog to \ref{_classify-scalar_} is
\ref{_classify-vector_}. The results are undefined if the classification
would have otherwise yielded a scalar value (that is, do not use this to
force a scalar into a vector). It may work in an intuitive way, but it's
not designed to.
<template name="_classify-vector_"
desc="Classification with a forced-vector result">
<param name="@values@" desc="Predicates" />
<param name="@as@" desc="Classification name" />
<param name="@desc@" desc="Classification description" />
<param name="@yields@" desc="Scalar result name">
<text>__</text>
<param-value snake="true" name="@as@" />
</param>
<param name="@sym@" desc="Optional yield symbol">
<text></text>
</param>
<classify as="--{@as@}-pre"
yields="__{@yields@}Pre"
desc="{@desc@}, pre-vector">
<param-copy name="@values@" />
</classify>
<t:cmatch-to-vector class="--{@as@}-pre"
generates="__{@yields@}Vector"
sym="@sym@" />
<classify as="@as@" yields="@yields@"
desc="@desc@"
sym="@sym@">
<match on="__{@yields@}Vector" />
</classify>
</template>
<!--
Counts one for each classification vector match
-->
<template name="_cmatch-count_" desc="Counts the number of classification matches of a vector">
<param name="@class@" desc="Classification match" />
<param name="@yields@" desc="Value to yield" />
<!-- nothing by default -->
<param name="@no@" desc="Non-match">
<text></text>
</param>
<rate class="@class@" no="@no@" yields="@yields@">
<c:sum of="_CMATCH_" />
</rate>
</template>
<!-- because verbose repition is an evil -->
<inline-template>
<for-each>
<set cmp="eq" />
<set cmp="ne" />
<set cmp="gt" />
<set cmp="gte" />
<set cmp="lt" />
<set cmp="lte" />
</for-each>
<template name="_match-{@cmp@}_" desc="Match value {@cmp@}">
<param name="@on@" desc="Value to assert" />
<!-- pick one -->
<param name="@const@" desc="Match against constant value" />
<param name="@value@" desc="Match against variable" />
<if name="@const@">
<warning>
@const@ is deprecated; use @value@ with a #-prefix instead.
</warning>
</if>
<match on="@on@">
<dyn-node name="c:{@cmp@}">
<if name="@const@">
<c:const value="@const@" desc="Comparison" />
</if>
<unless name="@const@">
<c:value-of name="@value@" />
</unless>
</dyn-node>
</match>
</template>
</inline-template>
<template name="_match-class_"
desc="Match on a class name (rather than @yields)">
<param name="@name@" desc="Classification name" />
<param name="@__yields@" desc="Classification yield to match on">
<param-class-to-yields name="@name@" />
</param>
<param name="@value@" desc="Value to match on">
<text></text>
</param>
<match on="@__yields@" value="@value@" />
</template>
\ref{_vector-to-class_} converts a vector into a classification.
<template name="_vector-to-class_"
desc="Convert a vector to a classification">
<param name="@name@" desc="Source vector" />
<param name="@as@" desc="Classification name" />
<param name="@yields@" desc="Classification yield">
<text></text>
</param>
<param name="@desc@" desc="Classification description">
<text>Classification of </text>
<param-value name="@name@" />
</param>
<classify as="@as@" desc="@desc@" yields="@yields@">
<match on="@name@" />
</classify>
</template>
</package>