Metadata-Version: 2.4
Name: ddgbasic
Version: 1.0.0
Summary: A procedural BASIC around SQLite and DuckDB: SQL in the program, loops over query results, text screens and an IDE
Author: Dan Bailey
License-Expression: MIT
Project-URL: Homepage, https://github.com/ddgflorida/DDGBasic
Project-URL: Documentation, https://github.com/ddgflorida/DDGBasic/blob/main/docs/manual/README.md
Project-URL: Examples, https://github.com/ddgflorida/DDGBasic/blob/main/examples/README.md
Project-URL: Issues, https://github.com/ddgflorida/DDGBasic/issues
Keywords: basic,sqlite,duckdb,sql,etl,interpreter
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Other
Classifier: Operating System :: OS Independent
Classifier: Environment :: Console
Classifier: Topic :: Database
Classifier: Topic :: Software Development :: Interpreters
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests
Requires-Dist: duckdb>=1.2
Requires-Dist: numpy
Requires-Dist: xlrd3
Requires-Dist: openpyxl
Requires-Dist: beautifulsoup4
Requires-Dist: lxml
Requires-Dist: xmltodict
Requires-Dist: pyarrow
Dynamic: license-file

# DDGBasic: A Data-Centric BASIC Interpreter and Procedural Language for SQLite and DuckDB

