--------
Effectus
--------

Atari MADS cross-assembler/parser for Action! language


Description

The goal of Effectus project is to make it compatible with Action! programming language as close as possible. Windows (i386-win32) and Linux version of the program are available. Linux version has some issues which will be fixed in next versions.

examples\ folder includes some demonstration programs to show what Effectus currently is capable to do. The runtime library consists of several supporting libraries. Besides runtime.asm there are several others, implemented in your programs whenever needed. Maintaining the compatibily with Action! will be of HIGH priority. The implementation of runtime library routines can be changed, but the number and order of parameters should not be changed. This is one of the rules you must follow to successfully compile any Effectus program. Also, additional requirement for proper working of Effectus is having config.ini configuration file in the same directory as the Effectus executable program.

Effectus compiles and produces MADS assembly language source code and binary files for executing on real 8-bit Atari or software emulator. Version of MADS currently used and tested with Windows version of the program is 1.8.7, whereas Linux version is 1.8.5. Source code can be further manually modified with the use of MADS for additional improvements. The restrictions mentioned above comply just to the stage when Effectus source code is compiling. You can set optional values for MADS and Effectus source code and binary code folder, program starting address, extensions, etc. in config.ini file or by using parameters in the console.

The name Effectus comes from Latin word for "execution".

I have to thank the author of MADS, Tebe, who helped me with many important suggestions to improve the code. Thanks go also to my friend Sandor, who motivated me further for continuing work on this project, providing me with new domain name for Effectus, http://www.atari-effectus.com/.


- Features (in some cases limited functionality)

- Procedures (PROC, the last procedure entered is the main procedure in the program like in Action!)

- Functions (FUNC), RETURN statement resulting value is of .word type

- Machine language code in PROCs and FUNCs with [] block

- Procedure and function parameters (arguments) support, maximum five parameters allowed

- Variables, constants and strings

- Improved support for POINTER declaration and manipulation (not all features implemented yet)

- Improved support for ARRAY declaration and manipulation (not all features implemented yet)

- Limited support for arrays of TYPE records

- TYPE record declaration 

- Support for Action! conditions and branches (IF-ELSE, WHILE, UNTIL, FOR)

- Supported are all MADS operators (+, -, *, /, %, &, |, ^, <<, >>, =, ==, <>, !=, <, >, <=, >=, &&, ||)

- Arithmetic 8-bit operations (addition, substraction, multiplication, division) - limited to two operands only for multiplication and division

- Arithmetic 16-bit addition and substraction - limited to two operands

- Bitwise operators: LSH, RSH, XOR, !, &

- Global variables

- Pre-declared variables

Example: BYTE i=[3]

- INCLUDE files (user defined libraries)

- DEFINE constants (partly supported, currently only literal numeric values in double quotation marks allowed)

- Comments

- I/O support

- Graphics support

- Game controllers support

- Sound support

- Manipulation with strings (SCopy, InputS, InputSD)

- Increment, decrement, multiplication and division expression syntax in format

x==+1
x==-2
x==/3
x==*4

- No space dependency on one line for most of the code

- Limited support for 8-bit math operations (addition, substraction, multiplication, division)

- Modification of runtime.asm and other libraries' routine implementations, but great care must be taken not to change the number and order of parameters


Supported Action! global system variables

color, device


Add-on Action! procedures

Asm - This procedure allows you to directly write assembly language code as part of the the final MADS assembly language program
PrintG, PrintGE - Temporary available procedures for printing text on screen in graphics modes with text window. These will be probably removed when ordinary Print procedures will be fixed.


Rules (and current restrictions)

- Every command (statement) must be on separate line, except TYPE declaration, FOR and WHILE loops
- ARRAY declaration is adviced to be of type INT or CARD, because BYTE values are not handled properly yet
- PROCs and FUNCs parameters are limited to one type
- Conditions are limited to one type (AND or OR)


Effectus release files and directories 

Program directory (effectus.exe, effcon.exe, config.ini)

Runtime library lib\ directory (click here to see current runtime libraries)

examples\ directory (click here to see some examples)

docs\ directory


To do

- I/O routines
- Local variables
- Variable types (ARRAYs, POINTERs, type structures)
- INCLUDE files
- More complete functionality of arrays of TYPE records (string support)
- DEFINE constants (partly implemented, currently only literal numeric values allowed)
- Recursion (non-Action! functionality)
- Nested procedures and functions (non-Action! functionality)
- Support for player/missiles
- Floating point support
- Syntax checking
- Multi-line statements
- WHILE loop (changing beginning offset to anything else than 0)
- implementing MADS features and compiling options
- remaining set of procedures, functions and other functionality of Action! language
- ...


Installation

Console version of Effectus (i386-win32 platform)

Program and its dependencies are archived in ZIP format. Before using the program, you must download the version of your choice, which is in ZIP format. When you download this file, unzip it and create a directory to place the main files and all subdirectories as is. Executable file is called effectus.exe, which is accompanied with config.ini setup file, which has predeclared default settings for the program. Configuration file is not necessarily needed for proper functioning of the program, but in this case, proper parameters must be put in place. To start using Effectus, typically just type effectus and the fully qualified pathname of the source file to be compiled.

Program usage

Common syntax: 
effectus filename [parameters]

Program parameters:

-md: MADS cross-assembler directory
-sa: program starting address
-ms: source output directory
-mb: binary output directory
-se: source output extension
-be: binary output extension
-rl: Effectus/MADS runtime library directory
-lo: log filename (with fully qualified pathname)

If config.ini file is in the same directory, where Effectus is run, then its settings are read and used in the program. These are:

ORG=3200 - Start address of the program 
MADS_DIR=c:\atari\mads\ - The path of MADS cross-compiler
MADS_SRC_EXT=asm - Output assembly source extension 
MADS_BIN_EXT=xex - Output executable code extension
MADS_RTL_DIR=c:\atari\effectus\lib\ - The runtime libraries used in compiling Effectus programs
MADS_OUTPUT_DIR=c:\atari\effectus\output.txt - assembly log file with fully qualified pathname

If MADS cross-assembler pathname is included in your system path configuration file (autoexec.bat or registry key), then MADS_DIR option is deprecated unless the MADS program is placed in root directory, where Effectus is run. 

As mentioned in Installaction section, config.ini file is not mandatory for proper functioning of the program. In this case, some caution must be taken. By default, all forementioned program parameters have their default values in place (similar to pre-declared values in config.ini file, with exception of path declaraions for which description follows). In this case, the runtime library directory is declared below root where Effectus is run (/lib) and log filename is set in root directory as well. 

Otherwise, if you decide to set your own values, parameters must be used manually.

Caution!
If config.ini is not used, MADS cross-compiler will be searched first in root directory, where Effectus is run. In this case, MADS cross-compiler set on system path will not be used.

To start using Effectus, typically, just type effectus and the fully qualified pathname of the source file to be compiled. Your program is compiled in directory you are currently on, but that can be changed with -ms: and -mb: parameters. The fully qualified pathname with space characters must be put in double quotation marks.

Every parameter must end with colon, for example: -sa:

Summary of Effectus settings in config.ini file

ORG - Starting address of generated program (in hexadecimal notation, for example 3200 - resulting to $3200)

MADS_DIR - Directory of MADS executable

MADS_SRC_EXT - MADS source code output extension

MADS_BIN_EXT - MADS binary output extension

MADS_RTL_DIR - Effectus/MADS runtime library directory


Console version of Effectus (i386-Linux platform)

Documentation for Linux version of the program will be prepared on next stable version of the program.

