Lugaru's Epsilon
Programmer's
Editor

Context:
Epsilon User's Manual and Reference
   Welcome
      Introduction
      Features
   Getting Started
      . . .
      Invoking Epsilon
      Configuration Variables
      Epsilon Command Line
      File Inventory
   General Concepts
      Buffer Concepts
      Window Concepts
      Epsilon's Screen Layout
      . . .
      The Menu Bar
   . . .

Previous   Up    Next
The Customization Directory  Getting Started   File Inventory


Epsilon User's Manual and Reference > Getting Started >

Epsilon Command Line

When you start Epsilon, you may specify a sequence of command line flags (also known as command-line options, or switches) to alter Epsilon's behavior. Flags must go before any file name.

Each flag consists of a minus sign ("-"), a letter, and sometimes a parameter. You can use the special flag -- to mark the end of the flags; anything that follows will be interpreted as a file name even if it starts with a - like a flag.

If a parameter is required, you can include a space before it or not. If a parameter is optional (-b, -m, -p) it must immediately follow the flag, with no space.

Before examining the command line, Epsilon looks for a configuration variable (see Configuration Variables) named EPSILON and "types in" the value of that variable to the command line before the real command line. Thus, if you define a Unix environment variable:

export EPSILON=-m250000 -smine

then Epsilon would behave as if you had typed

epsilon -m250000 -smine myfile

when you actually type

epsilon myfile

Here we list all of the flags, and what they do:

+number
Epsilon normally shows you the beginning of each file you name on the command line. If you want to start at a different line, put "+number" before the file's name, where number indicates the line number to go to. You can follow the line number with a colon and a column number if you wish.

-add
This flag tells Epsilon to locate an existing instance of Epsilon, pass it the rest of the command line, and exit. Epsilon ignores the flag if there's no prior instance. If you want to configure another program to run Epsilon to edit a file, but use an existing instance of Epsilon if there is one, just include this flag in the Epsilon command line. See Sending Files to a Prior Instance for details on Epsilon's server support.

-bfilename
Epsilon normally reads all its commands from a state file at startup. (See the -s flag below.) Alternately, you can have Epsilon start up from a file generated directly by the EEL compiler. These bytecode files end with a ".b" extension. This flag says to use the bytecode file with name filename, or "epsilon" if you leave out the filename. You may omit the extension in filename. You would rarely use this flag, except when building a new version of Epsilon from scratch. Compare the -l flag.

-dvariable!value
You can use this flag to set the values of string and integer variables from the command line. The indicated variable must already exist at startup. You can also use the syntax -dvariable=value, but beware: if you run Epsilon for Windows via a .BAT or .CMD file, the system will replace any ='s with spaces, and Epsilon will not correctly interpret the flag.

-dir dirname
Epsilon interprets any file names that follow on the command line relative to this directory.

-fdfilename
This flag tells Epsilon where to look for the on-line documentation file. Normally, Epsilon looks for a file named edoc. This flag tells Epsilon to use filename for the documentation file. If you provide a relative name for filename, then Epsilon will search for it; see How Epsilon Finds its Files. Use a file name, not a directory name, for filename.

-fsdirnames
This switch tells Epsilon what directories to use for temporary files, such as Epsilon's swap file, which it uses when you edit files too big for available memory, or the eshell file it creates in some environments to help capture the output of a process. Dirnames should indicate a list of one or more directories, separated by semicolons (colons under Unix). Epsilon will use the first directory named as long as there is space on its device; then it will switch to the second directory, and so forth. If it cannot find any available space, it will ask you for another directory name.

If you don't use this switch, Epsilon will create any temporary files it needs in the directory named by the TMP environment variable. If TMP doesn't exist, Epsilon tries TEMP, then picks a fallback location. Epsilon calls its swap file eswap, but it will use another name (like eswap0, eswap1, etc.) to avoid a conflict with another Epsilon using this file.

-geometry
When Epsilon for Unix runs as an X program, it recognizes this standard X11 flag. It specifies the size and position of Epsilon's window, using the format WIDTHxHEIGHT+XOFF+YOFF. The WIDTH and HEIGHT values are in characters. The XOFF and YOFF values are in pixels, measured from the top left corner of the screen. You can use - instead of + as the offset separator to positon relative to the right or bottom edge of the screen instead. You may omit trailing values (for instance, just specify width and height).

