THIS FILE MARCH 2026 # BROADSWORD SYNTAX REFERENCE Kernel: BROADSWORD | Architecture: 128-bit Slab --- ## SIGILS | Sigil | Meaning | |:------|:--------| | `###` | Bulkhead — global division marker | | `#` | Literal number — never a name | | `--` | Comment — machine ignores to end of line | | `[]` | Container — a variable or step label | | `""` | Text literal — SAY only | --- ## PROGRAM STRUCTURE ``` ### DATA DIVISION declarations go here ### PROCEDURE DIVISION STEP [NAME] verbs go here DONE ### END OF LINE ``` --- ## DATA DIVISION DECLARATIONS ``` [NAME] NUMBER -- integer [NAME] NUMBER 64.64 -- Q-format fixed point (64.64) [NAME] NUMBER 96.32 -- Q-format fixed point (96.32) [NAME] NUMBER 32.96 -- Q-format fixed point (32.96) [NAME] NUMBER RANGE #0 TO #359 -- integer with bounds check [NAME] NUMBER ARRAY #8 -- array of 8 integers, 1-based [NAME] NUMBER ARRAY #1 TO #8 -- array with explicit bounds [NAME] TEXT #20 -- fixed 20-character ASCII buffer [NAME] FLAG -- ON or OFF [NAME] FIXED #13 -- compile-time constant, refuses WRITE ``` --- ## RESERVED SLABS (always available, never declared) | Name | Contents | |:----------|:---------| | CHAMBER | Accumulator — internal, not directly addressable | | TIME | Current time HH:MM:SS — loaded at program launch | | DATE | Current date DD-MM-YYYY — loaded at program launch | | TIMESTAMP | Raw unix tick — updated by TIMESTAMP verb on demand | | ERROR | Last error message | Usage: ``` SAY TIME SAY DATE ``` --- ## VERBS ### Data Movement ``` COPY [SRC] TO [DEST] -- copy value, source unchanged COPY #literal TO [DEST] -- store literal into variable MOVE [SRC] TO [DEST] -- copy value, source zeroed SWAP [A] AND [B] -- exchange values FILL [ARRAY] WITH #val -- set every element to value WRITE #val TO [DEST] -- write literal or value to variable or array element WRITE #val TO [ARRAY AT #n] -- write to array element by literal index WRITE #val TO [ARRAY AT [IDX]] -- write to array element by variable index ``` ### Arithmetic ``` SUM [A] AND [B] TO [DEST] -- addition DIFF [A] AND [B] TO [DEST] -- subtraction TIMES [A] BY [B] TO [DEST] -- multiplication DIVIDE [A] BY [B] TO [DEST] -- division (integer quotient) REST [A] BY [B] TO [DEST] -- modulo (remainder) ``` ### Bitwise ``` BITS AND [A] WITH [B] TO [DEST] BITS OR [A] WITH [B] TO [DEST] BITS XOR [A] WITH [B] TO [DEST] BITS NOT [A] TO [DEST] ``` ### Flow Control ``` SEEK [STEP] -- jump to step (tail call, no return) CALL [STEP] -- call step, return here when DONE RETURN -- return from CALL WHEN [A] EQUALS [B] SEEK [STEP] -- conditional jump WHEN [A] EQUALS [B] CALL [STEP] -- conditional call WHEN [A] OVER [B] SEEK [STEP] -- A greater than B WHEN [A] UNDER [B] SEEK [STEP] -- A less than B WHEN [A] ZERO SEEK [STEP] -- A equals zero WHEN [A] BLANK SEEK [STEP] -- TEXT variable is empty ``` ### Input / Output ``` SAY "string literal" -- print string SAY [VAR] -- print variable (NUMBER or TEXT) SAY [ARRAY AT #n] -- print array element SAY TIME -- print current time HH:MM:SS SAY DATE -- print current date DD-MM-YYYY HEAR [DEST] -- read line from terminal into TEXT variable ``` ### Time ``` TIMESTAMP TO [DEST] -- read current unix tick into variable WAIT #n -- wait n SECONDS (default unit) WAIT #n SECONDS -- wait n seconds (explicit) WAIT #n MS -- wait n milliseconds WAIT #n MINUTES -- wait n minutes WAIT #n HOURS -- wait n hours WAIT [VAR] -- wait VAR seconds ``` ### Drawing (display target decided per platform) ``` DRAW LINE [X1] [Y1] TO [X2] [Y2] DRAW CIRCLE [CX] [CY] RADIUS #r DRAW RECT [X1] [Y1] TO [X2] [Y2] DRAW ARC [CX] [CY] RADIUS #r FROM #deg TO #deg DRAW FILL [X] [Y] DRAW TEXT [MSG] AT [X] [Y] PIXEL [X] AND [Y] -- single pixel ERASE -- clear display SCROLL #lines -- scroll buffer ``` ### Random ``` RND TO [DEST] -- random number into variable ``` ### Filesystem (not yet implemented) ``` FILE OPEN [NAME] TO [HANDLE] FILE READ [HANDLE] TO [DEST] FILE WRITE [SRC] TO [HANDLE] FILE CLOSE [HANDLE] FILE DEL [NAME] FILE EXISTS [NAME] TO [DEST] DIR LIST TO [ARRAY] DIR MAKE [NAME] ``` ### Network (not yet implemented) ``` NET LISTEN #port TO [HANDLE] NET ACCEPT [HANDLE] TO [CONN] NET SEND [SRC] TO [CONN] NET RECV [CONN] TO [DEST] NET CLOSE [CONN] NET CONN [HOST] AT #port TO [HANDLE] NET POLL TO [DEST] ``` ### Control ``` STOP "reason" -- halt program, print reason STOP -- halt program silently LOG "message" -- write to log (same as SAY on x86) ``` --- ## ARRAY ACCESS ``` [ARRAY AT #1] -- element 1 (literal index) [ARRAY AT [IDX]] -- element IDX (variable index) ``` Arrays are 1-based by default. Bounds declared in DATA DIVISION. --- ## ERROR HANDLING ``` FILE OPEN [NAME] TO [HANDLE] OR STOP "FILE NOT FOUND" NET LISTEN #70 TO [HANDLE] OR SEEK [FAILED] ``` OR followed by STOP or SEEK. If the operation fails, the OR branch executes. Not yet implemented — reserved syntax. --- ## COMPLETE EXAMPLE ``` ### DATA DIVISION [COUNT] NUMBER [LIMIT] FIXED #10 [MSG] TEXT #20 ### PROCEDURE DIVISION STEP [MAIN] COPY #1 TO [COUNT] SEEK [LOOP] DONE STEP [LOOP] SAY [COUNT] SUM [COUNT] AND #1 TO [COUNT] WHEN [COUNT] OVER [LIMIT] SEEK [DONE] SEEK [LOOP] DONE STEP [DONE] SAY "FINISHED" STOP "OK" DONE ### END OF LINE ``` --- ## COMPILER ``` bsc input.bs -- compile, output named after input bsc input.bs output -- compile to named output ``` Output is a native executable binary. No dependencies. No runtime required.