Class: Dry::Schema::DSL

Inherits:
Object
  • Object
show all
Extended by:
Initializer
Defined in:
lib/dry/schema/dsl.rb

Overview

The schema definition DSL class

The DSL is exposed by:

- `Schema.define`
- `Schema.Params`
- `Schema.JSON`
- `Schema::Params.define` - use with sub-classes
- `Schema::JSON.define` - use with sub-classes

Examples:

class-based definition

class UserSchema < Dry::Schema::Params
  define do
    required(:name).filled
    required(:age).filled(:integer, gt: 18)
  end
end

user_schema = UserSchema.new
user_schema.(name: 'Jame', age: 21)

instance-based definition shortcut

UserSchema = Dry::Schema.Params do
  required(:name).filled
  required(:age).filled(:integer, gt: 18)
end

UserSchema.(name: 'Jame', age: 21)

Constant Summary collapse

Types = 
Schema::Types

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.new(**options, &block) ⇒ DSL

Build a new DSL object and evaluate provided block

Parameters:

  • options (Hash)

Options Hash (**options):

  • :processor (Class) —

    The processor type (`Params`, `JSON` or a custom sub-class)

  • :compiler (Compiler) —

    An instance of a rule compiler (must be compatible with `Schema::Compiler`) (optional)

  • :parent (Array[DSL]) —

    One or more instances of the parent DSL (optional)

  • :config (Config) —

    A configuration object (optional)

Returns:

See Also:



98
99
100
101
102
 
# File 'lib/dry/schema/dsl.rb', line 98

def self.new(**options, &block)
  dsl = super
  dsl.instance_eval(&block) if block
  dsl
end

Instance Method Details

#[](name) ⇒ Macros::Core

Return a macro with the provided name

Parameters:

  • name (Symbol)

Returns:



130
131
132
 
# File 'lib/dry/schema/dsl.rb', line 130

def [](name)
  macros.detect { |macro| macro.name.equal?(name) }
end

#after(key, &block) ⇒ DSL

Method allows steps injection to the processor

Examples:

after(:rule_applier) do |input|
  input.compact
end

Returns:



273
274
275
276
 
# File 'lib/dry/schema/dsl.rb', line 273

def after(key, &block)
  steps.after(key, &block)
  self
end

#array ⇒ Dry::Types::Array::Member

A shortcut for defining an array type with a member

Examples:

required(:tags).filled(array[:string])

Returns:

  • (Dry::Types::Array::Member) 


244
245
246
 
# File 'lib/dry/schema/dsl.rb', line 244

def array
  -> member_type { type_registry["array"].of(resolve_type(member_type)) }
end

#before(key, &block) ⇒ DSL

Method allows steps injection to the processor

Examples:

before(:rule_applier) do |input|
  input.compact
end

Returns:



258
259
260
261
 
# File 'lib/dry/schema/dsl.rb', line 258

def before(key, &block)
  steps.before(key, &block)
  self
end

#call ⇒ Processor, ...

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.

Build a processor based on DSL's definitions

Returns:



201
202
203
204
205
206
207
208
209
210
211
212
213
 
# File 'lib/dry/schema/dsl.rb', line 201

def call
  all_steps = parents.map(&:steps) + [steps]

  result_steps = all_steps.inject { |result, steps| result.merge(steps) }

  result_steps[:key_validator] = key_validator if config.validate_keys
  result_steps[:key_coercer] = key_coercer
  result_steps[:value_coercer] = value_coercer
  result_steps[:rule_applier] = rule_applier
  result_steps[:filter_schema] = filter_schema.rule_applier if filter_rules?

  processor_type.new(schema_dsl: self, steps: result_steps)
end

#compiler ⇒ Compiler

Returns The rule compiler object.

Returns:

  • (Compiler) —

    The rule compiler object



57
 
# File 'lib/dry/schema/dsl.rb', line 57

option :compiler, default: -> { Compiler.new }

#config ⇒ Config

Returns Configuration object exposed via `#configure` method.

Returns:

  • (Config) —

    Configuration object exposed via `#configure` method



72
 
# File 'lib/dry/schema/dsl.rb', line 72

option :config, optional: true, default: proc { default_config }

#configure(&block) ⇒ DSL

Provide customized configuration for your schema

Examples:

Dry::Schema.define do
  configure do |config|
    config.messages.backend = :i18n
  end
end

Returns:

See Also:



118
119
120
121
 
# File 'lib/dry/schema/dsl.rb', line 118

def configure(&block)
  config.configure(&block)
  self
end

#custom_type?(name) ⇒ Bool

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.

Check if a custom type was set under provided key name

Returns:

  • (Bool) 


327
328
329
 
# File 'lib/dry/schema/dsl.rb', line 327

def custom_type?(name)
  !types[name].meta[:default].equal?(true)
end

#filter_rules? ⇒ Boolean

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.

Check if any filter rules were defined

Returns:

  • (Boolean) 


364
365
366
367
368
369
370
 
# File 'lib/dry/schema/dsl.rb', line 364

def filter_rules?
  if instance_variable_defined?("@filter_schema_dsl") && !filter_schema_dsl.macros.empty?
    return true
  end

  parents.any?(&:filter_rules?)
end

#filter_schema ⇒ Object

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. 



348
349
350
 
# File 'lib/dry/schema/dsl.rb', line 348

def filter_schema
  filter_schema_dsl.call
end

#filter_schema_dsl ⇒ Object

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.

Build an input schema DSL used by `filter` API

See Also:

  • Macros::Value#filter


357
358
359
 
# File 'lib/dry/schema/dsl.rb', line 357

def filter_schema_dsl
  @filter_schema_dsl ||= new(parent: parent_filter_schemas)
end

#key(name, macro:, &block) ⇒ Macros::Key

