Module: Verquest::Base::PrivateClassMethods Private

Included in:
Verquest::Base
Defined in:
lib/verquest/base/private_class_methods.rb

Overview

This module is part of a private API. You should avoid using this module if possible, as it may be removed or be changed in the future.

Private class methods for Verquest::Base

This module contains internal class methods used by the versioning system that are not intended for direct use by client code.

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#current_scope ⇒ Verquest::Version, Verquest::Properties::Object (readonly, private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns The current scope being defined.

Returns:



30
31
32
 
# File 'lib/verquest/base/private_class_methods.rb', line 30

def current_scope
  @current_scope
end

#default_options ⇒ Hash (readonly, private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Default options used when using teh with_options method.

Returns:

  • (Hash) —

    Default options for property definitions



34
35
36
 
# File 'lib/verquest/base/private_class_methods.rb', line 34

def default_options
  @default_options
end

Instance Method Details

#array(name, type:, required: nil, nullable: nil, map: nil, item_schema_options: {}, **schema_options) ⇒ void (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Defines a new array property for the current version scope

Parameters:

  • name (Symbol) —

    The name of the array property

  • type (Symbol) —

    The data type of the array elements

  • required (Boolean, Array<Symbol>) (defaults to: nil) —

    Whether the array property is required

  • nullable (Boolean) (defaults to: nil) —

    Whether this array can be null

  • map (String, nil) (defaults to: nil) —

    An optional mapping to another array property

  • item_schema_options (Hash) (defaults to: {}) —

    Additional JSON schema options for the array items (merged with custom type options)

  • schema_options (Hash) —

    Additional schema options for the array property



271
272
273
274
275
276
277
278
279
280
281
 
# File 'lib/verquest/base/private_class_methods.rb', line 271

def array(name, type:, required: nil, nullable: nil, map: nil, item_schema_options: {}, **schema_options)
  camelize(schema_options)

  type = default_options.fetch(:type, type)
  required = default_options.fetch(:required, false) if required.nil?
  nullable = default_options.fetch(:nullable, false) if nullable.nil?
  schema_options = default_options.except(:type, :required, :nullable).merge(schema_options)

  array = Properties::Array.new(name:, type:, required:, nullable:, map:, item_schema_options:, **schema_options)
  current_scope.add(array)
end

#collection(name, item: nil, required: nil, nullable: nil, map: nil, **schema_options) { ... } ⇒ void (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Defines a new collection for the current version scope

Parameters:

  • name (Symbol) —

    The name of the collection

  • item (Class, nil) (defaults to: nil) —

    The item type in the collection

  • required (Boolean, Array<Symbol>) (defaults to: nil) —

    Whether the collection is required

  • nullable (Boolean) (defaults to: nil) —

    Whether the collection can be null

  • map (String, nil) (defaults to: nil) —

    An optional mapping to another collection

  • schema_options (Hash) —

    Additional schema options for the collection

Yields:

  • Block executed in the context of the new collection definition



219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
 
# File 'lib/verquest/base/private_class_methods.rb', line 219

def collection(name, item: nil, required: nil, nullable: nil, map: nil, **schema_options, &block)
  if item.nil? && !block_given?
    raise ArgumentError, "item must be provided or a block must be given to define the collection"
  elsif !item.nil? && !block_given? && !(item <= Verquest::Base)
    raise ArgumentError, "item must be a child of Verquest::Base class or nil" unless type.is_a?(Verquest::Properties::Base)
  end

  camelize(schema_options)
  required = default_options.fetch(:required, false) if required.nil?
  nullable = default_options.fetch(:nullable, false) if nullable.nil?
  schema_options = default_options.except(:required, :nullable).merge(schema_options)

  collection = Properties::Collection.new(name:, item:, required:, nullable:, map:, **schema_options)
  current_scope.add(collection)

  if block_given?
    previous_scope = current_scope
    @current_scope = collection

    instance_exec(&block)
  end
ensure
  @current_scope = previous_scope if block_given?
end

#const(name, value:, map: nil, required: nil, **schema_options) ⇒ void (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Defines a new constant property for the current version scope

Parameters:

  • name (Symbol) —

    The name of the constant

  • value (Object) —

    The value of the constant

  • map (String, nil) (defaults to: nil) —

    An optional mapping to another constant

  • required (Boolean, Array<Symbol>) (defaults to: nil) —

    Whether the constant is required

  • schema_options (Hash) —

    Additional schema options for the constant



169
170
171
172
173
174
175
 
# File 'lib/verquest/base/private_class_methods.rb', line 169

