nessuse.txt

m5ness (mness.exe) release 5 - Usage Guide
(note that this is not Version 5, nor even Version 2,
just release 5! The version is still 1ish!)

---]

Invoking Syntax:

prototype ledgend:

<> optional
[] required

prototype:

m1 < r[ramsize value]<ramsize exponent> >

e.g. m1 r38k
(reserve 38K)

e.g. m1 
(default ramsize is 3.8K.)

e.g. m1 r1M
(reserve 1 Megabyte)

e.g. m1 r300b
(reserve 300 bytes)

e.g. m1 r38911
(reserve 28911 bytes, just like a C64)

ramsize exponent is :

b = byte;
K = Kilobyte, 1024 bytes;
p = C64 page, 256 bytes;
P = x86 Page, 4 Kilobytes;
M = Megabyte, 1024 Kilobytes;
default = byte;

---]
Required files:

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

MAUTORUN.TXT : This is run by mness to imm the C64's startup;
the C64's startup was actually in ML. Press SPACE to
continue after it's done.

TESTIN.TXT : The input file, in C-NASIC Text.
Either an m1 TESTIN.TXT format, or the new, improved, 
m5ness format. See the Format section l8r.

***for compilation, see readme.txt;

---]
Output files:

m5ness.log, 
m1parse.log,
amd m1imp.log
are written by mness.exe;

You can ignore these files, they should be about
1K in length; They're not as useful as m1 because
u can't control their output directly... but,
the next version will make debugging more possible.

---]
TESTIN.TXT format:

This is a plain ANSI ASCII text file;
**NEW to m5 (as of m5ness-r5):
You now have not one, not two, but 3
possible ways of putting comments in the source file.
commnents will not be store dwhen the file is
loaded to memory; so feel free ot be libiral.

---:
Forgotten Comments

//
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

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

they are about 12 valid commands,
each command is one character long.

-
: 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;
it will be translated as END later.

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
(actuallt, transparent) canvas will stare at you.

The number is "dummy", placebo, not minded at all.
It's needed because it was easier to use it than to 
re-implement the parser/preparser. Think of it as the
number used when u use RND() on a C64.

*** New as of r5: 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!


?"[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. If not, just know that all letters will be
in upper case for now. Again, this is more restricting
than m1 but will be addressed in the Next Version.

]"Label"
: Declares a Label.

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. 

["Label"
: GOTO Label. * depricated *

***depricated!!! obsolete!!! never implemented!!! do not use!!!
I realise this is easily confused with the label decaration,
So don't use it.
Forget it exists.
The Parser will recognise it and lookup the label name 
but take no useful action.

g"Label"
: GOTO 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 GOTO command if you press TAB whilst it
is about to start parsing a new line. Just hold TAB and
you should be cool, if sloth is disabled then just tap
TAB.

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 settign 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.

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

fun, fun fun!

---]
Format of TESTIN.TXT; another look.
(adopted from m1's usage.txt)

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.

***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.

This code is stable, but the preparsor doesn't strip
all whitespace properly. This is indeed a bug, but 
I am in no hurry to fix it.

Oh, and also, press ESC to exit;
press Print Screen to take a screenshot to dump.pcx;
That is, after the Parser has finished running the program.

I intend to make the parser more interactive, but then again,
I also intend to run a multimillion dollar co-orporation
some day, guess which one will come first...

---:
** 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?

---:


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.
