/node_modules/nope/node_modules/joose/lib/Joose/Manual/Roles.js
JavaScript | 288 lines | 0 code | 0 blank | 288 comment | 0 complexity | 7dc671229b923356daa86113fc72dc19 MD5 | raw file
1/**
2
3NAME
4====
5
6Joose.Manual.Roles - Roles, an alternative to deep hierarchies and base classes
7
8WHAT IS A ROLE?
9===============
10
11A role is something that classes do. Usually, a role encapsulates some piece of behavior or state that can be shared between classes. It is important to understand that roles are not classes.
12You cannot inherit from a role, and a role cannot be instantiated. We sometimes say that roles are *consumed*, either by classes or *other roles*.
13
14Instead, a role is *composed* into a class. In practical terms, this means that all of the methods and attributes defined in a role are added directly to (we sometimes say *composed into*) the class that consumes the role.
15However attributes or methods, alredy defined in the class *will not be overriden*.
16
17Composed attributes and methods then appear as if they were *defined in the class itself*. Thus, they *will override* the methods, inherited from superclass.
18Further subclasses of the consuming class, will inherit all of these composed methods and attributes.
19
20Joose roles are similar to mixins or interfaces in other languages.
21
22Besides defining their own methods and attributes, roles can also require that the consuming class define certain methods of its own. You could have a role that consisted only of a list of required methods,
23in which case the role would be very much like a Java interface.
24
25Note that attribute accessors also count as methods for the purposes of satisfying the requirements of a role.
26
27
28`does` BUILDER
29==============
30
31Creating a role looks a lot like creating a Joose class:
32
33 Role('Winged', {
34 has : {
35 leftWing : { is : 'rw' },
36 rightWing : { is : 'rw' }
37 },
38
39 methods : {
40
41 flight : function () {
42 this.leftWing.flutter()
43 this.rightWing.flutter()
44 },
45
46 land : function () {
47 this.leftWing.hold()
48 this.rightWing.hold()
49 }
50 }
51 })
52
53Except for our use of Role, this looks just like a class definition with Joose. However, this is not a class, and it cannot be instantiated.
54
55Instead, its attributes and methods will be composed into classes which use the role:
56
57 Class('Bird', {
58 isa : Animal,
59
60 does : Winged
61 })
62
63The `does` builder composes roles into a class. Once that is done, the `Bird` class has an `leftWing/rightWing` attributes and a number of `fly*` methods.
64
65 var bird = new Bird()
66
67 bird.flight()
68 bird.land()
69
70You may ask, whats the point of defining such role, if all birds can fly? The answer is that sometimes, other animals can also fly:
71
72 Class('Gryphon', {
73 isa : Lion,
74
75 does : Winged
76 })
77
78 var gryphon = new Gryphon()
79
80 gryphon.flight()
81 gryphon.land()
82
83Defining a role for flying will allow us to re-use "flying logic" in any other class.
84
85
86REQUIRED METHODS. USING METHOD MODIFIERS
87========================================
88
89As mentioned previously, a role can require that consuming classes provide one or more methods (attribute accessors also count as methods for the purpose). Using our 'Winged' example, make it require that consuming classes implement their own 'turnLeft' and 'turnRight' methods:
90
91 Role('Winged', {
92 requires : [ 'turnLeft', 'turnRight' ],
93
94 has : {
95 isFlying : false,
96
97 leftWing : { is : 'rw' },
98 rightWing : { is : 'rw' }
99 },
100
101 methods : {
102
103 flight : function () {
104 leftWing.flutter()
105 rightWing.flutter()
106
107 this.isFlying = true
108 },
109
110 land : function () {
111 leftWing.hold()
112 rightWing.hold()
113
114 this.isFlying = false
115 },
116
117 flyLeft : function () {
118 leftWing.hold()
119 rightWing.flutter()
120 },
121
122 flyRight : function () {
123 leftWing.flutter()
124 rightWing.hold()
125 },
126 },
127
128 override : {
129 turnLeft : function () {
130 if (this.isFlying)
131 this.flyLeft()
132 else
133 this.SUPER()
134 },
135
136 turnRight : function () {
137 if (this.isFlying)
138 this.flyRight()
139 else
140 this.SUPER()
141 }
142 }
143 })
144
145If we try to consume this role in a class that does not have a `turnRight` or `turnLeft` method, we will get an exception.
146
147You can see that we added a method modifier on `turnLeft/turnRight`. We want classes that consume this role to implement their own "ground" logic for turning, but we make sure that this logic will be overriden during flight.
148
149Method modifiers and roles are a very powerful combination. Often, a role will combine method modifiers and required methods. We already saw one example with our Winged role.
150
151Method modifiers increase the complexity of roles, because they make the role application order relevant.
152If a class uses multiple roles, each of which modify the same method, those modifiers will be applied in the same order as the roles are used.
153
154
155Roles Versus Abstract Base Classes
156----------------------------------
157
158If you are familiar with the concept of abstract base classes in other languages, you may be tempted to use roles in the same way.
159
160You can define an "interface-only" role, one that contains just a list of required methods.
161
162However, any class which consumes this role must implement all of the required methods, either directly or through inheritance from a parent.
163You cannot delay the method requirement check so that they can be implemented by future subclasses.
164
165Because the role defines the required methods directly, adding a base class to the mix would not achieve anything.
166We recommend that you simply consume the interface role in each class which implements that interface.
167
168
169
170METHOD CONFLICTS
171================
172
173If a class (or role) consumes multiple roles, and those roles have methods of the same name, we will have a *methods conflict*. One of the solutions for such case, is that the composing class is required to provide its own method of the same name.
174For example:
175
176 Role('Walk', {
177 have : {
178 walking : false
179 },
180
181 methods : {
182 walk : function (where) { this.walking = true },
183 stop : function () { this.walking = false }
184 }
185 })
186
187 Role('Eat', {
188 have : {
189 eating : false
190 },
191
192 methods : {
193 eat : function (food) { this.eating = true },
194 stop : function () { this.eating = false }
195 }
196 })
197
198If we compose both Walk and Eat in a class, we must provide our own 'stop' method:
199
200 Class('Creature', {
201 does : [ Walk, Eat ],
202
203 methods : {
204 stop : function () {
205 this.walking = false
206 this.eating = false
207 }
208 }
209 })
210
211
212METHOD EXCLUSION AND ALIASING
213=============================
214
215If we want our `Creature` class to be able to call the methods from both its roles, we can alias the methods:
216
217 Class('Creature', {
218 does : [{
219 role : Walk,
220 alias : {
221 stop : 'stopWalk'
222 }
223 }, {
224 role : Eat,
225 alias : {
226 stop : 'stopEat'
227 }
228 }]
229 })
230
231However, aliasing a method simply makes a copy of the method with the new name. We also need to exclude the original name:
232
233 Class('Creature', {
234 does : [{
235 role : Walk,
236 alias : {
237 stop : 'stopWalk'
238 },
239 exclude : [ 'stop' ]
240 }, {
241 role : Eat,
242 alias : {
243 stop : 'stopEat'
244 },
245 exclude : [ 'stop' ]
246 }]
247 })
248
249The `exclude` parameter prevents the `stop` method from being composed into the `Creature` class, so we don't have a conflict. This means that Creature does not need to implement its own `stop` method.
250
251This is useful, but it's worth noting that this breaks the contract implicit in consuming a role. Our `Creature` class does both the `Walk` and `Eat`, but does not provide a `stop` method.
252If some API expects an object that does one of those roles, it probably expects it to implement that method.
253
254In some use cases we might alias and exclude methods from roles, but then provide a method of the same name in the class itself.
255
256
257
258THEORETICAL BACKGROUND OF ROLES
259===============================
260
261If you would like to dig into theoretical roots of Roles, refer to [this publication.](http://scg.unibe.ch/archive/papers/Scha02bTraits.pdf)
262
263
264
265AUTHOR
266======
267
268Nickolay Platonov [nickolay8@gmail.com](mailto:nickolay8@gmail.com)
269
270Heavily based on the original content of Moose::Manual, by Dave Rolsky [autarch@urth.org](mailto:autarch@urth.org)
271
272
273COPYRIGHT AND LICENSE
274=====================
275
276Copyright (c) 2008-2011, Malte Ubl, Nickolay Platonov
277
278All rights reserved.
279
280Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
281
282* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
283* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
284* Neither the name of Malte Ubl nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
285
286THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
287
288*/