home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 626a.lha / Textra_v1.12 / Docs / RexxCommand.doc.pp / RexxCommand.doc
Text File  |  1992-04-07  |  20KB  |  678 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 interface design and implementation.
  13.     
  14.        And to youse guys at Commodore-Amiga, for the obvious.
  15.  
  16.  
  17.  
  18.  
  19.     This document describes the TEXTRA commands that may be placed 
  20.     within ARexx scripts and launched from within TEXTRA via the 
  21.     "Utilities, AREXX..." menu item or key-equivalent.
  22.  
  23.     It applies to TEXTRA v1.10 and later.  I'll make every attempt 
  24.     to keep later versions backward-compatible and NOT break any 
  25.     existing scripts later on.
  26.  
  27.     v1.12 - Replace WRAPAT.textra script with PARAGRAPH.textra
  28.           - added File/Window Management section
  29.           - added TEXTRAVERSION command
  30.  
  31.  
  32. A Quick example...
  33.  
  34. A simple script is supplied to illustrate the usage of AREXX 
  35. from TEXTRA.  It is called "Hello.textra" and you should 
  36. place it in your rexx: directory, if you have not already 
  37. done so.  (In fact, copy all the ".textra" files there).
  38.  
  39. If you want to try this out...
  40.  
  41. 1. Launch TEXTRA by double-clicking its icon
  42.    from Workbench.  When the "Open File" requester
  43.    appears, click on the "CANCEL" button.
  44.    
  45. 2. Pull-down the "Utilities, AREXX..." menu item.  Enter
  46.    HELLO (case doesn't matter) into one of the requesters
  47.    and press RETURN.  Watch what happens.
  48.  
  49. ARexx provides a complete programming environment that can 
  50. make full use of the TEXTRA command set.  The TEXTRA user 
  51. may use combinations of AREXX commands, TEXTRA commands, and 
  52. even commands from other applications to 'take control' of 
  53. TEXTRA and probably get it to do things I never dreamed of!
  54.  
  55. I've provided a few ARexx scripts in the TEXTRA distribution 
  56. package.  Specific instructions are provided at the 
  57. beginning of each script...load 'em into TEXTRA & check 'em 
  58. out!  Make SURE to look at SLIDE.textra, EVAL.textra and 
  59. PARAGRAPH.textra...these are really useful tools.
  60.  
  61. Also, there a a couple 'language-specific' directories in the
  62. Scripts directory... these hold scripts that are handy if you
  63. happen to be working in C or Forth.  They too should be placed
  64. in the rexx: directory should you wish to use them.  (NOTE: the
  65. 'Box' & 'UnBox' scripts in the 'C_Scripts' directory were written
  66. by Bernie Cosell and apply to REXX programming, also.)
  67.  
  68. Please feel free to use these as basis for developing your 
  69. own ARexx programs, if you are inclined to such things.  If 
  70. you do, and can see your way clear, please send me a copy of 
  71. your stuff... perhaps it can be included in the standard release
  72. package.
  73.  
  74. Mike Haas
  75. 3867 La Colina Rd.
  76. El Sobrante, CA. 94803
  77.  
  78.  
  79.  
  80. AREXX Scripts containing the TEXTRA commands described in 
  81. this file may reside in either of 2 places:
  82.  
  83. 1. The REXX: directory (if you have one ASSIGNed)
  84.     
  85.                         OR
  86.  
  87.     2. The Textra "startup" directory...
  88.     
  89.        a. If you launch TEXTRA from Workbench, this is the same
  90.           directory that TEXTRA is in.
  91.        
  92.        b. If you run TEXTRA from CLI/Shell, this is the "current
  93.           directory" of the CLI/Shell.
  94.     
  95.  
  96.  
  97. Notes about TEXTRA Command Invocations from ARexx scripts...
  98.  
  99. 1. When specifying strings in TEXTRA commands, encase them 
  100.    in double-quotes, even if there is no whitespace.  
  101.    (Otherwise, ARexx will convert all your characters to 
  102.    UPPER case.  Nice of it, huh?)
  103.  
  104. 2. Script usage is case-INsensitive for the TEXTRA commands 
  105.    and keyword-matching.
  106.  
  107. 3. TEXTRA will sometimes set combinations of 2 pre-defined 
  108.    AREXX variables, RESULT and RC (return code).  Both are 
  109.    strings, RESULT being primarily informational in nature 
  110.    and RC used for error situation return values 
  111.    ('out-of-range value' or 'not found' type error codes).
  112.    
  113.    Note that to retrieve the RESULT string, if used, the 
  114.    AREXX program must have declared OPTIONS RESULTS 
  115.    somewhere previously.  RC is always available and TEXTRA 
  116.    will return 0 in it for a SUCCESS condition or a non-zero 
  117.    value (5 is considered a minor condition, 10 is the more 
  118.    serious type, etc.).
  119.    
  120.    
  121. The remainder of this document is divided into the following
  122. sections, each describing commands related to that topic...
  123.  
  124.    Movement commands
  125.    Set Selected Area
  126.    Operations on Selected Areas
  127.    Interactive commands
  128.    File/Window Management
  129.  
  130. There is some overlap to the functionality of these sections,
  131. so if you're looking for a specific capability, scan everything.
  132.  
  133. The commands themselves...
  134.  
  135.  
  136.  ===================================================================
  137.  Movement Commands
  138.  ===================================================================
  139.  
  140.  
  141.  GOTOXY x y            move cursor to x y position
  142.  
  143.     Place the cursor to the given 'x y' coordinates, where
  144.     'x' is the decimal column position (strting with 0) and 'y'
  145.     is the decimal line number (starting with 0).
  146.     
  147.     'rc' set to:
  148.     
  149.      0 = 'x y' within range of text
  150.      5 = 'x' too large (cursor positioned to end-of-line)
  151.     10 = 'y' too large (no change in cursor/selection)
  152.  
  153.  
  154.  UP   n                cursor up n lines
  155.  
  156.     'rc' set to:
  157.     
  158.      0 = cursor position was successfully changed by at least 1 line
  159.      5 = cursor was at top line to begin with
  160.      
  161.      
  162.  DOWN n                cursor down n lines
  163.  
  164.     'rc' set to:
  165.     
  166.      0 = cursor position was successfully changed by at least 1 line
  167.      5 = cursor was at bottom line to begin with
  168.      
  169.      
  170.  RIGHT n            cursor right n characters (
  171.  
  172.     'rc' set to:
  173.     
  174.      0 = cursor position was successfully changed by at least 1 column
  175.      5 = cursor was at last character in file to begin with
  176.      
  177.      
  178.  LEFT  n            cursor left  n characters
  179.  
  180.     'rc' set to:
  181.     
  182.      0 = cursor position was successfully changed by at least 1 column
  183.      5 = cursor was at first character in file to begin with
  184.      
  185.      
  186.  FIRSTLINE        cursor to beg of file (rc always = 0)
  187.   
  188.  
  189.  LASTLINE        cursor to end of file (rc always = 0)
  190.  
  191.  
  192.  TOP            cursor up to topline of visable page (rc always = 0)
  193.  
  194.  
  195.  BOTTOM            cursor to bottom line of visable page (rc always = 0)
  196.  
  197.  
  198.  CENTER            cursor to middle line (rc always = 0)
  199.  
  200.  
  201.  HOPTO next word    cursor to start of next word
  202.  HOPTO prev word    cursor to END of prev word
  203.  HOPTO next char    cursor to next non-white
  204.  HOPTO prev char     cursor to prev non-white
  205.  HOPTO next blank     cursor to next whitespace char
  206.  HOPTO prev blank     cursor to prev whitespace char
  207.  
  208.     HOPTO moves the cursor to a specific position relative to the
  209.     current cursor or selection location.  The direction and
  210.     ultimate destination position is determined by the keywords
  211.     provided.
  212.  
  213.     'rc' set to:
  214.     
  215.      0 = SUCCESS
  216.     10 = keywords supplied to HOPTO were invalid
  217.      
  218.     if 'rc' = 0, 'result' set to:
  219.     
  220.      "<number>" = cursor column
  221.     "NOT FOUND" = could not HOPTO (at one end of file)
  222.      
  223.  
  224.  
  225.  ===================================================================
  226.  Set Selected Area
  227.  ===================================================================
  228.  
  229.  
  230.  SELECTLINE n        select and display line n
  231.  
  232.     Same as the 'Go to Line...' menu item.  No effect if 'line n'
  233.     is not both a valid decimal number and in range for the file.
  234.     (rc always = 0)
  235.  
  236.  
  237.  FIND "text"        find "text", observe wrap setting
  238.  
  239.     Find and select the specified text.  The search is case-INsensitive.
  240.     
  241.     'result' set to:
  242.     
  243.            "OK" = text has been located, selected and displayed
  244.     "NOT FOUND" = could not be found
  245.     
  246.     (rc always = 0)
  247.  
  248.  
  249.  FINDNEXT
  250.  
  251.     Conducts another search for the same string, see FIND.
  252.  
  253.  
  254.  SELECTTO x y
  255.  
  256.     Used to establish or modify a select range as follows:
  257.     
  258.     - If 'x y' is below the current cursor location or start
  259.       of selection,    'x y' then becomes the new start of selection.
  260.     
  261.     - If 'x y' is after the current cursor location or end of
  262.       selection, 'x y' then becomes the new end of selection.
  263.     
  264.     - If 'x y' is within the current selection, then 'x y' becomes
  265.       the new end of selection.
  266.  
  267.     (rc always = 0)
  268.  
  269.  
  270.  HOPSELECT next word
  271.  HOPSELECT prev word
  272.  HOPSELECT next char
  273.  HOPSELECT prev char
  274.  
  275.     HOPSELECT establishes a selection relative to the current
  276.     cursor or selection location.  The direction and destination
  277.     selection is determined by the keywords    provided.
  278.  
  279.     'rc' set to:
  280.     
  281.      0 = SUCCESS
  282.     10 = keywords supplied to HOPSELECT were invalid
  283.      
  284.     if 'rc' = 0, 'result' set to:
  285.     
  286.      "<number>" = length of selected string
  287.     "NOT FOUND" = could not HOPSELECT (at one end of file)
  288.      
  289.  
  290.  UNSELECT          make sure nothing is selected
  291.  
  292.     If there is a selection, place the cursor at the end of it.
  293.     No effect if nothing selected.
  294.     (rc always = 0)
  295.  
  296.  
  297.  ===================================================================
  298.  Operations on Selected Areas
  299.  ===================================================================
  300.  
  301.  
  302.  CUT
  303.  
  304.     Same as the 'CUT' menu item.  No effect if nothing selected.
  305.     (rc always = 0)
  306.  
  307.  
  308.  COPY
  309.  
  310.     Same as the 'COPY' menu item.  No effect if nothing selected.
  311.     (rc always = 0)
  312.  
  313.  
  314.  PASTE
  315.  
  316.     Same as the 'PASTE' menu item.  No effect if nothing has been
  317.     CUT or COPY'ed. (rc always = 0)
  318.  
  319.  
  320.  KILLSELECT
  321.  
  322.     If a select range exists, delete it.  Do NOT save it in the
  323.     TEXTRA clipboard.  (rc always = 0)
  324.  
  325.     'result' set to:
  326.     
  327.     "OK" if a select range existed.  The cursor will now reside
  328.          where the select range previously began. 
  329.     
  330.     "NO SELECT" = There is no selection.  (nothing is changed)
  331.  
  332.  
  333.  LOCASE
  334.  
  335.     Selected or next word to lower case. (rc always = 0)
  336.  
  337.  
  338.  HICASE
  339.  
  340.     Selected or next word to upper case. (rc always = 0)
  341.  
  342.  
  343.  CAPS
  344.  
  345.     Capitalize the selected or next word. (rc always = 0)
  346.  
  347.  
  348.  ===================================================================
  349.  INTERACTIVE Control
  350.  ===================================================================
  351.  
  352.  
  353.  TEXT token
  354.  
  355.     Inserts the 'token' into the current window at the current
  356.     cursor location.  If a select range exists, it is deleted
  357.     before the insertion. (rc always = 0)
  358.  
  359.  
  360.  TEXTN token
  361.  
  362.     Same as TEXT, but includes a newline after the specified string.
  363.     (rc always = 0)
  364.  
  365.  
  366.  NEWLINE
  367.  
  368.     Inserts a newline into the current window at the current
  369.     cursor location.  If a select range exists, it is deleted
  370.     before the insertion. (rc always = 0)
  371.  
  372.  
  373.  BACKSPACE
  374.  
  375.     Same behavior as the BackSpace key on the keyboard.
  376.     (rc always = 0)
  377.  
  378.  
  379.  DEL
  380.  
  381.     Same behavior as the DEL key on the keyboard.
  382.     (rc always = 0)
  383.  
  384.  
  385.  PREFS attribute action
  386.  
  387.     Perform an action to the specified Edit or Printing Preferences
  388.     attribute.  The action may be to either read and return the
  389.     current setting of the attribute, or set it.
  390.     
  391.     The valid attribute keywords are listed here, along with the
  392.     appropriate action keywords for each...
  393.  
  394.     Usage:   PREFS [AutoIndent]        [read on off]
  395.                    [AutoBackspace]     [read on off]
  396.                    [PrintLineNumbers]  [read on off]
  397.                    [PrintPageHeaders]  [read on off]
  398.                    [TabWidth]          [read <value>]
  399.                    [ConvertCRLF]       [read on off]
  400.     
  401.     If the action is 'read', the returned string will either be
  402.     "ON", "OFF", or "<value>", depending on whether the attribute
  403.     is a 'state' or 'numeric' variable.
  404.     
  405.     example:   PREFS AutoIndent read
  406.                AIstatus = result    /* should be ON or OFF */
  407.                
  408.     If the action is to set the attribute, then the action keyword
  409.     will be either "ON", "OFF" or "<value>", depending on whether
  410.     the attribute is a 'state' or 'numeric' variable.  If the
  411.     attribute is successfully set, the string "OK" will be returned.
  412.  
  413.     example:   PREFS AutoIndent on
  414.                AIstatus = result    /* should be OK */
  415.  
  416.     'rc' set to:
  417.     
  418.      0 = SUCCESS
  419.     10 = keywords supplied to PREFS were invalid
  420.      
  421.     if 'rc' = 0 and action is "read", 'result' set to:
  422.     
  423.         "<number>" = if requested attribute is numeric in nature
  424.      "ON" or "OFF" = if requested attribute is a 'state'
  425.      
  426.  
  427.  GET item attribute
  428.  
  429.     GET is used to aquire information about a certain 'attribute'
  430.     of a particular 'item'.
  431.  
  432.     'rc' set to:
  433.     
  434.      0 = SUCCESS
  435.     10 = keywords supplied to GET were invalid
  436.     
  437.     Assuming the given keyword pairs are valid (in the following list),
  438.     'result' will be set as indicated.
  439.  
  440.     A brief summary of the available reports:
  441.     
  442.     GET    cursor position    - report column & line of cursor
  443.     GET    cursor char        - report character at cursor position
  444.     GET    file name        - get just the filename (no path)
  445.     GET    file path        - get just the file path (no name)
  446.     GET    line <num>        - return text of line
  447.     GET    select position    - return start and end points of select range
  448.     GET    select text        - return the string that is selected
  449.     GET    select next        - used after 'get select text' to get later lines
  450.     
  451.     Specific info about each command...
  452.  
  453.     GET    cursor position
  454.     
  455.         'result' set to:
  456.         
  457.         "x y" = column & line numbers, both 0-based (ex: "0 13"
  458.                 to indicate first column of the fourteenth line).
  459.                 Use "PARSE var result col ' ' line" in AREXX scripts.
  460.         
  461.         "SELECT" = There is no cursor (a selection exists).
  462.     
  463.     GET    cursor char
  464.     
  465.         'result' set to:
  466.         
  467.         "c" = a single-character string (or "-1" if on empty line)
  468.         
  469.         "SELECT" = There is no cursor as a selection exists.
  470.         
  471.     GET    file name        'result' set to "filename"
  472.     
  473.     GET    file path        'result' set to "vol:dir/" or "vol:" format
  474.     
  475.     GET    line <num>
  476.     
  477.         'rc' set to:
  478.         
  479.         10 = <num> is too large (the specified line doesn't exist),
  480.     
  481.         otherwise, 'result' set to:
  482.         
  483.         "line text" = contents of line <num>
  484.         
  485.     GET    select position
  486.     
  487.         'result' set to:
  488.         
  489.         "startx starty endx endy" = select range coordinates.
  490.         
  491.             (For example, "0 0 2 4" indicates that from the first
  492.              column of the first line to the third column of the fifth
  493.              line is selected.  From AREXX, use:
  494.              "PARSE var result ' ' startx ' ' starty ' ' endx ' ' endy")
  495.         
  496.         "NO SELECT" = There is no selection.
  497.         
  498.     GET    select text        "numleft selected text"  |  "NO SELECT"
  499.     
  500.         Used to retrieve the currently selected, or at least
  501.         the component of it that is on the first line.  The
  502.         first portion of the returned string is always the number
  503.         of remaining lines that can be returned via "GET select next".
  504.         This number is always followed by a SPACE character, then the
  505.         selected text on that line.
  506.         
  507.         For example, if "0 Four score" is returned, the caller knows
  508.         that the selection does not extend over 1 line and that the
  509.         selected text is "Four Score".
  510.         
  511.         If "1 seven years ago," is returned, the caller knows
  512.         that the selected text is "seven years ago," and that
  513.         the selection extends over to the next line (see
  514.         "GET select next").
  515.         
  516.         'result' set to:
  517.         
  518.         "<num> selected text" = <num> is number of times to call
  519.                                 "GET select next" (separated by a
  520.                                 SPACE character from the text).
  521.         
  522.         "NO SELECT" = no selection currently exists.
  523.  
  524.     GET    select next        "numleft selected text"  |  "NO SELECT"
  525.         
  526.         Used to retrieve remaining lines, if the previous
  527.         "GET select text" indicated it should be called at all.
  528.         It returns the same format string as "GET select text",
  529.         but will return a 'numleft' component that decreases
  530.         by 1 each time, ultimately to zero.
  531.  
  532.         'result' set to:  same as "GET select text"
  533.         
  534.         NOTE: returns just "0" if called past end of selection.
  535.  
  536.  
  537.  WAITFOR num
  538.  
  539.     Wait for 'num' seconds, where 'num' is a decimal number of
  540.     the form "4.36" or "4".  Minimum resolution is .02 seconds,
  541.     and with the speed AREXX operates at, that should be quite
  542.     sufficient!
  543.  
  544.  
  545.  CLEAR
  546.  
  547.     Delete all text from and blank the current window.
  548.  
  549.  
  550.  NOTIFY "token"
  551.  
  552.     Presents a standard informational 'Please Note!' requester
  553.     to the user and waits for him/her to click the single 'OK'
  554.     button.  The token string is presented in the requester
  555.     and should not exceed 60 characters in length.  Does not
  556.     return a result.  rc always = 0.
  557.  
  558.  
  559.  ASK "token"
  560.  
  561.     Presents a standard 'YES/NO' requester to the user and waits
  562.     for him/her to click on a button.  The token string
  563.     is presented in the requester and should not exceed 60
  564.     characters in length.  rc always = 0.
  565.     
  566.     'result' set to:
  567.     
  568.     "YES" or "NO", depending of course on which button was clicked.
  569.  
  570.  TEXTRAVERSION   (only in v1.12 and later)
  571.  
  572.     Returns a string describing the TEXTRA version, and the
  573.     incremental version of the AREXX interface (increments with
  574.     each modification to the interface code).
  575.     
  576.     format:   major-version minor-version rexxinterface
  577.  
  578.     for example:    1            12             2
  579.  
  580.     "1 12 2" will be returned for v1.12, last 2 indicates
  581.              AREXX interface, rev2.  This should increment with
  582.              every addition, deletion, modification, or fix.
  583.  
  584.  
  585.  ===================================================================
  586.  File/Window Management  (only in v1.12 and later)
  587.  ===================================================================
  588.  
  589.  
  590.  Some of the commands in this section deal with a parameter called
  591.  a 'window-pointer'.  These may be saved by your program and later
  592.  used to select the active window.  They are valid as long as that
  593.  window is open.  This parameter is bound to the window, not the
  594.  file.  As a result, it always describes the same window, even if
  595.  the filename of that window changes (perhaps via SAVEAS).
  596.  
  597.  
  598.  OPENFILE "filename"
  599.  
  600.     Reads in the specified file from disk, unless the file is
  601.     already open.  TEXTRA first expands the "filename" to it's
  602.     full pathname equivalent, then checks the titles of it's
  603.     current windows for a match.
  604.     
  605.     If the specified file is already open, it is brought to the
  606.     front and the cursor is set to 0,0 (just as if the file was
  607.     freshly opened).
  608.     
  609.     If the specified file is not open, and can't be found on the
  610.     disk, an empty window is created and given the specified
  611.     filename.
  612.     
  613.     NOTE: Do not pass a string that describes a directory to 
  614.           OPENFILE.  It will create a window, then present the 
  615.           file requester on that directory,  thereby requiring 
  616.           user input via the mouse.  Currently, OPENFILE does not 
  617.           wait for the selection before returning to the AREXX 
  618.           script, which operates on the window in that condition 
  619.           (with the requester in place).  (This will be protected 
  620.           against in future versions.)
  621.     
  622.     'result' set to:
  623.     
  624.     "window-pointer"  = descriptor to later use to re-select this
  625.                         window (see SELECTWINDOW)
  626.     
  627.     "0"               = window could not be opened
  628.  
  629.  
  630.  FINDFILE "filename"
  631.  
  632.     TEXTRA first expands the "filename" to it's full pathname 
  633.     equivalent, then checks the titles of it's current windows 
  634.     for a match.
  635.     
  636.     If the filename is found, it is brought to the
  637.     front and the associated 'window-pointer' is returned.
  638.     
  639.     FINDFILE is similar to OPENFILE, except that it never
  640.     creates a new window.
  641.     
  642.     'result' set to:
  643.     
  644.     "window-pointer"  = descriptor to later use to re-select this
  645.                         window (see SELECTWINDOW)
  646.     
  647.     "0"               = filename not found as a window title
  648.  
  649.  
  650.  SELECTWINDOW "window-pointer"
  651.  
  652.     The specified window is brought to the front and made
  653.     the current window.
  654.     
  655.     The window-pointer parameter must have been aquired from
  656.     either OPENFILE or FINDFILE, and the window must still be
  657.     open.
  658.  
  659.  
  660.  SAVEAS "filename"
  661.  
  662.     The currently selected window is saved to disk under the
  663.     specified name.
  664.     
  665.     If the specified filename is a single asterisk, i.e. "*",
  666.     the file will be written under the currently existing
  667.     filename (equivalent to a SAVE operation).
  668.     
  669.     'result' set to:
  670.     
  671.     "OK"             = file successfully written
  672.     "ERROR"          = some error occured, file not saved
  673.     "NOT FOUND"      = "filename" either describes a directory
  674.                        or contains an invalid pathname component
  675.     "FILE NOT NAMED" = a "*" has been specified, but the file has
  676.                        never been given a name
  677.     
  678.