@DATABASE "ARB53"
@INDEX "ARB:Misc/Index.Text/Main"
@HELP "ARB:Misc/Help/Main"
@NODE "Main" "ARexx For Beginners - Article 53 - Using ARexx With ED Pt 2"

@{B}@{U}@{JCENTER}AREXX FOR BEGINNERS

ARTICLE 53 - USING AREXX WITH ED PART 2

BY FRANK BUNTON@{UB}@{UU}

@{" COPYRIGHT © FRANK P. BUNTON 1995-1998 " LINK "ARB:Misc/Read_Me_First!!/Copyright"}
@{JLEFT}

The methods of running an ARexx program from within the Ed program are
discussed in @{"the last article" LINK "ARB:Articles_51-60/52.ARexx_With_Ed_Pt-1/MAIN"}.

This article will deal with using the Ed commands in an ARexx program.
@{JCENTER}

@{" The ED Port Name                                   " LINK "Port"}
@{" The ED Extended Commands                           " LINK "Extended"}
@{" Sending Extended Commands From Within ED           " LINK "Sending"}
@{" Using ED Extended Commands Within an ARexx Program " LINK "Using"}
@{" The RV Extended Command                            " LINK "RV"}
@{" Example Programs Of Practical Use                  " LINK "Example"}


@{JCENTER}=== End of Text ===
@{JLEFT}
@ENDNODE

@NODE "Port" "Article 53 - Using ARexx With ED Pt 2 - ED Port Name"

@{B}@{U}@{JCENTER}THE ED PORT NAME@{UB}@{UU}
@{JLEFT}
I have already covered the fact that "ED" can have more than one copy
running at the same time so that a number of text files can be edited
simultaneously. When this is so, the port names are:-

   Ed    Ed_1    Ed_2    Ed_3    etc.

Reread @{"Article 24" LINK "ARB:Articles_21-30/24.Talking-Programs-2/Address()"116} to see how to pick up the port name for the particular
copy of "ED" that you are to use ARexx with.


@{JCENTER}=== End of Text ===
@{JLEFT}
@ENDNODE

@NODE "Extended" "Article 53 - Using ARexx With ED Pt 2 - ED Extended Commands"

@{B}@{U}THE ED EXTENDED COMMANDS@{JCENTER}@{UB}@{UU}
@{JLEFT}
Once the port has been addressed, you can send to ED a lot of ED's "extended
commands". These are the commands entered into ED after pressing the ESC
key. It is not practical to discuss all these commands here. Read your
Amiga manuals if you do not know them. However, the most common ones
are:-

  X - to save the text to disk then exit ED
  Q - to exit ED without saving the text
  F - to find text within the file

and some I will talk about in this article are:-

 SF - to set up a function key
 RV - to set up the special compound symbol to hold information about ED
 RX - to start an ARexx program

There are two ways that these extended commands can be used:-

  @{" From Within ED Itself         " LINK "Sending"}
  @{" From Within an ARexx Program  " LINK "Using"}

There is also a section on:-

  @{" Using The RV Extended Command " LINK "RV"}


@{JCENTER}=== End of Text ===
@{JLEFT}
@ENDNODE

@NODE "Sending" "Article 53 - Using ARexx With ED Pt 2 - Sending Extended Commands From In ED"

@{B}@{U}@{JCENTER}SENDING EXTENDED COMMANDS FROM WITHIN ED@{UB}@{UU}
@{JLEFT}
Before seeing how to send Ed's extended commands @{"from an ARexx program" LINK "Using"},
we first need to understand how to send them from within ED itself. This
will help us to understand how to send them from an ARexx program.

When the ESC key is pressed from within an ED window, an asterisk appears
in the bottom left of the ED window. This is the spot at which you enter
the extended commands. You just type in the extended command line and
press return.

Some extended commands are used on their own without @{"arguments" LINK "ARB:Misc/Glossary/Arguments"} and others
need an argument @{"string" LINK "ARB:Misc/Glossary/Strings"} to come after them.

If the extended command is one that does not need an argument then it
is entered on its own without using any string delimiters. For
example:-

  X

(to save the file to disk and exit from ED)

If the extended command is one that requires a string argument after it
then you put the argument within @{"Ed Style delimiters" LINK "ARB:Articles_51-60/52.ARexx_With_Ed_Pt-1/Delimiters"}. For example:-

  F "text"

(to find "text" within the document being edited)

There are also times when one string must be contained within another
string. In this case, you must use two different types of string delimiters.
For example:-

  SF 1 "RX 'rexx:ProgramName'"

