ChangeLog

ChangeLog
---------

Version 0.5.0 - 3-Feb-2023:
  - Changed to semantic versioning scheme.
    Note that MMB4L is still versioned independently of Geoff and Peter's
    "mainline" MMBasic platforms.
        - MM.INFO(VERSION) will return the integer 5000000 for this release,
          divide by 10000000 to get float equivalent, e.g. 0.5
        - MM.INFO(VERSION MAJOR) will return major version, 0 for this release.
        - MM.INFO(VERSION MINOR) will return minor version, 5 for this release.
        - MM.INFO(VERSION MICRO) will return minor/patch version, 0 for this
          release.
        - MM.INFO(VERSION BUILD) will return the build number, 0 for this
          release and only included for use in some theoretical future.
  - Added "automatic path completion" to the MMBasic prompt.
        - Pressing TAB will attempt to complete (as far as can be unambiguously
          determined) a filename that the user is typing at the prompt, or sound
          the console bell if no completion is possible.
  - Added MM.INFO(CALLDEPTH) to return the current function/subroutine call
    depth.
        - 0 when at the global level, i.e. not in a function/subroutine.
        - Primarily for debugging purposes, though a possible production
          use-case would be to allow a program to "bail out" if recursion gets
          too deep.
  - Added MM.INFO(PID) to get the process ID of the MM4L process.
  - Added MM.INFO(CPUTIME) to get the value (in nanoseconds) of the CPU timer
    for the MMB4L process.
  - Changed function, label, subroutine and variable lookup to use hashmap.
        - Depending on the problem this might be expected to produce a 3-5%
          improvement in performance.
  - Changed syntax of RUN command to:
        RUN [file$] [, cmdline$]
    Both file$ and cmdline$ can now be string expressions instead of
    the legacy behaviour where the command line argument was "not processed" by
    MMBasic and was copied verbatim into the MM.CMDLINE$ of the new program.
        - This change means that cmdline$ can now be constructed from other
          variables and functions instead of having to be hardcoded, or
          finessed by using EXECUTE to construct the RUN statement.
        - If the text following the comma contains an unquoted minus sign then
          for backward compatibility MMB4L trys to use the legacy behaviour,
          but this does not work for all possible legacy command lines.
    Note that the behaviour of the * command is unchanged; expressions in any
    command line provided via * are not evaluated by MMB4L, e.g.
        *foo a$ + b$
    is equivalent to:
        RUN "foo", "a$ + b$"
  - Changed RUN file$ so that it is not necessary for file$ to have a ".bas"
    extension.
        - If file$ does not exist then will try appending the extensions
          ".bas", ".BAS" and ".Bas" in turn.
  - Changed #INCLUDE "<file>" so that it is not necessary for <file> to have
    a ".inc" extension.
        - If <file> does not exist then will try appending the extension
          ".inc", ".INC" and ".Inc" in turn.
  - Changed XMODEM to improve read/write performance.
        - It now reads/writes 128 characters at a time instead of 1.
  - Changed MMBasic prompt so that you can access the history with the up
    and down cursors even after you start typing a command.
  - Changed some error messages to be clearer and/or more specific.
  - Changed "mmbasic.syntax.nanorc" to improve syntax highlighting of comments.
        - Even so it is still not 100% correct.
  - Fixed bug where relative #INCLUDE files could not be found when running
    a symbolic link to an MMBasic file.
        - The path to the #INCLUDE files was incorrectly being resolved relative
          to the parent of the symbolic link instead of the parent of the target
          file.
  - Fixed several bugs with identifiers allowing / being limited to 32
    characters (not including variable/function type suffix).
  - Fixed bug with GOSUB/RETURN corrupting the interpreter state when using
    ON ERROR SKIP.
  - Fixed bug where function returns corrupted the interpreter state when using
    ON ERROR SKIP.
  - Fixed bug where an "Internal fault" error would be reported immediately if
    the console/tty dimensions could not be determined when displaying the
    MMBasic prompt.
        - This can be a transient problem so MMB4L now retries for 1 second
          before reporting a "Cannot determine terminal size" error.
  - Fixed bug in OPTION LIST for F<num> function key options whose values
    contained carriage-return character.

