sproutit-sproutcore 1.0.0.20090407205609 → 1.0.0.20090408130025

data/frameworks/sproutcore/frameworks/foundation/system/benchmark.js

@@ -0,0 +1,244 @@
+// ==========================================================================
+// Project:   SproutCore - JavaScript Application Framework
+// Copyright: ©2006-2009 Sprout Systems, Inc. and contributors.
+//            Portions ©2008-2009 Apple, Inc. All rights reserved.
+// License:   Licened under MIT license (see license.js)
+// ==========================================================================
+
+/** @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.
+    
+    @param key {String} A unique key that identifies this benchmark.  All calls to start/end with the same key will be groups together.
+    @param topLevelOnly {Boolean} If true then recursive calls to this method with the same key will be ignored.  
+    @param time {Integer} Only pass if you want to explicitly set the start time.  Otherwise the start time is now.
+  */
+  start: function(key, topLevelOnly, time) {
+    if (!this.enabled) return ;
+    var stat = this._statFor(key) ;
+    
+    if (topLevelOnly && stat._starts.length > 0) {
+      stat._starts.push('ignore') ;
+    } else {
+      stat._starts.push(time || Date.now()) ;
+    }
+  },
+  
+  /**
+    Call this method at the end of whatever you want to collect.  This will
+    save the collected benchmark.
+    
+    @param key {String} The benchmark key you used when you called start()
+    @param time {Integer} Only pass if you want to explicitly set the end time.  Otherwise start time is now.
+  */
+  end: function(key, time, runs) {
+    if (!this.enabled) return ;
+    var stat = this._statFor(key) ;
+    var start = stat._starts.pop() ;
+    if (!start) {
+      console.log('SC.Benchmark "%@" ended without a matching start.  No information was saved.'.fmt(key));
+      return ;
+    }
+
+    // top level only.
+    if (start == 'ignore') return ; 
+    
+    stat.amt += (time || Date.now()) - start ;
+    stat.runs += (runs || 1) ;
+    
+    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, context) {
+    if (!key) key = "bench%@".fmt(this._benchCount++) ;
+    if (!reps) reps = 1 ;
+    var ret ;
+    
+    var runs = reps; 
+    SC.Benchmark.start(key) ;
+    while(--reps >= 0) {
+      ret = func(context);
+    }
+    SC.Benchmark.end(key, null, runs) ; 
+    
+    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, SC.$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 = [] ;
+    
+    // find the longest stat name...
+    var maxLen = 0 ;
+    for(key in this.stats) {
+      if (!this.stats.hasOwnProperty(key)) continue ;
+      if (key.length > maxLen) maxLen = key.length;
+    }
+    
+    // now gen report...
+    var keys = [] ;
+    for(key in this.stats) {
+      if (!this.stats.hasOwnProperty(key)) continue ;
+      keys.push(key) ;
+    }
+    keys = keys.sort() ;
+    var idx, max = keys.length ;
+    for(idx=0;idx<max;idx++) {
+      ret.push(this._genReport(keys[idx], maxLen)) ;
+    }
+    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, nameLength) {
+    var stat = this._statFor(key) ;
+    var avg = (stat.runs > 0) ? (Math.floor(stat.amt * 100000 / stat.runs) / 100000) : 0 ;
+     
+    // Generate the name, adding padding spaces if needed.
+    var name = (stat.name || key)  ;
+    nameLength = (nameLength) ? nameLength : 0; 
+    if (nameLength > name.length) {
+      var toJoin = [name] ;
+      nameLength -= name.length ;
+      while(--nameLength >= 0) toJoin.push(' ') ;
+      name = toJoin.join('') ;
+    }
+    
+    return 'BENCH | %@1 | avg: %@4 msec | total: %@2 msec | reps: %@3x '.fmt(name, stat.amt, stat.runs, avg) ;  
+  },
+  
+  // @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 = {} ;  /*debugger;*/},
+  
+  // 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/frameworks/foundation/system/browser.js

