Crafting elegant code with Ruby DSLs - Euruko 2023

Given at Euruko 2023 in Vilnius, Lithuania on 23th of September 2023.

- https://tomdebruijn.com/
- https://twitter.com/tombruijn
- https://mastodon.social/@tombruijn

Transcript

2. / ~130 I love Ruby I can write elegant code The developer in me is happy Doesn't get in my way I can do cool metaprogramming I can be dangerous with Ruby 2
3. I love metaprogramming / ~130 3
4. / ~130 Tom de Bruijn @tombruijn / tomdebruijn.com 4
5. / ~130 5
6. / ~130 6
7. / ~130 Unmaintainable mess Complaints about inaccuracy 7
8. / ~130 module DiagnoseReportPresenter class Config include Validations::ReportValidator SUPPORTED_LOG_LEVELS = ["error", "warn", "info", "debug", "trace"].freeze attr_reader :key, :label def initialize(report) @report = report @key = "config" @label = "Configuration" end def options @options ||= begin is_new_style = report[key].key?("options") option_keys = if is_new_style report.dig(key, "options") || {} else report.dig(key) || {} end clean_up_internal_config_keys!(option_keys) definitions = config_definitions keys = definitions.keys | option_keys.keys keys.map do |option| ConfigOption.new(option, report, definitions.fetch(option, {})) end end end def config_definitions # rubocop:disable return @definitions if @definitions d = {} d["active"] = { :label => "Active", :required => true, :highlight => true, :validate => proc do |option| next if option.value == true option.validations << [:error, "AppSignal is not configured as active."] end } d["name"] = { :label => "App name", :highlight => true, :required => true } if report.elixir? d["otp_app"] = { :label => "OTP app name", :highlight => true, :required => true, :since => { :elixir => "2.0.0" } } end d["log_level"] = { :label => "Log level", :since => { :ruby => "3.0.16", :elixir => "2.2.8", :nodejs => "2.2.6" }, :validate => proc do |option, _report| if option.value? && !SUPPORTED_LOG_LEVELS.include? (option.value) option.validations << [ :error, "Unknown log level. Supported levels: #{SUPPORTED_LOG_LEVELS.join(", ")}" ] end end } # Repeat for every config option end end end 8
9. / ~130 d["active"] = { :label => "App active", :required => true, :highlight => true, :validate => proc do |option| next if option.value == true option.validations << [:error, "not configured as active."] end } 9
10. / ~130 It has to change 10
11. / ~130 Crafting elegant code with Ruby DSLs 11
12. / ~130 What is a DSL? 12 ? ? ?
13. / ~130 Domain Speci fi c Language 13 ? ?
14. / ~130 What Domain? 14
15. Domains you know / ~130 15
16. / ~130 attr_reader :name attr_writer :name attr_accessor :name Getter & setter domain 16
17. / ~130 # Rake task :hello do puts "Hello there" end Gem domain 17
18. / ~130 $ rake hello Hello there 18
19. / ~130 Your app BusinessLogic.do_the_thing! CommentCreator.create MetricsAggregator.new do ... 19
20. / ~130 Terminology and Interaction methods 20
21. Why use a DSL? / ~130 21
22. / ~130 Like an API, but friendlier 22
23. / ~130 window = Engine::Window.new window.add( Engine::Text.new("My game name")) button = Engine::Button.new("Start game") event = Engine::Events::OnClicked .new do |state| state.windows["menu"].navigate end button.add_event(event) window.add(button) window.open window { title "My game name" button do text "Start game" on_clicked do state.windows["menu"].navigate end end }.open API DSL 23
24. / ~130 # config/application.rb class Application < Rails::Application config.load_defaults 7.0 config.time_zone = "UTC" config.app.custom_option = "oh hi!" Easier configuration 24
25. / ~130 No YAML required 😌 25
26. / ~130 class CreateProducts < ActiveRecord::Migration[7.0] def change create_table :products do |t| t.string :name t.text :description t.timestamps end end end Automate writing code 26
27. / ~130 case ARGV.first when "hello" puts "Hello world" when "bye" puts "Goodbye world" end # ruby tasks.rb hello task :hello do puts "Hello world" end task :bye do puts "Goodbye world" end # rake hello Make high churn code more maintainable 27
28. / ~130 Easier for 
 non-developers? 28
