sproutcore 1.5.0.rc.2 → 1.5.0

data/lib/frameworks/sproutcore/frameworks/runtime/ext/array.js

@@ -0,0 +1,92 @@
+// ==========================================================================
+// Project:   SproutCore Costello - Property Observing Library
+// Copyright: ©2006-2011 Strobe Inc. and contributors.
+//            Portions ©2008-2011 Apple Inc. All rights reserved.
+// License:   Licensed under MIT license (see license.js)
+// ==========================================================================
+
+sc_require('mixins/array');
+
+SC.supplement(Array.prototype, SC.CoreArray);
+
+// Because Arrays are dealt with so much, we add specialized functions.
+
+SC.mixin(Array.prototype, {
+
+  // primitive for array support.
+  replace: function(idx, amt, objects) {
+    if (this.isFrozen) { throw SC.FROZEN_ERROR ; }
+
+    var args;
+    var len = objects ? (objects.get ? objects.get('length') : objects.length) : 0;
+
+    // Notify that array content is about to mutate.
+    this.arrayContentWillChange(idx, amt, len);
+
+    if (len === 0) {
+      this.splice(idx, amt) ;
+    } else {
+      args = [idx, amt].concat(objects) ;
+      this.splice.apply(this,args) ;
+    }
+
+    this.arrayContentDidChange(idx, amt, len);
+    this.enumerableContentDidChange(idx, amt, len - amt) ;
+    return this ;
+  },
+
+  // If you ask for an unknown property, then try to collect the value
+  // from member items.
+  unknownProperty: function(key, value) {
+    var ret = this.reducedProperty(key, value) ;
+    if ((value !== undefined) && ret === undefined) {
+      ret = this[key] = value;
+    }
+    return ret ;
+  }
+
+});
+
+if (Array.prototype.indexOf === SC.CoreArray.indexOf) {
+  /**
+    Returns the index for a particular object in the index.
+
+    @param {Object} object the item to search for
+    @param {Number} startAt optional starting location to search, default 0
+    @returns {Number} index of -1 if not found
+  */
+  Array.prototype.indexOf = function(object, startAt) {
+    var idx, len = this.length;
+
+    if (startAt === undefined) startAt = 0;
+    else startAt = (startAt < 0) ? Math.ceil(startAt) : Math.floor(startAt);
+    if (startAt < 0) startAt += len;
+
+    for(idx=startAt;idx<len;idx++) {
+      if (this[idx] === object) return idx ;
+    }
+    return -1;
+  } ;
+}
+
+if (Array.prototype.lastIndexOf === SC.CoreArray.lastIndexOf) {
+  /**
+    Returns the last index for a particular object in the index.
+
+    @param {Object} object the item to search for
+    @param {Number} startAt optional starting location to search, default 0
+    @returns {Number} index of -1 if not found
+  */
+  Array.prototype.lastIndexOf = function(object, startAt) {
+    var idx, len = this.length;
+
+    if (startAt === undefined) startAt = len-1;
+    else startAt = (startAt < 0) ? Math.ceil(startAt) : Math.floor(startAt);
+    if (startAt < 0) startAt += len;
+
+    for(idx=startAt;idx>=0;idx--) {
+      if (this[idx] === object) return idx ;
+    }
+    return -1;
+  };
+}

data/lib/frameworks/sproutcore/frameworks/runtime/ext/date.js

@@ -0,0 +1,15 @@
+// ==========================================================================
+// Project:   SproutCore Costello - Property Observing Library
+// Copyright: ©2006-2011 Strobe Inc. and contributors.
+//            Portions ©2008-2011 Apple Inc. All rights reserved.
+// License:   Licensed under MIT license (see license.js)
+// ==========================================================================
+
+if (!Date.now) {
+  /**
+    @ignore
+  */
+  Date.now = function() {
+    return new Date().getTime() ;
+  };
+}

data/lib/frameworks/sproutcore/frameworks/runtime/ext/function.js

