hermod 1.0.1

data/README.md

@@ -0,0 +1,496 @@
+# Hermod
+
+This gem makes it easier to talk to HMRC through the [Government Gateway][1] by
+providing a DSL you can use to create Ruby classes to build the XML required in
+a form that meets HMRC's specification.
+
+It ensures that nodes appear in the correct order with the correct formatting
+and allows you to preprocess values and apply validations at submission time.
+
+[1]: http://www.hmrc.gov.uk/schemas/GatewayDocumentSubmissionProtocol_V3.1.pdf "HMRC's specification"
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'hermod'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install hermod
+
+## Usage
+
+This gem allows you to describe classes that represent a section of XML that
+will be sent to HMRC. This description includes type, validation, and format
+information as well as any runtime mutations that should be applied to inputs
+you provide.
+
+### Supported Types
+
+The following types of XML node are supported:
+
+* Strings
+* Integers
+* Dates
+* Yes/No
+* Yes only
+* Monetary values
+* Parent XML
+
+#### Global Options
+
+There are some options that can be passed to all or some of the different node
+types.
+
+**XML Name**
+
+By default the name used for the XML node is generated by converting the node
+name from `snake_case` to `TitleCase`. For example, the `date_of_birth` node in
+the example above would become `DateOfBirth`. By providing an `xml_name` you
+can override this, thus changing it to `BirthDate`
+
+*Building an XmlSection*
+```ruby
+Example = Hermod::XmlSection.build do |builder|
+  builder.string_node :ni_number, xml_name: "NINumber"
+end
+```
+
+*Using that XmlSection*
+```ruby
+Example.new do |example|
+  example.ni_number "AB123456C"
+end
+```
+
+*The Resulting XML*
+```xml
+<Example>
+  <NINumber>AB123456C</NINumber>
+</Example>
+```
+
+**Attributes**
+
+Any node can have attributes which are defined by passing a `Hash` of symbol,
+string pairs. The symbol is used to refer to the attribute when setting the
+value of the node and the string is the form that will be sent to HMRC.
+
+*Building an XmlSection*
+```ruby
+Example = Hermod::XmlSection.build do |builder|
+  builder.string_node :tax_code, attributes: {week_1_month_1: "WeekOneMonthOne"}
+end
+```
+
+*Using that XmlSection*
+```ruby
+Example.new do |example|
+  example.tax_code "1000L", week_1_month_1: true
+end
+```
+
+*The Resulting XML*
+```xml
+<Example>
+  <TaxCode WeekOneMonthOne="yes">1000L</TaxCode>
+</Example>
+```
+
+**Optional**
+
+Not all nodes allow this but for those that do (String, Date and Monetary nodes)
+if a node is marked as optional then any blank values (like nil or an empty
+string) will be ignored.
+
+*Building an XmlSection*
+```ruby
+Example = Hermod::XmlSection.build do |builder|
+  builder.string_node :middle_name, optional: true
+end
+```
+
+*Using that XmlSection*
+```ruby
+Example.new do |example|
+  example.middle_name nil
+end
+```
+
+*No XML will be produced*
+
+#### String Nodes
+
+String nodes handle a wide variety of cases and can take regular expressions
+and lists of values to restrict the provided values. If they are marked as
+optional then the node will be excluded if the value given is blank
+(`nil` or the empty string).
+
+**Regular Expressions**
+
+The `matches` option allows you to provide a regular expression that is used to
+validate the input. If you try to pass a value that doesn't match the expression
+a `Hermod::InvalidInputError` will be raised.
+
+*Building an XmlSection*
+```ruby
+Example = Hermod::XmlSection.build do |builder|
+  builder.string_node :ni_number, matches: /\A[A-Z]{2}[0-9]{6}[A-D ]\z/
+end
+```
+
+*Using that XmlSection*
+```ruby
+Example.new do |example|
+  example.ni_number "I can't remember it"
+end
+```
+
+*A `Hermod::InvalidInputError` will be raised*
+
+
+**Allowable Values**
+
+The `allowable_values` lets you specify a list of string that are allowed for
+this node. Passing a value not in this list will raise
+a `Hermod::InvalidInputError`.
+
+*Building an XmlSection*
+```ruby
+Example = Hermod::XmlSection.build do |builder|
+  builder.string_node :mood, allowable_values: %w(Happy Sad Hangry)
+end
+```
+
+*Using that XmlSection*
+```ruby
+Example.new do |example|
+  example.gender "Wrathful"
+end
+```
+
+*A `Hermod::InvalidInputError` will be raised*
+
+**Input Mutator**
+
+The `input_mutator` option allows you to provide a lambda that is provided with
+two arguments, the value assigned to the node and the `Hash` of attributes (if
+any). This can be used to change either or both of these and the lambda must
+return both the value and the attributes as an array (`[value, attributes]`)
+after they've been modified.
+
+*Building an XmlSection*
+```ruby
+Example = Hermod::XmlSection.build do |builder|
+  builder.string_node :ni_number, xml_name: "NINO", optional: true, matches: /\A[A-Z]{2}[0-9]{6}[A-D ]\z/,
+    input_mutator: (lambda { |value, attrs| [value.delete(' ').upcase, attrs] })
+end
+```
+
+*Using that XmlSection*
+```ruby
+Example.new do |example|
+  example.ni_number "AB 12 34 56 C"
+end
+```
+
+*The Resulting XML*
+```xml
+<Example>
+  <NiNumber>AB123456C</NiNumber>
+</Example>
+```
+
+#### Integer Nodes
+
+Integer nodes let you provide a whole number that won't be formatted as
+a monetary value.
+
+**Range**
+
+You can specify a `range` option as a hash with a `min` and `max` value. If you
+provide a value outwith the range (inclusive) then
+a `Hermod::InvalidInputError` exception will be raised.
+
+*Building an XmlSection*
+```ruby
+Example = Hermod::XmlSection.build do |builder|
+  builder.integer_node :day_of_the_week, range: {min: 1, max: 7}
+end
+```
+
+*Using that XmlSection*
+```ruby
+Example.new do |example|
+  example.day_of_the_week 8
+end
+```
+
+*A `Hermod::InvalidInputError` will be raised*
+
+#### Date Nodes
+
+Date nodes let you send through a date to HMRC. It will be converted to the
+given date format which you can specify as a format string in the `formats`
+option passed to the `Hermod::XmlSection.build` call. Anything that responds to
+`strftime` can be passed to the node. Anything else will cause an
+`Hermod::InvalidInputError` exception to be raised.
+
+*Building an XmlSection*
+```ruby
+Example = Hermod::XmlSection.build(formats: {date: "%Y-%m-%d"}) do |builder|
+  builder.date_node :date_of_birth
+end
+```
+
+*Using that XmlSection*
+```ruby
+Example.new do |example|
+  example.date_of_birth Date.new(1988, 8, 13)
+end
+```
+
+*The Resulting XML*
+```xml
+<Example>
+  <DateOfBirth>1988-08-13</DateOfBirth>
+</Example>
+```
+
+#### Yes Nodes
+
+Yes nodes allow you to send a boolean value to HMRC provided that value is
+true. Nothing will be sent if the value is false. This pattern is commonly used
+by HMRC for optional boolean nodes. They're known as "yes nodes" because HMRC
+use "yes" and "no" in place of true and false in their XML.
+
+*Building an XmlSection*
+```ruby
+Example = Hermod::XmlSection.build do |builder|
+  builder.yes_node :verily
+  builder.yes_node :nae
+end
+```
+
+*Using that XmlSection*
+```ruby
+Example.new do |example|
+  example.verily true
+  example.nae false
+end
+```
+
+*The Resulting XML*
+```xml
+<Example>
+  <Verily>yes</Verily>
+</Example>
+```
+
+#### Yes/No Nodes
+
+This works in a similar fashion to the yes nodes described above but if a false
+value is provided a "no" will be sent instead of the node being excluded.
+
+*Building an XmlSection*
+```ruby
+Example = Hermod::XmlSection.build do |builder|
+  builder.yes_no_node :verily
+  builder.yes_no_node :nae
+end
+```
+
+*Using that XmlSection*
+```ruby
+Example.new do |example|
+  example.verily true
+  example.nae false
+end
+```
+
+*The Resulting XML*
+```xml
+<Example>
+  <Verily>yes</Verily>
+  <Nae>no</Nae>
+</Example>
+```
+
+#### Monetary Nodes
+
+Monetary nodes let you send through monetary values to HMRC. They will be
+converted to the given monetary format which you can specify as a format string
+in the `formats` option passed to the `Hermod::XmlSection.build` call. Values
+passed to monetary nodes should be BigDecimal objects.
+
+**Negative**
+
+By default negative numbers are allowed. If you need to prevent them you can
+set the `negative` option to false.
+
+*Building an XmlSection*
+```ruby
+Example = Hermod::XmlSection.build(formats: {money: "%.2f"}) do |builder|
+  builder.monetary_node :taxable_pay, negative: false
+end
+```
+
+*Using that XmlSection*
+```ruby
+Example.new do |example|
+  example.taxable_pay BigDecimal.new("-300")
+end
+```
+
+*A `Hermod::InvalidInputError` will be raised*
+
+**Whole Units**
+
+Sometimes HMRC require that you send through a value as a whole unit. If this
+is the case you can set the `whole_units` option to true and if an invalid
+value is passed a `Hermod::InvalidInputError` exception will be raised.
+
+*Building an XmlSection*
+```ruby
+Example = Hermod::XmlSection.build(formats: {money: "%.2f"}) do |builder|
+  builder.monetary_node :lower_earnings_limit, whole_units: true
+end
+```
+
+*Using that XmlSection*
+```ruby
+Example.new do |example|
+  example.lower_earnings_limit BigDecimal.new("153.49")
+end
+```
+
+*A `Hermod::InvalidInputError` will be raised*
+
+**Optional**
+
+For monetary nodes the `optional` option will also prevent zero values from
+being submitted.
+
+*Building an XmlSection*
+```ruby
+Example = Hermod::XmlSection.build(formats: {money: "%.2f"}) do |builder|
+  builder.monetary_node :taxable_pay
+  builder.monetary_node :tax, optional: true
+end
+```
+
+*Using that XmlSection*
+```ruby
+Example.new do |example|
+  example.taxable_pay BigDecimal.new("1000")
+  example.tax BigDecimal.new("0")
+end
+```
+
+*The Resulting XML*
+```xml
+<Example>
+  <TaxablePay>1000.00</TaxablePay>
+</Example>
+```
+
+#### Parent Nodes
+
+Parent nodes are the way you specify that the contents of this node is another
+`XmlSection`. The `xml_name` is ignored (whether you supply it or rely on the
+default) so the given `symbolic_name` is just the name of the method you call
+to add content. Instead the node name is picked up from the class name of the
+XmlSection you add as a child.
+
+*Building an XmlSection*
+```ruby
+Example = Hermod::XmlSection.build do |builder|
+  builder.parent_node :inner
+end
+
+Inside = Hermod::XmlSection.build do |builder|
+  builder.string_node :text"
+end
+```
+
+*Using that XmlSection*
+```ruby
+Example.new do |example|
+  example.inner(Inside.new do |inside|
+    inside.text "Hello, World"
+  end)
+end
+```
+
+*The Resulting XML*
+```xml
+<Example>
+  <Inside>
+    <Text>Hello, World</Text>
+  </Inside>
+</Example>
+```
+
+### Full Example
+
+This is all explained in more detail below but a reasonably complex XML section
+may be described as follows.
+
+```ruby
+Details = Hermod::XmlSection.build(xml_name: "EmployeeDetails", formats: Payroll::RTI::FORMATS) do |builder|
+  builder.string_node :ni_number, xml_name: "NINO", optional: true, matches: /\A[A-Z]{2}[0-9]{6}[A-D ]\z/,
+  input_mutator: (lambda do |value, attrs|
+  [value.delete(' ').upcase, attrs]
+  end)
+  builder.parent_node :name
+  builder.parent_node :address
+  builder.date_node   :date_of_birth, xml_name: "BirthDate", optional: true
+  builder.string_node :gender, allowable_values: %w(Male Female),
+  input_mutator: (lambda do |input, attrs|
+  [input == AppConstants::MALE ? Payroll::RTI::MALE : Payroll::RTI::FEMALE, attrs]
+  end)
+end
+```
+
+This creates a class that can be used like so.
+
+```ruby
+xml = Payroll::RTI::Employee::Details.new do |details|
+  details.name(Payroll::RTI::Name.new do |name|
+    name.title employee.title
+    employee.forenames.each do |forename|
+      name.forename forename
+    end
+    name.surname employee.last_name
+  end)
+  details.gender employee.gender
+
+  details.address(Address.new do |address|
+    employee.address_lines.each do |line|
+      address.line line
+    end
+    address.postcode profile.postcode
+  end)
+
+  details.ni_number employee.ni_number
+  details.date_of_birth employee.date_of_birth
+end)
+```
+
+Nodes are defined in the builder in the order they will be sent to HMRC. They
+can then be called in any order when using the class. Calling the same method
+multiple times will add multiple instances of that node and they will be output
+in the order the calls were made in.
+
+## Contributing
+
+1. Fork it ( https://github.com/fac/hermod/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request

data/Rakefile

@@ -0,0 +1,10 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "spec"
+  t.test_files = FileList["spec/**/*_spec.rb"]
+end
+
+task :default => :test
+

data/hermod.gemspec

@@ -0,0 +1,32 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'hermod/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "hermod"
+  spec.version       = Hermod::VERSION
+  spec.authors       = ["Harry Mills"]
+  spec.email         = ["harry@freeagent.com"]
+  spec.summary       = %q{A Ruby library for talking to the HMRC Government Gateway.}
+  spec.description   = %q{A Ruby library for talking to the HMRC Government Gateway.
+  This provides a builder for creating classes that can generate the XML needed complete with type information and
+  runtime validation.}
+  spec.homepage      = ""
+  spec.license       = "Apache License, Version 2.0"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.required_ruby_version = ">= 2"
+
+  spec.add_runtime_dependency "libxml-ruby", "~> 2.7", ">= 2.7.0"
+  spec.add_runtime_dependency "activesupport", "~> 4.1", ">= 4.1.4"
+
+  spec.add_development_dependency "bundler", "~> 1.6"
+  spec.add_development_dependency "rake", "~> 10.3", ">= 10.3.2"
+  spec.add_development_dependency "minitest", "~> 5.3", ">= 5.3.5"
+  spec.add_development_dependency "nokogiri", "~> 1.6", ">= 1.6.2.1"
+end

data/lib/hermod/sanitisation.rb

@@ -0,0 +1,26 @@
+module Hermod
+  module Sanitisation
+    # TODO: replace this module with something better
+    # Any replacement should make it possible for both yes only attributes and
+    # yes/no attributes to work correctly.
+
+    private
+
+    # Private: alters attributes so a true becomes "yes", a no isn't sent and
+    # anything else gets turned into a String.
+    #
+    # value - the non-sanitised value
+    #
+    # Returns the sanitised value of the attribute ready for sending to HMRC.
+    def sanitise_attribute(value)
+      case value
+      when true
+        XmlSectionBuilder::YES
+      when false
+        nil # Attributes aren't included if they're false
+      else
+        value.to_s
+      end
+    end
+  end
+end

data/lib/hermod/version.rb

@@ -0,0 +1,3 @@
+module Hermod
+  VERSION = "1.0.1"
+end

data/lib/hermod/xml_node.rb

@@ -0,0 +1,55 @@
+require 'hermod/sanitisation'
+
+module Hermod
+  # A representation of an XML node with content and attributes.
+  class XmlNode
+    include Sanitisation
+
+    attr_reader :name, :value, :attributes
+
+    # Internal: creates a XmlNode. This is used by the XmlSectionBuilder's node
+    # building methods and should not be called manually.
+    #
+    # name       - the name of the node as it appears in the XML
+    # value      - the node contents as a string.
+    # attributes - a Hash of attributes as Symbol -> value pairs. The symbol
+    #              must be in the list of attributes allowed for the node as
+    #              set in the builder.
+    def initialize(name, value, attributes={})
+      @name = name
+      @value = value
+      @attributes = attributes
+    end
+
+    # Internal: turns the XmlNode into an XML::Node including any attributes
+    # without any sanitisation (currently - this may change in a future
+    # version).
+    #
+    # Returns an XML::Node built from the XmlNode object.
+    def to_xml
+      if value.respond_to? :to_xml
+        value.to_xml
+      else
+        XML::Node.new(@name, @value).tap do |node|
+          @attributes.each do |attribute_name, attribute_value|
+            node[attribute_name] = attribute_value if attribute_value.present?
+          end
+        end
+      end
+    end
+
+    # Internal: replaces symbol attributes with strings looked up in the provided
+    # hash
+    #
+    # lookup_hash - the hash to use to convert symbols to strings HMRC recognise
+    #
+    # Returns self so it can be used in a call chain (This may change in
+    # future)
+    def rename_attributes(lookup_hash)
+      attributes.keys.each do |attribute|
+        attributes[lookup_hash.fetch(attribute)] = sanitise_attribute(attributes.delete(attribute))
+      end
+      self
+    end
+  end
+end