automat - npm Package Compare versions

Comparing version 0.1.1 to 1.0.0

index.js

@@ -5,3 +5,3 @@ /* eslint-env browser */
 
-var extract = /\/\*\s+([^]+?)\s+\*\//; // finds the string inside the /* ... */; the group excludes the whitespace
+var FUNCTION_CONSISTING_ENTIRELY_SINGLE_MULTILINE_COMMENT = /^function\s*\w*\(\)\s*\{\s*\/\*\s*([^]+?)\s*\*\/\s*\s*}$/;
 
@@ -22,20 +22,25 @@ var ENCODERS = /%\{(\d+)\}/g; // double $$ to encode
  *
- * @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 {string|function} template - A template to be formatted as described above. Overloads:
+ * * A string primitive containing the template.
+ * * A "template" function, which is a function consisting entirely of a single multi-line comment containing the template. The template is extracted from the comment.
+ * * A (non-template) function to be called with `this` as the calling context. The template is the value returned from this call.
  *
  * @param {...*} [replacements] - Replacement values for numbered format patterns.
  *
- * @return {string|HTMLElement} Depends on `node`:
- * * If omitted, formatted text is returned as a string.
- * * If an `HTMLElement`, its `innerHTML` is set to the formatted text and this element is returned instead of the text string.
+ * @return {string} The formatted text.
  */
-function automat(format, replacements/*...*/) {
-    var args = arguments;
+function automat(template, replacements/*...*/) {
+    var hasReplacements = arguments.length > 1;
 
-    if (typeof format === 'function') {
-        format = format.toString().match(extract)[1];
+    // if `template` is a function, convert it to text
+    if (typeof template === 'function') {
+        var format = template.toString().match(FUNCTION_CONSISTING_ENTIRELY_SINGLE_MULTILINE_COMMENT);
+        template = format
+            ? format[1] // template function: extract text from comment
+            : template.call(this); // non-template function: call it with context and use return value
     }
 
-    if (args.length > 1) {
-        format = format.replace(automat.replacersRegex, function(match, key) {
+    if (hasReplacements) {
+        var args = arguments;
+        template = template.replace(automat.replacersRegex, function(match, key) {
             key -= -1; // convert to number and increment
@@ -45,6 +50,6 @@ return args.length > key ? args[key] : '';
 
-        format = format.replace(automat.encodersRegex, function(match, key) {
+        template = template.replace(automat.encodersRegex, function(match, key) {
             key -= -1; // convert to number and increment
             if (args.length > key) {
-                var htmlEncoderNode = htmlEncoderNode || document.createElement('DIV');
+                var htmlEncoderNode = document.createElement('DIV');
                 htmlEncoderNode.textContent = args[key];
@@ -58,3 +63,3 @@ return htmlEncoderNode.innerHTML;
 
-    return format;
+    return template;
 }
@@ -65,27 +70,25 @@
  *
- * 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.
+ * @param {string|function} template - See `template` parameter of {@link automat}.
  *
- * 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.
+ * @return {HTMLElement} The `el` provided or a new `<div>...</div>` element, its `innerHTML` set to the formatted text.
+ *
+ * @memberOf automat
  */
-function replace(el, template, replacements/*...*/) {
-    var asMarkup = el instanceof HTMLElement,
-        args = asMarkup ? Array.prototype.slice.call(arguments, 1) : arguments;
+function replace(template, el, replacements/*...*/) {
+    var elOmitted = typeof el !== 'object',
+        args = Array.prototype.slice.call(arguments, 1);
 
-    if (!asMarkup) {
+    if (elOmitted) {
         el = document.createElement('DIV');
+        args.unshift(template);
+    } else {
+        args[0] = template;
     }
 
     el.innerHTML = automat.apply(null, args);
+
     return el;
@@ -96,18 +99,28 @@ }
  * @summary Append or insert `Node`s generated from formatted template into given `el`.
+ *
+ * @param {string|function} template - See `template` parameter of {@link automat}.
+ *
+ * @param {HTMLElement} 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}
+ *
+ * @memberOf automat
  */
-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;
+function append(template, el, referenceNode, replacements/*...*/) {
+    var replacementsStartAt = 3,
+        referenceNodeOmitted = typeof referenceNode !== 'object',  // replacements are never objects
+        childNodes;
 
     if (referenceNodeOmitted) {
-        el = referenceNode;
         referenceNode = null;
+        replacementsStartAt = 2;
     }
 
+    replacements = Array.prototype.slice.call(arguments, replacementsStartAt);
+    childNodes = replace.apply(null, [template].concat(replacements)).childNodes;
+
     for (var i = 0; i < childNodes.length; ++i) {
@@ -122,13 +135,32 @@ el.insertBefore(childNodes[i], referenceNode);
  * 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.
+ *
+ * @memberOf automat
  */
-function firstChild(html, replacements/*...*/) {
+function firstChild(template, replacements/*...*/) {
     return replace.apply(null, arguments).firstChild;
 }
 
+/**
+ * @summary Finds string substitution lexemes that require HTML encoding.
+ * @desc Modify to suit.
+ * @default %{n}
+ * @type {RegExp}
+ * @memberOf automat
+ */
 automat.encodersRegex = ENCODERS;
+
+/**
+ * @summary Finds string substitution lexemes.
+ * @desc Modify to suit.
+ * @default ${n}
+ * @type {RegExp}
+ * @memberOf automat
+ */
 automat.replacersRegex = REPLACERS;
 
-automat.format = automat; // if you find using just automat() confusing
+automat.format = automat; // if you find using just `automat()` confusing
 automat.replace = replace;
@@ -135,0 +167,0 @@ automat.append = append;

package.json

 {
   "name": "automat",
-  "version": "0.1.1",
+  "version": "1.0.0",
   "description": "String and markup formatter.",
@@ -26,4 +26,5 @@ "repository": {
     "jsdoc": "^3.4.0",
-    "run-sequence": "^1.1.5"
+    "run-sequence": "^1.1.5",
+    "should": "^8.3.0"
   }
 }

README.md

 # automat
 String and markup formatter.
 
+> Caveat: This 1.0 has breaking changes from 0.x, in particular the order of parameters for `automat.replace` and `automat.append`
+
 ## Features
 
-* Text substitution
-* Optional HTML encoding of substitutions
-* Optional Extraction of a template from a function comment
-* Optional creation of `HTMLElement`
-* Settable substitution regex patterns
+* String formatting
+  * Text substitution via numbered text substitution patterns
+  * Substitution patterns overrideable
+  * Optional Extraction of a template from a function comment
+  * Optional HTML encoding of substituted text
+* DOM node convenience methods convert your formatted markup to DOM nodes and:
+  * Return them in a new `<div>...</div>` element
+  * Return them in an existing `HTMLElement` you provide
+  * Append/insert them into an existing `HTMLElement` you provide
 
-## Synopsis
+## Examples
 
-[ to be written ]
+See tests.
 
@@ -16,0 +22,0 @@ ### API documentation

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

No v1

Quality

Package is not semver >=1. This means it is not stable and does not support ^ ranges.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

8759

increased by7.51%

Lines of code

139

increased by26.36%

Number of low quality alerts

1

decreased by-50%

Number of lines in readme file

41

increased by17.14%

Worsened metrics

Dev dependency count

13

increased by8.33%

No dependency changes