Chapter 11

Running MrEd

MrEd accepts a number of command-line flags.

Under Mac OS X, a leading flag of the form -psn_ is treated specially. It indicates that Finder started the application, so the current input, output, and error output are redirected to a GUI window.

MrEd accepts the following flags (in addition to the X-specific flags described in X Window System Flags):

• Startup file and expression flags:

  •    -e expr or --eval expr : Evaluates expr after MrEd starts.

  •    -f file or --load file : Loads file after MrEd starts.

  •    -d file or --load-cd file : Uses load/cd to load file after MrEd starts.

  •    -t file or --require file : Requires file after MrEd starts.

  •    -F or --Load : Loads each remaining argument as a file after MrEd starts.

  •    -D or --Load-cd : Loads each remaining argument as a file using load/cd after MrEd starts.

  •    -T or --Require : Requires each remaining argument as a file after MrEd starts.

  •    -l file or --mzlib file: Requires the MzLib library file after MrEd starts.

  •    -L file collect : Requires the library file in the collection collect after MrEd starts.

  •    -M collect : Requires the library collect.ss in the collection collect after MrEd starts.

  •    -r file or --script file : Use this flag for MrEd-based scripts. It mutes the startup banner printout, suppresses the graphical read-eval-print loop, and loads file after MrEd starts. No argument after file is treated as a flag. The -r or --script flag is a shorthand for -fmv-.

  •    -i file or --script-cd file : Same as -r file or --script file, except that the current directory is changed to file's directory before it is loaded. The -i or --script-cd flag is a shorthand for -dmv-.

  •    -u file or --require-script file : Same as -r file or --script file, except that file is required instead of loaded. The -u or --require-script flag is a shorthand for -tmv-.

  •    -z or --stdio : Calls read-eval-print loop (using the current input and output) instead of graphical-read-eval-print-loop, and also prints version information to stdout.

  •    -Z or --nogui : Skips the built-in require of (lib "class.ss") and (lib "mred.ss" "mred") on startup. Also skips setting current-load to text-editor-load-handler.

  •    -K or --back : Under Mac OS X, skips bringing the application into the foreground on startup (in case it was started through a command line).

  •    -w or --awk : Loads the awk.ss library after MrEd starts.

  •    -k n m : Loads code embedded in the executable from file position n to m after MrEd starts. This flag is useful for creating a stand-alone binary by appending code to the normal MrEd executable. See PLT mzc: MzScheme Compiler Manual for more details.

  •    -C or --main : Like -r, then calls the function bound to main in the top-level environment. The argument to main is a list of immutable strings; the first string is the path of the file that was loaded, and the rest of the list contains leftover command-line arguments (the ones installed in current-command-line-arguments). The main function is called only if no previous evaluations or loads resulted in an uncaught exception.

