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: false, 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 array property for the current version scope

Parameters:

  • name (Symbol) —

    The name of the array property

  • type (String) —

    The data type of the array elements

  • required (Boolean) (defaults to: false) —

    Whether the array property is required

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

    An optional mapping to another array property

  • schema_options (Hash) —

    Additional schema options for the array property



225
226
227
228
229
230
231
232
233
234
 
# File 'lib/verquest/base/private_class_methods.rb', line 225

def array(name, type:, required: false, map: nil, **schema_options)
  camelize(schema_options)

  type = default_options.fetch(:type, type)
  required = default_options.fetch(:required, required)
  schema_options = default_options.except(:type, :required).merge(schema_options)

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

#collection(name, item: nil, required: false, 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) (defaults to: false) —

    Whether the collection is required

  • 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



178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
 
# File 'lib/verquest/base/private_class_methods.rb', line 178

def collection(name, item: nil, required: false, 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, required)
  schema_options = default_options.except(:required).merge(schema_options)

  collection = Properties::Collection.new(name:, item:, required:, 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

#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

#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



241
242
243
244
245
 
# File 'lib/verquest/base/private_class_methods.rb', line 241

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

#field(name, type: nil, map: nil, required: false, **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) (defaults to: false) —

    Whether the field is required

  • schema_options (Hash) —

    Additional schema options for the field



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

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

  type = default_options.fetch(:type, type)
  required = default_options.fetch(:required, required)
  schema_options = default_options.except(:type, :required).merge(schema_options)

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

#object(name, map: nil, required: false, **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) (defaults to: false) —

    Whether the object is required

  • schema_options (Hash) —

    Additional schema options for the object

Yields:

  • Block executed in the context of the new object definition



147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
 
# File 'lib/verquest/base/private_class_methods.rb', line 147

def object(name, map: nil, required: false, **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, required)
  schema_options = default_options.except(:type, :required).merge(schema_options)

  object = Properties::Object.new(name:, map:, required:, **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: false) ⇒ 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) (defaults to: false) —

    Whether the reference is required



210
211
212
213
214
215
 
# File 'lib/verquest/base/private_class_methods.rb', line 210

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

  reference = Properties::Reference.new(name:, from:, property:, map:, required:)
  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 = schema_options
  elsif current_scope.is_a?(Version)
    current_scope.schema_options = 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)
  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