Module: IS::DSL

Defined in:
lib/is-dsl.rb

Overview

DSL Facade module for encapsulating methods and constants from external sources.

Provides a clean API for Domain Specific Language (DSL) creation by delegating functionality from other modules/classes to the main facade and its private shadow module.

Examples:

module MyDSL
  extend IS::DSL
  encapsulate SomeAPI, :get, :post, new: :create
end

MyDSL.get(url)  # => delegates to SomeAPI.get(url)

Instance Method Summary collapse

Instance Method Details

#attach_to(mod, nm = self.name) ⇒ self Also known as: >>

Attaches the shadow module as a constant to the target module/class.

Examples:

module Target; end
module DSL; extend IS::DSL; end
DSL.attach_to Target           # Target::DSL = DSL.shadow
DSL.attach_to Target, :Facade  # Target::Facade = DSL.shadow (alias)
DSL >> Target                  # Target::DSL = DSL.shadow

Parameters:

  • mod (Module, Class) —

    target module or class

  • nm (String, Symbol) (defaults to: self.name) —

    constant name (defaults to name)

Returns:

  • (self) 


33
34
35
 
# File 'lib/is-dsl.rb', line 33

def attach_to mod, nm = self.name
  mod.const_set nm, shadow
end

#encapsulate(src, *names, **aliases) ⇒ self

Encapsulates constants and methods from src into both main module and shadow.

Examples:

encapsulate HTTP, :get, :post, new: :create
self.get(url)     # => HTTP.get(url)
self.create       # => HTTP.new

Parameters:

  • src (Module, Class, Object) —

    source of methods/constants

  • names (Array<String or Symbol>) —

    names of methods/constants to copy

  • aliases (Hash{String or Symbol => String or Symbol}) —

    aliases (key=source name, value=new name)

Returns:

  • (self)

See Also:



54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
 
# File 'lib/is-dsl.rb', line 54

def encapsulate src, *names, **aliases
  names.each do |nm|
    if nm[0] >= 'A' && nm[0] <= 'Z'
      value = fetch_const src, nm
      const_set nm, value
      shadow.const_set nm, value
    else
      sym = nm.to_sym
      define_function self, src, sym, sym
      define_function shadow, src, sym, sym
    end
  end
  aliases.each do |nm, als|
    if nm[0] >= 'A' && nm[0] <= 'Z'
      value = fetch_const src, nm
      const_set als, value
      shadow.const_set als, value
    else
      sym = als.to_sym
      define_function self, src, sym, nm
      define_function shadow, src, sym, nm
    end
  end
  self
end

#encapsulate_all(src) ⇒ self

Encapsulates all public constants and singleton methods from source.

Parameters:

  • src (Module, Class, Object) —

    source

Returns:

  • (self)

See Also:



154
155
156
157
 
# File 'lib/is-dsl.rb', line 154

def encapsulate_all src
  encapsulate_constants src
  encapsulate_methods src
end

#encapsulate_constants(src) ⇒ self

Encapsulates all public constants.

Parameters:

  • src (Module, Class, Object) —

    source

Returns:

  • (self) 


163
164
165
166
167
168
169
170
 
# File 'lib/is-dsl.rb', line 163

def encapsulate_constants src
  list = if Module === src
    src.constants false
  else
    src.class.constants false
  end
  encapsulate src, *list unless list.nil? || list.empty?
end

#encapsulate_methods(src) ⇒ self

Encapsulates all public singleton methods.

Parameters:

  • src (Module, Class, Object) —

    source

Returns:

  • (self) 


176
177
178
179
 
# File 'lib/is-dsl.rb', line 176

def encapsulate_methods src
  list = src.singleton_methods false
  encapsulate src, *list unless list.nil? || list.empty?
end

#lazy_encapsulate(*names, **aliases, &block) ⇒ self

Lazy encapsulates methods with singleton instance pattern.

Examples:

lazy_encapsulate :get_report do
  ReportManager.instance  # called ONCE
