stockboy 0.5.0

data/lib/stockboy/readers/xml.rb

@@ -0,0 +1,155 @@
+require 'stockboy/reader'
+require 'stockboy/string_pool'
+
+module Stockboy::Readers
+
+  # Extract data from XML
+  #
+  # This works great with SOAP, probably not fully-featured yet for various XML
+  # formats.  The SOAP provider returns a hash, because it takes care of
+  # extracting the envelope body already, so this reader supports options for
+  # reading elements from a nested hash too.
+  #
+  # Backed by the Nori gem from Savon, see nori for full options.
+  #
+  class XML < Stockboy::Reader
+    include Stockboy::StringPool
+
+    # Override source encoding
+    #
+    # @!attribute [rw] encoding
+    # @return [String]
+    #
+    dsl_attr :encoding
+
+    # Element nesting to traverse, the last one should represent the record
+    # instances that contain tags for each attribute.
+    #
+    # @!attribute [rw] elements
+    # @return [Array]
+    # @example
+    #   elements ["allItemsResponse", "itemList", "recordItem"]
+    #
+    dsl_attr :elements, attr_accessor: false
+
+    # Removes namespace prefixes from tag names, default true.
+    #
+    # @!attribute [rw] strip_namespaces
+    # @return [Boolean]
+    #
+    dsl_attr :strip_namespaces, attr_accessor: false
+
+    # Change tag formatting, e.g. underscore if it happens to match your actual
+    # record attributes
+    #
+    # @!attribute [rw] convert_tags_to
+    # @return [Proc]
+    # @example
+    #   convert_tags_to ->(tag) { tag.underscore }
+    #
+    dsl_attr :convert_tags_to, attr_accessor: false
+
+    # Detects input tag types and tries to extract dates, times, etc. from the data.
+    # Normally this is handled by the attribute map.
+    #
+    # @!attribute [rw] advanced_typecasting
+    # @return [Boolean]
+    #
+    dsl_attr :advanced_typecasting, attr_accessor: false
+
+    # Defaults to Nokogiri. Why would you change it?
+    #
+    # @!attribute [rw] parser
+    # @return [Symbol]
+    #
+    dsl_attr :parser, attr_accessor: false
+
+    [:strip_namespaces, :convert_tags_to, :advanced_typecasting, :parser].each do |opt|
+      define_method(opt)        { @xml_options[opt] }
+      define_method(:"#{opt}=") { |value| @xml_options[opt] = value }
+    end
+
+    def elements
+      convert_tags_to ? @elements.map(&convert_tags_to) : @elements
+    end
+
+    def elements=(schema)
+      return @elements = [] unless schema
+      raise(ArgumentError, "expected an array of XML tag strings") unless schema.is_a? Array
+      @elements = schema.map(&:to_s)
+    end
+
+    # @!endgroup
+
+    # Initialize a new XML reader
+    #
+    def initialize(opts={}, &block)
+      super
+      self.elements = opts.delete(:elements)
+      @xml_options = opts
+      DSL.new(self).instance_eval(&block) if block_given?
+    end
+
+    # XML options passed to the underlying Nori instance
+    #
+    # @!attribute [r] options
+    # @return [Hash]
+    #
+    def options
+      @xml_options
+    end
+
+    def parse(data)
+      hash = if data.is_a? Hash
+        data
+      else
+        if data.respond_to? :to_xml
+          data.to_xml("UTF-8")
+          nori.parse(data)
+        elsif data.respond_to? :to_hash
+          data.to_hash
+        else
+          data.encode!("UTF-8", encoding) if encoding
+          nori.parse(data)
+        end
+      end
+
+      with_string_pool do
+        remap_keys hash
+        extract hash
+      end
+    end
+
+    private
+
+    def nori
+      @nori ||= Nori.new(options)
+    end
+
+    def extract(hash)
+      result = elements.inject hash do |memo, key|
+        return [] if memo[key].nil?
+        memo[key]
+      end
+
+      result = [result] unless result.is_a? Array
+      result.compact!
+      result
+    end
+
+    def remap_keys(node)
+      mapper = convert_tags_to || ->(tag) { tag }
+      case node
+      when Hash
+        node.keys.each do |k|
+          tag = string_pool(mapper.call(k))
+          node[tag] = remap_keys(node.delete(k))
+        end
+      when Array
+        node.each { |value| remap_keys(value) }
+      end
+      node
+    end
+
+  end
+end

