                         CueAct CueCat/Internet linker
                         -----------------------------
                                    v0.0.4
                                    ------

                   Pierre-Philippe Coupard <pierre@lineo.com>
                                   11/08/00



1 - What is CueAct ?

CueAct is a userspace utility provided as part of the CueCat driver software.
Its purpose is to exploit barcodes read by a CueCat reader, and decoded by
the CueCat driver, by performing an action of interest associated with the
barcode swiped (the most obvious being to link a barcode with a suitable
database to look up in no time the information relevant to that barcode).

The actions performed by CueAct are fully configurable.



2 - Compiling CueAct :

in the source directory, simply type ./make : the "CueAct" binary should be
created without problem, the software being very simple and portable.



3 - Using CueAct :

You need to have the CueCat driver installed and enabled (please refer to the
CueCat driver's documentation on how to install and enable it).

Install CueAct wherever you wish, for example /usr/local/bin/. When ran, CueAct
expects to find a configuration file at ~/.cueactrc : to create one, simply
copy the supplied configuration file (cueactrc.sample) to your home directory
as .cueactrc.

NOTE : unless you wish to create a different application than Internet
       information lookup with CueAct, I suggest you reuse and complete the
       supplied .cueactrc file.

Then, invoke :

$cueact

The software should start and wait for you to swipe a barcode with the CueCat.
When you do this, if the barcode type is recognized, the corresponding command
is executed : with the supplied configuration file, it is required that
you have Netscape Communicator running prior to swiping a barcode. When you
swipe a barcode, CueAct will instruct Netscape to go fetch information on
that particular barcode using the appropriate web page.

Options :

-f <filename> : specify alternative configuration file
                (default is ~/.cueactrc
-h            : gives a help screen
-o            : read and process only one barcode
-s            : run silently
-v            : be verbose

By default, cueact runs continuously.

Tip : invoke "cueact -s &" from your ~/.Xclients file and you'll have cueact
      automatically start each time you start X.



4 - Configuration file syntax :

The configuration file lists what command is associated with what type of
barcode. One barcode and its associated command are listed on a single line.
The format of this line is :

<CUECAT ID, MAX 18 LETTERS>:<BARCODE TYPE, MAX 3 LETTER>:<CMD> <CMD ARGUMENTS>

The command arguments are separated by spaces, unless they are isolated by
single or double quotes.

You can use jokers ('*' and '?') within the CueCat ID or the barcode type. For example, a CueCat ID of 0000?1*2 will match any CueCat ID with 4 leading zeros,
which 6th digit is 1 and last digit is 2.

Inside an argument, it is possible to specify a special substitution pattern
that CueAct will substitute at runtime by any part of the barcode swipe
information you wish. The substitution pattern has the following syntax :

[<v>,[a],[b]]

where <v> is 'i' for the CueCat device ID, 't' for the barcode type, or 'b'
for the barcode itself, [a] is the letter of the piece of information to start
substituting with, and [b] the number of letters to substitute with, from [a].
[a] and [b] are not required : if [a] is omitted, it is 0 by default (1st
letter). if [b] is omitted, it is the length of the piece of information by
default.

examples of configuration lines :

*:IBN:netscape -remote 'openURL(http://shop.barnesandnoble.com/booksearch/isbnIn
quiry.asp?ean=[b,,],new-window)'

tells CueAct that when it sees a IBN (ISBN) type of barcode scanned by any
CueCat, it should substitute "[b,,]" by the value of the entire barcode and run
the command.

00000000*:IB5:netscape -remote 'openURL(http://shop.barnesandnoble.com/booksearc
h/isbnInquiry.asp?ean=[b,,13],new-window)'

tells CueAct that when it sees a IB5 (ISBN-5) type of barcode scanned by a
CueCat with an ID starting with 8 zeros, it should substitute "[b,,13]" by the
13 first letters of the barcode and run the command.

*:UPA:/bin/bash -c "echo [i,5,2]"

tells CueAct that when it sees a UPA (UPC-A) type of barcode scanned by any
CueCat, it should substitute "[i,5,2]" by the 6th and the 7th digits of the
CueCat device ID and run the command.

Tip : when creating a configuration line, put CueAct in verbose mode so it'll
      tell you in detail what it scanned, and what it's doing with the
      information.



5 - LEGALESE

This software is released under the terms of the General Public License. See
the "COPYING" file for details.

Oh, and yes, I forgot :

DISCLAIMER :

I am not responsible for any damage caused by this software, whether it's on
your computer, your CueCat, or if it wipes out your hard-drive, or if it sets
off a nuclear bomb, etc ...
