@jdeighan/coffee-utils 4.1.13 → 4.1.17

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@jdeighan/coffee-utils",
 	"type": "module",
-	"version": "4.1.13",
+	"version": "4.1.17",
 	"description": "A set of utility functions for CoffeeScript",
 	"main": "coffee_utils.js",
 	"exports": {
@@ -10,6 +10,7 @@
 		"./log": "./src/log_utils.js",
 		"./block": "./src/block_utils.js",
 		"./indent": "./src/indent_utils.js",
+		"./stack": "./src/call_stack.js",
 		"./debug": "./src/debug_utils.js",
 		"./svelte": "./src/svelte_utils.js",
 		"./test": "./src/UnitTester.js",
@@ -18,6 +19,9 @@
 	"engines": {
 		"node": ">=12.0.0"
 	},
+	"ava": {
+		"verbose": false
+	},
 	"scripts": {
 		"build": "cls && rm -f ./src/*.js && coffee -c ./src",
 		"old_pretest": "npm run build && rm -f ./test/*.js && rm -f ./test/*.coffee && cielo -fq ./test",
@@ -40,7 +44,7 @@
 	},
 	"homepage": "https://github.com/johndeighan/coffee-utils#readme",
 	"dependencies": {
-		"ava": "^3.15.0",
+		"ava": "^4.0.0",
 		"cross-env": "^7.0.3",
 		"js-yaml": "^4.1.0",
 		"readline-sync": "^1.4.10"

package/src/call_stack.coffee

@@ -0,0 +1,46 @@
+# call_stack.coffee
+
+import {undef, croak} from '@jdeighan/coffee-utils'
+import {log} from '@jdeighan/coffee-utils/log'
+
+# ---------------------------------------------------------------------------
+
+export class CallStack
+
+	constructor: () ->
+
+		@reset()
+
+	# ........................................................................
+
+	call: (funcName, hInfo) ->
+
+		@lStack.push({funcName, hInfo})
+		return
+
+	# ........................................................................
+
+	returnFrom: (fName) ->
+
+		if @lStack.length == 0
+			croak "returnFrom('#{fName}') but stack is empty"
+		{funcName, hInfo} = @lStack.pop()
+		if funcName != fName
+			@dump()
+			croak "returnFrom('#{fName}') but TOS is '#{funcName}'"
+		return hInfo
+
+	# ........................................................................
+
+	reset: () ->
+
+		@lStack = []
+
+	# ........................................................................
+
+	dump: (label='CALL STACK') ->
+
+		console.log "#{label}:"
+		for item, i in @lStack
+			console.log "#{i}: #{JSON.stringify(item)}"
+		return

package/src/call_stack.js

@@ -0,0 +1,53 @@
+// Generated by CoffeeScript 2.6.1
+  // call_stack.coffee
+import {
+  undef,
+  croak
+} from '@jdeighan/coffee-utils';
+
+import {
+  log
+} from '@jdeighan/coffee-utils/log';
+
+// ---------------------------------------------------------------------------
+export var CallStack = class CallStack {
+  constructor() {
+    this.reset();
+  }
+
+  // ........................................................................
+  call(funcName, hInfo) {
+    this.lStack.push({funcName, hInfo});
+  }
+
+  // ........................................................................
+  returnFrom(fName) {
+    var funcName, hInfo;
+    if (this.lStack.length === 0) {
+      croak(`returnFrom('${fName}') but stack is empty`);
+    }
+    ({funcName, hInfo} = this.lStack.pop());
+    if (funcName !== fName) {
+      this.dump();
+      croak(`returnFrom('${fName}') but TOS is '${funcName}'`);
+    }
+    return hInfo;
+  }
+
+  // ........................................................................
+  reset() {
+    return this.lStack = [];
+  }
+
+  // ........................................................................
+  dump(label = 'CALL STACK') {
+    var i, item, j, len, ref;
+    console.log(`${label}:`);
+    ref = this.lStack;
+    for (i = j = 0, len = ref.length; j < len; i = ++j) {
+      item = ref[i];
+      console.log(`${i}: ${JSON.stringify(item)}`);
+    }
+  }
+
+};

package/src/coffee_utils.coffee

@@ -74,6 +74,12 @@ export isString = (x) ->
 
 # ---------------------------------------------------------------------------
 
+export isBoolean = (x) ->
+
+	return typeof x == 'boolean'
+
+# ---------------------------------------------------------------------------
+
 export isNumber = (x) ->
 
 	return typeof x == 'number' || x instanceof Number

package/src/coffee_utils.js

@@ -77,6 +77,11 @@ export var isString = function(x) {
   return typeof x === 'string' || x instanceof String;
 };
 
+// ---------------------------------------------------------------------------
+export var isBoolean = function(x) {
+  return typeof x === 'boolean';
+};
+
 // ---------------------------------------------------------------------------
 export var isNumber = function(x) {
   return typeof x === 'number' || x instanceof Number;

package/src/debug_utils.coffee

@@ -1,12 +1,13 @@
 # debug_utils.coffee
 
 import {
-	assert, undef, error, croak, warn, words, isString, isFunction,
-	oneline, escapeStr, isNumber, isArray,
+	assert, undef, error, croak, warn, isString, isFunction, isBoolean,
+	oneline, escapeStr, isNumber, isArray, words,
 	} from '@jdeighan/coffee-utils'
 import {blockToArray} from '@jdeighan/coffee-utils/block'
 import {log, setLogger} from '@jdeighan/coffee-utils/log'
 import {slurp} from '@jdeighan/coffee-utils/fs'
+import {CallStack} from '@jdeighan/coffee-utils/stack'
 
 vbar = '│'       # unicode 2502
 hbar = '─'       # unicode 2500
@@ -17,91 +18,105 @@ indent = vbar + '   '
 arrow = corner + hbar + arrowhead + ' '
 
 debugLevel = 0   # controls amount of indentation - we ensure it's never < 0
+stdLogger = false
 
-lDebugStack = []
-
-# --- These are saved/restored in lDebugStack
+# --- These are saved/restored on the call stack
 export debugging = false
-ifMatches = undef
-lDebugFuncs = undef   # --- names of functions to debug
+shouldDebug = shouldLog = undef
 
-stdLogger = false
+stack = new CallStack()
 
 # ---------------------------------------------------------------------------
 
-export useStdLogger = (flag=true) ->
+export resetDebugging = (funcDoDebug=undef, funcDoLog=undef) ->
 
-	stdLogger = flag
+	debugging = false
+	debugLevel = 0
+	stack.reset()
+	shouldDebug = (funcName) -> debugging
+	shouldLog   = (str)      -> debugging
+	if funcDoDebug
+		setDebugging funcDoDebug, funcDoLog
 	return
 
 # ---------------------------------------------------------------------------
 
-logger = (lArgs...) ->
+export setDebugging = (funcDoDebug=undef, funcDoLog=undef) ->
 
-	if stdLogger
-		log lArgs...
+	if isBoolean(funcDoDebug)
+		debugging = funcDoDebug
+	else if isString(funcDoDebug)
+		debugging = false
+		lFuncNames = words(funcDoDebug)
+		assert isArray(lFuncNames), "words('#{funcDoDebug}') returned non-array"
+		shouldDebug = (funcName) ->
+			debugging || funcMatch(funcName, lFuncNames)
+	else if isFunction(funcDoDebug)
+		shouldDebug = funcDoDebug
 	else
-		orgLogger = setLogger(console.log)
-		log lArgs...
-		setLogger(orgLogger)
+		croak "setDebugging(): bad parameter #{oneline(funcDoDebug)}"
+
+	if funcDoLog
+		assert isFunction(funcDoLog), "setDebugging: arg 2 not a function"
+		shouldLog = funcDoLog
 	return
 
 # ---------------------------------------------------------------------------
+# --- export only to allow unit tests
 
-stripArrow = (prefix) ->
+export funcMatch = (curFunc, lFuncNames) ->
 
-	return prefix.replace(arrow, '    ')
+	assert isString(curFunc), "funcMatch(): not a string"
+	assert isArray(lFuncNames), "funcMatch(): bad array #{lFuncNames}"
+	if lFuncNames.includes(curFunc)
+		return true
+	else if (lMatches = curFunc.match(reMethod)) \
+			&& ([_, cls, meth] = lMatches) \
+			&& lFuncNames.includes(meth)
+		return true
+	else
+		return false
 
 # ---------------------------------------------------------------------------
 
-export debugIfLineMatches = (regexp=undef) ->
+curEnv = () ->
 
-	ifMatches = regexp
-	return
+	return {debugging, shouldDebug, shouldLog}
 
 # ---------------------------------------------------------------------------
 
-saveDebugEnv = () ->
+setEnv = (hEnv) ->
 
-	lDebugStack.push({
-		debugging,
-		ifMatches,
-		lDebugFuncs,
-		})
+	{debugging, shouldDebug, shouldLog} = hEnv
 	return
 
-restoreDebugEnv = () ->
+# ---------------------------------------------------------------------------
 
-	if (lDebugStack.length == 0)
-		debugging = false
-		ifMatches = undef
-		lDebugFuncs = undef
-	else
-		h = lDebugStack.pop()
-		{debugging, ifMatches, lDebugFuncs} = h
+export useStdLogger = (flag=true) ->
 
+	stdLogger = flag
 	return
 
 # ---------------------------------------------------------------------------
 
-export setDebugging = (x) ->
+logger = (lArgs...) ->
 
-	if (x==false)
-		restoreDebugEnv()
+	if stdLogger
+		log lArgs...
 	else
-		# --- save current setting
-		saveDebugEnv()
-		if (x==true)
-			debugging = true
-		else if isString(x)
-			debugging = false
-			lDebugFuncs = words(x)
-		else
-			croak "setDebugging(): bad parameter #{oneline(x)}"
+		orgLogger = setLogger(console.log)
+		log lArgs...
+		setLogger(orgLogger)
 	return
 
 # ---------------------------------------------------------------------------
 
+stripArrow = (prefix) ->
+
+	return prefix.replace(arrow, '    ')
+
+# ---------------------------------------------------------------------------
+
 getPrefix = (level) ->
 
 	if (level < 0)
@@ -111,17 +126,6 @@ getPrefix = (level) ->
 
 # ---------------------------------------------------------------------------
 
-export resetDebugging = () ->
-
-	debugging = false
-	debugLevel = 0
-	ifMatches = undef
-	lDebugFuncs = undef
-	lDebugStack = []
-	return
-
-# ---------------------------------------------------------------------------
-
 export debug = (lArgs...) ->
 	# --- either 1 or 2 args
 
@@ -130,7 +134,7 @@ export debug = (lArgs...) ->
 	#     when debugging is off
 
 	nArgs = lArgs.length
-	assert ((nArgs >= 1) && (nArgs <= 2)), "debug(); Bad # args #{nArgs}"
+	assert ((nArgs == 1) || (nArgs == 2)), "debug(); Bad # args #{nArgs}"
 	str = lArgs[0]
 
 	# --- str must always be a string
@@ -153,21 +157,21 @@ export debug = (lArgs...) ->
 			///))
 		entering = true
 		curFunc = lMatches[1]
+		stack.call(curFunc, curEnv())
+		debugging = shouldDebug(curFunc, debugging)
 	else if (lMatches = str.match(///^
 			\s*
 			return
-			.*
+			.+
 			from
 			\s+
 			([A-Za-z_][A-Za-z0-9_\.]*)
 			///))
 		returning = true
 		curFunc = lMatches[1]
+		hInfo = stack.returnFrom(curFunc)
 
-	if entering && lDebugFuncs && funcMatch(curFunc)
-		setDebugging true
-
-	if debugging && (! ifMatches? || str.match(ifMatches))
+	if debugging && shouldLog(str)
 
 		# --- set the prefix, i.e. indentation to use
 		if returning
@@ -186,14 +190,15 @@ export debug = (lArgs...) ->
 				logItem: true,
 				itemPrefix: stripArrow(prefix),
 				}
-		if returning && (debugLevel > 0)
-			debugLevel -= 1
 
-	if returning && lDebugFuncs && funcMatch(curFunc)
-		setDebugging false    # revert to previous setting - might still be on
-
-	if debugging && entering
-		debugLevel += 1
+	# --- Adjust debug level
+	if returning
+		if debugLevel > 0
+			debugLevel -= 1
+		setEnv(hInfo)
+	else if entering
+		if debugging
+			debugLevel += 1
 	return
 
 # ---------------------------------------------------------------------------
@@ -204,21 +209,6 @@ reMethod = ///^
 	([A-Za-z_][A-Za-z0-9_]*)
 	$///
 
-# ---------------------------------------------------------------------------
-# --- export only to allow unit tests
-
-export funcMatch = (curFunc) ->
-
-	assert isString(curFunc), "funcMatch(): not a string"
-	if lDebugFuncs.includes(curFunc)
-		return true
-	else if (lMatches = curFunc.match(reMethod)) \
-			&& ([_, cls, meth] = lMatches) \
-			&& lDebugFuncs.includes(meth)
-		return true
-	else
-		return false
-
 # ---------------------------------------------------------------------------
 
 export checkTrace = (block) ->
@@ -256,9 +246,5 @@ export checkTrace = (block) ->
 	return
 
 # ---------------------------------------------------------------------------
-# --- export only to allow unit tests
 
-export checkTraceFile = (filepath) ->
-
-	checkTrace(slurp(filepath))
-	return
+resetDebugging()

package/src/debug_utils.js

@@ -1,6 +1,6 @@
 // Generated by CoffeeScript 2.6.1
 // debug_utils.coffee
-var arrow, arrowhead, corner, debugLevel, getPrefix, hbar, ifMatches, indent, lDebugFuncs, lDebugStack, logger, reMethod, restoreDebugEnv, saveDebugEnv, stdLogger, stripArrow, vbar;
+var arrow, arrowhead, corner, curEnv, debugLevel, getPrefix, hbar, indent, logger, reMethod, setEnv, shouldDebug, shouldLog, stack, stdLogger, stripArrow, vbar;
 
 import {
   assert,
@@ -8,13 +8,14 @@ import {
   error,
   croak,
   warn,
-  words,
   isString,
   isFunction,
+  isBoolean,
   oneline,
   escapeStr,
   isNumber,
-  isArray
+  isArray,
+  words
 } from '@jdeighan/coffee-utils';
 
 import {
@@ -30,6 +31,10 @@ import {
   slurp
 } from '@jdeighan/coffee-utils/fs';
 
+import {
+  CallStack
+} from '@jdeighan/coffee-utils/stack';
+
 vbar = '│'; // unicode 2502
 
 hbar = '─'; // unicode 2500
@@ -44,77 +49,99 @@ arrow = corner + hbar + arrowhead + ' ';
 
 debugLevel = 0; // controls amount of indentation - we ensure it's never < 0
 
-lDebugStack = [];
+stdLogger = false;
 
-// --- These are saved/restored in lDebugStack
+// --- These are saved/restored on the call stack
 export var debugging = false;
 
-ifMatches = undef;
+shouldDebug = shouldLog = undef;
 
-lDebugFuncs = undef; // --- names of functions to debug
+stack = new CallStack();
 
-stdLogger = false;
+// ---------------------------------------------------------------------------
+export var resetDebugging = function(funcDoDebug = undef, funcDoLog = undef) {
+  debugging = false;
+  debugLevel = 0;
+  stack.reset();
+  shouldDebug = function(funcName) {
+    return debugging;
+  };
+  shouldLog = function(str) {
+    return debugging;
+  };
+  if (funcDoDebug) {
+    setDebugging(funcDoDebug, funcDoLog);
+  }
+};
 
 // ---------------------------------------------------------------------------
-export var useStdLogger = function(flag = true) {
-  stdLogger = flag;
+export var setDebugging = function(funcDoDebug = undef, funcDoLog = undef) {
+  var lFuncNames;
+  if (isBoolean(funcDoDebug)) {
+    debugging = funcDoDebug;
+  } else if (isString(funcDoDebug)) {
+    debugging = false;
+    lFuncNames = words(funcDoDebug);
+    assert(isArray(lFuncNames), `words('${funcDoDebug}') returned non-array`);
+    shouldDebug = function(funcName) {
+      return debugging || funcMatch(funcName, lFuncNames);
+    };
+  } else if (isFunction(funcDoDebug)) {
+    shouldDebug = funcDoDebug;
+  } else {
+    croak(`setDebugging(): bad parameter ${oneline(funcDoDebug)}`);
+  }
+  if (funcDoLog) {
+    assert(isFunction(funcDoLog), "setDebugging: arg 2 not a function");
+    shouldLog = funcDoLog;
+  }
 };
 
 // ---------------------------------------------------------------------------
-logger = function(...lArgs) {
-  var orgLogger;
-  if (stdLogger) {
-    log(...lArgs);
+// --- export only to allow unit tests
+export var funcMatch = function(curFunc, lFuncNames) {
+  var _, cls, lMatches, meth;
+  assert(isString(curFunc), "funcMatch(): not a string");
+  assert(isArray(lFuncNames), `funcMatch(): bad array ${lFuncNames}`);
+  if (lFuncNames.includes(curFunc)) {
+    return true;
+  } else if ((lMatches = curFunc.match(reMethod)) && ([_, cls, meth] = lMatches) && lFuncNames.includes(meth)) {
+    return true;
   } else {
-    orgLogger = setLogger(console.log);
-    log(...lArgs);
-    setLogger(orgLogger);
+    return false;
   }
 };
 
 // ---------------------------------------------------------------------------
-stripArrow = function(prefix) {
-  return prefix.replace(arrow, '    ');
+curEnv = function() {
+  return {debugging, shouldDebug, shouldLog};
 };
 
 // ---------------------------------------------------------------------------
-export var debugIfLineMatches = function(regexp = undef) {
-  ifMatches = regexp;
+setEnv = function(hEnv) {
+  ({debugging, shouldDebug, shouldLog} = hEnv);
 };
 
 // ---------------------------------------------------------------------------
-saveDebugEnv = function() {
-  lDebugStack.push({debugging, ifMatches, lDebugFuncs});
+export var useStdLogger = function(flag = true) {
+  stdLogger = flag;
 };
 
-restoreDebugEnv = function() {
-  var h;
-  if (lDebugStack.length === 0) {
-    debugging = false;
-    ifMatches = undef;
-    lDebugFuncs = undef;
+// ---------------------------------------------------------------------------
+logger = function(...lArgs) {
+  var orgLogger;
+  if (stdLogger) {
+    log(...lArgs);
   } else {
-    h = lDebugStack.pop();
-    ({debugging, ifMatches, lDebugFuncs} = h);
+    orgLogger = setLogger(console.log);
+    log(...lArgs);
+    setLogger(orgLogger);
   }
 };
 
 // ---------------------------------------------------------------------------
-export var setDebugging = function(x) {
-  if (x === false) {
-    restoreDebugEnv();
-  } else {
-    // --- save current setting
-    saveDebugEnv();
-    if (x === true) {
-      debugging = true;
-    } else if (isString(x)) {
-      debugging = false;
-      lDebugFuncs = words(x);
-    } else {
-      croak(`setDebugging(): bad parameter ${oneline(x)}`);
-    }
-  }
+stripArrow = function(prefix) {
+  return prefix.replace(arrow, '    ');
 };
 
 // ---------------------------------------------------------------------------
@@ -126,25 +153,16 @@ getPrefix = function(level) {
   return '   '.repeat(level);
 };
 
-// ---------------------------------------------------------------------------
-export var resetDebugging = function() {
-  debugging = false;
-  debugLevel = 0;
-  ifMatches = undef;
-  lDebugFuncs = undef;
-  lDebugStack = [];
-};
-
 // ---------------------------------------------------------------------------
 export var debug = function(...lArgs) {
-  var curFunc, entering, item, lMatches, nArgs, prefix, returning, str;
+  var curFunc, entering, hInfo, item, lMatches, nArgs, prefix, returning, str;
   // --- either 1 or 2 args
 
   // --- We always need to manipulate the stack when we encounter
   //     either "enter X" or "return from X", so we can't short-circuit
   //     when debugging is off
   nArgs = lArgs.length;
-  assert((nArgs >= 1) && (nArgs <= 2), `debug(); Bad # args ${nArgs}`);
+  assert((nArgs === 1) || (nArgs === 2), `debug(); Bad # args ${nArgs}`);
   str = lArgs[0];
   // --- str must always be a string
   //     if 2 args, then str is meant to be a label for the item
@@ -158,14 +176,14 @@ export var debug = function(...lArgs) {
   if ((lMatches = str.match(/^\s*enter\s+([A-Za-z_][A-Za-z0-9_\.]*)/))) {
     entering = true;
     curFunc = lMatches[1];
-  } else if ((lMatches = str.match(/^\s*return.*from\s+([A-Za-z_][A-Za-z0-9_\.]*)/))) {
+    stack.call(curFunc, curEnv());
+    debugging = shouldDebug(curFunc, debugging);
+  } else if ((lMatches = str.match(/^\s*return.+from\s+([A-Za-z_][A-Za-z0-9_\.]*)/))) {
     returning = true;
     curFunc = lMatches[1];
+    hInfo = stack.returnFrom(curFunc);
   }
-  if (entering && lDebugFuncs && funcMatch(curFunc)) {
-    setDebugging(true);
-  }
-  if (debugging && ((ifMatches == null) || str.match(ifMatches))) {
+  if (debugging && shouldLog(str)) {
     // --- set the prefix, i.e. indentation to use
     if (returning) {
       if (debugLevel === 0) {
@@ -185,35 +203,23 @@ export var debug = function(...lArgs) {
         itemPrefix: stripArrow(prefix)
       });
     }
-    if (returning && (debugLevel > 0)) {
+  }
+  // --- Adjust debug level
+  if (returning) {
+    if (debugLevel > 0) {
       debugLevel -= 1;
     }
-  }
-  if (returning && lDebugFuncs && funcMatch(curFunc)) {
-    setDebugging(false); // revert to previous setting - might still be on
-  }
-  if (debugging && entering) {
-    debugLevel += 1;
+    setEnv(hInfo);
+  } else if (entering) {
+    if (debugging) {
+      debugLevel += 1;
+    }
   }
 };
 
 // ---------------------------------------------------------------------------
 reMethod = /^([A-Za-z_][A-Za-z0-9_]*)\.([A-Za-z_][A-Za-z0-9_]*)$/;
 
-// ---------------------------------------------------------------------------
-// --- export only to allow unit tests
-export var funcMatch = function(curFunc) {
-  var _, cls, lMatches, meth;
-  assert(isString(curFunc), "funcMatch(): not a string");
-  if (lDebugFuncs.includes(curFunc)) {
-    return true;
-  } else if ((lMatches = curFunc.match(reMethod)) && ([_, cls, meth] = lMatches) && lDebugFuncs.includes(meth)) {
-    return true;
-  } else {
-    return false;
-  }
-};
-
 // ---------------------------------------------------------------------------
 export var checkTrace = function(block) {
   var funcName, i, lMatches, lStack, len, len1, line, ref;
@@ -244,7 +250,4 @@ export var checkTrace = function(block) {
 };
 
 // ---------------------------------------------------------------------------
-// --- export only to allow unit tests
-export var checkTraceFile = function(filepath) {
-  checkTrace(slurp(filepath));
-};
+resetDebugging();