From: Svjatoslav Agejenko Date: Fri, 20 Feb 2026 17:30:33 +0000 (+0200) Subject: Document Fifth language commands. X-Git-Url: http://www2.svjatoslav.eu/gitweb/?a=commitdiff_plain;h=1437509765d493a22091cab53e360f11564adb09;p=fifth.git Document Fifth language commands. --- diff --git a/doc/language.org b/doc/language.org index d64d0f6..3a8e6a6 100644 --- a/doc/language.org +++ b/doc/language.org @@ -9,12 +9,14 @@ - [[file:5TH_ET.txt][Example Fifth source file - text editor]] * 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 | @@ -25,9 +27,10 @@ like ordinary letters. | 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. @@ -190,9 +193,9 @@ modulechk ( Dstr -- ) check if module is loaded, if not 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. @@ -229,9 +232,8 @@ until ( -- ) (immideate) 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. @@ -285,9 +287,9 @@ fsDload ( DynStr DynHand -- ) 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. @@ -325,9 +327,9 @@ dyncon ( size "name" -- ) 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 @@ -393,67 +395,119 @@ screen const 32 bit 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 +*** off ( n -- ) + +- Description :: Writes 0 to given address, good for zeroing variable. +- Example :: + : MyVariable off + +*** on ( n -- ) + +- Description :: Writes -1 (true flag) to given address. +- Example :: + : MyVariable on + + +*** 2dup ( n1 n2 -- n1 n2 n1 n2 ) +*** 2drop ( n1 n2 -- ) +*** nip ( n1 n2 -- n2 ) +*** neg ( n1 -- -n1 ) +:PROPERTIES: +:ID: a7cf0a47-40f1-49bc-afde-f6e86ac2c6d8 +:END: ++ See also: [[id:861f65e6-7ecb-43f0-9927-396855fb993f][abs ( n -- |n| )]] + +- Description :: Invert sign (negate) of a numerical value. + +*** bit@ ( n bit -- result ) + +- Description :: Return specified bit from n. +- Example :: + : 38 2 bit@ + result will be 1 + +*** to32bit ( n1 n2 n3 n4 -- n32 ) + +- Description :: Treat 4 last stack elements as bytes and unite them + into 32 bit double word. Most significant byte on top. +- Example :: + : 12 76 23 11 to32bit + result: 186076172 + +*** to8bit ( n32 -- n1 n2 n3 n4 ) + +- Description :: Break 32 bit number into 4 bytes. Useful if you need + to send 32 bit numbers though 8 bit COM port. +- Example :: + : 186076172 to8bit + result: 12 76 23 11 + +*** mod ( n1 n2 -- reminder ) + +- Description :: Divide *n1* by *n2* and returns reminder. +- Example :: + : 12 5 mod + result: 2 + +*** bound ( low n high -- n ) + +- Description :: Check if *n* is in given bounds (upper and lower + bounds are both inclusive). If *n* if outside of bounds, increase or + decrease its value accordingly to stay within bounds. +- Examples :: + : 5 80 15 bound + result: 15 + + : 5 10 15 bound + result: 10 + + : 5 -10 15 bound + result: 5 + +*** bound? ( low n high -- result ) + +- Description :: Returns true if *n* is in the given bounds. Upper and + lower bounds are both inclusive. + +*** tab ( col -- spaces ) + +- Description :: Calculate amount of spaces to add to reach next + tabulation from given column. + +*** count ( addr -- addr+1 n ) + +- Description :: Useful for returning bytes from constantly + incareasing address. Module =type= is nice example. + +*** c, ( n -- ) + +- Description :: Store one byte at memory specified by =h=. And + incarease =h= by 1. + +*** , ( n -- ) + +- Description :: Store 32 bit number at memory specified by =h=. And + incarease =h= by 4. + +*** cmove ( addr1 addr2 n -- ) + +- Description :: Copy *n* amount of bytes from memory at *addr1* to + memory at *addr2*. + +*** rnd ( limit -- result ) + +- Description :: Generates random number in range 0 to =limit= - 1. + +*** abs ( n -- |n| ) +:PROPERTIES: +:ID: 861f65e6-7ecb-43f0-9927-396855fb993f +:END: ++ See also: [[id:a7cf0a47-40f1-49bc-afde-f6e86ac2c6d8][neg ( n1 -- -n1 )]] + +- Description :: Returns absolute value of *n*. + ** Dynamic & static strings Fifth supports both static and dynamic strings. Static strings must have predefined space reserved, and string mustn't exceed this @@ -468,7 +522,7 @@ 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 ) @@ -578,4 +632,3 @@ ex: var mystring1 mystring1 Df ; \ deallocates it again when no longer needed. -#+END_VERSE