Native/Function.js

   1 /*
   2 Script: Function.js
   3         Contains Function prototypes and utility functions .
   4
   5 License:
   6         MIT-style license.
   7
   8 Credits:
   9         - Some functions are inspired by those found in prototype.js <http://prototype.conio.net/> (c) 2005 Sam Stephenson sam [at] conio [dot] net, MIT-style license
  10 */
  11
  12 /*
  13 Class: Function
  14         A collection of The Function Object prototype methods.
  15 */
  16
  17 Function.extend({
  18
  19         /*
  20         Property: create
  21                 Main function to create closures.
  22
  23         Returns:
  24                 a function.
  25
  26         Arguments:
  27                 options - An Options object.
  28
  29         Options:
  30                 bind - The object that the "this" of the function will refer to. Default is the current function.
  31                 event - If set to true, the function will act as an event listener and receive an event as first argument.
  32                                 If set to a class name, the function will receive a new instance of this class (with the event passed as argument's constructor) as first argument.
  33                                 Default is false.
  34                 arguments - A single argument or array of arguments that will be passed to the function when called.
  35
  36                                         If both the event and arguments options are set, the event is passed as first argument and the arguments array will follow.
  37
  38                                         Default is no custom arguments, the function will receive the standard arguments when called.
  39
  40                 delay - Numeric value: if set, the returned function will delay the actual execution by this amount of milliseconds and return a timer handle when called.
  41                                 Default is no delay.
  42                 periodical - Numeric value: if set, the returned function will periodically perform the actual execution with this specified interval and return a timer handle when called.
  43                                 Default is no periodical execution.
  44                 attempt - If set to true, the returned function will try to execute and return either the results or false on error. Default is false.
  45         */
  46
  47         create: function(options){
  48                 var fn = this;
  49                 options = $merge({
  50                         'bind': fn,
  51                         'event': false,
  52                         'arguments': null,
  53                         'delay': false,
  54                         'periodical': false,
  55                         'attempt': false
  56                 }, options);
  57                 if ($chk(options.arguments) && $type(options.arguments) != 'array') options.arguments = [options.arguments];
  58                 return function(event){
  59                         var args;
  60                         if (options.event){
  61                                 event = event || window.event;
  62                                 args = [(options.event === true) ? event : new options.event(event)];
  63                                 if (options.arguments) args.extend(options.arguments);
  64                         }
  65                         else args = options.arguments || arguments;
  66                         var returns = function(){
  67                                 return fn.apply($pick(options.bind, fn), args);
  68                         };
  69                         if (options.delay) return setTimeout(returns, options.delay);
  70                         if (options.periodical) return setInterval(returns, options.periodical);
  71                         if (options.attempt) try {return returns();} catch(err){return false;};
  72                         return returns();
  73                 };
  74         },
  75
  76         /*
  77         Property: pass
  78                 Shortcut to create closures with arguments and bind.
  79
  80         Returns:
  81                 a function.
  82
  83         Arguments:
  84                 args - the arguments passed. must be an array if arguments > 1
  85                 bind - optional, the object that the "this" of the function will refer to.
  86
  87         Example:
  88                 >myFunction.pass([arg1, arg2], myElement);
  89         */
  90
  91         pass: function(args, bind){
  92                 return this.create({'arguments': args, 'bind': bind});
  93         },
  94
  95         /*
  96         Property: attempt
  97                 Tries to execute the function, returns either the result of the function or false on error.
  98
  99         Arguments:
 100                 args - the arguments passed. must be an array if arguments > 1
 101                 bind - optional, the object that the "this" of the function will refer to.
 102
 103         Example:
 104                 >myFunction.attempt([arg1, arg2], myElement);
 105         */
 106
 107         attempt: function(args, bind){
 108                 return this.create({'arguments': args, 'bind': bind, 'attempt': true})();
 109         },
 110
 111         /*
 112         Property: bind
 113                 method to easily create closures with "this" altered.
 114
 115         Arguments:
 116                 bind - optional, the object that the "this" of the function will refer to.
 117                 args - optional, the arguments passed. must be an array if arguments > 1
 118
 119         Returns:
 120                 a function.
 121
 122         Example:
 123                 >function myFunction(){
 124                 >       this.setStyle('color', 'red');
 125                 >       // note that 'this' here refers to myFunction, not an element
 126                 >       // we'll need to bind this function to the element we want to alter
 127                 >};
 128                 >var myBoundFunction = myFunction.bind(myElement);
 129                 >myBoundFunction(); // this will make the element myElement red.
 130         */
 131
 132         bind: function(bind, args){
 133                 return this.create({'bind': bind, 'arguments': args});
 134         },
 135
 136         /*
 137         Property: bindAsEventListener
 138                 cross browser method to pass event firer
 139
 140         Arguments:
 141                 bind - optional, the object that the "this" of the function will refer to.
 142                 args - optional, the arguments passed. must be an array if arguments > 1
 143
 144         Returns:
 145                 a function with the parameter bind as its "this" and as a pre-passed argument event or window.event, depending on the browser.
 146
 147         Example:
 148                 >function myFunction(event){
 149                 >       alert(event.clientx) //returns the coordinates of the mouse..
 150                 >};
 151                 >myElement.onclick = myFunction.bindAsEventListener(myElement);
 152         */
 153
 154         bindAsEventListener: function(bind, args){
 155                 return this.create({'bind': bind, 'event': true, 'arguments': args});
 156         },
 157
 158         /*
 159         Property: delay
 160                 Delays the execution of a function by a specified duration.
 161
 162         Arguments:
 163                 delay - the duration to wait in milliseconds.
 164                 bind - optional, the object that the "this" of the function will refer to.
 165                 args - optional, the arguments passed. must be an array if arguments > 1
 166
 167         Example:
 168                 >myFunction.delay(50, myElement) //wait 50 milliseconds, then call myFunction and bind myElement to it
 169                 >(function(){alert('one second later...')}).delay(1000); //wait a second and alert
 170         */
 171
 172         delay: function(delay, bind, args){
 173                 return this.create({'delay': delay, 'bind': bind, 'arguments': args})();
 174         },
 175
 176         /*
 177         Property: periodical
 178                 Executes a function in the specified intervals of time
 179
 180         Arguments:
 181                 interval - the duration of the intervals between executions.
 182                 bind - optional, the object that the "this" of the function will refer to.
 183                 args - optional, the arguments passed. must be an array if arguments > 1
 184         */
 185
 186         periodical: function(interval, bind, args){
 187                 return this.create({'periodical': interval, 'bind': bind, 'arguments': args})();
 188         }
 189
 190 });