gury8 / effectus Goto Github PK

==================
  Effectus 0.5.3
==================

This is new version of Effectus, done from scratch. The most important thing to consider was to
emulate Action! language as close as possible. The main priority is to handle Action! statements
(declarations, commands, assignments...) properly and to support multi-line statements as well.

In new version the source code is generated by using Mad Pascal cross-compiler, which is further
compiled to binary code with Mad Assembler (Mads). These amazing tools were created by
Tomasz Biela (Tebe).

The steps are as follows:
- Action! code is parsed and appropriate Mad Pascal source code listing is generated
- Mad Pascal compiles this code to *.a65 file prepared for compilation by Mad Assembler
- Mad Assembler compiles *.a65 file to final binary code (*.xex by default)

examples directory includes listing examples to demonstrate available features of Effectus language,
which can be basis for your further development and experimentation.

My special thanks and credits go to:
- Tomasz Biela (Tebe), author of Mad Pascal and Mad Assembler (Mads). He made this all possible!
- Zbyti, who helps me with developing, fixing bugs, Linux distribution compilation and providing
  me with many listing examples and benchmark test examples. And laughs... :)
- Mariusz Buk for hosting original project on GitHub with MacOs compilation 
- All others not mentioned here, who help me with suggestions, testing, etc.

------------------
What is supported?
------------------

Data types
----------

BYTE, CHAR, INT, CARD

Extended data type
------------------

BYTE ARRAY, CARD ARRAY, POINTER
SBYTE ARRAY as temporary solution for BYTE ARRAY string definitions

- Variable memory address assignment

  Examples:
  BYTE CH=764, COL=710, BYTE GRACTL=$D01D

- TYPE declaration

  TYPE REC = [
    BYTE day, month CARD year
    BYTE height
  ]

- Declaring array variables pointing to memory address

  BYTE ARRAY arrD=28000
  CARD ARRAY arr=$8000

Conditions and branches
-----------------------

- IF/THEN/ELSE/ELSEIF condition statements
- FOR, WHILE, DO, UNTIL, OD branch statements
- infinite loops using DO OD
- EXIT statement for unconditional exit from the current condition or loop

Graphics
--------

PROCedures: GRAPHICS, PLOT, DRAWTO, FILL, LOCATE
Global variable Color for setting the color to draw on screen

Sound
-----

PROCedures: SOUND, SNDRST

INCLUDE files
-------------

Files can be included, starting in the same directory as main compiled listing code.
Currently one level of included files is supported. This means only main listing program can read
files with INCLUDE directive, but not any other files, even if they have this directive called in.

String manipulation
-------------------

PROCedures:
  STRB, STRC, STRI, SCOPY, SCOPYS, SASSIGN, INPUTS,
  PRINT, PRINTE, PRINTB, PRINTBE, PRINTI, PRINTIE, PRINTC, PRINTCE, PRINTF, PUT, PUTE

FUNCtions:
  GETD, INPUTB, INPUTC, INPUTI, SCOMPARE, VALB, VALC, VALI

Arithmetic manipulation
-----------------------

Bitwise manipulation
--------------------

Bitwise/logical operators: AND (&), OR (%), XOR (!), LSH (left shift), RSH (right shift)

Data manipulation
-----------------

PROCedures:
  ZERO, SETBLOCK, MOVEBLOCK

DEFINE declaration (constant substitutions for any statement)
-------------------------------------------------------------

Device I/O support
------------------

PROCedures:
  OPEN, CLOSE, PUTD, PUTDE, PRINTD, PRINTDE, XIO,
  PRINTBD, PRINTBDE, PRINTCD, PRINTCDE, PRINTID, PRINTIDE,
  INPUTSD, INPUTMD

FUNCtions:
  INPUTBD, INPUTCD, INPUTID

- Printing to text modes by using PrintD and PrintDE is allowed

Inline machine language
-----------------------

- Support for inline machine language anywhere in the body of code listing (after variable
  declaration)

  Examples:
    [$A9$21$8D$02C6$0$60]
    [
      $A9$90
      $3E$02C6 $0 $60
    ]