@@ -0,0 +1,189 @@
+// ==========================================================================
+// Project:   SproutCore Costello - Property Observing Library
+// Copyright: ©2006-2011 Strobe Inc. and contributors.
+//            Portions ©2008-2011 Apple Inc. All rights reserved.
+// License:   Licensed under MIT license (see license.js)
+// ==========================================================================
+
+sc_require('system/function');
+
+SC.mixin(Function.prototype,
+/** @lends 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.
+
+    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.
+
+    Sometimes you may need to depend on keys that are several objects deep. In
+    that case, you can provide a path to property():
+
+        capitalizedName: function() {
+          return this.getPath('person.fullName').toUpper();
+        }.property('person.firstName')
+
+    This will cause observers of +capitalizedName+ to be fired when either
+    +fullName+ _or_ +person+ changes.
+
+    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')
+
+          }) ;
+
+    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 {String...} dependentKeys optional set of dependent keys
+    @returns {Function} the declared function instance
+  */
+  property: function() {
+    return SC.Function.property(this, arguments);
+  },
+
+  /**
+    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, useful for chaining calls.
+  */
+  cacheable: function(aFlag) {
+    return SC.Function.cacheable(this, aFlag);
+  },
+
+  /**
+    Indicates that the computed property is volatile.  Normally SproutCore
+    assumes that your computed property is idempotent.  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 idempotent 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} reciever, useful for chaining calls.
+  */
+  idempotent: function(aFlag) {
+    return SC.Function.idempotent(this, aFlag);
+  },
+
+  enhance: function() {
+    return SC.Function.enhance(this);
+  },
+
+  /**
+    Declare that a function should observe an object or property at the named 
+    path.  Note that the path is used only to construct the observation one time.
+
+    @param {String...} propertyPaths A list of strings which indicate the
+      properties being observed
+      
+    @returns {Function} reciever, useful for chaining calls.
+  */
+  observes: function(propertyPaths) {
+    return SC.Function.observes(this, arguments);
+  }
+
+});

data/lib/frameworks/sproutcore/frameworks/runtime/ext/string.js

@@ -0,0 +1,31 @@
+// ==========================================================================
+// Project:   SproutCore Costello - Property Observing Library
+// Copyright: ©2006-2011 Strobe Inc. and contributors.
+//            Portions ©2008-2011 Apple Inc. All rights reserved.
+// License:   Licensed under MIT license (see license.js)
+// ==========================================================================
+
+sc_require('system/string');
+
+/** 
+  @namespace
+  Extends String by adding a few helpful methods.
+*/
+SC.mixin(String.prototype,
+/** @scope String.prototype */ {
+
+  /**
+    @see SC.String.fmt
+  */
+  fmt: function() {
+    return SC.String.fmt(this, arguments);
+  },
+
+  /**
+    @see SC.String.w
+  */
+  w: function() {
+    return SC.String.w(this);
+  }
+
+});

data/lib/frameworks/sproutcore/frameworks/runtime/mixins/array.js

@@ -7,45 +7,14 @@
 
 // note: SC.Observable also enhances array.  make sure we are called after
 // SC.Observable so our version of unknownProperty wins.
+sc_require('ext/function');
 sc_require('mixins/observable');
 sc_require('mixins/enumerable');
 sc_require('system/range_observer');
 
-SC.OUT_OF_RANGE_EXCEPTION = "Index out of range" ;
+SC.OUT_OF_RANGE_EXCEPTION = "Index out of range";
 