def const(name, value:, map: nil, required: nil, **schema_options)
  camelize(schema_options)
  required = default_options.fetch(:required, false) if required.nil?

  const = Properties::Const.new(name:, value:, map:, required:, **schema_options)
  current_scope.add(const)
end

#description(text) ⇒ void (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Sets the description for the current version scope or globally

Parameters:

  • text (String) —

    The description text

Raises:

  • (RuntimeError) —

    If called outside of a version scope



76
77
78
79
80
81
82
83
84
 
# File 'lib/verquest/base/private_class_methods.rb', line 76

def description(text)
  if current_scope.nil?
    versions.description = text
  elsif current_scope.is_a?(Version)
    current_scope.description = text
  else
    raise "Description can only be set within a version scope or globally"
  end
end

#enum(name, values:, map: nil, required: nil, nullable: nil, **schema_options) ⇒ void (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Defines a new enum property for the current version scope

Parameters:

  • name (Symbol) —

    The name of the enum

  • values (Array) —

    The possible values for the enum

  • map (String, nil) (defaults to: nil) —

    An optional mapping to another property

  • required (Boolean, Array<Symbol>) (defaults to: nil) —

    Whether the enum is required

  • nullable (Boolean) (defaults to: nil) —

    Whether the enum can be null

  • schema_options (Hash) —

    Additional schema options for the enum



150
151
152
153
154
155
156
157
158
159
 
# File 'lib/verquest/base/private_class_methods.rb', line 150

def enum(name, values:, map: nil, required: nil, nullable: nil, **schema_options)
  camelize(schema_options)

  required = default_options.fetch(:required, false) if required.nil?
  nullable = default_options.fetch(:nullable, false) if nullable.nil?
  schema_options = default_options.except(:required, :nullable).merge(schema_options)

  enum_property = Properties::Enum.new(name:, values:, map:, required:, nullable:, **schema_options)
  current_scope.add(enum_property)
end

#exclude_properties(*names) ⇒ void (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Excludes specified properties from the current scope by removing them from the version’s property set

Parameters:

  • names (Array<Symbol>) —

    The names of the properties to exclude



288
289
290
291
292
 
# File 'lib/verquest/base/private_class_methods.rb', line 288

def exclude_properties(*names)
  names.each do |name|
    current_scope.remove(name)
  end
end

#field(name, type: nil, map: nil, required: nil, nullable: nil, **schema_options) ⇒ void (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Defines a new field for the current version scope

Parameters:

  • name (Symbol) —

    The name of the field

  • type (Symbol) (defaults to: nil) —

    The data type of the field

  • map (String, nil) (defaults to: nil) —

    An optional mapping to another field

  • required (Boolean, Array<Symbol>) (defaults to: nil) —

    Whether the field is required

  • nullable (Boolean) (defaults to: nil) —

    Whether the field can be null

  • schema_options (Hash) —

    Additional schema options for the field



129
130
131
132
133
134
135
136
137
138
139
 
# File 'lib/verquest/base/private_class_methods.rb', line 129

def field(name, type: nil, map: nil, required: nil, nullable: nil, **schema_options)
  camelize(schema_options)

  type = default_options.fetch(:type, type)
  required = default_options.fetch(:required, false) if required.nil?
  nullable = default_options.fetch(:nullable, false) if nullable.nil?
  schema_options = default_options.except(:type, :required, :nullable).merge(schema_options)

  field = Properties::Field.new(name:, type:, map:, required:, nullable:, **schema_options)
  current_scope.add(field)
end

#object(name, map: nil, required: nil, nullable: nil, **schema_options) { ... } ⇒ void (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Defines a new object for the current version scope

Parameters:

  • name (Symbol) —

    The name of the object

  • map (String, nil) (defaults to: nil) —

    An optional mapping to another object

  • required (Boolean, Array<Symbol>) (defaults to: nil) —

    Whether the object is required

  • nullable (Boolean) (defaults to: nil) —

    Whether the object can be null

  • schema_options (Hash) —

    Additional schema options for the object

Yields:

  • Block executed in the context of the new object definition



186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
 
# File 'lib/verquest/base/private_class_methods.rb', line 186

def object(name, map: nil, required: nil, nullable: nil, **schema_options, &block)
  unless block_given?
    raise ArgumentError, "a block must be given to define the object"
  end

  camelize(schema_options)
  required = default_options.fetch(:required, false) if required.nil?
  nullable = default_options.fetch(:nullable, false) if nullable.nil?
  schema_options = default_options.except(:type, :required, :nullable).merge(schema_options)

  object = Properties::Object.new(name:, map:, required:, nullable:, **schema_options)
  current_scope.add(object)

  if block_given?
    previous_scope = current_scope
    @current_scope = object

    instance_exec(&block)
  end
