Skip to content

Language Reference Manual

Jump to bottom
Andreas AFENTAKIS edited this page Dec 18, 2025 · 41 revisions

FBASIC - Language Reference Manual

FBasic syntax represents the fundamental rules of a programming language. Without these rules, it is impossible to write a functioning code. FBasic is extendable and the developer can incorporate new functions and new statements. It is a free-form language, but as it is an interpreter, the error if that exists will be raised when the execution flow reaches the mistyped command. 

Index

In this manual you can find the following chapters

  1. All the Statements

  2. Flow Control Statements

  3. Loops

  4. Statements

  5. Debugging

  6. Comments

  7. Datatypes

  8. Functions

  9. Variables - Arrays - Collections

  10. Operators

  11. Libraries and Add-Ons
    1. String functions
    2. Mathematical functions
    3. Date and Time functions 
    4. SQL Data provider (see Language Reference Collections)
    5. Events triggering
    6. Text (Placeholder) Replacer
    7. Stack Library
    8. Artificial intelligence (AI) Chat Library
    9. Events Library
    10. Json Library
    11. Streams Library
    12. Decision Tables

  12. Handlers

  13. Error Messages

All the Statements

Here is the markdown table listing the FBasic statements, their descriptions, classifications, and the libraries they belong to, sorted alphabetically by the statement name:

Statement Description Classification Library
AIPROVIDER Sets up an AI provider with the selected type and model; use * for the provider's default. AI Integration FBasicAIChat
AISESSION Initializes an AI chat session tied to a provider, using a given system prompt for context. AI Integration FBasicAIChat
AIPROMPT Sends a prompt to the session and stores the AI's response in a variable for later use. AI Integration FBasicAIChat
AISETPROVIDER Changes the provider used for an existing AI chat session. AI Integration FBasicAIChat
DTDIM Defines a Decision Table structure for rule-based logic. Rule Engine DecisionTables
DTFIND Searches a Decision Table based on key values, retrieving matched data. Rule Engine DecisionTables
DTMAPPER Alters the mapping behavior of Decision Table lookups. Rule Engine DecisionTables
DTROW Adds a row entry to an existing Decision Table. Rule Engine DecisionTables
ERROR Raises a runtime error halting program execution with a message. Event Handling Events
EVAL Runs a program code that is stored in a variable in the same execution session. System Control Core
CALL Executes a system command or script from within the FBasic program. System Control Core
CHAIN Includes a system command or script from within the FBasic program. System Control Core
FOREACH Loops through all rows in a data cursor or collection. Loop Control Collections
GOTO Jumps to a labeled statement to change flow of control unconditionally. Flow Control Core
GOSUB Jumps to a subroutine label, allowing a later RETURN to return control. Flow Control Core
IF Branches program flow based on a boolean condition, with optional ELSE clause. Flow Control Core
INPUT Pauses execution to receive input from the user via the keyboard or standard input device. I/O Core
JSON Serializes or deserializes data to and from JSON strings. Data Manipulation Json
MEMSTREAM Defines an in-memory data stream for temporary data storage. I/O Streams
PRINT Sends output data to the console or screen. I/O Core
PUSH Pushes a value onto the global stack for later retrieval. Data Structure Stack
POP Retrieves and removes the top value from the global stack. Data Structure Stack
RAISEEVENT Triggers a custom event that may have pre-defined handlers. Event Handling Events
RETURN Returns control from a GOSUB subroutine to the calling location. Flow Control Core
SCOPY Copies data streams from one source to another. I/O Streams
STACKPEEK Retrieves the current top value on the stack without removing it. Data Structure Stack
WAIT Dealy (sync and async) for a specific number of milliseconds Core
WORDAPPEND Appends a block or section to a Word document. Document Template Templating
WORDAPPENDROW Duplicates a row within a Word document template for dynamic content generation. Document Template Templating
WORDEXTRACTBODY Extracts the full text content from a Word document. Document Template Templating
WORDEXTRACTPART Extracts a section of text from a Word document specified by markers. Document Template Templating
WORDDELETEPART Removes a marked part from a Word document. Document Template Templating
WORDDELETEROW Removes a specified row from a Word document template. Document Template Templating
WORDREPALCEBODY Replaces placeholder text in the Word document body with specified content. Document Template Templating
JSON Used to serialize and deserialize instances of objects to and from string variables in JSON format. It supports specifiers including FROM, TO, DYNAMIC FROM, and DYNAMIC TO to control serialization and deserialization behavior. Data Manipulation Json
PHVSDATA Creates an array with placeholders for document templating, used for text replacement in documents. Templating TextReplacer
CURSOR Declares a SQL cursor with a data retrieval command (usually a SELECT statement). Data Access FBasicSQLDataAdapter
RETRIEVE Retrieves rows using a SQL data retrieval statement into a collection (array), supports NEW or APPEND modes. Data Access FBasicSQLDataAdapter
RESET Resets a collection cursor to the first item. Cursor Control FBasicSQLDataAdapter
FETCH Fetches the next row of a collection (used in manual fetch loops). Cursor Control FBasicSQLDataAdapter
FOREACH Loops through each row of a collection/cursor automatically fetching each in sequence. Loop Control FBasicSQLDataAdapter
ENDFOREACH Ends a FOREACH loop, triggering fetch for the next row and looping again. Loop Control FBasicSQLDataAdapter
EOD Checks if the cursor/collection has reached the end (End Of Data). Cursor Control FBasicSQLDataAdapter

