hBasic Manual

By 'scope' we mean the list/s that Basic! searches through when trying to find a variable.
There are mainly two types of scopes which a basic program is running in.

OR

2. A local scope i.e

inside a function

An interrupt could happen in the middle of a function.
In Legacy v01.91,  Basic would detect this and change the scope (from local) to the 'global' list which starts at the main program list. If the variable is not found, it would keep searching through the list of the first function that was called, then the next function, and so on until it reached the end of the last called function (the function that was interrupted).
This normally works fine if the variable exists in the main list. Many uses of Interrupts rely on finding a variable in a convenient 'global' area such as the main list.

There are two problems with this design;
and

myfunc ()

Back.Resume

In Legacy v01.91, Functions called by an interrupt block were getting wrong scope.
This is clearly undesirable, and is a side-effect of an interrupt handling system not intended to call functions.

The following fixes were done.

Fixed scope during an interrupt.


Fixed scope for new variables created during an interrupt

Exceptions

When VOLKEYS.OFF is run in the editor, the next program that is run does not reset a system flag, so volume keys stay blocked.

Fix was to reset that flag at start of a run.

BYTE.WRITE.BUFFER <file_table_nexp>, <buffer_sexp>

This enhancement converts the string to a byte array and writes the whole array at once.

The conversion (from a string to a byte array)  assumes this;

If there's anything in the high byte of the source (i.e >255) then a question mark glyph (3F) is used to mark unknown data because it can't find anything to map to.

Assignments

e.g  a[] = b[]    or    LET a[] = b[]
e.g  a$[] = b$[]


   
hBasic uses the term  "array pointer" (e.g a[] )as representing the whole array. An array pointer has no indices within the brackets. It is a reference to an array as opposed to just one element.

(This syntax is inline with traditional Basic 01.91 which already uses the syntax for some commands and functions.)
   

Evaluation (place holder for future development).

Functions can now return an Array (pointer) by adding "[]"

Array function names cannot be the same as existing non-array functions.

        e.g

        fn.def func_a$(n)[]           % define an Array Function

            dim b$[3]
            b$[2] = "nice"

            if n=1 then fn.rtn        % returns a useless default array
            if n=99 then fn.rtn b$[]  % return specified array

        fn.end                        % returns default array

        ! fn.def func_a$()            % (error) Function previously defined at:
       
        a$[] = func_a$(99)[]          % Array function assignment (deep copy)

        ! print func_a$(99)[]         % Error> Array functions cannot be evaluated :
        print a$[2]                   % only normal arrays can be evaluated with an index

Before, if TEXT.OPEN or BYTE.OPEN fails to open a file, an unusable filetable entry was still created.
This no longer happens for v2.80+, there is no new filetable entry upon failure.

First off, there is a difference between a shortcut and a fileshare.

A shortcut is a widget on the home screen that calls the app with a string of data.
Note that shortcut creation requires the app to be run once beforehand.

A file-share is a request (normally by a file-manger) to hBasic with a filename.

A) Legacy Basic only has shortcut support for a filename <something>.bas which is passed to the Standard app (i.e with editor) for execution. This is the same for hBasic (Standard).

B) hBasic also has shortcut support for StandAlone (i.e without editor) only if you had compiled the app as StandAlone with included the supporting patch H0290.

For (B), a shortcut can be created on the Android home screen. It can launch the app and send a string of data.
This feature will entertain any shortcut data string being sent by a shortcut launch and put the string into an undocumented function called COMMAND$().

Shortcuts to Standard APKs (non-standalone) will not be affected since they are always assumed to be <something>.bas.

Note that COMMAND$() is also used for a file-share data string (e.g from a file-manager) , the difference between a shortcut and a file-share is that a file-share will prepend a relative path to a file-name. Shortcut data strings are not prepended with anything, the data string is what the user typed in and is clean. The string can be any text and can have spaces, e.g "Dark Theme".

Shortcut fixes since v4.49


File-Share fixes since v4.49

Permissions Fix 1 - Android 10+




Permissions Fix 2 - Android 11+


Permissions Fix 3 - No-Grant-Run-Time-Error

SENSORS command would crash on devices with Android-10+ if (internal) parameters were less than 3.
The fix code is from aFox from a github issue.

Ack: afox - forum.

Gr.Modify Group "list" would treat the list as a polygon list of coordinates instead of a list of objects.
Fixed and tidied up code.

Ack: dkal - forum.

Status bar would not show in graphics mode, even if flagged with GR.OPEN for Android 11+ devices.
Upgraded and used new API.

The status bar flag has been superceded with Decors Flag since v4.13.

Android-11's scoped storage prevents outside access to source, data ..etc.

So an ftp server (hFTP server)  was embedded. (This is thanks to server code from MoStueck / hk University).

