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) 


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

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) 


85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
 
# File 'lib/cmdx/input.rb', line 85

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

#as ⇒ Symbol?

Returns:

  • (Symbol, nil) 


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

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}) 


164
165
166
 
# File 'lib/cmdx/input.rb', line 164

def as_json(*)
  to_h
end

#condition_if ⇒ Symbol, ...

Returns:

  • (Symbol, Proc, #call, nil) 


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

def condition_if
  @options[:if]
end

#condition_unless ⇒ Symbol, ...

Returns:

  • (Symbol, Proc, #call, nil) 


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

def condition_unless
  @options[:unless]
end

#default ⇒ Object, ...

Returns:

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


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

def default
  @options[:default]
end

#description ⇒ String?

Returns:

  • (String, nil) 


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

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



109
110
111
 
# File 'lib/cmdx/input.rb', line 109

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

#prefix ⇒ Boolean, ...

Returns:

  • (Boolean, String, nil) 


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

def prefix
  @options[:prefix]
end

#required ⇒ Boolean

Returns:

  • (Boolean) 


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

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) 


118
119
120
121
122
123
124
 
# File 'lib/cmdx/input.rb', line 118

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?

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)



133
134
135
136
 
# File 'lib/cmdx/input.rb', line 133

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) 


144
145
146
147
 
# File 'lib/cmdx/input.rb', line 144

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) 


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

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

#suffix ⇒ Boolean, ...

Returns:

  • (Boolean, String, nil) 


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

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`



150
151
152
153
154
155
156
157
158
 
# File 'lib/cmdx/input.rb', line 150

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) 


174
175
176
 
# File 'lib/cmdx/input.rb', line 174

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

#transform ⇒ Symbol, ...

Returns:

  • (Symbol, Proc, #call, nil) 


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

def transform
  @options[:transform]
end