314 lines
10 KiB
XML
314 lines
10 KiB
XML
<?xml version="1.0"?>
|
|
<!--
|
|
Copyright (C) 2014-2023 Ryan 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="Base features">
|
|
|
|
The \pkgself~package exposes common and internal
|
|
defintions. Ideally, this package will be included automatically by
|
|
the compiler to remove repetitive, boilerplate imports. Importing
|
|
this package isn't necessary if none of these definitions are
|
|
needed.
|
|
|
|
|
|
|
|
<section title="Internal Constants">
|
|
\ref{_CMATCH_} is a magic constant that contains the result of
|
|
a~classification match. This is used implicity by
|
|
\ref{rate-each}.\footnote{The symbol is \Xi~because it looks like
|
|
a sideways array.}
|
|
|
|
\todo{Remove in favor of a local variable or generated
|
|
classification; there is no need (anymore) for this to be magic.}
|
|
|
|
<const name="_CMATCH_" type="boolean" sym="\Xi"
|
|
desc="Classification match vector (applicability)">
|
|
<item value="0"
|
|
desc="Dummy value; this set is populated upon entering
|
|
each rate block" />
|
|
</const>
|
|
</section>
|
|
|
|
|
|
|
|
<section title="Primitive Types">
|
|
Primitives are defined internally; these definitions simply
|
|
provide symbols to permit their use.
|
|
|
|
<typedef name="integer"
|
|
desc="Any value in the set of integers"
|
|
sym="\mathbb{I}">
|
|
<base-type />
|
|
</typedef>
|
|
|
|
|
|
<typedef name="float"
|
|
desc="Any real number (represented as a float)"
|
|
sym="\mathbb{R}">
|
|
<base-type />
|
|
</typedef>
|
|
|
|
|
|
\ref{empty} does not have much use outside of the compiler.
|
|
|
|
<typedef name="empty"
|
|
desc="Empty set"
|
|
sym="\emptyset">
|
|
<base-type />
|
|
</typedef>
|
|
</section>
|
|
|
|
|
|
<section title="Boolean and Unknown">
|
|
\ref{boolean} contains the boolean \ref{TRUE} and~\ref{FALSE} values,
|
|
which map to~$1$ and~$0$ respectively.
|
|
The \ref{maybe} type is the union of \ref{boolean} and \ref{NOTHING},
|
|
with a value of~$-1$;\footnote{
|
|
This is similar in spirit to the Haskell \tt{Maybe} type,
|
|
or the OCaml \tt{Option} type.
|
|
}this is commonly used to represent an unknown state or missing
|
|
value.\footnote{
|
|
The \ref{nothing}~type is used for the sake of the union;
|
|
it should not be used directly.}
|
|
|
|
<typedef name="maybe" desc="Boolean or unknown value">
|
|
<union>
|
|
<typedef name="nothing" desc="Unknown value">
|
|
<enum type="integer">
|
|
<item name="NOTHING" value="-1" desc="Unknown or missing value" />
|
|
</enum>
|
|
</typedef>
|
|
|
|
<typedef name="boolean" desc="Boolean values">
|
|
<enum type="integer">
|
|
<item name="TRUE" value="1" desc="True" />
|
|
<item name="FALSE" value="0" desc="False" />
|
|
</enum>
|
|
</typedef>
|
|
</union>
|
|
</typedef>
|
|
|
|
The constant \ref{UNKNOWN} is also defined as~$-1$ to serve as an
|
|
alternative to the term~``nothing''.
|
|
|
|
<const name="UNKNOWN" value="-1"
|
|
desc="Unknown or missing value" />
|
|
</section>
|
|
|
|
|
|
|
|
<section title="Convenience">
|
|
$0$~is a~common value. Where a value is required (such
|
|
as a~template argument), \ref{ZERO} may be used. TAME now
|
|
supports a~constant-scalar syntax ({\tt #0}; \todo{reference this
|
|
in documentation}), making this largely unnecessary.
|
|
|
|
This is declared as a float to provide compatibility with all
|
|
types of expressions.
|
|
|
|
<const name="ZERO" value="0.00"
|
|
desc="Zero value" />
|
|
|
|
|
|
In the case where classifications are required, but a~static
|
|
assumption about the applicability of the subject can be made, we
|
|
have values that are always~true and always~false. The use
|
|
of~\ref{never} may very well be a~code smell, but let us not rush
|
|
to judgment.\footnote{\ref{never} has been added as an analog
|
|
to~\ref{always}; its author has never had use for it. Oh, look,
|
|
we just used ``never''.}
|
|
|
|
<classify as="always"
|
|
desc="Always true"
|
|
yields="alwaysTrue" />
|
|
|
|
<classify as="never"
|
|
any="true"
|
|
desc="Never true"
|
|
yields="neverTrue" />
|
|
</section>
|
|
|
|
|
|
|
|
<section title="Work-In-Progress">
|
|
\ref{_todo_} formalizes TODO items and may optionally yield a
|
|
value~\tt{@value@} for use within calculations.%
|
|
\footnote{This is different than its previous behavior of always
|
|
yielding a scalar~$0$.}
|
|
All uses of the \ref{_todo_} template will produce a warning composed of
|
|
its description~\tt{@desc@}.
|
|
|
|
<template name="_todo_"
|
|
desc="Represents work that needs to be done">
|
|
<param name="@desc@" desc="TODO desc">
|
|
<text>TODO</text>
|
|
</param>
|
|
|
|
<param name="@value@" desc="Placeholder value" />
|
|
<param name="@index@" desc="Placeholder value index">
|
|
<text></text>
|
|
</param>
|
|
|
|
<unless name="@value@">
|
|
<unless name="@index@" eq="">
|
|
<error>Using @index@ without @value@</error>
|
|
</unless>
|
|
</unless>
|
|
|
|
|
|
<warning>
|
|
TODO: <param-value name="@desc@" />
|
|
</warning>
|
|
|
|
|
|
<if name="@value@">
|
|
<c:value-of name="@value@" index="@index@" />
|
|
</if>
|
|
</template>
|
|
|
|
|
|
The \ref{_ignore_} template serves as a~block
|
|
comment.\footnote{This is useful since XML does not support nested
|
|
comments, which makes it difficult to comment out code that
|
|
already has XML comments.} It may be useful for debugging, but is
|
|
discouraged for use otherwise. The \ref{_ignore_/@desc@} param
|
|
should be used to describe intent.
|
|
|
|
<template name="_ignore_"
|
|
desc="Removes all child nodes (as if commented out)">
|
|
<param name="@values@" desc="Nodes to comment out" />
|
|
<param name="@desc@" desc="Reason for ignore" />
|
|
|
|
|
|
<warning>Ignored block!</warning>
|
|
</template>
|
|
</section>
|
|
|
|
|
|
<section title="Calculations">
|
|
These templates represent calculations that used to be defined as XSLT
|
|
templates before TAME's template system existed.
|
|
|
|
<extern name="___yield" type="rate" dtype="float" dim="0" />
|
|
|
|
<template name="_yield_"
|
|
desc="Final scalar result provided to caller">
|
|
<param name="@values@" desc="Yield calculation" />
|
|
|
|
<rate yields="___yield" local="true">
|
|
<param-copy name="@values@" />
|
|
</rate>
|
|
</template>
|
|
|
|
|
|
<template name="_rate-each_"
|
|
desc="Convenience template that expands to a lv:rate block summing over
|
|
the magic _CMATCH_ set with the product of its value">
|
|
<param name="@values@"
|
|
desc="Yield calculation" />
|
|
|
|
<param name="@generates@" desc="Generator name (optional)">
|
|
<text></text>
|
|
</param>
|
|
|
|
<param name="@yields@" desc="Yield (optional)">
|
|
<text>_</text>
|
|
<param-value name="@generates@" />
|
|
</param>
|
|
|
|
<!-- at least one of generates or yields is required -->
|
|
<if name="@yields@" eq="">
|
|
<if name="@generates@" eq="">
|
|
<error>must provide at least one of @generates or @yields</error>
|
|
</if>
|
|
</if>
|
|
|
|
<param name="@class@"
|
|
desc="Space-delimited classifications for predicated iteration" />
|
|
<param name="@no@"
|
|
desc="Space-delimited classifications for predicated iteration to prevent matches">
|
|
<text></text>
|
|
</param>
|
|
|
|
<param name="@index@"
|
|
desc="Generator index" />
|
|
|
|
<param name="@dim@" desc="Dim (optional)">
|
|
<text></text>
|
|
</param>
|
|
|
|
<param name="@gensym@" desc="Generator TeX symbol">
|
|
<text></text>
|
|
</param>
|
|
|
|
<rate class="@class@" no="@no@" yields="@yields@"
|
|
gentle-no="true"
|
|
desc="Total {@yields@} premium">
|
|
<c:sum of="_CMATCH_" dim="@dim@" sym="@gensym@"
|
|
generates="@generates@" index="@index@"
|
|
desc="Set of individual {@yields@} premiums">
|
|
<c:product>
|
|
<c:value-of name="_CMATCH_" index="@index@"
|
|
label="One if {@class@} and not {@no@} (if provided), otherwise zero" />
|
|
<param-copy name="@values@" />
|
|
</c:product>
|
|
</c:sum>
|
|
</rate>
|
|
</template>
|
|
</section>
|
|
|
|
|
|
<section title="Feature Flags">
|
|
These templates alter the behavior of the TAME compiler or runtime.
|
|
They will be removed at some point in the future.
|
|
|
|
|
|
<section title="Classification System">
|
|
The template \tt{_use-new-classification-system_} sets a compile-time
|
|
flag that will cause all following sibling classifications to be
|
|
compiled using the new classification system.
|
|
Once the feature is enabled by default,
|
|
this template will become a noop and will begin to emit a warning,
|
|
before eventually being removed.
|
|
|
|
It is possible to mix both old and new classifications within the same
|
|
package,
|
|
though such behavior may lead to confusion in certain cases.
|
|
For more information on where the new and old system differ,
|
|
see the \tt{core/test/core/class} specification.
|
|
|
|
<template name="_use-new-classification-system_"
|
|
desc="Compile following-sibling::lv:classify using the new
|
|
classification system">
|
|
<!-- Even though this is a template param-meta, it will only affect
|
|
following-sibling for performance reasons -->
|
|
<param-meta name="___feature-newclassify" value="1" />
|
|
|
|
<t:todo desc="remove _use-new-classification-system_ application;
|
|
the new classification system is enabled by default
|
|
and this template no longer has any effect" />
|
|
</template>
|
|
</section>
|
|
</section>
|
|
</package>
|
|
|