Class: CMDx::Input

Inherits:
Object
  • Object
show all
Defined in:
lib/cmdx/input.rb

Overview

A single declared task input. Holds declaration options (:source, :default, :required, :coerce, validators, :transform, etc.) and owns the resolution pipeline that produces the value the task will read through the generated accessor.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(name, children: EMPTY_ARRAY, **options) ⇒ Input

Returns a new instance of Input.

Parameters:

  • name (Symbol, String) —

    input key (symbolized)

  • children (Array<Input>) (defaults to: EMPTY_ARRAY) —

    nested child inputs resolved from this one's value

  • options (Hash{Symbol => Object}) —

    declaration options

Options Hash (**options):

  • :description (String) — default: also accepts `:desc`
  • :as (Symbol) —

    overrides the accessor name

  • :prefix (Boolean, String) —

    prefix for the accessor name

  • :suffix (Boolean, String) —

    suffix for the accessor name

  • :source (Symbol, Proc, #call) — default: `:context` —

    where to fetch from

  • :default (Object, Symbol, Proc, #call)
  • :transform (Symbol, Proc, #call) —

    mutator applied after coercion

  • :if (Symbol, Proc, #call)
  • :unless (Symbol, Proc, #call)
  • :required (Boolean)
  • :allow_nil (Boolean) — default: see {#allow_nil} 


26
27
28
29
30
 
# File 'lib/cmdx/input.rb', line 26

def initialize(name, children: EMPTY_ARRAY, **options)
  @name     = name.to_sym
  @children = children.freeze
  @options  = options.freeze
end

Instance Attribute Details

#children ⇒ Object (readonly)

Returns the value of attribute children.



10
11
12
 
# File 'lib/cmdx/input.rb', line 10

def children
  @children
end

#name ⇒ Object (readonly)

Returns the value of attribute name.



10
11
12
 
# File 'lib/cmdx/input.rb', line 10

def name
  @name
end

Instance Method Details

#accessor_name ⇒ Symbol

Computed accessor/reader method name. Uses :as when provided, otherwise combines :prefix, name, and :suffix around the source.

Returns:

  • (Symbol) 


94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
 
# File 'lib/cmdx/input.rb', line 94

def accessor_name
  return as if as

  @accessor_name ||= begin
    prefix_str =
      case prefix
      when true
        "#{source}_"
      when ::String
        prefix
      end
    suffix_str =
      case suffix
      when true
        "_#{source}"
      when ::String
        suffix
      end

    :"#{prefix_str}#{name}#{suffix_str}"
  end
end

#allow_nil ⇒ Boolean

When true, a nil value after defaults skips coercion, transform, and validation. Per-validator :allow_nil only skips individual rules.

Returns:

  • (Boolean) 


86
87
88
 
# File 'lib/cmdx/input.rb', line 86

def allow_nil
  @options.fetch(:allow_nil, false)
end

#as ⇒ Symbol?

Returns:

  • (Symbol, nil) 


38
39
40
 
# File 'lib/cmdx/input.rb', line 38

def as
  @options[:as]
end

#as_json ⇒ Hash{Symbol => Object}

JSON-friendly hash view. Aliases #to_h for conventional as_json callers (e.g. Rails).

Returns:

  • (Hash{Symbol => Object}) 


179
180
181
 
# File 'lib/cmdx/input.rb', line 179

def as_json(*)
  to_h
end

#condition_if ⇒ Symbol, ...

Returns:

  • (Symbol, Proc, #call, nil) 


68
69
70
 
# File 'lib/cmdx/input.rb', line 68

def condition_if
  @options[:if]
end

#condition_unless ⇒ Symbol, ...

Returns:

  • (Symbol, Proc, #call, nil) 


73
74
75
 
# File 'lib/cmdx/input.rb', line 73

def condition_unless
  @options[:unless]
end

#default ⇒ Object, ...

Returns:

  • (Object, Symbol, Proc, #call, nil) 


58
59
60
 
# File 'lib/cmdx/input.rb', line 58

def default
  @options[:default]
end

#description ⇒ String?

Returns:

  • (String, nil) 


33
34
35
 
# File 'lib/cmdx/input.rb', line 33

def description
  @options[:description] || @options[:desc]
end

#ivar_name ⇒ Symbol

Returns backing ivar used by the generated reader method.

Returns:

  • (Symbol) —

    backing ivar used by the generated reader method



118
119
120
 
# File 'lib/cmdx/input.rb', line 118

def ivar_name
  @ivar_name ||= :"@_input_#{accessor_name}"
end

#prefix ⇒ Boolean, ...

Returns:

  • (Boolean, String, nil) 


43
44
45
 
# File 'lib/cmdx/input.rb', line 43

def prefix
  @options[:prefix]
end

#required ⇒ Boolean

Returns:

  • (Boolean) 


78
79
80
 
# File 'lib/cmdx/input.rb', line 78

def required
  @options.fetch(:required, false)
end

#required?(task = nil) ⇒ Boolean

Evaluates required-ness against task, respecting :if/:unless. When called without a task, returns the static :required flag.

Parameters:

  • task (Task, nil) (defaults to: nil)

Returns:

  • (Boolean) 


127
128
129
130
131
132
133
 
# File 'lib/cmdx/input.rb', line 127

def required?(task = nil)
  return false unless required
  return true if task.nil?
  return false unless Util.satisfied?(condition_if, condition_unless, task)

  true
end

#resolve(task) ⇒ Object?

Note:

"Required" here means "the key is present in the source"; an explicit nil under an existing key satisfies the required check and is then routed through :default. Combine with :presence / :validate to reject explicit nil values, or :allow_nil (see #allow_nil) to leave nil unresolved.

Fetches + coerces + transforms + validates the value from its configured :source on task. Missing-but-required inputs add a validation error to task.errors. Returns nil when coercion or any validator fails (the failure message is recorded on task.errors).

Parameters:

Returns:

  • (Object, nil) —

    the resolved value (nil on failure)



148
149
150
151
 
# File 'lib/cmdx/input.rb', line 148

def resolve(task)
  value, key_provided = resolve_with_key(task)
  run_pipeline(value, key_provided, task)
end

#resolve_from_parent(parent_value, task) ⇒ Object?

Same as #resolve but fetches the value from parent_value (used for nested child inputs) instead of the declared :source.

Parameters:

  • parent_value (#[], #key?, Object) —

    the parent input's resolved value

  • task (Task)

Returns:

  • (Object, nil) 


159
160
161
162
 
# File 'lib/cmdx/input.rb', line 159

def resolve_from_parent(parent_value, task)
  value, key_provided = resolve_from_parent_with_key(parent_value)
  run_pipeline(value, key_provided, task)
end

#source ⇒ Symbol, ...

Returns:

  • (Symbol, Proc, #call) 


53
54
55
 
# File 'lib/cmdx/input.rb', line 53

def source
  @options[:source] || :context
end

#suffix ⇒ Boolean, ...

Returns:

  • (Boolean, String, nil) 


48
49
50
 
# File 'lib/cmdx/input.rb', line 48

def suffix
  @options[:suffix]
end

#to_h ⇒ Hash{Symbol => Object}

Returns serialized schema used by inputs_schema.

Returns:

  • (Hash{Symbol => Object}) —

    serialized schema used by inputs_schema



165
166
167
168
169
170
171
172
173
 
# File 'lib/cmdx/input.rb', line 165

def to_h
  {
    name: accessor_name,
    description:,
    required: required?,
    options: @options,
    children: children.map(&:to_h)
  }
end

#to_json(*args) ⇒ String

Serializes the input schema to a JSON string. Non-primitive entries in :options (Procs, arbitrary callables) emit via their stdlib to_json defaults.

Parameters:

  • args (Array) —

    forwarded to Hash#to_json

Returns:

  • (String) 


189
190
191
 
# File 'lib/cmdx/input.rb', line 189

def to_json(*args)
  to_h.to_json(*args)
end

#transform ⇒ Symbol, ...

Returns:

  • (Symbol, Proc, #call, nil) 


63
64
65
 
# File 'lib/cmdx/input.rb', line 63

def transform
  @options[:transform]
end