hermod | A Ruby library for talking to the HMRC Government Gateway | Application Framework library

The following types of XML node are supported:. There are some options that can be passed to all or some of the different node types. 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. 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. 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. 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). 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. 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. 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. Integer nodes let you provide a whole number that won't be formatted as a monetary value. 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. 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. Datetime nodes let you send through a date and a time to HMRC. It will be converted to the given datetime 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. 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. 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. 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. By default negative numbers are allowed. If you need to prevent them you can set the negative option to false. 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. For monetary nodes the optional option will also prevent zero values from being submitted. 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.