sproutit-sproutcore 1.0.0.20090407205609 → 1.0.0.20090408130025

data/frameworks/sproutcore/frameworks/runtime/core.js

@@ -0,0 +1,777 @@
+// ==========================================================================
+// Project:   SproutCore Costello - Property Observing Library
+// Copyright: ©2006-2009 Sprout Systems, Inc. and contributors.
+//            Portions ©2008-2009 Apple, Inc. All rights reserved.
+// License:   Licened under MIT license (see license.js)
+// ==========================================================================
+
+/*global NodeList */
+
+// These commands are used by the build tools to control load order.  On the
+// client side these are a no-op.
+var require = require || function require() { } ;
+var sc_require = sc_require || require;
+var sc_resource = sc_resource || function sc_resource() {};
+
+sc_require('license') ;
+
+// ........................................
+// GLOBAL CONSTANTS
+// 
+// Most global constants should be defined inside of the SC namespace.  
+// However the following two are useful enough and generally benign enough
+// to put into the global object.
+var YES = true ; 
+var NO = false ;
+
+// prevent a console.log from blowing things up if we are on a browser that
+// does not support it
+if (typeof console === 'undefined') {
+  var console = console || window.console || {} ;
+  console.log = console.info = console.warn = console.error = function(){};
+}
+
+// ........................................
+// BOOTSTRAP
+// 
+// The root namespace and some common utility methods are defined here. The
+// rest of the methods go into the mixin defined below.
+
+/**
+  @namespace
+  
+  The SproutCore namespace.  All SproutCore methods and functions are defined
+  inside of this namespace.  You generally should not add new properties to
+  this namespace as it may be overwritten by future versions of SproutCore.
+  
+  You can also use the shorthand "SC" instead of "SproutCore".
+  
+  SproutCore-Base is a framework that provides core functions for SproutCore
+  including cross-platform functions, support for property observing and
+  objects.  It's focus is on small size and performance.  You can use this 
+  in place of or along-side other cross-platform libraries such as jQuery or
+  Prototype.
+  
+  The core Base framework is based on the jQuery API with a number of 
+  performance optimizations.
+*/
+var SC = SC || {} ; 
+var SproutCore = SproutCore || SC ;
+
+/**
+  Adds properties to a target object.
+  
+  Takes the root object and adds the attributes for any additional 
+  arguments passed.
+
+  @param target {Object} the target object to extend
+  @param properties {Object} one or more objects with properties to copy.
+  @returns {Object} the target object.
+  @static
+*/
+SC.mixin = function() {
+  // copy reference to target object
+  var target = arguments[0] || {};
+  var idx = 1;
+  var length = arguments.length ;
+  var options ;
+
+  // Handle case where we have only one item...extend SC
+  if (length === 1) {
+    target = this || {};
+    idx=0;
+  }
+
+  for ( ; idx < length; idx++ ) {
+    if (!(options = arguments[idx])) continue ;
+    for(var key in options) {
+      if (!options.hasOwnProperty(key)) continue ;
+      var src = target[key];
+      var copy = options[key] ;
+      if (target===copy) continue ; // prevent never-ending loop
+      if (copy !== undefined) target[key] = copy ;
+    }
+  }
+  
+  return target;
+} ;
+
+/** 
+  Alternative to mixin.  Provided for compatibility with jQuery.
+  @function 
+*/
+SC.extend = SC.mixin ;
+
+// ..........................................................
+// CORE FUNCTIONS
+// 
+// Enough with the bootstrap code.  Let's define some core functions
+
+SC.mixin(/** @scope SC */ {
+  
+  // ........................................
+  // GLOBAL CONSTANTS
+  // 
+  T_ERROR:     'error',
+  T_OBJECT:    'object',
+  T_NULL:      'null',
+  T_CLASS:     'class',
+  T_HASH:      'hash',
+  T_FUNCTION:  'function',
+  T_UNDEFINED: 'undefined',
+  T_NUMBER:    'number',
+  T_BOOL:      'boolean',
+  T_ARRAY:     'array',
+  T_STRING:    'string',
+  
+  // ........................................
+  // TYPING & ARRAY MESSAGING
+  //   
+
+  /**
+    Returns a consistant type for the passed item.
+
+    Use this instead of the built-in typeOf() to get the type of an item. 
+    It will return the same result across all browsers and includes a bit 
+    more detail.  Here is what will be returned:
+
+    | Return Value Constant | Meaning |
+    | SC.T_STRING | String primitive |
+    | SC.T_NUMBER | Number primitive |
+    | SC.T_BOOLEAN | Boolean primitive |
+    | SC.T_NULL | Null value |
+    | SC.T_UNDEFINED | Undefined value |
+    | SC.T_FUNCTION | A function |
+    | SC.T_ARRAY | An instance of Array |
+    | SC.T_CLASS | A SproutCore class (created using SC.Object.extend()) |
+    | SC.T_OBJECT | A SproutCore object instance |
+    | SC.T_HASH | A JavaScript object not inheriting from SC.Object |
+
+    @param item {Object} the item to check
+    @returns {String} the type
+  */  
+  typeOf: function(item) {
+    if (item === undefined) return SC.T_UNDEFINED ;
+    if (item === null) return SC.T_NULL ; 
+    var ret = typeof(item) ;
+    if (ret == "object") {
+      if (item instanceof Array) {
+        ret = SC.T_ARRAY ;
+      } else if (item instanceof Function) {
+        ret = item.isClass ? SC.T_CLASS : SC.T_FUNCTION ;
+
+      // NB: typeOf() may be called before SC.Error has had a chance to load
+      // so this code checks for the presence of SC.Error first just to make
+      // sure.  No error instance can exist before the class loads anyway so
+      // this is safe.
+      } else if (SC.Error && (item instanceof SC.Error)) {
+        ret = SC.T_ERROR ;        
+      } else if (item.isObject === true) {
+        ret = SC.T_OBJECT ;
+      } else ret = SC.T_HASH ;
+    } else if (ret === SC.T_FUNCTION) ret = (item.isClass) ? SC.T_CLASS : SC.T_FUNCTION;
+    return ret ;
+  },
+
+  /**
+    Returns YES if the passed value is null or undefined.  This avoids errors
+    from JSLint complaining about use of ==, which can be technically 
+    confusing.
+  */
+  none: function(obj) {
+    return obj===null || obj===undefined;  
+  },
+
+  /**
+    Returns YES if the passed object is an array or array-like. Instances
+    of the NodeList class return NO.
+
+    Unlike SC.typeOf this method returns true even if the passed object is 
+    not formally array but appears to be array-like (i.e. has a length 
+    property, responds to .objectAt, etc.)
+
+    @param obj {Object} the object to test
+    @returns {Boolean} 
+  */
+  isArray: function(obj) {
+    if (obj && obj.objectAt) return YES ; // fast path
+
+    var len = (obj ? obj.length : null), type = SC.typeOf(obj);
+    return !(SC.none(len) || (type === SC.T_FUNCTION) || (type === SC.T_STRING) || obj.setInterval) ;
+  },
+
+  /**
+    Makes an object into an Array if it is not array or array-like already.
+    Unlike SC.A(), this method will not clone the object if it is already
+    an array.
+  */
+  makeArray: function(obj) {
+    return SC.isArray(obj) ? obj : SC.$A(obj);
+  },
+
+  /**
+    Converts the passed object to an Array.  If the object appears to be 
+    array-like, a new array will be cloned from it.  Otherwise, a new array
+    will be created with the item itself as the only item in the array.
+
+    @param object {Object} any enumerable or array-like object.
+    @returns {Array} Array of items
+  */
+  A: function(obj) {
+
+    // null or undefined -- fast path
+    if (SC.none(obj)) return [] ;
+
+    // primitive -- fast path
+    if (obj.slice instanceof Function) return obj.slice() ; 
+
+    // enumerable -- fast path
+    if (obj.toArray) return obj.toArray() ;
+
+    // if not array-like, then just wrap in array.
+    if (!SC.isArray(obj)) return [obj];
+
+    // when all else fails, do a manual convert...
+    var ret = [], len = obj.length;
+    while(--len >= 0) ret[len] = obj[len];
+    return ret ;
+  },  
+  
+  // ..........................................................
+  // GUIDS & HASHES
+  // 
+  
+  guidKey: "_sc_guid_" + new Date().getTime(),
+
+  // Used for guid generation...
+  _nextGUID: 0, _numberGuids: [], _stringGuids: {}, _keyCache: {},
+
+  /**
+    Returns a unique GUID for the object.  If the object does not yet have
+    a guid, one will be assigned to it.  You can call this on any object,
+    SC.Object-based or not, but be aware that it will add a _guid property.
+
+    You can also use this method on DOM Element objects.
+
+    @param obj {Object} any object, string, number, Element, or primitive
+    @returns {String} the unique guid for this instance.
+  */
+  guidFor: function(obj) {
+    
+    // special cases where we don't want to add a key to object
+    if (obj === undefined) return "(undefined)" ;
+    if (obj === null) return '(null)' ;
+    if (obj === Object) return '(Object)';
+    if (obj === Array) return '(Array)';
+    
+    var guidKey = this.guidKey ;
+    if (obj[guidKey]) return obj[guidKey] ;
+
+    switch(this.typeOf(obj)) {
+      case SC.T_NUMBER:
+        return (this._numberGuids[obj] = this._numberGuids[obj] || ("nu" + obj));
+      case SC.T_STRING:
+        return (this._stringGuids[obj] = this._stringGuids[obj] || ("st" + obj));
+      case SC.T_BOOL:
+        return (obj) ? "(true)" : "(false)" ;
+      default:
+        return SC.generateGuid(obj);
+    }
+  },
+
+  /**
+    Returns a key name that combines the named key + prefix.  This is more 
+    efficient than simply combining strings because it uses a cache  
+    internally for performance.
+    
+    @param 
+  */
+  keyFor: function(prefix, key) {
+    var ret, pcache = this._keyCache[prefix];
+    if (!pcache) pcache = this._keyCache[prefix] = {}; // get cache for prefix
+    ret = pcache[key];
+    if (!ret) ret = pcache[key] = prefix + '_' + key ;
+    return ret ;
+  },
+
+  /**
+    Generates a new guid, optionally saving the guid to the object that you
+    pass in.  You will rarely need to use this method.  Instead you should
+    call SC.guidFor(obj), which return an existing guid if available.
+
+    @param {Object} obj the object to assign the guid to
+    @returns {String} the guid
+  */
+  generateGuid: function(obj) { 
+    var ret = ("sc" + (this._nextGUID++)); 
+    if (obj) obj[this.guidKey] = ret ;
+    return ret ;
+  },
+
+  /**
+    Returns a unique hash code for the object.  If the object implements
+    a hash() method, the value of that method will be returned.  Otherwise,
+    this will return the same value as guidFor().  
+
+    Unlike guidFor(), this method allows you to implement logic in your 
+    code to cause two separate instances of the same object to be treated as
+    if they were equal for comparisons and other functions.
+
+    IMPORTANT:  If you implement a hash() method, it MUST NOT return a 
+    number or a string that contains only a number.  Typically hash codes 
+    are strings that begin with a "%".
+
+    @param obj {Object} the object
+    @returns {String} the hash code for this instance.
+  */
+  hashFor: function(obj) {
+    return (obj && obj.hash && SC.typeOf(obj.hash) === SC.T_FUNCTION) ? obj.hash() : this.guidFor(obj) ;
+  },
+    
+  /**
+    This will compare the two object values using their hash codes.
+
+    @param a {Object} first value to compare
+    @param b {Object} the second value to compare
+    @returns {Boolean} YES if the two have equal hash code values.
+
+  */
+  isEqual: function(a,b) {
+    // shortcut a few places.
+    if (a === null) {
+      return b === null ;
+    } else if (a === undefined) {
+      return b === undefined ;
+
+    // finally, check their hash-codes
+    } else return this.hashFor(a) === this.hashFor(b) ;
+  },
+  
+  // ..........................................................
+  // OBJECT MANAGEMENT
+  // 
+  
+  /** 
+    Empty function.  Useful for some operations. 
+  */
+  K: function() { return this; },
+
+  /** Empty array.  Useful for some optimizations. */
+  EMPTY_ARRAY: [],
+
+  EMPTY_HASH: {},
+  
+  EMPTY_RANGE: {start: 0, length: 0},
+  /**
+    Creates a new object with the passed object as its prototype.
+
+    This method uses JavaScript's native inheritence method to create a new 
+    object.    
+
+    You cannot use beget() to create new SC.Object-based objects, but you
+    can use it to beget Arrays, Hashes, Sets and objects you build yourself.
+    Note that when you beget() a new object, this method will also call the
+    didBeget() method on the object you passed in if it is defined.  You can
+    use this method to perform any other setup needed.
+
+    In general, you will not use beget() often as SC.Object is much more 
+    useful, but for certain rare algorithms, this method can be very useful.
+
+    For more information on using beget(), see the section on beget() in 
+    Crockford's JavaScript: The Good Parts.
+
+    @param obj {Object} the object to beget
+    @returns {Object} the new object.
+  */
+  beget: function(obj) {
+    if (SC.none(obj)) return null ;
+    var K = SC.K; K.prototype = obj ;
+    var ret = new K();
+    K.prototype = null ; // avoid leaks
+    if (SC.typeOf(obj.didBeget) === SC.T_FUNCTION) ret = obj.didBeget(ret); 
+    return ret ;
+  },
+
+  /**
+    Creates a clone of the passed object.  This function can take just about
+    any type of object and create a clone of it, including primitive values
+    (which are not actually cloned because they are immutable).
+
+    If the passed object implements the clone() method, then this function
+    will simply call that method and return the result.
+
+    @param object {Object} the object to clone
+    @returns {Object} the cloned object
+  */
+  clone: function(object) {
+    var ret = object ;
+    switch (SC.typeOf(object)) {
+    case SC.T_ARRAY:
+      if (object.clone && SC.typeOf(object.clone) === SC.T_FUNCTION) {
+        ret = object.clone() ;
+      } else ret = object.slice() ;
+      break ;
+
+    case SC.T_HASH:
+    case SC.T_OBJECT:
+      if (object.clone && SC.typeOf(object.clone) === SC.T_FUNCTION) {
+        ret = object.clone() ;
+      } else {
+        ret = {} ;
+        for(var key in object) ret[key] = object[key] ;
+      }
+    }
+
+    return ret ;
+  },
+
+  /**
+    Returns a new object combining the values of all passed hashes.
+
+    @param object {Object} one or more objects
+    @returns {Object} new Object
+  */
+  merge: function() {
+    var ret = {}, len = arguments.length, idx;
+    for(idx=0;idx<len;idx++) SC.mixin(ret, arguments[idx]);
+    return ret ;
+  },
+
+  /**
+    Returns all of the keys defined on an object or hash.  This is useful
+    when inspecting objects for debugging.
+
+    @param {Object} obj
+    @returns {Array} array of keys
+  */
+  keys: function(obj) {
+    var ret = [];
+    for(var key in obj) ret.push(key);
+    return ret;
+  },
+
+  /**
+    Convenience method to inspect an object.  This method will attempt to 
+    convert the object into a useful string description.
+  */
+  inspect: function(obj) {
+    var v, ret = [] ;
+    for(var key in obj) {
+      v = obj[key] ;
+      if (v === 'toString') continue ; // ignore useless items
+      if (SC.typeOf(v) === SC.T_FUNCTION) v = "function() { ... }" ;
+      ret.push(key + ": " + v) ;
+    }
+    return "{" + ret.join(" , ") + "}" ;
+  },
+
+  /**
+    Returns a tuple containing the object and key for the specified property 
+    path.  If no object could be found to match the property path, then 
+    returns null.
+
+    This is the standard method used throughout SproutCore to resolve property
+    paths.
+
+    @param path {String} the property path
+    @param root {Object} optional parameter specifying the place to start
+    @returns {Array} array with [object, property] if found or null
+  */
+  tupleForPropertyPath: function(path, root) {
+
+    // if the passed path is itself a tuple, return it
+    if (SC.typeOf(path) === SC.T_ARRAY) return path ;
+
+    // find the key.  It is the last . or first *
+    var key ;
+    var stopAt = path.indexOf('*') ;
+    if (stopAt < 0) stopAt = path.lastIndexOf('.') ;
+    key = (stopAt >= 0) ? path.slice(stopAt+1) : path ;
+
+    // convert path to object.
+    var obj = this.objectForPropertyPath(path, root, stopAt) ;
+    return (obj && key) ? [obj,key] : null ;
+  },
+
+  /** 
+    Finds the object for the passed path or array of path components.  This is 
+    the standard method used in SproutCore to traverse object paths.
+
+    @param path {String} the path
+    @param root {Object} optional root object.  window is used otherwise
+    @param stopAt {Integer} optional point to stop searching the path.
+    @returns {Object} the found object or undefined.
+  */
+  objectForPropertyPath: function(path, root, stopAt) {
+
+    var loc, nextDotAt, key, max ;
+
+    if (!root) root = window ;
+
+    // faster method for strings
+    if (SC.typeOf(path) === SC.T_STRING) {
+      if (stopAt === undefined) stopAt = path.length ;
+      loc = 0 ;
+      while((root) && (loc < stopAt)) {
+        nextDotAt = path.indexOf('.', loc) ;
+        if ((nextDotAt < 0) || (nextDotAt > stopAt)) nextDotAt = stopAt;
+        key = path.slice(loc, nextDotAt);
+        root = root.get ? root.get(key) : root[key] ;
+        loc = nextDotAt+1; 
+      }
+      if (loc < stopAt) root = undefined; // hit a dead end. :(
+
+    // older method using an array
+    } else {
+
+      loc = 0; max = path.length; key = null;
+      while((loc < max) && root) {
+        key = path[loc++];
+        if (key) root = (root.get) ? root.get(key) : root[key] ;
+      }
+      if (loc < max) root = undefined ;
+    }
+
+    return root ;
+  }
+  
+  
+}); // end mixin
+
+/** @private Alias for SC.A() */
+SC.$A = SC.A;
+
+/** @private Alias for SC.typeOf() */
+SC.typeOf = SC.typeOf ;
+  
+/** @private Provided for compatibility with old HTML templates. */
+SC.didLoad = SC.K ;
+
+// ........................................
+// FUNCTION ENHANCEMENTS
+//
+SC.mixin(Function.prototype, 
+/** @scope Function.prototype */ {
+  
+  /**
+    Indicates that the function should be treated as a computed property.
+    
+    Computed properties are methods that you want to treat as if they were
+    static properties.  When you use get() or set() on a computed property,
+    the object will call the property method and return its value instead of 
+    returning the method itself.  This makes it easy to create "virtual 
+    properties" that are computed dynamically from other properties.
+    
+    Consider the following example:
+    
+    {{{
+      contact = SC.Object.create({
+
+        firstName: "Charles",
+        lastName: "Jolley",
+        
+        // This is a computed property!
+        fullName: function() {
+          return this.getEach('firstName','lastName').compact().join(' ') ;
+        }.property('firstName', 'lastName'),
+        
+        // this is not
+        getFullName: function() {
+          return this.getEach('firstName','lastName').compact().join(' ') ;
+        }
+      });
+
+      contact.get('firstName') ;
+      --> "Charles"
+      
+      contact.get('fullName') ;
+      --> "Charles Jolley"
+      
+      contact.get('getFullName') ;
+      --> function()
+    }}}
+    
+    Note that when you get the fullName property, SproutCore will call the
+    fullName() function and return its value whereas when you get() a property
+    that contains a regular method (such as getFullName above), then the 
+    function itself will be returned instead.
+    
+    h2. Using Dependent Keys
+
+    Computed properties are often computed dynamically from other member 
+    properties.  Whenever those properties change, you need to notify any
+    object that is observing the computed property that the computed property
+    has changed also.  We call these properties the computed property is based
+    upon "dependent keys".
+    
+    For example, in the contact object above, the fullName property depends on
+    the firstName and lastName property.  If either property value changes,
+    any observer watching the fullName property will need to be notified as 
+    well.
+    
+    You inform SproutCore of these dependent keys by passing the key names
+    as parameters to the property() function.  Whenever the value of any key
+    you name here changes, the computed property will be marked as changed
+    also.
+    
+    You should always register dependent keys for computed properties to 
+    ensure they update.
+    
+    h2. Using Computed Properties as Setters
+    
+    Computed properties can be used to modify the state of an object as well
+    as to return a value.  Unlike many other key-value system, you use the 
+    same method to both get and set values on a computed property.  To 
+    write a setter, simply declare two extra parameters: key and value.
+    
+    Whenever your property function is called as a setter, the value 
+    parameter will be set.  Whenever your property is called as a getter the
+    value parameter will be undefined.
+    
+    For example, the following object will split any full name that you set
+    into a first name and last name components and save them.
+    
+    {{{
+      contact = SC.Object.create({
+        
+        fullName: function(key, value) {
+          if (value !== undefined) {
+            var parts = value.split(' ') ;
+            this.beginPropertyChanges()
+              .set('firstName', parts[0])
+              .set('lastName', parts[1])
+            .endPropertyChanges() ;
+          }
+          return this.getEach('firstName', 'lastName').compact().join(' ');
+        }.property('firstName','lastName')
+        
+      }) ;
+      
+    }}}
+    
+    bq. *Why Use The Same Method for Getters and Setters?*  Most property-
+    based frameworks expect you to write two methods for each property but
+    SproutCore only uses one.  We do this because most of the time when
+    you write a setter is is basically a getter plus some extra work.  There 
+    is little added benefit in writing both methods when you can conditionally
+    exclude part of it.  This helps to keep your code more compact and easier
+    to maintain.
+    
+    @param dependentKeys {String...} optional set of dependent keys
+    @returns {Function} the declared function instance
+  */
+  property: function() {
+    this.dependentKeys = SC.$A(arguments) ; 
+    this.cacheKey = "__cache__" + SC.guidFor(this) ;
+    this.lastSetValueKey = "__lastValue__" + SC.guidFor(this) ;
+    this.isProperty = true; return this; 
+  },
+  
+  /**
+    You can call this method on a computed property to indicate that the 
+    property is cacheable (or not cacheable).  By default all computed 
+    properties are not cached.  Enabling this feature will allow SproutCore
+    to cache the return value of your computed property and to use that
+    value until one of your dependent properties changes or until you 
+    invoke propertyDidChange() and name the computed property itself.
+    
+    If you do not specify this option, computed properties are assumed to be
+    not cacheable.
+    
+    @param {Boolean} aFlag optionally indicate cacheable or no, default YES
+    @returns {Function} reciever
+  */
+  cacheable: function(aFlag) {
+    this.isProperty = YES;  // also make a property just in case
+    if (!this.dependentKeys) this.dependentKeys = [] ;
+    this.isCacheable = (aFlag === undefined) ? YES : aFlag ;
+    return this;
+  },
+  
+  /**
+    Indicates that the computed property is volatile.  Normally SproutCore 
+    assumes that your computed property is indempotent.  That is, calling 
+    set() on your property more than once with the same value has the same
+    effect as calling it only once.  
+    
+    All non-computed properties are indempotent and normally you should make
+    your computed properties behave the same way.  However, if you need to
+    make your property change its return value everytime your method is
+    called, you may chain this to your property to make it volatile.
+    
+    If you do not specify this option, properties are assumed to be 
+    non-volatile. 
+    
+    @param {Boolean} aFlag optionally indicate state, default to YES
+    @returns {Function} receiver
+  */
+  indempotent: function(aFlag) {
+    this.isProperty = YES;  // also make a property just in case
+    if (!this.dependentKeys) this.dependentKeys = [] ;
+    this.isVolatile = !((aFlag === undefined) ? NO : aFlag) ;
+    return this;
+  },
+  
+  /**  
+    Declare that a function should observe an object at the named path.  Note
+    that the path is used only to construct the observation one time.
+  */
+  observes: function(propertyPaths) { 
+    
+    // sort property paths into local paths (i.e just a property name) and
+    // full paths (i.e. those with a . or * in them)
+    var loc = arguments.length, local = null, paths = null;
+    while(--loc >= 0) {
+      var path = arguments[loc] ;
+      // local
+      if ((path.indexOf('.')<0) && (path.indexOf('*')<0)) {
+        if (!local) local = this.localPropertyPaths = [];
+        local.push(path);
+        
+      // regular
+      } else {
+        if (!paths) paths = this.propertyPaths = [];
+        paths.push(path) ;
+      }
+    }
+    return this;
+  }
+    
+}) ;
+
+// ..........................................................
+// STRING ENHANCEMENT
+// 
+
+// Interpolate string. looks for %@ or %@1; to control the order of params.
+/**
+  Apply formatting options to the string.  This will look for occurrences
+  of %@ in your string and substitute them with the arguments you pass into
+  this method.  If you want to control the specific order of replacement, 
+  you can add a number after the key as well to indicate which argument 
+  you want to insert.  
+
+  Ordered insertions are most useful when building loc strings where values
+  you need to insert may appear in different orders.
+
+  h3. Examples
+  
+  {{{
+    "Hello %@ %@".fmt('John', 'Doe') => "Hello John Doe"
+    "Hello %@2, %@1".fmt('John', 'Doe') => "Hello Doe, John"
+  }}}
+  
+  @param args {Object...} optional arguments
+  @returns {String} formatted string
+*/
+String.prototype.fmt = function() {
+  // first, replace any ORDERED replacements.
+  var args = arguments;
+  var idx  = 0; // the current index for non-numerical replacements
+  return this.replace(/%@([0-9]+)?/g, function(s, argIndex) {
+    argIndex = (argIndex) ? parseInt(argIndex,0)-1 : idx++ ;
+    s =args[argIndex];
+    return ((s===null) ? '(null)' : (s===undefined) ? '' : s).toString(); 
+  }) ;
+};
+