Background evaluations

Until now, we have always considered interfaces between TeXmacs and applications which are intended to be used interactively in shell sessions. But there also exists a Scheme command

(plugin-eval plugin session expression)

for evaluating an expression using the application. Here plugin is the name of the plug-in, session the name of the session and expression a Scheme expression which represents a TeXmacs tree.

The substitute plug-in

Background evaluations may for instance be used in order to provide a feature which allows the user to select an expression and replace it by its evaluation. For instance, the substitute plug-in converts mathematical LaTeX expressions into TeXmacs, and it provides the C-F12 keyboard shortcut for replacing a selected text by its conversion. The plug-in consists of the following files 

    substitute/Makefile
    substitute/progs/init-substitute.scm
    substitute/src/substitute.cpp

The main evaluation loop of substitute.cpp simply consists of 

char buffer[100];
cin.getline (buffer, 100, '\n');
cout << DATA_BEGIN;
cout << "latex:$" << buffer << "$";
cout << DATA_END;
fflush (stdout);

Moreover, the configuration file init-substitute.scm contains the following code for replacing a selected region by its evaluation

(define (substitute-substitute)

(import-from (texmacs plugin plugin-cmd))

(if (selection-active-any?)

(let* ((t (tree->stree (the-selection)))

(u (plugin-eval "substitute" "default" t)))

(clipboard-cut "primary")

(insert (stree->tree u)))))

as well as the keyboard shortcut for C-F12:

(kbd-map

("C-F12" (substitute-substitute)))

Notice that these routines should really be defined in a separate module for larger plug-ins.

The secure plug-in

Another example of using an interface in the background is the secure plug-in which consists of the files 

    secure/Makefile
    secure/packages/secure.ts
    secure/progs/init-secure.scm
    secure/progs/secure-secure.scm
    secure/src/secure.cpp

Just as substitute.cpp above, the main program secure.cpp just converts mathematical LaTeX expressions to TeXmacs. The secure-secure.scm module contains the secure Scheme routine latexer:

(tm-define (latexer s)

(:type (tree -> object))

(:synopsis "convert LaTeX string to TeXmacs tree using plugin")

(:secure #t)

(plugin-eval "secure" "default" (tree->string s)))

It is important to define latexer as being secure, so that it can be used in order to define additional markup using the extern primitive. This is done in the style file secure.ts:

<document|See a LaTeX math command as a TeXmacs expression via plug-in|<assign|latexer|<macro|x|<extern|latexer|x>>>>

After compilation, installation, relaunching TeXmacs and selecting Document→Use package→secure, you will now be able to use latexer as a new primitive. The primitive takes a mathematical LaTeX expression as its argument and displays its TeXmacs conversion.

© 1998–2002 Joris van der Hoeven
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".