Skip to content

Commit 0118b27

Browse files
author
Dan Burzo
committed
Added some documentation around eventsplitter/eventnamespace
1 parent 66f2716 commit 0118b27

File tree

3 files changed

+256
-216
lines changed

3 files changed

+256
-216
lines changed

‎docs/pubsub.html‎

Lines changed: 128 additions & 96 deletions
Original file line numberDiff line numberDiff line change
@@ -27,9 +27,9 @@ <h1>pubsub.js</h1>
2727
<div class="pilwrap ">
2828
<a class="pilcrow" href="#section-1">&#182;</a>
2929
</div>
30-
<pre><code> pubsub (c) <span class="number">2013</span> Dan Burzo
31-
pubsub can be freely distributed under the MIT license.</code></pre>
32-
<p>Made by <a href="https://twitter.com/danburzo">@danburzo</a>.</p>
30+
<p> pubsub (c) 2013 Dan Burzo
31+
pubsub can be freely distributed under the MIT license.
32+
Made by <a href="https://twitter.com/danburzo">@danburzo</a>.</p>
3333
<p>Fork &amp; contribute at <a href="https://github.com/danburzo/pubsub">github.com/danburzo/pubsub</a>. </p>
3434
<p>Download <a href="https://github.com/danburzo/pubsub/zipball/master">zip</a>, <a href="https://github.com/danburzo/pubsub/tarball/master">tar</a>. </p>
3535
<p>The guiding principles were: speed, terseness and progressive disclosure.</p>
@@ -51,79 +51,69 @@ <h2>Annotated API</h2>
5151
</div>
5252

