- [[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 |
| 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.
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.
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.
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.
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
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
holds current string length, following bytes are string itself.
-#+BEGIN_VERSE
+
Dynamic:
Dstral ( -- handle )
<whatever>
mystring1 Df ; \ deallocates it again when no longer needed.
-#+END_VERSE
projects / fifth.git / commitdiff