Class: Lutaml::Model::Listener

Inherits:
Object
  • Object
show all
Defined in:
lib/lutaml/model/mapping/listener.rb

Overview

Base listener class for the listener-based mapping model.

Listeners are handlers that respond to format elements/keys (e.g., XML element names, JSON keys). Multiple listeners per element are allowed, and all matching listeners are invoked during parsing.

There are two types of listeners:

  • Simple listeners: Created via map_element/map_attribute DSL (no handler block). The framework handles the default deserialization behavior.

  • Complex listeners: Created via on_element/on_attribute DSL (with handler block). The block provides custom deserialization logic.

Examples:

Simple listener (implicit handler)

Lutaml::Xml::Mapping do
  map_element "Documentation", to: :documentation
end

Complex listener (explicit handler)

Lutaml::Xml::Mapping do
  on_element "CustomElement", id: :custom_parse do |element, context|
    context[:custom] = CustomParser.parse(element)
  end
end

Multiple listeners for same element

class MyMapping < Lutaml::Xml::Mapping
  on_element "Documentation", id: :parse_docs do |element, context|
    context[:documentation] = Documentation.from_xml(element)
  end

  on_element "Documentation", id: :log_docs do |element, context|
    logger.info("Parsing docs")
  end
end

Inheritance with override

class ExtendedMapping < BaseMapping
  # Overrides parent's :parse_docs listener
  on_element "Documentation", id: :parse_docs do |element, context|
    context[:documentation] = EnhancedDocs.from_xml(element)
  end

  # New listener (added to parent's)
  on_element "Extension", id: :parse_ext do |element, context|
    context[:extension] = Extension.from_xml(element)
  end

  # Remove a specific parent listener
  omit_listener "TaggedValue", id: :validate_tags

  # Remove all listeners for an element
  omit_element "UnusedElement"
end

Direct Known Subclasses

Xml::Listener

Defined Under Namespace

Classes: NoHandlerError

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(id:, target:, handler: nil, **options) ⇒ Listener

Returns a new instance of Listener.

Parameters:

  • id (Symbol, String, nil) —

    Unique identifier for this listener. Used for override/omit operations. Defaults to nil (no override/omit support).

  • target (String, Symbol) —

    The element name or key this listener responds to.

  • handler (Proc, nil) (defaults to: nil) —

    Custom handler block for complex listeners. Nil for simple listeners (framework handles deserialization).

  • options (Hash) —

    Additional options for the listener.



67
68
69
70
71
72
73
 
# File 'lib/lutaml/model/mapping/listener.rb', line 67

def initialize(id:, target:, handler: nil, **options)
  @id = id
  @target = target.to_s if target
  @handler = handler
  @options = options.freeze
  freeze
end

Instance Attribute Details

#handler ⇒ Object (readonly)

Returns the value of attribute handler.



59
60
61
 
# File 'lib/lutaml/model/mapping/listener.rb', line 59

def handler
  @handler
end

#id ⇒ Object (readonly)

Returns the value of attribute id.



59
60
61
 
# File 'lib/lutaml/model/mapping/listener.rb', line 59

def id
  @id
end

#options ⇒ Object (readonly)

Returns the value of attribute options.



59
60
61
 
# File 'lib/lutaml/model/mapping/listener.rb', line 59

def options
  @options
end

#target ⇒ Object (readonly)

Returns the value of attribute target.



59
60
61
 
# File 'lib/lutaml/model/mapping/listener.rb', line 59

def target
  @target
end

Instance Method Details

#call(*args) ⇒ Object

Invoke the listener’s handler with the given arguments.

rubocop:disable Style/ArgumentsForwarding – anonymous * requires Ruby 3.2+

Parameters:

  • args (Array) —

    Arguments to pass to the handler block

Returns:

  • (Object) —

    Result of the handler invocation



95
96
97
98
99
100
101
102
103
 
# File 'lib/lutaml/model/mapping/listener.rb', line 95

def call(*args)
  if simple?
    raise NoHandlerError,
          "Cannot call simple listener #{id.inspect}"
  end

  @handler.call(*args)
  # rubocop:enable Style/ArgumentsForwarding
end

#complex? ⇒ Boolean

Returns true if this is a complex listener (has a custom handler).

Returns:

  • (Boolean) 


86
87
88
 
# File 'lib/lutaml/model/mapping/listener.rb', line 86

def complex?
  !simple?
end

#eql?(other) ⇒ Boolean Also known as: ==

Equality based on id and target (for deduplication)

Returns:

  • (Boolean) 


118
119
120
121
122
 
# File 'lib/lutaml/model/mapping/listener.rb', line 118

def eql?(other)
  other.is_a?(Listener) &&
    id == other.id &&
    target == other.target
end

#inspect ⇒ Object 



108
109
110
111
 
# File 'lib/lutaml/model/mapping/listener.rb', line 108

def inspect
  "#<#{self.class.name} id=#{id.inspect} target=#{target.inspect} " \
    "simple=#{simple?}>"
end

#simple? ⇒ Boolean

Returns true if this is a simple listener (no custom handler). Simple listeners rely on framework default deserialization behavior.

Returns:

  • (Boolean) 


79
80
81
 
# File 'lib/lutaml/model/mapping/listener.rb', line 79

def simple?
  @handler.nil?
end

#to_s ⇒ Object 



113
114
115
 
# File 'lib/lutaml/model/mapping/listener.rb', line 113

def to_s
  inspect
end