@jdeighan/coffee-utils 9.0.4 → 10.0.1

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@jdeighan/coffee-utils",
 	"type": "module",
-	"version": "9.0.4",
+	"version": "10.0.1",
 	"description": "A set of utility functions for CoffeeScript",
 	"main": "coffee_utils.js",
 	"exports": {

package/src/Section.coffee

@@ -2,18 +2,22 @@
 
 import {assert, error, croak} from '@jdeighan/unit-tester/utils'
 import {
-	pass, undef, defined, isArray,
+	pass, undef, defined, isArray, isEmpty,
 	} from '@jdeighan/coffee-utils'
 import {arrayToBlock} from '@jdeighan/coffee-utils/block'
 import {indented} from '@jdeighan/coffee-utils/indent'
+import {debug} from '@jdeighan/coffee-utils/debug'
 
 # ---------------------------------------------------------------------------
 
 export class Section
 
-	constructor: (@name) ->
+	constructor: (@name, content=undef) ->
+		# --- name can be undef or empty
 
 		@lParts = []
+		if defined(content)
+			@lParts.push content
 
 	# ..........................................................
 
@@ -73,7 +77,11 @@ export class Section
 
 	getBlock: () ->
 
+		debug "enter Section.getBlock()"
 		if (@lParts.length == 0)
+			debug "return undef from Section.getBlock()"
 			return undef
 		else
-			return arrayToBlock(@lParts)
+			result = arrayToBlock(@lParts)
+			debug "return from Section.getBlock()", result
+			return result

package/src/Section.js

@@ -10,7 +10,8 @@ import {
   pass,
   undef,
   defined,
-  isArray
+  isArray,
+  isEmpty
 } from '@jdeighan/coffee-utils';
 
 import {
@@ -21,11 +22,19 @@ import {
   indented
 } from '@jdeighan/coffee-utils/indent';
 
+import {
+  debug
+} from '@jdeighan/coffee-utils/debug';
+
 // ---------------------------------------------------------------------------
 export var Section = class Section {
-  constructor(name) {
+  constructor(name, content = undef) {
     this.name = name;
+    // --- name can be undef or empty
     this.lParts = [];
+    if (defined(content)) {
+      this.lParts.push(content);
+    }
   }
 
   // ..........................................................
@@ -88,10 +97,15 @@ export var Section = class Section {
 
   // ..........................................................
   getBlock() {
+    var result;
+    debug("enter Section.getBlock()");
     if (this.lParts.length === 0) {
+      debug("return undef from Section.getBlock()");
       return undef;
     } else {
-      return arrayToBlock(this.lParts);
+      result = arrayToBlock(this.lParts);
+      debug("return from Section.getBlock()", result);
+      return result;
     }
   }
 

package/src/SectionMap.coffee

@@ -2,12 +2,13 @@
 
 import {assert, error, croak} from '@jdeighan/unit-tester/utils'
 import {
-	pass, undef, defined, OL, isEmpty, nonEmpty,
+	pass, undef, defined, notdefined, OL, isEmpty, nonEmpty,
 	isString, isHash, isArray, isUniqueTree, isNonEmptyString,
 	isNonEmptyArray,
 	} from '@jdeighan/coffee-utils'
 import {arrayToBlock} from '@jdeighan/coffee-utils/block'
 import {indented} from '@jdeighan/coffee-utils/indent'
+import {LOG} from '@jdeighan/coffee-utils/log'
 import {debug} from '@jdeighan/coffee-utils/debug'
 import {Section} from '@jdeighan/coffee-utils/section'
 
@@ -15,149 +16,145 @@ import {Section} from '@jdeighan/coffee-utils/section'
 
 isSectionName = (name) ->
 
-	return isString(name) && name.match(/^[a-z][a-z0-9]*/)
+	return isString(name) && name.match(/^[a-z][a-z0-9_]*/)
 
 # ---------------------------------------------------------------------------
 
 isSetName = (name) ->
 
-	return isString(name) && name.match(/^[A-Z][a-z0-9]*/)
+	return isString(name) && name.match(/^[A-Z][a-z0-9_]*/)
 
 # ---------------------------------------------------------------------------
 
 export class SectionMap
 
-	constructor: (lSectionTree) ->
-		# --- lSectionTree is a tree of section names
+	constructor: (@lSectionTree) ->
+		# --- lSectionTree is a tree of section/set names
 
-		debug "enter SectionMap()", lSectionTree
-		@lSectionTree = lSectionTree   # a tree of section names
-		@hSets = {}
+		debug "enter SectionMap()", @lSectionTree
+		assert isArray(@lSectionTree), "not an array"
+
+		# --- keys are section names, values are Section objects
 		@hSections = {}
-		@addSections lSectionTree
+
+		# --- keys are set names, values are subtrees of lSectionTree
+		@hSets = {}
+
+		@build @lSectionTree
 		debug "return from SectionMap()", @hSections
 
 	# ..........................................................
 
-	addSections: (desc) ->
-		# --- returns a flat array of sections that were added
-
-		if isString(desc)
-			assert nonEmpty(desc), "empty section name"
-			assert isSectionName(desc), "bad section name #{OL(desc)}"
-			assert (@hSections[desc] == undef), "duplicate section #{OL(desc)}"
-			@hSections[desc] = new Section(desc)
-			return [desc]
+	build: (lTree) ->
+
+		debug "enter build()", 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
-			assert isArray(desc), "not an array or string #{OL(desc)}"
-			name = undef
-			lParts = []
-			for item,i in desc
-				if (i==0) && isSetName(item)
-					name = item
+			for item in lTree
+				if isArray(item)
+					@build item
+				else if isSectionName(item)
+					@hSections[item] = new Section(item)
 				else
-					lAdded = @addSections item
-					for item in lAdded
-						lParts.push item
-			if defined(name)
-				@addSet name, lParts
-			return lParts
+					croak "Bad section tree: #{OL(@lSectionTree)}"
+		debug "return from build()", @hSections, @hSets
 		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)
 
-	addSet: (name, lSectionTree) ->
-
-		debug "enter addSet()", name, lSectionTree
-
-		# --- check the name
-		assert isSetName(name), "not a valid set name #{OL(name)}"
-
-		# --- check lSectionTree
-		assert isArray(lSectionTree), "arg 2 not an array"
-		for secName in lSectionTree
-			assert isNonEmptyString(secName),
-					"not a non-empty string #{OL(secName)}"
-			assert defined(@hSections[secName]),
-					"not a section name #{OL(secName)}"
-
-		@hSets[name] = lSectionTree
-		debug 'hSets', @hSets
-		debug "return from addSet()"
-		return
+	getBlock: (desc=undef, hReplacers={}) ->
 
-	# ..........................................................
-	# --- sections returned in depth-first order from section tree
-	#     Set names are simply skipped
-	#     yields: [<level>, <section>]
+		debug "enter SectionMap.getBlock()", desc, hReplacers
 
-	allSections: (desc=undef, level=0) ->
+		# --- 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
 
-		debug "enter allSections()", desc, level
-		if (desc == undef)
+		if isHash(desc)
+			debug "arg 1 is hReplacers, no desc"
+			assert isEmpty(hReplacers), "invalid parms"
+			hReplacers = desc
 			desc = @lSectionTree
+		else if notdefined(desc)
+			desc = @lSectionTree
+
 		if isArray(desc)
+			lBlocks = []
+			setName = undef
 			for item in desc
-				if isSectionName(item)
-					result = [level, @section(item)]
-					debug 'yield', result
-					yield result
+				subBlock = undef
+				if isArray(item)
+					subBlock = @getBlock(item, hReplacers)
+				else if isSectionName(item)
+					subBlock = @getBlock(item, hReplacers)
 				else if isSetName(item)
-					pass
+					setName = item
+				else if isString(item)
+					subBlock = item   # a literal string
+				else
+					croak "Bad item: #{OL(item)}"
+				if defined(subBlock)
+					lBlocks.push subBlock
+			block = arrayToBlock(lBlocks)
+			if defined(setName)
+				if defined(proc = hReplacers[setName])
+					debug "REPLACE #{setName}"
+					block = proc(block)
 				else
-					assert isArray(item), "not an array #{OL(item)}"
-					yield from @allSections(item, level+1)
+					debug "NO REPLACER for #{setName}"
 		else if isSectionName(desc)
-			result = [level, @section(desc)]
-			debug 'yield', result
-			yield result
+			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)
-			lTree = @hSets[desc]
-			assert defined(lTree), "Not a Set: #{OL(desc)}"
-			yield from @allSections(lTree, level)
+			# --- pass array to getBlock()
+			block = @getBlock(@hSets[desc], hReplacers)
 		else
-			croak "Bad item: #{OL(desc)}"
-		debug "return from allSections()"
-		return
+			croak "Bad 1st arg: #{OL(desc)}"
+		debug "return from SectionMap.getBlock()", block
+		return block
 
 	# ..........................................................
-	# --- hProc should be <name> -> <function>
-	#     <function> should be <block> -> <block>
-	# --- lTree allows you to get just a section
 
-	getBlock: (hProc={}, lTree=undef) ->
+	isEmpty: () ->
 
-		debug "enter getBlock()"
-		if (lTree == undef)
-			lTree = @lSectionTree
-		else
-			assert isArray(lTree), "not an array #{OL(lTree)}"
-
-		lParts = []
-		for part in lTree
-			if isString(part)
-				block = @section(part).getBlock()
-				if defined(hProc[part])
-					# --- called even if block is empty
-					block = hProc[part](block)
-			else if isNonEmptyArray(part)
-				if isSectionName(part[0])
-					block = @getBlock(hProc, part)
-				else if isSetName(part[0])
-					block = @getBlock(hProc, part.slice(1))
-					if defined(hProc[part[0]])
-						block = hProc[part[0]](block)
-				else
-					croak "Bad part: #{OL(part)}"
-			else
-				croak "Bad part: #{OL(part)}"
-			if defined(block)
-				lParts.push block
+		for name,sect of @hSections
+			if sect.nonEmpty()
+				return false
+		return true
+
+	# ..........................................................
+
+	nonEmpty: () ->
 
-		debug 'lParts', lParts
-		result = arrayToBlock(lParts)
-		debug "return from getBlock()", result
-		return result
+		for name,sect of @hSections
+			if sect.nonEmpty()
+				return true
+		return false
 
 	# ..........................................................
 
@@ -172,50 +169,15 @@ export class SectionMap
 	firstSection: (name) ->
 
 		assert isSetName(name), "bad set name #{OL(name)}"
-		lSectionTree = @hSets[name]
-		assert defined(lSectionTree), "no such set #{OL(name)}"
-		assert nonEmpty(lSectionTree), "empty section #{OL(name)}"
-		return @section(lSectionTree[0])
+		lSubTree = @hSets[name]
+		assert defined(lSubTree), "no such set #{OL(name)}"
+		return @section(lSubTree[1])
 
 	# ..........................................................
 
 	lastSection: (name) ->
 
 		assert isSetName(name), "bad set name #{OL(name)}"
-		lSectionTree = @hSets[name]
-		assert defined(lSectionTree), "no such set #{OL(name)}"
-		assert nonEmpty(lSectionTree), "empty section #{OL(name)}"
-		return @section(lSectionTree[lSectionTree.length - 1])
-
-	# ..........................................................
-
-	length: (desc=undef) ->
-
-		result = 0
-		for [_, sect] from @allSections(desc)
-			result += sect.length()
-		return result
-
-	# ..........................................................
-
-	isEmpty: (desc=undef) ->
-
-		return (@length(desc) == 0)
-
-	# ..........................................................
-
-	nonEmpty: (desc=undef) ->
-
-		return (@length(desc) > 0)
-
-	# ..........................................................
-
-	getShape: () ->
-
-		debug "enter getShape()"
-		lParts = []
-		for [level, sect] from @allSections()
-			lParts.push indented(sect.name, level)
-		result = arrayToBlock(lParts)
-		debug "return from getShape()", result
-		return result
+		lSubTree = @hSets[name]
+		assert defined(lSubTree), "no such set #{OL(name)}"
+		return @section(lSubTree[lSubTree.length - 1])

package/src/SectionMap.js

@@ -12,6 +12,7 @@ import {
   pass,
   undef,
   defined,
+  notdefined,
   OL,
   isEmpty,
   nonEmpty,
@@ -31,6 +32,10 @@ import {
   indented
 } from '@jdeighan/coffee-utils/indent';
 
+import {
+  LOG
+} from '@jdeighan/coffee-utils/log';
+
 import {
   debug
 } from '@jdeighan/coffee-utils/debug';
@@ -41,158 +46,160 @@ import {
 
 // ---------------------------------------------------------------------------
 isSectionName = function(name) {
-  return isString(name) && name.match(/^[a-z][a-z0-9]*/);
+  return isString(name) && name.match(/^[a-z][a-z0-9_]*/);
 };
 
 // ---------------------------------------------------------------------------
 isSetName = function(name) {
-  return isString(name) && name.match(/^[A-Z][a-z0-9]*/);
+  return isString(name) && name.match(/^[A-Z][a-z0-9_]*/);
 };
 
 // ---------------------------------------------------------------------------
 export var SectionMap = class SectionMap {
   constructor(lSectionTree) {
-    // --- lSectionTree is a tree of section names
-    debug("enter SectionMap()", lSectionTree);
-    this.lSectionTree = lSectionTree; // a tree of section names
-    this.hSets = {};
+    this.lSectionTree = lSectionTree;
+    // --- lSectionTree is a tree of section/set names
+    debug("enter SectionMap()", this.lSectionTree);
+    assert(isArray(this.lSectionTree), "not an array");
+    // --- keys are section names, values are Section objects
     this.hSections = {};
-    this.addSections(lSectionTree);
+    // --- keys are set names, values are subtrees of lSectionTree
+    this.hSets = {};
+    this.build(this.lSectionTree);
     debug("return from SectionMap()", this.hSections);
   }
 
   // ..........................................................
-  addSections(desc) {
-    var i, item, j, k, lAdded, lParts, len, len1, name;
-    // --- returns a flat array of sections that were added
-    if (isString(desc)) {
-      assert(nonEmpty(desc), "empty section name");
-      assert(isSectionName(desc), `bad section name ${OL(desc)}`);
-      assert(this.hSections[desc] === undef, `duplicate section ${OL(desc)}`);
-      this.hSections[desc] = new Section(desc);
-      return [desc];
+  build(lTree) {
+    var firstItem, i, item, j, len, len1, ref;
+    debug("enter build()", 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 {
-      assert(isArray(desc), `not an array or string ${OL(desc)}`);
-      name = undef;
-      lParts = [];
-      for (i = j = 0, len = desc.length; j < len; i = ++j) {
-        item = desc[i];
-        if ((i === 0) && isSetName(item)) {
-          name = item;
+      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 {
-          lAdded = this.addSections(item);
-          for (k = 0, len1 = lAdded.length; k < len1; k++) {
-            item = lAdded[k];
-            lParts.push(item);
-          }
+          croak(`Bad section tree: ${OL(this.lSectionTree)}`);
         }
       }
-      if (defined(name)) {
-        this.addSet(name, lParts);
-      }
-      return lParts;
-    }
-  }
-
-  // ..........................................................
-  addSet(name, lSectionTree) {
-    var j, len, secName;
-    debug("enter addSet()", name, lSectionTree);
-    // --- check the name
-    assert(isSetName(name), `not a valid set name ${OL(name)}`);
-    // --- check lSectionTree
-    assert(isArray(lSectionTree), "arg 2 not an array");
-    for (j = 0, len = lSectionTree.length; j < len; j++) {
-      secName = lSectionTree[j];
-      assert(isNonEmptyString(secName), `not a non-empty string ${OL(secName)}`);
-      assert(defined(this.hSections[secName]), `not a section name ${OL(secName)}`);
     }
-    this.hSets[name] = lSectionTree;
-    debug('hSets', this.hSets);
-    debug("return from addSet()");
+    debug("return from build()", this.hSections, this.hSets);
   }
 
   // ..........................................................
-  // --- sections returned in depth-first order from section tree
-  //     Set names are simply skipped
-  //     yields: [<level>, <section>]
-  * allSections(desc = undef, level = 0) {
-    var item, j, lTree, len, result;
-    debug("enter allSections()", desc, level);
-    if (desc === undef) {
+  // --- 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)) {
       desc = this.lSectionTree;
     }
     if (isArray(desc)) {
-      for (j = 0, len = desc.length; j < len; j++) {
-        item = desc[j];
-        if (isSectionName(item)) {
-          result = [level, this.section(item)];
-          debug('yield', result);
-          yield result;
+      lBlocks = [];
+      setName = undef;
+      for (i = 0, len = desc.length; i < len; i++) {
+        item = desc[i];
+        subBlock = undef;
+        if (isArray(item)) {
+          subBlock = this.getBlock(item, hReplacers);
+        } else if (isSectionName(item)) {
+          subBlock = this.getBlock(item, hReplacers);
         } else if (isSetName(item)) {
-          pass;
+          setName = item;
+        } else if (isString(item)) {
+          subBlock = item; // a literal string
+        } else {
+          croak(`Bad item: ${OL(item)}`);
+        }
+        if (defined(subBlock)) {
+          lBlocks.push(subBlock);
+        }
+      }
+      block = arrayToBlock(lBlocks);
+      if (defined(setName)) {
+        if (defined(proc = hReplacers[setName])) {
+          debug(`REPLACE ${setName}`);
+          block = proc(block);
         } else {
-          assert(isArray(item), `not an array ${OL(item)}`);
-          yield* this.allSections(item, level + 1);
+          debug(`NO REPLACER for ${setName}`);
         }
       }
     } else if (isSectionName(desc)) {
-      result = [level, this.section(desc)];
-      debug('yield', result);
-      yield result;
+      block = this.section(desc).getBlock();
+      if (defined(proc = hReplacers[desc])) {
+        debug(`REPLACE ${desc}`);
+        block = proc(block);
+      } else {
+        debug(`NO REPLACER for ${desc}`);
+      }
     } else if (isSetName(desc)) {
-      lTree = this.hSets[desc];
-      assert(defined(lTree), `Not a Set: ${OL(desc)}`);
-      yield* this.allSections(lTree, level);
+      // --- pass array to getBlock()
+      block = this.getBlock(this.hSets[desc], hReplacers);
     } else {
-      croak(`Bad item: ${OL(desc)}`);
+      croak(`Bad 1st arg: ${OL(desc)}`);
     }
-    debug("return from allSections()");
+    debug("return from SectionMap.getBlock()", block);
+    return block;
   }
 
   // ..........................................................
-  // --- hProc should be <name> -> <function>
-  //     <function> should be <block> -> <block>
-  // --- lTree allows you to get just a section
-  getBlock(hProc = {}, lTree = undef) {
-    var block, j, lParts, len, part, result;
-    debug("enter getBlock()");
-    if (lTree === undef) {
-      lTree = this.lSectionTree;
-    } else {
-      assert(isArray(lTree), `not an array ${OL(lTree)}`);
-    }
-    lParts = [];
-    for (j = 0, len = lTree.length; j < len; j++) {
-      part = lTree[j];
-      if (isString(part)) {
-        block = this.section(part).getBlock();
-        if (defined(hProc[part])) {
-          // --- called even if block is empty
-          block = hProc[part](block);
-        }
-      } else if (isNonEmptyArray(part)) {
-        if (isSectionName(part[0])) {
-          block = this.getBlock(hProc, part);
-        } else if (isSetName(part[0])) {
-          block = this.getBlock(hProc, part.slice(1));
-          if (defined(hProc[part[0]])) {
-            block = hProc[part[0]](block);
-          }
-        } else {
-          croak(`Bad part: ${OL(part)}`);
-        }
-      } else {
-        croak(`Bad part: ${OL(part)}`);
+  isEmpty() {
+    var name, ref, sect;
+    ref = this.hSections;
+    for (name in ref) {
+      sect = ref[name];
+      if (sect.nonEmpty()) {
+        return false;
       }
-      if (defined(block)) {
-        lParts.push(block);
+    }
+    return true;
+  }
+
+  // ..........................................................
+  nonEmpty() {
+    var name, ref, sect;
+    ref = this.hSections;
+    for (name in ref) {
+      sect = ref[name];
+      if (sect.nonEmpty()) {
+        return true;
       }
     }
-    debug('lParts', lParts);
-    result = arrayToBlock(lParts);
-    debug("return from getBlock()", result);
-    return result;
+    return false;
   }
 
   // ..........................................................
@@ -205,59 +212,20 @@ export var SectionMap = class SectionMap {
 
   // ..........................................................
   firstSection(name) {
-    var lSectionTree;
+    var lSubTree;
     assert(isSetName(name), `bad set name ${OL(name)}`);
-    lSectionTree = this.hSets[name];
-    assert(defined(lSectionTree), `no such set ${OL(name)}`);
-    assert(nonEmpty(lSectionTree), `empty section ${OL(name)}`);
-    return this.section(lSectionTree[0]);
+    lSubTree = this.hSets[name];
+    assert(defined(lSubTree), `no such set ${OL(name)}`);
+    return this.section(lSubTree[1]);
   }
 
   // ..........................................................
   lastSection(name) {
-    var lSectionTree;
+    var lSubTree;
     assert(isSetName(name), `bad set name ${OL(name)}`);
-    lSectionTree = this.hSets[name];
-    assert(defined(lSectionTree), `no such set ${OL(name)}`);
-    assert(nonEmpty(lSectionTree), `empty section ${OL(name)}`);
-    return this.section(lSectionTree[lSectionTree.length - 1]);
-  }
-
-  // ..........................................................
-  length(desc = undef) {
-    var _, ref, result, sect, x;
-    result = 0;
-    ref = this.allSections(desc);
-    for (x of ref) {
-      [_, sect] = x;
-      result += sect.length();
-    }
-    return result;
-  }
-
-  // ..........................................................
-  isEmpty(desc = undef) {
-    return this.length(desc) === 0;
-  }
-
-  // ..........................................................
-  nonEmpty(desc = undef) {
-    return this.length(desc) > 0;
-  }
-
-  // ..........................................................
-  getShape() {
-    var lParts, level, ref, result, sect, x;
-    debug("enter getShape()");
-    lParts = [];
-    ref = this.allSections();
-    for (x of ref) {
-      [level, sect] = x;
-      lParts.push(indented(sect.name, level));
-    }
-    result = arrayToBlock(lParts);
-    debug("return from getShape()", result);
-    return result;
+    lSubTree = this.hSets[name];
+    assert(defined(lSubTree), `no such set ${OL(name)}`);
+    return this.section(lSubTree[lSubTree.length - 1]);
   }
 
 };

package/src/block_utils.coffee

@@ -25,6 +25,23 @@ export blockToArray = (block) ->
 			len -= 1
 		return lLines
 
+# ---------------------------------------------------------------------------
+#   toArray - split a block or array into lines w/o newlines
+
+export toArray = (item) ->
+
+	if isString(item)
+		return item.split(/\r?\n/)
+	else if isArray(item)
+		# --- We still need to ensure that no strings contain newlines
+		lLines = []
+		for str in item
+			for substr in toArray(str)
+				lLines.push substr
+		return lLines
+	else
+		croak "Not a string or array"
+
 # ---------------------------------------------------------------------------
 #   arrayToBlock - block will have no trailing whitespace
 
@@ -39,6 +56,21 @@ export arrayToBlock = (lLines) ->
 	else
 		return rtrim(lLines.join('\n'))
 
+# ---------------------------------------------------------------------------
+#   toBlock - block may have trailing whitespace
+#             but undef items are ignored
+
+export toBlock = (lLines) ->
+
+	if (lLines == undef)
+		return undef
+	assert isArray(lLines), "lLines is not an array"
+	lLines = lLines.filter((line) => defined(line));
+	if lLines.length == 0
+		return undef
+	else
+		return lLines.join('\n')
+
 # ---------------------------------------------------------------------------
 
 export splitBlock = (block) ->

package/src/block_utils.js

@@ -37,6 +37,29 @@ export var blockToArray = function(block) {
   }
 };
 
+// ---------------------------------------------------------------------------
+//   toArray - split a block or array into lines w/o newlines
+export var toArray = function(item) {
+  var i, j, lLines, len1, len2, ref, str, substr;
+  if (isString(item)) {
+    return item.split(/\r?\n/);
+  } else if (isArray(item)) {
+    // --- We still need to ensure that no strings contain newlines
+    lLines = [];
+    for (i = 0, len1 = item.length; i < len1; i++) {
+      str = item[i];
+      ref = toArray(str);
+      for (j = 0, len2 = ref.length; j < len2; j++) {
+        substr = ref[j];
+        lLines.push(substr);
+      }
+    }
+    return lLines;
+  } else {
+    return croak("Not a string or array");
+  }
+};
+
 // ---------------------------------------------------------------------------
 //   arrayToBlock - block will have no trailing whitespace
 export var arrayToBlock = function(lLines) {
@@ -54,6 +77,24 @@ export var arrayToBlock = function(lLines) {
   }
 };
 
+// ---------------------------------------------------------------------------
+//   toBlock - block may have trailing whitespace
+//             but undef items are ignored
+export var toBlock = function(lLines) {
+  if (lLines === undef) {
+    return undef;
+  }
+  assert(isArray(lLines), "lLines is not an array");
+  lLines = lLines.filter((line) => {
+    return defined(line);
+  });
+  if (lLines.length === 0) {
+    return undef;
+  } else {
+    return lLines.join('\n');
+  }
+};
+
 // ---------------------------------------------------------------------------
 export var splitBlock = function(block) {
   var pos;

package/src/coffee_utils.coffee

@@ -51,6 +51,17 @@ export patchStr = (bigstr, pos, str) ->
 
 # ---------------------------------------------------------------------------
 
+export charCount = (str, ch) ->
+
+	count = 0
+	pos = str.indexOf(ch, 0)
+	while (pos >= 0)
+		count += 1
+		pos = str.indexOf(ch, pos+1)
+	return count
+
+# ---------------------------------------------------------------------------
+
 export isString = (x) ->
 
 	return (typeof x == 'string') || (x instanceof String)

package/src/coffee_utils.js

@@ -56,6 +56,18 @@ export var patchStr = function(bigstr, pos, str) {
   }
 };
 
+// ---------------------------------------------------------------------------
+export var charCount = function(str, ch) {
+  var count, pos;
+  count = 0;
+  pos = str.indexOf(ch, 0);
+  while (pos >= 0) {
+    count += 1;
+    pos = str.indexOf(ch, pos + 1);
+  }
+  return count;
+};
+
 // ---------------------------------------------------------------------------
 export var isString = function(x) {
   return (typeof x === 'string') || (x instanceof String);

package/src/indent_utils.coffee

@@ -5,7 +5,9 @@ import {
 	undef, escapeStr, defined,
 	OL, isInteger, isString, isArray, isEmpty, rtrim,
 	} from '@jdeighan/coffee-utils'
-import {arrayToBlock, blockToArray} from '@jdeighan/coffee-utils/block'
+import {
+	arrayToBlock, blockToArray, toArray, toBlock,
+	} from '@jdeighan/coffee-utils/block'
 
 # ---------------------------------------------------------------------------
 
@@ -71,14 +73,11 @@ export isUndented = (line) ->
 export indented = (input, level=1, oneIndent="\t") ->
 
 	assert (level >= 0), "indented(): negative level"
-	if level == 0
+	if (level == 0)
 		return input
 
 	toAdd = indentation(level, oneIndent)
-	if isArray(input)
-		lInputLines = input
-	else
-		lInputLines = blockToArray(input)
+	lInputLines = toArray(input)
 
 	lLines = for line in lInputLines
 		if isEmpty(line)
@@ -93,27 +92,18 @@ export indented = (input, level=1, oneIndent="\t") ->
 #              indentation is removed
 #            - returns same type as text, i.e. either string or array
 
-export undented = (text, level=undef, oneIndent="\t") ->
+export undented = (input, level=undef, oneIndent="\t") ->
 
 	if defined(level) && (level==0)
-		return text
-
-	if isString(text)
-		lLines = blockToArray(text)
-		if (lLines.length == 0)
-			return ''
-	else if isArray(text)
-		lLines = text
-		for line in lLines
-			assert isString(line), "undented(): array not all strings"
-		if (lLines.length == 0)
-			return []
-	else
-		error "undented(): Not an array or string: #{OL(text)}"
+		return input
+
+	lLines = toArray(input)
+	if (lLines.length == 0)
+		return ''
 
 	# --- determine what to remove from beginning of each line
 	if defined(level)
-		assert isInteger(level), "undented(): level must be an integer"
+		assert isInteger(level), "level must be an integer"
 		toRemove = indentation(level, oneIndent)
 	else
 		lMatches = lLines[0].match(/^\s*/)
@@ -129,8 +119,8 @@ export undented = (text, level=undef, oneIndent="\t") ->
 				throw new Error("remove #{OL(toRemove)} from #{OL(text)}")
 			lNewLines.push(line.substr(nToRemove))
 
-	if isString(text)
-		return arrayToBlock(lNewLines)
+	if isString(input)
+		return toBlock(lNewLines)
 	else
 		return lNewLines
 
@@ -167,6 +157,21 @@ export untabify = (str, numSpaces=3) ->
 # ---------------------------------------------------------------------------
 #    enclose - indent text, surround with pre and post
 
-export enclose = (text, pre, post) ->
+export enclose = (text, pre, post, oneIndent="\t") ->
+
+	return arrayToBlock([
+		pre
+		indented(text, 1, oneIndent)
+		post
+		])
+
+# ---------------------------------------------------------------------------
+#    elem - indent text, surround with HTML tags
+
+export elem = (text, tag, oneIndent="\t") ->
 
-	return pre + "\n" + indented(text) + "\n" + post
+	return arrayToBlock([
+		"<#{tag}>"
+		indented(text, 1, oneIndent)
+		"</#{tag}>"
+		])

package/src/indent_utils.js

@@ -19,7 +19,9 @@ import {
 
 import {
   arrayToBlock,
-  blockToArray
+  blockToArray,
+  toArray,
+  toBlock
 } from '@jdeighan/coffee-utils/block';
 
 // ---------------------------------------------------------------------------
@@ -87,11 +89,7 @@ export var indented = function(input, level = 1, oneIndent = "\t") {
     return input;
   }
   toAdd = indentation(level, oneIndent);
-  if (isArray(input)) {
-    lInputLines = input;
-  } else {
-    lInputLines = blockToArray(input);
-  }
+  lInputLines = toArray(input);
   lLines = (function() {
     var i, len1, results;
     results = [];
@@ -113,31 +111,18 @@ export var indented = function(input, level = 1, oneIndent = "\t") {
 //            - unless level is set, in which case exactly that
 //              indentation is removed
 //            - returns same type as text, i.e. either string or array
-export var undented = function(text, level = undef, oneIndent = "\t") {
-  var i, j, lLines, lMatches, lNewLines, len1, len2, line, nToRemove, toRemove;
+export var undented = function(input, level = undef, oneIndent = "\t") {
+  var i, lLines, lMatches, lNewLines, len1, line, nToRemove, toRemove;
   if (defined(level) && (level === 0)) {
-    return text;
+    return input;
   }
-  if (isString(text)) {
-    lLines = blockToArray(text);
-    if (lLines.length === 0) {
-      return '';
-    }
-  } else if (isArray(text)) {
-    lLines = text;
-    for (i = 0, len1 = lLines.length; i < len1; i++) {
-      line = lLines[i];
-      assert(isString(line), "undented(): array not all strings");
-    }
-    if (lLines.length === 0) {
-      return [];
-    }
-  } else {
-    error(`undented(): Not an array or string: ${OL(text)}`);
+  lLines = toArray(input);
+  if (lLines.length === 0) {
+    return '';
   }
   // --- determine what to remove from beginning of each line
   if (defined(level)) {
-    assert(isInteger(level), "undented(): level must be an integer");
+    assert(isInteger(level), "level must be an integer");
     toRemove = indentation(level, oneIndent);
   } else {
     lMatches = lLines[0].match(/^\s*/);
@@ -145,8 +130,8 @@ export var undented = function(text, level = undef, oneIndent = "\t") {
   }
   nToRemove = indentLevel(toRemove);
   lNewLines = [];
-  for (j = 0, len2 = lLines.length; j < len2; j++) {
-    line = lLines[j];
+  for (i = 0, len1 = lLines.length; i < len1; i++) {
+    line = lLines[i];
     if (isEmpty(line)) {
       lNewLines.push('');
     } else {
@@ -156,8 +141,8 @@ export var undented = function(text, level = undef, oneIndent = "\t") {
       lNewLines.push(line.substr(nToRemove));
     }
   }
-  if (isString(text)) {
-    return arrayToBlock(lNewLines);
+  if (isString(input)) {
+    return toBlock(lNewLines);
   } else {
     return lNewLines;
   }
@@ -199,6 +184,12 @@ export var untabify = function(str, numSpaces = 3) {
 
 // ---------------------------------------------------------------------------
 //    enclose - indent text, surround with pre and post
-export var enclose = function(text, pre, post) {
-  return pre + "\n" + indented(text) + "\n" + post;
+export var enclose = function(text, pre, post, oneIndent = "\t") {
+  return arrayToBlock([pre, indented(text, 1, oneIndent), post]);
+};
+
+// ---------------------------------------------------------------------------
+//    elem - indent text, surround with HTML tags
+export var elem = function(text, tag, oneIndent = "\t") {
+  return arrayToBlock([`<${tag}>`, indented(text, 1, oneIndent), `</${tag}>`]);
 };