@@ -0,0 +1,64 @@
+// ==========================================================================
+// Project:   SproutCore - JavaScript Application Framework
+// Copyright: ©2006-2009 Sprout Systems, Inc. and contributors.
+//            Portions ©2008-2009 Apple, Inc. All rights reserved.
+// License:   Licened under MIT license (see license.js)
+// ==========================================================================
+
+/** Detects the current browser type. Borrowed from jQuery + prototype */
+SC.browser = (function() {
+  
+  var userAgent = navigator.userAgent.toLowerCase();
+  var version = (userAgent.match( /.+(?:rv|it|ra|ie)[\/: ]([\d.]+)/ ) || [])[1] ;
+
+  var browser = /** @scope SC.browser */ {
+    
+    /** The current browser version */
+    version: version,
+    
+    /** non-zero if webkit-based browser */
+    safari: (/webkit/).test( userAgent ) ? version : 0,
+    
+    /** non-zero if this is an opera-based browser */
+    opera: (/opera/).test( userAgent ) ? version : 0,
+    
+    /** non-zero if this is IE */
+    msie: (/msie/).test( userAgent ) && !(/opera/).test( userAgent ) ? version : 0,
+    
+    /** non-zero if this is a miozilla based browser */
+    mozilla: (/mozilla/).test( userAgent ) && !(/(compatible|webkit)/).test( userAgent ) ? version : 0,
+    
+    /** non-zero if this is mobile safari */
+    mobileSafari: (/apple.*mobile.*safari/).test(userAgent) ? version : 0,
+    
+    /** non-zero if we are on windows */
+    windows: !!(/(windows)/).test(userAgent),
+    
+    /** non-zero if we are on a mac */
+    mac: !!((/(macintosh)/).test(userAgent) || (/(mac os x)/).test(userAgent)),
+    
+    language: ((navigator.language || navigator.browserLanguage).split('-', 1)[0])
+  };
+  
+  // Add more SC-like descriptions...
+  SC.extend(browser, /** @scope SC.browser */ {
+    
+    isOpera: !!browser.opera,
+    isIe: !!browser.msie,
+    isIE: !!browser.msie,
+    isSafari: !!browser.safari,
+    isMobileSafari: !!browser.mobileSafari,
+    isMozilla: !!browser.mozilla,
+    isWindows: !!browser.windows,
+    isMac: !!browser.mac,
+
+    /**
+      The current browser name.  This is useful for switch statements. */
+    current: (browser.msie) ? 'msie' : (browser.mozilla) ? 'mozilla' : (browser.safari) ? 'safari' : (browser.opera) ? 'opera' : 'unknown'
+    
+  }) ;
+  
+  return browser ;
+
+})();
+

data/frameworks/sproutcore/frameworks/foundation/system/builder.js

