endbasic 0.11.1

Output from HELP:

    This is EndBASIC X.Y.Z.

    Project page at <https://www.endbasic.dev/>
    License Apache Version 2.0 <http://www.apache.org/licenses/LICENSE-2.0>

    Top-level help topics

    >> Array functions
    >> Cloud access
    >> Console
    >> Data management
    >> File system
    >> Graphics
    >> Hardware interface
    >> Interpreter
    >> Language reference
    >> Numerical functions
    >> Stored program
    >> String and character functions

    Type HELP followed by the name of a topic for details.
    Type HELP "HELP" for details on how to specify topic names.
    Type LOAD "DEMOS:/TOUR.BAS": RUN for a guided tour.
    Type END or press CTRL+D to exit.

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 topic 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 topic 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 one or more values to the console.
    >> SCRCOLS%    Returns the number of columns in the text console.
    >> SCRROWS%    Returns the number of rows in the text console.

    Type HELP followed by the name of a topic for details.

Output from HELP "DATA":

    Data management

    >> READ       Extracts data values from DATA statements.
    >> RESTORE    Resets the index of the data element to be returned.

    Type HELP followed by the name of a topic 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 topic 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_CIRCLE     Draws a circle of radius r centered at (x,y).
    >> GFX_CIRCLEF    Draws a filled circle of radius r centered at (x,y).
    >> GFX_HEIGHT%    Returns the height in pixels of the graphical console.
    >> 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.
    >> GFX_WIDTH%     Returns the width in pixels of the graphical console.

    Type HELP followed by the name of a topic 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 topic for details.

Output from HELP "INTERPRETER":

    Interpreter

    >> CLEAR      Restores initial machine state but keeps the stored program.
    >> ERRMSG$    Returns the last captured error message.
    >> HELP       Prints interactive help.
    >> SLEEP      Suspends program execution.

    Type HELP followed by the name of a topic for details.

Output from HELP "LANG":

    General language topics

    >> DO             Do loops
    >> Expressions    Expressions and operators
    >> FOR            For loops
    >> Functions      User-defined functions
    >> IF             Multiline and uniline IF statements
    >> Jumps          GOTO, GOSUB, END, and labels
    >> ON ERROR       Error handling
    >> SELECT CASE    Conditional statement to choose among values
    >> Style          Spacing, comments, and general style
    >> Subroutines    User-defined subroutines
    >> Types          Primitive types and arrays
    >> Variables      Variable references, assignments, and the DIM keyword
    >> WHILE          While loops

    Type HELP followed by the name of a topic for details.

Output from HELP "NUMERICAL":

    Numerical functions

    >> ATN#         Computes the arc-tangent of a number.
    >> CINT%        Casts the given numeric expression to an integer (with rounding).
    >> COS#         Computes the cosine of an angle.
    >> DEG          Sets degrees mode of calculation.
    >> INT%         Casts the given numeric expression to an integer (with truncation).
    >> MAX#         Returns the maximum number out of a set of numbers.
    >> MIN#         Returns the minimum number out of a set of numbers.
    >> 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.
    >> SQR#         Computes the square root of the given number.
    >> TAN#         Computes the tangent of an angle.

    Type HELP followed by the name of a topic 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.

    >> DISASM    Disassembles the stored program.
    >> EDIT      Interactively edits the stored program.
    >> KILL      Deletes the given 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 topic for details.

Output from HELP "STRING":

    String and character functions

    >> ASC%      Returns the UTF character code of the input character.
    >> CHR$      Returns the UTF character that corresponds to the given code.
    >> 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.
    >> STR$      Formats a scalar value as a string.

    Type HELP followed by the name of a topic for details.

Output from HELP "DO":

    Do loops

    `DO` loops are a generalized form of `WHILE` loops.  `DO` loops allow
    testing a condition before or after every iteration, and the condition
    can be tested until it is true or false.  Take a look at the following
    examples:

        DO
            PRINT "Infinite loop"
        LOOP

        DO
            a = a + 1
        LOOP UNTIL a = 10

        DO
            a = a + 1
        LOOP WHILE a < 10

        a = 0
        DO UNTIL a = 10
            a = a + 1
        LOOP

        a = 0
        DO WHILE a < 10
            a = a + 1
        LOOP

    `DO` loops can be exited an any point via the `EXIT DO` statement.

Output from HELP "EXPRESSIONS":

    Expressions and operators

    EndBASIC provides the following operators:

    * Numeric operators:
        * Binary infix: +, -, *, /, MOD, ^
        * Unary prefix: -

    * Logical and bitwise operators:
        * Binary infix: AND, OR, XOR
        * Unary prefix: NOT
        * Whether these perform a logical or bitwise operation depends on
        the expression context.

    * Bitwise operators:
        * Binary infix: <<, >> (signed integer shift without rotation)

    * Relational operators:
        * Binary infix: =, <>, <, <=, >, >=

    Expressions can also contain variable references, function calls, and
    array element references.  For example, the following defines an array
    of doubles, sets one of them, and then reads the value in an expression
    and rounds it to an integer via the `CINT` builtin function:

        DIM floats(5) AS DOUBLE
        floats(2) = 5.6
        PRINT 3 + 9 - CINT(floats(2))

