Purpose:

The primary purpose of this laboratory is to familiarize you with basic use of the text editor Emacs. You will also learn how to compile and run a java application.

Emacs:

A text editor is a program that allows you to create and modify files containing ordinary text. We use a text editor to create and modify programs and data. The text editor we will use in this course is a version of Emacs called XEmacs. Emacs is a powerful editor available on many systems. It was originally developed by Richard Stallman and the Free Software Foundation. It is infinitely tailorable: any key can be made to perform any function.

The version we will use is window-based. But editor functions can be performed with mouse and menus or with the keyboard. Thus you can use XEmacs from a terminal or telnet window. Some keyboard commands are given as an appendix to this handout.

Remember that there are in general many different ways to accomplish the same task. You should spend time experimenting to determine which methods you prefer, and to become proficient in the use of the editor.

You will perform the following tasks with XEmacs under the direction of the lab instructor:

• create a new file;
• open an existing file;
• save a file;
• add text to a file;
• delete text from a file;
• select text with the mouse;
• cut, copy, and paste text;
• undo changes;
• find a string of characters in a file (search);
• iteratively replace one string of characters with another;
• open a new "frame" containing a different file;
• copy and paste across frames.

Since Emacs is configurable, the version and configuration you use may not be exactly as described below.

Run XEmacs by clicking the appropriate front panel icon as directed by your instructor (Usually the one displaying a document with an "XE" over it.) The XEmacs window will look something like the one pictured below.

When you open XEmacs, you are in an area (buffer) named *scratch*. You can key text into this buffer, but you generally will not. Typically you first either open a file or create a new one.

Create a new file:

To create a new file, choose the Open option from the File menu, or press the Open tool button. Key the file name of the file to be created in the sub-window that appears, and press the Return key. If you see the message "[no completions; confirm]" or "[incomplete; confirm]" in the minibuffer, press the Return key again. You are confirming that you want to create a new file.

• Click the Open tool bar button.
• In the open file dialog box type Something.txt. (Make sure that the dialog box is active!)
• Press the Return key twice.

Add text to a file:

• Type something into the workspace.
• Click the mouse in the workspace over some of the text you have entered, and key additional text.

Save a file:

At this point, the text you have entered is stored only in a memory buffer. To write the buffer to a disk file, choose the Save or Save As... option from the File menu, or press the Save tool button.

• Click the Save button on the tool bar.

Choosing Save As... from the File menu brings up a dialog box allowing you to specify another file name.

Using buffers:

You can be editing several files at the same time in XEmacs. Each file you are editing has its own memory buffer. Selecting the Buffers menu will list all of the current buffers. You should see two open buffers now, *scratch* and Something.txt. When you select one of these buffers a sub menu appears. Among the choices are Switch to Buffer and Delete Buffer.

Remember, changes that you make in a buffer are not stored to the file until you save the buffer. If the buffer contains changes that have not been saved to the file, the third and fourth characters on the "mode line" will be asterisks ("*") rather than hyphens. When the buffer is consistent with the file, the mode line will start with five hyphens.

• Using the Buffers menu, switch to the *scratch* buffer and then back to the Something.txt buffer.
• Delete the Something.txt buffer.

Open an existing file:

You open an existing file in the same way that you created a new files: by choosing the Open option from the File menu, or pressing the Open tool button. You can then key the name of the file to be opened in the sub-window that appears and press the Return key, or click with the middle button in the sub-window on the name of the file to be opened. You can also key the first few characters of the file name and press the Tab key.

• Click the Open tool bar button.
• In the open file dialog box type Something.txt and press Return, or middle click Something.txt.

Open a new "frame" containing a different file:

What we generally refer to as a window is called a frame in XEmacs. There is rarely the need to run multiple instances of XEmacs. XEmacs is a complex and powerful application and requires a good deal of system resources. If you want to have more than one window open, you simply create a new frame. You can choose Open in New Frame from the File menu and open another file in the new frame, or choose New Frame from the File menu and open another frame displaying the same buffer. From the Buffers menu, you can independently display different buffers in each frame.

• From the File menu choose Open in New Frame....
• Open a file. (It can be the same one as the one that is already open.)
• Choose Something.txt from the Buffers menu and choose Switch to Buffer - Other Frame from the sub-menu. You should now have three frames open.

