The Tor Browser / file comparison
comparison: addon-sdk/source/lib/method/Readme.md
addon-sdk/source/lib/method/Readme.md
- branch
- TOR_BUG_9701
- changeset 15
- b8a032363ba2
equal
deleted
inserted
replaced
| -1:000000000000 | 0:7124d2924163 |
|---|---|
| 1 # method | |
| 2 | |
| 3 [](http://travis-ci.org/Gozala/method) | |
| 4 | |
| 5 Library provides an API for defining polymorphic methods that dispatch on the | |
| 6 first argument type. This provides a powerful way for decouple abstraction | |
| 7 interface definition from an actual implementation per type, without risks | |
| 8 of interference with other libraries. | |
| 9 | |
| 10 ### Motivation | |
| 11 | |
| 12 - Provide a high-performance, dynamic polymorphism construct as an | |
| 13 alternative to existing object methods that does not provides any | |
| 14 mechanics for guarding against name conflicts. | |
| 15 - Allow independent extension of types, and implementations of methods | |
| 16 on types, by different parties. | |
| 17 | |
| 18 ## Install | |
| 19 | |
| 20 npm install method | |
| 21 | |
| 22 ## Use | |
| 23 | |
| 24 ```js | |
| 25 var method = require("method") | |
| 26 | |
| 27 // Define `isWatchable` method that can be implemented for any type. | |
| 28 var isWatchable = method("isWatchable") | |
| 29 | |
| 30 // If you call it on any object it will | |
| 31 // throw as nothing implements that method yet. | |
| 32 //isWatchable({}) // => Exception: method is not implemented | |
| 33 | |
| 34 // If you define private method on `Object.prototype` | |
| 35 // all objects will inherit it. | |
| 36 Object.prototype[isWatchable] = function() { | |
| 37 return false; | |
| 38 } | |
| 39 | |
| 40 isWatchable({}) // => false | |
| 41 | |
| 42 | |
| 43 // Although `isWatchable` property above will be enumerable and there for | |
| 44 // may damage some assumbtions made by other libraries. There for it"s | |
| 45 // recomended to use built-in helpers methods that will define extension | |
| 46 // without breaking assumbtions made by other libraries: | |
| 47 | |
| 48 isWatchable.define(Object, function() { return false }) | |
| 49 | |
| 50 | |
| 51 // There are primitive types in JS that won"t inherit methods from Object: | |
| 52 isWatchable(null) // => Exception: method is not implemented | |
| 53 | |
| 54 // One could either implement methods for such types: | |
| 55 isWatchable.define(null, function() { return false }) | |
| 56 isWatchable.define(undefined, function() { return false }) | |
| 57 | |
| 58 // Or simply define default implementation: | |
| 59 isWatchable.define(function() { return false }) | |
| 60 | |
| 61 // Alternatively default implementation may be provided at creation: | |
| 62 isWatchable = method(function() { return false }) | |
| 63 | |
| 64 // Method dispatches on an first argument type. That allows us to create | |
| 65 // new types with an alternative implementations: | |
| 66 function Watchable() {} | |
| 67 isWatchable.define(Watchable, function() { return true }) | |
| 68 | |
| 69 // This will make all `Watchable` instances watchable! | |
| 70 isWatchable(new Watchable()) // => true | |
| 71 | |
| 72 // Arbitrary objects can also be extended to implement given method. For example | |
| 73 // any object can simply made watchable: | |
| 74 function watchable(object) { | |
| 75 return isWatchable.implement(objct, function() { return true }) | |
| 76 } | |
| 77 | |
| 78 isWatchable(watchable({})) // => true | |
| 79 | |
| 80 // Full protocols can be defined with such methods: | |
| 81 var observers = "observers@" + module.filename | |
| 82 var watchers = method("watchers") | |
| 83 var watch = method("watch") | |
| 84 var unwatch = method("unwatch") | |
| 85 | |
| 86 watchers.define(Watchable, function(target) { | |
| 87 return target[observers] || (target[observers] = []) | |
| 88 }) | |
| 89 | |
| 90 watch.define(Watchable, function(target, watcher) { | |
| 91 var observers = watchers(target) | |
| 92 if (observers.indexOf(watcher) < 0) observers.push(watcher) | |
| 93 return target | |
| 94 }) | |
| 95 unwatch.define(Watchable, function(target, watcher) { | |
| 96 var observers = watchers(target) | |
| 97 var index = observers.indexOf(watcher) | |
| 98 if (observers.indexOf(watcher) >= 0) observers.unshift(watcher) | |
| 99 return target | |
| 100 }) | |
| 101 | |
| 102 // Define type Port that inherits form Watchable | |
| 103 | |
| 104 function Port() {} | |
| 105 Port.prototype = Object.create(Watchable.prototype) | |
| 106 | |
| 107 var emit = method("emit") | |
| 108 emit.define(Port, function(port, message) { | |
| 109 watchers(port).slice().forEach(function(watcher) { | |
| 110 watcher(message) | |
| 111 }) | |
| 112 }) | |
| 113 | |
| 114 var p = new Port() | |
| 115 watch(p, console.log) | |
| 116 emit(p, "hello world") // => info: "hello world" | |
| 117 ``` |
