hermod 1.0.1

data/lib/hermod/xml_section.rb

@@ -0,0 +1,108 @@
+require 'xml'
+require 'hermod/xml_section_builder'
+require 'hermod/sanitisation'
+
+module Hermod
+  # A representation of a section of XML sent to HMRC using the Government
+  # Gateway
+  class XmlSection
+    include Sanitisation
+
+    # Public: builds a new class using the XmlSectionBuilder DSL
+    #
+    # Returns the new Class
+    def self.build(options = {}, &block)
+      Class.new(XmlSection).tap do |new_class|
+        options.each do |name, value|
+          new_class.public_send "#{name}=", value
+        end
+        XmlSectionBuilder.new(new_class).build(&block)
+      end
+    end
+
+    attr_reader :attributes
+
+    # Public: turns the XmlSection into an XML::Node instance (from
+    # libxml-ruby). This creates this as a node, adds any attributes (after
+    # sanitising them according to HMRC's rules) and then adds child nodes in
+    # the order they were defined in the DSL. Nodes that have been called multiple
+    # times are added in the order they were called.
+    #
+    # Returns an XML::Node
+    def to_xml
+      XML::Node.new(self.class.xml_name).tap do |root_node|
+        # Add attributes
+        attributes.each do |attribute_name, attribute_value|
+          sane_value = sanitise_attribute(attribute_value)
+          root_node[attribute_name] = sane_value if sane_value.present?
+        end
+        # Add child nodes
+        self.class.node_order.each do |node_name|
+          nodes[node_name].each do |node|
+            root_node << node.to_xml
+          end
+        end
+      end
+    end
+
+    # Internal: creates an XmlSection. This shouldn't normally be called
+    # directly, instead the subclasses call it as they define a useful
+    # NODE_ORDER.
+    #
+    # name  - a Symbol that corresponds to the node name in NODE_ORDER
+    # block - a Block that will be executed in the context of this class for
+    #         setting up descendents.
+    def initialize(attributes={}, &block)
+      @attributes = attributes
+      yield self if block_given?
+    end
+
+    class << self
+      attr_writer :xml_name, :formats
+      attr_accessor :node_order
+    end
+
+    # Internal: a class method for getting the name of the XML node used when
+    # converting instances to XML for HMRC. If the `xml_name` has been set then
+    # it will be used, otherwise the class name will be used as a default.
+    #
+    # Returns a String
+    def self.xml_name
+      @xml_name || name.demodulize
+    end
+
+    # Internal: provides access to the formats hash, falling back on an empty
+    # hash by default. These formats are used by the date and monetary nodes
+    # for converting their values to strings HMRC will accept.
+    #
+    # Returns a Hash
+    def self.formats
+      @formats ||= {
+        date: "%Y-%m-%d",
+        money: "%.2f"
+      }
+    end
+
+    # Internal: provides access to the hash of nodes where the default for an
+    # unspecified key is an empty array. This stores the nodes as they are
+    # created with the key being the name of the node (which is the name of the
+    # method called to set it) and the value being an array of all the values
+    # set on this node in the order they are set.
+    #
+    # Returns a Hash
+    def nodes
+      @nodes ||= Hash.new { |h, k| h[k] = [] }
+    end
+
+    private
+
+    # Private: a convenience method for getting the format string for a given
+    # key.
+    #
+    # Returns a format String
+    # Raises a KeyError if the requested format is not found
+    def format_for(type)
+      self.class.formats.fetch(type)
+    end
+  end
+end

data/lib/hermod/xml_section_builder.rb

