-macas.txt;
(c)1999 Keinall "Lord Granitor" Caddle

---]
Refrernce Document on
Mainstream Constricted Annoying Symbols,
a.k.a. Mainstream Constricted NASIC,
a.k.a. More Annoying Constructs And Syntax.

Based on the featureset of Parse3r6,
or the Flat Six MaCas Parser(tm), as it
appears in "DMX". 

Parse3r6 uses a variety of 
technologies, including 
Parse4, a.k.a. Real Flat Parser(tm),
and the "foop" library of independent
function calls.

---:
mini glossary:

MACAS, now known as Macas and Cas and also
known as CAS and .CAS and C-NASIC, is a simple,
pathetic language which is processed at runtime
from plaintext format (in a file) to binary format
(in RAM). The result is called..

proCAS, now known as ProCas, or simly procas. Or
ProCas. This can be parsed by a variety of parsers,
most of which break soem compatibility with another
parser. Fun and exciting, huh?

MPM, Multi-Processed Macas, is a (so far vapor) idea
to convert the various Macas files to one format,
with the eventual idea being to have a single, related
file format for processd Macas. Another incoportated
idea is parsing BASIC-ish tokens as primatives, 
and kicking the ass of other languages which parse
smaller, less useful units. But the motivations is not
to be better than other languages, but to be the best
language for me to think/kode in, eventually. A lofty
and complex goal but, hey, i'm made of lofty and 
complex concepts.

---]
Latest changes:

***NB (18 Oct 1999 -e- ):

The current build of beta.exe (a DMX spawn) uses a modified
parser, Parse3r5; which may or may not support all of these
commands. In particular, '@' is not currently supported,
conversion will come eventually. I suppose if everything
worked, I wouldn't call it beta :)

** (28 Oct 1999 -e- ):
the '@' command is being changed. 
so far it's not 100% like legacy.

*** all the PRINT-ish commands now use PRINT EX,
so , t, e, ?, p, v, are all identical in all current
DMX manifestations. 

---]
*Dooong*

"In order to master MACAS, 
you must first search
for the files of testvar,
and initide, and testin. 

They have many decendants, 
their various iterations 
cause mortals to beome confused.

Know that all Macas is not 
the same, they are many small
but fatal syntaxical differences
which happen during the course of
time and lines of kode.

Yet they all end in .CAS.

Notice their ways,
and then, seek the 
MACAS.txt file.

The power of the MACAS
will soon be yours
to wield."

	-Shin Scripter,
	"Enter the Hyphen".
---]
Mainstream CAS format:

This is a plain ANSI ASCII text file;
aka the CASsrc. (C-NASIC source).
this is loaded and processed, such
that the file takes up (usually) less
space in RAM than it did when on
disk. (This is more important for low-RAM systems,
to which MACAS has currently no ports.)
Also, the label table is built.
The processed CAS file is sometimes called
proCAS. It's never written to disk, however.


---]
MACAS Commands 

Ledgend

[]	: required parament
<>	: optional parament
,	: seperates paraments. 



---:	Now Presenting... 

		The Macas command set !

---:	:	:	:	:	:	:	:	:
s
: Clear the Screen
- duh. This does NOT home the cursor, although SHIFT-HOME does.
---:
c[color]
: Set the foreground Color

Fairly self explanitory;
[color] is a numeric value; a nybble in scope,
i.e. 0-15 in range, whole numbers.
---:
b[color]
: Set the Background color

The background color is a per-cell
attribute, rather than a whole-screen basis.
---:	Now presenting...
		The venerable Art of Printing!
---:	featuring...
		The Awesome Print Ex facility!
---:
[preferred format follows]
?<string literal>,<$[system string]>,<%[system integer]>,
	<[variable name]> < , | ; >

[alternative formats follow]
e<string literal>,<$[system string]>,<%[system integer]>,<[variable name]>
t<string literal>,<$[system string]>,<%[system integer]>,<[variable name]>
p<string literal>,<$[system string]>,<%[system integer]>,<[variable name]>

[simplified format follows]
?[PrintString]

---:	Components of a PrintString

A PrintString is a complex extity comprised of simple components,
representing something that one wishes to print (using the new
Print Ex facility...). In order to be flexible, everthing that can
be manipulated internally must be able to be printed, e.g. variables,
and also constants and so on. 

Later on, things such as strings, numeric expressions, and 
..stuff.. will be added to Macas, or whatever it becomes
(Nasic? CBM BASIC 2.2 clone?), and so a PrintString may become
even more fun, exciting, and complex.

---:	[variable name]
: description of variables in Macas.
- by default, [variable name] refers to a double precision floating 
	point number.
- if the [variable name] ends in %, it refers to an 32-bit signed 
	integer. 

see testvar3.cas for examples galore.
---:	<string literal>

string literals are enclosed within in double quotes,
as in "this is a string literal". 

---:	[seperator]
each component of the PrintString thingy can
be seperated by either a comma or a semicolon.

comma:	This acts like a TAB character (9).

semicolon:	
	This is a generic filler seperastor, but 
	when used to terminate a line, surpresses the
	impilicit newline that would otherwise be
	printed.
	
---:	[system string]
- valid [system string]s are currently:
--	engine: e.g. Parse3r4 ; refers to the parsing engine being used.
--	product: e.g. IDE MT.m7.C99 ; refers to the name given to the 
		final product for pseudo-marketing purposes, 
		i.e. "Brand new in IDE MT is the ability to skin cats",
		as opposed to "new in DMX" or "now, dmx.exe features".
		(perhaps "codename" would be more appropriate...)
