tame/core/base.xml

314 lines
10 KiB
XML

<?xml version="1.0"?>
<!--
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="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>