support.dtx

% 
% \iffalse driver
%<*driver>
\documentclass{mtmtcl}
\begin{document}
\DocInput{support.dtx}
\end{document}
%</driver>
% \fi
% 
% 
% 
% \section{Auxilliary interfaces}
% 
% \subsection{Equality}
% \label{Ssec:Equality}
% 
% A very great number of basic mathematical claims have the form of 
% an equality, but a prerequisite for speaking about that is that 
% there is an equality relation in the first place. Like all other 
% relations, equality is something relative to a structure.
% 
% \begin{APIspec}{equality}{1.0}
%   The |equality| interface v\,1.0 is applicable to principal 
%   structures. It implies that there exists a method
%   \begin{APIdescription}{structure}
%     \begin{APImethod}{=}
%       \word{element} \word{element}
%     \end{APImethod}
%     which returns a boolean, and thus constitutes a binary relation 
%     on the principal set of elements $S$. Moreover this relation 
%     must be an equivalence relation, i.e.,
%     \begin{displaysyntax}
%       [\meta{structure} = $a$ $a$]
%     \end{displaysyntax}
%     is boolean true for any \(a \in S\) (reflexivity),
%     \begin{displaysyntax}
%       [\meta{structure} = $a$ $b$]\par
%       [\meta{structure} = $b$ $a$]
%     \end{displaysyntax}
%     are equivalent for any \(a,b \in S\) (symmetry), and for all 
%     \(a,b,c \in S\) if both of 
%     \begin{displaysyntax}
%       [\meta{structure} = $a$ $b$]\par
%       [\meta{structure} = $b$ $c$]
%     \end{displaysyntax}
%     are true then
%     \begin{displaysyntax}
%       [\meta{structure} = $a$ $c$]
%     \end{displaysyntax}
%     must be true as well (transitivity).
%   \end{APIdescription}
% \end{APIspec}
% 
% \begin{definition}
%   A method taking as input zero or more elements of structures 
%   which support the |equality| v\,1.0 interface is said to be 
%   \defining{congruent} if two arguments lists which are pointwise 
%   |=|-equal produce equal output, where the latter `equal' should 
%   be interpreted in accordance to how the output values of the 
%   method is described.
% \end{definition}
% 
% \begin{APIspec}{equality}{1.1}
%   Version 1.1 of the |equality| interface extends the |=| to be 
%   variadic.
%   \begin{APIdescription}{structure}
%     \begin{APImethod}{=}
%       \word{element}\regstar
%     \end{APImethod}
%     Returns boolean true if the binary form would return true for 
%     any two of \word{element}s.
%     
%     As usual, the status of |=| as equivalence relation implies that
%     \begin{displaysyntax}
%       [$S$ = $a_1$ $a_2$ $\dots$ $a_n$]
%     \end{displaysyntax}
%     is true if and only if all of
%     \begin{displaysyntax}
%       [$S$ = $a_1$ $a_2$]\par
%       [$S$ = $a_2$ $a_3$]\par
%       $\vdots$\par
%       [$S$ = $a_{n-1}$ $a_n$]
%     \end{displaysyntax}
%     are true.
%   \end{APIdescription}
%   The nullary and unary forms of |=| always return true, but this is 
%   sensible behaviour when applied to expanded lists. In particular, 
%   it is a consequence of having as property that adding extra 
%   \word{element}s can change the result from true to false, but not 
%   vice versa.
% \end{APIspec}
% 
% \begin{tcl}
%<*docstrip.tcl::catalogue>
pkgProvide mtmtcl::adaptors::equality 1.0 adaptors::equality
%</docstrip.tcl::catalogue>
%<*adaptors::equality>
namespace eval mtmtcl::adaptors::equality {}
% \end{tcl}
% \setnamespace{mtmtcl::adaptors::equality}
% 
% \begin{proc}{variadic_equal}
%   Knowing the above two versions of \APIref{equality}{1.1}, one thing 
%   that can be done is to implement a variadic equality on top of 
%   the binary one. To that end, this procedure has the call syntax
%   \begin{displaysyntax}
%     |variadic_equal| \word{binary-equal} \word{argument}\regstar
%   \end{displaysyntax}
%   where the \word{binary-equal} is a command prefix with the syntax
%   \begin{displaysyntax}
%     \meta{binary-equal} \word{left} \word{right}
%   \end{displaysyntax}
%   that returns boolean true if \word{left} and \word{right} are 
%   equal, and boolean false otherwise. |variadic_equal| furthermore 
%   presumes that the relation so defined is an equivalence relation. 
%   It returns |1| if all \word{argument}s compare as equal, and |0| 
%   otherwise.
%   \begin{tcl}
proc mtmtcl::adaptors::equality::variadic_equal {prefix args} {
   if {![llength $args]} then {return 1}
   set left [lindex $args 0]
   foreach right [lrange $args 1 end] {
      if {![{*}$prefix $left $right]} then {return 0}
   }
   return 1
}
%   \end{tcl}
% \end{proc}
% 
% \begin{proc}{to-1.1}
%   This procedure constructs a command prefix satisfying 
%   \APIref+{equality}{1.1} from one satisfying 
%   \APIref+{equality}{1.0}. The call syntax is
%   \begin{displaysyntax}
%     mtmtcl::adaptors::equality::to-1.1 \word{base}
%     \begin{regblock}[\regstar] \word{option} \word{value} 
%     \end{regblock}
%   \end{displaysyntax}
%   and the return value is the constructed command prefix. 
%   Currently, the only option supported is \texttt{-strict}, which 
%   takes a boolean value and defaults to false. Strictness refers 
%   to adherence to the API mechanism in general; see below for 
%   details on what this means.
%   
%   First check the basics: If \meta{base} already supports 
%   version~1.1 of \texttt{equality}, then it is the wanted result. 
%   If \meta{base} doesn't support version~1.0, then there's nothing 
%   we can do about it.
%   \begin{tcl}
proc mtmtcl::adaptors::equality::to-1.1 {base args} {
   if {[{*}$base API equality 1.1]} then {return $base}
   if {![{*}$base API equality 1.0]} then {
      return -code error "Prefix does not support equality 1.0: $base"
   }
%   \end{tcl}
%   With those trivial cases out of the way, it is time to get down 
%   to business. In this case, the prefix will be a call to a lambda 
%   that dispatches the |=| subcommand to the |variadic_equal| 
%   procedure. It also handles the |API| subcommand, since it changes 
%   what version of \texttt{equality} is supported. The syntax for a 
%   complete call will be
%   \begin{displaysyntax}
%     apply \word{lambda} \word{base} \word{API-dict} 
%     \word{subcommand} \word{argument}\regstar
%   \end{displaysyntax}
%   \begin{tcl}
   set lambda [list {base API subcmd args}]
%   \end{tcl}
%   What it does with other subcommands than |=| and |API| depends on 
%   the \describeopt+{to-1.1}{-strict} setting; in the non-strict case, 
%   it maps all other subcommands to their \meta{base} counterparts 
%   and presumes no other interface is affected by the redefinition of 
%   |=| (and also that the interfaces are static).
%   \begin{tcl}
   if {[dict exists $args -strict] && [dict get $args -strict]} then {
      lappend lambda {
         if {$subcmd eq "="} then {
            variadic_equal [list {*}$base =] {*}$args
         } elseif {$subcmd eq "API"} then {
            ::API::static $API {*}$args
         } else {
            tailcall {*}$base $subcmd {*}$args
         }
      }
      set API [{*}$base API]
      dict set API equality 1.1
   } else {
%   \end{tcl}
%   If going strictly by the book however, one cannot assume that any 
%   interface other than \texttt{equality} version~1.1 is supported 
%   by the result, so that is all that will be claimed. The 
%   unmodified \meta{base} structure is made available using a new 
%   |understructure| method, i.e., \meta{result}| understructure API| 
%   queries the \meta{base} |API|.
%   \begin{tcl}
      lappend lambda {
         switch -- $subcmd "=" {
            variadic_equal [list {*}$base =] {*}$args
         } "API" {
            ::API::static $API {*}$args
         } "understructure" {
            tailcall {*}$base {*}$args
         } default {
            tailcall {*}$base $subcmd {*}$args
         }
      }
      set API {equality 1.1}
   }
   lappend lambda [namespace current]
   return [list ::apply $lambda $base $API]
}
%</adaptors::equality>
%   \end{tcl}
% \end{proc}
% 
% In some cases, it is important to have a canonical representation for 
% an value. The most immediate need for this occurs when values are 
% used as keys in \Tcl\ dictionaries, as equality of keys is always 
% string equality. There are two naturally occurring approaches to 
% canonical representation: automatic and manual conversion to 
% canonical form. Automatic canonicity is something often seen with 
% numbers (in particular integers), whereas for quotient algebras the 
% problem of canonical representation (normal forms) is felt even at 
% the mathematical level.
% 
% In \Tcl, lists are containers with automatic canonicity\Ldash two 
% lists generated by list commands are equal as strings if and only if 
% they have the same number of elements and the $i$th elements of the 
% lists are equal as strings\Dash whereas dictionaries are not. The 
% catch for dictionaries is that the order of the keys is not uniquely 
% determined, and even though only a few orders occur in practice, 
% the exact order used depends on how the dictionary was constructed. 
% 
% 
% \begin{APIspec}{canonise}{1.0}
%   The |canonise| interface v\,1.0 is applicable to principal 
%   structures. It implies that there exists a method
%   \begin{APIdescription}{structure}
%     \begin{APImethod}{canonise}
%       \word{element}
%     \end{APImethod}
%       which returns the canonical form of the \word{element}. This 
%       method has to satisfy the property that
%       \begin{displaysyntax}
%         [$S$ canonise [$S$ canonise $a$]]\par
%         [$S$ canonise $a$]
%       \end{displaysyntax}
%       are equal as strings for all elements $a$ of the 
%       \meta{structure} $S$.
%   \end{APIdescription}
% \end{APIspec}
% 
% \begin{APIspec}{canonise}{1.1}
%   It is natural to relate canonicity to equality, but that requires 
%   having an equality relation to relate it to.
%   \begin{APIdescription}{structure}
%     \begin{APImethod}{=}
%       \word{element} \word{element}
%     \end{APImethod}
%       This method satisfies the \texttt{equality} (v\,1.0) interface.
%       
%     \begin{APImethod}{canonise}
%       \word{element}
%     \end{APImethod}
%       Two elements $a$ and $b$ of a \meta{structure} $S$ are 
%       |=|-equal if and only if the two expressions
%       \begin{displaysyntax}
%         [$S$ canonise $a$]\par
%         [$S$ canonise $b$]
%       \end{displaysyntax}
%       are equal as strings.
%   \end{APIdescription}
% \end{APIspec}
% 
% At this point, it would be possible to define an adaptor that from 
% a \APIref+{canonise}{1.0} structure constructs a 
% \APIref+{canonise}{1.1}, just as above. For the moment, that 
% programming task is left as an exercise to the reader. 
% Alternatively, one could modify the above |equality::to-1.1| 
% procedure so that it will create an \APIref+{equality}{1.1} 
% structure out of a \APIref+{canonise}{1.0} structure.
% 
% 
% \subsection{Data export}
% 
% The basic format for exporting structure elements is as a 
% data-tree, so that further processing is easy in \Tcl.
% The node types (\word{tag}s) used should primarily be those defined 
% in the OpenMath standard, but there are exceptions (e.g.~|integer|) 
% in which a more \Tcl-native encoding is preferable.
% For processing to the end of rendering data, it is often 
% interesting to incorporate presentation-oriented information in the 
% data-tree. Here it is preferable to use MathML-elements to encode 
% such information, when there is one which is suitable for the 
% problem at hand (e.g.~|mfenced| for bracketing subexpressions). 
% MathML does however seem less useful as a \emph{standard} for the 
% data.
% 
% \changes{0}{2008/10/01}{Prioritising OpenMath over MathML. 
%   Introducing the idea of \emph{temporary} conversions from 
%   OpenMath node types to specialised node types. (LH)}
% 
% 
% \stringtypeheading{node type}{Data-tree node types:}
% \stringtypeheading{attribute}{Data-tree attributes:}
% 
% The key route from \mtl\ to OpenMath is the |export| interface, 
% which specifies how structure elements are converted to 
% near-OpenMath data-trees.
% 
% \begin{APIspec}{export}{2.0} \label{export-2.0}
%   This interface is applicable to principal structures. It provides 
%   a method |export| for converting the internal representation of 
%   an element to an external format. The syntax for this method is:
%   \begin{APIdescription}{structure}
%     \begin{APImethod}{export}
%       \word{element} \word{common attributes}
%     \end{APImethod}
%       where \word{element} is the element to export. The return 
%       value is a data-tree that encodes the \word{element} as 
%       near-OpenMath.
%       
%       The \word{common attributes} is a dictionary of common 
%       attributes for nodes in the tree. The |export| method is 
%       however allowed to override part or all of it, so it is 
%       prefectly acceptable to ignore the \word{common attributes} 
%       entirely for some sets of nodes. The typical use is that 
%       the \word{common attributes} are used for |OMA| nodes and 
%       get |cd| and |name| entries added in |OMS| nodes.
%       
%       For |export| methods that call other |export| methods 
%       recursively, there is however the condition that they must 
%       update the \describestring+[attribute]{mtmtcl:path} entry in 
%       the \word{common attributes} dictionary. The value of this 
%       attribute is a list of strings, typically a list of method 
%       names. The purpose of this list is to establish a system for 
%       addressing subordinate structures by mirroring the command 
%       prefix that would be used to access its methods. If a 
%       structure $S_1$ makes use of the |export| method of another 
%       structure $S_2$ and $S_2$ can be accessed using the $s$ 
%       method of $S_1$, then the |mtmtcl:path| used for the 
%       \texttt{[$S_2$ export $\dotsb$]} call should have an $s$ 
%       append to its value from the \texttt{[$S_1$ export $\dotsb$]} 
%       call.
%       
%       The |mtmtcl:path| may be extended with method names also when 
%       there is no recursive call to the |export| method. This can 
%       be done e.g.~to clarify which method corresponds to a 
%       particular operation symbol.
%   \end{APIdescription}
% \end{APIspec}
% 
% \medskip
% 
% \begin{APIspec}{import}{1.0}
%   Where there is export, this is usually also import. 
%   \begin{APIdescription}{structure}
%     \begin{APImethod}{import}
%       \word{path} \word{data-tree} 
%     \end{APImethod}
%       returns the element of the \meta{structure} that corresponds 
%       to the \word{data-tree}, or throws an error if the 
%       \word{data-tree} couldn't be interpreted as an element of the 
%       \meta{structure}. The |-errorcode| of such an error should be
%       \begin{displaysyntax}
%         API import EDOM \word{who} \word{bad node}
%       \end{displaysyntax}
%       where |EDOM| is POSIX for ``domain error'', \word{who} is the 
%       \word{path} of the party detecting the error, and \word{bad 
%       node} should be the \word{data-tree} which couldn't be 
%       interpreted.
%       
%       The \word{path} serves two purposes. One is that it may be 
%       matched against \describestring+[attribute]{mtmtcl:path} 
%       attributes in the \word{data-tree}, which can aid in 
%       interpreting abbreviated \word{data-tree}s (for example trees 
%       where unary addition or multiplication nodes have been 
%       elided). The other is to identify the substructure that 
%       has thrown an |EDOM| error. The idea is that it should be 
%       handled as |mtmtcl:path| by the |export| method, i.e., if the 
%       |import| method of structure $S_1$ makes use of the |import| 
%       method of structure $S_2$, and $S_2$ can be accessed using 
%       the $s$ method of $S_1$, then the \texttt{[$S_2$ import $P_2$ 
%       $\dotsb$]} call used by the \texttt{[$S_1$ import $P_1$ 
%       $\dotsb$]} should be such that \(P_2 = P_1 s\) (list append).
%       
%       The \word{path} should not be taken into account when 
%       interpreting a \word{data-tree} without |mtmtcl:path| 
%       attributes.
%   \end{APIdescription}
% \end{APIspec}
% 
% \medskip
% 
% 
% \subsection{More on equality}
% \label{Ssec:MoreEquality}
% 
% \begin{APIspec}{onlycanonical}{1.0}
%   The |onlycanonical| interface is applicable to arbitrary structure. 
%   Version 1.0 of it means that the \emph{only} valid representations 
%   for elements are the canonical ones.
% \end{APIspec}
% 
% 
% \begin{APIspec}{autocanonical}{1.0}
%   The |autocanonical| interface v\,1.0 is applicable to 
%   arbitrary structures. It is supported if all elements computed 
%   by the structure methods are on canonical form.
% \end{APIspec}
% 
% Version~1.0 of |autocanonical| is problematic in that it makes a 
% vague reference to ``all elements computed by the structure''\Dash 
% a promise that it might be hard to verify. Two alternatives are:
% \begin{enumerate}
%   \item
%     Split |autocanonical| into a family of interfaces (one for each 
%     method).
%   \item
%     Create a new version of the interface which makes provides a 
%     method for quering whether a method is autocanonical.
% \end{enumerate}
% Both are possible, although the first looks a bit strange.
% 
% \begin{APIspec}{autocanonical \meta{method}}{1.0}
%   This interface claims that elements output from the \meta{method} 
%   are on canonical form. \textbf{Note:} For greater 
%   distinctiveness, the \meta{method} is \emph{the canonical 
%   list-coded form of the method name}, rather than the raw 
%   string.\footnote{
%     Note to self: 
%     Therefore the interface name should preferably appear as 
%     \texttt{autocanonical\PrintChar{32}\word{method}} rather than 
%     \texttt{autocanonical\PrintChar{32}\meta{method}}, but that 
%     will have to wait until the \textsf{tclldoc} \LaTeX\ package 
%     gets based on \textsf{harmless}.
%   }
%   This makes a difference if for example the method name contains a 
%   space.
% \end{APIspec}
% 
% \begin{APIspec}{autocanonical}{2.0}
%   Structures supporting version 2.0 of the |autocanonical| interface 
%   have a method
%   \begin{APIdescription}{structure}
%     \begin{APImethod}{autocanonical}
%       \word{method}
%     \end{APImethod}
%       This call returns a boolean. If it returns boolean true, then 
%       this \meta{structure} has a method \word{method} which only 
%       outputs elements on canonical form.
%   \end{APIdescription}
% \end{APIspec}
% 
% \begin{tcl}
%<*pkg>
namespace eval ::mtmtcl::sets {
   namespace path [list [namespace parent]]
}
%</pkg>
% \end{tcl}
% \setnamespace{mtmtcl::sets}
% 
% \begin{tcl}
%<*docstrip.tcl::catalogue>
pkgProvide mtmtcl::sets::universe 1.0 universe
%</docstrip.tcl::catalogue>
%<*universe,pkg>
package require mtmtcl::openmath 1.0
namespace eval ::mtmtcl::sets {}
% \end{tcl}
% 
% \begin{proc}{universe}
%   The |universe| structure simply has as elements all \Tcl\ 
%   strings, but no actual operations on them. It is meant as a dummy 
%   structure to use in cases where a set of values need to be 
%   presented as residing in a structure, but one doesn't want to 
%   wrap the true thing up as a structure.
%   \changes{0.1}{2010/01/28}{Structure added. (LH)}
%   
%   The call syntax is
%   \begin{displaysyntax}
%     ::mtmtcl::sets::universe \word{subcommand} \word{argument}\regstar
%   \end{displaysyntax}
%   \begin{tcl}
proc ::mtmtcl::sets::universe {subcmd args} {
   switch -- $subcmd "API" {
%   \end{tcl}
%   The set of subcommands and supported interfaces are chosen so that 
%   it at least becomes possible to form formal linear combinations 
%   of |universe| elements.
%   \begin{tcl}
      ::API::static {
         equality 1.0
         canonise 1.1
         onlycanonical 1.0
         export 2.0
         import 1.0
      } {*}$args
   } "=" {
      string equal [lindex $args 0] [lindex $args 1]
   } "canonise" {
      lindex $args 0
   } "export" {
      list OMFOREIGN [
         dict replace [lindex $args 1] encoding\
           application/x-mtmtcl-internal-representation
      ] [list [list \#text [lindex $args 0]]]
   } "import" {
      if {[lindex $args 1 0] eq "OMFOREIGN"} then {
         ::mtmtcl::openmath::gettext [lindex $args 1] ""
      } else {
         return -code error\
           -errorcode [concat [list API import EDOM] [lrange $args 0 1]]\
           "Universe elements are expected to be OMFOREIGN"
      }
   } default {
      return -code error "Unknown subcommand \"$subcmd\": must be\
        API, =, canonise, export, or import"
   }
}
%</universe,pkg>
%   \end{tcl}
% \end{proc}
% 
% \begin{APIspec}{finite set}{1.0}
%   The |finite set| interface v\,1 is for sets like 
%   $\{a_1,\dotsc,a_n\}$ that are introduced by listing all the 
%   elements. It is in particular a single-sorted interface.
%   
%   \begin{APIdescription}{set}
%     \begin{APImethod}{=}
%       \word{element} \word{element}
%     \end{APImethod}
%       The |=| method satisfies v\,1.0 of the |equality| interface.
%       
%     \begin{APImethod}{elements}
%     \end{APImethod}
%       The |elements| method returns the list of elements in the set. 
%       No two elements of this list may be |=|-equal.
%   \end{APIdescription}
% \end{APIspec}
% 
% \begin{APIspec}{finite set}{1.1}
%   Version 1.1 of |finite set| refines version 1.0 by making it 
%   possible to identify elements by index.
%   \begin{APIdescription}{set}
%     \begin{APImethod}{elements}
%     \end{APImethod}
%       The order of elements in the list returned by this method must 
%       not change over time.
%   \end{APIdescription}
% \end{APIspec}
% 
% 
% \begin{tcl}
%<*docstrip.tcl::catalogue>
pkgProvide mtmtcl::sets::finite_ordinal 1.0 ordinal
%</docstrip.tcl::catalogue>
% \end{tcl}
% 
% 
% \begin{proc}{finite_ordinal}
%   In set theory (at least the most common flavours of it), the 
%   \emph{ordinal numbers} is a number system construction where each 
%   number is the set of all smaller numbers, so that \(0 = 
%   \emptyset\), \(1 = \{0\} = \{\emptyset\}\), \(2 = \{0,1\} = \bigl\{ 
%   \emptyset, \{\emptyset\} \bigr\}\), \(3 = \{0,1,2\} = \Bigl\{ 
%   \emptyset, \{\emptyset\}, \bigl\{ \emptyset, \{\emptyset\} \bigr\} 
%   \Bigr\}\), and so on. Theoretically this is useful mostly for the 
%   infinite ordinals, where one can define the first inifinite ordinal 
%   $\omega$ simply as the set of all finite ordinals (natural 
%   numbers), and then continue with \(\omega + 1 = \omega \cup 
%   \{\omega\}\), \(\omega + 2 = \omega \cup \{\omega, \omega+1\}\), 
%   etc., with the first uncountable ordinal arising precisely as the 
%   set of all countable ordinals. Obviously, these transfinite 
%   applications are not the subject here.
%   
%   Instead, this procedure merely usurps the name for the family of 
%   finite set structures of the form $\{0,\dotsc,n-1\}$, since these 
%   technically happen to be finite ordinals. The basic call syntax is
%   \begin{displaysyntax}
%     |::mtmtcl::sets::finite_ordinal| \word{cardinality}
%     \word{method} \word{argument}\regstar
%   \end{displaysyntax}
%   whereas the return value depends on the \word{method}.
%   \begin{tcl}
%<*ordinal,pkg>
namespace eval ::mtmtcl::sets {}
proc ::mtmtcl::sets::finite_ordinal {card method args} {
   switch -- $method {
%   \end{tcl}
%   
%   \begin{procmethod}{elements}
%     This is the main method of this structure: construct a list of 
%     the integers $0$ through one less than the cardinality.
%     \begin{tcl}
      elements {
         set res [list]
         for {set n 0} {$n < $card} {incr n} {lappend res $n}
         return $res
      }
%     \end{tcl}
%   \end{procmethod}
%   
%   \begin{procmethod}{=}
%     Equality is straightforward.
%     \begin{tcl}
      = { expr {[lindex $args 0] == [lindex $args 1]} }
%     \end{tcl}
%   \end{procmethod}
%   
%   \begin{procmethod}{canonise}
%     However, since the above allows arbitrary integer 
%     representations, it might be best to define a canonisation 
%     method as well. This can be a good place to check argument 
%     validity.
%     \begin{tcl}
      canonise {
         if {
           [string is integer -strict [lindex $args 0]] &&\
           [lindex $args 0] >= 0 && [lindex $args 0] < $card
         } then {
            return [expr {[lindex $args 0] + 0}]
         } else {
            return -code error "Not an element"
         }
      }
%     \end{tcl}
%   \end{procmethod}
%   
%   \begin{procmethod}{API}
%     Finally, the supported interfaces must be listed.
%     \begin{tcl}
      API {
         ::API::static {equality 1.0  "finite set" 1.1 \
            canonise 1.0} {*}$args
      }
%     \end{tcl}
%   \end{procmethod}
%   
%   \begin{tcl}
   }
}
%</ordinal,pkg>
%   \end{tcl}
% \end{proc}
% 
% 
% \begin{tcl}
%<*docstrip.tcl::catalogue>
pkgProvide mtmtcl::sets::string_set 1.0 stringset
%</docstrip.tcl::catalogue>
% \end{tcl}
% 
% \begin{proc}{string_set}
%   This procedure implements a finite set of strings as a structure. 
%   The basic call syntax is
%   \begin{displaysyntax}
%     |::mtmtcl::sets::string_set| \word{element-list}
%     \word{method} \word{argument}\regstar
%   \end{displaysyntax}
%   whereas the return value depends on the \word{method}.
%   \begin{tcl}
%<*stringset,pkg>
namespace eval ::mtmtcl::sets {}
proc ::mtmtcl::sets::string_set {elements method args} {
   switch -- $method {
%   \end{tcl}
%   
%   \begin{procmethod}{elements}
%     The list of elements is simply the |elements| parameter.
%     \begin{tcl}
      elements {return $elements}
%     \end{tcl}
%   \end{procmethod}
%   
%   \begin{procmethod}{=}
%     Equality is as strings.
%     \begin{tcl}
      = { string equal [lindex $args 0] [lindex $args 1] }
%     \end{tcl}
%   \end{procmethod}
%   
%   \begin{procmethod}{canonise}
%     The only valid representations are the canonical ones, but 
%     it is convenient to provide a canonisation method for users 
%     that expect one, even if it is trivial.
%     \begin{tcl}
      canonise {return [lindex $args 0]}
%     \end{tcl}
%   \end{procmethod}
%   
%   \begin{procmethod}{export}
%     An appropriate implementation of this is to take the element 
%     as an |OMSTR| node.
%     \begin{tcl}
      export {
         return [list OMSTR [lindex $args 1]\
           [list [list \#text [lindex $args 0]]]]
      }
%     \end{tcl}
%     It is quite likely that this implementation may seem 
%     inappropriate, and that other outputs (|OMV| nodes, |OMS| 
%     nodes, either of the above with |OMATTR|) are wanted 
%     instead. This is not an error, but an opportunity to provide 
%     alternative methods implementing the |finite set| interface; 
%     regardless of how one proceeds, it would be necessary to 
%     provide additional parameters for the structure.
%   \end{procmethod}
%   
%   \begin{procmethod}{API}
%     Finally, the supported interfaces must be listed.
%     \begin{tcl}
      API {
         ::API::static {equality 1.0  "finite set" 1.1 \
            canonise 1.0  onlycanonical 1.0  export 2.0} {*}$args
      }
%     \end{tcl}
%   \end{procmethod}
%   
%   \begin{tcl}
   }
}
%</stringset,pkg>
%   \end{tcl}
% \end{proc}
% 
% 
% 
% \subsection{Naming}
% 
% It is often useful to have symbolic names (that are independent of 
% the string representation) for important structure elements, and 
% translate back and forth between elements and names. Possible 
% applications of this include
% \begin{longtable}{ll}
%   \textbf{Command}& \textbf{Result}\endhead
%   |float named pi|& $3.14159265359$\\
%   |float named e|&  $2.71828182846$\\
%   |integer named Taxicab(2)|& $1729$\\
%   $\mathbb{C}$| named i|& $i = \sqrt{-1}$\\
%   $\mathbb{Q}[x,y]$| named x|& $x$
% \end{longtable}\noindent
% with the last two perhaps being the most interesting\Dash to give 
% practical access to distinguished generators of a structure. 
% Accordingly, some of the |generated|\dots\ interfaces below return 
% names of generators (rather than the actual generator elements) since 
% this is more convenient for several applications.
% 
% \begin{APIspec}{named element}{1.0}
%   The \verb*|named element| interface provides the basic 
%   functionality of mapping symbolic names to structure elements.
%   \begin{APIdescription}{structure}
%     \begin{APImethod}{named}
%       \word{string}
%     \end{APImethod}
%       Returns the structure element whose symbolic name is 
%       \word{string}. It is not required that all return values are of 
%       the same sort, but whatever provides the name \word{string} 
%       should also provide information about what sort of element it 
%       denotes.
%   \end{APIdescription}
% \end{APIspec}
% 
% A natural extension would be to have an inverse operation |nameof| 
% which returns the name of an element (or throws an error if it isn't 
% one of the named elements), but this is complicated by the 
% possibility of having several sorts; it is in principle possible that 
% the same string could be the representation of two different named 
% elements (provided they have different sorts). On the other hand, it 
% could also be reasonable in some cases to have several names for a 
% single element\dots
% 
% Another natural extension is to have an operation |names| which 
% returns the list of known symbolic names of elements. This would in 
% particular imply that the list is finite, which is closely related to 
% the property of being finitely generated.
% 
% \begin{tcl}
%<*docstrip.tcl::catalogue>
pkgProvide mtmtcl::sets::variable_set 1.0 varset
%</docstrip.tcl::catalogue>
% \end{tcl}
% 
% \begin{proc}{variable_set}
%   This procedure implements a finite set of variables as a 
%   structure. It improves upon |string_set| in that it offers 
%   control over the presentation of a variable, and in that it 
%   supports naming variables. The basic call syntax is
%   \begin{displaysyntax}
%     |::mtmtcl::sets::variable_set| \word{element-list} 
%     \word{extra-dict} \word{method} \word{argument}\regstar
%   \end{displaysyntax}
%   where \word{element-list} is the list of variable names (|name| 
%   attribute values) and \word{extra-dict} is a dictionary of 
%   additional information. The primary keys into this dictionary are 
%   very much like options, whereas element-specific information (if 
%   any) typically appears under a secondary key. The primary keys 
%   currently supported are:
%   \begin{description}
%     \renewcommand{\makelabel}[1]{\hspace\labelsep
%        \describeopt*+[mtmtcl::sets]{variable_sep}[proc]{#1}[key]^^A
%     }
%     \item[LaTeX_encoding]
%       This entry is a dictionary, indexed by elements. The value is 
%       the |LaTeX_encoding| for the element in question.
%     \item[names]
%       This entry is a dictionary, indexed by names recognised by 
%       the |named| method, and the entries are corresponding 
%       variable names. If for example a variable is technically 
%       |name|d $\delta$, but one wishes to write |delta| in one's 
%       code, then one can put
%       \begin{quote}
%         |names {delta \u03B4 |\dots| }|
%       \end{quote}
%       in one's \word{extra-dict}.
%     \item[pseudoexpression]
%       This entry is a dictionary, indexed by elements. The value 
%       is a near-OpenMath data-tree that is used as the ``content'' 
%       of the |OMV| node upon export. This can be used to improve 
%       the presentation of the variable.
%   \end{description}
%   
%   The internal representation of an element of this structure is as 
%   a string, more precisely as a string which is an element of the 
%   \word{element-list}.
%   \begin{tcl}
%<*varset,pkg>
namespace eval ::mtmtcl::sets {}
proc ::mtmtcl::sets::variable_set {elements extra method args} {
   switch -- $method {
%   \end{tcl}
%   
%   \begin{procmethod}{elements}
%     The list of elements is simply the |elements| parameter.
%     \begin{tcl}
      elements {return $elements}
%     \end{tcl}
%   \end{procmethod}
%   
%   \begin{procmethod}{=}
%     Equality is as strings.
%     \begin{tcl}
      = { string equal [lindex $args 0] [lindex $args 1] }
%     \end{tcl}
%   \end{procmethod}
%   
%   \begin{procmethod}{canonise}
%     The only valid representations are the canonical ones, but 
%     it is convenient to provide a canonisation method for users 
%     that expect one, even if it is trivial.
%     \begin{tcl}
      canonise {return [lindex $args 0]}
%     \end{tcl}
%   \end{procmethod}
%   
%   \begin{procmethod}{named}
%     Names are first looked up in the |names| dictionary, then taken 
%     as explicit variable |name|s.
%     \begin{tcl}
      named {
         if {[llength $args] != 1} then {
            return -code error "wrong # arguments, should be:\
              <variable set> named {name}"
         }
         if {[dict exists $extra names [lindex $args 0]]} then {
            return [dict get $extra names [lindex $args 0]]
         } elseif {[lindex $args 0] in $elements} then {
            return [lindex $args 0]
         } else {
            return -code error "unknown variable: [lindex $args 0]"
         }
      }
%     \end{tcl}
%   \end{procmethod}
%   
%   \begin{procmethod}{names}
%     The set of variable names is just the set of elements.
%     \begin{tcl}
      names {return $elements}
%     \end{tcl}
%   \end{procmethod}
%   
%   \begin{procmethod}{export}
%     This is the most complex method, since no less than two of the 
%     \word{extra-dict} entries exist to provide data for it. On the 
%     other hand, it's a pretty straightforward arrangement of 
%     available data in the requested format.
%     \begin{tcl}
      export {
         if {[llength $args] != 2} then {
            return -code error "wrong # arguments, should be:\
              <variable set> export {element} {attributes}"
         }
         foreach {var attr} $args break
         set res {}
         if {[dict exists $extra pseudoexpression $var]} then {
            lappend res [dict get $extra pseudoexpression $var]
         }
         set res [list OMV [dict replace $attr name $var] $res]
         if {[dict exists $extra LaTeX_encoding $var]} then {
            set res [list OMATTR $attr [list [
               list OMATP {} [list\
                 {OMS {cd altenc name LaTeX_encoding} {}}\
                 [openmath::OM STR [dict get $extra LaTeX_encoding $var]]]
            ] $res]]
         }
         return $res
      }
%     \end{tcl}
%   \end{procmethod}
%   
%   \begin{procmethod}{import}
%     Import is pretty straightforward here; the things that might 
%     occur at this point are precisely the OpenMath variables. The 
%     only complication is that they may carry an attribution, but 
%     that is ignored. Variable |name|s must match exactly.
%     \begin{tcl}
      import {
         if {[llength $args] != 2} then {
            return -code error "wrong # arguments, should be:\
              <variable set> import {tree} {path}"
         }
         set tree [lindex $args 0]
         while {[lindex $tree 0] eq "OMATTR"} {
            set tree [lindex $tree 2 1]
         }
         if {[lindex $tree 0] eq "OMV"} then {
            set var [dict get [lindex $tree 1] name]
            if {$var in $elements} then {return $var}
            return -code error\
              -errorcode [list API import EDOM $path $tree]\
              "unknown variable: $var"
         }
         return -code error\
           -errorcode [list API import EDOM $path $tree]\
           "Expected OMV, got [lindex $tree 0]"
      }
%     \end{tcl}
%   \end{procmethod}
%   
%   \begin{procmethod}{API}
%     Finally, the supported interfaces must be listed.
%     \begin{tcl}
      API {
         ::API::static {equality 1.0  "finite set" 1.1 \
            canonise 1.0  onlycanonical 1.0 "named element" 1.0 \
            export 2.0  import 1.0} {*}$args
      }
%     \end{tcl}
%   \end{procmethod}
%   
%   \begin{tcl}
      default {
         return -code error "Unknown subcommand \"$method\",\
           must be: =, API, canonise, elements, export, import,\
           or named"
      }
   }
}
%</varset,pkg>
%   \end{tcl}
% \end{proc}
% 
% 
% 
% 
% \subsection{Understructure access}
% 
% It could be convenient, as a curtesy by adapters and adaptors, to 
% provide access to the underlying structure. Algorithms should not 
% make use of this, but it can be awfully useful for debugging.
% 
% The natural format would be to have a method which accesses the 
% underlying structure, but what should it be called? Possibilities 
% are:
% \begin{longtable}{lp{0.6\linewidth}}
%   base& But that's too close to basis and such.\\
%   understructure& Surprisingly enough, an official English word. 
%     Feels a bit childish, though (perhaps because it mixes Germanic 
%     and Latin components).\\
%   foundation& Certainly posh enough, and seems unclaimed in math.\\
%   fundament& Ditto.\\
%   stem& To the point, but could perhaps be useful for other things.
% \end{longtable}
% Since it's not to be used in production, |understructure| might 
% actually be appropriate; otherwise |fundament| seems best.
% 
% 
% \begin{APIspec}{subset}{1.0}
%   One case of understructure that has applications beyond mere 
%   debugging is that when one structure is defined as a subset of 
%   another, e.g.~a matrix group is typically defined as some subset 
%   of a matrix ring. In this case, every element of the |subset| is 
%   also an element of the |superset|, but not necessarily vice versa.
%   
%   \begin{APIdescription}{subset}
%     \begin{APImethod}{superset}
%       \word{method} \word{argument}\regstar
%     \end{APImethod}
%       The |superset| method gives access to the structure of which 
%       the \meta{subset} is a subset. Every element of the 
%       \meta{subset} is also a valid element of \meta{subset}'s 
%       \texttt{superset}.
%   \end{APIdescription}
%   
%   This may seem meagre on first sight, but is in practice pretty 
%   powerful; among those methods of the |superset| that (if at all 
%   defined) can be applied directly to elements of the \meta{subset} 
%   are such things as |export|, |import|, methods for constructing 
%   elements, and methods for taking them apart.
% \end{APIspec}
% 
% \begin{APIspec}{subset}{1.1}
%   One thing that constructing elements (e.g.~through |import|) in 
%   the |superset| does not provide is however information about 
%   whether they in fact belong to the subset in question. This 
%   suggests adding a membership test method.
%   
%   \begin{APIdescription}{subset}
%     \begin{APImethod}{member}
%       \word{superset element}
%     \end{APImethod}
%       This method takes an element of the |superset| structure as 
%       argument. It returns boolean true if that argument is also an 
%       element of the \meta{subset}, and boolean false otherwise.
%   \end{APIdescription}
% \end{APIspec}
% 
% Is this what one needs? Well, in some cases yes, but in others no. 
% The above works well for subsets of sets that can be exactly 
% represented, but not so well where the representation rather is 
% approximate. Testing whether some \(\left( \begin{smallmatrix} a & b 
% \\ c & d \end{smallmatrix} \right) \in \mathbb{Z}^{2 \times 2}\) 
% belongs to the subset $\mathrm{SL}_2(\mathbb{Z})$ is merely a 
% matter of checking whether \(ad-bc=1\). Testing whether some $3 
% \times 3$ matrix of floating-point numbers belongs to 
% $\mathrm{SO}_3(\mathbb{R})$ is quite another matter, because very 
% few orthogonal matrices can be exactly represented in 
% floating-point arithmetic, even though approximate representations 
% are easy to come by and suffice for most purposes. A 
% \texttt{member} method with some tolerance would be one way of 
% approaching this, but a more interesting idea is to make the 
% possibility of imperfection explicit and provide a tool to 
% challenge it.
% 
% \begin{APIspec}{subset}{2.0}
%   This is exactly the same as \APIref+{subset}{1.0}, but will be 
%   developed differently.
%   \begin{APIdescription}{subset}
%     \begin{APImethod}{superset}
%       \word{method} \word{argument}\regstar
%     \end{APImethod}
%       The |superset| method gives access to the structure of which 
%       the \meta{subset} is a subset. Every element of the 
%       \meta{subset} is also a valid element of \meta{subset}'s 
%       \texttt{superset}.
%   \end{APIdescription}
% \end{APIspec}
% 
% \begin{APIspec}{subset}{2.1}
%   Version~2.1 is what introduces a tool for approximate 
%   representation.
%   \begin{APIdescription}{subset}
%     \begin{APImethod}{improve}
%       \word{superset element}
%     \end{APImethod}
%       The \word{superset element} is an element of the |superset| 
%       structure which is approximately an element of the 
%       \meta{subset}. This method returns an element of the 
%       |superset| structure which is a better (if possible) 
%       approximation of the same \meta{subset} element.
%   \end{APIdescription}
%   
%   The idea is that by occasionally applying |improve| to things 
%   that have been computed and should be elements of the 
%   \meta{subset}, it is possible to keep one's calculations 
%   approximately within the \meta{subset}, even if the other 
%   operations applied would tend to magnify deviations from the 
%   \meta{subset}.
% \end{APIspec}
% 
% For an example of what \texttt{improve} might do, one can consider 
% some \(A \in \mathrm{SL}_n(\mathbb{R})\). If \(\det A > 1\) then 
% taking a power of $A$ will accumulate this deviation and bring the 
% result further and further away from $\mathrm{SL}_n(\mathbb{R})$. A 
% suitable \texttt{improve} would then be
% \begin{equation*}
%   \texttt{[$\mathrm{SL}_n(\mathbb{R})$ improve $A$]} =
%   (\det A)^{-1/n} A
% \end{equation*}
% since the effect of the right hand side is to rescale $A$ to have 
% determinant $1$ (up to rounding errors).
% 
% \begin{tcl}
%<*docstrip.tcl::catalogue>
pkgProvide mtmtcl::support::subset 1.0 subset
%</docstrip.tcl::catalogue>
% \end{tcl}
% The |mtmtcl::support::subset| package collects some procedures that 
% may come in handy when implementing the \texttt{subset} interfaces.
% 
% \begin{tcl}
%<*subset>
package require Tcl 8.6
package require mtmtcl::support 1.0
namespace eval ::mtmtcl::support::subset {
% \end{tcl}
% \setnamespace{mtmtcl::support::subset}
% 
% \begin{proc}{superexport}
%   The most common way of exporting an element of a subset would be 
%   to delegate the operation to the |superset|, but this cannot be 
%   done by an ensemble mapping alone as there is no way for an 
%   ensemble-with-parameters to insert the new |export| subcommand in 
%   the proper position; procedure help with the argument juggling is 
%   needed. While at that, one should also adjust the |mtmtcl:path| 
%   attribute of the |export| call, to reflect that any methods that 
%   the |superset export| might refer to are methods of the |superset| 
%   rather than the |subset|.
%   
%   The most straightforward way of providing that functionality is 
%   with a procedure that has the call syntax
%   \begin{displaysyntax}
%     ::mtmtcl::support::subset::superexport \meta{subset prefix} 
%     \word{element} \word{common attributes}
%   \end{displaysyntax}
%   and performs the call
%   \begin{displaysyntax}
%     \meta{subset prefix} superset export \word{element} 
%     \word{adjusted attributes}
%   \end{displaysyntax}
%   Here, the \meta{subset prefix} should be the full command prefix 
%   of the |subset| structure. If that structure command $c$ is an 
%   ensemble (possibly with parameters), then what it should map its 
%   |export| subcommand to is simply
%   \begin{displaysyntax}
%     ::mtmtcl::support::subset::superexport $c$
%   \end{displaysyntax}
%   since the parameters (if any) are simply copied straight off.
%   \begin{tcl}
   proc superexport {args} {
      set attrD [lindex $args end]
      dict lappend attrD mtmtcl:path superset
      {*}[lrange $args 0 end-2] superset export [lindex $args end-1]\
        $attrD
   }
%   \end{tcl}
%   A slight disadvantage of this command is that it is vulnerable to 
%   user calling errors: if an |export| call has an argument too much 
%   or too little, then the method names will be inserted in the 
%   wrong place. One argument too little will even lead to an 
%   infinite recursion! (But that should be very noticable, and thus 
%   caught the first time the calling code is tested.)
% \end{proc}
% 
% \begin{proc}{superexport1p}
%   A case which turns out to not be entirely uncommon is that the 
%   parameters of the |superset| are pretty much the same as (or a 
%   superset of) the parameters of the |subset|; then it can be 
%   better to call the |superset| command directly. The 
%   |superexport1p| does the special case that the |superset| command 
%   takes one parameter, and has the call syntax
%   \begin{displaysyntax}
%     ::mtmtcl::support::subset::superexport1p \word{super-command} 
%     \word{parameter1} \word{element} \word{attributes}
%   \end{displaysyntax} 
%   which it translates to
%   \begin{displaysyntax}
%     \word{super-command} \word{parameter1} export \word{element} 
%     \word{attributes$'$}
%   \end{displaysyntax} 
%   \begin{tcl}
   proc superexport1p {command param1 element attrD} {
      dict lappend attrD mtmtcl:path superset
      $command $param1 export $element $attrD
   }
%   \end{tcl}
% \end{proc}
% 
% \begin{proc}{byfilter}
%   This procedure implements a \APIref+{subset}{1.1} by set 
%   comprehension: the subset of elements which satisfy some 
%   condition. In functional programming, this is often known as 
%   filtering; some elements are let through and others are not.
%   
%   The call syntax is
%   \begin{displaysyntax}
%     ::mtmtcl::support::subset::byfilter \word{superset} 
%     \word{filter} \word{method} \word{arg}\regstar
%   \end{displaysyntax}
%   where \word{superset} is the command prefix for the |superset| 
%   structure and \word{filter} is a command prefix with the syntax
%   \begin{displaysyntax}
%     \meta{filter} \word{superset-element}
%   \end{displaysyntax}
%   returning boolean true if the \word{superset-element} is in this 
%   subset and boolean false otherwise.
%   
%   \begin{tcl}
   proc byfilter {superset filter method args} {
      switch -- $method {
%   \end{tcl}
%   The \APIref+{subset}{1.1} methods are pretty obvious.
%   \begin{tcl}
         superset {tailcall {*}$superset {*}$args}
         member {{*}$filter [lindex $args 0]}
%   \end{tcl}
%   A couple of other methods can be delegated to the |superset|. (It 
%   is not checked whether that actually implements them, except when 
%   quering the API.)
%   \begin{tcl}
         = {tailcall {*}$superset = {*}$args}
         canonise {tailcall {*}$superset canonise [lindex $args 0]}
         export {
            set attrD [lindex $args 1]
            dict lappend attrD mtmtcl:path superset
            tailcall {*}$superset export [lindex $args 0] $attrD
         }
%   \end{tcl}
%   An interesting case is that of the |elements| method, where this 
%   procedure does something nontrivial.
%   \begin{tcl}
         elements {
            set res {}
            foreach x [{*}$superset elements] {
               if {[{*}$filter $x]} then {lappend res $x}
            }
            return $res
         }
%   \end{tcl}
%   But besides this, there really isn't all that much that makes 
%   sense for a generic |subset| to provide. Parts of \APIref{direct 
%   product}{1.0} could be implemented, but the |tuple| command 
%   obviously could not. \APIref{named element}{1.0} could also be 
%   provided, but would there be any advantage to it over calling 
%   |superset named| directly? Probably not. \APIref{random 
%   element}{1.0} could similarly be implemented as picking random 
%   elements of the |superset| until one is found that is in the 
%   |subset|, but this could be an extremely inefficient way of 
%   producing them (if the subset is small), and if it is a 
%   reasonable method then it may again be better to let the user 
%   program it explicitly.
%   
%   Thus it is instead best to finish off with the |API| subcommand, 
%   which is delegated to |sdAPI|.
%   \begin{tcl}
         API {
            ::mtmtcl::support::sdAPI {
               equality canonise export onlycanonical autocanonical 
               "finite set" subset 
            } ::mtmtcl::support::subset::byfilter,API \
              2 $superset $filter {} {*}$args
         }
      }
   }
%   \end{tcl}
% \end{proc}
% 
% \begin{proc}{byfilter,API}
%   The compute-prefix for |byfilter| is again a procedure, which 
%   thus has the call syntax
%   \begin{displaysyntax}
%     |::mtmtcl::support::subset::byfilter,API| \word{interface} 
%     \word{superset} \word{filter} |{}| \word{interface}\regopt\ 
%     \word{version}\regopt
%   \end{displaysyntax}
%   It is implemented as another big |switch|.
%   \begin{tcl}
   proc byfilter,API {interface superset filter args} {
      switch -- $interface {
%   \end{tcl}
%   The only \APIref{equality}{1.1} versions we know about are 1.0 
%   and 1.1. Ditto for \APIref{canonise}{1.1}.
%   \begin{tcl}
         equality - canonise - "finite set" {
            if {[{*}$superset API $interface 1.0]} then {
               if {[{*}$superset API $interface 1.1]} then {
                  return {1.0 1.1}
               } else {
                  return {1.0}
               }
            }
         }
%   \end{tcl}
%   For \APIref{export}{2.0} it is 2.0.
%   \begin{tcl}
         export {
            if {[{*}$superset API export 2.0]} then {
               return {2.0}
            }
         }
%   \end{tcl}
%   For \APIref{onlycanonical}{1.0} and \APIref{autocanonical}{1.0} 
%   it is 1.0.
%   \begin{tcl}
         onlycanonical - autocanonical {
            if {[{*}$superset API export 1.0]} then {
               return {1.0}
            }
         }
%   \end{tcl}
%   \APIref{subset}{1.1} is the only interface which is not 
%   completely dependent on the \word{superset}.
%   \begin{tcl}
         subset {return {1.1 2.0}}
      }
   }
%   \end{tcl}
% \end{proc}
% 
% 
% \begin{tcl}
}
%</subset>
% \end{tcl}
% 
% 
% \subsection{Products}
% 
% \begin{APIspec}{direct product}{1.0}
%   A \texttt{direct product} of structures has elements composed from 
%   component structure elements.
%   
%   \begin{APIdescription}{product}
%     \begin{APImethod}{no.components}
%     \end{APImethod}
%       This method returns the number of factors (components) in the 
%       product.
%       
%     \begin{APImethod}{component}
%       \word{index} \word{method} \word{argument}\regstar
%     \end{APImethod}
%       This method gives easy access to component structure methods. 
%       The \word{index} $i$ is an integer \(0 \leqslant i < n\) where 
%       $n$ is the number of factors. The command prefix
%       \begin{displaysyntax}
%         \meta{product} component \word{index}
%       \end{displaysyntax}
%       is a command prefix for the \word{index}th component of the 
%       structure.
%       
%     \begin{APImethod}{index}
%       \word{index} \word{element}
%     \end{APImethod}
%       This returns the projection of the \word{element} onto the 
%       \word{index}th component, an element of the \word{index}th 
%       component structure.
%       
%     \begin{APImethod}{tuple}
%       \word{component}\regstar
%     \end{APImethod}
%       The $i$th \word{component} must be an element of the $i$th 
%       component structure, and there must be exactly 
%       \texttt{[\meta{product} no.components]} \word{component} 
%       arguments. This returns the element of the \meta{product} 
%       structure which consists of the specified \word{component}s.
%   \end{APIdescription}
% \end{APIspec}
% 
% Direct products are normally required to satisfy a decomposition 
% axiom\Ldash two tuples are equal iff they have the same 
% components\Dash but this requires having |equality|.
% 
% \begin{APIspec}{direct product}{1.1}
%   A \texttt{direct product} with equality 
%   
%   \begin{APIdescription}{product}
%     \begin{APImethod}{=}
%       \word{element} \word{element}
%     \end{APImethod}
%       This method satisfies the \APIref{equality}{1.0} interface.
%       
%     \begin{APImethod}{component}
%       \word{index} = \word{argument}\regstar
%     \end{APImethod}
%       Every component structure also satisfies the 
%       \APIref{equality}{1.0} interface.
%   \end{APIdescription}
%   
%   Furthermore the |index| and |tuple| methods have to be congruent, 
%   i.e., if $a$ and $b$ are |=|-equal in the \texttt{direct product} 
%   $P$, then
%   \begin{displaysyntax}
%     [$P$ index $k$ $a$]\par
%     [$P$ index $k$ $b$]
%   \end{displaysyntax}
%   are (\texttt{component}~$k$~|=|)-equal for every $k$, and if 
%   $a_k$ is (\texttt{component}~$k$~|=|)-equal to $b_k$ for every 
%   \(0 \leqslant k < n\),then
%   \begin{displaysyntax}
%     [$P$ tuple $a_0$ \dots~$a_{n-1}$]\par
%     [$P$ tuple $b_0$ \dots~$b_{n-1}$]
%   \end{displaysyntax}
%   are |=|-equal.
% \end{APIspec}
% 
% \begin{tcl}
%<*docstrip.tcl::catalogue>
pkgProvide mtmtcl::sets::cartesian_product 1.1 cartesian
%</docstrip.tcl::catalogue>
% \end{tcl}
% \setnamespace{mtmtcl::sets}
% 
% \begin{ensemble}{cartesian_product}
%   The |cartesian_product| ensemble implements the direct product 
%   of two structures with equality. The general syntax is
%   \begin{displaysyntax}
%     |::mtmtcl::sets::cartesian_product| \word{substructures} 
%     \word{API} \word{method} \word{arg}\regstar
%   \end{displaysyntax}
%   where the \word{substructures} and \word{API} are parameters that 
%   would be part of the structure command prefix. The \word{API} may 
%   be empty, in which case API queries are computed at each call, or 
%   a dictionary.
%   
%   Besides \APIref{equality}{1.0} and \APIref{direct product}{1.1}, 
%   this implementation also tries to satisfy the 
%   \APIref{canonise}{1.1} and \APIref{finite set}{1.1} interfaces, 
%   when the component structures so permit. The latter is because, 
%   from experience, if a set is ``infinite'' then it will typically 
%   also have some additional structure which one might want a 
%   cartesian product to preserve, and then one will typically use 
%   some more specialised cartesian product constructor than this.
%   
%   An element of the cartesian structure is a list of elements in 
%   the substructures; list element $i$ belongs to substructure $i$. 
%   This is part of the documented interface of this package.
%   
%   \begin{tcl}
%<cartesian>package require mtmtcl::support 1.0
%<*cartesian,pkg>
package require Tcl 8.6
namespace eval ::mtmtcl::sets::cartesian_product {
   namespace ensemble create -prefix 0\
     -subcommands {API = component index tuple canonise elements}\
     -parameters {substructures API-dict}
%   \end{tcl}
%   
%   \begin{ensproc}{API}
%     The |API| method implementation makes use of a helper ensemble 
%     also named |API| to compute supported version lists for the 
%     relevant interfaces, but the actual |API| method handler is the 
%     |::mtmtcl::support::sdAPI| command.
%     \begin{tcl}
   namespace ensemble create -command [namespace current]::API -map {
      equality  API,equality
      canonise  API,canonise
      "direct product" API,direct_product
      "finite set" API,finite_set
   } -unknown {list apply {args {}}}
   namespace ensemble configure ::mtmtcl::sets::cartesian_product\
     -map [dict create API [
        list ::mtmtcl::support::sdAPI\
          {"direct product" "equality" "canonise" "finite set"}\
          [namespace which API] 1
   ]]
%     \end{tcl}
%   \end{ensproc}
%   
%   \begin{ensproc}{no.components}
%     The number of components is the number of component structures.
%     \begin{tcl}
   proc no.components {substructures API} {llength $substructures}
%     \end{tcl}
%   \end{ensproc}
%   
%   \begin{ensproc}{component}
%     Accessing a component structure is mostly a matter of indexing. 
%     \begin{tcl}
   proc component {substructures API index args} {
      tailcall {*}[lindex $substructures $index] {*}$args
   }
%     \end{tcl}
%     Using |tailcall| makes it straightforward for the component 
%     structure to use |upvar| (an |uplevel| could work too, but 
%     raises a few issues for impure list command prefixes).
%   \end{ensproc}
%   
%   \begin{ensproc}{index}
%     Apart from the order of arguments, this just |lindex|.
%     \begin{tcl}
   proc index {substructures API index elem} {lindex $elem $index}
%     \end{tcl}
%   \end{ensproc}
%   
%   \begin{ensproc}{tuple}
%     And |tuple| is just |list|, on a subset of the arguments.
%     \begin{tcl}
   proc tuple {substructures API args} {return $args}
%     \end{tcl}
%   \end{ensproc}
%   
%   \begin{ensproc}{=}
%     Two elements are equal iff their components are equal.
%     \begin{tcl}
   proc = {substructures API a b} {
      foreach S $substructures ak $a bk $b {
         if {![{*}$S = $ak $bk]} then {return 0}
      }
      return 1
   }
%     \end{tcl}
%   \end{ensproc}
%   
%   \begin{proc}{API,equality}
%     Testing for \APIref+{equality}{1.0} thus requires that all 
%     component structures support it.
%     \begin{tcl}
   proc API,equality {substructures args} {
      foreach S $substructures {
         if {![{*}$S API equality 1.0]} then {return ""}
      }
      return [list 1.0]
   }
%     \end{tcl}
%     Implementing v\,1.1 instead would be possible, but one cannot 
%     take advantage of the component structures supporting it, so 
%     there doesn't seem to be much point in doing so.
%   \end{proc}
%   
%   \begin{proc}{API,direct_product}
%     The \APIref{direct product}{1.1} version is 1.1 if the 
%     structure has \APIref{equality}{1.0}, and 1.0 otherwise.
%     \begin{tcl}
   proc API,direct_product {substructures args} {
      foreach S $substructures {
         if {![{*}$S API equality 1.0]} then {return [list 1.0]}
      }
      return [list 1.1]
   }
%     \end{tcl}
%     One could alternatively make use of |API,equality| here, but it 
%     is easier to duplicate the test than to parse the result of 
%     |API,equality|.
%   \end{proc}
%   
%   \begin{ensproc}{canonise}
%     A pure list will receive its canonical string representation 
%     when one is requested, so we're fine once the list elements 
%     have been canonised.
%     \begin{tcl}
   proc canonise {substructures API tuple} {
      set res {}
      foreach s $substructures t $tuple {
         lappend res [{*}$s canonise $t]
      }
      return $res
   }
%     \end{tcl}
%   \end{ensproc}
%   
%   \begin{proc}{API,canonise}
%     In order for the product to satisfy \APIref+{canonise}{1.1}, 
%     all its components need to do that as well, but if some only 
%     satisfy \APIref+{canonise}{1.0} then that is what it'll have to 
%     be.
%     \begin{tcl}
   proc API,canonise {substructures args} {
      set minor 1
      foreach S $substructures {
         if {$minor==1} then {
            if {![{*}$S API canonise 1.1]} then {set minor 0}
         }
         if {$minor==0} then {
            if {![{*}$S API canonise 1.0]} then {return ""}
         }
      }
      return [list 1.$minor]
   }
%     \end{tcl}
%   \end{proc}
%   
%   \begin{proc}{elements}
%     The set of elements is constructed component by component; if 
%     $E_i$ is the set of elements of the $i$th component and $P_i$ 
%     is the set of elements in the product of components $\leqslant 
%     i$ then \(P_i = P_{i-1} \times E_i\). The empty product starts 
%     out with one element that is the empty list.
%     \begin{tcl}
   proc elements {substructures API} {
      set res {{}}
      foreach component $substructures {
         set prod {}
         foreach item [{*}$component elements] {
            foreach L $res {
               lappend L $item
               lappend prod $L
            }
         }
         set res $prod
      }
      return $res
   }
%     \end{tcl}
%     A consequence of the above implementation is that the order of 
%     elements is such that the first component changes most rapidly 
%     and the last component changes the slowest. This is probably the 
%     opposite of what one would expect, and could be changed in the 
%     future.
%   \end{proc}
%   
%   \begin{proc}{API,finite_set}
%     In order for the product to satisfy \APIref+{finite set}{1.1}, 
%     all its components need to do that as well, but if some only 
%     satisfy \APIref+{finite set}{1.0} then that is what it'll have to 
%     be.
%     \begin{tcl}
   proc API,finite_set {substructures args} {
      set minor 1
      foreach S $substructures {
         if {$minor==1} then {
            if {![{*}$S API "finite set" 1.1]} then {set minor 0}
         }
         if {$minor==0} then {
            if {![{*}$S API "finite set" 1.0]} then {return ""}
         }
      }
      return [list 1.$minor]
   }
}
%</cartesian,pkg>
%     \end{tcl}
%   \end{proc}
% \end{ensemble}
% 
% 
% \subsection{Metric spaces}
% 
% \begin{APIspec}{metric space}{1.0}
%   A \emph{metric space} is, in general, a set with a real-valued 
%   distance function that satisfies the triangle inequality.
%   
%   \begin{APIdescription}{metric space}
%     \begin{APImethod}{distance}
%       \word{element} \word{element}
%     \end{APImethod}
%       This method returns the distance between the two 
%       \word{element}s, in the form of a |double| (most likely an 
%       IEEE $64$-bit floating point number).
%       
%       For any points $x$, $y$, and $z$ in a metric space $M$, 
%       |distance| must satisfy the conditions
%       \begin{align*}
%         \texttt{[$M$ distance $x$ $y$]} ={}&
%           \texttt{[$M$ distance $y$ $x$]} \text{,}\\
%         \texttt{[$M$ distance $x$ $y$]} \geqslant{}& 0 \text{,}\\
%         \texttt{[$M$ distance $x$ $x$]} ={}& 0 \text{,}\\
%         \texttt{[$M$ distance $x$ $z$]} \leqslant{}&
%           \texttt{[$M$ distance $x$ $y$]} + 
%           \texttt{[$M$ distance $y$ $z$]} \text{.}
%       \end{align*}
%   \end{APIdescription}
%   
%   The reason the method is called |distance| rather than for 
%   example |metric| the latter is somewhat ambiguous; it can also 
%   mean an inner product.
% \end{APIspec}
% 
% \begin{APIspec}{metric space}{1.1}
%   Version~1.1 introduces the correlation between distance and 
%   equality. Technically, it defines what it means to be a 
%   \emph{pseudometric space}, since there is no condition that 
%   elements at $0$ distance are equal.
%   
%   \begin{APIdescription}{metric space}
%     \begin{APImethod}{=}
%       \word{element} \word{element}
%     \end{APImethod}
%       This method satisfies the \APIref+{equality}{1.0} interface.
%     
%     \begin{APImethod}{distance}
%       \word{element} \word{element}
%     \end{APImethod}
%       This method is as specified in the \APIref+{metric 
%       space}{1.0} interface. In addition, if $x$ and $y$ are 
%       |=|-equal elements, then the distance between them is $0$.
%   \end{APIdescription}
%   
%   It follows from the above that |distance| is congruent, because 
%   if $M$ is a metric space where \(x,x',y,y' \in M\) are such that 
%   $x$ and $x'$ are |=|-equal, and $y$ and $y'$ are |=|-equal, then
%   \(
%     \texttt{[$M$ distance $x$ $y$]} \leqslant
%     \texttt{[$M$ distance $x$ $x'$]} +
%       \texttt{[$M$ distance $x'$ $y'$]} +
%       \texttt{[$M$ distance $y'$ $y$]} =
%     \texttt{[$M$ distance $x'$ $y'$]} \leqslant
%     \texttt{[$M$ distance $x'$ $x$]} +
%       \texttt{[$M$ distance $x$ $y$]} +
%       \texttt{[$M$ distance $y$ $y'$]} =
%     \texttt{[$M$ distance $x$ $y$]}
%   \).
% \end{APIspec}
% 
% \begin{APIspec}{metric space}{1.2}
%   Version~1.2 strengthens the correlation between distance and 
%   equality to the normal sense of metric space: if $M$ is a 
%   \APIref+{metric space}{1.2} and \(x,y \in M\) are such that 
%   \texttt{[$M$ distance $x$ $y$]}\({}=0\), then $x$ and $y$ are 
%   |=|-equal.
% \end{APIspec}
%   
% 
% 
% \subsection{Random structure elements}
% 
% For e.g.~testing purposes, it is sometimes convenient to have a 
% source of arbitrary structure elements. Practically this can be 
% implemented as a method which generates ``random'' structure 
% elements from a given source of ``random'' data.
% 
% 
% \begin{APIspec}{random element}{1.0}
%   This interface is applicable to principal structures. 
%   \begin{APIdescription}{structure}
%     \begin{APImethod}{random}
%       \word{PRNG}
%     \end{APImethod}
%       This method returns a random element in the structure. 
%       The \word{PRNG} is a prefix supporting the \APIref+{random 
%       bit}{1.0} and \APIref+{random integer}{1.0} interfaces. 
%       The |random| method should use it as its source of random 
%       data.
%   \end{APIdescription}
% \end{APIspec}
% 
% 
% \subsection{Random number generators}
% 
% Random number generators are present in \mtl\ primarily because the 
% |random element| interface needs them. The definitions here follow 
% those of \emph{The API convention} documentation~\cite{LH:API}.
% 
% 
% \begin{APIspec}{random bit}{1.0}
%   Version 1.0 of |random bit| offers the basic ``flip of a coin''.
%   \begin{APIdescription}{PRNG}
%     \begin{APImethod}{bit}
%     \end{APImethod}
%     Returns |0| or |1|, randomly and with equal probability.
%   \end{APIdescription}
% \end{APIspec}
% 
% \begin{APIspec}{random bit}{2.0}
%   Version 2.0 of |random bit| adds the possibility that the 
%   mechanisms for pseudo-random number generation are present even if 
%   they are uninitialised.
%   \begin{APIdescription}{PRNG}
%     \begin{APImethod}{seeded}
%     \end{APImethod}
%     The |seeded| method is used to check whether \meta{PRNG} is 
%     seeded. It returns |0| if \meta{PRNG} is not fully seeded and 
%     therefore cannot produce output, |1| if \meta{PRNG} has been 
%     fully seeded, and |-1| if it has not been fully seeded but can 
%     generate output anyway.
%     
%     \begin{APImethod}{bit}
%     \end{APImethod}
%     If the |seeded| method returns a boolean true value, then |bit| 
%     will return |0| or |1|, randomly and with equal probability. 
%     The behaviour of |bit| is unspecified if |seeded| returns a 
%     boolean false value.
%   \end{APIdescription}
% \end{APIspec}
% 
% 
% \begin{APIspec}{random integer}{1.0}
%   Version 1.0 of |random integer| offers the basic ``throw of a 
%   dice'' (with variable number of sides).
%   \begin{APIdescription}{PRNG}
%     \begin{APImethod}{integer}
%       \word{min}\regopt\ \word{max}
%     \end{APImethod}
%     Returns an integer $n$ such that \(\mathit{min} \leqslant n 
%     \leqslant \mathit{max}\). If omitted, \word{min} defaults to 
%     $1$. It is an error if \(\mathit{min} > \mathit{max}\). All 
%     valid return values should have the same probability.
%   \end{APIdescription}
% \end{APIspec}
% 
% \begin{APIspec}{random integer}{2.0}
%   Version 2.0 of |random integer| adds the possibility of signalling 
%   that the mechanisms for pseudo-random number generation are present 
%   even if they are uninitialised.
%   
%   \begin{APIdescription}{PRNG}
%     \begin{APImethod}{seeded}
%     \end{APImethod}
%     The |seeded| method is used to check whether \meta{PRNG} is 
%     seeded. It returns |0| if \meta{PRNG} is not fully seeded and 
%     therefore cannot produce output, |1| if \meta{PRNG} has been 
%     fully seeded, and |-1| if it has not been fully seeded but can 
%     generate output anyway.
%     
%     \begin{APImethod}{integer}
%       \word{min}\regopt\ \word{max}
%     \end{APImethod}
%     If the |seeded| method returns a boolean true value, then 
%     |integer| returns an integer $n$ such that \(\mathit{min} 
%     \leqslant n \leqslant \mathit{max}\). If omitted, \word{min} 
%     defaults to $1$. It is an error if \(\mathit{min} > 
%     \mathit{max}\). All valid return values should have the same 
%     probability.
%     
%     The behaviour of |integer| is unspecified if |seeded| returns 
%     a boolean false value.
%   \end{APIdescription}
% \end{APIspec}
% 
% 
% \subsection{Helper procedures}
% 
% \begin{tcl}
%<*docstrip.tcl::catalogue>
pkgProvide mtmtcl::support 1.0 support
%</docstrip.tcl::catalogue>
%<*support,pkg>
namespace eval ::mtmtcl::support {}
% \end{tcl}
% \setnamespace{mtmtcl::support}
% 
% \begin{proc}{constant}
%   This procedure takes one argument and returns it.
%   \begin{tcl}
proc ::mtmtcl::support::constant {arg} {return $arg}
%   \end{tcl}
%   This is probably not needed; |::return -level 0| does this too.
% \end{proc}
% 
% \begin{proc}{sdAPI}
%   The |sdAPI| procedure can be used to give a uniform handling of 
%   static and dynamic API queries. It has the call syntax
%   \begin{displaysyntax}
%     ::mtmtcl::support::sdAPI \word{interface-list} 
%     \word{compute-prefix} \word{parameter count} \meta{parameters} 
%     \word{API-dict} \word{interface}\regopt\ \word{version}\regopt
%   \end{displaysyntax}
%   where the last three items are as for the |::API::static| 
%   command. A nonempty \word{API-dict} signals that the API is 
%   precomputed and need only be parsed, but otherwise it is up to 
%   this command to supervise the computation of the API.
%   
%   The idea is that the \word{compute-prefix} should be an 
%   ensemble-like command prefix with interfaces as subcommands. 
%   The call syntax for these commands is
%   \begin{displaysyntax}
%     \meta{compute-prefix} \word{interface} \meta{parameters}
%     \word{API-dict} \word{interface}\regopt\ \word{version}\regopt
%   \end{displaysyntax}
%   where the two optional arguments are what was in the call to 
%   |sdAPI|; these are usually not so interesting, but it is easier 
%   to pass them on than it is to remove them. These calls return a 
%   list of versions that they support for the first \word{interface}; 
%   the list would typically be the list of all versions 
%   supported, but \emph{if} there is an explicit \word{version} and 
%   it is cheaper to test for only this than to list all supported 
%   versions, then it is perfectly acceptable to return only this 
%   version.
%   
%   The \word{parameter count} argument is the number of 
%   elements in the \meta{parameters}, which is needed to identify 
%   the \word{API-dict} etc.~arguments. The reason for this call 
%   syntax is that |sdAPI| might be used as implementation of the 
%   |API| method in an ensemble with parameters.
%   
%   \begin{tcl}
proc ::mtmtcl::support::sdAPI {interfaces prefix paramcount args} {
   set tail [lrange $args $paramcount end]
   if {[dict size [lindex $tail 0]]} then {
      return [::API::static {*}$tail]
   }
   if {[llength $tail] > 1} then {
      set verL [{*}$prefix [lindex $tail 1] {*}$args]
      if {[llength $tail] == 2} then {
         return $verL
      }
      foreach ver $verL {
         if {[package vsatisfies $ver [lindex $tail 2]]} then {
            return 1
         }
      }
      return 0
   }
   set res [dict create]
   foreach interface $interfaces {
      set verL [{*}$prefix $interface {*}$args]
      if {[llength $verL]} then {dict set res $interface $verL}
   }
   return $res
}
%</support,pkg>
%   \end{tcl}
% \end{proc}
% 
% 
% \subsubsection{Ensemble variant families}
% 
% It often happens that a structure operation needs to be implemented 
% in several different ways, depending on the features provided by 
% the underlying structures: sometimes subtraction is provided as a 
% separate operation, whereas other times it will have to be done by 
% a combination of negation and addition. Dynamically choosing one 
% implementation or the other is one possibility, but it would be 
% neater if already the ensemble of the structure took care of 
% routing all calls to the correct implementation. The main obstacle 
% to setting up that manually is that there can be several 
% independent implementation variants, which (by the multiplication 
% principle) would combine to a rather large set of implementing 
% ensembles; easily too many to manage manually.
% 
% The idea of having variant families of ensembles is instead that 
% an ensemble is only created on demand, when a |make|-command 
% returns a prefix that would make use of it. Each variant is 
% assigned a unique name, so different variants can coexist, but 
% different command prefixes that make use of the same variant will 
% call the same underlying ensemble command; there is no need for any 
% garbage collection as the ensemble commands are not owned by the 
% command prefixes they are generated for.
% 
% To begin defining an ensemble variant, one uses the command
% \begin{displaysyntax}
%   mtmtcl::support::vensemble::start \word{variable} \word{namespace} 
%   \word{root} \begin{regblock}[\regstar] \word{option} \word{value} 
%   \end{regblock}
% \end{displaysyntax}
% The \word{variable} is the name of a variable in the local context 
% of the caller; this is used to store a preliminary definition of 
% the ensemble, which will be modified by subsequent commands, until 
% finalised by the |finish| command. The \word{namespace} is the 
% namespace of the ensemble, where not-fully-qualified names are 
% interpreted relative to the current namespace in the calling context; 
% an empty \word{namespace} refers to that current namespace. The 
% \word{root} is used as root of the name for the ensemble command to 
% create; to this will be appended a suffix that is unique for each 
% variant. If the \word{root} is empty then it is taken equal to the 
% name of the ensemble's namespace. If the \word{root} is not fully 
% qualified then the components of the current 
% namespace in the calling context are prepended to this to make it 
% fully qualified. The \word{option}s and \word{value}s can be used 
% to specify additional options for the ensemble to create; this is 
% mostly useful for the |-prefixes| and |-parameters| options, as the 
% other options are managed by the ensemble variant mechanisms.
% 
% To finish defining an ensemble variant, one uses the command
% \begin{displaysyntax}
%   mtmtcl::support::vensemble::finish \word{variable}
%   \begin{regblock}[\regstar] \word{option} \word{value} 
%   \end{regblock}
% \end{displaysyntax}
% which returns the fully qualified name of the ensemble command 
% whose variant was encoded into the \word{variable}, if necessary 
% creating that command first. The \word{option} and \word{value} 
% arguments give another chance of setting unmanaged options of the 
% ensemble. In addition, there is an option |-withapi| which takes an 
% API-dict as \word{value}; it creates an |API| subcommand that is 
% mapped to |API::static| or |API::staticn| as required for the 
% effective |-parameters| setting.
% 
% Between these two commands, one may use
% \begin{displaysyntax}
%   mtmtcl::support::vensemble::subcommands \word{variable}
%   \word{subcommand-name}\regstar
%   \par
%   mtmtcl::support::vensemble::mapping \word{variable}
%   \word{subcommand-name} \meta{prefix}
%   \par
%   mtmtcl::support::vensemble::variation \word{variable}
%   \word{choice} \begin{regblock}[\regstar] \word{subcommand-name} 
%   \word{prefix-list} \end{regblock}
% \end{displaysyntax}
% to add subcommands to the ensemble description in the 
% \word{variable}. The ensemble as a whole is of the |-map|-based 
% type; the |subcommands| command adds each \word{subcommand-name} as 
% a mapping to itself and the |mapping| command adds one mapping to a 
% custom prefix.
% 
% For |variation|, each \word{prefix-list} is a \emph{list} of 
% prefixes (where each prefix is itself a list), of which one is 
% picked as that which the \word{subcommand-name} is mapped to; it is 
% an error if different \word{prefix-list}s of the same |variation| 
% call have different lengths. Which element is picked is controlled 
% by the \word{choice}, which must be a nonnegative integer. This integer 
% (in hexadecimal) is appended to the name of the ensemble command, 
% to make sure that ensembles made with different choices have 
% different command names. An element in a \word{prefix-list} that is 
% `|-|' (a hyphen) is interpreted as ``same as the next element'', in 
% analogy with how hyphen branches are treated in |switch|. An 
% element that is empty means ``don't define this subcommand in this 
% variant''.
% 
% One variation can control several subcommands, but each subcommand 
% can only be dependent on one |variant|. It is not necessary that 
% the \word{choice}s for separate |variant| calls are independent; 
% the only harm there can be in that is getting a slightly longer 
% name for the ensemble command. The |variation| command returns the 
% \word{choice}, so that it may be reused in further processing (see 
% the |apichoice| command).
% 
% For more general variation, one may use
% \begin{displaysyntax}
%   mtmtcl::support::vensemble::branch \word{variable} \word{choice} 
%   \word{script}\regplus\par
%   mtmtcl::support::vensemble::when \word{variable} 
%   \begin{regblock}[\regstar] \word{condition} \word{script} 
%   \end{regblock}
% \end{displaysyntax}
% for which the variability consists of evaluating one of the 
% \word{script}s, which in turn may contain |subcommands| and 
% |mapping| commands to define subcommands of the ensemble. Like 
% |variation|, but unlike the core conditionals |if| and |switch|, 
% the |branch| and |when| commands record the choice made in the name 
% of the ensemble being constructed. For |branch|, the \word{choice} 
% is a nonnegative integer just as for |variation|; it is an error if 
% the \word{choice} is greater than or equal to the number of 
% \word{script}s. For |when|, the choice is instead computed by the 
% command itself: the \word{condition}s are |expr|essions evaluated 
% one by one until encountering one that is true, and then the 
% corresponding \word{script} will be the one chosen; it behaves like 
% an |elseif| chain. If the last \word{condition} is |1| (as 
% expression, not merely in value) then that behaves as the final 
% |else| branch, otherwise a final choice with empty \word{script} is 
% implicitly provided. Both |branch| and |when| return the effective 
% \word{choice} used.
% 
% For even more free-form variations, there is
% \begin{displaysyntax}
%   mtmtcl::support::vensemble::freechoice \word{variable} 
%   \word{choice}
% \end{displaysyntax}
% where \word{choice} is still a natural number, but unlike all 
% previous cases not limited to a particular range. This is intended 
% for situations where the number of possible choices is large 
% (perhaps infinite), but the number of choices that at any run will 
% be realised remains small; situations where the potential and the 
% actual are quite different. The command \emph{only} affects the 
% ensemble by encoding the \word{choice} into the command name, so 
% whatever calls for this variation remains the responsibility of the 
% user (both to effect and to contain).
% 
% A suggested rule of thumb is that if a variation can be 
% characterised by one string literal that is explicit somewhere in 
% the source code (of the whole program, not necessarily in the source 
% code of the package calling |vensemble::finish|) then it can be 
% justified to use |freechoice| for that variation, whereas if the 
% variation is not so explicit then it is probably better encoded 
% into an ensemble parameter.
% 
% 
% \begin{tcl}
%<*docstrip.tcl::catalogue>
pkgProvide mtmtcl::support::vensemble 1.0 vensemble
%</docstrip.tcl::catalogue>
%<*vensemble>
package require API 1.0
namespace eval mtmtcl::support::vensemble {
% \end{tcl}
% \setnamespace{mtmtcl::support::vensemble}
% \begin{variable}{force}
%   There is a variable |force| which takes a boolean value. When 
%   true, this causes |finish| to always redefine the ensemble 
%   command even if it already exists, whereas when false the 
%   ensemble command will not be redefined if it already exists. The 
%   default setting of false is natural in production environments, 
%   but for interactive development setting it to true simplifies 
%   replacing a buggy definition with a fixed one.
%   \begin{tcl}
   variable force 0
}
%   \end{tcl}
% \end{variable}
% 
% 
% \begin{proc}{start}
%   As stated above, the |start| procedure has the syntax
%   \begin{displaysyntax}
%     mtmtcl::support::vensemble::start \word{variable} \word{namespace} 
%     \word{root} \begin{regblock}[\regstar] \word{option} \word{value} 
%     \end{regblock}
%   \end{displaysyntax}
%   \begin{tcl}
proc mtmtcl::support::vensemble::start {var namespace root args} {
   upvar 1 $var D
   set D [dict create {*}$args]
   set ns [uplevel 1 {namespace current}]
   switch -glob -- $namespace "::*" {
      dict set D -namespace $namespace
   } "" {
      dict set D -namespace $ns
   } default {
      dict set D -namespace ${ns}::${namespace}
   }
   switch -glob -- $root "::*" {
      dict set D -command $root
   } "" {
      dict set D -command [dict get $D -namespace]
   } default {
      dict set D -command ${ns}::${root}
   }
   dict append D -command +
   dict set D -map {}
}
%   \end{tcl}
%   The |-subcommands| are not used, so never initialised.
% \end{proc}
% 
% \begin{proc}{subcommands}
%   Instead the |subcommands| procedure will install a mapping of 
%   each \word{subcommand} to itself.
%   \begin{tcl}
proc mtmtcl::support::vensemble::subcommands {var args} {
   upvar 1 $var D
   foreach subcmd $args {
      dict set D -map $subcmd [list $subcmd]
   }
}
%   \end{tcl}
% \end{proc}
% 
% \begin{proc}{mapping}
%   Mapping a subcommand to a differently named command can be done 
%   as a |mapping|. A non-fully-qualified name gets appended to the 
%   ensemble's namespace by |namespace ensemble|. Each word of the 
%   target prefix is a separate argument of |mapping|, which means it 
%   is easy to explicitly include a |[namespace current]| or whatnot 
%   if that is what is desired.
%   \begin{tcl}
proc mtmtcl::support::vensemble::mapping {var subcmd args} {
   upvar 1 $var D
   dict set D -map $subcmd $args
}
%   \end{tcl}
% \end{proc}
% 
% 
% \begin{proc}{variation}
%   In summary, this command has the call syntax
%   \begin{displaysyntax}
%     mtmtcl::support::vensemble::variation 
%     \word{vensemble-var} \word{choice}
%     \begin{regblock}[\regstar] \word{subcommand} \word{prefix-list} 
%     \end{regblock}
%   \end{displaysyntax}
%   where \word{vensemble-var} is the name in the calling context of 
%   the variable in which the preliminary definition of the ensemble 
%   variant is being stored; modifying this variable is what the 
%   command does. The return values is the \word{choice}.
%   \begin{tcl}
proc mtmtcl::support::vensemble::variation {varname choice args} {
   upvar 1 $varname V
   foreach {subcommand prefixL} $args {
      if {![info exists len]} then {
         set len [llength $prefixL]
      } elseif {$len != [llength $prefixL]} then {
         return -code error "Inconsistent number of choices for:\
           $subcommand"
      }
      set c $choice
      while {$c<[llength $prefixL] &&\
        [llength [lindex $prefixL $c]]==1 &&\
        [lindex $prefixL $c] eq "-"} {incr c}
      if {[llength [lindex $prefixL $c]] > 0} then {
         dict set V -map $subcommand [lindex $prefixL $c]
      }
   }
   if {![info exists len]} then {return}
   if {$choice >= $len || $choice<0} then {
      return -code error "Choice $choice not in range."
   }
   set digits [string length [format %x [incr len -1]]]
   dict append V -command [format %0${digits}x $choice]
   return $choice
}
%   \end{tcl}
% \end{proc}
% 
% \begin{proc}{branch}
%   Choosing one branch by index is quite straightforward.
%   \begin{tcl}
proc mtmtcl::support::vensemble::branch {varname choice args} {
   upvar 1 $varname D
   set len [string length [format %x [expr {[llength $args]-1}]]]
   dict append D -command [format %0*x $len $choice]
   uplevel 1 [lindex $args $choice]
   return $choice
}
%   \end{tcl}
% \end{proc}
% 
% \begin{proc}{when}
%   Choosing one branch based on evaluating conditions is a bit 
%   more work, but still fairly straightforward. First do some error 
%   checking \dots
%   \begin{tcl}
proc mtmtcl::support::vensemble::when {varname args} {
   upvar 1 $varname D
   if {[llength $args] & 1} then {
      return -code error "wrong # args: should be\
        \"[namespace which when] varname ?condition script ...?\""
   }
%   \end{tcl}
%   \dots\ then figure out which branch to take and evaluate it \dots
%   \begin{tcl}
   set choice 0
   foreach {cond script} $args {
      if {[uplevel 1 [list ::expr $cond]]} then {
         uplevel 1 $script
         break
      }
      incr choice
   }
%   \end{tcl}
%   \dots\ finally record the choice in the command name.
%   \begin{tcl}
   set last [expr {[llength $args]/2}]
   if {[lindex $args end-1] eq "1"} then {incr last -1}
   dict append D -command\
     [format %0*x [string length [format %x $last]] $choice]
   return $choice
}
%   \end{tcl}
% \end{proc}
% 
% 
% \begin{proc}{freechoice}
%   On the practical side, this is \emph{only} about appending a 
%   number to the command name, but there is the extra complication 
%   that the number of digits in that number is not fixed, so how can 
%   one tell where it ends? The following exploits some properties of 
%   the ASCII table to injectively map the \emph{last} digit to an 
%   upper case letter (|0|--|9| becomes |P|--|Y|).
%   \begin{tcl}
proc mtmtcl::support::vensemble::freechoice {varname choice} {
   upvar 1 $varname D
   set hex [format {%llx} $choice]
   scan [string index $hex end] %c c
   dict append D -command [string range $hex 0 end-1]\
     [format %c [expr {$c&31 | 64}]]
}
%   \end{tcl}
% \end{proc}
% 
% 
% \begin{proc}{finish}
%   The actual definition work is carried out by the |finish| procedure.
%   \begin{tcl}
proc mtmtcl::support::vensemble::finish {varname args} {
   variable force
   upvar 1 $varname D
   foreach {key val} $args {dict set D $key $val}
   if {[dict exists $D -withapi]} then {
      if {![dict exists $D -parameters]} then {
         set call [list ::API::static]
      } else {
         set call [list ::API::nstatic\
           [llength [dict get $D -parameters]]]
      }
      lappend call [dict get $D -withapi]
      dict set D -map API $call
   }
   if {$force ||\
     [namespace which -command [dict get $D -command]] eq ""} then {
      namespace inscope [dict get $D -namespace] {
         ::namespace ensemble create
      } {*}[dict filter $D key -command -map -prefixes -parameters -unknown]
   }
   return [dict get $D -command]
}
%   \end{tcl}
%   Possibly this should, when not creating the ensemble command but 
%   called |-withapi|, verify that the two API-dicts are equivalent.
% \end{proc}
% 
% \begin{proc}{apichoice}
%   This procedure adds material to an API dictionary based on a 
%   choice, similar to how |variation| adds material to an ensemble 
%   |-map|. The call syntax is
%   \begin{displaysyntax}
%     mtmtcl::support::vensemble::apichoice \word{dict-var} 
%     \word{choice} \word{addition}\regstar
%   \end{displaysyntax}
%   where \word{dict-var} is the name in the calling context of the 
%   variable that will be modified; the return value is the 
%   \word{choice}, which is also used as index into the list of 
%   \word{addition}s. An \word{addition} is either a dash `|-|' 
%   (meaning `same as the next item') or an API-style dictionary. 
%   The way an \word{addition} is merged into the \word{dict-var} is 
%   that corresponding version lists are concatenated.
%   \begin{tcl}
proc mtmtcl::support::vensemble::apichoice {var choice args} {
   upvar 1 $var D
   set c $choice
   while {[lindex $args $c] eq "-"} {incr c}
   dict for {interface verL} [lindex $args $c] {
      dict lappend D $interface {*}$verL
   }
   return $choice
}
%   \end{tcl}
% \end{proc}
% 
% \begin{tcl}
%</vensemble>
% \end{tcl}
% 
% 
\endinput