improve calc error code system

Added help/errorcodes rule to the top level Makefile. Added E_USERMAX symbol (== 32767) to indicate the maximum value allowed for user error codes. Improve help/error. Added text about error code ranges and range symbols.
2025-08-19 01:13:27 +03:00 · 2023-09-12 14:08:49 -07:00
parent 4c65986502
commit 19819340ff
6 changed files with 105 additions and 17 deletions
--- a/8
+++ b/8
@@ -213,6 +213,14 @@ The following are the changes from calc version 2.14.3.5 to date:
 	E_FUNC COMPLEX *c_sec(COMPLEX *c, NUMBER *eps);
 	E_FUNC COMPLEX *c_cot(COMPLEX *c, NUMBER *eps);

+    Added help/errorcodes rule to the top level Makefile.
+
+    Added E_USERMAX symbol (== 32767) to indicate the maximum value
+    allowed for user error codes.
+
+    Improve help/error.  Added text about error code ranges and
+    range symbols.
+

 The following are the changes from calc version 2.14.3.4 to 2.14.3.5:

--- a/12
+++ b/12
@@ -325,7 +325,8 @@ STATIC_FIRST_TARGETS= ${LICENSE} .static
 # late targets - things needed after the main build phase is complete
 #
 LATE_TARGETS= calc.1 calc.usage \
-	      cal/.all help/.all help/builtin cscript/.all
+	      cal/.all help/.all help/builtin help/errorcodes \
+	      cscript/.all

 # calc tools - tools used by the maintainers of the calc source base
 #
@@ -2465,6 +2466,15 @@ help/builtin: help/Makefile \
 	${V} echo '=-=-=-=-= Back to the main Makefile for $@ rule =-=-=-=-='
 	${V} echo '=-=-=-=-= ${MAKE_FILE} end of $@ rule =-=-=-=-='

+help/errorcodes: help/Makefile \
+	      calcerr.h help/errorcodes.hdr help/errorcodes.sed
+	${V} echo '=-=-=-=-= ${MAKE_FILE} start of $@ rule =-=-=-=-='
+	${V} echo '=-=-=-=-= Invoking builtin rule for help =-=-=-=-='
+	${RM} -f $@
+	cd help; ${MAKE} -f Makefile errorcodes
+	${V} echo '=-=-=-=-= Back to the main Makefile for $@ rule =-=-=-=-='
+	${V} echo '=-=-=-=-= ${MAKE_FILE} end of $@ rule =-=-=-=-='
+
 cscript/.all: ${CSCRIPT_TARGETS}

 ${CSCRIPT_TARGETS}: cscript/Makefile
--- a/calcerr_c.awk
+++ b/calcerr_c.awk
@@ -2,7 +2,7 @@
 #
 # calcerr_c - help produce calcerr.c from calcerr.tbl
 #
-# Copyright (C) 1999  Landon Curt Noll
+# Copyright (C) 1999,2023  Landon Curt Noll
 #
 # Calc is open software; you can redistribute it and/or modify it under
 # the terms of the version 2.1 of the GNU Lesser General Public License
@@ -34,12 +34,12 @@ BEGIN {
    printf(" * names of calc error values\n");
    printf(" */\n");
    printf("CONST char *error_table[E__COUNT+2] = {\n");
-    printf("	\"No error\",\n");
+    printf("    \"No error\",\t\t/* MUST be first */\n");
 }
 {
    print $0;
 }
 END {
-    printf("	NULL\n");
+    printf("    NULL\t/* MUST be last */\n");
    printf("};\n");
 }
