tame/core/vector/cmatch.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="@keep@" desc="Rate block @keep">
      <text></text>
    </param>

    <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@" accumulate="none" yields="@yields@" always="true" keep="@keep@">
      <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>

    <param name="@keep@" desc="Rate block @keep">
      <text></text>
    </param>


    <rate class="@class@" accumulate="none" yields="@yields@" sym="@sym@" keep="@keep@">
      <!-- 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="@keep@" desc="Whether to force compilation">
      <text></text>
    </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@"
                        keep="@keep@" />

    <classify as="@as@" yields="@yields@"
              desc="@desc@"
              keep="@keep@"
              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>