In this example, the SF command sets up function key number 1 so that
pressing F1 will act in the same way as if the string following the "SF
1" were entered as an extended command after pressing ESC. Thus if the
above definition were given to F1 then the extended command line:-

  RX 'rexx:ProgramName'

would be used.

As you can see, we have used the extended command "RX" @{B}within@{UB} the extended
command "SF" and each must have their own separate string
delimiters.


@{JCENTER}=== End of Text ===
@{JLEFT}
@ENDNODE

@NODE "Using" "Article 53 - Using ARexx With ED Pt 2 - Extended Commands In Programs"

@{B}@{U}USING ED EXTENDED COMMANDS WITHIN AN AREXX PROGRAM@{JCENTER}@{UB}@{UU}
@{JLEFT}
Before sending commands to ED, it must be ADDRESSed by using:-

  HostName = ADDRESS()
  ADDRESS Hostname

@{"Click here" LINK "ARB:Articles_21-30/24.Talking-Programs-2/Address()"116} for an explanation of these two lines.

Once having set up ED as the host, you can proceed with sending any of
ED's extended commands to that port name.

The extended command line sent to ED from an ARexx program is exactly
the same as it would be if you entered it in @{"direct mode" LINK "Sending"}, i.e. after
pressing ESC. However, @{B}the whole@{UB} of the extended command line must be seen
by the ARexx program as the @{B}one single string@{UB} and therefore @{B}must@{UB} be
enclosed in ARexx style @{"delimiters" LINK "ARB:Misc/Glossary/Strings"15}.

In other words, you @{B}must only use@{UB} one of the delimiters " or '.

These delimiters are for @{B}ARexx usage only.@{UB} They are @{B}not@{UB} sent to ED.

However, you must remember that any @{"Ed style string delimiters" LINK "ARB:Articles_51-60/52.ARexx_With_Ed_Pt-1/Delimiters"} that are
used @{B}within@{UB} the ARexx string @{B}must@{UB} be different to the ARexx string
delimiters that you use in your program. For example, your ARexx program
could @{B}legitimately@{UB} include this line:-

  'F "text"'

In this case, the command line sent to ED would be:-

  F "text"

However, you could @{B}NOT@{UB} legitimately use:-

  "F "text""

as ARexx would see this line as three different tokens:-

- a string consisting of "F" followed by a space

- a symbol named TEXT

- A null string which is nothing between two ""


@{JCENTER}=== End of Text ===
@{JLEFT}
@ENDNODE

@NODE "RV" "Article 53 - Using ARexx With ED Pt 2 - RV Extended Command"

@{B}@{U}@{JCENTER}THE RV EXTENDED COMMAND@{UB}@{UU}
@{JLEFT}
ED has an extended command "RV" that sets up an array of compound symbols
containing a lot of information about the ED program. Its usage is:-

  RV "StemName"

Thus, if you want to use a stem named "info" you would use this line in
your ARexx program:-

  'RV "info"'

Once this line has been sent to ED you can recover information in these
compound symbol names:-

  Stemname.Left          Current left margin
  Stemname.Right         Current right margin
  Stemname.TabStop       Current tab stop setting
  Stemname.LMax          Maximum visible line in window
  Stemname.Width         Width of window in characters
  Stemname.X             Current X position of cursor in window
                           (1 = left most edge)
  Stemname.Y             Current Y position of cursor in window
                           (1 = top most line)
  Stemname.Base          Window base (normally 0 but non-zero when screen
                           is shifted to the right.)
  Stemname.Extend        Extended margin value
  Stemname.ForceCase     Case sensitivity flag used in searches
  Stemname.Line          Current line number in file
                           (1 = first line)
  Stemname.FileName      Name of file being edited
  Stemname.Current       Text of the current line
  Stemname.LastCmd       Last extended command used
  Stemname.Search        Last string searched for

The things to remember are:-

- You can use @{B}any@{UB} @{"legitimate stem name" LINK "ARB:Articles_21-30/29.Compound_Symbols/Naming"}