--- a/calcerr_h.awk
+++ b/calcerr_h.awk
@@ -43,6 +43,7 @@ NF > 1 {
 END {
    printf("\n#define E__HIGHEST\t%d\t/* highest calc error */\n", NR+ebase);
    printf("#define E__COUNT\t%d\t/* number of calc errors */\n", NR);
-    printf("#define E_USERDEF\t20000\t/* base of user defined errors */\n\n");
+    printf("#define E_USERDEF\t20000\t/* base of user defined errors */\n");
+    printf("#define E_USERMAX\t32767\t/* maximum user defined error value */\n\n");
    printf("/* names of calc error values */\n");
 }
--- a/help/error
+++ b/help/error
@@ -5,30 +5,97 @@ SYNOPSIS
    error([n])

 TYPES
-    n		integer, 0 <= n <= 32767; defaults to errno()
+    n		integer, defaults to errno()

    return	null value or error value

 DESCRIPTION
+    If n == 0:

-    If n is zero,  error(n) returns the null value.
+	error(n) returns the null value.

-    For positive n, error(n) returns a value of error type n.
+	The "global calc_errno value" is set to 0.

-    error(n) sets calc_errno to n so that until another error-value
-    is returned by some function, errno() will return the value n.
+	The global calc error count is not changed.
+
+    For 0 < n <= 32767:
+
+	error(n) returns a value that is of a special type called
+	"error".  The "error" return value, when given to iserror()
+	will cause that function to return a true value that happens
+	to match the "global calc_errno value".
+
+	The "global calc_errno value" is then set to n.
+
+	The global calc error count (see help errcount) is incremented.
+	If the global calc error count exceeds the maximum count
+	(see help errmax), any ongoing calc execution is aborted.
+
+    All other values of n are reserved for future use and currently
+    will generate an error.
+
+    The term "global calc_errno value" is an internal calc state.
+    This is NOT a calc variable called calc_errno.
+
+    The "global calc_errno value" be set to some other non-zero
+    value by other builtin functions and calculations, especially
+    if they result in an error.  Thus, while calling errno(n) may
+    set calc_errno, some other error may later overwrite the
+    "global calc_errno value".
+
+    By convention, the "global calc_errno value" has the following ranges:
+
+	n < 0			Reserved for future use
+
+	n == 0			calc_errno cleared: libc errno codes above here
+
+	1 <= n <= 9999		system error and libc errno codes
+
+	n == 10000		Reserved for "No error" calc internal state
+
+	10001 <= n <= E__HIGHEST	calc computation error codes
+
+	E__HIGHEST < n < 20000		Reserved for future calc error codes
+
+	20000 < n <= 32767		User defined error codes start here
+
+	n >= 32768		Reserved for future use
+
+    The following constants are part of the calc error code mechanism:
+
+	E__BASE == 10000
+	E_USERDEF == 20000
+	E_USERMAX == 32767
+	E__BASE < E__HIGHEST < E_USERDEF
+	E__COUNT == E__HIGHEST - E__BASE
+
+    See help errorcodes for the actual values of the above constants.

 EXAMPLE
-    ; errmax(errcount()+1)
-	   20
+    ; errcount(0),; errmax(20),;
+    ; print errcount(), errmax()
+    0 20
+
    ; a = error(10009)
-    ; a
-	   Error 10009
+
+    ; print errcount(), errmax()
+    1 20
+    ; print a
+    Error 10009
+    ; print iserror(a)
+    10009
    ; strerror(a)
 	   "Bad argument for inverse"

+    ; b = error(0)
+
+    ; print errcount(), errmax()
+    1 20
+    ; print isnull(b)
+    1
+
 LIMITS
-    none
+    0 <= n <= 32767

 LINK LIBRARY
    none
@@ -37,7 +104,7 @@ SEE ALSO
    errcount, errmax, errorcodes, iserror, errno, strerror, newerror,
    stoponerror

-## Copyright (C) 1999-2006  Landon Curt Noll
+## Copyright (C) 1999-2006,2023  Landon Curt Noll
 ##
 ## Calc is open software; you can redistribute it and/or modify it under
 ## the terms of the version 2.1 of the GNU Lesser General Public License
--- a/help/errorcodes.hdr
+++ b/help/errorcodes.hdr
@@ -1,6 +1,6 @@
 Calc generated error codes (see the error help file):

-## Copyright (C) 1999  Landon Curt Noll
+## Copyright (C) 1999,2023  Landon Curt Noll
 ##
 ## Calc is open software; you can redistribute it and/or modify it under
 ## the terms of the version 2.1 of the GNU Lesser General Public License
@@ -21,3 +21,5 @@ Calc generated error codes (see the error help file):
 ##
 ## chongo <was here> /\oo/\	http://www.isthe.com/chongo/
 ## Share and enjoy!  :-)	http://www.isthe.com/chongo/tech/comp/calc/
+    0		calc_errno cleared: libc errno codes above here
+    10000	calc errors start above here