automat - npm Package Compare versions

Comparing version 0.1.0 to 0.1.1

index.js

@@ -13,14 +13,6 @@ /* eslint-env browser */
 /**
- * @summary String/markup formatter.
+ * @summary String formatter.
  *
- * @desc Automatic string or template formatting:
- * * If input is a template, format and return as an `HTMLElement`.
- * * If input is a string:
- *   * Format and return as string; or
- *   * Format and return as an `HTMLElement`.
+ * @desc String substitution is performed on numbered _replacer_ patterns like `${n}` or _encoder_ patterns like `%{n}` where n is the zero-based `arguments` index. So `${0}` would be replaced with the first argument following `text`.
  *
- * A "template" is a JavaScript function whose body consists entirely of a single multi-line JavaScript comment containing (presumably) HTML -- which is extracted, ignoring any White space surrounding the comment delimiters.
- *
- * String substitution is performed on numbered _replacer_ patterns like `${n}` or _encoder_ patterns like `%{n}` where n is the zero-based `arguments` index. So `${0}` would be replaced with the first argument following `text` (or `element` if given).
- *
  * Encoders are just like replacers except the argument is HTML-encoded before being used.
@@ -30,8 +22,5 @@ *
  *
- * @param {string|function} text - One of:
- * * A simple text string to be formatted and returned as described below.
+ * @param {string} text - A simple text string to be formatted and returned as described above.
  * * A "template" (function) as described above. The text is extracted and returned in `HTMLElement` provided in `node` or in a new `<div>...</div>` element if `node` was omitted.
  *
- * @param {HTMLElement} [node]
- *
  * @param {...*} [replacements] - Replacement values for numbered format patterns.
@@ -43,51 +32,103 @@ *
  */
-function automat(text, node) {
-    var asMarkup = node instanceof HTMLElement,
-        repaclementsOffset = asMarkup ? 2 : 1,
-        repaclementsLength = arguments.length - repaclementsOffset,
-        isTemplate = typeof text === 'function';
+function automat(format, replacements/*...*/) {
+    var args = arguments;
 
-    if (isTemplate) {
-        text = text.toString().match(extract)[1];
-        asMarkup = true;
+    if (typeof format === 'function') {
+        format = format.toString().match(extract)[1];
     }
 
-    if (isTemplate || !asMarkup) {
-        node = document.createElement('DIV');
+    if (args.length > 1) {
+        format = format.replace(automat.replacersRegex, function(match, key) {
+            key -= -1; // convert to number and increment
+            return args.length > key ? args[key] : '';
+        });
+
+        format = format.replace(automat.encodersRegex, function(match, key) {
+            key -= -1; // convert to number and increment
+            if (args.length > key) {
+                var htmlEncoderNode = htmlEncoderNode || document.createElement('DIV');
+                htmlEncoderNode.textContent = args[key];
+                return htmlEncoderNode.innerHTML;
+            } else {
+                return '';
+            }
+        });
     }
 
-    if (repaclementsLength) {
-        var repaclements = Array.prototype.slice.call(arguments, repaclementsOffset);
+    return format;
+}
 
-        text = text.replace(REPLACERS, function(match, key) {
-            return repaclements[key];
-        });
+/**
+ * @summary Replace contents of `el` with `Nodes` generated from formatted template.
+ *
+ * A "template" is a JavaScript function whose body consists entirely of a single multi-line JavaScript comment containing (presumably) HTML -- which is extracted, ignoring any White space surrounding the comment delimiters.
+ *
+ * String substitution is performed on numbered _replacer_ patterns like `${n}` or _encoder_ patterns like `%{n}` where n is the zero-based `arguments` index. So `${0}` would be replaced with the first argument following `text` (or `element` if given).
+ *
+ * Encoders are just like replacers except the argument is HTML-encoded before being used.
+ *
+ * To change the format patterns, assign new `RegExp` patterns to `automat.encoders` and `automat.replacers`.
+ *
+ * @param {HTMLElement} [el] - Node in which to return markup generated from template. If omitted, a new `<div>...</div>` element will be created and returned.
+ *
+ * @param {string|function} template - If a function, extract template from comment within.
+ *
+ * @param {...*} [replacements] - Replacement values for numbered format patterns.
+ *
+ * @return {HTMLElement} The `HTMLElement` provided or a new `<div>...</div>` element, its `innerHTML` set to the formatted text.
+ */
+function replace(el, template, replacements/*...*/) {
+    var asMarkup = el instanceof HTMLElement,
+        args = asMarkup ? Array.prototype.slice.call(arguments, 1) : arguments;
 
-        text = text.replace(ENCODERS, function(match, key) {
-            node.textContent = repaclements[key];
-            return node.innerHTML;
-        });
+    if (!asMarkup) {
+        el = document.createElement('DIV');
     }
 
-    if (isTemplate || asMarkup) {
-        node.innerHTML = text;
-        return node;
-    } else {
-        return text;
-    }
+    el.innerHTML = automat.apply(null, args);
+    return el;
 }
 
 /**
- * Use this wrapper to return the first child described in `html`.
- * @param {string|function} html
+ * @summary Append or insert `Node`s generated from formatted template into given `el`.
+ * @param {Node} [referenceNode=null] Inserts before this element within `el` or at end of `el` if `null`.
+ * @param {HTMLElement} el
+ * @param {string|function} template - If a function, extract template from comment within.
+ * @param {...*} [replacements] - Replacement values for numbered format patterns.
  * @returns {HTMLElement}
  */
-automat.first = function(html) {
-    return automat(html, document.createElement('div')).firstChild;
-};
+function append(referenceNode, el, template, replacements/*...*/) {
+    var referenceNodeOmitted = !(el instanceof HTMLElement),
+        args = Array.prototype.slice.call(arguments, referenceNodeOmitted ? 1 : 2),
+        childNodes = replace.apply(null, args).childNodes;
 
-automat.encoders = ENCODERS;
-automat.replacers = REPLACERS;
+    if (referenceNodeOmitted) {
+        el = referenceNode;
+        referenceNode = null;
+    }
 
+    for (var i = 0; i < childNodes.length; ++i) {
+        el.insertBefore(childNodes[i], referenceNode);
+    }
 
+    return el;
+}
+
+/**
+ * Use this convenience wrapper to return the first child described in `html`.
+ * @param {string|function} template - If a function, extract template from comment within.
+ * @returns {HTMLElement} A new `<div>...</div>` element, its `innerHTML` set to the formatted text.
+ */
+function firstChild(html, replacements/*...*/) {
+    return replace.apply(null, arguments).firstChild;
+}
+
+automat.encodersRegex = ENCODERS;
+automat.replacersRegex = REPLACERS;
+
+automat.format = automat; // if you find using just automat() confusing
+automat.replace = replace;
+automat.append = append;
+automat.firstChild = firstChild;
+
 module.exports = automat;

package.json

 {
   "name": "automat",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "String and markup formatter.",
@@ -5,0 +5,0 @@ "repository": {

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

8147

increased by36.99%

Lines of code

110

increased by48.65%

No dependency changes