tame/core/aggregate.xml

155 lines
5.3 KiB
XML

<?xml version="1.0"?>
<!--
Copyright (C) 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:c="http://www.lovullo.com/calc"
xmlns:t="http://www.lovullo.com/rater/apply-template"
core="true"
desc="Aggregating Values">
<import package="base" export="true" />
<import package="vector/cmatch" export="true" />
Aggregate templates simplify aggregating values through various means.
Unless otherwise specified,
the default means of aggregation is summation.
<section title="Symbol-Based Aggregation">
For large numbers of values,
the most convenient way to aggregate is by matching on symbol names.
Note that symbols must be available for a match to occur.
All imported symbols are immediately available,
but \tt{expand-sequence} may need to be used for symbols produced by
the same package.
\ref{_aggregate-rate-each_} aggregates values of generators (usually
referred to by \tt{rate-each}) through summation.
A \tt{rate-each} block is generated to perform the summation.
Since \tt{rate-each} multiplies its body by \tt{_CMATCH_},
zero symbols would normally result in the summation of \tt{_CMATCH_}
itself, which is not desirable;
this template always includes \ref{ZERO} in the body to defend
against this,
causing a yield of~$0.00$ if there are no symbol matches.
<template name="_aggregate-rate-each_"
desc="Aggregate generator values by symbol prefix">
<param name="@class@" desc="Iterator class (omit for scalars)" />
<param name="@prefix@" desc="Symbol prefix" />
<param name="@yields@" desc="Scalar yield name (optional)">
<text></text>
</param>
<param name="@generates@" desc="Generator name (optional)">
<text></text>
</param>
<rate-each class="@class@" yields="@yields@"
generates="@generates@" index="k">
<c:sum>
<!-- prevent summing _CMATCH_ if there are no symbols (see above
comments) -->
<c:value-of name="ZERO"
label="Guard against zero symbol matches" />
<inline-template>
<for-each>
<sym-set name-prefix="@prefix@" type="gen" />
</for-each>
<c:value-of name="@sym_name@" index="k" />
</inline-template>
</c:sum>
</rate-each>
</template>
\ref{_aggregate-rate_} is analgous to \ref{_aggregate-rate-each_},
handling only scalar~\tt{@yields@}.
A \tt{rate} block is generated to aggregate by summation.
To prevent an empty rate block from being generated if there are no
symbol matches,
\ref{ZERO} is always included as part of the summation.
<template name="_aggregate-rate_"
desc="Aggregate scalar results by symbol prefix">
<param name="@prefix@" desc="Symbol prefix" />
<param name="@yields@" desc="Scalar yield name" />
<rate yields="@yields@">
<c:sum>
<!-- prevent completely empty rate block -->
<c:value-of name="ZERO"
label="Guard against zero symbol matches" />
<inline-template>
<for-each>
<sym-set name-prefix="@prefix@" type="rate" />
</for-each>
<c:value-of name="@sym_name@" />
</inline-template>
</c:sum>
</rate>
</template>
\ref{_aggregate-classify_} aggregates classifications.
Keep in mind that classifications act as universal quantifiers by default,
meaning zero symbol matches will produce a match and a scalar~$1$;
existential quantifiers (\tt{@any@} set to \tt{true}) will \emph{not}
match and will produce the scalar~$0$.
<template name="_aggregate-classify_"
desc="Aggregate classification results by symbol prefix">
<param name="@prefix@" desc="Symbol prefix" />
<param name="@as@" desc="Classification name" />
<param name="@desc@" desc="Generated classification description" />
<param name="@yields@" desc="Vector yield name (optional)">
<text></text>
</param>
<param name="@any@"
desc="Existential classification (default false, universal)">
<text></text>
</param>
<classify as="@as@" yields="@yields@" desc="@desc@" any="@any@">
<inline-template>
<for-each>
<sym-set name-prefix="@prefix@" type="class" />
</for-each>
<t:match-class name="@sym_name@" />
</inline-template>
</classify>
</template>
</section>
</package>