home *** CD-ROM | disk | FTP | other *** search
/ Otherware / Otherware_1_SB_Development.iso / amiga / misc / textra.lzh / textra / docs / RexxCommand.doc next >
Text File  |  1991-10-23  |  15KB  |  565 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 to 
  24. keep later versions backward-compatible and NOT break any 
  25. existing scripts later on.
  26.  
  27.  
  28.  
  29.  
  30. A Quick example...
  31.  
  32. A simple script is supplied to illustrate the usage
  33. of AREXX from TEXTRA.  It is called "Hello.textra"
  34. and you should place it in your rexx: directory, if you
  35. have not already done so.  (In fact, copy all the ".textra"
  36. files there).
  37.  
  38. If you want to try this out...
  39.  
  40. 1. Launch TEXTRA by double-clicking its icon
  41.    from Workbench.  When the "Open File" requester
  42.    appears, click on the "CANCEL" button.
  43.    
  44. 2. Pull-down the "Utilities, AREXX..." menu item.  Enter
  45.    HELLO (case doesn't matter) into one of the requesters
  46.    and press RETURN.  Watch what happens.
  47.  
  48. ARexx provides a complete programming environment that can make
  49. full use of the TEXTRA command set.  The TEXTRA user may use
  50. combinations of AREXX commands, TEXTRA commands, and even commands
  51. from other applications to 'take control' of TEXTRA and probably
  52. get it to do things I never dreamed of!
  53.  
  54. I've provided a few ARexx scripts in the TEXTRA distribution
  55. package.  Specific instructions are provided at the beginning of each
  56. script...load 'em into TEXTRA & check 'em out!  Make SURE to
  57. look at SLIDE.textra, EVAL.textra and WRAPAT.textra...these are
  58. really useful tools.
  59.  
  60. Please feel free to use these as basis for developing
  61. your own ARexx programs, if you are inclined to such things.
  62. If you do, and can see your way clear, please send me a copy of
  63. your stuff.  (a little payback for TEXTRA, maybe?)
  64.  
  65. Mike Haas
  66. 3867 La Colina Rd.
  67. El Sobrante, CA. 94803
  68.  
  69.  
  70.  
  71. AREXX Scripts containing the TEXTRA commands described in this
  72. file may reside in either of 2 places:
  73.  
  74.     1. The Textra "startup" directory...
  75.     
  76.        a. If you launch TEXTRA from Workbench, this is the same
  77.           directory that TEXTRA is in.
  78.        
  79.        b. If you run TEXTRA from CLI/Shell, this is the "current
  80.           directory" of the CLI/Shell.
  81.     
  82.     2. The REXX: directory (if you have one ASSIGNed)
  83.  
  84.  
  85.  
  86. Notes about TEXTRA Command Invocations from ARexx scripts...
  87.  
  88. 1. When specifying strings in TEXTRA commands, encase them in
  89.    double-quotes, even if there is no whitespace.  (Otherwise,
  90.    ARexx will convert all your characters to UPPER case.  Nice
  91.    of it, huh?)
  92.  
  93. 2. Script usage is case-INsensitive for the TEXTRA commands and
  94.    keyword-matching.
  95.  
  96. 3. TEXTRA will sometimes set combinations of 2 pre-defined AREXX
  97.    variables, RESULT and RC (return code).  Both are strings,
  98.    RESULT being primarily informational in nature and RC used
  99.    for error situation return values ('out-of-range value' or
  100.    'not found' type error codes).
  101.    
  102.    Note that to retrive the RESULT string, if used, the AREXX program
  103.    must have declared OPTIONS RESULTS somewhere previously.  RC is
  104.    always available and TEXTRA will return 0 in it for a SUCCESS
  105.    condition or a non-zero value (5 is considered a minor
  106.    condition, 10 is the more serious type, etc.).
  107.    
  108.  
  109.  
  110. LIMITATIONS...
  111.  
  112.    This is the first release of an AREXX interface into TEXTRA.
  113.    I've tried to provide a comprehensive set of editing commands
  114.    to operate on one window (the currently selected one).
  115.    Enhancement suggestions welcome.
  116.    
  117.    At present, there is no capability for an ARexx script to
  118.    change the selected window, open another window, revert or
  119.    save any window (including the selected one).  All forthcoming.
  120.    In time.
  121.    
  122.    See the associated 'KnownProblems.doc' file for a more detailed
  123.    description of things to be careful of.
  124.    
  125.    Have fun & SEND ME YOUR STUFF!!!!!
  126.  
  127.  
  128. The commands themselves...
  129.  
  130.  
  131.  ===================================================================
  132.  Movement Commands
  133.  ===================================================================
  134.  
  135.  
  136.  GOTOXY x y            move cursor to x y position
  137.  
  138.     Place the cursor to the given 'x y' coordinates, where
  139.     'x' is the decimal column position (strting with 0) and 'y'
  140.     is the decimal line number (starting with 0).
  141.     
  142.     'rc' set to:
  143.     
  144.      0 = 'x y' within range of text
  145.      5 = 'x' too large (cursor positioned to end-of-line)
  146.     10 = 'y' too large (no change in cursor/selection)
  147.  
  148.  
  149.  UP   n                cursor up n lines
  150.  
  151.     'rc' set to:
  152.     
  153.      0 = cursor position was successfully changed by at least 1 line
  154.      5 = cursor was at top line to begin with
  155.      
  156.      
  157.  DOWN n                cursor down n lines
  158.  
  159.     'rc' set to:
  160.     
  161.      0 = cursor position was successfully changed by at least 1 line
  162.      5 = cursor was at bottom line to begin with
  163.      
  164.      
  165.  RIGHT n            cursor right n characters (
  166.  
  167.     'rc' set to:
  168.     
  169.      0 = cursor position was successfully changed by at least 1 column
  170.      5 = cursor was at last character in file to begin with
  171.      
  172.      
  173.  LEFT  n            cursur left  n characters
  174.  
  175.     'rc' set to:
  176.     
  177.      0 = cursor position was successfully changed by at least 1 column
  178.      5 = cursor was at first character in file to begin with
  179.      
  180.      
  181.  FIRSTLINE        cursor to beg of file (rc always = 0)
  182.   
  183.  
  184.  LASTLINE        cursor to end of file (rc always = 0)
  185.  
  186.  
  187.  TOP            cursor up to topline of visable page (rc always = 0)
  188.  
  189.  
  190.  BOTTOM            cursor to bottom line of visable page (rc always = 0)
  191.  
  192.  
  193.  CENTER            cursor to middle line (rc always = 0)
  194.  
  195.  
  196.  HOPTO next word    cursor to start of next word
  197.  HOPTO prev word    cursor to END of prev word
  198.  HOPTO next char    cursor to next non-white
  199.  HOPTO prev char     cursor to prev non-white
  200.  HOPTO next blank     cursor to next whitespace char
  201.  HOPTO prev blank     cursor to prev whitespace char
  202.  
  203.     HOPTO moves the cursor to a specific position relative to the
  204.     current cursor or selection location.  The direction and
  205.     ultimate destination position is determined by the keywords
  206.     provided.
  207.  
  208.     'rc' set to:
  209.     
  210.      0 = SUCCESS
  211.     10 = keywords supplied to HOPTO were invalid
  212.      
  213.     if 'rc' = 0, 'result' set to:
  214.     
  215.      "<number>" = cursor column
  216.     "NOT FOUND" = could not HOPTO (at one end of file)
  217.      
  218.  
  219.  
  220.  ===================================================================
  221.  Set Selected Area
  222.  ===================================================================
  223.  
  224.  
  225.  SELECTLINE n        select and display line n
  226.  
  227.     Same as the 'Go to Line...' menu item.  No effect if 'line n'
  228.     is not both a valid decimal number and in range for the file.
  229.     (rc always = 0)
  230.  
  231.  
  232.  FIND "text"        find "text", observe wrap setting
  233.  
  234.     Find and select the specified text.  The search is case-INsensitive.
  235.     
  236.     'result' set to:
  237.     
  238.            "OK" = text has been located, selected and displayed
  239.     "NOT FOUND" = could not be found
  240.     
  241.     (rc always = 0)
  242.  
  243.  
  244.  FINDNEXT
  245.  
  246.     Conducts another search for the same string, see FIND.
  247.  
  248.  
  249.  SELECTTO x y
  250.  
  251.     Used to establish or modify a select range as follows:
  252.     
  253.     - If 'x y' is below the current cursor location or start
  254.       of selection,    'x y' then becomes the new start of selection.
  255.     
  256.     - If 'x y' is after the current cursor location or end of
  257.       selection, 'x y' then becomes the new end of selection.
  258.     
  259.     - If 'x y' is within the current selection, then 'x y' becomes
  260.       the new end of selection.
  261.  
  262.     (rc always = 0)
  263.  
  264.  
  265.  HOPSELECT next word
  266.  HOPSELECT prev word
  267.  HOPSELECT next char
  268.  HOPSELECT prev char
  269.  
  270.     HOPSELECT establishes a selection relative to the current
  271.     cursor or selection location.  The direction and destination
  272.     selection is determined by the keywords    provided.
  273.  
  274.     'rc' set to:
  275.     
  276.      0 = SUCCESS
  277.     10 = keywords supplied to HOPSELECT were invalid
  278.      
  279.     if 'rc' = 0, 'result' set to:
  280.     
  281.      "<number>" = length of selected string
  282.     "NOT FOUND" = could not HOPSELECT (at one end of file)
  283.      
  284.  
  285.  UNSELECT          make sure nothing is selected
  286.  
  287.     If there is a selection, place the cursor at the end of it.
  288.     No effect if nothing selected.
  289.     (rc always = 0)
  290.  
  291.  
  292.  ===================================================================
  293.  Operations on Selected Areas
  294.  ===================================================================
  295.  
  296.  
  297.  CUT
  298.  
  299.     Same as the 'CUT' menu item.  No effect if nothing selected.
  300.     (rc always = 0)
  301.  
  302.  
  303.  COPY
  304.  
  305.     Same as the 'COPY' menu item.  No effect if nothing selected.
  306.     (rc always = 0)
  307.  
  308.  
  309.  PASTE
  310.  
  311.     Same as the 'PASTE' menu item.  No effect if nothing has been
  312.     CUT or COPY'ed. (rc always = 0)
  313.  
  314.  
  315.  KILLSELECT
  316.  
  317.     If a select range exists, delete it.  Do NOT save it in the
  318.     TEXTRA clipboard.  (rc always = 0)
  319.  
  320.     'result' set to:
  321.     
  322.     "OK" if a select range existed.  The cursor will now reside
  323.          where the select range previously began. 
  324.     
  325.     "NO SELECT" = There is no selection.  (nothing is changed)
  326.  
  327.  
  328.  LOCASE
  329.  
  330.     Selected or next word to lower case. (rc always = 0)
  331.  
  332.  
  333.  HICASE
  334.  
  335.     Selected or next word to upper case. (rc always = 0)
  336.  
  337.  
  338.  CAPS
  339.  
  340.     Capitalize the selected or next word. (rc always = 0)
  341.  
  342.  
  343.  ===================================================================
  344.  INTERACTIVE Control
  345.  ===================================================================
  346.  
  347.  
  348.  TEXT token
  349.  
  350.     Inserts the 'token' into the current window at the current
  351.     cursor location.  If a select range exists, it is deleted
  352.     before the insertion. (rc always = 0)
  353.  
  354.  
  355.  TEXTN token
  356.  
  357.     Same as TEXT, but includes a newline after the specified string.
  358.     (rc always = 0)
  359.  
  360.  
  361.  NEWLINE
  362.  
  363.     Inserts a newline into the current window at the current
  364.     cursor location.  If a select range exists, it is deleted
  365.     before the insertion. (rc always = 0)
  366.  
  367.  
  368.  BACKSPACE
  369.  
  370.     Same behavior as the BackSpace key on the keyboard.
  371.     (rc always = 0)
  372.  
  373.  
  374.  DEL
  375.  
  376.     Same behavior as the DEL key on the keyboard.
  377.     (rc always = 0)
  378.  
  379.  
  380.  PREFS attribute action
  381.  
  382.     Perform an action to the specified Edit or Printing Preferences
  383.     attribute.  The action may be to either read and return the
  384.     current setting of the attribute, or set it.
  385.     
  386.     The valid attribute keywords are listed here, along with the
  387.     appropriate action keywords for each...
  388.  
  389.     Usage:   PREFS [AutoIndent]        [read on off]
  390.                    [AutoBackspace]     [read on off]
  391.                    [PrintLineNumbers]  [read on off]
  392.                    [PrintPageHeaders]  [read on off]
  393.                    [TabWidth]          [read <value>]
  394.                    [ConvertCRLF]       [read on off]
  395.     
  396.     If the action is 'read', the returned string will either be
  397.     "ON", "OFF", or "<value>", depending on whether the attribute
  398.     is a 'state' or 'numeric' variable.
  399.     
  400.     example:   PREFS AutoIndent read
  401.                AIstatus = result    /* should be ON or OFF */
  402.                
  403.     If the action is to set the attribute, then the action keyword
  404.     will be either "ON", "OFF" or "<value>", depending on whether
  405.     the attribute is a 'state' or 'numeric' variable.  If the
  406.     attribute is successfully set, the string "OK" will be returned.
  407.  
  408.     example:   PREFS AutoIndent on
  409.                AIstatus = result    /* should be OK */
  410.  
  411.     'rc' set to:
  412.     
  413.      0 = SUCCESS
  414.     10 = keywords supplied to PREFS were invalid
  415.      
  416.     if 'rc' = 0 and action is "read", 'result' set to:
  417.     
  418.         "<number>" = if requested attribute is numeric in nature
  419.      "ON" or "OFF" = if requested attribute is a 'state'
  420.      
  421.  
  422.  GET item attribute
  423.  
  424.     GET is used to aquire information about a certain 'attribute'
  425.     of a particular 'item'.
  426.  
  427.     'rc' set to:
  428.     
  429.      0 = SUCCESS
  430.     10 = keywords supplied to GET were invalid
  431.     
  432.     Assuming the given keyword pairs are valid (in the following list),
  433.     'result' will be set as indicated.
  434.  
  435.     A brief summary of the available reports:
  436.     
  437.     GET    cursor position    - report column & line of cursor
  438.     GET    cursor char        - report character at cursor position
  439.     GET    file name        - get just the filename (no path)
  440.     GET    file path        - get just the file path (no name)
  441.     GET    line <num>        - return text of line
  442.     GET    select position    - return start and end points of select range
  443.     GET    select text        - return the string that is selected
  444.     GET    select next        - used after 'get select text' to get later lines
  445.     
  446.     Specific info about each command...
  447.  
  448.     GET    cursor position
  449.     
  450.         'result' set to:
  451.         
  452.         "x y" = column & line numbers, both 0-based (ex: "0 13"
  453.                 to indicate first column of the fourteenth line).
  454.                 Use "PARSE var result col ' ' line" in AREXX scripts.
  455.         
  456.         "SELECT" = There is no cursor (a selection exists).
  457.     
  458.     GET    cursor char
  459.     
  460.         'result' set to:
  461.         
  462.         "c" = a single-character string (or "-1" if on empty line)
  463.         
  464.         "SELECT" = There is no cursor as a selection exists.
  465.         
  466.     GET    file name        'result' set to "filename"
  467.     
  468.     GET    file path        'result' set to "vol:dir/" or "vol:" format
  469.     
  470.     GET    line <num>
  471.     
  472.         'rc' set to:
  473.         
  474.         10 = <num> is too large (the specified line doesn't exist),
  475.     
  476.         otherwise, 'result' set to:
  477.         
  478.         "line text" = contents of line <num>
  479.         
  480.     GET    select position
  481.     
  482.         'result' set to:
  483.         
  484.         "startx starty endx endy" = select range coordinates.
  485.         
  486.             (For example, "0 0 2 4" indicates that from the first
  487.              column of the first line to the third column of the fifth
  488.              line is selected.  From AREXX, use:
  489.              "PARSE var result ' ' startx ' ' starty ' ' endx ' ' endy")
  490.         
  491.         "NO SELECT" = There is no selection.
  492.         
  493.     GET    select text        "numleft selected text"  |  "NO SELECT"
  494.     
  495.         Used to retrieve the currently selected, or at least
  496.         the component of it that is on the first line.  The
  497.         first portion of the returned string is always the number
  498.         of remaining lines that can be returned via "GET select next".
  499.         This number is always followed by a SPACE character, then the
  500.         selected text on that line.
  501.         
  502.         For example, if "0 Four score" is returned, the caller knows
  503.         that the selection does not extend over 1 line and that the
  504.         selected text is "Four Score".
  505.         
  506.         If "1 seven years ago," is returned, the caller knows
  507.         that the selected text is "seven years ago," and that
  508.         the selection extends over to the next line (see
  509.         "GET select next").
  510.         
  511.         'result' set to:
  512.         
  513.         "<num> selected text" = <num> is number of times to call
  514.                                 "GET select next" (separated by a
  515.                                 SPACE character from the text).
  516.         
  517.         "NO SELECT" = no selection currently exists.
  518.  
  519.     GET    select next        "numleft selected text"  |  "NO SELECT"
  520.         
  521.         Used to retrieve remaining lines, if the previous
  522.         "GET select text" indicated it should be called at all.
  523.         It returns the same format string as "GET select text",
  524.         but will return a 'numleft' component that decreases
  525.         by 1 each time, ultimately to zero.
  526.  
  527.         'result' set to:  same as "GET select text"
  528.         
  529.         NOTE: returns just "0" if called past end of selection.
  530.  
  531.  
  532.  WAITFOR num
  533.  
  534.     Wait for 'num' seconds, where 'num' is a decimal number of
  535.     the form "4.36" or "4".  Minimum resolution is .02 seconds,
  536.     and with the speed AREXX operates at, that should be quite
  537.     sufficient!
  538.  
  539.  
  540.  CLEAR
  541.  
  542.     Delete all text from and blank the current window.
  543.  
  544.  
  545.  NOTIFY "token"
  546.  
  547.     Presents a standard informational 'Please Note!' requester
  548.     to the user and waits for him/her to click the single 'OK'
  549.     button.  The token string is presented in the requester
  550.     and should not exceed 60 characters in length.  Does not
  551.     return a result.  rc always = 0.
  552.  
  553.  
  554.  ASK "token"
  555.  
  556.     Presents a standard 'YES/NO' requester to the user and waits
  557.     for him/her to click on a button.  The token string
  558.     is presented in the requester and should not exceed 60
  559.     characters in length.  rc always = 0.
  560.     
  561.     'result' set to:
  562.     
  563.     "YES" or "NO", depending of course on which button was clicked.
  564.  
  565.