Rev. 17 released today.

[Greg Field]

Released version :

------------------

    17.07.01

Major new features.

===================

1. Named variables.

2. 64 bit integers.

3. Maths Exceptions.

Named Variables

---------------

if ( %version% >= 170600 )

You can now create your own "named" user variables.

You can optionally assign an initial value to integers and strings.

The new commands to do these are :

INTeger    name = value

INTeger    name [ size ] = value

STRing     name = value

FSTREAM    name

DIRectory  name

These create a new integer, string, file stream and directory variable respectivly.

If the initial value is left out, integers are set to 0 and strings to NUL.

For example :

    int dozen = 12

    int three = 3

    int total

    let total = %three% * %dozen%

    echo We have a total of %total%.

    We have a total of 36.

The original user variables int#, str#, file#, dir# are still available.

They just do not need to be declared.

Named user variables, like the original user variables, are only visible at the current

stack level. That is, within a macro, subroutine or the typed command line. In this case

we mean the "main" part of a macro ; before a subroutine or other macro are called.

Integer arrays

--------------

Integers can also be a single dimension array. The initial value, if used,

sets the initial value of each element in the array.

INTeger name [ size ] = value

The integer used to select one elemnt in an array is the "subscript".

The "subscript" of the array is 0 based as in C based languages.

    int day [ 7 ]              ; rem Seven days in a week.

    let day [ 0 ] = 1

To reference an element on the left hand side of an "=", put %'s around the subscript.

To get the value of an element on the right hand side of "=", enclose the whole variable in %'s.

    int sunday = 6

    let day [ %sunday% ] = %sunday% + 1

    if ( %day [ sunday ]% == 7 )

64 bit integers.

----------------

if ( %version% >= 170000 )

All int# and named integer variables are signed 64 bit values.

Functions and constants are updated for 64 bit.

Open/ed system variables and time constants are signed 64 bit.

%INT_MIN% is the largest negative integer and %INT_MAX% is the largest positive integer.

%INT_MIN% = -9223372036854775808

%INT_MAX% =  9223372036854775807

The constants %RAND_LIMIT_MIN% and %RAND_LIMIT_MAX% govern the RANDOM() function.

These are the smallest and largest values that RANDOM ( upper_limit ) can be set to.

The new constantd %EO_TIME% is the largest integer that can be passed to STRTIME().

TIMESTR () has been renamed to STRTIME ().

Maths Exception handling

------------------------

if ( %version% >= 170000 )

A maths exception is when an integer maths expression can not evaluate

to an integral number between %INT_MIN% and %INT_MAX%.

When a maths exception happens, a special variable such as %math.over% is incremented to be

greater than zero. These variables are sometimes referred to as flags but are no different

to other variables. The action taken is controlled by the MATHERROR mode.

For example :

: no mather

: let int1 = %INT_MAX%

: let int1 = %int1% + 1

: if ( %math.over% )

:      rem Take action ....

: endif

: mode mather

: let int1 = %INT_MAX%

: let int1 = %int1% + 1

? Maths overflow : "1".

  This integer addition would cause an overflow.

  Command line : "let int1 = %int1% + 1"

  No macro was running.

In the first example MODE MATHERROR is off. The first LET sets int1 to

%INT_MAX%, the largest possible positive integer. The second LET

overflows int1. There is no error message and macro execution continues.

However he variable %math.over% is true and we can take what ever action

we need.

The second example is with MODE MATHERROR on. The first LET sets int1 to

%INT_MAX%. The second LET overflows int1. This time an error message is

printed and the macro stops.

The maths exceptions are ...

%math.over%

    An integer calculation overflowed the %INT_MAX% value or

    an integer calculation underflowed the %INT_MIN% value.

    Here after the term overflow includes underflows.

    Raised by :

      LET +, -, or *.

      INC or DEC.

      PI() or POW( ) when the result overflows %INT_MAX% or %INT_MIN%.

      When an integer literal is too large (+ or -) for Open/ed.

      Any ( condition ) that uses these.

      When a DO loop step exceeds %INT_MAX% or %INT_MIN%.

      When an integer larger than %EO_TIME% is passed to STRTIME().

      When use of the counter @ causes an overflow (or underflow).

    Result :

      If NO MATHER

        - No error message is printed,

        - The target integer value is set to %INT_MAX%.

        - The macro keeps running.

        - If in a DO loop, the loop terminates.

      If MODE MATHER

        - An error message is printed,

        - The target integer value is not changed.

        - The macro stops running.

        - If in a DO loop, the loop terminates.