• Initialization flags:

  •    -X dir or --collects dir : Sets dir as the path to the main collection of libraries (and makes (find-system-path 'collects-dir) produce dir).

  •    -S dir or --search dir : Adds dir to the library collection search path (after a user-specific directory, if any, and before the main collection directory).

  •    -U or --no-user-path : Omits paths in the search for collections, C libraries, etc. More specifically, this flag initializes the use-user-specific-search-paths parameter to #f.

  •    -x or --no-lib-path : Suppresses the initialization of current-library-collection-paths (as described in Library Collections and MzLib, section 16 in PLT MzScheme: Language Manual).

  •    -N file or --name file : sets the name of the executable as reported by (find-system-path 'run-file) to file. Also, program is initially defined as file.

  •    -q or --no-init-file : Suppresses loading the user's initialization file, as described below.

  •    -A or --no-argv : Suppresses the definition of argv and program, as described below.

  •    -j or --no-jit : Disables the native-code just-in-time compiler, setting the eval-jit-enabled parameter to #f.

• Language setting flags:

  •    -g or --case-sens : Makes the reader initially case-sensitive (the default).

  •    -G or --case-insens : Makes the reader initially case-insensitive.

  •    -s or --set-undef : Creates an initial namespace where set! will successfully mutate an undefined global variable (implicitly defining it).

• Miscellaneous flags:

  •    -- : No argument following this flag is used as a flag.

  •    -m or --mute-banner : Suppresses the startup banner text produced by -v.

  •    -v or --version : Suppresses the graphical read-eval-print loop and prints version information to stdout.

  •    -V or --no-yield : Suppresses the graphical read-eval-print loop, prints version information to stdout, and suppresses the normal yield that follows command-line expression evaluation and file loading.

  •    -h or --help : Shows information about MrEd's command-line flags and then exits, ignoring other flags.

  •    -p or --persistent : Catches the SIGDANGER (low page space) signal and ignores it (AIX only).

11.1  Flag Conventions

Extra arguments following the last flag are available from the current-command-line-arguments parameter (see Loading, section 7.9.1.6 in PLT MzScheme: Language Manual) as an immutable vector of immutable strings. The name used to start MrEd is available from the find-system-path procedure (see Locating Paths, section 11.3.2 in PLT MzScheme: Language Manual) using 'exec-file. In addition, unless -A is specified, the argument vector is put into the global variable argv, and the name used to start MrEd is put into the global variable program as a path.

Multiple single-letter flags (the ones preceded by a single dash) can be collapsed into a single flag by concatenating the letters, as long as the first flag is not --. The arguments for each flag are placed after the collapsed flags (in the order of the flags). For example,

   -vfme file expr

and

   -v -f file -m -e expr

are equivalent. If a collapsed -- appears before other collapsed flags, it is implicitly moved to the end of the collapsed set.

11.2  Executable Name

If the MrEd executable is given a name of the form scheme-dialect, then the command line is effectively prefixed with

   -qAeC '(require (lib "init.ss" "script-lang" "dialect"))'

The first actual command-line argument thus serves as a file to load. The file is loaded into a namespace that is initialized by the dialect-specific init.ss library. The loaded file should define main, which is called with command-line arguments -- starting with the loaded file name -- as a list of immutable strings.

11.3  Initialization

The current-library-collection-paths parameter is initialized (as described in Library Collections and MzLib, section 16 in PLT MzScheme: Language Manual) before any expression or file is evaluated or loaded, unless the -x or --no-lib-path flag is specified.

Unless the -q or --no-init-file flag is specified, a user initialization file is loaded after current-library-collection-paths parameter is initialized and before any other expression or file is evaluated or loaded. The path to the user initialization file is obtained from MzScheme's find-system-path procedure using 'init-file.

Expressions and files are evaluated and loaded in order that they are provided on the command line, including calls to main implied by --main, embeddings loaded by -k, and so on. If an uncaught exception occurs, the remaining expressions and files are skipped. The thread that loads the files and evaluates the expressions is the main thread. When the main thread terminates (or is killed), the MrEd process exits. The main thread is also the handler thread of the initial eventspace.

After the command-line files and expressions are loaded and evaluated, the main thread calls graphical-read-eval-print-loop, unless the -v, --version, -r, --script, -i, or --script-cd flag is specified. The -z or --stdio flag also suppresses the call to graphical-read-eval-print-loop, but it calls read-eval-print-loop, instead. (The other flags, such as -v, have no effect on this call to read-eval-print-loop.)

Finally, after the command-line files and expressions are loaded and evaluated, and after graphical-read-eval-print-loop or read-eval-print-loop is called, the main thread evaluates (yield 'wait). The -V or --no-yield flag suppresses this call to yield.

The exit status for the MrEd process indicates an error if an error occurs evaluating or loading a command-line expression or file and graphical-read-eval-print-loop is not called afterwards, or if the default exit handler is called with an exact integer between 1 and 255.

Evaluating command-line expressions with -f or -v is different from evaluating the same expressions within the window provided by graphical-read-eval-print-loop. The graphical-read-eval-print-loop window creates a new eventspace (and thus a new thread) for evaluating expressions entered into the window. One consequence of this convention is that terminating the evaluation thread (e.g., with (kill-thread (current-thread))) does not cause MrEd to exit, because the evaluation thread is not MrEd's main thread.¹⁹

In contrast, MzScheme's read-eval-print-loop always evaluates expressions within the thread that calls read-eval-print-loop. Using the -z or --stdio flag calls read-eval-print-loop in the main thread, so (kill-thread (current-thread)) in that case does exit MrEd. Furthermore, the main thread is the handler thread for the initial eventspace; thus, windows created in read-eval-print-loop without changing the eventspace never receive events unless (yield) is called explicitly.

11.4  Initial Eventspace

MrEd creates an initial eventspace, and the handler thread for the eventspace is MrEd's main thread; if the thread is killed, then the MrEd process exits.

11.5  X Window System Flags

Under Unix/X, the following standard X Window System flags are recognized (but not necessarily implemented): -display (1 argument), -geometry (1 argument), -bg (1 argument), -background (1 argument), -fg (1 argument), -foreground (1 argument), -fn (1 argument), -font (1 argument), -iconic (0 arguments), -name (1 argument), -rv (0 argument), -reverse (0 arguments), +rv (0 arguments), -selectionTimeout (1 argument), -synchronous (0 arguments), -title (1 argument), -xnllanguage (1 argument), and -xrm (1 argument).

All X flags must precede all other flags and arguments.