ScriptControl 0.1 (SC01)
	(this primer brought to you by Benoit)

**"Implementation in the way" version, highly subject to changes !**

0. A SHORT INTRODUCTION TO SC
-----------------------------

 0.1 What is ScriptControl
 -------------------------
	ScriptControl is a scripting system that enables remote control of any
application through humanly readable commands and especially from scripts
written in any language (more or less) suited for that purpose.

	ScriptControl is currently written by :
- Benoit Triquet for the Python port, the SCmodule and SCserver design and
implementation (don't search, it's based on GoodIdeas TM from
the machine with a 68k and the Copper), and libSC design and implementation
except the templates parser.
- Osma Avhenlampi for the string based design, the templates design (don't
search, it's also based on DamnGoodIdeas TM from the machine with a 68k and
the Agnus) and the templates parser design and implementation in libSC.

	Of course we made our own additions and changed things we didn't liked
in the way the machine with a 68k and the Paula did scripting... But if you
have a knowledge of how scripting was done there, you get and idea of what
SC may bring to you, happy BeBox user and app developer.

	(Benoit personal credits : I'd like to thanks 5Bats (and IRC !) who
helped me to get these damn shared libs working for the dr6 shared libs
version of Python... R'alf (GeekPlayer writer) for his early comments
and help in the dispatch and reply design, and Guido Van Rossum for
Python !)
	Please notice that all the TMs, registered TMs and all that stuff are
owned by their owners. That way, it's settled.
	Please also forgive my bad English and mistakes, but French people
aren't very talented for foreign languages...

 0.2 What is SC *currently* !
 ----------------------------
	Currently it runs on the BeOS 1.1d6, locally (would go through TCP asap
BMessages support TCP), between C, C++ and Python 1.3.

 0.3 Advocacy : the choices for the first implementation
 (or what is portable, what is not, why did I choosed these languages)
 ---------------------------------------------------------------------
	Actually the provided libraries are in C rather than C++ because there
was no real need for OO design : basically, for the Be app programmer it is
a bunch of support functions to deal with some particular messages its app
may receive. Only those functions which deal with BMessages are (of course)
written in C++. They also mainly form the BeOS dependant part of SC.

	The Python part is written as a module, and is BeOS independant in its
API, except for the target identification part (of course it is Python
dependant :) but its implementation is BeOS dependant : the code dealing
with BMessages, BMessages, BApplication and the BRoster is BeOS dependant,
and though it's well isolated in functions, everything has been kept as a
single module for the sake of simplicity (for the Python user of course !)

	Why Python ?
(later :-)

 0.4 Availability
 ----------------
	Currently limited to documentation, it is still in alpha implementation,
and the design is still subject to changes.
	It will be available on ftp.amigalib.com, ftp.be.com, ...

	License terms : SC belongs to us but you are free to use it for now.
The docs, Python module and all the C/C++ code are (c)1996 by us.
Python has its own license and is distributed with SC for your convenience.
It is nonetheless subject to its own license terms. The port to the BeOS
I've done is also subject to Python's License.
	more babbles go there...

	Python for the BeBox is free, in both full source and binary
distribution.
	The SCmodule is free in binary form.
	SCserver is free in binary form.
	The protocol, specifications, API and all the docs remain our property
but are free and you are free to use them to design anything you want.
	If you want to use SC in your apps :
	libSC in binary form is shareware, for unrestricted integration in your
apps (ie you can distribute it with these apps, your users don't have to pay
the shareware fee). You can try it out but if you decide to use it (ie
release apps that use it) you have to pay a shareware fee of $10.
	The full development kit (full sources provided for information and
documentation purposes, support) is $50, for unrestricted integration in
your apps. You are explicitely asked not to redistribute the sources nor
modified versions of the SCserver or the libSC.

	For these fees you get a forever license on the version you register for
and preferred conditions on updates (ie free as long as we don't change our
policy, ie until Be buys SC and put it into BeOS (!) I personnaly accept 4
quad 604ev166 w/ 256 MB ram 10 GB hd, 3 21" displays BeBoxes as a payment.
After you see with Osma :-).



1. SC PRINCIPLES AND IDEAS
--------------------------
 1.1 Let's please everybody
 --------------------------
	As you may guess, SC is based on messages : a script or an app send
messages to another app.
   "- Simple, uh ?
	- Well, not so...
	- So what ? we have a nice BMessage'ing system with named and typed
fields, we send remote messages faster than light, and certainly don't need
another layer of encapsulation for these messages ! What may SC bring me ??
	- Actually, yes, if you pack your message from C++ code and have the doc
for the app you're talking to to know the type and name of each field, it's
simple, straightforward and easy. We're on the bleeding edge or not ?
	Right, if you're sending messages from C++ you probably don't need SC.
Though... we'll see later.
	But now suppose you want to do scripts : you may use shell scripts with
say a little /bin/send command which sends a message given an app signature
(I have a quit_app tool for when my apps forget to quit after having closed
all their windows).
	At that point I don't very well see how you'll tell send what are the