5353
<div class="content"><div class='highlight'><pre>(<span class="keyword">function</span>() {
54-
<span class="keyword">var</span> root = <span class="keyword">this</span>;
54+
<span class="keyword">var</span> root = <span class="keyword">this</span>;
5555

56-
<span class="keyword">var</span> pubsub = root.pubsub = <span class="keyword">function</span>(options) {
57-
<span class="keyword">this</span>.options = options;
58-
<span class="keyword">this</span>._pubsubEvents = {};
59-
<span class="keyword">this</span>._pubsubHappened = {};
60-
};
61-
62-
<span class="keyword">var</span> prototype = {</pre></div></div>
56+
<span class="keyword">var</span> pubsub = root.pubsub = <span class="keyword">function</span>(options) {
57+
<span class="keyword">this</span>.options = options;
58+
<span class="keyword">this</span>._pubsubEvents = {};
59+
<span class="keyword">this</span>._pubsubHappened = {};
60+
};</pre></div></div>
6361

6462
</li>
6563

6664

6765
<li id="section-3">
6866
<div class="annotation">
6967

70-
<div class="pilwrap for-h3">
68+
<div class="pilwrap ">
7169
<a class="pilcrow" href="#section-3">&#182;</a>
7270
</div>
73-
<h3>pubsub.pub</h3>
74-
<p>Publish an event.</p>
75-
<ul>
76-
<li><strong>pub(event, [arg1, [arg2 …]])</strong><ul>
77-
<li><em>event</em> the event to trigger;</li>
78-
<li><em>arg1 … argN</em> (optional) any number of additional params to pass to the event subscribers.</li>
79-
</ul>
80-
</li>
81-
</ul>
71+
<p>Current version of the <code>pubsub</code>, using <a href="http://semver.org/">semantic versioning</a>.</p>
8272

8373
</div>
8474

85-
<div class="content"><div class='highlight'><pre> pub: <span class="keyword">function</span>(eventString) {
86-
<span class="keyword">var</span> eventComponents = <span class="keyword">this</span>.eventNamespace(eventString);
87-
<span class="keyword">var</span> eventArray, i, ilen, j, jlen, args, subscriber, ret, event;
88-
<span class="keyword">for</span> (i = <span class="number">0</span>, ilen = eventComponents.length; i &lt; ilen; i++) {
89-
eventArray = <span class="keyword">this</span>._pubsubEvents[event = eventComponents[i]] || [];
90-
args = Array.prototype.slice.call(arguments, <span class="number">1</span>);
91-
<span class="keyword">for</span> (j = <span class="number">0</span>, jlen = eventArray.length; j &lt; jlen; j++) {
92-
subscriber = eventArray[j];
93-
ret = subscriber[<span class="number">0</span>].apply(subscriber[<span class="number">1</span>] || <span class="keyword">this</span>, args);
94-
<span class="keyword">if</span> (subscriber[<span class="number">2</span>] &amp;&amp; ret !== <span class="literal">false</span>) {
95-
<span class="keyword">this</span>.unsub(event, subscriber[<span class="number">0</span>]);
96-
}
97-
}
98-
<span class="keyword">this</span>._pubsubHappened[event] = args;
99-
}
100-
<span class="keyword">return</span> <span class="keyword">this</span>;
101-
},</pre></div></div>
75+
<div class="content"><div class='highlight'><pre> pubsub.version = <span class="string">'0.1.0'</span>;
76+
77+
<span class="keyword">var</span> prototype = {</pre></div></div>
10278

10379
</li>
10480

10581

10682
<li id="section-4">
10783
<div class="annotation">
10884

109-
<div class="pilwrap ">
85+
<div class="pilwrap for-h3">
11086
<a class="pilcrow" href="#section-4">&#182;</a>
11187
</div>
112-
<p>Parses the namespaced event string to identify its components.</p>
88+
<h3>pubsub.pub</h3>
89+
<p>Publish an event.</p>
90+
<ul>
91+
<li><strong>pub(event, [arg1, [arg2 …]])</strong><ul>
92+
<li><em>event</em> the event to trigger;</li>
93+
<li><em>arg1 … argN</em> (optional) any number of additional params to pass to the event subscribers.</li>
94+
</ul>
95+
</li>
96+
</ul>
11397

11498
</div>
11599

116-
<div class="content"><div class='highlight'><pre> eventNamespace: <span class="keyword">function</span>(eventString) {
117-
<span class="keyword">var</span> events = [], str = <span class="string">''</span>, ch, i;
118-
<span class="keyword">for</span> (i = <span class="number">0</span>; i &lt; eventString.length; i++) {
119-
<span class="keyword">if</span> ((ch = eventString.charAt(i)) === <span class="string">':'</span>) {
120-
events.push(str);
100+
<div class="content"><div class='highlight'><pre> pub: <span class="keyword">function</span>(eventString) {
101+
<span class="keyword">var</span> eventComponents = <span class="keyword">this</span>.eventNamespace(eventString);
102+
<span class="keyword">var</span> eventArray, i, ilen, j, jlen, args, subscriber, ret, event;
103+
<span class="keyword">for</span> (i = <span class="number">0</span>, ilen = eventComponents.length; i &lt; ilen; i++) {
104+
eventArray = <span class="keyword">this</span>._pubsubEvents[event = eventComponents[i]] || [];
105+
args = Array.prototype.slice.call(arguments, <span class="number">1</span>);
106+
<span class="keyword">for</span> (j = <span class="number">0</span>, jlen = eventArray.length; j &lt; jlen; j++) {
107+
subscriber = eventArray[j];
108+
ret = subscriber[<span class="number">0</span>].apply(subscriber[<span class="number">1</span>] || <span class="keyword">this</span>, args);
109+
<span class="keyword">if</span> (subscriber[<span class="number">2</span>] &amp;&amp; ret !== <span class="literal">false</span>) {
110+
<span class="keyword">this</span>.unsub(event, subscriber[<span class="number">0</span>]);
121111
}
122-
str += ch;
123112
}
124-
events.push(str);
125-
<span class="keyword">return</span> events;
126-
},</pre></div></div>
113+
<span class="keyword">this</span>._pubsubHappened[event] = args;
114+
}
115+
<span class="keyword">return</span> <span class="keyword">this</span>;
116+
},</pre></div></div>
127117

128118
</li>
129119

@@ -142,38 +132,36 @@ <h3>pubsub.sub</h3>
142132
<li><em>method</em> the function to subscribe to the events;</li>
143133
<li><em>thisArg</em> (optional) context for the method;</li>
144134
<li><em>flags</em> (optional) boleans to configure the subscribers&#39;s behavior:<ul>
145-
<li><em>once</em> if true, the subscriber will self-unsubscribe after the first successful execution. You&#39;ll usually use <em>PubSub.once()</em> for this;</li>
146-
<li><em>recoup</em> if true, the subscriber will execute immediately if the event it subscribes to already happened. You&#39;ll usually use <em>PubSub.recoup()</em> for this.</li>
135+
<li><em>once</em> if true, the subscriber will self-unsubscribe after the first successful execution. Use <em>pubsub.once()</em> for clarity;</li>
136+
<li><em>recoup</em> if true, the subscriber will execute immediately if the event it subscribes to already happened. Use <em>pubsub.recoup()</em> for clarity.</li>
147137
</ul>
148138
</li>
149139
</ul>
150140
</li>
151141
</ul>
152-
<p><em>Careful!</em> When subscribing a method to multiple events, if the events don‘t get published
153-
with compatible parameters, you can end up with weird behavior. To avoid this, it’s best to
154-
keep a common interface for all events in the list.</p>
142+
<p><em>Note:</em> When subscribing to multiple events, make sure these events are published with the same (or similar) list of arguments.</p>
155143

156144
</div>
157145

158-
<div class="content"><div class='highlight'><pre> sub: <span class="keyword">function</span>(eventStr, method, thisArg, flags) {
159-
<span class="keyword">var</span> events = eventStr.split(<span class="regexp">/\s+/</span>), event, eventArray, i, len, oldArgs;
160-
flags = flags || { once: <span class="literal">false</span>, recoup: <span class="literal">false</span> };
161-
<span class="keyword">for</span> (i = <span class="number">0</span>, len = events.length; i &lt; len; i++) {
162-
eventArray = <span class="keyword">this</span>._pubsubEvents[event = events[i]];
163-
<span class="keyword">if</span> (eventArray) {
164-
eventArray.push([method, thisArg, flags.once]);
165-
} <span class="keyword">else</span> {
166-
<span class="keyword">this</span>._pubsubEvents[event] = [[method, thisArg, flags.once]];
167-
}
168-
<span class="keyword">if</span> (flags.recoup) {
169-
oldArgs = <span class="keyword">this</span>._pubsubHappened[event];
170-
<span class="keyword">if</span> (oldArgs) {
171-
method.apply(thisArg || <span class="keyword">this</span>, oldArgs);
172-
}
146+
<div class="content"><div class='highlight'><pre> sub: <span class="keyword">function</span>(eventStr, method, thisArg, flags) {
147+
<span class="keyword">var</span> events = eventStr.split(<span class="regexp">/\s+/</span>), event, eventArray, i, len, oldArgs;
148+
flags = flags || { once: <span class="literal">false</span>, recoup: <span class="literal">false</span> };
149+
<span class="keyword">for</span> (i = <span class="number">0</span>, len = events.length; i &lt; len; i++) {
150+
eventArray = <span class="keyword">this</span>._pubsubEvents[event = events[i]];
151+
<span class="keyword">if</span> (eventArray) {
152+
eventArray.push([method, thisArg, flags.once]);
153+
} <span class="keyword">else</span> {
154+
<span class="keyword">this</span>._pubsubEvents[event] = [[method, thisArg, flags.once]];
155+
}
156+
<span class="keyword">if</span> (flags.recoup) {
157+
oldArgs = <span class="keyword">this</span>._pubsubHappened[event];
158+
<span class="keyword">if</span> (oldArgs) {
159+
method.apply(thisArg || <span class="keyword">this</span>, oldArgs);
173160
}
174161
}
175-
<span class="keyword">return</span> <span class="keyword">this</span>;
176-
},</pre></div></div>
162+
}
163+
<span class="keyword">return</span> <span class="keyword">this</span>;
164+
},</pre></div></div>
177165

178166
</li>
179167

@@ -197,20 +185,20 @@ <h3>pubsub.unsub</h3>
197185

198186
</div>
199187

200-
<div class="content"><div class='highlight'><pre> unsub: <span class="keyword">function</span>(eventStr, method) {
201-
<span class="keyword">var</span> events = eventStr.split(<span class="regexp">/\s+/</span>), event, eventArray, newEventArray, i, j;
202-
<span class="keyword">for</span> (i = <span class="number">0</span>; i &lt; events.length; i++) {
203-
eventArray = <span class="keyword">this</span>._pubsubEvents[event = events[i]] || [];
204-
newEventArray = [];
205-
<span class="keyword">for</span> (j = <span class="number">0</span>; method &amp;&amp; j &lt; eventArray.length; j++) {
206-
<span class="keyword">if</span> (eventArray[j][<span class="number">0</span>] !== method) {
207-
newEventArray.push(eventArray[j]);
208-
}
188+
<div class="content"><div class='highlight'><pre> unsub: <span class="keyword">function</span>(eventStr, method) {
189+
<span class="keyword">var</span> events = eventStr.split(<span class="regexp">/\s+/</span>), event, eventArray, newEventArray, i, j;
190+
<span class="keyword">for</span> (i = <span class="number">0</span>; i &lt; events.length; i++) {
191+
eventArray = <span class="keyword">this</span>._pubsubEvents[event = events[i]] || [];
192+
newEventArray = [];
193+
<span class="keyword">for</span> (j = <span class="number">0</span>; method &amp;&amp; j &lt; eventArray.length; j++) {
194+
<span class="keyword">if</span> (eventArray[j][<span class="number">0</span>] !== method) {
195+
newEventArray.push(eventArray[j]);
209196
}
210-
<span class="keyword">this</span>._pubsubEvents[event] = newEventArray;
211197
}
212-
<span class="keyword">return</span> <span class="keyword">this</span>;
213-
},</pre></div></div>
198+
<span class="keyword">this</span>._pubsubEvents[event] = newEventArray;
199+
}
200+
<span class="keyword">return</span> <span class="keyword">this</span>;
201+
},</pre></div></div>
214202

215203
</li>
216204

@@ -227,14 +215,14 @@ <h3>pubsub.once</h3>
227215
To mark the function execution as unsuccessful
228216
(and thus keep it subscribed), make it return <code>false</code>.</p>
229217
<ul>
230-
<li><strong>once(eventString, method, thisArg)</strong> identical to <em>PubSub.sub()</em>.</li>
218+
<li><strong>once(eventString, method, thisArg)</strong> identical to <em>pubsub.sub()</em>.</li>
231219
</ul>
232220

233221
</div>
234222

235-
<div class="content"><div class='highlight'><pre> once: <span class="keyword">function</span>(eventStr, method, thisArg) {
236-
<span class="keyword">return</span> <span class="keyword">this</span>.sub(eventStr, method, thisArg, { once: <span class="literal">true</span> });
237-
},</pre></div></div>
223+
<div class="content"><div class='highlight'><pre> once: <span class="keyword">function</span>(eventStr, method, thisArg) {
224+
<span class="keyword">return</span> <span class="keyword">this</span>.sub(eventStr, method, thisArg, { once: <span class="literal">true</span> });
225+
},</pre></div></div>
238226

239227
</li>
240228

@@ -249,21 +237,65 @@ <h3>pubsub.recoup</h3>
249237
<p>Subscribe to an event, and execute immediately if that event was ever published before.</p>
250238
<p>If executed immediately, the subscriber will get as parameters the last values sent with the event.</p>
251239
<ul>
252-
<li><strong>recoup(eventString, method, thisArg)</strong> identical to <em>PubSub.sub()</em>.</li>
240+
<li><strong>recoup(eventString, method, thisArg)</strong> identical to <em>pubsub.sub()</em>.</li>
253241
</ul>
254242

255243
</div>
256244

257-
<div class="content"><div class='highlight'><pre> recoup: <span class="keyword">function</span>(eventStr, method, thisArg) {
258-
<span class="keyword">return</span> <span class="keyword">this</span>.sub(eventStr, method, thisArg, { recoup: <span class="literal">true</span> });
245+
<div class="content"><div class='highlight'><pre> recoup: <span class="keyword">function</span>(eventStr, method, thisArg) {
246+
<span class="keyword">return</span> <span class="keyword">this</span>.sub(eventStr, method, thisArg, { recoup: <span class="literal">true</span> });
247+
},</pre></div></div>
248+
249+
</li>
250+
251+
252+
<li id="section-9">
253+
<div class="annotation">
254+
255+
<div class="pilwrap for-h3">
256+
<a class="pilcrow" href="#section-9">&#182;</a>
257+
</div>
258+
<h3>pubsub.eventSplitter</h3>
259+
<p>The character on which to split the event namespace.</p>
260+
261+
</div>
262+
263+
<div class="content"><div class='highlight'><pre> eventSplitter: <span class="string">':'</span>,</pre></div></div>
264+
265+
</li>
266+
267+
268+
<li id="section-10">
269+
<div class="annotation">
270+
271+
<div class="pilwrap for-h3">
272+
<a class="pilcrow" href="#section-10">&#182;</a>
273+
</div>
274+
<h3>pubsub.eventNamespace</h3>
275+
<p>Parses the namespaced event string and returns an array of events to publish.
276+
The original implementation does: <code>&quot;path:to:event&quot; =&gt; [&quot;path&quot;, &quot;path:to&quot;, &quot;path:to:event&quot;]</code>.
277+
Overwrite the implementation to create your custom namespacing rules.</p>
278+
279+
</div>
280+
281+
<div class="content"><div class='highlight'><pre> eventNamespace: <span class="keyword">function</span>(eventString) {
282+
<span class="keyword">var</span> events = [], str = <span class="string">''</span>, ch, i, splitter = <span class="keyword">this</span>.eventSplitter;
283+
<span class="keyword">for</span> (i = <span class="number">0</span>; i &lt; eventString.length; i++) {
284+
<span class="keyword">if</span> ((ch = eventString.charAt(i)) === splitter) {
285+
events.push(str);
286+
}
287+
str += ch;
259288
}
260-
};
289+
events.push(str);
290+
<span class="keyword">return</span> events;
291+
}
292+
};
261293

262-
<span class="keyword">for</span> (<span class="keyword">var</span> i <span class="keyword">in</span> prototype) {
263-
<span class="keyword">if</span> (prototype.hasOwnProperty(i)) {
264-
pubsub.prototype[i] = prototype[i];
265-
}
266-
}
294+
<span class="keyword">for</span> (<span class="keyword">var</span> i <span class="keyword">in</span> prototype) {
295+
<span class="keyword">if</span> (prototype.hasOwnProperty(i)) {
296+
pubsub.prototype[i] = prototype[i];
297+
}
298+
}
267299
})(<span class="keyword">this</span>);</pre></div></div>
268300

269301
</li>

0 commit comments

Comments
 (0)