Skip to main content

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

Language Backend Status License

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 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.

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/. 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.

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.

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 lists them all. These show what DDGBasic is for:

Example Shows
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 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 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 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 A 1990s-style invoice screen on the Chinook database: a header form, a lines grid, business rules
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 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
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:

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:

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. 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 by Luis Rocha (MIT License).

Metadata

Release files for ddgbasic 1.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ddgbasic 1.0.0
File Size Uploaded Provenance Actions
ddgbasic-1.0.0.tar.gz 256.9 kB Without provenance Details for ddgbasic-1.0.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ddgbasic 1.0.0
File Interpreter ABI Platform Actions
ddgbasic-1.0.0-py3-none-any.whl Python 3 none any Details for ddgbasic-1.0.0-py3-none-any.whl

Total release size: 492.1 kB

Release files / ddgbasic-1.0.0.tar.gz

Download URL ddgbasic-1.0.0.tar.gz
Size 256.9 kB
Tags Source
SHA-256 checksum
How to use checksums
a3d7232993da8e150bceca9e7da090b8853dc5965af0df7f28aabd930683381a
BLAKE2b-256 checksum
How to use checksums
6f60630ef2e34290f82bbf9bd4cce096a5938162fb5f3d9349c2dd8db0ab9d34
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.10

Release files / ddgbasic-1.0.0-py3-none-any.whl

Download URL ddgbasic-1.0.0-py3-none-any.whl
Size 235.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
9dea2d46a89bee78a7175eb16018f4061761ba95182025ff94895b1f897adc84
BLAKE2b-256 checksum
How to use checksums
3f4edc1c9fc38499a4bd2c371922d8f186f208d6acab9a23eaf805ba0360fdc1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.10

Security for ddgbasic 1.0.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.0.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page