Close a frame as you would close any other window. For instance, you can double click the window menu button in the upper left hand corner of the window.

Delete text from a file:

Click the mouse after the text to be deleted and use the Delete or Backspace key to rub out text. Alternately, cut text as described below.

• Delete some text from your buffer.

Select text with the mouse:

Click at the beginning of the text region, and holding the left button down drag the mouse to the end of the region. Double click selects a word, triple click selects a line. The selected text is sometimes referred to a the "region."

• Experiment selecting text.

Cut, copy, and paste text:

To cut or copy, select text to be cut or copied with the mouse as described above. Then press the Cut or Copy tool button, choose the appropriate option from the Edit menu, or use the Cut or Copy keys on the keyboard. To paste, click at the position the text is to be located. Then press the Paste tool button, choose the Paste option from the Edit menu, or press the Paste key on the keyboard.

Text can also be copied by selecting it with the mouse, and pasting it with a middle mouse button click.

Also note that text can be copied from windows other than XEmacs windows.

• Experiment cutting and copying text. Copy text from one window to another.

Undo changes:

Pressing the Undo tool button, or choosing that option from the Edit menu, "backs out" the previous change made to the buffer. Note that the Undo button can be pressed multiple times. When all changes since the most recent save have been undone, the mode line will begin with hyphens.

Find a string of characters in a file (search):

Choose the Search option from the Edit menu. Key in the string you want to search for. The characters will be matched automatically as they are keyed. Pressing Control-S moves to the next instance of the string. Pressing Return ends the search.

Iteratively replace one string of characters with another:

Choose Replace from the Edit menu. Key the string to be replaced followed by Return. Key the replacement string, followed by Return. The next occurrence of the string (starting from the current position) to be replaced will highlighted. Key y or Space to replace it, and move to the next occurrence; key n or Delete to move to the next occurrence without replacement. Key q or Return to end the replacement operation.

This completes our brief introduction to XEmacs. Keyboard commands appear in the appendix at the end of this lab.

The Java compiler and interpreter:

We will use a terminal window to enter line commands for compilation and execution of Java programs. If necessary, review how to create terminal windows, how to create subdirectories, how to copy files, and how to navigate directories.

We will compile and run a very simple Java program, just to see how these steps are carried out.

• Create a subdirectory named Java in your home directory if you do not already have one:

    mkdir Java

• Create a subdirectory named hello2 in you Java directory:

    cd Java
    mkdir hello2

• Copy all of the files ending .java from the directory ~labCourse/Labs/Lab2/hello2 to your hello2 subdirectory. Files with an extension .java are typically text files containing program segments written in Java. They are called source files.

