@jdeighan/coffee-utils 11.0.30 → 11.0.32

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@jdeighan/coffee-utils",
 	"type": "module",
-	"version": "11.0.30",
+	"version": "11.0.32",
 	"description": "A set of utility functions for CoffeeScript",
 	"main": "coffee_utils.js",
 	"exports": {
@@ -19,7 +19,6 @@
 		"./svelte": "./src/svelte.js",
 		"./store": "./src/DataStores.js",
 		"./taml": "./src/taml.js",
-		"./placeholders": "./src/placeholders.js",
 		"./section": "./src/Section.js",
 		"./sectionmap": "./src/SectionMap.js",
 		"./fsa": "./src/fsa.js",
@@ -32,8 +31,7 @@
 		"verbose": false
 	},
 	"scripts": {
-		"build": "cls && rm -f ./*.js && coffee -c .",
-		"pretest": "cls && cielo -qfc ./test && coffee -c .",
+		"build": "cls && coffee -c .",
 		"test": "npm run build && ava ./test/*.test.js && git status"
 	},
 	"repository": {
@@ -50,7 +48,7 @@
 	},
 	"homepage": "https://github.com/johndeighan/coffee-utils#readme",
 	"dependencies": {
-		"@jdeighan/exceptions": "^1.0.24",
+		"@jdeighan/exceptions": "^1.0.26",
 		"cross-env": "^7.0.3",
 		"js-yaml": "^4.1.0",
 		"n-readlines": "^1.0.1",
@@ -58,6 +56,6 @@
 		"svelte": "^3.52.0"
 	},
 	"devDependencies": {
-		"@jdeighan/unit-tester": "^2.0.49"
+		"@jdeighan/unit-tester": "^2.0.52"
 	}
 }

package/src/Section.coffee

@@ -3,36 +3,20 @@
 import {assert, croak} from '@jdeighan/exceptions'
 import {debug} from '@jdeighan/exceptions/debug'
 import {
-	pass, undef, defined, isArray, isEmpty,
+	pass, undef, defined, isArray, isEmpty, isFunction,
 	} from '@jdeighan/coffee-utils'
-import {arrayToBlock} from '@jdeighan/coffee-utils/block'
-import {indented} from '@jdeighan/coffee-utils/indent'
+import {toBlock} from '@jdeighan/coffee-utils/block'
 
 # ---------------------------------------------------------------------------
 
 export class Section
 
-	constructor: (@name, content=undef) ->
+	constructor: (@name, @replacer=undef) ->
 		# --- name can be undef or empty
 
 		@lParts = []
-		if defined(content)
-			@lParts.push content
-
-	# ..........................................................
-
-	length: () ->
-
-		return @lParts.length
-
-	# ..........................................................
-
-	indent: (level=1, oneIndent="\t") ->
-
-		lNewLines = for line in @lParts
-			indented(line, level, oneIndent)
-		@lParts = lNewLines
-		return
+		if defined(@replacer)
+			assert isFunction(@replacer), "bad replacer"
 
 	# ..........................................................
 
@@ -81,7 +65,8 @@ export class Section
 		if (@lParts.length == 0)
 			debug "return undef from Section.getBlock()"
 			return undef
-		else
-			result = arrayToBlock(@lParts)
-			debug "return from Section.getBlock()", result
-			return result
+		block = toBlock(@lParts)
+		if defined(@replacer)
+			block = @replacer block
+		debug "return from Section.getBlock()", block
+		return block

package/src/Section.js

@@ -14,49 +14,26 @@ import {
   undef,
   defined,
   isArray,
-  isEmpty
+  isEmpty,
+  isFunction
 } from '@jdeighan/coffee-utils';
 
 import {
-  arrayToBlock
+  toBlock
 } from '@jdeighan/coffee-utils/block';
 
