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-2022 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 is a cloud service that provides online file sharing across users of EndBASIC and the public. Files that have been shared publicly can be accessed without an account via the cloud:// file system scheme. All you have to do is mount a user's cloud drive and then access the files as you would with your own. For example: MOUNT "X", "cloud://user-123": DIR "X:" To upload files and share them, you need to create an account. 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. If you have any questions or experience any problems while interacting with the cloud service, please contact support@endbasic.dev. >> LOGIN Logs into the user's account. >> LOGOUT Logs the user out of their account. >> SHARE Displays or modifies the ACLs of a file. >> SIGNUP Creates a new user account interactively. 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 "Stored 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: ...: ELSEIF 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. These operations will ask you to save the program if you have forgotten to do so, but it's better to get in the habit of saving often. 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 valid EndBASIC path. The .BAS extension is optional but, if present, it must be .BAS. See the "File system" help topic for information on the path syntax. 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 valid EndBASIC path. The .BAS extension is optional but, if present, it must be .BAS. Any previously stored program is discarded from memory, but LOAD will pause to ask before discarding any unsaved modifications. See the "File system" help topic for information on the path syntax. 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, use the SIGNUP command. Output from HELP LOGOUT: LOGOUT Logs the user out of their account. Unmounts the CLOUD drive that was mounted by the LOGIN command. As a consequence of this, running LOGOUT from within the CLOUD drive will fail. 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, but NEW will pause to ask before discarding any unsaved modifications. 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 valid EndBASIC path. The .BAS extension is optional but, if present, it must be .BAS. If no filename is given, SAVE will try to use the filename of the loaded program (if any) and will fail if no name has been given yet. See the "File system" help topic for information on the path syntax. 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. These files can be auto-run via the web interface using the special URL that the command prints on success. 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 SIGNUP: SIGNUP Creates a new user account interactively. This command will ask you for your personal information to create an account in the EndBASIC cloud service. You will be asked for confirmation before proceeding. 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), end or CTRL+E (END), enter (ENTER), CTRL+D (EOF), escape (ESC), home or CTRL+A (HOME), CTRL+C (INT), page up (PGUP), page down (PGDOWN), and tab (TAB). 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