jsbeans

/*!
 * Copyright (c) 2009 Francesco Mele jsbeans@francescomele.com
 *
 * This Software is licenced under the LGPL Licence (GNU Lesser General 
 * Public License).
 * In addition to the LGPL Licence the Software is subject to the 
 * following conditions:
 * 
 * 	i	every modification must be public and comunicated to the Author
 * 	ii	every "jsbean" added to this library must be self consistent 
 * 		except for the dependence from jsbeans-x.x.x.js
 * 	iii	copyright notice and this permission notice shall be included 
 * 		in all copies or substantial portions of the Software
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
 * OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
 * HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
 * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
 * OTHER DEALINGS IN THE SOFTWARE.
 */
/**
 * An Iterator generates a series of elements, one at a time. Successive calls to the
 * {@method} <code class="methd">next</code> method return successive elements of the series.
 * @namespace jsbeans
 * @class Iterator
 * @constructor
 * @param object {Object} any object that supports the <code>for in</code> directive.
 * @param [parserFunction] {Function} a custom function to format each element returned by <code class="methd">next</code>.<br/>
 * <code class="param">parserFunction</code> will be called with property name as first argument and property value as second one.<br/>
 * If not set or <code class="param">parserFunction</code> is not a Function the default parser will be used (see <a href="#method_next"><code class="methd">next</code></a> method).<br/>
 * Please, note that error handling is up to developer since the <code>catch</code> block on each step is empty.<br/>
 * To return a JSON in the format <code>&#123;name: itemName, value: itemValue&#125;</code> use <code class="prop">jsbeans.Iterator.JSON_FORMAT</code>
 * */
jsbeans.Iterator = function(obj /*, parserFunction */) {
	var __innerArray = [], __innerIdx = 0;
	// checks if an object is a function
	var __isFunc = function(fn) {
		return !!fn && typeof fn != "string" && !fn.nodeName && fn.constructor != Array && /function/i.test( fn + "" );
	};
	// default parser
	var __parser = function(p, v) {
		return [p, v];
	};
	if (__isFunc(arguments[1])) {
		__parser = arguments[1];
	};

	if (obj.length) {
		__innerArray = obj;
	} 
	else {
		for (var p in obj) {
			try {
				__innerArray.push(__parser(p, obj[p]));
			}
			// hide error
			catch(e) {}
		}
	}
	/**
	 * Returns the next element in the iteration.
	 * @method next
	 * @return {Array} an Array of original Object with the property name at first position and the property value at second position (<code>[name, value]</code>).<br/>
	 * If the constructor has been called with the optional <code class="param">parserFunction</code> argument the result format may vary.
	 * */
	this.next = function() {
		return __innerArray[__innerIdx++];
	};
	/**
	 * Returns <code>true</code> if the iteration has more elements.
	 * @method hasNext
	 * @return {boolean}
	 * */
	this.hasNext = function() {
		return __innerIdx < __innerArray.length;
	};
	/**
	 * Facility function to format items in the form of a JSON as follow: <code>{name: itemName, value: itemValue}</code>
	 * @property JSON_FORMAT
	 * @type Function
	 * @static
	 * @final
	 * */
	JSON_FORMAT = function(itemName, itemValue) {
		return {name: itemName, value: itemValue};
	};
};