ensure
  @current_scope = previous_scope if block_given?
end

#reference(name, from:, property: nil, map: nil, required: nil, nullable: nil) ⇒ void (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Defines a new reference for the current version scope

Parameters:

  • name (Symbol) —

    The name of the reference

  • from (Verquest::Base) —

    The source of the reference

  • property (Symbol, nil) (defaults to: nil) —

    An optional specific property to reference

  • map (String, nil) (defaults to: nil) —

    An optional mapping to another reference

  • required (Boolean, Array<Symbol>) (defaults to: nil) —

    Whether the reference is required

  • nullable (Boolean) (defaults to: nil) —

    Whether this reference can be null



253
254
255
256
257
258
259
 
# File 'lib/verquest/base/private_class_methods.rb', line 253

def reference(name, from:, property: nil, map: nil, required: nil, nullable: nil)
  required = default_options.fetch(:required, false) if required.nil?
  nullable = default_options.fetch(:nullable, false) if nullable.nil?

  reference = Properties::Reference.new(name:, from:, property:, map:, required:, nullable:)
  current_scope.add(reference)
end

#resolve(version) ⇒ Verquest::Version

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Resolves the version to use, either from the provided version, configuration’s current_version, or raises an error if none is available

Parameters:

  • version (String, nil) —

    The specific version to resolve

Returns:

Raises:

  • (ArgumentError) —

    If no version is provided and no current_version is configured



17
18
19
20
21
22
23
24
25
 
# File 'lib/verquest/base/private_class_methods.rb', line 17

def resolve(version)
  if version.nil? && Verquest.configuration.current_version
    version = instance_exec(&Verquest.configuration.current_version)
  elsif version.nil?
    raise ArgumentError, "Version must be provided or set by Verquest.configuration.current_version"
  end

  versions.resolve(version)
end

#schema_options(**schema_options) ⇒ void (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Sets additional schema options for the current version scope or globally

Parameters:

  • schema_options (Hash) —

    The schema options to set

Raises:

  • (RuntimeError) —

    If called outside of a version scope



91
92
93
94
95
96
97
98
99
100
101
 
# File 'lib/verquest/base/private_class_methods.rb', line 91

def schema_options(**schema_options)
  camelize(schema_options)

  if current_scope.nil?
    versions.schema_options.merge!(schema_options)
  elsif current_scope.is_a?(Version)
    current_scope.schema_options.merge!(schema_options)
  else
    raise "Additional properties can only be set within a version scope or globally"
  end
end

#version(name, inherit: true, exclude_properties: []) { ... } ⇒ void (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Defines a new version with optional inheritance from another version

Parameters:

  • name (String) —

    The name/identifier of the version

  • inherit (Boolean, String) (defaults to: true) —

    Whether to inherit from current scope or specific version name

  • exclude_properties (Array<Symbol>) (defaults to: []) —

    Properties to exclude when inheriting

Yields:

  • Block defining the version’s structure and properties



50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
 
# File 'lib/verquest/base/private_class_methods.rb', line 50

def version(name, inherit: true, exclude_properties: [], &block)
  version = Version.new(name:)
  versions.add(version)

  if inherit && @current_scope
    version.copy_from(@current_scope, exclude_properties:)
  elsif inherit.is_a?(String)
    inherit_version = versions.resolve(inherit)
    version.copy_from(inherit_version, exclude_properties:)
  end

  @default_options = {}
  @current_scope = version

  instance_exec(&block)
ensure
  version.description ||= versions.description
  version.schema_options = versions.schema_options.merge(version.schema_options).transform_keys(&:to_s)
  version.prepare
end

#versions ⇒ Verquest::Versions (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns the versions container, initializing it if needed

Returns:



39
40
41
 
# File 'lib/verquest/base/private_class_methods.rb', line 39

def versions
  @versions ||= Versions.new
end

#with_options(**options) { ... } ⇒ void (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Executes the given block with the specified options, temporarily overriding the default options for the duration of the block

Parameters:

  • options (Hash) —

    The options to set during the block execution

Yields:

  • Block to be executed with the temporary options



109
110
111
112
113
114
115
116
117
118
 
# File 'lib/verquest/base/private_class_methods.rb', line 109

def with_options(**options, &block)
  camelize(options)

  original_options = default_options
  @default_options = options.except(:map)

  instance_exec(&block)
ensure
  @default_options = original_options
end