 |
Function definition and contextual overloading |  |
Conventional programming languages often provide mechanism to overload certain functions depending on the types of the arguments. TeXmacs provides additional context-based overloading mechanisms, which require the use of the tm-define construct for function declarations (and tm-define-macro for macro declarations). Furthermore, one may use tm-define for associating additional properties to a function, such as documentation or default values for the arguments.
TeXmacs function and macro declarations are similar to usual declarations based on define and define-macro, except for the additional list of options and the fact that all functions and macros defined using tm-define and tm-define-macro are public. Each option is of the form (:kind arguments*) and the body starts at the first element of the list following head which is not of this form.
Contextual overloading
We will first describe the various options for overloading. If several definitions are given for the same function (or macro) foo and several definitions satisfy the corresponding overloading conditions, when applying foo to some arguments, then the most particular definition will prevail. For any of the overloading options, we will therefore have to specify what we mean my “most particular”. When trying to find out the most particular set of options, we first sort on mode, next on context and finally on function arguments. Notice that sorting on function arguments is not yet fully implemented, so we will not discuss this yet.
This option specifies that the definition is only valid when we are in a given mode. New modes are defined using texmacs-modes and modes can inherit from other modes. A mode m1 is understood to be more particular than another mode m2 if m1 inherits from m2.
Let t1 be the innermost tree to which the cursor is attached and let t2,…,tn denote the successive parents of t1, ending with the document tn itself. The context option is satisfied if and only if one of the trees t1,…,tn satisfies the preducate pred?. In the case when two predicates P1 and P2 compete, then the most particular one is the one which is satisfied by a ti with the lowest value of i. An example will be given below for the option :inside, which is a special case of :context.
This option is a special case of the :context option, for the predicate (lambda (t) (tree-in? 'label)). As an example, let us consider the following definitions:
(tm-define (special)
(:inside 'frac)
(with-innermost t 'frac
(tree-set! t ‘(frac ,(tree-ref t 1)
,(tree-ref t 0)))))
(tm-define (special)
(:inside 'rsub)
(with-innermost t 'rsub
(tree-set! t ‘(rsup ,(tree-ref t
0)))))
Assuming that your cursor is inside a fraction inside a subscript, calling special will swap the numerator and the denominator. On the other hand, if your cursor is inside a subscript inside a fraction, then calling special will change the subscript into a superscript.
This option specifies that one necessary condition for the declaration to be valid valid is that the arguments match the specified pattern according to the primitive match?. We have not yet implemented a function to test whether a pattern is a restriction of another pattern, so ambiguous overloads cannot be resolved.
This option specifies that one necessary condition for the declaration to be valid is that the condition cond is met. This condition may involve the arguments of the function. Again, ambiguous overloads cannot be resolved.
This is a very special case of the :match option, where we require the first argument to be a compound hybrid tree whose root label is amongst label-1 until label-n. Besides a simplified syntax, the implementation of :case is done using a dispatch via a hash table. When appropriate, you should therefore priviledge :case over the general form of :match. A typical situation when :case is useful is when writing a converter tm->foo of TeXmacs trees into your own foormat: specific converters for given tags can be added using
(tm-define (tm->foo t)
(:case frac)
tm-to-foo-converter-for-frac)
Other options for function and macro declarations
Besides the contextual overloading options, the tm-define and tm-define-macro primitives admit several other options for attaching additional information to the function or macro. We will now describe these options and explain how the additional information attached to functions can be exploited.
This option gives a short discription of the function or macro,
in the form of a string short-help. As a convention,
(tm-define (list-square l)
(:synopsis "Appends the list @l to
itself")
(append l l))
The synopsis of a function is used for instance in order to provide a short help string for the function. In the future, we might also use it for help balloons describing menu items.
This option gives a short description of one of the arguments var to the function or macro. Such a description is used for instance for the prompts, when calling the function interactively.
This option gives a short description of the return value of the function or macro.