# What

Atalan is a smart compiler generating highly optimized code, sometimes indistinguishable from programs written directly in assembler. Currently it supports MOS 6502, MOS 6510 (+ clones) and Z80 CPUs, but it is very easy to create other targets.

Compiler is rule driven and extremely retargettable. It is very easy to add support for new platform and it is possible to provide support for new CPU without touching the compiler source code. Programmers can easily provide support for new data types or operators.

Atalan is cross-platform development system. Compiler runs on desktop machine (Windows, Linux, OSX - it is developed just using ANSI C, so porting to other systems should be straightforward). Target systems include Atari, Commodore 64, ZX Sepctrum, NES and Atmos.

## Language Features

- structured programming (`if then else`, `while`, `until`)

- powerful loop construct (`for k where sieve(k) = 1 until KEY = Q`)

- enumerations

- procedures

- nested procedures

- functions with multiple return values

- macros

- numeric types defined using range `(min..max)`

- variables may be stored in user defined place

- blocks defined by parentheses, indent or one line

- local scope rules for constants

- type associated constants `(type hour:0..23 (noon = 12 midnight = 0))`

- multidimensional arrays

- support for interrupts

- chained relational operators `(10 < x <= 100)`

- parametrized modules

- type inferencing

- possibility to call assembler routines including definition of register arguments

# Who

Atalan was written by Rudla Kudla and unfortunately abandoned. He has no time/interest in developing it anymore.

# Why

Since it seems original Atalan project was abandoned and certainly it's **too good** to be in such state I decided to create this repo in hope **someone with better compiler knowledge is able to fix some of the bugs present currently**.

Any help appreciated!

# Documentation

