head	1.20;
access;
symbols;
locks; strict;
comment	@# @;


1.20
date	2001.07.08.14.42.02;	author david;	state Exp;
branches;
next	1.19;

1.19
date	2001.07.08.08.04.48;	author david;	state Exp;
branches;
next	1.18;

1.18
date	2001.07.08.07.56.11;	author david;	state Exp;
branches;
next	1.17;

1.17
date	2001.07.06.13.52.25;	author david;	state Exp;
branches;
next	1.16;

1.16
date	2001.07.06.13.18.00;	author david;	state Exp;
branches;
next	1.15;

1.15
date	2001.06.28.18.03.20;	author david;	state Exp;
branches;
next	1.14;

1.14
date	2001.06.28.14.18.55;	author david;	state Exp;
branches;
next	1.13;

1.13
date	2001.06.28.14.17.57;	author david;	state Exp;
branches;
next	1.12;

1.12
date	2001.06.28.13.16.06;	author david;	state Exp;
branches;
next	1.11;

1.11
date	2001.06.28.12.50.29;	author david;	state Exp;
branches;
next	1.10;

1.10
date	2001.06.28.10.56.50;	author david;	state Exp;
branches;
next	1.9;

1.9
date	2001.06.28.06.23.27;	author david;	state Exp;
branches;
next	1.8;

1.8
date	2001.06.28.06.07.13;	author david;	state Exp;
branches;
next	1.7;

1.7
date	2001.06.28.05.43.45;	author david;	state Exp;
branches;
next	1.6;

1.6
date	2001.06.28.01.36.11;	author david;	state Exp;
branches;
next	1.5;

1.5
date	2000.12.12.15.26.44;	author david;	state Exp;
branches;
next	1.4;

1.4
date	2000.12.12.14.59.00;	author david;	state Exp;
branches;
next	1.3;

1.3
date	2000.12.12.14.38.16;	author david;	state Exp;
branches;
next	1.2;

1.2
date	2000.12.12.14.31.11;	author david;	state Exp;
branches;
next	1.1;

1.1
date	2000.11.01.01.15.05;	author david;	state Exp;
branches;
next	;


desc
@@


1.20
log
@*** empty log message ***
@
text
@Introduction
------------
Welcome to the ICCS 2001 release of pCG, version 0.1!

The name "pCG" is symbolic of a process operating upon a CG. 
 
Go to http://www.adelaide.net.au/~dbenn/Masters/ for the context of this 
language which is the outcome of my coursework Masters thesis at the 
University of South Australia under the supervision of Dan Corbett.

Please send all comments and questions to me at djbenn@@ozemail.com.au or
david_benn@@asclink.net.au

Installation
------------
By reading this file, you've completed the most important step: unzipping the
archive with a WinZip or zip utility.

The distribution comes with pre-built Java code (in the lib directory) and 
invocation scripts for Unix and Windows: pCG and pCG.bat respectively. Change 
the paths in the invocation script to match the place where you unzipped pCG 
to yield a cgp directory.

Optionally add the script to your path. On a Win95/98 machine, you can do 
this by adding to your c:\autoexec.bat file's exiting SET PATH command, or 
adding after this a command such as:

	SET PATH=%PATH%;C:\cgp\pCG

assuming you have unzipped the archive at the top-level of your C drive. On
a Windows NT machine you or your administrator will have to add to the path
via the System Control Panel.

Under Unix, the path setting procedure will vary depending upon the shell
you're using. For csh and tcsh, add to the path line in your .cshrc file, 
while for bash (e.g. under Linux) add to the PATH line in a manner such as 
this:

	PATH=$PATH:$HOME/bin:/usr/local/Acrobat4/bin:$HOME/cgp

For Windows machines, reboot so that the new path comes into effect. For
Unix systems, source the .cshrc file or .bash_profile file (with the source
and "." commands respectively).
 
Moreover, if you have more than one JDK/JRE installed on your system or the 
java executable is not on your path, you may wish to fully qualify the path 
to the java interpreter in the pCG Unix shell script or DOS batch file, e.g. 
in the pCG script, instead of:

	java -classpath $ANTLR_HOME/antlr.jar:...

you could have:

	/usr/local/jdk1.2.2/bin/java -classpath $ANTLR_HOME/antlr.jar:...

pCG *requires* Java 2, JDK/JRE 1.2.2. I make no guarantees about whether
it will work with any other version of Java at this time.

pCG comes with the Java class libraries it requires in cgp/lib, specifically 
those for Antlr (2.7.0) and Notio (0.2.2).
 
pCG has been tested under Linux 2.2 (RedHat 6.0), Windows 98, and a few
versions of Solaris/SunOS, but primarily the first two. Despite being
Java software, I won't make any claims about whether pCG will run on
other operating systems, but please let me know if you are using another
OS apart from the ones listed, e.g. Mac.

