# DVX BASIC

A Visual Basic 3 clone for the DVX GUI system. Provides a visual form
designer, per-procedure code editor, project management, and a
stack-based bytecode compiler/VM for running event-driven BASIC programs.

## Architecture

DVX BASIC is built as a DXE3 app (dvxbasic.app) loaded by the DVX shell.
It consists of four major subsystems:

### Compiler (compiler/)

Single-pass compiler that translates BASIC source to stack-based p-code.

- **lexer.c** -- Tokenizer with keyword lookup, type suffixes, hex literals,
  line continuation (`_`), and `?` as PRINT shortcut.
- **parser.c** -- Recursive descent parser. Handles all VB3 statements,
  expressions, operator precedence (VB-correct: `^` binds tighter than
  unary `-`), Sub/Function with forward references, bare sub calls,
  OPTION EXPLICIT, STATIC, CONST, DEF FN, SELECT CASE, ON ERROR GOTO,
  UDTs (nested), arrays of UDTs, DECLARE LIBRARY.
- **codegen.c** -- Bytecode emitter. Dynamic arrays (stb_ds) for code,
  constants, and proc table. Module building, forward reference patching,
  unresolved reference detection.
- **symtab.c** -- Symbol table with local/global scoping, type tracking.
- **opcodes.h** -- ~90 bytecode instructions. OP_END (explicit END statement)
  vs OP_HALT (implicit end of module).

### Runtime (runtime/)

- **vm.c** -- Stack-based virtual machine. Step-limited execution for
  cooperative multitasking. Event handler dispatch via basVmCallSub
  (runs to completion, no step limit). basVmCallSubWithArgsOut for
  events that return values (QueryUnload Cancel parameter).
- **values.c** -- Tagged value system: Integer, Long, Single, Double,
  String (ref-counted), Boolean, Array (ref-counted, multi-dim), UDT
  (ref-counted, nested), Object (opaque host pointer), Ref (ByRef).

### Form Runtime (formrt/)

- **formrt.c** -- Bridge between BASIC VM and DVX widgets. Loads .frm
  files at runtime, creates windows and controls, dispatches events to
  BASIC code. Supports property get/set, method calls, and control
  creation via the widget interface system.

Events: Click, DblClick, Change, GotFocus, LostFocus, KeyPress,
KeyDown, KeyUp, MouseDown, MouseUp, MouseMove, Scroll, Load,
QueryUnload, Unload, Resize, Activate, Deactivate, Timer.

### IDE (ide/)

- **ideMain.c** -- Main IDE orchestration. File switching via
  `activateFile()`, per-procedure editing, Object/Event dropdowns
  with hash-based syntax highlighting, dirty tracking with
  `sEditorFileIdx` ownership, compile-and-run with IDE window
  hiding, VB-style event loop.
- **ideDesigner.c** -- Visual form designer. Live widget creation,
  drag/resize handles, widget interface property persistence
  (including WGT_IFACE_ENUM with named values), code-in-FRM files.
- **ideProject.c** -- Project system (.dbp files, INI format). Project
  window with tree view, project properties dialog with startup form
  dropdown and icon browser. All files loaded into memory at project
  open.
- **ideProperties.c** -- Property editor. ListView with type-aware
  editing (bool toggle, int spinner, enum cycling, string input).
  Interface property display via widget descriptors.
- **ideToolbox.c** -- Widget palette loaded from registered widget
  interfaces.

## Project Files

    project.dbp       INI-format project file
    module.bas        BASIC module (code only)
    form.frm          Form file (layout + code section after "End")

.bas modules are compiled before .frm code sections so CONST
declarations are available to form event handlers.

## Build

    make -C apps/dvxbasic          # cross-compile for DJGPP
    make -C apps/dvxbasic tests    # build native test programs

Test programs: test_compiler, test_vm, test_lex, test_quick.
162 test sections covering the compiler, VM, and language features.

## File Structure

    apps/dvxbasic/
      compiler/         Lexer, parser, codegen, symbol table, opcodes
      runtime/          VM and tagged value system
      formrt/           Form runtime (BASIC <-> DVX widget bridge)
      ide/              IDE (main, designer, project, properties, toolbox)
      samples/          Sample .bas, .frm, .dbp files
      dvxbasic.res      App resources (icons, toolbar buttons)
      Makefile           Builds basrt.lib (runtime) + dvxbasic.app (IDE)