sproutcore 0.9.0

data/frameworks/sproutcore/foundation/benchmark.js

@@ -0,0 +1,211 @@
+// ========================================================================
+// SproutCore
+// copyright 2006-2007 Sprout Systems, Inc.
+// ========================================================================
+
+require('Core') ;
+require('foundation/date');
+require('foundation/string') ;
+
+/** @namespace SC.Benchmark
+
+  This bit of meta-programming magic can install a benchmark handler on any
+  object method.  When a benchmark is installed, the time required to execute
+  the method will be printed to the console log everytime the method is 
+  called.
+
+  This class can be used to implement benchmarking.  To use this object, just
+  call start() with a key name and end() with a keyname.  The benchmark will 
+  be logged.  If you set verbose = true, then benchmark will log everytime it 
+  saves a bench.  Otherwise, it just keeps stats.  You can get the stats by
+  calling report().
+
+  Benchmark does not require anything other than the date.js class.  It also
+  does not rely on SC.Object so that you can benchmark code in that area as
+  well.
+
+*/
+SC.Benchmark = {
+
+  /**
+    If true, then benchmarks will be logged to the console as they are 
+    recorded.
+  
+    @type bool
+  */
+  verbose: NO,
+  
+  /**
+    If false, benchmarking will be disabled.  You might want to disable this
+    during production to maximize performance.
+  
+    @type bool
+  */
+  enabled: YES,
+  
+/**
+   This hash stores collected stats.  It contains key value pairs.  The value
+   will be a hash with the following properties:
+   
+  * * *runs*: the number of times this stat has run
+  * * *amt*: the total time consumed by this (divide by runs to get avg)
+  * * *name*: an optional longer name you assigned to the stat key.  Set this  using name().
+  * * *_starts*: this array is used internally. 
+*/
+  stats: {},
+
+  /**
+    Call this method at the start of whatever you want to collect.
+    if topLevelOnly is passed, then recursive calls to the start will be 
+    ignored and only the top level call will be benchmarked.
+  */
+  start: function(key, topLevelOnly) {
+    if (!this.enabled) return ;
+    var stat = this._statFor(key) ;
+    
+    if (topLevelOnly && stat._starts.length > 0) {
+      stat._starts.push('ignore') ;
+    } else {
+      stat._starts.push(Date.now()) ;
+    }
+  },
+  
+  /**
+    Call this method at the end of whatever you want to collect.  This will
+    save the collected benchmark.
+  */
+  end: function(key) {
+    if (!this.enabled) return ;
+    var stat = this._statFor(key) ;
+    var start = stat._starts.pop() ;
+    if (!start) {
+      console.log('WARNING: SC.Benchmark "%@" ended without a matching start.  No information was saved.'.fmt(key));
+      return ;
+    }
+
+    // top level only.
+    if (start == 'ignore') return ; 
+    
+    stat.amt += Date.now() - start ;
+    stat.runs++ ;
+    
+    if (this.verbose) this.log(key) ;
+  },
+
+  /**
+    This is a simple way to benchmark a function.  The function will be 
+    run with the name you provide the number of times you indicate.  Only the
+    function is a required param.
+  */  
+  bench: function(func, key, reps) {
+    if (!key) key = "bench%@".fmt(this._benchCount++) ;
+    if (!reps) reps = 1 ;
+    var ret ;
+    
+    while(--reps >= 0) {
+      SC.Benchmark.start(key) ;
+      ret = func();
+      SC.Benchmark.end(key) ; 
+    }
+    
+    return ret ;
+  },
+  
+  /**  
+    This bit of metaprogramming magic install a wrapper around a method and
+    benchmark it whenever it is run.
+  */  
+  install: function(object,method, topLevelOnly) {
+    
+    // vae the original method.
+    var __func = object['b__' + method] = object[method] ;
+    
+    // replace with this helper.
+    object[method] = function() {
+      var key = '%@(%@)'.fmt(method, $A(arguments).join(', ')) ;
+      SC.Benchmark.start(key, topLevelOnly) ;
+      var ret = __func.apply(this, arguments) ;
+      SC.Benchmark.end(key) ;
+      return ret ;
+    } ;
+  },
+  
+  /**
+    Restore the original method, deactivating the benchmark.
+  
+    @param {object} object the object to change
+    @param {string} method the method name as a string.
+  
+  */  
+  restore: function(object,method) {
+    object[method] = object['b__' + method] ;
+  },
+  
+  /**
+    This method will return a string containing a report of the stats
+    collected so far.  If you pass a key, only the stats for that key will
+    be returned.  Otherwise, all keys will be used.
+  */
+  report: function(key) {
+    if (key) return this._genReport(key) ;
+    var ret = [] ;
+    for(var key in this.stats) {
+      if (!this.stats.hasOwnProperty(key)) continue ;
+      ret.push(this._genReport(key)) ;
+    }
+    return ret.join("\n") ;
+  },
+
+  /**
+    This method is just like report() except that it will log the results to
+    the console.
+  */  
+  log: function(key) {
+    console.log(this.report(key)) ;
+  },
+  
+  /**
+    This will activate profiling if you have Firebug installed.  Otherwise
+    does nothing.
+  */
+  startProfile: function(key) {
+    if (!this.enabled) return ;
+    if (console && console.profile) console.profile(key) ;
+  },
+  
+  endProfile: function(key) {
+    if (!this.enabled) return ;
+    if (console && console.profileEnd) console.profileEnd(key) ;
+  },
+  
+  // PRIVATE METHODS
+  
+  _genReport: function(key) {
+    var stat = this._statFor(key) ;
+    var avg = (stat.runs > 0) ? (Math.floor(stat.amt * 1000 / stat.runs) / 1000) : 0 ;
+     
+    return 'BENCH %@ msec: %@ (%@x)'.fmt(avg, (stat.name || key), stat.runs) ;  
+  },
+  
+  // @private
+  // returns a stats hash for the named key.  If the hash does not exist yet,
+  // creates it.
+  _statFor: function(key) {
+    var ret = this.stats[key] ;
+    if (!ret) ret = this.stats[key] = {
+      runs: 0, amt: 0, name: key, _starts: []      
+    };
+    return ret ;
+  },
+  
+  reset: function() { this.stats = {} ; },
+  
+  // This is private, but it is used in some places, so we are keeping this for
+  // compatibility.
+  _bench: function(func, name) {
+    SC.Benchmark.bench(func, name, 1) ;
+  },
+  
+  _benchCount: 1
+  
+} ;

