
    RexxTool.cmd is a multi-function tool for Rexx. Most of the functions
    are things I needed at one time or another, but I have added some
    variations that I thought other people might want.

    Formatting Rexx code was the original purpose. It will indent lines
    correctly, correct the capitalization of variables and functions,
    and space words and symbols consistently. It can move THEN and THEN DO
    to fit the style you prefer. It can reformat comments in several ways.
    It can insert header and footer comments for routines. It can wrap
    some long lines to fit the page width, but not all of them.

    It will also check for some common mistakes, including unbalanced quotes,
    comments, and parentheses; unbalanced DO/END pairs; duplicate labels;
    and some cmd.exe or 4OS2 commands that I am likely to type by mistake.
    It will also warn about constructions that are not strictly errors but
    that I prefer to avoid.

    As a code analyzer, it will show all the subroutines, where they are called
    from and which external procedures and built-in functions they call. It can
    draw a tree diagram of a program or part of it, showing where each
    subroutine is used. It can show the external routines, built-in functions,
    and libraries a program depends on. It can show all the variables and where
    they are used. It can also extract one part of a program with all the
    procedures it depends on. It can insert code to count how many times each
    procedure is called.

    I have tried to make it practical for people to add more functions to it.

    Using it:
      The command line syntax is
           RexxTool.cmd <command> <filename> [<output filename>] [options]

      To start, try reformatting a Rexx script with the default options:
           RexxTool.cmd format OldFile.cmd NewFile.cmd

      RexxTool.cmd is written in my own particular style:
           RexxTool.cmd format OldFile.cmd NewFile.cmd -style=akm

      or you might prefer
           RexxTool.cmd format OldFile.cmd NewFile.cmd -style=alternate

      but those are just examples; all the individual options can be changed
      on the command line. For a list of options type
           RexxTool.cmd -config

      For more detailed documentation about formatting, type
           RexxTool.cmd help format

      To simply check for errors, type
           RexxTool.cmd checkonly OldFile.cmd -check=all
      which is the same as
           RexxTool.cmd checkonly OldFile.cmd -check=error,warn,4os2,style,expose

      You might also try
           RexxTool.cmd tree FileName.cmd
      which will draw a nice diagram showing where routines are called

      for a list of other commands, type
           RexxTool.cmd help

      All commands are safe to use; the original file is never changed.

      Most commands have additional switches to control what is done or how
      information is shown

      Most of the documentation is extracted from the comments inside
      RexxTool.cmd. It doesn't look elegant, but it is easier for me to
      maintain this way.
      Try
           RexxTool.cmd help              for some basic help
           RexxTool.cmd -config           for a list of command-line switches
                                          and their current values
           RexxTool.cmd help <subject>    for a longer explanation of a switch
                                          or command
           RexxTool.cmd help all          for information about all subjects,
                                          which is probably more than you
                                          really want. The file RexxTool.help
                                          is the output of this command.

   Bugs:
      There's sure to be some. The only ones I know of are minor cosmetic
      things. But it has not been tested well on writing styles other than
      my own. Feedback and bug reports are welcome. Bug fixes are even
      more welcome.

   Limitations:
      RexxTool.cmd is intended for the original ("Classic" or RexxSAA)
      Rexx for OS/2. It does not understand Object Rexx.

      It should also work for Regina Rexx on OS/2 and Linux, but see
      Regina.txt. I have not tried it with Regina/Windows.

      It expects more-or-less valid Rexx code. If the error-checking task
      reports errors, you might want to fix the mistakes before accepting
      the reformatted text.

      Under OS/2 Rexx, a couple of commands may fail on a file with deeply-nested
      subroutines (about 30 levels), with a "Control Stack Full" error message.
      I have worked around that to the point where the only Rexx script I know
      of that still has that problem is PPWizard.cmd.
      You could work around it by using Regina, but OS/2 Regina has other problems
      with very large files.

      RexxTool.cmd assumes well-structured code. Meaning that a routine has
      only one entry point, and execution does not fall through to the next label.
      Like this:
                    LabelA:
                        if a == 1 then
                    LabelB:
                        do
                           say a
                        end
      If your script does things like that, you will want to avoid the
      -AddHeader and -ThenDo formatting options. And the Tree, Calls,
      Depends, and Extract commands may not be accurate.

      I have even seen a few examples of Rexx code with a label in the middle
      of a DO...END structure. It is legal in Rexx, but it seems like a bad
      design. A file like that will be indented correctly but the
      error-checking task will show a false warning about an unbalanced
      DO...END.

      Sometimes a procedure uses a "local" or "sub" label to perform a loop
      or as a temporary error-handler. A convention I use in my own writing
      is to name sub-labels after the procedure, as in
            Foo:
            signal on error name Foo.Error
            ...
            Foo.loop:
            ...
            signal Foo.loop
            Foo.Error:
            ...
      It makes it more obvious that Foo.loop is intended to be part of the
      Foo procedure and reduces the chance of duplicate label names.
      You don't have to use that style of naming labels, but if you do,
      RexxTool commands like Extract, Depends, and Tree may be more accurate.

   Improving it:
      One of my goals is to make it possible for other people to add
      features to it. If you are interested in doing that, try
         RexxTool.cmd help Hack
         RexxTool.cmd help Types
         RexxTool.cmd help ToDo
         RexxTool.cmd help DevHelp
      and read the source, of course. There are many comments in it.

   Credits:
      This started because I wanted to learn Rexx. Much of the code
      that I looked at was hard to understand because the indenting was
      inconsistent, capitalization hard to read, the structure was not
      obvious, and comments were badly placed. I was surprised to find very
      few Rexx code formatters at all, and none that satisfied me. I tried
      writing a formatter and soon understood why there are so few of them.

      The best way to write a formatter is to break up the code into tokens,
      but writing a Rexx tokenizer was beyond my ability. Then I found the
      CheckFunc.cmd script by Toby Thurston, which contains a "mini-tokeniser".
      I have changed Toby's tokeniser almost beyond recognition, but it is
      the basis of the tokeniser in RexxTool.cmd.

      The StringMatch function is adapted from Marcel Mller's RXMMUTIL.CMD at
      <http://www.maazl.de>

      Also thanks to the Regina documentation, which explained some things
      better than the OS/2 Rexx documentation.

   send bug reports to: Anton Monroe <amonroe5301@gmail.com>

