                                 SquigglyPipes
                                 =============

Version 1.03 (03 Jan 1999)
     
Introduction
------------
If you've used Unix you'll know how nice it can be to perform a task and,
depending on the result, do something else. Take, for example a simple 'list
all files and show the symlinks'; this might be done as something like 
"ls -al | grep '->'". Whilst this probably isn't the best example of pipes,
it does illustrate the point that this is impossible under Risc OS in a
single command.

Squiggly pipes allows you to do a similar thing to the above unix command
with the line "ex { | grep Link }" (ex is the equivilent of ls -al, SymLinks
have the filetype 'Link'). Notice that the pipe usage is almost identical to
the redirection usage "command { <|> file }".


Usage
-----
Basically any line with { | <anything> } will be parsed as a piped command.
The piped command /must/ be the last thing on the line; anything after it
will be ignored at present. Pipes may be nested, but you should remember to
include the correct number of closing brackets. That's about all I can tell
you really... It works in the majority of cases :-)


Redirection
-----------
Pipes are implemented using both the Risc OS and C redirection systems. If a
program is recognised as C it will have an input, or output (or both)
appended to it's command line; otherwise a standard OS_ChangeRedirection call
is issued. C programs are recognised as such by the signature &EF000011 at
&8010, so if you have a basic program which uses C style IO you should modify
it to contain a !&8010=&EF000011 /before/ the OS_GetEnv line. Conversely, to
ensure that you know how much data to read from the input if using 'GET'
(etc) you should do something like : 
  SYS "OS_ChangeRedirection",-1,-1 TO i%:IF i%<>0 THENleft%=EXT#i%-PTR#i%
  ELSEleft%=0

Error redirection is not performed in C, and should still result in output to
the screen in much the same way an error would in assembler or for built-ins.


Examples
--------
These are some of the examples I've tried any found to work successfully.

=== examples of simple pipes ===
( search the help for a the word 'key', search the modules list for a
  particular module, and search for commands starting with 'wimp' )
| *help { | grep key }
| ==> Help on keyword Help
| *Help <subjects> attempts to give useful information on the selected
| topics. Special keywords
| *modules { | grep URI }
| 111 0186A2B4 01830414  URI
| *help wimp. { | grep "==>" }
| ==> Help on keyword WimpFlags
| ==> Help on keyword WimpMode
| ==> Help on keyword WimpPalette
| ==> Help on keyword WimpSlot
| ==> Help on keyword WimpTask
| ==> Help on keyword WimpWriteDir
| ==> Help on keyword WimpDragDelay
| ==> Help on keyword WimpDragMove
| ==> Help on keyword WimpDoubleClickDelay
| ==> Help on keyword WimpDoubleClickMove
| ==> Help on keyword WimpAutoMenuDelay
| ==> Help on keyword WimpMenuDragDelay
| ==> Help on keyword WimpSWIVe

=== example of complex gzip ===
( compress a file, decompress it, and search the output for the word 'Justin')
| *gzip -c text { | gzip -d -c { | grep Justin } }
| Author    Justin Fletcher

=== examples of error handling ===
( Command where the first half of a pipe is broken, then second part is
broken )
| *ahelp wimp { | grep found }
| Bad vector release
(only under a taskwindow; under a shell this works correctly... curious)
| *help wimp. { | agrep "==>" }
| File 'agrep' not found

=== example of use of awk ===
( show the directory [as example], then search for files dated 'August',
  display them and at the end the total of their lengths )
