tame/core/map.xml

189 lines
5.8 KiB
XML
Raw Normal View History

2015-03-18 11:31:47 -04:00
<?xml version="1.0" encoding="ISO-8859-1"?>
<!--
Copyright (C) 2015 LoVullo Associates, Inc.
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/>.
-->
<!--
Brings c:case statements to life
The problem with cases is that they are so verbose for simple cases. This
makes simple cases simple.
-->
2015-03-18 11:31:47 -04:00
<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"
2015-08-07 14:24:53 -04:00
title="Map Sets">
The problem with \texttt{case} statements is that they are very
verbose, which is greatly distracting for smaller cases, and~can
take away from the actual intent of the~code. Map~sets make simple
cases simple by allowing concise map definitions.
If \ref{_map-set_/@name@} is provided, then each map implicitly
operates on that reference as its input, unless overridden using
\ref{_map_/@name@}. \ref{_map-set_/@default@} can be used to
provide a constant default if no mapping is otherwise available; see
also~\ref{_map-else_}.
2015-03-18 11:31:47 -04:00
<template name="_map-set_" desc="Map a set of values">
<param name="@name@" desc="Param name" />
<param name="@index@" desc="Index" />
<param name="@values@" desc="Criteria (map nodes)" />
<param name="@label@" desc="Case statement label">
<!-- default empty -->
2015-03-18 11:31:47 -04:00
<text></text>
</param>
<!-- used in param-meta for _map-else_, so let's make the default
clear -->
<param name="@default@" desc="Default value">
<text></text>
</param>
2015-08-07 14:24:53 -04:00
<c:cases label="@label@">
2015-03-18 11:31:47 -04:00
<param-copy name="@values@">
<param-meta name="map_param" value="@name@" />
<param-meta name="map_index" value="@index@" />
<param-meta name="map_default" value="@default@" />
2015-03-18 11:31:47 -04:00
</param-copy>
<unless name="@default@" eq="">
<c:otherwise>
<c:const value="@default@" type="integer" desc="No mapping" />
</c:otherwise>
</unless>
</c:cases>
2015-03-18 11:31:47 -04:00
</template>
2015-08-07 14:24:53 -04:00
Mappings are defined using \ref{_map_}. The input defaults to
the~reference declared by~\ref{_map-set_/@name@},
if~provided. \ref{_map_/@name@} takes precedence, even if
the~former is provided. Just like \texttt{case}~statements,
multiple inputs can be provided by specifying multiple references;
this means that each \ref{_map_/@name@} can differ.\footnote{This
isn't particularly intuitive or recommended, but it does simplify
certain tasks enough to maybe justify this type of use.}
Just like \texttt{case}~statements themselves, maps are
surjective---the codomain implicitly includes $0$~to handle all
default cases, unless a default is provided.
2015-03-18 11:31:47 -04:00
<template name="_map_" desc="Map criteria">
<param name="@from@" desc="Value to map from" />
<param name="@value@" desc="Constant to map to" />
<param name="@to@" desc="Named value (use instead of @value@)" />
2015-08-07 14:23:48 -04:00
<param name="@to-index@" desc="Named value index">
<text></text>
</param>
2015-03-18 11:31:47 -04:00
<param name="@type@" desc="Constant value type">
<text>float</text>
</param>
2015-03-18 11:31:47 -04:00
<param name="@desc@" desc="Map description">
<text>Destination mapping</text>
</param>
<!-- set by parent map-set -->
2015-03-18 11:31:47 -04:00
<param name="@name@" desc="Param name">
<param-inherit meta="map_param" />
</param>
<param name="@index@" desc="Index">
<param-inherit meta="map_index" />
</param>
2015-08-07 14:23:48 -04:00
<c:case>
<!-- index provided -->
2015-03-18 11:31:47 -04:00
<if name="@index@">
<c:when name="@name@" index="@index@">
<c:eq>
<c:value-of name="@from@" />
</c:eq>
</c:when>
2015-03-18 11:31:47 -04:00
</if>
<!-- no index provided -->
2015-03-18 11:31:47 -04:00
<unless name="@index@">
<c:when name="@name@">
<c:eq>
<c:value-of name="@from@" />
</c:eq>
</c:when>
2015-03-18 11:31:47 -04:00
</unless>
2015-03-18 11:31:47 -04:00
<if name="@value@">
<c:const value="@value@" desc="@desc@" />
2015-03-18 11:31:47 -04:00
</if>
<unless name="@value@">
2015-08-07 14:23:48 -04:00
<c:value-of name="@to@" index="@to-index@" />
2015-03-18 11:31:47 -04:00
</unless>
</c:case>
2015-03-18 11:31:47 -04:00
</template>
2015-08-07 14:24:53 -04:00
The default condition can be handled in two different ways: via
\ref{_map-set_/@default@}, or using \ref{_map-else_}; the latter
provides more flexibility and generally reads better. Both cannot
be used together.
2015-03-18 11:31:47 -04:00
<template name="_map-else_" desc="Non-matching map criteria">
<param name="@value@" desc="Constant to map to" />
<param name="@to@" desc="Named value (use instead of @value@)" />
2015-08-07 14:24:27 -04:00
<param name="@desc@" desc="Map description">
<text>Destination mapping</text>
</param>
2015-08-07 14:23:48 -04:00
<param name="@to-index@" desc="Named value index">
<text></text>
</param>
<param name="@_map-default@" desc="_map_-specified default">
<param-inherit meta="map_default" />
</param>
<!-- provide a more friendly error; otherwise, they'd get an error
from having two c:otherwise nodes, which would be confusing -->
<unless name="@_map-default@" eq="">
<error>
A default value was already provided by _map-set_/@default@
</error>
</unless>
2015-08-07 14:23:48 -04:00
<c:otherwise>
2015-03-18 11:31:47 -04:00
<if name="@value@">
<c:const value="@value@" desc="@desc@" />
2015-03-18 11:31:47 -04:00
</if>
<unless name="@value@">
2015-08-07 14:23:48 -04:00
<c:value-of name="@to@" index="@to-index@" />
2015-03-18 11:31:47 -04:00
</unless>
</c:otherwise>
2015-03-18 11:31:47 -04:00
</template>
</package>