types and names for your message but you'll probably find a compact,
cryptographic way to do that in one single line...
	Or you may notice that the shell language is not very powerful, hard to
write and at least as hard to read, has almost no builtin ability... Well
it isn't suited for scripts of more than a few lines.
	- I guess you're right but...
	- So you agree to go and use another language. You still want an
interpreted language, easy to write, easy to read, which you could add the
communication features a bit more naturally than in shell scripts, btw that
is object oriented (why not ?), and as you're lazy (I am !), why not using
one of those nice scripting languages existing on other platforms : tcl,
perl, rexx, scheme, hypercard (?) or one of these OSA compliant languages...
and have something already written (:-), not new to some of the users...
If you haven't been convinced by my choice of Python (see 0.3), port or
write your own language and I'll tell you how to use it with SC !
	- Gimme ten seconds and I write one !
	- As you haven't already done so, we'll go on with Python. And anyway
you'll be able to use several scripting languages at the same time, if you
want."

	At that point we probably agree Python is a good choice but you also
keep in mind that you could use something else.

   "- Now suppose you use the language of your dreams, but unfortunately it
is BRexx, which doesn't have other types than the string. Don't you think
you're in trouble to build the wonderful 'plot' message which will make
Eboda PhotoShoops plot a wonderful pixel at float x,y ?
	And even if you have a language which knows what is an int and what is
a float, how the hell your send function will know if it must use AddLong
or AddFloat to pack the message when the script writer writes :
  send "PhotoShoops", "plot", 45, 32.8
	- Easy ! I provide a plot function which _knows_ it must pack two
floats !
	- You ? but you don't know how the messages PhotoShoops handles are,
because it is not yet written...
	- Mmmm I guess Eboda must provide it, so.
	- And how will Eboda be able to provide functions for BrainFuck v33
which will be released 2 years after PhotoShoops ?
	- Don't get me started ! Eboda can aswell provide a file describing
the messages PhotoShoops understands in a form defined by SC, I provide
a program to create BRexx functions from it, and so do BrainFuck v37
(time passes...) writers ! We would even have nice function calls whose
names tell what they do, rather than your ugly send !
	- I have to agree that such calls named by what they do would be
nicer, but there are some flaws in such a design : some languages won't
allow you to write something like :
  PhotoShoopsTargetDescriptor.plot 45, 32.8
(BRexx would have, btw) and you may also want to use ARPro (Art Region
Professional) plot function in the same script ! Of course they may
give you PhotoShoops_plot and ARPro_plot functions, but don't you think
it's ugly too ? And we didn't even talked about how to select one of the
3 PhotoShoops you have launched (of course this is an issue for you, you
have 256 MB of ram, and me only 16)
	- Actually this is an issue anyway, whichever language you use, even
C or C++.
	- Granted, but with say BrainFuck v39 you would have to write :
  PhotoShoops_plot photoShoops_3, 45, 32.8
  ARPro_plot aRPro, 54, 82.3
Nice isn't it ?? Of course in Python it would be :
  PhotoShoops_2.plot( 45, 32.8 )
  ARPro.plot( 54, 82.3 )
which is a bit better. But as you have payed attention to what I said, you
will have noticed that obviously these functions have been written :-)
	* Either they have been written in C by the functions translator (this
can be quite systematic, especially if I give you a sample translator you
adapt for your language : only the part of the code which ties these
functions with your interpreter is scripting language dependant. C is typed
so you won't have trouble to pack typed BMessages ) and the "package" has
been loaded on the fly : not all the languages allow that. 
	Even my current Python doesn't, though it has at least provision for,
so it's not envisageable for now. And even for later, as some languages
nice by other respects will never have dynamic loading, and I don't want to
throw them away.
	And anyway the user will have to issue statements before being able to
use the package, check for the success of the loading... It's damn too hard
for an occasional script writer who doesn't have a clue at script
programming, except that he _wants_ a perfect sinusoid in his PhotoShoops
window, and vaguely remembers how to do this with a for loop, because he
used to learn Basic at school.
	* Or they have been written in the scripting language. We can more or
less imagine that the translator do that, though it will be a real hack if
the language is type-less : the generated would have to rely on more or less
type Add<any type> functions that pack a message ala Application kit and
would be integrated to the set of builtin functions of your interpreter.
You _can_ do that because you had to give me a special version of your
interpreter for the SCserver, and no, I won't make SCserver issue
  system("BRexx thescript.brexx");
but more on this later.
	Anyway there is another issue, with our dumb PhotoShoops user. He won't
know how to install the "package" for the language he choosed from the file
Eboda gave him (ok I wonder how he managed to install SC, but that's MY
problem). You probably could make a nice drag'n'drop tool for that purpose,
or do it from PhotoShoops'installer script, but if something goes wrong,
he will never manage to fix it.
	This is arguable, but I prefer installation-less systems :-)
	- So that the scripting languages you installed don't know at all how to
pack the plot message for PhotoShoops.
	- Exactly ! this is the point of the one-string argument passing system.
If 




Benoit Triquet
triquet_ben@lsi.supelec.fr