![Language](https://img.shields.io/badge/language-BASIC-blue.svg)
![Backend](https://img.shields.io/badge/backend-Python-green.svg)
![Status](https://img.shields.io/badge/status-Active-brightgreen.svg)
![License](https://img.shields.io/badge/license-MIT-lightgrey.svg)

**DDGBasic wraps a procedural language around SQLite and DuckDB.** SQL is written straight into the program, query results come back as rows you can loop over, and program variables go into queries as bind variables (`:name`). Around the SQL you get what SQL lacks: variables, `IF` rules, loops, functions, error handling, files, HTTP and a text-mode UI.

- **Load, clean and check data in one statement:** `LOAD CSV` calls your own BASIC functions on every cell (`TRANSFORM phone WITH normalize_phone$`) and drops rows that fail a check (`VALIDATE email WITH is_valid_email`).
- **Rules over query results:** `FOR row IN (SELECT ...)` loops apply logic that is awkward in SQL (tiers, allocations, alerts) and write back with bind variables, inside transactions.
- **Two engines in one program:** SQLite for records (a file, constraints, transactions), DuckDB for analytics (columnar, fast, querying Parquet and CSV files directly), with `DATABASE ENGINE` to switch.
- **Results anywhere:** the same query to the console, CSV, JSON, Excel, Parquet, HTML or SQL, or to a grouped `REPORT`.

The language is a modern BASIC, and it comes with 1990s-style text screens and a QBasic-style IDE. See [Examples](#-examples) for programs that show this off.

---

## ✨ Key Features

DDGBasic combines the simplicity of classic BASIC syntax with powerful, modern features for today's data-driven world.

* ### Dual Database Engines
    * **SQLite & DuckDB Support:** Seamlessly switch between the world's most deployed database engine (**SQLite**) for general-purpose tasks and a high-performance analytical engine (**DuckDB**) for complex queries.
    * **SQL:** Directly embed SQL statements, iterate over resultsets.
    * **Engine Switching:** Use the `DATABASE ENGINE [SQLITE|DUCKDB]` command to change the backend at any time within a script.

* ### Powerful Data Ingestion & Transformation
    * **`LOAD` Command:** Ingest data from `.csv`, fixed-width, `.json`, `.jsonl`, `.xml`, `.parquet`, `.html`, and `.xls`/`.xlsx` (**Excel**) files into database tables or for file-to-file conversion.
    * **First-class TRANSFORM and VALIDATE clauses:** Apply user-defined functions (UDFs) or built-ins per cell or per row during loading: `LOAD CSV "raw.csv" CREATE TABLE clean TRANSFORM phone WITH normalize_phone$ VALIDATE email WITH is_valid_email TRANSFORM ROW WITH derive_full_name`.
    * **OPTIONS string:** Headers, delimiters, encoding, and simple built-in transform/validate rules (upper, lower, trim, REQUIRED, MINLENGTH, REGEX).
    * **Field manipulation:** Select, rename (`fields=[Name] as N`), and exclude (`fields=*,-[Name]`) columns on the fly during data loading.

* ### User-Defined Functions
    * **`FUNCTION ... END FUNCTION`:** Define your own functions with parameters and return values.
    * **Local scope:** Parameters are local by shadow. Use `DIM` inside a function body to declare additional locals — outer same-named variables are preserved across the call.
    * **Recursion:** Functions can call themselves; recursion is safe when locals are declared via `DIM`.
    * **Early return:** `EXIT FUNCTION` returns immediately.
    * **Call as statement or expression:** `log_event("started")` discards the return; `score = lead_score(row)` uses it.

* ### Higher-Order Functions
    * **`FILTER`, `MAP`, `REDUCE`** accept either a UDF or a built-in by name: `MAP(words, UCASE$)`, `REDUCE(nums, MAX)`, `FILTER(leads, is_qualified)`.
    * **`SORT array WITH fn`:** Sort by a function-computed key — `SORT names WITH UCASE$ ASC` for case-insensitive sort, or use a UDF for composite/numeric/custom keys.
    * **Composition:** Pipelines like `REDUCE(MAP(FILTER(nums, is_even), square), add, 0)` work cleanly.

* ### 1990s-Style Text Screens
    * Blue screens, boxes and data-entry forms the way they used to be: `CLS`, `COLOR 15, 1`, `BOX`, `@ 5, 10 SAY "Name: " GET name$ PICTURE "@!" VALID name$ <> ""`, `READ`, light-bar `MENU()` and a scrolling `BROWSE (SELECT ...)` that can edit cells in place (`EDIT`). Keyboard and mouse. No extra packages. See `examples/retro_contacts.bas`, and the short `contact`, `form_demo`, `menu_demo`, `grid_demo`, `orders_demo`, `invoice_demo`, `progress_demo`, `themes_demo`, `report_demo`, `notes_demo` and `mouse_demo` examples.

* ### A QBasic-style IDE
    * `ddgbasic --ide program.bas` opens a full-screen editor with syntax colouring and a menu bar. F5 runs the program and, if it stops with an error, puts the cursor on the error's line; F1 shows the help for the keyword under the cursor, the Immediate window (F6) runs a line at a time (`? x`, a quick `SELECT`), and F9/F8 set breakpoints and step through the program, with the Immediate window seeing its variables.

* ### String Interpolation
    * Backtick-delimited strings (`` ` ``) support `${expr}` interpolation: `` `Hello, ${name$}! Total: ${FORMAT$(amount, "$#,##0.00")}` ``.
    * Full expressions allowed inside `${...}` — including UDF calls, hash lookups, arithmetic.
    * Lone `{` and `}` remain literal (so JSON, code snippets, and regex survive intact).
    * `$$` produces a literal `$`. Double-quoted strings are unaffected (no interpolation).

* ### Modern Connectivity & Tooling
    * **`FETCH` Command:** HTTP `GET`/`POST`/`PUT`/`PATCH`/`DELETE`. Send a hash as the body, attach custom request headers, upload files (multipart), capture the response into a variable or file, and optionally capture response headers as a hash.
    * **`SHELL` Command:** Execute shell commands directly from the script.
    * **Data Analysis:** `ANALYZE [CSV|JSON|JSONL|FIXED|TEXT|XML]` commands provide detailed statistical reports and schema information about local files.
    * **Format Conversion:** `LOAD` combined with `SET OUTPUT FORMAT [format]` and a `SELECT` statement converts files between formats.

* ### Rich Language & SQL Integration
    * **Full control flow:** `IF...THEN...ELSE...END IF`, `FOR...TO...NEXT`, `WHILE...WEND`, `DO...LOOP`, `FOR EACH`.
    * **Row-streaming `FOR ... IN`:** Iterate over CSV, JSON, JSONL, files, text lines, or a SQL result set — `FOR row IN (SELECT * FROM sales) ... NEXT`.
    * **`EXIT` statements:** Reliably exit any loop (`EXIT FOR`, `EXIT WHILE`, `EXIT DO`), even from within nested blocks.
    * **Direct SQL execution:** Run any SQL query directly. Supports transactions (`BEGIN`, `COMMIT`, `ROLLBACK`) and logical checks like `IF EXISTS (...)`.
    * **Embedded subqueries:** Use scalar SQL subqueries directly in assignment statements: `LET count = (SELECT COUNT(*) FROM my_table;)`.
    * **Modern data types:** `HASH` (dictionary) and dynamic `ARRAY`, with a rich library of built-in functions.

---

## 📦 Installation

DDGBasic needs Python 3.10 or newer.

```bash
pip install ddgbasic
ddgbasic examples/hello.bas          # run a script
ddgbasic                             # interactive REPL
ddgbasic --ide examples/contact.bas  # the QBasic-style IDE: F5 runs, F1 helps
```

To run from a copy of the source instead, install the dependencies with `pip install -r requirements.txt` and use `python3 src/ddgbasic.py` in place of `ddgbasic`. `pip install .` in the copy installs the `ddgbasic` command from it.

To build a standalone executable, install `requirements-build.txt` and run `./compilenuitka.sh` (macOS/Linux; installs to `~/.local/bin`) or `compilenuitka.bat` (Windows; installs to `%USERPROFILE%\bin`). Both build `src/ddgbasic.py` from any folder and take another install folder as an argument, for example `compilenuitka.bat d:\tools`. Add the install folder to your `PATH` to run `ddgbasic` from anywhere. The build bundles the DuckDB of the Python that runs it, so both scripts stop if that DuckDB is older than 1.2 (`pip install --upgrade duckdb` fixes it).

The full **Programmer's Reference Manual** is in [`docs/manual/`](https://github.com/ddgflorida/DDGBasic/blob/main/docs/manual/README.md). Run the test suite with `python3 tests/run_tests.py`.

---

## 🚀 Quick Start Example

The following DDGBasic script demonstrates several key features: it downloads a CSV file, loads it into a DuckDB in-memory table, and queries the result.

```basic
REM --- Set engine to DuckDB for high-speed analytics ---
DATABASE ENGINE DUCKDB
DATABASE OPEN ":memory:"

REM --- Download a CSV and create a table from it in one command ---
PRINT "Fetching and loading data..."
CREATE TABLE domains AS
  SELECT * FROM read_csv_auto('https://raw.githubusercontent.com/cisagov/dotgov-data/main/current-full.csv');

REM --- Run a query on the loaded data ---
PRINT "Top 5 States with the most .gov domains:"
SELECT State, COUNT(*) AS DomainCount
FROM domains
GROUP BY State
ORDER BY DomainCount DESC
LIMIT 5;

DATABASE CLOSE
END
```

---

## 🧩 ETL Pipeline Example

This shows the declarative ETL style enabled by UDFs and first-class TRANSFORM/VALIDATE clauses.

```basic
FUNCTION normalize_phone$(p$)
  DIM digits$
  digits$ = ""
  FOR i = 1 TO LEN(p$)
    c$ = MID$(p$, i, 1)
    IF ISDIGIT(c$) THEN digits$ = digits$ & c$
  NEXT
  IF LEN(digits$) = 11 AND LEFT$(digits$, 1) = "1" THEN digits$ = MID$(digits$, 2, 10)
  IF LEN(digits$) = 10 THEN
    normalize_phone$ = "(" & LEFT$(digits$,3) & ") " & MID$(digits$,4,3) & "-" & RIGHT$(digits$,4)
  ELSE
    normalize_phone$ = ""
  END IF
END FUNCTION

FUNCTION is_valid_email(addr$)
  is_valid_email = 0
  at_pos = INSTR(addr$, "@")
  IF at_pos < 2 THEN EXIT FUNCTION
  IF INSTR(MID$(addr$, at_pos+1, LEN(addr$)), ".") = 0 THEN EXIT FUNCTION
  is_valid_email = -1
END FUNCTION

DATABASE ENGINE SQLITE
DATABASE OPEN "leads.sqlite"

LOAD CSV "raw_leads.csv" CREATE TABLE leads _
  OPTIONS "header=true" _
  TRANSFORM name  WITH PROPER$ _
  TRANSFORM phone WITH normalize_phone$ _
  VALIDATE  email WITH is_valid_email

PRINT `Imported ${(SELECT COUNT(*) FROM leads;)} clean rows.`
```

---

## 🗂️ Examples

The `examples/` folder has some 60 programs; [`examples/README.md`](https://github.com/ddgflorida/DDGBasic/blob/main/examples/README.md) lists them all. These show what DDGBasic is for:

| Example | Shows |
|---|---|
| [`etl_pipeline.bas`](https://github.com/ddgflorida/DDGBasic/blob/main/examples/etl_pipeline.bas) | A messy CSV becomes a clean table: BASIC functions clean every cell as `LOAD` reads it and drop bad rows; BASIC rules flag duplicates and assign customer tiers; SQL totals; JSON, Excel and a grouped report out |
| [`duckdb_analytics.bas`](https://github.com/ddgflorida/DDGBasic/blob/main/examples/duckdb_analytics.bas) | Half a million rows in DuckDB, queried straight from Parquet and CSV files, window functions, and BASIC rules (targets per region, in a hash) over the results, with timings |
| [`two_engines.bas`](https://github.com/ddgflorida/DDGBasic/blob/main/examples/two_engines.bas) | SQLite keeps the records (constraints, a transaction), DuckDB analyses them from a Parquet file (median, best month), and the results go back to SQLite |
| [`row_logic.bas`](https://github.com/ddgflorida/DDGBasic/blob/main/examples/row_logic.bas) | Allocating limited stock to orders by priority, row by row, with all-or-nothing and partial rules, in a transaction that `ON ERROR` rolls back |
| [`invoice_demo.bas`](https://github.com/ddgflorida/DDGBasic/blob/main/examples/invoice_demo.bas) | A 1990s-style invoice screen on the Chinook database: a header form, a lines grid, business rules |
| [`retro_contacts.bas`](https://github.com/ddgflorida/DDGBasic/blob/main/examples/retro_contacts.bas) | A complete text-mode application: menu bar, editable grid, forms, memo editor, report |

Run one with `ddgbasic examples/etl_pipeline.bas`, or open it in the IDE with `ddgbasic --ide examples/etl_pipeline.bas`.

---

## 📜 Statements Reference

A summary. The [Programmer's Reference Manual](https://github.com/ddgflorida/DDGBasic/blob/main/docs/manual/README.md) has the full syntax, options and examples for every statement and function.

| Statement Keyword        | Description                                             |
|-------------------------|--------------------------------------------------------|
| @ ... SAY ... GET        | Writes text at a screen position (`SAY`) and adds an entry field (`GET`) for a variable, a hash field such as `rec.name`, or an array element, with optional `PICTURE`, `VALID ... MESSAGE`, `WHEN` and `LOOKUP (SELECT ...)` clauses, date fields (`@D`), numeric masks, `CHECKBOX` and drop-down `LIST` fields, and `HINT` help lines. See `READ`. |
| @ ... BUTTON            | Adds a `[ label ]` button to a form; pressing it ends `READ`, and `BUTTON$` returns its label (`CANCEL` buttons put the old values back). |
| ANALYZE CSV             | Provides a detailed statistical report on a CSV file, including delimiter detection, header presence, and column data types. |
| ANALYZE FIXED           | Analyzes a fixed-width text file, automatically guessing column breaks if not specified, and reports on the layout. |
| ANALYZE JSON            | Analyzes a JSON file, reporting on its structure, record count, and the consistency of object keys. |
| ANALYZE JSONL           | Analyzes a JSON Lines file, reporting on structural consistency, and counting valid and invalid JSON objects. |
| ANALYZE TEXT            | Provides a statistical analysis of a plain text file, including character, word, and line counts, encoding, and newline style. |
| ANALYZE XML             | Analyzes an XML file to determine its structure, infer the primary record tag, and list its fields. |
| BELL                    | Emits an audible system beep sound. |
| BOX                     | Draws a single- or double-line box with an optional title and `SHADOW` on the text screen. Pop-ups have drop shadows unless `SET SHADOW OFF`. |
| BROWSE                  | Shows query results in a scrolling grid; `INTO var` receives the chosen row as a hash. With `EDIT`, cells are edited in place and saved to the table, Ins adds a row and Del deletes one. Click a heading (or F3) to sort, type to jump to a row; `FREEZE`, `FORMAT` and `COLOR` set frozen columns, number masks and row colours. `DETAIL` adds a second grid for the rows of the current one (an order's lines). |
| BROWSER                 | Opens a specified URL in the system's default web browser. |
| CHAIN                   | Transfers program execution to a different DDGBasic script, optionally preserving variables. |
| CHDIR                   | Changes the current working directory. |
| CLEAR                   | Deletes all variables. User-defined functions stay defined. |
| CLOSE                   | Closes a specific file handle or all open file handles. |
| CLS                     | Clears the screen in the current colours. |
| COLOR                   | Sets the text colours (0-15) and the colours of entry fields and menu bars. |
| COPY ... AS             | Copies a source file to a destination file. |
| DATABASE                | Manages the database connection, allowing you to open a file-based database or switch the database engine (SQLite/DuckDB). |
| DESCRIBE                | Lists a table's columns and types. Use `SHOW CREATE TABLE` for the CREATE TABLE statement. |
| DIM                     | Declares a variable (scalar, ARRAY, or HASH). When used inside a FUNCTION body, the declared name is scoped to the function and the outer variable of the same name is preserved across the call. |
| DO ... LOOP             | Defines a block of code that executes repeatedly, with optional WHILE or UNTIL conditions at the beginning or end. |
| DUMP                    | A debugging command to print the internal state of the interpreter, such as tokens, variables, or labels. |
| EDIT RECORD             | A one-line entry form: one labelled field per column of a query's row, saved with UPDATE (or INSERT when there is no row). |
| EDIT TEXT               | A boxed memo editor for a multi-line string (a variable or a field such as `rec.notes`); Ctrl-W saves, Esc cancels. |
| EMAIL                   | Sends an email using the configured provider (see `HELP SET EMAIL`), with support for HTML body, CC/BCC, and attachments. |
| END                     | Terminates the program execution. |
| ERROR                   | Triggers a user-defined runtime error with a specific error code and optional message. |
| EVAL                    | Executes a DDGBasic source string as code. |
| EXECUTE                 | Executes a SQL statement that is dynamically constructed in a string variable. |
| EXIT                    | Immediately exits the current loop structure (`EXIT FOR`, `EXIT DO`, `EXIT WHILE`) or function (`EXIT FUNCTION`). |
| FETCH                   | Performs an HTTP request (GET, POST, PUT, PATCH, or DELETE). Supports request body hashes, custom request headers, multipart file uploads, INTO var$ or TO FILE destinations, and optional `HEADERS INTO h` capture of response headers. |
| FILES                   | Lists files and directories in the filesystem, similar to DIR or ls, with options for recursion and details. |
| FOR ... NEXT            | Iterates a set number of times, over the results of a SQL query, or through records in a CSV, JSON, JSONL, TEXT, or FILES list. |
| FOR EACH ... NEXT       | Iterates over each key in a HASH variable. |
| FUNCTION ... END FUNCTION | Defines a user-defined function. Parameters are local (shadow outer same-named variables). Use `DIM` inside the body for additional locals. The function returns the value of its own name. `EXIT FUNCTION` returns early. |
| GOSUB ... RETURN        | Jumps to a labeled subroutine and returns to the next statement after the GOSUB call. |
| GOTO                    | Unconditionally jumps program execution to a specified label. |
| HELP                    | Help system when running in interactive mode. |
| IF ... THEN ... ELSE ... END IF | Executes blocks of code conditionally. |
| INPUT                   | Prompts the user for input from the console and stores it in a variable. |
| KILL                    | Deletes a file from the filesystem. |
| LET                     | Assigns a value to a variable (the LET keyword is optional). |
| LINE INPUT              | Reads a single line of text from an open file into a variable. |
| LOAD                    | Loads data from a file (CSV, JSON, JSONL, XML, HTML, FIXED, EXCEL, PARQUET, TEXT) into a database table. Supports first-class `TRANSFORM col WITH fn`, `VALIDATE col WITH fn`, `TRANSFORM ROW WITH fn`, `VALIDATE ROW WITH fn` clauses. |
| LOCATE                  | Moves the cursor to a row and column. |
| MAKE FORM               | Writes a complete data-entry program for a table: menu bar, editable grid, and an entry form with fields chosen from the column types (dates, number masks, check boxes, drop-downs for foreign keys). |
| MKDIR                   | Creates a new directory. |
| NAME ... AS             | Renames a file. |
| ON ERROR GOTO           | Specifies a label to jump to when a runtime error occurs. |
| ON KEY                  | Makes a key (F1, CTRL-S, ALT-H, ...) run a FUNCTION whenever the program waits for a key, in any form, grid or menu. |
| OPEN                    | Opens a file for reading, writing, or appending, assigning it a file handle. |
| POP                     | Removes the last element from an array, optionally storing it in a variable. |
| PRINT                   | Outputs text, variables, or expressions to the console or an open file. |
| PROGRESS                | Shows a centred box with a progress bar and percentage for a long job; `PROGRESS OFF` removes it. |
| PUSH                    | Adds a new element to the end of an array. |
| READ                    | Edits the pending `@ ... GET` fields; Esc restores the original values. |
| REPORT                  | Turns a query into a report with a title, group headings, subtotals, totals and pages, to the screen, a file, `VIEW` or a string. |
| RESTSCREEN              | Puts back a screen area saved with `SAVESCREEN()`. |
| READ FILE               | Reads the entire content of a text file into a single string variable. |
| REDIM                   | Resizes a previously declared ARRAY. |
| RESUME                  | Used within an error-handling routine to resume program execution at the statement after the one that caused the error. |
| REVERSE                 | Reverses the order of elements in an array. |
| RMDIR                   | Removes an empty directory. |
| RUN                     | Executes another DDGBasic script as a subroutine and returns control to the calling script upon completion. |
| SET                     | Configures global settings for the interpreter, such as OUTPUT redirection, output FORMAT, EMAIL provider, SQL_FATAL_ERRORS, or HASH_KEYS handling. `SET THEME "classic"` sets the screen colours from a named theme. |
| SHELL                   | Executes a command in the underlying operating system shell. |
| SHIFT                   | Removes the first element from an array, optionally storing it in a variable. |
| SHOW                    | Displays database schema information, such as `SHOW TABLES` or `SHOW INDEXES`. Also `SHOW VARIABLES`. |
| SORT                    | Sorts an array in-place. Use `ON "key"` to sort an array of hashes by a key. Use `WITH fn` to sort by a function-computed key (UDF or built-in). Optional `ASC` / `DESC`. |
| SPLICE                  | Modifies an array by removing, replacing, and/or adding elements at a specific index. |
| SQL Statement           | Any line starting with a SQL keyword (e.g., SELECT, INSERT, UPDATE) is executed directly against the current database. Must end in semi-colon. |
| TROFF                   | Turns off (Trace Off) the line-by-line execution trace. |
| TRON                    | Turns on (Trace On) a line-by-line execution trace for debugging. |
| UNSHIFT                 | Adds a new element to the beginning of an array. |
| UNZIP                   | Extracts files from a zip archive into a specified directory. |
| VIEW                    | Shows a file (`VIEW FILE`), a query or a string in a read-only, scrolling box with search (`/`, `n`). |
| WHILE ... WEND          | Executes a block of code as long as a specified condition is true. |
| WRITE                   | Writes a comma-separated list of expressions to the console or a file, automatically quoting strings. |
| ZIP                     | Creates a zip archive from a list of specified files. |

---

# DDGBasic Interpreter: Functions

This document provides a quick reference to all available functions in the DDGBasic language, categorized by function type.

| Function Name            | Type        | Description |
|-------------------------|-------------|-------------|
| ABS(number)             | MATH        | Returns the absolute value of a number. |
| ALERT(message$, [button$, ...]) | SCREEN | Shows a message box with buttons and returns the chosen button number (0 for Esc). |
| ARRAY(...)              | ARRAY       | A constructor that creates and returns a new ARRAY from the provided arguments. |
| ARRAY_JOIN(array, [delimiter$]) | ARRAY  | Concatenates the elements of an array into a single string, separated by delimiter$ (default comma). |
| ARRAY_SIZE(array)       | ARRAY       | Returns the total number of elements in an array. |
| ASC(string$)            | STRING      | Returns the ASCII code of the first character in the string. |
| ATN(number)             | MATH        | Returns the arctangent of a number in radians. |
| ATAN2(y, x)             | MATH        | Returns the arctangent of y/x in radians. |
| BASENAME$(path$)        | FILE        | Returns the filename portion of a path. |
| BUTTON$                 | SCREEN      | The label of the button that ended the last `READ` ("" if none). |
| CARDINAL$(number)       | STRING      | Returns the English cardinal words for a number (e.g. 12 → "twelve", 1234 → "one thousand two hundred thirty-four"). Negative numbers prefix "negative". Decimals are spelled digit-by-digit after "point". |
| CEIL(number)            | MATH        | Rounds a number up to the nearest integer. |
| CENTER$(string$, width, [pad_char$]) | STRING | Centers a string within a field of the given width, padded with pad_char$ (default space). |
| CHR$(code)              | STRING      | Returns the character corresponding to the given ASCII code. |
| COMMAND$(index)         | INFO        | Returns the command-line argument at the specified index position. |
| CONTAINS(string$, substring$) | STRING | Returns true (-1) if string$ contains substring$, otherwise false (0). |
| COS(number)             | MATH        | Returns the cosine of an angle given in radians. |
| CURDIR$()               | FILE        | Returns the current working directory as a string. |
| DATE$()                 | DATE/TIME   | Returns the current system date as a "YYYY-MM-DD" string. |
| DATEADD(date$, days)    | DATE/TIME   | Adds a specified number of days to a date$ and returns the new date string. |
| DATEDIFF(date1$, date2$)| DATE/TIME   | Returns the number of days between two date strings. |
| DATESERIAL(year, month, day) | DATE/TIME | Returns a date string built from year, month, and day numbers. |
| DAY(date$)              | DATE/TIME   | Returns the day of the month (1-31) from a date string. |
| DAYSINMONTH(month, year) | DATE/TIME | Returns the number of days in the given month and year. (year, month) is also accepted. |
| DAYSINYEAR(year)        | DATE/TIME   | Returns 365 or 366 depending on whether the year is a leap year. |
| DEGREES(radians)        | MATH        | Converts an angle from radians to degrees. |
| DISKSPACE(path$)        | FILE        | Returns the number of free bytes on the disk containing the specified path. |
| ENDSWITH(string$, suffix$) | STRING   | Returns true (-1) if string$ ends with suffix$, otherwise false (0). |
| ENVIRON$(var_name$)     | INFO        | Returns the value of a system environment variable. |
| EOF(file_num)           | FILE        | Returns true (-1) if the end of the specified file handle has been reached, otherwise false (0). |
| EXP(number)             | MATH        | Returns e (the base of natural logarithms) raised to the power of number. |
| EXTRACT$(string$, position, [delimiter$]) | STRING | Returns the field at position (1-based) when string$ is split on delimiter$ (default comma). |
| FILE_EXISTS(path$)      | FILE        | Returns true (-1) if the specified file or directory path exists, otherwise false (0). |
| FILEATTR(path$)         | FILE        | Returns a number representing the file's attributes (e.g., read-only, directory). |
| FILESIZE(path$)         | FILE        | Returns the size of the specified file in bytes. Returns -1 if the file doesn't exist. |
| FILETIME(path$)         | FILE        | Returns the last modification timestamp of the file as a string (e.g., "YYYY-MM-DD HH:MI:SS"). |
| FILTER(array, criteria) | ARRAY/HOF   | Returns a new array of elements matching criteria. The criteria can be a substring (case-sensitive match against str(item)) OR a bare function name (UDF or built-in) called with each item. Optional third arg = 0 inverts (returns non-matches). |
| FIND(array, value)      | ARRAY       | Returns the zero-based index of the first occurrence of value in an array. Returns -1 if not found. |
| FIX(number)             | MATH        | Truncates the decimal part of a number. |
| FLOOR(number)           | MATH        | Rounds a number down to the nearest integer. |
| FORMAT$(value, mask$)   | STRING      | Formats a value according to a numeric mask (e.g. `"#,##0.00"`, `"$#,##0"`, `"0.00%"`). |
| FORMATDATE$(date$, output_mask$, [input_mask$]) | DATE/TIME | Formats a date string according to a specified mask (e.g. "YYYY-MM-DD"). Optional input_mask$ tells DDGBasic how to parse the input. |
| FREEFILE()              | FILE        | Returns the next available integer for use as a file handle. |
| HASH_COUNT(hash)        | HASH        | Returns the number of key-value pairs in a hash. |
| HASH_DELETE(hash, key$) | HASH        | Deletes a key-value pair from a hash. Use it in an expression (`r = HASH_DELETE(h, k$)`); it returns -1 if the key was deleted, 0 if it was not present. |
| HASH_EXISTS(hash, key$) | HASH        | Returns true (-1) if the key$ exists in the hash, otherwise false (0). |
| HASH_JOIN(hash1, hash2, ...) | HASH   | Merges two or more hashes into a new hash. Keys from later hashes overwrite earlier ones. |
| HASH_KEYS(hash)         | HASH        | Returns an ARRAY containing all the keys from a hash. |
| HASH_RENAME(hash, old_key$, new_key$) | HASH | Renames a key in a hash. |
| HASH_VALUES(hash)       | HASH        | Returns an ARRAY containing all the values from a hash. |
| HEX$(number)            | STRING      | Returns the hexadecimal representation of a number as a string. |
| HTMLDECODE$(string$)    | STRING      | Decodes HTML entities back to characters. |
| HTMLENCODE$(string$)    | STRING      | Encodes a string for safe inclusion in HTML. |
| INKEY$ / INKEY$(seconds) | SCREEN     | Returns the key pressed ("" if none). INKEY$(0) waits for a key. Special keys come back as names such as UP or F1. |
| INSTR([start_pos,] haystack$, needle$) | STRING | Finds the starting position of needle$ within haystack$. Returns 0 if not found. |
| INSTRREV(haystack$, needle$, [start]) | STRING | Like INSTR but searches from the end. start limits where the search ends. |
| INT(number)             | MATH        | Returns the integer portion of a number by rounding down (same as FLOOR). |
| IS_ARRAY(variable)      | ARRAY       | Returns true (-1) if the variable is an ARRAY, otherwise false (0). |
| IS_HASH(variable)       | HASH        | Returns true (-1) if the variable is a HASH, otherwise false (0). |
| ISALNUM(string$)        | STRING      | Returns true (-1) if all characters in the string are alphanumeric, otherwise false (0). |
| ISALPHA(string$)        | STRING      | Returns true (-1) if all characters in the string are alphabetic, otherwise false (0). |
| ISDATE(string$)         | DATE/TIME   | Returns true (-1) if the string parses as a date, otherwise false (0). |
| ISDIGIT(string$)        | STRING      | Returns true (-1) if all characters in the string are digits, otherwise false (0). |
| ISLEAP(year)            | DATE/TIME   | Returns true (-1) if the year is a leap year, otherwise false (0). |
| ISNUMERIC(string$)      | STRING      | Returns true (-1) if the string parses as a number, otherwise false (0). |
| JSON_SERIALIZE$(variable, [indent], [options...]) | HASH/ARRAY | Converts a DDGBasic HASH or ARRAY into a JSON formatted string. |
| LASTKEY$                | SCREEN      | The key that ended the last READ, MENU or BROWSE. |
| LCASE$(string$)         | STRING      | Converts a string to all lowercase characters. |
| LEFT$(string$, length)  | STRING      | Returns the first length characters from the left of the string. |
| LEN(value)              | STRING      | Returns the number of characters in the string representation of a value. |
| LOG(number)             | MATH        | Returns the natural logarithm of a number. |
| LTRIM$(string$)         | STRING      | Removes whitespace from the beginning (left side) of a string. |
| MAP(array, fn)          | ARRAY/HOF   | Returns a new array with each element passed through fn (a UDF or built-in name). |
| MAX(num1, num2, ...)    | MATH        | Returns the largest number from a list of arguments. |
| MENU(row, col, item$, ...) | SCREEN   | Shows a light-bar menu and returns the chosen item number (0 for Esc). |
| MENUBAR$([row,] "Title:item|...", ...) | SCREEN | Shows a menu bar with pull-down menus and returns "Title.Item" ("" for Esc). |
| MID$(string$, start_pos, [length]) | STRING | Returns a substring of a specified length starting from start_pos. |
| MIN(num1, num2, ...)    | MATH        | Returns the smallest number from a list of arguments. |
| MOD(number1, number2)   | MATH        | Returns the remainder of number1 divided by number2. |
| MONTH(date$)            | DATE/TIME   | Returns the month (1-12) from a date string. |
| MONTHCAL$(year, month)  | DATE/TIME   | Returns a calendar of the given month as a multi-line string. |
| MONTHNAME$(month_num)   | DATE/TIME   | Returns the English name of the given month (1-12). |
| MOUSECOL                | SCREEN      | The column of the last mouse click or wheel turn. |
| MOUSEROW                | SCREEN      | The row of the last mouse click or wheel turn. |
| NOW()                   | DATE/TIME   | Returns the current date and time as "YYYY-MM-DD HH:MI:SS". |
| NVL(value, default, ...) | UTILITY    | Returns the first argument that is not empty (`""` or 0). |
| OCT$(number)            | STRING      | Returns the octal representation of a number as a string. |
| ORDINAL$(number)        | STRING      | Returns the English ordinal words for a number (e.g. 1 → "first", 21 → "twenty-first", 100 → "one hundredth"). |
| PADLEFT$(text$, length, pad_char$) | STRING | Pads a string on the left to a total length using pad_char$. |
| PADRIGHT$(text$, length, pad_char$) | STRING | Pads a string on the right to a total length using pad_char$. |
| PARSEJSON(string$)      | HASH/ARRAY  | Parses a JSON string into a HASH or ARRAY. |
| PATHNAME$(path$)        | FILE        | Returns the directory portion of a path. |
| POWER(base, exponent)   | MATH        | Returns the value of base raised to the power of exponent. |
| PROPER$(string$)        | STRING      | Converts a string to title case (e.g., "hello world" becomes "Hello World"). |
| RADIANS(degrees)        | MATH        | Converts an angle from degrees to radians. |
| REDUCE(array, fn, [initial]) | ARRAY/HOF | Folds an array into a single value using fn(acc, item). If initial is omitted, the first element is used as the initial accumulator. |
| REPEAT$(string$, count) | STRING      | Returns a string consisting of string$ repeated count times. |
| REPLACE$(source$, old$, new$, [count], [ignore_case]) | STRING | Replaces occurrences of old$ with new$ in the source$ string. |
| REVERSE$(string$)       | STRING      | Reverses the order of characters in a string. |
| RIGHT$(string$, length) | STRING      | Returns the last length characters from the right of the string. |
| RND([max_val])          | MATH        | Returns a random number. If max_val is provided, returns an integer between 1 and max_val. Otherwise, returns a float between 0 and 1. |
| ROUND(number, [decimals]) | MATH      | Rounds a number to a specified number of decimals. |
| RTRIM$(string$)         | STRING      | Removes whitespace from the end (right side) of a string. |
| SAVESCREEN([top, left, bottom, right]) | SCREEN | Copies the screen or an area (with colours) into a string for `RESTSCREEN`. |
| SECOND(time$)           | DATE/TIME   | Returns the seconds component (0-59) from a time/datetime string. |
| MINUTE(time$)           | DATE/TIME   | Returns the minutes component (0-59) from a time/datetime string. |
| HOUR(time$)             | DATE/TIME   | Returns the hours component (0-23) from a time/datetime string. |
| SGN(number)             | MATH        | Returns the sign of a number (-1 for negative, 0 for zero, 1 for positive). |
| SIN(number)             | MATH        | Returns the sine of an angle given in radians. |
| SOUNDEX$(string$)       | STRING      | Returns the Soundex phonetic code of a string. |
| SPACE$(count)           | STRING      | Returns a string consisting of count spaces. |
| SPLIT(string$, delimiter$, [limit]) | ARRAY | Splits a string by a delimiter$ and returns an ARRAY of substrings. |
| SQR(number)             | MATH        | Returns the square root of a number. |
| STARTSWITH(string$, prefix$) | STRING | Returns true (-1) if string$ starts with prefix$, otherwise false (0). |
| STR$(number)            | STRING      | Converts a number to a string as `PRINT` shows it, with a leading space for zero and positive numbers. |
| STRIPHTML$(string$)     | STRING      | Removes HTML tags from a string. |
| TAN(number)             | MATH        | Returns the tangent of an angle given in radians. |
| TIME$()                 | DATE/TIME   | Returns the current system time as an "HH:MI:SS" string. |
| TIMER                   | DATE/TIME   | Seconds since midnight, with fractions of a second: take it before and after some work to time it. |
| TRIM$(string$)          | STRING      | Removes whitespace from both the beginning and end of a string. |
| TYPENAME$(value)        | UTILITY     | Returns the name of the value's type: "FLOAT", "STRING", "ARRAY" or "HASH". |
| UBOUND(array)           | ARRAY       | Returns the upper bound (the highest index) of an array. Returns -1 for an empty array. |
| UCASE$(string$)         | STRING      | Converts a string to all uppercase characters. |
| URL_FILENAME$(url$)     | STRING      | Returns the filename portion of a URL path. |
| URL_HOSTNAME$(url$)     | STRING      | Returns the hostname component of a URL. |
| URL_PATH$(url$)         | STRING      | Returns the directory portion of a URL path. |
| URL_SCHEME$(url$)       | STRING      | Returns the scheme (e.g., "http", "https") of a URL. |
| URLDECODE$(string$)     | STRING      | URL-decodes a percent-encoded string. |
| URLENCODE$(string$)     | STRING      | Percent-encodes a string for safe use in a URL. |
| VAL(string$)            | STRING/MATH | Returns the number at the start of string$ (`VAL("12abc")` is 12), or 0. |
| WEEKDAY(date$)          | DATE/TIME   | Returns the day of the week as a number (1 for Sunday, 7 for Saturday). |
| WEEKDAYNAME$(weekday_num) | DATE/TIME | Returns the English name of the given weekday (1 = Sunday ... 7 = Saturday, matching WEEKDAY). |
| YEAR(date$)             | DATE/TIME   | Returns the year from a date string. |
| YEARCAL$(year)          | DATE/TIME   | Returns a calendar of the given year as a multi-line string. |

---

**Note:** All functions return a value and can be used in expressions, assignments, or as arguments to other functions/statements.

### Function References as First-Class Arguments

`FILTER`, `MAP`, `REDUCE`, and `SORT WITH` accept a bare function name (without parentheses) as a first-class argument. The name may be a user-defined function or any of the built-ins above. Examples:

```basic
upper_names = MAP(names, UCASE$)
positives   = FILTER(values, ISNUMERIC)
total       = REDUCE(amounts, MAX)
SORT items WITH UCASE$ ASC
```

### String Interpolation in Backtick Strings

Backtick-delimited string literals support `${expr}` interpolation. Expressions may include arithmetic, built-in calls, UDF calls, and hash/array access:

```basic
PRINT `Hello, ${name$}!`
PRINT `Total: ${FORMAT$(amount, "$#,##0.00")}`
PRINT `Row ${i}: ${row("city$")} (${CARDINAL$(row("count"))})`
```

`$$` produces a literal `$`. Lone `{` and `}` are literal, so JSON, regex, and code snippets pass through intact. Regular double-quoted strings are unaffected.

---

## 📄 License

DDGBasic is released under the [MIT License](https://github.com/ddgflorida/DDGBasic/blob/main/LICENSE). The sample data in `examples/dotgov.csv` is the public list of .gov domains published by CISA, and `examples/data/chinook.sqlite` is the [Chinook sample database](https://github.com/lerocha/chinook-database) by Luis Rocha (MIT License).
