-
Notifications
You must be signed in to change notification settings - Fork 2
/
MANUAL.DOC
1613 lines (1369 loc) · 63.1 KB
/
MANUAL.DOC
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
Common Forth Experiment Version 1.668 User Manual
ÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ
Luke Lee
( This file is still under construction !!! )
þ This software is distributed WITHOUT ANY WARRANTY.
þ Read README.TXT for release notes.
þ This manual is written for DJGPP versions, so if you try
to use Watcom C/C++ versions, please forgive me for all
the version inconsistency.
ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
Operating Basics
ÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ
þ This system is Case-Sensitive !! This is all because of Chinese
Big-5 codes.
þ Do not press <CTRL>-<BREAK> or <CTRL>-<C> unless you have no other
way to quit system, this will abort system and discard any unsaved
information.
þ Any command you typed in is called a 'WORD' in FORTH, each word is
delimited by a space character ( space bar ) .
------------------------
I. Commonly used words :
------------------------
WORDS ( -- ) Display all the available commands in this vocabulary .
ALLWORDS ( -- ) Display complete command set in this vocabulary,
including any INVISIBLE words which should not be used .
SEE <WordName> Decompile <WordName> into source code .
You must FLOAD SEE.4TH first.
For example : FLOAD SEE.4TH
SEE parse
SEE WORDS
SEE SEE
<SEE> ( code -- ) Decompile an address .
Example :
' WORDS <SEE>
'?KEY @ <SEE>
BYE ( -- ) Leave this system, return to DOS .
BYE' ( -- ) Terminate this system immediately, if BYE fails, use
this instead.
<< NOTE : If it still won't work, press <CTRL>-<BREAK> . >>
CLS ( -- ) Clear screen .
...............................................................................
: NOTE : If your VGA system supports VESA BIOS, you should set the following :
: environment variable before you enter CF system, otherwise the :
: following DOS commands MIGHT crash your system, this bug is in :
: GO32.EXE with its default VGA driver. Use VESA driver instead :
: SHOULD fix this problem. :
: :
: SET GO32=driver f:/cf/vesadrv.vdr gw 640 gh 480 nc 256 :
: ÄÄÂÄÄ- ÄÄÂÄÄ- ÄÄÂÄÄÄ- :
: ³ ³ ³ :
: ³ ³ À default number of :
: ³ ³ colors in graphics md.:
: ³ ³ :
: ³ ÀÄ- default number of pixels of :
: ³ screen height in graphics md:
: ³ :
: ÀÄ- default number of pixels of screen :
: width in graphics mode. :
: ( The maximum number of colors is 32768 ) :
:.............................................................................:
DOS <DOS commands>
Shell to DOS, the first time might take a little longer since
program space is completely swap out to a disk file by GO32.
For example : DOS ...... shell to DOS, type EXIT to return
DOS DIR /W
DOS MSBACKUP
DOS QBASIC
DOS EDIT CF.INI
DOS TYPE CF.INI
þ Available DOS commands are :
DIR COPY DEL XCOPY ECHO MD MKDIR RD RMDIR CD CHDIR
MEM CHKDSK TREE PATH RENAME REN
<< Note 1 : The DOS command 'TYPE' cannot be used since 'TYPE' is
a FORTH word with its own meaning.
Use 'DOS TYPE ...' instead . >>
<< Note 2 : The parameter for commands must be delimited by a space
like "DIR /W" but not "DIR/W" . >>
FLOAD <filename> Load a source program written in FORTH, extension name
must also be typed in .
For example : FLOAD DEMO_GRX.4TH
FLOAD DEMO_C.4TH
FLOAD 3DROTATE.SEQ
FLOAD 3DR.4TH
NEEDS <filename> If <filename> is not loaded, it will FLOAD it, otherwise
nothing will happen, this word is used for preventing
duplicated FLOAD .
UNLOAD <filename> Unload a program , however, if it modified system vectors,
THIS MIGHT CRASH YOUR SYSTEM !!!!
RELOAD <filename> UNLOAD a program and FLOAD it again .
MULTI ( -- ) Multitasking mode, if any exception catched by this system
,system will be reset to single tasking mode, which will
cause the cursor in graphics mode to disappear.
TEXT-MODE ( -- ) Switch display to 80x25 text mode, the display speed is
faster since each character requires only 2 bytes .
This facility is provided by GRAPHICS.4TH .
GRAPHICS-MODE Switch display and screen I/O to pure graphics mode, the
display resolution is default in 640 x 480 x 16. You
can change it by setting the GO32 environment variable
described above, for example : 1024x768x256
SET GO32 = driver f:/cf/vesadrv.vdr gw 1024 gh 768 nc 256
and in FORTH do
G1024x768x256 to GDefaultMode GRAPHICS-MODE
The display speed changes according to your resolution.
-----------------------
II. Keyboard commands :
-----------------------
The keyboard commands are similar to DOSKEY .
<ESC> : Clear current command.
<Up> <Down> : Scroll the command histories .
<F7> : Display command history .
<Alt-F7> : Clear command history .
<Ctrl-Left> : Left one word .
<Ctrl-Right> : Right one word.
<Ctrl-End> : Delete characters to end of line.
<Insert> : Switch between inserting mode and replacing mode .
<Back space> : Delete the previous character .
<Delete> : Delete the next character .
<Left> <Right> : Cursor movements, no need to explain.
<Enter> : Enter your command.
-------------------------
III. Using CHINESE.4TH :
-------------------------
0. There are a few user-controlled flags :
PreReadFonts? Default value is FALSE, since this function
takes a lot of memory,
ChooseBestFont? Default value is TRUE, it will choose the best
font according to your selected resolution.
If your default resolution is 1024x768, it will
choose 24x24 fonts.
FONTSIZE Accept only 15 or 24, is will be set to proper
value if ChooseBestFont? is TRUE .
FONTTYPE Apply to 24x24 fonts only, accept ASCII character,
'R' for STDFONT.24R , 'K' for STDFONT.24K ...
1. Setting path of your ET3 :
Before you enter CF.EXE , set environment variable ET3 :
SET ET3=E:\ET3
or the default path will be C:\ET3
2. Try this :
FLOAD CHINESE.4TH
FLOAD SAMPLES\DUMPFILE.4TH
DUMPFILE <filename> ... dump a Chinese Big-5 coded text file.
3. If you are now running Eten Chinese system and still wish to do graphics
works, then you MUST use CHINESE.4TH or your have to switch Eten to
proper mode by your hand, otherwise your graphics works might disturb
Eten's Chinese displaying .
4. Used in turnkey systems :
Before you 'FSAVE', remember to 'CloseChinese' first, and your
application startup code must execute 'OpenChinese' .
5. Some details :
a) OpenChinese v.s. CloseChinese
b) use 'ENGLISH' will back to ASCII character set.
c) use 'CHINESE' will enter Chinese character set.
d) Example :
if you are using 1024x768, try the following :
FLOAD CHINESE.4TH // default STDFONT.24
FLOAD SAMPLES\DUMPFILE.4TH
DUMPFILE <filename> // Dump a BIG-5 coded Chinese file
CloseChinese
ASCII R TO FONTTYPE // use STDFONT.24R
OpenChinese
DUMPFILE <filename> // Dump a BIG-5 coded Chinese file
6. About Chinese Font cache :
OpenChineseCache .... default. Takes some virtual memory.
The hit ratio is about 90% in average .
CloseChineseCache .... greatly reduce it's performance
7. Before you FLOAD CHINESE.4TH, define a word named 'statistics' will
enable Chinese Font Cache statistics , for example :
: statistics ;
FLOAD CHINESE.4TH
FLOAD SAMPLE\DUMPFILE.4TH
DUMPFILE <filename> ... Big-5 coded text file.
CACHE/STAT ...... display Chinese Font cache hit ratio.
8. Note that no font file have been pre-read into memory by default,
you can set
TRUE to PreReadFonts?
and then CloseChinese OpenChinese , all fonts (except USRFONT) will
be loaded . However this takes up A LOT OF memory, in fact, VIRTUAL
memory. This will lift up the performance on cache miss.
9. For extra details, see CHINESE.4TH source code itself.
ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
Meta Compilation
ÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ
The meta-compilation process is automatical; however, during the
automatic meta-compiling process, you MUST NOT press any key, or it
might break the automatic process, in such situation, just do BYE' or
perform the compilation manually.
You must use BYE' after you try meta, BYE won't work in such cases.
NOTE : Before you start meta-compilation, rename the CF.INI into other
names or it will cause problems.
Detail steps ( for manual meta-compilation ) :
1. GO32 CF ................... ..... CF 1.6X, under MSDOS
2. FLOAD CFMETA.4TH ................ loading this meta compiler
3. AUTOMETA OFF .................... turn off autometa facility
4. META1 ........................... start meta compiling pass 1
5. FLOAD HI.4TH .................... after new system starts up
6. FLOAD CFMETA.4TH ................ same as step 1.
7. AUTOMETA OFF .................... same as step 3.
8. META2 ........................... meta compiling pass 2
9. FLOAD HI.4TH .................... for obtaining FSAVE ...etc.
10. FSAVE BYE' ...................... save image and quit.
Use BYE' not BYE !!
Quick steps ( for automatic meta-compilation ) :
1. GO32 CF ......................... CF 1.6X, under MSDOS
2. FLOAD CFMETA ................... steps 2,4,5,6,8,9.
< NOTE! Do not press any key until it stops and shows "ok" >
3. FSAVE BYE' ...................... step 10.
ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
Creating Turnkey System
ÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ
See README.TXT for this .
ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
Including your C(++) Library :
ÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ
This depends on what kind of C(++) compiler you use, this version is
implemented by DJGPP ( GNU C for DOS ) + GO32 . So you must compile your
C source code under DJGPP :
1. Compile your C source code with DJGPP .
2. Register the function names and parameter description in EXTENDED.CC,
( not INVOKEC.CC, it is for ANSI C standard library . )
3. Modify MAKEFILE or CYCLE.BAT and then use MAKE or CYCLE.BAT to
rebuild the loader 'CF.' ( Don't use BIND.BAT to bind it with
GO32.EXE currently, since you havn't test your codes yet ) .
4. Run your new loader with command line "GO32 CF" and then
FLOAD INVOKEC.4TH , test your functions in FORTH.
5. After you have tested your C functions, use BIND.BAT to bind your
new loader with GO32.EXE .
6. Keep your source codes yourself if you are not willing to release.
For Watcom C/C++ users, there is another version of loader for this. The
Common Forth system itself is the same but only C interfaces are different.
The released version use PMODE for DOS Extender, you can change it with
Phar Lap's RUN386, but you cannot use DOS4GW since the memory map is
different. However, if you know how to meta-compile this system, you could
meta-compile a new version for your need. Besides, the RUN386 version could
be executed under Windows's MSDOS session.
A version for DJGPP 2.0 is about to release, after DJGPP's out of beta.
ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
Brief Summary
ÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ
-----------------------------
þ Frequently Used Constants :
-----------------------------
TRUE ( -- -1 )
FALSE ( -- 0 )
CELL ( -- 4 )
BL ( -- 32 ) Return 32, the blank character in ASCII code
LF ( -- 10 ) Return 10, Line feed character in ASCII code.
NULL$ ( -- a ) Return address of a null string with zero count.
NULL ( -- 0 ) Zero pointer .
---------------------
þ Memory Operations :
---------------------
CODE: ! ( w a -- )
Pop the data stack to memory.
CODE: H! ( hw a -- )
Pop the data stack to half-word ( 16bit ) memory.
CODE: C! ( c b -- )
Pop the data stack to byte memory.
: 2! ( d a -- )
Store the double integer to address a.
CODE: @ ( a -- w )
Push memory location to the data stack.
CODE: H@ ( a -- hw )
Push halfword memory location to the data stack.
CODE: C@ ( b -- c )
Push byte memory location to the data stack.
: 2@ ( a -- d )
Fetch double integer from address a.
: MOVE ( from to count -- )
Move memory block with 'count' bytes, move from 'from' to 'to'.
This word will determine the correct direction if 'from' and 'to'
are overlapped.
: CMOVE ( from to count -- )
Copy memory block 'count' bytes from 'from' to 'to'.
Direction : lower memory first.
: CMOVE> ( from to count -- )
Copy memory block 'count' bytes from 'from' to 'to'.
Direction : higher memory first.
: FILL ( addr count ch -- )
Fill 'count' bytes of character 'ch' to area beginning at 'addr'.
: ERASE ( addr count -- ) Fill memory with zeros.
Fill 'addr' with 'count' bytes of zero.
: OFF ( adr -- )
Clear the content of adr . ( Set to FALSE = 0 )
: ON ( adr -- )
Set the content of adr . ( Set to TRUE = -1 )
: +! ( n addr -- )
Add n to the contents at address addr.
------------------------
þ I/O Port fetch/store :
------------------------
CODE: PC@ ( addr -- byte ) Fetch byte from port 'addr'
CODE: PH@ ( addr -- byte ) Fetch 16bit from port 'addr'
CODE: P@ ( addr -- byte ) Fetch 32bit from port 'addr'
CODE: PC! ( byte addr -- ) Store byte to port 'addr'
CODE: PH! ( 16bit addr -- ) Store 16bit to port 'addr'
CODE: P! ( 32bit addr -- ) Store 32bit to port 'addr'
--------------------
þ Stack Operations :
--------------------
CODE: DUP ( w -- w w ) Duplicate the top stack item.
CODE: DROP ( w -- ) Discard top stack item.
CODE: SWAP ( w1 w2 -- w2 w1 ) Exchange top two stack items.
CODE: OVER ( w1 w2 -- w1 w2 w1 ) Copy second stack item to top.
CODE: ROT ( w1 w2 w3 -- w2 w3 w1 ) Rot 3rd item to top. ( Rotate out )
CODE: -ROT ( w1 w2 w3 -- w3 w1 w2 ) Rot top item to 3rd. ( Rotate in )
CODE: NIP ( w1 w2 -- w2 ) Discard second of stack
CODE: 2DUP ( a b -- a b a b ) Duplicate a double-precision item
CODE: 2DROP ( n n -- ) Drop a double-precision (64bit) item.
: 2SWAP ( a b c d -- c d a b )
: 2OVER ( a b c d -- a b c d a b )
: 2ROT ( a b c d e f -- c d e f a b )
: TUCK ( n1 n2 -- n2 n1 n2 )
CODE: PICK ( ... +n -- ... w ) Copy the nth stack item to tos.
CODE: 3DROP ( n n n -- ) Drop three items on data stack.
CODE: 4DROP ( n n n n -- ) Drop four items on data stack.
CODE: 5DROP ( n n n n n -- )
CODE: 6DROP ( n n n n n n -- )
CODE: 7DROP ( n n n n n n n -- )
CODE: 8DROP ( n n n n n n n n -- )
CODE: >R ( w -- ) Push top of data stack to the return stack.
CODE: R@ ( -- w ) Copy top of return stack to the data stack.
CODE: R> ( -- w ) Pop the return stack to the data stack.
CODE: RDROP ( -- ) Drop top of return stack.
: ?DUP ( w -- w w | 0 ) Dup tos if its is not zero.
---------------------------------
þ Forth CPU Register Operations :
---------------------------------
CODE: RP@ ( -- a ) Push the current RP to the data stack.
CODE: RP! ( a -- ) Set the return stack pointer.
CODE: SP@ ( -- a ) Push the current data stack pointer.
CODE: SP! ( a -- ) Set the data stack pointer.
CODE: UP@ ( -- a ) Pointer to the user area.
CODE: UP! ( a -- ) Set user pointer to 'a'.
---------------------------------------
þ Logical operations ( bit operations )
---------------------------------------
CODE: NOT ( w -- w ) One's complement of TOS.
CODE: AND ( w w -- w ) Bitwise AND.
CODE: OR ( w w -- w ) Bitwise inclusive OR.
CODE: XOR ( w w -- w ) Bitwise exclusive OR.
CODE: = ( w w -- t ) Return true if top two are equal.
CODE: < ( n1 n2 -- t ) Signed compare of n1 and n2.
CODE: > ( n1 n2 -- t )
: <= ( n1 n2 -- t )
: >= ( n1 n2 -- t )
: <> ( n1 n2 -- t )
CODE: U< ( u1 u2 -- t ) Unsigned comparision of u1 and u2
CODE: U> ( u1 u2 -- t )
: U>= ( u1 u2 -- t )
: U<= ( u1 u2 -- t )
CODE: 0< ( n -- t ) Return true if n is negative.
CODE: 0= ( n -- t ) Return true if n is zero.
CODE: 0<> ( n -- t ) Return true if n is not zero.
CODE: 0> ( n -- f ) Return true if n is positive.
: 0>= ( n -- t ) Return true if n>=0
: 0<= ( n -- t ) Return true if n<=0
: [...] ( n l h -- t ) TRUE if l <= n <= h ( signed comparsion )
: [...) ( n l h -- t ) TRUE if l <= n < h ( signed comparsion )
: (...] ( n l h -- t ) TRUE if l < n <= h ( signed comparsion )
: (...) ( n l h -- t ) TRUE if l < n < h ( signed comparsion )
: BETWEEN ( N LO HI -- T/F ) Same as [...]
: WITHIN ( u ul uh -- t ) Unsigned comparsion, return TRUE if u is
within the range of ul and uh. ( ul <= u < uh )
-------------------------
þ Arithmetic Operations :
-------------------------
CODE: NEGATE ( n -- -n )
Two's complement of tos.
: DNEGATE ( d -- -d )
Two's complement of a double integer.
CODE: SGN ( n -- -1/0/1 )
Get the sign of n.
: ABS ( n -- n )
Return the absolute value of n.
CODE: UM+ ( u u -- udsum )
Add two unsigned single numbers and return a double sum.
CODE: UM* ( u u -- ud )
Unsigned multiply. Return double product.
CODE: UM/MOD ( udl udh un -- ur uq )
Unsigned divide of a double by a single. Return mod and quotient.
CODE: + ( n1 n2 -- n1+n2 )
Add top two items.
CODE: - ( n1 n2 -- n1-n2 )
Subtraction.
CODE: * ( n1 n2 -- n )
Return n1*n2.
CODE: / ( n1 n2 -- q )
Return only quotient of (n1/n2)
CODE: MOD ( n1 n2 -- r )
Return only remainder of (n1/n2)
: D+ ( d1 d2 -- d3 )
Add two double integers.
: M/MOD ( d n -- r q )
Floored division, divide a double precision number with a
single precision number.
: /MOD ( n1 n2 -- r q )
Return remandier/quotient of (n1/n2)
: M* ( n1 n2 -- d )
Return (n1*n2) with double precision.
: */MOD ( n1 n2 n3 -- r q )
r,q are remainder/quotient of (n1*n2/n3)
: */ ( n1 n2 n3 -- q )
Return only quotient of (n1*n2/n3)
CODE: CELL+ ( a -- a+4 )
Add cell size in byte to address.
CODE: CELL- ( a -- a-4 )
Subtract cell size in byte from address.
CODE: CELL* ( n -- n*4 )
Multiply tos by cell size in bytes.
CODE: CELL/ ( n -- n/4 )
Shift tos 2 bits rightward.
CODE: 1+ ( n -- n+1 )
Increase TOS by 1 .
CODE: 1- ( n -- n-1 )
Decrease TOS by 1 .
CODE: 2* ( N -- n*2 )
Shift tos 1 bit leftward.
CODE: U2/ ( N -- n/2 ) ( Change sign if negative. )
Shift tos 1 bit rightward logically.
CODE: 2/ ( N -- n/2 ) ( Keep sign bit the same. )
Shift tos 1 bit rightward arithmatically.
CODE: 256* ( n -- n*256 )
Shift TOS 8 bits leftward.
CODE: U256/ ( u -- u/256 ) ( Change sign if negative. )
Shift TOS 8 bits leftward logically.
CODE: 256/ ( n -- n/256 ) ( keep sign bit the same. )
Shift TOS 8 bits leftward arithmatically.
: MAX ( n1 n2 -- n )
Return the greater one of n1 and n2.
: MIN ( n1 n2 -- n )
Return the smaller one of n1 and n2.
------------------------
þ Basic Text I/O Words :
------------------------
: CLS ( -- )
Clear screen.
: AT? ( -- col_x row_y )
Return current cursor position.
: AT ( col_x row_y -- )
Set current cursor position.
: ?KEY ( -- c T | F )
Return input character and true, or a false if no input.
: KEY ( -- c )
Wait for and return an input character.
: EMIT ( c -- )
Send a character to the output device.
: SPACE ( -- )
Emit a BL character.
: BEEP ( -- )
Make a beep. ( Send an ASCII 7 )
: CR ( -- )
Send a carrage return character.
: EXPECT ( buf len -- )
Accept input stream and store count in SPAN.
: QUERY ( -- )
Accept input stream to terminal input buffer.
: SPACES ( +n -- )
Emit 'n' BL characters.
: NUF? ( -- F )
Return TRUE and wait for next keystroke if any key pressed,
otherwise return FALSE.
: TAB ( -- )
Emit spaces and advance current cursor position to multiples of eight.
: TYPE ( buf count -- )
Display the content of 'buf' with 'count' characters.
: . ( n -- )
Display a signed number at current cursor position.
: U. ( u -- )
Display an unsigned number at current cursor position.
: .H ( n -- )
Display a signed number in hexadecimal at current curosr position.
: U.H ( n -- )
Display an unsigned number in hexadecimal at current cursor position.
: .R ( n +n -- )
Display a signed number 'n' with '+n' characters with right adjustment.
: U.R ( u +n -- )
Similar to .R but with unsigned output.
: U.0R ( n +n -- )
Similar to U.R but with zeros leading.
: .( ( -- ) < Interpreting mode >
Display text string in interpreting mode, text string terminated with
a character ')'.
: ." ( -- ) < Compiling mode >
Compile text string into dictionary, display text string at run-time,
The text string is terminated with a character '"'.
: ? ( addr -- ) @ . ;
Display the content of 'addr'.
----------------------------------------------
þ String/Number Conversion, single precision :
----------------------------------------------
: DECIMAL ( -- )
Set current convertion base to decimal. This is the default.
: HEX ( -- )
Set current convertion base to hexadecimal.
: BINARY ( -- )
Set current convertion base to binary.
: NUMBER? ( adr -- d T / n T / adr F )
Convert a counted string 'adr' to number.
: str ( w -- buf count )
Convert a number to a string at 'buf' with length 'count' .
: <# ( -- )
Initiate the numeric output process.
: HOLD ( c -- )
Insert a character into the numeric output string.
: # ( u -- u )
Extract one digit from u and append the digit to output string.
: #S ( u -- 0 )
Convert u until all digits are added to the output string.
: SIGN ( n -- ) 0< IF ASCII - HOLD ENDIF ; 1 0 #PARMS
Hold a sign character '-' if n < 0.
: #> ( w -- b u )
End convertion procedure, return a string with address at 'b' and
length with 'u'.
: DIGIT ( u -- c )
Convert digit u to a character.
---------------------
þ String Operations :
---------------------
: COUNT ( b -- b+1 +n ) Convert counted string to string and length.
Return count byte of a string and add 1 to byte address.
: $" (( -- )TIB: <string> ) Runtime : ( -- addr )
Compile an inline string literal. Return the address of
a counted string at 'addr', use COUNT to TYPE it.
: " (( -- )TIB: <string> ) Runtime : ( -- string length )
Compile an inline string literal. Return string and length
of this inline string literal at run-time.
: Z$" (( -- )TIB: <string> ) Runtime : ( -- addr )
Compile an counted ASCIIZ string. Return the address of
a zero-ended counted string.
: $= ( CSTR1 CSTR2 -- T/F )
Compare two counted string, check whether they are the same.
: $+ ( target$ src len -- target$ ) Concat strings .
Concat source string into a counted-string
Note that target$ buffer must be large enough
target$ : counted string
src : source string address ( not including the count byte )
len : the length to concat
CODE: COMP ( S D len -- flag )
Compare two string with len bytes,
flag<0 if S<D, flag=0 if S=D, flag>0 if S>D, you can use
'SGN' to convert them into -1/0/1.
: -TRAILING ( b u -- b u )
Adjust the count to eliminate trailing white space.
: PACK$ ( b u a -- a )
Build a counted string with 'u' characters from 'b' at 'a'.
Null fill. Also put a trailing zero to build an ASCIIZ sting.
-------------------------------------------------
þ Define Named Data Objects / Memory Allocation :
-------------------------------------------------
: ALLOT ( n -- )
Allocate n bytes to the code dictionary.
: CREATE ( -- )TIB: <name> )
Create a buffer and named it as <name>.
Ex : create a 4K buffer and named it as Buffer
CREATE Buffer 4096 ALLOT
: "CREATE ( string length -- )
Create a buffer with name specified with 'string' and 'length'.
Ex : create a 4K buffer and named it as Buffer
: CreateBuf " Buffer" "CREATE 4096 ALLOT ;
: VARIABLE ( -- )TIB: <name> )
Compile a new variable initialized to 0. And named it as '<name>'
: CONSTANT ( n -- )TIB: <name> )
Create a constant with name '<name>'.
: 2VARIABLE ( -- )TIB: <name> )
Compile a new double-precision variable initialized to 0.
And named it as '<name>'
: ARRAY: ( cell_size #cells -- )TIB: <name> -- )
Create an array with '#cells' items, each item takes 'cell_size'
bytes. This array is initialized by zeros.
Ex : create a 50 entry string buffer, each string has 10 bytes.
10 50 ARRAY: []StringBuf
: InitStrBuf
50 0 DO #I []StringBuf " abcdefg" $+ DROP LOOP ;
: DOES> ( -- ) Runtime : ( ... pfa -- ... )
Define the run-time behavior of the CREATEd name.
--------------------------------
þ FORTH VCPU Code Flow Control :
--------------------------------
CODE: EXECUTE ( ca -- )
Execute the word at ca.
CODE: @EXECUTE ( a -- )
Execute vector stored in address a.
CODE: trap ( EBP EDI ESI EDX ECX EBX EAX int#
-- EBP EDI ESI EDX ECX EBX EAX flag )
System call, a standard interface for software interrupts.
However, this word is CPU dependent .
Other VCPU branching instructions like ?BRANCH and BRANCH are generated
by the following structure control words .
---------------------------
þ Structure Control Words :
---------------------------
* The following words are all immediate words .
: IF ( )runtime : T/F -- )
Begin a conditional branch structure.
: ELSE ( )runtime : -- )
Start the false clause in an IF-ELSE-ENDIF structure.
: ENDIF ( )runtime : -- )
Terminate a conditional branch structure.
: FOR ( )runtime : n -- )
Start a FOR-NEXT loop structure in a colon definition.
: NEXT ( )runtime : -- )
Terminate a FOR-NEXT loop structure.
: AFT ( )runtime : -- )
Jump to THEN in a FOR-AFT-THEN-NEXT loop the first time through.
: THEN ( )runtime : -- )
Terminate a conditional branch structure, in fact, it is an
alias name of ENDIF, but when used in stack expression, they
are definite different.
: BEGIN ( )runtime : -- )
Start an infinite or indefinite loop structure.
: WHILE ( )runtime : T/F -- )
Conditional branch out of a BEGIN-WHILE-REPEAT loop.
: REPEAT ( )runtime : -- )
Terminate a BEGIN-WHILE-REPEAT indefinite loop.
: UNTIL ( )runtime : T/F -- )
Terminate a BEGIN-UNTIL indefinite loop structure.
: AGAIN ( )runtime : -- )
Terminate a BEGIN-AGAIN infinite loop structure.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
* CASE structure :
<n> CASE
<m1> OF ... ENDOF
<m2> OF ... ENDOF
... // no need to drop , ENDCASE will do this for you.
ENDCASE
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
: CASE ( )Runtime : n -- )
Begin CASE ... OF ... ENDOF ... ENDCASE control structure
: OF ( )Runtime : n -- )
Begin a OF ... ENDOF statement .
: ENDOF ( )
Terminate a OF ... ENDOF statement.
: ENDCASE ( )
Terminate a CASE ... ENDCASE statement.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
* Short-Cut Boolean Evaluation Control Structure :
Syntax :
1. Full boolean evaluation :
A B > C D < AND E F = AND
Short cut boolean evaluation :
A B > ANDTHEN C D < ANDTHEN E F = THEN-AND
2. Full boolean evaluation :
A B > C D < OR E F = OR
Short cut boolean evaluation :
A B > ORELSE C D < ORELSE E F = ELSE-OR
3. Mixing two structure :
Full boolean evaluation :
A B AND C AND D AND E F OR G OR AND
Short cut boolean evaluation :
A ANDTHEN B ANDTHEN C ANDTHEN D ANDTHEN
E ORELSE F ORELSE G ELSE-OR
THEN-AND
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
: ANDTHEN ( runtime : T/F -- )
A shortcut point in ANDTHEN ... ANDTHEN ... THEN-AND structure,
branch to THEN-AND when T/F is FALSE .
: THEN-AND ( runtime : -- T/F )
The terminate point in ANDTHEN ... THEN-AND structure.
Return the result of the shortcut boolean evaluation.
: ORELSE ( runtime : T/F -- )
A shortcut point in ORELSE ... ORELSE ... ELSE-OR structure,
branch to ELSE-OR when T/F is TRUE .
: ELSE-OR ( runtime : -- T/F )
The terminate point in ORELSE ... ELSE-OR structure.
Return the result of the shortcut boolean evaluation.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
* DO ... LOOP structure :
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
: #I ( -- current_loop_index )
Loop index value for either FOR ... NEXT or DO ... LOOP .
: #J ( -- inner_loop_index )
Outer loop index for nesting DO ... LOOP structure .
: #K ( -- third_loop_index )
Third outer loop index for nesting DO ... LOOP structure .
: DO ( runtime : limit start -- )
Begin of DO ... (+)LOOP structure.
: ?DO ( runtime : limit start -- )
Begin of ?DO ... (+)LOOP structure.
Skip this loop if 'start' = 'limit' .
: LOOP ( runtime : -- )
Loop back .
: +LOOP ( runtime : inc -- )
Add loop index by 'inc' and check for loop back.
: LEAVE ( runtime : -- )
Leave current loop immediately.
: ?LEAVE ( runtime : T/F -- )
If T/F flag is true, leave current loop.
: #REPEATS: ( n -- ) < my creation >
Execute the codes between '#REPEATS:' and ';' for 'n' times.
Ex1:
: TEST 10 #REPEATS: 1 2 + . ; <enter>
TEST <enter>
3 3 3 3 3 3 3 3 3 3 3 ok
Ex2:
: TEST #REPEATS: 2 + DUP . ; <enter>
10 5 TEST <enter>
12 14 16 18 20 ok
. <enter>
20 ok
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
* Conditional Compilation :
1. #IF ... #ELSE ... #ENDIF
2. #DEFINED : defined in CONTEXT ?
3. #NOTDEFINED : not defined in CONTEXT ?
4. #EXISTED : exist in any vocabulary ?
5. There is no '#DEFINE' since colon DEFINitions are defining words.
6. #UNDEFINE : Corrupt it's name to make it un-searchable. Don't use
this if possible.
Examples
Ex1 : Used in interpreting mode.
: SYMBOL1 ;
#DEFINED SYMBOL1 #DEFINED SYMBOL2 AND #IF
.( SYMBOL1 and SYMBOL2 Both exists )
#ELSE
.( Either SYMBOL1 or SYMBOL2 not defined )
#ENDIF
Ex2 : Used in compiling mode.
: Speed-Oriented-Word
[ 386? ] #IF
386-CODES
#ELSE [ 486? ] #IF
486-OPTIMIZED-CODES
#ENDIF #ENDIF ;
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
--------------------------
þ MS-DOS/BIOS Interface
--------------------------
* Three Modes for HOPEN , FOPEN
READ/ONLY = 000 (binary)
WRITE/ONLY = 001
READ/WRITE = 010
These 3 constants are consistent with MS-DOS system call $3D access
modes. If you have installed SHARE.EXE in your system, you must define
the access modes it provided youself.
* Modes for HSEEK , move file pointer
SEEK_SET = 0 : relative to begin of file .
SEEK_CUR = 1 : relative to current file pointer.
SEEK_END = 2 : relative to end of file.
: HCLOSE ( handle -- T/F )
Close a file, flush file buffer.
: HREAD ( buffer bytes handle -- bytes-read T / err-code F )
Read file at current file pointer, read 'bytes' into 'buffer'.
: HWRITE ( buffer bytes handle -- bytes-written T / err-code F )
Write a file at current file pointer, write 'bytes' of the
contents of 'buffer' .
: HSEEK ( mode offset handle -- file_pointer T / err-code F )
Move file pointer according to 'mode' and 'offset', offset can
be a positive value or negative value.
'mode' = SEEK_SET, SEEK_CUR or SEEK_END.
: OPEN ( fname-str fname-len mode -- handle True / err-code False )
Open a EXISTED file with "mode", with a FORTH string. It can be used
to detect whether a file is existed or not.
: FOPEN ( fname-str fname-len mode -- handle True / err-code False )
If file already exists, open it with 'mode' ; otherwise create
a new file .
: HERROR$ ( err-code -- str len )
Convert MS-DOS error code to a message string, you could use TYPE
to display it.
** Generally, the following three words are not necessary. **
: HCREATE ( fattr asciiz-adr -- handle True / err-code False )
MS-DOS function call $3C .
Create a file no matter this file has been existed or not.
fattr = 0 : normal , 1 : read-only, 2 : hidden, 4 : system .
: HOPEN ( mode asciiz-adr -- handle True / err-code False )
MS-DOS function call $3D .
Open a existing file with READ/ONLY , WRITE/ONLY or READ/WRITE mode.
But for file name, it MUST BE an ASCIIZ string.
: READLN ( buffer handle -- bytes-read T / err-code F )
A very slow file reading routine, read one text line into 'buffer',
one character at a time.
------------------------------------------
þ FORTH System Memory Access and Parsing :
------------------------------------------
: HERE ( -- addr )
Return the top of the code dictionary.
: PAD ( -- addr )
Return the address of the text buffer above the code dictionary.
: TIB ( -- addr )
Return the address of the current terminal input buffer.
: WORD ( c -- here )TIB: <string> )
Parse a word from input stream and copy it to code dictionary.
( put it HERE .)
: TOKEN ( -- addr )TIB : <string> )
Parse a word from input stream and copy it to name dictionary.
: "TOKEN ( b u -- addr )
Copy a string into name dictionary.
: // ( -- )
Treate the following as comment, till end of line.
: ( ( -- )
Comments all things inside two right paren ')' .
: ASCII ( compile time : -- )TIB: char )
( runtime : -- c ) Where c is the 'char' in compile time.
------------------
þ Error Handling :
------------------
: ABORT ( -- )
Reset data stack and jump to QUIT.
: ABORT" ( Runtime : T/F -- )TIB: <string>" )
Conditional abort with an error message. Abort if T/F flag is
TRUE .
: CATCH ( ca -- 0 | err# )
Execute word at ca and set up an error frame for it.
: THROW ( err# -- )CATCH: -- err# )
Reset system to current local error frame an update error flag.
-------------------------------
þ Standard Graphics Interface :
-------------------------------
: GRAPHICS-MODE ( -- )
Enter graphics mode, according to current value of 'GDefaultMode'.
It's default value is G640x480x16
Ex. G1024x768x256 to GDefaultMode
GRAPHICS-MODE
: TEXT-MODE ( -- )
Return to text mode if in graphics mode.
: VIDEO-MODE ( -- )
Execute GRAPHICS-MODE or TEXT-MODE according to GDefaultMode .
: GCurrentMode ( -- m )
Get current mode, 0 = text-mode, otherwise GWidthxHeightxColor
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
* User Controlled Values, these values must be setup before GRAPHICS-MODE
GDefaultMode
GUseDefaultFont? Generally this value is not needed for user.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
* Eight Constants for GDefaultMode
G320x200x16 G320x200x256
G640x480x16 G640x480x256
G800x600x16 G800x600x256
G1024x768x16 G1024x768x256
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
* 16 Color Constants
G_BLACK
G_BLUE
G_GREEN
G_CYAN
G_RED
G_MAGENTA
G_BROWN
G_LIGHTGRAY
G_DARKGRAY
G_LIGHTBLUE
G_LIGHTGREEN
G_LIGHTCYAN
G_LIGHTRED
G_LIGHTMAGENTA
G_YELLOW
G_WHITE
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
* Constants for GPutImage operation :
G_COPY_PUT ( must have )
G_XOR_PUT ( must have )
G_AND_PUT
G_OR_PUT
G_NOT_PUT ( optional )
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
* Basic Graphics Words :
: GraphicsMode? ( -- T/F )
Is it in graphics mode now ?
-- There are two set of drawing words, one is color parameterred . --
: GDrawCPoint ( x y color -- )
Draw a colorred point at screen coordinate (x,y).
: GDrawCLine ( x0 y0 x1 y1 color -- )