Version 2022.01.00-a4 - 15-May-2022:
  - MMB4L is now open-source and licensed under a modified 4-clause BSD license
    similar to that for the PicoMite firmware and MMBasic for Windows. See the
    LICENSE file for details. My thanks to Geoff and Peter for allowing this to
    be possible.
  - Added * command which may be used at the MMBasic prompt (but not within
    programs) as a short-cut for RUN, e.g.
        *foo --bar "wombat"
    is translated to:
        RUN "foo", --bar "wombat"
  - Added ! command which may be used at the MMBasic prompt (but not within
    programs) as a short-cut for SYSTEM, e.g.
        !cp foo bar
    is translated to:
        SYSTEM "cp foo bar"
    An exception is !cd, e.g.
        !cd foo
    is translated to:
        CHDIR "foo"
    This is required because "!cd foo" would otherwise appear to do nothing
    due to the fact that each SYSTEM command is run in the context of a separate
    forked process instead of the MMBasic process itself.
  - Added SYSTEM sub-commands for getting and setting environment variables:
        - SYSTEM GETENV name$, {value$ | value%()}
        - SYSTEM SETENV name$, {value$ | value%()}
    This supplements MM.INFO$(ENVVAR) because it allows values > 255 characters
    to be read into a LONGSTRING.
  - Added option persistence to file "~/.mmbasic/mmbasic.options" for all
    options except for BASE, BREAK, CASE, CODEPAGE, CONSOLE, EXPLICIT and
    RESOLUTION:
        - only options that differ from their defaults are saved to this file.
  - Added OPTION EDITOR <editor> command to change the EDITor.
    Supported editors are:
        - ATOM
        - CODE     (synonym for VSCODE)
        - DEFAULT  (synonym for NANO)
        - GEANY
        - GEDIT
        - LEAFPAD
        - NANO
        - SUBLIME
        - VI
        - VIM
        - VSCODE
        - XED      (untested because I couldn't get a version for Ubuntu 21.)
        - or a string specifying a command to run, e.g.
              OPTION EDITOR "code -g ${file}:${line}"
          ${file} is a placeholder for the filename to edit, the filename will
                  be automatically enclosed in double-quoted.
          ${line} is a placeholder for the line number to set the initial
                  cursor position to.
  - Added OPTION F<num> string$ sub-commands to define the strings that will be
    generated when pressing function keys at the MMBasic prompt:
        - all of F1-F12 can be redefined.
        - beware that some function keys may be captured by the Linux window
          manager and never passed on to MMBasic.
  - Added OPTION SEARCH PATH <path> command as per CMM2.
  - Added OPTION {SAVE | LOAD} <filename> command.
  - Added OPTION RESET {ALL | <option>} command.
  - Added PEEK(DATAPTR) function and POKE DATAPTR ptr% command for getting
    and setting the DATA read pointer.
  - Added READ {RESTORE | SAVE} command for pushing and popping the DATA read
    position to an internal stack as per PicoMite.
  - Changed OPTION LIST to only show options that differ from their defaults:
         - use OPTION LIST ALL to list all options.
  - Changed OPTION <option> <value> command so that for all options with
    enumerated values the value can now be supplied as a string, e.g.
        OPTION CODEPAGE NONE
        OPTION CODEPAGE "NONE"
        DIM none$ = "NONE"
        OPTION CODEPAGE none$
  - Changed RESTORE command to support targets given as string or number
    expressions as per PicoMite.
  - Changed SYSTEM execute command to have a 3rd optional argument to capture
    the exit status of the executed command, e.g.
        SYSTEM command$, out$, exit_status%
        SYSTEM command$, out%(), exit_status%
    The SYSTEM command now only reports an error if it cannot run the command.
    If the command runs but fails then no error is reported and the failure
    code will be captured in exit_status%.
  - Changed LOAD and RUN so that if a filename without a [.bas|.BAS|.Bas]
    extension is not provided then one is automatically appended:
        - unlike other MMBasic ports MMB4L has a case-sensitive file-system
          and expects MMBasic program files to have one of three possible
          extensions: .bas, .BAS, or .Bas.
        - if no extension is specified then MMB4L will check for the existence
          of a file with each extension in order, if no such file is found then
          it assumes the .bas extension.
  - Changed assignment of values to MM.ERRNO, they are now:
           0      : no error.
       1  ..  255 : standard error numbers (errno) for C library calls.
          256     : unclassified MMBasic error.
      257 .. 1023 : other standard MMBasic errors.
         1024+    : recommended range for program specific errors.
  - Removed LS as an alias of FILES:
        - LS was a non-standard aberration inherited from the CMM2.
        - use !ls instead to execute the 'ls' Linux shell command with all its
          power and with no requirement to enquote its arguments.
  - Fixed bug where could not open non-existing file for RANDOM access.
  - Fixed bug where when one program tried to RUN another it would resolve the
    path to the new program from the current program directory instead of from
    the current working directory.
  - Fixed bugs in interaction between ON ERROR and interrupts.
    The normal thread of execution and the execution of interrupts now maintain
    independent error states.
  - Fixed bug where MM.ERRMSG$ would contain trailing newline character after
    an uncaught ERROR.
  - Fixed more issues with "mmbasic.syntax.nanorc".

Version 2022.01.00-a3 - 16-Jan-2022:
  - Added serial port support, e.g.
        OPEN "/dev/ttyS0: 115200" As #1
    this is very preliminary and in need of extensive user testing,
    see README for details.
  - Added XMODEM {SEND | RECEIVE} file$, #fnbr command:
    - #fnbr must first have been OPENed as a serial port.
    - unlike other MMBasic versions, MMB4L cannot use XMODEM to send to or
      receive from the console.
  - Added OPTION CODEPAGE page$ command:
    - causes character bytes in the range 128-255 to be translated to Unicode
      (UTF-8) when printed to the console according to a given code page /
      mapping.
    - supported values of page$ are currently:
      - "NONE"   : no mapping, characters 128-255 are written as-is.
      - "CMM2"   : best effort mapping to the characters of the CMM2 font.
      - "CP437"  : characters 128-255 of the original IBM PC code 437.
                   Note this was a non-ANSI code page which also included
                   characters 1-31 which are not available in this mapping,
                   but see "MMB4L".
      - "CP1252" : the classic Windows-1252 Latin alphabet code page.
      - "MMB4L"  : as "CP437" but with characters 129-159 replaced by the
                   original non-ANSI CP437 characters 1-31 and with additional
                   "useful" characters in positions 128, 161-170 and 255.
  - Added CHR$(UTF8 codepoint%) function:
    - given a Unicode code-point this returns the 1-4 character string encoding
      that character in UTF-8 format.
    - printing such characters is not compatible with OPTION CODEPAGE being
      set.
  - Added AUTOSAVE file$ command:
    - note that as with the CMM2 there is no CRUNCH option; AUTOSAVE writes to a
      file and MMB4L always crunches the program automatically when it loads it
      for execution.
  - Added CONSOLE SETSIZE [ATLEAST] width%, height% command:
    - sends an XTerm control sequence to set the terminal size.
    - if the optional ATLEAST modifier is used then this will not reduce the
      terminal width or height.
  - Added PRINT @(x%, y%) expression:
    - unlike the CMM2, x% & y% are obligatory and in character coordinates,
      there is no mode parameter.
    - equivalent to:
        CONSOLE SETCURSOR x, y : PRINT expression
  - Added missing LIST FILES command:
    - just another synonym for FILES and LS and only present for compatibility
      with the CMM2.
  - Changed SYSTEM command to allow standard output to be captured in a STRING
    (as an alternative to existing functionality to capture it in a LONGSTRING),
    e.g.
        DIM out$
        SYSTEM "echo `date`", out$
        PRINT out$
    Also any trailing whitespace, including CRLF is now trimmed from the
    captured STRING or LONGSTRING output.
  - Changed EOF() function to return 1 when at the end of file (like the CMM2),
    previously it returned -1.
  - Fixed bug so that MEMORY COPY command correctly handles overlapping source
    and destination.
  - Fixed bug with MM.INFO$(...) not being recognised in interactive mode:
    - synonym for MM.INFO(...).
    - interim fix pending rewrite of pre-processor and its use from interactive
      mode.
  - Fixed bug where error messages over 127 characters would overflow into
    the storage for MM.CMDLINE$
    - error messages are now truncated to 127 characters.

Version 2021.01.00-a2 - 6-Nov-2021:
  - Added ability to specify at the Linux shell a BASIC program that MMB4L
    should RUN when it starts, e.g.
        ./mmbasic myprogram.bas arg1 arg2 arg3
    see README for details.
  - Added optional integer argument (default 0) to END and QUIT that can be
    used to return an exit code to the Linux shell, see README for details.
  - Added SETTICK command from the CMM2:
    - SETTICK FAST is not supported.
    - Be aware that Since Linux is not a Real Time Operating System all timing
      commands such as PAUSE and SETTICK are subject to more error and variation
      than on the microcontroller MMBasic implementations.
  - Added JSON$() function from the CMM2:
    - MMB4L adds an optional 3rd parameter which is a 2 bit argument controlling
      how explicit nulls and missing values are handled in the JSON:
        - &b00 : return empty strings for both.
        - &b01 : return "<null>" for explicit null.
        - &b10 : return "<missing>" for missing value.
        - &b11 : return both "<null>" and "<missing>".
  - Added DAY$(), DATETIME$() and EPOCH() functions from the CMM2:
    - note that unlike DATE$ and TIME$ the DATETIME$(NOW) function will return
      the date & time in UTC, not in the local timezone.
  - Added missing MEMORY, PEEK and POKE sub-commands.
    Now implements the same as the CMM2 (5.07.01) with the exception of the
    undocumented/legacy:
        PEEK(hiaddr, loaddr)
        POKE hiaddr, loaddr, byte
    And with the addition of:
        MEMORY COPY BYTE src, dst, number_of_bytes
          - which is equivalent to MEMORY COPY src, dst, number_of_bytes
        MEMORY COPY SHORT src, dst, number_of_shorts
        MEMORY COPY WORD src, dst, number_of_words
  - Added optional integer array parameter to SYSTEM command to allow any
    standard output generated to be captured in a LONGSTRING, e.g.
        DIM out%(100)
        SYSTEM "ls", out%()
        LONGSTRING PRINT out%()
  - Added support for prefixing paths with '~' which is expanded to the
    users home directory (the value of the HOME environment variable).
  - Added optional integer argument (default 1) to ERROR command allowing an
    error code to be specified, this can be retrieved using MM.ERRNO, e.g.
        ERROR "error message", 220
    For MMB4L the values of MM.ERRNO are:
      - 0        : no error.
      - 1        : unclassified MMBasic error, also reported if a C library call
                   reports the error EPERM (Operation not permitted).
                   Note this differs from other versions of MMBasic which use
                   the value of 16 for general errors, this would correspond to
                   the EBUSY (Device or resource busy) error from a C library
                   call.
      - 2..150   : standard error numbers (errno) for C library calls.
      - 151..200 : reserved for future classification of MMBasic errors.
      - 201..255 : suggested range for program specific error codes.
      - error codes from the SYSTEM command are an exception to this rule,
        see the next entry.
  - Changed SYSTEM command to set MM.ERRNO equal to the executed program's
    exit code. Also changed error message to include this value.
  - Changed CONSOLE SETCURSOR command to allow a maximum x, y of 1023
    (previously 255) and updated "examples/mandelbrot.bas" to support this.
  - Changed "mmbasic.nanorc" to make behaviour more like the CMM2 editor:
      - added 'set constantshow' so the cursor position display is always
        visible.
      - added 'set zap' so that [Delete] and [Backspace] erase all the selected
        text instead of just a single character.
      - either of these can be commented out with # if you prefer.
  - Fixed issues with "mmbasic.syntax.nanorc":
      - command keywords always highlighted, not just when they are the first
        token on a line.
      - hexadecimal and binary constants highlighted as numbers (green).
      - comments correctly highlighted following string constants containing
        apostrophes.
      - highlighting of additional keywords.
  - Fixed timeout bugs with CONSOLE GETCURSOR:
      - increase the timeout to 10s.
      - correct the signed 64-bit arithmetic used in timing code.
  - Fixed bug where navigating the MMBasic prompt history with up/down arrow
    keys would show display artifacts when using PuTTY; though not sure why
    the issue was not generally visible.
  - Many other fixes and tweaks for minor issues encountered along the way.

Version 2021.01.00-a1 - 23-Sep-2021:
  - First alpha version.