- PROCedure machine language support
- FUNCtion machine language support

  Example:

  PROC TEST=*(BYTE CURSOR,BACK,BORDER,X,Y,UPDOWN)
  [
    $8E 710  ; BACKGROUND COLOR
    $8C 712  ; BORDER COLOR
    $8D 752  ; CURSOR VISIBILITY
    $A5 $A5 $8D 755  ; CHARACTERS UPSIDE DOWN?
    $A5 $A3 $8D 85 0  ; COLUMN FOR TEXT
    $A5 $A4 $8D 84 0  ; ROW FOR TEXT
    $60]
    
You can send parameters to machine language routines. The compiler stores parameters using
A, X and Y registers, then zero-page addresses from $A3 to $AF are used.

Address      nth byte of parameters
-------      -----------------------
 A register   1st
 X register   2nd
 Y register   3rd
 $A3          4th
 $A4          5th
 :            :
 :            :
 $AF          16th

System manipulation
-------------------

PROCedures:
  POKE, POKEC

PROCedures:
  PEEK, PEEKC

Extra, non-standard statements
------------------------------

- Support for Mad Pascal with directive PAS {}
  
  Example:  
    PAS {
      repeat until keypressed;
      for i := 0 to 14 do begin
        SayHelloProc;
        Delay(120);
      end;
    }

  Calling PROCedures and FUNCtions, implemented in Effectus, must include appropriate string
  extension in PAS {} block, in particular, Proc extension for PROCedures and Func extension for
  FUNCtions. Variables or any other entities can be interchanged between Effectus and PAS {}
  block of code.

- Support for Mad Assembler with directive ASM {}

  Example:
    ASM {
      lda #0
      sta 710
    }

- ODFOR and ODWHILE loop directives, which can be used as substitutions for enclosing OD directive
  to close FOR and WHILE loop blocks as there are some issues when using FOR and WHILE statements inside
  ELSE and ELSEIF condition blocks

Misc
----

- Additional PROCedures: POSITION, SETCOLOR
- Aditional FUNCtions: RAND, STICK, STRIG, Paddle, PTrig
- Custom PROCedures and FUNCtions are supported
  (parameters can be mixture of any scalar data type: BYTE, CARD, INT, CHAR)
- Memory address calls through PROCedures are supported (OS calls can be accomplished)

  Examples:
  ; Scroll screen
  PROC SCROLL=$F7F7()
  ; Cassette-beep sound
  PROC BEEPWAIT=$FDFC(BYTE times)

Effectus directory structure
----------------------------

- root directory: program executables, license documents and other supporting files
- examples: Action!/Effectus examples
- base: Mad Assembler library directory
- lib: Mad Pascal library directory

Command prompt execution
------------------------

effectus <filename> <parameters>

Available options:
  -i   Information about declared variables, PROCedures, FUNCtions and DEFINE constants
  -o:  Binary file extension
  -c   Clear summarized log file
  -t   Effectus only translate source to Mad Pascal
  -z   Variable zero page address
  -zb  BYTE variable zero page address
  -zw  CARD (word) variable zero page address
  -zp  Pointer (PByte) zero page address

- Effectus/Action! source code listing can reside on any path and resulting code
  is also generated there

- Log files are created on compile time

Missing features and bug issues
-------------------------------

You can read about missing features and bug issues in additional file dev_log.txt!

-------------------------------------------------------------------------------

Written by Bostjan Gorisek from Slovenia
References:
  https://github.com/mariusz-buk/effectus
  http://freeweb.siol.net/diomedes/effectus/
  https://atariage.com/forums/topic/291426-effectus-action-cross-compiler-using-mad-assembler-mads/
  https://atariage.com/forums/topic/306222-effectus-suggestions-and-bug-reports/

Mad Pascal and MAD Assembler (MADS) are products written by Tomasz Biela (Tebe) from Poland
References:
  http://mads.atari8.info/
  https://github.com/tebe6502/Mad-Pascal
  https://github.com/tebe6502/Mad-Assembler