Usage
-----
pCG is a command-line interpreter but has no interactive mode. Edit a pCG
file, say "foo.cgp", with your favourite text editor, make sure pCG (or 
pCG.bat if you're using Windows) is on your path or fully qualify its path,
and run it:

	pCG foo.cgp

Alternatively, you can add an interpreter invocation line to the top of
the file (given a Unix-style shell), e.g. see cgp/examples/gfx/tree.cgp.

Harry Delugach's excellent CharGer CG editor is useful for viewing files in 
the examples directory with a ".cgf" or ".CGF" suffix.
 
To test pCG against the final CGTools workshop graph set, do the following
from a shell or MS-DOS prompt on your system (using the appropriate path
separator of course) where <root> is where you installed pCG:

 o Change directory to <root>/cgp/examples/CGTools01
 
 o Run pCG with final.cgp as the sole argument.

 o Read that program's comments for more information.

 o A minimal pCG program is also present in that directory, tiny.cgp,
   which opens a single file, reads a CG stream into a list, and prints 
   each graph in it. Assuming pCG is on your path and the above directory
   is your working directory, you could type the following:

	pCG tiny.cgp final/final_graphs_level1.cgf

 o See the other program in that directory which relates to the basic 
   graph set: basic-info.cgp

 o Programs for a simple actor and Mineau's iterative factorial process
   have also been converted to make use of the new June 2001 compliant 
   CG Standard CGIF parser.

Note that pCG program files have by convention, a ".cgp" suffix, while CGIF 
files end with ".cgf".

Note also that example programs have MS-DOS line termination character
sequences so that they may be viewed under both Unix and Windows.

pCG allows you to specify whether to generate CGIF or LF output, as well as
the kind of CGIF parser and CGIF generator. Look for "option cgifparser = ..."
and "option cgifgen = ..." in example pCG programs, which specify the Java
class to be used.

All graphs in code found in cgp/examples/CGTools01 are June 2001 CG Standard
compliant with respect to CGIF. Example code elsewhere still uses the older 
CGIF version.

Also, some programs generate CGIF, LF, or a mixture, as output.

Documentation
-------------
The file pCG.pdf is based upon a chapter from my thesis which describes 
pCG in some detail. References to other parts of the thesis should be 
ignored, or you can download the thesis from the aforementioned URL.
Between this and the example programs, you should gain a good understanding 
of the language. I may add more information later. Please ignore any message
you may see from Acrobat Reader regarding being unable to find the StarMath
font (which comes with Sun's StarOffice). I will fix this at some stage, but
there appears to be no impact with respect to reading the document.

The docs directory contains EBNF for pCG derived automatically from the ANTLR
grammars (docs/CGPParser.html, AntlrCGIFParser.html). JavaDocs generated from
the source code are also included (docs/index.html) and are definitive with
 
respect to pCG's run-time type attributes and operations. See the source code
(under cgp directory) for more non-JavaDoc comments.

Distribution
------------
pCG distribution is freely redistributable under the Gnu Public Licence.
See gpl.html. See also the licensing directory under <root>/cgp/lib.

Bugs
----
See the aforementioned web page for the current bug list. This software 
requires real testing by real users, i.e. people other than me who are 
going to try to apply it to their own problems.

If you're using pCG under Windows, you may see one or more errors such as
"non-fatal JIT error" when running pCG programs. You can ignore this as
there is no side effect that I've ever noticed. I have seen this error
even from commercial Java programs.

Build Notes
-----------
o Only people who wish to extend or modify pCG need read this section.

o The Makefile has only been tested under RedHat Linux 6.0, but should
  work under all Unices, and may be adaptable to other platforms with
  the make utility.

o If the make process stops with an error re: AntlrCGIFParser, just type
  make again and all will be well. There must be a bug in my Makefile
  but I haven't had time to track this down.
  
o The symbolic links to cgp/*TokenTypes.txt is necessary for the 
  CGPInterpreter class's importVocab directive which seems to look in
  the Makefile's directory rather than in the cgp directory for
  the tokens file. This looks like a bug in ANTLR since exportVocab
  writes to the cgp directory. Need to workaound this since not all
  OSes have symbolic links which would mean taking a copy of the
  tokens file. How to fix? => i) move Makefile to cgp directory?;
  ii) run make from cgp/cgp directory?

o  Note that it should be possible to use $ANTLR_HOME/antlr.jar but a class
   required by SemanticException.toString() -- FileLineFormatter.class -- is
   not contained within antlr.jar, but is contained in $ANTLR_HOME/antlr.
   We get around this by calling SemanticException.getMessage().

o Please note that the Revision Control System (RCS) has been used for 
  version control, hence the RCS directories everywhere.

Thanks
------
Terrence Parr's fantastic LL(k) parser generator tool, ANTLR, reduced the 
size of the code of pCG by several thousand lines, and made it easy for me 
to enforce a clean separation between the parser and the core interpreter.

Finnegan Southey's Notio Java API which embodies a significant part of the 
functionality laid out in the proposed CG ANSI Standard, helped me enormously
in the implementation of pCG, particularly its CGIF parsing capability. In
order to make this conform to the June 2001 CG Standard however, I wrote my
own CGIF Parser, again, in ANTLR (see cgp/cgp/translators). Hopefully this
can be added to the Notio distribution. This is specified in pCG programs via
the directive: 'option cgifparser = "cgp.translators.CGIFParser";'.

Harry Delugach's CharGer CG editor has been a great help with actors and
general non-trivial CG creation and visualisation.

Guy Mineau, of course, for presenting the process formalism at ICCS 1998.

Dan Corbett, for his enthusisasm and encouragement re: my thesis work.

My wife Karen, for all the coffee and hugs.


David Benn, Adelaide, July 2001
@


1.19
log
@*** empty log message ***
@
text
@d136 4
a139 3
grammar (docs/CGPParser.html). JavaDocs generated from the source code are 
also included (docs/index.html). See the source code (under cgp directory)
for more non-JavaDoc comments.
@


1.18
log
@*** empty log message ***
@
text
@d45 10
a54 3
Moreover, if you have more than one JDK/JRE installed on your system you
may wish to fully qualify the path to the java interpreter in the pCG
Unix shell script or DOS batch file. That's it.
d95 2
a96 2
   each in turn. Assuming pCG is on your path and the above directory was
   your working directory, you could type the following:
@


1.17
log
@*** empty log message ***
@
text
@d1 202
a202 202
Introduction
------------
Welcome to the ICCS 2001 release of pCG, version 0.1!

The name "pCG" is symbolic of a process operating upon a CG. 
 
Go to http://www.adelaide.net.au/~dbenn/Masters/ for the context of this 
language which is the outcome of my coursework Masters thesis at the 
University of South Australia under the supervision of Dan Corbett.

Please send all comments and questions to me at djbenn@@ozemail.com.au or
david_benn@@asclink.net.au

Installation
------------
By reading this file, you've completed the most important step: unzipping the
archive with a WinZip or zip utility.

The distribution comes with pre-built Java code (in the lib directory) and 
invocation scripts for Unix and Windows: pCG and pCG.bat respectively. Change 
the paths in the invocation script to match the place where you unzipped pCG 
to yield a cgp directory.

Optionally add the script to your path. On a Win95/98 machine, you can do 
this by adding to your c:\autoexec.bat file's exiting SET PATH command, or 
adding after this a command such as:

	SET PATH=%PATH%;C:\cgp\pCG

assuming you have unzipped the archive at the top-level of your C drive. On
a Windows NT machine you or your administrator will have to add to the path
via the System Control Panel.

Under Unix, the path setting procedure will vary depending upon the shell
you're using. For csh and tcsh, add to the path line in your .cshrc file, 
while for bash (e.g. under Linux) add to the PATH line in a manner such as 
this:

	PATH=$PATH:$HOME/bin:/usr/local/Acrobat4/bin:$HOME/cgp

For Windows machines, reboot so that the new path comes into effect. For
Unix systems, source the .cshrc file or .bash_profile file (with the source
and "." commands respectively).
 
Moreover, if you have more than one JDK/JRE installed on your system you
may wish to fully qualify the path to the java interpreter in the pCG
Unix shell script or DOS batch file. That's it.

pCG *requires* Java 2, JDK/JRE 1.2.2. I make no guarantees about whether
it will work with any other version of Java at this time.

pCG comes with the Java class libraries it requires in cgp/lib, specifically 
those for Antlr (2.7.0) and Notio (0.2.2).
 
pCG has been tested under Linux 2.2 (RedHat 6.0), Windows 98, and a few
versions of Solaris/SunOS, but primarily the first two. Despite being
Java software, I won't make any claims about whether pCG will run on
other operating systems, but please let me know if you are using another
OS apart from the ones listed, e.g. Mac.

Usage
-----
pCG is a command-line interpreter but has no interactive mode. Edit a pCG
file, say "foo.cgp", with your favourite text editor, make sure pCG (or 
pCG.bat if you're using Windows) is on your path or fully qualify its path,
and run it:

	pCG foo.cgp

Alternatively, you can add an interpreter invocation line to the top of
the file (given a Unix-style shell), e.g. see cgp/examples/gfx/tree.cgp.

Harry Delugach's excellent CharGer CG editor is useful for viewing files in 
the examples directory with a ".cgf" or ".CGF" suffix.
 
To test pCG against the final CGTools workshop graph set, do the following
from a shell or MS-DOS prompt on your system (using the appropriate path
separator of course) where <root> is where you installed pCG:

 o Change directory to <root>/cgp/examples/CGTools01
 
 o Run pCG with final.cgp as the sole argument.

 o Read that program's comments for more information.

 o A minimal pCG program is also present in that directory, tiny.cgp,
   which opens a single file, reads a CG stream into a list, and prints 
   each in turn. Assuming pCG is on your path and the above directory was
   your working directory, you could type the following:

	pCG tiny.cgp final/final_graphs_level1.cgf

 o See the other program in that directory which relates to the basic 
   graph set: basic-info.cgp

 o Programs for a simple actor and Mineau's iterative factorial process
   have also been converted to make use of the new June 2001 compliant 
   CG Standard CGIF parser.

Note that pCG program files have by convention, a ".cgp" suffix, while CGIF 
files end with ".cgf".

Note also that example programs have MS-DOS line termination character
sequences so that they may be viewed under both Unix and Windows.

pCG allows you to specify whether to generate CGIF or LF output, as well as
the kind of CGIF parser and CGIF generator. Look for "option cgifparser = ..."
and "option cgifgen = ..." in example pCG programs, which specify the Java
class to be used.

All graphs in code found in cgp/examples/CGTools01 are June 2001 CG Standard
compliant with respect to CGIF. Example code elsewhere still uses the older 
CGIF version.

Also, some programs generate CGIF, LF, or a mixture, as output.

Documentation
-------------
The file pCG.pdf is based upon a chapter from my thesis which describes 
pCG in some detail. References to other parts of the thesis should be 
ignored, or you can download the thesis from the aforementioned URL.
Between this and the example programs, you should gain a good understanding 
of the language. I may add more information later. Please ignore any message
you may see from Acrobat Reader regarding being unable to find the StarMath
font (which comes with Sun's StarOffice). I will fix this at some stage, but
there appears to be no impact with respect to reading the document.

The docs directory contains EBNF for pCG derived automatically from the ANTLR
grammar (docs/CGPParser.html). JavaDocs generated from the source code are 
also included (docs/index.html). See the source code (under cgp directory)
for more non-JavaDoc comments.

Distribution
------------
pCG distribution is freely redistributable under the Gnu Public Licence.
See gpl.html. See also the licensing directory under <root>/cgp/lib.

Bugs
----
See the aforementioned web page for the current bug list. This software 
requires real testing by real users, i.e. people other than me who are 
going to try to apply it to their own problems.

If you're using pCG under Windows, you may see one or more errors such as
"non-fatal JIT error" when running pCG programs. You can ignore this as
there is no side effect that I've ever noticed. I have seen this error
even from commercial Java programs.

Build Notes
-----------
o Only people who wish to extend or modify pCG need read this section.

o The Makefile has only been tested under RedHat Linux 6.0, but should
  work under all Unices, and may be adaptable to other platforms with
  the make utility.

o If the make process stops with an error re: AntlrCGIFParser, just type
  make again and all will be well. There must be a bug in my Makefile
  but I haven't had time to track this down.
  
o The symbolic links to cgp/*TokenTypes.txt is necessary for the 
  CGPInterpreter class's importVocab directive which seems to look in
  the Makefile's directory rather than in the cgp directory for
  the tokens file. This looks like a bug in ANTLR since exportVocab
  writes to the cgp directory. Need to workaound this since not all
  OSes have symbolic links which would mean taking a copy of the
  tokens file. How to fix? => i) move Makefile to cgp directory?;
  ii) run make from cgp/cgp directory?

o  Note that it should be possible to use $ANTLR_HOME/antlr.jar but a class
   required by SemanticException.toString() -- FileLineFormatter.class -- is
   not contained within antlr.jar, but is contained in $ANTLR_HOME/antlr.
   We get around this by calling SemanticException.getMessage().

o Please note that the Revision Control System (RCS) has been used for 
  version control, hence the RCS directories everywhere.

Thanks
------
Terrence Parr's fantastic LL(k) parser generator tool, ANTLR, reduced the 
size of the code of pCG by several thousand lines, and made it easy for me 
to enforce a clean separation between the parser and the core interpreter.

Finnegan Southey's Notio Java API which embodies a significant part of the 
functionality laid out in the proposed CG ANSI Standard, helped me enormously
in the implementation of pCG, particularly its CGIF parsing capability. In
order to make this conform to the June 2001 CG Standard however, I wrote my
own CGIF Parser, again, in ANTLR (see cgp/cgp/translators). Hopefully this
can be added to the Notio distribution. This is specified in pCG programs via
the directive: 'option cgifparser = "cgp.translators.CGIFParser";'.

Harry Delugach's CharGer CG editor has been a great help with actors and
general non-trivial CG creation and visualisation.

Guy Mineau, of course, for presenting the process formalism at ICCS 1998.

Dan Corbett, for his enthusisasm and encouragement re: my thesis work.

My wife Karen, for all the coffee and hugs.


David Benn, Adelaide, July 2001
@


1.16
log
@*** empty log message ***
@
text
@d1 202
a202 198
Introduction
------------
Welcome to the ICCS 2001 release of pCG, version 0.1!

The name "pCG" is symbolic of a process operating upon a CG. 
 
Go to http://www.adelaide.net.au/~dbenn/Masters/ for the context of this 
language which is the outcome of my coursework Masters thesis at the 
University of South Australia under the supervision of Dan Corbett.

Please send all comments and questions to me at djbenn@@ozemail.com.au or
david_benn@@asclink.net.au

Installation
------------
By reading this file, you've completed the most important step: unzipping the
archive with a WinZip or zip utility.

The distribution comes with pre-built Java code (in the lib directory) and 
invocation scripts for Unix and Windows: pCG and pCG.bat respectively. Change 
the paths in the invocation script to match the place where you unzipped pCG 
to yield a cgp directory.

Optionally add the script to your path. On a Win95/98 machine, you can do 
this by adding to your c:\autoexec.bat file's exiting SET PATH command, or 
adding after this a command such as:

	SET PATH=%PATH%;C:\cgp\pCG

assuming you have unzipped the archive at the top-level of your C drive. On
a Windows NT machine you or your administrator will have to add to the path
from the Environment tabbed pane in the System Control Panel.

Under Unix, the path setting procedure will vary depending upon the shell
you're using. For csh and tcsh, add to the path line in your .cshrc file, 
while for bash (e.g. under Linux) add to the PATH line in a manner such as 
this:

	PATH=$PATH:$HOME/bin:/usr/local/Acrobat4/bin:$HOME/cgp

Moreover, if you have more than one JDK/JRE installed on your system you
may wish to fully qualify the path to the java interpreter in the pCG
Unix shell script or DOS batch file. That's it.

pCG *requires* Java 2, JDK/JRE 1.2.2. I make no guarantees about whether
it will work with any other version of Java at this time.

pCG comes with the Java class libraries it requires in cgp/lib, specifically 
those for Antlr (2.7.0) and Notio (0.2.2).
 
pCG has been tested under Linux 2.2 (RedHat 6.0), Windows 98, and a few
versions of Solaris/SunOS, but primarily the first two. Despite being
Java software, I won't make any claims about whether pCG will run on
other operating systems, but please let me know if you are using another
OS apart from the ones listed, e.g. Mac.

Usage
-----
pCG is a command-line interpreter but has no interactive mode. Edit a pCG
file, say "foo.cgp", with your favourite text editor, make sure pCG (or 
pCG.bat if you're using Windows) is on your path or fully qualify its path,
and run it:

	pCG foo.cgp

Alternatively, you can add an interpreter invocation line to the top of
the file (given a Unix-style shell), e.g. see cgp/examples/gfx/tree.cgp.

Harry Delugach's excellent CharGer CG editor is useful for viewing files in 
the examples directory with a ".cgf" or ".CGF" suffix.
 
To test pCG against the final CGTools workshop graph set, do the following
from a shell or MS-DOS prompt on your system (using the appropriate path
separator of course) where <root> is where you installed pCG:

 o Change directory to <root>/cgp/examples/CGTools01
 
 o Run pCG with final.cgp as the sole argument.

 o Read that program's comments for more information.

 o A minimal pCG program is also present in that directory, tiny.cgp,
   which opens a single file, reads a CG stream into a list, and prints 
   each in turn. Assuming pCG is on your path and the above directory was
   your working directory, you could type the following:

	pCG tiny.cgp final/final_graphs_level1.cgf

 o See the other program in that directory which relates to the basic 
   graph set: basic-info.cgp

 o Programs for a simple actor and Mineau's iterative factorial process
   have also been converted to make use of the new June 2001 compliant 
   CG Standard CGIF parser.

Note that pCG program files have by convention, a ".cgp" suffix, while CGIF 
files end with ".cgf".

Note also that example programs have MS-DOS line termination character
sequences so that they may be viewed under both Unix and Windows.

pCG allows you to specify whether to generate CGIF or LF output, as well as
the kind of CGIF parser and CGIF generator. Look for "option cgifparser = ..."
and "option cgifgen = ..." in example pCG programs, which specify the Java
class to be used.

All graphs in code found in cgp/examples/CGTools01 are June 2001 CG Standard
compliant with respect to CGIF. Example code elsewhere still uses the older 
CGIF version.

Also, some programs generate CGIF, LF, or a mixture, as output.

Documentation
-------------
The file pCG.pdf is based upon a chapter from my thesis which describes 
pCG in some detail. References to other parts of the thesis should be 
ignored, or you can download the thesis from the aforementioned URL.
Between this and the example programs, you should gain a good understanding 
of the language. I may add more information later. Please ignore any message
you may see from Acrobat Reader regarding being unable to find the StarMath
font (which comes with Sun's StarOffice). I will fix this at some stage, but
there appears to be no impact with respect to reading the document.

The docs directory contains EBNF for pCG derived automatically from the ANTLR
grammar (docs/CGPParser.html). JavaDocs generated from the source code are 
also included (docs/index.html). See the source code (under cgp directory)
for more non-JavaDoc comments.

Distribution
------------
pCG distribution is freely redistributable under the Gnu Public Licence.
See gpl.html. See also the licensing directory under <root>/cgp/lib.

Bugs
----
See the aforementioned web page for the current bug list. This software 
requires real testing by real users, i.e. people other than me who are 
going to try to apply it to their own problems.

If you're using pCG under Windows, you may see one or more errors such as
"non-fatal JIT error" when running pCG programs. You can ignore this as
there is no side effect that I've ever noticed. I have seen this error
even from commercial Java programs.

Build Notes
-----------
o Only people who wish to extend or modify pCG need read this section.

o The Makefile has only been tested under RedHat Linux 6.0, but should
  work under all Unices, and may be adaptable to other platforms with
  the make utility.

o If the make process stops with an error re: AntlrCGIFParser, just type
  make again and all will be well. There must be a bug in my Makefile
  but I haven't had time to track this down.
  
o The symbolic links to cgp/*TokenTypes.txt is necessary for the 
  CGPInterpreter class's importVocab directive which seems to look in
  the Makefile's directory rather than in the cgp directory for
  the tokens file. This looks like a bug in ANTLR since exportVocab
  writes to the cgp directory. Need to workaound this since not all
  OSes have symbolic links which would mean taking a copy of the
  tokens file. How to fix? => i) move Makefile to cgp directory?;
  ii) run make from cgp/cgp directory?

o  Note that it should be possible to use $ANTLR_HOME/antlr.jar but a class
   required by SemanticException.toString() -- FileLineFormatter.class -- is
   not contained within antlr.jar, but is contained in $ANTLR_HOME/antlr.
   We get around this by calling SemanticException.getMessage().

o Please note that the Revision Control System (RCS) has been used for 
  version control, hence the RCS directories everywhere.

Thanks
------
Terrence Parr's fantastic LL(k) parser generator tool, ANTLR, reduced the 
size of the code of pCG by several thousand lines, and made it easy for me 
to enforce a clean separation between the parser and the core interpreter.

Finnegan Southey's Notio Java API which embodies a significant part of the 
functionality laid out in the proposed CG ANSI Standard, helped me enormously
in the implementation of pCG, particularly its CGIF parsing capability. In
order to make this conform to the June 2001 CG Standard however, I wrote my
own CGIF Parser, again, in ANTLR (see cgp/cgp/translators). Hopefully this
can be added to the Notio distribution. This is specified in pCG programs via
the directive: 'option cgifparser = "cgp.translators.CGIFParser";'.

Harry Delugach's CharGer CG editor has been a great help with actors and
general non-trivial CG creation and visualisation.

Guy Mineau, of course, for presenting the process formalism at ICCS 1998.

Dan Corbett, for his enthusisasm and encouragement re: my thesis work.

My wife Karen, for all the coffee and hugs.


David Benn, Adelaide, July 2001
@


1.15
log
@*** empty log message ***
@
text
@d16 3
d21 20
a40 2
the paths in the invocation script to match the place where you unzipped
pCG to yield a cgp directory. Optionally add the script to your path.
d42 1
a42 1
may wish to fully qualify the path to the java interpreter in this pCG
d80 8
a87 1
 o Read that program's comments.
d89 2
a90 2
 o See also the other program in that directory which relates to the
   basic graph set: basic-info.cgp
d108 2
a109 2
compliant with respect to CGIF. Some example code elsewhere still uses the
older CGIF version, e.g. see cgp/examples/Larflast.
d198 1
a198 1
David Benn, Adelaide, June 2001
@


1.14
log
@*** empty log message ***
@
text
@d20 3
a22 1
That's it.
d46 1
a46 1
the file (given a Unix-style shell), e.g. see examples/gfx/tree.cgp.
d59 1
a59 1
 o See also that program's comments.
d83 1
a83 1
Also, some programs generate CGIF, LF, or a mixture.
d91 4
a94 1
of the language. I may add more information later.
d111 5
@


1.13
log
@*** empty log message ***
@
text
@a71 5
Be aware that some example programs may require you to change file paths
to suit your installation. If a program fails to do what you expect,
check whether it accesses any files. The CGTools01 examples do not require
such changes however.

@


1.12
log
@*** empty log message ***
@
text
@d1 165
a165 165
Introduction
------------
Welcome to the ICCS 2001 release of pCG, version 0.1!

The name "pCG" is symbolic of a process operating upon a CG. 
 
Go to http://www.adelaide.net.au/~dbenn/Masters/ for the context of this 
language which is the outcome of my coursework Masters thesis at the 
University of South Australia under the supervision of Dan Corbett.

Please send all comments and questions to me at djbenn@@ozemail.com.au or
david_benn@@asclink.net.au

Installation
------------
The distribution comes with pre-built Java code (in the lib directory) and 
invocation scripts for Unix and Windows: pCG and pCG.bat respectively. Change 
the paths in the invocation script to match the place where you unzipped
pCG to yield a cgp directory. Optionally add the script to your path.
That's it.

pCG *requires* Java 2, JDK/JRE 1.2.2. I make no guarantees about whether
it will work with any other version of Java at this time.

pCG comes with the Java class libraries it requires in cgp/lib, specifically 
those for Antlr (2.7.0) and Notio (0.2.2).
 
pCG has been tested under Linux 2.2 (RedHat 6.0), Windows 98, and a few
versions of Solaris/SunOS, but primarily the first two. Despite being
Java software, I won't make any claims about whether pCG will run on
other operating systems, but please let me know if you are using another
OS apart from the ones listed, e.g. Mac.

Usage
-----
pCG is a command-line interpreter but has no interactive mode. Edit a pCG
file, say "foo.cgp", with your favourite text editor, make sure pCG (or 
pCG.bat if you're using Windows) is on your path or fully qualify its path,
and run it:

	pCG foo.cgp

Alternatively, you can add an interpreter invocation line to the top of
the file (given a Unix-style shell), e.g. see examples/gfx/tree.cgp.

Harry Delugach's excellent CharGer CG editor is useful for viewing files in 
the examples directory with a ".cgf" or ".CGF" suffix.
 
To test pCG against the final CGTools workshop graph set, do the following
from a shell or MS-DOS prompt on your system (using the appropriate path
separator of course) where <root> is where you installed pCG:

 o Change directory to <root>/cgp/examples/CGTools01
 
 o Run pCG with final.cgp as the sole argument.

 o See also that program's comments.

 o See also the other program in that directory which relates to the
   basic graph set: basic-info.cgp

 o Programs for a simple actor and Mineau's iterative factorial process
   have also been converted to make use of the new June 2001 compliant 
   CG Standard CGIF parser.

Note that pCG program files have by convention, a ".cgp" suffix, while CGIF 
files end with ".cgf".

Note also that example programs have MS-DOS line termination character
sequences so that they may be viewed under both Unix and Windows.

Be aware that some example programs may require you to change file paths
to suit your installation. If a program fails to do what you expect,
check whether it accesses any files. The CGTools01 examples do not require
such changes however.

pCG allows you to specify whether to generate CGIF or LF output, as well as
the kind of CGIF parser and CGIF generator. Look for "option cgifparser = ..."
and "option cgifgen = ..." in example pCG programs, which specify the Java
class to be used.

All graphs in code found in cgp/examples/CGTools01 are June 2001 CG Standard
compliant with respect to CGIF. Some example code elsewhere still uses the
older CGIF version, e.g. see cgp/examples/Larflast.

Also, some programs generate CGIF, LF, or a mixture.

Documentation
-------------
The file pCG.pdf is based upon a chapter from my thesis which describes 
pCG in some detail. References to other parts of the thesis should be 
ignored, or you can download the thesis from the aforementioned URL.
Between this and the example programs, you should gain a good understanding 
of the language. I may add more information later.

The docs directory contains EBNF for pCG derived automatically from the ANTLR
grammar (docs/CGPParser.html). JavaDocs generated from the source code are 
also included (docs/index.html). See the source code (under cgp directory)
for more non-JavaDoc comments.

Distribution
------------
pCG distribution is freely redistributable under the Gnu Public Licence.
See gpl.html. See also the licensing directory under <root>/cgp/lib.

Bugs
----
See the aforementioned web page for the current bug list. This software 
requires real testing by real users, i.e. people other than me who are 
going to try to apply it to their own problems.

Build Notes
-----------
o Only people who wish to extend or modify pCG need read this section.

o The Makefile has only been tested under RedHat Linux 6.0, but should
  work under all Unices, and may be adaptable to other platforms with
  the make utility.

o If the make process stops with an error re: AntlrCGIFParser, just type
  make again and all will be well. There must be a bug in my Makefile
  but I haven't had time to track this down.
  
o The symbolic links to cgp/*TokenTypes.txt is necessary for the 
  CGPInterpreter class's importVocab directive which seems to look in
  the Makefile's directory rather than in the cgp directory for
  the tokens file. This looks like a bug in ANTLR since exportVocab
  writes to the cgp directory. Need to workaound this since not all
  OSes have symbolic links which would mean taking a copy of the
  tokens file. How to fix? => i) move Makefile to cgp directory?;
  ii) run make from cgp/cgp directory?

o  Note that it should be possible to use $ANTLR_HOME/antlr.jar but a class
   required by SemanticException.toString() -- FileLineFormatter.class -- is
   not contained within antlr.jar, but is contained in $ANTLR_HOME/antlr.
   We get around this by calling SemanticException.getMessage().

o Please note that the Revision Control System (RCS) has been used for 
  version control, hence the RCS directories everywhere.

Thanks
------
Terrence Parr's fantastic LL(k) parser generator tool, ANTLR, reduced the 
size of the code of pCG by several thousand lines, and made it easy for me 
to enforce a clean separation between the parser and the core interpreter.

Finnegan Southey's Notio Java API which embodies a significant part of the 
functionality laid out in the proposed CG ANSI Standard, helped me enormously
in the implementation of pCG, particularly its CGIF parsing capability. In
order to make this conform to the June 2001 CG Standard however, I wrote my
own CGIF Parser, again, in ANTLR (see cgp/cgp/translators). Hopefully this
can be added to the Notio distribution. This is specified in pCG programs via
the directive: 'option cgifparser = "cgp.translators.CGIFParser";'.

Harry Delugach's CharGer CG editor has been a great help with actors and
general non-trivial CG creation and visualisation.

Guy Mineau, of course, for presenting the process formalism at ICCS 1998.

Dan Corbett, for his enthusisasm and encouragement re: my thesis work.

My wife Karen, for all the coffee and hugs.


David Benn, Adelaide, June 2001
@


1.11
log
@CGIF/LF opts
@
text
@d82 6
@


1.10
log
@Libs
@
text
@d77 5
@


1.9
log
@*** empty log message ***
@
text
@d19 2
a20 1
pCG. Optionally add the script to your path. That's it.
d25 3
@


1.8
log
@Added more re: file paths
@
text
@d55 6
a60 1
 o See also the other program in that directory: basic-info.cgp
@


1.7
log
@Updated
@
text
@d63 5
@


1.6
log
@Updated for version 0.1
@
text
@d49 1
a49 1
 o Change directory to <root>/cgp/examples/CGTools01/final
d51 5
a55 1
 o Run pCG with cgtools-final.cgp as the sole argument.
d128 1
a128 1
the directive: option cgifparser = "cgp.translators.CGIFParser";
@


1.5
log
@*** empty log message ***
@
text
@d3 1
a3 1
Welcome to the preliminary release of pCG!
d5 2
d8 2
a9 2
language which is the outcome of my coursework Masters thesis with the 
University of South Australia.
d11 2
a12 1
Please send all comments and questions to me at dbenn@@camtech.net.au
d21 9
d33 3
a35 1
file, say "foo.cgp", with your favourite text editor, and run it thus:
d40 1
a40 1
the file, e.g. see examples/gfx/tree.cgp.
d45 14
d61 3
a63 3
The Microsoft Word 97 file, Lang.doc, is a chapter from my recently 
submitted thesis which describes pCG in some detail. References to other
parts of the thesis should be ignored. If you want other formats, please ask.
d65 1
a65 3
of the language. I may add more information later. Once my thesis has been 
assessed and corrections applied, it will very likely be made available via 
the aforementioned web page.
d67 1
a67 1
The docs directory contains BNF for pCG derived automatically from the ANTLR
d74 2
a75 5
The complete pCG distribution is freely redistributable under the Gnu
Public Licence. See gpl.html.

Please note that the Revision Control System (RCS) has been used for version
control, hence the RCS directories everywhere.
d79 3
a81 3
See the aforementioned web page for the current bug list. This software
is not production quality. It requires real testing by real users, i.e.
people other than me who are going to try to apply it to their own problems.
d85 2
d90 4
d95 1
a95 1
o The symbolic link to cgp/CGPTokenTypes.txt is necessary for the 
d107 4
a110 1
   Get around this by calling SemanticException.getMessage().
d120 5
a124 1
in the implementation of pCG, particularly its CGIF parsing capability.
d127 5
a131 1
general non-trivial CG creation.
d133 1
a133 1
Guy Mineau, of course, for presenting the process formalism in ICCS 1998.
d136 1
a136 1
David Benn, Adelaide, December 13 2000@


1.4
log
@Adding Mineau thanks.
@
text
@d3 1
a3 1
Welcome to the first release of pCG!
@


1.3
log
@Changed path of pCG Language doc.
@
text
@d93 2
@


1.2
log
@Added a bunch of stuff in preparation for distribution.
@
text
@d33 7
a39 7
The Microsoft Word file docs/pCG_Lang.doc is a chapter from my recently 
submitted thesis which describes pCG in some detail. References to other 
chapters should be ignored. If you want other formats, please ask. Between 
this and the example programs, you should gain a good understanding of the 
language. I may add more information later. Once my thesis has been assessed
and corrections applied, it will very likely be made available via the 
aforementioned web page.
@


1.1
log
@Initial revision
@
text
@d1 18
a18 1
Notes
d20 73
d94 1
a94 14
1. The symbolic link to cgp/CGPTokenTypes.txt is necessary for the 
   CGPInterpreter class's importVocab directive which seems to look in
   the Makefile's directory rather than in the cgp directory for
   the tokens file. This looks like a bug in ANTLR since exportVocab
   writes to the cgp directory. Need to workaound this since not all
   OSes have symbolic links which would mean taking a copy of the
   tokens file. How to fix? => i) move Makefile to cgp directory;
   will this lead to classpath problems? ii) run make from cgp/cgp
   directory?

2.  Note that it should be possible to use $ANTLR_HOME/antlr.jar but a class
    required by SemanticException.toString() -- FileLineFormatter.class -- is
    not contained within antlr.jar, but is contained in $ANTLR_HOME/antlr.
    Get around this by calling SemanticException.getMessage().@