data/lib/stockboy/registry.rb

@@ -0,0 +1,42 @@
+module Stockboy
+
+  # Holds a collection of registered classes for convenient reference by
+  # symbolic name
+  #
+  module Registry
+
+    def self.extended(base)
+      base.class_eval do
+        @registry = {}
+      end
+    end
+
+    # Register a class under a convenient symbolic name
+    #
+    # @param [Symbol] key      Symbolic name of the class
+    # @param [Class]  provider Class to be returned when requested
+    #
+    def register(key, provider)
+      @registry[key] = provider
+    end
+
+    # Look up a class and return it by symbolic name
+    #
+    # @param [Symbol] key
+    # @return [Class]
+    #
+    def find(key)
+      @registry[key]
+    end
+    alias_method :[], :find
+
+    # List all named classes in the registry
+    #
+    # @return [Hash]
+    #
+    def all
+      @registry
+    end
+
+  end
+end

data/lib/stockboy/source_record.rb

@@ -0,0 +1,43 @@
+require 'stockboy/mapped_record'
+
+module Stockboy
+
+  # This represents the raw "input" side of a {CandidateRecord}
+  #
+  # It provides access to the original field values before mapping or
+  # translation as hash keys.
+  #
+  # @example
+  #   input = SourceRecord.new(
+  #       {check_in: "2012-12-12"},
+  #       {"RawCheckIn" => "2012-12-12"})
+  #
+  #   input["RawCheckIn"] # => "2012-12-12"
+  #   input.check_in # => "2012-12-12"
+  #
+  class SourceRecord < MappedRecord
+
+    # Initialize a new instance
+    #
+    # @param [Hash{Symbol=>Object}] mapped_fields
+    #   Represents the raw values mapped to the final attribute names
+    # @param [Hash] data_fields
+    #   The raw input fields with original key values
+    #
+    def initialize(mapped_fields, data_fields)
+      @data_fields = data_fields
+      super(mapped_fields)
+    end
+
+    # Access a raw field value by the original input field name
+    #
+    # @param [String] key
+    #
+    def [](key)
+      key = key.to_s if key.is_a? Symbol
+      @data_fields[key]
+    end
+
+  end
+
+end

data/lib/stockboy/string_pool.rb

@@ -0,0 +1,35 @@
+module Stockboy
+
+  # Holds frozen strings for shared lookup between different object instances
+  #
+  # @visibility private
+  #
+  module StringPool
+
+    # Pass a block to yield a new string pool context around a group of
+    # actions that should share the same string key instances
+    #
+    # @yield
+    #
+    def with_string_pool
+      @string_pool = []
+      result = yield
+      @string_pool = []
+      result
+    end
+
+    # Look up duplicate strings and return the shared frozen string
+    #
+    # @return [String]
+    #
+    def string_pool(name)
+      if i = @string_pool.index(name)
+        @string_pool[i]
+      else
+       @string_pool << name.freeze
+       name
+      end
+    end
+
+  end
+end

data/lib/stockboy/template_file.rb

@@ -0,0 +1,44 @@
+require 'stockboy/configuration'
+
+module Stockboy
+
+  # Find and read template files from the configured load paths
+  #
+  module TemplateFile
+
+    # Read template file contents for defining a new job
+    #
+    # @param [String] template_name
+    #   The file basename of a predefined template
+    # @return [String] Job template DSL or nil if nothing is found
+    #
+    def self.read(template_name)
+      return template_name.read if template_name.is_a? File
+      return unless path = find(template_name)
+
+      File.read(path)
+    end
+
+    # Find a named DSL template from configuration.template_load_paths
+    #
+    # @param [String] filename Template basename to be searched from load paths
+    # @return [String] The full path to the first matched filename if found
+    #
+    def self.find(filename)
+      sources = template_file_paths(filename)
+      Dir.glob(sources).first
+    end
+
+    # Potential locations for finding a template file
+    #
+    # @param [String] filename Template basename
+    # @return [Array] filename on each possible load path
+    #
+    def self.template_file_paths(filename)
+      filename = "#{filename}.rb" unless filename =~ /\.rb$/
+      load_paths = Array(Stockboy.configuration.template_load_paths)
+      load_paths.map { |d| File.join(d, filename) }
+    end
+
+  end
+end

