casperjs 1.0.0.RC1 → 1.0.0

data/modules/utils.js

@@ -30,400 +30,552 @@
 
 /*global CasperError console exports phantom require*/
 
-(function(exports) {
-    "use strict";
-
-    /**
-     * Provides a better typeof operator equivalent, able to retrieve the array
-     * type.
-     *
-     * @param  mixed  input
-     * @return String
-     * @see    http://javascriptweblog.wordpress.com/2011/08/08/fixing-the-javascript-typeof-operator/
-     */
-    function betterTypeOf(input) {
+/**
+ * Provides a better typeof operator equivalent, able to retrieve the array
+ * type.
+ *
+ * CAVEAT: this function does not necessarilly map to classical js "type" names,
+ * notably a `null` will map to "null" instead of "object".
+ *
+ * @param  mixed  input
+ * @return String
+ * @see    http://javascriptweblog.wordpress.com/2011/08/08/fixing-the-javascript-typeof-operator/
+ */
+function betterTypeOf(input) {
+    "use strict";
+    switch (input) {
+        case undefined:
+            return 'undefined';
+        case null:
+            return 'null';
+        default:
         try {
             return Object.prototype.toString.call(input).match(/^\[object\s(.*)\]$/)[1].toLowerCase();
         } catch (e) {
             return typeof input;
         }
     }
-    exports.betterTypeOf = betterTypeOf;
-
-    /**
-     * Dumps a JSON representation of passed value to the console. Used for
-     * debugging purpose only.
-     *
-     * @param  Mixed  value
-     */
-    function dump(value) {
-        console.log(serialize(value, 4));
-    }
-    exports.dump = dump;
-
-    /**
-     * Returns the file extension in lower case.
-     *
-     * @param  String  file  File path
-     * @return string
-     */
-    function fileExt(file) {
-        try {
-            return file.split('.').pop().toLowerCase().trim();
-        } catch(e) {
-            return '';
-        }
+}
+exports.betterTypeOf = betterTypeOf;
+
+/**
+ * Cleans a passed URL if it lacks a slash at the end when a sole domain is used.
+ *
+ * @param  String  url An HTTP URL
+ * @return String
+ */
+function cleanUrl(url) {
+    "use strict";
+    var parts = /(https?):\/\/(.*)/i.exec(url);
+    if (!parts) {
+        return url;
     }
-    exports.fileExt = fileExt;
-
-    /**
-     * Takes a string and append blanks until the pad value is reached.
-     *
-     * @param  String  text
-     * @param  Number  pad   Pad value (optional; default: 80)
-     * @return String
-     */
-    function fillBlanks(text, pad) {
-        pad = pad || 80;
-        if (text.length < pad) {
-            text += new Array(pad - text.length + 1).join(' ');
-        }
-        return text;
+    var protocol = parts[1];
+    var subparts = parts[2].split('/');
+    if (subparts.length === 1) {
+        return format("%s://%s/", protocol, subparts[0]);
     }
-    exports.fillBlanks = fillBlanks;
-
-    /**
-     * Formats a string with passed parameters. Ported from nodejs `util.format()`.
-     *
-     * @return String
-     */
-    function format(f) {
-        var i = 1;
-        var args = arguments;
-        var len = args.length;
-        var str = String(f).replace(/%[sdj%]/g, function _replace(x) {
-            if (i >= len) return x;
-            switch (x) {
-            case '%s':
-                return String(args[i++]);
-            case '%d':
-                return Number(args[i++]);
-            case '%j':
-                return JSON.stringify(args[i++]);
-            case '%%':
-                return '%';
-            default:
-                return x;
-            }
-        });
-        for (var x = args[i]; i < len; x = args[++i]) {
-            if (x === null || typeof x !== 'object') {
-                str += ' ' + x;
-            } else {
-                str += '[obj]';
-            }
-        }
-        return str;
+    return url;
+}
+exports.cleanUrl = cleanUrl;
+
+/**
+ * Clones an object.
+ *
+ * @param  Mixed  o
+ * @return Mixed
+ */
+function clone(o) {
+    "use strict";
+    return JSON.parse(JSON.stringify(o));
+}
+exports.clone = clone;
+
+/**
+ * Dumps a JSON representation of passed value to the console. Used for
+ * debugging purpose only.
+ *
+ * @param  Mixed  value
+ */
+function dump(value) {
+    "use strict";
+    console.log(serialize(value, 4));
+}
+exports.dump = dump;
+
+/**
+ * Tests equality between the two passed arguments.
+ *
+ * @param  Mixed  v1
+ * @param  Mixed  v2
+ * @param  Boolean
+ */
+function equals(v1, v2) {
+    "use strict";
+    if (isFunction(v1)) {
+        return v1.toString() === v2.toString();
     }
-    exports.format = format;
-
-    /**
-     * Retrieves the value of an Object foreign property using a dot-separated
-     * path string.
-     *
-     * Beware, this function doesn't handle object key names containing a dot.
-     *
-     * @param  Object  obj   The source object
-     * @param  String  path  Dot separated path, eg. "x.y.z"
-     */
-    function getPropertyPath(obj, path) {
-        if (!isObject(obj) || !isString(path)) {
-            return undefined;
+    if (v1 instanceof Object) {
+        if (Object.keys(v1).length !== Object.keys(v2).length) {
+            return false;
         }
-        var value = obj;
-        path.split('.').forEach(function(property) {
-            if (typeof value === "object" && property in value) {
-                value = value[property];
-            } else {
-                value = undefined;
-                return;
-            }
-        });
-        return value;
-    }
-    exports.getPropertyPath = getPropertyPath;
-
-    /**
-     * Inherit the prototype methods from one constructor into another.
-     *
-     * @param {function} ctor Constructor function which needs to inherit the
-     *     prototype.
-     * @param {function} superCtor Constructor function to inherit prototype from.
-     */
-    function inherits(ctor, superCtor) {
-        ctor.super_ = ctor.__super__ = superCtor;
-        ctor.prototype = Object.create(superCtor.prototype, {
-            constructor: {
-                value: ctor,
-                enumerable: false,
-                writable: true,
-                configurable: true
+        for (var k in v1) {
+            if (!equals(v1[k], v2[k])) {
+                return false;
             }
-        });
-    }
-    exports.inherits = inherits;
-
-    /**
-     * Checks if value is a javascript Array
-     *
-     * @param  mixed  value
-     * @return Boolean
-     */
-    function isArray(value) {
-        return Array.isArray(value) || isType(value, "array");
-    }
-    exports.isArray = isArray;
-
-    /**
-     * Checks if passed argument is an instance of Capser object.
-     *
-     * @param  mixed  value
-     * @return Boolean
-     */
-    function isCasperObject(value) {
-        return value instanceof require('casper').Casper;
-    }
-    exports.isCasperObject = isCasperObject;
-
-    /**
-     * Checks if value is a phantomjs clipRect-compatible object
-     *
-     * @param  mixed  value
-     * @return Boolean
-     */
-    function isClipRect(value) {
-        return isType(value, "cliprect") || (
-            isObject(value) &&
-            isNumber(value.top) && isNumber(value.left) &&
-            isNumber(value.width) && isNumber(value.height)
-        );
-    }
-    exports.isClipRect = isClipRect;
-
-    /**
-     * Checks if value is a javascript Function
-     *
-     * @param  mixed  value
-     * @return Boolean
-     */
-    function isFunction(value) {
-        return isType(value, "function");
-    }
-    exports.isFunction = isFunction;
-
-    /**
-     * Checks if a file is apparently javascript compatible (.js or .coffee).
-     *
-     * @param  String  file  Path to the file to test
-     * @return Boolean
-     */
-    function isJsFile(file) {
-        var ext = fileExt(file);
-        return isString(ext, "string") && ['js', 'coffee'].indexOf(ext) !== -1;
+        }
+        return true;
     }
-    exports.isJsFile = isJsFile;
-
-    /**
-     * Checks if the provided value is null
-     *
-     * @return Boolean
-     */
-    function isNull(value) {
-        return isType(value, "null");
+    return v1 === v2;
+}
+exports.equals = equals;
+
+/**
+ * Returns the file extension in lower case.
+ *
+ * @param  String  file  File path
+ * @return string
+ */
+function fileExt(file) {
+    "use strict";
+    try {
+        return file.split('.').pop().toLowerCase().trim();
+    } catch(e) {
+        return '';
     }
-    exports.isNull = isNull;
-
-    /**
-     * Checks if value is a javascript Number
-     *
-     * @param  mixed  value
-     * @return Boolean
-     */
-    function isNumber(value) {
-        return isType(value, "number");
+}
+exports.fileExt = fileExt;
+
+/**
+ * Takes a string and append blanks until the pad value is reached.
+ *
+ * @param  String  text
+ * @param  Number  pad   Pad value (optional; default: 80)
+ * @return String
+ */
+function fillBlanks(text, pad) {
+    "use strict";
+    pad = pad || 80;
+    if (text.length < pad) {
+        text += new Array(pad - text.length + 1).join(' ');
     }
-    exports.isNumber = isNumber;
-
-    /**
-     * Checks if value is a javascript Object
-     *
-     * @param  mixed  value
-     * @return Boolean
-     */
-    function isObject(value) {
-        var objectTypes = ["array", "object", "qtruntimeobject"];
-        return objectTypes.indexOf(betterTypeOf(value)) >= 0;
+    return text;
+}
+exports.fillBlanks = fillBlanks;
+
+/**
+ * Formats a string with passed parameters. Ported from nodejs `util.format()`.
+ *
+ * @return String
+ */
+function format(f) {
+    "use strict";
+    var i = 1;
+    var args = arguments;
+    var len = args.length;
+    var str = String(f).replace(/%[sdj%]/g, function _replace(x) {
+        if (i >= len) return x;
+        switch (x) {
+        case '%s':
+            return String(args[i++]);
+        case '%d':
+            return Number(args[i++]);
+        case '%j':
+            return JSON.stringify(args[i++]);
+        case '%%':
+            return '%';
+        default:
+            return x;
+        }
+    });
+    for (var x = args[i]; i < len; x = args[++i]) {
+        if (x === null || typeof x !== 'object') {
+            str += ' ' + x;
+        } else {
+            str += '[obj]';
+        }
     }
-    exports.isObject = isObject;
-
-    /**
-     * Checks if value is a javascript String
-     *
-     * @param  mixed  value
-     * @return Boolean
-     */
-    function isString(value) {
-        return isType(value, "string");
+    return str;
+}
+exports.format = format;
+
+/**
+ * Retrieves the value of an Object foreign property using a dot-separated
+ * path string.
+ *
+ * Beware, this function doesn't handle object key names containing a dot.
+ *
+ * @param  Object  obj   The source object
+ * @param  String  path  Dot separated path, eg. "x.y.z"
+ */
+function getPropertyPath(obj, path) {
+    "use strict";
+    if (!isObject(obj) || !isString(path)) {
+        return undefined;
     }
-    exports.isString = isString;
-
-    /**
-     * Shorthands for checking if a value is of the given type. Can check for
-     * arrays.
-     *
-     * @param  mixed   what      The value to check
-     * @param  String  typeName  The type name ("string", "number", "function", etc.)
-     * @return Boolean
-     */
-    function isType(what, typeName) {
-        if (typeof typeName !== "string" || !typeName) {
-            throw new CasperError("You must pass isType() a typeName string");
+    var value = obj;
+    path.split('.').forEach(function(property) {
+        if (typeof value === "object" && property in value) {
+            value = value[property];
+        } else {
+            value = undefined;
         }
-        return betterTypeOf(what).toLowerCase() === typeName.toLowerCase();
-    }
-    exports.isType = isType;
-
-    /**
-     * Checks if the provided value is undefined
-     *
-     * @return Boolean
-     */
-    function isUndefined(value) {
-        return isType(value, "undefined");
+    });
+    return value;
+}
+exports.getPropertyPath = getPropertyPath;
+
+/**
+ * Inherit the prototype methods from one constructor into another.
+ *
+ * @param {function} ctor Constructor function which needs to inherit the
+ *     prototype.
+ * @param {function} superCtor Constructor function to inherit prototype from.
+ */
+function inherits(ctor, superCtor) {
+    "use strict";
+    ctor.super_ = ctor.__super__ = superCtor;
+    ctor.prototype = Object.create(superCtor.prototype, {
+        constructor: {
+            value: ctor,
+            enumerable: false,
+            writable: true,
+            configurable: true
+        }
+    });
+}
+exports.inherits = inherits;
+
+/**
+ * Checks if value is a javascript Array
+ *
+ * @param  mixed  value
+ * @return Boolean
+ */
+function isArray(value) {
+    "use strict";
+    return Array.isArray(value) || isType(value, "array");
+}
+exports.isArray = isArray;
+
+/**
+ * Checks if passed argument is an instance of Capser object.
+ *
+ * @param  mixed  value
+ * @return Boolean
+ */
+function isCasperObject(value) {
+    "use strict";
+    return value instanceof require('casper').Casper;
+}
+exports.isCasperObject = isCasperObject;
+
+/**
+ * Checks if value is a phantomjs clipRect-compatible object
+ *
+ * @param  mixed  value
+ * @return Boolean
+ */
+function isClipRect(value) {
+    "use strict";
+    return isType(value, "cliprect") || (
+        isObject(value) &&
+        isNumber(value.top) && isNumber(value.left) &&
+        isNumber(value.width) && isNumber(value.height)
+    );
+}
+exports.isClipRect = isClipRect;
+
+/**
+ * Checks that the subject is falsy.
+ *
+ * @param  Mixed  subject  Test subject
+ * @return Boolean
+ */
+function isFalsy(subject) {
+    "use strict";
+    /*jshint eqeqeq:false*/
+    return !subject;
+}
+exports.isFalsy = isFalsy;
+/**
+ * Checks if value is a javascript Function
+ *
+ * @param  mixed  value
+ * @return Boolean
+ */
+function isFunction(value) {
+    "use strict";
+    return isType(value, "function");
+}
+exports.isFunction = isFunction;
+
+/**
+ * Checks if passed resource involves an HTTP url.
+ *
+ * @param  Object  resource The PhantomJS HTTP resource object
+ * @return Boolean
+ */
+function isHTTPResource(resource) {
+    "use strict";
+    return isObject(resource) && /^http/i.test(resource.url);
+}
+exports.isHTTPResource = isHTTPResource;
+
+/**
+ * Checks if a file is apparently javascript compatible (.js or .coffee).
+ *
+ * @param  String  file  Path to the file to test
+ * @return Boolean
+ */
+function isJsFile(file) {
+    "use strict";
+    var ext = fileExt(file);
+    return isString(ext, "string") && ['js', 'coffee'].indexOf(ext) !== -1;
+}
+exports.isJsFile = isJsFile;
+
+/**
+ * Checks if the provided value is null
+ *
+ * @return Boolean
+ */
+function isNull(value) {
+    "use strict";
+    return isType(value, "null");
+}
+exports.isNull = isNull;
+
+/**
+ * Checks if value is a javascript Number
+ *
+ * @param  mixed  value
+ * @return Boolean
+ */
+function isNumber(value) {
+    "use strict";
+    return isType(value, "number");
+}
+exports.isNumber = isNumber;
+
+/**
+ * Checks if value is a javascript Object
+ *
+ * @param  mixed  value
+ * @return Boolean
+ */
+function isObject(value) {
+    "use strict";
+    var objectTypes = ["array", "object", "qtruntimeobject"];
+    return objectTypes.indexOf(betterTypeOf(value)) >= 0;
+}
+exports.isObject = isObject;
+
+/**
+ * Checks if value is a javascript String
+ *
+ * @param  mixed  value
+ * @return Boolean
+ */
+function isString(value) {
+    "use strict";
+    return isType(value, "string");
+}
+exports.isString = isString;
+
+/**
+ * Checks that the subject is truthy.
+ *
+ * @param  Mixed  subject  Test subject
+ * @return Boolean
+ */
+function isTruthy(subject) {
+    "use strict";
+    /*jshint eqeqeq:false*/
+    return !!subject;
+}
+exports.isTruthy = isTruthy;
+
+/**
+ * Shorthands for checking if a value is of the given type. Can check for
+ * arrays.
+ *
+ * @param  mixed   what      The value to check
+ * @param  String  typeName  The type name ("string", "number", "function", etc.)
+ * @return Boolean
+ */
+function isType(what, typeName) {
+    "use strict";
+    if (typeof typeName !== "string" || !typeName) {
+        throw new CasperError("You must pass isType() a typeName string");
     }
-    exports.isUndefined = isUndefined;
-
-    /**
-     * Checks if value is a valid selector Object.
-     *
-     * @param  mixed  value
-     * @return Boolean
-     */
-    function isValidSelector(value) {
-        if (isString(value)) {
-            try {
-                // phantomjs env has a working document object, let's use it
-                document.querySelector(value);
-            } catch(e) {
-                if ('name' in e && e.name === 'SYNTAX_ERR') {
-                    return false;
-                }
-            }
-            return true;
-        } else if (isObject(value)) {
-            if (!value.hasOwnProperty('type')) {
-                return false;
-            }
-            if (!value.hasOwnProperty('path')) {
-                return false;
-            }
-            if (['css', 'xpath'].indexOf(value.type) === -1) {
+    return betterTypeOf(what).toLowerCase() === typeName.toLowerCase();
+}
+exports.isType = isType;
+
+/**
+ * Checks if the provided value is undefined
+ *
+ * @return Boolean
+ */
+function isUndefined(value) {
+    "use strict";
+    return isType(value, "undefined");
+}
+exports.isUndefined = isUndefined;
+
+/**
+ * Checks if value is a valid selector Object.
+ *
+ * @param  mixed  value
+ * @return Boolean
+ */
+function isValidSelector(value) {
+    "use strict";
+    if (isString(value)) {
+        try {
+            // phantomjs env has a working document object, let's use it
+            document.querySelector(value);
+        } catch(e) {
+            if ('name' in e && e.name === 'SYNTAX_ERR') {
                 return false;
             }
-            return true;
         }
-        return false;
-    }
-    exports.isValidSelector = isValidSelector;
-
-    /**
-     * Checks if the provided var is a WebPage instance
-     *
-     * @param  mixed  what
-     * @return Boolean
-     */
-    function isWebPage(what) {
-        return betterTypeOf(what) === "qtruntimeobject" && what.objectName === 'WebPage';
-    }
-    exports.isWebPage = isWebPage;
-
-    /**
-     * Object recursive merging utility.
-     *
-     * @param  Object  origin  the origin object
-     * @param  Object  add     the object to merge data into origin
-     * @return Object
-     */
-    function mergeObjects(origin, add) {
-        for (var p in add) {
-            try {
-                if (add[p].constructor === Object) {
-                    origin[p] = mergeObjects(origin[p], add[p]);
-                } else {
-                    origin[p] = add[p];
-                }
-            } catch(e) {
-              origin[p] = add[p];
-            }
+        return true;
+    } else if (isObject(value)) {
+        if (!value.hasOwnProperty('type')) {
+            return false;
         }
-        return origin;
+        if (!value.hasOwnProperty('path')) {
+            return false;
+        }
+        if (['css', 'xpath'].indexOf(value.type) === -1) {
+            return false;
+        }
+        return true;
     }
-    exports.mergeObjects = mergeObjects;
-
-    /**
-     * Creates an (SG|X)ML node element.
-     *
-     * @param  String  name        The node name
-     * @param  Object  attributes  Optional attributes
-     * @return HTMLElement
-     */
-    function node(name, attributes) {
-        var _node = document.createElement(name);
-        for (var attrName in attributes) {
-            var value = attributes[attrName];
-            if (attributes.hasOwnProperty(attrName) && isString(attrName)) {
-                _node.setAttribute(attrName, value);
+    return false;
+}
+exports.isValidSelector = isValidSelector;
+
+/**
+ * Checks if the provided var is a WebPage instance
+ *
+ * @param  mixed  what
+ * @return Boolean
+ */
+function isWebPage(what) {
+    "use strict";
+    return betterTypeOf(what) === "qtruntimeobject" && what.objectName === 'WebPage';
+}
+exports.isWebPage = isWebPage;
+
+/**
+ * Object recursive merging utility.
+ *
+ * @param  Object  origin  the origin object
+ * @param  Object  add     the object to merge data into origin
+ * @return Object
+ */
+function mergeObjects(origin, add) {
+    "use strict";
+    for (var p in add) {
+        try {
+            if (add[p].constructor === Object) {
+                origin[p] = mergeObjects(origin[p], add[p]);
+            } else {
+                origin[p] = add[p];
             }
+        } catch(e) {
+          origin[p] = add[p];
         }
-        return _node;
     }
-    exports.node = node;
-
-    /**
-     * Serializes a value using JSON.
-     *
-     * @param  Mixed  value
-     * @return String
-     */
-    function serialize(value, indent) {
-        if (isArray(value)) {
-            value = value.map(function _map(prop) {
-                return isFunction(prop) ? prop.toString().replace(/\s{2,}/, '') : prop;
-            });
+    return origin;
+}
+exports.mergeObjects = mergeObjects;
+
+/**
+ * Converts milliseconds to seconds and rounds the results to 3 digits accuracy.
+ *
+ * @param  Number  milliseconds
+ * @return Number  seconds
+ */
+function ms2seconds(milliseconds) {
+    "use strict";
+    return Math.round(milliseconds / 1000 * 1000) / 1000;
+}
+exports.ms2seconds = ms2seconds;
+
+/**
+ * Creates an (SG|X)ML node element.
+ *
+ * @param  String  name        The node name
+ * @param  Object  attributes  Optional attributes
+ * @return HTMLElement
+ */
+function node(name, attributes) {
+    "use strict";
+    var _node   = document.createElement(name);
+    for (var attrName in attributes) {
+        var value = attributes[attrName];
+        if (attributes.hasOwnProperty(attrName) && isString(attrName)) {
+            _node.setAttribute(attrName, value);
         }
-        return JSON.stringify(value, null, indent);
     }
-    exports.serialize = serialize;
-
-    /**
-     * Returns unique values from an array.
-     *
-     * Note: ugly code is ugly, but efficient: http://jsperf.com/array-unique2/8
-     *
-     * @param  Array  array
-     * @return Array
-     */
-    function unique(array) {
-        var o = {},
-            r = [];
-        for (var i = 0, len = array.length; i !== len; i++) {
-            var d = array[i];
-            if (o[d] !== 1) {
-                o[d] = 1;
-                r[r.length] = d;
-            }
+    return _node;
+}
+exports.node = node;
+
+/**
+ * Maps an object to an array made from its values.
+ *
+ * @param  Object  obj
+ * @return Array
+ */
+function objectValues(obj) {
+    "use strict";
+    return Object.keys(obj).map(function(arg) {
+        return obj[arg];
+    });
+}
+exports.objectValues = objectValues;
+
+/**
+ * Serializes a value using JSON.
+ *
+ * @param  Mixed  value
+ * @return String
+ */
+function serialize(value, indent) {
+    "use strict";
+    if (isArray(value)) {
+        value = value.map(function _map(prop) {
+            return isFunction(prop) ? prop.toString().replace(/\s{2,}/, '') : prop;
+        });
+    }
+    return JSON.stringify(value, null, indent);
+}
+exports.serialize = serialize;
+
+/**
+ * Returns unique values from an array.
+ *
+ * Note: ugly code is ugly, but efficient: http://jsperf.com/array-unique2/8
+ *
+ * @param  Array  array
+ * @return Array
+ */
+function unique(array) {
+    "use strict";
+    var o = {},
+        r = [];
+    for (var i = 0, len = array.length; i !== len; i++) {
+        var d = array[i];
+        if (o[d] !== 1) {
+            o[d] = 1;
+            r[r.length] = d;
         }
-        return r;
     }
-    exports.unique = unique;
-})(exports);
+    return r;
+}
+exports.unique = unique;