Class: HatiCommand::Result Abstract

Inherits:
Object
  • Object
show all
Defined in:
lib/hati_command/result.rb

Overview

This class is abstract.

Subclass and override #to_sym to implement a concrete result type

Base class for the Result pattern implementation. This class serves as the foundation for Success and Failure result types, providing common functionality and a consistent interface for handling operation outcomes.

The Result pattern helps in handling operation outcomes in a type-safe way, making it explicit whether an operation succeeded or failed, and carrying additional context like error messages and metadata.

Examples:

Basic usage

result = HatiCommand::Result.new("Operation output")
result.value  # => "Operation output"

With error and metadata

result = HatiCommand::Result.new(
  "Operation output",
  err: "Warning: partial completion",
  meta: { duration_ms: 150 }
)

Using trace information

result = HatiCommand::Result.new("Output", trace: caller(1..1))
result.trace  # => ["path/to/file.rb:42:in `method_name'"]

See Also:

Direct Known Subclasses

Failure, Success

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(value, err: nil, meta: {}, trace: nil) ⇒ Result

Initializes a new Result instance with a value and optional context.

Examples:

Basic initialization

result = Result.new("Success")

With full context

result = Result.new(
  "Partial success",
  err: "Some records failed",
  meta: { processed: 10, failed: 2 },
  trace: caller
)

Parameters:

  • value (Object) —

    The value to be wrapped in the result

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

    Optional error message or error object

  • meta (Hash) (defaults to: {}) —

    Optional metadata for additional context

  • trace (Array<String>, nil) (defaults to: nil) —

    Optional execution trace for debugging



65
66
67
68
69
70
 
# File 'lib/hati_command/result.rb', line 65

def initialize(value, err: nil, meta: {}, trace: nil)
  @value = value
  @err = err
  @meta = meta
  @trace = trace
end

Instance Attribute Details

#err ⇒ Object

Returns the value of attribute err.



46
47
48
 
# File 'lib/hati_command/result.rb', line 46

def err
  @err
end

#meta ⇒ Hash (readonly)

Returns Additional metadata associated with the result.

Returns:

  • (Hash) —

    Additional metadata associated with the result



44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
 
# File 'lib/hati_command/result.rb', line 44

class Result
  attr_reader :value, :meta
  attr_accessor :trace, :err

  # Initializes a new Result instance with a value and optional context.
  #
  # @param value [Object] The value to be wrapped in the result
  # @param err [String, nil] Optional error message or error object
  # @param meta [Hash] Optional metadata for additional context
  # @param trace [Array<String>, nil] Optional execution trace for debugging
  #
  # @example Basic initialization
  #   result = Result.new("Success")
  #
  # @example With full context
  #   result = Result.new(
  #     "Partial success",
  #     err: "Some records failed",
  #     meta: { processed: 10, failed: 2 },
  #     trace: caller
  #   )
  def initialize(value, err: nil, meta: {}, trace: nil)
    @value = value
    @err = err
    @meta = meta
    @trace = trace
  end

  # Returns self to provide a consistent interface across result types.
  # This method ensures that all result objects can be treated uniformly
  # when chaining operations.
  #
  # @return [HatiCommand::Result] The result instance itself
  # @api public
  def result
    self
  end

  # Returns the error associated with this result.
  # This can be used to check for warnings or errors even in successful results.
  #
  # @return [String, nil] The error message or object, if any
  # @raise [StandardError] If accessing the error triggers an error condition
  # @api public
  # @example
  #   result = Result.new("Value", err: "Warning message")
  #   result.error  # => "Warning message"
  def error
    @err
  end

  # Returns the symbolic representation of this result type.
  # This is an abstract method that should be overridden by concrete result types.
  #
  # @return [Symbol] Returns :undefined for the base class
  # @abstract Subclasses must override this method
  # @api public
  # @example
  #   Result.new("value").to_sym  # => :undefined
  def to_sym
    :undefined
  end
end

#trace ⇒ Array<String>?

Returns Execution trace information for debugging.

Returns:

  • (Array<String>, nil) —

    Execution trace information for debugging



44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
 
# File 'lib/hati_command/result.rb', line 44

