Method: Hoodoo::Errors#add_error

Defined in:
lib/hoodoo/errors/errors.rb

#add_error(code, options = nil) ⇒ Object

Add an error instance to this collection.

code

Error code in full, e.g. +generic.invalid_state’.

options

An options Hash, optional.

The options hash contains symbol keys named as follows, with values as described:

reference

Reference data Hash, optionality depending upon the error code and the reference data its error description mandates. Provide key/value pairs where (symbol) keys are names from the array of description requirements and values are strings. All values are concatenated into a single string, comma-separated. Commas within values are escaped with a backslash; backslash is itself escaped with a backslash.

You must provide that data at a minimum, but can provide additional keys too if you so wish. Required keys are always included first, in order of appearance in the requirements array of the error declaration, followed by any extra values in undefined order.

See also Hoodoo::ErrorDescriptions::DomainDescriptions#error

message

Optional human-readable for-developer message, en-nz locale. Default messages are provided for all errors, but if you think you can provide something more informative, you can do so through this parameter.

Example:

errors.add_error(
  'platform.not_found',
  :message => 'Optional custom message',
  :reference => { :entity_name => 'mandatory reference data' }
)

In the above example, the mandatory reference data entity_name comes from the description for the ‘platform.not_found’ message - see the Hoodoo::ErrorDescriptions#initialize implementation and Platform API.

Raises:



121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
 
# File 'lib/hoodoo/errors/errors.rb', line 121

def add_error( code, options = nil )

  options   = Hoodoo::Utilities.stringify( options || {} )
  reference = options[ 'reference' ] || {}
  message   = options[ 'message' ]

  # Make sure nobody uses an undeclared error code.

  raise UnknownCode, "In \#add_error: Unknown error code '#{code}'" unless @descriptions.recognised?( code )

  # If the error description specifies a list of required reference keys,
  # make sure all are present and complain if not.

  description = @descriptions.describe( code )

  required_keys = description[ 'reference' ] || []
  actual_keys   = reference.keys
  missing_keys  = required_keys - actual_keys

  unless missing_keys.empty?
    raise MissingReferenceData, "In \#add_error: Reference hash missing required keys: '#{ missing_keys.join( ', ' ) }'"
  end

  # All good!

  @http_status_code = ( description[ 'status' ] || 200 ).to_i if @errors.empty? # Use first in collection for overall HTTP status code

  error = {
    'code'    => code,
    'message' => message || description[ 'message' ] || code
  }

  ordered_keys   = required_keys + ( actual_keys - required_keys )
  ordered_values = ordered_keys.map { | key | escape_commas( reference[ key ].to_s ) }

  # See #unjoin_and_unescape_commas to undo the join below.

  error[ 'reference' ] = ordered_values.join( ',' ) unless ordered_values.empty?

  @errors << error
end