Fifth - language

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".

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"

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.

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.

. ( 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.

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"

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.