---:	[system integer]
- valid [system integer]s : 
	first let me say that all system numerics are likely to be integers,
	as floating points (real numbers) tend to be used for calculations,
	and not for initial data storage or anything a system would need.

--	free : returns the number of unused bytes within NASIC Protected
		Access Memory (NPAM).
		
---:
		Now back to our regularly scheduled documentation!
---:
@[column],[row],"[string literal]" 
: Plot At ; a.k.a. Print At. deprecated. archaic. sad,
abandoned, and neglected. 

In it's traditonal form, 
Plot At ('@') does not change the position set
by LOCATE ('l').

This command will not wrap the string to keep it within
the screen matrix, now will it scroll the screen.

This command was useful for quickly outputting a string
literal to a specific position on the screen, but not
much else. 

It was use to test that bound checks were being performed
in earlier parsers, indeed, as early as the now infamous
(and quite archaic) "m1.exe".
---:
l[column],[row] 
: Locate

This command locates the cursor at the specified position;
The default position is "undefined", and not influenced
by Print At. Thus, the first thing you should do is 
locate the cursor somewhere, unless you plan to use
Print At exclusively. 
---:		
o"Label"
: Declares an Objective Label (OL, pronounced aul)

Objective Lavels are simply targets to JMP ('j') commands.
---:
j"Label"
: JMP Label.

This marvelous command causes infinte loops with no remorse
for its actions. The easy way to get out of such a loop is
the use the SKIP command, which is not yet part of NASIC,
but it is a part of the New Interactive Parser.  The NIP
will omit the next JMP command if you press TAB. This keypress
is not buffered, so you may have to hold TAB for a bit.
---:
u"label"
: JSR Label.

This command is basically a GOSUB, the GOUSB/RETURN 
stack is curently 10 deep, so you can nest GOSUBs...

Please note that this is still somewhat experimental.
I will not be liable for damage caused to cats...
---:
n
: Return from JSR

Just like the RETURN Basic command.
---:
r[numeric constant]
: REST time

Based on Allegro's rest(long time) function; this cute
little thing allows you to pause the program for a given
time (in miliseconds); usually done for dramatic effect.

***Runtime Keyboard Commands to Adjust Parser Speed ***
use the PAUSE key on the keyboard to toggle sloth, and also,
use the Keypad Plus ('+') key to speed up the imm,
and the Keypad Minus ('-') key to slow it down. 
This is very Alpha and may not work in you build. This is
now supposed to be here before the HUD (rendlib3/4).
---:
%[variable name]=[numeric constant]
: LET var = constant

The feature attraction, a result of many man-hours of design, planning,
and pure inpired kode, this new fangled command LETs you assign values
to double precision floating point numbers!!! Isn't that great?

Actually, if [variable name] ends in a %, the variable will be a 
signed integer...
---:
!"[String literal]"
: Exclaim 

This unique command echos to the log file,
in v2 it will echo to the status bar as well,
aiding in debugging.
---:
m[conversion mode]
: set ASCII to CBM screencode Conversion Mode

0=uppercase only,
1=uppercase/graphic
2=lowercase/uppercase

Note that mode 0 is bogus, but then again, all of the modes are,
relative to the C64. The C64's whole Screen Matrix was in either
mode 1 or 2 (i simplify, avoiding talk of custom charsets and
bank selection), and thus you couldn't mix graphics and lowercase
characters on the screen. Currently, scrolling (inadvertently) imitates
this behaviour, as only one byte is used to store the values used to
refresh the screen after a scroll.
---:
-
: End Of Used Text

In order to mark the end of a MACAS program,
a single hypen ('-') is used. This is extremely
important, without it, mayhem will ensue!
---]

zoot.

---]
Other features of MACAS: Comments 
-or, what else can I put in those .cas files?

They are 4 possible ways of putting comments in the source file.
There are two ... classes.. of comments, Forgotten, and Remembered.
Read on, it's koolnessism!

Forgotten Comments

(forgotten comments are omitted from the proCAS,
so, don't worry about them taking up valuable
memory)

//
starts a C++ style comment, it's terminated by an EOL
i.e. everything else on that line is ignored.

/* ... */
C style comment; may span several lines.

---:
Remembered comments

(these comments are included in the proCAS,
although they are ignored.)

'
(single quote) : currently broken due to the lack of
this character in the C64's charset, and no decisive
conversion...

or

/
(forward slash) : works perfectly.

: The comments following these characters will be stored
in NASIC code; with white space preserved. Again,
EOL terminates. 

---:

Iggle.

---]
Rayman:

There's a PSX (and now PC-CDROM) game called
Rayman, by Ubi Soft, which has a very atmospheric soundtrack,
in CD-audio tracks. It's like 40+ tracks of music.

I like that soundtrack. 

---]
Contact Info:

email   : granitor@geocities.com (personal) ; c99@mail.com (C99 related) 
url    	: http://www.geocities.com/SiliconValley/Lakes/2658/
	: http://www.geocities.com/granitor (short version of above)
	: http://sig9.dyndns.org/~granitor (silly, mild content)
	
---:
Links:

C64info :

	http://www.c64.org/

C64warez:

        http://www.c64.com/

VICE, the best (IMHO) C64 emulator, as well as emulators for other
Commodore 8-bitten boxen :

	http://fripp.hrz.tu-chemnitz.de/~fachat/vice/

DJGPP:

	http://www.delorie.com/djgpp/

Allegro:

	http://www.talula.demon.co.uk/allegro/

Sex :

	http://www.sexuality.org/

News for Nerds :

	http://slashdot.org/

New kool programs and stuff :

        http://freshmeat.net/ (the Well Known Site)
        http://current.nu/ (a Lesser Known Site)

---]

[[[MooFoxyDinkle!!!
