<\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 most important option for contextual overloading, which was already discussed . <\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. As an example, let us consider the following definitions: <\scm-code> (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. When the conditions of several (re)declarations are met, then the last redeclaration will be used. Inside a redeclaration, one may also use the keyword in order to explicitly access the former value of the redefined symbol. <\explain> )> <|explain> This option is equivalent to ))> and 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. <\explain> )> <|explain> Use this macro to define new modes that you can use for contextual overloading, for instance in . Modes may be made dependent on other modes. This macro takes a variable number of definitions as arguments, each of the form . End your and any dependencies with one , like this: <\scm-code> (texmacs-modes \ \ (in-verbatim% (inside? 'verbatim) in-text%) \ \ (in-tt% (inside? 'tt))) When creating new modes remember to place first the faster checks (against booleans, etc.) for speed. 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. <\warning> A current limitation of the implementation is that functions overloaded using and cannot have different options. This means in particular that you cannot specify different values for depending on the context. <\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-code> (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>