29. / ~130 Are all DSLs good? 29
30. / ~130 Make 
 reading and writing 
 code easier 30
31. / ~130 We fear what 
 we don't understand 31
32. / ~130 RSpec.describe Post do context "with comments" do let(:comment) { Comment.new(:body => "hi!") } let(:post) { Post.new(:comments => [comment]) } it "has comments" do expect(post).to have_comments # ... 32
33. / ~130 I love RSpec 33
34. Crafting your own DSL / ~130 34
35. / ~130 d["active"] = { :label => "App active", :required => true, :highlight => true, :validate => proc do |option| next if option.value == true option.validations << [:error, "not active"] end } 35
36. / ~130 Diagnose report 
 representation The Domain of the DSL 36
37. / ~130 attribute :active do label "App active" required message: "is not active" highlight true 
 check do |attr| attr.add_error "custom error" end end 37
38. / ~130 Let's rewrite! 38
39. accessors / ~130 39
40. / ~130 class ConfigReport attr_accessor :active, :name end report = ConfigReport.new report.active = true report.name = "My app" 40
41. / ~130 report.attributes # {:active=>true, :name=>"My app"} 41
42. / ~130 class ConfigReport attr_reader :attributes def initialize @attributes = {} end def active=(value) @attributes[:active] = value end def name=(value) @attributes[:name] = value end # Repeated for a 100 options 42
43. / ~130 def filter_parameters(value) @attributes[:filter_parameters] = value end def hostname(value) @attributes[:hostname] = value end def ignore_errors(value) @attributes[:ignore_errors] = value end def running_in_container(value) @attributes[:running_in_container] = value end def active=(value) @attributes[:active] = value end def name=(value) @attributes[:name] = value end def filter_parameters(value) @attributes[:filter_parameters] = value end def hostname(value) @attributes[:hostname] = value def active=(value) @attributes[:active] = value end def name=(value) @attributes[:name] = value end def filter_parameters(value) @attributes[:filter_parameters] end def hostname(value) @attributes[:hostname] = value end def ignore_errors(value) @attributes[:ignore_errors] = va end def running_in_container(value) @attributes[:running_in_containe end def active=(value) @attributes[:active] = value end def name=(value) @attributes[:name] = value active] = value ) name] = value meters(value) filter_parameters] = value lue) hostname] = value rs(value) ignore_errors] = value container(value) running_in_container] = value ue) active] = value ) name] = value New problem: Methods for every attribute 43
44. Dynamically de fi ne 
 methods / ~130 44
45. / ~130 class ConfigReport def self.attribute(name, metadata = {}) # ... end attribute :active, :label => "App active" 45
46. / ~130 class ConfigReport def self.attribute(name, metadata = {}) define_method name do @attributes[name] end # ... end attribute :active, :label => "App active" 46 define_method name do @attributes[name] end
47. / ~130 define_method :my_method do |arg| puts arg end def my_method(arg) puts arg end 47
48. / ~130 class ConfigReport def self.attribute(name, metadata = {}) define_method name do @attributes[name] end define_method "#{name}=" do |value| @attributes[name] = { :value => value }.merge(config) end end attribute :active, :label => "App active" 48 [:value] define_method "#{name}=" do |value| @attributes[name] = { :value => value }.merge(metadata) end
49. / ~130 report = ConfigReport.new report.active = true report.active # true report.attributes { :active => { :value=>true, :label=>"App active" } } 49
50. Using Blocks / ~130 50
51. / ~130 [1, 2, 3].each do |i| puts i end We use blocks all the time 51
52. / ~130 class ConfigReport attribute :active do |attr| # ... end 52
53. / ~130 class ConfigReport def self.attribute(name) attr = Attribute.new yield attr # ... 53 attr = AttributeDSL.new yield attr
54. / ~130 class ConfigReport attribute :active do |attr| end 54 |attr| attr.label = "App active"
55. DSL class / ~130 55
56. / ~130 class AttributeDSL def self.def_metadata(*metadata) # define_method ... end def_metadata :label, :required 56
57. / ~130 # config/puma.rb workers 3 preload_app! # puma/lib/puma/dsl.rb Puma::DSL 57
58. / ~130 class ConfigReport attribute :active do # attr.label = "Active" label "App active" end 58
59. / ~130 class ConfigReport def self.attribute(name, &block) attr = AttributeDSL.new attr.instance_eval(&block) # ... 59 &block attr.instance_eval(&block)
60. / ~130 class ConfigReport attribute :active do self == #<AttributeDSL:...> end 60
61. / ~130 class ConfigReport attribute :active do label "App active" end 61
62. / ~130 attr = AttributeDSL.new attr.label "App active" 62
63. / ~130 Which one to use? Mostly personal preference 63
64. / ~130 attribute :active do check do |attr| if attr.value == false end end 64 check do |attr| if attr.value == false attr.add_error "Some error" end end
65. / ~130 class AttributeDSL def self.check(&block) @checks << block end # ... @checks.each do |check| check.call(attribute) end 65
66. / ~130 Check-in halfway-ish point 66
67. / ~130 class ConfigReport attribute :active do label "Active" end end 67
68. / ~130 MyGem.configure do |config| config.time_zone = "UTC" end 68
69. / ~130 Error: 
 Missing business logic 69
