// FILE. . . . . d:/hak/hlt/src/hlt/fot/fuz/syntax/sources/fff-description.grm
// EDIT BY . . . Hassan Ait-Kaci
// ON MACHINE. . Hak-Laptop
// STARTED ON. . Tue Aug 21 05:03:21 2018

// Last modified on Fri Apr 26 08:27:59 2019 by hak

 /**
  * In <b><tt>FFF</tt></b>, one can specify similar pairs of functors
  * and compute the least similarity on this signature containing these
  * pairs.  On a complete and consistent similarity on a signature, one
  * then can compute fuzzy lattice operations, where the <i>infimum</i>
  * operation (<tt>&and;</tt>) is unification and the <i>supremum</i>
  * operation (<tt>&or;</tt>) is generalization, modulo the specified
  * signature similarity.  One can also specify partial
  * argument-position alignment maps for some pairs of similar functors,
  * and ask <b><tt>FFF</tt></b> to verify their consistency, by
  * introducing new functors if necessary to obtain a consistent total
  * argument-position maps for all similarity classes, or establish that
  * such a completion is not possible by pointing out existing
  * inconsistencies among the specified maps. <b>N.B.</b>: at the time
  * of this documentation's writing, these last two features (the
  * pragmas "<tt>#map</tt>" and "<tt>#comp</tt>") have not been
  * implemented yet. But everything else that has been published is
  * implemented and <b><tt>FFF</tt></b> runs as predicted there. See:
  *
  * <ul>
  *
  * <li><a target="_blank"
  * href="http://hassan-ait-kaci.net/pdf/fuzfotlats-lopstr2017.pdf">conference
  * paper</a>;</li>
  *
  * <li><a target="_blank"
  * href="http://hassan-ait-kaci.net/pdf/fuzfotlats-lopstr2017-slides.pdf">presentation
  * slides</a>.</li>
  *
  * </ul>
  *
  * <p>To illustrate <b><tt>FFF</tt></b> code and runs, here are <a
  * href="../../examples.html">a few examples</a>.</b>
  *
  * <ul>
  *
  * <p><li><b><i>Declarations</i>:</b>
  *
  * In <b><tt>FFF</tt></b>, one may declare and verify properties of
  * various components of a first-order term signature and a similarity
  * on it by using a <i>pragma</i>. A pragma is a command that has a
  * specific effect. It has a name starting with the character
  * ('<tt>#</tt>') and a pragma's name may be possibly followed by
  * arguments. The number, order, nature, and syntax of such arguments
  * depend on the pragma (see below). An <b><tt>FFF</tt></b> pragma is
  * executed upon reading its ending semi-colon ('<tt>;</tt>') followed
  * by a carriage-return on the current input stream (either the standard
  * input or a file).
  *
  * <p>
  *
  * The pragmas that are currently supported are
  * <a href="#info" name="infoitem"><tt>#info</tt></a>,
  * <a href="#fun" name="funitem"><tt>#fun</tt></a>,
  * <a href="#sig" name="sigitem"><tt>#sig</tt></a>,
  * <a href="#sim" name="simitem"><tt>#sim</tt></a>,
  * <a href="#close" name="closeitem"><tt>#close</tt></a>,
  * <a href="#show" name="showitem"><tt>#show</tt></a>,
  * <a href="#funclass" name="funclassitem"><tt>#funclass</tt></a>,
  * <a href="#termclass" name="termclassitem"><tt>#termclass</tt></a>,
  * <a href="#funrep" name="funrepitem"><tt>#funrep</tt></a>,
  * <a href="#termrep" name="termrepitem"><tt>#termrep</tt></a>,
  * <a href="#map" name="mapitem"><tt>#map</tt></a>,
  * <a href="#comp" name="compitem"><tt>#comp</tt></a>,
  * <a href="#load" name="loaditem"><tt>#load</tt></a>,
  * <a href="#trace" name="traceitem"><tt>#trace</tt></a>,
  * and
  * <a href="#reset" name="resetitem"><tt>#reset</tt></a>,
  * and are defined below. One enters:
  *
  * <ul>
  *
  * <li><a name="info" href="#infoitem"><tt><b>#info #pragma</b>;</tt></a></li>
  *
  * <p>to print a description of pragma <tt>#pragma</tt>; if invoked with
  * no argument (</i>i.e.</i>, <tt>#info;</tt>), to print the list of
  * defined pragmas;
  *
  * <li><a name="fun" href="#funitem"><tt><b>#fun</b> <i>f<sub>1</sub>/n<sub>1</sub> ... f<sub>k</sub>/n<sub>k</sub></i>;</tt></a></li>
  *
  * <p>to declare signature functor symbols, where
  * <tt><i>f<sub>i</sub></i></tt> is an identifier denoting a functor's
  * name being declared, and <tt><i>n<sub>i</sub></i></tt> is a natural
  * number specifying its arity, for each <tt><i>i = 1,...,k</i></tt>,
  * then print the current signature; the slashes "<tt>/</tt>" are
  * optional and can be blank space; <i>e.g.</i>, <tt>#fun
  * <i>f<sub>1</sub> n<sub>1</sub> ... f<sub>k</sub>
  * n<sub>k</sub></i>;</tt>;
  *
  * <li><a name="sig" href="#sigitem"><tt><b>#sig</b>;</tt></a></li>
  *
  * <p>to print the current signature (same as "<tt>#fun;</tt>");
  *
  * <li><a name="sim" href="#simitem"><tt><b>#sim</b> <i>f<sub>1</sub> g<sub>1</sub> &alpha;<sub>1</sub> ... f<sub>k</sub> g<sub>k</sub> &alpha;<sub>k</sub></i>;</tt></a></li>
  *
  * <p>to declare similar pairs of functors, where
  * <tt><i>f<sub>i</sub></i></tt> and <tt><i>g<sub>i</sub></i></tt>
  * denote (necessarily distinct and similar) functors' names and each
  * <tt><i>&alpha;<sub>i</sub></i></tt> is a value in the interval
  * <tt>(0.0,1.0]</tt> defining their similariy degree, for each <tt><i>i
  * = 1,...,k</i></tt>; then print the set of all declared similar pairs;
  *
  * <li><a name="close" href="#closeitem"><tt><b>#close</b>;</tt></a></li>
  *
  * <p>to compute the similarity closure of the set of fuzzy pairs
  * that have been declared for the current signature;
  *
  * <li><a name="show" href="#showitem"><tt><b>#show</b>;</tt></a></li>
  *
  * <p>to display the currently declared similar pairs on the current
  * signature as a square matrix on the signature, of values in
  * <tt>[0.0,1.0]</tt>; it also displays its corresponding set of
  * similarity degrees, and lists the partitions per similarity degrees;
  *
  * <li><a name="funclass" href="#funclassitem"><tt><b>#funclass</b> <i>f &alpha;</i>;</tt></a></li>
  *
  * <p>if the similarity has been closed, to display the similarity
  * class of functor <i><tt>f</tt></i> at similarity degree
  * <i><tt>&alpha;</tt></i>;
  *
  * <li><a name="termclass" href="#termclassitem"><tt><b>#termclass</b> <i>t &alpha;</i>;</tt></a></li>
  *
  * <p>if the similarity has been closed, to display the similarity
  * class of FOT <i><tt>t</tt></i> at similarity degree
  * <i><tt>&alpha;</tt></i>;
  *
  * <li><a name="funrep" href="#funrepitem"><tt><b>#funrep</b> <i>f &alpha;</i>;</tt></a></li>
  *
  * <p>if the similarity has been closed, to show the similarity
  * class representative of functor <i><tt>f</tt></i> at similarity
  * degree <i><tt>&alpha;</tt></i>;
  *
  * <li><a name="termrep" href="#termrepitem"><tt><b>#termrep</b> <i>t &alpha;</i>;</tt></a></li>
  *
  * <p>if the similarity has been closed, to show the similarity
  * class representative of FOT <i><tt>t</tt></i> at similarity degree
  * <i><tt>&alpha;</tt></i>;
  *
  * <li><a name="map" href="#mapitem"><tt><b>#map</b> <i>f g &alpha; i<sub>1</sub>:j<sub>1</sub> ... i<sub>k</sub>:j<sub>k</sub></i>;</tt></a></li>
  *
  * <p> to specify an argument-position map where:
  *
  * <ul>
  *
  * <li><tt><i>f</i></tt> and <tt><i>g</i></tt> are (necessarily distinct
  * and similar) functors;</li>
  *
  * <li><tt><i>&alpha;</i></tt> is a value in the interval
  * <tt>(0.0,1.0]</tt> that belongs to the (finite) set of known
  * approximation degrees in the current similarity on the current
  * functor signature (if it is not, it will be set <i>de facto</i> to
  * the greatest known positive degree in the similary that has a lesser
  * value if one exists, otherwise this will generate an error);</li>
  *
  * <li><tt><i>k</i></tt> is a natural number such that <tt><i>0 &le; k
  * &le; Math.min(f.arity(),g.arity())</i></tt>;</li>
  *
  * <li>each <tt><i>i:j</i></tt> is a pair of non-zero natural numbers
  * such that <tt>1 <i>&le; i &le; f.arity()</i></tt> and <tt>1 <i>&le; j
  * &le; g.arity()</i></tt> that indicates which argument positions of
  * <tt><i>f</i></tt> and <tt><i>g</i></tt> are in (necessarily
  * injective) mutual correspondence at approximation level
  * <tt><i>&alpha;</i></tt>.</i>
  *
  * </ul>
  *
  * <p> This is therefore equivalent to <tt><b>#map</b> <i>g f &alpha;
  * j<sub>1</sub>:i<sub>1</sub> ... j<sub>k</sub>:i<sub>k</sub></i></tt>.
  *
  * <p>Note that when <tt><i>k=0</i></tt> (<i>i.e.</i>, just entering
  * <tt>#map <i>f g &alpha;</i>;</tt>), the similarity between any two
  * term structures whose root symbols are these respective functors will
  * involve none of their subterms at approximation degree
  * <tt><i>&alpha;</i></tt> or less, regardless of whether either of
  * their respective arities is non-zero.
  *
  * <p><b>N.B.</b>: a <tt>#map</tt> pragma may be executed several times
  * on the same two functors <tt><i>f</i></tt> and <tt><i>g</i></tt> for
  * a same or different <tt><i>&alpha;</i></tt>. Upon invoking the pragma
  * <a href="#comp"><tt>#comp</tt></a>, the compound effects on the same
  * pair will result, in the order specified if these position maps are
  * verified to be consistent, later ones overriding the effects of any
  * earlier ones executed. Also, for any pair of functors
  * <tt>&#10216;<i>f,g</i>&#10217;</tt> for which no <tt>#map</tt> is
  * specified, the default is the identity on <tt>{1, ...,
  * <i>Math.min(f.arity(),g.arity())</i>}</tt>.
  *
  * <p>Executing a <tt>#map</tt> defines how argument positions of
  *    similar functors correspond to one another. Therefore, it refers
  *    the similarity that has been defined. If no similarity is
  *    defined, it will define one as necessary; that is, the effect of
  *    <tt>#map <i>f g &alpha;</i> ...;</tt> may trigger an automatic
  *    <tt>#sim <i>f g &alpha;</i>;</tt> if needed.
  *
  *
  * <li><a name="comp" href="#compitem"><tt><b>#comp</b>;</tt></a></li>
  *
  * <p>to verify all the necessary <i>consistency conditions for partial
  * non-aligned similar functor arguments</i>. That is, that all the
  * declared argument-position maps between any similar pair of functors
  * for the current signature's similarity, as the approximation degree
  * decreases:
  *
  * <ol>
  *
  * <li>have monotonically decreasing domains and ranges;</li>
  *
  * <li>are one-to-one from domain to range (and vice-versa); and,</li>
  *
  * <li>are consistent under argument-position map composition,
  *     completing the signature and its similarity if necessary and if
  *     a consistent completion is possible, or indicating that such a
  *     completion is not possible due to a mapping specification
  *     inconsistency and what causes it.</li>
  *
  * </ol>
  *
  * <p>(<a
  *     href="http://hassan-ait-kaci.net/pdf/partial-non-aligned-maps-prelim-june-2018.pdf">Click
  *     here</a> for details.)
  *
  * <p>Because a <tt>#map</tt> may implicitly trigger a <tt>#sim</tt> if
  * needed, executing a <tt>#comp;</tt> may trigger a <tt>#close;</tt>
  * as needed.
  *
  * <li><a name="load" href="#loaditem"><tt><b>#load</b> <i>"file"</i>;</tt></a></li>
  *
  * <p>to load  the clauses contained in the specified
  * file and process them in reading order;
  *
  * <li><a name="trace" href="#traceitem"><tt><b>#trace <i>n</i></b>;</tt></a></li>
  *
  * <p>where <tt><i>n</i></tt> is a natural number, to turn on tracing
  * mode at a verbosity detail level of <tt><i>n</i></tt> (the greater,
  * the more verbose).  To turn off tracing mode, one uses <tt>#trace
  * 0;</tt>. When in tracing mode, <tt>FFF</tt> gives details of what it
  * does (useful for debugging or if one wishes to see this sort of
  * information);
  *
  * <li><a name="reset" href="#resetitem"><tt><b>#reset</b>;</tt></a></li>
  *
  * <p>to erase all declared functors, resetting the signature and the
  * similarity.
  *
  * </ul></li>
  *
  * <p><li><b><i>Evaluations</i>:</b>
  *
  * <b><tt>FFF</tt></b> can evaluate term similarity and lattice
  * operations on two well-formed first-order terms.  These operations
  * it performs are fuzzy unless no similarity is defined, in which case
  * they are crisp. Such an expression has one of the following forms
  * and is evaluated upon a carriage-return. Enter:
  *
  * <ul>
  *
  * <li><p><b><tt>lhs ~ rhs;</tt></b>
  *
  * <p>where <tt>lhs</tt> and <tt>rhs</tt> are first-order terms, and
  * <b><tt>FFF</tt></b> will tell you how similar these two terms are
  * with an approximation degree <tt>&alpha;</tt> &isin;
  * <tt>[0.0,1.0]</tt> (if no similarity is defined, this can only be
  * equality: <i>i.e.</i>, either <tt>0.0</tt> or <tt>1.0</tt>);
  *
  * <li><b><tt>lhs /\\ rhs;</tt></b>
  *
  * <p>where <tt>lhs</tt> and <tt>rhs</tt> are first-order terms
  * possibly sharing variables, and <b><tt>FFF</tt></b> will try to
  * fuzzy-unify them. If they are unifiable (<i>i.e.</i>, if the
  * resulting fuzzy degree <tt>&alpha;</tt> is greater than <tt>0</tt>),
  * <b><tt>FFF</tt></b> will print the resulting term that is their
  * fuzzy-greatest common instance <tt>glb</tt>, along with the most
  * general unifying substitution <tt>&sigma;</tt> and fuzzy degree
  * <tt>&alpha;</tt> &isin; <tt>(0.0,1.0]</tt> such that <tt>glb</tt>
  * &asymp;<sub><tt>&alpha;</tt></sub> <tt>&sigma;(lhs)</tt>
  * &asymp;<sub><tt>&alpha;</tt></sub> <tt>&sigma;(rhs)</tt>.  If not
  * (<i>i.e.</i>, if the resulting fuzzy degree <tt>&alpha;</tt> is
  * equal to <tt>0.0</tt>), <b><tt>FFF</tt></b> will print a message
  * indicating that the terms are not unifiable.</li>
  *
  * <li><b><tt>lhs \\/ rhs;</tt></b>
  *
  * <p>where <tt>lhs</tt> and <tt>rhs</tt> are first-order terms
  * possibly sharing variables, and <b><tt>FFF</tt></b> will
  * fuzzy-generalize them and print their fuzzy-least upper bound term
  * <tt>lub</tt>, along with the two most fuzzy general generalizing
  * substitutions <tt>&sigma;</tt><sub><i>l</i></sub> and
  * <tt>&sigma;</tt><sub><i>r</i></sub> and the greatest fuzzy degree
  * <tt>&alpha;</tt> such that <tt>lhs</tt>
  * &asymp;<sub><tt>&alpha;</tt></sub>
  * <tt>&sigma;</tt><sub><i>l</i></sub><tt>(lub)</tt> and <tt>rhs</tt>
  * &asymp;<sub><tt>&alpha;</tt></sub>
  * <tt>&sigma;</tt><sub><i>r</i></sub><tt>(lub)</tt>. Note that there
  * cannot be any failure in generalizing because it is always possible
  * to generalize dissimilar terms with a new variable at any fuzzy
  * degree <tt>&alpha;</tt> &\isin; <tt>(0.0,1.0]</tt>.
  *
  * </ul>
  *
  * <p>Again, here are <a href="../../examples.html">a few examples</a>.</b>
  * </li>
  *
  * <p><li><b><i>Technical Background</i>:</b>
  *
  * For more formal details on, and justifications of,
  * <b><tt>FFF</tt></b>'s constructs and computations, please refer to
  * <a
  * href="http://hassan-ait-kaci.net/pdf/partial-non-aligned-maps-prelim-june-2018.pdf">this
  * preliminary abstract spec</a> until further evolution of either this
  * software, or more details on the specs side.</li>
  *
  * </ul>
  */

 /* ************************************************************************ */
