                                    _                 _ 
                                   | |               | |
                      __ ___      _| | _____  ___  __| |
                     / _` \ \ /\ / / |/ / __|/ _ \/ _` |
                    | (_| |\ V  V /|   <\__ \  __/ (_| |
                     \__,_| \_/\_/ |_|\_\___/\___|\__,_|
                                                        

                 version 135 3rd August 2000     Harriet Bazley
                                              
!awksed was written with the aid of Andrew Ayre's "Dr Wimp" system.   It is
freeware.   If you want to improve it, steal useful procedures, etc., I shall
be flattered...

This program provides a WIMP interface to the GNU command-line utilities
'sed' and 'awk'.  If you do not have a copy of either this program will be of
no use to you.

How to Use:
         Once you have loaded the program, clicking SELECT on the iconbar icon
will bring up the main window.   The downward-pointing arrows are 'drop-
boxes'.   Select 'Awk' or 'Sed' from the main menu and drop the file you wish
the GNU utility to process onto the left-hand drop-box. Drop the sed 'script'
or awk program file onto the right-hand drop-box. Select 'Apply script' from
the menu or click ADJUST on the iconbar icon. Awk or sed will now be run and
the output, if any (it depends on your script) should appear in a TaskWindow.

Hardware:
         The program should run on any Acorn computer with RISC-OS 31 and
above.   It has been tested on an A4000, an A500, an A3000 and a RISC-PC 600.
It requires sufficient free memory to run awk/sed as well as the WIMP front
end;  if you have only a few hundred kilobytes free you may have trouble
when you actually come to run the awk/sed script.   You will probably also
need to have enough spare memory to load a text editor such as Edit or
StrongED.

Software:
         The program uses temporary files inside the !Scrap application.   A
copy of !Scrap must therefore have been seen by the Filer.   (Probably not a
problem unless you are running the program from floppy disc).
         The actual programs sed and/or awk need to be in your Library
directory, or in another directory which also appears in Run$Path.
         This application supports Acorn's interactive !Help extensively.

  ** CONTENTS **
- The Menu
- The Main Window
- Converting a temporary script to a 'permanent' script
- Applying a Script to the Contents of a Directory
- The Iconbar
- The Choices window
- Hidden Options (pre-scanning directories)
- Parameters passed on the command line and DDEUtils
- Problems and known bugs
- CONTACTING THE AUTHOR
- HISTORY

In Detail:
         The Menu
         --------
         'Info' opens the 'About this program' window.
         'Apply script' runs awk or sed with parameters appropriate to the
options you have selected, first checking that you have supplied both input
and script files.   ADJUST-clicking on the iconbar acts as a short-cut for
this menu option.
          'Choices' opens the Choices window  see below.
         'Sed' and 'Awk' switch the program between awk mode and sed mode.
The currently selected mode is ticked.   This can also be done from the
Choices window, where you can save the setting so that 'awksed' always starts
up in that mode - see below under 'The Choices Window'.
          'Quit' deletes all temporary files, including the current script
file, if this was created from within awksed using the 'New script' button -
you will be given a warning if this is about to happen, allowing you to
change your mind.   (See below for how to save a temporary script file ino a
more permanent location).   Otherwise, the program resets the system
variable File$Path (see below under 'Problems') and quits.

         The Main Window
         ---------------
         Click SELECT on the iconbar to bring up this window, or drag a file
or directory to the iconbar  see below.

         The two writable icons below the drop-boxes display the names
of the current input file and awk/sed script. You may type directly into these
icons if you wish.   Since awk and sed do not accept system variables,
these will be expanded just before the script is run, and the icons updated.

         If the object dragged onto the drop-box is a directory, or is not a
text file, then you will be asked to confirm that you really want to load it.
Select "OK" to load it or "Cancel" to reject it.  'awksed' can be configured
to accept up to nine other filetypes without querying them  see 'The Choices
Window' below. Directories are always queried.

         The 'Edit script' button will start up your text editor, if it is not
already running, and load the current script into it, allowing you to change
the script until it finally does what you originally intended.

         The 'New script' button will create a new blank file, enter its name
into the script icon, and load it into your text editor.   This option allows
you to write one-off scripts (the most common kind) without needing to create
and save the file and then drag it onto the main window.
         Technical note:  the file is always created as
"<Wimp$ScrapDir>.awksed.script".   This means that every time you press
this button you will delete the previous file.   'awksed' will warn you if
this is about to happen, allowing you to save the file elsewhere - see
below for how to do this.

         Dragging a file or directory to the iconbar will cause it to be
loaded as the current input file/directory just as if it had been dropped onto
the appropriate drop-box.

 Converting a temporary script to a 'permanent' script
 -----------------------------------------------------
        Scripts created by 'awksed' with the 'New script' button are
'temporary scripts' which get deleted when you press the 'New script' button
again or quit the program.   If you use this option to create a script and
then decide you want to keep it, load it back into the editor (using 'Edit
script') and then save it out to another location.   Note that you will have
to drag this 'new' file back onto the script drop-box in the main window to
update the icon there before you can use it - otherwise 'awksed' will go on
using the temporary copy. 

         Applying a Script to the Contents of a Directory
         ------------------------------------------------
        'awksed' allows you to drag a directory or even an application to
the iconbar, or drop it onto the 'input file' drop-box, although you will be
asked to confirm this.   The name of the directory will be displayed in the
writable icon, followed by ".*" in order to indicate that it is the files
within the directory rather than the directory itself which will be loaded.

         When you click on 'Apply script' the names of all the files in the
directory will be passed to awk or sed, instead of just the name of a single
input file.   Filetypes will be checked according to the currently selected
options  see 'The Choices window' below.

         If there are too many files in the directory, this can cause trouble
 see 'Problems' below.
         If you are running an awk program, the names of all the files of the
correct filetype will be saved to a scrap file, which will then be passed to
your program as an extra parameter, along with an extra awk program stub to
read them in.   (This has been tested on a DOS directory containing 1960
files - it worked, albeit slowly!)   'awksed' will report how far it has got
in the scanning process every ten seconds, giving you the opportunity to abort
the scan and run your program with just the files scanned so far, and
reassuring you that it has not crashed.   (I may get round to putting a proper
multitasking status window in here at some point.)
          Unfortunately, if you are running a sed program (or redirecting
output from an awk program to a file) this option is not available, and you
will have to resort to the other expedients detailed below under 'Problems'.

         Technical note:  the search does not recurse.   Files in sub-
directories will not be included.   This is in order that as many filenames as
possible can be fitted onto the command line.

         The Choices window
         ------------------
         This window is accessed from the menu.   If you click on the menu
option it will be displayed as a permanent window;  if you display it by
following the arrow off the right-hand side of the menu, it will disappear
again when you move the pointer back to the left.

         The Choices window is in two sections.   The top section, the only
one which is initially visible, controls output.  The two radio icons in the
'Echo output' section on the left allow you to control the destination of any
text output to the screen by awk or sed  see below.

         The option at the bottom controls how much text is generated by sed.
If 'Don't echo all output' is selected, then text will only be output when a
'p' or 'w' command or a '/p' or '/w' flag is encountered in the script.
Otherwise, every line is output, in its edited form  and if an explicit print
command is then encountered, the line will be output twice!   Whether you
select this option or not will probably be determined by the contents of your
sed script. (What it actually does is invoke sed with the '-n' or '--quiet'
command-line option set).
         This option is irrelevant to awk and will be greyed out while the
'Awk' menu item is ticked.

         Once you have a working script you will want to keep a copy of the
results.   The 'Echo output to' section controls whether the output will be
saved to file or displayed in a Taskwindow (from which it can later be saved).
These two options are mutually exclusive.   However, it is possible to
deselect both, in which case any output will scroll past rapidly in a
non-multitasking window on the screen!   You might want to do this in order to
test a script, since it is a lot faster than printing to a Taskwindow.
         When 'File' is selected you can then drag the text file icon to a
Filer window to set the output filepath.   Note that the output file is not
written until sed is actually run by clicking on 'Apply script'  don't be
alarmed if the contents seem unrelated to the input file....   Dragging this
icon into a window belonging to another application will display the temporary
file but not set the output path;  when the 'File' option is selected, you
will not be able to run sed until the output path (displayed under the text
file icon) has been set up, either by typing or by dragging the icon.

         Technical note:  unless 'Taskwindow' is selected awk and sed will not
multitask.   Note also that altering the settings of these two icons may
sometimes help cure "Too many files in directory" errors  see below under
'Problems'.

         The 'Program' section controls which of the two utilities, awk or
sed, will be invoked by clicking on 'Apply script'.   These two radio icons
are linked to the menu options of the same name and have exactly the same
effect.   When you switch from awk to sed or vice versa, the window, menu and
iconbar titles, the 'Don't echo' option setting, the filetype checking (see
below) and much of the interactive help all change to reflect the new mode.
         Technical note:  in fact it is the icons which do all the work  a
click on the menu options is set to simulate a click on the appropriate icon
 and it is the icon settings which control the display of ticks on the menu
and which are saved when you select 'Save choices' (see below).

          Clicking on the 'Save choices' button will save all the current
settings of the Choices window, including the output filename and whether the
program is in awk or sed mode, to a Config file in the !awksed.Resources
directory. These settings will be automatically loaded next time the program
is run. To return to the default settings, just delete the Config file.


         The lower half of the window controls how input files will be
treated.   In order to view this part of the window, you will need to scroll
the window down or use the toggle size icon on the titlebar.   Unless you
frequently load directories containing many non-text files, you will probably
not need to alter these settings.   

         The two writable icons labelled 'awk' and 'sed' contain a list of the
valid input filetypes for their respective modes.   The filetype of all files
dropped on the drop-boxes in the main window or encountered while scanning a
directory is checked against these lists.   Any file of a filetype not
appearing in the list for the current mode will either be queried or silently
rejected, according to the options set by the two radio icons below.

         Technical note:  you should not attempt to edit these lists unless
you understand what you are doing.   Filetypes must be given as three-digit
hexadecimal numbers and separated by commas.   There is room for ten
filetypes, which should include 'Text' (FFF)  although supplying an empty
list will enable you to select a sub-set of text files from a directory by
querying all of them!
         The default setting for awk includes filetypes &0A0 and &0A1.   There
is no special significance to these  they are simply the filetypes used by
Gavin Wraith in his !Gawk application and by me for my StrongED awk mode, and
you can delete them if you like....

         Selecting 'Query other filetypes' causes 'awksed' to ask for
confirmation every time it is about to load a filetype not in the list.
         If you are scanning a large directory containing a mixture of text
and non-text files, rejecting all the inappropriate files can be very
time-consuming.   In this case, selecting 'Ignore other filetypes' causes
'awksed' to reject all files not on the list without asking for confirmation.

         If you deselect both radio icons, 'awksed' can be forced to load
files of any filetype.   However, attempting to run files in compressed,
graphics or machine code format through either awk or sed can cause very
undesirable results  so be careful how you use this option!

         The Iconbar
         -----------
         Click SELECT to bring up the main window.   Click ADJUST to re-run
the last program.

         Hold down CTRL and click SELECT to 'fix' the list of files scanned
from the current input directory.   Hold down CTRL and click ADJUST to view
this list.   Hold down CTRL and drag a file to the iconbar to use it instead
of the scanned list.   For further explanation, see 'Hidden Options' below.

         Hidden Options (technical notes)
         -------------
        Three options have been provided for handling directories containing
very large (500+) numbers of files.   You are only likely to encounter such
directories on foreign-format CD-ROMs!

        Holding down CTRL and dropping a file onto the iconbar icon will cause
the file to be treated as a list of filenames to be processed by the current
awk program, in the same manner as the scrap file produced by 'awksed' itself
while scanning a directory (see 'Applying a Script to the Contents of a
Directory' above).   Such a file should be in the format of a file produced by
the '*EnumDir' command, with one filename only per line.   Filenames may be in
any format - full pathnames, just leafnames, or paths relative to the CSD.
Optionally you may provide an initial line starting '#Prefix ' and naming a
directory in which files are to be sought. If you do so, this must be the
first line and it MUST be followed by a blank line before the first filename.
       Example of a possible file:
-----------------------------------------------------------------------------
        #PREFIX  ADFS::4.$.Work.Docs
        
        Letters.Jan12
        Letters.Jan27
        Misc
        ADFS::4.$.temp.SearchList
        Fred02
        Report
-----------------------------------------------------------------------------
Such a file would apply the awk program to ADFS::4.$.Work.Docs.Letters.Jan12,
ADFS::4.$.Work.Docs.Letters.Jan27, ADFS::4.$.Work.Docs.Misc,
ADFS::4.$.temp.SearchList, ADFS::4.$.Work.Docs.Fred02 and
ADFS::4.$.Work.Docs.Report.

         The normal application of this feature is in reloading pre-scanned
files in order to avoid repeated scanning of a large directory.   Note that
this bypasses the querying of filetypes altogether -  be careful that all
files listed are of an appropriate filetype.


         Once you have generated a scrap file for a given directory, you can
'fix' it by holding down CTRL and clicking the iconbar icon with the SELECT
mouse button.   The lefthand icon in the main window will change to read "Use
Scrap".   The same file will now be used every time you run your program, so
that the directory will not be rescanned for each run.   This will cause no
problems unless you delete or rename some of the files listed!

         To inspect the current scrap file, and possibly to save it for future
re-use, hold down CTRL and click the iconbar icon with the ADJUST mouse
button.   This will load the file into a text editor, where you can read it or
save it elsewhere.

** Note that neither of these short-cuts will have any effect until a scrap **
** file exists, i.e. until the program has been run at least once.          **

         When 'awksed' is using a 'fixed' scrap file to list the input files,
the icon below the left-hand drop-box reads "Use Scrap".  To make 'awksed'
forget this scrap file and return to normal operation, simply drop a file or
directory onto the left-hand drop-box  - you will see the icon change to
reflect the new input path.

         Parameters passed on the command line and DDEUtils
         --------------------------------------------------
         If you frequently use a given combination of input/script files, you
can create an Obey file specifying the relevant options to start up awksed
as if you had already dragged those files to the drop-boxes.   The available
options are:
         -script or -s    followed by the pathname of the script file
         -input or -i     followed by the pathname of the input file or dir
         -sed             if present, selects 'sed' mode
         -awk             if present, selects 'awk' mode

A real-life example:   "Run <awksed$Dir> -input IDEFS::A5000.$.Text.Documents.
NotToKnow.Textfiles  -script IDEFS::A5000.$.Text.Documents.NotToKnow.keyword
-awk"

This applies the script 'keyword' to the contents of the directory
'Textfiles' in awk mode.

       If you don't specify -awk or -sed then the currently-configured
default will be used.   If you specify *both* then -sed will be used!  If
either the -s or the -i option is omitted, then the icon in question will be
left blank. If you use the -input option to specify a directory, its
contents will be scanned as normal.

        awksed also supports the DDEUtils extended command line, allowing you to
pass very long pathnames as parameters if you have to.   Note that if you do
use the DDEUtils command line any parameters passed in the normal manner
will be totally ignored!   Technical note:  the file DDETest in the
application directory shows one way of doing this.


         Problems and known bugs (technical stuff)
         -----------------------------------------
         Redirecting output to an output file (which uses the RISC-OS { >
filename } redirection syntax) seems to result in DOS-type "CR+LF" line
endings.   The problem is either with RISC-OS or within awk and sed;  it seems
to be unavoidable.   It is also incompatible with the use of 'scrap files' to
pass extra filenames to awk - see above under 'Applying a Script to the
Contents of a Directory'.

         The most annoying bug in 'awksed' is the one caused by the
256-character limit on the RISC-OS command line.   This generates the 'Too
many files in directory' error when you try to scan a directory, indicating
that the total length of the command line, which has the basic format "sed -f
ADFS::4.$.!Scrap.ScrapDir.awksed.script inputfile1 inputfile2 inputfile3
inputfile4...", has exceeded 256 characters.
         (This applies to both modes if you redirect the program's output to a
file - otherwise it only applies to 'sed' mode, not the 'awk' mode - see
above, under 'Applying a Script to the Contents of a Directory'.)
         
         As you can see, since the full pathname of the script file is used,
moving it to the root directory of your hard disc can release space for three
or four more input filenames.   (Note that you will have to reload it by
dropping it back onto the drop-box in the main window, though, since 'awksed'
doesn't know that the file has been moved.)
         The full pathname of the output file, if you have selected 'File' in
the Choices window, is also used and the same applies to this.   Note that
selecting 'TaskWindow' uses less space on the command line, and selecting
neither releases even more space  although if you do this you will have to
redirect your output from within your sed script.
         More desperate measures include deleting the entire contents of the
awk or sed valid filetypes list and setting the 'Query filetypes' option in
order manually to select a subset of the files within the directory, and
renaming all the files with very short names!
         Unfortunately it doesn't seem to be possible to get around the 256-
character limit for sed in the same way that I have managed to do for awk,
(see above) since sed scripts are not sophisticated enough to redirect their
own input in the way that awk scripts can.
         
         In order to avoid having to give the full pathnames of all input
files (see above) 'awksed' manipulates the value of the system variable
File$Path, which controls the default path for loading files.   When it quits,
it restores File$Path to the value it had when the program was loaded.
However, if any other programs change the value of File$Path while 'awksed' is
running, these changes will be forgotten every time you click on 'Apply
script' and when you quit the program.   I've never encountered a program that
_does_ change File$Path (as opposed to Run$Path), but if you have one that
does, loading it while running 'awksed' could cause some very obscure errors.


Other:
      Remember, adjust-click on the iconbar is a handy short-cut for 'Apply
script'.
      All the program actually does is create an Obey file with the
appropriate RISC-OS/sed command-line options set and then run it.   If it
crashes, you may find such a file, and others, inside a directory called
'awksed' in your !Scrap application.   It is perfectly safe to delete this 
alternatively, !awksed will tidy them up next time it is run.
      If things go wrong it might help to have a look at this file to find out
what is actually going on.
         
# # # # # READ THIS IF YOU WANT TO ALTER THE PROGRAM! # # # # # # # # # #

  Unfortunately I had to compress the !RunImage in order to reduce the
Wimpslot from a ludicrous 128k to 32k.  However, I've provided the source
files.
  Note that many of the main DrWimp functions have been replaced by cut-down
versions in order to save memory.

# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # 

CONTACTING THE AUTHOR

The author may be contacted at:
  43, Wilton Grove
  Wimbledon
  London SW19 3QU

or via e-mail at chrisbazley@bigfoot.com

Note that this is not my personal e-mail address - all enquiries have to be
printed out and sent to me in London through the post - so replies via this
route will take some time.

# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # 

History:

        V 100 (16/10/1998)     Program written to save manually creating a
file, launching a taskwindow, etc. when I only wanted to run a one- or
two-line script.  Submitted to Paul Beverley of Archive magazine together
with some other sed-related stuff.
        V 110 (12/11/1998)     Altered program to work with Dr Wimp 300.
"Name-changing" facilities added to allow the alternative use of the program
as a front-end for gawk.  The mechanics of the change were easy.   The
cosmetic alterations (especially to the interactive help) were horrible! 
Program name changed from 'Sed' to 'awksed'.
        V 120 (13/11/1998)     Added (limited) support for applying a script
to more than one file.   Due to the 256-character limit on the RISC-OS command
line, (and on strings in BASIC) it can't cope with more than about eight files
at once.
        V 121 (14/11/1998)     Moved filetype checking from system variables
in the !Run file to writable icons in the Choices window, making it much more
flexible.   Standardised filetype checking behaviour for single files and for
directories, and provided yet more options in the Choices window to control
it.   As a side-effect of this it is now possible to turn filetype checking
off altogether!   Added menu options linked to the radio icons in the Choices
window to make it easier to switch between awk and sed.
        V 122 (1/2/1999)        Program now creates its awk script files as
filetype &0A0 so that they automatically use my StrongED awk mode where
available.
        V 123 (8/3/1999)     Program no longer null-polls and slows down
the desktop.   Corrected a misspelt variable name.   Added a warning before
deleting temporary script file on quitting program.
        V 130 (21/6/1999)    'awksed' now allows many more files per
directory to be scanned.   Unfortunately this only works for awk, as sed is
not sufficiently sophisticated to add to its own input file list.  Upgraded
to DrWimp version 350 (but promptly replaced large portions of it with
truncated versions!)

        Finally fixed the bug which occasionally passed the names of
directories instead of files as parameters, crashing awk, and the bug which
placed the caret in a greyed-out writable icon.   Found some more misspelt
LOCAL variables!   The last filename on the list of parameters is no longer
ever repeated twice.  Keypresses in Choices window now handled correctly.
        V 131 (25/6/1999)    Added 'Hidden Options' (see above), mainly in
order to make processing the Maximum Doom CD easier!   Program reverts to old-
style scanning when output is redirected to a file (the 'scrap file' method
didn't work in this situation).   Further improvements to input focus handling
in Choices window.
        The 'Continue scanning' error box now comes up ten seconds after the
last error-box, not ten seconds after the start of scanning - if you're
querying lots of files, you don't need more confirmation.  Various small bugs
corrected.
         V 132 (22/7/1999)   Fixed minor problem with File$Path (I had
assumed this variable always ended in a comma and hadn't bothered to add one)
         V 133 (29/12/1999)  'awksed' now starts up a text editor to edit
awk program files if no application responds to the broadcast message to load
the file.   Rather nasty to implement!   The 'Scrap' file is 'broadcast'
(simulated Shift-double-click) instead of Filer_Run, so the program now
works properly with !Edit again.
         V 134 (16/6/2000)    Upgraded to DrWimp 354.   Corrected very
silly error (%*0 instead of %%*0) which resulted in a system command 'Awk'
being defined consisting of all the parameters passed to the RunImage!   As
a result you can now successfully run the program from the command
line specifying initial '-input' and '-script' parameters.  DDEUtils
extended command line also supported.   Occurrences of the historical
<Sed$Dir> finally changed to <awksed$Dir> throughout. Main window now opens
by default when program first loaded.
         V 134 (19/6/2000)   DrWimp upgrade appears to have caused notable
increase in memory requirements.  Replaced even more sections of DrWimp with
my own functions in an attempt to stop crashes due to memory shortage.
         V 135  (3/8/2000)   Desktop save now saves current set-up, i.e.
names of input and script files and whether awksed is currently in 'awk' or
'sed' mode.