If you are in your Java directory, you can easily copy these files with the command:

    cp ~labCourse/Labs/Lab2/hello2/*.java hello2

The asterisk ("*") matches any string of characters.

• Examine the contents of hello2:

    ls hello2

You should see six files, named Figures.java, HelloWorldGUI.java, HelloWorldGUIStart.java, HelloWorldTUI.java, HelloWorldTUIStart.java, and Show.java. These are segments of two programs.

Next, you will compile a program: that is, run a program (the compiler) that will translate the Java source code to binary byte code. To compile, you run the Java compiler, javac, and provide it with the name of the file or files we wish to compile.

• Compile HelloWorldGUIStart.java:

    javac hello2/HelloWorldGUIStart.java

The current working directory is your java directory. Relative to this directory, the name of the file you want to compile is hello2/HelloWorldGUIStart.java.

You could also move to the hello2 subdirectory:

    cd hello2
    javac HelloWorldGUIStart.java

(A handy note: you can select text in the terminal window with the mouse, and then past it into the command line by clicking the middle mouse button.)

• Examine the contents of hello2 again. If you are in your Java directory, key

    ls hello2

If you are in your hello2 directory, simply key

    ls

You will notice there are eight additional files with the extension .class. These are the output from the compiler, and are the binary byte code files. Note that the compiler compiled not only the file that you specified, but also compiled three other source files as well: Figures.java, HelloWorldGUI.java, and Show.java. This is because the file that you specified, HelloWorldGUIStart.java, is dependent on these other files. The program is made up of these four source files. The compiler is generally clever enough to compile whatever is necessary.

Finally, you will run the program using the Java interpreter, java. The interpreter reads the byte code and executes it.

• Before you do run the program, check the CLASSPATH environment variable:

    echo $CLASSPATH

You will see a list of directories separated by colons. Something like:

    /apps/java:/home/fred/Java

Be sure that your Java directory is on this list. If it is not, consult your lab instructor.

• Run the program by keying

    java hello2.HelloWorldGUIStart

Note that you do not give the interpreter a file name: hello2.HelloWorldGUIStart is a class name, not a file name. (If you don't yet know what a class name is, don't worry about it. Just note that it is not a file name.)

The interpreter will look in the directories listed in the CLASSPATH for the first one containing a file named hello2/HelloWorldGUIStart.class. This is what the interpreter then executes.

If successful, you should see the following window, or an approximation thereof:

• End the program by closing the window, or by keying Control-C in the terminal window from which you are running the program.
• Now compile and execute the program, HelloWorldTUIStart. When you run the program, the following line should appear in you terminal window:

    Hello World. Welcome to programming with objects

Important note: these are not representative Object Oriented programs. Their only purpose is to teach you how to compile and execute.

XEmacs and Java:

XEmacs recognizes Java syntax, and provides special commands for editing and compiling Java files.

• Using XEmacs, open the file HelloWorldBroken.java, located in your Java/hello2 directory.

You should notice Java and JDE options in the menu bar, and the mode line should say something like "(JDE Font)". Whenever you open a file with the extension .java, XEmacs automatically enters JDE mode.

You can explicitly enter JDE mode by keying " Meta-X jde-mode". (Key Meta-X by pressing the X key while holding down a Meta key. The Meta keys are the keys with diamonds on either side of the space bar. Alternatively, you can press Esc followed by X.)

• Position the cursor on the line that begins "public class ..." and key the three characters "/**" followed by Return.
• Now, on the line below the "/**" key a single asterisk "*". Note that the asterisk you key aligns with the asterisk on the previous line. Type your name, followed by Return, and type "*/" on the next line. You have entered a "doc comment."
• Position the cursor anywhere on the first line beginning "System..." and press Tab. Note that the line moves over a bit. The Tab key will indent a line to show program structure.
• Press Esc followed by semicolon. Note that two slashes are added to the line and the cursor is placed at the end of the line. Any text you enter here is an "in-line comment."
• Press Control-J. Note that the next line aligns with the previous. You can accomplish the same thing by pressing Return followed by Tab.
• Select the entire buffer with the mouse. (Position the mouse to the top of the buffer; press the left mouse button, and move the mouse to the bottom of the buffer. All the text should be highlighted.)
• Choose Indent Line or Region from the Java menu.

The buffer will be indented to exhibit the program structure. One sure sign of a syntactic error is if the indention is not what you expect. (Of course, this will make more sense when you understand the program structure!)

• Save the buffer.
• Now return to the terminal window and compile HelloWorldBroken.java by keying

    javac hello2/HelloWorldBroken.java

if you are in the Java directory, or

    javac HelloWorldBroken.java

if you are in the hello2 directory.

Since there are errors in the code, the compile will not succeed. You will get output something like this:

    HelloWorldBroken.java:15: ';' expected
            System.out.println("You fixed it!")
                                               ^
    HelloWorldBroken.java:14: cannot resolve symbol
    symbol  : method printl  (java.lang.String)
    location: class java.io.PrintStream
        System.out.printl("");
                  ^
    2 errors

(There are two errors. Depending on the compiler version, the compiler may detect more. One syntactic error often spawns others, since the compiler is unable to successfully parse the erroneous statement.)

The errors occur in the file HelloWorldBroken.java at lines 15 and 14.

• Return to the XEmacs window and key Meta-G 15. (Remember, to key Meta-G, press the G key while holding down a Meta key. The Meta keys are the keys with diamonds on either side of the space bar. Alternatively, you can press Esc followed by G.) This will position you to line 15.

Can you determine what the error is and where it is located by reading the error message?

• You can also compile directly from XEmacs. Select Compile from the JDE menu.
Select Compile from the JDE menu.

Note that the window is split, and the Java compiler run in the bottom half. Again, the compile will not succeed.

• To position the cursor to the line containing the first error, key Control-X `. That is, Control-X followed by the grave. (This is the character on the upper row of the keyboard, on the same key as the tilde (~). It is not the apostrophe.)

The cursor should be positioned on the second line that begins "System...."

• The error here is that a semicolon is missing from the end of the line. Correct this error.
• Press Control-X ` again, and the cursor should be positioned on the first line that begins "System...".