Until I prepare proper new documentation, please check original docs written by Atalan author, here: [Atalan Language Reference](http://atalan.kutululu.org/reference.html)

Note that it seems the docs weren't updated during development and some language features have different syntax than stated. Check errata in his readme for updates.

# What's new

Updated so far:

- Atalan makefile was updated to and builds on Linux.

- Implemented bit reading and writing for MOS 6502, like:

```

if joystickPort$4 = 1 then ... ; check if bit 4 of joystick port is set

interruptControlRegister$2 = 0 ; clear bit 2 of some register

```

- Created a lot of Kernal and library code for Commodore 64 platform.

- Added I flag to 6502 to be able to SEI/CLI by doing `@CPU.i=1`

# Bugs

Following things are broken in Atalan compiler:

- `dec` backend command segfaults the compiler, this means you probably can't subtract 1 from anything!

- `adr` used for `proc` addres segfaults the compiler

- forward declaration for `proc` is broken, it will cause "already defined" compile error

- `const` doesn't seem to be working, neither is used in any example Atalan source code

- A lot of different array code has to be added to backend for any but simple arrays to be usable

# Backend Documentation

Atalan compiler provides configurable backend that can be easily enhanced (or maybe even used to produce code for other processors).

Compilation is done in four phases:

- parsing

- translation

- optimization

- emit

## Parsing

Parser parses code and produces program written using compiler instructions. Compiler instructions are three address instructions, like

```

let P, 10

let Q, 15

add R, P, Q

```

## Translation

Code generated by parser it then translated for specific processor. This is done using rules defined in Atalan processor file. Resulting code consist of processor instructions, which are equivalent to some processor instructions.

```

let _a, 10 ; lda #10

let P, _a ; sta P

let _a, 15 ; lda #15

let Q, _a ; sta Q

let _a, P ; lda P

let _c, 0 ; clc

add _a, _a, Q ; adc Q

let R,_a ; sta R

```

For this example, following rules were used:

```

rule let %A:byte, %B:byte = instr

let _a,%B

let %A,_a

rule add %A:byte, %B:byte, %C:byte = instr

let _a,%B

let _c,0

add _a,_a,%C

let %A,_a

```

## Optimization

Compiler instructions (= processor instructions) are now optimized.

## Emit

For every compiler instruction, appropriate rule generating source code is found.

```

lda #10

sta P

lda #15

sta Q

lda P

clc

adc Q

sta R

```

For this example, following rules were used:

```

rule let _a,const %A:byte = " lda #%A"

rule let %A:byte,_a = " sta %A"

rule let _c, 0 = " clc"

rule add _a,_a,%A:byte = " adc %A"

```

## Backend language syntax

Here's everyghing I was able to guess about Atalan backend language used to create compiler rules.

### General Definitions

`whitespace =` space, tab or cr/lf with indent

`assembler_body = "assembler text" whitespace [assembler_body]`

`backend_body = backend_rule whitespace [backend_body]`

`atalan_body = atalan_code whitespace [atalan_body]`

`argument_list = argument [`space` argument_list]`

`macro_argument_list = argument [`,` argument_list]`

### Argument matching patterns

When choosing which rule to use the backend first matches with argument types:

`%A` – match/get value of argument

`%A_lo` – get argument low byte

`%A_hi` – get argument hi byte

`%A:type` – match values of type

`const %A:type` – match constant argument of type

`%A:type(%B)` – get B-th element of array A of type

`@%A` – reference to variable to which A points

`%A$%B` – get B-th bit of variable A

`%A-%B` – obtain difference between B and A, usable for arrays

`%A..%B` – obtain range between A and B

`%Z` – special macro variable, used as local variable in macro evaluation

For commutative operations, if mathing rule for `op A,B,C` is not found, `op A,C,B` will be searched

Constant is put on the right side of operation if possible

Note: due to special meaning of `%` it is impossible to use it as binary literal symbol in assembler instructions. It will give a strange error.

### Macros

A macro inlines code given by its body in processed source code. It supports both Atalan source code and backend `instr`uctions

Note: macro arguments HAVE TO BE separated by comma, while rules arguments (see below) don't!

**macro** __name__ [argument_list] = atalan_body

Defines a macro consisting of Atalan code with given arguments. Example:

```

inc: macro x =

x = x + 1

```

**macro** __name__ [argument_list] = **instr** backend_body

Defines a macro consisting of backend code. Example:

```

system.print_scr: macro = instr

call system.print_out

```

Note: code looking like 6502 opcodes in m6502.atl is in fact backend instructions, i.e.:

```

adc:macro o = instr add ca, a+c, o

inc:macro o = instr add o, o, 1

bcc:macro lb = instr ifeq lb, c, 0

cmp:macro o = instr sub cznv, a, o

```

Note: I don't think it is possible to create a macro that injects assembler instructions directly.

### Rules

**rule** __pattern__ [argument_list] [**#**__cycles__] [**@**__trashedReg__…] = assembler_body

Defines how to translate specific backend rule to assembler code, specifies registers that get overwritten with following code, and cpu cycles that it takes, examples:

```

rule nop #2 = " nop"

rule let c, 0 #2 = " clc"

rule let c, 1 #2 = " sec"

rule add x,x,1 @zn #2 = " inx"

rule let x,const %A:byte1 @zn #2 = " ldx #%A"

```

**rule** __pattern__ [argument_list] = **instr** backend_body

**rule** __pattern__ [argument_list] = **macro** atalan_body

Defines how to translate specific backend rule to set of another backend rules or Atalan code, example:

```

rule mul %A:byte, %A:byte, 3 = instr

mula %A, 3

let %A, a

rule %A:array of %B(%C..%D) = %E:%B = macro

for i:%C..%D %A#i = %E

```

# Errata

Following language features have are implemented differently than stated in Atalan online docs:

## enum

Enum values are given using semicolon, not equal sign:

```

Joystick: enum

up : 1

down : 2

left : 4

right : 8

fire : 16

```

## proc

Procedures may have types, like:

```

IrqProc:type = interrupt

rule proc %A:IrqProc =

"%A .proc"

```

This can be used to emit special procedures for i.e. interrupts. See Atari and Commodore 64 platforms.

## const

Not working? Not implemented? Changed syntax?