What are some defining characteristics of a Ruby DSL that separate it from just a regular API?
When you use an API you instantiate objects and call methods in an imperative manner. On the other hand a good DSL should be declarative, representing rules and relationships in your problem domain, not instructions to be executed. Moreover ideally DSL should be readable and modifiable by somebody who is not a programmer (which is not the case with APIs).
Also please keep in mind the distinction between internal and external DSLs.
Internal domain specific language is embedded in a programming language (eg. Ruby). It's easy to implement, but the structure of the DSL is dependent on the parent language it is embedded in.
External domain specific language is a separate language designed with the particular domain in mind. It gives you a greater flexibility when it comes to syntax, but you have to implement the code to interpret it. It's also more secure, as the person editing domain rules doesn't have access to all the power of the parent language.
DSL (domain specific language) is an over-hyped term. If you are simply using a sub-set of a language (say Ruby), how is it a different language than the original? The answer is, it isn't.
However, if you do some preprocessing of the source text to introduce new syntax or new semantics not found in the core language then you indeed have a new language, which may be domain-specific.
The combination of Ruby's poetry mode and operator overloading does present the possibility of having something that is at the same time legal Ruby syntax and a reasonable DSL.
And the continued aggravation that is XML does show that perhaps the simple DSL built into all those config files wasn't completely misguided..
Creating a DSL:
Adding new methods to the Object class so that you can just call them as if they were built-in language constructs. (see rake)
Creating methods on a custom object or set of objects, and then having script files run the statements in the context of a top-level object. (see capistrano)
API design:
Creating methods on a custom object or set of objects, so the user creates an object to use the methods.
Creating methods as class methods, so that the user prefixes the classname in front of all the methods.
Creating methods as a mixin that users include or extend to use the methods in their custom objects.
So yes, the line is thin between them. It's trivial to turn a custom set of objects into a DSL by adding one method that runs a script file in the right context.
The difference between a DSL and an API to me is that a DSL could be at least understood (and verified) if not written as a sub-language of Ruby by someone in that domain.
For example, you could have financial analysts writing rules for a stock trading application in a Ruby DSL and they would never have to know they were using Ruby.
They are, in fact, the same thing. DSLs are generally implemented via the normal language mechanisms in Ruby, so technically they're all APIs.
However, for people to recognize something as a DSL, it usually ends up adding what look like declarative statements to existing classes. Something like the validators and relationship declarations in ActiveRecord.
class Foo << ActiveRecord::Base
validates_uniqueness_of :name
validates_numericality_of :number, :integer_only => true
end
looks like a DSL, while the following doesn't:
class Foo <<ActiveRecord::BAse
def validate
unless unique? name
errors.add(:name, "must be unique")
end
unless number.to_s.match?(/^[-]?\d$/)
errors.add(:number, "must be an integer")
end
end
end
They're both going to be implemented by normal Ruby code. It's just that one looks like you've got cool new language constructs, while the other seems rather pedestrian (and overly verbose, etc. etc.)
Related
I've been reading Sandi Metz's Practical Object-Oriented Design in Ruby and many sites online discussing design in Ruby. Something I've had a hard time fully understanding is the proper way to implement dependency injection.
The internet is flooded with blog posts that explain how dependency injection works in what I think is a very partial way.
I understand that this is supposed to be bad:
class ThisClass
def initialize
#another_class = AnotherClass.new
end
end
While this is a solution:
class ThisClass
def initialize(another_class)
#another_class = another_class
end
end
And that I could send the AnotherClass.new like this:
this_class = ThisClass.new(AnotherClass.new)
That is the approach that Sandi Metz recommends at least. What I don't understand is where should a line like that go? It has to go somewhere and generally in examples of this what's shown is a line like that being placed totally outside of any class, method, or module as if I'm simply entering it all by hand in IRB for testing purposes.
This post (among others) suggests this different approach:
class ThisClass
def another_class
#another_class ||= AnotherClass.new
end
end
Jamis Buck would take a similar approach like this:
class AnotherClass
end
class ThisClass
def another_class_factory(class_name = AnotherClass)
class_name.new
end
end
However, these two examples both preserve AnotherClass's name inside ThisClass, which Sandi Metz says is one of the main things we're trying to avoid.
So what is the best practice for doing this? Should I make a 'dependency' module filled with methods that are factories for objects of each class in my application?
Something I've had a hard time fully understanding is the proper way to implement dependency injection.
I think the best definition of a "proper" implementation is one that adheres to the SOLID principles of object oriented design. In this case mostly the Dependency Inversion Principle.
In this regard, this is the only presented solution that does not violate the DIP(1):
class ThisClass
def initialize(another_class)
#another_class = another_class
end
end
In all other cases, ThisClass has a hard dependency on AnotherClass, and can not function without it. Furthermore, if we wish to replace AnotherClass with a third, we need to modify ThisClass, which is a violation of the Open Closed Principle.
Of course, in the example above, naming the parameter and instance variable another_class is not ideal, since we do not now (and do not need to know) what object is passed to us, as long as it responds to the expected interface. This is the beauty of polymorphism.
Consider the below example, taken from this ThoughtBot video on DIP:
class Copier
def initialize(reader, writer)
#reader = reader
#writer = writer
end
def copy
#writer.write(#reader.read_until_eof)
end
end
Here you can pass any reader and writer objects that respond to read_until_eof and write respectively. This gives you full freedom to compose your business logic using different pairs of read and write implementations, even at runtime:
Copier.new(KeyboardReader.new, Printer.new)
Copier.new(KeyboardReader.new, NetworkPrinter.new)
Which brings us to your next question.
It has to go somewhere and generally in examples of this what's shown is a line like that being placed totally outside of any class, method, or module [...]
You are correct. While object thinking involves modelling the domain with well isolated, decoupled, and composable objects, you will still need to define how these objects interact, in order to implement any business logic. After all, having composable objects is no good unless we compose them.
The analogy that is often made here is to think of your objects as actors. You are the director, and you still need to create a script(2) for the actors to know how to interact with each other.
That is, you need an entry point into your application. A place where the script starts. This might itself be an object--normally an abstract one. In a command line application, it can be your classic Main class, and in a Rails application it can be your controller.
This might seem strange at first, because the focus of object thinking is on modelling concrete domain objects, and a great deal of all writings on the subject is dedicated to this effort, but just remember the actor-script metaphor, and you'll be on your way.
I strongly recommend you pick up the book Object Thinking. It does a great job explaining the mindset behind object oriented design, without which knowing the language specific implementation details becomes rather futile.
(1): It is worth noting that some proponents consider storing an instance of another class in an instance variable an anti-pattern, but in Ruby, this is fairly idiomatic.
(2): I am not sure if this is the origin of the term script in programming in general, but maybe some historian can shed some light on this.
I'm implementing several classes which does not have data by itself, just logics. These classes implements access control policy to date which depends on several parameters taken from data from other models.
I initially try to find answer to "Where to store such classes?" here, and the answer was apps/models directory. That's ok, but I like to clearly separate these classes from ActiveRecord inherited classes in hierarchy, both as file and class.
So, I created classes inside Logic module, like Logic::EvaluationLogic or Logic::PhaseLogic. I also wanted to have constants which passed between these logics. I prefer to place these constants into Logic module too. Thus, I implemented like this:
# in logic/phase_logic.rb
module Logic
PHASE_INITIAL = 0
PHASE_MIDDLE = 1000
class PhaseLogic
def self.some_phase_control_code
end
end
end
# in logic/evaluation_logic.rb
module Logic
class EvaluationLogic
def self.some_other_code
Logic::PhaseLogic.self.some_phase_control_code(Logic::PHASE_INITIAL)
end
end
end
Now, it work just fine with rspec (It passes tests I wrote without issues), but not with development server, since it can't find the Logic::PHASE_INITIAL constant.
I suspect it's related to the mismatch of the autoloading scheme of Rails and what I wanted to do. I tried to tweak rails, but no luck, ended-up with eliminating module Logic wrap.
Now the question I want to ask: How I can organize these classes with Rails?
I'm using 3.2.1 at this moment.
Posted a follow-up question "How I can organize namespace of classes in app/modules with rails?"
I am not sure whether I really understand your classes, but couldn't you create a Logic module or (I would rather do this:) PhaseLogic and EvaluationLogic objects in /lib directory?
It is not said that "Model" is always descendant of ActiveRecord. If the object belongs to "business logic" then it is a model. You can have models which do not touch database in any way. So, if your classes are "business objects", place them in 'app/models' and use like any other model.
Another question is whether you should use inheritance or modules - but I would rather think about including a module in PhaseLogic, and not about defining PhaseLogic in a module. Of course, all this depends heavily on the intended role of your objects.
Because in Ruby the class of object is not important, you do not need to use inheritance. If you want to 'plug' the logic objects into other objects, just take care that all '*Logic' classes have the required methods. I know that all I said is very vague, but I think I cannot give you some more concrete suggestions without knowing more about the role of these objects.
Ah, and one more thing!
If you find yourself fighting with Rails class autoloading, just use the old require "lib/logic.rb" in all the classes where you are using Logic::PHASE_INITIAL constants.
In this case I suppose that your problem was caused by different order of loading. The logic/evaluation_logic.rb has been loaded before logic/phase_logic.rb. The problem may disappear if you create logic.rb somewhere, where class autoloading can find it, and define these constants in that file.
Don't name your classes or modules Logic use specific names. Start with extracting logic into separate classes and then try to break them into smaller ones. Use namespaces to distinguish them from each other in lib folder, after this steps you would be able to extract some logic parts to separate gems and reduce codebase and complexity of application. Also take a look into presenter pattern.
Say I am writing a Ruby gem. I want to design classes and modules going to be used.
How to identify them?
Where do I need classes and where do I need modules?
Your question is about one of the main design feature of the Ruby language.
Basically, you can see module as collection of tools, and class as collection of objects which are able to mix with those tools.
Ruby faq says about modules :
Modules are collections of methods and constants. They cannot generate instances.
When you want to provide something, you'll need a class. You can do a MyClass.new, you cannot with a module : MyModule.new won't work.
On the other hand :
Classes may generate instances (objects), and have per-instance state (instance variables).
When you want to provide a way of doing something, you'll a need a module. You can do a MyModule.doSomething(SomeParams). You can also do that with a class methods, but you won't be able to do some mix-in with it.
See this faq for a more detailed answer.
This is a object oriented design task, if you are really new to that I would recommend to study a book like Head First Object-Oriented Analysis and Design. I usually try to identify the core actors/concepts in the business model to discover which classes I need.
A basic rule is to use classes when you need to maintain some states, and modules when there is no need of maintaining states. Ruby has several uses for modules Ruby, there are several articles about this topic in the Practicing Ruby blog: part 1, part 2, part 3, part 4
I use to think of Modules stricly as as behaviour capsules and Classes as state and behaviour capsules (from encapsulation).
So, if you want to encapsulate a behaviour use a module. Otherwise use a class.
I read ESR's essay named "How to become a hacker?" several years ago (link can be found in my profile) and Eric suggested learning LISP. Well I'm learning LISP for quite a while and I like it so much that I decided to write a web application using it.
Since I'm using Spring for a while I think that it's a good idea to write decoupled components and glue them together using an IoC container and depencency injection. I did a power search on google and it turned out that there is no such idea implemented in LISP. Do I miss something? Is there a good implementation of this concept in LISP or there is no point using it for some reason which is not yet clear to me?
'Inversion of control' is widely used in Lisp. It's totally simple, since functions and closures are first class objects.
Dependency injection is trivial. Classes and functions can be configured via symbols and first class classes.
You usually don't need a 'framework' for IoC or DI in Common Lisp, since a lot of functionality to configure and parameterize applications and libraries is built in.
'first class' means that something can be stored in variables, passed as arguments or returned as results.
In a language like Common Lisp, functions and classes are first class objects. Plus for decoupling via late-binding, you can use symbols as their names instead. The Common Lisp Object System knows meta classes and symbols as names for classes. Even generic functions and methods are objects and have meta-classes.
If concurrent-secure-server is a class and default-response is a function, you can do for example:
(make-instance 'web-services
:server-class 'concurrent-secure-server
:default-response-function 'default-reponse)
Above uses the symbol as the name for the class and the function. If the function gets a new version, the web service might call the new one later.
Alternatively:
(make-instance 'web-services
:server-class (find-class 'concurrent-secure-server)
:default-response-function #'default-reponse)
In above case we pass the class object and the function object.
In Common Lisp software modules can have global variables, which you can set with the right information:
(defvar *default-server-class* 'concurrent-secure-server)
Alternatively you can set those in slots of like below.
(defclass server-object ()
((default-response-function
:initarg :default-response-function
:initform *server-default-response-function*)))
(defvar *my-server*
(make-instance 'server-object
:default-response-function 'my-default-response-function))
You can even create objects and later change their class in a configuration phase.
The Common Lisp Object System allows you to change classes and have existing objects to be updated.
If you create an instance, you can be as flexible as you want:
you can pass in the class
you can pass in the arguments
Like this:
(let ((my-class 'foo-class)
(my-args `(:response-function ',*some-reponse-function)))
(apply #'make-instance my-class my-args))
Sometimes you see Lisp libraries which are computing such arguments lists at runtime.
Another thing where you can configure Lisp applications at runtime is via generic functions. Generic functions allow :before, :after and :around methods - they even allow your own custom call schemes. So by using your own classes inheriting from other classes and mixin classes, the generic function gets reconfigured. This is like you have basic mechanisms of Aspect-oriented programming built-in.
For people interested in these more advanced object-oriented concepts, there is some literature by Xerox PARC, where these issues had been researched when CLOS was created. It was called 'Open implementation' then:
http://www2.parc.com/csl/groups/sda/publications.shtml
In the Open Implementation approach, modules allow their clients individual control over the module's own implementation strategy. This allows the client to tailor the module's implementation strategy to better suit their needs, effectively making the module more reusable, and the client code more simple. This control is provided to clients through a well-designed auxiliary interface.
One thing you don't need: XML. Common Lisp is its own configuration language. Writing extensions for easier configuration can for example be done via macros. Loading of these configurations can be easily done via LOAD.
Actually IoC is the building principle of most web-frameworks, not only in Java or Lisp.
Considering DI, as noted by Rammaren, it's an implicit pattern in a dynamic language such as Lisp. You can see that for yourself, if you compare Hello World applications in Spring and Restas (one of the well-supported CL web-frameworks). You'll see, that there's the same pattern, except for the absence of a need for fancy type/class/interface declaration stuff in Lisp.
I'd like to know when is the best time to use mixins vs calling a method directly.
For example, consider HTTParty. On one of its examples https://github.com/jnunemaker/httparty/blob/master/examples/basic.rb
you can use HTTParty.get('http://twitter.com/statuses/public_timeline.json') or you can create a class that includes HTTParty and then use it as you would calling HTTParty itself.
What's the difference with me just creating something like this:
class Partay
#base_uri = 'http://localhost:3000'
def self.post(endpoint, options)
HTTParty.post(#base_uri + endpoint, options)
end
end
versus the given example:
class Partay
include HTTParty
base_uri 'http://localhost:3000'
end
True that in such a trivial example perhaps using the include would save more characters, but I'd imagine on a much more complicated class it doesn't really make a difference.
A few clarificatory questions:
Would this be related to a composition vs aggregation argument? Is there any design or architecture best practice regarding this? Should I treat mixins as some sort of inheritance and use them as such (inheritance if it's an is-a relationship, composition if it's a has-a relationship, etc.)? Should I only mixin a module if it was intended to be done so (because docs say it expects certain methods from you, like Enumerable) or is it just good practice to do so? Would using a mixin mean a tighter coupling between the module and my class (and is it relatively good or bad in general)?
In the given example, there is not much difference, other than the syntax is much more friendly with the mixin, and could potentially become a DSL that you can use later.
More generally, mixins allow you to use these same functions in different classes without repeating yourself, and without extending another class (mixins are, for example, a way of working around the fact that ruby does not allow multiple inheritance). This favours reuse and goes towards the DRY philosophy dear to the ruby users. As ruby is duck-typed, mixins allows you to take full advantage of polymorphism without inheritance.
Another great advantage of mixins is that they can be added at runtime, so this means you can add behaviour to a class "dynamically".
Update: I personally prefer using modules as mixins, rather than calling methods on it as the methods then become part of your class, which means that they can access the other members of the class. I’m however reluctant to call it a is-a relationship, even though that’s what it is in practice. As the “Well-Grounded Rubyist” says, classes model entities or things (class names tend to be nouns), modules encapsulate properties or characteristics (module names tend to be adjectives).