Docs for Into tool by Iain King

   This is Into version 1.00 (C)1997 by Iain King

   You can give this to anyone, but I *do* want something for it now.  It
used to be freeware, which I like, but I am only a poor student, and have
put some effort into this.  My dream is to have something come through the
post because of something I wrote, but it never happened before. If
something I've got says "you can send me stuff if you want" then I'll say,
OK, I won't. Now I really *do* want stuff.

   So INTO is now a kind of Shareware.  If you use it a lot (hey, its
possible) then you should send me something. (Money (a couple of quid's
fine), a small gift, a postcard), basically anything costing less than a
fiver.  You can send me more if you want to, but a) you don't, and b) you
won't.  I don't like getting all Microsofty and commercialised, but this
thing takes some effort you know (when I went back to add loops I just
looked at my (uncommented) code and closed my eyes).

   I really *really* **hate** cripple-ware, so I haven't implemented any
here.  (Also, I couldn't be botherd having to send people non-crippled
versions).

   More stuff at bottom about sending me stuff - if you use into PLEASE READ
THE DOCS, IE - THIS BIT HERE :


N.b. The examples i've given are extremely useless and came straight off the
top of my head while writing these docs, but they should make it easy to
understand whats going on (hopefully).



   What INTO does is let you feed a pattern of files into a program,
which is very handy for programs that do not support pattern matching 
(I wanted this cause my sound player 'sound' doesnt).  Its also handy for
 batch processing. (And more :) To use:


   into PATTERN <options> | command <tags>

PATTERN is any dos standard pattern (#, ?, #?, ~, etc)

MAJOR NOTE HERE!!!!!!!!!!!!!!!!!!!!!!!

   You *MUST* specify a pattern, even if you use IGNORE or FROM.  Nothing I
can do about this without losing functionality (or complicating the
cluttered command line options further).  If you think you dont need it just
type in   #   , but do put something as the pattern or you'll get all sorts
of spurious error messages. (i.e. a 'pattern not found' more than likely)

END MAJOR NOTE!!!!!!!!!!!!!!!!!!!!!!!!


<options> - optional :), they are

   QUIET - INTO displays no output except for requesters
   SILENT - same as QUIET plus any output from the command is redirected to
            NIL:
   INCINFO - includes .info files for processing
   DIRS - only processes directories
   FILES - only processes files
   ALL - processes directories recursively       * very usefull!
   QUIT=#

   lets you select quit mode.
   By default you can't quit (sorry), but adding one of these will solve the
prob:

   QUIT=1 means holding dowm both mouse buttons between jobs will quit
   QUIT=2 means holding down the joystick firebutton between jobs quits

   mode 2 is best because it doesnt get muddled up with menus, then
again - you cant play games :)
   If your using mode 1 it seems to work better if you repeatedly press the
buttons when you expect a job to finish. Sorry for it being kinda cack.


   +CONFIRM - asks the user for confirmation on each job, <return>=yes
   -CONFIRM - same as above but <return>=no

   n.b. for confirmations, y=yes, n=no, a=all (i.e. everything else), s=skip
   (skips everything else)

   FILEKEY=###  sets the filekey tag to ###
   QUERYKEY=### sets the querykey tag to ###

   these are to give greater flexibility for running commands (more later)

   FROM=###   make into get its list of names from the file ###
               meaning you can create a list of files, like this one:

