m6casuse.txt

m6's Mainstream CAS Usage Guide
(c)1999 Keinall "Granitor" Caddle
---]
What's this file about?

This file is roughly equivalent to nessuse.txt;
it gives enough info for one to write C-NASIC src filen.
However, see ident.txt for ident.exe info (such as Command Line
Arguments).

---]
Version and  stuff:

MCAS version : 1.6.1
(parse3 v1.6.1)

for use with (IDENT v1.1.1)

succeeds (mness.exe v1r5u4)

---]
Required files:

CHAR.ROM : Character set; 512 characters * 8 bytes each;
The same as with the C64 will do.

*.CAS : Arbitary MCAS files, revised for m6 format, or, using
the NYI filters in the NYI m6imp, mness or even TESTIN.TXT format.

***for compilation, see ident.txt;

---]
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 volitile RAM than it did when on
disk. Also, the label table is built.
The processed CAS file is sometimes called
proCAS. It's never written to disk, however.
More on storage of M filen later.

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 form the proCAS,
so, don't worry about them taking up volatile
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.)

'
or
/

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

---:
C-NASIC Commands

They are about a dozen valid commands,
each command is one character long (hence "Constricted").

-
: End of File

This is the most important command,
without it, the preparser will never stop
reading the input file, and the program
will loop endlessly. Use Ctrl-Alt-End
to exit swiftly.

**NB: as of r5; i now check for the End of the
input File; so it SHOULD not loop endlessly if
you forget this.

It's still good practice to include
this, however, as otherwise the proCAS will be
malterminated!

s[dummy number]
: CLear Screen

This is the new, improved part of the format.
You can now Clear the Screen! Unlike m1, it's
necessary to clear the screen if u want the 
background to be monochromic; else just a black
(actually, transparent) canvas will stare at you.

**NB: Dummy number no longer needed.
everything after the 's' is ignored.

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

Note that the background color is on a per-cell
basis, as in Standard Hi-Resolution mode on the C64,
rather than a whole-screen basis, as in 
Standard Text Mode on a C64.

l[column],[row] 
: Locate

This command locates the cursor at the specified position;
The default position is "undefined", and not influenced
by Print At.


@[column],[row],"[string literal]" 
: Plot At

The almighty command used to be used for everything.
Now it is surpassed by Print, however, it's still
handy ot use Plot sometimes...parse3.c is a bit
muddled about this codewise, but it works this way:

LOCATE ('l') puts the cursor where you want it for PRINT ('?'),
whilst Plot At ('@') doesn't change the position you set
by LOCATE ('l').


?"[string literal]"
: the supermighty -Print- Command!

Not only does this print the given screen, but 
it wraps the string (something Plot At does not do);
AND it scrolls the screen if necessary!!! 

Note that the quotes are necessary, The string
literal is converted to CBM charcodes using
the new improved getFasc; see foolib.h/.c if u are
C-literate. Also see the MODE command ('m').

]"Label"
: Declares a Label. Obsolete.

Rather than using line numbers, 
C-NASIC uses labels, which are
more Symbolic and fun; A Label Table is established in 
NASIC Protected Access Memory by m1import (the preparser);
and it's used by the parser to convert labels to native
line numbers; there is currently a ratio of one statement
per line, also, line numbers start at 1 and may go to
2^32 - 1; or around 4 billion. However, NASIC RAM is 
limited by m5ness to 16MB max. 

Note aslo that labels are currently
case sensitive, this is wrong, they will eventually be case
insensitive.

o"Label"
: Declares an Objective Label (OL, pronounced aul)

Whilst hacking around in parse3, I inadvertantly broke GOTO, and
decided it was time to toss away line numbers in any case,
as CAS replaces ASM on the C64, rather than BASIC. ASM is mnemonic
and fast, so I want CAS to be fast and .. err.. somewhat mnemonic, I guess.

The emphasis is on fast, though. I figure that when you're interpeting,
the commands should do one discrete task, wheter it takes one or a
thousand lines of C code is not important, because it's easier to
optimise the C code that prints a string than to optimise the code that
prints one character, because we could print the line, then refresh the
screen vs. printing each char, refreshing the screen, and then getting the
next command. But, I digress.

Objective Labels are just like normal labels, except that the offset
is stored rather than the line number. As line numbers are calculated
rather than embedded, it's better to use offsets and avoid the
excess calculations. How much better? at least twice as fast, I guess.
I could do the math, but that would be boring. Working out the speed
increase is left as an exercise for the reader.