end

Parameters:

  • names (Array<String or Symbol>) —

    names of methods/constants to copy

  • aliases (Hash{String or Symbol => String or Symbol}) —

    aliases (key=source name, value=new name)

Yield Returns:

  • (Object) —

    object with methods (called once per method)

Returns:

  • (self) 


119
120
121
122
123
124
125
126
127
128
129
130
131
 
# File 'lib/is-dsl.rb', line 119

def lazy_encapsulate *names, **aliases, &block
  names.each do |nm|
    sym = nm.to_sym
    define_lazy_function self, sym, sym, &block
    define_lazy_function shadow, sym, sym, &block
  end
  aliases.each do |nm, als|
    sym = als.to_sym
    define_lazy_function self, sym, nm, &block
    define_lazy_function shadow, sym, nm, &block
  end
  self
end

#shadow_encapsulate(src, *names, **aliases) ⇒ self

Encapsulates into shadow module only (not main module).

Parameters:

  • src (Module, Class, Object) —

    source of methods/constants

  • names (Array<String or Symbol>) —

    names of methods/constants to copy

  • aliases (Hash{String or Symbol => String or Symbol}) —

    aliases (key=source name, value=new name)

Returns:

  • (self) 


85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
 
# File 'lib/is-dsl.rb', line 85

def shadow_encapsulate src, *names, **aliases
  names.each do |nm|
    if nm[0] >= 'A' && nm[0] <= 'Z'
      value = fetch_const src, nm
      shadow.const_set nm, value
    else
      sym = nm.to_sym
      define_function shadow, src, sym, sym
    end
  end
  aliases.each do |nm, als|
    if nm[0] >= 'A' && nm[0] <= 'Z'
      value = fetch_const src, nm
      shadow.const_set als, value
    else
      sym = als.to_sym
      define_function shadow, src, sym, nm
    end
  end
  self
end

#shadow_encapsulate_all(src) ⇒ self

Shadow version of #encapsulate_all

Parameters:

  • src (Module, Class, Object) —

    source

Returns:

  • (self) 


185
186
187
188
 
# File 'lib/is-dsl.rb', line 185

def shadow_encapsulate_all src
  shadow_encapsulate_constants src
  shadow_encapsulate_methods src
end

#shadow_encapsulate_constants(src) ⇒ self

Shadow version of #encapsulate_constants

Parameters:

  • src (Module, Class, Object) —

    source

Returns:

  • (self) 


194
195
196
197
198
199
200
201
 
# File 'lib/is-dsl.rb', line 194

def shadow_encapsulate_constants src
  list = if Module === src
    src.constants false
  else
    src.class.constants false
  end
  shadow_encapsulate src, *list unless list.nil? || list.empty?
end

#shadow_encapsulate_methods(src) ⇒ self

Shadow version of #encapsulate_methods

Parameters:

  • src (Module, Class, Object) —

    source

Returns:

  • (self) 


207
208
209
210
 
# File 'lib/is-dsl.rb', line 207

def shadow_encapsulate_methods src
  list = src.singleton_methods false
  shadow_encapsulate src, *list unless list.nil? || list.empty?
end

#shadow_lazy_encapsulate(*names, **aliases, &block) ⇒ self

Lazy encapsulation into shadow only.

Parameters:

  • names (Array<String or Symbol>) —

    names of methods/constants to copy

  • aliases (Hash{String or Symbol => String or Symbol}) —

    aliases (key=source name, value=new name)

Returns:

  • (self) 


137
138
139
140
141
142
143
144
145
146
 
# File 'lib/is-dsl.rb', line 137

def shadow_lazy_encapsulate *names, **aliases, &block
  names.each do |nm|
    sym = nm.to_sym
    define_lazy_function shadow, sym, sym, &block
  end
  aliases.each do |nm, als|
    sym = als.to_sym
    define_lazy_function shadow, sym, nm, &block
  end
end