The error is that the "n" is missing from "println". Correct this error as well.

• Save the buffer and compile again. This time the compilation should be successful. If not, contact your lab instructor.
• Return to the terminal window and run the program by keying

    java hello2.HelloWorldBroken

• If everything is ok, you should see the line

    You fixed it!

printed. If you do not, contact your lab instructor.

• You can also run the program from XEmacs. Choose Run App from the JDE menu. The program will run in the bottom half of the XEmacs window.
• Click in the upper half of the window (the half containing HelloWorldBroken.java), and key Control-X 1. This should get rid of the lower half window.
• Choose Pretty-Print Buffer from the File menu. This will produce laser printed output. Submit the listing to your lab instructor.

Exercise:

• Using XEmacs, open the file Counter.java that you copied to your Java/counter4 directory in a previous lab. If you have not yet copied this file, copy it from ~labCourse/Labs/Lab1/counter4.
• Add lines to the beginning of the file that contain your name, the course and section number, date, and your lecture instructor's name. Each line should begin with the characters "//". For instance,

    // Fred Hosch
    // CSCI 1581 Section 1
    // 10 Oct 2002
    // Instructor: J. Nino

• Compile the file using the Java compiler. This will ensure that you have not introduced errors into the file. (Note: since this is not a complete program, you cannot execute it.)
• Print the modified file on the line printer using the lp command. Submit the listing to your lab instructor.

Appendix: Some Emacs Commands

In the following, the notation "C- character" means "control- character" and "M- character" means "meta- character". These are generated by pressing the character key while holding down the Control key or meta key. On Sun workstations, the lozenge keys (<> ) or the LEFT and RIGHT keys on either side of the space bar are likely to serve as meta keys. Some systems do not generate meta-characters easily. In Emacs, the character sequence "ESCAPE character" is generally equivalent to "M- character". Thus to key "M-a", you can press "ESC" followed by "a".

"Button-1", "Button-2", and "Button-3" refer to the left, middle, right mouse buttons respectively. "S-Button-1" means hold the Shift key while pressing the left mouse button, "C-Button-1" means hold the Control key while pressing the left mouse button, etc. To "drag" means to move the mouse while holding down one of the buttons.

ENTERING AND LEAVING EMACS

To start XEmacs from the command line, key

xemacs filename &

If you want XEmacs to run in the terminal window or the telnet window, key

xemacs -nw filename

The option "-nw" mean "no window."

Note : You should only have one instance of Emacs running at a time. Don't crank up another Emacs process just to see another file in another window!

To leave Emacs:

