home *** CD-ROM | disk | FTP | other *** search
/ The CDPD Public Domain Collection for CDTV 4 / CDPD_IV.bin / utilities / editors / textra / docs / rexxcommand.doc < prev    next >
Text File  |  1994-06-24  |  36KB  |  1,141 lines
  1.  
  2.  
  3.          TREXXTRA, The TEXTRA-to-ARexx Command Interface!
  4.  
  5.             (The mother-of-all-concatenated-names!!!)
  6.  
  7.                  again, by Mike Haas  (who else?)
  8.  
  9.  
  10.  
  11.     *** Many THANX to Martin Kees, who generously contributed ***
  12.        his AREXX original interface design and implementation.
  13.     
  14.       *** Many THANX to James Cooper of SAS Institute, Inc. ***
  15.             for contributing the SAS/C interface scripts.
  16.       
  17.    *** Many THANX to all the registered users who have reported ***
  18.           bugs and contributed a wealth of much-appreciated
  19.                 suggestions for our favorite editor.
  20.     
  21.          And to youse guys at Commodore-Amiga, past, present
  22.                   and future, for the obvious.
  23.  
  24.  
  25.     This document describes the TEXTRA commands that may be placed 
  26.     within ARexx scripts and launched from within TEXTRA via the 
  27.     "Utilities, AREXX..." menu item or key-equivalent.
  28.  
  29.     TEXTRA introduced its ARexx interface in v1.10.  I'll make every 
  30.     attempt to keep later versions backward-compatible and NOT break 
  31.     any existing scripts later on.
  32.     
  33.     This document describes the feature set of Textra Version 1.15.
  34.     A complete Revision History for the ARexx interface is at end
  35.     of this document.
  36.     
  37.           
  38. A Quick example...
  39.  
  40. Before trying anything, copy the provided TEXTRA ARexx script
  41. files, the ones in the provided "Scripts" directory, into your
  42. rexx: directory.  The provided Textra_Install program will do that
  43. for you automatically.  (This need be done only once and completes
  44. the TEXTRA AREXX Interface installation on your system.)
  45.  
  46. (Alternatively, you could temporarily assign rexx: to the Scripts 
  47. directory.  If necessary, refer to your Amiga System Manuals for 
  48. information about any of these operations.)
  49.  
  50. Launch TEXTRA by double-clicking on it's icon and click on the
  51. 'CANCEL' button on the file requester.
  52.  
  53. Pull-down the "Utilities, AREXX..." menu item and, if not already 
  54. present, enter  Tutorial  into one of the string gadgets and press 
  55. RETURN.  (Note: you can clear one first with Rt-Amiga-X, if 
  56. necessary).
  57.  
  58. Please feel free to use the provided scripts as a basis for developing 
  59. your own ARexx programs, if you are inclined to such things.  If you 
  60. do, and can see your way clear, please send me a copy of your stuff...  
  61. if you wish it to be included in the standard release package, include 
  62. a signed statement to that effect, OK?
  63.  
  64. Mike Haas
  65. 3867 La Colina Rd.
  66. El Sobrante, CA. 94803
  67.  
  68.  
  69.  
  70. AREXX Scripts containing the TEXTRA commands described in 
  71. this file may reside in either of 2 places:
  72.  
  73. 1. The REXX: directory (if you have one ASSIGNed)
  74.     
  75.                     OR
  76.  
  77. 2. The Textra "startup" directory...
  78.     
  79.    a. If you launch TEXTRA from Workbench, this is the same
  80.       directory that TEXTRA is in.
  81.        
  82.    b. If you run TEXTRA from CLI/Shell, this is the "current
  83.       directory" of the CLI/Shell when you launch Textra.
  84.     
  85.  
  86.  
  87. Notes about TEXTRA Command Invocations from ARexx scripts...
  88.  
  89. 1. When specifying strings in TEXTRA commands, encase them 
  90.    in double-quotes, even if there is no whitespace.  
  91.    (Otherwise, ARexx will convert all your characters to 
  92.    UPPER case.  Nice of it, huh?)
  93.  
  94. 2. Script usage is case-INsensitive for the TEXTRA commands 
  95.    and keyword-matching.
  96.  
  97. 3. TEXTRA will sometimes set combinations of 2 pre-defined 
  98.    AREXX variables, RESULT and RC (return code).  Both are 
  99.    strings, RESULT being primarily informational in nature 
  100.    and RC used for error situation return values 
  101.    ('out-of-range value' or 'not found' type error codes).
  102.    
  103.    Note that to retrieve the RESULT string, if used, the 
  104.    AREXX program must have declared OPTIONS RESULTS 
  105.    somewhere previously.  RC is always available and TEXTRA 
  106.    will return 0 in it for a SUCCESS condition or a non-zero 
  107.    value (5 is considered a minor condition, 10 is the more 
  108.    serious type, etc.).
  109.    
  110.    
  111. The remainder of this document is divided into the following
  112. sections, each describing commands related to that topic...
  113.  
  114.    Movement commands
  115.    Set Selected Area
  116.    Operations on Selected Areas
  117.    Interactive Control
  118.    File/Window Management
  119.  
  120. There is some overlap to the functionality of these sections,
  121. so if you're looking for a specific capability, scan everything.
  122.  
  123. The commands themselves...
  124.  
  125.  
  126.  ===================================================================
  127.  Movement Commands
  128.  ===================================================================
  129.  
  130.  
  131.  GOTOXY x y            move cursor to x y position
  132.  
  133.     Place the cursor to the given 'x y' coordinates, where
  134.     'x' is the decimal column position (starting with 0) and 'y'
  135.     is the decimal line number (starting with 0).
  136.     
  137.     'rc' set to:
  138.     
  139.      0 = 'x y' within range of text
  140.      5 = 'x' too large (cursor positioned to end-of-line)
  141.     10 = 'y' too large (no change in cursor/selection)
  142.  
  143.  
  144.  GOTOXY1 x y        move cursor to x y position (1's-based)
  145.  
  146.     This command is identical with GOTOXY, except that it accepts
  147.     'x' and 'y' arguments which start with 1 (passing less than 1 for
  148.     either will set 'rc' as indicated above).
  149.  
  150.  
  151.  UP   n                cursor up n lines
  152.  
  153.     'rc' set to:
  154.     
  155.      0 = cursor position was successfully changed by at least 1 line
  156.      5 = cursor was at top line to begin with
  157.      
  158.      
  159.  DOWN n                cursor down n lines
  160.  
  161.     'rc' set to:
  162.     
  163.      0 = cursor position was successfully changed by at least 1 line
  164.      5 = cursor was at bottom line to begin with
  165.      
  166.      
  167.  RIGHT n            cursor right n characters
  168.  
  169.     'rc' set to:
  170.     
  171.      0 = cursor position was successfully changed by at least 1 column
  172.      5 = cursor was at last character in file to begin with
  173.      
  174.      
  175.  LEFT  n            cursor left  n characters
  176.  
  177.     'rc' set to:
  178.     
  179.      0 = cursor position was successfully changed by at least 1 column
  180.      5 = cursor was at first character in file to begin with
  181.      
  182.      
  183.  FIRSTLINE        cursor to beg of file (rc always = 0)
  184.   
  185.  
  186.  LASTLINE        cursor to end of file (rc always = 0)
  187.  
  188.  
  189.  TOP            cursor up to topline of visable page (rc always = 0)
  190.  
  191.  
  192.  BOTTOM            cursor to bottom line of visable page (rc always = 0)
  193.  
  194.  
  195.  CENTER            cursor to middle line (rc always = 0)
  196.  
  197.  
  198.  HOPTO next word    cursor to start of next word
  199.  HOPTO prev word    cursor to END of prev word
  200.  HOPTO next char    cursor to next non-white
  201.  HOPTO prev char     cursor to prev non-white
  202.  HOPTO next blank     cursor to next whitespace char
  203.  HOPTO prev blank     cursor to prev whitespace char
  204.  
  205.     HOPTO moves the cursor to a specific position relative to the
  206.     current cursor or selection location.  The direction and
  207.     ultimate destination position is determined by the keywords
  208.     provided.
  209.     
  210.     HOPTO observes the current setting of the PREFS attribute
  211.     'AlphanumericHops' (see the PREFS command) to determine how it
  212.     skips over characters and words.
  213.     
  214.     'rc' set to:
  215.     
  216.      0 = SUCCESS
  217.     10 = keywords supplied to HOPTO were invalid
  218.      
  219.     if 'rc' = 0, 'result' set to:
  220.     
  221.      "<number>" = cursor column
  222.     "NOT FOUND" = could not HOPTO (at one end of file)
  223.      
  224.  
  225.  LINE <num>
  226.  
  227.     Positions the cursor at the beginning of the specified
  228.     line (relative to 0).  Specifying -1 will place the cursor
  229.     at the beginning of the current cursor line.  If a select
  230.     range exists, the line on which it starts is considered
  231.     the 'current' line.
  232.     
  233.     For results, see GOTOXY.
  234.  
  235.  
  236.  LINE1 <num>     *** 1's based ***
  237.  
  238.     Same as LINE, but 1's-based.  For results, see GOTOXY.
  239.  
  240.  
  241.  COLUMN <num>
  242.  
  243.     Positions the cursor at column <num> of the current
  244.     line (relative to 0).  Specifying -1 will move the cursor
  245.     to the end of the current cursor line.  If a select
  246.     range exists, the line on which it starts is considered
  247.     the 'current' line.
  248.     
  249.     For results, see GOTOXY.
  250.  
  251.  
  252.  COLUMN1 <num>     *** 1's based ***
  253.  
  254.     Same as COLUMN, but 1's-based.  For results, see GOTOXY.
  255.  
  256.  
  257.  ===================================================================
  258.  Set Selected Area
  259.  ===================================================================
  260.  
  261.  
  262.  SELECTLINE n        select and display line n
  263.  
  264.     Same as the 'Go to Line...' menu item.  No effect if 'line n'
  265.     is not both a valid decimal number and in range for the file.
  266.     (rc always = 0)
  267.  
  268.  
  269.  FIND "text"        find "text", observe wrap setting
  270.  
  271.     Find and select the specified text.  The search is case-INsensitive.
  272.     
  273.     'result' set to:
  274.     
  275.            "OK" = text has been located, selected and displayed
  276.     "NOT FOUND" = could not be found
  277.     
  278.     (rc always = 0)
  279.  
  280.  
  281.  FINDNEXT
  282.  
  283.     Conducts another search for the same string, see FIND.
  284.  
  285.  
  286.  SELECTTO x y
  287.  
  288.     Used to establish or modify a select range as follows:
  289.     
  290.     - If 'x y' is below the current cursor location or start
  291.       of selection,    'x y' then becomes the new start of selection.
  292.     
  293.     - If 'x y' is after the current cursor location or end of
  294.       selection, 'x y' then becomes the new end of selection.
  295.     
  296.     - If 'x y' is within the current selection, then 'x y' becomes
  297.       the new end of selection.
  298.  
  299.     (rc always = 0)
  300.  
  301.  
  302.  HOPSELECT next word
  303.  HOPSELECT prev word
  304.  HOPSELECT next char
  305.  HOPSELECT prev char
  306.  
  307.     HOPSELECT establishes a selection relative to the current
  308.     cursor or selection location.  The direction and destination
  309.     selection is determined by the keywords    provided.
  310.  
  311.     HOPSELECT observes the current setting of the PREFS attribute
  312.     'AlphanumericHops' (see the PREFS command) to determine how it
  313.     selects characters and words.
  314.     
  315.     'rc' set to:
  316.     
  317.      0 = SUCCESS
  318.     10 = keywords supplied to HOPSELECT were invalid
  319.      
  320.     if 'rc' = 0, 'result' set to:
  321.     
  322.      "<number>" = length of selected string
  323.     "NOT FOUND" = could not HOPSELECT (at one end of file)
  324.      
  325.  
  326.  UNSELECT          make sure nothing is selected
  327.  
  328.     If there is a selection, place the cursor at the end of it.
  329.     No effect if nothing selected.
  330.     (rc always = 0)
  331.  
  332.  
  333.  ===================================================================
  334.  Operations on Selected Areas
  335.  ===================================================================
  336.  
  337.  
  338.  CUT
  339.  
  340.     Same as the 'CUT' menu item.  No effect if nothing selected.
  341.     rc = 30 if window is write protected, otherwise 0
  342.  
  343.  
  344.  COPY
  345.  
  346.     Same as the 'COPY' menu item.  No effect if nothing selected.
  347.     (rc always = 0)
  348.  
  349.  
  350.  PASTE
  351.  
  352.     Same as the 'PASTE' menu item.  No effect if nothing has been
  353.     CUT or COPY'ed. rc = 30 if window is write protected, otherwise 0
  354.  
  355.  
  356.  KILLSELECT
  357.  
  358.     If a select range exists, delete it.  Do NOT save it in the
  359.     clipboard.  rc = 30 if window is write protected, otherwise 0
  360.  
  361.     'result' set to:
  362.     
  363.     "OK" if a select range existed.  The cursor will now reside
  364.          where the select range previously began. 
  365.     
  366.     "NO SELECT" = There is no selection.  (nothing is changed)
  367.     "WRITE PROTECTED" = window must be unlocked, see WRITEENABLE
  368.  
  369.  
  370.  LOCASE
  371.  
  372.     Selected or next word to lower case.  rc = 30 if window is
  373.     write protected, otherwise 0
  374.  
  375.  
  376.  HICASE
  377.  
  378.     Selected or next word to upper case.  rc = 30 if window is
  379.     write protected, otherwise 0
  380.  
  381.  
  382.  CAPS
  383.  
  384.     Capitalize the selected or next word.  rc = 30 if window is
  385.     write protected, otherwise 0
  386.  
  387.  
  388.  ===================================================================
  389.  INTERACTIVE Control
  390.  ===================================================================
  391.  
  392.  
  393.  TEXT token
  394.  
  395.     Inserts the 'token' into the current window at the current
  396.     cursor location.  If a select range exists, it is deleted
  397.     before the insertion.  rc = 30 if window is    write protected,
  398.     otherwise 0
  399.  
  400.  
  401.  TEXTN token
  402.  
  403.     Same as TEXT, but includes a newline after the specified string.
  404.     rc = 30 if window is write protected, otherwise 0
  405.  
  406.  
  407.  NEWLINE
  408.  
  409.     Inserts a newline into the current window at the current
  410.     cursor location.  If a select range exists, it is deleted
  411.     before the insertion. rc = 30 if window is write protected,
  412.     otherwise 0
  413.  
  414.  
  415.  BACKSPACE
  416.  
  417.     Same behavior as the BackSpace key on the keyboard.
  418.     rc = 30 if window is write protected, otherwise 0
  419.  
  420.  
  421.  DEL
  422.  
  423.     Same behavior as the DEL key on the keyboard.
  424.     rc = 30 if window is write protected, otherwise 0
  425.  
  426.  
  427.  PREFS attribute action
  428.  
  429.     Perform an action to the specified Edit or Printing Preferences
  430.     attribute.  The action may be to either read and return the
  431.     current setting of the attribute, or set it.
  432.     
  433.     The valid attribute keywords are listed here, along with the
  434.     appropriate action keywords for each...
  435.  
  436.     Usage:   PREFS [AutoIndent]        [read on off]
  437.                    [AutoBackspace]     [read on off]
  438.                    [PrintLineNumbers]  [read on off]
  439.                    [PrintPageHeaders]  [read on off]
  440.                    [TabWidth]          [read <value>]
  441.                    [Alphanumeric]      [read on off]
  442.                    [AlphanumericHops]  [read on off]
  443.                    [WrapFind]          [read on off]
  444.     
  445.     If the action is 'read', the returned string will either be
  446.     "ON", "OFF", or "<value>", depending on whether the attribute
  447.     is a 'state' or 'numeric' variable.
  448.     
  449.     example:   PREFS AutoIndent read
  450.                AIstatus = result    /* should be ON or OFF */
  451.                
  452.     If the action is to set the attribute, then the action keyword
  453.     will be either "ON", "OFF" or "<value>", depending on whether
  454.     the attribute is a 'state' or 'numeric' variable.  If the
  455.     attribute is successfully set, the string "OK" will be returned.
  456.     
  457.     NOTE: setting the    PREFS Alphanumeric  attribute to 'off'
  458.           automatically infers the 'Non-Whitespace" mode of selecting
  459.           text on double-click mouse events.
  460.     
  461.     NOTE: the    PREFS AlphanumericHops [read on off]   attribute,
  462.           determines how the HOPTO and HOPSELECT commands will look
  463.           at text. Turning this attribute off automatically infers
  464.           the 'Non-Whitespace" mode of parsing text.
  465.     
  466.     NOTE: the WrapFind setting is initialized to OFF at the beginning
  467.           of each script or command invocation.  This attribute applies
  468.           ONLY to the FIND and FINDNEXT commands (is independant of
  469.           the Wrap setting in the FIND STRING... requester).
  470.     
  471.     examples:   PREFS AutoIndent on
  472.                 AIstatus = result    /* should be OK */
  473.                 
  474.                 PREFS TabWidth read
  475.                 notify result
  476.  
  477.     'rc' set to:
  478.     
  479.      0 = SUCCESS
  480.     10 = keywords supplied to PREFS were invalid
  481.      
  482.     if 'rc' = 0 and action is "read", 'result' set to:
  483.     
  484.         "<number>" = if requested attribute is numeric in nature
  485.      "ON" or "OFF" = if requested attribute is a 'state'
  486.      
  487.  
  488.  GET item attribute
  489.  
  490.     GET is used to aquire information about a certain 'attribute'
  491.     of a particular 'item'.
  492.  
  493.     'rc' set to:
  494.     
  495.      0 = SUCCESS
  496.     10 = keywords supplied to GET were invalid
  497.     
  498.     Assuming the given keyword pairs are valid (in the following list),
  499.     'result' will be set as indicated.
  500.  
  501.     A brief summary of the available reports:
  502.     
  503.     GET cursor position    - report column & line of cursor
  504.     GET cursor char        - report character at cursor position
  505.     GET file name        - get just the filename (no path)
  506.     GET file path        - get just the file path (no name)
  507.     GET file info       - get characteristics of the file
  508.     GET window info     - get characteristics of the window
  509.     GET window <num>    - get 'window-pointer' for window N
  510.     GET line <num>        - return text of line
  511.     GET select position    - return start and end points of select range
  512.     GET select text        - return the string that is selected
  513.     GET select next        - used after 'get select text' to get later lines
  514.     
  515.     Specific info about each command...
  516.  
  517.     GET cursor position
  518.     
  519.         'result' set to:
  520.         
  521.         "x y" = column & line numbers, both 0-based (ex: "0 13"
  522.                 to indicate first column of the fourteenth line).
  523.                 Use "PARSE var result col ' ' line" in AREXX scripts.
  524.         
  525.         "SELECT" = There is no cursor (a selection exists).
  526.     
  527.     GET cursor char
  528.     
  529.         'result' set to:
  530.         
  531.         "c" = a single-character string (or "-1" if on empty line)
  532.         
  533.         "SELECT" = There is no cursor as a selection exists.
  534.         
  535.     GET file name    'result' set to "filename"
  536.     
  537.     GET file path    'result' set to "vol:dir/" or "vol:" format
  538.     
  539.     GET file info    'result' set to "string" describing characteristics
  540.         
  541.         'result' set to:
  542.         
  543.         "modified? numLines size-in-mem size-on-disk"
  544.         
  545.         where:
  546.         
  547.             modified? = "YES" or "NO"
  548.             
  549.             numLines = number of lines in memory
  550.         
  551.             size-in-mem = number of characters in memory
  552.         
  553.             size-on-disk = number of characters on disk (-1 if
  554.                            file doesn't exist or error)
  555.         
  556.     GET window info  'result' set to "string" describing characteristics
  557.         
  558.         'result' set to:
  559.         
  560.         "left top width height numVisLines numVisChars"
  561.         
  562.         where:
  563.         
  564.             left = window left edge
  565.         
  566.             top = window topedge
  567.         
  568.             width = window width
  569.         
  570.             height = window height
  571.         
  572.             numVisLines = height in visible text lines
  573.         
  574.             numVisChars = width in visible characters
  575.         
  576.             NOTE: all coordinates relative to screen 0,0
  577.     
  578.     GET window <num>    obtain the 'window-pointer' for window N
  579.     
  580.         <num> must be in the range of from 1 to number-of-windows.
  581.         
  582.         This command is especially useful for doing something to
  583.         each open Textra window, when used in combination with
  584.         the SELECTWINDOW command.
  585.         
  586.         ONE SHOULD BE AWARE OF THE FOLLOWING CAVEAT WHEN USING
  587.         THIS COMMAND VARIANT:  If a window is closed by any
  588.         means (meaning the 'number-of-windows' is lowered), one
  589.         cannot assume that the same 'window-pointer' value will
  590.         be returned for the same <num> argument.  For example,
  591.         if 'GET window 2' returns -148200, and then window 1
  592.         is closed, 'GET window 2' may now be invalid (if there
  593.         is only 1 window left), and 'GET window 1' will now
  594.         return the -148200 window value.  (This is not a
  595.         consideration if new windows are opened, just when they
  596.         are closed.)
  597.         
  598.         'result' set to:
  599.         
  600.             'window-pointer'  = if <num> was in range
  601.                            0  = if <num> was out of range
  602.         
  603.     GET line <num>
  604.     
  605.         'rc' set to:
  606.         
  607.         10 = <num> is too large (the specified line doesn't exist),
  608.     
  609.         otherwise, 'result' set to:
  610.         
  611.         "line text" = contents of line <num>
  612.         
  613.     GET select position
  614.     
  615.         'result' set to:
  616.         
  617.         "startx starty endx endy" = select range coordinates.
  618.         
  619.             (For example, "0 0 2 4" indicates that from the first
  620.              column of the first line to the third column of the fifth
  621.              line is selected.  From AREXX, use:
  622.              PARSE var result startx' 'starty' 'endx' 'endy    )
  623.         
  624.         "NO SELECT" = There is no selection.
  625.         
  626.     GET select text        "(num) selected text"  |  "NO SELECT"
  627.     
  628.         Used to retrieve the current selection, or at least
  629.         the component of it that is on the first line.  The
  630.         first portion of the returned string is always the number
  631.         of remaining lines that can be returned via "GET select next".
  632.         This number is always followed by a SPACE character, then the
  633.         selected text on that line.
  634.         
  635.         For example, if "0 Four score" is returned, the caller knows
  636.         that the selection does not extend over 1 line and that the
  637.         selected text is "Four Score".
  638.         
  639.         If "1 seven years ago," is returned, the caller knows
  640.         that the selected text is "seven years ago," and that
  641.         the selection extends over to the next line (see
  642.         "GET select next").
  643.         
  644.         'result' set to:
  645.         
  646.         "<num> selected text" = <num> is number of times to call
  647.                                 "GET select next" (separated by a
  648.                                 SPACE character from the text).
  649.         
  650.         "NO SELECT" = no selection currently exists.
  651.  
  652.     GET select next        "numleft selected text"  |  "NO SELECT"
  653.         
  654.         Used to retrieve remaining lines, if the previous
  655.         "GET select text" indicated it should be called at all.
  656.         It returns the same format string as "GET select text",
  657.         but will return a 'numleft' component that decreases
  658.         by 1 each time, ultimately to zero.
  659.  
  660.         'result' set to:  same as "GET select text"
  661.         
  662.         NOTE: returns just "0" if called past end of selection.
  663.  
  664.  
  665.  WAITFOR num
  666.  
  667.     Wait for 'num' seconds, where 'num' is a decimal number of
  668.     the form "4.36" or "4".  Minimum resolution is .02 seconds,
  669.     and with the speed AREXX operates at, that should be quite
  670.     sufficient!
  671.  
  672.  
  673.  CLEAR
  674.  
  675.     Delete all text from and blank the current window.
  676.     rc = 30 if window is write protected, otherwise 0
  677.  
  678.  
  679.  NOTIFY "token"
  680.  
  681.     Presents a standard informational 'Please Note!' requester
  682.     to the user and waits for him/her to click the single 'OK'
  683.     button.  The token string is presented in the requester
  684.     and should not exceed 60 characters in length.  Does not
  685.     return a result.  rc always = 0.
  686.  
  687.  
  688.  ASK "token"
  689.  
  690.     Presents a standard 'YES/NO' requester to the user and waits
  691.     for him/her to click on a button.  The token string
  692.     is presented in the requester and should not exceed 60
  693.     characters in length.  rc always = 0.
  694.     
  695.     'result' set to:
  696.     
  697.     "YES" or "NO", depending of course on which button was clicked.
  698.  
  699.  
  700.  TEXTRAVERSION   (only in v1.12 and later)
  701.  
  702.     Returns a string describing the TEXTRA major and minor versions, 
  703.     as well as the incremental version of the AREXX interface 
  704.     (increments with each release that contains a modification to
  705.      the interface code and/or command set).
  706.     
  707.     format:   major-version minor-version rexxinterface
  708.  
  709.     for example:    1            12             2
  710.  
  711.     "1 12 2" will be returned for v1.12, last 2 indicates
  712.              AREXX interface, rev2.  This should increment with
  713.              every release that contains an ARexx interface
  714.              addition, deletion, modification, or fix.
  715.     
  716.     "1 13 5" is returned for 1.13
  717.  
  718.     The 3rd digit will never be less than 2, as it was that rev
  719.     which implemented this command.
  720.     
  721.     The commands in the following list have been added since the
  722.     initial V1.10 release (which first incorporated the ARexx
  723.     interface).  For best results, you should check for the highest
  724.     relevant rexx version at the beginning of your script (rexx
  725.     code for checking shown below)...
  726.     
  727.     min Rexx revision              needed for command
  728.     -----------------              ------------------
  729.         2  (v1.12)         OPENFILE, FINDFILE, SELECTWINDOW, SAVEAS
  730.         
  731.         5  (v1.13)         INSERTFILE, CHECKCANCEL, CLOSEWINDOW,
  732.                            RETURNPROMPT, RETURNPROMPTN,
  733.                            PREFS Alphanumeric, PREFS AlphanumericHops,
  734.                            address Textra (with no command string)
  735.         
  736.         6  (v1.14)         QUITTEXTRA
  737.         
  738.        12  (v1.15)         MARKSELECT, GOTOMARK, DELETEMARK,
  739.                            PREFS WrapFind [action], GOTOXY1,
  740.                            STATUSTEXT, LINE, LINE1, COLUMN, COLUMN1,
  741.                            GET file info, GET window info,
  742.                            GET window <num>, OPENFILEWAIT
  743.     
  744.     For example, if the most recent command listed that your 
  745.     script uses is CHECKCANCEL, you will want to check for 
  746.     rexx ver of 5.  However, if you call QUITTEXTRA, you will need 
  747.     rexx ver 6.
  748.     
  749.     Note that not checking for an appropriate rexx version will 
  750.     not crash older, incompatible versions of the editor, but the 
  751.     user may be confronted with less-explanatory 'unknown 
  752.     command' error requesters.  Checking the rexx ver is how you 
  753.     can explain just what the problem is.
  754.     
  755.     The following ARexx example illustrates how to check for a 
  756.     specific rexx version.  This example checks for rexx ver of 
  757.     5, indicated by the "(rex < 5)" statement on the 6th line:
  758.     
  759.         options results
  760.     
  761.         rex = 0; result = "NOTSUPPORTED"
  762.         textraversion
  763.         parse var result maj min rex
  764.         if (result == "NOTSUPPORTED") | (rex < 5) then do
  765.             notify "Textra V1.13 or later required for this script."
  766.             exit
  767.         end
  768.     
  769.     As of V1.13, all release TEXTRA scripts check that the 
  770.     TEXTRA that is calling them is of a compatible version as 
  771.     appropriate.
  772.  
  773.  
  774.  CHECKCANCEL
  775.  
  776.     Checks whether the user wants to cancel the command.  To
  777.     respond accordingly, the programmer should put something like
  778.     this in his/her ".textra" script:
  779.     
  780.        /* Check if the user wants to cancel... */
  781.        CheckCancel; if (result == CANCEL) then exit
  782.     
  783.     Note that the script has the ability to perform specific actions
  784.     before exiting, such as flushing data for example.
  785.     
  786.     'result' set to:
  787.     
  788.     "CANCEL"     The user wants to cancel current operation
  789.     
  790.     "NO"         Do not cancel
  791.  
  792.  
  793.  RETURNPROMPT "string"
  794.  
  795.     Presents the specified string as a prompt, then waits for the user 
  796.     to press the RETURN or ENTER keys.  Until either is pressed, other 
  797.     keys are entered into the document as usual.  (If the specified
  798.     string is entered as "noprompt", none is presented).
  799.  
  800.     When the user presses RETURN, 4 values are returned as the 
  801.     'result' string.  These represent the starting x, y and ending x, 
  802.     y coordinates for the "response".
  803.     
  804.     The response is considered to be either:
  805.     
  806.        - Any selected text.   (OR, if no text is selected...)
  807.        
  808.        - The cursor position when the command was invoked is
  809.          considered the start x, y.  The end x, y is the position
  810.          when the RETURN key was pressed.
  811.  
  812.     'result' set to:
  813.     
  814.     "WRITE PROTECTED" = window must be unlocked via WRITEENABLE
  815.     
  816.     "startx starty endx endy" = successful query
  817.     
  818.     This can be retrieved via:
  819.     
  820.        parse var result startx starty endx endy
  821.  
  822.  
  823.  RETURNPROMPTN "string"
  824.  
  825.     Works exactly as does RETURNPROMPT, but also adds a NEWLINE after 
  826.     the prompt is displayed, allowing the response to occupy an entire
  827.     line.
  828.     
  829.     See RETURNPROMPT for all other details.
  830.     
  831.     
  832.  QUITTEXTRA <exit-save-action>
  833.  
  834.     There are 3 possible forms of this command:
  835.  
  836.       QUITTEXTRA prompt   (normal shutdown, prompts if files modified)
  837.       QUITTEXTRA save     (doesn't prompt, always saves modified files)
  838.       QUITTEXTRA nosave   (doesn't prompt, doesn't save modified files)
  839.  
  840.     NOTE: The last two forms of this command have special user
  841.     interface considerations.  
  842.     
  843.     Users of a script containing such a command may not desire to have 
  844.     their files saved, almost certainly not discarded.  Use carefully! 
  845.     Make sure others know if you use either of these forms.  (None of 
  846.     the release scripts use any form of the QUITTEXTRA command).
  847.       
  848.     Note that Textra will not exit if a print job is active.  If an ARexx 
  849.     script is running, the exit is postponed until the script finishes.  
  850.  
  851.  
  852.  MARKSELECT <Mark name>
  853.  
  854.     Create a mark called <Mark name> (will be truncated
  855.     to 31 characters maximum length), which will be
  856.     associated with the currently-selected text.  The
  857.     name will be made available to the GUI as well as
  858.     the GOTOMARK and DELETEMARK commands.
  859.     
  860.     Note that an existing mark of the same <Mark name>
  861.     will be replaced with the new mark.
  862.     
  863.     'result' set to:
  864.     
  865.     "OK"   - Mark defined
  866.     
  867.     "NO"   - an error prevented definition of the mark
  868.     
  869.     "NO SELECT" - no select range is highlighted to mark.
  870.     
  871.     "WRITE PROTECTED" - window must be unlocked via WRITEENABLE
  872.     
  873.  
  874.  GOTOMARK <Mark name>
  875.  
  876.     Select and display the text corresponding to
  877.     <Mark name>.
  878.  
  879.     'result' set to:
  880.     
  881.     "OK"   - Mark selected and displayed
  882.     
  883.     "NOT FOUND"   - no mark exists of that name
  884.     
  885.     
  886.  DELETEMARK <Mark name>
  887.  
  888.     Delete the mark called <Mark name>.
  889.  
  890.     'result' set to:
  891.     
  892.     "OK"   - Mark deleted
  893.     
  894.     "NOT FOUND"   - no mark exists of that name
  895.  
  896.     "WRITE PROTECTED" - window must be unlocked via WRITEENABLE
  897.     
  898.  
  899.  STATUSTEXT "Text string"
  900.  
  901.     Displays the passed-in text in the status line, replacing the 
  902.     previous status line display.  (The normal status line 
  903.     display can be recovered at any time by clicking on the 
  904.     status line.)
  905.  
  906.  
  907.  ===================================================================
  908.  File/Window Management
  909.  ===================================================================
  910.  
  911.  
  912.  Some of the commands in this section deal with a parameter called
  913.  a 'window-pointer'.  These may be saved by your program and later
  914.  used to select the active window.  They are valid as long as that
  915.  window is open.  This parameter is bound to the window, not the
  916.  file.  As a result, it always describes the same window, even if
  917.  the filename of that window changes (perhaps via SAVEAS).
  918.  
  919.  See also the 'GET window <num>' command, which also returns a
  920.  'window-pointer'.
  921.  
  922.  
  923.  OPENFILE "filename"
  924.  
  925.     Reads in the specified file from disk, unless the file is
  926.     already open.  TEXTRA first expands the "filename" to it's
  927.     full pathname equivalent, then checks the titles of it's
  928.     current windows for a match.
  929.     
  930.     If the specified file is already open, it is brought to the
  931.     front and the cursor is set to 0,0 (just as if the file was
  932.     freshly opened).
  933.     
  934.     If the specified file is not open, and can't be found on the
  935.     disk, an empty window is created and given the specified
  936.     filename.
  937.     
  938.     NOTE: Do not pass a string that describes a directory to 
  939.           OPENFILE.  It will create a window, then present the 
  940.           file requester on that directory,  thereby requiring 
  941.           user input via the mouse.  Currently, OPENFILE does not 
  942.           wait for the selection before returning to the AREXX 
  943.           script, which operates on the window in that condition 
  944.           (with the requester in place).  (This will be protected 
  945.           against in a future version.)
  946.     
  947.     'result' set to:
  948.     
  949.     "window-pointer"  = descriptor to later use to re-select this
  950.                         window (see SELECTWINDOW)
  951.     
  952.     "0"               = window could not be opened
  953.  
  954.  
  955.  OPENFILEWAIT "filename"
  956.  
  957.     Works identically to OPENFILE, except that this command will
  958.     not return until the edited window is closed.
  959.     
  960.     THIS COMMAND IS ONLY FOR USE FROM EXTERNAL PROGRAMS.  DO NOT
  961.     EXECUTE THIS COMMAND FROM TEXTRA, EITHER IN A SCRIPT OR
  962.     AS A DIRECT COMMAND.
  963.     
  964.     This command was added to support programs like mail readers,
  965.     which sometimes expect the editor to NOT return until the
  966.     user is finished with the specified document.
  967.  
  968.  
  969.  FINDFILE "filename"
  970.  
  971.     TEXTRA first expands the "filename" to it's full pathname 
  972.     equivalent, then checks the titles of it's current windows 
  973.     for a match.
  974.     
  975.     If the filename is found, it is brought to the
  976.     front and the associated 'window-pointer' is returned.
  977.     
  978.     FINDFILE is similar to OPENFILE, except that it never
  979.     creates a new window.
  980.     
  981.     'result' set to:
  982.     
  983.     "window-pointer"  = descriptor to later use to re-select this
  984.                         window (see SELECTWINDOW)
  985.     
  986.     "0"               = filename not found as a window title
  987.  
  988.  
  989.  SELECTWINDOW "window-pointer"
  990.  
  991.     The specified window is brought to the front and made
  992.     the current window.
  993.     
  994.     The window-pointer parameter must have been aquired from
  995.     either OPENFILE or FINDFILE, and the window must still be
  996.     open.
  997.     
  998.     v1.13 and later (only)...  SELECTWINDOW returns...
  999.     
  1000.     "OK"              = Window found and selected
  1001.     "NOT FOUND"       = passed in value was not a valid window-
  1002.                         pointer
  1003.  
  1004.  
  1005.  SAVEAS "filename"
  1006.  
  1007.     The currently selected window is saved to disk under the
  1008.     specified name.
  1009.     
  1010.     If the specified filename is a single asterisk, i.e. "*",
  1011.     the file will be written under the currently existing
  1012.     filename (equivalent to a SAVE operation).
  1013.     
  1014.     'result' set to:
  1015.     
  1016.     "OK"             = file successfully written
  1017.     "ERROR"          = some error occured, file not saved
  1018.     "NOT FOUND"      = "filename" either describes a directory
  1019.                        or contains an invalid pathname component
  1020.     "FILE NOT NAMED" = a "*" has been specified, but the file has
  1021.                        never been given a name
  1022.  
  1023.  
  1024.  CLOSEWINDOW
  1025.  
  1026.     The currently selected window is closed unless it is the
  1027.     last window.
  1028.  
  1029.     'result' set to:
  1030.     
  1031.     "RANGE ERROR"    = file is the last one open (can't be closed
  1032.                        via ARexx)
  1033.     "window-pointer" = the selected window was closed, the returned
  1034.                        "file-pointer" is for the new selected window
  1035.     
  1036.  PLACEWINDOW  leftedge topedge width height
  1037.  
  1038.     Positions the window to the supplied screen-relative coordinates.
  1039.     Example:   PlaceWindow 20 20 300 100
  1040.     
  1041.     If successful, one might want to perform a 'GET window info'
  1042.     operation, to obtain the new value for number-of-visible-lines
  1043.     and number-of-visible-chars, which are both dependant on the
  1044.     user-selected font.
  1045.     
  1046.     If -1 is used for any input parameter, no change in that window
  1047.     dimension (only) will be made.  For example...
  1048.     
  1049.       PLACEWINDOW "-1" "-1" "-1" "-1"   /*arexx needs the quotes*/
  1050.     
  1051.     ...will not change the window position at all.
  1052.     
  1053.     result set to:
  1054.     
  1055.     "RANGE ERROR"   = supplied coordinates are too large, too small
  1056.                       or OS error
  1057.     "OK"            = Window successfully placed
  1058.  
  1059.  
  1060.  WRITEPROTECT
  1061.  
  1062.     Identical to the menu item behavior, "locks" the window against
  1063.     changes by either the user or ARexx.  Commands which normally
  1064.     change window text will set rc=30 and, if appropriate,
  1065.     return result="WRITE PROTECTED".
  1066.  
  1067.  
  1068.  WRITEENABLE
  1069.  
  1070.     Identical to the menu item behavior, "unlocks" the window allowing
  1071.     changes by both user and ARexx.  All commands operate normally.
  1072.  
  1073.  
  1074.     Revision History
  1075.     ----------------
  1076.     
  1077.     v1.10 (Did not support the TEXTRAVERSION command)
  1078.           - Initial ARexx release
  1079.  
  1080.     v1.11 (Did not support the TEXTRAVERSION command)
  1081.           - Fixed GET CURSOR CHAR problem (probable crash
  1082.             if cursor was at the end of a line)
  1083.  
  1084.     These flavors are represented by the third digit in the
  1085.     TEXTRAVERSION ARexx command.  Refer to the text for that
  1086.     command.
  1087.     
  1088.     v1.12 (TEXTRAVERSION returns 1 12 2) 
  1089.           - Replace WRAPAT.textra script with PARAGRAPH.textra
  1090.           - Added File/Window Management section
  1091.           - Added TEXTRAVERSION command
  1092.  
  1093.     v1.13 (TEXTRAVERSION returns 1 13 5) 
  1094.           - Select "next word"-type words will now select
  1095.             Alpha-NUMERIC strings.  (Earlier versions only selected
  1096.             alphabetics) (Beta2)
  1097.           - If no "s:Textra.cmds" file exists, default strings are
  1098.             placed in the ARexx requester string gadgets (including
  1099.             one "@command"-type ARexx STRING FILE as an example).
  1100.             (Beta2)
  1101.           - Added INSERTFILE <filename> (Beta3)
  1102.           - TEXTRAVERSION  returns "1 13 3" (Beta2 was still "1 13 2")
  1103.             (Beta3)
  1104.           - '.textra' ARexx scripts can now be used like normal commands
  1105.             inside other '.textra' ARexx scripts.   (Beta3)
  1106.           - Fixed problem in ARexx interface that would cause a deadlock
  1107.             if 'address "TEXTRA"' was used within a .textra script (Beta7)
  1108.           - CLOSEWINDOW command  (Beta9)
  1109.           - CHECKCANCEL command  (Beta9)
  1110.           - version returns 1 13 4 (Beta12)
  1111.           - SELECTWINDOW was broken in Beta8... window would become active,
  1112.             but all subsequent events went to previously-selected window!
  1113.             (Beta12)
  1114.           - Added the following attributes to PREFS command/1 13 5 (Beta14)
  1115.               [Alphanumeric]      [read on off]
  1116.               [AlphanumericHops]  [read on off]
  1117.     
  1118.     v1.14 (TEXTRAVERSION returns 1 14 6)
  1119.           - Added the QUITTEXTRA command
  1120.           - Fixed a possible crash in the CLEAR command
  1121.           - Fixed a possible crash in the CLOSEWINDOW command
  1122.  
  1123.     v1.15 (TEXTRAVERSION returns 1 15 12)
  1124.           - Added the MARKSELECT command
  1125.           - Added the GOTOMARK command
  1126.           - Added the DELETEMARK command
  1127.           - Added the PREFS WrapFind [on off read] attribute
  1128.           - removed [ConvertCRLF] option for PREFS command as Textra
  1129.             is now MSDOS-text-compatible.
  1130.           - Added the GOTOXY1 and STATUSTEXT commands.
  1131.           - Added the 'GET file info', 'GET window info', 'GET window <num>'
  1132.             and the PLACEWINDOW commands
  1133.           - Added the LINE, LINE1, COLUMN and COLUMN1 commands
  1134.           - (Beta9) When Write-protected, commands which don't change
  1135.             window will work. (In beta8, nothing but WRITEENABLE
  1136.             worked... the files.textra scripts would fail if
  1137.             a write-protected window existed. Also, rexx commands
  1138.             which write to file now report errors. (rexxver to 11)
  1139.           - Added the OPENFILEWAIT command (rexxver to 12)
  1140.  
  1141.