Class: OFX::Configuration

Inherits:
Object
  • Object
show all
Defined in:
lib/ofx_kit/configuration/core.rb,
lib/ofx_kit/configuration/date_parser.rb,
lib/ofx_kit/configuration/section_proxy.rb,
lib/ofx_kit/configuration/mapping_applicator.rb

Overview

Manages XML-to-Ruby field mappings used during OFX document parsing.

Mappings are split into two layers:

  • Core (core_mappings.yml): OFX-standard fields whose Ruby attribute names are referenced by name inside Base::Builder. These cannot be overridden.

  • User (field_mappings.yml): convenience mappings that can be added to or replaced at runtime via #load_mappings or the OFX.configure block.

Defined Under Namespace

Modules: DateParser, MappingApplicator Classes: SectionProxy

Constant Summary collapse

CORE_MAPPINGS_PATH =

Absolute path to the built-in core OFX field mappings (read-only).

File.join(__dir__, '..', 'mappings', 'core_mappings.yml')
MAPPINGS_PATH =

Absolute path to the built-in user-layer field mappings.

File.join(__dir__, '..', 'mappings', 'field_mappings.yml')
RAILS_MAPPINGS_PATH =

Conventional path for user mappings in a Rails application. Auto-loaded on boot when present. Ejected via rails generate ofx_kit:eject.

'config/initializers/ofx_mappings.yml'

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(auto_load_path: File.expand_path(RAILS_MAPPINGS_PATH)) ⇒ Configuration

Creates a new Configuration instance. auto_load_path is the path to a YAML mappings file loaded automatically on initialization. Defaults to RAILS_MAPPINGS_PATH expanded from the working directory.



43
44
45
46
47
48
49
50
51
52
53
54
55
 
# File 'lib/ofx_kit/configuration/core.rb', line 43

def initialize(auto_load_path: File.expand_path(RAILS_MAPPINGS_PATH))
  @multi_statement_warnings = true

  core = YAML.safe_load_file(CORE_MAPPINGS_PATH)
  @sections = core.fetch('SECTIONS', {})
  @core_fields = core.fetch('FIELDS', {})
  @section_to_tag = @sections.invert

  user = YAML.safe_load_file(MAPPINGS_PATH)
  @user_fields = user.fetch('FIELDS', {})

  load_mappings(auto_load_path) if File.exist?(auto_load_path)
end

Instance Attribute Details

#multi_statement_warnings=(value) ⇒ Object (writeonly)

Controls whether a warning is emitted when OFX::Parser#transactions or OFX::Parser#balances aggregate across multiple statements. Defaults to true.



31
32
33
 
# File 'lib/ofx_kit/configuration/core.rb', line 31

def multi_statement_warnings=(value)
  @multi_statement_warnings = value
end

Instance Method Details

#balance ⇒ Object

Returns a SectionProxy for balance field mappings.



79
 
# File 'lib/ofx_kit/configuration/core.rb', line 79

def balance               = SectionProxy.new(@user_fields, @core_fields, xml_tag_for(:balance))

#bank_account ⇒ Object

Returns a SectionProxy for bank account field mappings.



71
 
# File 'lib/ofx_kit/configuration/core.rb', line 71

def           = SectionProxy.new(@user_fields, @core_fields, xml_tag_for(:bank_account))

#bank_statement ⇒ Object

Returns a SectionProxy for bank statement field mappings.



59
 
# File 'lib/ofx_kit/configuration/core.rb', line 59

def bank_statement        = SectionProxy.new(@user_fields, @core_fields, xml_tag_for(:bank_statement))

#credit_card_account ⇒ Object

Returns a SectionProxy for credit card account field mappings.



75
 
# File 'lib/ofx_kit/configuration/core.rb', line 75

def    = SectionProxy.new(@user_fields, @core_fields, xml_tag_for(:credit_card_account))

#credit_card_statement ⇒ Object

Returns a SectionProxy for credit card statement field mappings.



63
 
# File 'lib/ofx_kit/configuration/core.rb', line 63

def credit_card_statement = SectionProxy.new(@user_fields, @core_fields, xml_tag_for(:credit_card_statement))

#load_mappings(path) ⇒ Object

Merges additional field mappings from a YAML file at path (String) into the user-layer configuration. The file must have a top-level FIELDS key. Core OFX fields cannot be overridden.

Raises Errors::ConfigurationError if the file is missing, malformed, references unknown sections, or attempts to override a core field mapping.

Example: Load a custom mappings file

OFX.configure do |config|
  config.load_mappings 'config/my_ofx_mappings.yml'
end

Example: Expected YAML format

# config/my_ofx_mappings.yml
FIELDS:
  STMTTRN:
    MYFIELD: my_attribute

Raises:



119
120
121
122
123
124
125
126
127
128
129
130
 
# File 'lib/ofx_kit/configuration/core.rb', line 119

def load_mappings(path)
  raise Errors::ConfigurationError, "Mappings file not found: #{path}" unless File.exist?(path)

  raw = YAML.safe_load_file(path)
  raise Errors::ConfigurationError, 'Invalid mappings file: expected a Hash' unless raw.is_a?(Hash)

  fields = raw.fetch('FIELDS') do
    raise Errors::ConfigurationError, "Invalid mappings file: missing top-level 'FIELDS' key"
  end

  fields.each { |tag, mappings| merge_user_section(tag, mappings) }
end

#multi_statement_warnings? ⇒ Boolean

Returns true if multi-statement aggregation warnings are enabled.

Returns:

  • (Boolean) 


35
36
37
 
# File 'lib/ofx_kit/configuration/core.rb', line 35

def multi_statement_warnings?
  @multi_statement_warnings
end

#transaction ⇒ Object

Returns a SectionProxy for transaction field mappings.



67
 
# File 'lib/ofx_kit/configuration/core.rb', line 67

def transaction           = SectionProxy.new(@user_fields, @core_fields, xml_tag_for(:transaction))

#xml_mappings_for(section_name) ⇒ Object

Returns the merged Hash of XML tag to Ruby attribute mappings for the given section_name (String or Symbol). Core mappings take precedence; user mappings extend them.



92
93
94
95
96
97
 
# File 'lib/ofx_kit/configuration/core.rb', line 92

def xml_mappings_for(section_name)
  tag = xml_tag_for(section_name)
  return {} unless tag

  (@core_fields[tag] || {}).merge(@user_fields[tag] || {})
end

#xml_tag_for(section_name) ⇒ Object

Returns the OFX XML tag name corresponding to the given section_name (String or Symbol), e.g. :transaction. Returns nil if not found.



84
85
86
 
# File 'lib/ofx_kit/configuration/core.rb', line 84

def xml_tag_for(section_name)
  @section_to_tag[section_name.to_s]
end