C-z	In windows, this shrinks the XEmacs window to an icon. (If you're not in windows, this leaves the XEmacs session "active" as a suspended job. Reenter with the command fg, assuming you don't subsequently suspend other jobs.)
Exit XEmacs	Option on the File menu. (C-x C-c exits XEmacs, if you're not in windows.)

HELP

There is an elaborate help and info system available in Emacs. Check the Help menu (on the extreme right of the XEmacs menu bar) as well as the following.

C-h t	Run Emacs tutorial.
C-h i	Enter info mode - VERY USEFUL! READ THE INSTRUCTIONS AT THE TOP OF THE FIRST PAGE.
C-h k	Show the function of a key. (For example, C-h k C-n tells you what C-n does.)
C-h a	Show commands matching a string.
C-h f	Describe a function.

FILES

C-x C-f	Read a file into Emacs. (Open option on the File menu.)
C-x C-s	Save current buffer without leaving Emacs. (Save option on the tool bar.)
C-x s	Save selected buffers. (Save Some Buffers option on the File menu.)
C-x C-w	Write a buffer to a specified file. (Save As ... option on the File menu.)

CURSOR ("POINT") MOVEMENT

The cursor shows the location at which editing commands will take effect. This location is called point. You can use keystrokes or the mouse buttons to set the point. The point is actually between two characters: it is before the character on which the cursor appears.

The point can be positioned with the left mouse button (Button-1) or moved with the following keystroke commands.

	FORWARD	BACK
character	C-f or RIGHT ARROW	C-b or LEFT ARROW
word	M-f	M-b
line (down/up)	C-p or DOWN ARROW	C-n or UP ARROW
end/beginning of line	C-e	C-a
sentence	M-e	M-a
paragraph	M-]	M-[
page	C-x ]	C-x [
end/beginning of file (buffer)	M->	M-<

SCREEN MOTION

scroll forward	C-v
scroll back	M-v
scroll left	C-x <
scroll right	C-x >

DELETING

Delete:	FORWARD	BACK
character	C-d	Del, Back Space
word	M-d	M-Del
line (to end)	C-k	M-0 C-k
sentence	M-k	C-x Del

REGION OPERATIONS (CUTTING and PASTING)

To operate on a region of text, set the mark at one end and the point at the other. Once the mark is set, it remains fixed until it is set again. The text between the point and mark is called the region. When the region is active, it will appear highlighted and can be operated on by various region commands.

The following are useful for setting the mark.

C-@ or C-SPACE	Set mark here (at point).
C-x C-x	Exchange point and mark.
C-<	Set mark at beginning of buffer.
C->	Set mark at end of buffer.

The following keystrokes are useful to cut and paste selected text.

C-w	Kill (cut) active region.
C-y	Yank (paste) back last thing killed.
M-w	GNU Emacs: Copy active region.

Text can also be copied from other windows into an Emacs buffer. Select the text by dragging the mouse while pressing the left button (Button-1). Use the middle button (Button-2) to paste the text into the Emacs buffer.

There are many commands that apply to regions. For example, C-x C-u will convert the region to all upper-case.

NUMERIC ARGUMENTS

Numeric arguments can be given to a command by typing

C-u numeric-argument command

ERROR RECOVERY

C-g	Abort partially typed or executing command.
C-_ or C-x C-u	Undo previous change (repeated, this will "unstack" previous changes.). (Undo option on the Edit menu.)
C-l	Repaint screen.

INCREMENTAL SEARCH

C-s	Search forward.
C-r	Search backward.
Use C-s or C-r again to repeat the search in either direction.
RETURN	Exit incremental search mode.
C-g	Abort current search.

QUERY REPLACE

M-%	Interactively replace a text string.

SPACE	Replace this one; go on to the next.
,	Replace this one; don't go on to the next.
DELETE	Skip to next without replacing.
!	Replace all remaining matches.
~	Back up to previous match.
RETURN	Exit query-replace mode.

FRAMES, WINDOWS and BUFFERS

An instance of XEmacs can be controlling several windows (called XEmacs frames). Each XEmacs frame (window) can be split into multiple XEmacs "windows." Each XEmacs window displays a portion of a buffer. The following commands refer to XEmacs windows within a single X window.

C-x 2	Break window vertically.
C-x 5	Break window horizontally.
C-x o	Switch cursor to other window.
ESCAPE C-v	Scroll other window.
C-x f	Load file into other window.
C-x 1	Delete other window.
C-x 0	Delete current window.

C-x 5 2 creates a new window (XEmacs frame), and C-x 5 0 deletes a frame.

The following are useful buffer commands. See the Buffers menu as well.

C-x b	Switch buffer in current window.
C-x 4 b	Switch buffer in other window.
C-x C-b	List buffers.
C-x k	Kill buffer. (Delete Buffer option under a particular buffer on the Buffers menu.)

MISCELLANEOUS

A few random items. Keys in XEmacs are not "hard wired." In fact, each key stroke runs a function, and the function tied to any key can be changed dynamically. To see what function is being run by a key or key sequence, you can use C-h k.

You can also run functions explicitly by name. To do this, type M-x and then the name of the function. For instance, the command to change major mode is typically name-of-mode-mode. Keying

    M-x c-mode
    M-x fundamental-mode
    M-x text-mode

    M-x auto-fill-mode

    M-x auto-f TAB

XEmacs can be initialized with a file named .emacs in your home directory. For example, you can set your default mode by including a line such as

    (setq default-major-mode 'text-mode)

As another example of key to function binding, suppose you are running Emacs remotely through a terminal server. You might have trouble getting the terminal server to pass the characters C-s and C-q through to Emacs. By default, C-s runs the function isearch-forward and C-q runs quoted-insert. You can run these functions directly (with M-x as mentioned above), or you can bind them to other keys. For instance, if you enter

    M-x global-set-key RETURN C-x $ isearch-forward RETURN

Finally,

C-o	Open line (insert newline after point).