- You @{B}must@{UB} use the @{B}exact@{UB} part names that are shown above.
  (i.e. the parts that come after the "Stemname."
  However, the CASE is irrelevant.

Thus you could use:-

  Info.X
  Info.y
  Info.CurrENT

etc.

The following example illustrates these items

  /* Example53-1.ed */

  Host = ADDRESS()
  ADDRESS VALUE Host

  'RV "Info"'

  SAY 'Left margin setting       =' Info.Left
  SAY 'Right margin setting      =' Info.Right
  SAY 'Current tab stop          =' Info.TabStop
  SAY 'Max visible lines         =' Info.LMax
  SAY 'Width of window           =' Info.Width
  SAY 'Current X cursor position =' Info.X
  SAY 'Current Y cursor position =' Info.Y
  SAY 'Window Base               =' Info.Base
  SAY 'Extended margin           =' Info.Extend
  SAY 'Case sensitivity flag     =' Info.ForceCase
  SAY 'Current line number       =' Info.Line
  SAY 'Current file name         =' Info.FileName
  SAY 'Text of current line      =' Info.Current
  SAY 'Last extended command     =' Info.LastCmd
  SAY 'Last string search        =' Info.Search


This program @{B}must be run from within ED, NOT from a Shell/CLI window!!@{UB}

The simplest way to do this is to go to a Shell/CLI window and enter:-

  > CD ARB:Articles_51-60

Now start up ED from that window. It would be best to have a file loaded
into ED so that you can see that the above program is picking up line
numbers and text of lines. Any file will do as long as it is a plain ASCII
file. The example of this program's output shown below relates to the
text file that is "Example53-1.ed" itself.

ED will have the same current directory as the Shell/CLI window from which
it was started so, to run the above example program, simply press ESC
and enter at the asterisk:-

  RX "Example53-1"

Note that the ".ed" suffix is @{B}not@{UB} needed as ED will look for programs
with that suffix.

Move the cursor around in the ed window to different places and rerun
the program to see the changing values of some of the array components.
(Tip - Pressing CTRL-G in ED will repeat the last extended command so
you don't have to press ESC and enter the above RX command line all the
time.) You could also try changing the size and shape of the ED window
to see the changes in output.

The output of the ARexx program should appear in the Shell/CLI window
from which the ED program was launched. However, if you start up ED by
using the Workbench "Execute Command" menu item then the system will open
a new output window for the ARexx program to use for its output. If you
start ED this way, you will need to include the @{B}full path name@{UB} for the
program:-

  RX "ARB:Articles_51-60/Example53-1"

Its output will look something like the following, which was obtained
while ED was holding the text of the above example and the cursor was
on the first character of the first line:-

  Left margin setting       = 1
  Right margin setting      = 77
  Current tab stop          = 3
  Max visible lines         = 11
  Width of window           = 76
  Current X cursor position = 1
  Current Y cursor position = 1
  Window Base               = 0
  Extended margin           = 0
  Case sensitivity flag     = 0
  Current line number       = 1
  Current file name         = example53-1.ed
  Text of current line      = /* Example53-1.ed */
  Last extended command     = RX "Example53-1"
  Last string search        =

If the cursor is on the last character of the last line then this will
be the output:-

  left margin setting       = 1
  Right margin setting      = 77
  Current tab stop          = 3
  Max visible lines         = 10
  Width of window           = 75
  Current X cursor position = 46
  Current Y cursor position = 11
  Window Base               = 0
  Extended margin           = 0
  Case sensitivity flag     = 0
  Current line number       = 21
  Current file name         = example53-1.ed
  Text of current line      = SAY 'Last string search        =' Info.Search
  Last extended command     = RX "Example53-1"
  Last string search        =

You may get a different number for "Current Y cursor position".

In the first listing, @{B}Current Y cursor position@{UB} was the same as @{B}Current
Line Number@{UB} but this time it is different.

This is because:-

- the @{B}Y position@{UB} refers to the line number
  @{B}within the text displayed in the window.@{UB}

- the @{B}current line@{UB} refers to the line number
  @{B}within the total document@{UB}.

Thus if the first line in the window is the 12th line of the text file,
and the cursor is on this line, the outputs will be:-

  Current Y cursor position = 1

  Current line number       = 12

@{"Click here" LINK "Example"} to read about examples that are of more practical use.

@{JCENTER}=== End of Text ===
@{JLEFT}
@ENDNODE

@NODE "Example" "Article 53 - Using ARexx With ED Pt 2 - Practical Example Programs"

@{B}@{U}@{JCENTER}PRACTICAL EXAMPLE PROGRAMS@{UB}@{UU}
@{JLEFT}
Although it demonstrates the use of the "RV" command, the @{"above example"  LINK "RV"52}
is of no practical use.

@{"Article 54" LINK "ARB:Articles_51-60/54.ARexx_With_Ed_Transpose/MAIN"} discusses a program that will transpose two characters within
the text held by Ed. For example, it can change "teh" into "the".

@{"Article 55" LINK "ARB:Articles_51-60/55.ARexx_With_Ed_SearchReplace/MAIN"} discusses a program that adds a "proper" search and replace
function to Ed.


@{JCENTER}=== End of Text ===
@{JLEFT}
@ENDNODE