          ____         ______
         /    \         \   \\
        |               |     |   Scripting engine
         \____  ____ ___|     |
              \/   \\  \\____/      v 0.92a
        /      |_____|___|   \
       |      /\    \   |     |
        \____/  \___/\___/     \
          by Theur - Przemyslaw Podsiadly 1998-99

#include <std_disclaimer.h>

   "I do not accept responsibility for any effects, adverse or otherwise,
    that this code may have on you, your computer, your sanity, your dog,
    and anything else that you can think of. Use it at your own risk."

                     GENERAL RELEASE INFORMATION

  //                                                                 \\
 |                     1.  Introduction                                |
  \___________________________________________________________________/

  The idea was to make a script engine for any purpose you would need.
This can be for AI in the game, for macros in an editor or whatever.
This is for things you cannot (or don't want to) have compiled
(hard-coded) inside your program. The idea was to make it easy to
learn, and though it's a C library, SeeR is (or will be) an almost
complete C compiler.

 It gives you ability to write scripts for your own program/game, that can
be compiled on runtime or just precompiled and stored in your archive
(e.g. DATAFILE for Allegro users) in binary format. From inside the script
you can use variables or function for your program (import). The program
on the other hand can call any of exported functions of your script.

 The existing releases of SeeR (?? - version number,i.e. 08)
 -- Precompiled versions --
 seer??dj    DJGPP 2.x
 seer??lx    LINUX GCC
 seer??vc    MS Visual C++ (tested with version 5)
  Ready to compile in your project PRECOMPILED library. Package contains
 also the SeeRC compiler and some examples.
 -- Source version --
 seer??s    DJGPP 2.x
 The full source version, contains all examples, but ready to
 compile only for DJGPP.

  //                                                                 \\
 |                          2. General information                     |
  \___________________________________________________________________/

=== 2.1. Documentation ===
==========================

See seer.txt and examples on how to use SeeR.
See also seer.h for additional info.

=== 2.2. Examples ===
=====================

 All packages contain more or less the same examples. As some of the
examples use external non-standard libraries (like Allegro game library
by Shawn Hargreaves), you may not be able to compile all the examples.
If it is not stated in description, the example is by default a text
console program using standard ANSI I/O functions (like printf).

No   sources     description
 1. example1.c   "Hello world!", importing function `printf'
    example1.sc

 2. example2.c   Benchmark of SeeR - requires DJGPP (I think). Runs
    example2.sc  a loop in both SeeR and CPU so you can compare
                 how much slower SeeR is. Also shows how to write
                 a script to disk. Example3 shows how to load one.

 3. example3.c   importing scanf and own function sqrt, loads already
    example3.sc  compiled script from file example3.cs (compiled by SeeRC),
                 usage of doubles

 4. example4.c   source of script written as char* variable (use of
                 Compile_Text(...)), accessing variable with scVar
                 macro

 5. example5.c   like example2, but demonstrates usage of structs and
    example5.sc  internal headers

 6. example6.c   Allegro to SeeR interface (allegro.sh) included to one
    example6.sc  of Allegro's examples (ex24) - you see you can write all
    allegro.sh   the stuff as if it was GCC!!! Uses seer.pcx.
                 WARNING:requires Allegro library

 7. example7.c   simple multitasking demo (worms...)
    example7.sc  WARNING:requires Allegro library

 8. example8.cc  C++ multitasking demo using Allegro (again),
    example8.sc  accessing class variables and member functions
                 WARNING:requires Allegro library

 9. example9.c   multitasking demo introducing fork, priorities
    example9.sc  and builtin internal header: Kernel and Instances

External libraries used in examples:
 Allegro- exists for
          DJGPP  (alleg30.zip by Shawn Hargreaves)
                 http://www.talula.demon.co.uk/allegro/
          Linux  (actually two versions exist:
                  lalleg??.zip or xalleg??.zip(XWindows))
                 WARNING:untested
          Win32  (WinAllegro by Stefan Schimanski)
                 http://www.geocities.com/SiliconValley/Way/1280/

=== 2.3. History  ===
=====================

1998.02.16 -SeeR 0.0 was born...
1998.04.09 (SeeR 0.1a) -
         first public alpha release
1998.04.15 -
         some bugfixes
1998.04.21 (SeeR 0.2a) -
         able to use imported variables, able to use infinite
         parameters (...), debug version and more examples added.
1998.04.26 -
         fixed some errors (e.g. a/b != b/a), SeeRC compiler added,
         switch/case added, Compile_Text now complete, more examples.
1998.04.29 (SeeR 0.3a) -
         structs works (NOT FULLY TESTED YET), changed way to access
         imported variables (so it's able to read it's address),
         Allegro example (example6 - check it out if you use this
         great library!)
         major fixes:
         -parser reading comments,
         -calling imported functions without parameters
1998.05.12 (SeeR 0.4a) -
         include added : able to include file or internal header (as char*)
         multitasking
         fixes:
         -using result of imported function as parameter to function
          (previously caused Internal compiler error)
         -some optimizations and fixes in code generation
         -parser loading when last line not empty
1998.05.24 (SeeR 0.41a) -
         assembler interface `__vcpu(...)',
         multitasking keyword `secured',
         WAIT macro (__vcpu(43))-forces SeeR to interrupt script
         (in multitasking environment),
         NULL defined,
         arrays defined in script work,
         new multitasking Allegro demo,
         fixes:
         -functions returning sth different from int didn't work as params
          to functions!
         -final (hopefully) parser fix with last line duplication
         -"include after include" and line-numbering bug fix
         -sometimes crashed, when some structures allocated above
          0x7fffffff-fixed
1998.06.09 (SeeR 0.5a) -
         floating types implemented with many major changes in code,
         doesn't exit on compilation error: just reports it to the caller
         fixes:
         -accessing variables of size different from 4(ie char)
1998.06.12 (SeeR 0.6a) -
         able to call function before definition (but after declaration),
         new example of accessing C++ class variables and member functions
         fixes:
         -major fix in preprocessor on macros,
         -report some syntax errors
         -accessing script's variables (macro scVar) fixed
         -imported functions returning fixed
1998.06.27 (SeeR 0.61a) -
         the last release before my summer holidays, some bugfixes
         (mainly in error reporting), implementations in documentation
1998.07.10 (SeeR 0.62a) -
         major operator++ and operator-- bug fixed, parameter parsing
         bug in SeeRC compiler
1998.07.26 (SeeR 0.7a) -
         fork feature (so one instance can fork into sub-instances
         running parallelly),
         priorities feature (so some scripts "kernels" can operate on
         advanced internal SeeR functions, while "user" scripts are
         not allowed to e.g kill other instances or use some user-defined
         functions),
         preprocessor keywords #title and #author for easier handling
         runtime errors of instances (error message contains title
         of instance where error occured),
         all new allegro example6 based: Allegro's ex24 runs as a script
         with almost no change int it.
         fixes:
         example3:scanf("%lf",..) instead of scanf("%G",..) makes it work
                  in Linux and some versions of DJGPP,
         tables passed as pointers,
         pointer arythmethic (pointer+value),
         crashed when freeing memory allocated above 0x7fffffff,
         calculating size of data segment,
         calling imported functions returning double (in optimized version only),
         error "function declared and not defined" wasn't reported before,
         preprocessor in #ifs redefined all defines
1998.08.26 (SeeR 0.8a) -
         Win32 version (MS Visual C++ 5), changes in priorities,
         initializing internal Kernel header optional (scExport_Kernel),
         operations on schedulers
         fixes:
         many major bugs connected with memory handling (while I was porting
         SeeR to Win32, thanks to MSVC debugger I traced many nasty bugs),
         still remains a problem with MSVC's ASSERTION warnings in debug
         version (when freeing script after scCompile_Script -
         anybody can help?)
1999.01.01 (SeeR 0.9a) -
         the ultimate compilation cleanup - rewrite all code connected with
         variable type handling (it's almost all compilation functions),
         casting implemented ( like (int*)a ),
         initialization of structures and tables finally implemented.
         fixes:
         ?: operator bug when using with imported variables,
         undefined identifier used as parameter to function reported
         as "Too many parameters",
         imported variables of typedef'd type were losing its' import flag,
         multiple-lines macros didn't work,
         switch(fun(...)) {...} didn't work OK,
         return didn't work for functions returning void,
         division by zero detected,
         fork sometimes copied the wrong stack to the child,
         the child process was not freed when finished,
         and many others... (uff)
1999.02.18 (SeeR 0.91a) -
         fixes:
         initialization of strings in structures or arrays,
         scGet_Instance_Status was not exported in DLL,
         small bug in macros with strings containing '\',
         better test program,
         arrays [x][y] were thought to be [y][x]
         in macros #c didn't work, if c contained '"'
         DJGPP and VC (and possibly other C compilers) don't pack the struct
          - all not char members has to be aligned, and sizeof(struct) must sometimes
           be multiplies of 4. SeeR always packed the structures.
1999.03.07 (SeeR 0.92a) -
         C++ interface in seer.h,
         fixes:
         about 10x faster compiling !,
         more initialization bugs removed,
         array size wasn't allowed to be constant expression other than single
           integer (so int x[4*12] was not allowed),
         initializating pointers with tables,
         fork {} (without parameter) didn't work sometimes (internal compiler error),
         long decided to be 64bit constant, yet unsupported, use int instead of
           32-bit long),
         some operations on fixed didn't work,
         unary operator * didn't work (!),
         duplicate identifier checking,
         bug in operators || and &&, when used with imported or complex vars.

=== 2.4. Unsupported features ===
=================================

Short list of unsupported features:

 -unions and enums ,
 -goto instruction ,
 -bitfields ,
 -C++ classes ,

Other limitations:
 -unable to use declare variables with [] (instead use * or specify size
  explicitly)
    so
        main(int argc, char *argv[])
    should be
        main(int argc, char **argv)

=== 2.5. Debugging ===
======================

 When you encounter any errors while running/compiling script, you can
try debug version of SeeR library. This version gives you the ability to
create a file during execution describing what SeeR is doing. It also
contains SeeR-Asm version of the compiled script. To start creating
this file use following functions:
 scOpen_Debug (char *filename);           Opens debug file, turns
                                          debugging ON
 scToggle_Debug (bool deb);               if (deb==true) turns
                                          debugging ON
                                          (scOpen_Debug must have been
                                          called before)
                                          else OFF
 scClose_Debug();                         turns debugging OFF and
                                          closes debug file.

 Example:
 scOpen_Debug("debug.txt");
 s=scCompile_File("script.sc");
 scClose_Debug();

 In non-debug version these functions do nothing, of course. You can check,
if actual SeeR build is a debug one using scSeeR_Info(scInfo_Build).

 You can also use SeeRC compiler with debugging on, which will generate
*.deb file.

  //                                                                 \\
 |                   3. Compiler specific information                  |
  \___________________________________________________________________/

=== 3.1. GCC (DJGPP & Linux) version ===
========================================
Files: seer??dj.zip, seer??lx.zip

/--------FILES------------\       DESC
<example files,see 2.2>
libseer.a                       GCC lib  - optimized "release" version
libseerd.a                      GCC lib  - unoptimized "debug" version
makefile                        makefile for examples
readme.txt                      this file
seer.txt                        SeeR reference
seer.h                          main header file
seer.pcx                        SeeR logo (for example6)
seerc{.exe}                     SeeRC compiler (->4.1)

This release contains console version of SeeRC (->4.1)

To compile examples, type make. All examples should be created, unless
some external libraries were not found by compiler (->2.2)

To use SeeR in your programs, you should first include "seer.h", and
link with libseer.a (-lseer option). Make sure seer.h and libseer.a are
in the same directory as you program or in compiler's include and lib
directories.

=== 3.2. Win32 (MS Visual C++) version ===
==========================================
File: seer??vc.zip

/--------FILES------------\       DESC
<example files,see 2.2>
release/seer.dll                optimized "release" version
release/seer.lib                interface to seer.dll
debug/seerd.dll                 debug version (required by WSeeRC)
debug/seerd.lib                 interface to seerd.dll
readme.txt                      this file
seer.txt                        SeeR reference
seer.h                          main header file
seer.pcx                        SeeR logo (for example6)
WSeeRC.exe                      WSeeRC compiler (->4.2)
Ex1.dsp ... Ex9.dsp             project files for examples
SeeRExmp.dsw                    workspace for examples

This release contains Win32 version of SeeRC (WSeeRC,->4.2)

To compile examples, load SeeRExmp.dsw and compile each project separately.
To compile Allegro examples, remember to specify WinAllegro include and lib
directories in options!

To use SeeR in your Win32 programs, you should first include "seer.h", and
link with seer.lib. Make sure seer.h and seer.lib are in the same directory
as you program or in compiler's include and library directories. To run such
a program you will need seer.dll in your programs directory or in
windows\system.

  //                                                                 \\
 |                        4. SeeRC compiler                            |
  \___________________________________________________________________/

 SeeRC is a program that compiles script sources (*.sc) to scripts (*.cs).
All versions of SeeRC declare internal header called stdio, which contains:
  import int printf(char *,...);
  import int sprintf(char*,char *,...);
  import int scanf(char *,...);
  import int getchar();
  import int scrandom(int);
  import int rand();
  import int srand(int seed);
  import int strcpy(char *,char *);
  import int strcmp(char *,char *);
  import int strtol(char *,char **,int);
  import int atoi(char *);
  import double atof(char *);
  import unsigned int strtoul(char *,char **,int);
  import double strtod(char *,char **);
  import char *strdup(char *);
  import double sqrt(double);
  import double sin(double);
  import double cos(double);
  import void* malloc(int);
  import void free(void *);


4.1. The console version of SeeRC (GCC-compatible releases)
  Usage:
   seerc {options} filenames

Filenames can be a list of files or file masks.
Options:
 -a {author} assign an author to the script
 -d          compilation to produce also *.deb files that contain SeeR-Asm
             code of processed script.
 -h          help
 -i          see the script infos (SeeR version,interface objects),
 -o {output} output filename specification (other then *.cs)
 -r          run script (not implemented)
 -s          display compilation message on the screen
 -t {tile}   assign a title to the script
 -v          displays SeeR version

4.2. Win32 version : WSeeRC
 This is a dialog based application. It seems to be self-explanatory.

  //                                                                 \\
 |                      5. Documentation:                              |
  \___________________________________________________________________/

See seer.txt and examples on how to use SeeR.
See also seer.h for additional info.

  //                                                                 \\
 |                      6. Conclusion                                  |
  \___________________________________________________________________/

That's all for now. Enjoy !!!
  This software is free , but if you use it
        -= PUT MY NAME (and the lib's ) IN THE CREDITS!! =-
and let me know about your program...
I'd be happy to see what you've used it for...

I need your feedback - mail to
------->          ppodsiad@elka.pw.edu.pl
Do you have any suggestions on how it should work? Don't hesitate and write!

                Enjoy!
                        Theur - Przemyslaw Podsiadly