| *ex ^.^.^
| Dir. ADFS::Gerph.$.Utils.Library Option 02 (Run) 
| CSD  ADFS::Gerph.$.Utils.Library.GNU.awk.Egs
| Lib. ADFS:"Unset"
| URD  ADFS:"Unset"
| Acorn        D/      Directory 14:08:51 06-May-1997 2048  bytes
| C            D/      Directory 18:35:27 03-Aug-1997 2048  bytes
| CD           D/      Directory 14:16:02 06-May-1997 2048  bytes
| Compress     D/      Directory 14:26:08 06-May-1997 2048  bytes
| Econet       D/      Directory 14:24:06 06-May-1997 2048  bytes
| Encode       D/      Directory 14:18:04 06-May-1997 2048  bytes
| FSCK         D/      Directory 14:09:20 06-May-1997 2048  bytes
| GNU          D/      Directory 14:16:34 06-May-1997 2048  bytes
| Graphics     D/      Directory 14:22:01 06-May-1997 2048  bytes
| Internet     D/      Directory 16:53:28 06-May-1997 2048  bytes
| Mail         D/      Directory 18:18:18 07-Aug-1997 2048  bytes
| Misc         D/      Directory 14:26:36 06-May-1997 2048  bytes
| Module       D/      Directory 14:13:16 06-May-1997 2048  bytes
| Obsolete     D/      Directory 14:11:20 06-May-1997 2048  bytes
| Prog         D/      Directory 14:17:31 06-May-1997 2048  bytes
| RCS          D/      Directory 15:57:16 12-Apr-1997 2048  bytes
| ReadFiles    WR/     BASIC     14:54:59 06-May-1997  985  bytes
| System       D/      Directory 14:19:31 06-May-1997 2048  bytes
| Unix         D/      Directory 14:13:54 06-May-1997 2048  bytes
| UnixComs     D/      Directory 14:28:40 06-May-1997 2048  bytes
| 
| *ex ^.^.^ { | awk "{ if ($5 ~ /Aug/) { sum+=$6; print } } END { print sum }" }
| C            D/      Directory 18:35:27 03-Aug-1997 2048  bytes
| Mail         D/      Directory 18:18:18 07-Aug-1997 2048  bytes
| 4096


    
How it works
------------
Basically I'm just using the built in redirection system to a better effect;
Temporary files are stored in the SqPipes$Path directory and should be
deleted after the commands exit. Error handling is rudimentary but should be
sufficient for 99% of occassions.


Disclaimer
----------
The author accepts no responsibility for any problems which this application
may cause or loss of data resulting in its use. This application is currently
on beta release. Please observe this and don't do anything foolish, like
sticking it on bbs's :-)
  

Source code
-----------
Source code for this module is not currently available. Contact
Gerph@essex.ac.uk for details.


Bugs
----
There are a few bugs in it. To be honest (and I really mean this) I wasn't
actually at the stage at which it should have worked when it did, it was
still in the 'let's try this and see what happens' stage. As such there maybe
some fundamental things I've missed out. If there are I'm sorry, and a quick
mail to me would be muchly appreciated.

Major bug which I need to find the cause of : 'Bad vector release' - see
example on error handling (only happens in taskwindows).


Contact
-------
Any comments, queries, donations or bug reports can be sent to Justin
Fletcher at :

E-Mail : gerph@innocent.com
URL    : http://www.thevillage.ndirect.co.uk/justin/
IRC    : On #Acorn as Gerph
Tel    : (01842) 812276

Snail Mail :
    Justin Fletcher
    Galadriel
    17b Cromwell Road,
    Weeting,
    Brandon,
    Suffolk.
    IP27 0QT


History
-------
Version 1.00 : 09 Aug 1997
               A twinkle in my eye this morning, which left my screaming that
               my head would explode by lunch time (C redirection fiddle), and
               finally worked at around 7pm.

Version 1.01 : 10 Aug 1997
               Error handling ? What's that ? Oh, well I suppose I'd better
               add some then. Oh... And maybe I should remove those little
               memory leaks that are going around.

Version 1.02 : 12 May 1998
               Pay attention when things say 'PRM 1-107 will not work on a
               StrongARM'. Squiggly pipes should work now.

Version 1.03 : 03 Jan 1999
               Now works on StrongARM /without/ giving any errors - previously
               it generated an exception but generally worked. Now it works.