data/frameworks/sproutcore/foundation/binding.js

@@ -0,0 +1,384 @@
+// ========================================================================
+// SproutCore
+// copyright 2006-2007 Sprout Systems, Inc.
+// ========================================================================
+
+require('foundation/object') ;
+
+// A relay simply allows you to connect the properties of two objects. 
+// Whenever the value of one property changes, the value of the other 
+// property will change also.  This allows you to design your system more
+// modular.
+//
+// You can also configure a relay to be one way so only the from -> to path
+// changes are permitted. We will also allow transforms and placeholder values 
+// eventually.
+
+SC.Binding = SC.Object.extend({
+  
+  // ......................................
+  // PROPERTIES
+  // Configure these on setup.  They should be either tuples or property
+  // paths.  The relay will try to observe both of them.
+  from: '', to: '',
+  
+  // set to true if you don't want changes to -> from to relay.
+  oneWay: false,
+  
+  // set this to some value if you want a placeholder when the source
+  // value is an empty array or null (if you don't also set a nullPlaceholder)
+  emptyPlaceholder: null,
+  
+  // set this to some value if you want a placeholder value when the source
+  // value is null.  If you don't set this but you do set an emptyPlaceholder
+  // then the emptyPlaceholder will be used instead.
+  nullPlaceholder: null,
+  
+  // set this to some value if you want a placeholder when the value is 
+  // an array with multiple values.  If you set this, arrays with single
+  // values will be converted to indivdual objects.  If this is set ot null,
+  // multiple values will be allowed to pass untouched.
+  multiplePlaceholder: null,
+  
+  // set this to a function if you want a transform performed on an input
+  // value.  This transform is performed both ways and before placeholder
+  // values are applied.
+  transform: null,
+  
+  // ......................................
+  // METHODS
+  
+  // This will connect the relay so that properties can be forwarded.  If
+  // the items are already connected, this has no effect.
+  connect: function() {
+    if (this._connected) return ;
+    var funcs = this._boundObservers() ;
+    
+    SC.Observers.addObserver(this.get('from'),funcs.from) ;
+    SC.Observers.addObserver(this.get('to'),funcs.to) ;
+    this._connected = true ;
+    return this ;
+  },
+  
+  // this will disconnect the relay from its observing.  Call this if you 
+  // want to destroy the relay. This returns null so you can use it in
+  // assignment.
+  disconnect: function() {  
+    if (!this._connected) return ;
+    var funcs = this._boundObservers() ;
+    SC.Observers.removeObserver(this.get('from'),funcs.from) ;
+    SC.Observers.removeObserver(this.get('to'),funcs.to) ;
+    this._connected = false ;
+    return this ;
+  },
+  
+  // simulate a from -> to relay.
+  relay: function() { 
+    var tuple = SC.Object.tupleForPropertyPath(this.get('from')) ;
+    if (tuple) tuple = this._walkTuple(tuple) ;
+    if (tuple) this._fromObserver(tuple[0],tuple[1],tuple[0].get(tuple[1]));
+  },
+  
+  // ......................................
+  // INTERNAL METHODS
+
+  init: function() {
+    arguments.callee.base.call(this) ;
+    this.connect() ;
+  },
+  
+  _boundObservers: function() {
+    var ret = this._boundObserverFuncs ;
+    if (!ret) {
+      this._boundObserverFuncs = ret = {
+        from: this._fromObserver.bind(this),
+        to: this._toObserver.bind(this)
+      } ;
+    }
+    return ret ;
+  },
+  
+  _fromObserver: function(target,key,value, propertyRevision) {
+    // to avoid echos, check against last toProperty revision.
+    if (propertyRevision <= this._lastFromPropertyRevision) return ;
+    this._lastFromPropertyRevision = propertyRevision ;
+    
+    // no need to forward values if they haven't actually changed.
+    if (!this._didChange(this._lastFromValue,value)) return ;
+    this._lastFromValue = value ;
+    
+    // try to get the to object.
+    var tuple = SC.Object.tupleForPropertyPath(this.get('to')) ;
+    if (tuple) tuple = this._walkTuple(tuple) ;
+    if (tuple) {
+
+      // transform the value
+      var transformFunc = this.transform ;
+      if (transformFunc) value = transformFunc('to', key, value) ;
+      this._lastToValue = value ;
+
+      // apply placeholder settings.
+      var pholder ;
+
+      // handle empty placeholder.
+      if (value && (value == []) && (pholder = this.get('emptyPlaceholder'))) {
+        value = pholder ;
+
+      // handle multiple value placeholder
+      } else if (value && (value instanceof Array) && (pholder = this.get('multiplePlaceholder'))) {
+        value = (value.length == 1) ? value[0] : pholder ;
+      }
+
+      // now handle null placeholder.  This is used if one of these other 
+      // transforms results in a null value.
+      if ((value == null) && (pholder = this.get('nullPlaceholder') || this.get('emptyPlaceholder'))) {
+        value = pholder ;
+      }
+
+      tuple[0].set(tuple[1],value) ;      
+      this._lastToPropertyRevision = tuple[0].propertyRevision ;
+      
+    }
+  },
+
+  _toObserver: function(target,key,value, propertyRevision) {
+    // try to get the to object.
+    if (this.get('oneWay')) return ; // block.
+
+    // to avoid echos, check against last toProperty revision.
+    if (propertyRevision <= this._lastToPropertyRevision) return ;
+    this._lastToPropertyRevision = propertyRevision ;
+    
+    // no need to forward values if they haven't actually changed.
+    if (!this._didChange(this._lastToValue,value)) return ;
+    this._lastToValue = value ;
+    
+    var tuple = SC.Object.tupleForPropertyPath(this.get('from')) ;
+    if (tuple) tuple = this._walkTuple(tuple) ;
+    if (tuple) {
+      // transform the value
+      var transformFunc = this.get('transform') ;
+      if (transformFunc) value = transformFunc('from', key, value) ;
+      this._lastFromValue = value ;
+      
+      // send along to the 'from' source.
+      var result = tuple[0].set(tuple[1],value) ;
+      if (result) this._lastFromPropertyRevision = result.propertyRevision ;
+      
+      // now that it has been set, the FROM object might not allow some 
+      // changes.  If that is the case, then we need to set this back on the
+      // sender.
+      if (result != value) {
+        target.set(key,result) ;
+        this._lastToPropertyRevision = target.propertyRevision ;
+      }
+      
+    } 
+  },
+  
+  _didChange: function(lastValue, newValue) {
+    if (newValue && lastValue) {
+      if (typeof(newValue) == typeof(lastValue)) {
+        if (lastValue == newValue) return false ;
+      }
+    } else if (((newValue === null) && (lastValue === null)) || ((newValue === undefined) && (lastValue === undefined))) return false ;
+    return true ;
+  },
+  
+  _lastToPropertyRevision: 0,
+  _lastFromPropertyRevision: 0,
+  
+  _walkTuple: function(tuple) {
+    var parts = tuple[1].split('.') ;
+    if (parts.length > 1) {
+      tuple = tuple.slice() ; // duplicate to avoid an error.
+      var obj = tuple[0] ;
+      tuple[1] = parts.pop() ;
+      for(var loc=0;(obj && (loc<parts.length));loc++) {
+        obj = obj.get(parts[loc]) ;
+      }
+      tuple[0] = obj ;
+    }
+    return (tuple[0] && tuple[1]) ? tuple : null ;
+  }
+  
+}) ;
+
+SC.Binding.mixin({
+  // Constant values for placeholders
+  MULTIPLE_PLACEHOLDER: '@@MULT@@',
+  NULL_PLACEHOLDER: '@@NULL@@',
+  EMPTY_PLACEHOLDER: '@@EMPTY@@'
+}) ;
+
+// This is the basic method you can use to create a builder function for
+// different types of relays.  The first param is either a string or a set
+// of properties.  The second param is a set of properties.  Both are opt.
+SC.Binding.From = function(from,opts) {
+  if (!opts) opts = {} ;
+  if ((typeof(from) == "string") || (from instanceof Array)) {
+    opts.from = from ;
+  } else Object.extend(opts,from) ;
+  var ret = SC.Binding.extend(opts) ; 
+  return ret ;
+} ;
+
+SC.Binding.build = function(tr) {
+  return function(from) { 
+    return SC.Binding.From(from,{ transform: tr }) ; 
+  } ;
+} ; 
+
+SC.Binding.NoChange = SC.Binding.From;
+
+// This binding will return errors as null.
+SC.Binding.NoError = SC.Binding.build(function(dir, key, value) {
+  return ($type(value) == T_ERROR) ? null : value ;  
+}) ;
+
+SC.Binding.NoError.ext = function(bindFunc) {
+  return function(d,k,v) {
+    return ($type(value) == T_ERROR) ? null : bindFunc(d,k,v) ;  
+  } ;
+} ;
+
+// This binding only allows single, null, or error values.  If an array is 
+// passed, it will be mapped like so:
+//
+// [] => null
+// [x] => x
+// [x,x,x] => MULTIPLE_PLACEHOLDER
+//
+SC.Binding.Single = SC.Binding.build(function(d,k,v) {
+  if ($type(v) == T_ARRAY) {
+    switch(v.length) {
+      case 0:
+        v = null ;
+        break ;
+      case 1:
+        v = v[0] ;
+        break ;
+      default:
+        v = SC.Binding.MULTIPLE_PLACEHOLDER ;
+    }
+  }
+  return v;
+});
+
+// This binding works just like Single except if you pass a multiple value
+// it will be converted to NULL.
+SC.Binding.SingleNull = SC.Binding.build(function(d,k,v) {
+  if ($type(v) == T_ARRAY) {
+    switch(v.length) {
+      case 0:
+        v = null ;
+        break ;
+      case 1:
+        v = v[0] ;
+        break ;
+      default:
+        v = null ;
+    }
+  }
+  return v;
+});
+
+// NoError versions.
+SC.Binding.SingleNoError = SC.Binding.NoError.ext(SC.Binding.Single);
+SC.Binding.SingleNullNoError = SC.Binding.NoError.ext(SC.Binding.SingleNull);
+
+// This requires the value to be a multiple.  null => [], x => [x]
+SC.Binding.Multiple = SC.Binding.build(function(d,k,v) {
+  var t = $type(v) ;
+  if (t != T_ARRAY) {
+    if (t == null) {
+      v = [] ;
+    } else if (t != T_ERROR) {
+      v = [v] ;
+    }
+  }
+  return v ;
+}) ;
+
+SC.Binding.MultipleNoError = SC.Binding.NoError.ext(SC.Binding.Multiple);
+
+// Converts value to a bool.  true if: not null, not empty array, not 0, '',
+// etc.
+SC.Binding.Bool = SC.Binding.build(function(d,k,v) {
+  return ($type(v) == T_ARRAY) ? (t.length > 0) : !!v ;
+}) ;
+
+// Converts value to a bool, but its only true if not null
+SC.Binding.NotNull = SC.Binding.build(function(d,k,v) { 
+  return (v != null) ;
+}) ;
+
+// Converts inverse of bool.
+SC.Binding.Not = SC.Binding.build(function(d,k,v) {
+  return !(($type(v) == T_ARRAY) ? (t.length > 0) : !!v) ;
+}) ;
+
+// Converts value to a bool, but its only true if not null
+SC.Binding.IsNull = SC.Binding.build(function(d,k,v) {
+  return (v == null) ;
+}) ;
+
+// No Error versions.
+SC.Binding.BoolNoError = SC.Binding.NoError.ext(SC.Binding.Bool) ;
+SC.Binding.NotNullNoError = SC.Binding.NoError.ext(SC.Binding.NotNull) ;
+SC.Binding.NotNoError = SC.Binding.NoError.ext(SC.Binding.Not) ;
+SC.Binding.IsNullNoError = SC.Binding.NoError.ext(SC.Binding.IsNull) ;
+
+// .........................................................
+// DEPRECATED
+
+// This relay forces all values to be multiple values
+SC.Binding.Multiple = function(from) {
+  return SC.Binding.From(from,{
+    transform: function(dir,key,value) { 
+      return (value) ? (SC.isArray(value) ? value : [value]) : value;
+    }
+  }) ;
+} ;
+
+// This relay forces all values to be multiple values, null values are not
+// allowed.
+SC.Binding.MultipleNotEmpty = function(from) {
+  return SC.Binding.From(from,{
+    transform: function(dir,key,value) { 
+      return (value) ? (SC.isArray(value) ? value : [value]) : [];
+    }
+  }) ;
+} ;
+
+// This relay allows single values and no null/empty values.
+SC.Binding.SingleNotEmpty = function(from) {
+  return SC.Binding.From(from,{
+    multiplePlaceholder: SC.Binding.MULTIPLE_PLACEHOLDER,
+    emptyPlaceholder: SC.Binding.EMPTY_PLACEHOLDER,
+    nullPlaceholder: SC.Binding.NULL_PLACEHOLDER
+  }) ;
+} ;
+
+// This relay allows any values, but only one way flow.
+SC.Binding.OneWay = function(from) {
+  return SC.Binding.From(from, { oneWay: true }) ;
+} ;
+
+// This relay forces the value to be true or false.  Empty and null values
+// represent false.
+SC.Binding.Flag = function(from) {
+  return SC.Binding.From(from, { 
+    transform: function(dir,key,value) {
+      return (value && (value instanceof Array)) ? (value.length == 0) : !!value ;
+    }
+  }) ;
+} ;
+
+SC.Binding.OneWayFlag = function(from) {
+  var ret = SC.Binding.Flag(from) ;
+  ret.oneWay = true ;
+  return ret ;  
+} ;
+
+