Context:

Epsilon User's Manual and Reference

Commands by Topic

Simple Customizing

. . .

Saving Customizations

Command Files

Command File Syntax

Command File Examples

Building Command Files

Epsilon User's Manual and Reference > Commands by Topic > Simple Customizing > Command Files >

Command File Examples

;  This example binds show-matching-delimiter to the
;  } character so that typing a } shows the matching
;  { character.
(bind-to-key "show-matching-delimiter" "}")

Unlike the regular command version, bind-to-key in a command file can unbind a prefix key. Say you want to make Ctrl-x no longer function as a prefix key, but instead have it invoke down-line. If, from the keyboard, you typed F4 to invoke bind-to-key, supplied the command name down-line, and then typed Ctrl-x as the key to rebind, Epsilon would assume you meant to rebind some subcommand of Ctrl-x, and wait for you to type a Ctrl-k, for instance, to bind down-line to Ctrl-x Ctrl-k. Epsilon doesn't know you have finished typing the key sequence. But in a command file, quotes surround each of the arguments to bind-to-key. Because of this, Epsilon can tell exactly where a key sequence ends, and you could rebind Ctrl-x as above (discarding the bindings available through Ctrl-x in the process) by saying:

(bind-to-key "down-line" "C-X") 

In a command file, define-macro allows you to define a keyboard macro. Its first string specifies the name of the new Epsilon command to define, and its second string specifies the sequence of keys you want the command to type. The define-macro command does not correspond to any single regular Epsilon command, but functions like a combination of start-kbd-macro, end-kbd-macro, and name-kbd-macro.

In a command file, set-variable lets you set a variable with any simple type (numeric or string), just like the usual set-variable command. It takes a string with the variable name, a value (either a number or a quoted string), and optionally a numeric code that says how to treat buffer-specific or window-specific variables.

With no numeric code, set-variable sets the default value of the variable and its value in all non-system buffers (or windows). A numeric code of 0 sets the value only in the current buffer (or window). The value 1 sets only the default, and 2 sets both. The value 3 sets its value in all non-system buffers or windows, as well as the default value (like omitting the code), while 4 includes system ones too. For example:

(set-variable "compile-java-cmd" "oldjavac \"%r\"")
(set-variable "delete-hacking-tabs" 2 1)

The set-variable command can't enlarge character array variables to accommodate a very long definition. Use the variable-setting syntax produced by commands like list-all or list-customizations for that; it includes a variable length to set a larger size.

The command file command create-prefix-command takes a single string, which specifies a key, and makes that key a prefix character. It works just as the regular command of the same name does.

Using the same syntax, you can also call EEL commands and subroutines. For subroutines, any that take only numeric and string arguments should work. Here are some useful ones:

(load-eel-from-path "file.e" 2)
(load-from-path "file.b")

The first line makes Epsilon search the EPSPATH for an EEL extension language source file named file.e, then compile and load it. (You can use an absolute path instead, remembering to double any backslashes.) Its second argument 2 makes the load_eel_from_path( ) subroutine stop if there's an error; the value 1 won't complain if the file wasn't found but complains on other errors, and the value 0 suppresses all errors. (Add the value 4 to make load-eel-from-path look for the file in the current directory before checking the EPSPATH.) Put the EEL file in the same directory as einit.ecm (your customization directory) and you can use a relative pathname. (In command names in command files, - and _ are the same.)

The second line makes Epsilon search the EPSPATH for the compiled version of that same file and load it; this is faster, but it requires you to manually recompile that file when updating.

You can even run EEL code directly from a command file, using the do_execute_eel( ) subroutine:

(do-execute-eel "
    int i=0;
    while (i++ < 10) {
       has_arg = 1;
       start_process();
    }")

Epsilon will compile the code and then execute it. This example starts ten concurrent process buffers.

(inline-eel "
command show_color()
{
 char *col = name_color_class(get_character_color(point));
 if (col) 
  say(\"Color class at point is %s.\", col);
 else
  say(\"No color class at point.\");
}
")

To define commands or variables using EEL code from a command file, you can use the inline_eel( ) subroutine. But it's easier and faster to put longer definitions into a separate .e file and load it from the command file with load-eel-from-path.

Many commands that prompt for some information like a file name aren't directly suitable for including in a command file; they don't know how to accept an argument supplied by a command file and will always prompt. In many cases an EEL subroutine is available that performs a similar task but is suitable for use in a command file. But a command that takes a numeric prefix argument may be used in a command file: put the prefix argument just before the command name, as in (100 goto-line), which goes to line 100.

Use the change-name command to rename an existing command, EEL subroutine, variable, keyboard macro, or color scheme. It takes the old name, then the new one.

Here's an example command file:

; This macro makes the window below the
; current one advance to the next page.
(define-macro "scroll-next-window" "C-XnC-VC-Xp")
(bind-to-key "scroll-next-window" "C-A-v")

;This macro asks for a file and puts
;it in another window.
(define-macro "split-and-find" "A-Xsplit-window
A-Xredisplay
A-Xfind-file
")

The first two lines contain comments. The third line begins the definition of a macro called scroll-next-window. It contains three commands. First Ctrl-x n invokes next-window, to move to the next window on the screen. The Ctrl-v key runs next-page, scrolling that window forward, and Ctrl-x p then invokes previous-window, to return to the original window. The fourth line of this example binds this new macro to the Ctrl-Alt-v key, so that from then on, typing a "v" with Control and Alt depressed will scroll the next window forward.

The file defines a second macro named split-and-find. It invokes three commands by name. Notice that the macro could have invoked two of the commands by key. Invoking by name makes the macro easier to read and modify later. The redisplay command shows the action of split-window before the find-file command prompts the user for a file name.

Previous	Up	Next
Command File Syntax	Commands by Topic	Building Command Files

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