@@ -0,0 +1,223 @@
+require 'bigdecimal'
+require 'active_support'
+require 'active_support/core_ext/string/inflections'
+require 'active_support/core_ext/object/blank'
+
+require 'hermod/xml_node'
+
+module Hermod
+
+  # Internal: the base class from which all Hermod errors inherit
+  XmlError = Class.new(StandardError)
+
+  # Public: the error that's raised whenever some validation or constraint
+  # specified on a node fails.
+  InvalidInputError = Class.new(XmlError)
+
+  # Public: the error that's raised when you try to define two nodes with the
+  # same name when building an XmlSection.
+  DuplicateNodeError = Class.new(XmlError)
+
+  # Public: Used to build an anonymous subclass of XmlSection with methods for
+  # defining nodes on that subclass of varying types used by HMRC.
+  class XmlSectionBuilder
+
+    ZERO = BigDecimal.new('0').freeze
+    BOOLEAN_VALUES = [
+      YES = "yes".freeze,
+      NO  = "no".freeze,
+    ]
+
+    # Internal: Sets up the builder with the anonymous subclass of XmlSection.
+    # Don't use this directly, instead see `Hermod::XmlSection.build`
+    def initialize(new_class)
+      @new_class = new_class
+      @node_order = []
+    end
+
+    # Internal: Takes a block to build the class using the methods on this
+    # builder and then sets the correct node_order (to ensure the nodes are
+    # ordered correctly in the XML).
+    #
+    # Returns the newly built class. This should be assigned to a constant
+    # before use.
+    def build(&block)
+      yield self
+      @new_class.node_order = @node_order
+      @new_class
+    end
+
+    # Public: defines a node for sending a string to HMRC
+    #
+    # symbolic_name - the name of the node. This will become the name of the
+    #                 method on the XmlSection.
+    # options       - a hash of options used to set up validations.
+    #
+    # Returns nothing you should rely on
+    def string_node(symbolic_name, options={})
+      raise DuplicateNodeError, "#{symbolic_name} is already defined" if @node_order.include? symbolic_name
+      @node_order << symbolic_name
+
+      xml_name = options.fetch(:xml_name, symbolic_name.to_s.camelize)
+
+      @new_class.send :define_method, symbolic_name do |value, attributes={}|
+        if options.has_key?(:input_mutator)
+          value, attributes = options[:input_mutator].call(value, attributes)
+        end
+        if value.blank?
+          if options[:optional]
+            return # Don't need to add an empty node
+          else
+            raise InvalidInputError, "#{symbolic_name} isn't optional but no value was provided"
+          end
+        end
+        if options.has_key?(:allowed_values) && !options[:allowed_values].include?(value)
+          raise InvalidInputError,
+            "#{value.inspect} is not in the list of allowed values for #{symbolic_name}: #{options[:allowed_values].inspect}"
+        end
+        if options.has_key?(:matches) && value !~ options[:matches]
+          raise InvalidInputError,
+            "Value #{value.inspect} for #{symbolic_name} doesn't match #{options[:matches].inspect}"
+        end
+        nodes[symbolic_name] << XmlNode.new(xml_name, value.to_s, attributes).rename_attributes(options[:attributes])
+      end
+    end
+
+    # Public: defines a node for sending an integer to HMRC
+    #
+    # symbolic_name - the name of the node. This will become the name of the
+    #                 method on the XmlSection.
+    # options       - a hash of options used to set up validations.
+    #
+    # Returns nothing you should rely on
+    def integer_node(symbolic_name, options={})
+      raise DuplicateNodeError, "#{symbolic_name} is already defined" if @node_order.include? symbolic_name
+      @node_order << symbolic_name
+
+      xml_name = options.fetch(:xml_name, symbolic_name.to_s.camelize)
+
+      @new_class.send :define_method, symbolic_name do |value, attributes={}|
+        if options.has_key?(:range) && (options[:range][:min] > value || options[:range][:max] < value)
+          raise InvalidInputError,
+            "#{value} is outwith the allowable range for #{symbolic_name}: #{options[:range][:min]} - #{options[:range][:max]}"
+      end
+      nodes[symbolic_name] << XmlNode.new(xml_name, value.to_s, attributes).rename_attributes(options[:attributes]) if value.present?
+      end
+    end
+
+    # Public: defines a node for sending a date to HMRC
+    #
+    # symbolic_name - the name of the node. This will become the name of the
+    #                 method on the XmlSection.
+    # options       - a hash of options used to set up validations.
+    #
+    # Returns nothing you should rely on
+    def date_node(symbolic_name, options={})
+      raise DuplicateNodeError, "#{symbolic_name} is already defined" if @node_order.include? symbolic_name
+      @node_order << symbolic_name
+
+      xml_name = options.fetch(:xml_name, symbolic_name.to_s.camelize)
+
+      @new_class.send :define_method, symbolic_name do |value, attributes={}|
+        if value.blank?
+          if options[:optional]
+            return # Don't need to add an empty node
+          else
+            raise InvalidInputError, "#{symbolic_name} isn't optional but no value was provided"
+          end
+      end
+      unless value.respond_to?(:strftime)
+        raise InvalidInputError, "#{symbolic_name} must be set to a date"
+      end
+      nodes[symbolic_name] << XmlNode.new(xml_name, value.strftime(format_for(:date)), attributes).rename_attributes(options[:attributes])
+      end
+    end
+
+    # Public: defines a node for sending a boolean to HMRC. It will only be
+    # sent if the boolean is true.
+    #
+    # symbolic_name - the name of the node. This will become the name of the
+    #                 method on the XmlSection.
+    # options       - a hash of options used to set up validations.
+    #
+    # Returns nothing you should rely on
+    def yes_node(symbolic_name, options={})
+      raise DuplicateNodeError, "#{symbolic_name} is already defined" if @node_order.include? symbolic_name
+      @node_order << symbolic_name
+
+      xml_name = options.fetch(:xml_name, symbolic_name.to_s.camelize)
+
+      @new_class.send :define_method, symbolic_name do |value, attributes={}|
+        if value
+          nodes[symbolic_name] << XmlNode.new(xml_name, YES, attributes).rename_attributes(options[:attributes]) if value.present?
+      end
+      end
+    end
+
+    # Public: defines a node for sending a boolean to HMRC. A "yes" will be
+    # sent if it's true and a "no" will be sent if it's false
+    #
+    # symbolic_name - the name of the node. This will become the name of the
+    #                 method on the XmlSection.
+    # options       - a hash of options used to set up validations.
+    #
+    # Returns nothing you should rely on
+    def yes_no_node(symbolic_name, options={})
+      raise DuplicateNodeError, "#{symbolic_name} is already defined" if @node_order.include? symbolic_name
+      @node_order << symbolic_name
+
+      xml_name = options.fetch(:xml_name, symbolic_name.to_s.camelize)
+
+      @new_class.send :define_method, symbolic_name do |value, attributes={}|
+        nodes[symbolic_name] << XmlNode.new(xml_name, value ? YES : NO, attributes).rename_attributes(options[:attributes])
+      end
+    end
+
+    # Public: defines a node for sending a monetary value to HMRC
+    #
+    # symbolic_name - the name of the node. This will become the name of the
+    #                 method on the XmlSection.
+    # options       - a hash of options used to set up validations.
+    #
+    # Returns nothing you should rely on
+    def monetary_node(symbolic_name, options={})
+      raise DuplicateNodeError, "#{symbolic_name} is already defined" if @node_order.include? symbolic_name
+      @node_order << symbolic_name
+
+      xml_name = options.fetch(:xml_name, symbolic_name.to_s.camelize)
+
+      @new_class.send :define_method, symbolic_name do |value, attributes={}|
+        value ||= 0 # nils are zero
+      if !options.fetch(:negative, true) && value < ZERO
+        raise InvalidInputError, "#{symbolic_name} cannot be negative"
+      end
+      # Don't allow fractional values for whole number nodes
+      if options[:whole_units] && value != value.to_i
+        raise InvalidInputError, "#{symbolic_name} must be in whole pounds"
+      end
+      # Don't include optional nodes if they're zero
+      if !(options[:optional] && value.zero?)
+        nodes[symbolic_name] << XmlNode.new(xml_name, sprintf(format_for(:money), value), attributes).rename_attributes(options[:attributes]) if value.present?
+      end
+      end
+    end
+
+    # Public: defines an XML parent node that wraps other nodes
+    #
+    # symbolic_name - the name of the node. This will become the name of the
+    #                 method on the XmlSection.
+    # options       - a hash of options used to set up validations.
+    #
+    # Returns nothing you should rely on
+    def parent_node(symbolic_name, options={})
+      raise DuplicateNodeError, "#{symbolic_name} is already defined" if @node_order.include? symbolic_name
+      @node_order << symbolic_name
+
+      xml_name = options.fetch(:xml_name, symbolic_name.to_s.camelize)
+
+      @new_class.send :define_method, symbolic_name do |value, attributes={}|
+        nodes[symbolic_name] << XmlNode.new(xml_name, value, attributes).rename_attributes(options[:attributes]) if value.present?
+      end
+    end
+  end
+end

