Stars of Shareware: Programmierung

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

/ Stars of Shareware: Programmierung / SOURCE.mdf / programm / msdos / progtool / ae20a / ae.doc < prev next >

Wrap

Text File | 1993-11-11 | 28.3 KB | 610 lines

AE.COM: A .ASM file editor. This document describes the use of Asm Editor, ver. 2.0. AE is an editor intended for creation and maintainance of assembly language source files. It is not intended as a general purpose editor nor an editor for other types of source files. LEGAL STUFF: First, AE is not in the public domain. It is freeware, which means it can be distributed freely, used freely, but not sold. This is due to Ziff's copyrights on TED, the ancestor of AE. Although TED has been so heavily modified to become AE, I just don't feel right trying to circumvent Ziff's copyright. Second, the use of this software is entirely at the user's OWN RISK. It is not guaranteed to do anything except occupy 0 or more bytes of disk space. ANY un-desired effects caused by this program, directly or indirectly, are the responsiblity of the USER, and the USER's sole recourse is to dis-continue use of the program. As this program alters data files, normal data processing techniques dictate keeping reasonable back ups, as AE.COM or AECONFIG.COM are NOT guaranteed to hold your hardware, software, or data safe from harm. In-other-words, AE.COM and AECONFIG.COM *should* perform in a manner *similar* to that set forth in this document, but there are NO GUARANTEES! USE AT YOUR OWN RISK!!! WordStar and WS are trademarks of WordStar International. 80286+ ONLY!!! As with the 8080 vs. Z-80 question under CP/M, there comes a time when writing to the lowest common denominator no-longer makes sense. Especially when the '286 introduced many space/time saving instructions. So this program only works on a '286 or better. HOWEVER, 8088 based XT users aren't entirely left out in the cold. Replace that useless 8088 chip with a Nec V-20 (Nec V-30 if you have an 8086). For about $10, you will pick up the ability to run this program, and any other '286 only programs that don't require protected mode features (almost all 286 only programs fall into this cataogory). PLUS you will pick up a little speed. Instead of a Norton SI of 1.0, you'll have a SI of about 1.1 or 1.2 - every bit helps. Features: o 80286 coded for speed/compactness. o Very compact program. o Edit files up to 64K in length. o Uses TRUE TABS for ease of use, and compact file size. o Enter key is always a cursor motion key. o Intelegent TAB key. o Emulates most applicable WordStar commands. o Uses cursor keys for DOS weenies. o User configurable initial insert state. o User configurable backspace key - distructive or non-distructive. o Smart, column oriented cursor. o Intelegent use of EOF. o Automaticly inserts semi-colon at beginning of comment field if none there. o FORM7 filter. o Automaticly appends colons on labels. o Asm oriented auto-indent. o Automaticly strips trailing spaces/tabs. o Automaticly tabs from operand field to comment field. Introduction: AE.COM is an adaptation of Tom Kihlken's TED.COM. AE.COM is written by Mark D. Pickerill, a professional assembly language programmer. From the author: C and Pascal programmers have a wide array of specialized editors available to them to assist in the coding process. Assembly Language programmers have always had to make do with a general purpose text editor. It occured to me some time back, that much of the process of writing assembly language could be automated - thus the birth of AE. AE takes care of most of the mundane tasks of creating well-documented code. Keystrokes are minimized as AE anticipates what comes next, and does it for you. It can put colons on labels, make sure you go directly to the next appropiate field, insert the semicolon for you so you can immediately type your comment, and even take care of caps lock for you so you can write upper case code with lower case comments - by far the most readable, and most popular assembly language source formatting choice. AE closely follows the format and options of Irv Hoff's FORM7 assembly language source formatter program. I have used this program daily for many, many years. AE minimizes my need to use it. I searched endlessly for an existing editor to modify, as I did not want to re-invent the wheel. TED, by Tom Kihlken, fit the bill. It was small, source was included, source was reasonably well commented and structured, and most important, the source was in assembly. Please bear in mind, that while some attempt has been made towards user configurablity, this editor was created by me, for me, for my coding style. Naturally, I think my coding style is the best, but others may not agree. I comment every line, use colons after all labels (NOT allowed by MASM), etc. ******************************************************************************* If you like AE, and can use it, fine. If it is incompatable with your coding style, it is not for you. I developed my coding style over many years of writing assembly language for a living, and code this way for a reason. I like my assembly source files to be pleasing to the eye, and very well documented. Nobody's source code meets my documentation standards - including mine! AE is oriented towards a person who is used to, and prefers WordStar keystrokes. Some attempt has been made to accomodate "DOS Weenies" with F-keys, cursor arrow keys, etc., but the program remains heavily WordStar-ish. ******************************************************************************* FEATURES EXPLAINED: Auto-commenting feature: This is real time saver. If this configurable option is turned on, it automaticly inserts semi-colons as needed. It inserts them under two circumstances: 1) The TAB key is pressed, moving the cursor to the comment column specified in the program installation. (see configuration, below) At this time, a semi-colon is inserted, so the programmer can immediately type his comment. A space is automaticly placed after the semi-colon, if AE was installed to do so. AE does NOT insert a semi-colon if one already exists. This allows tabbing in full line comments without conflict. 2) The <CR> key is pressed on a line that 1) is shorter than the specified comment column, and 2) has no existing semi-colon. This is for two reasons: 1) Blank lines in source code (semi-colon present for consistancy) (and I don't like semicolons at the beginning of the line for a blank line) 2) The programmer isn't going to comment this line right now. The programmer may want to go back later to comment this line in which case the semi-colon is already there, or the line may stay un-commented (tsk-tsk!) but the semi-colon remains for consistancy and style. In all cases the semi-colon is inserted at the specified comment column. If the line is already longer than the specified comment column (long instructions, DB strings, etc.), no semi colon is placed. This feature is great for going back and re-formatting and adding comments to someone else's code. Load the code into AE, and hold down <CR> until the file as scrolled to the end. You now have a properly placed semicolon in all uncommented lines, vastly simplifying the commenting process. See QUIRKS, below. FORM7 Filter: If this configurable option is turned on, the code is automaticly generated as upper case labels and instructions, with capitalized lower case comments. The first non-space character is capitalized in the comment field, then the caps lock is removed so that the remaing portion of the comment is in lower case. The programmer may use the shift keys and/or re-engage the caps lock normally as needed. <CR> switches back to upper case. This is similar to the output of Irv Hoff's FORM7 program. (Highly recommended!) The feature that strips trailing spaces and tabs (detailed below), is, strictly speaking, part of the FORM7 filter. However, AE strips off trailers regardless of whether the FORM7 filter is selected or not. Weenies that program with lower case labels and instructions (YUK!), will want this feature turned off. See QUIRKS, below. AUTO-COLONS: AE has the ability to automaticly place a colon after all labels. Just type the label and press either TAB or CR, and the colon is automaticly generated. MASM users may not like this feature and want it turned off as MASM dis-allows colons on labels on EQU's, etc. Or MASM users can backspace out the colon when it isn't desired, OR press the space bar after typing the label as AE won't place a colon after the label in this circumstance. See QUIRKS, below. AUTO-INDENT: AE has a primitive auto-indent feature that is suitable for ASM programming. Like many other features, it is user configurable. When on, this feature remembers the state of the previous line, and applies it to the current line. If a label or full line comment was typed in the previous line, when <CR> is pressed, it will set the cursor at the start of the current line for another label or full line comment. If the previous line has no label or full line comment, the cursor will be placed at the first tab stop on the current line. You may then type an instruction or <BS> to insert a label or full line comment. TRAILING SPACES/TABS: AE automaticly strips any and all trailing spaces or trailing tabs when <CR> is pressed on a line. This happens regardless of the cursor position on the line. This means any new lines entered into a source file by AE will not have any trailing spaces/tabs. To remove these from existing source files created by editors other than AE, either use FORM7, or, starting at the top, hold down the <CR> key until the entire file has scrolled by. This feature minimizes file size and maximizes assembler throughput. FIND/FIND NEXT: Unlike WordStar, FIND always starts at the top of the file. I always *HATED* having to do ^QR before ^QF. FIND NEXT starts from the current location. After entering the search string, FIND asks if you want the search to be case sensitive. Any letter other than Y defaults to case insensitive. Search and Replace: This function also always starts at the top of the file. This is ALWAYS a global search and replace, the most-often-used. Search and Replace also doesn't waste your time by updating the display while doing its job - unlike WordStar which shows every single replacement done. TABs: AE uses TRUE TABs. This means 1) a single TAB replaces up to 8 spaces, and 2) TABs are the standard length of 8 characters. Non-standard tab stops, such as 4 or 10 are not supported. If insert status is on, a tab is inserted. If insert status is off, the cursor is moved to the next tab stop, over any characters that are there. Just functions as a cursor move key. If insert status is off, and the next tab stop is beyond the current end of line, a tab is appended to the end of the line. This is contrary to some editors I've used that either insert a tab regardless of insert status; or, with insert off, replace the current character with a tab. This way is far more useful, especially when writing assembly code which is TAB oriented anyway. AUTO-TABS: This configurable option simplifies operation for the programmer by automaticly tabbing from the operand field to the configured comment column. Thus: LABEL: MOV AL,0FFH ; Comment ... The operand field starts with the AL,0FFH. After typing the last of this, the TAB key is pressed and the cursor moves to the configured comment column, without stopping at intermediate tab stops along the way. The semi-colon is inserted, etc, if AE is configured this way. The <RETURN> key. This acts differently from any other editor I've ever used, and I like it this way. <RETURN> is always a cursor movement key, regardless of insert status. Only if the editor needs to append a new line on the end of the file does it actually do anything. This allows the <RETURN> key to be pressed halfway through a line, and just have it move to the beginning of the next line. If you need to insert a line in the middle of a file, or in the middle of a line, use ^N. Furthermore, <RETURN> can be configured to turn OFF insert, unless the LAME feature is turned on. The LAME feature makes AE as lame as any other editor. Newline is inserted if insert status is on. Needless to say, the neat feature of turning off insert on <CR> doesn't apply here. This feature was provided by popular request. <GRIN> See configuration, below. The <BACKSPACE> key. I hate distructive backspaces. Therefore, backspace is just another cursor movement key. I realize a lot of people do like distructive backspaces. Therefore it is user configurable to be this way. INITIAL INSERT STATUS. I think I'm the only person in the world who likes to fire up an editor with insert turned OFF. Every other editor in the world, except WS where it is configurable, comes up with insert ON. Some don't even allow you to turn insert off! Needless to say, AE comes up with insert OFF. As I'm probably the only person in the world who will like this, it is configurable. MOVING VERTICALY: A very nice feature of AE, which I've always wanted, is the way the cursor column is handled when moving verticaly. Let's say the cursor is positioned at the end of a fairly long line. The up-arrow or ^E is pressed. The cursor moves up to the next line. Let's say the next line up happens to be a short line. The cursor moves to the end of the short line. So far, this is no different from any other editor that does not place trailing blanks to fill in a line. Now let's say we move up again. This next line up is even longer than the first line we started from. In this case, the cursor will be positioned *in the same column it was to start with*! WS drove me nuts when moving verticaly in the comment field of an assembly language source file. AE is much nicer. I cannot claim credit for this, it was inheirited from TED. PROCESSOR TECHNOLOGY COMPATIBILITY: AE is compatable with the Processor Technology assembler's way of allowing a * in the first location of a line to mean a full line comment, without having to use a semi-colon. Now, I doubt that anyone is using this assembler anymore (or if they are, not on a MuSh-DOS machine.), but this quirk has crept into several subsequent products, including ASM for CP/M, and the FORM7 program. Even my assembler, the 2500 A.D. assembler allows this, although it carries it a bit farther. So a * in the first column is the same as a semi-colon, and the FORM7 filter will key off of it. Just in case some flakey future version of MASM uses a * as the first character in a label to mean something special, there is a config byte to turn this off. The bottom line: You probably don't care. Leave on unless you code with a * as the first character of a LABEL. EDITING BEYOND 80 COLUMNS: AE retains the capability inherited from TED of allowing editing beyond 80 columns. Any line longer than 80 columns will have a diamond placed in the rightmost column. Using ^LEFTARROW and ^RIGHTARROW will shift the display 8 characters at a time to be able to "reach" this longer text. ASM source is seldom wider than 80 chars anyway, but the capability is there, if needed. QUIRKS: Like any program that attempts to do your thinking for you, there are times where it isn't doing what you want it to. AE is no exception. A good deal of care has gone into the program, in an attempt to make it as un-obtrusive as possible. A balance between doing your thinking for you vs. getting in the way when you want to do something else has been struck. As mentioned before, AE assumes that you write your ASM source much like I do. It assumes that you use the TAB key to move to the next field. It assumes you press <CR> when finished typing in a new line. Most of the automatic features are keyed off of either the TAB key or <CR>, or both. Here are some of the quirks you may encounter... FORM7 filter: If there is a semi-colon inserted in a quoted string, caps lock will want to fight you. Pressing the semicolon will turn on caps lock. Then 1 or 2 characters later, it will come off. The editor will also insert the "space after semicolon" if configured this way. You'll have to go back and delete this space manualy. This is due to AE making the assumption that a semi-colon means a comment. It doesn't know about quoted strings. As semicolons aren't used too often in quoted strings, it isn't felt worth the code space to work around this problem. Code to detect all possible permutations of quoted strings with single quotes, double quotes, reverse quotes, and things like '' to actually insert the quote character into the literal string, would be big, clunky, and ugly... Personally, I can't remember the last time I had a semi-colon in a quoted string anyway. A work-around is to DB 3BH or just toggle the caps lock as needed. Auto commenting: Similar to the FORM7 quirk, if there is a semi-colon in a quoted string, the auto comment feature won't work. You will have to insert the semi-colon manualy, and handle the formatting of the comment manualy. AUTO-COLONS: Does not automaticly place a colon after the label if any key besides <CR> or TAB is pressed when typing the label. This has been left this way in order to accomodate MASM users who cannot have colons after some labels. MASM users are advised to press <SPACE> after a un-coloned label, or use one of the control keys. (or turn this feature off). EDITING MARKED TEXT: Not allowed. If you have a block defined, you cannot edit inside it as long as it is visably marked. Use ^KH to hide the block, edit it, then ^KH to un-hide it again. Search & Replace, since it is global, will not function if there is a defined block visable *anywhere* in the file. In a similar vein, block load from file is non-functional while the cursor is inside a marked block. Turn off, then load, or move outside the marked area. FIND, SEARCH & REPLACE: If using these functions, espcially search & replace with a large file where there will be a lot of replacements, IF POSSIBLE, use the case sensitive feature instead of the default case insensitive. The exact match routine for the case sensitive routine is MUCH faster than the "mask and compensate" that must be performed for the case insensitive search. So you may have a situation where you know the case is the same, or it's numeric data, or whatever, then you can use the case sensitive search with the same result. ALL QUIRKS: Yes, it *is* possible to "fix" most of these. However, doing so would result in the editor becoming too rigid to be able to work around the automatic features, when desired. It is felt that the balance is best served this way. It goes without saying, that the way *I* code, minimizes my encountering these quirks. WORDSTAR KEYS: There are 4 catagories of WordStar emlation: Catagory 1: Absolutely, positively, *MUST* act just like WordStar. Item 2, below, and most other implemented commands fit this description. Catagory 2: Needs to be close, but need not be exact. Items 1 & 4, below, fit this description. Catagory 3: Needs to be close, but needs some kind of improvement. Items 3 (in the default configuration), and 6, fit this description. Catagory 4: Not implemented. Either non-applicable, or too complicated for the amount of times the function is required. ^KN, enter column mode, comes to mind. Nice feature when you need it, but you seldom do. Most WordStar keys are catagory 1 implementations. A few exceptions: 1) Word Left and Word Right (^A and ^F). Merely move to the previous/next tab stop. Felt to be good enough for programming. 2) To the best of my knowledge, AE handles tabs just like WS. 3) <CR> acts just like WS if AE has been configured this way. The default configuration does not. See above. 4) ^KS and ^KX. Save and resume/save and exit. Invoke just like WS, but have the added question about file name. This allows AE to be invoked without a filename or utilized in a SAVE AS: mode. 5) As stated above, an initial FIND always starts at the top of the file. Find next is just like WS. FIND only asks about case sensitivity, does not have the other WS options. 6) Depending on what version of WS you may have been using, the handling of the cursor when moving verticaly over a tab: LAB_L: MOV AH,09H ; Comment JMP SHORT SOMEWHERE ; Exit ...asuming the _ in the above label is the location of the cursor, WS 4.0, when the cursor was moved DOWN (^X), would move the cursor to the beginning of the JMP instruction, unlike WS 3.3, which would move the cursor to the beginning of the line (beginning of the TAB). The 4.0 way drove the author nuts! AE does it the 3.3 way. In fact, the 4.0 way was the beginning of the reason for AE! 7) Block marking is a catagory two implementation. Unlike WS, it doesn't matter if you use ^KB, then move up to do a ^KK. With AE, always start a block with ^KB, then move to the end, even if it is a backwards move, then define the end with ^KK. AE will swap them internaly for you. (Rather than printing a stupid error message.) ^KK *cannot* be used first. (Nothing happens) AE keystrokes: The following is a chart of all keystrokes AE accepts. It should be noted that some commands are only present in the WordStar column. It is next to impossible to use weenie keys for everything without resorting to a menu. Most commands missing from the weenie column won't be missed by non-WordStar users anyway. (I hope). Some weenie keys may not make much sense and be hard to remember, esp. the ^F keys. Tried to make the ^F keys as intuitive as possible. Most other weenie keys should be fairly intuitive. Remember, the program *is* oriented towards folks used to WordStar (for better or worse). WordStar key DOS weenie key Action --------------------------------------------------------------------------- ^KQ F1 Abort edit ^KX F2 Save & exit ^KS ^F2 Save and resume editing ^KB F3 Begin block ^KR ^F3 Read block from disk file ^KK F4 End block ^KH ^F4 Hide/unhide block (toggle) ^KC F5 Copy block ^KW ^F5 Write block to disk file ^KV F6 Move block ^KY ^F6 Delete block ^QF F7 Find ^L ^F7 Find next ^QA F8 Search & Replace ^QI ^F8 Jump to specified line # ^QY F9 Delete to EOL ^Y F10 Delete line ^U ^F10 Undelete line ^QB F11 * Jump to start of block ^QK F12 * Jump to end of block ^QR ^PGUP Top of file ^QC ^PGDWN End of file ^R PGUP Go up one screen ^C PGDWN Go down one screen ^QS HOME Go to beginning of line ^QD END Go to end of line ^E UPARROW Go up one line ^X DOWNARROW Go down one line ^S LEFTARROW Go left one char ^D RIGHTARROW Go right one char ^W ^UPARROW * Scroll up one line ^Z ^DNARROW * Scroll down one line ^A SHIFT-TAB Move to previous tab stop ^QE ^HOME Go to upper right of screen ^QX ^END Go to lower left of screen ^F or <TAB> TAB Move to next tab stop ^V INS Toggle insert state ^G DEL Delete character under cursor ^N ^ENTER Insert line ^K0 - ^K9 Place marker 0 - 9. ^Q0 - ^Q9 Jump to marker 0 - 9 ^T Delete word right ^RIGHTARROW Shift display right 8 chars ^LEFTARROW Shift display left 8 chars * Extended keyboard only. USER CONFIGURABLE ITEMS: You can use the supplied program AECONFIG.COM to configure AE.COM. This is a simple get-the-job-done program. AECONFIG prompts include the recommended settings, following these will result in an "out of the box" copy of AE.COM. Or following items can be patched in the .COM file with DEBUG. All values are hex unless noted. OFFSET Default Meaning 0103 00 Inital insert status, 00=insert off, FF=insert on 0104 FF FF=non-distructive backspace, 00=distructive backspace. 0105 FF FF=Handle EOF properly. Append a single EOF when saving, stop at the first EOF when loading. 00=Do MS-DOS style EOF handling. Ignore when loading, do not append when saving. 0106 FF FF=Do backup files, 00=don't do backup files 0107 FF FF=Auto comment feature. Insert semicolons. 00=Auto comment off. 0108 FF FF=Space after auto comment semi-colon 00=No space. 0109 FF FF=FORM7 filter on. 00 = FORM7 filter off 010A FF FF for auto colons, 00 for no auto-colons. 010B FF FF for auto-tab to comment column 010C FF FF for auto indent, 00 for no auto indent 010D 00 FF to allow <CR> to generate new line with insert on. 00 for <CR> to be cursor motion only 010E FF FF for Processor Technology compatiblity. Most users will leave this on. 010F FF FF to allow <CR> to turn OFF insert. Meaningless if LAME is turned on. (010D=FF) 0110 0A Color for color users. Green = 02, intense green = 0A If this byte is 00, AE will use the existing attribute. This is for folks that like to set default colors from DOS with one of the many programs available to do this. 0111 20 (32 Decimal) Column comments start in for auto-comment If this byte is not a multiple of 8, AE sets this to the next lowest multiple of 8. 0112 ; (ASCII Value) Comment delimiter. Normally a semi-colon Change to meet your needs. 0113 2E DO NOT CHANGE!! (Dot for file extension) 0114-0116 BAC (ASCII values) Backup file extension. 0117 00 DO NOT CHANGE!! (Termination for file extension) FUTURE VERSIONS: A future version of AE will probably be able to at least be able to edit files as large as available memory, as opposed to the current 64K limit. The current 64K limit hasn't been too much of a limitation to me, but it would be nice to be able to edit larger files. Rest assured, that an AE capable of larger files *will* require a '386 or better. "I don't do segments." Rumor has it that MS-DOS 7 will have 32 bit extensions. If this is true, I'll be using them... Virtualizing. This is the ability to buffer to disk all but the immediate portion of the file you're editing. Would be nice, but probably won't happen. The program is too hard structured for that to be an easy task. Doubtless, as I and others use the program, other enhancements will be needed. Look for new releases from time-to-time. I use this program daily, and continue to find things that aren't quite right and pop over and tweek the program a little more. THINGS YOU WON'T SEE: There are several things you won't see, either because I don't do them, or the necessary coding is beyond the scope of the project. Mouse support: Mice are great for CAD programs, draw/paint programs, etc. They don't belong in text editors, nor do they belong in operating systems... Color support: There is rudimentary color support already built into the program. I am willing to listen to suggestions on how to "improve" this. However, as I am a color refusenik, I'm not going to go overboard on this. Color monitors HURT my eyes... Tab stops other than 8: Sorry folks, tab stops are 8 characters each, always have been. I have had it suggested to me that the label field be longer, say 10 characters. First, the 8 character tab stop thing is hard coded into the program, inheirited from TED (as it should be). Second, it is a religious issue to me, I don't believe in long labels (or non-standard TAB stops). Long labels can always be placed on their own line, AE makes this very easy to do. Third, as stated at the top of the documentation, AE assumes the user codes in a similar manner to the guy who wrote it. <GRIN> And fourth, TRUE tabs are 8 characters. MS-DOS is the only OS I've encountered that doesn't rigidly enforce this. KUDOS: A number of folks helped test AE and pestered me with bug reports and "Requests". The person most responsible for a good BETA cycle was Larry Alm. Clarence Dyson, Bob Shepard, and Robert Cabral were also very helpful. SUPPORT: The "home" BBS for AE.COM is the Hacker Heaven BBS at (408) 375-5455. We currently support baud rates from 300 to 14.4K+v.42bis. In this day of media hype, it is necessary to point out that the word "Hacker" means computer programmer, NOT computer crimminal. We do not tolerate illegal activities of any kind.