Programming the HP49G editor with SystemRPL =========================================== by Carsten Dominik The HP49G ROM contains a number of supported entry points which can beused to manipulate the editor from SysRPL programs. You can find outwhere the cursor is, move around, insert and delete text, and searchfor strings.CONTENTS======== 1. Introduction 2. Terminology 3. Examples 4. Executing commands from within the editor 5. Reference 5.1 Status 5.2 Inserting Text 5.3 Deleting Text 5.4 Moving the Cursor 5.5 Selection, Cut and Paste 5.6 Search and Replace 5.7 Evaluation 5.8 Miscellaneous 6. Acknowledgement1. INTRODUCTION===============The HP49G has a builtin editor which is much faster and nicer than theeditor on the HP48. However, it is a general-purpose editor, and itwould be useful for specific applications to add some features withouthaving to write a whole new editor.The HP49G ROM contains a number of supported entry points which can beused to manipulate the editor from programs. Of course, theseprograms will not be overly fast since they are written in System RPLand not in Assembler like the builtin editor commands. But speed issufficient for simple tasks like inserting a template.I don't know about any documentation on these entry points, but onecan guess some of them by looking at names containing "CMD" (probablyfor "command line") or "CURS" for cursor. Other possible entry pointscan be selected by proximity in ROM address to known editor commands.This document summarizes information I have collected by trial anderror. Please send corrections and further discoveries to me: CarstenDominik .2. TERMINOLOGY============== EditLine The string which is currently being edited. Also called "Buffer" and "Command line". In the stack diagrams I will use $buf for it. Cursor position The position of the cursor in the Editline. A BINT. In stack diagrams written as #cpos. Current line The current line in the editor, i.e. the substring after the NEWLINE before the cursor up to the next NEWLINE character. Editor window When the text being edited is long and/or wide, the screen of the HP49G shows only a part of the text, the window. When the cursor is moved, the window must be re-positioned to show the new position. Selection A region in the buffer can be selected when the begin marker and the end marker are active. The selected substring is called $sel in the stack diagrams. Word-start The beginning of a word, a position in a string where the char before is SPACE or NEWLINE, and the char after is a non-white character. Several commands deal with word-start positions, called #ws in the stack diagrams below. Invisible chars The HP49G can show text in different fonts and styles. In order to switch between fonts and styles, special markers are inserted into the text to indicates a change in font or style. These 3-character sequences are not visible, but they count in string length and in cursor position. Some Editor commands are aware of these strings and do complicated computations to cut and paste text with attributes. This of course makes these commands less fast than they could be. If you don't use fonts and styles, you need not to worry about all this.3. EXAMPLES=========== All examples are SystemRPL routines. In principle, you could also use SYSEVAL and do stuff from UserRPL. a) Select the current line and copy it onto the clipboard. :: TakeOver CMD_END_LINE (goto end of line) RCL_CMD_POS (recall position) CMD_STO_FIN (store as marker) CMD_DEB_LINE (beginning of line) RCL_CMD_POS (recall position) CMD_STO_DEBUT (store as marker) CMD_COPY (copy to clipboard) ; This can actually be done shorter by using the builtin SELECT.LINE command. The following is equivalent to the above. :: TakeOver SELECT.LINE CMD_COPY ; b) Insert a ':: ;' template on a single line and position the cursor between '::' and ';'. :: TakeOver ":: ;" CMD_PLUS CMD_BAK CMD_BAK ; c) Insert a multi-line ':: ;' template and position the cursor with extra indentation on the second line. :: TakeOver "::\0A\0A;" CMD_PLUS CMD_UP SPACE$ (Fix indentation to two extra spaces) CMD_PLUS ; d) Go to next label. Labels are lines starting with '*'. :: TakeOver "\0A*" (Newline followed by star) FindStrInCmd (Find, starting from cursor pos) IT :: (If successful) DROP (drop #end) #1+ (add #1 to #start to move over NL) STO_CURS_POS (set new cursor position) ; DROP (drop the search string) ; e) My RPLCPL program does completion of names in the Editor. It needs to find the word fragment before the cursor. Here is how this can be done: :: RCL_CMD (recall EditLine) RCL_CMD_POS (current position) DUP (arg needed by GET.WSkip (jump to next word) RCL_CMD_POS # $buf )EDITLINE$ 2EEEB Same as RCL_CMD (HP48 compatibility). ( -> $buf )RCL_CMD2 2F197 Similar to RCL_CMD, but if there is not enough memory to copy the EditLine to the stack, it will move the current EditLine into TEMPOB. Of course, this will delete the current EditLine. RCL_CMD_POS 2EF87 RCL the cursor position. ( -> #cpos )CURSOR@ 2EF87 Same as RCL_CMD_POS (HP48 compatibility). ( -> #cpos )CAL_CURS_POS 2EF91 Compute a position in the current EditLine from line and column number. The result can be used by STO_CURS_POS to move the cursor to that location. ( #line #col -> #pos )CAL_CURS_POS_VIS 2EF90 Similar to CAL_CURS_POS, but will ignore invisible characters. The result can be used by STO_CURS_POS_VIS to move the cursor to that location. ( #line #col -> #pos )RCL_CMD_MODE 2F199 RCL a string with current editor settings. Can be used together with STO_CMD_MODE to save and restore the state of the EditLine, when temporarily leaving the editor with HALT or when calling a program which must temporarily change settings. ( -> $mode )STO_CMD_MODE 2F198 STO a mode string similar to the one obtained by RCL_CMD_MODE. ( $mode -> )5.2 Inserting Text------------------CMD_PLUS 2EF74 Insert string at current cursor position in EditLine. ( $ins -> )CMD_PLUS2 2F194 Replace entire current EditLine with new string. When there is not enough memory to copy the string on stack level 1, moves the string out of TEMPOB. You must be careful that the string is not referenced in any way. The cursor is moved to the end of the new string. ( $new -> )CMD_PLUS3 2F195 Same as CMD_PLUS2, but the cursor position is not changed. Useful when restoring a command line context after HALT. ( $new -> )InsertEcho 2EF97 Same as CMD_PLUS (HP48 compatibility). ( $ins -> )Echo$NoChr00 2F11C Same as CMD_PLUS (HP48 compatibility). ( $ins -> )TOGGLE_I/R 2577F Toggle between Insert and Replace mode. This entry is not in SUPROM.a, but it is supported anyway and you can confidently call it with its address (says JYA).5.3 Deleting Text-----------------CMD_DEL 2EF82 Delete next char in Editor. Same as LS+DEL. If you hold down BS while this entry is executed, the HP49G will think you have pressed the key and want to repeat it. ( -> )CMD_DROP 2EF81 Backspace in Editor. Deletes char before cursor. Same as BS key. If you hold down BS while this entry is executed, the HP49G will think you have pressed the key and want to repeat it. ( -> )DEL_CMD 2EF95 Clear the entire EDITLINE. ( -> )DODel 2F2F1 Delete right to beginning of next word, Same as the DEL-> button in the editor TOOL menu. ( -> )DODEL.L 2F2F9 Delete all chars in the current line. If the line is already empty, delete the NEWLINE. Same as the 'DEL L' button in the editor TOOL menu. ( -> )DoFarBS 2F2DD Delete to beginning of line. Same as the RS+' $sel )PASTE.EXT 2EF94 Paste from Stack with treatment of fonts and styles. Inserts the string on stack level at the cursor position. It can insert normal text right in the middle of bold test etc. If you don't use styles or different fonts, CMD_PLUS is probably faster, but I have not verified this. ( $ins -> )SELECT.LINE 2F2E1 Select current line, position cursor at beginning of line. Selection does not include the NEWLINE char at the end of the line. ( -> )SELECT.LINEEND 2F2E2 Select current line, position cursor at end of line. Selection does not include the NEWLINE char at the end of the line. ( -> )5.7 Search and Replace----------------------FindStrInCmd 2F2F2 Find a string in the EditLine, starting from the current cursor position. The search string remains on the stack, presumably in order to do repeated searches. Returns the start and end positions of the match and a flag. This function respects the setting of the internal flag for case-sensitive search. ( $find -> $find $start $end TRUE ) ( $find -> $find FALSE )GET.W-> 2F2F3 Return the position of the next word-start to the right of the current cursor position. Note the asymmetry of this command and the next. ( -> #ws )GET.W #ws )DOFIND 2F2E8 Same as the FIND menu button in the editor TOOL/SEARCH menu. Pops up the FIND input form. ( -> )DONEXT 2F2EA Find next. Same as the NEXT button in the editor TOOL/SEARCH menu. ( -> )DOREPL 2F2E9 Same as the REP button in the editor TOOL/SEARCH menu. Pops up the REPLACE input form. ( -> )DOREPLACE 2F2EB Replace current match. Same as the R button in the editor TOOL/SEARCH menu. ( -> )DOREPLACE/NEXT 2F2EC Replace current match and move to next match. Same as the R/N button in the editor TOOL/SEARCH menu. ( -> )REPLACEALL 2F2ED Replace all matches in buffer. Same as the ALL button in the editor TOOL/SEARCH menu. ( -> )REPLACEALLNOSCREEN 2F2FC Like REPLACEALL, but does not update the screen. Much faster this way. ( -> )5.7 Evaluation--------------EditSelect 2F2DF Edit the current selection. Opens the editor with the selection only. You can then edit the selection. After pressing ENTER the edited text is inserted back into the previous editing environment. ( -> )EVAL.LINE 2F2E3 Evaluate the current line and replace it with the result of the evaluation. Similar to EVAL.SELECTION, but without the need to select the line first. ( ? -> ? )EVAL.SELECTION 2F2FB Evaluate the current selection and replace it with the result of the evaluation. Same as the EXEC button in the editor TOOL menu. ( ? -> ? )EXEC_CMD 2F2F8 Run a command on the selection in the Editline. Takes two arguments: the command to run and a flag which says how to compile the selection before the command is applied. If the flag is TRUE, and ALG mode in on, the ALG compiler is used and the DOTAG :: xEVAL prologue of the result is removed. Use this if the result is to be edited by another editor. The selection is left on stack level 1 as an object. ( cmd T/F -> obsel )5.8 Miscellaneous-----------------?Space/Go> 2EF73 Insert a SPACE character unless there is already one before the cursor position. Use this if you want to make sure the next stuff echoed is separated by at least one space from the word preceding it. ( -> ).AddLeadingSpace 2EF76 Add a leading space to the string on level1 if it does not start with a space *and* if the cursor in the editor is after a non-white character. So :: "DUP" AddLeadingSpace AddTrailingSpace CMD_PLUS ; inserts "DUP" and makes sure it will be surrounded by spaces. ( $ -> $' )AddTrailingSpace 2EF75 Add a trailing space to the string on level1 unless the string already ends with a space. ( $ -> $' )CMDSIZE 26855 ML entry point to get the size of the EditLine. As ML entries cannot be called directly from SysRPL, don't use it unless you know the necessary magic. :: RCL_CMD LEN$ ; works for us assembler dummies ;-)CommandLineHeight 2EF9A Returns the number pixel rows occupied by visible part of the EditLine. ( -> #height )DOTEXTINFO 2F2DB Display the info screen about the Editline. Same as the INFO button in the editor TOOL menu.GET_CUR_FONT.EXT 2F2F6 Return the ID (as a system binary) of the font used for the character under the cursor. ( -> #font )NO_AFFCMD 2EF96 Tells the next CMD_PLUS call not to update the display. For speed, if you want to do more insertion before the user needs to see it. ( -> )DispCommandLine 2F19E Redisplay the command line. ( -> )?DispCommandLine 2F19F Redisplay the command line if necessary. ( -> )PUT_STYLE 2F2F7 Changes the style at point. If the selection is active, changes the style of the text in the selection. Otherwise changes the style of text typed subsequently. Takes a BINT from the stack which is the number of the style. In think the ITALI button in the editor TOOL/STYLE menu could be implemented with the following program: :: BINT2 PUT_STYLE ; ( #style -> ) PUT_FONTE 2F2F5 Change the font at point. Works similar to the PUT_STYLE command, but I could not test it because I don't have multiple fonts installed. ( #font -> )SELECT.FONT 2F2E7 Pops up the CHOOSE box to select a font. Same as the FONT button in the editor TOOL/STYLE menu. ( -> )ViewEditGrob 2F2E0 View the grob currently edited in the Editline near the cursor. If the EditLine contains GROB 10 10 FFFFFFFFFFFFFFFFF move the cursor to the "1" of the first "10". Then this entry point will display the grob. ( -> )XLINE_SIZE 2EF92 Check if the cursor outside the current line. In the HP49G editor, you can move the cursor further to the right than the line length, without actually making the line longer. The line gets extended only if you actually insert text or use CMD_DEL to catch to following line to the position. This entry returns TRUE if it is not on or before the newline. Note that it takes an arbitrary object from the stack first - so put something there before calling it. ( ob -> TRUE ) ; outside line ( ob -> FALSE ) ; in line6. ACKNOWLEDGEMENT==================Jean-Yves Avenard was kind enough to fill in the holes in the firstversion of this document.