core/base (_use-new-classification-system): New template

This template prepares for the introduction of the new classification
system, which is a full rewrite that is both more performant and more
correct in its behavior.  Unfortunately, the corrections will cause problems
with old code that may be relying on certain cases, particularly where
undefined values are implicitly treated as zero.

Consequently, the legacy and new systems will exist side-by-side, able to be
toggled on as desired so people can verify that behavior is correct before
we switch it on by default.  This template allows switching on the system
for an entire package (if it's placed at the toplevel), or portions of a
package, though the latter should only be used in exceptional circumstances.

See the test cases in commits to follow for more information.
master
Mike Gerwitz 2021-06-08 14:06:47 -04:00
parent d4dc1e651b
commit 1e620e1e96
1 changed files with 30 additions and 0 deletions

View File

@ -287,5 +287,35 @@
</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" />
</template>
</section>
</section>
</package>