Flow Control

For the flow control statements see the Language reference: Flow Control Statements manual chapter.

Loops

  • FOR … TO … NEXT
  • FOREACH ( for further info check collections paragraf )

Statement:  FOR…TO…NEXT

FOR is used to create a loop within a program with the given parameters. In each loop, the variable value is increased by 1.  When the variable value is above the TO value, the loop stops. The increase of the variable value happened on the NEXT statement. 

Note: the word STEP known from other BASICs is not supported. 

Example:

For i = 1 To 10
  let a = a + 1
  print a
Next i
assert a = 10

Statements

  • LET
  • PRINT
  • INPUT
  • RINPUT
  • WAIT

Statement LET

Used to assign the value of an expression to a variable. Syntax is: Let  varname = expression

LET D=12
LET E=12^2
LET F=12^4
LET SUM=D+E+F

Statements PRINT, INPUT

Both statements are used for input and output. They have only one argument, which is variable or literal. The input and the output handler should be installed.

Statement Reference Notes
PRINT See examples here and in statements manual page
INPUT See examples for input usage

example:

print "Enter value for a1:";
input a1
print a1

Statement RINPUT

Used to perform an input request to the RequestObjectHandler. Has 3 arguments separated by comma.
Usage: RINPUT group, name, identifier
Where Group and Name are identifiers that are passed to the RequestObjectHandler to organize the request. The Context is always "IN"
The last argument, which is variable name that will store the return of the request.
The RequestObjectHandler, handler should be installed.

example:

let s="empty!"
print s
rinput TEST, NAME, s
print s
End

Statement WAIT

Used to delay the execution for specific milliseconds. This statement has different implementation code for sync and for async executions.
Usage: WAIT variable|value

example:

WAIT 2000

Debug

  • ASSERT
  • DUMP
  • LOGINFO

Comments

  • REM
  • inline comment character:  ' [single quote]

example:

REM test code
let a=10 ' set the value 10 to variable a

Datatypes

FBASIC, as programming language, typically offers two primary data types: String and Real.

  • A String is a sequence of characters, such as letters, numbers, or symbols, enclosed in double quotes. It's used for handling text.
  • A Real (also known as a floating-point number) represents a number with a fractional component. It's used for all numerical calculations, from simple arithmetic to complex equations.

In FBASIC interpreter, other data types like Integer, Boolean, Date, and Time are not natively supported. The FBASIC simulate these by using the existing Real and String types and applying specific conventions or libraries to manage them. For instance, integers are stored as Real numbers, and logical values (true/false) can be represented by numeric value. This simplifies the language while still allowing for a wide range of programming tasks.

Especially for Date and Time datatypes check this manual at libraries chapter (Date & Time libraries). 

About the Boolean values there a need to explain further the concept. In most of the BASIC implementations, 0 is false and -1 is true.
Why this?  In most modern programming languages, the integer 0 represents false, and any non-zero integer represents true.
However, in early versions of BASIC, a different convention was adopted. This was due to the way logical operations were implemented at the machine-code level.
The bitwise operations for AND, OR, and NOT were often optimized to work with all the bits of a value.
A bitwise NOT of 00000000 (which is 0 in a byte) results in 11111111, which is -1 in two's complement representation.
This made it convenient to use -1 for true, as it was the direct result of a NOT operation on the false value (0).
In conclusion, FBASIC will consider the zero (0) numeric value as False, and any non-zero as True. If the value of True will requested the interpreter will return -1.

Functions