70. / ~130 Metadata per report 70
71. / ~130 class ConfigReport < Report attribute :active do required true end class LanguageReport < Report attribute :otp_version do package :elixir end 71
72. Modules to extend or include / ~130 72
73. / ~130 Module.extend: 
 Class level code inclusion MyClass.extend MyModule MyClass.module_method 73
74. / ~130 Module.include: 
 Instance level code inclusion MyClass.include MyModule MyClass.new.module_method 74
75. / ~130 class ConfigReport::Attribute extend Metadata def_metadata :label class LanguageReport::Attribute extend Metadata def_metadata :package 75
76. / ~130 Dynamically extend your DSL, with a DSL 76
77. / ~130 Extend with Plugins 77
78. / ~130 class LabelPlugin < Plugin metadata :label 78
79. / ~130 class LabelPlugin < Plugin metadata :label class ConfigReport < Report plugin LabelPlugin attribute :name do label "App version" end 79
80. / ~130 class RequiredPlugin < Plugin metadata :required check do |attr, required:| next unless required
 next if attr.value attr.add_error "value not set" end end 80
81. / ~130 Less gem bloat Less maintenance More customizability 81
82. / ~130 To make plugins, 
 let's simplify a bit 82
83. / ~130 class MyAttribute extend Metadata def_metadata :label 83
84. / ~130 class MyAttribute extend Metadata.define(:label, :required) 84
85. / ~130 module Metadata def self.define(*metadata) mod = Module.new # ... mod # Returns the module end 85
86. / ~130 mod = Module.new
 =~ 
 mod = module ... end. 86
87. / ~130 Anonymous Module 
 =~ 
 A Module without a constant 87
88. / ~130 class MyAttribute extend Module.new 88
89. / ~130 module Metadata def self.define(*metadata) mod = Module.new metadata.each do |option| mod.define_method option do |value| @metadata[option] = value end end mod end 89 mod = Module.new mod.define_method option do |value| @metadata[option] = value end mod
90. / ~130 class MyAttribute extend Metadata.define(:label, :required) module "AnonymousModule" def label(value) @metadata[:label] = value end def required(value) @metadata[:required] = value end end 90
91. / ~130 module "AnonymousModule" def label(value) @metadata[:label] = value end def required(value) @metadata[:required] = value end end class MyAttribute extend "AnonymousModule" end 91
92. / ~130 module "AnonymousModule" # ... end class MyAttribute def self.label(value) @metadata[:label] = value end
 
 def self.required(value) @metadata[:required] = value end end 92
93. / ~130 Advantage #1: 
 Easy to reuse everywhere 93 extend Metadata.define(:label, :required)
94. / ~130 Advantage #2: 
 No de fi nition logic in the class itself 94 No define method on the Attribute class