example file: name "flarp.list"
------snip------
foo.iff
bar.iff
baz.iff
quux.iff
------snip------

   INTO will use each of these files for jobs, ignoring the given pattern
   this could be used for a slide=show, i.e.:

      INTO # FROM=flarp.list SILENT | vt


     (Thanks to Daniele Carnino for reporting the bug in FROM)


   HELP - small :) help text

   INCSPACES - this determines how files with spaces in there name are
               handled: more on this in the tags section

   LOOPCOUNT=# - Turns on looping and sets the number of loops per file to #

   LOOPKEY=### - sets the loopkey tag to ### (more later)

   IGNORE=# - Instead of using a pattern, into will instead simply process
              this number of times. (could be useful for a purely loop based
              op) N.B. *not* the same as loops = LOOPKEY will not register
              unless the loops are done with LOOPCOUNT.  The suggested
              method is to use IGNORE=1 with LOOPCOUNT=# and LOOPKEY=###.

   OUT=### - sets the text ### to be interpreted as the redirect output >
             sign.  This is necessary because if you use the normal sign
             (i.e. ">"), then AmigaDOS interprets this before INTO can, so
             INTO's output is redirected, rather than your commands

   IN=### - sets the text ### to be interpreted as the redirect input < sign
            for the same reason given above.

   NOPATH - operates on the file name only - no path given

      i.e. for the match   :                 work:games/worms/wormsfile
           using NOPATH will operate on :    wormsfile

   RELATIVE - filename operated on is given forwards relative to the current
               directory.

      i.e. if the current dir is   :  work:temp/
           and match is            :  work:temp/stuff/thisfile
           then the filename used= :  stuff/thisfile

      NOTE:  only works forwards.  If you specify a PATTERN the refers to a 
             directory either 'behind' or on a different device jiberish
             will be returned : i.e.

          into /#? all relative | echo            ERROR!!!!!
          into df0:#? all relative | echo         ERROR if current disk is
                                                         not df0:


 '|'

   this must be a on its own with a space on either side - denotes start of
command.



   command


   Any DOS command, and its arguments i.e.

      list dirs nohead

   If INTO finds one of the parameters to contain the file tag or a query
tag then it:

   If it finds a file tag it inserts the current job at that point (handy
for commands that are fidly for where you put a filename)

   If it finds a loop tag then it inserts the number of the current
iteration of the loop at that point.  Loop counter goes from 1 to LOOPCOUNT.

   If it finds a query tag it stops and asks the user for input, using the
user input as parameters.

I.E.
 using above example, you could set up:

   INTO # FROM=flarp.list FILEKEY=£££ QUERYKEY=$$$ | vt £££ $$$

this would respond with:

Working on file    foo.iff   : <user input>

you then type in any options specific to that file
(fullscreen, window, whatever), it would then do

vt foo.iff fullscreen

and move onto the next file.  NOTE you can include the tags into other
parameters:

   For instance, to back up every file in a directory to an equivalent
backup file:

   INTO #? INCINFO FILEKEY=! | copy ! !.back

for a directory:

foo
foo.info
bar.iff
bar.iff.info

would do

copy foo foo.back
copy foo.info foo.info.back
copy bar.iff bar.iff.back
copy bar.iff.info bar.iff.info.back

To give the backups icons (ie, to put the .back extension before the .info
extensions):

   INTO #? FILEKEY=$ | copy $ $.back

   INTO #? INCINFO FILEKEY=$ | copy $.info $.back.info

N.B.  If no FILEKEY is given then the file is appened to the end of the
command.  If given it is only inserted expletively - only when you tell it
to.


   INCSPACES comes in here, for example:

   INTO #? DIRS FILEKEY=$ | LIST $/

   This would do a directory list of the contents of all the dirs in the cd.
However, if the current dir had a space in it, say its name is "foo bar",
then theis would result in:

   LIST "foo bar"/

   Which is not what you want.  This is where INCSPACES comes in.  If used
then the quotes will extend to surround all the current argument:


   INTO #? DIRS FILEKEY=$ INCSPACES | LIST $/

would result in:

   LIST "foo bar/"


   For loops Backing up is also a good example.  Say for a dir with files:

   foobar
   bazbob

   To back them up twice you could:

   INTO #? FILEKEY=! LOOP LOOPKEY=$ LOOPCOUNT=2 | copy ! !$

   which would:

   copy foobar foobar1
   copy foobar foobar2
   copy bazbob bazbob1
   copt bazbob bazbob2

   And to show why this is not totally pointless, for the same original dir,
   try and work out what this would do:




   assign 1: work:backups/mainbackups
   assign 2: df0:backups
   assign 3: pc1:backups

   INTO #? NOPATH FILEKEY=! LOOP LOOPKEY=$ LOOPCOUNT=3 | copy ! $:!

   assign 1: remove
   assign 2: remove
   assign 3: remove



   Not bad eh? This technique could also be used with Alias or Scripts
