Welcome to EndBASIC X.Y.Z.
Type HELP for interactive usage information.
For a guided tour, type: LOAD "DEMOS:/TOUR.BAS": RUN
Output from HELP:
EndBASIC X.Y.Z
Copyright 2020-2021 Julio Merino
Project page at
License Apache Version 2.0
Top-level help topics:
>> Array functions
>> Cloud access
>> Console
>> File system
>> Graphics
>> Hardware interface
>> Interpreter
>> Language reference
>> Numerical functions
>> Stored program
>> String functions
Type HELP followed by the name of a topic for details.
Type HELP HELP for details on how to specify topic names.
Output from HELP ARRAY:
Array functions
>> LBOUND% Returns the lower bound for the given dimension of the array.
>> UBOUND% Returns the upper bound for the given dimension of the array.
Type HELP followed by the name of a symbol for details.
Output from HELP CLOUD:
Cloud access
The EndBASIC service, should you choose to create an account in, is a
cloud service that provides online file sharing across users of
EndBASIC. The commands below allow you interact with this service once
you have created an account.
To create an account, visit https://www.endbasic.dev/service.html and
come back here once the account is ready.
During account creation time, you are assigned a unique, persistent
drive in which you can store files privately. You can later choose to
share individual files with the public or with specific individuals, at
which point those people will be able to see them by mounting your
drive.
Once logged in, the cloud:// file system scheme becomes available. You
can use it to mount other people's drives by specifying their username
as the path. For example, a command like the following would mount
user-123's shared files as a new drive X: MOUNT "X", "cloud://user-123"
>> LOGIN Logs into the user's account.
>> SHARE Displays or modifies the ACLs of a file.
Type HELP followed by the name of a symbol for details.
Output from HELP CONSOLE:
Console
The EndBASIC console is the display you are seeing: both the
interpreter and the effects of all commands happen within the same
console. There is no separate output window as other didactical
interpreters provide. This unified console supports text and,
depending on the output backend, graphics. This help section focuses
on the textual console; for information about graphics, run HELP
GRAPHICS.
The text console is a matrix of variable size. The upper left position
is row 0 and column 0. Each position in this matrix contains a
character and a color attribute. The color attribute indicates the
foreground and background colors of that character. There is a default
attribute to match the default settings of your terminal, which might
not be a color: for example, in a terminal emulator configured with a
black tint (aka a transparent terminal), the default color respects the
transparency whereas color 0 (black) does not.
If you are writing a script and do not want the script to interfere
with other parts of the console, you should restrict the script to
using only the INPUT and PRINT commands.
Be aware that the console currently reacts poorly to size changes.
Avoid resizing your terminal or web browser. If you do resize them,
however, restart the interpreter.
>> CLS Clears the screen.
>> COLOR Sets the foreground and background colors.
>> INKEY$ Checks for an available key press and returns it.
>> INPUT Obtains user input from the console.
>> LOCATE Moves the cursor to the given position.
>> PRINT Prints a message to the console.
Type HELP followed by the name of a symbol for details.
Output from HELP "FILE SYSTEM":
File system
The EndBASIC storage subsystem is organized as a collection of drives,
each identified by a case-insensitive name. Drives can be backed by a
multitude of file systems with different behaviors, and their targets
are specified as URIs. Special targets include: memory://, which
points to an in-memory read/write drive; and demos://, which points to
a read-only drive with sample programs. Other targets may be available
such as file:// to access a local directory or local:// to access
web-local storage, depending on the context. The output of the MOUNT
command can help to identify which targets are available.
All commands that operate with files take a path. Paths in EndBASIC
can be of the form FILENAME.EXT, in which case they refer to a file in
the current drive; or DRIVE:/FILENAME.EXT and DRIVE:FILENAME.EXT, in
which case they refer to a file in the specified drive. Note that the
slash before the file name is currently optional because EndBASIC does
not support directories yet. Furthermore, if .EXT is missing, a .BAS
extension is assumed.
Be aware that the commands below must be invoked using proper EndBASIC
syntax. In particular, this means that path arguments must be
double-quoted and multiple arguments have to be separated by a comma
(not a space). If you have used commands like CD, DIR, or MOUNT in
other contexts, this is likely to confuse you.
See the "Strored program" help topic for information on how to load,
modify, and save programs.
>> CD Changes the current path.
>> DIR Displays the list of files on the current or given path.
>> MOUNT Lists the mounted drives or mounts a new drive.
>> PWD Prints the current working location.
>> UNMOUNT Unmounts the given drive.
Type HELP followed by the name of a symbol for details.
Output from HELP GRAPHICS:
Graphics
The EndBASIC console overlays text and graphics in the same canvas.
The consequence of this design choice is that the console has two
coordinate systems: the character-based system, used by
the commands described in HELP CONSOLE, and the pixel-based system,
used by the commands described in this section.
>> GFX_LINE Draws a line from (x1,y1) to (x2,y2).
>> GFX_PIXEL Draws a pixel at (x,y).
>> GFX_RECT Draws a rectangle from (x1,y1) to (x2,y2).
>> GFX_RECTF Draws a filled rectangle from (x1,y1) to (x2,y2).
>> GFX_SYNC Controls the video syncing flag and/or forces a sync.
Type HELP followed by the name of a symbol for details.
Output from HELP HARDWARE:
Hardware interface
EndBASIC provides features to manipulate external hardware. These
features are currently limited to GPIO interaction on a Raspberry Pi
and are only available when EndBASIC has explicitly been built with the
--features=rpi option. Support for other busses and platforms may come
later.
>> GPIO_CLEAR Resets the GPIO chip or a specific pin.
>> GPIO_READ? Reads the state of a GPIO pin.
>> GPIO_SETUP Configures a GPIO pin for input or output.
>> GPIO_WRITE Sets the state of a GPIO pin.
Type HELP followed by the name of a symbol for details.
Output from HELP INTERPRETER:
Interpreter
>> CLEAR Restores initial machine state but keeps the stored program.
>> EXIT Exits the interpreter.
>> HELP Prints interactive help.
>> SLEEP Suspends program execution.
Type HELP followed by the name of a symbol for details.
Output from HELP LANG:
Symbols (variable, array and function references):
name? Boolean (TRUE and FALSE).
name# Floating point (double).
name% Integer (32 bits).
name$ String.
name Type determined by value or definition.
Assignments and declarations:
varref[(dim1[, ..., dimN])] = expr
DIM varname[(dim1[, ..., dimN])] [AS BOOLEAN|DOUBLE|INTEGER|STRING]
Expressions:
a + b a - b a * b a / b a MOD b -a
a AND b NOT a a OR b a XOR b
a = b a <> b a < b a <= b a > b a >= b
(a) varref
arrayref(s1[, ..., sN]) funcref(a1[, ..., aN])
Flow control:
IF expr THEN: ...: ELSE IF expr THEN: ...: ELSE: ...: END IF
FOR varref = expr TO expr [STEP int]: ...: NEXT
WHILE expr: ...: WEND
Misc:
st1: st2 Separates statements (same as a newline).
REM text Comment until end of line.
' text Comment until end of line.
, Long separator for arguments to builtin call.
; Short separator for arguments to builtin call.
Output from HELP NUMERICAL:
Numerical functions
>> ATN# Computes the arc-tangent of a number.
>> COS# Computes the cosine of an angle.
>> DEG Sets degrees mode of calculation.
>> DTOI% Rounds the given double to the closest integer.
>> ITOD# Converts the given integer to a double.
>> MAXD# Returns the maximum number out of a set of doubles.
>> MAXI% Returns the maximum number out of a set of integers.
>> MIND# Returns the minimum number out of a set of doubles.
>> MINI% Returns the minimum number out of a set of integers.
>> PI# Returns the Archimedes' constant.
>> RAD Sets radians mode of calculation.
>> RANDOMIZE Reinitializes the pseudo-random number generator.
>> RND# Returns a random number in the [0..1] range.
>> SIN# Computes the sine of an angle.
>> TAN# Computes the tangent of an angle.
Type HELP followed by the name of a symbol for details.
Output from HELP STORED:
Stored program
The EndBASIC interpreter has a piece of read/write memory called the
"stored program". This memory serves to maintain the code of a program
you edit and manipulate right from the interpreter.
The common flow to interact with a stored program is to load a program
from disk using the LOAD command, modify its contents via the EDIT
command, execute the program via the RUN command, and finally save the
new or modified program via the SAVE command.
Be aware that the stored program's content is lost whenever you load a
program, exit the interpreter, or use the NEW command, so don't forget
to save it.
See the "File system" help topic for information on where the programs
can be saved and loaded from.
>> DEL Deletes the given program.
>> EDIT Interactively edits the stored program.
>> LIST Prints the currently-loaded program.
>> LOAD Loads the given program.
>> NEW Restores initial machine state and creates a new program.
>> RUN Runs the stored program.
>> SAVE Saves the current program in memory to the given filename.
Type HELP followed by the name of a symbol for details.
Output from HELP STRING:
String functions
>> LEFT$ Returns a given number of characters from the left side of a string.
>> LEN% Returns the length of the string in expr$.
>> LTRIM$ Returns a copy of a string with leading whitespace removed.
>> MID$ Returns a portion of a string.
>> RIGHT$ Returns a given number of characters from the right side of a string.
>> RTRIM$ Returns a copy of a string with trailing whitespace removed.
Type HELP followed by the name of a symbol for details.
Output from HELP CD:
CD path$
Changes the current path.
Output from HELP CLEAR:
CLEAR
Restores initial machine state but keeps the stored program.
This command resets the machine to a semi-pristine state by clearing
all user-defined variables and restoring the state of shared resources.
These resources include: the console, whose color and video syncing bit
are reset; and the GPIO pins, which are set to their default state.
The stored program is kept in memory. To clear that too, use NEW (but
don't forget to first SAVE your program!).
Output from HELP CLS:
CLS
Clears the screen.
Output from HELP COLOR:
COLOR [fg%][, [bg%]]
Sets the foreground and background colors.
Color numbers are given as ANSI numbers and can be between 0 and 255.
If a color number is not specified, then the color is reset to the
console's default. The console default does not necessarily match any
other color specifiable in the 0 to 255 range, as it might be
transparent.
Output from HELP DEG:
DEG
Sets degrees mode of calculation.
The default condition for the trigonometric functions is to use
radians. DEG configures the environment to use degrees until
instructed otherwise.
Output from HELP DEL:
DEL filename
Deletes the given program.
The filename must be a string and must be a basename (no directory
components). The .BAS extension is optional, but if present, it must
be .BAS.
Output from HELP DIR:
DIR [path$]
Displays the list of files on the current or given path.
Output from HELP EDIT:
EDIT
Interactively edits the stored program.
Output from HELP EXIT:
EXIT [code%]
Exits the interpreter.
The optional code indicates the return value to return to the system.
Output from HELP GFX_LINE:
GFX_LINE x1%, y1%, x2%, y2%
Draws a line from (x1,y1) to (x2,y2).
The line is drawn using the foreground color as selected by COLOR.
Output from HELP GFX_PIXEL:
GFX_PIXEL x%, y%
Draws a pixel at (x,y).
The pixel is drawn using the foreground color as selected by COLOR.
Output from HELP GFX_RECT:
GFX_RECT x1%, y1%, x2%, y2%
Draws a rectangle from (x1,y1) to (x2,y2).
The outline of the rectangle is drawn using the foreground color as
selected by COLOR and the area of the rectangle is left untouched.
Output from HELP GFX_RECTF:
GFX_RECTF x1%, y1%, x2%, y2%
Draws a filled rectangle from (x1,y1) to (x2,y2).
The outline and area of the rectangle are drawn using the foreground
color as selected by COLOR.
Output from HELP GFX_SYNC:
GFX_SYNC [enabled?]
Controls the video syncing flag and/or forces a sync.
With no arguments, this command triggers a video sync without updating
the video syncing flag. When enabled? is specified, this updates the
video syncing flag accordingly and triggers a video sync if enabled? is
TRUE.
When video syncing is enabled, all console commands immediately refresh
the console. This is useful to see the effects of the commands right
away, which is why this is the default mode in the interpreter.
However, this is a *very* inefficient way of drawing.
When video syncing is disabled, all console updates are buffered until
video syncing is enabled again. This is perfect to draw complex
graphics efficiently. If this is what you want to do, you should
disable syncing first, render a frame, call GFX_SYNC to flush the
frame, repeat until you are done, and then enable video syncing again.
Note that the textual cursor is not visible when video syncing is
disabled.
WARNING: Be aware that if you disable video syncing in the interactive
interpreter, you will not be able to see what you are typing any longer
until you reenable video syncing.
Output from HELP GPIO_CLEAR:
GPIO_CLEAR [pin%]
Resets the GPIO chip or a specific pin.
If no pin% is specified, resets the state of all GPIO pins. If a pin%
is given, only that pin is reset. It is OK if the given pin has never
been configured before.
Output from HELP GPIO_SETUP:
GPIO_SETUP pin% mode$
Configures a GPIO pin for input or output.
Before a GPIO pin can be used for reads or writes, it must be
configured to be an input or output pin. Additionally, if pull up or
pull down resistors are available and desired, these must be configured
upfront too.
The mode$ has to be one of "IN", "IN-PULL-DOWN", "IN-PULL-UP", or
"OUT". These values are case-insensitive. The possibility of using
the pull-down and pull-up resistors depends on whether they are
available in the hardware, and selecting these modes will fail if they
are not.
It is OK to reconfigure an already configured pin without clearing its
state first.
Output from HELP GPIO_WRITE:
GPIO_WRITE pin% value?
Sets the state of a GPIO pin.
A FALSE value? sets the pin to low, and a TRUE value? sets the pin to
high.
Output from HELP HELP:
HELP [topic]
Prints interactive help.
Without arguments, shows a summary of all available top-level help
topics.
With a single argument, which may be a bare name or a string, shows
detailed information about the given help topic, command, or function.
Topic names with spaces in them must be double-quoted.
Topic names are case-insensitive and can be specified as prefixes, in
which case the topic whose name starts with the prefix will be shown.
For example, the following invocations are all equivalent: HELP CON,
HELP console, HELP "Console manipulation".
Output from HELP INPUT:
INPUT ["prompt"] <;|,> variableref
Obtains user input from the console.
The first expression to this function must be empty or evaluate to a
string, and specifies the prompt to print. If this first argument is
followed by the short `;` separator, the prompt is extended with a
question mark.
The second expression to this function must be a bare variable
reference and indicates the variable to update with the obtained input.
Output from HELP LIST:
LIST
Prints the currently-loaded program.
Output from HELP LOAD:
LOAD filename
Loads the given program.
The filename must be a string and must be a basename (no directory
components). The .BAS extension is optional, but if present, it must
be .BAS.
Output from HELP LOCATE:
LOCATE column%, row%
Moves the cursor to the given position.
Output from HELP LOGIN:
LOGIN username$ [password$]
Logs into the user's account.
On a successful login, this mounts your personal drive under the
CLOUD:/ location, which you can access with any other file-related
commands. Using the cloud:// file system scheme, you can mount other
people's drives with the MOUNT command.
To create an account, visit https://www.endbasic.dev/service.html and
come back here once the account is ready.
Output from HELP MOUNT:
MOUNT [drive_name$, target$]
Lists the mounted drives or mounts a new drive.
With no arguments, prints a list of mounted drives and their targets.
With two arguments, mounts the drive_name$ to point to the target$.
Drive names are specified without a colon at the end, and targets are
given in the form of a URI.
Output from HELP NEW:
NEW
Restores initial machine state and creates a new program.
This command resets the machine to a pristine state by clearing all
user-defined variables and restoring the state of shared resources.
These resources include: the console, whose color and video syncing bit
are reset; and the GPIO pins, which are set to their default state.
The stored program is also discarded from memory, so don't forget to
SAVE it first! To reset resources but avoid clearing the stored
program, use CLEAR instead.
Output from HELP PWD:
PWD
Prints the current working location.
If the EndBASIC path representing the current location is backed by a
real path that is accessible by the underlying operating system,
displays such path as well.
Output from HELP PRINT:
PRINT [expr1 [<;|,> .. exprN]]
Prints a message to the console.
The expressions given as arguments are all evaluated and converted to
strings. Arguments separated by the short `;` separator are
concatenated with a single space, while arguments separated by the long
`,` separator are concatenated with a tab character.
Output from HELP RAD:
RAD
Sets radians mode of calculation.
The default condition for the trigonometric functions is to use radians
but it can be set to degrees with the DEG command. RAD restores the
environment to use radians mode.
Output from HELP RANDOMIZE:
RANDOMIZE [seed%]
Reinitializes the pseudo-random number generator.
If no seed is given, uses system entropy to create a new sequence of
random numbers.
WARNING: These random numbers offer no cryptographic guarantees.
Output from HELP RUN:
RUN
Runs the stored program.
This issues a CLEAR operation before starting the program to prevent
previous leftover state from interfering with the new execution.
Output from HELP SAVE:
SAVE filename
Saves the current program in memory to the given filename.
The filename must be a string and must be a basename (no directory
components). The .BAS extension is optional, but if present, it must
be .BAS.
Output from HELP SHARE:
SHARE filename$ [, acl1$, .., aclN$]
Displays or modifies the ACLs of a file.
If given only a filename$, this command prints out the ACLs of the
file.
Otherwise, when given a list of ACL changes, applies those changes to
the file. The acl1$ to aclN$ arguments are strings of the form
"username+r" or "username-r", where the former adds "username" to the
users allowed to read the file, and the latter removes "username" from
the list of users allowed to read the file.
You can use the special "public+r" ACL to share a file with everyone.
Note that this command only works for cloud-based drives as it is
designed to share files among users of the EndBASIC service.
Output from HELP SLEEP:
SLEEP seconds%|seconds#
Suspends program execution.
Pauses program execution for the given number of seconds, which can be
specified either as an integral or as a floating point number for finer
precision.
Output from HELP UNMOUNT:
UNMOUNT drive_name
Unmounts the given drive.
Drive names are specified without a colon at the end.
Output from HELP ATN:
ATN#(n%|n#)
Computes the arc-tangent of a number.
The resulting angle is measured in degrees or radians depending on the
angle mode as selected by the DEG and RAD commands.
Output from HELP COS:
COS#(angle%|angle#)
Computes the cosine of an angle.
The input angle% or angle# is measured in degrees or radians depending
on the angle mode as selected by the DEG and RAD commands.
Output from HELP DTOI:
DTOI%(expr#)
Rounds the given double to the closest integer.
If the value is too small or too big to fit in the integer's range,
returns the smallest or biggest possible integer that fits,
respectively.
Output from HELP GPIO_READ:
GPIO_READ?(pin%)
Reads the state of a GPIO pin.
Returns FALSE to represent a low value, and TRUE to represent a high
value.
Output from HELP INKEY:
INKEY$()
Checks for an available key press and returns it.
If a key press is available to be read, returns its name. Otherwise,
returns the empty string. The returned key matches its name, number,
or symbol and maintains case. In other words, pressing the X key will
return 'x' or 'X' depending on the SHIFT modifier.
The following special keys are recognized: arrow keys (UP, DOWN, LEFT,
RIGHT), backspace (BS), enter (ENTER), escape (ESC), CTRL+D (EOF), and
CTRL+C (INT).
This function never blocks. To wait for a key press, you need to
explicitly poll the keyboard. For example, to wait until the escape
key is pressed, you could do:
k$ = "": WHILE k$ = <> "ESC": k = INKEY$(): SLEEP 0.01: WEND
This non-blocking design lets you to combine the reception of multiple
evens, such as from GPIO_INPUT?, within the same loop.
Output from HELP ITOD:
ITOD#(expr%)
Converts the given integer to a double.
Output from HELP LEFT:
LEFT$(expr$, n%)
Returns a given number of characters from the left side of a string.
If n% is 0, returns an empty string.
If n% is greater than or equal to the number of characters in expr$,
returns expr$.
Output from HELP LEN:
LEN%(expr$)
Returns the length of the string in expr$.
Output from HELP LBOUND:
LBOUND%(array[, dimension%])
Returns the lower bound for the given dimension of the array.
The lower bound is the smallest available subscript that can be
provided to array indexing operations.
For one-dimensional arrays, the dimension% is optional. For
multi-dimensional arrays, the dimension% is a 1-indexed integer.
Output from HELP LTRIM:
LTRIM$(expr$)
Returns a copy of a string with leading whitespace removed.
Output from HELP MIND:
MIND#(expr#[, .., expr#])
Returns the minimum number out of a set of doubles.
Output from HELP MINI:
MINI%(expr%[, .., expr%])
Returns the minimum number out of a set of integers.
Output from HELP MAXD:
MAXD#(expr#[, .., expr#])
Returns the maximum number out of a set of doubles.
Output from HELP MAXI:
MAXI%(expr%[, .., expr%])
Returns the maximum number out of a set of integers.
Output from HELP MID:
MID$(expr$, start%[, length%])
Returns a portion of a string.
start% indicates the starting position of the substring to extract and
it is 1-indexed.
length% indicates the number of characters to extract and, if not
specified, defaults to extracting
until the end of the string.
Output from HELP PI:
PI#()
Returns the Archimedes' constant.
Output from HELP RIGHT:
RIGHT$(expr$, n%)
Returns a given number of characters from the right side of a string.
If n% is 0, returns an empty string.
If n% is greater than or equal to the number of characters in expr$,
returns expr$.
Output from HELP RND:
RND#(n%)
Returns a random number in the [0..1] range.
If n% is zero, returns the previously generated random number. If n%
is positive, returns a new random number.
If you need to generate an integer random number within a specific
range, say [0..100], compute it with an expression like DTOI%(RND#(1) *
100.0).
WARNING: These random numbers offer no cryptographic guarantees.
Output from HELP RTRIM:
RTRIM$(expr$)
Returns a copy of a string with trailing whitespace removed.
Output from HELP SIN:
SIN#(angle%|angle#)
Computes the sine of an angle.
The input angle% or angle# is measured in degrees or radians depending
on the angle mode as selected by the DEG and RAD commands.
Output from HELP TAN:
TAN#(angle%|angle#)
Computes the tangent of an angle.
The input angle% or angle# is measured in degrees or radians depending
on the angle mode as selected by the DEG and RAD commands.
Output from HELP UBOUND:
UBOUND%(array[, dimension%])
Returns the upper bound for the given dimension of the array.
The upper bound is the largest available subscript that can be provided
to array indexing operations.
For one-dimensional arrays, the dimension% is optional. For
multi-dimensional arrays, the dimension% is a 1-indexed integer.
End of input by CTRL-D