TMIDL version 1.0 - First Revision

tmidl.txt

    @@@@@@@
  @@ ##### @@      TMIDL DEVELOPER DOCUMENTATION
 @@@@@ # @@@@@     VERSION 1.0
@@@@@ (@) @@@@@    FIRST REVISION
 @@@@@ # @@@@@
  @@@@ # @@@@
    @@@@@@@


TMIDL (Turing Machine Instruction Description Language), pronounced "T-middle",
is a simple programming language designed for extensibility, compactness and
portability - it describes the instructions of any Turing machine. The language
is mainly composed of compiler directives, extensions, states and symbols.

                    ====== Compiler directives ======

%tmidl <version>				Defines a TMIDL program. version is the
						minimum TMIDL version required. This MUST
						be the first line of any TMIDL program.

%tapesize <size>				Defines the tape size. Required.
						The minimum is 4, and the maximum is at
						least 1024.

%states <A,B,C,D...>				Defines all used states. Required.

%symbols <0,1,2,3...>				Defines all used symbols. Required.

%tape <2564295..>				Defines tape init. Default all blanks.

%halt <#>					Defines "halt" state character. Default #.

%include <extension> [with {var=1}]		Includes an extension. Optionally variables
			 			may be provided with "with".

%pos <pos>					Defines initial head position. Default 0.

Extensions may add or modify compiler directives except %tmidl and %include.
Additionally, all directives starting with %% are implementation-defined, and
directives in the format %directive[:id]@extension are reserved for extensions.
The ID is optional. Examples:
	%directive@exampleext true
	%directive:1@exampleext 510
	%settings:on@exampleext "rr"

                            ====== Syntax ======

The standard TMIDL syntax uses 5-character instructions:


		A57LC
		||||L------------> next state (# to halt)
		|||L-------------> direction to move head: Left or Right
		||L--------------> symbol to write (- for none, / for blank)
		|L---------------> read symbol condition (- any, / blank)
		L----------------> state condition

An instruction has two parts: the condition and action. The condition consists
of the first two characters of the instruction, and the other three correspond
to the action. The diagram above explains the TMIDL syntax.

Extensions can extend this syntax with the parseExtendedSyntax() function. The
Registers core extension uses this feature. It is disallowed to use this to
modify the base syntax; use the parseBaseInstruction() function instead.

Comments are made using tilde (~). Example:
	A9/R# ~ error handler



=========================== EXTENSION DOCUMENTATION ===========================

This section of the documentation covers the Core Extensions, which must always
be available.

TMIDL-2D						Two-dimensional tape support
	Usage:
		%include tmidl2d with {tw=W;th=H}		Q U P
		%tapesize T					L - R
	W = tape width, H = tape height, T = W*H		Z D M
	The image shows the directions.

Registers 						Registers for quick and simple state changes
	Usage:
		%include registers
		%registers a,b,c,...

	Conditions:
		b!=7& a=2& A57LC
		if b not 7 AND a equals 2 AND state equals A AND symbol equals 5:
			write 7;
			move left;
			state=C;

		Available operators:
		= equals != unequals < lesser > greater <= lesser or equals
		=> greater or equals == identical | or ^ bitwise and

	Setting:
		A57LC;b=3+2;d=b+a
		if state equals A AND symbol equals 5:
			write 7;
			move left;
			state=C;
			b = 3 + 2;
			d = b + a;

		Available operations:
		+ plus - minus / divide * multiply ^ exponent

Video							Graphics and text output
	Usage:
		%include video
		%videosize 640,480
		
	Syntax example:
		A57LC$p[4,5,7,16,16,vga:4,vga:5]W
		if state equals A AND symbol equals 5:
			write 7;
			move left;
			state=C;
			drawPoly(sides:4 x:5 y:7 width:16 height:16 fill:vga:4 line:vga:5

	Commands:
		Parameters marked with * are required.

		$p[sides,x,y,w,h,F,O,R,t]					Draw Polygon
			*sides		Amount of sides to draw
			*x *y		Position of polygon
			*w *h		Size of polygon
			F		Fill color 					(default = main:1)
			O		Outline color					(default = main:2)
			R		Rotation					(default = 0)
			t		Outline thickness				(default = 1)

		$c[name,ow,c1,c2,c3,c4,c5...]					Set Palette
			*name		Palette name
			*ow		If 1, overwrite colors
			c1, c2,...	Color codes (see color info)

		$x[x,y,color]							Draw Pixel
			*x *y		Position to draw pixel
			*color		Color

		$l[x1,x2,y1,y2,color,t]						Draw Line
			*x1 *y1		Position of first point
			*x2 *y2		Position of second poin
			color		Color						(default = main:2)

		$t[text,x,y,color,font,size,R,B,I,U,S,V,W]			Draw Text
			*text		Text to draw
			*x *y		Position to write text
			color		Text color					(default = main:2)
			font		Font						(default = Courier New)
			size		Font size					(default = 12)
			R		Rotation					(default = 0)
			B I U S		Bold Italic Underline Strike 			(default = all 0)
			V		Reverse video					(default = 0)
			W		Wrap-around					(default = 1)

		$I[img,x,y,w,h,R]						Draw Image
			*img		Image to draw (see image info)
			*x *y		Position of center of image
			*w *h		Size of image
			R		Rotation					(default = 0)

		$f[color]							Clear Screen
			color		Color to fill screen				(default = #000000)

		$W								Flush Framebuffer

	Compiler directives

		%videosize <width> <height>			Define video size. Required.

		%font:<name>@video <font>			Load font. font may be a file name,
								base64 or system font name.

		%img:<name>@video <image>			Load image. image may be a file
								name or base64.

		%palette:<name>@video <palette>		Load palette. palette may be a file
							name, base64 or comma-separated hex
							color code list.

	Colors
		Colors are identified by a palette name and a number. Examples:
			vga:8
			ega:2
			main:6
			cga:5
		
		Palettes contain 256 colors. The default palettes are:
			vga ega cga0 cga1 cga2