<\body> Conventional programming languages often provide mechanism to overload certain functions depending on the types of the arguments. provides additional context-based overloading mechanisms, which require the use of the construct for function declarations (and for macro declarations). Furthermore, one may use for associating additional properties to a function, such as documentation or default values for the arguments. <\explain> )> function definition> )> macro definition> <|explain> function and macro declarations are similar to usual declarations based on and , except for the additional list of and the fact that all functions and macros defined using and are public. Each option is of the form )> and the starts at the first element of the list following which is not of this form. We will first describe the various options for overloading. If several definitions are given for the same function (or macro) and several definitions satisfy the corresponding overloading conditions, when applying to some arguments, then the 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. <\explain> )> <|explain> This option specifies that the definition is only valid when we are in a given . New modes are defined using and modes can inherit from other modes. A mode > is understood to be more particular than another mode > if > inherits from >. <\explain> )> <|explain> 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 . We have not yet implemented a function to test whether a pattern is a restriction of another pattern, so ambiguous overloads cannot be resolved. <\explain> )> <|explain> This option specifies that one necessary condition for the declaration to be valid is that the condition is met. This condition may involve the arguments of the function. Again, ambiguous overloads cannot be resolved. As an example, let us consider the following definitions: <\scm-fragment> (tm-define (special t) \ \ (and-with p (tree-outer t) \ \ \ \ (special p))) \; (tm-define (special) \ \ (:require (tree-is? t 'frac)) \ \ (tree-set! t `(frac ,(tree-ref t 1) ,(tree-ref t 0)))) \; (tm-define (special) \ \ (:require (tree-is? t 'rsub)) \ \ (tree-set! t `(rsup ,(tree-ref t 0)))) The default implementation of is to apply to the parent of as long as is not the entire document itself. The two overloaded cases apply when is either a fraction or a right subscript. Assuming that your cursor is inside a fraction inside a subscript, calling will swap the numerator and the denominator. On the other hand, if your cursor is inside a subscript inside a fraction, then calling will change the subscript into a superscript. <\explain> ... )> <|explain> This is a very special case of the option, where we require the first argument to be a compound hybrid tree whose root label is amongst until . Besides a simplified syntax, the implementation of is done using a dispatch via a hash table. When appropriate, you should therefore priviledge over the general form of . A typical situation when is useful is when writing a converter foo> of trees into your own foormat: specific converters for given tags can be added using <\scm-fragment> (tm-define (tm-\foo t) \ \ (:case frac) \ \ ) Besides the contextual overloading options, the and 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. <\explain> )> <|explain> This option gives a short discription of the function or macro, in the form of a string . As a convention, expressions may be encoded inside this string by using the -prefix. For instance: <\scm-fragment> (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. <\explain> )> <|explain> This option gives a short of one of the arguments to the function or macro. Such a description is used for instance for the prompts, when calling the function interactively. <\explain> )> <|explain> This option gives a short of the return value of the function or macro. <\initial> <\collection>