-kanumber
This switch turns off certain keyboard functions to help diagnose problems. It's followed by a number, a bit pattern made by summing the bit values that follow.

For Windows, the value 1 tells Epsilon not to translate the Ctrl-2 key combination to Ctrl-@. (Ctrl-Shift-2 always produces Ctrl-@.) The value 8 tells Epsilon to be more conservative when writing text on the screen, at the price of some performance; it may help with fonts that use inconsistent character sizes, or with display driver compatibility issues. The value 16 makes text a little darker, and sometimes helps with display driver compatibility too.

A value of 128 tells Epsilon for Windows not to apply the Ctrl key to those ASCII characters that have no Control version in ASCII. For instance, the ASCII code includes characters Ctrl-A and Ctrl-\, but not Ctrl-9 or Ctrl-(. Epsilon for Windows will construct a non-ASCII key code for the latter pair unless you use this bit. (Under X11, Epsilon always does this.)

For Unix, bits in this flag can set which X11 modifier keys indicate an Alt key. By default, Epsilon chooses an appropriate key, but you can use 1 or 2 to force modifier key 1 or 2, respectively. The number is a bit pattern specifying which of the five possible X11 modifier keys will be used as an Alt key, using the values 1, 2, 4, 8, and 16. The value 32 tells Epsilon under X11 not to translate the Ctrl-2 key combination to NUL (as 1 for Windows does).

Both Windows and X11 GUI versions recognize the 64 bit, which tells Epsilon not to translate the Ctrl-6 combination into Ctrl-^, or Ctrl-<Minus> on the main keyboard into Ctrl-_.

-ksnumber
This flag lets you adjust the emphasis Epsilon puts on speed during long operations versus responsiveness to the abort key. Higher numbers make Epsilon slightly faster overall, but when you press the abort key, Epsilon may not respond as quickly. Lower numbers make Epsilon respond more quickly to the abort key, but with a performance penalty. The default setting is -ks100.

-lbytecode
Giving this switch makes Epsilon load a bytecode file named bytecode.b after loading the state file. If you give more than one -l flag on the command line, the files load in the order they appear. Compare the -b flag.

-mbytes
This switch controls how much memory Epsilon uses for the text of buffers. Epsilon interprets a number less than 1000 as a number of kilobytes, otherwise, as bytes. You may explicitly specify kilobytes by ending bytes with "k", or megabytes by ending bytes with "m". Specify -m0 to use as little memory as possible, and -m to put no limit on memory use.

If you read in more files than will fit in the specified amount of memory, or if despite a high limit, the operating system refuses Epsilon's requests for more memory, Epsilon will swap portions of the files to disk. By default, Epsilon puts no limits on its own memory usage.

-noinit
This flag tells Epsilon not to read any einit.ecm customization file.

-nologo
In some environments Epsilon prints a short copyright message when it starts. This flag makes it skip displaying that message.

-noserver
This flag tells Epsilon for Windows or Unix that it should not register itself as a server so as to accept messages from other instances of Epsilon. By default, Epsilon will receive messages from future instances of Epsilon that are started with the -add flag, or (for Windows) sent via file associations or DDE. See Sending Files to a Prior Instance for details. The flag -nodde is a synonym.

-pfilename
This overrides the ESESSION configuration variable to control the name of the session file that Epsilon uses. When you specify a file name, Epsilon uses that for the session file, just as with ESESSION. Because the -p0 and -p1 flags enable and disable sessions (see the next item), the given filename must not begin with a digit.

-pnumber
This flag controls whether or not Epsilon restores your previous session when it starts up. By default, Epsilon will try to restore your previous window and buffer configuration. The -p flag with no number toggles whether Epsilon restores the session. Give the -p0 flag to disable session restoring and saving, and the -p1 flag to enable session restoring and saving. This flag understands the same values as the preserve-session variable; see its description for other options.

-quickup
Epsilon uses this flag to help perform certain updates. It searches for and loads a bytecode file named quickup.b. This flag is similar to the -l flag above, but the -quickup flag doesn't require any EEL functions to run. For that reason, it can replace and update any EEL function.

-rcommand
Giving this switch makes Epsilon try to run a command or keyboard macro named command at startup. If the command doesn't exist, nothing happens. If you specify more than one -r flag on the command line, they execute in the order they appear. Use the syntax -rcmdname=param or -rcmdname!param to run an EEL subroutine and pass it a value; the subroutine must be defined to accept a single parameter of char * type.

-sfilename
When Epsilon starts up, it looks for a state file named epsilon-v13.sta. The state file contains definitions for all of Epsilon's commands. You can create your own state file by using the write-state command. This switch says to use the state file with the name filename. Epsilon will add the appropriate extension if you omit it. Specify a file name for filename, not a directory name. Of course, the file name may include a directory or drive prefix. If you specify a relative file name, Epsilon will search for it. See How Epsilon Finds its Files. See also the -b flag, described above.

-sendonly
The startup script in Epsilon for Mac OS X uses this flag in combination with the -add flag. It makes Epsilon exit with an error code whenever no prior instance was found to receive the -add command line.

-server:servername
The command line flag -server may be used to alter the server name for an instance of Epsilon. An instance of Epsilon started with -server:somename -add will only pass its command line to a previous instance started with the same -server:somename flag. See Sending Files to a Prior Instance. The flag -dde is a synonym.

-teach
This flag tells Epsilon to load the on-line tutorial file at startup. See Epsilon Tutorial.

-vcx
x indicates the number of columns you want displayed while in Epsilon. For example, use "-vc132" for 132 columns. See the -vl flag, described below. See the -geometry flag for the equivalent in Epsilon for Unix.

-vcolor
Epsilon normally tries to determine whether to use a monochrome color scheme or a full-color one based on the type of display in use and its mode. This flag forces Epsilon to use a full-color color scheme, regardless of the type of the display.

-vlx
x indicates the number of screen lines you want to use while in Epsilon. Also See the -vc switch, described above. See -geometry for the equivalent in Epsilon for Unix.

-vmono
Epsilon normally tries to determine whether to use a monochrome color scheme or a full-color one based on the type of display in use and its mode. This flag forces Epsilon to use its monochrome color scheme, regardless of the type of the display.

-vt
(Unix only) This flag forces Epsilon to run as a curses-style terminal program, not an X11 program. By default Epsilon for Unix runs as an X program whenever an X display is specified (either through a DISPLAY environment variable or a -display flag), and a terminal program otherwise.

-vv
This flag instructs Epsilon to split the screen vertically, not horizontally, when more than one file is specified on the command line.

-vx and -vy
These flags let you specify the position of Epsilon's window in Epsilon for Windows. For example, -vx20 -vy30 positions the upper left corner of Epsilon's window at pixel coordinates 20x30. See -geometry for the equivalent in Epsilon for Unix.

-wnumber
This flag controls several directory-related settings. Follow it with a number.

The -w1 flag tells Epsilon to remember the current directory from session to session. Without this flag, Epsilon will remain in whatever current directory it was started from. Epsilon always records the current directory when it writes a session file; this flag only affects whether or not Epsilon uses this information when reading a session file.

The -w2 and -w4 flags have no effect in this version of Epsilon.

The -w8 flag tells Epsilon not to look for its own files in the parent of the directory containing the Epsilon executable. See How Epsilon Finds its Files.

The -w16 flag tells Epsilon to set its current directory to the directory containing the first file named on its command line. If you edit files by dragging and dropping them onto a shortcut to Epsilon, you may wish to use this flag in the shortcut.

The -w32 flag tells Epsilon to look for its own files in the directory containing the Epsilon executable before searching the EPSPATH. See How Epsilon Finds its Files.

You can combine -w flags by adding their values together. For example, -w9 makes Epsilon remember the current directory and exclude its executable's parent directory from the default EPSPATH. These -w flags are cumulative, so -w1 -w8 works the same as -w9. Omitting the number discards all prior -w flags on the command line, so -w9 -w -w32 acts like just -w32.

All Windows program icons for Epsilon invoke it with -w1 so that Epsilon remembers the current directory.

-wait
This flag tells Epsilon to locate an existing instance of Epsilon, pass it the rest of the command line, and wait for the user in that instance to invoke the resume-client command. (Epsilon ignores the flag if there's no prior instance.) If you want to configure another program to run Epsilon to edit a file, but use an existing instance of Epsilon, just include this flag in the Epsilon command line. See Sending Files to a Prior Instance for details on Epsilon's server support.



Previous   Up    Next
The Customization Directory  Getting Started   File Inventory


Lugaru Copyright (C) 1984, 2012 Lugaru Software Ltd. All Rights Reserved.