The new built-in ftp server (hFTP) allows any ftp-client (or plugin) to access the base
    ( /Android/data/com.rfo.hbasic ) for management of your source, data & databases files).
   
    To start the server;
    Editor menu > Start FTP server.


    To stop the server
    Editor menu > Stop FTP server.

    To change the ftp command port number
    Editor menu > Preferences > FTP server port,
        you can change the ftp command port.

    On your ftp client,
        default cmd port : 1025  2345    (since version 3.04)
        user Name     : hbasic
        password     : hbasic
        mode         : passive or active (passive recommended)
        type         : unix
        auth         : plain text

    You can also control the server programmatically with FTPS commands.

    Where are you scoped ?
    The root of the server starts at ( /Android/data/com.rfo.hbasic ).

    Server Exiting
    The server will close if;
    a) You tell it to stop via the Editor menu.
    b) hBasic is killed via the android recents list
    c) android removes it in the background.

    If hBasic is 'Exit' ed, either via Editor menu or Basic command, the server is still running.
    You will have to re-enter the hBasic app in order to stop it.
    It will be killed if android decides to remove hBasic from memory.

Due to the same functionality within DEVICE command.

Legacy Basic remembers commands per line as a form of tokenisation to circumvent future command searches. This happens only after the first execution of that command.

hBasic adds Pre-Loading by default, so that all lines have commands pre-loaded before the program starts.
This ensures that all commands start off without needing a search and with equal footing.

In legacy Basic, there were 6 seperate control stacks for loops, gosubs, if-blocks and functions.
hBasic is the first to combine 5 of them into one block control stack (BCS).
The remaining function stack is still separate but each called function gets to have it's own local BCS.

Where before, you had to make sure inner loops were exited before exiting outer loops, a central BCS can cancel all inner loops/blocks automatically.

The Rules are;

1. You can execute;
                W_R.break, D_U.break, F_N.break,
                W_R.continue, D_U.continue, F_N.continue
                RETURN
   1.a You can execute;
                REPEAT, UNTIL, NEXT,   
Loop bottoms must begin a line by itself, they cannot be part of THEN statements.

---

2. You cannot stagger an ELSE, ELSEIF or ENDIF to cancel a loop or gosub.

e.g you cannot do stuff like this

    IF a THEN
        DO
            ELSE      % Error - Misplaced ELSE
            PRINT "impossible"
        UNTIL ++a > 3
    ENDIF

---

3. You can safely use FN.RTN in the middle of  a loop, a gosub, or an IF block
    only if they started inside the function.

---

4. You can only use <x>.BREAK. , <x>.CONTINUE,
                    REPEAT, UNTIL, NEXT,
                or  RETURN
    if their headers also began inside the function

e.g
    FN.DEF myfunc()
        NEXT        % error: NEXT without FOR
    FN.END

    otherwise you will get an error.

---

5. No support for Multiple Bottoms.

e.g  you cannot do this;

    FOR a=1 TO 5
        IF a<3 THEN GOTO SKIP1
        IF a>3 THEN GOTO SKIP2
        b++
    NEXT                % true-bottom (only one)
    END

    SKIP1:
    NEXT                % false-bottom1
                        % Error> NEXT without FOR
    SKIP2:
    IF a<5 THEN NEXT    % false-bottom2 (and illegal)
                        % Error> NEXT without FOR
    ? "found 5"
    END

Instead, to make the above work, you must use <loop>.CONTINUE
which has the same effect;


        IF a<3 THEN GOTO SKIP1
        IF a>3 THEN GOTO SKIP2
        b++
    NEXT                % true-bottom (only one)
    END

    SKIP1:
    F_N.CONTINUE                % no error
    SKIP2:
    IF a<5 THEN F_N.CONTINUE    % no error

    ? "found 5"
    END

Originally, paths for FILE commands were designed for relative paths.
These paths are relative to the data directory at

      <BasePath>/App_Path/data

e.g <BasePath>/rfo-basic/data
e.g /storage/emulated/0/Android/data/com.rfo.hbasic/rfo-basic/data.

This means to get to the root directory you need a path like "../../../../../../../.."
 and this is just to get to the root.

Normally you would not need to navigate too far away from data or even rfo-basic. Also, since Android 11's, scoped storage, you probably wouldn't have access to anywhere before the BasePath.

But for rooted phones or special places where you do have access, e.g to get to internal private storage, or native library areas, using relative paths to these places can be cumbersome.

hBasic now allows Absolute Paths for these FILE operations. To specify an absolute path, just begin it with a slash '/'.

Examples

Editor GPU Acceleration.


Graphics Hardware overlay layer.

Directives are used to configure the intepreter and the console.

These directives should be put the before the start of a program together on their own.
They all start with "@@".
Any line that isn't a directive or a comment will stop directive processing and furthur directives will be ignored.

(Note: Prior to v4.13, the directive prefixes used to be a single"@". The change to "@@" is to allow through variables that start with a single "@")

Directives are processed before the a program is run. Therefore you cannot use any variables for arguments.

Directive
@@hide_actionbar	Hides the actionbar at startup
@@dark_statustxt	( replaced with console.set statustxt dark )
@@void_color "<color>"	Set the console background (void) color
@@window_bg "<color>"	Set the window background color

@@HIDE_ACTIONBAR

@@VOID_COLOR "<color>"           e.g @@void_color "blue"

@@WINDOW_BG "<color>"           e.g @@window_bg "blue"