Class: DSLCompose::DSL

Inherits:
Object
  • Object
show all
Defined in:
lib/dsl_compose/dsl.rb,
lib/dsl_compose/dsl/arguments.rb,
lib/dsl_compose/dsl/dsl_method.rb,
lib/dsl_compose/dsl/interpreter.rb,
lib/dsl_compose/dsl/arguments/argument.rb,
lib/dsl_compose/dsl/dsl_method/interpreter.rb,
lib/dsl_compose/dsl/arguments/argument/interpreter.rb,
lib/dsl_compose/dsl/arguments/argument/in_validation.rb,
lib/dsl_compose/dsl/arguments/argument/is_a_validation.rb,
lib/dsl_compose/dsl/arguments/argument/format_validation.rb,
lib/dsl_compose/dsl/arguments/argument/length_validation.rb,
lib/dsl_compose/dsl/arguments/argument/not_in_validation.rb,
lib/dsl_compose/dsl/arguments/argument/end_with_validation.rb,
lib/dsl_compose/dsl/arguments/argument/equal_to_validation.rb,
lib/dsl_compose/dsl/arguments/argument/less_than_validation.rb,
lib/dsl_compose/dsl/arguments/argument/start_with_validation.rb,
lib/dsl_compose/dsl/arguments/argument/greater_than_validation.rb,
lib/dsl_compose/dsl/arguments/argument/not_end_with_validation.rb,
lib/dsl_compose/dsl/arguments/argument/not_start_with_validation.rb,
lib/dsl_compose/dsl/arguments/argument/less_than_or_equal_to_validation.rb,
lib/dsl_compose/dsl/arguments/argument/greater_than_or_equal_to_validation.rb

Overview

The class is reponsible for creating and representing a dynamic DSL

These new dynamic DSL’s are created using our own internal DSL, which is accessed by calling ‘define_dsl` in a class and passing it a block which contains the DSL definition

Defined Under Namespace

Classes: Arguments, DSLMethod, DescriptionAlreadyExistsError, Interpreter, InvalidDescriptionError, InvalidNameError, InvalidNamespaceError, InvalidTitleError, MethodAlreadyExistsError, MethodDoesNotExistError, NamespaceAlreadyExistsError, NoBlockProvidedError, TitleAlreadyExistsError

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(name, klass) ⇒ DSL

Create a new DSL object with the provided name and class.

‘name` must be a symbol. `klass` should be the class in which `define_dsl` is being called.



59
60
61
62
63
64
65
66
67
68
69
70
71
 
# File 'lib/dsl_compose/dsl.rb', line 59

def initialize name, klass
  @dsl_methods = {}

  @arguments = Arguments.new

  if name.is_a? Symbol
    @name = name
  else
    raise InvalidNameError, "The DSL name `#{name}` is invalid, it must be of type symbol"
  end

  @klass = klass
end

Instance Attribute Details

#arguments ⇒ Object (readonly)

an object which represents the argument configuration



53
54
55
 
# File 'lib/dsl_compose/dsl.rb', line 53

def arguments
  @arguments
end

#description ⇒ Object (readonly)

An otional description of this DSL, if provided then it must be a string. The description accepts markdown and is used when generating documentation.



45
46
47
 
# File 'lib/dsl_compose/dsl.rb', line 45

def description
  @description
end

#klass ⇒ Object (readonly)

klass will be the class where ‘define_dsl` was called.



42
43
44
 
# File 'lib/dsl_compose/dsl.rb', line 42

def klass
  @klass
end

#name ⇒ Object (readonly)

The name of this DSL.



40
41
42
 
# File 'lib/dsl_compose/dsl.rb', line 40

def name
  @name
end

#namespace ⇒ Object (readonly)

An otional namespace for this DSL, if provided then it must be a Symbol. This is currently used to group DSLs for the sake of documentation.



48
49
50
 
# File 'lib/dsl_compose/dsl.rb', line 48

def namespace
  @namespace
end

#title ⇒ Object (readonly)

An otional namespace for this DSL, if provided then it must be a String. This is currently used when generating documentation.



51
52
53
 
# File 'lib/dsl_compose/dsl.rb', line 51

def title
  @title
end

Instance Method Details

#add_method(name, unique, required, &block) ⇒ Object

Takes a method name, unique flag, required flag, and a block and creates a new DSLMethod object.

Method ‘name` must be unique within the DSL.



159
160
161
162
163
164
165
 
# File 'lib/dsl_compose/dsl.rb', line 159

def add_method name, unique, required, &block
  if has_dsl_method? name
    raise MethodAlreadyExistsError, "The method `#{name}` already exists for this DSL"
  end

  @dsl_methods[name] = DSLMethod.new(name, unique, required, &block)
end

#dsl_method(name) ⇒ Object

returns a specific DSLMethod by it’s name, if the DSLMethod does not exist, then an error is raised



199
200
201
202
203
204
205
 
# File 'lib/dsl_compose/dsl.rb', line 199

def dsl_method name
  if has_dsl_method? name
    @dsl_methods[name]
  else
    raise MethodDoesNotExistError, "The method `#{name}` does not exist for this DSL"
  end
end

#dsl_methods ⇒ Object

Returns an array of all this DSLs DSLMethods.



168
169
170
 
