--- /dev/null
+:PROPERTIES:
+:ID: da7fff9b-0b67-4843-828a-52a404d7f401
+:END:
+
+#+TITLE: Fifth - language
+#+AUTHOR: Svjatoslav Agejenko
+#+LANGUAGE: en
+
+
+* 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.
+** 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. |
+* Fifth commands
+** Compilation & miscellaneous
+#+BEGIN_VERSE
+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".
+#+END_VERSE
+** Conditionals & control flow
+#+BEGIN_VERSE
+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"
+
+#+END_VERSE
+** Disk & file access
+#+BEGIN_VERSE
+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.
+#+END_VERSE
+** Dynamic memory
+#+BEGIN_VERSE
+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.
+#+END_VERSE
+** Graphics and text
+#+BEGIN_VERSE
+. ( 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.
+#+END_VERSE
+** Math, memory & stack manipulation
+#+BEGIN_VERSE
+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"
+#+END_VERSE
+** 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.
+
+
+#+BEGIN_VERSE
+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.
+#+END_VERSE
projects / fifth.git / blobdiff