instead of Assigns to perform multiple commands on the files.
   (OK. so you could simply use 3 into's, but if youve got 20 dirs its not
so easy.  OK thats unlikely for backups, but it's still handy)

   ALL lets you move through directories recursively
 Say you wanted to delete all backup (.bak) files on your hard disk:

doing a

         DELETE #?.bak all

does not work cause it wouldnt enter a directory unless it had a .bak
extension - and then it would delete it !!!

   This would though

      INTO #? DIRS ALL FILEKEY=$$$ | INTO $$$/#?.bak +CONFIRM | DELETE

.  N.B., you dont need to use 2 INTOs, but this shows another use of
INTO - you can add confirmation to commands.  The above could be done by:

      INTO #? DIRS ALL FILEKEY=$$$ | DELETE $$$/#?.bak

but using the second INTO means that every file is prompted before deletion.


   Some extra stuff:


      Some uses for Into I've come across, worked out, thought up, or been
reported.  Not really useful, but Ill put it in anyway:

   Backing up.  This is covered pretty much above.

   Any batch processing.  Well, almost any.

   Renaming/Copying groups of files.  For example, I like using the
Spectrum emulator/ downloading games at Uni and bringing them home.  My
Emulator defaults to the extension .Snapshot , but as PC's truncate this to
.SNA during download, renaming/copying them all from floppy can be a hassle
- NO MORE!

      cd df0:
      into #?.sna nopath filekey=! | copy ! work:stuff/speccy/!pshot

   Magic WB users may wish to copy the new icon set to there hard disk.
Copying, for example, to all the directory icons on your hard disk is easy:

      cd work:
      into #? dirs filekey=! | copy diricon.info !.info

   Creating a slide show is easy.  Either, simply

      cd WhereThePicsAre
      into #?.iff quiet | vt

     or

      create a list of the files you want to slide-show and

      into # from=slideshow quiet | vt


   A pointless idea, but you can use Into to find a file:

      into #? dirs all quiet filekey=! | list !/FileYouWant#?

   Create a directory listing of your hard disk

      into #? incinfo all quiet filekey=! | echo !

    or, to a file

      into #? incinfo all quiet filekey=! out=} | echo ! }}OutPutFile

   D.C. used it for triming log files, something like:

      into logfiles:#?.log filekey=$ | trimfile $

   He also used it for mounting network stuff, by creating a list of
devices and using FROM.  Sorry D.C. - I lost your email, and this is all I
can remember :)



   Or, for a laugh, or if your feeling particularly masochistic, a text
editor!

          into # ignore=1 loopcount=4096 querykey=! quiet out=} |
(cont.)   echo ! }}OutputFile


      Notes:  loopcount sets the max number of lines
              outputfile is the file to save to

   Oh what fun! :)





      Disclaimer:  Sorry folks, but I cant and wont be held responsible for
any damage INTO does.  It seems to work OK but it seemed to work very
quickly with basically no bugs, so watch yerselves and let me know if you
find any.  Also, watch out - it is a very powerful file tool and you
could shoot yourself in the foot VERY easily ( the syntax is by nature
baroque, and its a hell of a lot easier to kill files than a simple
"delete #? all" mistake.

   Note - because of the Way It Works,  INTO can be quite RAM intensive.
Note also that INTO requires a RAM: device. You are warned.

   You can send me stuff at :

         Blairs Croft
         Creetown
         Newton Stewart
         DG8 7DF
         Scotland

   Also, you can email me with bug reports (which are gratefully read) at:

   iking@cs.strath.ac.uk       - ill be here (Hopefully) till about the year
                                 2000!!!

   Hope its handy