X-Git-Url: http://www2.svjatoslav.eu/gitweb/?p=fifth.git;a=blobdiff_plain;f=doc%2Findex.org;h=6096aba734e7f1f7199c7f4f43adaa769af8afa6;hp=79b559293f7645a1b97353658b45f9829a36ddc9;hb=HEAD;hpb=a913785891f6089f929cf5e12720d1da1269de51 diff --git a/doc/index.org b/doc/index.org index 79b5592..c370a29 100644 --- a/doc/index.org +++ b/doc/index.org @@ -1,14 +1,5 @@ #+TITLE: Fifth - virtual machine, operating system, programming language -* (document settings) :noexport: -** use dark style for TWBS-HTML exporter -#+HTML_HEAD: -#+HTML_HEAD: -#+HTML_HEAD: -#+HTML_HEAD: * General - This program is free software: released under Creative Commons Zero (CC0) license @@ -19,6 +10,7 @@ - Email: mailto://svjatoslav@svjatoslav.eu - [[https://www.svjatoslav.eu/projects/][Other software projects hosted at svjatoslav.eu]] + ** Source code - [[https://www2.svjatoslav.eu/gitweb/?p=fifth.git;a=snapshot;h=HEAD;sf=tgz][Download latest snapshot in TAR GZ format]] @@ -38,14 +30,13 @@ Currently I try to implement those new ideas in the project called System is built many years ago when I was still using DOS as a primary operating system. * Introduction -Fifth is programming lanquage & operating system, running on [[id:9b251eb9-aff6-4025-94bf-25e89e26d54a][virtual -machine]], with custom instruction set. It is much like Charles Chunk -Moore's Forth, it also uses stack architecture, and many commands are -similar. Basically I got familiar with concepts of Forth, and being -inspired created my own system. - -- [[file:5TH_ET.txt][Example Fifth source file - text editor]] -** screenshots +Fifth is a combination of: +- [[id:da7fff9b-0b67-4843-828a-52a404d7f401][Programming language]] (inspired by Forth). +- Operating system. +- [[id:9b251eb9-aff6-4025-94bf-25e89e26d54a][Virtual machine]] with custom instruction set. + +** Screenshots + [[file:screenshots/start.png]] Startup screen diplaying Fifth logo and full file list. @@ -53,8 +44,8 @@ Startup screen diplaying Fifth logo and full file list. [[file:screenshots/dictionary.png]] Sample words defined. Most of the words are commands that can be -executed interactively from command line or from file. When executed -they can be selectively compiled or interpreted. +executed interactively from the command line or from a file. When +executed, they can be selectively compiled or interpreted. [[file:screenshots/text editor.png]] @@ -63,11 +54,16 @@ Built in text editor. * Installation Just unpack all files, witout altering original directory structure, -somewhere in your hard disk. For example: C:\MISC\FIFTH\.... To run -fifth you need minimally just 2 files. emulator itself ( EMULATOR.EXE -or EMULATOR.COM ), and virtual disk file ( DISK.RAW ). +somewhere in your hard disk. For example: -Read more about [[id:0759f3e0-28bb-4901-9e4f-09ef41732173][Fifth distribution directory tree description]]. +: C:\MISC\FIFTH\ + +To run fifth you need minimally just 2 files: +- EMULATOR.COM :: Virtual CPU emulator +- DISK.RAW :: Virtual disk file + +For more information, please refer to [[id:0759f3e0-28bb-4901-9e4f-09ef41732173][Fifth distribution directory +tree description]]. * Fifth distribution directory tree description :PROPERTIES: @@ -94,30 +90,37 @@ tree similar to this: * Requirements ** Software -- MS-DOS 6.22, with HIMEM.SYS loaded. -- Mouse driver if you have a mouse. -- Does work only when CPU is in real mode. -- To recompile ASM sources I used FASM (Flat Assembler). -- I ran QBasic utilities on QB 4.5 . -- VESA support by BIOS, or external driver (UNIVBE). +- MS-DOS 6.22 with HIMEM.SYS loaded. +- Mouse driver (optional, if you have a mouse). +- CPU is initialized into [[https://en.wikipedia.org/wiki/Unreal_mode][Unreal Mode]] during operation. +- To recompile ASM sources, you can use FASM (Flat Assembler). +- To run Quick Basic utilities, use Microsoft Quick Basic 4.5. +- VESA support through BIOS or external driver (UNIVBE). + ** Hardware -- Minimum CPU 386. -- 64 KB free RAM below 640KB, -- 2 MB of free XMS. -- VESA compatible video card. -** Human -- Beginner level Forth knowledge is recommended. -- Lots of enthusiasm. +- A minimum of a i386 CPU. +- 64 KB of free RAM below 640KB. +- 2 MB of free [[https://en.wikipedia.org/wiki/Extended_memory][extended memory]]. +- A VESA-compatible video card. + * Numbers representation within Fifth +Because we are in full experimentation mode here (no regard for +compatibility whatsoever), why not to try also alternative number +representation ? + +Here alternative hexadecimal number representation format is devised: + [[file:numbers.png][file:numbers.png]] -Because I can define everything, starting from CPU, why not try also -alternative and unique number representation ? +Essentially square is split into 4 triangles. Each triangle represents +one bit. + +Fifth uses this hexadecimal format as primary throughout entire +system. + +See also: [[https://en.wikipedia.org/wiki/Bibi-binary][Bibi-binary]]. -Fifth uses its hexdecimal number representation as primary. Numbers -shape is formed by dividing a square into four parts. And manipulating -their color (black or white). * Disk file map, and it's data structures Core and high-level boot code is stored outside of the filesystem to allow easy access to it, at early booting time, when filesystem is not @@ -185,695 +188,6 @@ run through headers backwards and find needed entry. | 1500000 | ~32000 | highlevel Fifth boot code | | 200000h | | core startup messages area | | 5200000 | | end of dynamic memory space | -* Virtual machine -:PROPERTIES: -:ID: 9b251eb9-aff6-4025-94bf-25e89e26d54a -:END: -Using CPU emulator slows it down but I shouldn't now think too mutch -about, and waste my time on batteling with problems whitch results on -complex design of PC hardware. Also it allows me to use existing DOS -and resident drivers services in real mode. So I don't need to deal -with hardware too mutch. It also allows me to use all free XMS for -flat code & data storage. - -Current emulator emulates 1 CPU. It has 2 stacks, ~50 instructions, -and 4GB flat address space (theoretically). I'm not sure that DOS -6.22 that I currently prefer can handle more than 64 MB of RAM. While -I tried to keep instructionset simple, I was forced to put in lot of -complex instructions to make it's performance acceptable on -emulator. On actual silicon ~20 instructions is enaugh (I think). - -Maybe one day similar system will run directly on custom silicon chip :) - - -CPU has following registers: -| IP | instruction pointer | -| DSP | data stack pointer | -| RSP | return stack pointer | -** instruction set -*** overview table -Virtual CPU, commands (most of them are avaiable as ordinary commands -in programming language): - - -| # | name | stack footprint | description | -|----+--------------+--------------------------------------+-------------------------------------------------------------| -| 0 | nop | -- | does nothing | -| 1 | halt | -- | halt CPU ( return to DOS on emulator ) | -| 2 | [[id:820b1b90-4f4c-4ab1-b49f-9b4a52ea2528][kbd@]] | -- c | read scancode of pressed or released key | -| 3 | num | -- n | put immidiate number into datastack | -| 4 | jmp | -- | jump to specified code | -| 5 | call | | jump to specified code, save return address to return stack | -| 6 | 1+ | n -- n+1 | | -| 7 | 1- | n -- n-1 | | -| 8 | dup | n -- n n | duplicate top of data stack | -| 9 | drop | n -- | drop last element in data stack | -| 10 | if | n -- | jump to addr if top element was 0 | -| 11 | ret | | jump to code, specified in return stack. | -| 12 | c@ | addr -- n | read byte from memory at specified address | -| 13 | c! | n addr -- | store byte to specified memory | -| 14 | push | DSTK -> RSTK | move top of datastack to returnstack | -| 15 | pop | RSTK -> DSTK | move top of returnstack to datastack | -| 16 | | | | -| 17 | rot | n1 n2 n3 -- n2 n3 n1 | rotate stack elements | -| 18 | disk@ | FromDiskSect ToMem -- | read 1KB from disk into RAM | -| 19 | disk! | FromMem ToDiskSect -- | write 1KB to disk | -| 20 | @ | addr -- n | read 32 bit number from memory | -| 21 | ! | n addr -- | store 32 bit number to memory | -| 22 | over | n1 n2 -- n1 n2 n1 | | -| 23 | swap | n1 n2 -- n2 n1 | | -| 24 | + | n1 n2 -- n1+n2 | | -| 25 | - | n1 n2 -- n1-n2 | | -| 26 | * | n1 n2 -- n1*n2 | | -| 27 | / | n1 n2 -- n1/n2 | | -| 28 | > | n1 n2 -- result | is true when n1 > n2 | -| 29 | < | n1 n2 -- result | is true when n1 < n2 | -| 30 | not | n1 -- not_n1 | logical not | -| 31 | i | -- n | copies top of return stack into datastack | -| 32 | cprt@ | addr -- n | read one byte from hardware port | -| 33 | cprt! | n addr -- | store one byte to hardware port | -| 34 | i2 | -- n | like "i" but takes second top stack element | -| 35 | i3 | -- n | like "i" but takes third top stack element. | -| 36 | shl | n amount -- n | left bit shift | -| 37 | shr | n amount -- n | right bit shift | -| 38 | or | n1 n2 -- n | logical or | -| 39 | xor | n1 n2 -- n | exclusive logical or | -| 40 | vidmap | addr -- | copy memory from "addr" to video memory. | -| 41 | mouse@ | -- x y button | read mouse coordinates & buttons | -| 42 | [[id:238e8b03-57b6-424d-bfee-b6bb652cefbc][vidput]] | addr1 addr2 x y -- | put image1 into image2, at location x, y | -| 43 | [[id:79e1916f-4103-42cc-ac10-bb1ee776ed50][cmove]] | addr1 addr2 amount | move memory from addr1 to addr2 | -| 44 | cfill | c addr amount -- | fill memory starting at "addr" with "c" bytes. | -| 45 | [[id:ab45247c-44c3-464d-9e2a-337f483b4616][tvidput]] | addr1 addr2 x y -- | put image with transparency support | -| 46 | depth | -- depth | returns current depth of data stack. | -| 47 | [[id:4bb479cf-aae0-4128-9868-f016c286a162][charput]] | colorfg colorbg addrsrc addrdest x y | draw text character | - -*** kbd@ - read scancode of pressed or released key -:PROPERTIES: -:ID: 820b1b90-4f4c-4ab1-b49f-9b4a52ea2528 -:END: -Returns 0 if no data available. -*** vidput - put image1 into image2, at location x, y -:PROPERTIES: -:ID: 238e8b03-57b6-424d-bfee-b6bb652cefbc -:END: -Does clipping, so part of a big image can be mapped into smaller one. -*** cmove - copy memory array -:PROPERTIES: -:ID: 79e1916f-4103-42cc-ac10-bb1ee776ed50 -:END: -Move memory from addr1 to addr2. If addr1 is greater than addr2 then -count address foward while moving, elseway starts from end and counts -backwards, so no data loss occurs when memory regions partially -overlap. -*** tvidput - put image with transparency support -:PROPERTIES: -:ID: ab45247c-44c3-464d-9e2a-337f483b4616 -:END: -Stack footprint -: addr1 addr2 x y -- - -Put image1 into image2, at location x, y with transparency support - -Color 255 in source image is treated as transparent. -*** charput - draw text character -:PROPERTIES: -:ID: 4bb479cf-aae0-4128-9868-f016c286a162 -:END: -Draw character to image buffer located at "addrdest" to specified x & -y location. Decodes 8 bytes from source to bits, used to draw -character. - -* 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 * Dynamically loadable modules ** Keyboard driver #+BEGIN_VERSE @@ -928,24 +242,31 @@ mousedo ( -- ) Updates mouse coordinates and keys. Parse mouse click buffer, and draw mouse cursor to "screen". #+END_VERSE ** 2D graphic library -#+BEGIN_VERSE -lineh ( color len x y imgbuf -- ) draws horisontal line - from X,Y coordinates to right, with specified length. -linev ( color len x y imgbuf -- ) draws vertical line - down, from coordinates X,Y, with specified length. -box ( color x2 x1 y2 y1 imgbuf -- ) draws rectangular - box. x2 bust be >= x1, y2 must be >= y1. - x1,y1-----------+ - | | - | | - +-----------x2,y2 - -flipv ( imgbuf -- ) flip image vertically. -imgcoltrans ( ImgBuf Color ToColor -- ) Translate all pixels in - specified image with "Color" into "ToColor". -imgfill ( color x y imgbuf -- ) Fill image region starting at location - X & Y with specified color. -#+END_VERSE + ++ lineh ( color len x y imgbuf -- ) :: draws horisontal line from X,Y + coordinates to right, with specified length. + ++ linev ( color len x y imgbuf -- ) :: draws vertical line down, from + coordinates X,Y, with specified length. + ++ box ( color x2 x1 y2 y1 imgbuf -- ) :: draws rectangular box. x2 + bust be >= x1, y2 must be >= y1. + + #+begin_example + x1,y1-----------+ + | | + | | + +-----------x2,y2 + #+end_example + ++ flipv ( imgbuf -- ) :: flip image vertically. + ++ imgcoltrans ( ImgBuf Color ToColor -- ) :: Translate all pixels in + specified image with "Color" into "ToColor". + ++ imgfill ( color x y imgbuf -- ) :: Fill image region starting at + location X & Y with specified color. + ** Trigonometry functions *** sin ( a -- result ) :PROPERTIES: