Module: MultiXML::Helpers

Included in:
MultiXML
Defined in:
lib/multi_xml/helpers.rb,
sig/multi_xml.rbs

Overview

Methods for transforming parsed XML hash structures

These helper methods handle key transformation and type casting of parsed XML data structures.

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.apply_converter(hash, content, converter) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Apply a type converter to content

Parameters:

  • hash (Hash) —

    Original hash with type info

  • content (String) —

    Content to convert

  • converter (Proc) —

    Converter to apply

Returns:

  • (Object) —

    Converted value



220
221
222
223
224
225
226
 
# File 'lib/multi_xml/helpers.rb', line 220

def apply_converter(hash, content, converter)
  # Binary converters need access to entity attributes (e.g., encoding, name)
  return converter.call(content, hash) if converter.arity == 2

  hash.delete("type")
  unwrap_if_simple(hash, converter.call(content))
end

.convert_hash(hash, type, disallowed_types) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Convert a hash based on its type and content

Parameters:

  • hash (Hash) —

    Hash to convert

  • type (String, nil) —

    Type attribute value

  • disallowed_types (Array<String>) —

    Types to reject

Returns:

  • (Object) —

    Converted value



93
94
95
96
97
98
99
100
 
# File 'lib/multi_xml/helpers.rb', line 93

def convert_hash(hash, type, disallowed_types)
  return extract_array_entries(hash, disallowed_types) if type == "array"
  return convert_text_content(hash) if hash.key?(TEXT_CONTENT_KEY)
  return "" if type == "string" && !hash["nil"].eql?("true")
  return nil if empty_value?(hash, type)

  typecast_children(hash, disallowed_types)
end

.convert_text_content(hash) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Convert text content using type converters

Parameters:

  • hash (Hash) —

    Hash containing text content and type

Returns:

  • (Object) —

    Converted value



155
156
157
158
159
160
161
162
 
# File 'lib/multi_xml/helpers.rb', line 155

def convert_text_content(hash)
  content = hash.fetch(TEXT_CONTENT_KEY)
  converter = TYPE_CONVERTERS[hash["type"]]

  return unwrap_if_simple(hash, content) unless converter

  apply_converter(hash, content, converter)
end

.disallowed_type?(type, disallowed_types) ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Check if a type is in the disallowed list

Parameters:

  • type (String, nil) —

    Type to check

  • disallowed_types (Array<String>) —

    Disallowed type list

Returns:

  • (Boolean) —

    true if type is disallowed



82
83
84
 
# File 'lib/multi_xml/helpers.rb', line 82

def disallowed_type?(type, disallowed_types)
  type && !type.is_a?(Hash) && disallowed_types.include?(type)
end

.empty_value?(hash, type) ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Check if a hash represents an empty value

Parameters:

  • hash (Hash) —

    Hash to check

  • type (String, nil) —

    Type attribute value

Returns:

  • (Boolean) —

    true if value should be nil



180
181
182
183
184
 
# File 'lib/multi_xml/helpers.rb', line 180

def empty_value?(hash, type)
  hash.empty? ||
    hash["nil"] == "true" ||
    (type && hash.size == 1 && !type.is_a?(Hash))
end

.extract_array_entries(hash, disallowed_types) ⇒ Array

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Extract array entries from element with type="array"

Parameters:

  • hash (Hash) —

    Hash containing array entries

  • disallowed_types (Array<String>) —

    Types to reject

Returns:

  • (Array) —

    Extracted and typecasted entries

See Also:



120
121
122
123
124
125
 
# File 'lib/multi_xml/helpers.rb', line 120

def extract_array_entries(hash, disallowed_types)
  entries = find_array_entries(hash)
  return [] unless entries

  wrap_and_typecast(entries, disallowed_types)
end

.find_array_entries(hash) ⇒ Array, ...

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Find array or hash entries in a hash, excluding the type key

Parameters:

  • hash (Hash) —

    Hash to search

Returns:

  • (Array, Hash, nil) —

    Found entries or nil



132
133
134
135
136
137
 
# File 'lib/multi_xml/helpers.rb', line 132

def find_array_entries(hash)
  hash.each do |key, value|
    return value if !key.eql?("type") && (value.is_a?(Array) || value.is_a?(Hash))
  end
  nil
end

.symbolize_keys(data) ⇒ Hash, ...

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Recursively convert all hash keys to symbols

Examples:

Symbolize hash keys

symbolize_keys({"name" => "John"}) #=> {name: "John"}

Parameters:

  • data (Hash, Array, Object) —

    Data to transform

Returns:

  • (Hash, Array, Object) —

    Transformed data with symbolized keys



18
19
20
 
# File 'lib/multi_xml/helpers.rb', line 18

def symbolize_keys(data)
  transform_keys(data, &:to_sym)
end

.transform_keys(data, &block) ⇒ Hash, ...

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Recursively transform hash keys using a block

Parameters:

  • data (Hash, Array, Object) —

    Data to transform

Returns:

  • (Hash, Array, Object) —

    Transformed data



193
194
195
196
197
198
199
200
201
 
# File 'lib/multi_xml/helpers.rb', line 193

def transform_keys(data, &block)
  case data
  when Hash then data.each_with_object(
    {} #: Hash[Symbol, MultiXML::xmlValue] # rubocop:disable Layout/LeadingCommentSpace
  ) { |(key, value), acc| acc[yield(key)] = transform_keys(value, &block) }
  when Array then data.map { |item| transform_keys(item, &block) }
  else data
  end
end

.typecast_array(array, disallowed_types) ⇒ Object, Array

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Typecast array elements and unwrap single-element arrays

Parameters:

  • array (Array) —

    Array to typecast

  • disallowed_types (Array<String>) —

    Types to reject

Returns:

  • (Object, Array) —

    Typecasted array or single element



57
58
59
60
 
# File 'lib/multi_xml/helpers.rb', line 57

def typecast_array(array, disallowed_types)
  array.map! { |item| typecast_xml_value(item, disallowed_types) }
  (array.size == 1) ? array.first : array
end

.typecast_children(hash, disallowed_types) ⇒ Hash, StringIO

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Typecast all child values in a hash

Parameters:

  • hash (Hash) —

    Hash with children to typecast

  • disallowed_types (Array<String>) —

    Types to reject

Returns:

  • (Hash, StringIO) —

    Typecasted hash or unwrapped file



108
109
110
111
 
# File 'lib/multi_xml/helpers.rb', line 108

def typecast_children(hash, disallowed_types)
  result = hash.transform_values { |v| typecast_xml_value(v, disallowed_types) }
  unwrap_file_if_present(result)
end

.typecast_hash(hash, disallowed_types) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Typecast a hash based on its type attribute

Parameters:

  • hash (Hash) —

    Hash to typecast

  • disallowed_types (Array<String>) —

    Types to reject

Returns:

  • (Object) —

    Typecasted value

Raises:



69
70
71
72
73
74
 
# File 'lib/multi_xml/helpers.rb', line 69

def typecast_hash(hash, disallowed_types)
  type = hash["type"]
  raise DisallowedTypeError, type if disallowed_type?(type, disallowed_types)

  convert_hash(hash, type, disallowed_types)
end

.typecast_xml_value(value, disallowed_types = DISALLOWED_TYPES) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Recursively typecast XML values based on type attributes

Examples:

Typecast integer value

typecast_xml_value({"__content__" => "42", "type" => "integer"})
#=> 42

Parameters:

  • value (Hash, Array, Object) —

    Value to typecast

  • disallowed_types (Array<String>) (defaults to: DISALLOWED_TYPES) —

    Types to reject

Returns:

  • (Object) —

    Typecasted value

Raises:



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

def typecast_xml_value(value, disallowed_types = DISALLOWED_TYPES)
  case value
  when Hash then typecast_hash(value, disallowed_types)
  when Array then typecast_array(value, disallowed_types)
  else value
  end
end

.undasherize_keys(data) ⇒ Hash, ...

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Recursively convert dashes in hash keys to underscores

Examples:

Convert dashed keys

undasherize_keys({"first-name" => "John"}) #=> {"first_name" => "John"}

Parameters:

  • data (Hash, Array, Object) —

    Data to transform

Returns:

  • (Hash, Array, Object) —

    Transformed data with undasherized keys



29
30
31
 
# File 'lib/multi_xml/helpers.rb', line 29

def undasherize_keys(data)
  transform_keys(data) { |key| key.tr("-", "_") }
end

.unwrap_file_if_present(result) ⇒ Hash, StringIO

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Unwrap a file object from the result hash if present

Parameters:

  • result (Hash) —

    Hash that may contain a file

Returns:

  • (Hash, StringIO) —

    The file if present, otherwise the hash



208
209
210
211
 
# File 'lib/multi_xml/helpers.rb', line 208

def unwrap_file_if_present(result)
  file = result["file"]
  file.is_a?(StringIO) ? file : result
end

.unwrap_if_simple(hash, value) ⇒ Object, Hash

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Unwrap value if hash has no other significant keys

Parameters:

  • hash (Hash) —

    Original hash

  • value (Object) —

    Converted value

Returns:

  • (Object, Hash) —

    Value or hash with merged content



170
171
172
 
# File 'lib/multi_xml/helpers.rb', line 170

def unwrap_if_simple(hash, value)
  (hash.size > 1) ? hash.merge(TEXT_CONTENT_KEY => value) : value
end

.wrap_and_typecast(entries, disallowed_types) ⇒ Array

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Wrap hash in array if needed and typecast all entries

Parameters:

  • entries (Array, Hash) —

    Entries to process

  • disallowed_types (Array<String>) —

    Types to reject

Returns:

  • (Array) —

    Typecasted entries



145
146
147
148
 
# File 'lib/multi_xml/helpers.rb', line 145

def wrap_and_typecast(entries, disallowed_types)
  entries = [entries] if entries.is_a?(Hash)
  entries.map { |entry| typecast_xml_value(entry, disallowed_types) }
end

Instance Method Details

#self?.apply_converter ⇒ xmlValue

Apply a type converter to content Content is xmlValue (from hash.fetch) but typically String in practice

Parameters:

  • hash (xmlHash)
  • content (Object)
  • converter (Proc, Method)

Returns:

  • (xmlValue) 


235
 
# File 'sig/multi_xml.rbs', line 235

def self?.apply_converter: (xmlHash hash, untyped content, Proc | Method converter) -> xmlValue

#self?.convert_hash ⇒ xmlValue

Convert a hash based on its type and content

Parameters:

  • hash (xmlHash)
  • type (xmlValue)
  • disallowed_types (Array[String])

Returns:

  • (xmlValue) 


198
 
# File 'sig/multi_xml.rbs', line 198

def self?.convert_hash: (xmlHash hash, xmlValue type, Array[String] disallowed_types) -> xmlValue

#self?.convert_text_content ⇒ xmlValue

Convert text content using type converters hash is xmlValue, used as Hash key - Steep requires String

Parameters:

  • hash (xmlHash)

Returns:

  • (xmlValue) 


215
 
# File 'sig/multi_xml.rbs', line 215

def self?.convert_text_content: (xmlHash hash) -> xmlValue

#self?.disallowed_type? ⇒ boolish

Check if a type is in the disallowed list Uses is_a?(Hash) guard then include? - Steep can't narrow xmlValue to String

Parameters:

  • type (Object)
  • disallowed_types (Array[String])

Returns:

  • (boolish) 


195
 
# File 'sig/multi_xml.rbs', line 195

def self?.disallowed_type?: (untyped type, Array[String] disallowed_types) -> boolish

#self?.empty_value? ⇒ Boolean

Check if a hash represents an empty value

Parameters:

  • hash (xmlHash)
  • type (xmlValue)

Returns:

  • (Boolean) 


221
 
# File 'sig/multi_xml.rbs', line 221

def self?.empty_value?: (xmlHash hash, xmlValue type) -> bool

#self?.extract_array_entries ⇒ Array[xmlValue]

Extract array entries from element with type="array"

Parameters:

  • hash (xmlHash)
  • disallowed_types (Array[String])

Returns:

  • (Array[xmlValue]) 


204
 
# File 'sig/multi_xml.rbs', line 204

def self?.extract_array_entries: (xmlHash hash, Array[String] disallowed_types) -> Array[xmlValue]

#self?.find_array_entries ⇒ Object

Find array or hash entries in a hash, excluding the type key Returns xmlValue subset (Array or Hash) - uses is_a? that Steep can't narrow

Parameters:

  • hash (xmlHash)

Returns:

  • (Object) 


