Skip to content
Browse files

[doc/api] updated docs to reflect the changes to events.js

  • Loading branch information...
1 parent 09c1ccd commit c32263f7e7ba01658747419850bca9563eb86251 hij1nx committed with Aug 1, 2011
Showing with 77 additions and 15 deletions.
  1. +77 −15 doc/api/events.markdown
View
92 doc/api/events.markdown
@@ -12,6 +12,24 @@ Functions can then be attached to objects, to be executed when an event
is emitted. These functions are called _listeners_.
+**Namespaces** with **Wildcards**
+To use namespaces/wildcards, pass the `wildcard` option into the EventEmitter constructor.
+When namespaces/wildcards are enabled, events can either be strings (`foo.bar`) separated
+by a delimiter or arrays (`['foo', 'bar']`). The delimiter is also configurable as a
+constructor option.
+
+An event name passed to any event emitter method can contain a wild card (the `*` character).
+If the event name is a string, a wildcard may appear as `foo.*`. If the event name is an array,
+the wildcard may appear as `['foo', '*']`.
+
+If either of the above described events were passed to the `on` method, subsequent emits such
+as the following would be observed...
+
+
+ emitter.emit(['foo.bazz']);
+ emitter.emit(['foo', 'bar']);
+
+
### events.EventEmitter
To access the EventEmitter class, `require('events').EventEmitter`.
@@ -29,31 +47,63 @@ added.
Adds a listener to the end of the listeners array for the specified event.
+
server.on('connection', function (stream) {
console.log('someone connected!');
});
+
+#### emitter.onAny(listener)
+
+Adds a listener that will be fired when any event is emitted.
+
+ function f(value) {
+ console.log('This event will be listened to exactly four times.');
+ };
+
+ server.onAny(f);
+
+
+#### emitter.unAny(listener)
+
+Removes the listener that will be fired when any event is emitted.
+
+
+ server.unAny(f);
+
+
#### emitter.once(event, listener)
-Adds a **one time** listener for the event. The listener is
-invoked only the first time the event is fired, after which
-it is removed.
+Adds a **one time** listener for the event. The listener is invoked only the first time the event is fired, after which it is removed.
- server.once('connection', function (stream) {
- console.log('Ah, we have our first user!');
+
+ server.once('connection', function (value) {
+ console.log('Ah, we have our first value!');
+ });
+
+
+#### emitter.many(event, timesToListen, listener)
+
+Adds a listener that will execute **n times** for the event before being removed. The listener is invoked only the first time the event is fired, after which it is removed.
+
+
+ server.many('connection', 4, function (value) {
+ console.log('Ah, we have captured a user!');
});
+
#### emitter.removeListener(event, listener)
+#### emitter.un(event, listener)
+
+Remove a listener from the listener array for the specified event. **Caution**: changes array indices in the listener array behind the listener.
-Remove a listener from the listener array for the specified event.
-**Caution**: changes array indices in the listener array behind the listener.
var callback = function(stream) {
console.log('someone connected!');
};
server.on('connection', callback);
// ...
- server.removeListener('connection', callback);
+ server.un('connection', callback);
#### emitter.removeAllListeners([event])
@@ -63,28 +113,40 @@ Removes all listeners, or those of the specified event.
#### emitter.setMaxListeners(n)
-By default EventEmitters will print a warning if more than 10 listeners are
-added to it. This is a useful default which helps finding memory leaks.
-Obviously not all Emitters should be limited to 10. This function allows
-that to be increased. Set to zero for unlimited.
+By default EventEmitters will print a warning if more than 10 listeners are added to it. This is a useful default which helps finding memory leaks. Obviously not all Emitters should be limited to 10. This function allows that to be increased. Set to zero for unlimited.
#### emitter.listeners(event)
-Returns an array of listeners for the specified event. This array can be
-manipulated, e.g. to remove listeners.
+Returns an array of listeners for the specified event. This array can be manipulated, e.g. to remove listeners.
+
server.on('connection', function (stream) {
console.log('someone connected!');
});
+
console.log(util.inspect(server.listeners('connection')); // [ [Function] ]
+
+#### emitter.listenersAny(event)
+
+Returns an array of listeners that are listening for any event that is specified. This array can be manipulated, e.g. to remove listeners.
+
+
+ server.onAny(function(value) {
+ console.log('someone connected!');
+ });
+
+ console.log(console.log(server.listenersAny()[0]); // [ [Function] ] // someone connected!
+
+
#### emitter.emit(event, [arg1], [arg2], [...])
-Execute each of the listeners in order with the supplied arguments.
+Execute each of the listeners that may be listening for the specified event name in order with the list of arguments.
#### Event: 'newListener'
`function (event, listener) { }`
This event is emitted any time someone adds a new listener.
+

0 comments on commit c32263f

Please sign in to comment.
Something went wrong with that request. Please try again.