StringIns v1.0
==============

©2007 Peter Gordon (pete@petergordon.org.uk)

IF YOU FIND STRINGINS USEFUL PLEASE CONSIDER DONATING SOME CASH TO
MY PAYPAL ACCOUNT! (Use the email above)


1. Introduction
===============

StringIns converts a string into keyboard events and adds them to the input
queue as if they were typed on the keyboard, with an optional delay. This
allows you to automate tasks in scripts which normally require user input
such as acknowledging requesters or typing in passwords.

StringIns takes two arguments "DELAY" and "KEYSTRING". "KEYSTRING" is the
string to 'type' onto the keyboard buffer, and "DELAY" is a length
of time to wait in 1/50ths of a second before processing the keystring.

For example, if you typed:

run <>NIL: stringins delay=50 keystring="hello world"

into the shell, after a second "hello world" would appear in the shell
as if you typed it.

One example use would be a script which decodes a PGP encrypted file
and automatically typed in your password:

--------
.bra {
.ket }
.key PGPFILE/A
run <>NIL: stringins delay=100 keystring="mypassword\n"
pgp {PGPFILE}
--------

(\n is a special code to say "hit enter")


2. Advanced usage
=================

As you saw in the above example, you can use the backslash charactor '\' to
insert special keycodes into the keystring. Here are all the special codes:

 \\ = Insert a backslash
 \a = Press and hold the left-amiga key
 \A = Release left-amiga key
 \m = Press and hold the right-amiga key
 \M = Release right-amiga key
 \l = Press and hold the left-alt key
 \L = Release left-alt key
 \t = Press and hold the right-alt key
 \T = Release right-alt key
 \s = Press and hold the left-shift key
 \S = Release left-shift key
 \h = Press and hold the right-shift key
 \H = Release right-shift key
 \c = Press and hold the ctrl key
 \C = Release the ctrl key
 \n = Enter key
 \b = Tab key
 \^ = Cursor up
 \v = Cursor down
 \< = Cursor left
 \> = Cursor right
 \k = Press key associated with a rawkey value (see below)
 \d = Wait 1/10th of a second before continuing
 \D = Wait 1 second before continuing
 
The "\k" code is different to the others in that it requires an argument. It
must be immediately followed by a 2-digit hex code of the rawkey to press. For
example, to press F1 followed by escape, you would use:

stringins "\k50\k45"

Some other examples:

stringins "hello \Dworld"    -> Types "hello ", waits 1sec then types "world".
stringins "\mcq\Mhello\mv"   -> Types RAmiga-C, RAmiga-Q, "hello" then RAmiga-v

Note that the "press and hold" escape chars don't generate a key-down event
for the qualifier, they just set the corresponding qualifier bit in subsequent
keypresses. To actually generate a keydown for the Amiga, Alt, Shift or Ctrl
keys you would have to use '\k'. Note also that every keypress (including
those with \k) will automatically generate a key-up event, so trying
"\k63\k66\k67" to reboot the Amiga won't work ;-)

A final example is one that I use myself. I often use the eval command to
quickly do some maths in the CLI, but eval only uses integer maths. The
following script uses the calculator program to do floating point sums from
the CLI:

------
.bra {
.ket }
.key CALCSTR/F

run <>NIL: stringins delay=10 "{CALCSTR}=\mcq\M\d;\mv\M\n"
calculator
------

First, it inserts your sum, then presses '=' to get the result in the
calculator window, then presses RAmiga-C to copy the result, and
RAmiga-Q to quit calculator. It then waits 1/10th of a second to let
calculator quit, and types ";" followed by RAmiga-V into the shell
and then hits return.

This leaves you the result both in the window and on the clipboard.
Nifty, eh? The only thing to remember with this script is that because
of the way AmigaOS handles argument passing in scripts, if you want to
do multiplication, you need to use "**" instead of "*".

 PERMSSN    UID  GID    PACKED    SIZE  RATIO METHOD CRC     STAMP          NAME
---------- ----------- ------- ------- ------ ---------- ------------ -------------
[generic]                 4373   12224  35.8% -lh5- 19c9 May  4 13:44 stringins
[generic]                 1770    3851  46.0% -lh5- 7f51 May  4 13:44 stringins.txt
---------- ----------- ------- ------- ------ ---------- ------------ -------------
 Total         2 files    6143   16075  38.2%            May  4 06:15