@@ -0,0 +1,210 @@
+// ==========================================================================
+// Project:   SproutCore - JavaScript Application Framework
+// Copyright: ©2006-2009 Sprout Systems, Inc. and contributors.
+//            Portions ©2008-2009 Apple, Inc. All rights reserved.
+// License:   Licened under MIT license (see license.js)
+// ==========================================================================
+
+/** @class
+
+  The Builder class makes it easy to create new chained-builder API's such as
+  those provided by CoreQuery or jQuery.  Usually you will not create a new
+  builder yourself, but you will often use instances of the Builder object to
+  configure parts of the UI such as menus and views.
+  
+  h1. Anatomy of a Builder
+  
+  You can create a new Builder much like you would any other class in 
+  SproutCore.  For example, you could create a new CoreQuery-type object with
+  the following:
+  
+  {{{
+    SC.$ = SC.Builder.create({
+      // methods you can call go here.
+    });
+  }}}
+  
+  Unlike most classes in SproutCore, Builder objects are actually functions 
+  that you can call to create new instances.  In the example above, to use 
+  the builder, you must call it like a function:
+  
+  {{{
+    buildit = SC.$();
+  }}}
+  
+  If you define an init() method on a builder, it will be invoked wheneve the
+  builder is called as a function, including any passed params.  Your init()
+  method MUST return this, unlike regular SC objects.  i.e.
+  
+  {{{
+    SC.$ = SC.Builder.create({
+      init: function(args) { 
+        this.args = SC.A(args);
+        return this;
+      }
+    });
+    
+    buildit = SC.$('a', 'b');
+    buildit.args => ['a','b']
+  }}}
+  
+  In addition to defining a function like this, all builder objects also have
+  an 'fn' property that contains a hash of all of the helper methods defined
+  on the builder function.  Once a builder has been created, you can add 
+  addition "plugins" for the builder by simply adding new methods to the
+  fn property.
+  
+  h1. Writing Builder Functions
+  
+  All builders share a few things in comming:
+  
+  - when a new builder is created, it's init() method will be called.  The default version of this method simply copies the passed parameters into the builder as content, but you can override this with anything you want.
+  
+  - the content the builder works on is stored as indexed properties (i.e. 0,1,2,3, like an array).  The builder should also have a length property if you want it treated like an array.
+    
+  - Builders also maintain a stack of previous builder instances which you can pop off at any time.
+    
+  To get content back out of a builder once you are ready with it, you can
+  call the method done().  This will return an array or a single object, if 
+  the builder only works on a single item.
+  
+  You should write your methods using the getEach() iterator to work on your
+  member objects.  All builders implement SC.Enumerable in the fn() method.
+
+  CoreQuery = SC.Builder.create({
+    ...
+  }) ;
+  
+  CoreQuery = new SC.Builder(properties) {
+    
+  } ;
+
+  CoreQuery2 = CoreQuery.extend() {
+  }
+  
+  @constructor
+*/
+SC.Builder = function (props) { return SC.Builder.create(props); };
+
+/** 
+  Create a new builder object, applying the passed properties to the 
+  builder's fn property hash.
+  
+  @param {Hash} properties
+  @returns {SC.Builder}
+*/
+SC.Builder.create = function create(props) { 
+  
+  // generate new fn with built-in properties and copy props
+  var fn = SC.mixin(SC.beget(this.fn), props||{}) ;
+  if (props.hasOwnProperty('toString')) fn.toString = props.toString;
+  
+  // generate new constructor and hook in the fn
+  var construct = function() {
+    var ret = SC.beget(fn); // NOTE: using closure here...
+    
+    // the defaultClass is usually this for this constructor. 
+    // e.g. SC.View.build() -> this = SC.View
+    ret.defaultClass = this ;
+    ret.constructor = construct ;
+
+    // now init the builder object.
+    return ret.init.apply(ret, arguments) ;
+  } ;
+  construct.fn = construct.prototype = fn ;
+
+  // the create() method can be used to extend a new builder.
+  // eg. SC.View.buildCustom = SC.View.build.extend({ ...props... })
+  construct.extend = SC.Builder.create ;
+  construct.mixin = SC.Builder.mixin ;
+  
+  return construct; // return new constructor
+} ;
+
+SC.Builder.mixin = function() {
+  var len = arguments.length, idx;
+  for(idx=0;idx<len;idx++) SC.mixin(this, arguments[idx]);
+  return this ;
+};
+
+/** This is the default set of helper methods defined for new builders. */
+SC.Builder.fn = {
+
+  /** 
+    Default init method for builders.  This method accepts either a single
+    content object or an array of content objects and copies them onto the 
+    receiver.  You can override this to provide any kind of init behavior 
+    that you want.  Any parameters passed to the builder method will be 
+    forwarded to your init method.
+    
+    @returns {SC.Builder} receiver
+  */
+  init: function(content) {
+    if (content !== undefined) {
+      if (SC.typeOf(content) === SC.T_ARRAY) {
+        var loc=content.length;
+        while(--loc >= 0) {
+          this[loc] = content.objectAt ? content.objectAt(loc) : content[loc];
+        }
+        this.length = content.length ;
+      } else {
+        this[0] = content; this.length=1;
+      }
+    }
+    return this ;
+  },
+  
+  /** Return the number of elements in the matched set. */
+  size: function() { return this.length; },
+  
+  /** 
+    Take an array of elements and push it onto the stack (making it the
+    new matched set.)  The receiver will be saved so it can be popped later.
+    
+    @param {Object|Array} content
+    @returns {SC.Builder} new isntance
+  */
+  pushStack: function() {
+    // Build a new CoreQuery matched element set
+    var ret = this.constructor.apply(this,arguments);
+
+    // Add the old object onto the stack (as a reference)
+    ret.prevObject = this;
+
+    // Return the newly-formed element set
+    return ret;
+  },
+
+  /**
+    Returns the previous object on the stack so you can continue with that
+    transform.  If there is no previous item on the stack, an empty set will
+    be returned.
+  */
+  end: function() { 
+    return this.prevObject || this.constructor(); 
+  },
+  
+  // toString describes the builder
+  toString: function() { 
+    return "%@$(%@)".fmt(this.defaultClass.toString(), 
+      SC.A(this).invoke('toString').join(',')); 
+  },
+  
+  /** You can enhance the fn using this mixin method. */
+  mixin: SC.Builder.mixin
+  
+};
+
+// Apply SC.Enumerable.  Whenever possible we want to use the Array version
+// because it might be native code.
+(function() {
+  var enumerable = SC.Enumerable, fn = SC.Builder.fn, key, value ;
+  for(key in enumerable) {
+    if (!enumerable.hasOwnProperty(key)) continue ;
+    value = Array.prototype[key] || enumerable[key];
+    fn[key] = value ;
+  }
+})();
+
+
+