Output from HELP "FOR":

    For loops

    `FOR` loops provide iteration through a numeric range.  Their most
    basic form looks like this:

        FOR a = 1 to 10
            PRINT a
        NEXT

    You can optionally specify a positive or negative `STEP` to change how
    the iterator changes in each loop body execution:

        FOR a = 10 to 1 STEP -2
            PRINT a
        NEXT

Output from HELP "FUNCTIONS":

    User-defined functions

    To define a function, use the `FUNCTION` keyword followed by an
    arbitrary list of argument definitions.  Argument declarations can use
    type annotations or `AS type` suffixes to define their types, but not
    both in a single argument.  The return value of a function is specified
    by assigning a value to the variable named after the function:

        FUNCTION my_function#(b AS BOOLEAN, i%)
            IF b THEN my_function = i * 2.3 ELSE my_function = 1.1
        END FUNCTION

        PRINT my_function(TRUE, 5) ' Prints 11.5.
        PRINT my_function(FALSE, 8) ' Prints 1.1.

    Global variables can be defined via the `DIM SHARED` keyword.  See the
    "Variables" help topic for details.

Output from HELP "IF":

    Multiline and uniline IF statements

    Multiline IF statements look like the following.  Note that the
    `ELSEIF` and `ELSE` clauses are all optional, but if `ELSE` is present,
    it must appear last and only once:

        IF a = 1 THEN
            PRINT "a is 1"
        ELSEIF a <> 2 THEN
            PRINT "a is not 2"
        ELSE
            PRINT "a is something else"
        END IF

    IF statements can be collapsed into a single line and look like the
    following.  Similarly to the previous, the `ELSE` clause is optional
    and can only appear once:

        IF a = 1 THEN PRINT "a is 1" ELSE PRINT "a is something else"

    Note that, in the uniline form, only a subset of statements can be
    specified.

Output from HELP "JUMPS":

    GOTO, GOSUB, END, and labels

    EndBASIC statements can be labeled via explicitly-assigned line numbers
    or textual identifiers.  These labels can be used as the target of the
    unstructured control flow statements `GOTO` and `GOSUB`.  For example:

        i = 1
        20 PRINT i ' Statement with a numeric label.
        IF i = 10 THEN GOTO @out
        i = i + 1
        GOTO 20
        @out ' Statement with a textual label.

    When using `GOSUB` to temporarily jump to a subroutine, use the
    `RETURN` keyword when done:

        GOTO @main

        @add
        result = a + b
        RETURN

        @main
        a = 3: b = 5: GOSUB @add
        PRINT result

    Program execution can be terminated at any point via the `END`
    statement, which optionally takes an exit code to return to the calling
    program.

Output from HELP "ON ERROR":

    Error handling

    Certain types of errors can be caught for inspection and program
    recovery.

    To jump to a line number or label when a recoverable error is caught:

        ON ERROR GOTO 100
        ON ERROR GOTO @label

    To continue execution at the next statement after an error is caught:

        ON ERROR RESUME NEXT

    To reset the error handler to its default, which terminates program
    execution on an error:

        ON ERROR GOTO 0

    The ERRMSG function can be used to fetch the textual description of the
    string that was caught.

Output from HELP "SELECT CASE":

    Conditional statement to choose among values

    The SELECT CASE statement allows evaluating an expression and comparing
    it to multiple different values or ranges.

        INPUT "Enter a number"; a
        SELECT CASE a
            CASE 1, 3, 5, 7, 9
                PRINT "Odd"
            CASE 0, 2, 5, 6, 8
                PRINT "Even"
            CASE IS < 0, 10 TO 100
                PRINT "Other cases"
            CASE ELSE
                PRINT "Fallback"
        END SELECT

    The expression given to `SELECT CASE` is evaluated exactly once.
    Similarly to `IF` statements, the `CASE ELSE`, if present, must appear
    only once at as the last case guard.

    When using the `IS` guard, all relational operators can be specified.

Output from HELP "SUBROUTINES":

    User-defined subroutines

    To define a subroutine (also known as procedure or command), use the
    `SUB` keyword followed by an arbitrary list of argument definitions.
    Argument declarations can use type annotations or `AS type` suffixes to
    define their types, but not both in a single argument:

        SUB my_command(b AS BOOLEAN, i%)
            IF b THEN PRINT i * 2.3 ELSE PRINT 1.1
        END SUB

        my_command TRUE, 5 ' Prints 11.5.
        my_command FALSE, 8 ' Prints 1.1.

    Global variables can be defined via the `DIM SHARED` keyword.  See the
    "Variables" help topic for details.