data/lib/stockboy/translations.rb

@@ -0,0 +1,70 @@
+require 'stockboy/exceptions'
+require 'stockboy/translator'
+
+module Stockboy
+
+  # Registry of available {Translator} classes for lookup by symbolic name in the
+  # job template DSL.
+  #
+  module Translations
+
+    @registry ||= {}
+
+    # Register a translator under a convenient symbolic name
+    #
+    # @param [Symbol] name
+    #   Symbolic name of the class
+    # @param [Translator, #call] callable
+    #   Translator class or any callable object
+    #
+    def self.register(name, callable)
+      if callable.respond_to?(:call) or callable < Stockboy::Translator
+        @registry[name.to_sym] = callable
+      else
+        raise ArgumentError, "Registered translators must be callable"
+      end
+    end
+
+    # Calls a named translator for the raw value
+    #
+    # @param [Symbol, Translator, #call] func_name
+    #   Symbol representing a registered translator, or an actual translator
+    # @param [SourceRecord, MappedRecord, Hash, String] context
+    #   Collection of fields or the raw value to which the translation is applied
+    #
+    def self.translate(func_name, context)
+      translator_for(:value, func_name).call(context)
+    end
+
+    # Prepare a translator for a given attribute
+    #
+    # @param [Symbol] attr
+    #   Name of the mapped record attribute to address for translation
+    # @param [Symbol, #call] lookup
+    #   Symbolic translator name or callable object
+    # @return [Translator] instance
+    #
+    def self.translator_for(attr, lookup)
+      if lookup.respond_to?(:call)
+        lookup
+      elsif tr = self[lookup]
+        tr.is_a?(Class) && tr < Stockboy::Translator ? tr.new(attr) : tr
+      else
+        ->(context) { context.public_send attr } # no-op
+      end
+    end
+
+    # Look up a translation and return it by symbolic name
+    #
+    # @param [Symbol] func_name
+    # @return [Translator]
+    #
+    def self.find(func_name)
+      @registry[func_name]
+    end
+    class << self
+      alias_method :[], :find
+    end
+
+  end
+end

data/lib/stockboy/translations/boolean.rb

@@ -0,0 +1,58 @@
+require 'stockboy/translator'
+
+module Stockboy::Translations
+
+  # Convert common false-like and true-like values to proper boolean +true+ or
+  # +false+.
+  #
+  # Returns nil for indeterminate values. This should be chained with a
+  # default value translator like [DefaultFalse] or [DefaultTrue].
+  #
+  # == Job template DSL
+  #
+  # Registered as +:boolean+. Use with:
+  #
+  #   attributes do
+  #     active as: :boolean
+  #   end
+  #
+  # @example
+  #   bool = Stockboy::Translator::Boolean.new
+  #
+  #   record.active = 't'
+  #   bool.translate(record, :active) # => true
+  #
+  #   record.active = 'f'
+  #   bool.translate(record, :active) # => false
+  #
+  #   record.active = '1'
+  #   bool.translate(record, :active) # => true
+  #
+  #   record.active = '0'
+  #   bool.translate(record, :active) # => false
+  #
+  #   record.active = 'y'
+  #   bool.translate(record, :active) # => true
+  #
+  #   record.active = 'n'
+  #   bool.translate(record, :active) # => false
+  #
+  #   record.active = '?'
+  #   bool.translate(record, :active) # => nil
+  #
+  class Boolean < Stockboy::Translator
+    TRUTHY_VALUES = [true, 1, '1', 't', 'T', 'true', 'TRUE', 'y', 'Y', 'yes', 'YES']
+    FALSY_VALUES = [false, 0, '0', 'f', 'F', 'false', 'FALSE', 'n', 'N', 'no', 'NO']
+
+    # @return [Boolean]
+    #
+    def translate(context)
+      value = field_value(context, field_key)
+
+      return true if TRUTHY_VALUES.include?(value)
+      return false if FALSY_VALUES.include?(value)
+      return nil
+    end
+
+  end
+end