Tutorial 1.x
Version 1.x
This file is written using a literate JavaScript. You can download this tutorial to use as a local reference or to run it locally.
If you prefer to see text as inline comments, just click on a sidebar handle at the far right.
While dcl
works great in browsers using an AMD loader or
even simple <script>
, this tutorial is assumed to be run with
node.js.
For our examples we will need the main dcl module:
1
|
|
Inheritance, and constructors
Let’s declare a class derived from Object:
1
|
|
Name of class. It is optional, but highly recommended, because it will help while debugging your objects.
1
|
|
A default name as a class-level constant:
1
|
|
A constructor is a method named … constructor
1 2 3 4 5 6 7 |
|
We can derive more classes from it using single inheritance. Let’s define a bureaucrat (yes, it is a person too!):
1 2 |
|
Remember that all inherited constructors are chained in automatically!
1 2 3 4 5 6 7 8 |
|
Now we can create a typical anonymous clerk:
1
|
|
Output:
Person Anonymous is created
Bureaucrat Anonymous is created
Let’s ask him to approve something:
1
|
|
Output:Rejected by Anonymous
As you can see it is trivial to define “classes”, and derive them using single inheritance.
Constructors are automatically chained and called from the farthest to the closest with the same arguments. Our Bureaucrat’s constructor ignores name, because it knows that Person will take care of it.
Mixins
Let’s declare one more class that will be used as a mixin. Any normal class would do.
1 2 3 4 5 |
|
Now we are ready to create Talker from Person + Speaker:
1
|
|
It has no own methods for simplicity.
1 2 |
|
Let’s create Alice, who is a Talker:
Person Alice is created
1
|
|
Alice: hello!
1
|
|
Supercalls
Let’s declare another mixin, this time using a super call:
1
|
|
Here we use the double function technique to inject
sup
– a method from a super class.
1 2 |
|
Theoretically it is possible that there is no super method – we can be the last in line; not in this case, though – we are based on Speaker meaning it will be always pulled in.
1 2 3 4 5 6 |
|
Let’s create a Shouter called Sarge.
1
|
|
It has no own methods for simplicity.
1 2 |
|
Person Bob is created
1
|
|
Bob: GIVE ME TWENTY!
1
|
|
The double function technique for a super call allows you to work directly with a next method in chain – no intermediaries means that this call is as fast as it can be, no run-time penalties are involved during method calls, and it greatly simplifies debugging.
Anonymous one-off classes
And, of course, our “classes” can be absolutely anonymous, like in this one-off “class”:
Person Loud Bob is created
1
|
|
Loud Bob: ANYBODY HOME?
1
|
|
AOP
We can use aspect-oriented advices to create our “classes” using dcl.advise().
Let’s create one more mixin:
1 2 3 4 5 6 7 8 9 10 |
|
Now we can create Sick Talker.
1
|
|
Person Clara is created
1
|
|
Clara: *hiccup* *hiccup*
Clara: I want a glass of water!
Clara: *sniffle* I am sick!
1
|
|
Hmm, both Talker
and Sick
require the same “class”
Person
. How is it going to work? Don’t worry,
all duplicates are going to be eliminated by
the underlying C3 MRO algorithm. Read all about it in
the documentation.
Of course we can use an “around” advice as well, and it will behave just like a super call above. It will require the same double function technique to inject a method from a super class.
One more mixin, this time using a shortcut dcl.around():
1 2 3 4 5 6 7 8 9 |
|
Now we are ready for…
1
|
|
Person Don is created
1
|
|
Don: *hiccup* *hiccup*
Don: BEEP-BEEP-BEEP
Don: *sniffle* I am sick!
1
|
|
For convenience, dcl
provides shortcuts for
all singular advices. Read all about it in
the documentation.
Chaining
While constructors are chained by default, you can chain any method you like. Usually it works well for lifecycle methods, and event-like methods.
Waker-upper and sleeper:
1 2 3 |
|
Now wakeUp()
and sleep()
are automatically chained.
Note that we don’t need to define methods to declare them chained.
Our handy mixins:
1 2 3 4 5 6 7 8 9 10 11 12 |
|
All together now:
1 2 3 4 5 6 7 |
|
Ethel’s morning ritual:
turn on lights
brush my teeth
dress up for work
1
|
|
Ethel’s evening ritual:
switch to pajamas
brush my teeth again
turn off lights
1
|
|
As you can see chaining allows to do our ritual actions in the correct order. So we don’t need to worry for Ethel to brush her teeth in a dark.
Advising objects
While class-level AOP is static, we can always advise any method dynamically, and unadvise it at will.
Let’s implement the previous example with object-level AOP. For that we need to use a new module dcl/advise:
1
|
|
Let’s use a one-off class this time:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
|
Notice that after advices attached in the reverse order:
1 2 3 4 5 6 7 8 9 |
|
turn on lights
brush my teeth
dress up for work
1
|
|
switch to pajamas
brush my teeth again
turn off lights
1
|
|
Let’s save on electricity:
1
|
|
Brushing teeth more than once a day is overrated, right?
1
|
|
No need to dress up for work either – our Fred is CEO!
1
|
|
brush my teeth
1
|
|
switch to pajamas
turn off lights
1
|
|
Again, for convenience, dcl/advise provides shortcuts for singular advices.
Naturally “around” advices use the same double function technique to be super light-weight.
Debugging helpers
There is a special module dcl/debug that adds better error checking and reporting for your “classes” and objects. All you need is to require it, and it will plug right in:
1
|
|
In order to use it to its fullest, we should include a static class id in our “class” definitions like so:
1 2 |
|
The rest of definitions goes there. It is skipped here for simplicity.
1
|
|
It is strongly suggested to specify declaredClass
for every declaration in every real project.
This declaredClass
can be any unique string,
but by convention it should be a human-readable
name of your “class”, which possibly indicates
where this class can be found.
For example, if you follow the convention
“one class per file” it can be something like
"myProject/SubDir/FileName"
. If you define
several “classes” per file you can use
a following schema:
"myProject/SubDir/FileName/ClassName"
.
Remember that this name is for you and users of your code, it will be reported in error messages and logs. The debug module can log constructors and objects created by those constructors.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
|
Time to hit the pillow!
*zzzzzzzzzzzzz*
*ZzZzZzZzZzZzZ*
1
|
|
Now we can inspect all our objects:
*** class A depends on 0 classes
class method constructor is CHAINED AFTER (length: 0)
class method sleep is UNCHAINED BUT CONTAINS ADVICE(S),
and has an AOP stub (before: 0, around: 0, after: 1)
1
|
|
*** class B depends on 1 classes
dependencies: A
class method constructor is CHAINED AFTER (length: 0)
class method sleep is UNCHAINED BUT CONTAINS ADVICE(S),
and has an AOP stub (before: 0, around: 1, after: 1)
1
|
|
*** object of class B
*** class B depends on 1 classes
dependencies: A
class method constructor is CHAINED AFTER (length: 0)
class method sleep is UNCHAINED BUT CONTAINS ADVICE(S),
and has an AOP stub (before: 0, around: 1, after: 1)
object method sleep has an AOP stub (before: 0, around: 1, after: 2)
1
|
|
This way we can always know that we generated correct classes, inspect static chaining and advices, and even can monitor dynamically attached/removed advices.
Summary
The ultimate goal of dcl
is to provide a solid OOP/AOP foundation
for your projects. Using mixins you can decompose a project into
a small set of simple orthogonal pieces, and glue them together
with supercalls, chains, and advices reducing the overall codebase.
This tutorial just scratched the surface of what dcl
can do.
You will find more examples, explanations, and new features
in the documentation.
Happy hacking! Go small and keep your code DRY!