#!/bin/more

Example Programs for use with Gamma under Photon
================================================

The example programs are intended to help you become confident in
developing a few test programs of your own, using the evaluation
software we have provided.  Although the example programs are often
only a few lines of actual code, they implement functionality that is
considerably more complex to express using other less advanced
programming languages.

We hope you find enough information in these example for you to start
developing your own applications.

You have received the following example programs:

Example 1. Gamma language overview
Example 2. Object-oriented features
Example 3. Lists
Example 4. Error handling
Example 5. Dynamic scoping
Example 6. Photon coding in Gamma
Example 7. Photon coding using PhAB
Example 8. Callbacks
Example 9. Timers
Example 10. Dynamic arrays
Example 11. Active values
Example 12. Inter-process communication (IPC)


How to run the examples
-----------------------

All examples cited in this document are automatically installed when
you install the evaluation version of Gamma from the floppy disk.  The
examples can be found under the directory:

	/usr/cogent/examples

Each example is named example01, example02, etc. Each example contains
extensive documentation to explain how each example program works.  To
view the source code for each example, just edit the appropriate
example file.  The /usr/cogent/examples directory also contains a
number of ".wgtw" window files created by the Photon Application
Builder (PhAB).

To run any of the examples, move to the /usr/cogent/examples directory
and type the name of the example (e.g. example01, example02, etc.).

To stop any of the examples, click on the menu button in the upper
left-hand corner of the window and select Close. Alternately,
highlight the example window and use the key-chord Ctrl+F4.


Example 1 - Gamma language overview
-----------------------------------

The syntax of Gamma is very similar to C.  Programmers familiar with C
will find they can immediately start programming in Gamma.  This first
example program demonstrates the basic similarities between Gamma and
the C language, and some important differences that highlight the
power of Gamma.

Example 2 - Object-oriented features
------------------------------------

Gamma implements Object Oriented Programming features which provide a
single-inheritance class mechanism with instance variables and
methods.  Since Gamma is an interpreter, the object definitions are
truly dynamic, allowing for run-time extensibility.  This example
provides the simplest of starting points to this key software
methodology.

Example 3 - Lists
-----------------

This example demonstrates some of the basics of list manipulation.
Since Gamma uses the SCADALisp engine, it inherits the rich set of
list manipulation functions for which LISP is known.

Example 4 - Error handling
--------------------------

This example demonstrates the error handling mechanisms available in
Gamma.  There are two basic means of trapping and handling errors.

1) Execute a protected block of code, and specify an error handler
which is only executed if an error occurs within the protected code.
If an error occurs, the error handling code is executed, and the error
condition is cleared.  This is the TRY/CATCH mechanism.
 
2) Execute a protected block of code, and specify a second block of
code which must be executed even if an error occurs in the first
block.  Normally when an error occurs, the execution stack is unwound
to the nearest error handler, aborting any intervening execution
immediately.  If a block of code must be run, even when an error
occurs, we want to unwind protect that code.  After the error is dealt
with, it is passed on up the stack rather than being cleared.  This is
the PROTECT/UNWIND mechanism.

Example 5 - Dynamic scoping
---------------------------

This example uses the error handling mechanisms from example04 to
demonstrate dynamic scoping.  Most compiled languages use lexical
scoping, which means that a variable is defined only where it is
visibly declared, either as an external global, file global, or local
variable.  Gamma uses dynamic scoping, meaning that a variable is
defined in any function which defines it, and in any function which
the defining function subsequently calls.  This powerful mechanism
allows the programmer to override global variables by defining them in
a higher scope, and then calling a function which believes itself to
be using a global variable.

One useful side-effect of dynamic scoping is that functions and
variables do not have to be declared before they are used in other
functions.  The function or variable only has to be declared when the
other function is actually run.

Example 6 - Photon coding in Gamma
----------------------------------

This example demonstrates how to create a Photon application in Gamma.
Since the Photon widget set is mapped as OOP classes in Gamma, any
Photon widget can be created using the new function and then
manipulated by simply modifying its instance variables.

Example 7 - Photon coding using PhAB
------------------------------------

This example shows the minimal program required to create a Photon
application using Gamma and a window created in PhAB.  PhAB creates a
file with a .wgtw extension which Gamma can read and display.  Widget
names in PhAB are mapped to Gamma global variables for easy access.
Creating windows using PhAB gives you all of the advantages of using a
graphical editor to quickly create your user interface and Gamma
allows you to create the application code in a fraction of the time
required for the same C functionality.

Example 8 - Callbacks
---------------------

After a window is created in code or loaded from a PhAB definition
file, one of the most common things to do is to attach callbacks to
the window items.  A callback is a block of code which will be
executed whenever a particular Photon event occurs. Gamma greatly
enhances the Photon callback mechanism to allow any Gamma expression
to be attached to a callback.  This example demonstrates some simple
Photon callbacks.

Example 9 - Timers
------------------

Timers are one of the easiest and most powerful features of Gamma.
There are three kinds of timers supported by Gamma:

	 every	- interval timer
	 after	- one-shot timer
	 at	- calendar (time-of-day) timer

This example demonstrates several uses of timers.

Example 10 - Dynamic arrays
---------------------------

Another powerful feature of Gamma is dynamic arrays. To make an array
in Gamma the developer can use either the array() or make-array()
functions.  The array() function creates a pre-built array while the
make-array() function creates an empty array of a given size.  If the
programmer attempts to write to an element beyond the end of the
array, the array will expand to accept the new element.  This
mechanism allows the programmer to approximate the size of the array,
and then increase its size as necessary simply by using it.

Example 11 - Active values
--------------------------

This example demonstrates the use of active values.  An active value
is a symbol which also carries code to be executed whenever its value
changes.  This is useful for adding side-effects to program variables.
For example, it might be very useful to add a function which will
update a Photon widget whenever a variable changes.  Active values
make it possible to implement algorithms such as forward-chaining
expert systems very easily.  An active value is established by calling
the add-set-function function.

Example 12 - Inter-process communication (IPC)
----------------------------------------------

This is a simple example of communicating with a Gamma application
through program control.  There is a text file called example12.doc in
the /usr/cogent/examples directory, which walks you through an
interactive session allowing you to modify a program as it runs.

The example12 program itself, will perform the same steps as the
interactive sample, without the interactive component.

To run, start example08 in the background by typing:

	example08 &

and then run this program using:

	example12

This program will exit when it completes. 

