Club Amiga de Montreal

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

/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 579a.lha / Textra_v1.11 / Docs / RexxCommand.doc.pp / RexxCommand.doc

Wrap

Text File | 1991-12-06 | 15.1 KB | 565 lines

TREXXTRA, The TEXTRA-to-ARexx Command Interface! (The mother-of-all-concatenated-names!!!) again, by Mike Haas (who else?) *** Many THANX to Martin Kees, who generously contributed *** his AREXX interface design and implementation. And to youse guys at Commodore-Amiga, for the obvious. This document describes the TEXTRA commands that may be placed within ARexx scripts and launched from within TEXTRA via the "Utilities, AREXX..." menu item or key-equivalent. It applies to TEXTRA v1.10 and later. I'll make every attempt to keep later versions backward-compatible and NOT break any existing scripts later on. A Quick example... A simple script is supplied to illustrate the usage of AREXX from TEXTRA. It is called "Hello.textra" and you should place it in your rexx: directory, if you have not already done so. (In fact, copy all the ".textra" files there). If you want to try this out... 1. Launch TEXTRA by double-clicking its icon from Workbench. When the "Open File" requester appears, click on the "CANCEL" button. 2. Pull-down the "Utilities, AREXX..." menu item. Enter HELLO (case doesn't matter) into one of the requesters and press RETURN. Watch what happens. ARexx provides a complete programming environment that can make full use of the TEXTRA command set. The TEXTRA user may use combinations of AREXX commands, TEXTRA commands, and even commands from other applications to 'take control' of TEXTRA and probably get it to do things I never dreamed of! I've provided a few ARexx scripts in the TEXTRA distribution package. Specific instructions are provided at the beginning of each script...load 'em into TEXTRA & check 'em out! Make SURE to look at SLIDE.textra, EVAL.textra and WRAPAT.textra...these are really useful tools. Please feel free to use these as basis for developing your own ARexx programs, if you are inclined to such things. If you do, and can see your way clear, please send me a copy of your stuff. (a little payback for TEXTRA, maybe?) Mike Haas 3867 La Colina Rd. El Sobrante, CA. 94803 AREXX Scripts containing the TEXTRA commands described in this file may reside in either of 2 places: 1. The Textra "startup" directory... a. If you launch TEXTRA from Workbench, this is the same directory that TEXTRA is in. b. If you run TEXTRA from CLI/Shell, this is the "current directory" of the CLI/Shell. 2. The REXX: directory (if you have one ASSIGNed) Notes about TEXTRA Command Invocations from ARexx scripts... 1. When specifying strings in TEXTRA commands, encase them in double-quotes, even if there is no whitespace. (Otherwise, ARexx will convert all your characters to UPPER case. Nice of it, huh?) 2. Script usage is case-INsensitive for the TEXTRA commands and keyword-matching. 3. TEXTRA will sometimes set combinations of 2 pre-defined AREXX variables, RESULT and RC (return code). Both are strings, RESULT being primarily informational in nature and RC used for error situation return values ('out-of-range value' or 'not found' type error codes). Note that to retrive the RESULT string, if used, the AREXX program must have declared OPTIONS RESULTS somewhere previously. RC is always available and TEXTRA will return 0 in it for a SUCCESS condition or a non-zero value (5 is considered a minor condition, 10 is the more serious type, etc.). LIMITATIONS... This is the first release of an AREXX interface into TEXTRA. I've tried to provide a comprehensive set of editing commands to operate on one window (the currently selected one). Enhancement suggestions welcome. At present, there is no capability for an ARexx script to change the selected window, open another window, revert or save any window (including the selected one). All forthcoming. In time. See the associated 'KnownProblems.doc' file for a more detailed description of things to be careful of. Have fun & SEND ME YOUR STUFF!!!!! The commands themselves... =================================================================== Movement Commands =================================================================== GOTOXY x y move cursor to x y position Place the cursor to the given 'x y' coordinates, where 'x' is the decimal column position (strting with 0) and 'y' is the decimal line number (starting with 0). 'rc' set to: 0 = 'x y' within range of text 5 = 'x' too large (cursor positioned to end-of-line) 10 = 'y' too large (no change in cursor/selection) UP n cursor up n lines 'rc' set to: 0 = cursor position was successfully changed by at least 1 line 5 = cursor was at top line to begin with DOWN n cursor down n lines 'rc' set to: 0 = cursor position was successfully changed by at least 1 line 5 = cursor was at bottom line to begin with RIGHT n cursor right n characters ( 'rc' set to: 0 = cursor position was successfully changed by at least 1 column 5 = cursor was at last character in file to begin with LEFT n cursur left n characters 'rc' set to: 0 = cursor position was successfully changed by at least 1 column 5 = cursor was at first character in file to begin with FIRSTLINE cursor to beg of file (rc always = 0) LASTLINE cursor to end of file (rc always = 0) TOP cursor up to topline of visable page (rc always = 0) BOTTOM cursor to bottom line of visable page (rc always = 0) CENTER cursor to middle line (rc always = 0) HOPTO next word cursor to start of next word HOPTO prev word cursor to END of prev word HOPTO next char cursor to next non-white HOPTO prev char cursor to prev non-white HOPTO next blank cursor to next whitespace char HOPTO prev blank cursor to prev whitespace char HOPTO moves the cursor to a specific position relative to the current cursor or selection location. The direction and ultimate destination position is determined by the keywords provided. 'rc' set to: 0 = SUCCESS 10 = keywords supplied to HOPTO were invalid if 'rc' = 0, 'result' set to: "<number>" = cursor column "NOT FOUND" = could not HOPTO (at one end of file) =================================================================== Set Selected Area =================================================================== SELECTLINE n select and display line n Same as the 'Go to Line...' menu item. No effect if 'line n' is not both a valid decimal number and in range for the file. (rc always = 0) FIND "text" find "text", observe wrap setting Find and select the specified text. The search is case-INsensitive. 'result' set to: "OK" = text has been located, selected and displayed "NOT FOUND" = could not be found (rc always = 0) FINDNEXT Conducts another search for the same string, see FIND. SELECTTO x y Used to establish or modify a select range as follows: - If 'x y' is below the current cursor location or start of selection, 'x y' then becomes the new start of selection. - If 'x y' is after the current cursor location or end of selection, 'x y' then becomes the new end of selection. - If 'x y' is within the current selection, then 'x y' becomes the new end of selection. (rc always = 0) HOPSELECT next word HOPSELECT prev word HOPSELECT next char HOPSELECT prev char HOPSELECT establishes a selection relative to the current cursor or selection location. The direction and destination selection is determined by the keywords provided. 'rc' set to: 0 = SUCCESS 10 = keywords supplied to HOPSELECT were invalid if 'rc' = 0, 'result' set to: "<number>" = length of selected string "NOT FOUND" = could not HOPSELECT (at one end of file) UNSELECT make sure nothing is selected If there is a selection, place the cursor at the end of it. No effect if nothing selected. (rc always = 0) =================================================================== Operations on Selected Areas =================================================================== CUT Same as the 'CUT' menu item. No effect if nothing selected. (rc always = 0) COPY Same as the 'COPY' menu item. No effect if nothing selected. (rc always = 0) PASTE Same as the 'PASTE' menu item. No effect if nothing has been CUT or COPY'ed. (rc always = 0) KILLSELECT If a select range exists, delete it. Do NOT save it in the TEXTRA clipboard. (rc always = 0) 'result' set to: "OK" if a select range existed. The cursor will now reside where the select range previously began. "NO SELECT" = There is no selection. (nothing is changed) LOCASE Selected or next word to lower case. (rc always = 0) HICASE Selected or next word to upper case. (rc always = 0) CAPS Capitalize the selected or next word. (rc always = 0) =================================================================== INTERACTIVE Control =================================================================== TEXT token Inserts the 'token' into the current window at the current cursor location. If a select range exists, it is deleted before the insertion. (rc always = 0) TEXTN token Same as TEXT, but includes a newline after the specified string. (rc always = 0) NEWLINE Inserts a newline into the current window at the current cursor location. If a select range exists, it is deleted before the insertion. (rc always = 0) BACKSPACE Same behavior as the BackSpace key on the keyboard. (rc always = 0) DEL Same behavior as the DEL key on the keyboard. (rc always = 0) PREFS attribute action Perform an action to the specified Edit or Printing Preferences attribute. The action may be to either read and return the current setting of the attribute, or set it. The valid attribute keywords are listed here, along with the appropriate action keywords for each... Usage: PREFS [AutoIndent] [read on off] [AutoBackspace] [read on off] [PrintLineNumbers] [read on off] [PrintPageHeaders] [read on off] [TabWidth] [read <value>] [ConvertCRLF] [read on off] If the action is 'read', the returned string will either be "ON", "OFF", or "<value>", depending on whether the attribute is a 'state' or 'numeric' variable. example: PREFS AutoIndent read AIstatus = result /* should be ON or OFF */ If the action is to set the attribute, then the action keyword will be either "ON", "OFF" or "<value>", depending on whether the attribute is a 'state' or 'numeric' variable. If the attribute is successfully set, the string "OK" will be returned. example: PREFS AutoIndent on AIstatus = result /* should be OK */ 'rc' set to: 0 = SUCCESS 10 = keywords supplied to PREFS were invalid if 'rc' = 0 and action is "read", 'result' set to: "<number>" = if requested attribute is numeric in nature "ON" or "OFF" = if requested attribute is a 'state' GET item attribute GET is used to aquire information about a certain 'attribute' of a particular 'item'. 'rc' set to: 0 = SUCCESS 10 = keywords supplied to GET were invalid Assuming the given keyword pairs are valid (in the following list), 'result' will be set as indicated. A brief summary of the available reports: GET cursor position - report column & line of cursor GET cursor char - report character at cursor position GET file name - get just the filename (no path) GET file path - get just the file path (no name) GET line <num> - return text of line GET select position - return start and end points of select range GET select text - return the string that is selected GET select next - used after 'get select text' to get later lines Specific info about each command... GET cursor position 'result' set to: "x y" = column & line numbers, both 0-based (ex: "0 13" to indicate first column of the fourteenth line). Use "PARSE var result col ' ' line" in AREXX scripts. "SELECT" = There is no cursor (a selection exists). GET cursor char 'result' set to: "c" = a single-character string (or "-1" if on empty line) "SELECT" = There is no cursor as a selection exists. GET file name 'result' set to "filename" GET file path 'result' set to "vol:dir/" or "vol:" format GET line <num> 'rc' set to: 10 = <num> is too large (the specified line doesn't exist), otherwise, 'result' set to: "line text" = contents of line <num> GET select position 'result' set to: "startx starty endx endy" = select range coordinates. (For example, "0 0 2 4" indicates that from the first column of the first line to the third column of the fifth line is selected. From AREXX, use: "PARSE var result ' ' startx ' ' starty ' ' endx ' ' endy") "NO SELECT" = There is no selection. GET select text "numleft selected text" | "NO SELECT" Used to retrieve the currently selected, or at least the component of it that is on the first line. The first portion of the returned string is always the number of remaining lines that can be returned via "GET select next". This number is always followed by a SPACE character, then the selected text on that line. For example, if "0 Four score" is returned, the caller knows that the selection does not extend over 1 line and that the selected text is "Four Score". If "1 seven years ago," is returned, the caller knows that the selected text is "seven years ago," and that the selection extends over to the next line (see "GET select next"). 'result' set to: "<num> selected text" = <num> is number of times to call "GET select next" (separated by a SPACE character from the text). "NO SELECT" = no selection currently exists. GET select next "numleft selected text" | "NO SELECT" Used to retrieve remaining lines, if the previous "GET select text" indicated it should be called at all. It returns the same format string as "GET select text", but will return a 'numleft' component that decreases by 1 each time, ultimately to zero. 'result' set to: same as "GET select text" NOTE: returns just "0" if called past end of selection. WAITFOR num Wait for 'num' seconds, where 'num' is a decimal number of the form "4.36" or "4". Minimum resolution is .02 seconds, and with the speed AREXX operates at, that should be quite sufficient! CLEAR Delete all text from and blank the current window. NOTIFY "token" Presents a standard informational 'Please Note!' requester to the user and waits for him/her to click the single 'OK' button. The token string is presented in the requester and should not exceed 60 characters in length. Does not return a result. rc always = 0. ASK "token" Presents a standard 'YES/NO' requester to the user and waits for him/her to click on a button. The token string is presented in the requester and should not exceed 60 characters in length. rc always = 0. 'result' set to: "YES" or "NO", depending of course on which button was clicked.