class Result
  attr_reader :value, :meta
  attr_accessor :trace, :err

  # Initializes a new Result instance with a value and optional context.
  #
  # @param value [Object] The value to be wrapped in the result
  # @param err [String, nil] Optional error message or error object
  # @param meta [Hash] Optional metadata for additional context
  # @param trace [Array<String>, nil] Optional execution trace for debugging
  #
  # @example Basic initialization
  #   result = Result.new("Success")
  #
  # @example With full context
  #   result = Result.new(
  #     "Partial success",
  #     err: "Some records failed",
  #     meta: { processed: 10, failed: 2 },
  #     trace: caller
  #   )
  def initialize(value, err: nil, meta: {}, trace: nil)
    @value = value
    @err = err
    @meta = meta
    @trace = trace
  end

  # Returns self to provide a consistent interface across result types.
  # This method ensures that all result objects can be treated uniformly
  # when chaining operations.
  #
  # @return [HatiCommand::Result] The result instance itself
  # @api public
  def result
    self
  end

  # Returns the error associated with this result.
  # This can be used to check for warnings or errors even in successful results.
  #
  # @return [String, nil] The error message or object, if any
  # @raise [StandardError] If accessing the error triggers an error condition
  # @api public
  # @example
  #   result = Result.new("Value", err: "Warning message")
  #   result.error  # => "Warning message"
  def error
    @err
  end

  # Returns the symbolic representation of this result type.
  # This is an abstract method that should be overridden by concrete result types.
  #
  # @return [Symbol] Returns :undefined for the base class
  # @abstract Subclasses must override this method
  # @api public
  # @example
  #   Result.new("value").to_sym  # => :undefined
  def to_sym
    :undefined
  end
end

#value ⇒ Object (readonly)

Returns The wrapped value representing the operation's output.

Returns:

  • (Object) —

    The wrapped value representing the operation's output



44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
 
# File 'lib/hati_command/result.rb', line 44

class Result
  attr_reader :value, :meta
  attr_accessor :trace, :err

  # Initializes a new Result instance with a value and optional context.
  #
  # @param value [Object] The value to be wrapped in the result
  # @param err [String, nil] Optional error message or error object
  # @param meta [Hash] Optional metadata for additional context
  # @param trace [Array<String>, nil] Optional execution trace for debugging
  #
  # @example Basic initialization
  #   result = Result.new("Success")
  #
  # @example With full context
  #   result = Result.new(
  #     "Partial success",
  #     err: "Some records failed",
  #     meta: { processed: 10, failed: 2 },
  #     trace: caller
  #   )
  def initialize(value, err: nil, meta: {}, trace: nil)
    @value = value
    @err = err
    @meta = meta
    @trace = trace
  end

  # Returns self to provide a consistent interface across result types.
  # This method ensures that all result objects can be treated uniformly
  # when chaining operations.
  #
  # @return [HatiCommand::Result] The result instance itself
  # @api public
  def result
    self
  end

  # Returns the error associated with this result.
  # This can be used to check for warnings or errors even in successful results.
  #
  # @return [String, nil] The error message or object, if any
  # @raise [StandardError] If accessing the error triggers an error condition
  # @api public
  # @example
  #   result = Result.new("Value", err: "Warning message")
  #   result.error  # => "Warning message"
  def error
    @err
  end

  # Returns the symbolic representation of this result type.
  # This is an abstract method that should be overridden by concrete result types.
  #
  # @return [Symbol] Returns :undefined for the base class
  # @abstract Subclasses must override this method
  # @api public
  # @example
  #   Result.new("value").to_sym  # => :undefined
  def to_sym
    :undefined
  end
end

Instance Method Details

#error ⇒ String?

Returns the error associated with this result. This can be used to check for warnings or errors even in successful results.

Examples:

result = Result.new("Value", err: "Warning message")
result.error  # => "Warning message"

Returns:

  • (String, nil) —

    The error message or object, if any

Raises:

  • (StandardError) —

    If accessing the error triggers an error condition



91
92
93
 
# File 'lib/hati_command/result.rb', line 91

def error
  @err
end

#result ⇒ HatiCommand::Result

Returns self to provide a consistent interface across result types. This method ensures that all result objects can be treated uniformly when chaining operations.

Returns:



78
79
80
 
# File 'lib/hati_command/result.rb', line 78

def result
  self
end

#to_sym ⇒ Symbol

This method is abstract.

Subclasses must override this method

Returns the symbolic representation of this result type. This is an abstract method that should be overridden by concrete result types.

Examples:

Result.new("value").to_sym  # => :undefined

Returns:

  • (Symbol) —

    Returns :undefined for the base class



103
104
105
 
# File 'lib/hati_command/result.rb', line 103

def to_sym
  :undefined
end