# File 'lib/dsl_compose/dsl.rb', line 168

def dsl_methods
  @dsl_methods.values
end

#evaluate_configuration_block(&block) ⇒ Object

Evaluate the configuration block which defines our new DSL ‘block` contains the DSL definition and will be evaluated to create the rest of the DSL.



76
77
78
79
80
81
82
83
84
85
86
87
88
 
# File 'lib/dsl_compose/dsl.rb', line 76

def evaluate_configuration_block &block
  if block
    # We evaluate the internal DSL configuration blocks using a seperate interpreter
    # class. We do this because the interpreter class contains no other methods or
    # variables, if it was evaluated in the context of this class then the block
    # would have access to all of the methods defined in here.
    Interpreter.new(self).instance_eval(&block)
  else
    raise NoBlockProvidedError, "No block was provided for this DSL"
  end
rescue => e
  raise e, "Error defining DSL #{@name} on #{@klass}: #{e.message}", e.backtrace
end

#has_description? ⇒ Boolean

Returns ‘true` if this DSL has a description, else false.

Returns:

  • (Boolean) 


141
142
143
 
# File 'lib/dsl_compose/dsl.rb', line 141

def has_description?
  @description.nil? == false
end

#has_dsl_method?(name) ⇒ Boolean

Returns ‘true` if a DSLMethod with the provided name exists in this DSL, otherwise it returns `false`.

Returns:

  • (Boolean) 


209
210
211
 
# File 'lib/dsl_compose/dsl.rb', line 209

def has_dsl_method? name
  @dsl_methods.key? name
end

#has_methods? ⇒ Boolean

does this DSL have any methods

Returns:

  • (Boolean) 


173
174
175
 
# File 'lib/dsl_compose/dsl.rb', line 173

def has_methods?
  dsl_methods.any?
end

#has_namespace? ⇒ Boolean

Returns ‘true` if this DSL has a namespace, else false.

Returns:

  • (Boolean) 


146
147
148
 
# File 'lib/dsl_compose/dsl.rb', line 146

def has_namespace?
  @namespace.nil? == false
end

#has_optional_methods? ⇒ Boolean

does this DSL have any optional methods

Returns:

  • (Boolean) 


183
184
185
 
# File 'lib/dsl_compose/dsl.rb', line 183

def has_optional_methods?
  optional_dsl_methods.any?
end

#has_required_methods? ⇒ Boolean

does this DSL have any required methods

Returns:

  • (Boolean) 


178
179
180
 
# File 'lib/dsl_compose/dsl.rb', line 178

def has_required_methods?
  required_dsl_methods.any?
end

#has_title? ⇒ Boolean

Returns ‘true` if this DSL has a title, else false.

Returns:

  • (Boolean) 


151
152
153
 
# File 'lib/dsl_compose/dsl.rb', line 151

def has_title?
  @title.nil? == false
end

#optional_dsl_methods ⇒ Object

Returns an array of only the optional DSLMethods in this DSL.



193
194
195
 
# File 'lib/dsl_compose/dsl.rb', line 193

def optional_dsl_methods
  dsl_methods.filter(&:optional?)
end

#required_dsl_methods ⇒ Object

Returns an array of only the required DSLMethods in this DSL.



188
189
190
 
# File 'lib/dsl_compose/dsl.rb', line 188

def required_dsl_methods
  dsl_methods.filter(&:required?)
end

#set_description(description) ⇒ Object

Set the description for this DSL to the provided value.

‘description` must be a string with a length greater than 0. The `description` can only be set once per DSL



94
95
96
97
98
99
100
101
102
103
104
 
# File 'lib/dsl_compose/dsl.rb', line 94

def set_description description
  unless description.is_a?(String) && description.strip.length > 0
    raise InvalidDescriptionError, "The DSL description `#{description}` is invalid, it must be of type string and have length greater than 0"
  end

  if has_description?
    raise DescriptionAlreadyExistsError, "The DSL description has already been set"
  end

  @description = description.strip
end

#set_namespace(namespace) ⇒ Object

Set the namespace for this DSL to the provided value.

‘namespace` must be a Symbol. The `namespace` can only be set once per DSL this is currently used for grouping together DSLS for the sake of documentation



111
112
113
114
115
116
117
118
119
120
121
 
# File 'lib/dsl_compose/dsl.rb', line 111

def set_namespace namespace
  unless namespace.is_a?(Symbol)
    raise InvalidNamespaceError, "The DSL namespace `#{namespace}` is invalid, it must be of type Symbol"
  end

  if has_namespace?
    raise NamespaceAlreadyExistsError, "The DSL namespace has already been set"
  end

  @namespace = namespace
end

#set_title(title) ⇒ Object

Set the title for this DSL to the provided value.

‘title` must be a String with a length greater than 0. The `title` can only be set once per DSL this is currently used for documentation



128
129
130
131
132
133
134
135
136
137
138
 
# File 'lib/dsl_compose/dsl.rb', line 128

def set_title title
  unless title.is_a?(String) && title.strip.length > 0
    raise InvalidTitleError, "The DSL title `#{title}` is invalid, it must be of type string and have length greater than 0"
  end

  if has_title?
    raise TitleAlreadyExistsError, "The DSL title has already been set"
  end

  @title = title.strip
end