data/lib/hermod.rb

@@ -0,0 +1,5 @@
+require 'hermod/xml_section'
+
+# The namespace for the gem
+module Hermod
+end

data/spec/hermod/xml_section_builder/date_node_spec.rb

@@ -0,0 +1,27 @@
+require "minitest_helper"
+
+module Hermod
+  describe XmlSection do
+
+    DateXml = XmlSection.build(formats: {date: "%Y-%m-%d"}) do |builder|
+      builder.date_node :date_of_birth
+      builder.date_node :anniversary
+    end
+
+    describe "Date nodes" do
+      subject do
+        DateXml.new do |dummy|
+          dummy.date_of_birth Date.new(1988, 8, 13)
+        end
+      end
+
+      it "should format the date with the given date string" do
+        value_of_node("DateOfBirth").must_equal "1988-08-13"
+      end
+
+      it "should raise an error if given something that isn't a date" do
+        proc { subject.anniversary "yesterday" }.must_raise InvalidInputError
+      end
+    end
+  end
+end

data/spec/hermod/xml_section_builder/monetary_node_spec.rb

@@ -0,0 +1,50 @@
+require "minitest_helper"
+
+module Hermod
+  describe XmlSection do
+
+    MonetaryXml = XmlSection.build(formats: {money: "%.2f"}) do |builder|
+      builder.monetary_node :pay
+      builder.monetary_node :tax, optional: true
+      builder.monetary_node :ni, xml_name: "NI", negative: false
+      builder.monetary_node :pension, whole_units: true
+    end
+
+    describe "Monetary nodes" do
+      subject do
+        MonetaryXml.new do |dummy|
+          dummy.pay 1000
+          dummy.tax 0
+        end
+      end
+
+      it "should format values with the provided format string" do
+        value_of_node("Pay").must_equal "1000.00"
+      end
+
+      it "should not include optional nodes if they're zero" do
+        number_of_nodes("Tax").must_equal 0
+      end
+
+      it "should use xml_name as the node name if provided" do
+        subject.ni 100
+        number_of_nodes("NI").must_equal 1
+      end
+
+      it "should raise an error if given a negative number for a field that cannot be negative" do
+        ex = proc { subject.ni -100 }.must_raise InvalidInputError
+        ex.message.must_equal "ni cannot be negative"
+      end
+
+      it "should allow negative numbers for fields by default" do
+        subject.pension(-100)
+        value_of_node("Pension").must_equal "-100.00"
+      end
+
+      it "should not allow pennies for whole unit nodes" do
+        ex = proc { subject.pension BigDecimal.new("12.34") }.must_raise InvalidInputError
+        ex.message.must_equal "pension must be in whole pounds"
+      end
+    end
+  end
+end

