2 :ID: da7fff9b-0b67-4843-828a-52a404d7f401
5 #+TITLE: Fifth - language
6 #+AUTHOR: Svjatoslav Agejenko
9 - [[file:5TH_ET.txt][Example Fifth source file - text editor]]
12 Fifth uses a different character table and codes than ASCII (still
13 almost similar). I call it FSCII (Fifth Standard Code for Information
14 Interchange) for example space character is not 32 but 255 instead. I
15 plan to use mainly HEX numbers, and create new characters to represent
16 numeric values. So typical nemric characters "0123..." is treated
17 like ordinary letters.
20 | DEC | HEX | function |
21 |--------+-------+----------------------------------------|
22 | 0 - 15 | 0 - F | HEX numbers |
23 | 252 | FC | backspace |
24 | 253 | FD | tabulator (TAB) |
25 | 254 | FE | carriage return (CR) |
27 | else | | ordinary characters, same as in ASCII. |
29 ** Compilation & miscellaneous
32 First module, control is passed to on startup. Contains
33 initialization routines. Also it is the last core module.
34 All new modules on top of it comes as result of executing
35 external source files.
37 head <name> ( -- ) compiles new dictionary entry without specifying
41 : <name> ( -- ) creates new code module
42 ; ( -- ) ends module (immideate)
43 ex: : hello ." hi there" ;
45 const <name> ( n -- ) defines new constant.
46 ex: 2147483647 const max
48 :i <name> ( -- ) same as ":" but this module will be executed
49 immideately even in compile mode.
52 create <name> ( -- ) same as "head" , but specify module type as data.
53 ex: create LotoResults 5 , 13 , 52 , 12 , 11 , 3 ,
55 allot ( n -- ) allocate n bytes in dictionary.
56 ex: create MyArray 100 allot
58 " <string>" ( -- ) compile string and its size into core.
59 ex: create Mystring " This is it's contects"
61 str <name> <string>" ( -- ) just shorter way for defining strings.
62 ex: str Mystring This is it's contenc"
64 var <name> ( -- ) define new 32 bit variable.
67 ' <module> ( -- n ) return memory address of given entry.
70 forget <name> ( -- ) erases from RAM given entry and all entries what was
74 [ ( -- ) set interpret mode (immideate)
75 ] ( n -- ) set compile mode and compile top stack element
76 in as literal. Together [ .... ] cobination provides good
77 way to compute some values only once, at compile time,
78 rather than every time while program is running.
79 ex: : calculate - [ 4 MyConst1 + MyConst2 * ] ;
81 defer <name> ( -- ) creates new module, with jump instruction.
82 Later address where to jump can be modified by "is" command.
83 This provides method of foward referencing. So you can use
84 modules what not jet exist.
85 is ( address1 address2 -- ) address1 - where to jump, address2 -
86 address of module created by defer command.
88 : run dispver ." running ..." ;
90 : (dispver ." Version 9.99 " ;
91 ' (dispver ' dispver is
93 Now if I type "run" on the screen appears:
94 Version 9.99 running ...
96 asc <char> ( -- ) reads char ascii code and treats it as literal.
98 ex: : BreakLine 30 do asc - emit loop ;
100 : BreakLine 30 do 45 emit loop ;
102 dyninc ( handle -- ) execute code in dynamic memory handle.
103 automatically deallocates it when done.
105 include ( filenumber -- ) execute code in specified file.
107 words ( -- ) display existing blocks in core.
109 bye ( -- ) exit from Fifth
112 Read one byte from input stream.
115 Add one byte "c" to string located at "addr" and updates
119 Read input stream and store it to pad until it finds c .
120 It ignores all "c" bytes until it finds any non "c" byte.
123 input stream: """"This is test !"aoeu idh
124 result: This is test !
126 Is useful for breaking text lines into words.
129 So called safe "fkey". Reads data from input stream
130 but converts characters with ASCII codes: 9 13 10
133 str=str? ( adr1 adr2 -- result )
134 Compares string at "adr1" with string at "adr2", returns
135 true flag if they are equal or false if they are not.
140 Searches whole dictionary for word in "pad". If found,
141 returns it address, if not, returns 0.
144 Execute word located in "pad". Depending on "mode".
146 dta ( addr -- DataAddr )
147 Calculates address of dictionary entry data area, from
150 2num ( -- num result )
151 Attempt to convert string located in "pad" into numeric
152 value. If succeed returns number and true as result.
153 If not, returns whatever and false as result.
155 dadd ( addr length -- )
156 Add to dictionary data located at "addr", with specified
160 Act with number depending on "mode". When interpreting,
165 Add to dictionary data located at "addr"+1 , length is taken
172 Holds input stream parser operation mode.
177 Holds temprorary strings.
180 Pointer to free byte in memory, always at the end of the
181 dictionary. Each time when something is stored
182 by "c," command, pointer is incareased.
185 Pointer to last dictionary word. Each time when new word is
186 compiled or erased by "forget", this pointer is updated.
188 modulechk ( Dstr<filename> -- ) check if module is loaded, if not
191 ne ( entrydata entrytype -- ) Compile new dictionary entry.
192 It's name must be in "pad".
194 ** Conditionals & control flow
196 if ( flag -- ) (immideate)
197 "if 1.. else 2.. then" or
198 "if 1.. then" construction. Conditional execution.
199 Performs "1.." if "flag" was true,
200 elseway performs "2.." if exist. Execution continues after
202 ex: 1 if ." nonzero" else ." zero" then
204 >= ( n1 n2 -- result ) true if (n1 = n2) or (n1 > n2)
205 ex: 5 3 >= if ." first number is greater or equal" then
207 <= ( n1 n2 -- result ) true if (n1 = n2) or (n1 < n2)
208 = ( n1 n2 -- result ) true if n1 = n2
210 do ( count -- ) (immideate)
211 "do .. loop" construction. Performs ".." "count" times.
212 In every step "count" is decareased until it is 0.
213 ex: : test 5 do i .d loop ;
216 doexit ( -- ) exit from "do .. loop"
218 for ( count top -- ) (immideate)
219 "for .. loop" construction. Performs ".." (top - count) times.
220 In every step "count" is incareased until it reaches "top" .
221 ex: : test 4 10 for i .d loop ;
224 forexit ( -- ) exit from "for .. loop"
226 until ( -- ) (immideate)
227 "until .. loop" construction. Performs ".." until flag become
228 true. False by default. Top of return stack holds flag.
230 done ( -- ) exit from "until .. loop"
233 ** Disk & file access
235 diskload ( FromDisk ToMem amount -- )
236 Load specified abount of bytes from disk into memory.
238 disksave ( FromMem ToDisk amount -- )
239 save specified abount of bytes from memory into disk.
241 format ( -- ) Erase all files.
243 fsDfilesize@ ( handle -- size )
244 Return size of opened file.
246 fsDcurloc@ ( handle -- location )
247 Return current location in file.
249 fsDupdated@ ( handle -- updated? )
250 Return true if file was updated,
251 ie. write operations occured.
253 fssave ( FromMem DestFileHandle amount -- )
256 fsload ( SrcFileHandle ToMem amount -- )
259 fseof ( handle -- bytesLeft )
260 Return amount of bytes left till end of file.
261 Useful before read operation.
263 fsls ( -- ) List all files and lists (directories,folders)
266 fslsr ( -- ) Same as "fsls" but recursively scans also sub lists.
268 fscl ( DynStrHand -- )
271 fscreate ( DynStrHand -- DescPnt )
272 Create new file or list. Can create multiple lists at once.
274 "\listGAMES\listSTRATEGY\listSIMWORLD\5th-runme"
275 and only "\listGAMES\" already exist, then
276 "listSTRATEGY" and "listSIMWORLD" lists will be created,
277 and empty file "5th-runme" placed in there.
279 fsDsave ( DynHand<data> DynStrHand<filename> -- )
280 Create new file and save all data from dynamic memory
283 fsDload ( DynStr<SrcFileName> DynHand<DataDest> -- )
284 Load whole file into dynamic memory block.
286 fsDloadnew ( DynStr<SrcFileName> -- DynHand<DataDest> )
287 Load whole file into new dynamic memory block.
291 dynal ( size -- handle )
292 Allocate dynamic memory block and return it's handle.
295 Deallocate dynamic memory block.
297 dynp ( handle -- addr )
298 Returns pointer to memory where dynamic block
301 dyns ( handle -- size )
302 Returns size of dynamic block.
304 dynresize ( NewSize handle -- )
305 Nondestructively resize dynamic block.
307 dync@ ( addr handle )
308 Read one byte from dynamic block.
310 dync! ( byte addr dynhandle )
311 Write one byte to dynamic block.
314 Read 32 bit number from dynamic block.
315 Address will spacify, whitch number, not byte.
317 dyn! ( 32BitNum addr dynhandle )
318 Write 32 bit number to dynamic block.
319 Address will spacify, whitch number, not byte.
321 dyncon ( size "name" -- )
322 Allocate dynamic block with specified size, and
323 create constant honding its handle.
324 ex: 100 dyncon MyNewBlock
327 Write contenc of dynamic memory block to screen.
331 . ( n -- ) print number on screen
333 d. ( n -- ) print number on screen in decimal
335 ? ( addr -- ) print 32 bit value located at addr.
337 ." <string>" ( -- ) print string into screen. Immideately
339 ex: : greeting ." Hello, World" ;
341 tab. ( -- ) print tabulator
343 calccol ( b g r -- c ) calculate color what best matches given
344 Blue Green & Red values. Values must be in range 0 - 255.
346 imgalloc ( xsize ysize -- imgbuf ) allocate image buffer for
349 imgsize ( imgbuf -- ) print on the screen X & Y size of image
352 point ( x y imgbuf -- addr ) returns memory address for specified
355 pset ( color x y imgbuf -- ) set graphic point
357 boxf ( x1 x2 y1 y2 imgbuf color -- ) draw filled box
359 cls ( imgbuf -- ) clear image buffer
361 setpal ( b g r color -- ) set palette value for specified color.
362 values bust be in size 0 - 63.
364 putchar ( char color x y imgbuf -- ) put graphic character in
365 imagebuffer to specified (x & y) location.
367 scroll ( x y imgbuf -- ) scroll in imgbuf.
369 scrollf ( color x y screen -- ) scroll and fill empty space with
372 at! ( x y -- ) set cursor location
373 curc! ( color -- ) set text color
374 curb! ( solor -- ) set backround color
376 colnorm ( -- ) set text color to normal
377 colneg ( -- ) set text color to negative (selected)
379 dyntype ( dynhandle -- ) display contenc of dynamic memory on screen
380 fsdisp ( file -- ) clear screen, display file, and wait for key
382 type ( addr length -- )
383 Types on the screen string, from memory at addr and
387 Types on the screen string, from memory at "addr"+1
388 length is taken from "addr" .
391 Holds handle of screen buffer.
393 copyscreen ( SrcImgHandle DestImgHandle -- ) copy contenc of source
394 image to destination image. Source and destination images
397 ** Math, memory & stack manipulation
399 off ( n -- ) writes 0 to given address, good for zeroing variable.
401 on ( n -- ) writes -1 (true flag) to given address.
404 2dup ( n1 n2 -- n1 n2 n1 n2 )
407 neg ( n1 -- -n1 ) negotiate
408 bit@ ( n bit -- result ) return specified bit from n.
409 ex: 38 2 bit@ (result will be 1)
410 to32bit ( n1 n2 n3 n4 -- n32 ) treat 4 last stack elements as bytes
411 and unite them into 32 bit dword. Most significant byte
413 ex: 12 76 23 11 to32bit result: 186076172
415 to8bit ( n32 -- n1 n2 n3 n4 ) break 32 bit number into 4 bytes.
416 Useful if you need to send 32 bit numbers thru 8 bit COM
418 ex: 186076172 to8bit result: 12 76 23 11
420 mod ( n1 n2 -- reminder ) divide n1 by n2 and returns reminder.
421 ex: 12 5 mod result: 2
423 bound ( low n high -- n ) check if n is in given bounds,
424 if not then incarease/decarease it to match bounds.
425 ex: 5 80 15 bound result: 15
426 5 10 15 bound result: 10
427 5 -10 15 bound result: 5
429 bound? ( low n high -- result ) returns true if n is in the
432 tab ( col -- spaces) calculate amount of spaces to add
433 ta reach next tabulation from given column.
435 count ( addr -- addr+1 n )
436 Useful for returning bytes from constantly incareasing
437 address. Module "type" is nice example.
440 store one byte at memory specified by "h". And incarease
444 store 32 bit number at memory specified by "h". And
447 cmove ( addr1 addr2 n -- )
448 copy "n" amount of bytes from memory at "addr1" to memory
451 rnd ( limit -- result )
452 generates random number in range 0 to "limit"-1.
455 returns absolute value of "n"
457 ** Dynamic & static strings
458 Fifth supports both static and dynamic strings. Static strings must
459 have predefined space reserved, and string mustn't exceed this
460 length. They manipulation is faster. But they use more memory. Static
461 string memory address is used to refer to the string.
463 Dynamic strings can have at any time length form 0 to 0FFh, They take
464 up only memory they currently need. They are held in dynamic memory
465 blocks, so dynamic block handle is used to refer to this string.
467 Both types of strings are stored in the way, where first (0th) byte
468 holds current string length, following bytes are string itself.
477 Dstrlen ( handle -- length )
478 Return string length.
480 c+Dstr ( chr handle -- )
481 Add one byte to end of the string.
483 c+lDstr ( chr handle -- )
484 Add one byte to left side (beginning) of the string.
487 Write contec of string into screen.
489 Dstrsure ( size Dstr -- )
490 Makes sure that at least rquested
491 "size" (amount of characters) is allocated for given
494 Dstr2str ( handle address -- )
495 Copy dyamic string into static memory space.
497 str2Dstr ( address handle -- )
498 Copy static string into dyamic string.
500 Dstr+str ( Dstr addr -- )
501 Add contenc of dynamic string to static string.
503 D" any string" ( -- Dstr )
504 Moves specified string into dynamic string called "defDstr".
506 D> any_string ( -- Dstr )
507 Moves specified string into dynamic string called "defDstr".
508 Space marks end of string!
510 D>2 any_string ( -- Dstr )
511 Moves specified string into dynamic string called "defDstr2".
512 Space marks end of string!
514 Dstr+Dstr ( Dstr1 Dstr2 -- )
515 Adds "Dstr1" to "Dstr2" and places result into "Dstr2".
517 Dstrclear ( Dstr -- )
518 Clears contenc of dynamic string.
520 Dstr2Dstr ( Dstr1 Dstr2 -- )
521 Moves "Dstr1" to "Dstr2".
522 Dstr ( data" name -- )
523 Creates new dynamic string and moves specified data into it.
524 Then creates new constant with given "name" holding created
525 dynamic string handle.
527 ex: Dstr Hello, my name is Sven!" message \ creates it
528 message Dstr. \ tests it
530 Dstrlscan ( char Dstr -- loc )
531 Searches dynamic string for "char", from left to right,
532 returns first found "char" location in string, or 0,
535 Dstrrscan ( char Dstr -- loc )
536 Searches dynamic string for "char", from right to left,
537 returns first found "char" location in string, or 0,
540 Dstrlscane ( char Dstr -- loc )
541 Same as "Dstrlscan" buf returns string length+1 as location.
543 Dstrleft ( amo Dstr -- )
544 Only specified amount of characters from left remains
545 in dynamic string. ie. cut right part out.
547 Dstrright ( amo Dstr -- )
548 Only specified amount of characters from right remains
549 in dynamic string. ie. cut left part out.
551 Dstrcutl ( amo Dstr -- )
552 Cut specified amount of characters from left of dynamic
555 Dstrsp ( char Dstr1 Dstr2 -- )
556 Separate dynamic string in Dstr1 into two parts,
557 using "char" as separator. First part will be stored in
558 "Dstr2", second part in "Dstr1".
559 ex: asc \ \ ..separator
560 D> listF\listLIB\5TH_DRVMOUSE \ ..separate from
561 defDstr2 \ ..place result in
562 Dstrsp \ separation command
563 defDstr Dstr. \ will be: listLIB\5TH_DRVMOUSE
564 defDstr2 Dstr. \ will be: listF
567 Allocates empty dynamic string, and places it's handle
571 Reads dynamic string handle from given address and
572 deallocates (frees) it.
576 mystring1 Dv \ allocates string
580 mystring1 Df ; \ deallocates it again when no longer needed.