From 2101135eae654355b0759bb60b0ae539d443af2c Mon Sep 17 00:00:00 2001
From: ewinslow <ewinslow@36083f99-b078-4883-b0ff-0f9b5a30f544>
Date: Sun, 7 Nov 2010 09:12:53 +0000
Subject: Addition of type-checking helper functions, various tweaks to
 comments, code style, etc.

git-svn-id: http://code.elgg.org/elgg/trunk@7252 36083f99-b078-4883-b0ff-0f9b5a30f544
---
 js/lib/elgglib.js | 167 +++++++++++++++++++++++++++++++++++++++++++++---------
 1 file changed, 140 insertions(+), 27 deletions(-)

diff --git a/js/lib/elgglib.js b/js/lib/elgglib.js
index 5f1edf812..d71e82747 100644
--- a/js/lib/elgglib.js
+++ b/js/lib/elgglib.js
@@ -1,24 +1,132 @@
 /**
+ * @namespace Singleton object for holding the Elgg javascript library
+ */
+var elgg = elgg || {};
+
+/**
+ * Pointer to the global context
  * 
+ * @see elgg.require
+ * @see elgg.provide
+ */
+elgg.global = this;
+
+/**
+ * Convenience reference to an empty function.
  * 
+ * Save memory by not generating multiple empty functions.
  */
+elgg.nullFunction = function() {};
 
 /**
- * @namespace Namespace for elgg javascript functions
+ * 
+ * @example
+ * AbstractClass.prototype.toBeImplemented = elgg.abstractMethod;
+ * 
+ * Now this forces an inheriting class to implement the method or
+ * it will throw an error.
  */
-var elgg = elgg || {};
+elgg.abstractMethod = function(name) {
+	throw new Error("Oops... you forgot to implement " + name + "!");
+};
 
-elgg.assertTypeOf = function(type, param) {
-	if (typeof param !== type) {
-		throw new TypeError("Expecting param to be a(n) " + type + ".  Was a(n) " + typeof param + ".");
-	}
+/**
+ * Check if the value is an array.  
+ * 
+ * No sense in reinventing the wheel!
+ * 
+ * @return boolean
+ */
+elgg.isArray = jQuery.isArray;
+
+/**
+ * Check if the value is a function.  
+ * 
+ * No sense in reinventing the wheel!
+ * 
+ * @return boolean
+ */
+elgg.isFunction = jQuery.isFunction;
+
+/**
+ * Check if the value is a "plain" object (i.e., created by {} or new Object())
+ * 
+ * No sense in reinventing the wheel!
+ * 
+ * @return boolean
+ */
+elgg.isPlainObject = jQuery.isPlainObject;
+
+/**
+ * Check if the value is a string
+ * 
+ * @param {*} val
+ * 
+ * @return boolean
+ */
+elgg.isString = function(val) {
+	return typeof val === 'string';
 };
 
 /**
- * Pointer to the global context
- * {@see elgg.require} and {@see elgg.provide}
+ * Check if the value is an object
+ * 
+ * @note This returns true for functions and arrays!  If you want to return true only
+ * for "plain" objects (created using {} or new Object()) use elgg.isPlainObject.
+ * 
+ * @param {*} val
+ * 
+ * @return boolean
  */
-elgg.global = this;
+elgg.isObject = function(val) {
+	return typeof val === 'object';
+};
+
+/**
+ * Check if the value is undefined
+ * 
+ * @param {*} val
+ * 
+ * @return boolean
+ */
+elgg.isUndefined = function(val) {
+	return val === undefined;
+};
+
+/**
+ * Check if the value is null
+ * 
+ * @param {*} val
+ * 
+ * @return boolean
+ */
+elgg.isNull = function(val) {
+	return val === null;
+};
+
+/**
+ * Check if the value is either null or undefined
+ * 
+ * @param {*} val
+ * 
+ * @return boolean
+ */
+elgg.isNullOrUndefined = function(val) {
+	return val == null;
+};
+
+/**
+ * Throw an exception of the type doesn't match
+ * 
+ * @todo Might be more appropriate for debug mode only?
+ */
+elgg.assertTypeOf = function(type, val) {
+	if (typeof val !== type) {
+		throw new TypeError("Expecting param of " + 
+			arguments.caller + "to be a(n) " + type + "." + 
+			"  Was actually a(n) " + typeof val + ".");
+	}
+};
 
 /**
  * Throw an error if the required package isn't present
@@ -30,12 +138,12 @@ elgg.require = function(pkg) {
 	
 	var parts = pkg.split('.'),
 		cur = elgg.global,
-		part;
+		part, i;
 
-	for (var i = 0; i < parts.length; i++) {
+	for (i = 0; i < parts.length; i += 1) {
 		part = parts[i];
 		cur = cur[part];
-		if(typeof cur == 'undefined') {
+		if (elgg.isUndefined(cur)) {
 			throw new Error("Missing package: " + pkg);
 		}
 	}
@@ -60,17 +168,18 @@ elgg.require = function(pkg) {
  * 
  * @param {string} pkg The package name.
  */
-elgg.provide = function(pkg) {
+elgg.provide = function(pkg, opt_context) {
 	elgg.assertTypeOf('string', pkg);
 	
 	var parts = pkg.split('.'),
-		cur = elgg.global,
-		part;
+		context = opt_context || elgg.global,
+		part, i;
 	
-	for (var i = 0; i < parts.length; i++) {
+	
+	for (i = 0; i < parts.length; i += 1) {
 		part = parts[i];
-		cur[part] = cur[part] || {};
-		cur = cur[part];
+		context[part] = context[part] || {};
+		context = context[part];
 	}
 };
 
@@ -113,7 +222,8 @@ elgg.normalize_url = function(url) {
 	url = url || '';
 	elgg.assertTypeOf('string', url);
 	
-	if(/(^(https?:)?\/\/)/.test(url)) {
+	// jslint complains if you use /regexp/ shorthand here... ?!?!
+	if ((new RegExp("^(https?:)?//")).test(url)) {
 		return url;
 	}
 	
@@ -129,33 +239,36 @@ elgg.normalize_url = function(url) {
  * @private
  */
 elgg.system_messages = function(msgs, delay, type) {
-	if (msgs == undefined) {
+	if (elgg.isUndefined(msgs)) {
 		return;
 	}
 	
+	var classes = [],
+		messages_html = [],
+		i;
+	
 	//validate delay.  Must be a positive integer. 
-	delay = parseInt(delay);
+	delay = parseInt(delay, 10);
 	if (isNaN(delay) || delay <= 0) {
 		delay = 6000;
 	}
 	
 	classes = ['elgg_system_message', 'radius8'];
-	if (type == 'error') {
+	if (type === 'error') {
 		classes.push('messages_error');
 	}
 
 	//Handle non-arrays
-	if (msgs.constructor.toString().indexOf("Array") == -1) {
+	if (!elgg.isArray(msgs)) {
 		msgs = [msgs];
 	}
 	
-	var messages_html = [];
-	
-	for (var i in msgs) {
+	for (i in msgs) {
 		messages_html.push('<div class="' + classes.join(' ') + '"><p>' + msgs[i] + '</p></div>');
 	}
 	
-	$(messages_html.join('')).appendTo('#elgg_system_messages').animate({opacity:'1.0'},delay).fadeOut('slow');
+	$(messages_html.join('')).appendTo('#elgg_system_messages')
+	    .animate({opacity: '1.0'}, delay).fadeOut('slow');
 };
 
 /**
-- 
cgit v1.2.3