208
 
# File 'sig/multi_xml.rbs', line 208

def self?.find_array_entries: (xmlHash hash) -> untyped

#self?.symbolize_keys ⇒ Object

Recursively convert all hash keys to symbols Uses case/when type dispatch - Steep can't track flow narrowing

Parameters:

  • data (Object)

Returns:

  • (Object) 


177
 
# File 'sig/multi_xml.rbs', line 177

def self?.symbolize_keys: (untyped data) -> untyped

#self?.transform_keys {|arg0| ... } ⇒ Object

Recursively transform hash keys using a block Block receives key (String) and returns transformed key Uses untyped because &:to_sym Proc type narrowing not supported by Steep

Parameters:

  • data (Object)

Yields:

Yield Parameters:

  • arg0 (Object)

Yield Returns:

  • (Object)

Returns:

  • (Object) 


228
 
# File 'sig/multi_xml.rbs', line 228

def self?.transform_keys: (untyped data) { (untyped) -> untyped } -> untyped

#self?.typecast_array ⇒ xmlValue

Typecast array elements and unwrap single-element arrays

Parameters:

  • array (Array[xmlValue])
  • disallowed_types (Array[String])

Returns:

  • (xmlValue) 


188
 
# File 'sig/multi_xml.rbs', line 188

def self?.typecast_array: (Array[xmlValue] array, Array[String] disallowed_types) -> xmlValue

#self?.typecast_children ⇒ xmlHash, StringIO

Typecast all child values in a hash

Parameters:

  • hash (xmlHash)
  • disallowed_types (Array[String])

Returns:

  • (xmlHash, StringIO) 


201
 
# File 'sig/multi_xml.rbs', line 201

def self?.typecast_children: (xmlHash hash, Array[String] disallowed_types) -> (xmlHash | StringIO)

#self?.typecast_hash ⇒ xmlValue

Typecast a hash based on its type attribute

Parameters:

  • hash (xmlHash)
  • disallowed_types (Array[String])

Returns:

  • (xmlValue) 


191
 
# File 'sig/multi_xml.rbs', line 191

def self?.typecast_hash: (xmlHash hash, Array[String] disallowed_types) -> xmlValue

#self?.typecast_xml_value ⇒ xmlValue

Recursively typecast XML values based on type attributes Uses case/when type dispatch - Steep can't track flow narrowing

Parameters:

  • value (Object)
  • disallowed_types (Array[String])

Returns:

  • (xmlValue) 


185
 
# File 'sig/multi_xml.rbs', line 185

def self?.typecast_xml_value: (untyped value, ?Array[String] disallowed_types) -> xmlValue

#self?.undasherize_keys ⇒ Object

Recursively convert dashes in hash keys to underscores Uses case/when type dispatch - Steep can't track flow narrowing

Parameters:

  • data (Object)

Returns:

  • (Object) 


181
 
# File 'sig/multi_xml.rbs', line 181

def self?.undasherize_keys: (untyped data) -> untyped

#self?.unwrap_file_if_present ⇒ xmlHash, StringIO

Unwrap a file object from the result hash if present

Parameters:

  • result (xmlHash)

Returns:

  • (xmlHash, StringIO) 


231
 
# File 'sig/multi_xml.rbs', line 231

def self?.unwrap_file_if_present: (xmlHash result) -> (xmlHash | StringIO)

#self?.unwrap_if_simple ⇒ xmlValue, xmlHash

Unwrap value if hash has no other significant keys

Parameters:

  • hash (xmlHash)
  • value (xmlValue)

Returns:

  • (xmlValue, xmlHash) 


218
 
# File 'sig/multi_xml.rbs', line 218

def self?.unwrap_if_simple: (xmlHash hash, xmlValue value) -> (xmlValue | xmlHash)

#self?.wrap_and_typecast ⇒ Array[xmlValue]

Wrap hash in array if needed and typecast all entries

Parameters:

  • entries (Array[xmlValue], xmlHash)
  • disallowed_types (Array[String])

Returns:

  • (Array[xmlValue]) 


211
 
# File 'sig/multi_xml.rbs', line 211

def self?.wrap_and_typecast: (Array[xmlValue] | xmlHash entries, Array[String] disallowed_types) -> Array[xmlValue]