Class: CMDx::Output

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

Overview

A single declared output. Runtime calls #verify after ‘work` to enforce presence on `task.context` (every declared output is implicitly required) and to apply `:default`. `:if`/`:unless` gate verification entirely.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(name, **options) ⇒ Output

Returns a new instance of Output.

Parameters:

  • name (Symbol, String) —

    output key (symbolized)

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

    declaration options

Options Hash (**options):

  • :description (String) — default: also accepts `:desc`
  • :if (Symbol, Proc, #call)
  • :unless (Symbol, Proc, #call)
  • :default (Object, Symbol, Proc, #call) 


17
18
19
20
 
# File 'lib/cmdx/output.rb', line 17

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

Instance Attribute Details

#name ⇒ Object (readonly)

Returns the value of attribute name.



9
10
11
 
# File 'lib/cmdx/output.rb', line 9

def name
  @name
end

Instance Method Details

#as_json ⇒ Hash{Symbol => Object}

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

Returns:

  • (Hash{Symbol => Object}) 


55
56
57
 
# File 'lib/cmdx/output.rb', line 55

def as_json(*)
  to_h
end

#condition_if ⇒ Symbol, ...

Returns:

  • (Symbol, Proc, #call, nil) 


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

def condition_if
  @options[:if]
end

#condition_unless ⇒ Symbol, ...

Returns:

  • (Symbol, Proc, #call, nil) 


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

def condition_unless
  @options[:unless]
end

#default ⇒ Object, ...

Returns:

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


28
29
30
 
# File 'lib/cmdx/output.rb', line 28

def default
  @options[:default]
end

#description ⇒ String?

Returns:

  • (String, nil) 


23
24
25
 
# File 'lib/cmdx/output.rb', line 23

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

#to_h ⇒ Hash{Symbol => Object}

Returns serialized schema for ‘outputs_schema`.

Returns:

  • (Hash{Symbol => Object}) —

    serialized schema for ‘outputs_schema`



43
44
45
46
47
48
49
 
# File 'lib/cmdx/output.rb', line 43

def to_h
  {
    name:,
    description:,
    options: @options
  }
end

#to_json(*args) ⇒ String

Serializes the output 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) 


65
66
67
 
# File 'lib/cmdx/output.rb', line 65

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

#verify(task) ⇒ void

This method returns an undefined value.

Enforces the output contract against ‘task.context` after `work` runs.

Steps, in order:

  1. Skips entirely when ‘:if`/`:unless` excludes it.

  2. Reads the value from ‘task.context` and falls back to `:default` when nil.

  3. Adds a ‘cmdx.outputs.missing` error when neither the key nor a default supplied a value (every declared output is implicitly required).

  4. Writes the resolved value back to ‘task.context`.

Parameters:

  • task (Task) —

    the running task whose context is inspected and mutated



80
81
82
83
84
85
86
87
88
89
90
91
92
93
 
# File 'lib/cmdx/output.rb', line 80

def verify(task)
  return unless Util.satisfied?(condition_if, condition_unless, task)

  key_provided = task.context.key?(name)
  value        = task.context[name]
  value        = apply_default(task) if value.nil?

  if !key_provided && value.nil?
    task.errors.add(name, I18nProxy.t("cmdx.outputs.missing"))
    return
  end

  task.context[name] = value
end