Lugaru's Epsilon
Programmer's
Editor 14.04

Context:
Epsilon User's Manual and Reference
   . . .
   Command Reference
   Variable Reference
   Changing Epsilon
   Introduction to EEL
   Epsilon Extension Language
   . . .

Previous   Up    Next
yank-rectangle-to-corner  Epsilon User's Manual and Reference   Introduction to EEL


Epsilon User's Manual and Reference >

Changing Epsilon

Epsilon provides several ways for you to change its behavior. Some commands enable you to make simple changes. For example, set-fill-column can change the width of filled lines of text. Commands like bind-to-key and create-prefix-command can move commands around on the keyboard, and using keyboard macros, you can build simple new commands. The remaining chapters of the manual describe how to use the Epsilon Extension Language, EEL, to make more sophisticated commands and to modify existing commands.

Unless you save them, all these types of changes go away when you exit, and you must reload them the next time you run Epsilon. (But see the record-customizations variable.)

There are many ways to save such changes. The easiest way to save them is with the list-customizations command. That's the best method, unless you have a very large number of customizations. It works by adding lines to your einit.ecm customization file, which Epsilon reads every time it starts. Or you can customize Epsilon by manually editing that file. See Command Files for details on both techniques.

But you can also save changes by storing them in a state file. This method lets Epsilon start up faster when you have hundreds of customizations, or have made many customizations using the EEL extension language. This chapter describes various ways to customize Epsilon using a modified state file.

When it starts, Epsilon reads a state file named epsilon-v14.sta containing all of Epsilon's initial commands, variables, and bindings. (You can use Epsilon's -s flag to make Epsilon load its state from some other file. For example, "epsilon -sfilename" loads its commands from the file filename.sta. The default name includes Epsilon's major version number.)

You can change Epsilon's set of commands and settings by generating a new state file with the Epsilon command write-state on Ctrl-F3. So one way to customize Epsilon is to make your changes (bind some keys, set a variable, define some macros) and use the write-state command to put the changes in epsilon-v14.sta. Your customizations will take effect each time you run Epsilon. See Saving Customizations for more on write-state.

Instead of manually setting variables, then saving them in a (binary) state file, you may want to preserve your changes in a human-readable format. Commands like list-customizations provide one way to do that, preserving variable settings and the like in Epsilon's command file format. You can also do this using EEL.

In that case, you may find it handy to have a file that loads your changes into a fresh Epsilon, then writes the new state file automatically. The following simple EEL file, which we'll call changes.e, uses features described in later chapters to do just that:

#include "eel.h"  /* Load standard definitions. */

when_loading()    /* Execute this file when loaded. */
{
    want_bell = 0;            /* Turn off the bell. */
    kill_buffers = 6;         /* Use only 6 kill buffers. */
    load_commands("mycmds");  /* Load my new commands. */
    do_save_state("epsilon"); /* Save these changes. */
}

Each time you get an update of Epsilon, you can compile this program (type eel changes outside of Epsilon) and start Epsilon with its new state file (type epsilon). Then when you load this file (type F3 changes <Enter> to Epsilon), Epsilon will make all your changes in the updated version and automatically save them for next time.

You can change most variables as in the example above. Some variables, however, have a separate value for each buffer. Consider, for example, the tab size (which corresponds to the value of the tab-size variable). This variable's value can potentially change from buffer to buffer. We call this a buffer-specific variable. Buffer-specific variables have one value for each buffer plus a special value called the default value. The default value specifies the value for the variable in a newly created buffer. A state file stores only the default value of a buffer-specific variable.

Thus, to change the tab size permanently, you must change tab_size's default value. You can use the set-variable command to make the change, or an EEL program. The following version of changes.e sets the default tab size to 5.

#include "eel.h"  /* load standard definitions */

when_loading()    /* execute this file when loaded */
{
    tab_size.default = 5;     /* set default value  */
    load_commands("mycmds");  /* load my new cmnds */
    do_save_state("epsilon"); /* save these changes */
}

For comparison, here are the lines you could add to your einit.ecm file instead, to make similar customizations without using EEL:

(set-variable tab-size 5)
(load-eel-from-path "mycmds.e" 2)

This technique, using an einit.ecm file as shown in Command Files, is simpler than using a changes.e file, and doesn't require running the EEL compiler explicitly, so it's better for all but the most complex customizations.

Once you've learned a little EEL, you may want to modify some of Epsilon's built-in commands. We recommend that you keep your modifications to Epsilon in files other than the standard distributed source files. That way, when you get an update of Epsilon, you will find it easy to recompile your changes without accidentally loading in old versions of some of the standard functions.

You cannot redefine a function during that function's execution. Thus, changing the load-bytes command, for example, would seem to require writing a different command with the same functionality, and using each to load a new version of the other. You don't have to do this, however. Using the -b flag, you can load an entire system into Epsilon from bytecode files, not reading a state file at all. Epsilon does not execute any EEL functions while loading commands with the -b flag, so you can redefine any function using this technique.

To use this technique, first compile all the files that make up Epsilon. If you have a "make" utility program, you can use the makefile included with Epsilon to do this. Then start Epsilon with the -b flag. This loads the single bytecode file epsilon.b, which automatically loads all the others. The makefile then has Epsilon write a new state file using these definitions. If you have made extensive changes to Epsilon's commands, this method may be most convenient.



Previous   Up    Next
yank-rectangle-to-corner  Epsilon User's Manual and Reference   Introduction to EEL


Lugaru Epsilon Programmer's Editor 14.04 manual. Copyright (C) 1984, 2021 by Lugaru Software Ltd. All rights reserved.