用Ruby 创建领域特定语言（DSL）
转自豆瓣：https://www.douban.com/note/61163698/整理了一下格式
这是以前翻译的文章，现在都重新收集到豆瓣来吧。2006年翻译的。
by Jim Freeze
英文原文见：http://www.artima.com/rubycs/articles/ruby_as_dsl.html
摘要：
总的说来，有两种创建 DSL 的方法。 一种方法是从零开始发明一个新的语法，并为之构造一个编译器或解释器。 另一种方法是裁剪一个现存的通用目的语言， 增加或修改方法（methods）, 操作符（operators）,以及缺省的行为。 本文讲述使用第二种方法来在 Ruby 之上创建 DSL.
一个 DSL, 是一个针对相对窄的应用范围设计的编程或描述语言。相对于通用目的语言， 它被设计来处理特定的计算任务， DSL 仅适用于特定领域。 你可以用两种方式创建一个 DSL.
- 从零开始发明一个新的语法，并为之构造一个编译器或解释器。
- 裁剪一个现存的通用目的语言， 增加或修改方法（method）, 操作符（operator）,以及缺省的行为。
第二种方法的优势是你节省了时间， 因为你不需要生成和调试一个新的语言， 这样你有更多的时间用于解决最终用户面临的问题。缺点是 DSL 会受限于其下的通用目的语言的语法和能力。 更进一步来说，基于另一个语言来构造DSL 常常意味着最终用户可以获得这个基础语言所有的威力，这可能是优点也可能是缺点， 它取决于特定的应用环境。 这篇文章讲述怎么使用第二种方法来在Ruby之上创建 DSL.
描述堆叠模型（stackup models）
我是一个互连模型（interconnect modeling） 工程师，在工作中， 我们需要一种方式来描述半导体晶片上的电路的垂直几何结构（vertical geometric profile）。这些描述被保存在一个堆叠模型（stackup model） 文件中。（我们造了一个词stackup，因为金属连线是在装配过程（fabrication process）中通过层层堆叠形成的）。现在的问题是，每一个供货商有他们自己的描述堆叠模型（stackup） 的格式， 而我们想要一个公共的格式使得我们可以在不同的格式间进行转换。 换句话说， 我们需要定义一个公共的堆叠模型（stackup） DSL, 并且写一个程序用来从我们格式转换为不同供货商的特定的格式。
供货商没有使用一个复杂的DSL 语言，他们的语言仅仅包含静态的数据元素于一个基本平坦的文本数据库中。他们的文件格式不允许有参数化类型（parameterized type）, 变量， 常量， 以及等式（equation）。 只有静态数据。更进一步来说，格式非常简单。它是基于行的，或者基于只有一个层次的块结构。
我们开始描述我们的堆叠模型格式时，要求并不高，因为我们仅仅需要达到供货商实现的程度就行。但我们很快扩展了我们的格式。为什么我们可以做到这一点， 而我们的供货商却做不到。我相信这是因为我们使用了 Ruby, 而不象我们的供货商用 C 从零开始。我相信也可以用其他的语言， 但是我不认为最终的产品可以同样出色。通用语言的选择是关键的一步。
我也相信供货商的开发速度因为使用 C 而受到阻碍， 因为他们要保持他们的堆叠模型的语法尽量简单以便于分析（parse）. 可能并非偶然，很多供货商在他们的文件格式中使用一些共同的简单的语法结构。 因为这些简单的语法结构出现频繁， 我们将先在 Ruby 中仿制它们， 然后再转到更复杂的语法结构。
基于行和块级别的 DSL 结构（constructs）
基于行的结构是一种将一个值或一个范围的值赋予一个参数（parameter）的方式。 在我们所考察的供货商的文件中，使用了下面的格式。
parameter = valueparameter valueparameter min_value max_value step_value
除了2 中没有显式出现’=’ , 格式1和2 是等价的。 格式3 将一个范围的值赋给了一个参数。
更为复杂的格式包含一个块结构。有两种格式如下所示。 这两种块结构可以使用一个基于行的分析器和一个堆栈 ，或一个带堆栈的关键字分析器(key-letter and word parser)来手动分析。
begin
type = TYPE
name = NAME
param1 = value1
param2 = value2
...
end
下面一种块格式使用 C 风格的大括号{}来标识一个块， 但参数/值对用空格来分隔。
TYPE NAME {param1 = value1 param2 = value2 }
三次是一个咒语
在我们构建我们的堆叠文件的DSL时， 我们把问题解决了三次。 首先， 我们写了自己的语法分析器，然后发现那样的话有太多的工作要维护。不仅仅是代码，而且还有文档。因为我们的DSL 足够复杂，如果没有足够文档，没有显然的方法去使用它的所有特性。
接着，在一个短时间内，我们用 XML实现了 DSL。 这样，我们不需要去写自己的语法分析器，因为XML 有现成的分析器。但是 XML引入太多的噪声，模糊了文件的实际内容 。我们的工程师发现思维在理解堆叠文件的含义和理解XML之间进行切换很困难。由此我认识到，XML 不适合人来阅读，XML可能不是用来创建DSL 的好的选择， 尽管我们有不用开发语法分析器（parser）的好处。
最后，我们用Ruby实现了DSL。 因为利用了 Ruby 解释器的分析功能，实现起来是很快的。我们不需要写分析器（就是Ruby）的文档，因为它已经存在。而且，最终的DSL 非常容易被人理解，也很简洁灵活。
好的。 让我们用Ruby来创建一个 DSL，该DSL允许我们定义形如‘parameter = value’的语句。请考虑以下假想的DSL 文件。
% cat params_with_equal.dsl
name = fred
parameter = .55
这不是合法的Ruby代码，我们需要稍微修改一下语法使得Ruby可以接受它。让我们将它改为：
% cat params_with_equal.dsl
name = "fred"
parameter = 0.55
一旦我们让DSL 遵循Ruby的语法，Ruby 就为我们做了所有的分析工作，并且提供了一种方式访问分析的结果。 现在，让我们写一些 Ruby 代码来读DSL。
首先，我们想要将这些参数用某种方式封装起来。 一个好的方法是将它们放到一个类中。我们称这个类为 MyDSL。
% cat mydsl.rb
class MyDSL
...
end#class MyDSL
从开发者的角度看，我们需要一个简单和直接的方式来分析DSL 文件。就如下面所示：
my_dsl = MyDSL.load(filename)
接着，让我们来写类方法 load:
def self.load(filename)
dsl = new
dsl.instance_eval(File.read(filename), filename)
dsl
end
类方法load 产生一个MyDSL对象， 并且以DSL 文件的内容为参数调用该对象的instance_eval。Instance_eval的第二个参数是可选的， 它使得Ruby 在出现语法分析错误时可以报告文件名。 一个可选的第三个参数（没有使用）可以使Ruby 在出现分析错误时能提供错误开始的行号
这个代码能工作吗？ 让我们看看发生了什么？
% cat dsl-loader.rb
require 'mydsl'
my_dsl = MyDSL.load(ARGV.shift) # put the DSL filename on the command line
p my_dsl
p my_dsl.instance_variables
% ruby dsl-loader.rb params_with_equal.dsl
#
[]
发生了什么? name 和parameter到那里去了？ 这是因为name和parameter在等号的左侧，Ruby 认为他们是局部变量。我们可以告诉Ruby它们是实例变量。有两种方式，一种是使用 self.name = “fred” self.parameter = 0.55 ， 另一种是使用@符号。
@name = "fred"
@parameter = 0.55
但是对我来说，这样很丑陋。写成下面的形式也是一样。
$name = "fred"
$parameter = 0.55
还有一个办法让Ruby 知道这些方法（method）执行的上下文， 那就是利用块(block)和 yield self（MyDsl的对象实例） 来显式的声明作用域。 为了做到这一点，我们将加一个顶层方法来开始我们的DSL， 并且将实际内容放进所附的块(block)中。 修改过的 DSL 看起来是这样：
% cat params_with_equal2.dsl
define_parameters do |p|
p.name = "fred"
p.parameter = 0.55
end
define_parameter 已经被定义为一个实例方法（instance method）。
% cat mydsl2.rb
class MyDSL
def define_parameters
yield self
end
def self.load(filename)
dsl = new
dsl.instance_eval(File.read(filename), filename)
dsl
end
end#class MyDSL
修改dsl- loader中的require，让它使用mydsl2.rb 中的新版本的MyDSL 类：
% cat dsl-loader.rb
require 'mydsl2'
my_dsl = MyDSL.load(ARGV.shift)
p my_dsl
p my_dsl.instance_variables
理论上，这可以工作， 让我们测试一下。
% ruby dsl-loader.rb params_with_equal2.dsl
params_with_equal2.dsl:2:in 'load': undefined method 'name=' for # (NoMethodError)
噢，我们忘记了为 name 和parameter 定义访问函数（accessor）。 让我们加上它们， 然后看一下完整的程序：
% cat mydsl2.rb
class MyDSL
attr_accessor :name, :parameter
def define_parameters
yield self
end
def self.load(filename)
# ... same as before
end
end
现在， 再测试一遍。
% ruby dsl-loader.rb params_with_equal2.dsl
#["@name", "@parameter"]
成功！ 现在工作了。但是我们在DSL文件中加了额外的两行， 还有额外的 .p , 这些都引入了噪声。这样的记法（notation）更适合于当DSL文件中存在多个层次， 并且需要显式指定上下文的情况。 在我们的简单例子里，我们应该隐式的定义上下文， 且让Ruby 知道name 和parameter 是方法（method）。 让我们删掉 ‘=’ ， 将DSL 文件写成：
% cat params.dsl
name "fred"
parameter 0.55
现在，我们需要为name 和 parameter 定义新的访问方法（accessor）。这里的窍门是：不带参数的name 是@name的读方法（reader）， 带一个或多个参数的name 是@name的写方法（setter）。（注意：使用这个办法很方便，即使是DSL文件有多个层次而且上下文是显式声明的）。 我们下面为name 和parameter 定义访问方法, 删除attr_accessor那一行，加入以下代码：
% cat mydsl3.rb
class MyDSL
def name(*val)
if val.empty?
@name
else
@name = val.size == 1 ? val[0] : val
end
end
def parameter(*val)
if val.empty?
@parameter
else
@parameters = val.size == 1 ? val[0] : val
end
end
def self.load(filename)
# ... same as before
end
end#class MyDSL
如果 name 或parameter 不带参数，它们将返回它们的值。如果带参数：
- 如果带一个参数，它们会被赋予该参数的值
- 如果带多个参数，它们会被赋予一个数组，该数组包含所有的参数值
让我们运行我们的分析器（现在是mydsl3.rb）来测试一下：
% ruby dsl-loader.rb params.dsl
#["@parameter", "@name"]
又成功了。但是显式地定义访问方法( accessors) 很烦人。让我们定义一个定制的访问方法，并且让所有的类都可以使用它。 我们通过将此方法(method)放到 Module class 中来做到这一点。
% cat dslhelper.rb
class Module
def dsl_accessor(*symbols)
symbols.each { |sym|
class_eval %{
def #{sym}(*valz
if val.empty?
@#{sym}
else
@#{sym} = val.size == 1 ? val[0] : val
end
end
}
}
end
end
上面的代码简单的定义了一个 dsl_accessor 方法， 它是我们的DSL特定的访问方法。现在我们用它取代attr_accessor：
% cat mydsl4.rb
require 'dslhelper'
class MyDSL
dsl_accessor :name, :parameter
def self.load(filename)
# ... same as before
end
end#class MyDSL
再一次，我们更新dsl-loader.rb 中的require 语句，加载mydsl4.rb， 然后运行loader:
% ruby dsl-loader.rb params.dsl
#["@parameter", "@name"]
一切都很好。但是如果我不能事先知道参数的名字怎么办？ 在实际使用中，参数名应该可以由用户来生成。 别害怕。有Ruby 在， 我们可以使用 method_missing 的威力。给 MyDSL加一个两行的方法， 我们可以用dsl_accessor 根据需要随时定义新的属性(attribute)。 也就是说，如果一个值被赋予一个不存在的参数，method_missing 会定义一个 getter 和一个setter ，并且将该值赋予新生成的参数。
% cat mydsl5.rb
require 'dslhelper'
class MyDSL
def method_missing(sym, *args)
self.class.dsl_accessor sym
send(sym, *args)
end
def self.load(filename)
# ... Same as before
end
end
% head -1 dsl-loader.rb
require 'mydsl5'
% ruby dsl-loader.rb params.dsl
#["@parameter", "@name"]
哇！是不是感觉很好？ 仅仅写了一点代码，我们有了一个可以读和定义任意数目参数的分析器。还可以吧。但是如果最终用户不知道Ruby，且使用了与现存的Ruby 方法冲突的名字，怎么办？ 举例来说，如果我们的DSL文件包含以下内容：
% cat params_with_keyword.dsl
methods %w(one two three)
id 12345
% ruby dsl-loader.rb params_with_keyword.dsl
params_with_keyword.dsl:2:in 'id': wrong number of arguments (1 for 0) (ArgumentError)
噢，真不好意思。不过我们可以迅速的解决这个问题。 这里要用到一个类叫BlankSlate, 它最初是由 Jim Weirich构思出来的。 用在这的BlankSlate 和Jim 的有细微的差别，因为我们想要多保留一些功能。 我们将留下七个方法。 你可以试一试看看那些是绝对需要的，那些是用来辅助我们看MyDSL 的对象实例的内容。
% cat mydsl6.rb
require 'dslhelper'
class BlankSlate
instance_methods.each { |m| undef_method(m) unless %w(
__send__ __id__ send class
inspect instance_eval instance_variables
).include?(m)
}
end #class BlankSlate
# MyDSL now inherits from BlankSlate
class MyDSL < BlankSlate
# ... nothing new here, move along...
end#class MyDSL
现在我们试一下加载包含关键字(keyword)的DSL 文件， 我们会看到一些更合理的东西。
% head -1 dsl-loader.rb
require 'mydsl6'
% ruby dsl-loader.rb params_with_keyword.dsl
#["@id", "@methods"]
可以确信， 我们成功了。 这是一个好消息， 我们可以去掉那些没用的方法，给予我们的最终用户更自由的使用参数名字的权利。但是不管怎样，请注意，我们终究不能让最终用户完全自由的使用参数名。这是使用通用编程语言创建DSL的一个缺点， 但我认为，禁止最终用户使用’class’作为参数名，应该不会给我们的产品销路带来多大的风险。
更复杂的DSL
我们现在来实现更复杂的DSL 特性。 不仅仅操作数据，而且要执行更具体的行为。 想象一下我们厌烦了在每次开始一个新的项目的时候，手动的生成一个通用的目录集和文件集。 如果Ruby可以帮我们做这些就好了。更进一步，如果我们有一个小的DSL使得我们可以直接修改项目目录结构而不用去编写低级的代码，岂不更好。
我们现在开始为这个问题定义一个DSL。 下面的文件是这个DSL 的0.01 版本：
% cat project_template.dsl
create_project do
dir "bin" do
create_from_template :exe, name
end
dir "lib" do
create_rb_file name
dir name do
create_rb_file name
end
end
dir "test"
touch :CHANGELOG, :README, :TODO
end
在这个DSL 文件里，我们生成了一个项目，在其中加了三个目录和三个文件。在’bin' 目录中，我们使用’:exe’模板生成了一个与项目名字同名的可执行文件。在’lib’目录，我们生成了一个.rb 文件和一个目录， 都与项目名字同名。在这个内部子目录中，又生成另一个与项目名字同名的’.rb’ 文件。最后，在项目顶级目录下，生成了一个’test’目录，和三个空文件。
这个DSL需要的方法(method) 是：create_project,dir,create_from_template,create_rb_file, 以及 touch。 让我们逐个的看一下这些方法。
方法create_project是最外层的壳（wrapper）。 这个方法提供了一个作用域让我们将所有的DSL代码都放在一个块(block)中。（完整的代码列表请看文章的最后）
def create_project()
yield
end
方法dir 完成实质性的工作。该方法不仅仅生成目录，而且将当前的工作目录保存在实例变量 @cwd中。 在这里，使用ensure 来保证@cwd 的始终有正确的值。
def dir(dir_name)
old_cwd = @cwd
@cwd = File.join(@cwd, dir_name)
FileUtils.mkdir_p(@cwd)
yield self if block_given?
ensure
@cwd = old_cwd
end
方法touch和 create_rb_file基本是一样的，除了后面一个给文件名加了一个后缀’rb’以外。 这些方法可以接受一个或多个文件名，这些名字可以是字符串或符号（symbols）。
def touch(*file_names)
file_names.flatten.each { |file|
FileUtils.touch(File.join(@cwd, "#{file}"))
}
end
最后，方法 create_from_template 是一个粗略的例子用于说明怎么样可以在一个DSL中实现一些实际的功能。(请看代码的完整列表)
为了运行这些代码，我们构建了一个小的测试应用。
% cat create_project.rb
require 'project_builder'
project_name = ARGV.shift
proj = ProjectBuilder.load(project_name)
puts "== DIR TREE OF PROJECT '#{project_name}' =="
puts `find #{project_name}`
运行结果是：
% ruby create_project.rb fred
== DIR TREE OF PROJECT 'fred' ==
fred
fred/bin
fred/bin/fred
fred/CHANGELOG
fred/lib
fred/lib/fred
fred/lib/fred/fred.rb
fred/lib/fred.rb
fred/README
fred/test
fred/TODO
% cat fred/bin/fred
#!/usr/bin/env ruby
require 'rubygems'
require 'commandline
require 'fred'
class FredApp < CommandLine::Application
def initialize
end
def main
end
end#class FredApp
哇！工作得很好。 并且没费多少力气。
总结
我做过的很多项目要求一个非常详细的控制流描述。 在每个项目中，这常常让我停下来并思考怎么将这些详细的配置数据引入到应用（application）中。 现在，Ruby作为一个DSL，几乎是最适合的，而且常常可以非常高效和快速的解决问题。
在培训Ruby 的时候，我会让整个班级用以下方法来解决问题，我们先用英语来描述问题，然后用伪代码，然后用Ruby。但是，在某些情况下，伪代码就是合法的 Ruby 代码。 我认为，Ruby的高度可读性使得 Ruby是一个可用做DSL的理想语言。 当Ruby 为更多的人所了解， 用Ruby 写的DSL 将成为一个与应用通信的流行的方式
项目 ProjectBuilder DSL 的代码列表：
% cat project_builder.rb
require 'fileutils'
class ProjectBuilder
PROJECT_TEMPLATE_DSL = "project_template.dsl"
attr_reader :name
TEMPLATES = {
:exe =>
<<-EOT
#!/usr/bin/env ruby
require 'rubygems'
require 'commandline
require '%name%'
class %name.capitalize%App < CommandLine::Application
def initialize
end
def main
end
end#class %name.capitalize%App
EOT
}
def initialize(name)
@name = name
@top_level_dir = Dir.pwd
@project_dir = File.join(@top_level_dir, @name)
FileUtils.mkdir_p(@project_dir)
@cwd = @project_dir
end
def create_project
yield
end
def self.load(project_name, dsl=PROJECT_TEMPLATE_DSL)
proj = new(project_name)
proj = proj.instance_eval(File.read(dsl), dsl)
proj
end
def dir(dir_name)
old_cwd = @cwd
@cwd = File.join(@cwd, dir_name)
FileUtils.mkdir_p(@cwd)
yield self if block_given?
ensure
@cwd = old_cwd
end
def touch(*file_names)
file_names.flatten.each { |file|
FileUtils.touch(File.join(@cwd, "#{file}"))
}
end
def create_rb_file(file_names)
file_names.each { |file| touch(file + ".rb") }
end
def create_from_template(template_id, filename)
File.open(File.join(@cwd, filename), "w+") { |f|
str = TEMPLATES[template_id]
str.gsub!(/%[^%]+%/) { |m| instance_eval m[1..-2] }
f.puts str
}
end
end#class ProjectBuilder
Execute as:
ruby create-project.rb project_name
资源
- BlankSlate 是一个Ruby class,用于产生没有方法(method-free)的对象实例。 参见：http://onestepback.org/index.cgi/Tech/Ruby/BlankSlate.rdoc
- JimWeirich 是BlankSlate 的创建者，也是很多著名的Ruby 工具和库的创建者。http://onestepback.org
关于作者
Jim Freeze 从2001年初学习Ruby以来，一直是 Ruby 的热爱者。
Jim 是 CommandLine and Stax gems 的作者
