RapidASM draft docs 2015-08-11@1657

RapidASM Scratch Documentation Draft

NOTES...
Compiles into assembly, making C/C++ header files as necessary.
Stack managed automagically, as would in C.  SI, SP, and related registers are normally unaccessable.
Instructions that have suffixes depending on data side have suffixed applied based on the context, but
can be defined manually.

SUBROUTINE DECLARATIONS... !!! NEEDS WORK !!!
sub<$name $cType> { /* $name impl */ }
sub<$name($reg1=$arg1 /* etc. */) $cType> { /* $name impl */ }
sub($conv)<$name $cType> { /* $name impl */ }
sub($conv)<$name($reg1=$arg1 /* etc. */) $cType> { /* $name impl */ }

For $name is sub name, $cType is return type in the header, $conv, is the calling convention, $reg# is argument
#'s register's name, and $arg# is the name of argument # in the header.

OPERATIONS...
Set value of register: 		`eax = 42`, `eax = [42h]`
Move register values:		`eax -> ebx`, `ebx <- eax`, etc. (Adapts to size of reg.)
Instruction:			`:hlt`, `:HLT`, etc.
Exchange registers:		`eax <-> abx`
Subroutine call:		`~foo`
Number literals:		`10` (10), `10h` (16), `10o` (8), `10b` (2)

STRUCTURE...
Comment:
	// yadda yadda yadda
	/* inline yadda */
Subroutine example (using cdecl convention):

	sub<foo(ax=bar bx=baz) int> {
		// foo impl
	}
	Generates .h as(?):
		int _cdecl foo(int bar, int baz);

	sub(stdcall, etc.)<bar(r12=bob) boolean> {
		// bar impl
	}
	Generates .h as(?):
		boolean _stdcall bar(long bob)

Other file(s):
	include {
		<file1.?>
		<file2.?>
		<file3.?>
		...
	}

Branching (if statements) example, for $exp is a boolean expression:
	if($exp) ~foo
	if($exp) rax -> rbx

Simple loops (checked at beginning), for $exp is a boolean expression:
	while($exp) {
		// looped content
	}
	May become...
		jnz ($exp result)
		// looped content
		jmp (jnz instruction)

Simple loops (checked at end), for $exp is a boolean expression:
	do {
		// looped content
	} while($exp)
	May become...
		// looped content
		jnz ($exp result), (beginning of content)