Built-ins functions:

Function Description
str(n) converts the numeric value n to a string value
num(s) converts the string value s to a numeric value
abs(n) the absolute value of the numeric value n
ubound("entity") Function returns the total number of elements (upper bound) for the entity array, collection or other entities.
min(n,n) the minimum number between the two numbers in the arguments
max(n,n) the maximum number between the two numbers in the arguments
not(n) If the underlying number is not equal to the value for true (1) return True, otherwise returns False (-1)

String functions:

Functions for string manipulation, available if library FBasicStringFunctions is enabled.

  • len(string): Returns the length (number of characters) of a string.
  • left(string, n): Extracts the first n characters from a string.
  • right(string, n): Extracts the last n characters from a string.
  • mid(string, start, length): Extracts a substring of a specific length from a string, starting at a given position.
  • ucase(string): Converts a string to uppercase.
  • lcase(string): Converts a string to lowercase.
  • instr(start, string1, string2): Returns the position of the first occurrence of string2 within string1, starting the search at the specified position.

Math Functions:

FBASIC,  includes a variety of built-in mathematical functions to perform common calculations. There are available if library FBasicMathFunctions is enabled.

Trigonometric Functions

  • sin(X): Returns the sine of X. The value of X must be in radians.
  • cos(X): Returns the cosine of X. The value of X must be in radians.
  • tan(X): Returns the tangent of X. The value of X must be in radians.
  • atn(X): Returns the arctangent of X. The result is in radians.

Logarithmic and Exponential, Powers Functions

  • log(X): Returns the natural logarithm (base e) of X.
  • exp(X): Returns the value of e raised to the power of X. This is the inverse of the LOG function.
  • sqr(X): Square Root. Returns the square root of X. The value of X must be non-negative.

Value Functions

  • abs(X): Returns the absolute value of X. This function is useful for ensuring a number is non-negative. Note that abs() functions is available without the math library.
  • sgn(X): Returns the sign of X. It returns 1 if X>0, -1 if X<0, and 0 if X=0.
  • rnd(): This function is used to generate a random number. Its behavior can vary between different versions of BASIC. Often, RND without an argument generates a random number between 0 and 1.
  • mod(X, Y): Returns the remainder of X divided by Y. This is useful for various calculations, including determining even or odd numbers.

Integer and Rounding Functions

  • int(X): Returns the largest integer less than or equal to X. For positive numbers, this is equivalent to truncating the decimal part.
  • fix(X): Returns the integer part of X by truncating the decimal part. For negative numbers, it behaves differently from INT. For example, fix(-3.7) returns -3, while int(-3.7) returns -4.
  • round(X,D): Rounds X to D decimal places.

Constants

as the FBASIC does not support constants, a constant is a variable with a value. Its up to the programmer to avoid to modify that value. 

  • PI: The PI value, approximately equal to 3.14159.

Date & Time Functions

Date and Time functions in the BASIC programming language are used to handle and manipulate dates and times. These functions allow programs to retrieve the current date and time, perform calculations with dates, and format dates for display or any other usage. The native date format is the DD-MM-YYYY. As the FBASIC does not support date as datatype, the functions will consider any valid value having this format as a date. 

Date and Time functions listed here are available if library FBasicDateFunctions is enabled.

Function Syntax Description
date() date() This function returns a string representing the current system date. The format typically includes the day, month, and year.
isdate() isdate(d) Check if the input string is a valid date.
day() day(d) Extract the day as an numeric value (integer) from a date variable. For example, day("26-10-2025") would return 26.
month() monrh(d) Extract the month as an numeric value (integer) from a date variable. For example, month("26-10-2025") would return 10.
year() year(d) Extract the year as an numeric value (integer) from a date variable. For example, year("26-10-2025") would return 2025.
jtod() jtod(d) Converts the japan style of date (YYYY-MM-DD) to International (DD-MM-YYYY).  For example, JTOD("2025-10-26") would return “26-10-2025”
dtoj() dtoj(d) Converts the International (DD-MM-YYYY) date to japan style of date (YYYY-MM-DD).
datediff() datediff(unit, d1, d2) Calculates the differect bettween d2 and d1 and return the requestd unit. Units are: YEAR,MONTH,DAY.
dateadd() dateadd(unit,num,d) Add the number of units to the input date d, and returns the new date.

The native time format is the HH:MM:SS.FFF. As the FBASIC does not support date or time as datatype, the functions will consider any valid value having this format as a time. Also the functions will consider valid a time of the formats:  HH:MM:SS, HH:MM, and the HH:MM:SS.FFF, HH:MM:SS.FF and HH:MM:SS.F

