@jdeighan/coffee-utils 7.0.50 → 7.0.53

package/src/debug_utils.js

@@ -1,6 +1,6 @@
 // Generated by CoffeeScript 2.7.0
 // debug_utils.coffee
-var adjustStack, doDebugDebug, reMethod, resetDebugging, shouldLogFunc, shouldLogString, stack;
+var callStack, doDebugDebug, reMethod, resetDebugging;
 
 import {
   assert,
@@ -12,6 +12,7 @@ import {
   isString,
   isFunction,
   isBoolean,
+  sep_dash,
   OL,
   escapeStr,
   isNumber,
@@ -36,28 +37,170 @@ import {
   CallStack
 } from '@jdeighan/coffee-utils/stack';
 
+import {
+  getPrefix,
+  addArrow,
+  removeLastVbar
+} from '@jdeighan/coffee-utils/arrow';
+
 import {
   log,
   logItem,
   LOG,
-  setStringifier,
-  orderedStringify
+  shortEnough
 } from '@jdeighan/coffee-utils/log';
 
-// --- These are saved/restored on the call stack
-export var debugging = false;
+callStack = new CallStack();
 
-shouldLogFunc = function(func) {
-  return debugging;
-};
+doDebugDebug = false;
+
+export var shouldLog = undef; // set in resetDebugging() and setDebugging()
+
+export var lFuncList = [];
 
-shouldLogString = function(str) {
-  return debugging;
+// ---------------------------------------------------------------------------
+export var debug = function(label, ...lObjects) {
+  var doLog, funcName, i, j, k, l, len1, len2, len3, level, nObjects, obj, prefix, type;
+  assert(isString(label), `1st arg ${OL(label)} should be a string`);
+  // --- We want to allow objects to be undef. Therefore, we need to
+  //     distinguish between 1 arg sent vs. 2 or more args sent
+  nObjects = lObjects.length;
+  // --- funcName is only set for types 'enter' and 'return'
+  [type, funcName] = getType(label, nObjects);
+  if (doDebugDebug) {
+    LOG(`debug(): type = ${OL(type)}`);
+    LOG(`debug(): funcName = ${OL(funcName)}`);
+  }
+  switch (type) {
+    case 'enter':
+      callStack.enter(funcName);
+      label = shouldLog(label, type, funcName, callStack);
+      break;
+    case 'return':
+      label = shouldLog(label, type, funcName, callStack);
+      break;
+    case 'string':
+      label = shouldLog(label, type, undef, callStack);
+      assert(nObjects === 0, `multiple objects only not allowed for ${OL(type)}`);
+      break;
+    case 'objects':
+      label = shouldLog(label, type, undef, callStack);
+      assert(nObjects > 0, `multiple objects only not allowed for ${OL(type)}`);
+  }
+  doLog = defined(label);
+  if (doDebugDebug) {
+    if (nObjects === 0) {
+      LOG(`debug(${OL(label)}) - 1 arg`);
+    } else {
+      LOG(`debug(${OL(label)}), ${nObjects} args`);
+    }
+    LOG(`doLog = ${OL(doLog)}`);
+  }
+  if (doLog) {
+    level = callStack.getLevel();
+    prefix = getPrefix(level);
+    if (doDebugDebug) {
+      LOG("callStack", callStack);
+      LOG(`level = ${OL(level)}`);
+      LOG(`prefix = ${OL(prefix)}`);
+    }
+    switch (type) {
+      case 'enter':
+        log(label, {prefix});
+        for (i = j = 0, len1 = lObjects.length; j < len1; i = ++j) {
+          obj = lObjects[i];
+          if (i > 0) {
+            log(sep_dash, {
+              prefix: removeLastVbar(prefix)
+            });
+          }
+          logItem(undef, obj, {
+            prefix: removeLastVbar(prefix)
+          });
+        }
+        break;
+      case 'return':
+        log(label, {
+          prefix: addArrow(prefix)
+        });
+        for (i = k = 0, len2 = lObjects.length; k < len2; i = ++k) {
+          obj = lObjects[i];
+          if (i > 0) {
+            log(sep_dash, {
+              prefix: removeLastVbar(prefix)
+            });
+          }
+          logItem(undef, obj, {
+            prefix: removeLastVbar(prefix)
+          });
+        }
+        break;
+      case 'string':
+        log(label, {prefix});
+        break;
+      case 'objects':
+        if ((nObjects === 1) && shortEnough(label, lObjects[0])) {
+          logItem(label, lObjects[0], {prefix});
+        } else {
+          if (label.indexOf(':') !== label.length - 1) {
+            label += ':';
+          }
+          log(label, {prefix});
+          for (l = 0, len3 = lObjects.length; l < len3; l++) {
+            obj = lObjects[l];
+            logItem(undef, obj, {prefix});
+          }
+        }
+    }
+  }
+  if ((type === 'enter') && doLog) {
+    callStack.logCurFunc();
+  } else if (type === 'return') {
+    callStack.returnFrom(funcName);
+  }
+  return true; // allow use in boolean expressions
 };
 
-stack = new CallStack();
 
-doDebugDebug = false;
+// ---------------------------------------------------------------------------
+export var stdShouldLog = function(label, type, funcName, stack) {
+  // --- if type is 'enter', then funcName won't be on the stack yet
+  //     returns the (possibly modified) label to log
+
+  // --- If we're logging now,
+  //     but we won't be logging when funcName is activated
+  //     then change 'enter' to 'call'
+  assert(isString(label), `label ${OL(label)} not a string`);
+  assert(isString(type), `type ${OL(type)} not a string`);
+  if ((type === 'enter') || (type === 'return')) {
+    assert(isString(funcName), `func name ${OL(funcName)} not a string`);
+  } else {
+    assert(funcName === undef, `func name ${OL(funcName)} not undef`);
+  }
+  assert(stack instanceof CallStack, "not a call stack object");
+  if (doDebugDebug) {
+    LOG(`stdShouldLog(${OL(label)}, ${OL(type)}, ${OL(funcName)}, stack)`);
+    LOG("stack", stack);
+    LOG("lFuncList", lFuncList);
+  }
+  switch (type) {
+    case 'enter':
+      if (funcMatch(stack, lFuncList)) {
+        return label;
+      // --- As a special case, if we enter a function where we will not
+      //     be logging, but we were logging in the calling function,
+      //     we'll log out the call itself
+      } else if (stack.isLoggingPrev()) {
+        return label.replace('enter', 'call');
+      }
+      break;
+    default:
+      if (funcMatch(stack, lFuncList)) {
+        return label;
+      }
+  }
+  return undef;
+};
 
 // ---------------------------------------------------------------------------
 export var debugDebug = function(flag = true) {
@@ -69,177 +212,137 @@ export var debugDebug = function(flag = true) {
 
 // ---------------------------------------------------------------------------
 resetDebugging = function() {
-  debugging = false;
   if (doDebugDebug) {
-    LOG("resetDebugging() - debugging = false");
+    LOG("resetDebugging()");
   }
-  stack.reset();
-  shouldLogFunc = function(func) {
-    return debugging;
-  };
-  shouldLogString = function(str) {
-    return debugging;
+  callStack.reset();
+  shouldLog = function(label, type, funcName, stack) {
+    return undef;
   };
 };
 
 // ---------------------------------------------------------------------------
-export var setDebugging = function(funcDoDebug = undef, funcDoLog = undef) {
-  var lFuncNames;
+export var setDebugging = function(option) {
   resetDebugging();
-  if (isBoolean(funcDoDebug)) {
-    debugging = funcDoDebug;
+  if (isBoolean(option)) {
+    if (option) {
+      shouldLog = function(label, type, funcName, stack) {
+        return label;
+      };
+    } else {
+      shouldLog = function(label, type, funcName, stack) {
+        return undef;
+      };
+    }
     if (doDebugDebug) {
-      LOG(`setDebugging(): debugging = ${funcDoDebug}`);
+      LOG(`setDebugging = ${option}`);
     }
-  } else if (isString(funcDoDebug)) {
-    debugging = false;
-    lFuncNames = words(funcDoDebug);
-    assert(isArray(lFuncNames), `words('${funcDoDebug}') returned non-array`);
-    shouldLogFunc = function(funcName) {
-      return funcMatch(funcName, lFuncNames);
-    };
+  } else if (isString(option)) {
+    lFuncList = getFuncList(option);
+    shouldLog = stdShouldLog;
     if (doDebugDebug) {
-      LOG(`setDebugging FUNCS: ${lFuncNames.join(',')}, debugging = false`);
+      LOG(`setDebugging FUNCS: ${option}`);
+      LOG('lFuncList', lFuncList);
     }
-  } else if (isFunction(funcDoDebug)) {
-    shouldLogFunc = funcDoDebug;
+  } else if (isFunction(option)) {
+    shouldLog = option;
     if (doDebugDebug) {
       LOG("setDebugging to custom func");
     }
   } else {
-    croak(`setDebugging(): bad parameter ${OL(funcDoDebug)}`);
-  }
-  if (isFunction(funcDoLog)) {
-    assert(isFunction(funcDoLog), "setDebugging: arg 2 not a function");
-    shouldLogString = funcDoLog;
+    croak(`bad parameter ${OL(option)}`);
   }
 };
 
 // ---------------------------------------------------------------------------
 // --- 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 {
-    return false;
-  }
-};
-
-// ---------------------------------------------------------------------------
-// 1. adjust call stack on 'enter' or 'return from'
-// 2. adjust debugging flag
-// 3. return [mainPrefix, auxPrefix, hEnv, type] - hEnv can be undef
-// 4. disable logging by setting type to undef
-adjustStack = function(str) {
-  var _, auxPre, curFunc, hEnv, lMatches, mainPre, trans;
-  if ((lMatches = str.match(/^\s*enter\s+([A-Za-z_][A-Za-z0-9_\.]*)/))) {
-    // --- We are entering function curFunc
-    curFunc = lMatches[1];
-    hEnv = {debugging, shouldLogFunc, shouldLogString};
-    debugging = shouldLogFunc(curFunc);
-    if (doDebugDebug) {
-      trans = `${hEnv.debugging} => ${debugging}`;
-      LOG(`   ENTER ${curFunc}, debugging: ${trans}`);
-    }
-    [mainPre, auxPre] = stack.doCall(curFunc, hEnv, debugging);
-    return [mainPre, auxPre, undef, shouldLogFunc(curFunc) ? 'enter' : undef];
-  } else if ((lMatches = str.match(/^\s*return.+from\s+([A-Za-z_][A-Za-z0-9_\.]*)/))) {
-    curFunc = lMatches[1];
-    [mainPre, auxPre, hEnv] = stack.returnFrom(curFunc);
-    if (doDebugDebug) {
-      LOG(`   RETURN FROM ${curFunc}`);
+export var getFuncList = function(str) {
+  var _, ident1, ident2, j, lMatches, len1, plus, ref, word;
+  lFuncList = [];
+  ref = words(str);
+  for (j = 0, len1 = ref.length; j < len1; j++) {
+    word = ref[j];
+    if (lMatches = word.match(/^([A-Za-z_][A-Za-z0-9_]*)(?:\.([A-Za-z_][A-Za-z0-9_]*))?(\+)?$/)) {
+      [_, ident1, ident2, plus] = lMatches;
+      if (ident2) {
+        lFuncList.push({
+          name: ident2,
+          object: ident1,
+          plus: plus === '+'
+        });
+      } else {
+        lFuncList.push({
+          name: ident1,
+          plus: plus === '+'
+        });
+      }
+    } else {
+      croak(`Bad word in func list: ${OL(word)}`);
     }
-    return [mainPre, auxPre, hEnv, shouldLogFunc(curFunc) ? 'return' : undef];
-  } else {
-    [mainPre, auxPre, _] = stack.logStr();
-    return [mainPre, auxPre, undef, shouldLogString(str) ? 'string' : undef];
   }
+  return lFuncList;
 };
 
 // ---------------------------------------------------------------------------
-export var debug = function(...lArgs) {
-  var auxPre, hEnv, hOptions, item, lResult, label, mainPre, nArgs, orgDebugging, trans, type;
-  // --- We want to allow item to be undef. Therefore, we need to
-  //     distinguish between 1 arg sent vs. 2 args sent
-  nArgs = lArgs.length;
-  assert((nArgs === 1) || (nArgs === 2), `debug(): ${nArgs} args`);
-  // --- label must always be there, and be a string
-  //     item is optional
-  [label, item] = lArgs;
-  assert(isString(label), `debug(): 1st arg ${OL(label)} should be a string`);
-  if (doDebugDebug) {
-    if (nArgs === 1) {
-      LOG(`debug('${escapeStr(label)}') - 1 arg`);
-    } else {
-      LOG(`debug('${escapeStr(label)}', ${typeof item}) - 2 args`);
-    }
-    LOG(`debugging flag = ${OL(debugging)}`);
-  }
-  // --- 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
-  lResult = adjustStack(label);
+// --- export only to allow unit tests
+export var funcMatch = function(stack, lFuncList) {
+  var curFunc, h, j, len1, name, object, plus;
+  assert(isArray(lFuncList), `not an array ${OL(lFuncList)}`);
+  curFunc = stack.curFunc();
   if (doDebugDebug) {
-    LOG('lResult', lResult);
+    LOG(`funcMatch(): curFunc = ${OL(curFunc)}`);
+    stack.dump('   ');
+    LOG('lFuncList', lFuncList);
   }
-  [mainPre, auxPre, hEnv, type] = lResult;
-  if (doDebugDebug && (type === undef)) {
-    LOG("type is undef - NOT LOGGING");
-  }
-  hOptions = {
-    prefix: mainPre,
-    itemPrefix: auxPre
-  };
-  switch (type) {
-    case 'enter':
-      log(label, hOptions);
-      if (nArgs === 2) {
-        // --- don't repeat the label
-        logItem(undef, item, hOptions);
+  for (j = 0, len1 = lFuncList.length; j < len1; j++) {
+    h = lFuncList[j];
+    ({name, object, plus} = h);
+    if (name === curFunc) {
+      if (doDebugDebug) {
+        LOG("   curFunc in lFuncList - match successful");
       }
-      break;
-    case 'return':
-      log(label, hOptions);
-      if (nArgs === 2) {
-        // --- don't repeat the label
-        logItem(undef, item, hOptions);
-      }
-      break;
-    case 'string':
-      if (nArgs === 2) {
-        logItem(label, item, hOptions);
-      } else {
-        log(label, hOptions);
+      return true;
+    }
+    if (plus && stack.isActive(name)) {
+      if (doDebugDebug) {
+        LOG(`   func ${OL(name)} is active - match successful`);
       }
-  }
-  if (hEnv) {
-    orgDebugging = debugging;
-    ({debugging, shouldLogFunc, shouldLogString} = hEnv);
-    if (doDebugDebug) {
-      trans = `${orgDebugging} => ${debugging}`;
-      LOG(`   Restore hEnv: debugging: ${trans}`);
+      return true;
     }
   }
-  return true; // allow use in boolean expressions
+  if (doDebugDebug) {
+    LOG("   - no match");
+  }
+  return false;
 };
 
+// ---------------------------------------------------------------------------
+// --- type is one of: 'enter', 'return', 'string', 'object'
+export var getType = function(str, nObjects) {
+  var lMatches;
+  if (lMatches = str.match(/^\s*enter\s+([A-Za-z_][A-Za-z0-9_\.]*)/)) {
+    // --- We are entering function curFunc
+    return ['enter', lMatches[1]];
+  } else if (lMatches = str.match(/^\s*return.+from\s+([A-Za-z_][A-Za-z0-9_\.]*)/)) {
+    return ['return', lMatches[1]];
+  } else if (nObjects > 0) {
+    return ['objects', undef];
+  } else {
+    return ['string', undef];
+  }
+};
 
 // ---------------------------------------------------------------------------
 reMethod = /^([A-Za-z_][A-Za-z0-9_]*)\.([A-Za-z_][A-Za-z0-9_]*)$/;
 
 // ---------------------------------------------------------------------------
 export var checkTrace = function(block) {
-  var funcName, i, lMatches, lStack, len, len1, line, ref;
+  var funcName, j, lMatches, lStack, len, len1, line, ref;
   // --- export only to allow unit tests
   lStack = [];
   ref = blockToArray(block);
-  for (i = 0, len1 = ref.length; i < len1; i++) {
-    line = ref[i];
+  for (j = 0, len1 = ref.length; j < len1; j++) {
+    line = ref[j];
     if (lMatches = line.match(/enter\s+([A-Za-z_][A-Za-z0-9_\.]*)/)) {
       funcName = lMatches[1];
       lStack.push(funcName);

package/src/log_utils.coffee

@@ -4,15 +4,28 @@ import yaml from 'js-yaml'
 
 import {
 	assert, undef, isNumber, isInteger, isString, isHash, isFunction,
-	escapeStr, sep_eq, sep_dash, pass
+	escapeStr, sep_eq, sep_dash, pass, OL,
 	} from '@jdeighan/coffee-utils'
 import {blockToArray} from '@jdeighan/coffee-utils/block'
-import {tabify, untabify, indentation} from '@jdeighan/coffee-utils/indent'
+import {
+	tabify, untabify, indentation, indented,
+	} from '@jdeighan/coffee-utils/indent'
 
 # --- This logger only ever gets passed a single string argument
 putstr = undef
+doDebugLog = false
 
 export stringify = undef
+fourSpaces  = '    '
+
+# ---------------------------------------------------------------------------
+
+export debugLog = (flag=true) ->
+
+	doDebugLog = flag
+	if doDebugLog
+		LOG "doDebugLog = #{flag}"
+	return
 
 # ---------------------------------------------------------------------------
 # This is useful for debugging
@@ -23,9 +36,9 @@ export LOG = (lArgs...) ->
 	if lArgs.length > 1
 		# --- There's both a label and an item
 		if (item == undef)
-			console.log "#{label}: UNDEFINED"
+			console.log "#{label} = undef"
 		else if (item == null)
-			console.log "#{label}: NULL"
+			console.log "#{label} = null"
 		else
 			console.log sep_dash
 			console.log "#{label}:"
@@ -112,19 +125,6 @@ maxOneLine = 32
 
 # ---------------------------------------------------------------------------
 
-fixStr = (str) ->
-
-	if !str
-		return ''
-
-	# --- If putstr is console.log, we'll convert TAB char to 3 spaces
-	if putstr == console.log
-		return untabify(str)
-	else
-		return str
-
-# ---------------------------------------------------------------------------
-
 export log = (str, hOptions={}) ->
 	# --- valid options:
 	#   prefix
@@ -132,8 +132,11 @@ export log = (str, hOptions={}) ->
 	assert isFunction(putstr), "putstr not properly set"
 	assert isString(str),      "log(): not a string"
 	assert isHash(hOptions),   "log(): arg 2 not a hash"
+	prefix = fixForTerminal(hOptions.prefix)
+
+	if doDebugLog
+		LOG "CALL log(#{OL(str)}), prefix = #{OL(prefix)}"
 
-	prefix = fixStr(hOptions.prefix)
 	putstr "#{prefix}#{str}"
 	return true   # to allow use in boolean expressions
 
@@ -141,15 +144,20 @@ export log = (str, hOptions={}) ->
 
 export logItem = (label, item, hOptions={}) ->
 	# --- valid options:
-	#   prefix     - not used
-	#   itemPrefix - always used
+	#   prefix
 
 	assert isFunction(putstr), "putstr not properly set"
 	assert !label || isString(label), "label a non-string"
 	assert isHash(hOptions), "arg 3 not a hash"
 
-	label = fixStr(label)
-	prefix = fixStr(hOptions.itemPrefix || hOptions.prefix)
+	label = fixForTerminal(label)
+	prefix = fixForTerminal(hOptions.prefix)
+	assert prefix.indexOf("\t") == -1, "prefix has TAB"
+
+	if doDebugLog
+		LOG "CALL logItem(#{OL(label)}, #{OL(item)})"
+		LOG "prefix = #{OL(prefix)}"
+
 	labelStr = if label then "#{label} = " else ""
 
 	if (item == undef)
@@ -162,21 +170,36 @@ export logItem = (label, item, hOptions={}) ->
 		else
 			if label
 				putstr "#{prefix}#{label}:"
-			putBlock item, prefix
+			putBlock item, prefix + fourSpaces
 	else if isNumber(item)
 		putstr "#{prefix}#{labelStr}#{item}"
 	else
-		putstr "#{prefix}#{sep_dash}"
 		if label
 			putstr "#{prefix}#{label}:"
 		for str in blockToArray(stringify(item, true))  # escape special chars
-			putstr "#{prefix}#{indentation(1)}#{fixStr(str)}"
-		putstr "#{prefix}#{sep_dash}"
+			putstr "#{prefix + fourSpaces}#{fixForTerminal(str)}"
 
 	return true
 
 # ---------------------------------------------------------------------------
 
+export shortEnough = (label, value) ->
+
+	return (value == undef)
+
+# ---------------------------------------------------------------------------
+# --- needed because Windows Terminal handles TAB chars badly
+
+fixForTerminal = (str) ->
+
+	if !str
+		return ''
+
+	# --- convert TAB char to 4 spaces
+	return str.replace(/\t/g, fourSpaces)
+
+# ---------------------------------------------------------------------------
+
 putBlock = (item, prefix='') ->
 
 	putstr "#{prefix}#{sep_eq}"