Relay-Version: version B 2.10 5/3/83; site utzoo.UUCP Path: utzoo!mnetor!uunet!husc6!necntc!ncoast!allbery From: nwd@j.cc.purdue.edu (Daniel Lawrence) Newsgroups: comp.sources.misc Subject: MicroEmacs 3.9 Manual (2 of 6) Message-ID: <5815@ncoast.UUCP> Date: Wed, 25-Nov-87 23:14:19 EST Article-I.D.: ncoast.5815 Posted: Wed Nov 25 23:14:19 1987 Date-Received: Mon, 30-Nov-87 00:57:01 EST Sender: allbery@ncoast.UUCP Lines: 1189 Approved: allbery@ncoast.UUCP X-Archive: comp.sources.misc/8711/13 Xvalue used to reset $ACOUNT after a save occurs. X X@section(CMODE mode)@index(CMODE mode) X X CMODE is useful to C programmers. When CMODE is active, EMACS Xwill try to assist the user in a number of ways. This mode is set Xautomatically with files that have a .c or .h extension. X X The key will normally attempt to return the user to the next Xline at the same level of indentation as the current line, unless the Xcurrent line ends with a open brace ({) in which case the new line will Xbe further indented by one tab position. X X A close brace (}) will delete one tab position preceeding itself Xas it is typed. This should line up the close brace with its matching XIF, FOR or WHILE statement. X X A pound sign (#) with only leading whitespace will delete all Xthe whitespace preceeding itself. This will always bring preprocessor Xdirectives flush to the left margin. X X Whenever any close fence is typed, ie )]>}, if the matching open Xfence is on screen in the current window, the cursor will briefly flash Xto it, and then back. This makes balancing expressions, and matching Xblocks much easier. X X@section(CRYPT mode)@index(CRYPT mode) X X When a buffer is in CRYPT mode, @index(encryption) it is Xencrypted whenever it is written to a file, and decrypted when it is Xread from the file. The encryption key can be specified on the command Xline with the -k switch, or with the @b(M-E) @i(set-encryption-key) X@index(set-encryption-key) command. If you attempt to read or write a Xbuffer in crypt mode and now key has not been set, EMACS will execute X@i(set-encryption-key) automatically, prompting you for the needed key. XWhenever EMACS prompts you for a key, it will not echo the key to your Xscreen as you type it (ie make SURE you get it right when you set it Xoriginally). X X The encryption algorithm used changes all characters into normal Xprinting characters, thus the resulting file is suitable for sending via Xelectronic mail. All version of MicroEMACS should be able decrypt the Xresulting file regardless of what machine encrypted it. Also available Xwith EMACS is the stand alone program, MicroCRYPT, which can en/decrypt Xthe files produced by CRYPT mode in EMACS. X X@section(EXACT mode)@index(EXACT mode) X X All string searches and replacements will take upper/lower case Xinto account. Normally the case of a string during a search or replace Xis not taken into account. X X@section(MAGIC mode)@index(MAGIC mode) X X In the MAGIC mode certain characters gain special meanings when Xused in a search pattern. Collectively they are know as regular Xexpressions, and a limited number of them are supported in MicroEmacs. XThey grant greater flexibility when using the search command. However, Xthey do not affect the incremental search command. X X The symbols that have special meaning in MAGIC mode are X^, $, ., &, *, [ (and ], used with it), and \. X X The characters ^ and $ fix the search pattern to the beginning and Xend of line, respectively. The ^ character must appear at the beginning Xof the search string, and the $ must appear at the end, otherwise they Xloose their meaning and are treated just like any other character. For Xexample, in MAGIC mode, searching for the pattern "t$" would put the Xcursor at the end of any line that ended with the letter 't'. Note that Xthis is different than searching for "t", that is, 't' followed by a Xnewline character. The character $ (and ^, for that matter) matches a Xposition, not a character, so the cursor remains at the end of the line. XBut a newline is a character that must be matched, just like any other Xcharacter, which means that the cursor is placed just after it - on the Xbeginning of the next line. X X The character . has a very simple meaning -- it matches any single Xcharacter, except the newline. Thus a search for "bad.er" could match X"badger", "badder" (slang), or up to the 'r' of "bad error". X X The character * is known as closure, and means that zero or more of Xthe preceding character will match. If there is no character preceding, X* has no special meaning, and since it will not match with a newline, * Xwill have no special meaning if preceded by the beginning of line symbol X^ or the literal newline character . X X The notion of zero or more characters is important. If, for Xexample, your cursor was on the line X X@quotation(This line is missing two vowels.) X Xand a search was made for "a*", the cursor would not move, because it is Xguaranteed to match no letter 'a' , which satifies the search Xconditions. If you wanted to search for one or more of the letter 'a', Xyou would search for "aa*", which would match the letter a, then zero or Xmore of them. X X The character [ indicates the beginning of a character class. It Xis similar to the 'any' character ., but you get to choose which Xcharacters you want to match. The character class is ended with the Xcharacter ]. So, while a search for "ba.e" will match "bane", "bade", X"bale", "bate", et cetera, you can limit it to matching "babe" and X"bake" by searching for "ba[bk]e". Only one of the characters inside Xthe [ and ] will match a character. If in fact you want to match any Xcharacter except those in the character class, you can put a ^ as the Xfirst character. It must be the first character of the class, or else Xit has no special meaning. So, a search for [^aeiou] will match any Xcharacter except a vowel, but a search for [aeiou^] will match any vowel Xor a ^. X XIf you have a lot of characters in order that you want to put in the Xcharacter class, you may use a dash (-) as a range character. So, [a-z] Xwill match any letter (or any lower case letter if EXACT mode is on), Xand [0-9a-f] will match any digit or any letter 'a' through 'f', which Xhappen to be the characters for hexadecimal numbers. If the dash is at Xthe beginning or end of a character class, it is taken to be just a Xdash. X X The character & (ampersand) is a replacement character, and Xrepresents the characters which matched the search string. When used in Xthe @b[M-R] @i(replace-string) @index(replace-string) or the @b[M-^R] X@i(query-replace-string) @index(query-replace-string) commands, the & Xwill be substituted for the search string. X X The escape character \ is for those times when you want to be in XMAGIC mode, but also want to use a regular expression character Xto be just a character. It turns off the special meaning of the Xcharacter. So a search for "it\." will search for a line with "it.", Xand not "it" followed by any other character. The escape character Xwill also let you put ^, -, or ] inside a character class with no Xspecial side effects. X X@section(OVER mode)@index(OVER mode) X X OVER mode stands for overwrite mode. When in this mode, when Xcharacters are typed, instead of simply inserting them into the file, XEMACS will attempt to overwrite an existing character past the point. XThis is very useful for adjusting tables and diagrams. X X@section(WRAP mode)@index(WRAP mode) X X Wrap mode is used when typing in continuous text. Whenever the Xcursor is past the currently set fill column @index(fill column) (72 by Xdefault) and the user types a space or a , the last word of the line Xis brought down to the beginning of the next line. Using this, one just Xtypes a continuous stream of words and EMACS automatically inserts s Xat appropriate places. X X@center(NOTE to programmers:) X X@quotation{EMACS actually calls up the function bound to the illegal Xkeystroke M-FNW. This is bound to the function @i(wrap-word) X@index(wrap-word) by default, but can be re-bound to activate different Xfunctions and macros at wrap time.} X X@section(VIEW mode)@index(VIEW mode) X X VIEW mode disables all commands which can change the current Xbuffer. EMACS will display an error message and ring the bell every Xtime you attempt to change a buffer in VIEW mode. X@newpage X@heading(Chapter @value(chapter) Summary) X XIn Chapter @value(chapter) you learned about modes and their effects. X X@begin{verbatim} X@u(Key Binding Keystroke Effect) XAdd-Mode @b(^X-M) Add a mode to the current buffer X XDelete-Mode @b(^X-^M) Delete a mode from the current buffer X XAdd-Global-Mode @b(M-M) Add a global mode to the X current buffer X XDelete-Global-Mode @b(M-^M) Delete a global mode from the X current buffer X@end(verbatim) X@chapter(Files) X XA file is simply a collection of related data. In EMACS we are dealing Xwith text files -- named collections of text residing on a disk (or some Xother storage medium). You will recall that the major entities EMACS Xdeals with are buffers. Disk-based versions of files are only active in XEMACS when you are reading into or writing out of buffers. As we have Xalready seen, buffers and physical files are linked by associated Xfile names. For example, the buffer "ch7.txt" which is associated with Xthe physical disk file "ch7.txt." You will notice that the file is Xusually specified by the drive name or (in the case of a hard drive) a Xpath. Thus you can specify full file names in EMACS, X Xe.g. disk:\directories\filename.extension X XIf you do not specify a disk and directories, the default disk is used. X XIMPORTANT -- If you do not explicitly save your buffer to a file, all your Xedits will be lost when you leave EMACS (although EMACS will prompt you Xwhen you are about to lose edits by exiting). In addition, EMACS does Xnot protect your disk-based files from overwriting when it saves files. XThus when you instruct EMACS to save a file to disk, it will create a Xfile if the specified file doesn't exist, or it will overwrite the Xpreviously saved version of the file thus replacing it. Your old Xversion is gone forever. X XIf you are at all unsure about your edits, or if (for any reason) you Xwish to keep previous versions of a file, you can change the name of the Xassociated file with the command @b{^X-N}. When this file is saved Xto disk, EMACS will create a new physical file under the new name. The Xearlier disk file will be preserved. X XFor example, let's load the file @b{fang.txt} into EMACS. Now, type X@b{^X-N}. The EMACS command line prompts "name:". Enter a new name Xfor the file -- say @b(new.txt) and press . The file will be Xsaved under the new filename, and your disk directory will show both X@b(fang.txt) and @b(new.txt). X XAn alternative method is to write the file directly to disk under a new Xfilename. Let's pull our "publish.txt" file into EMACS. To write this Xfile under another filename, type @b{^X-^W}. EMACS will prompt Xyou "write file:". Enter an alternate filename -- @b{desktop.txt}. XYour file will be saved as the physical file "desktop.txt". X XNote that in the examples above, although you have changed the names of Xthe related files, the buffer names remain the same. However, when you Xpull the physical file back into EMACS, you will find that the buffer Xname now relates to the filename. X XFor example -- You are working with a buffer "fang.txt" with the related Xfile "fang.txt". You change the name of the file to "new.txt". EMACS Xnow shows you working with the buffer "fang.txt" and the related file X"new.txt". Now pull the file "new.txt" into EMACS. Notice that the Xbuffer name has now changed to "new.txt". X XIf for any reason a conflict of buffer names occurs,(if you have files Xof the same name on different drives for example) EMACS will prompt Xyou "use buffer:". Enter an alternative buffer name if you need to. X XFor a list of file related commands (including some we`ve already Xseen), see the summary page. X@newpage X@heading(Chapter @value(chapter) Summary) X XIn Chapter @value(chapter) you learned some of the more advanced Xconcepts of file naming and manipulation. The relationship between Xfiles and buffers was discussed in some detail. X X@begin(verbatim) X@u(Key Binding Keystroke Effect) X XSave-file @b{^X-^S} Saves contents of current buffer with X associated filename on default disk/ X directory (if not specified) X XWrite-File @b{^X-^W} Current buffer contents will be X saved under specified name X XChange-File-name X @b{^X-N} The associated filename is changed X (or associated if not previously X specified) as specified X XFind-File @b{^X-^F} Reads specified file into buffer and X switches you to that buffer, or switches X to buffer in which the file has previously X been read X XRead-File @b{^X-^R} Reads file into buffer thus overwriting X buffer contents. If file has already X been read into another buffer, you will X be switched to it X XView-File @b{^X-^V} The same as read-file except the buffer X is automatically put into VIEW mode thus X preventing any changes from being made X@end{verbatim} X@chapter(Screen Formatting) X X@section X XAs we learned in the introduction, EMACS is not a word processor, but an Xeditor. Some simple formatting options are available however, although Xin most cases they will not affect the appearence of the finished text X@index(wrapping text) when it is run through the formatter. We have Xalready encountered WRAP mode which wraps lines longer than a certain Xlength (default is 75 characters). You will recall that WRAP is enabled Xby entering @b{^X-M} and responding to the command line prompt with X@b{wrap}. X XYou can also set your own wrap margin with the command @b{^X-F} X@i(set-fill-column) @index(set-fill-column). Notice EMACS responds X"[Fill column is 1]." Now try typing some text. You'll notice some very Xstrange things happening -- your text wraps at every word!! This effect Xoccurs because the set wrap margin command must be preceeded by a Xnumeric argument or EMACS sets it to the first column. Thus any text Xyou type that extends past the first column will wrap at the most Xconvenient line break. X XTo reset the wrap column to 72 characters, press the @b{} key and Xenter 72. EMACS will respond "Arg: 72". Now press @b<^X-F>. EMACS Xwill respond "[Fill column is 72]". Your text will again wrap at the Xmargin you've been using up to this point. X X@section X XAfter an intensive editing session, you may find that you have Xparagraphs containing lines of differing lengths. Although this Xdisparity will not affect the formatted text, aesthetic and technical Xconcerns may make it desirable to have consistent paragraph blocks on Xthe screen. If you are in WRAP mode, you can reformat a paragraph with Xthe command @b{M-Q} @i(fill-paragraph) @index(fill-paragraph). This Xcommand 'fills' the current paragraph reformatting it so all the lines Xare filled and wrap logically. The process is complex, and (especially Xwith longer paragraphs) may take a little time. X X@section X XThere may be occasions when you find it necessary to change the case of Xthe text you've entered. EMACS allows you to change the case of even Xlarge amounts of text with ease. Let's try and convert a few of the Xoffice traditionalists to the joy of word processing. Type in the Xfollowing text: X X@quotation{Throw away your typewriter and learn to use a word processor. XWord processing is relatively easy to learn and will increase your Xproductivity enormously. Enter the Computer Age and find out just how Xmuch fun it can be!!} X XLet's give it a little more impact by capitalizing the first four words. XThe first step is to define the region of text just as you would if you Xwere doing an extensive deletion. Set the mark at the beginning of the Xparagraph with @b{M-} @i(set-mark) and move the cursor to the Xspace beyond "typewriter." Now enter @b{^X-^U} @i(case-region-upper). XYour text should now look like this: X X@quotation{THROW AWAY YOUR TYPEWRITER and learn to use a word processor. XWord processing is relatively easy to learn and will increase your Xproductivity enormously. Enter the Computer Age and find out just how Xmuch fun it can be!!} X XIf you want to change the text back to lower case, type @b{^X-^L} X@i(case-region-lower) @index(case-region-lower). You can also Xcapitalize individual words. To capitalize the word "fun", position the Xcursor in front of the word and type @b{M-U} @i(case-word-upper) X@index(case-word-upper). The word is now capitalized. To change it Xback to lower case, move the cursor back to the beginning of the word Xand type @b{M-L} @i(case-word-lower) @index(case-word-lower). X XYou may also capitalize individual letters in EMACS. The command X@b{M-C} @i(case-word-capitalize) @index(case-word-capitalize) Xcapitalizes the first letter after the point. This command would Xnormally be issued with the cursor positioned in front of the first Xletter of the word you wish to capitalize. If you issue it in the Xmiddle of a word, you can end up with some strAnge looking text. X X@section X XUnless your formatter is instructed to take screen text literally (as XMicroSCRIBE does in the 'verbatim' environment for example), tabs in XEMACS generally affect screen formatting only. X XWhen EMACS is first started, it sets the default tab to every eighth Xcolumn. As long as you stay with default, every time you press the tab Xkey a tab character, @b(^I) is inserted. This character, like other Xcontrol characters, is invisible -- but it makes a subtle and Xsignificant difference to your file and editing. X XFor example, in default mode, press the tab key and then type the word X@b{Test}. "Test" appears at the eighth column. Move your cursor to the Xbeginning of the word and delete the backward character. The word Xdoesn't move back just one character, but flushes to the left margin. XThe reason for this behavior is easily explained. In tab default, EMACS Xinserts a 'real' tab character when you press the tab key. This Xcharacter is inserted at the default position, but NO SPACES are Xinserted between the tab character and the margin (or previous tab Xcharacter). As you will recall, EMACS only recognizes characters (such Xas spaces or letters) and thus when the tab character is removed, the Xtext beyond the tab is flushed back to the margin or previous tab mark. X XThis situation changes if you alter the default configuration. The Xdefault value may be changed by entering a numeric argument before Xpressing the tab key. As we saw earlier, pressing the @b{META} key and Xentering a number allows you to specify how EMACS performs a given Xaction. In this case, let's specify an argument of 10 and hit the tab Xkey. X XNow hit the tab key again and type @b{Test}. Notice the word now Xappears at the tenth column. Now move to the beginning of the word and Xdelete the backward character. "Test" moves back by one character. X XEMACS behaves differently in these circumstances because the @b(^I) X@index(tab handling) @i(handle-tab) @index(handle-tab) function deals Xwith tabbing in two distinct ways. In default conditions, or if the Xnumeric argument of zero is used, @i(handle-tab) inserts a true tab Xcharacter. If, however, a non-zero numeric argument is specified, X@i(handle-tab) inserts the correct number of spaces needed to position Xthe cursor at the next specified tab position. It does NOT insert the Xsingle tab character and hence any editing functions should take account Xof the number of spaces between tabbed columns. X XMany times you would like to take a line which has been created using Xthe tab character and change it to use just spaces. The command X@b(^X-^D) @i(detab-line) @index(detab-line) changes any tabs from the Xpoint to the end of the current line into the right number of spaces so Xthe line does not change. This is very useful for times when the file Xmust be printed or transfered to a machine which does not understand Xtabs. X XAlso, the inverse command, @b(^X-^E) @i(entab-lines) @index(entab-lines) Xchanges multiple spaces to tabs where possible. This is a good way to Xshrink the size of large documents, especially with data tables. Both Xof these commands can take a numeric argument which will be interpeted Xas the number of lines to en/detab. X@newpage X@heading(Chapter @value(chapter) Summary) X XIn Chapter @value(chapter) introduced some of the formatting features of XEMACS. Text-wrap, paragraph reformatting, and tabs were discussed in Xsome detail. The commands in the following table were covered in the Xchapter. X X@begin{verbatim} X X@u(Key Binding Keystroke Effect) XAdd-Mode/WRAP @b{^X-M}[WRAP] Add wrap mode to current buffer X XDelete-Mode/WRAP @b{^X-^M}[WRAP] Remove wrap mode from current buffer X XSet-Fill-Column @b{^X-F} Set fill column to given numeric X argument X XFill-Paragraph @b{M-Q} Logically reformats the current X paragraph X XCase-Word-Upper @b{M-U} Text from point to end of the X current word is changed to uppercase X XCase-Word-Lower @b{M-L} Text from point to end of the X current word is changed to lowercase X XCase-Word-Capitalize @b{M-C} First word (or letter) after the X point is capitalized X XCase-Region-Upper @b{^X-^U} The current region is uppercased X XCase-Region-Lower @b{^X-^L} The current region is lowercased X XHandle-Tab @b{^I} Tab interval is set to the given X numeric argument XEntab-Line @b(^X-^E) Changes multiple spaces to tabs X characters where possible XDetab-Line @b(^X-^D) Changes tab characters to the X appropriate number of spaces X@end{verbatim} X@chapter(Access to the Outside World) X X EMACS has the ability to interface to other programs and the Xenvironment of the computer outside of itself. It does this through a Xseries of commands that allow it to talk to the computer's @b(command Xprocessor) @index(command processor) or @b(shell) @index(shell). Just Xwhat this is varies between different computers. Under MSDOS or PCDOS Xthis is the @b(command.com) @index(command.com) command processor. XUnder UNIX it is the @b(csh) @index(cshell) shell. On the Atari ST is Xcan be the Mark Williams @b(MSH) or the Beckmeyer shell. In each case, Xit is the part of the computer's operating system that is responcable Xfor determining what programs are executed, and when. X X The @b(^X-!) @i(shell-command) @index(shell-command) command Xprompts the user for a command line to send out to the shell to execute. XThis can be very useful for doing file listings and changing the Xcurrent directory or folder. EMACS gives control to the shell, which Xexecuted the command, and then types @b([END]) and waits for the user to Xtype a character before redrawing the screen and resuming editing. If Xthe @i(shell-command) command is used from within the macro language, Xthere is no pause. X X @b(^X-@@) @i(pipe-command) @index(pipe-command) command allows XEMACS to execute a shell command, and if the particular computer allows Xit, send the results into a buffer which is automatically displayed on Xthe screen. The resulting buffer, called "command" can be manipulated Xjust like any other editing buffer. Text can be copied out of it or Xrearanged as needed. This buffer is originally created in @b(VIEW) mode, Xso remember to @b(^X-^Mview) in order to change it. X X Many computers provide tools which will allow you to @b(filter) X@index(filter) text, making some modifications to it along the way. A Xvery common tool is the @b(SORT) program which accepts a file, sorts it, Xand prints the result out. The EMACS command, @b(^X-#) @i(filter-buffer) Xsends the current buffer through such a filter. Therefore, if you Xwished to sort the current buffer on a system which supplied a sort Xfilter, you would type @b(^X-#sort). You can also create your own Xfilters by writing programs and utilities which read text from the Xkeyboard and display the results. EMACS will use any of these which Xwould normally be available from the current shell. X X If you would like to execute another program directly, without Xthe overhead of an intervening shell, you can use the @b(^X-$) X@i(execute-program) @index(execute-program) command. It will prompt you Xfor an external program and its arguments and attempt to execute it. XLike when EMACS looks for command files, EMACS will look first in the XHOME directory, then down the execute PATH, and finally in the current Xdirectory for the named program. On some systems, it will automatically Xtack the proper extension on the file name to indicate it is a program. XOn some systems that don't support this function, @b(^X-$) will be Xequivalent to @b(^X-!) @i(shell-command). X X Sometimes, you would like to get back to the shell and execute Xother commands, without losing the current contents of EMACS. The X@b(^X-C) @i(i-shell) @index(i-shell) command shells out of EMACS, Xleaving EMACS in the computer and executing another command shell. Most Xsystems would allow you to return to EMACS with the "exit" command. X X@i( On some systems, mainly advanced versions of UNIX, you can Xdirect EMACS to "go into the background" with the @b(^X-D) suspend-emacs X@index(suspend-emacs) command. This places EMACS in the background Xreturning you to the original command shell. EMACS can then be returned Xto at any time with the "fg" foreground command.) X@newpage X@heading(Chapter @value(chapter) Summary) X XIn Chapter @value(chapter) introduced different ways to access the Xcomputers shell or command processor from within EMACS. The commands Xin the following table were covered in the chapter. X X@begin{verbatim} X X@u(Key Binding Keystroke Effect) XExecute-program @b(^X-$) Execute an external program X directly X XFilter-command @b(^X-#) Send the current buffer through X a shell filter X XI-shell @b(^X-C) Escape to a new shell X XPipe-command @b(^X-@@) Send the results of an external X shell command to a buffer X XShell-command @b(^X-!) Execute one shell command X XSuspend-emacs @b(^X-D) Place EMACS in the background X (some UNIX systems only) X@end{verbatim} X@chapter(Keyboard Macros) X XIn many applications, it may be necessary to repeat a series of Xcharacters or commands frequently. For example, a paper may require the Xfrequent repetition of a complex formula or a long name. You may also Xhave a series of EMACS commands that you invoke frequently. Keyboard Xmacros offer a convenient method of recording and repeating these Xcommands. X XImagine, for example, you are writing a scholarly paper on @i{Asplenium Xplatyneuron}, the spleenwort fern. Even the dedicated botanist would Xprobably find it a task bordering on the agonizing to type X@i{Asplenium platyneuron} frequently throughout the paper. An Xalternative method is 'record' the name in a keyboard macro. Try it Xyourself. X XThe command @b{^X-(} @i(begin-macro) @index(begin-macro) starts Xrecording the all the keystrokes and commands you input. After you've Xtyped it, enter @b{Asplenium platyneuron}. To stop recording, type X@b{^X-)} @i(end-macro) @index(end-macro). EMACS has stored all the Xkeystrokes between the two commands. To repeat the name you've stored, Xjust enter @b{^X-E} @i(execute-macro) @index(execute-macro), and the Xname "Asplenium platyneuron" appears. You can repeat this action as Xoften as you want, and of course as with any EMACS command, you may Xprecede it with a numerical argument. X XBecause EMACS records keystrokes, you may freely intermix commands and Xtext. Unfortunately, you can only store one macro at a time. Thus, if Xyou begin to record another macro, the previously defined macro is Xlost. Be careful to ensure that you've finished with one macro before Xdefining another. If you have a series of commands that you would like Xto 'record' for future use, use the macro or procedure facilities Xdetailed in chapter . X@newpage X@heading(Chapter @value(chapter) Summary) X XChapter @value(chapter) covered keyboard macros. You learned how to Xrecord keystrokes and how to repeat the stored sequence. X X@begin{verbatim} X@u(Key Binding Keystroke Effect) X XStart-Macro @b{^X-(} Starts recording all keyboard input X XEnd-Macro @b{^X-)} Stops recording keystrokes for macro X XExecute-Macro @b{^X-E} Entire sequence of recorded X keystrokes is replayed X@end{verbatim} X@chapter(MicroEMACS Macros) X X Macros are programs that are used to customize the editor and to Xperform complicated editing tasks. They may be stored in files or Xbuffers and may be executed using an appropriate command, or bound to a Xparticular keystroke. Portions of the standard start-up file are Ximplemented via macros, as well as the example menu system. The X@i(execute-macro-) @index(execute-macro-) commands cause the Xmacro, numbered from 1 to 40, to be executed. The @i(execute-file) X@index(execute-file) command allows you to execute a macro stored in a Xdisk file, and the @i(execute-buffer) @index(execute-buffer) command Xallows you to execute a macro stored in a buffer. Macros are stored for Xeasy execution by executing files that contain the store-macro command. X X If you need more than 40 macros, named macroes, called X@b(procedures), @index(procedures) can be used. The @i(store-procedure) X@index(store-procedure) command takes a string argument which is the Xname of a procedure to store. These procedures than can be executed Xwith the @b(M-^E) @i(execute-procedure) @index(execute-procedure) or the X@i(run) @index(run) commands. X X There are many different aspects to the macro language within XMicroEMACS. Editor commands are the various commands that manipulate Xtext, buffers, windows, etc, within the editor. Directives are commands Xwhich control what lines get executed within a macro. Also there are Xvarious types of variables. Environmental variables both control and Xreport on different aspects of the editor. User variables hold string Xvalues which may be changed and inspected. Buffer variables allow text Xto be placed into variables. Interactive variable allow the program to Xprompt the user for information. Functions can be used to manipulate Xall these variables. X X@section(Constants) X X All constants and variable contents in EMACS are stored as Xstrings of characters. Numbers are stored digit by digit as characters. XThis allows EMACS to be "typeless", not having different variables types Xbe legal in different contexts. This has the disadvantage of forcing the Xuser to be more carefull about the context of the statements variables Xare placed in, but in turn gives them more flexibility in where they Xcan place variables. Needless to say, this also allows EMACS's expression Xevaluator to be both consice and quick. X X Wherever statements need to have arguments, it is legal to place Xconstants. A constant is a double quote character, followed by a string Xof characters, and terminated by another double quote character. To Xrepresent various special characters within a constant, the tilde (~) Xcharacter is used. The character following the tilde is interpeted Xaccording to the following table: X X@begin(verbatim) X@u(Sequence Result) X~n ^J linefeed/newline, (EMACS newline character) X~r ^M carraige return X~~ ~ X~b ^H backspace X~f ^L formfeed X~t ^I tab X~" " X@end(verbatim) X X Any character not in the table which follows a tilde will be Xpassed unmodified. This action is similar to the @b(^Q) X@i(quote-character) command available from the keyboard. X X The double quotes around constants are not needed if the Xconstant contains no internal whitespace and it also does not happen to Xmeet the rules for any other EMACS commands, directives, variables, or Xfunctions. This is reasonable useful for numeric constants. X X@section(Variables) X X Variables in MicroEMACS can be used to return values within Xexpressions, as repeat counts to editing commands, or as text to be Xinserted into buffers and messages. The value of these variables is set Xusing the set (^X-A) command. For example, to set the current fill Xcolumn to 64 characters, the following macro line would be used: X X set $fillcol 64 X X or to have the contents of @b(%name) inserted at the point in the Xcurrent buffer, the command to use would be: X X insert-string %name X@newpage X@subsection(Environmental Variables) X X "What good is a quote if you can't change it?" X X These variables are used to change different aspects of the way Xthe editor works. Also they will return the current settings if used as Xpart of an expression. All environmental variable names begin with a Xdollar sign ($) and are in lower case. X X@begin(description) X$acount@\The countdown of inserted characters until the next save-file. X X$asave@\The number of inserted characters between automatic file-saves Xin ASAVE mode. X X$cbufname@\Name of the current buffer X X$cfname@\File name of the current buffer X X$cmode@\Integer containing the mode of the current buffer. (See Appendix F Xfor values) X X$curchar@\Character currently at the point X X$curcol@\Current column of point in current buffer X X$curline@\Current line of point in current buffer X X$curwidth@\Number of columns used currently X X$cwline@\Current display line in current window X X$debug@\Flag to trigger macro debugging (try it... you'll like it!) X X$discmd@\Flag to disable the echoing of messages on the command line X X$disinp@\Flag to disable the echoing of characters during command line input X X$fillcol@\Current fill column X X$flicker@\Flicker Flag set to TRUE if IBM CGA set to FALSE for most others X X$gflags@\Global flags controlling some EMACS internal functions (See Xappendix G for details) X X$gmode@\Global mode flags. (See Appendix F for values) X X$lastkey@\[READ ONLY]Last keyboard character typed X X$line@\The current line in the current buffer can be retrieved and Xset with this environment variable X X$lwidth@\[READ ONLY]Returns the number of characters in the current line X X$match@\[READ ONLY]Last string matched in a magic mode search X X$pagelen@\Number of screen lines used currently X X$palette@\string used to control the palette register settings on Xgraphics versions. The usually form consists of groups of three octal Xdigits setting the red, green, and blue levels. X X$pending@\[READ ONLY]Flag to determine if there are user keystrokes Xwaiting to be processed. X X$progname@\[READ ONLY]Always contains the string "MicroEMACS" for Xstandard MicroEMACS. Could be something else if EMACS is incorporated Xas part of someone else's program X X$replace@\Current default replace string X X$rval@\This contains the return value from the last subprocess which was Xinvoked from EMACS X X$search@\Current default search string X X$seed@\Integer seed of the random number generator X X$sres@\Current screen resolution (CGA, MONO or EGA on the IBM-PC driver. XLOW, MEDIUM, HIGH or DENSE on the Atari ST1040, NORMAL on all others) X X$status@\[READ ONLY]Status of the success of the last command (TRUE or XFALSE). This is usually used with !force to check on the success of a Xsearch, or a file operation. X X$target@\Current target for line moves (setting this fool's EMACS into Xbelieving the last command was a line move) X X$tpause@\Controls the length of the pause to display a matched fence Xwhen the current buffer is in CMODE and a close fence has been typed X X$version@\[READ ONLY]Contains the current MicroEMACS version number X X$wline@\Number of display lines in current window X@end(description) X X Obviously, many more of these variables will be availible in Xfuture releases of MicroEMACS. (Yes, send a vote for your favorite new Xenvironmental variables today). X X@subsection(User variables) X X User variables allow you, the user, to store strings and Xmanipulate them. These strings can be pieces of text, numbers (in text Xform), or the logical values @b(TRUE) and @b(FALSE). These variables Xcan be combined, tested, inserted into buffers, and otherwise used to Xcontrol the way your macros execute. At the moment, up to 255 user Xvariables may be in use in one editing session. All users variable Xnames must begin with a percent sign (%) and may contain any printing Xcharacters. Only the first 10 characters are significant (ie Xdifferences beyond the tenth character are ignored). Most operators Xwill truncate strings to a length of 128 characters. X X@subsection(Buffer Variables) X X Buffer variables are special in that they can only be queried Xand cannot be set. What buffer variables are is a way to take text from Xa buffer and place it in a variable. For example, if I have a buffer by Xthe name of RIGEL2, and it contains the text: X X@begin(verbatim) X@begin(group) X Richmond X Lafayette X <*>Bloomington (where <*> is the current point) X Indianapolis X Gary X =* MicroEMACS 3.9e (WRAP) == rigel2 == File: /data/rigel2.txt ===== X@end(group) X@end(verbatim) X X and within a command I reference #rigel2, like: X X insert-string #rigel2 X X MicroEMACS would start at the current point in the RIGEL2 Xbuffer and grab all the text up to the end of that line and pass that Xback. Then it would advance the point to the beginning of the next line. XThus, after our last command executes, the string "Bloomington" gets Xinserted into the current buffer, and the buffer RIGEL2 now looks like Xthis: X X@begin(verbatim) X@begin(group) X Richmond X Lafayette X Bloomington X <*>Indianapolis (where <*> is the current point) X Gary X =* MicroEMACS 3.9e (WRAP) == rigel2 == File: /data/rigel2.txt ===== X@end(group) X@end(verbatim) X X as you have probably noticed, a buffer variable consists of the Xbuffer name, preceded by a pound sign (#). X X@subsection(Interactive variables) X X Interactive variables are actually a method to prompt the user Xfor a string. This is done by using an at sign (@@) followed either with Xa quoted string, or a variable containing a string. The string is the Xplaced on the bottom line, and the editor waits for the user to type in Xa string. Then the string typed in by the users is returned as the Xvalue of the interactive variable. For example: X X@begin(verbatim) X set %quest "What file? " X find-file @@%quest X@end(verbatim) X X will ask the user for a file name, and then attempt to find it. XNote also that complex expressions can be built up with these Xoperators, such as: X X@verbatim(@@&cat &cat "File to decode[" %default "]: ") X X which prompts the user with the concatinated string. X X@section(Functions) X X Functions can be used to manipulate variables in various ways. XFunctions can have one, two, or three arguments. These arguments will Xalways be placed after the function on the current command line. For Xexample, if we wanted to increase the current fill column by two, using Xemacs's set (^X-A) command, we would write: X X@begin(group) X@begin(verbatim) X set $fillcol &add $fillcol 2 X \ \ \ \ \____second operand X \ \ \ \_________first operand X \ \ \_______________function to execute X \ \_____________________variable to set X \___________________________set (^X-A) command X@end(verbatim) X@end(group) X X Function names always begin with the ampersand (&) character, Xand are only significant to the first three characters after the Xampersand. Functions will normal expect one of three types of Xarguments, and will automatically convert types when needed. X X@begin(description) X@\an ascii string of digits which is interpeted as a numeric value. XAny string which does not start with a digit or a minus sign (-) will be Xconsidered zero. X X@\An arbitrary string of characters. At the moment, strings are Xlimited to 128 characters in length. X X@\A logical value consisting of the string "TRUE" or "FALSE". XNumeric strings will also evaluate to "FALSE" if they are equal to zero, Xand "TRUE" if they are non-zero. Arbitrary text strings will have the Xvalue of "FALSE". X@end(description) X X A list of the currently availible functions follows: (Once Xagain, send in those votes on what kind of functions you would like to Xsee added!) Functions are always used in lower case, the uppercase Xletters in the function table are the short form of the function (ie X&div for ÷). X X@begin(verbatim) XNumeric Functions: (returns ) X X&ADD Add two numbers X&SUB Subtract the second number from the first X&TIMes Multiply two numbers X&DIVide Divide the first number by the second X giving an integer result X&MOD Return the reminder of dividing the X first number by the second X&NEGate Multiply the arg by -1 X&LENgth Returns length of string X&SINdex Finds the position of within X . Returns zero if not found. X&ASCii Return the ascii code of the first X character in X&RND Returns a random integer between 1 and X&ABS Returns the absolute value of X&BANd Bitwise AND function X&BOR Bitwise OR function X&BXOr Bitwise XOR function X&BNOt Bitwise NOT function X XString manipulation functions: (returns ) X X&CAT Concatinate the two strings to form one X&LEFt return the leftmost characters X from X&RIGht return the rightmost characters X from X&MID X Starting from position in , X return characters. X&UPPer Uppercase X&LOWer lowercase X&CHR return a string with the character X represented by ascii code X>K return a string containing a single X keystroke from the user X&ENV If the operating system is capable, this X returns the environment string associated X with X&BIND return the function name bound to the X keystroke X&ENV Returns the operating system value X attached to environmental variable X&FINd Find the named file along the X path and return its full file specification X or an empty string if none exists X XLogical Testing functions: (returns ) X X&NOT Return the opposite logical value X&AND Returns TRUE if BOTH logical arguments X are TRUE X&OR Returns TRUE if either argument X is TRUE X&EQUal If and are numerically X equal, return TRUE X&LESs If is less than , return X TRUE. X&GREater If is greater than, or equal to X , return TRUE. X&SEQual If the two strings are the same, return X TRUE. X&SLEss If is less alphabetically than X , return TRUE. X&SGReater If is alphabetically greater than X or equal to , return TRUE. X&FINd Does the named file exist? X XSpecial Functions: X X&INDirect Evaluate as a variable. X@end(verbatim) X X This last function deserves more explanation. The &IND function Xevaluates its argument, takes the resulting string, and then uses it as Xa variable name. For example, given the following code sequence: X X@begin(verbatim) X ; set up reference table X X set %one "elephant" X set %two "giraffe" X set %three "donkey" X X set %index "two" X insert-string &ind %index X@end(verbatim) X X the string "giraffe" would have been inserted at the point in Xthe current buffer. This indirection can be safely nested up to about X10 levels. X X@section(Directives) X X Directives are commands which only operate within an executing Xmacro, ie they do not make sense as a single command. As such, they Xcannot be called up singly or bound to keystroke. Used within macros, Xthey control what lines are executed and in what order. X X Directives always start with the exclamation mark (!) character Xand must be the first thing placed on a line. Directives executed Xinteractively (via the execute-command-line command) will be ignored. X X@subsection(!ENDM Directive) X X This directive is used to terminate a macro being stored. For Xexample, if a file is being executed contains the text: X X@begin(verbatim) X ; Read in a file in view mode, and make the window red X X 26 store-macro X find-file @@"File to view: " X add-mode "view" X add-mode "red" X !endm X X write-message "[Consult macro has been loaded]" X@end(verbatim) X X only the lines between the store-macro command and the !ENDM Xdirective are stored in macro 26. Both numbered macroes and named Xprocedures (via the @i(store-procedure) command) should be terminated with Xthis directive. X X@subsection(!FORCE Directive) X X When MicroEMACS executes a macro, if any command fails, the Xmacro is terminated at that point. If a line is preceeded by a !FORCE Xdirective, execution continues weather the command succeeds or not. For Xexample: X X@begin(verbatim) X ; Merge the top two windows X X save-window ;remember what window we are at X 1 next-window ;go to the top window X delete-window ;merge it with the second window X !force restore-window ;This will continue regardless X add-mode "red" X@end(verbatim) X X@subsection(!IF, !ELSE, and !ENDIF Directives) X X This directive allows statements only to be executed if a Xcondition specified in the directive is met. Every line following the X!IF directive, until the first !ELSE or !ENDIF directive, is only Xexecuted if the expression following the !IF directive evaluates to a XTRUE value. For example, the following macro segment creates the Xportion of a text file automatically. (yes believe me, this will be Xeasier to understand then that last explanation....) X X@begin(verbatim) X !if &sequal %curplace "timespace vortex" X insert-string "First, rematerialize~n" X !endif X !if &sequal %planet "earth" ;If we have landed on earth... X !if &sequal %time "late 20th century" ;and we are then X write-message "Contact U.N.I.T." X !else X insert-string "Investigate the situation....~n" X insert-string "(SAY 'stay here Sara')~n" X !endif X !else X set %conditions @@"Atmosphere conditions outside? " X !if &sequal %conditions "safe" X insert-string &cat "Go outside......" "~n" X insert-string "lock the door~n" X !else X insert-string "Dematerialize..try somewhen else" X newline X !endif X !endif X@end(verbatim) X X@subsection(!GOTO Directive) X X Flow can be controlled within a MicroEMACS macro using the !GOTO Xdirective. It takes as an argument a label. A label consists of a line Xstarting with an asterisk (*) and then an alphanumeric label. Only Xlabels in the currently executing macro can be jumped to, and trying to Xjump to a non-existing label terminates execution of a macro. For Xexample.. X X@begin(verbatim) X ;Create a block of DATA statements for a BASIC program X X insert-string "1000 DATA " X set %linenum 1000 X X *nxtin X update-screen ;make sure we see the changes X set %data @@"Next number: " X !if &equal %data 0 X !goto finish X !endif X X !if &greater $curcol 60 X 2 delete-previous-character X newline X set %linenum &add %linenum 10 X insert-string &cat %linenum " DATA " X !endif X X insert-string &cat %data ", " X !goto nxtin X X *finish X X 2 delete-previous-character X newline X@end(verbatim) X X@subsection(!WHILE and !ENDWHILE Directives) X X This directive allows you to set up repetitive tasks easily and Xefficiently. If a group of statements need to be executed while a Xcertain condition is true, enclose them with a while loop. For example, X X@begin(verbatim) X !while &less $curcol 70 X insert-string &cat &cat "[" #stuff "]" X !endwhile X@end(verbatim) X X places items from buffer "item" in the current line until the Xcursor is at or past column 70. While loops may be nested and can Xcontain and be the targets of !GOTOs with no ill effects. Using a while Xloop to enclose a repeated task will run much faster than the Xcorresponding construct using !IFs. X X@subsection(!BREAK Directive) X X This directive allows the user to abort out of the currently Xmost inner while loop, regardless of the condition. It is often used Xto abort processing for error conditions. For example: X X@begin(verbatim) X; Read in files and substitute "begining" with "beginning" X X set %filename #list X !while ¬ &seq %filename "" X!force find-file %filename X !if &seq $status FALSE X write-message "[File read error]" X !break X !endif X beginning-of-file X replace-string "begining" "beginning" X save-file X set %filename #list X !endwhile X@end(verbatim) X X This while loop will process files until the list is exhausted Xor there is an error while reading a file. X X@subsection(!RETURN Directive) X X The !RETURN Directive causes the current macro to exit, either Xreturning to the caller (if any) or to interactive mode. For example: X X@begin(verbatim) X ; Check the monitor type and set %mtyp X X !if &sres "CGA" X set %mtyp 1 X !return X !else X set %mtyp 2 X !endif X X insert-string "You are on a MONOCHROME machine!~n" X@end(verbatim) X@appendix(MicroEMACS Command Line Switches and Startup Files) X X@index(startup files) X When EMACS first executes, it always searches for a file, Xcalled @b(.emacsrc) @i(under most UNIX systems) or @b(emacs.rc) @i(on Xmost other systems) @index(emacs.rc) @index(.emacsrc) which it will Xexecute as EMACS macros before it reads in the named source files. This Xfile normally contains EMACS macroes to bind the function keys to Xuseful functions and load various usefull macros. The contents of this Xfile will probably vary from system to system and can be modified by the Xuser as desired. X X When searching for this file, EMACS looks for it in this order. XFirst, it attempts to find a definition for "@b(HOME)" in the Xenvironment. It will look in that directory first. Therwuffersmacro)