X-Git-Url: http://www2.svjatoslav.eu/gitweb/?p=fifth.git;a=blobdiff_plain;f=doc%2Flanguage.org;fp=doc%2Flanguage.org;h=4d7a07a94a69498ee2688e6a793e9f1d47a252e8;hp=0000000000000000000000000000000000000000;hb=0df562d446afbd2094012c8e57fb4144c510c434;hpb=be12874c4742b31507e81536b80db7de4b800d24 diff --git a/doc/language.org b/doc/language.org new file mode 100644 index 0000000..4d7a07a --- /dev/null +++ b/doc/language.org @@ -0,0 +1,580 @@ +: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 ( -- ) compiles new dictionary entry without specifying + new module type. + ex: head myentry + +: ( -- ) creates new code module +; ( -- ) ends module (immideate) + ex: : hello ." hi there" ; + +const ( n -- ) defines new constant. + ex: 2147483647 const max + +:i ( -- ) same as ":" but this module will be executed + immideately even in compile mode. + ex: :i ( 41 scan ; + +create ( -- ) 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 + +" " ( -- ) compile string and its size into core. + ex: create Mystring " This is it's contects" + +str " ( -- ) just shorter way for defining strings. + ex: str Mystring This is it's contenc" + +var ( -- ) define new 32 bit variable. + ex: var result + +' ( -- n ) return memory address of given entry. + ex: ' init + +forget ( -- ) 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 ( -- ) 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 ( -- ) 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 -- ) 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 DynStrHand -- ) + Create new file and save all data from dynamic memory + block to it. + +fsDload ( DynStr DynHand -- ) + Load whole file into dynamic memory block. + +fsDloadnew ( DynStr -- DynHand ) + 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. + +." " ( -- ) 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 + + + + mystring1 Df ; \ deallocates it again when no longer needed. +#+END_VERSE