%math.div%

    An integer calculation is doing a divide by zero.

    This could be from either a '/' or '%' division.

    Raised by :

      LET / or %.

      It is also raised by any ( condition ) that uses these.

    Result :

      If NO MATHER

        - No error message is printed,

        - The target integer value is set to 0.

        - The macro keeps running.

      If MODE MATHER

        - An error message is printed,

        - The target integer value is not changed.

        - The macro stops running.

%math.inf%

    An integer calculation results in infinity.

    Raised by :

      POW ( ).

      The POW ( ) function is 0 to the power of a negative number.

      It is also raised by any ( condition ) that uses this.

    Result :

      If NO MATHER

        - No error message is printed,

        - The target integer value is set to %INT_MAX%.

        - The macro keeps running.

      If MODE MATHER

        - An error message is printed,

        - The target integer value is not changed.

        - The macro stops running.

%math.nan%

    An integer calculation results in "not a number".

    Raised by :

      SQRT ( )

      The SQRT ( ) function is taking the square root of a negative number.

      It is also raised by any ( condition ) that uses this.

    Result :

      If NO MATHER

        - No error message is printed,

        - The target integer value is set to 0.

        - The macro keeps running.

      If MODE MATHER

        - An error message is printed,

        - The target integer value is not changed.

        - The macro stops running.

All four flags are cleared by a LET command.

Also the %math.over% flag is cleared by an INC or DEC command.

Warning : the %math.xxx% exception variables will be (0) for false

or non zero, 1 or more, for true. Do not test for %math.xxx% == 1 !

DO exceptions

-------------

DO loops are terminated by a +ve step calculation exceeding %INT_MAX%

or a -ve step calculation exceeding %INT_MIN%.

: do int1 = %INT_MAX%-1 , %INT_MAX% , 10

:     echo  Index var int1 = %int1%.

: endo

: echo    Overflow flag is %math.over%.

    Index var int1 = 9223372036854775806.

    Overflow flag is 1.

This DO loop will loop once then terminate. The first time, %int1% will

be set to one less than INT_MAX. The step calculation the second time

around will exceed %INT_MAX% by 9 and control passes to after the ENDO.

%math.over% will be at least 1.

The math exception function

---------------------------

  let int# = MATHEXC ( )

  if (  MATHEXC ( ) ) ; ... ; endif

      This function returns true if any math exception flag is true (non-zero).

      Otherwise all flags are false (0) and it returns false (0).

  Warning : The four %math.xxx% flags are cleared by a LET or INC or DEC.

  Test MATHEXC ( ) after the possible exception but before another one

  of these commands.

The math exception mode

-----------------------

  MODE MATHERROR

 This mode causes any maths exception to print an error message and stop

 the macro running. The abbreviation is MATHER.

 If disabled (the default) there are no error messages and the macro keeps

 running. You must examine MATHEXC ( ) or the %math.xxx% variables.

 This mode does not effect setting the math exception flags. These are

 still set. It only effects that an error message is printed and the macro

 stops execution.

 If you are running in MODE MATHER, then there may seem to be no point

 examining the %math.xxx% flags as the error message will stop the macro

 before hand. However it is better to code your macro to check maths

 exceptions and only use MODE MATHER while debugging the macro.

 Having MATHERROR off by default may appear to go against the design goal

 of enabling modes for safety, but there are good arguments on both sides.

 For example a DO loop increment may cause a benign overflow that causes

 an important macro to print an error and stop. This makes the macro less

 reliable. It is better to debug the new macro with MODE MATHER enabled,

 then in production, run in default with it off.

 If you need to run part of your macro in MATHER mode, add the following

 code.

    let int7 = mode ( 'MATHERROR' )  ; rem Restore mode mather later if it was set.

    MODE MATHER

    .... Code that runs in MATHER mode.

    if ( %int7% ) ;  NO MATHERROR ;  endif

Program options

---------------

None

Commands :

----------

Tidy SHIFT and SBEFORE to allow S* or SB* without an intervening space.

Column now defaults to *, the current column.

The EXIT command now uses %ERCODE% constants rather than ECODE arguments.

APROPOS command to search for HELP entries.

HELP command uses the same system.

INTEGER         See "Named variables".

STRING          See "Named variables".

FSTREAM         See "Named variables".

DIRECTORY       See "Named variables".

TAG GLIST. New format for a tag list file for grep'ed output.

UMASK   DEFault     (Abbrev = def )

        You can now specify "default" to change the umask to its default.

Modes

-----

MODE MATHERROR controls how maths exceptions are handled.

MODE SCROLLBAR displays a clickable positioning bar to screen mode. (Very cool).

MODE SHORTEDITMENU prints terser "Edit" menu prompts that are quicker for experienced users.

Rename MODE WINKBOLD to MODE KLIST. More options.

Add MODE SINGLECLICK. Menus etc that required a double-click now work on one click.

(Recomended only for experienced users).