-import {
-  indented
-} from '@jdeighan/coffee-utils/indent';
-
 // ---------------------------------------------------------------------------
 export var Section = class Section {
-  constructor(name, content = undef) {
+  constructor(name, replacer = undef) {
     this.name = name;
+    this.replacer = replacer;
     // --- name can be undef or empty
     this.lParts = [];
-    if (defined(content)) {
-      this.lParts.push(content);
+    if (defined(this.replacer)) {
+      assert(isFunction(this.replacer), "bad replacer");
     }
   }
 
-  // ..........................................................
-  length() {
-    return this.lParts.length;
-  }
-
-  // ..........................................................
-  indent(level = 1, oneIndent = "\t") {
-    var lNewLines, line;
-    lNewLines = (function() {
-      var i, len, ref, results;
-      ref = this.lParts;
-      results = [];
-      for (i = 0, len = ref.length; i < len; i++) {
-        line = ref[i];
-        results.push(indented(line, level, oneIndent));
-      }
-      return results;
-    }).call(this);
-    this.lParts = lNewLines;
-  }
-
   // ..........................................................
   isEmpty() {
     return this.lParts.length === 0;
@@ -96,16 +73,18 @@ export var Section = class Section {
 
   // ..........................................................
   getBlock() {
-    var result;
+    var block;
     debug("enter Section.getBlock()");
     if (this.lParts.length === 0) {
       debug("return undef from Section.getBlock()");
       return undef;
-    } else {
-      result = arrayToBlock(this.lParts);
-      debug("return from Section.getBlock()", result);
-      return result;
     }
+    block = toBlock(this.lParts);
+    if (defined(this.replacer)) {
+      block = this.replacer(block);
+    }
+    debug("return from Section.getBlock()", block);
+    return block;
   }
 
 };

package/src/SectionMap.coffee

@@ -1,15 +1,14 @@
 # SectionMap.coffee
 
-import {assert, croak} from '@jdeighan/exceptions'
-import {LOG} from '@jdeighan/exceptions/log'
-import {debug} from '@jdeighan/exceptions/debug'
 import {
-	pass, undef, defined, notdefined, OL, isEmpty, nonEmpty,
+	assert, croak, LOG, LOGVALUE, LOGTAML, debug, isTAML, fromTAML,
+	} from '@jdeighan/exceptions'
+import {
+	pass, undef, def, notdef, OL, isEmpty, nonEmpty,
 	isString, isHash, isArray, isUniqueTree, isNonEmptyString,
-	isNonEmptyArray,
+	isNonEmptyArray, isFunction, jsType, isArrayOfStrings,
 	} from '@jdeighan/coffee-utils'
 import {toBlock} from '@jdeighan/coffee-utils/block'
-import {isTAML, fromTAML} from '@jdeighan/coffee-utils/taml'
 import {Section} from '@jdeighan/coffee-utils/section'
 
 # ---------------------------------------------------------------------------
@@ -28,142 +27,161 @@ isSetName = (name) ->
 
 export class SectionMap
 
-	constructor: (@lSectionTree) ->
-		# --- lSectionTree is a tree of section/set names
-
-		debug "enter SectionMap()", @lSectionTree
+	constructor: (tree, @hReplacers={}) ->
+		# --- tree is a tree of section/set names
+		#        or a TAML string that converts to one
+		# --- hReplacers are callbacks that are called
+		#        when a set or section is processed
+		#        should be <name> -> <function>
+		#     <name> can be a section name or a set name
+		#     <function> should be <block> -> <block>
 
-		if isTAML(@lSectionTree)
-			@SectionTree = fromTAML(@lSectionTree)
+		debug "enter SectionMap()", tree, @hReplacers
 
-		assert isArray(@lSectionTree), "not an array"
+		@checkTree tree
+		@checkReplacers @hReplacers
 
-		# --- keys are section names, values are Section objects
-		@hSections = {}
+		@hSections = {}            # --- {section name: Section Object}
+		@hSets = {ALL: @lFullTree} # --- {set name: array of parts}
 
-		# --- keys are set names, values are subtrees of lSectionTree
-		@hSets = {}
+		@init @lFullTree
 
-		@build @lSectionTree
-		debug "return from SectionMap()", @hSections
+		debug 'hSections', @hSections
+		debug 'hSets', @hSets
+		debug "return from SectionMap()"
 
 	# ..........................................................
 
-	build: (lTree) ->
+	init: (lTree) ->
 
-		debug "enter build()", lTree
+		debug "enter init()", lTree
 		assert isArray(lTree), "not an array"
 		assert nonEmpty(lTree), "empty array"
 
 		firstItem = lTree[0]
 		if isSetName(firstItem)
-			assert (lTree.length >= 2), "set without sections"
-			@hSets[firstItem] = lTree
-			for item in lTree.slice(1)
-				if isArray(item)
-					@build item
-				else if isSectionName(item)
-					@hSections[item] = new Section(item)
-				else if ! isString(item)    # string would be literal
-					croak "Bad section tree: #{OL(@lSectionTree)}"
-		else
-			for item in lTree
-				if isArray(item)
-					@build item
-				else if isSectionName(item)
-					@hSections[item] = new Section(item)
-				else
-					croak "Bad section tree: #{OL(@lSectionTree)}"
-		debug "return from build()", @hSections, @hSets
+			debug "found set name #{OL(firstItem)}"
+			lTree = lTree.slice(1)
+			@mkSet firstItem, lTree
+
+		for item in lTree
+			if isArray(item)
+				debug "init subtree"
+				@init item
+			else if isSectionName(item)
+				debug "mkSection #{OL(item)}"
+				@mkSection item
+			else
+				assert isString(item), "Bad item in tree: #{OL(item)}"
+		debug "return from init()"
 		return
 
 	# ..........................................................
-	# --- hProc should be <name> -> <function>
-	#     <name> can be a section name or a set name
-	#     <function> should be <block> -> <block>
-	# --- desc can be:
-	#        an array, which may begin with a set name
-	#        a section name
-	#        a set name
-	#        undef (equivalent to being set to @SectionTree)
-
-	getBlock: (desc=undef, hReplacers={}) ->
-
-		debug "enter SectionMap.getBlock()", desc, hReplacers
-
-		# --- desc can only be a string or an array
-		#     so, if it's a hash, then it's really the hReplacers
-		#     and the real desc is undef
-
-		if isHash(desc)
-			debug "arg 1 is hReplacers, no desc"
-			assert isEmpty(hReplacers), "invalid parms"
-			hReplacers = desc
-			desc = @lSectionTree
-		else if notdefined(desc)
-			debug "desc is entire tree"
-			desc = @lSectionTree
-
-		if isArray(desc)
-			debug "item is an array"
-			lBlocks = []
-			setName = undef
-			for item in desc
-				subBlock = undef
-				if isSetName(item)
-					debug "set name is #{item}"
-					setName = item
-				else if isSectionName(item) || isArray(item)
-					subBlock = @getBlock(item, hReplacers)
-					if defined(subBlock)
-						debug "add subBlock", subBlock
-						lBlocks.push subBlock
-					else
-						debug "subBlock is undef"
-				else if isString(item) && nonEmpty(item)
-					debug "add string", item
-					lBlocks.push item
-				else
-					croak "Bad item: #{OL(item)}"
 
-			block = toBlock(lBlocks)
-			debug "block is", block
-			if defined(setName)
-				if defined(proc = hReplacers[setName])
-					block = proc(block)
-					debug "REPLACE #{setName} with", block
-				else
-					debug "NO REPLACER for #{setName}"
-		else if isSectionName(desc)
+	mkSet: (name, lTree) ->
+
+		assert isArray(lTree), "tree is not an array"
+		assert nonEmpty(lTree), "set without sections"
+		assert notdef(@hSets[name]), "set #{OL(name)} already exists"
+		@hSets[name] = lTree
+		return
+
+	# ..........................................................
+
+	mkSection: (name) ->
+
+		assert notdef(@hSections[name]), "duplicate section name"
+		@hSections[name] = new Section(name, @hReplacers[name])
+		return
+
+	# ..........................................................
+
+	getBlock: (desc='ALL') ->
+		# ..........................................................
+		# --- desc can be:
+		#        a section name
+		#        a set name
+		#        an array of section or set names or literal strings
+		#     i.e. it should NOT contain sub-arrays
+
+		if isString(desc)
+			debug "enter SectionMap.getBlock(#{OL(desc)})"
+		else if isArrayOfStrings(desc)
+			debug "enter SectionMap.getBlock()", desc
+		else
+			croak "Bad desc: #{OL(desc)}"
+
+		if isSectionName(desc)
 			debug "item is a section name"
+			# --- a section's getBlock() applies any replacer
 			block = @section(desc).getBlock()
-			if defined(proc = hReplacers[desc])
-				debug "REPLACE #{desc}"
-				block = proc(block)
-			else
-				debug "NO REPLACER for #{desc}"
 		else if isSetName(desc)
 			debug "item is a set name"
-			block = @getBlock(@hSets[desc], hReplacers)
+			lBlocks = for item in @hSets[desc]
+				if isArray(item)
+					@getBlock item[0]
+				else if isString(item)
+					@getBlock item
+				else
+					croak "Item in set #{desc} is not a string or array"
+			block = toBlock(lBlocks)
+			replacer = @hReplacers[desc]
+			debug "replacer for is #{OL(replacer)}"
+			if def(replacer)
+				block = replacer(block)
+		else if isString(desc)
+			debug "item is a literal string"
+			# --- a literal string
+			block = desc
+		else if isArray(desc)
+			debug "item is an array"
+			lBlocks = for item in desc
+				@getBlock(item)
+			block = toBlock(lBlocks)
 		else
-			croak "Bad 1st arg: #{OL(desc)}"
+			croak "Bad arg: #{OL(desc)}"
+
 		debug "return from SectionMap.getBlock()", block
 		return block
 
+	# ..........................................................
+	# --- does NOT call any replacers, and skips literal strings
+	#     so only useful for isEmpty() and nonEmpty()
+
+	allSections: (desc=undef) ->
+
+		debug "enter allSections()", desc
+		if notdef(desc)
+			desc = @lFullTree
+
+		if isSectionName(desc)
+			debug "is section name"
+			yield @section(desc)
+		else if isSetName(desc)
+			debug "is set name"
+			for name in @hSets[desc]
+				yield from @allSections(name)
+		else if isArray(desc)
+			debug "is array"
+			for item in desc
+				yield from @allSections(item)
+		debug "return from allSections()"
+		return
+
 	# ..........................................................
 
-	isEmpty: () ->
+	isEmpty: (desc=undef) ->
 
-		for name,sect of @hSections
+		for sect from @allSections(desc)
 			if sect.nonEmpty()
 				return false
 		return true
 
 	# ..........................................................
 
-	nonEmpty: () ->
+	nonEmpty: (desc=undef) ->
 
-		for name,sect of @hSections
+		for sect from @allSections(desc)
 			if sect.nonEmpty()
 				return true
 		return false
@@ -173,7 +191,7 @@ export class SectionMap
 	section: (name) ->
 
 		sect = @hSections[name]
-		assert defined(sect), "No section named #{OL(name)}"
+		assert def(sect), "No section named #{OL(name)}"
 		return sect
 
 	# ..........................................................
@@ -182,8 +200,8 @@ export class SectionMap
 
 		assert isSetName(name), "bad set name #{OL(name)}"
 		lSubTree = @hSets[name]
-		assert defined(lSubTree), "no such set #{OL(name)}"
-		return @section(lSubTree[1])
+		assert def(lSubTree), "no such set #{OL(name)}"
+		return @section(lSubTree[0])
 
 	# ..........................................................
 
@@ -191,5 +209,37 @@ export class SectionMap
 
 		assert isSetName(name), "bad set name #{OL(name)}"
 		lSubTree = @hSets[name]
-		assert defined(lSubTree), "no such set #{OL(name)}"
+		assert def(lSubTree), "no such set #{OL(name)}"
 		return @section(lSubTree[lSubTree.length - 1])
+
+	# ..........................................................
+
+	checkTree: (tree) ->
+
+		debug "enter checkTree()"
+		if isString(tree)
+			debug "tree is a string"
+			assert isTAML(tree), "not TAML"
+			@lFullTree = fromTAML(tree)
+		else
+			@lFullTree = tree
+
+		assert isArray(@lFullTree), "not an array"
+		assert nonEmpty(@lFullTree), "tree is empty"
+		if isSetName(@lFullTree[0])
+			LOGTAML 'lFullTree', @lFullTree
+			croak "tree cannot begin with a set name"
+		debug "return from checkTree()"
+		return
+
+	# ..........................................................
+
+	checkReplacers: (h) ->
+
+		assert isHash(h), "replacers is not a hash"
+		for key,func of h
+			assert isSetName(key) || isSectionName(key), "bad replacer key"
+			assert isFunction(func),
+					"replacer for #{OL(key)} is not a function"
+		return
+

package/src/SectionMap.js

@@ -4,22 +4,20 @@ var isSectionName, isSetName;
 
 import {
   assert,
-  croak
+  croak,
+  LOG,
+  LOGVALUE,
+  LOGTAML,
+  debug,
+  isTAML,
+  fromTAML
 } from '@jdeighan/exceptions';
 
-import {
-  LOG
-} from '@jdeighan/exceptions/log';
-
-import {
-  debug
-} from '@jdeighan/exceptions/debug';
-
 import {
   pass,
   undef,
-  defined,
-  notdefined,
+  def,
+  notdef,
   OL,
   isEmpty,
   nonEmpty,
@@ -28,18 +26,16 @@ import {
   isArray,
   isUniqueTree,
   isNonEmptyString,
-  isNonEmptyArray
+  isNonEmptyArray,
+  isFunction,
+  jsType,
+  isArrayOfStrings
 } from '@jdeighan/coffee-utils';
 
 import {
   toBlock
 } from '@jdeighan/coffee-utils/block';
 
-import {
-  isTAML,
-  fromTAML
-} from '@jdeighan/coffee-utils/taml';
-
 import {
   Section
 } from '@jdeighan/coffee-utils/section';
@@ -56,142 +52,170 @@ isSetName = function(name) {
 
 // ---------------------------------------------------------------------------
 export var SectionMap = class SectionMap {
-  constructor(lSectionTree) {
-    this.lSectionTree = lSectionTree;
-    // --- lSectionTree is a tree of section/set names
-    debug("enter SectionMap()", this.lSectionTree);
-    if (isTAML(this.lSectionTree)) {
-      this.SectionTree = fromTAML(this.lSectionTree);
-    }
-    assert(isArray(this.lSectionTree), "not an array");
-    // --- keys are section names, values are Section objects
-    this.hSections = {};
-    // --- keys are set names, values are subtrees of lSectionTree
-    this.hSets = {};
-    this.build(this.lSectionTree);
-    debug("return from SectionMap()", this.hSections);
+  constructor(tree, hReplacers = {}) {
+    this.hReplacers = hReplacers;
+    // --- tree is a tree of section/set names
+    //        or a TAML string that converts to one
+    // --- hReplacers are callbacks that are called
+    //        when a set or section is processed
+    //        should be <name> -> <function>
+    //     <name> can be a section name or a set name
+    //     <function> should be <block> -> <block>
+    debug("enter SectionMap()", tree, this.hReplacers);
+    this.checkTree(tree);
+    this.checkReplacers(this.hReplacers);
+    this.hSections = {}; // --- {section name: Section Object}
+    this.hSets = {
+      ALL: this.lFullTree // --- {set name: array of parts}
+    };
+    this.init(this.lFullTree);
+    debug('hSections', this.hSections);
+    debug('hSets', this.hSets);
+    debug("return from SectionMap()");
   }
 
   // ..........................................................
-  build(lTree) {
-    var firstItem, i, item, j, len, len1, ref;
-    debug("enter build()", lTree);
+  init(lTree) {
+    var firstItem, i, item, len;
+    debug("enter init()", lTree);
     assert(isArray(lTree), "not an array");
     assert(nonEmpty(lTree), "empty array");
     firstItem = lTree[0];
     if (isSetName(firstItem)) {
-      assert(lTree.length >= 2, "set without sections");
-      this.hSets[firstItem] = lTree;
-      ref = lTree.slice(1);
-      for (i = 0, len = ref.length; i < len; i++) {
-        item = ref[i];
-        if (isArray(item)) {
-          this.build(item);
-        } else if (isSectionName(item)) {
-          this.hSections[item] = new Section(item);
-        } else if (!isString(item)) { // string would be literal
-          croak(`Bad section tree: ${OL(this.lSectionTree)}`);
-        }
-      }
-    } else {
-      for (j = 0, len1 = lTree.length; j < len1; j++) {
-        item = lTree[j];
-        if (isArray(item)) {
-          this.build(item);
-        } else if (isSectionName(item)) {
-          this.hSections[item] = new Section(item);
-        } else {
-          croak(`Bad section tree: ${OL(this.lSectionTree)}`);
-        }
+      debug(`found set name ${OL(firstItem)}`);
+      lTree = lTree.slice(1);
+      this.mkSet(firstItem, lTree);
+    }
+    for (i = 0, len = lTree.length; i < len; i++) {
+      item = lTree[i];
+      if (isArray(item)) {
+        debug("init subtree");
+        this.init(item);
+      } else if (isSectionName(item)) {
+        debug(`mkSection ${OL(item)}`);
+        this.mkSection(item);
+      } else {
+        assert(isString(item), `Bad item in tree: ${OL(item)}`);
       }
     }
-    debug("return from build()", this.hSections, this.hSets);
+    debug("return from init()");
+  }
+
+  // ..........................................................
+  mkSet(name, lTree) {
+    assert(isArray(lTree), "tree is not an array");
+    assert(nonEmpty(lTree), "set without sections");
+    assert(notdef(this.hSets[name]), `set ${OL(name)} already exists`);
+    this.hSets[name] = lTree;
   }
 
   // ..........................................................
-  // --- hProc should be <name> -> <function>
-  //     <name> can be a section name or a set name
-  //     <function> should be <block> -> <block>
-  // --- desc can be:
-  //        an array, which may begin with a set name
-  //        a section name
-  //        a set name
-  //        undef (equivalent to being set to @SectionTree)
-  getBlock(desc = undef, hReplacers = {}) {
-    var block, i, item, lBlocks, len, proc, setName, subBlock;
-    debug("enter SectionMap.getBlock()", desc, hReplacers);
-    // --- desc can only be a string or an array
-    //     so, if it's a hash, then it's really the hReplacers
-    //     and the real desc is undef
-    if (isHash(desc)) {
-      debug("arg 1 is hReplacers, no desc");
-      assert(isEmpty(hReplacers), "invalid parms");
-      hReplacers = desc;
-      desc = this.lSectionTree;
-    } else if (notdefined(desc)) {
-      debug("desc is entire tree");
-      desc = this.lSectionTree;
+  mkSection(name) {
+    assert(notdef(this.hSections[name]), "duplicate section name");
+    this.hSections[name] = new Section(name, this.hReplacers[name]);
+  }
+
+  // ..........................................................
+  getBlock(desc = 'ALL') {
+    var block, item, lBlocks, replacer;
+    // ..........................................................
+    // --- desc can be:
+    //        a section name
+    //        a set name
+    //        an array of section or set names or literal strings
+    //     i.e. it should NOT contain sub-arrays
+    if (isString(desc)) {
+      debug(`enter SectionMap.getBlock(${OL(desc)})`);
+    } else if (isArrayOfStrings(desc)) {
+      debug("enter SectionMap.getBlock()", desc);
+    } else {
+      croak(`Bad desc: ${OL(desc)}`);
     }
-    if (isArray(desc)) {
-      debug("item is an array");
-      lBlocks = [];
-      setName = undef;
-      for (i = 0, len = desc.length; i < len; i++) {
-        item = desc[i];
-        subBlock = undef;
-        if (isSetName(item)) {
-          debug(`set name is ${item}`);
-          setName = item;
-        } else if (isSectionName(item) || isArray(item)) {
-          subBlock = this.getBlock(item, hReplacers);
-          if (defined(subBlock)) {
-            debug("add subBlock", subBlock);
-            lBlocks.push(subBlock);
+    if (isSectionName(desc)) {
+      debug("item is a section name");
+      // --- a section's getBlock() applies any replacer
+      block = this.section(desc).getBlock();
+    } else if (isSetName(desc)) {
+      debug("item is a set name");
+      lBlocks = (function() {
+        var i, len, ref, results;
+        ref = this.hSets[desc];
+        results = [];
+        for (i = 0, len = ref.length; i < len; i++) {
+          item = ref[i];
+          if (isArray(item)) {
+            results.push(this.getBlock(item[0]));
+          } else if (isString(item)) {
+            results.push(this.getBlock(item));
           } else {
-            debug("subBlock is undef");
+            results.push(croak(`Item in set ${desc} is not a string or array`));
           }
-        } else if (isString(item) && nonEmpty(item)) {
-          debug("add string", item);
-          lBlocks.push(item);
-        } else {
-          croak(`Bad item: ${OL(item)}`);
         }
-      }
+        return results;
+      }).call(this);
       block = toBlock(lBlocks);
-      debug("block is", block);
-      if (defined(setName)) {
-        if (defined(proc = hReplacers[setName])) {
-          block = proc(block);
-          debug(`REPLACE ${setName} with`, block);
-        } else {
-          debug(`NO REPLACER for ${setName}`);
-        }
-      }
-    } else if (isSectionName(desc)) {
-      debug("item is a section name");
-      block = this.section(desc).getBlock();
-      if (defined(proc = hReplacers[desc])) {
-        debug(`REPLACE ${desc}`);
-        block = proc(block);
-      } else {
-        debug(`NO REPLACER for ${desc}`);
+      replacer = this.hReplacers[desc];
+      debug(`replacer for is ${OL(replacer)}`);
+      if (def(replacer)) {
+        block = replacer(block);
       }
-    } else if (isSetName(desc)) {
-      debug("item is a set name");
-      block = this.getBlock(this.hSets[desc], hReplacers);
+    } else if (isString(desc)) {
+      debug("item is a literal string");
+      // --- a literal string
+      block = desc;
+    } else if (isArray(desc)) {
+      debug("item is an array");
+      lBlocks = (function() {
+        var i, len, results;
+        results = [];
+        for (i = 0, len = desc.length; i < len; i++) {
+          item = desc[i];
+          results.push(this.getBlock(item));
+        }
+        return results;
+      }).call(this);
+      block = toBlock(lBlocks);
     } else {
-      croak(`Bad 1st arg: ${OL(desc)}`);
+      croak(`Bad arg: ${OL(desc)}`);
     }
     debug("return from SectionMap.getBlock()", block);
     return block;
   }
 
   // ..........................................................
-  isEmpty() {
-    var name, ref, sect;
-    ref = this.hSections;
-    for (name in ref) {
-      sect = ref[name];
+  // --- does NOT call any replacers, and skips literal strings
+  //     so only useful for isEmpty() and nonEmpty()
+  * allSections(desc = undef) {
+    var i, item, j, len, len1, name, ref;
+    debug("enter allSections()", desc);
+    if (notdef(desc)) {
+      desc = this.lFullTree;
+    }
+    if (isSectionName(desc)) {
+      debug("is section name");
+      yield this.section(desc);
+    } else if (isSetName(desc)) {
+      debug("is set name");
+      ref = this.hSets[desc];
+      for (i = 0, len = ref.length; i < len; i++) {
+        name = ref[i];
+        yield* this.allSections(name);
+      }
+    } else if (isArray(desc)) {
+      debug("is array");
+      for (j = 0, len1 = desc.length; j < len1; j++) {
+        item = desc[j];
+        yield* this.allSections(item);
+      }
+    }
+    debug("return from allSections()");
+  }
+
+  // ..........................................................
+  isEmpty(desc = undef) {
+    var ref, sect;
+    ref = this.allSections(desc);
+    for (sect of ref) {
       if (sect.nonEmpty()) {
         return false;
       }
@@ -200,11 +224,10 @@ export var SectionMap = class SectionMap {
   }
 
   // ..........................................................
-  nonEmpty() {
-    var name, ref, sect;
-    ref = this.hSections;
-    for (name in ref) {
-      sect = ref[name];
+  nonEmpty(desc = undef) {
+    var ref, sect;
+    ref = this.allSections(desc);
+    for (sect of ref) {
       if (sect.nonEmpty()) {
         return true;
       }
@@ -216,7 +239,7 @@ export var SectionMap = class SectionMap {
   section(name) {
     var sect;
     sect = this.hSections[name];
-    assert(defined(sect), `No section named ${OL(name)}`);
+    assert(def(sect), `No section named ${OL(name)}`);
     return sect;
   }
 
@@ -225,8 +248,8 @@ export var SectionMap = class SectionMap {
     var lSubTree;
     assert(isSetName(name), `bad set name ${OL(name)}`);
     lSubTree = this.hSets[name];
-    assert(defined(lSubTree), `no such set ${OL(name)}`);
-    return this.section(lSubTree[1]);
+    assert(def(lSubTree), `no such set ${OL(name)}`);
+    return this.section(lSubTree[0]);
   }
 
   // ..........................................................
@@ -234,8 +257,38 @@ export var SectionMap = class SectionMap {
     var lSubTree;
     assert(isSetName(name), `bad set name ${OL(name)}`);
     lSubTree = this.hSets[name];
-    assert(defined(lSubTree), `no such set ${OL(name)}`);
+    assert(def(lSubTree), `no such set ${OL(name)}`);
     return this.section(lSubTree[lSubTree.length - 1]);
   }
 
+  // ..........................................................
+  checkTree(tree) {
+    debug("enter checkTree()");
+    if (isString(tree)) {
+      debug("tree is a string");
+      assert(isTAML(tree), "not TAML");
+      this.lFullTree = fromTAML(tree);
+    } else {
+      this.lFullTree = tree;
+    }
+    assert(isArray(this.lFullTree), "not an array");
+    assert(nonEmpty(this.lFullTree), "tree is empty");
+    if (isSetName(this.lFullTree[0])) {
+      LOGTAML('lFullTree', this.lFullTree);
+      croak("tree cannot begin with a set name");
+    }
+    debug("return from checkTree()");
+  }
+
+  // ..........................................................
+  checkReplacers(h) {
+    var func, key;
+    assert(isHash(h), "replacers is not a hash");
+    for (key in h) {
+      func = h[key];
+      assert(isSetName(key) || isSectionName(key), "bad replacer key");
+      assert(isFunction(func), `replacer for ${OL(key)} is not a function`);
+    }
+  }
+
 };

package/src/block.coffee

@@ -63,7 +63,8 @@ export toBlock = (lLines) ->
 
 	if notdefined(lLines)
 		return undef
-	assert isArrayOfStrings(lLines), "lLines is not an array: #{OL(lLines)}"
+	assert isArrayOfStrings(lLines),
+		"lLines is not an array of strings: #{OL(lLines)}"
 	lNewLines = []
 	for line in lLines
 		if defined(line)

package/src/block.js

@@ -90,7 +90,7 @@ export var toBlock = function(lLines) {
   if (notdefined(lLines)) {
     return undef;
   }
-  assert(isArrayOfStrings(lLines), `lLines is not an array: ${OL(lLines)}`);
+  assert(isArrayOfStrings(lLines), `lLines is not an array of strings: ${OL(lLines)}`);
   lNewLines = [];
   for (i = 0, len = lLines.length; i < len; i++) {
     line = lLines[i];

package/src/fs.coffee

@@ -5,7 +5,7 @@ import urllib from 'url'
 import fs from 'fs'
 import NReadLines from 'n-readlines'
 
-import {assert, croak, LOG, fromTAML} from '@jdeighan/exceptions'
+import {assert, croak, debug, LOG, fromTAML} from '@jdeighan/exceptions'
 import {
 	undef, pass, defined, rtrim, isEmpty, nonEmpty, getOptions,
 	isString, isArray, isHash, isRegExp, isFunction, OL,
@@ -377,6 +377,7 @@ export parseSource = (source) ->
 	#        }
 	# --- NOTE: source may be a file URL, e.g. import.meta.url
 
+	debug "enter parseSource(#{OL(source)})"
 	assert isString(source),\
 			"parseSource(): source not a string: #{OL(source)}"
 	if source == 'unit test'
@@ -413,6 +414,7 @@ export parseSource = (source) ->
 				([A-Za-z_]+)
 				$///)
 			hSourceInfo.purpose = lMatches[1]
+	debug "return from parseSource()", hSourceInfo
 	return hSourceInfo
 
 # ---------------------------------------------------------------------------

package/src/fs.js

@@ -13,6 +13,7 @@ import NReadLines from 'n-readlines';
 import {
   assert,
   croak,
+  debug,
   LOG,
   fromTAML
 } from '@jdeighan/exceptions';
@@ -446,6 +447,7 @@ export var parseSource = function(source) {
   //        purpose
   //        }
   // --- NOTE: source may be a file URL, e.g. import.meta.url
+  debug(`enter parseSource(${OL(source)})`);
   assert(isString(source), `parseSource(): source not a string: ${OL(source)}`);
   if (source === 'unit test') {
     croak("A source of 'unit test' is deprecated");
@@ -481,6 +483,7 @@ export var parseSource = function(source) {
       hSourceInfo.purpose = lMatches[1];
     }
   }
+  debug("return from parseSource()", hSourceInfo);
   return hSourceInfo;
 };
 

package/src/utils.coffee

@@ -11,8 +11,11 @@ import {
 	isEmpty, nonEmpty, chomp, rtrim, setCharsAt, words, getOptions,
 	} from '@jdeighan/exceptions/utils'
 
+def = defined
+notdef = notdefined
+
 export {
-	undef, pass, defined, notdefined, LOG, sep_dash, sep_eq,
+	undef, pass, def, defined, notdef, notdefined, LOG, sep_dash, sep_eq,
 	deepCopy, escapeStr, unescapeStr, hasChar, quoted, OL,
 	isString, isNumber, isInteger, isHash, isArray, isBoolean,
 	isConstructor, isFunction, isRegExp, isObject, getClassName,
@@ -137,22 +140,24 @@ export pushCond = (lItems, item, doPush=notInArray) ->
 # ---------------------------------------------------------------------------
 
 export isArrayOfHashes = (lItems) ->
+	# --- undefined items are allowed
 
 	if ! isArray(lItems)
 		return false
 	for item in lItems
-		if ! isHash(item)
+		if defined(item) && ! isHash(item)
 			return false
 	return true
 
 # ---------------------------------------------------------------------------
 
 export isArrayOfStrings = (lItems) ->
+	# --- undefined items are allowed
 
 	if ! isArray(lItems)
 		return false
 	for item in lItems
-		if ! isString(item)
+		if defined(item) && ! isString(item)
 			return false
 	return true
 

package/src/utils.js

@@ -1,6 +1,7 @@
 // Generated by CoffeeScript 2.7.0
-// utils.coffee
-var hasProp = {}.hasOwnProperty;
+  // utils.coffee
+var def, notdef,
+  hasProp = {}.hasOwnProperty;
 
 import {
   assert,
@@ -45,10 +46,16 @@ import {
   getOptions
 } from '@jdeighan/exceptions/utils';
 
+def = defined;
+
+notdef = notdefined;
+
 export {
   undef,
   pass,
+  def,
   defined,
+  notdef,
   notdefined,
   LOG,
   sep_dash,
@@ -202,7 +209,7 @@ export var isArrayOfHashes = function(lItems) {
   }
   for (i = 0, len = lItems.length; i < len; i++) {
     item = lItems[i];
-    if (!isHash(item)) {
+    if (defined(item) && !isHash(item)) {
       return false;
     }
   }
@@ -217,7 +224,7 @@ export var isArrayOfStrings = function(lItems) {
   }
   for (i = 0, len = lItems.length; i < len; i++) {
     item = lItems[i];
-    if (!isString(item)) {
+    if (defined(item) && !isString(item)) {
       return false;
     }
   }

package/src/placeholders.coffee

@@ -1,26 +0,0 @@
-# placeholders.coffee
-
-import {assert, croak} from '@jdeighan/exceptions'
-import {undef, defined} from '@jdeighan/coffee-utils'
-
-hDefOptions = {
-	pre:  '__'
-	post: '__'
-	}
-
-# ---------------------------------------------------------------------------
-
-export phStr = (name, hOptions=hDefOptions) ->
-
-	{pre, post} = hOptions
-	return "#{pre}#{name}#{post}"
-
-# ---------------------------------------------------------------------------
-
-export phReplace = (str, hValues, hOptions=hDefOptions) ->
-
-	{pre, post} = hOptions
-	return str.replace(
-			/// #{pre} ([A-Za-z_][A-Za-z0-9_]*) #{post} ///g,
-			(_, name) -> hValues[name]
-			)

package/src/placeholders.js

@@ -1,34 +0,0 @@
-// Generated by CoffeeScript 2.7.0
-// placeholders.coffee
-var hDefOptions;
-
-import {
-  assert,
-  croak
-} from '@jdeighan/exceptions';
-
-import {
-  undef,
-  defined
-} from '@jdeighan/coffee-utils';
-
-hDefOptions = {
-  pre: '__',
-  post: '__'
-};
-
-// ---------------------------------------------------------------------------
-export var phStr = function(name, hOptions = hDefOptions) {
-  var post, pre;
-  ({pre, post} = hOptions);
-  return `${pre}${name}${post}`;
-};
-
-// ---------------------------------------------------------------------------
-export var phReplace = function(str, hValues, hOptions = hDefOptions) {
-  var post, pre;
-  ({pre, post} = hOptions);
-  return str.replace(RegExp(`${pre}([A-Za-z_][A-Za-z0-9_]*)${post}`, "g"), function(_, name) {
-    return hValues[name];
-  });
-};