Function Syntax Description
time() time() This function returns a string representing the current system time. The format is usually HH:MM:SS.
hour() hour(d) extracts the hours as an integer from a time variable.
minute() minute(d) extracts the minutes as an integer from a time variable.
second() second(d) extracts the seconds as an integer from a time variable.

Operators

FBASIC supports the following operators:

Comparisons < > <> >= <=

Example:

assert 1 = 1
assert 3 = 2 + 1
assert 2 = (5 - 3)
assert 6 = 3 * 2
assert 2 = 6 / 3
assert -1 = 1 - 2
assert 1 <> 2
assert Not 1 <> 1
assert 3 > 2
assert 2 < 3
assert 2 >= 1
assert 1 >= 1
assert 1 < 2
assert 1 <= 1
assert 1 And 1
assert 1 Or 0
assert "abc" = "abc"
assert "abc" <> "abc1"
assert 1 = Not 0
assert 0 = Not 1
assert 9 = 3 ^ 2
Arithmetic Operations + - * / ^
Equality and Assignment =        
Other ( )      
Logical And Or Not    
           
           

Libraries and Add-Ons

What is a library

Libraries are add-ons to the main FBASIC Interpreter that provide functions, statements, and variables (or constants). You can only enable a library during the interpreter's initialization, before you run the FBASIC program. Implementing a library is incredibly easy; refer to the how-to manual for more information.

Library Description
Buildins contains the very basic functions are available to the FBASIC programing language, without the need to enable it. There is switch that the developer can disable that code.
Buildins Collections contains the very basic functions and statements for collections manipulation. It is enabled by default but the developer can disable that code.
Strings The name of this library is: FBasicStringFunctions and for further information see the Functions section of this document.
Mathematical The name of this library is: FBasicMathFunctions and for further information see the Functions section of this document.
Date & Time The name of this library is: FBasicDateFunctions and for further information see the Functions section of this document.
Events Triggering The name this library is: FBasicEvents (see below for further information)
2D Arrays Library FBasic2DArrays used to implement the basic functions of the 2D named arrays.
Decision Tables Library FBasicDecisionTables used to implement decision tables and decision support functionallity
Json Library FBasicJsonLibrary implements the Json functionallity for the FBasic interpreter
SQLDataAdapter Library FBasicSQLDataAdapter used to access SQL databases via a ADO connection
Stack For enchance the FBasic program with stack functions use the FBasicStack library
Streams The powerfull streams are enpowering the FBasic by using the library FBasicStreams
Text Replacer Library FBasicTextReplacer offering the basic functions for text templating and replaceing
Word Templating Used for advnaced Word templating. To use it install the nuget package FAST.FBasicTemplatingLibrary and then add the library FBasicTemplatingLibrary

Events Triggering

Event triggering is the act of generating a signal that notifies other parts of a program or system that a specific,
significant action or condition has occurred. Essentially, it's the mechanism that initiates
the event-driven sequence.

It is provided by the Library FBasicEvents and for further details see the document: Events

Placeholder Replacer

Placeholder Replacer implements the low level functionality is necessary to substitute placeholders in a string with value of identifiers (variables or collections).
It is provided by the Library FBasicTextReplacer

For further technical details and syntax about placeholder, format specifiers and text templating managment statements and functions see chapter "Language Reference Text Replacer Library"

Stack Library.

Stack functionality is provided and the stack can hold values by pushing a variable or a value to the stack.
It is provided by the Library FBasicStack

For further technical details and sytax about stack managment statements and functions see chapter "Language Reference Stack Library"

AI Chat Library

The AI Chat Library enables seamless integration with AI providers for conversational and generative tasks. It supports session management, dynamic provider switching, and prompt-response workflows. It is provided by the Library FBasicAIChat

For further technical details and syntax about placeholder, format specifiers and text templating managment statements and functions see chapter "Language Reference AI Chat Library"

Handlers

  • PRINT handler
  • INPUT handler
  • Program load handler
  • Request for Objecthandler

Error messages

The FBASIC system raises a comprehensive set of messages to help developers debug their code and address operational issues. These messages are primarily divided into Errors and Exceptions, more categories can listed for error message have their source in Statement and Functions Libraries.

See the error message in this Language Reference Manual - Error Messages

Notes:

The editor of this file is: https://onlinemarkdowneditor.dev/

Clone this wiki locally