95. Module builder pattern / ~130 95 dejimata.com/2017/5/20/the-ruby-module-builder-pattern
96. / ~130 Let's make plugins 96
97. / ~130 class Report def self.plugin(*plugs) Attribute.plugin(*plugs) end class ConfigReport < Report plugin LabelPlugin class LanguageReport < Report plugin PackagePlugin 97
98. / ~130 class ConfigReport < Report plugin LabelPlugin attribute :active do label "App active" end end class LanguageReport < Report attribute :otp_version do label "OTP version" # Doesn't error end end 98
99. / ~130 class Report def self.plugin(*plugs) Attribute.plugin(*plugs) end 99 Attribute
100. / ~130 class Report def self.plugin(*plugs) @plugins ||= [] @plugins |= plugs end Register plugins 100
101. / ~130 101 class Report def self.attribute(name, &block) definition = Class.new(Attribute) definition.plugin(*plugins) definition.instance_eval(&block)
102. Dynamically create classes / ~130 102
103. / ~130 c = Class.new(Attribute)
 =~ 
 c = class ... < Attribute 103
104. / ~130 104 class Report def self.attribute(name, &block) definition = Class.new(Attribute) definition.plugin(*plugins) definition.instance_eval(&block)
105. / ~130 class Attribute def self.plugin(*plugs) plugs.each do |plug| extend plug.class_dsl include plug.instance_dsl end end 105
106. / ~130 class Plugin def self.class_dsl mod = Module.new # ... mod # Return the module end 106
107. / ~130 class Plugin def self.class_dsl mod = Module.new metadata.each_key do |option| mod.define_method option do |value| @metadata[option] = value end end mod end 107 mod = Module.new mod.define_method option do |value| @metadata[option] = value end mod
108. / ~130 🥁 108
109. / ~130 class ConfigReport < Report plugin LabelPlugin, RequiredPlugin attribute :active do label "App active" required :message => "App is not active!" end end class LanguageReport < Report plugin PackagePlugin attribute :otp_version do package :elixir => "1.2.3" end end 109
110. / ~130 class ConfigReport < Report plugin LabelPlugin, RequiredPlugin attribute :active do label "App active" required :message => "App is not active!" end end class LanguageReport < Report plugin PackagePlugin attribute :otp_version do package :elixir => "1.2.3" end end 110 class ConfigReport < Report plugin LabelPlugin, RequiredPlugin 
 
 
 
 class LanguageReport < Report plugin PackagePlugin
111. / ~130 class ConfigReport < Report plugin LabelPlugin, RequiredPlugin attribute :active do label "App active" required :message => "App is not active!" end end class LanguageReport < Report plugin PackagePlugin attribute :otp_version do package :elixir => "1.2.3" end end 111 attribute :active do label "App active" required :message => "App is not active!" end attribute :otp_version do package :elixir => "1.2.3" end
112. / ~130 DSL done! 112
113. / ~130 What did I learn? 113
114. / ~130 Using the same tools, 
 for di ff erent purposes 114
115. / ~130 Ruby gem for instrumentation: Be invisible 115
116. / ~130 DSL: 
 Friendly interactions 116
117. / ~130 I love Ruby more I can write elegant code Write my own DSLs I can build cool things with metaprogramming 117
118. / ~130 What did you learn? 118
119. / ~130 Why to use a DSL 119
120. / ~130 How DSLs work 120
121. / ~130 New metaprogramming techniques 121
122. / ~130 Don't fear metaprogramming & DSLs 122
123. / ~130 Meta programming is just programming and it's readable - Masafumi Okura 123
124. / ~130 d["active"] = { :label => "App active", :required => true, :highlight => true, :validate => proc do |option| next if option.value == true option.validations << [:error, "not configured as active."] end } 124
125. / ~130 class ConfigReport < Report plugin LabelPlugin, RequiredPlugin attribute :options do label "Config options" attribute :active do # nested attributes! label "App active" required :message => "App is not active!" end end end 125
126. / ~130 Our toolbox • accessors • de fi ne_method • Ruby blocks • yield • .instance_eval • .call • DSL classes • Modules • Share behavior between classes • Module builder pattern • Dynamic Class and Module creation • Plugins 126
127. / ~130 You are ready to make your own DSL! 127
128. / ~130 github.com/tombruijn/schema 128
129. / ~130 Help me think of a Ruby Gem name 129
130. / ~130 Thank you! @tombruijn / tomdebruijn.com 
 
 
 Come say hi! 👋 130 DSL DS