Fifth - language
+Table of Contents
+ +1. Fifth source format
++Fifth uses a different character table and codes than ASCII (still +almost similar). I call it FSCII (Fifth Standard Code for Information +Interchange) for example space character is not 32 but 255 instead. I +plan to use mainly HEX numbers, and create new characters to represent +numeric values. So typical nemric characters "0123…" is treated +like ordinary letters. +
+1.1. FSCII
+| DEC | +HEX | +function | +
|---|---|---|
| 0 - 15 | +0 - F | +HEX numbers | +
| 252 | +FC | +backspace | +
| 253 | +FD | +tabulator (TAB) | +
| 254 | +FE | +carriage return (CR) | +
| 255 | +FF | +space | +
| else | ++ | ordinary characters, same as in ASCII. | +
2. Fifth commands
+2.1. Compilation & miscellaneous
+
+init module ( – )
+ First module, control is passed to on startup. Contains
+ initialization routines. Also it is the last core module.
+ All new modules on top of it comes as result of executing
+ external source files.
+
+head <name> ( – ) compiles new dictionary entry without specifying
+ new module type.
+ ex: head myentry
+
+: <name> ( – ) creates new code module
+; ( – ) ends module (immideate)
+ ex: : hello ." hi there" ;
+
+const <name> ( n – ) defines new constant.
+ ex: 2147483647 const max
+
+:i <name> ( – ) same as ":" but this module will be executed
+ immideately even in compile mode.
+ ex: :i ( 41 scan ;
+
+create <name> ( – ) same as "head" , but specify module type as data.
+ ex: create LotoResults 5 , 13 , 52 , 12 , 11 , 3 ,
+
+allot ( n – ) allocate n bytes in dictionary.
+ ex: create MyArray 100 allot
+
+" <string>" ( – ) compile string and its size into core.
+ ex: create Mystring " This is it's contects"
+
+str <name> <string>" ( – ) just shorter way for defining strings.
+ ex: str Mystring This is it's contenc"
+
+var <name> ( – ) define new 32 bit variable.
+ ex: var result
+
+' <module> ( – n ) return memory address of given entry.
+ ex: ' init
+
+forget <name> ( – ) erases from RAM given entry and all entries what was
+ defined after it.
+ ex: forget myprog
+
+[ ( – ) set interpret mode (immideate)
+] ( n – ) set compile mode and compile top stack element
+ in as literal. Together [ …. ] cobination provides good
+ way to compute some values only once, at compile time,
+ rather than every time while program is running.
+ ex: : calculate - [ 4 MyConst1 + MyConst2 * ] ;
+
+defer <name> ( – ) creates new module, with jump instruction.
+ Later address where to jump can be modified by "is" command.
+ This provides method of foward referencing. So you can use
+ modules what not jet exist.
+is ( address1 address2 – ) address1 - where to jump, address2 -
+ address of module created by defer command.
+ ex: defer dispver
+ : run dispver ." running …" ;
+ … whatever …
+ : (dispver ." Version 9.99 " ;
+ ' (dispver ' dispver is
+
+ Now if I type "run" on the screen appears:
+ Version 9.99 running …
+
+asc <char> ( – ) reads char ascii code and treats it as literal.
+ (immideate)
+ ex: : BreakLine 30 do asc - emit loop ;
+ same as:
+ : BreakLine 30 do 45 emit loop ;
+
+dyninc ( handle – ) execute code in dynamic memory handle.
+ automatically deallocates it when done.
+
+include ( filenumber – ) execute code in specified file.
+
+words ( – ) display existing blocks in core.
+
+bye ( – ) exit from Fifth
+
+fkey ( – c )
+ Read one byte from input stream.
+
+sadd ( c addr – )
+ Add one byte "c" to string located at "addr" and updates
+ string length.
+
+scan ( c – )
+ Read input stream and store it to pad until it finds c .
+ It ignores all "c" bytes until it finds any non "c" byte.
+ in other words:
+ c is: "
+ input stream: """"This is test !"aoeu idh
+ result: This is test !
+
+ Is useful for breaking text lines into words.
+
+skey ( – c )
+ So called safe "fkey". Reads data from input stream
+ but converts characters with ASCII codes: 9 13 10
+ to spaces.
+
+str=str? ( adr1 adr2 – result )
+ Compares string at "adr1" with string at "adr2", returns
+ true flag if they are equal or false if they are not.
+ true = -1
+ false = 0
+
+find ( – addr )
+ Searches whole dictionary for word in "pad". If found,
+ returns it address, if not, returns 0.
+
+execute ( – )
+ Execute word located in "pad". Depending on "mode".
+
+dta ( addr – DataAddr )
+ Calculates address of dictionary entry data area, from
+ entry point.
+
+2num ( – num result )
+ Attempt to convert string located in "pad" into numeric
+ value. If succeed returns number and true as result.
+ If not, returns whatever and false as result.
+
+dadd ( addr length – )
+ Add to dictionary data located at "addr", with specified
+ length.
+
+lit ( n – )
+ Act with number depending on "mode". When interpreting,
+ leaves it in stack.
+
+
+incmod ( addr – )
+ Add to dictionary data located at "addr"+1 , length is taken
+ from "addr".
+
+here ( – n )
+ return "h" contents.
+
+mode var 8 bit
+ Holds input stream parser operation mode.
+ 0 = interpreting
+ 1 = compiling
+
+pad var 128 bytes
+ Holds temprorary strings.
+
+h var 32 bit
+ Pointer to free byte in memory, always at the end of the
+ dictionary. Each time when something is stored
+ by "c," command, pointer is incareased.
+
+lp var 32 bit
+ Pointer to last dictionary word. Each time when new word is
+ compiled or erased by "forget", this pointer is updated.
+
+modulechk ( Dstr<filename> – ) check if module is loaded, if not
+ immideately load it.
+
+ne ( entrydata entrytype – ) Compile new dictionary entry.
+ It's name must be in "pad".
+
2.2. Conditionals & control flow
+
+if ( flag – ) (immideate)
+ "if 1.. else 2.. then" or
+ "if 1.. then" construction. Conditional execution.
+ Performs "1.." if "flag" was true,
+ elseway performs "2.." if exist. Execution continues after
+ word "then".
+ ex: 1 if ." nonzero" else ." zero" then
+
+>= ( n1 n2 – result ) true if (n1 = n2) or (n1 > n2)
+ ex: 5 3 >= if ." first number is greater or equal" then
+
+<= ( n1 n2 – result ) true if (n1 = n2) or (n1 < n2)
+= ( n1 n2 – result ) true if n1 = n2
+
+do ( count – ) (immideate)
+ "do .. loop" construction. Performs ".." "count" times.
+ In every step "count" is decareased until it is 0.
+ ex: : test 5 do i .d loop ;
+ result: 4 3 2 1 0
+
+doexit ( – ) exit from "do .. loop"
+
+for ( count top – ) (immideate)
+ "for .. loop" construction. Performs ".." (top - count) times.
+ In every step "count" is incareased until it reaches "top" .
+ ex: : test 4 10 for i .d loop ;
+ result: 4 5 6 7 8 9
+
+forexit ( – ) exit from "for .. loop"
+
+until ( – ) (immideate)
+ "until .. loop" construction. Performs ".." until flag become
+ true. False by default. Top of return stack holds flag.
+
+done ( – ) exit from "until .. loop"
+
+
2.3. Disk & file access
+
+diskload ( FromDisk ToMem amount – )
+ Load specified abount of bytes from disk into memory.
+
+disksave ( FromMem ToDisk amount – )
+ save specified abount of bytes from memory into disk.
+
+format ( – ) Erase all files.
+
+fsDfilesize@ ( handle – size )
+ Return size of opened file.
+
+fsDcurloc@ ( handle – location )
+ Return current location in file.
+
+fsDupdated@ ( handle – updated? )
+ Return true if file was updated,
+ ie. write operations occured.
+
+fssave ( FromMem DestFileHandle amount – )
+ Save data to file.
+
+fsload ( SrcFileHandle ToMem amount – )
+ Load data from file.
+
+fseof ( handle – bytesLeft )
+ Return amount of bytes left till end of file.
+ Useful before read operation.
+
+fsls ( – ) List all files and lists (directories,folders)
+ in current path.
+
+fslsr ( – ) Same as "fsls" but recursively scans also sub lists.
+
+fscl ( DynStrHand – )
+ Change list (path)
+
+fscreate ( DynStrHand – DescPnt )
+ Create new file or list. Can create multiple lists at once.
+ ex: when creating:
+ "\listGAMES\listSTRATEGY\listSIMWORLD\5th-runme"
+ and only "\listGAMES\" already exist, then
+ "listSTRATEGY" and "listSIMWORLD" lists will be created,
+ and empty file "5th-runme" placed in there.
+
+fsDsave ( DynHand<data> DynStrHand<filename> – )
+ Create new file and save all data from dynamic memory
+ block to it.
+
+fsDload ( DynStr<SrcFileName> DynHand<DataDest> – )
+ Load whole file into dynamic memory block.
+
+fsDloadnew ( DynStr<SrcFileName> – DynHand<DataDest> )
+ Load whole file into new dynamic memory block.
+
2.4. Dynamic memory
+
+dynal ( size – handle )
+ Allocate dynamic memory block and return it's handle.
+
+dynde ( handle – )
+ Deallocate dynamic memory block.
+
+dynp ( handle – addr )
+ Returns pointer to memory where dynamic block
+ data begins.
+
+dyns ( handle – size )
+ Returns size of dynamic block.
+
+dynresize ( NewSize handle – )
+ Nondestructively resize dynamic block.
+
+dync@ ( addr handle )
+ Read one byte from dynamic block.
+
+dync! ( byte addr dynhandle )
+ Write one byte to dynamic block.
+
+dyn@ ( addr handle )
+ Read 32 bit number from dynamic block.
+ Address will spacify, whitch number, not byte.
+
+dyn! ( 32BitNum addr dynhandle )
+ Write 32 bit number to dynamic block.
+ Address will spacify, whitch number, not byte.
+
+dyncon ( size "name" – )
+ Allocate dynamic block with specified size, and
+ create constant honding its handle.
+ ex: 100 dyncon MyNewBlock
+
+dyn. ( handle – )
+ Write contenc of dynamic memory block to screen.
+
2.5. Graphics and text
+
+. ( n – ) print number on screen
+
+d. ( n – ) print number on screen in decimal
+
+? ( addr – ) print 32 bit value located at addr.
+
+." <string>" ( – ) print string into screen. Immideately
+ compiles.
+ ex: : greeting ." Hello, World" ;
+
+tab. ( – ) print tabulator
+
+calccol ( b g r – c ) calculate color what best matches given
+ Blue Green & Red values. Values must be in range 0 - 255.
+
+imgalloc ( xsize ysize – imgbuf ) allocate image buffer for
+ specified size.
+
+imgsize ( imgbuf – ) print on the screen X & Y size of image
+ buffer.
+
+point ( x y imgbuf – addr ) returns memory address for specified
+ pixel.
+
+pset ( color x y imgbuf – ) set graphic point
+
+boxf ( x1 x2 y1 y2 imgbuf color – ) draw filled box
+
+cls ( imgbuf – ) clear image buffer
+
+setpal ( b g r color – ) set palette value for specified color.
+ values bust be in size 0 - 63.
+
+putchar ( char color x y imgbuf – ) put graphic character in
+ imagebuffer to specified (x & y) location.
+
+scroll ( x y imgbuf – ) scroll in imgbuf.
+
+scrollf ( color x y screen – ) scroll and fill empty space with
+ given color.
+
+at! ( x y – ) set cursor location
+curc! ( color – ) set text color
+curb! ( solor – ) set backround color
+
+colnorm ( – ) set text color to normal
+colneg ( – ) set text color to negative (selected)
+
+dyntype ( dynhandle – ) display contenc of dynamic memory on screen
+fsdisp ( file – ) clear screen, display file, and wait for key
+
+type ( addr length – )
+ Types on the screen string, from memory at addr and
+ specified length.
+
+write ( addr – )
+ Types on the screen string, from memory at "addr"+1
+ length is taken from "addr" .
+
+screen const 32 bit
+ Holds handle of screen buffer.
+
+copyscreen ( SrcImgHandle DestImgHandle – ) copy contenc of source
+ image to destination image. Source and destination images
+ must have same size.
+
2.6. Math, memory & stack manipulation
+
+off ( n – ) writes 0 to given address, good for zeroing variable.
+ ex: MyVariable off
+on ( n – ) writes -1 (true flag) to given address.
+ ex: MyVariable on
+
+2dup ( n1 n2 – n1 n2 n1 n2 )
+2drop ( n1 n2 – )
+nip ( n1 n2 – n2 )
+neg ( n1 – -n1 ) negotiate
+bit@ ( n bit – result ) return specified bit from n.
+ ex: 38 2 bit@ (result will be 1)
+to32bit ( n1 n2 n3 n4 – n32 ) treat 4 last stack elements as bytes
+ and unite them into 32 bit dword. Most significant byte
+ on top.
+ ex: 12 76 23 11 to32bit result: 186076172
+
+to8bit ( n32 – n1 n2 n3 n4 ) break 32 bit number into 4 bytes.
+ Useful if you need to send 32 bit numbers thru 8 bit COM
+ port.
+ ex: 186076172 to8bit result: 12 76 23 11
+
+mod ( n1 n2 – reminder ) divide n1 by n2 and returns reminder.
+ ex: 12 5 mod result: 2
+
+bound ( low n high – n ) check if n is in given bounds,
+ if not then incarease/decarease it to match bounds.
+ ex: 5 80 15 bound result: 15
+ 5 10 15 bound result: 10
+ 5 -10 15 bound result: 5
+
+bound? ( low n high – result ) returns true if n is in the
+ given bounds.
+
+tab ( col – spaces) calculate amount of spaces to add
+ ta reach next tabulation from given column.
+
+count ( addr – addr+1 n )
+ Useful for returning bytes from constantly incareasing
+ address. Module "type" is nice example.
+
+c, ( n – )
+ store one byte at memory specified by "h". And incarease
+ "h" by 1.
+
+, ( n – )
+ store 32 bit number at memory specified by "h". And
+ incarease "h" by 4.
+
+cmove ( addr1 addr2 n – )
+ copy "n" amount of bytes from memory at "addr1" to memory
+ at "addr2".
+
+rnd ( limit – result )
+ generates random number in range 0 to "limit"-1.
+
+abs ( n – |n| )
+ returns absolute value of "n"
+
2.7. Dynamic & static strings
++Fifth supports both static and dynamic strings. Static strings must +have predefined space reserved, and string mustn't exceed this +length. They manipulation is faster. But they use more memory. Static +string memory address is used to refer to the string. +
+ ++Dynamic strings can have at any time length form 0 to 0FFh, They take +up only memory they currently need. They are held in dynamic memory +blocks, so dynamic block handle is used to refer to this string. +
+ ++Both types of strings are stored in the way, where first (0th) byte +holds current string length, following bytes are string itself. +
+ + +
+Dynamic:
+
+Dstral ( – handle )
+ Allocate new string.
+
+Dstrlen ( handle – length )
+ Return string length.
+
+c+Dstr ( chr handle – )
+ Add one byte to end of the string.
+
+c+lDstr ( chr handle – )
+ Add one byte to left side (beginning) of the string.
+
+Dstr. ( handle – )
+ Write contec of string into screen.
+
+Dstrsure ( size Dstr – )
+ Makes sure that at least rquested
+ "size" (amount of characters) is allocated for given
+ dynamic string.
+
+Dstr2str ( handle address – )
+ Copy dyamic string into static memory space.
+
+str2Dstr ( address handle – )
+ Copy static string into dyamic string.
+
+Dstr+str ( Dstr addr – )
+ Add contenc of dynamic string to static string.
+
+D" any string" ( – Dstr )
+ Moves specified string into dynamic string called "defDstr".
+
+D> any_string ( – Dstr )
+ Moves specified string into dynamic string called "defDstr".
+ Space marks end of string!
+
+D>2 any_string ( – Dstr )
+ Moves specified string into dynamic string called "defDstr2".
+ Space marks end of string!
+
+Dstr+Dstr ( Dstr1 Dstr2 – )
+ Adds "Dstr1" to "Dstr2" and places result into "Dstr2".
+
+Dstrclear ( Dstr – )
+ Clears contenc of dynamic string.
+
+Dstr2Dstr ( Dstr1 Dstr2 – )
+ Moves "Dstr1" to "Dstr2".
+Dstr ( data" name – )
+ Creates new dynamic string and moves specified data into it.
+ Then creates new constant with given "name" holding created
+ dynamic string handle.
+
+ ex: Dstr Hello, my name is Sven!" message \ creates it
+ message Dstr. \ tests it
+
+Dstrlscan ( char Dstr – loc )
+ Searches dynamic string for "char", from left to right,
+ returns first found "char" location in string, or 0,
+ if not found.
+
+Dstrrscan ( char Dstr – loc )
+ Searches dynamic string for "char", from right to left,
+ returns first found "char" location in string, or 0,
+ if not found.
+
+Dstrlscane ( char Dstr – loc )
+ Same as "Dstrlscan" buf returns string length+1 as location.
+ÿ
+Dstrleft ( amo Dstr – )
+ Only specified amount of characters from left remains
+ in dynamic string. ie. cut right part out.
+
+Dstrright ( amo Dstr – )
+ Only specified amount of characters from right remains
+ in dynamic string. ie. cut left part out.
+
+Dstrcutl ( amo Dstr – )
+ Cut specified amount of characters from left of dynamic
+ string out.
+
+Dstrsp ( char Dstr1 Dstr2 – )
+ Separate dynamic string in Dstr1 into two parts,
+ using "char" as separator. First part will be stored in
+ "Dstr2", second part in "Dstr1".
+ ex: asc \ \ ..separator
+ D> listF\listLIB\5TH_DRVMOUSE \ ..separate from
+ defDstr2 \ ..place result in
+ Dstrsp \ separation command
+ defDstr Dstr. \ will be: listLIB\5TH_DRVMOUSE
+ defDstr2 Dstr. \ will be: listF
+
+Dv ( addr – )
+ Allocates empty dynamic string, and places it's handle
+ into given address.
+
+Df ( addr – )
+ Reads dynamic string handle from given address and
+ deallocates (frees) it.
+
+ex: var mystring1
+ : testmodule
+ mystring1 Dv \ allocates string
+
+ <whatever>
+
+ mystring1 Df ; \ deallocates it again when no longer needed.
+