data/spec/hermod/xml_section_builder/parent_node_spec.rb

@@ -0,0 +1,28 @@
+require "minitest_helper"
+
+module Hermod
+  ParentXml = XmlSection.build do |builder|
+    builder.parent_node :inner
+  end
+
+  InnerXml = XmlSection.build do |builder|
+    builder.string_node :inside
+  end
+
+  describe XmlSection do
+    describe "Parent XML nodes" do
+      subject do
+        ParentXml.new do |outer|
+          outer.inner(InnerXml.new do |inner|
+            inner.inside "layered like an onion"
+          end)
+        end
+      end
+
+      it "should correctly wrap the inner XML" do
+        expected = "<ParentXml>\n  <InnerXml>\n    <Inside>layered like an onion</Inside>\n  </InnerXml>\n</ParentXml>"
+        subject.to_xml.to_s.must_equal expected
+      end
+    end
+  end
+end

data/spec/hermod/xml_section_builder/string_node_spec.rb

@@ -0,0 +1,70 @@
+require "minitest_helper"
+
+module Hermod
+  describe XmlSection do
+
+    StringXml = XmlSection.build do |builder|
+      builder.string_node :greeting
+      builder.string_node :name, optional: true
+      builder.string_node :title, matches: /\ASir|Dame\z/, attributes: {masculine: "Male"}
+      builder.string_node :required
+      builder.string_node :gender, input_mutator: (lambda do |value, attributes|
+        [value == "Male" ? "M" : "F", attributes]
+      end)
+      builder.string_node :mood, allowed_values: %w(Happy Sad Hangry)
+    end
+
+    describe "String nodes" do
+      subject do
+        StringXml.new do |string_xml|
+          string_xml.greeting "Hello"
+          string_xml.name "World"
+        end
+      end
+
+      it "should set node contents correctly" do
+        value_of_node("Greeting").must_equal "Hello"
+      end
+
+      it "should allow values that pass the regex validation" do
+        subject.title "Sir"
+        value_of_node("Title").must_equal "Sir"
+      end
+
+      it "should raise an error when the regex validation fails" do
+        ex = proc { subject.title "Laird" }.must_raise InvalidInputError
+        ex.message.must_equal %{Value "Laird" for title doesn't match /\\ASir|Dame\\z/}
+      end
+
+      it "should require all non-optional nodes to have content" do
+        ex = proc { subject.required "" }.must_raise InvalidInputError
+        ex.message.must_equal "required isn't optional but no value was provided"
+      end
+
+      it "should apply changes to the inputs if a input_mutator is provided" do
+        subject.gender "Male"
+        value_of_node("Gender").must_equal "M"
+      end
+
+      it "should restrict values to those in the list of allowed values if such a list is provided" do
+        subject.mood "Hangry"
+        value_of_node("Mood").must_equal "Hangry"
+      end
+
+      it "should raise an error if the value is not in the list of allowed values" do
+        ex = proc { subject.mood "Jubilant" }.must_raise InvalidInputError
+        ex.message.must_equal %{"Jubilant" is not in the list of allowed values for mood: ["Happy", "Sad", "Hangry"]}
+      end
+
+      it "should use the given keys for attributes" do
+        subject.title "Sir", masculine: "no"
+        attributes_for_node("Title").keys.first.must_equal "Male"
+        attributes_for_node("Title")["Male"].value.must_equal "no"
+      end
+
+      it "should raise an error if given an attribute that isn't expected" do
+        proc { subject.title "Sir", knight: "yes" }.must_raise KeyError
+      end
+    end
+  end
+end

data/spec/hermod/xml_section_builder/yes_no_node_spec.rb

@@ -0,0 +1,36 @@
+require "minitest_helper"
+
+module Hermod
+  describe XmlSection do
+
+    YesNoXml = XmlSection.build do |builder|
+      builder.yes_no_node :awesome
+    end
+
+    describe "Yes/No nodes" do
+      describe "when true" do
+        subject do
+          YesNoXml.new do |yes_no_xml|
+            yes_no_xml.awesome true
+          end
+        end
+
+        it "should include the node with yes as the contents" do
+          value_of_node("Awesome").must_equal "yes"
+        end
+      end
+
+      describe "when not true" do
+        subject do
+          YesNoXml.new do |yes_no_xml|
+            yes_no_xml.awesome false
+          end
+        end
+
+        it "should include the node with no as the contents" do
+          value_of_node("Awesome").must_equal "no"
+        end
+      end
+    end
+  end
+end

data/spec/hermod/xml_section_builder/yes_node_spec.rb

@@ -0,0 +1,36 @@
+require "minitest_helper"
+
+module Hermod
+  describe XmlSection do
+
+    YesXml = XmlSection.build do |builder|
+      builder.yes_node :awesome
+    end
+
+    describe "Yes Only Nodes" do
+      describe "when true" do
+        subject do
+          YesXml.new do |yes_xml|
+            yes_xml.awesome true
+          end
+        end
+
+        it "should include the node with yes as the contents" do
+          value_of_node("Awesome").must_equal "yes"
+        end
+      end
+
+      describe "when not true" do
+        subject do
+          YesXml.new do |yes_xml|
+            yes_xml.awesome false
+          end
+        end
+
+        it "should not include the node" do
+          number_of_nodes("Awesome").must_equal 0
+        end
+      end
+    end
+  end
+end

data/spec/hermod/xml_section_spec.rb

@@ -0,0 +1,95 @@
+require "minitest_helper"
+
+module Hermod
+
+  NamedXML = XmlSection.build(xml_name: "Testing") { |builder| }
+  UnnamedXML = XmlSection.build { |builder| }
+  OrderingXML = XmlSection.build do |builder|
+    builder.string_node :first
+    builder.string_node :repeated
+    builder.string_node :last
+  end
+  FormattedXML = XmlSection.build do |builder|
+    builder.date_node :birthday
+    builder.monetary_node :allowance
+  end
+
+  describe XmlSection do
+    describe "building an XML generating class with no arguments" do
+      subject do
+        UnnamedXML.new
+      end
+
+      it "should use the class name as the XML node name" do
+        subject.to_xml.name.must_equal "UnnamedXML"
+      end
+    end
+
+    describe "building an XML generating class with a custom node name" do
+      subject do
+        NamedXML.new
+      end
+
+      it "should use the class name as the XML node name" do
+        subject.to_xml.name.must_equal "Testing"
+      end
+    end
+
+    describe "default formats" do
+      subject do
+        FormattedXML.new do |formatted|
+          formatted.birthday Date.new(1988, 8, 13)
+          formatted.allowance BigDecimal.new("20")
+        end
+      end
+
+      it "formats dates in yyyy-mm-dd form" do
+        value_of_node("Birthday").must_equal("1988-08-13")
+      end
+
+      it "formats money to two decimal places" do
+        value_of_node("Allowance").must_equal("20.00")
+      end
+    end
+
+    describe "#to_xml" do
+      subject do
+        OrderingXML.new do |ordering|
+          ordering.repeated "beta"
+          ordering.last "epsilon"
+          ordering.repeated "gamma"
+          ordering.first "alpha"
+        end
+      end
+
+      it "should order nodes by the order they were defined when the class was built" do
+        node_by_index(0).name.must_equal "First"
+        node_by_index(0).content.must_equal "alpha"
+
+        node_by_index(1).name.must_equal "Repeated"
+        node_by_index(1).content.must_equal "beta"
+
+        node_by_index(-1).name.must_equal "Last"
+        node_by_index(-1).content.must_equal "epsilon"
+      end
+
+      it "should order nodes called multiple times in the order they were called" do
+        node_by_index(1).name.must_equal "Repeated"
+        node_by_index(1).content.must_equal "beta"
+
+        node_by_index(2).name.must_equal "Repeated"
+        node_by_index(2).content.must_equal "gamma"
+      end
+
+      it "should order nodes at XML generation time, not at call time" do
+        subject.repeated "delta"
+
+        node_by_index(-2).name.must_equal "Repeated"
+        node_by_index(-2).content.must_equal "delta"
+
+        node_by_index(-1).name.must_equal "Last"
+        node_by_index(-1).content.must_equal "epsilon"
+      end
+    end
+  end
+end

data/spec/hermod_spec.rb

@@ -0,0 +1,7 @@
+require 'minitest_helper'
+
+describe Hermod do
+  it "should have a version number" do
+    Hermod::VERSION.wont_be_nil
+  end
+end