Output from HELP "STYLE":

    Spacing, comments, and general style

    Every statement in EndBASIC must appear in its own line.  Lines can be
    separated by natural newline characters, but also via the `:`
    character.  The following are equivalent:

        PRINT 3
        PRINT 4

        PRINT 3: PRINT 4

    Comments can be introduced via `REM` or an apostrophe character and run
    throughout the end of a line:

        ' This is a comment.
        REM This is another comment.
        a = 3 ' Comment after statement.

    The common EndBASIC style in documentation and sample programs is to:

    * Write all language keywords in uppercase.
    * Write all variable identifiers in lowercase.
    * Suffix all variable references and function calls with a type
    identifier.

    These are just style guidelines and they are neither required nor
    enforced in your own code.  For a more modern look, you can type all
    code in lowercase letters and avoid type identifiers.

Output from HELP "TYPES":

    Primitive types and arrays

    EndBASIC supports the following primitive types:

    * `?`: BOOLEAN
        * Literal values are `TRUE` and `FALSE`.

    * `#`: DOUBLE
        * 64-bit double floating point.
        * Literal values have the form 123.4.

    * `%`: INTEGER
        * 32-bit signed integers.
        * Literal values can be specified in binary (`b`), decimal (`d`),
        octal (`o`) and hexadecimal (`x`) bases.
        * Literal values have the form 123, &d123, or &d_123, where `d`
        specifies the base.

    * `$`: STRING
        * Literal values are UTF-8 double-quoted strings.
        * Nested double-quotes can be escaped with a `\` character.

    Multidimensional arrays are supported as well, although all the
    dimensions in an array must have the same type.

    Integers are automatically promoted to floats when they appear in a
    float expression, and floats are demoted to integers via rounding (3.4
    becomes 3, 3.5 becomes 4) when they appear in an integer expression.

Output from HELP "VARIABLES":

    Variable references, assignments, and the DIM keyword

    Variable identifiers are alphanumeric words that start with a letter or
    special character such as _.  Variable references can optionally be
    suffixed by a type identifier to force them to be of a specific type,
    but note that EndBASIC is strictly typed and variables cannot change
    type after they have been assigned.

    Variables can be first defined either via an assignment or via the
    `DIM` keyword, the latter of which sets the variable to its zero value.
    The following are all equivalent:

        DIM foo AS BOOLEAN
        DIM foo? AS BOOLEAN
        foo? = FALSE

    Arrays must be defined with the `DIM` keyword before they can be used.
    The following example defines a matrix and sets the value of a single
    element within it:

        DIM matrix%(10, 100) AS INTEGER
        matrix%(5, 15) = 1234

    Global variables can be defined via `DIM SHARED` and will be readable
    and settable from within user-defined functions:

        DIM SHARED global AS DOUBLE

Output from HELP "WHILE":

    While loops

    The `WHILE` keyword is used to define a loop that executes a collection
    of statements until a guard condition is false.  They look like this:

        a = 0
        WHILE a < 10
            PRINT a
            a = a + 1
        WEND

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

    This command is for interactive use only.

Output from HELP "CLS":

    CLS

    Clears the screen.

Output from HELP "COLOR":

    COLOR <> | <fg%> | <[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 "DIR":

    DIR <> | <path$>

    Displays the list of files on the current or given path.

Output from HELP "DISASM":

    DISASM

    Disassembles the stored program.

    The assembly code printed by this command is provided as a tool to
    understand how high level code gets translated to the machine code of a
    fictitious stack-based machine.  Note, however, that the assembly code
    cannot be reassembled nor modified at this point.

Output from HELP "EDIT":

    EDIT

    Interactively edits the stored program.

Output from HELP "GFX_CIRCLE":

    GFX_CIRCLE x%, y%, r%

    Draws a circle of radius r centered at (x,y).

    The outline of the circle is drawn using the foreground color as
    selected by COLOR and the area of the circle is left untouched.

Output from HELP "GFX_CIRCLEF":

    GFX_CIRCLEF x%, y%, r%

    Draws a filled circle of radius r centered at (x,y).

    The outline and area of the circle are drawn using the foreground color
    as selected by COLOR.

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 must be a string, shows detailed
    information about the given help topic, command, or function.

    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 <vref> | <[prompt$] <,|;> vref>

    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 "KILL":

    KILL 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 "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$> | <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 <> | <target$ AS drive_name$>

    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 "PRINT":

    PRINT [expr1 <,|;> ..  <,|;> exprN]

    Prints one or more values to the console.

    The expressions given as arguments are all evaluated and converted to
    strings before they are printed.  See the documentation of STR$() for
    the conversion rules.

    Using a `;` separator between arguments causes the two adjacent values
    to be displayed together.  For strings, this means that no space is
    added between them; for all other types, a space is added after the
    value on the left side.

    Using a `,` separator between arguments works the same as `;` except
    that the fields are left-aligned to 14-character wide fields on the
    screen.

    If the last expression is empty (i.e. if the statement ends in a
    semicolon or a comma), then the cursor position remains on the same
    line of the message right after what was printed.

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 "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 "READ":

    READ vref1[, .., vrefN]

    Extracts data values from DATA statements.

    DATA statements can appear anywhere in the program and they register
    data values into an array of values.  READ is then used to extract
    values from this array into the provided variables in the order in
    which they were defined.  In other words: READ maintains an internal
    index into the data array that gets incremented by the number of
    provided variables every time it is executed.

    The variable references in the vref1..vrefN list must match the types
    or be compatible with the values in the corresponding position of the
    data array.  Empty values in the data array can be specified by DATA,
    and those are converted into the default values for the relevant types:
    booleans are false, numbers are 0, and strings are empty.

    Attempting to extract more values than are defined by DATA results in
    an "out of data" error.

    The index that READ uses to extract DATA values can be reset by RESTORE
    and, more generally, by CLEAR.

Output from HELP "RESTORE":

    RESTORE

    Resets the index of the data element to be returned.

    This allows READ to re-return the same elements that were previously
    extracted from the array of values defined by DATA.

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#

    Suspends program execution.

    Pauses program execution for the given number of seconds, which can be
    specified either as an integer 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 "ASC":

    ASC%(char$)

    Returns the UTF character code of the input character.

    The input char$ argument is a string that must be 1-character long.

    This is called ASC for historical reasons but supports more than just
    ASCII characters in this implementation of BASIC.

    See CHR$() for the inverse of this function.

Output from HELP "ATN":

    ATN#(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 "CHR":

    CHR$(code%)

    Returns the UTF character that corresponds to the given code.

    See ASC%() for the inverse of this function.

Output from HELP "CINT":

    CINT%(expr#)

    Casts the given numeric expression to an integer (with rounding).

    When casting a double value to an integer, the double value is first
    rounded to the closest integer.  For example, 4.4 becomes 4, but both
    4.5 and 4.6 become 5.

Output from HELP "COS":

    COS#(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 "ERRMSG":

    ERRMSG$

    Returns the last captured error message.

    When used in combination of ON ERROR to set an error handler, this
    function returns the string representation of the last captured error.
    If this is called before any error is captured, returns the empty
    string.

Output from HELP "GFX_HEIGHT":

    GFX_HEIGHT%

    Returns the height in pixels of the graphical console.

    See GFX_WIDTH to query the other dimension.

Output from HELP "GFX_WIDTH":

    GFX_WIDTH%

    Returns the width in pixels of the graphical console.

    See GFX_HEIGHT to query the other dimension.

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 "INT%":

    INT%(expr#)

    Casts the given numeric expression to an integer (with truncation).

    When casting a double value to an integer, the double value is first
    truncated to the smallest

    integer that is not larger than the double value.  For example, all of
    4.4, 4.5 and 4.6 become 4.

Output from HELP "LBOUND":

    LBOUND%(<array> | <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 "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 "LTRIM":

    LTRIM$(expr$)

    Returns a copy of a string with leading whitespace removed.

Output from HELP "MAX":

    MAX#(expr1#[, .., exprN#])

    Returns the maximum number out of a set of numbers.

Output from HELP "MID":

    MID$(<expr$, start%> | <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 "MIN":

    MIN#(expr1#[, .., exprN#])

    Returns the minimum number out of a set of numbers.

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 or is not specified, 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 CINT%(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 "SCRCOLS":

    SCRCOLS%

    Returns the number of columns in the text console.

    See SCRROWS to query the other dimension.

Output from HELP "SCRROWS":

    SCRROWS%

    Returns the number of rows in the text console.

    See SCRCOLS to query the other dimension.

Output from HELP "SIN":

    SIN#(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 "SQR":

    SQR#(num#)

    Computes the square root of the given number.

Output from HELP "STR$":

    STR$(expr)

    Formats a scalar value as a string.

    If expr evaluates to a string, this returns the string unmodified.

    If expr evaluates to a boolean, this returns the strings FALSE or TRUE.

    If expr evaluates to a number, this returns a string with the textual
    representation of the number.  If the number does NOT have a negative
    sign, the resulting string has a single space in front of it.

    To obtain a clean representation of expr as a string without any
    artificial whitespace characters in it, do LTRIM$(STR$(expr)).

Output from HELP "TAN":

    TAN#(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> | <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.