-/**
-  @namespace
-
-  This module implements Observer-friendly Array-like behavior.  This mixin is
-  picked up by the Array class as well as other controllers, etc. that want to
-  appear to be arrays.
-
-  Unlike SC.Enumerable, this mixin defines methods specifically for
-  collections that provide index-ordered access to their contents.  When you
-  are designing code that needs to accept any kind of Array-like object, you
-  should use these methods instead of Array primitives because these will
-  properly notify observers of changes to the array.
-
-  Although these methods are efficient, they do add a layer of indirection to
-  your application so it is a good idea to use them only when you need the
-  flexibility of using both true JavaScript arrays and "virtual" arrays such
-  as controllers and collections.
-
-  You can use the methods defined in this module to access and modify array
-  contents in a KVO-friendly way.  You can also be notified whenever the
-  membership if an array changes by changing the syntax of the property to
-  .observes('*myProperty.[]') .
-
-  To support SC.Array in your own class, you must override two
-  primitives to use it: replace() and objectAt().
-
-  Note that the SC.Array mixin also incorporates the SC.Enumerable mixin.  All
-  SC.Array-like objects are also enumerable.
-
-  @extends SC.Enumerable
-  @since SproutCore 0.9.0
-*/
-SC.Array = /** @scope SC.Array.prototype */{
+SC.CoreArray = /** @lends SC.Array.prototype */ {
 
   /**
     Walk like a duck - use isSCArray to avoid conflicts
@@ -89,6 +58,46 @@ SC.Array = /** @scope SC.Array.prototype */{
     throw "replace() must be implemented to support SC.Array" ;
   },
 
+  /**
+    Returns the index for a particular object in the index.
+
+    @param {Object} object the item to search for
+    @param {Number} startAt optional starting location to search, default 0
+    @returns {Number} index of -1 if not found
+  */
+  indexOf: function(object, startAt) {
+    var idx, len = this.get('length');
+
+    if (startAt === undefined) startAt = 0;
+    else startAt = (startAt < 0) ? Math.ceil(startAt) : Math.floor(startAt);
+    if (startAt < 0) startAt += len;
+
+    for(idx=startAt;idx<len;idx++) {
+      if (this.objectAt(idx, YES) === object) return idx ;
+    }
+    return -1;
+  },
+
+  /**
+    Returns the last index for a particular object in the index.
+
+    @param {Object} object the item to search for
+    @param {Number} startAt optional starting location to search, default 0
+    @returns {Number} index of -1 if not found
+  */
+  lastIndexOf: function(object, startAt) {
+    var idx, len = this.get('length');
+
+    if (startAt === undefined) startAt = len-1;
+    else startAt = (startAt < 0) ? Math.ceil(startAt) : Math.floor(startAt);
+    if (startAt < 0) startAt += len;
+
+    for(idx=startAt;idx>=0;idx--) {
+      if (this.objectAt(idx) === object) return idx ;
+    }
+    return -1;
+  },
+
   /**
     This is one of the primitives you must implement to support SC.Array.
     Returns the object at the named index.  If your object supports retrieving
@@ -204,6 +213,27 @@ SC.Array = /** @scope SC.Array.prototype */{
     return this;
   },
 
+  /**
+    Returns a new array that is a slice of the receiver.  This implementation
+    uses the observable array methods to retrieve the objects for the new
+    slice.
+
+    If you don't pass in beginIndex and endIndex, it will act as a copy of the
+    array.
+
+    @param beginIndex {Integer} (Optional) index to begin slicing from.
+    @param endIndex {Integer} (Optional) index to end the slice at.
+    @returns {Array} New array with specified slice
+  */
+  slice: function(beginIndex, endIndex) {
+    var ret = [];
+    var length = this.get('length') ;
+    if (SC.none(beginIndex)) beginIndex = 0 ;
+    if (SC.none(endIndex) || (endIndex > length)) endIndex = length ;
+    while(beginIndex < endIndex) ret[ret.length] = this.objectAt(beginIndex++) ;
+    return ret ;
+  },
+
   /**
     Push the object onto the end of the array.  Works just like push() but it
     is KVO-compliant.
@@ -838,167 +868,36 @@ SC.Array = /** @scope SC.Array.prototype */{
 
 } ;
 
-// Add SC.Array to the built-in array before we add SC.Enumerable to SC.Array
-// since built-in Array's are already enumerable.
-SC.mixin(Array.prototype, SC.Array) ;
-SC.Array = SC.mixin({}, SC.Enumerable, SC.Array) ;
-
-// Add any extra methods to SC.Array that are native to the built-in Array.
 /**
-  Returns a new array that is a slice of the receiver.  This implementation
-  uses the observable array methods to retrieve the objects for the new
-  slice.
-
-  If you don't pass in beginIndex and endIndex, it will act as a copy of the
-  array.
-
-  @param beginIndex {Integer} (Optional) index to begin slicing from.
-  @param endIndex {Integer} (Optional) index to end the slice at.
-  @returns {Array} New array with specified slice
-*/
-SC.Array.slice = function(beginIndex, endIndex) {
-  var ret = [];
-  var length = this.get('length') ;
-  if (SC.none(beginIndex)) beginIndex = 0 ;
-  if (SC.none(endIndex) || (endIndex > length)) endIndex = length ;
-  while(beginIndex < endIndex) ret[ret.length] = this.objectAt(beginIndex++) ;
-  return ret ;
-}  ;
+  @namespace
 
-/**
-  Returns the index for a particular object in the index.
+  This module implements Observer-friendly Array-like behavior.  This mixin is
+  picked up by the Array class as well as other controllers, etc. that want to
+  appear to be arrays.
 
-  @param {Object} object the item to search for
-  @param {NUmber} startAt optional starting location to search, default 0
-  @returns {Number} index of -1 if not found
-*/
-SC.Array.indexOf = function(object, startAt) {
-  var idx, len = this.get('length');
+  Unlike SC.Enumerable, this mixin defines methods specifically for
+  collections that provide index-ordered access to their contents.  When you
+  are designing code that needs to accept any kind of Array-like object, you
+  should use these methods instead of Array primitives because these will
+  properly notify observers of changes to the array.
 
-  if (startAt === undefined) startAt = 0;
-  else startAt = (startAt < 0) ? Math.ceil(startAt) : Math.floor(startAt);
-  if (startAt < 0) startAt += len;
+  Although these methods are efficient, they do add a layer of indirection to
+  your application so it is a good idea to use them only when you need the
+  flexibility of using both true JavaScript arrays and "virtual" arrays such
+  as controllers and collections.
 
-  for(idx=startAt;idx<len;idx++) {
-    if (this.objectAt(idx, YES) === object) return idx ;
-  }
-  return -1;
-};
+  You can use the methods defined in this module to access and modify array
+  contents in a KVO-friendly way.  You can also be notified whenever the
+  membership if an array changes by changing the syntax of the property to
+  .observes('*myProperty.[]') .
 
-// Some browsers do not support indexOf natively.  Patch if needed
-if (!Array.prototype.indexOf) Array.prototype.indexOf = SC.Array.indexOf;
+  To support SC.Array in your own class, you must override two
+  primitives to use it: replace() and objectAt().
 
-/**
-  Returns the last index for a particular object in the index.
+  Note that the SC.Array mixin also incorporates the SC.Enumerable mixin.  All
+  SC.Array-like objects are also enumerable.
 
-  @param {Object} object the item to search for
-  @param {NUmber} startAt optional starting location to search, default 0
-  @returns {Number} index of -1 if not found
+  @extends SC.Enumerable
+  @since SproutCore 0.9.0
 */
-SC.Array.lastIndexOf = function(object, startAt) {
-  var idx, len = this.get('length');
-
-  if (startAt === undefined) startAt = len-1;
-  else startAt = (startAt < 0) ? Math.ceil(startAt) : Math.floor(startAt);
-  if (startAt < 0) startAt += len;
-
-  for(idx=startAt;idx>=0;idx--) {
-    if (this.objectAt(idx) === object) return idx ;
-  }
-  return -1;
-};
-
-// Some browsers do not support lastIndexOf natively.  Patch if needed
-if (!Array.prototype.lastIndexOf) {
-  Array.prototype.lastIndexOf = SC.Array.lastIndexOf;
-}
-
-// ......................................................
-// ARRAY SUPPORT
-//
-// Implement the same enhancements on Array.  We use specialized methods
-// because working with arrays are so common.
-(function() {
-  SC.mixin(Array.prototype, {
-
-    // primitive for array support.
-    replace: function(idx, amt, objects) {
-      if (this.isFrozen) { throw SC.FROZEN_ERROR ; }
-
-      var args;
-      var len = objects ? (objects.get ? objects.get('length') : objects.length) : 0;
-
-      // Notify that array content is about to mutate.
-      this.arrayContentWillChange(idx, amt, len);
-
-      if (len === 0) {
-        this.splice(idx, amt) ;
-      } else {
-        args = [idx, amt].concat(objects) ;
-        this.splice.apply(this,args) ;
-      }
-
-      this.arrayContentDidChange(idx, amt, len);
-      this.enumerableContentDidChange(idx, amt, len - amt) ;
-      return this ;
-    },
-
-    // If you ask for an unknown property, then try to collect the value
-    // from member items.
-    unknownProperty: function(key, value) {
-      var ret = this.reducedProperty(key, value) ;
-      if ((value !== undefined) && ret === undefined) {
-        ret = this[key] = value;
-      }
-      return ret ;
-    }
-
-  });
-
-  var indexOf = Array.prototype.indexOf;
-  if (!indexOf || (indexOf === SC.Array.indexOf)) {
-    /**
-      Returns the index for a particular object in the index.
-
-      @param {Object} object the item to search for
-      @param {NUmber} startAt optional starting location to search, default 0
-      @returns {Number} index of -1 if not found
-    */
-    Array.prototype.indexOf = function(object, startAt) {
-      var idx, len = this.length;
-
-      if (startAt === undefined) startAt = 0;
-      else startAt = (startAt < 0) ? Math.ceil(startAt) : Math.floor(startAt);
-      if (startAt < 0) startAt += len;
-
-      for(idx=startAt;idx<len;idx++) {
-        if (this[idx] === object) return idx ;
-      }
-      return -1;
-    } ;
-  }
-
-  var lastIndexOf = Array.prototype.lastIndexOf ;
-  if (!lastIndexOf || (lastIndexOf === SC.Array.lastIndexOf)) {
-    /**
-      Returns the last index for a particular object in the index.
-
-      @param {Object} object the item to search for
-      @param {NUmber} startAt optional starting location to search, default 0
-      @returns {Number} index of -1 if not found
-    */
-    Array.prototype.lastIndexOf = function(object, startAt) {
-      var idx, len = this.length;
-
-      if (startAt === undefined) startAt = len-1;
-      else startAt = (startAt < 0) ? Math.ceil(startAt) : Math.floor(startAt);
-      if (startAt < 0) startAt += len;
-
-      for(idx=startAt;idx>=0;idx--) {
-        if (this[idx] === object) return idx ;
-      }
-      return -1;
-    };
-  }
-
-})();
+SC.Array = SC.mixin({}, SC.Enumerable, SC.CoreArray);