Note also that NASIC RAM can actually be around 4GB big (i.e. 2^32 ish).


g"Label"
: GOTO Label. *deprecated. avoid usage, see 'j' *


j"Label"
: JMP Label.

This ingenious command decimates the dismal performance of GOTO,
using offsets instead of bogus line numbers. Also, it works,
whilst GOTO is broken...

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 GOTO command if you press TAB. this keypress
is buffered. I think.

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.

note also that m5ness now has a sloth setting which slows 
down program execution (necessary because the rendering 
engine is a bit spedier that i'd hoped). enable
CAPS LOCK to disable sloth. this relationship is 
maintained.

%[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?

Stay tuned for upcoming enhancements...

d[variable name]
: PRINT_DOUBLE var

In order to prove that variables are really being assigned and such,
this quick hack prints out the value of a variable. Isn't that
cute?

More to come...

!"[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.

In the future, the SMELL will be made to (optionally) emulate the C64's
behaviour totally, but I'm also thinking of using WORDs (16-bits)
to store Unicode characters in C99 native mode. We'll see, I guess.
Unicode seems kool...

---]
Format of TESTIN.TXT; another look.
(adopted from m1's usage.txt)
** NB: C-NASIC files now use the extention .CAS by convention,
even though they're still plain text (ASCII) files. 

TEXTIN.TXT : the semi-tokenized program file to parse.

        format:
	
	
	![literal]
	c[color]
	b[color]
	s1
	...
        @[column],[row],[literal]
        ...
        c[color]
	b[color]
        ...
	l[column],[row]
	?[literal]
	...
        r[time in ms]
	["Label"
	...
	g"label"
        -

The @ indicates PrintAt, [column] = 0-39, [row] = 0-24
 (numeric constant literals);
and [literal] is a quote-enclosed string, e.g.

@1,1,"HELLO WORLD!"
@1,24,"GOODBYE WORLD!"

The c indicates COLOR, and is equivalent to POKE 646,[color]
on the C64. Thus [color] ranges form 0 to 15.
The C64's BASIC really needed this command!!!

The s clears the screen, the number after it is 
arbitary and effectively a dummy variable, use 
any whole number from 0 to around 16 million.
**new for r5: s now doesn't need a dummy variable any more!

***IMPORTANT!!!
Note that the hyphen ('-') is the EOF character...
forget it, and suffer in unspeakable pain.

---]
Misc.:

The render library can actually render sprites;
In particular, load and display Chip's 24x24
sprites. But I have yet to write this into the 
interpeter. Depending on how NASIC goes, i may 
add this into the next release... this is more likely
than me writing instructions for KC; and less likely
than me releasing the full source soon.

I also intend to run a global co-orporation
some day, guess which one will come first...

Oh, and also, press ESC to exit;
press Print Screen to take a screenshot to dump.pcx;
 
---:
** NB: The Parser is now slightly interactive.
before running each command (i.e. at the start of each
line), the parser checks the status of certain keys:

ESC - aborts the program (parser); m5ness also traps this,
so you may have to tap it twice. I'm going to put some
text on the screen to prompt you do do this Real Soon Now.

SPACE - disables internal sloth (used to pause between
lines). Hold it down to maintain effect.

CAPS LOCK: if enabled, disables the REST[r]
command; but enables sloth.

UP/DOWN Arrows: they decrease and increase sloth,
repectively. ithis is a rough hack and I'll make a nicer
way to do it before I move onto NASIC proper (no C-);
but until then, deal with it.

TAB : Tapping this break the current infinite loop by ignoring
the next GOTO[g] command.

PRT_SCRN: The good old print screen key can now take a screenshot
(dump.pcx) whilst the C-NASIC program is running. Aren't u glad?

---]       
Conclusion:

Constricted NASIC is just used to test out the Screen
Matrix Emulation Layer Library, it's not meant for
serious use. I'm working slowly but surely on a proper
NASIC IDE, but it will be a while before it's usable,
for many reasons including (but not limited to )
the price of plane tickets to New York at the end of
Summer.

And, that's All I Have to Say.

Have a Good Life, and be careful.

---]
Contact Info:

email   : granitor@geocities.com
url     : http://www.geocities.com/SiliconValley/Lakes/2658/

---]
Be kind to integers.
Respect their alignment, 
for this is good.

Note the sign,
for this is the MSB.

Respect the endian,
wheter big or little.

---]
Read The Manual First. Please. I spend time writing it to
make eveyone's life easier.
