Mike Gerwitz

Activist for User Freedom

aboutsummaryrefslogtreecommitdiffstats
blob: e6f94e2a09f94fa06a5f17406823a340762c71f4 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
<?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 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>