From: Svjatoslav Agejenko Date: Thu, 19 Feb 2026 16:38:56 +0000 (+0200) Subject: Convert AGENTS.org to AGENTS.md: reformatted and migrated the project documentation... X-Git-Url: http://www2.svjatoslav.eu/gitweb/?a=commitdiff_plain;h=78c3e2ab4b555dc8200328a7b81df0fb43463725;p=fifth.git Convert AGENTS.org to AGENTS.md: reformatted and migrated the project documentation from `.org` to `.md`, preserving structure, conventions, and key details. --- diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..9dc5702 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,148 @@ +# Project Overview + +Fifth is a self-hosted hobby operating system built around a +Forth-inspired programming language. It runs on a custom 32-bit +stack-based virtual CPU, emulated on x86 DOS real mode. The system +integrates a kernel (compiler + interpreter), a virtual machine +emulator, device drivers, graphics libraries, a filesystem, a text +editor, and a graphics editor. + +# Key Conventions and Warnings + +1. *Do NOT edit =.html= files.* They are generated from =.org= files. + Always edit the =.org= source instead. + +2. *Files under =imageFile/f/= appear as plain text in the repo but + use FSCII encoding internally.* The files checked into git are + human-readable source representations. The actual disk image + (=disk.raw=) uses FSCII encoding. The conversion tools + (=src25th.bas=, =5th2src.bas=) handle translation. When editing + Fifth source files in =imageFile/f/=, write standard ASCII text — + the build tools handle FSCII conversion. + +3. *Two different assembly languages exist in this project:* + - =kernel/core.asm= and =kernel/define.inc= use the *virtual CPU's + own instruction set* (NOT x86). See the "Virtual CPU Instruction + Set" section below. + - =emulator/emulator.asm= and its =.inc= files are *x86 real-mode + DOS assembly* for FASM (Flat Assembler). + +4. *Binary files* (=.raw=, =.com=, =.dat=, =FNT_SYSTEM=, + =I01_MCARROW=, =core.raw=, =emulator.com=) are compiled outputs + or binary data — do not edit them directly. + +5. The project uses *spaces in directory names* (e.g., + ="floppy image/"=). Always quote paths in shell commands. + +6. *Numbers in Fifth source are hexadecimal by default*, not decimal. + For example, =FF= means 255, =400= means 1024, =3B= means 59. + The language has a =d.= word for decimal display but all literals + in source code are hex. + +# Documentation +- =doc/index.org= — Project overview, installation, architecture. +- =doc/language.org= — Complete Fifth language reference (all + commands, stack effects, examples). +- =doc/virtual machine.org= — Virtual CPU architecture. +- =doc/5TH_ET.txt= — Example Fifth source (text editor). + + +# Components — Detailed File Map + +## Kernel (Virtual CPU assembly — NOT x86) +| File | Description | +|---------------------|------------------------------------------------| +| =kernel/core.asm= | Main kernel: compiler, interpreter, core words | +| =kernel/define.inc= | Virtual CPU opcode macro definitions (FASM) | +| =kernel/font.asm= | 8×8 bitmap font data (256 characters) | +| =kernel/core.raw= | Compiled kernel binary (do not edit) | + +## Emulator (x86 real-mode FASM assembly) +| File | Description | +|-------------------------|--------------------------------------------| +| =emulator/emulator.asm= | Main emulator: instruction dispatch loop | +| =emulator/system.inc= | XMS allocation, protected mode, A20 gate | +| =emulator/vidput.inc= | Image-to-image blit (opaque) | +| =emulator/tvidput.inc= | Image-to-image blit (transparent, FF=skip) | +| =emulator/charput.inc= | Character glyph rendering to image buffer | +| =emulator/kbdrive.inc= | Keyboard interrupt handler + ring buffer | +| =emulator/compile.sh= | Build script (runs =fasm emulator.asm=) | +| =emulator/emulator.com= | Compiled DOS COM binary (do not edit) | + + +## High-Level Boot Code (Fifth language) +| File | Description | +|-----------------------------|-------------------------------------------------------------------| +| =imageFile/f/5th_boot= | Core language: compiler, strings, dynamic memory, filesystem, FAT | +| =imageFile/f/5TH_AUTORUN= | Startup script: loads drivers, shows logo, enters REPL | +| =imageFile/f/5TH_QUICKPATH= | Shortcut path definitions for navigation | + +## Applications (Fifth language) +| File | Description | +|-------------------------|--------------------------------------------| +| =imageFile/f/5th_et= | Full-screen text editor (ET command) | +| =imageFile/f/5th_eg= | Graphics editor (gedit/geditnew commands) | +| =imageFile/f/5th_logo= | Draws the Fifth logo on screen at startup | +| =imageFile/f/5th_demo= | Demo programs (graphics test, mouse test) | + +## Libraries (Fifth language, in =imageFile/f/lib/=) +| File | Description | +|--------------------|---------------------------------------------------------------| +| =5th_gfx= | Core graphics: screen buffer, palette, text output, scrolling | +| =5th_gfx2= | Extended graphics: lines, boxes, flood fill, flip | +| =5th_trig= | Trigonometry: sin/cos lookup table | +| =5TH_DRVKBD= | Keyboard driver: scan code reading, layout loading | +| =5TH_DRVMOUSE= | Mouse driver: position tracking, click regions | +| =5TH_KBD_US= | US QWERTY keyboard layout scan code → FSCII table | +| =5TH_KBD_USDVORAK= | US Dvorak keyboard layout table | +| =5TH_UICMD= | Command-line UI: =words=, =cmdline=, =fs.=, =bye= | + +## Help/Data Files +| File | Description | +|-------------------------|----------------------| +| =imageFile/f/txt_help= | General help text | +| =imageFile/f/txt_et= | Text editor help | +| =imageFile/f/txt_eg= | Graphics editor help | + +## Binary Assets (do not edit) +| File | Description | +|----------------------------|--------------------------| +| =imageFile/f/FNT_SYSTEM= | System font binary | +| =imageFile/f/I01_MCARROW= | Mouse cursor arrow image | + +# Tools (QuickBASIC / FreeBASIC) + +| File | Purpose | +|----------------------|--------------------------------------------------| +| =tools/5th2src.bas= | Convert FSCII file → readable =.src= text file | +| =tools/src25th.bas= | Convert readable =.src= text → FSCII =.5th= file | +| =tools/fsimport.bas= | Import a host file into =disk.raw= virtual disk | +| =tools/editor.bas= | Source code editor utility | +| =tools/font.dat= | Font data used by editor tool | + +## FSCII ↔ Source Conversion Details + +=5th2src.bas= converts: byte 0–9 → ASCII "0"–"9", byte 10–15 → +ASCII "A"–"F", byte 255 → space, byte 253 → tab, byte 254 → newline. +Everything else passes through as-is. + +=src25th.bas= does the reverse: tries to interpret words as hex +numbers (converting ASCII "0"–"9" → bytes 0–9, "A"–"F" → bytes +10–15), space → byte 255, tab → byte 253, newline → byte 254. + +# Building & Running + +## Compile the Emulator + + cd emulator && bash compile.sh + +Requires FASM (Flat Assembler). Produces =emulator.com= (DOS COM). + +## Run Under QEMU + + bash "floppy image/run under qemu.sh" + +## Mount/Unmount Floppy Image + + bash "floppy image/image mount.sh" + bash "floppy image/image umount.sh" diff --git a/AGENTS.org b/AGENTS.org deleted file mode 100644 index f53c41b..0000000 --- a/AGENTS.org +++ /dev/null @@ -1,450 +0,0 @@ -#+TITLE: AGENTS — Fifth Operating System Project Guide -#+AUTHOR: Guide for AI coding assistants (Aider, etc.) - -* Project Overview - -Fifth is a self-hosted hobby operating system built around a -Forth-inspired programming language. It runs on a custom 32-bit -stack-based virtual CPU, emulated on x86 DOS real mode. The system -integrates a kernel (compiler + interpreter), a virtual machine -emulator, device drivers, graphics libraries, a filesystem, a text -editor, and a graphics editor. - -* Key Conventions and Warnings - -** CRITICAL — Read Before Making Any Changes - -1. *Do NOT edit =.html= files.* They are generated from =.org= files. - Always edit the =.org= source instead. - -2. *Files under =imageFile/f/= appear as plain text in the repo but - use FSCII encoding internally.* The files checked into git are - human-readable source representations. The actual disk image - (=disk.raw=) uses FSCII encoding. The conversion tools - (=src25th.bas=, =5th2src.bas=) handle translation. When editing - Fifth source files in =imageFile/f/=, write standard ASCII text — - the build tools handle FSCII conversion. - -3. *Two different assembly languages exist in this project:* - - =kernel/core.asm= and =kernel/define.inc= use the *virtual CPU's - own instruction set* (NOT x86). See the "Virtual CPU Instruction - Set" section below. - - =emulator/emulator.asm= and its =.inc= files are *x86 real-mode - DOS assembly* for FASM (Flat Assembler). - -4. *Binary files* (=.raw=, =.com=, =.dat=, =FNT_SYSTEM=, - =I01_MCARROW=, =core.raw=, =emulator.com=) are compiled outputs - or binary data — do not edit them directly. - -5. The project uses *spaces in directory names* (e.g., - ="floppy image/"=). Always quote paths in shell commands. - -6. *Numbers in Fifth source are hexadecimal by default*, not decimal. - For example, =FF= means 255, =400= means 1024, =3B= means 59. - The language has a =d.= word for decimal display but all literals - in source code are hex. - -** Documentation -- =doc/index.org= — Project overview, installation, architecture. -- =doc/language.org= — Complete Fifth language reference (all - commands, stack effects, examples). -- =doc/virtual machine.org= — Virtual CPU architecture. -- =doc/5TH_ET.txt= — Example Fifth source (text editor). - -* FSCII Character Encoding - -Fifth uses FSCII (Fifth Standard Code for Information Interchange) -instead of ASCII. Key differences: - -| Dec | Hex | FSCII Function | -|------+-----+---------------------------------------------| -| 0–15 | 0–F | Hex digit characters (not control codes!) | -| 252 | FC | Backspace | -| 253 | FD | Tabulator (TAB) | -| 254 | FE | Carriage return (newline) | -| 255 | FF | Space | -| else | | Same as ASCII (letters, punctuation, etc.) | - -This means: ASCII space (32) is NOT space in FSCII. The character "0" -(ASCII 48) is an ordinary letter, not the number zero. Hex digits 0–F -are represented by byte values 0–15. - -* Virtual CPU Instruction Set - -The virtual CPU is stack-based with two stacks: a data stack (=edi= -register in emulator) and a return stack (=resp=). Instructions are -single-byte opcodes, some followed by a 32-bit argument. - -Opcodes defined in =kernel/define.inc= and dispatched in -=emulator/emulator.asm=: - -| Opcode | Mnemonic | Args | Stack Effect | Description | -|--------+----------+--------+---------------------------+-----------------------------------| -| 0 | xnop | | ( -- ) | No operation | -| 1 | xhalt | | | Halt / exit | -| 2 | kbd@ | | ( -- scancode ) | Read keyboard scancode | -| 3 | xnum | 32-bit | ( -- n ) | Push literal number | -| 4 | xjmp | 32-bit | | Unconditional jump | -| 5 | xcall | 32-bit | | Call subroutine (push return) | -| 6 | xinc | | ( n -- n+1 ) | Increment TOS | -| 7 | xdec | | ( n -- n-1 ) | Decrement TOS | -| 8 | xdup | | ( n -- n n ) | Duplicate TOS | -| 9 | xdrop | | ( n -- ) | Drop TOS | -| 10 | xif | 32-bit | ( flag -- ) | Jump if flag = 0 | -| 11 | xret | | | Return from subroutine | -| 12 | xc@ | | ( addr -- byte ) | Fetch byte from memory | -| 13 | xc! | | ( byte addr -- ) | Store byte to memory | -| 14 | xpush | | ( n -- ) R:( -- n ) | Move TOS to return stack | -| 15 | xpop | | ( -- n ) R:( n -- ) | Move from return stack to TOS | -| 17 | xrot | | ( a b c -- b c a ) | Rotate top 3 (note: non-standard) | -| 18 | xdisk@ | | ( sector mem -- ) | Load 1024 bytes from disk | -| 19 | xdisk! | | ( mem sector -- ) | Save 1024 bytes to disk | -| 20 | x@ | | ( addr -- n ) | Fetch 32-bit from memory | -| 21 | x! | | ( n addr -- ) | Store 32-bit to memory | -| 22 | xover | | ( a b -- a b a ) | Copy second to top | -| 23 | xswap | | ( a b -- b a ) | Swap top two | -| 24 | xplus | | ( a b -- a+b ) | Add | -| 25 | xminus | | ( a b -- a-b ) | Subtract | -| 26 | xmul | | ( a b -- a*b ) | Multiply (signed) | -| 27 | xdiv | | ( a b -- a/b ) | Divide (signed) | -| 28 | xcmpg | | ( a b -- flag ) | Greater than | -| 29 | xcmpl | | ( a b -- flag ) | Less than | -| 30 | xnot | | ( n -- ~n ) | Bitwise NOT | -| 31 | xi | | ( -- n ) | Copy return stack TOS | -| 32 | xcprt@ | | ( port -- byte ) | Read I/O port | -| 33 | xcprt! | | ( byte port -- ) | Write I/O port | -| 34 | xi2 | | ( -- n ) | Copy return stack 2nd | -| 35 | xi3 | | ( -- n ) | Copy return stack 3rd | -| 36 | xshl | | ( n count -- n<>count ) | Shift right | -| 38 | lor | | ( a b -- a OR b ) | Bitwise OR | -| 39 | lxor | | ( a b -- a XOR b ) | Bitwise XOR | -| 40 | xvidmap | | ( addr -- ) | Map image buffer to VESA video | -| 41 | xmouse@ | | ( -- btns dy dx ) | Read mouse state | -| 42 | xvidput | | ( src dst x y -- ) | Blit image to image | -| 43 | xcmove | | ( src dst count -- ) | Copy memory bytes | -| 44 | xcfill | | ( byte addr count -- ) | Fill memory with byte | -| 45 | xtvidput | | ( src dst x y -- ) | Transparent blit (FF=transparent) | -| 46 | xdep | | ( -- depth ) | Data stack depth | -| 47 | xcharput | | ( fg bg font dst x y -- ) | Render character glyph | - -* Fifth Language Quick Reference - -Fifth is Forth-like: postfix notation, stack-based, words separated by -spaces. Key syntax patterns found in the source code: - -** Defining Words -#+begin_example -: name ... ; \ Define a new word (subroutine) -:i name ... ; \ Define immediate word (runs at compile time) -var name \ Define a 32-bit variable (initialized to 0) -N vari name \ Define a variable initialized to N -N const name \ Define a constant -create name N alloc \ Allocate N bytes of data space -str content" name \ Define a string constant -Dstr content" name \ Define a dynamic string constant -#+end_example - -** Control Flow -#+begin_example -if ... then \ Conditional -if ... else ... then \ Conditional with else -N do ... loop \ Count down from N-1 to 0 (i = counter) -low high for ... loop \ Count up from low to high-1 (i = counter) -until ... loop \ Repeat until "done" is called -#+end_example - -** Stack Manipulation -#+begin_example -dup drop swap over rot 2dup 2drop nip -push pop \ Move to/from return stack -i i2 i3 \ Copy from return stack (loop counters) -#+end_example - -** Memory -#+begin_example -@ ! \ 32-bit fetch/store -c@ c! \ 8-bit fetch/store -cmove \ Block copy ( src dst count -- ) -cfill \ Block fill ( byte addr count -- ) -#+end_example - -** Comments -#+begin_example -\ single line comment (to end of line) -( comment until closing paren ) -.( visible message ) \ Print at compile time -#+end_example - -** Important Idioms in the Codebase -#+begin_example -rh name \ Remove word "name" from dictionary (hide it) - \ Used extensively to keep namespace clean -modulechk \ Load a module if not already loaded -include \ Execute code from a file -D> word \ Parse next word into default dynamic string -D" string" \ Parse string into default dynamic string -#+end_example - -* Disk Layout and Filesystem - -Constants from =5th_boot=: - -| Symbol | Hex Value | Description | -|----------+---------------------------------+--------------------------------------------------| -| fsroot | 24*400 | Root directory location (sector 24h × 1024) | -| fsfatbeg | 25 | FAT starts at sector 25h | -| fsfatsiz | 4000 | FAT size (4000h entries) | -| fsdata | fsfatbeg + fsfatsiz*4/400 + 1 | Data area start sector | - -Sector size is 1024 bytes (=400h=). FAT entry values: -- =-2= — last sector of a file chain -- =-1= — free/unused sector -- =0+= — pointer to next sector - -File directory entry (32 bytes): -| Offset | Size | Content | -|--------+------+-------------------------------------------------| -| 0 | 4 | Extension (4-byte FSCII, e.g. "list", "5th_") | -| 4 | 16 | Filename (padded with FF/spaces) | -| 20 | 4 | First block address (FAT chain start) | -| 24 | 4 | File size in bytes | - -Special extensions: ="free"= marks deleted entries, ="list"= marks -directories (subdirectories). - -* Memory Map - -| Address | Size | Description | -|----------+---------+----------------------------------------| -| 0 | ~4096 | Kernel (core.raw) | -| 1500000h | ~32000 | High-level Fifth boot code (5th_boot) | -| 200000h | varies | Core startup messages area | -| 5200000h | | End of dynamic memory space | - -Dynamic memory is managed by the =dynal=/=dynde=/=dynp=/=dyns= words -defined in =5th_boot=. Up to =100h= (256) dynamic blocks. - -* Boot Sequence (detailed) - -1. Emulator (=emulator.com=) starts, allocates XMS, sets VESA 640×480 - 8-bit mode, loads first 1024 bytes of =disk.raw= into virtual - memory at address 0. -2. Kernel (=core.asm=) executes: loads remaining kernel sectors, then - loads high-level boot code (=5th_boot=) at address =1500000h=. -3. =5th_boot= defines the compiler, interpreter, all core words - (arithmetic, stack ops, strings, dynamic memory, filesystem), - then runs =include= on =5TH_AUTORUN=. -4. =5TH_AUTORUN= loads graphics library (=5th_gfx=), displays logo - (=5th_logo=), loads keyboard driver (=5TH_DRVKBD=), loads command - line UI (=5TH_UICMD=), sets up quick paths, and enters interactive - mode. - -* Components — Detailed File Map - -** Kernel (Virtual CPU assembly — NOT x86) -| File | Description | -|---------------------+------------------------------------------------| -| =kernel/core.asm= | Main kernel: compiler, interpreter, core words | -| =kernel/define.inc= | Virtual CPU opcode macro definitions (FASM) | -| =kernel/font.asm= | 8×8 bitmap font data (256 characters) | -| =kernel/core.raw= | Compiled kernel binary (do not edit) | - -** Emulator (x86 real-mode FASM assembly) -| File | Description | -|-------------------------+--------------------------------------------| -| =emulator/emulator.asm= | Main emulator: instruction dispatch loop | -| =emulator/system.inc= | XMS allocation, protected mode, A20 gate | -| =emulator/vidput.inc= | Image-to-image blit (opaque) | -| =emulator/tvidput.inc= | Image-to-image blit (transparent, FF=skip) | -| =emulator/charput.inc= | Character glyph rendering to image buffer | -| =emulator/kbdrive.inc= | Keyboard interrupt handler + ring buffer | -| =emulator/compile.sh= | Build script (runs =fasm emulator.asm=) | -| =emulator/emulator.com= | Compiled DOS COM binary (do not edit) | - -** High-Level Boot Code (Fifth language) -| File | Description | -|-----------------------------+-------------------------------------------------------------------| -| =imageFile/f/5th_boot= | Core language: compiler, strings, dynamic memory, filesystem, FAT | -| =imageFile/f/5TH_AUTORUN= | Startup script: loads drivers, shows logo, enters REPL | -| =imageFile/f/5TH_QUICKPATH= | Shortcut path definitions for navigation | - -** Applications (Fifth language) -| File | Description | -|-------------------------+--------------------------------------------| -| =imageFile/f/5th_et= | Full-screen text editor (ET command) | -| =imageFile/f/5th_eg= | Graphics editor (gedit/geditnew commands) | -| =imageFile/f/5th_logo= | Draws the Fifth logo on screen at startup | -| =imageFile/f/5th_demo= | Demo programs (graphics test, mouse test) | - -** Libraries (Fifth language, in =imageFile/f/lib/=) -| File | Description | -|--------------------+---------------------------------------------------------------| -| =5th_gfx= | Core graphics: screen buffer, palette, text output, scrolling | -| =5th_gfx2= | Extended graphics: lines, boxes, flood fill, flip | -| =5th_trig= | Trigonometry: sin/cos lookup table | -| =5TH_DRVKBD= | Keyboard driver: scan code reading, layout loading | -| =5TH_DRVMOUSE= | Mouse driver: position tracking, click regions | -| =5TH_KBD_US= | US QWERTY keyboard layout scan code → FSCII table | -| =5TH_KBD_USDVORAK= | US Dvorak keyboard layout table | -| =5TH_UICMD= | Command-line UI: =words=, =cmdline=, =fs.=, =bye= | - -** Help/Data Files -| File | Description | -|-------------------------+----------------------| -| =imageFile/f/txt_help= | General help text | -| =imageFile/f/txt_et= | Text editor help | -| =imageFile/f/txt_eg= | Graphics editor help | - -** Binary Assets (do not edit) -| File | Description | -|----------------------------+--------------------------| -| =imageFile/f/FNT_SYSTEM= | System font binary | -| =imageFile/f/I01_MCARROW= | Mouse cursor arrow image | - -* Tools (QuickBASIC / FreeBASIC) - -| File | Purpose | -|----------------------+--------------------------------------------------| -| =tools/5th2src.bas= | Convert FSCII file → readable =.src= text file | -| =tools/src25th.bas= | Convert readable =.src= text → FSCII =.5th= file | -| =tools/fsimport.bas= | Import a host file into =disk.raw= virtual disk | -| =tools/editor.bas= | Source code editor utility | -| =tools/font.dat= | Font data used by editor tool | - -** FSCII ↔ Source Conversion Details - -=5th2src.bas= converts: byte 0–9 → ASCII "0"–"9", byte 10–15 → -ASCII "A"–"F", byte 255 → space, byte 253 → tab, byte 254 → newline. -Everything else passes through as-is. - -=src25th.bas= does the reverse: tries to interpret words as hex -numbers (converting ASCII "0"–"9" → bytes 0–9, "A"–"F" → bytes -10–15), space → byte 255, tab → byte 253, newline → byte 254. - -* Building & Running - -** Compile the Emulator -#+begin_src bash -cd emulator && bash compile.sh -#+end_src -Requires FASM (Flat Assembler). Produces =emulator.com= (DOS COM). - -** Run Under QEMU -#+begin_src bash -bash "floppy image/run under qemu.sh" -#+end_src - -** Mount/Unmount Floppy Image -#+begin_src bash -bash "floppy image/image mount.sh" -bash "floppy image/image umount.sh" -#+end_src - -* Graphics System Details - -The screen is a 640×480 (=280h= × =1E0h=) 8-bit indexed color image -buffer, allocated as a dynamic memory block. - -Image buffer format: -| Offset | Size | Content | -|--------+------+-------------------------------| -| 0 | 4 | X size (width) | -| 4 | 4 | Y size (height) | -| 8 | X*Y | Pixel data (1 byte per pixel) | - -Color is calculated with =calccol ( b g r -- c )= which maps RGB -(0–255 each) to a 6×6×6 color cube (216 colors). The palette is set -up by =setupal= in =5th_gfx=. - -Text output uses an 8×8 pixel font. Cursor position is tracked by -=curx= and =cury= variables. The =emit= word is vectored — initially -it writes to the core message area, then =5th_gfx= redirects it to -graphical text rendering via =(emit2=. - -* In-RAM commands dictionary structure - -Each dictionary entry is 24 bytes: - -| Offset | Size | Content | -|--------+------+-------------------------------------------| -| 0 | 4 | Link to previous entry (0=last, -1=empty) | -| 4 | 15 | Name string (padded) | -| 19 | 1 | Type: 0=data, 1=subroutine, 2=immediate | -| 20 | 4 | Entry data (address of code/data) | - -The dictionary is a linked list searched backwards from =lp= (last -pointer). Up to ~1000 entries fit in the 24000-byte dictionary space. - -Type behavior when referenced: -- Type 0 (data): compiles a =xnum= instruction with the address -- Type 1 (subroutine): compiles an =xcall= instruction -- Type 2 (immediate): executes immediately even during compilation - -* Keyboard System - -Scan codes from the hardware keyboard are buffered by =kbdrive.inc=. -The Fifth keyboard driver (=5TH_DRVKBD=) provides: - -- =KBD_@= — read raw scan code -- =KBD_SC2FSCII= — convert scan code to FSCII using layout table -- =KBD_F@= — read FSCII key (with shift/alt modifiers: +100h/+200h) -- =KBD_FW@= — blocking read (waits for keypress) - -Special key codes (FSK — Fifth Standard Keycodes): -| Code | Key | -|-------+-----------| -| 400h | ESC | -| 401h+ | F1, F2... | -| 410h | Up | -| 411h | Right | -| 412h | Down | -| 413h | Left | -| 414h | Insert | -| 415h | Delete | -| 416h | Home | -| 417h | End | -| 418h | Page Up | -| 419h | Page Down | -| FCh | Backspace | -| FDh | Tab | -| FEh | Enter | -| FFh | Space | - -* Common Patterns in Fifth Source Code - -** Module Loading Guard -#+begin_example -D> \listF\listLIB\5TH_GFX modulechk -#+end_example -Loads the module only if not already loaded (checks dictionary). - -** Variable Cleanup with =rh= -#+begin_example -var tmp1 var tmp2 -: myword ... ; rh tmp1 rh tmp2 -#+end_example -=rh= (remove head) hides temporary variables from the dictionary -after they're no longer needed externally. The variables still exist -in memory but can't be found by name. - -** Dynamic String Lifecycle -#+begin_example -myvar Dv \ allocate dynamic string, store handle in myvar -... \ use the string -myvar Df \ deallocate it -#+end_example - -** Vectored Execution (Deferred Words) -#+begin_example -defer cmdline \ create forward reference -... -' (cmdline ' cmdline is \ point it to actual implementation -#+end_example - -** File Operations -#+begin_example -D" \listF\myfile" fsDloadnew \ load file → new dynamic block -dup dynp \ get pointer to data -swap dynde \ deallocate when done -#+end_example