A generic method for defining keys

Parameters:

  • name (Symbol) —

    The key name

  • macro (Class) —

    The macro sub-class (ie `Macros::Required` or any other `Macros::Key` subclass)

Returns:

Raises:

  • (ArgumentError) 


179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
 
# File 'lib/dry/schema/dsl.rb', line 179

def key(name, macro:, &block)
  raise ArgumentError, "Key +#{name}+ is not a symbol" unless name.is_a?(::Symbol)

  set_type(name, Types::Any.meta(default: true))

  macro = macro.new(
    name: name,
    compiler: compiler,
    schema_dsl: self,
    filter_schema_dsl: filter_schema_dsl
  )

  macro.value(&block) if block
  macros << macro
  macro
end

#macros ⇒ Array

Returns An array with macros defined within the DSL.

Returns:

  • (Array) —

    An array with macros defined within the DSL



63
 
# File 'lib/dry/schema/dsl.rb', line 63

option :macros, default: -> { EMPTY_ARRAY.dup }

#merge(other) ⇒ DSL

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.

Merge with another dsl

Returns:



220
221
222
223
224
225
226
227
 
# File 'lib/dry/schema/dsl.rb', line 220

def merge(other)
  new(
    parent: parents + other.parents,
    macros: macros + other.macros,
    types: types.merge(other.types),
    steps: steps.merge(other.steps)
  )
end

#new(**options, &block) ⇒ Dry::Types::Safe

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.

Return a new DSL instance using the same processor type

Returns:

  • (Dry::Types::Safe) 


303
304
305
 
# File 'lib/dry/schema/dsl.rb', line 303

def new(**options, &block)
  self.class.new(**options, processor_type: processor_type, config: config, &block)
end

#optional(name, &block) ⇒ Macros::Optional

Define an optional key

This works exactly the same as `required` except that if a key is not present rules will not be applied

Parameters:

  • name (Symbol) —

    The key name

Returns:

See Also:



166
167
168
 
# File 'lib/dry/schema/dsl.rb', line 166

def optional(name, &block)
  key(name, macro: Macros::Optional, &block)
end

#parent ⇒ Object

The parent (last from parents) which is used for copying non mergeable configuration

Returns:

  • DSL



69
 
# File 'lib/dry/schema/dsl.rb', line 69

option :parent, Types::Coercible::Array, default: -> { EMPTY_ARRAY.dup }, as: :parents

#path ⇒ Path, Array

Returns Path under which the schema is defined.

Returns:

  • (Path, Array) —

    Path under which the schema is defined



78
 
# File 'lib/dry/schema/dsl.rb', line 78

option :path, -> *args { Path[*args] if args.any? }, default: proc { EMPTY_ARRAY }

#processor_type ⇒ Compiler

Returns The type of the processor (Params, JSON, or a custom sub-class).

Returns:

  • (Compiler) —

    The type of the processor (Params, JSON, or a custom sub-class)



60
 
# File 'lib/dry/schema/dsl.rb', line 60

option :processor_type, default: -> { Processor }

#required(name, &block) ⇒ Macros::Required

Define a required key

Examples:

required(:name).filled

required(:age).value(:integer)

required(:user_limit).value(:integer, gt?: 0)

required(:tags).filled { array? | str? }

Parameters:

  • name (Symbol) —

    The key name

Returns:



150
151
152
 
# File 'lib/dry/schema/dsl.rb', line 150

def required(name, &block)
  key(name, macro: Macros::Required, &block)
end

#resolve_type(spec) ⇒ Dry::Types::Type

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.

Resolve type object from the provided spec

Parameters:

  • spec (Symbol, Array<Symbol>, Dry::Types::Type)

Returns:

  • (Dry::Types::Type) 


338
339
340
341
342
343
344
345
 
# File 'lib/dry/schema/dsl.rb', line 338

def resolve_type(spec)
  case spec
  when ::Dry::Types::Type then spec
  when ::Array then spec.map { |s| resolve_type(s) }.reduce(:|)
  else
    type_registry[spec]
  end
end

#set_type(name, spec) ⇒ Dry::Types::Safe

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.

Set a type for the given key name

Parameters:

  • name (Symbol) —

    The key name

  • spec (Symbol, Array<Symbol>, Dry::Types::Type) —

    The type spec or a type object

Returns:

  • (Dry::Types::Safe) 


315
316
317
318
319
320
 
# File 'lib/dry/schema/dsl.rb', line 315

def set_type(name, spec)
  type = resolve_type(spec)
  meta = {required: false, maybe: type.optional?}

  types[name] = type.meta(meta)
end

#steps ⇒ ProcessorSteps

Returns Steps for the processor.

Returns:



75
 
# File 'lib/dry/schema/dsl.rb', line 75

option :steps, default: proc { ProcessorSteps.new }

#to_rule ⇒ RuleApplier

Cast this DSL into a rule object

Returns:



232
233
234
 
# File 'lib/dry/schema/dsl.rb', line 232

def to_rule
  call.to_rule
end

#type_schema ⇒ Dry::Types::Safe

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.

Return type schema used by the value coercer

Returns:

  • (Dry::Types::Safe) 


292
293
294
295
296
 
# File 'lib/dry/schema/dsl.rb', line 292

def type_schema
  our_schema = type_registry["hash"].schema(types).lax
  schemas = [*parents.map(&:type_schema), our_schema]
  schemas.inject { |result, schema| result.schema(schema.to_a) }
end

#types ⇒ Compiler

Returns A key=>type map defined within the DSL.

Returns:

  • (Compiler) —

    A key=>type map defined within the DSL



66
 
# File 'lib/dry/schema/dsl.rb', line 66

option :types, default: -> { EMPTY_HASH.dup }