MODE LONGER changed to MODE SHORTER and long error messages now the default.

Functions

---------

MATHEXC ( ) to test for any maths exceptions.

TIMESTR() renamed to STRTIME().

KBINT () is updated to handle up to Exabyte values.

COUNT ( array ) added to return array size.

NUMBASE () to determine a numerical strings base.

TEMPOPEN () to open a temp file.

FOPEN flags default to "r".

TEMPOPEN flags default to "w".

  Rename ISNUL() to NUL(), add synonym NONE().

  Add Synonym NO() for NOT().

PEEK () to get a character in text body.

POKE () to set a character in text body.

LENGTH() is added returning the string length not counting trailing spaces.

STRLEN() is unchanged, reporting the string length including tailing spaces.

UMASK() When setting a new umask, it now returns the same value for success.

Maths operators

---------------

None.

Symbols

-------

None.

Macros

------

'postcompile' updated so if no compile errors, it looks for grep listing 'grep.glist'.

Variables

---------

New variables :

        Variable :      %math.over%

        Result :        If true, a maths overflow exception has occurred.

        Variable :      %math.div%

        Result :        If true, a maths divide by 0 occurred.

        Variable :      %math.inf%

        Result :        If true, a maths result was infinity.

        Variable :      %math.nan%

        Result :        If true, a maths "not a number" has occurred.

        Variable :      %disp.mode%

        Result :        The current value of MODE DISPLAY.

        Variable :      %stack.index%

        Result :        The depth of nested macro calls.

                        2 = The first macro.

                        3 = The second called macro.

                        1 = No macro is running ; we are at the command line.

        Variable :      %tag.list.type%

        Result :        If the tag list file is none, SLIST, CLIST or GLIST.

        Variable :      %tag.list.file%

        Result :        File name of tag list. If none, then variable is NUL.

        Variable :      %/%

        Result :        The slash character or its file system equivalent on other OS.

Renamed variables :

        Variable :      %sev% the compile error severity in TA CLIST is

                        renamed to %severity%.

        Variable :      %level% the level of nested NED commands is

                        renamed %session.level%.

                        %session.level% now starts at 1 rather than 0.

  Use of @ count can now cause a %math.over% exception.

Constants

---------

Add %EO_TIME% "End of Time", the largest integer time.

Add %ERR% constant returned by GETCHAR( ).

Flip constant names %MAX_INT% %MIN_INT% to %INT_MAX% %INT_MIN%.

What type of TAG LIST file ? Compare to %tag.list.type%.

      %TAG_NOLIST%      If %tag.list.type% == %TAG_NOLIST%, then there is no TAG LIST file.

      %TAG_SLIST%       If %tag.list.type% == %TAG_SLIST%, then there is a simple TAG LIST file.

      %TAG_CLIST%       If %tag.list.type% == %TAG_CLIST%, then there is a C-lang TAG LIST file.

      %TAG_GLIST%       If %tag.list.type% == %TAG_GLIST%, then there is a grep'd TAG LIST file.

%RAND_LIMIT_MIN%

%RAND_LIMIT_MAX%

      These are the smallest and largest "limit" that can be passed to the RANDOM() function.

      %RAND_LIMIT_MIN%  is currently 2.

%OSX% has been renamed %MACOS%.

Added %DEFAULT_UMASK% the default umask.

Bug fixes.

--------

Fix to remove leading and trailing spaces from file names SAVEd or UNLOADed.

Add more break key handling to macro commands especially WHILE/ENDWHILE.

Was generating cryptic "stack error" "endCOMMAND not found" messages.

Fix : FROM 0 was not clearing a block.

IISINPUT is now supported in OLDED mode.

Fix : Negative DO step was not working.

Add : KEY_SBEG KEY_SEND.

Fix : FUN_EXEC was not remembering last choice.

Fix : notice file was not displaying.

Fix : FUN LIST gets "Not enough lines". Fixed by new menu pick feature.

Fix : NEW *.c was retruingin junk in filename.

Fix : UX/DX was unloading trailing spaces.

Fix : DUP was not working on bottom.null when FROM/TO set.

Fix : echo %%a%% %a% was returning ABC %a%.

Fix : UMASK <return> was not displaying the current umask.

Other

-----

  Screen mode .null. lines are italic which is supported on _LNX_.

  When not supported (_OSX_), they are dim.

  Key list windows such as HELP now use an improved scrolling window.

  Wildcard filenames (ex NEW *.c), now use the new Window Klist feature.

  NOTICE command now uses the new Window Klist feature.

  Added leap second detector for screen mode.

  Pop up message in screen mode and in the ACTIVE status bar,

  the time zone information is replaced by a leap second message.

   "Help" button has been added to screen mode long error messages.

   Clicking it takes you to the mentioned help page.