Shareware Grab Bag

home *** CD-ROM | disk | FTP | other *** search

/ Shareware Grab Bag / Shareware Grab Bag.iso / 007 / rascal.arc / RED.DOC < prev next >

Wrap

Text File | 1980-01-01 | 24.9 KB | 901 lines

November 1983 This document tells how to use the Rascal text editor program, RED.EXE, so that you can enter and maintain your Rascal programs. This manual assumes you are familiar with MS DOS and Microsoft BASIC. RASCAL EDITOR USER'S MANUAL RASCAL EDITOR USER'S MANUAL Manual version: 1.05 Software version: 1.05 Marty Franz 525 W. Walnut St., Kalamazoo, MI 49007 (616) 344-1821 (C) Copyright 1983 Marty Franz - All rights reserved 111483105 Rascal Editor User's Manual INTRODUCTION INTRODUCTION RED.EXE is a text editor specially designed for the entry and editing of Rascal programs. Briefly, RED lets you easily enter and modify your Rascal programs without resorting to EDLIN. RED is screen-oriented, so you can edit 24 lines of text at once, and uses the IBM PC's special keys for many of its editing functions. Right now, RED is an in-memory editor. This means that files must be transferred to and from a buffer in memory for editing. Only files small enough to fit entirely in memory (up to 60KB maximum) can be edited using RED. In actual use, RED works a lot like BASIC does: you LOAD programs into RED's memory buffer, edit them, then SAVE them back to diskette when you're done. After a program has been stored on diskette, it can be translated by the Rascal BASIC preprocessor into a BASIC program. Please take the time to read these instructions before you use RED. The best way to learn RED is to practice editing a file, trying out each command, editing function, or special key until you feel comfortable with it. RED's SAVE and RESAVE commands make it unlikely that you will destroy valuable data. PROGRAM REQUIREMENTS PROGRAM REQUIREMENTS To edit files using RED, you need an IBM PC or XT with: - at least 64KB of memory, (if you have this much memory your file size will be limited to about 15KB) - at least one single-sided diskette drive, - a color or monochrome adapter, with a monitor capable of displaying 80-character lines, - MS DOS version 1.1 or 2.0, and - the file RED.EXE. BUGS AND IDEAS BUGS AND IDEAS When you are using RED, please remember that this is only version 1.05. If you find bugs, or you have ideas for improving this editor, please contact me: Marty Franz 525 W. Walnut St. Kalamazoo, MI 49007 (616) 344-1821 Page 2 111483105 Rascal Editor User's Manual BASIC MODES BASIC MODES When you are editing with RED, the editor is always in one of three modes, called edit, insert, and command. Each mode is adapted to a particular set of editing tasks. Insert mode is used when a lot of text is being added to the file. Edit mode is used for touring the file and making minor changes to many lines. Command mode is used with longer, BASIC-like commands that affect the overall structure of the file and possibly even delete parts of it. RED uses the 25th line of your screen as a status line to display the current mode, and other important facts such as the name of the file being edited. The status line is always displayed in reverse video, and tells: - the mode (command, edit, or insert), - the name of the file being edited, - the line in the file the cursor is on, - the column on the screen the cursor is on. The remainder of the screen, lines 1-24, is called the "edit area" in this manual and is used to display the actual text lines of the file you are working on. CAUTION: in this version of RED, only the first 80 characters of a line can be displayed and edited. Furthermore, attempting to load lines longer than 132 characters can result in lost data. To start RED from MS DOS, enter: A>red and you will receive the messages: Rascal Program Editor version 1.05 (C) Copyright 1983 Marty Franz Press the "enter" key at this point and RED will go on to clear the screen, display the status line at the bottom, and begin your editing session. Page 3 111483105 Rascal Editor User's Manual COMMAND MODE COMMAND MODE RED begins the edit session in command mode. At this point the memory buffer is empty. You must use the LOAD command to load a file into memory for editing, or enter insert mode and input new text lines into the buffer. The LOAD command is described later in this section. Once editing is underway, you may freely switch between the three modes mentioned earlier. The functions available in each mode are described in one of the next three sections of this manual. The individual command mode commands are described below in this section. When you read their descriptions, remember that the squiggly braces { and } are placed around items which you must supply as "arguments" to a command. Also note that whenever a line number is mentioned, it refers to a line number in the file, not a BASIC line number generated by Rascal. APPEND APPEND The APPEND command has the format: APPEND {d:filename.ext} APPEND loads the file {d:filename.ext} into the buffer at the line just ahead of the current line. The name of the file being edited remains the same. CHANGE CHANGE CHANGE is used to search for a pattern in a range of text lines and replace it with another. The format of the CHANGE command is: CHANGE {start line} {end line} After this has been typed, RED prompts for the old pattern by asking "from:" . The old pattern is then entered. Just pressing the "enter" key cancels the command. After getting the old pattern RED prompts "to:" for the new pattern. When this is input the edit area clears and the changes made and their line numbers are displayed. If you press any key on the keyboard during this process the change is cancelled at that point. If {startline} and {endline} are specified, the change occurs only over that line range. If {endline} is omitted, the last line in the file is assumed. If both {startline} and {endline} are omitted, all the lines in the file are assumed. Page 4 111483105 Rascal Editor User's Manual Search Strings Search Strings In specifying a pattern to search for, two special characters may be used to make this process easier. The first, {^}, (the shifted-6 character on your keyboard) "anchors" the search to the start of the line in the file. That is, only characters beginning in column 1 will be checked for the pattern. The second special character, {?}, is used as a "wild card", a character that matches any at all in the text line. Change Strings Change Strings In specifying a new pattern for the CHANGE command, the {?} (wild card) character may be used to match a corresponding character in the old pattern. There must be as many {?}s in the change string as there are in the search string. DELETE DELETE The DELETE command is used to delete a range of lines in the buffer. It has the format: DELETE {start line} {end line} Here, {startline} and {endline} are used just as they are with the CHANGE command. No check is made to see if the buffer has been saved before the DELETE command is executed, so use this command with care. After DELETE completes, command mode resumes with the first line after those deleted shown at the top of the edit area. FIND FIND The FIND command searches for a string in the file. When the string is found, RED will enter edit mode and the line will be displayed at the top of the edit area with the next 23 lines in the file shown below it. The format of the FIND command is simply: FIND If the string is not found, RED remains in command mode. Page 5 111483105 Rascal Editor User's Manual G (GOTO) G (GOTO) The G command is used to go to a line in the file and enter edit mode. The line is displayed at the top of the edit area, with the next 23 lines in the file shown after it. G's format is: G {n} Typing G with no line number is the same as pressing F1, the edit mode key. HELP HELP The HELP command displays a one-page summary of RED's commands and function keys on the screen. LOAD LOAD LOAD will read a file from diskette into the memory buffer, overlaying whatever text was there before. If what you were editing wasn't saved, the "file not saved" message (see "NEW" below) is displayed. The LOAD command's format is: LOAD {d:filename.ext} The LOAD command also sets the filename on the status line for future SAVE and RESAVE commands. LLIST LLIST The LLIST command is used to list a range of lines in the file on your printer. Its format is: LLIST {start line} {end line} The printer currently used by MS DOS as LPT1: will receive the output. Both {startline} and {endline} work the way they do for the CHANGE command. NAME NAME NAME is used to set the name of the file for the SAVE and RESAVE commands. Normally, NAME isn`t used much because the name of the file being edited is set by the LOAD command. The format of NAME is: NAME {d:filename.ext} No disk access is done by NAME, only the filename displayed on the status line is changed. Page 6 111483105 Rascal Editor User's Manual NEW NEW NEW will clear the current buffer and the filename. Its format is simply: NEW A check is made to see if the buffer has been saved before proceeding. If not, the message: file not saved. proceed? is displayed. Answering {y} will cause RED to clear the buffer and the edit area; Typing {n} will abort the command. RESAVE RESAVE RESAVE will save the file currently being edited back to disk. It assumes the file already exists. The filename used It assumes the file already exists. will be the one displayed on the status line. The format of RESAVE is: RESAVE SAVE SAVE SAVE saves the file in the buffer back to disk. Unlike RESAVE, it assumes the file does not exist. If the file exists it assumes the file does not exist. a warning message is displayed and nothing happens. The format for SAVE is: SAVE Page 7 111483105 Rascal Editor User's Manual SEARCH SEARCH SEARCH will ask for a search string and will then display all the occurences of the string in the file. The format of the SEARCH command is simply: SEARCH SYSTEM SYSTEM The SYSTEM command is used to exit RED and go back to MS DOS, just like it is in Microsoft BASIC. TABS TABS The TABS command has the format: TABS {n} This command sets the column stops for the tab key to every {n} columns. Setting TABS less than or equal to 0 is the same as setting TABS to 1. When RED is started, 4 is the initial tab setting. Page 8 111483105 Rascal Editor User's Manual EDIT MODE EDIT MODE Edit mode is entered by pressing F1 at any time. Edit mode is used for changing individual text lines and for touring the file. In edit mode, you can't arbitrarily replace text. That can only be done in insert mode. Instead, to replace a single character at the current cursor position the X command (see below) is used. Another method for massive text replacement is to delete the characters you don't want, enter insert mode, reenter the new ones, and then resume edit mode. The majority of edit mode functions are activated by the PC's special keys. These are summarized in the "RED KEY MAP" section This section describes the edit mode functions not activated by special keys. EDIT: GOTO EDIT: GOTO Typing G when you are in edit mode will cause RED to ask for a line number. When this is supplied, this line is displayed at the top of the edit area and edit mode resumes. This function works the same as G does in command mode. EDIT: KILL EDIT: KILL Typing K in edit mode will cause RED to ask for a single character. After this is received, all the characters from the cursor right up to this character (or the end of the line if the character isn't found) will be deleted. EDIT: SEARCH EDIT: SEARCH Typing S when in edit mode will cause RED to ask for a single character. When this is entered, the cursor will move right to this character or the end of the line. EDIT: EXCHANGE EDIT: EXCHANGE Typing X in edit mode will cause RED to ask for a single character. This character will then replace the one under the cursor. Page 9 111483105 Rascal Editor User's Manual INSERT MODE INSERT MODE Insert mode is used for rapid entry of text. You can enter Insert mode at any time by pressing the Ins key on the PC. When this is done "insert" is displayed on the status line and the cursor fattens. Text can now be entered in the edit area at the line the cursor is on. The characters you enter will will be inserted to the left of the character the cursor was on when you started. In insert mode, only some of the special edit mode control keys retain their normal function. These are summarized in the "RED KEY MAP" section of the manual. More importantly, the ENTER key will continue insert mode on the line below the cursor, opening a new line in the edit area, and scrolling the lines below down a line. Insert mode is exited by pressing Ins again to enter edit mode, or F1 (edit) or F2 (command). Page 10 111483105 Rascal Editor User's Manual RED KEY MAP RED KEY MAP This section lists RED's special keys and what they do. KEY DESCRIPTION ___ ___________ F1 Enters edit mode. F2 Enters command mode. F3 In edit mode, moves cursor up one line and enters insert mode (insert up). F4 In edit mode, moves cursor down one line and enters insert mode (insert down). F5 In edit mode, splits the line at the cursor. F6 In edit mode, joins current line to end of line above it. All lines below the cursor move up one in the edit area. F7 In edit mode, deletes entire line cursor is on. All lines below move up one in edit area. F8 Deletes from cursor through the end of the current line. F10 Undoes any changes made in edit mode to current line. Home In edit mode, moves cursor to start of current line. End In edit mode, moves cursor to end of current line. Up In edit mode, moves cursor up one line. Used in Arrow insert mode, moves up a line and enters edit mode. Down In edit mode, moves cursor down one line. Used in Arrow insert mode, moves down a line and enters edit mode. Left In edit mode, moves cursor left one character. Arrow "Character" means a tab may move the cursor several columns. Also works in insert mode. Right In edit mode, moves cursor left one character. Also Arrow works in insert mode. PgUp In edit mode, starts scrolling the edit area forward through the file (towards the front). Pressing any key stops scrolling and resumes edit mode at the cursor. Page 11 111483105 Rascal Editor User's Manual KEY DESCRIPTION ___ ___________ PgDn Same as PgUp, but scrolls down through the file. Ins Insert mode toggle; enters insert mode, then enters edit mode if used in insert mode. Del Deletes character at cursor; line moves left one character, cursor stays at same place. Works in both insert and edit modes. <- (Backspace) Deletes character to left of cursor; cursor moves left one character. Works in both insert and edit modes. <-' (Enter) Has no effect in edit mode; in insert mode moves cursor down one line and continues text insertion. Space In edit mode only, acts the same as the Left Arrow Bar key, moving the cursor left one character. Page 12 111483105 Rascal Editor User's Manual ERROR MESSAGES ERROR MESSAGES Here's a list of the error messages RED will give you when you do something wrong. They will display on the status line after the incorrect command. To continue editing when an error occurs, press "enter" and the message will disappear. If you ever receive a message prefaced by the words "error:", "disk error:", or "system error:", SAVE your changes to a new file immediately and then abandon your editing session! One of these messages means RED has seriously malfunctioned. Report it after gathering as much information as you can. command not found This message means you tried to use a command that wasn't one of the ones listed earlier. pattern not found The search string you tried to find in the file isn't there. bad line number You used a line number in the GOTO command that isn't a positive number. Only the digits 0-9 can be used when you specify a line number. no file argument You tried to LOAD or APPEND a file without telling RED its name. file not found The file you tried to LOAD or APPEND from, or RESAVE to, does not exist on your diskette, or you misspelled its name. line truncated The result of a LOAD or CHANGE command was a line greater than 132 characters. The line was chopped off on the right. You cannot currently edit lines with more than 132 characters in them. Page 13 111483105 Rascal Editor User's Manual file not named You have tried to SAVE or RESAVE a file without giving RED a name to use for it. The NAME command will do this for you. file exists The file name you gave the SAVE command already exists on your diskette. You need the RESAVE command instead. bad argument You gave a command using two arguments, such as DELETE, one or more that were not numbers. file not saved. proceed? You will receive this message whenever you use the LOAD or NEW command and you have not saved what you were working on. This is because these commands clear the memory buffer. Answer {y} or {n} depending on what you want to do - {y} to continue and destroy the buffer, or {n} to back out and cancel the command. You don't need to press "enter" after typing {y} or {n}. new line too long The line created in a CHANGE command by substituting the new pattern for the old one is turned out to be greater than 132 characters long. The CHANGE command aborts at this point. too many ?'s in change mask You had more ?'s in your change string than you did in your search string. See the description of the CHANGE command in this manual for more information. error writing file You will receive this message when you try to SAVE or RESAVE your file and there isn't enough room on the drive you chose. Only part of the file has been saved. You must insert a fresh diskette and try to save the file again. Page 14 111483105 Rascal Editor User's Manual COPYRIGHT COPYRIGHT RED.EXE is based on ED2, a public-domain text editor written by Edward K. Ream and originally published in the January 1982 issue of Doctor Dobb's Journal. It has been substantially ______ ______ _______ changed to run on the IBM PC, including the addition of software support for the PC's display and keyboard hardware. The revised editor and manual are copyrighted materials and may be distributed only for private, noncommercial use. DISCLAIMER DISCLAIMER Although reasonable testing has been conducted, under no circumstances will the author be liable to you or any other third party for any damages, including lost profits or other incidental or consequential damages, arising out of the use of, or inability to use, this software. Page 15 111483105