utils.js

/*global respecEvents */
/*jshint laxcomma: true*/
// Module core/utils
// As the name implies, this contains a ragtag gang of methods that just don't fit
// anywhere else.
"use strict";
define(
    [],
    function () {
        var utils = {
            // --- SET UP
            run:    function (conf, doc, cb, msg) {
                msg.pub("start", "core/utils");
                msg.pub("end", "core/utils");
                cb();
            }
        ,
        /**
         * Allows a node to be swapped into a different document at
         * some insertion point(Element). This function is useful for
         * opportunistic insertion of DOM nodes into a document, without
         * first knowing if that is the final document where the node will
         * reside.
         *
         * @param  {Node} node The node to be swapped.
         * @return {Function} A function that takes a document and a new
         *                    insertion point (element). When called,
         *                    node gets inserted into doc at before a given
         *                    insertion point (node) - or just appended, if
         *                    the element has no children.
         */
            makeOwnerSwapper: function(node) {
                if(!(node instanceof Node)){
                    throw TypeError();
                }
                return function(doc, insertionPoint) {
                    node.remove();
                    doc.adoptNode(node);
                    if (insertionPoint.firstElementChild) {
                        insertionPoint.insertBefore(node, insertionPoint.firstElementChild);
                        return;
                    }
                    insertionPoint.appendChild(node);
                };
            }
        ,   calculateLeftPad: function(text) {
                var spaceOrTab = /^[\ |\t]*/;
                // Find smallest padding value
                var leftPad = text
                    .split("\n")
                    .filter(function (item){
                        return item;
                    })
                    .map(function(item){
                        var match = item.match(spaceOrTab)[0] || "";
                        return (match) ? match.length : 0;
                    })
                    .sort()
                    .shift(1);
                return leftPad || 0;
            }
        /**
         * Makes a ES conforming iterator allowing objects to be used with
         * methods that can interface with Iterators (Array.from(), etc.).
         *
         * @param  {Function} nextLikeFunction A function that returns a next value;
         * @return {Object} An object that implements the Iterator prop.
         */
        ,   toESIterable: function(nextLikeFunction) {
                if (!(nextLikeFunction instanceof Function)) {
                    throw TypeError("Expected a function");
                }
                var next = function() {
                  return {
                    value: nextLikeFunction(),
                    get done() {
                      return this.value === null;
                    }
                  };
                };
                // We structure the iterator like this, or else
                // RequireJS gets upset.
                var iterator = {};
                iterator[Symbol.iterator] = function() {
                  return {
                    next: next
                  };
                };
                return iterator;
        }
        ,   normalizePadding: function (text) {
                if (!text) {
                    return "";
                }

                if (typeof text !== "string") {
                    throw TypeError("Invalid input");
                }

                function isEmpty(node) {
                    return node.textContent === "";
                }

                function isWhiteSpace(node) {
                    return !/\S/gm.test(node.textContent);
                }

                function filterLastChildIsPadding(node) {
                    if (node.parentElement.lastChild === node && (isWhiteSpace(node) || isEmpty(node))) {
                        return NodeFilter.FILTER_ACCEPT;
                    }
                    return NodeFilter.FILTER_REJECT;
                }

                function isTextNode(node) {
                    return node.nodeType === Node.TEXT_NODE;
                }

                function parentIs(type) {
                    return function checkParent(node) {
                        if (!node) {
                            return false;
                        }
                        var match = node.parentNode && node.parentNode.localName === type;
                        return (!match) ? checkParent(node.parentNode) : true;
                    };
                }
                var filterParentIsPre = parentIs("pre");
                // Force into body
                var parserInput = "<body>" + text;
                var doc = new DOMParser().parseFromString(parserInput, "text/html");

                var firstPaddedLine = Array
                    .from(doc.body.childNodes)
                    .filter(isTextNode)
                    .map(function(textNode) {
                        return textNode.textContent;
                    })
                    .reduce(function(collector, textContent) {
                        if (collector) {
                            return collector;
                        }
                        var result = textContent
                            .split("\n")
                            .find(function(text) {
                                var result = /^[\s|\w]+/gm.test(text);
                                return result;
                            });
                        return result || "";
                    }, "");
                var baseCol = this.calculateLeftPad(firstPaddedLine);

                // With only the text nodes that are not children of pre elements,
                // we left align all those text nodes.
                Array
                    .from(doc.body.childNodes)
                    .filter(isTextNode)
                    .filter(function(textNode) {
                        // 🎵 Hey, processor! Leave those pre's alone! 🎵
                        return !filterParentIsPre(textNode);
                    })
                    .filter(function(textNode) {
                        // we don't care about last nodes that are just white space
                        var isLastChild = textNode.parentElement.lastChild === textNode;
                        var isJustWS = isWhiteSpace(textNode);
                        return !(isLastChild && isJustWS);
                    })
                    .map(function toTrimmedTextNode(textNode) {
                        var rawText = textNode.textContent;
                        // We remove tailing space on the right, which is just there
                        // to pad out tags like:
                        // <div>
                        //   <div>
                        //    Next line has 2 spaces hidden!
                        // __</div>
                        // </div>
                        //
                        var trimmedRight = rawText.trimRight();
                        var trimBy = this.calculateLeftPad(trimmedRight) || baseCol;
                        if (!trimBy) {
                            return null; //nothing to do
                        }
                        var exp = "^ {" + trimBy + "}";
                        var startTrim = new RegExp(exp, "gm");
                        var trimmedText = (trimBy) ? rawText.replace(startTrim, "") : rawText;
                        var newNode = textNode.ownerDocument.createTextNode(trimmedText);
                        // We can then swap the old with the new
                        return {
                            oldNode: textNode,
                            newNode: newNode,
                        };
                    }.bind(this))
                    .filter(function(nodes) {
                        return nodes;
                    })
                    .forEach(function(nodes) {
                        var oldNode = nodes.oldNode;
                        var newNode = nodes.newNode;
                        oldNode.parentElement.replaceChild(newNode, oldNode);
                    });
                var nodeIterator = doc.createNodeIterator(doc.body, NodeFilter.SHOW_TEXT, filterLastChildIsPadding);
                var iterable = this.toESIterable(nodeIterator.nextNode.bind(nodeIterator));
                // Remove trailing whitespace nodes
                Array
                    .from(iterable)
                    .forEach(function(node) {
                        node.remove();
                    });
                var result = doc.body.innerHTML;
                return result;
            }

            // --- RESPEC STUFF -------------------------------------------------------------------------------
        ,   removeReSpec:   function (doc) {
                $(".remove, script[data-requiremodule]", doc).remove();
            }

            // --- STRING HELPERS -----------------------------------------------------------------------------
            // Takes an array and returns a string that separates each of its items with the proper commas and
            // "and". The second argument is a mapping function that can convert the items before they are
            // joined
        ,   joinAnd:    function (arr, mapper) {
                if (!arr || !arr.length) return "";
                mapper = mapper || function (ret) { return ret; };
                var ret = "";
                if (arr.length === 1) return mapper(arr[0], 0);
                for (var i = 0, n = arr.length; i < n; i++) {
                    if (i > 0) {
                        if (n === 2) ret += ' ';
                        else         ret += ', ';
                        if (i == n - 1) ret += 'and ';
                    }
                    ret += mapper(arr[i], i);
                }
                return ret;
            }
            // Takes a string, applies some XML escapes, and returns the escaped string.
            // Note that overall using either Handlebars' escaped output or jQuery is much
            // preferred to operating on strings directly.
        ,   xmlEscape:    function (s) {
                return s.replace(/&/g, "&amp;")
                        .replace(/>/g, "&gt;")
                        .replace(/"/g, "&quot;")
                        .replace(/</g, "&lt;");
            }

            // Trims string at both ends and replaces all other white space with a single space
        ,   norm:   function (str) {
                return str.replace(/^\s+/, "").replace(/\s+$/, "").split(/\s+/).join(" ");
            }


            // --- DATE HELPERS -------------------------------------------------------------------------------
            // Takes a Date object and an optional separator and returns the year,month,day representation with
            // the custom separator (defaulting to none) and proper 0-padding
        ,   concatDate: function (date, sep) {
                if (!sep) sep = "";
                return "" + date.getFullYear() + sep + this.lead0(date.getMonth() + 1) + sep + this.lead0(date.getDate());
            }

            // takes a string, prepends a "0" if it is of length 1, does nothing otherwise
        ,   lead0:  function (str) {
                str = "" + str;
                return (str.length == 1) ? "0" + str : str;
            }

            // takes a YYYY-MM-DD date and returns a Date object for it
        ,   parseSimpleDate:    function (str) {
                return new Date(str.substr(0, 4), (str.substr(5, 2) - 1), str.substr(8, 2));
            }

            // takes what document.lastModified returns and produces a Date object for it
        ,   parseLastModified:    function (str) {
                if (!str) return new Date();
                return new Date(Date.parse(str));
                // return new Date(str.substr(6, 4), (str.substr(0, 2) - 1), str.substr(3, 2));
            }

            // list of human names for months (in English)
        ,   humanMonths: ["January", "February", "March", "April", "May", "June", "July",
                          "August", "September", "October", "November", "December"]

            // given either a Date object or a date in YYYY-MM-DD format, return a human-formatted
            // date suitable for use in a W3C specification
        ,   humanDate:  function (date) {
                if (!(date instanceof Date)) date = this.parseSimpleDate(date);
                return this.lead0(date.getDate()) + " " + this.humanMonths[date.getMonth()] + " " + date.getFullYear();
            }
            // given either a Date object or a date in YYYY-MM-DD format, return an ISO formatted
            // date suitable for use in a xsd:datetime item
        ,   isoDate:    function (date) {
                if (!(date instanceof Date)) date = this.parseSimpleDate(date);
                // return "" + date.getUTCFullYear() +'-'+ this.lead0(date.getUTCMonth() + 1)+'-' + this.lead0(date.getUTCDate()) +'T'+this.lead0(date.getUTCHours())+':'+this.lead0(date.getUTCMinutes()) +":"+this.lead0(date.getUTCSeconds())+'+0000';
                return date.toISOString() ;
            }

            // Given an object, it converts it to a key value pair separated by
            // ("=", configurable) and a delimiter (" ," configurable).
            // for example, {"foo": "bar", "baz": 1} becomes "foo=bar, baz=1"
        ,   toKeyValuePairs: function(obj, delimiter, separator) {
                if(!separator){
                    separator = "=";
                }
                if(!delimiter){
                    delimiter = ", ";
                }
                return Object.getOwnPropertyNames(obj)
                    .map(function(key){
                        return key + separator + JSON.stringify(obj[key]);
                    })
                    .join(delimiter);
            }

            // --- STYLE HELPERS ------------------------------------------------------------------------------
            // take a document and either a link or an array of links to CSS and appends a <link/> element
            // to the head pointing to each
        ,   linkCSS:  function (doc, styles) {
                if (!$.isArray(styles)) styles = [styles];
                $.each(styles, function (i, css) {
                    $('head', doc).append($("<link/>").attr({ rel: 'stylesheet', href: css }));
                });
            }

            // --- TRANSFORMATIONS ------------------------------------------------------------------------------
            // Run list of transforms over content and return result.
            // Please note that this is a legacy method that is only kept in order to maintain compatibility
            // with RSv1. It is therefore not tested and not actively supported.
        ,   runTransforms: function (content, flist) {
                var args = [this, content]
                ,   funcArgs = Array.prototype.slice.call(arguments)
                ;
                funcArgs.shift(); funcArgs.shift();
                args = args.concat(funcArgs);
                if (flist) {
                    var methods = flist.split(/\s+/);
                    for (var j = 0; j < methods.length; j++) {
                        var meth = methods[j];
                        if (window[meth]) {
                            // the initial call passed |this| directly, so we keep it that way
                            try {
                                content = window[meth].apply(this, args);
                            }
                            catch (e) {
                                respecEvents.pub("warn", "call to " + meth + "() failed with " + e) ;
                            }
                        }
                    }
                }
                return content;
            }
        };
        return utils;
    }
);