home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Club Amiga de Montreal - CAM
/
CAM_CD_1.iso
/
files
/
560.lha
/
ChemniMaTe_v0.8alpha
/
Language.DOC
< prev
next >
Wrap
Text File
|
1991-09-19
|
23KB
|
640 lines
33;1m
=============================================================================
CHEMNIMATE 0.8 alpha-release LANGUAGE MANUAL
=============================================================================
Klaas van Gend
Hoekerstraat 9b
5987 AN EGCHEL
THE NETHERLANDS
0;31m
REVISION HISTORY
----------------
EXT. 2 Klaas 08-Jul
EXT. 3 van Gend 22-Jul
REV. 1 W. Huis 27-Jul (My English Teacher) He corrected this manual.
REV. 2 Raymond Knaapen 07-Aug added some things Klaas stupidly had forgotten.
EXT. 4 KP van Gend 26-Aug
3mCONTENTS:0m
0 Preface
1 The command-line
.1 What does a command look like?
.2 What can be parameters ?
.3 What are expressions?
.4 The use of expressions.
2. The commands,
.1 Data
.2 Repeat
.3 Display
.4 Debugging
.5 Show
.6 Display part II.
.7 Text
.8 Change
.9 Assignation
3. Data-line/DisplayModes
.1 DisplayMode 0.
.2 DisplayMode 1.
.4 DisplayMode 3.
4. The Errors.
32;1m/****** 0 **************PREFACE**********************/31;0m
This file will explain you how to programme ChemniMaTe.If you don't have any
experience with programming-languages, it shouldn't be a good idea to start
with this one, as it isn't a very good example of a well-structured
clearly-defined language. It was written piece by piece, command after
command.
About this manual:
All normal text is displayed normally (in MuchMore). All chapter titles are
in black. All examples are in yellow. If you want to load it into some
textprocessor you have to remove all codes for coloured characters.
Otherwise, sending it to a printer will result in some spaghetti. In the
LhArc-Archive, you'll find a program to remove all these codes.
32;1m/****** 1 ***********A COMMAND LINE********************/
1.1 WHAT DOES A LINE LOOK LIKE ?31;0m
Well, a line consists of some text (sometimes no text at all) and should
always end with a hard-return. An empty line is ignored. Text put after a
semicolon (';') should be considered as comment. If a line only consists of
a semicolon or spaces/tabs, nothing will happen.
In all other cases, the first word in the line should be a command,
followed by (when necessary) parameters(values, vars, expressions or
strings). Only one command per line is allowed.
Of course, in a DATA-line (see below) there is no command, so take care the
line starts with something other than an alphanumeric character.
Make sure you enter the right number of parameters, and in the right order.
Always first the numeric ones and after that the strings.
Example 1:
33m Text 20 [#i# + 5] "This is a string" ;comment31m
^ ^ ^ ^
|spaces/tabs at the beginning are ignored.
|this is the command
|this is a value
|this is an expression
ChemniMaTe is case-insensitive, i.e. it doesn't differ whether you enter
commands uppercase or lowercase.
If the line contains more text than only the first word, all other text is
ignored (except for strings :->)
This is useful when entering codes, but I'll explain that later.
32;1m 1.2 What can be parameters?31;0m
There are a few kinds:
nummeric values:
Are always integers (= no floating point), can be negative or positive.
You shouldn't use values greater then ±1000, as there is no need to. The
programme can handle far bigger values, but it isn't really reliable.
vars:
Vars are values represented by a name. You can assign a value to that name.
Example 2:
33mI:= 3; put value 3 in #i# 31m
When you specify #i# as one of the parameters in another line, ChemniMaTe
will insert the value 3 instead of it.
Only numeric values can be assigned to a var, no strings.
Except in assignation, they're always preceded and followed by a '#'.
This is to indicate that between these # # is a varname.
You can do everything with it,i.e. similar to what you can do with values.
At the moment four names are supported:
#i# use when neccessary.
#j# use when neccessary.
#dAn# always contains the Delta-Angle. This is what in the next step of
turn will be added to the Angle.
#Ang# always contains the Angle under which the molecule is seen.
Note that case is not important for ChemniMaTe.
strings:
These always begin AND end in a double quote ( " ).
No processing is possible at the moment.
Make sure they are always last in a line and that there isn't a semicolon
within the string. The result would then be unpredictable.
expressions:
See below, paragraph 1.3.
32;1m 1.3 What are expressions?31;0m
When you want to add 2 and 3, the result equals five. If you want to,
ChemniMaTe can do this for you:
Example 3:
33mI:= [3 + 2]31m
After this line, #i# will contain the value 5.
Example 4:
33mI:= [#i# * 5]31m
In example 4, the value of #i# is multiplicated by 5.
An expression always consists of:
- '[' and ']' which precede and end ANY expression.
- TWO values, expressions or vars.
- ONE modifier.
choose from: * multiply
/ divide
% rest of a divide (12%4 = 0, 15%4 = 3, 16%4 =0)
+ add
- subtract
Oh, by the way, ChemniMaTe only supports integers, (thus: 73 , -20, not: 2.5)
and will round any result to floor.
This is why [15 / 4] will equal 3 and neither 3.75 nor 4.
This is wrong: 33m[ #i# + 6 * 8]31m
It should be: 33m[#i# + [6*8] ]31m
As you can see, nested expressions are allowed, as long as the number of
'[' and ']' stays the same. (otherwise an error will be generated).
Always use enough spaces, to aviod confusion, especially when when using
more than one pair of brackets. ChemniMaTe uses fully recursive routines to
parse the expressions, the only limitation of the size of an expression is
the length of a single line: 255 characters.
32;1m 1.4 The use of expressions.31;0m
Well, let's say you have 5 balls with the numbers 8 to 12 and you want them
to have lines to balls 5 to 9:
Example 5
33m I:= 8 ;assign value to #i#
Repeat 5 times ; repeat 5 times.(times is ignored)
CA #i# 4lin to [#i# - 3]; see below for CA. ('lin' and 'to' are ignored)
I:= [#i# + 1] ; add one to #i#
EndRepeat
31m
Put a ball in the centre of the screen, and move it away with increasing
speed.
Example 6
33mData 1
0 0 0 C0 0 ;1 just a ball.
EndData
I:= 0
Repeat 15
CR ball 1 0r #i# ;Change rel. see below. ('ball' and 'r' are ignored)
I:= [#i# + 1]
EndRepeat
31m
32;1m/********** 2 *******The commands**********************/31;0m
Commands are one word. It is the first thing that should occur in a line
(except for a DATA line...) after (optionally) preceding spaces. After any
command a space should be entered.
The commands are divided into a few different sections.
1m<value>0m means a value/var/expression which ALWAYS must be given.
1m"string"0m means a string. Should always be present when necessary.
The number preceding a command in this section, represents the token of the
command. Don't enter it (And forget the existence), as ChemniMaTe internally
replaces the command by the token.
32;1m 2.1 Data31;0m
0x10 1mDATA <first> 0m
Announces the start of some DATA-lines. The first line is read to be
belonging to ball number <first>.
See chapter ### for the syntax of a dataline.
0x11 1mEndData0m
Announces the end of DATA-lines. When you enter a dataline after this command
it will result in a Syntax Error. No values are required.
0x12 1mANIM "name"0m
This one means nothing. It should be the first command in an animation-script.
The only reason why it exists is called 'Raymond Knaapen' -> He wanted to
make the language look more like PASCAL. It should indicate the name of
the script. Please do not use it in scripts for the Amiga-version, as i might
in future use this one to set ChemniMaTe to displaymode 3 automatically.
32;1m 2.2 Repeat31;0m
0x20 1mRepeat <times>0m
Repeat the sequence between this command and the corresponding 'EndRepeat'
<times> times. Note that nested Repeats are allowed.
Example 7
33m Repeat 2 ;first repeat.
T "hi"
Repeat 2 ; second repeat
T "Goodbye"
EndRepeat ; second repeat
EndRepeat ;first repeat.31m
Will result in:
3m#text: hi
#text: Goodbye
#text: Goodbye
#text: hi
#text: Goodbye
#text: Goodbye0m
0x21 1mEndRepeat0m
Announces the end of a repeat (For BASIC-freaks: "Next").
If no corresponding Repeat is given, it will result in an error statement.
After this command, ChemniMaTe will return to the line after the
Repeat, when the counter of repeats allows for that.
0x22 1mLoop0m
Announces the begin of a Loop-Until sequence.
All statements between Loop and Until will be executed till Until knows
it's time to stop.
0x23 1mUntil <value1> <value2>0m
This is the condition-checker. Returns to the line after Loop when
<value1> is smaller than <value2>.
It is a good idea to put '>=' between the values (ChemniMaTe will
ignore it), but you know when Until will stop.
Example 8
33m Loop
Show 1 frame 1 to 10 ;show 1 time all balls from 1 to 10.
Until #Ang# >= 48 ;note that '>=' is ignored.31m
Will turn the molecule around until Angle is 48. Note that when #ang# is
already bigger than 48 (thus range: 48 to 63), Show will be executed once.
32;1m 2.3 Display31;0m
0x30 1mLines <#On#/#Off#>0m
Turns the displaying of lines on/off.
Example 9
33mLines #Off# ;turn lines off31m
When starting a script, the default is #On#.
0x31 1mBalls <#On#/#Off#>0m
Turns displaying balls on/off.
Default is #On#.
0x32 1mWait <frames>0m
Wait a number of frames. one frame is 1/25 (PAL) second.
Thus to wait 2 seconds:
Example 10
33mWait [2 * 25] ;2 seconds.31m
0x34 1mDisplayMode <which one>0m
Change the display to the specified display mode.
0: standard 3-d mode
1: 2-d watching from above.
3: reserved for Raymond's projection (not implemented yet).
See Data-Line/DisplayModes (Section 3) for discussing how everything works.
32;1m 2.4 debugging31;0m
0x41 1mDebug <from> <to>0m
This command is one of the oldest commands available. It displays the full
array of the balls <from> up to and including <to> on the 'STDIO' -> the
Cli/Shell ChemniMaTe was started from.
In the array, the dimensions are as followed:
0-4 (the first five): See DisplayMode 0.
5-7 (the last three): Carthesian coordinates X,Y,Z. (Not important for users)
0x45 1mSkip0m
Skip a piece of code until a 'EndSkip' is entered.
This is useful when writing large animations, as you can prevent pieces
from being executed. (At least, that's what I implemented these two for.).
0x46 1mEndSkip0m
Is the counterpart of Skip. (See there).
Example 11
33mSkip
T "This won't appear at the Stdio-console!"
Wait 50L ;we won't wait
EndSkip
Show 1 3 5 ;This show will be executed.31m
32;1m 2.5 Show31;0m
0x50 1mShow <times> <from> <to>0m
This command is the most important one: it displays the balls & lines in the
way which is defined by the current displaymode. It will do it <times> times,
and it will display the balls <from> up to and including <to>. It also recal-
culates Angle and DeltaAngle.
Note: it does page-swapping and the clearing of the next page.
0x51 1mShowNS <from> <to>0m
Displays the balls <from> up to and including <to> on the non-displayed
screenpage. This means two differences with "Show": only ONE frame, and not
even a complete frame, as it isn't displayed nor the next page is cleared. It
does do recalculating Angle & DeltaAngle anyway. Using this command only
doesn't make anything visible... You need to call a 'Show' or a 'SPages' to
do that.
0x52 1mSPages0m
Swaps the two screenpages and clears the non-visible one. When drawing or
displaying text after this command, it will be put on the non-visible page.
Use this command to make all changes (done by 'THeader,TFooter,Text,ShowNS')
visible.
32;1m 2.6 Display part II.31;0m
0x60 1mAngle <value>0m
Set the angle to <value>. You shouldn't use this command anymore, as it is
replaced by ANG:= . This command exists for compatibility with previous
versions only.
0x61 1mAngleD <value>0m
Set the Delta-angle to <value>. Delta Angle is the speed of turning.
You shouldn't use this command anymore, as it is replaced by DAN:= . This
command exists for compatibility with previous versions only.
0x62 1mMiddle <x> <y>0m
Set the middle of the display (in Carthesian coordinates it should be (0,0,0))
to the coordinates given by ( <x> , <y> ) . (0,0) is in the upper left corner.
defaultvalues of <x> and <y> are (180, 125) for PAL users.
32;1m 2.7 Text31;0m
0x70 1mTHeader "string"0m
Display the string as Header (text above the screen) on the screen. Note that
only the first 40 characters are displayed.
0x71 1mTFooter "string"0m
Display the string as footer (text below the screen) on the screen. Note that
only the first 40 characters are displayed.
0x72 1mText <x> <y> "string"0m
Put the string on this frame at (x,y). When the string is larger than the
screen, then the string is truncated until it fits. It is only displayed
at the current front-frame. As soon as you use a Show, it becomes invisible.
It is a good idea to do it this way:
Example 12
33mText (32,45) "This will be displayed."31m
Thus, putting (,) around the coordinates.
0x73 1mT "string"0m
Put a string on the stdio (the CLI/Shell ChemniMaTe was started from).
Only useful for debugging, I think.
32;1m 2.8 Change31;0m
0x80 1mCR <ballnr> <what> <delta>0m
Change <what> of ball number <ballnr> with delta -> thus add delta to the
current value.
In DisplayMode 0 (3-Dimensional),
<what> : 0r -> the radius
1ang -> the angle
2hei -> the heigth
3typ -> the type of the ball.
4lin -> the ball which a line should be drawn to.
In DisplayMode 1 (2-Dimensional), is '2hei' not used.
0x81 1mCA <ballnr> <what> <value>0m
Change <what> of <ballnr> to <value>
See for further information: CR.
0x82 1mCM <from> <to> <what> <delta>0m
Change <what> of the balls with the numbers <from> up to and including
<to> with <delta> -> thus Change relative More.
See CR.
32;1m 2.9 Assignation31;0m
0x90 1mI:= <value>0m
Assign <value> to #i#. note that <value> can be an expression, too!
Try to make <value> not bigger than -1000 to 1000.
0x91 1mJ:= <value>0m
Assign <value> to #j#. note that <value> can be an expression, too!
Try to keep <value> between -1000 and 1000.
0x92 1mANG:= <value>0m
Set the AngleOfDisplay to <value>.
<value> can range from 0 to 63, bigger or smaller (?) values are reduced until
they fit into this range, i.e. 123 will become 59.
0x93 1mDAN:= <value>0m
Set the DeltaAngleOfDisplay to <value>.
<value> Can range between -10 and 10, but only integers are allowed.
when negative, the object will turn anti-clockwise, when positive, the object
will turn clockwise. When zero, the object won't turn around.
32;1m/****** 3 ********Data-line/DisplayModes*******************/31;0m
A DATA-line is different from a command-line, as it doesn't contain a command.
It contains five values (NO EXPRESSIONS PLEASE). which will be loaded into the
data-array.
Note that ChemniMaTe should be set in Data-mode first, using the Data <x>
command, where <x> represents the number of the first ball which should be
receiving the data.
32m3.1 DisplayMode 031m
I advise to have the data-part ordened this way.
Example 13
33mData 1 ;In the beginning, there was nothing.
;r hei ang typ lin ;nr which
42 -7 16 In12 02 ;01 This is one of the invisibles.
EndData31m
32m ^ ^ ^ ^ ^ ^ ^
|31mthe distance to the vertical axis.
32m|31mdistance to floorplate.
32m|31mclockwise angle. 32m|31mcomment to explain what it is.
32m|31mwhich ball 32m|31mballnr(is after ';' so it will be ignored).
32m|31mline to which ballnr.
About (r,hei,ang):
|
|
|
| ang
| V
|______________
/33m\ 31m_/32m.31m
/ 33m\ 32m.31m
/ 33m\32m.33mr31m
/32m........33m\31m
/ h33m32m\31m©
/
/
(Or watch the Explain0.ilbm containing this picture.)
about type:
(Note that only the nummerical value is important; the alphanummerical ones
are ignored, as always).
code represents colour
C0 carbon black
S2 sulphur yellow
N4 nitrogen blue
H6 hydrogen white
O8 oxygen red
In12 invisible!! --
Cl14 chlorine green
pl16 (+) , charge of +1.6e-19 (Coulomb)
mi18 (-) , charge of -1.6e-19 (Coulomb)
Hr20 hydrogen RED
Hg22 hydrogen GREEN thus not mercury!!!
R10 -- background
-=>this one is for {restgroepen}:
H O-H
| | (just a prototype of an {aminozuur})
H-N-C-C=O
| |
H R <-this R
The use of Hr20 and Hr22 is for {isomerie}; then you can show how this is
done. i.e. there is a difference between:
H H H H H H
C---C C---C C---C
/H /H / / /H /H
/ / and H/ / and / H/
C===C C===C C===C
H H H H
{De Nederlandse benamingen voor deze stoffen zijn:
^ ^ ^
trans-1-cyclobuteen cis-1-cyclobuteen
}
But we were discussing the data-line, not discussing Chemistry.
A dataline should NEVER start with an alphanummerical character, as that
will be interpreted as a command, and also should(??) result in a "SYNTAX
ERROR".
Datacommands are NOT nested, thus:
Example 14
33mData 5
;r hei ang typ lin ;nr which
42 -7 16 In12 02 ;05 This is one of the invisibles.
33 -7 34 R10 02 ;06 -(R)
Data 9 31m;jump with data to number 9, thus skip 7 and 8.33m
12 23 -6 C0 07 ;09 carbon.
EndData31m
You shouldn't make the 'radius' bigger than ± 120, otherwise the ball will get
out of the screen. When a ball gets out of screen, even with only one pixel,
the WHOLE ball won't be displayed and an #Warning will be generated.
Also, don't make the 'height' too big.
'Ang' should range between 0 and 63. 64 means one time around.
(higher than 64 will be interpreted as x - n*64 to get it ranging
within [0,64>. )
Using a not defined 'Typ' is undefined, the results may vary each second.
Having a 'lin' to a non-displayed (or non-existing) ball will result in strange
lines on the screen.
32m3.2 DisplayMode 131m
Well, this is easy to explain:
It's the same as Displaymode 0, except that this one is 2-d. You watch along
the axis around which everything turns. This implies that 'Height' has no real
meaning here, but the balls are sorted to this one.
In short:
offset name0 meaning
0 Radius distance to turn-axis
1 ANGle angle. (range between 0 and 63).
2 HEIght ---
3 TYPe which kind of ball
4 LINe line to which other ball?
32m3.4 DisplayMode 331m
Not implemented yet, but it is reserved for the displaymode designed by
Raymond Knaapen for his MS-DOS version of this programme.
32;1m/****** 4 ***********The Errors**********************/31;0m
In this chapter I would like to discuss the errors the programme can return
to you. These are not all errors, there are some which should NEVER occur.
If they do occur, please let me know.
Normally, the error-message is followed by "IN LINE ###". In this file
a number is given before the error message. This is the internal error-number,
you won't ever come to see it outside the sourcecode, I hope.
Here we go:
1 1m ## EndData WITHOUT Data0m
Seems you've use EndData without using Data before.
3 1m ## EndRepeat/Until WITHOUT Repeat/Loop0m
You used EndRepeat or Until without specifying (the corresponding) Repeat or Loop
in one of the preceding lines, or you might have made this mistake:
Example 15:
33m Loop
Repeat 5
Show 1 2 5 ; show 1 frame the balls 2 up to and including 5
Until #Ang# >= 57
EndRepeat31m
In English: you've swapped the 'Until' and 'EndRepeat'.
You can't exchange the use of these four, Repeat belongs to EndRepeat, etc.
15 1m ## EndSkip WITHOUT Skip0m
You used EndSkip without specifying the corresponding Skip in a preceding
line.(Or did you think Skip's could be nested? You don't speak C ? That's
what I thought, as /* */ can't be nested, either!)
10 1m ## EXPRESSION: 2 VALUES AND 1 OF: + - * /0m
An expression is written in the following way:
33m[3 + 3]31m where '3' can be a value,expression or var.
'+' Can be replaced by '*', '/' or '-'.
Seems You forgot one of these.
9 1m ## EXPRESSION: DIVISION BY ZERO0m
You've tried to divide by zero.As a result this should give 'infinite'.
I guess, you've tried to divide by an uninitialized var.
16 1m #### EXPRESSION IN A DATA LINE0m
Isn't supported yet. Still, I prefer you not to use expressions in a
script between a 'Data' and an 'EndData' command.
11 1m ## EXPRESSION: UNEQUAL NUMBER OF [ AND ]0m
Take a good look. In the expression you used an unequal number of
left and right brackets.
2 1m ## INCORRECT VALUE(S)0m
At least one of the specified parameters is bigger or smaller than is allowed.
Normally this should be the one with an expression of var in it, or you are
really stupid.
6 1m ## NEEDED #, BUT GOT ONLY # VALUES0m
You gave too few values/expressions/vars.
12 1m ## NOT A KNOWN VARIABLE0m
Listen carefully, I'll say this only once: there are only these vars:
#i# #j# #Ang# and #dAn#. Further there are two constant factors: #On# and #Off#.
5 1m ## SYNTAX ERROR0m
You might get a headache of it, but ChemniMaTe doesn't understand this line.
13 1m ## VARIABLE NOT TERMINATED BY '#'0m
A var should always end with an #, as a string should end with " and an
expression should end in ].
14 1m ### until : INFINITY ERROR0m
This is a neat one. The equation in the 'until <a> >= <b>' still isn't met
after INFINITYMAX (350) times. This error might help you a bit when otherwise
ChemniMaTe would have TILTed. Guess everyone will ever be grateful for this
error to appear, it stops executing the loop.
4 1m # WARNING MORE / LESS THAN 5 DATA VALUES0m
You didn't specify the right number of parameters in this data-line.
7 1m # WARNING: MORE THAN REQUIRED # VALUES0m
Geezz, You have specified too many values/expressions/vars.
0 1m # WARNING: NOT RIGHT NUMBER OF VALUES0m
Shouldn't be in use anymore, as far as I know.
8 1m # WARNING: ONE OF BALLS GOT OUT SCREEN0m
One of the balls got out of the screen.
Note that an Invisible can get out of the screen, too!
That's it. I Hope it is, together with the examples, sufficient to teach your-
self to program animations, when you encounter problems, please write to me.
/* end - of - file */