occam-dom 5.2.28 → 5.2.31

package/README.md

@@ -13,9 +13,9 @@
 
 ## Introduction
 
-Specifically, "outer" token arrays and node trees resulting from the user of Occam's [lexers](https://github.com/djalbat/occam-lexers) and [parsers](https://github.com/djalbat/occam-parsers), respectively, can be refined into "inner" token arrays and node trees for convenience. 
+Specifically, "outer" token arrays and parse trees resulting from the user of Occam's [lexers](https://github.com/djalbat/occam-lexers) and [parsers](https://github.com/djalbat/occam-parsers), respectively, can be refined into "inner" token arrays and parse trees for convenience. 
 
-An example is helpful. Consider the following outer node tree that results from parsing some simple Markdown.
+An example is helpful. Consider the following outer parse tree that results from parsing some simple Markdown.
 
 ```
                                                   |                                                   
@@ -38,7 +38,7 @@ An example is helpful. Consider the following outer node tree that results from
                 "Heading"[word] [0]                             "Paragraph"[word] [2] "."[special] [2]
 ```
 
-This contains far more information than is needed to render the markdown as HTML. The following inner node tree will in fact suffice:
+This contains far more information than is needed to render the markdown as HTML. The following inner parse tree will in fact suffice:
 
 ```
                                                 |                 
@@ -55,7 +55,7 @@ This contains far more information than is needed to render the markdown as HTML
                                                plainText plainText
 ```
 
-Locating the outer nodes that contribute to this inner node tree is straightforward enough using Occam's [queries](https://github.com/djalbat/occam-query). However, the arrays of nodes that result are not in the above form. This package provides the means to form such node trees.
+Locating the outer nodes that contribute to this inner parse tree is straightforward enough using Occam's [queries](https://github.com/djalbat/occam-query). However, the arrays of nodes that result are not in the above form. This package provides the means to form such parse trees.
 
 ## Installation
 
@@ -93,7 +93,7 @@ One last thing to bear in mind is that this package is included by way of a rela
 
 ## Usage
 
-Suppose that a Markdown document is being parsed by way of [Highmark](https://github.com/djalbat/highmark-markdown)'s lexer and parser:
+Suppose that a Markdown document is being processed by way of [Highmark](https://github.com/djalbat/highmark-markdown)'s lexer and parser:
 
 ```
 const markdownLexer = MarkdownLexer.fromNothing(),
@@ -108,7 +108,7 @@ const content = markdown, ///
 ...
 ```
 
-A number of arrays of nodes can be created from the document's "outer" node by applying queries:
+A number of arrays of nodes can be created from the "outer" document node using queries:
 
 ```
 export function nodesFromNodeAndQueries(node, queries, nodes = []) {
@@ -122,7 +122,46 @@ export function nodesFromNodeAndQueries(node, queries, nodes = []) {
 }
 ```
 
-These can then be formed into an ""
+These can then be formed into an "inner" node tree using the `topmostNodeFromOuterNodes()` function:
+
+```
+import { nodeUtilities } from "occam-dom";
+
+const { topmostNodeFromOuterNodes } = nodeUtilities;
+
+...
+
+const outerNodes = nodes,   ///
+      topmostNode = topmostNodeFromOuterNodes(outerNode);
+      
+...
+```
+
+You can also pass an optional callback argument to this function that maps outer nodes to inner node Classes:
+
+```
+import htmlNodeMap from "../map/node/html";
+import TopmostHTMLNOde from "../node/html/topmost";
+
+function ClassFromOuterNode(outerNode) {
+  let Class;
+
+  if (outerNode === null) {
+    Class = TopmostHTMLNode;  ///
+  } else {
+    const nonTerminalNode = outerNode,  ///
+          ruleName = nonTerminalNode.getRuleName();
+
+    Class = htmlNodeMap[ruleName] || HTMLNode;
+  }
+
+  return Class;
+}
+
+const topmostNode = topmostNodeFromOuterNodes(ClassFromOuterNode, outerNode);
+```
+
+Note that the topmost inner node has no corresponding outer node and that a default of `HTMLNode` has been provided. There is no need to provide a unique class for every type of outer node that the algorithm may come across. 
 
 ## Building
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "occam-dom",
   "author": "James Smith",
-  "version": "5.2.28",
+  "version": "5.2.31",
   "license": "MIT, Anti-996",
   "homepage": "https://github.com/djalbat/occam-dom",
   "description": "Occam's DOM related functionality.",