hexapdf-extras 1.0.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: be80955331e2df5f0ce6c549d335930bf5eed3e031deb166e6b13122bfca89d1
-  data.tar.gz: ba2c0f0affc9be014a6e87a4bbdb08bd8843af6a179fc0cd2acb548191eba47e
+  metadata.gz: 18aea5b94e331d639be753fc306bf52a24a348356c05e958063a0066e896f1e4
+  data.tar.gz: fa64c74156bfe91e7692825741f85199383a3d56987fb32db8dc30063e802d55
 SHA512:
-  metadata.gz: 60b8b6103c054737c98ef349e5cf7f5f6596eec6bbfdb23ef4dbd04623ecdbf4d1076332be273b19ff10d6931543ab30e8db806fdbfa317e1ab5619d974028c8
-  data.tar.gz: e4e5144d3b851225a971e5944d160fe6a7d4f8dd32bba2e89e0dd3dd6e30cdc52bfa95e2cd3d9a8a36b8761c506a9368817775f57bbe06130ad2d809f1f9ae8d
+  metadata.gz: 6115bc7a6a964b76466dd030b33a7d0d394c0eec5c847875960fcf945d8fe253600c36837dbb5f18a756617a4308f162bb482c8a28d884460b7b15bd63b42ba7
+  data.tar.gz: df41b43ba6afb9cb76b20c87f05658f7c5d250228d66f87a6906660156cfe1099eb331632304d7a82dfb3d3529757fcd44f4cbd34ce1988a0a17105cc8c3815d

data/Rakefile

@@ -27,7 +27,7 @@ task publish_files: [:package] do
 end
 
 task :test_all do
-  versions = `rbenv versions --bare | grep -i 2.[67]\\\\\\|3.`.split("\n")
+  versions = `rbenv versions --bare | grep -i 2.[7]\\\\\\|3.`.split("\n")
   versions.each do |version|
     sh "eval \"$(rbenv init -)\"; rbenv shell #{version} && ruby -v && rake test"
   end

data/lib/hexapdf/extras/layout/swiss_qr_bill.rb

@@ -0,0 +1,683 @@
+# frozen_string_literal: true
+
+require 'hexapdf/error'
+require 'hexapdf/layout/box'
+require 'hexapdf/extras/layout'
+
+module HexaPDF::Extras::Layout::NumericMeasurementHelper #:nodoc:
+  refine Numeric do
+    def mm
+      self * 72 / 25.4
+    end
+  end
+end
+
+using HexaPDF::Extras::Layout::NumericMeasurementHelper
+
+# These values comes from the "Style Guide QR-bill", available at
+# https://www.six-group.com/dam/download/banking-services/standardization/qr-bill/style-guide-qr-bill-en.pdf
+font = '/usr/share/fonts/truetype/liberation/LiberationSans-Regular.ttf'
+font_bold = '/usr/share/fonts/truetype/liberation/LiberationSans-Bold.ttf'
+HexaPDF::DefaultDocumentConfiguration['layout.swiss_qr_bill'] = {
+  'section.heading.font' => font_bold,
+  'section.heading.font_size' => 11,
+  'payment.heading.font' => font_bold,
+  'payment.heading.font_size' => 8,
+  'payment.heading.line_height' => 11,
+  'payment.value.font' => font,
+  'payment.value.font_size' => 10,
+  'payment.value.line_height' => 11,
+  'receipt.heading.font' => font_bold,
+  'receipt.heading.font_size' => 6,
+  'receipt.heading.line_height' => 9,
+  'receipt.value.font' => font,
+  'receipt.value.font_size' => 8,
+  'receipt.value.line_height' => 9,
+  'alternative_procedures.heading.font' => font_bold,
+  'alternative_procedures.heading.font_size' => 7,
+  'alternative_procedures.heading.line_height' => 8,
+  'alternative_procedures.value.font' => font,
+  'alternative_procedures.value.font_size' => 7,
+  'alternative_procedures.value.line_height' => 8,
+}
+
+module HexaPDF
+  module Extras
+    module Layout
+
+      # Displays a Swiss QR-bill.
+      #
+      # This class implements version 2.2 of the Swiss QR-bill specification but takes into account
+      # version 2.3 where appropriate.
+      #
+      #
+      # == Requirements
+      #
+      # * Liberation Sans TrueType font installed in standard Linux path (or changed via the
+      #   configuration option, see next section)
+      # * Rubygem +rqrcode_core+ for generating the QR code
+      #
+      #
+      # == Configuration option 'layout.swiss_qr_bill'
+      #
+      # The configuration option 'layout.swiss_qr_bill' is a hash containing styling information for
+      # the various text parts: section heading, payment heading/value, receipt heading/value and
+      # the alternative procedures. The default values are taking from the QR-bill style guide.
+      #
+      # The keys of this hash are strings of the form 'part.subpart.property' where
+      #
+      # * 'part' can be 'section', 'payment', 'receipt', or 'alternative_procedures',
+      # * 'subpart' can be 'heading' or 'value' (the latter not for 'section'),
+      # * 'property' can be 'font', 'font_size' or 'line_height' (the latter not for 'section').
+      #
+      # The default font is Liberation Sans which is one of the four allowed fonts (the others being
+      # Arial, Frutiger, and Helvetica). The font files themselves are *not* included and the 'font'
+      # property, by default, references the standard Linux path where the fonts would be found.
+      # Note that all '*.heading.font' values should reference the bold version of the font whereas
+      # the '*.value.font' values should reference the regular version.
+      #
+      #
+      # == Data Structure
+      #
+      # All the necessary information for generating the Swiss QR-bill is provided on
+      # initialization. The following keys can be used:
+      #
+      # :lang::
+      #     The language to use for the literal text strings appearing in the QR-bill. One of :en,
+      #     :de, :fr or :it.
+      #
+      #     Defaults to :en if not specified.
+      #
+      # :creditor::
+      #     (required) The creditor of the transaction. This is a hash that can contain the
+      #     following elements:
+      #
+      #     :iban::
+      #         (required) The IBAN of the creditor (21 characters, no spaces, only IBANs for CH or
+      #         LI). Note that the IBAN is not checked for validity.
+      #
+      #     :name::
+      #         (required) The name of the creditor (maximum 70 characters).
+      #
+      #     :address_type::
+      #         (required) The type of address, either :structured or :combined. Defaults to
+      #         :structured which is the only choice in version 2.3 of the specification.
+      #
+      #     :address_line1::
+      #         The first line of the creditor's address (maximum 70 characters). In case of a
+      #         structured address, this is the street. Otherwise this has to be the street and
+      #         building number together.
+      #
+      #     :address_line2::
+      #         The second line of the creditor's address. In case of a structured address, this
+      #         has to be the building number (maximum 16 characters). Otherwise it has to be the
+      #         postal code and town (maximum 70 characters).
+      #
+      #     :postal_code::
+      #         The postal code of the creditor's address (maximum 16 characters, only for
+      #         structured addresses).
+      #
+      #     :town::
+      #         The town from the creditor's address (maximum 35 characters, only for structured
+      #         addresses).
+      #
+      #     :country::
+      #         (required) The country from the creditor's address (ISO 3166-1 two-letter country
+      #         code).
+      #
+      # :debtor::
+      #     The debtor information for the transaction. This information is optional but if used
+      #     some elements are required. The value is a hash that can contain the same elements as
+      #     the +:creditor+ key with the exception of the +:iban+.
+      #
+      # :amount::
+      #     The payment amount (between 0.01 and 999,999,999.99). If not filled in, a blank field is
+      #     shown for adding the amount by hand later. If the amount is set to zero, it means that
+      #     the QR-bill should be used as notification and the :message is set according to the
+      #     specification.
+      #
+      # :currency::
+      #     (required) The payment currency (either CHF or EUR).
+      #
+      # :reference_type::
+      #     The payment reference type (either QRR, SCOR or NON). Defaults to NON.
+      #
+      # :reference::
+      #     The structured reference data. All whitespace is removed before processing.
+      #
+      #     In case of a QRR reference, the value has to be a 26 digit reference without check digit
+      #     or a 27 digit reference with check digit. The check digit is validated.
+      #
+      #     In case of a SCOR reference, the value has to contain between 5 and 25 alpha-numeric
+      #     characters. The check digits are validated.
+      #
+      # :message::
+      #     Additional, unstructured information (maximum 140 characters).
+      #
+      # :billing_information::
+      #     Billing information for automated booking of the payment (maximum 140 characters).
+      #
+      # :alternative_schemes::
+      #     Alternative schemes parameters. Either a single string with a maximum of 100 characters
+      #     or an array of two such strings.
+      #
+      # == Example
+      #
+      #   HexaPDF::Composer.create("sample-qr-bill.pdf", margin: 0) do |composer|
+      #     data = {
+      #      lang: :de,
+      #      creditor: {
+      #        iban: "CH44 3199 9123 0008 8901 2",
+      #        name: "Max Muster & Söhne",
+      #        address_line1: "Musterstrasse",
+      #        address_line2: "123",
+      #        postal_code: "8000",
+      #        town: "Seldwyla",
+      #        country: "CH",
+      #      },
+      #      debtor: {
+      #        address_type: :combined,
+      #        name: "Simon Muster",
+      #        address_line1: "Musterstrasse 1",
+      #        address_line2: "8000 Seldwyla",
+      #        country: "CH"
+      #      },
+      #      amount: 2500.25,
+      #      currency: 'CHF',
+      #     }
+      #     composer.swiss_qr_bill(data: data, valign: :bottom)
+      #   end
+      #
+      # == References
+      #
+      # * Website https://www.six-group.com/en/products-services/banking-services/billing-and-payments/qr-bill.html
+      # * 2.2 Specification https://www.six-group.com/dam/download/banking-services/standardization/qr-bill/ig-qr-bill-v2.2-en.pdf
+      # * 2.3 Specification https://www.six-group.com/dam/download/banking-services/standardization/qr-bill/ig-qr-bill-v2.3-en.pdf
+      # * Style guide https://www.six-group.com/dam/download/banking-services/standardization/qr-bill/style-guide-qr-bill-en.pdf
+      class SwissQRBill < HexaPDF::Layout::Box
+
+        # Thrown when an error occurs when working with the SwissQRBill class.
+        class Error < HexaPDF::Error
+        end
+
+        # Mapping of the English text literals to their German, French and Italian counterparts,
+        # taken from Annex C of the specification.
+        TEXT_LITERALS = { #:nodoc:
+          de: {
+            'Payment part' => 'Zahlteil',
+            'Receipt' => 'Empfangsschein',
+            'Account / Payable to' => 'Konto / Zahlbar an',
+            'Reference' => 'Referenz',
+            'Additional information' => 'Zusätzliche Informationen',
+            'Payable by' => 'Zahlbar durch',
+            'Payable by (name/address)' => 'Zahlbar durch (Name/Adresse)',
+            'Currency' => 'Währung',
+            'Amount' => 'Betrag',
+            'Acceptance point' => 'Annahmestelle',
+            'In favour of' => 'Zugunsten',
+            'DO NOT USE FOR PAYMENT' => 'NICHT ZUR ZAHLUNG VERWENDEN',
+          },
+          fr: {
+            'Payment part' => 'Section paiement',
+            'Receipt' => 'Récépissé',
+            'Account / Payable to' => 'Compte / Payable à',
+            'Reference' => 'Référence',
+            'Additional information' => 'Information supplémentaires',
+            'Payable by' => 'Payable par',
+            'Payable by (name/address)' => 'Payable par (nom/address)',
+            'Currency' => 'Monnaie',
+            'Amount' => 'Montant',
+            'Acceptance point' => 'Point de dépôt',
+            'In favour of' => 'En faveur de',
+            'DO NOT USE FOR PAYMENT' => 'NE PAS UTILISER POUR LE PAIEMENT',
+          },
+          it: {
+            'Payment part' => 'Sezione pagamento',
+            'Receipt' => 'Ricevuta',
+            'Account / Payable to' => 'Conto / Pagabile a',
+            'Reference' => 'Riferimento',
+            'Additional information' => 'Informazioni supplementari',
+            'Payable by' => 'Pagabile da',
+            'Payable by (name/address)' => 'Pagabile da (nome/indirizzo)',
+            'Currency' => 'Value date ',
+            'Amount' => 'Importo',
+            'Acceptance point' => 'Punto di accettazione',
+            'In favour of' => 'A favore di',
+            'DO NOT USE FOR PAYMENT' => 'NON UTILIZZARE PER IL PAGAMENTO',
+          }
+        }
+
+        # The payment data - see the SwissQRBill class documentation for details.
+        attr_reader :data
+
+        # Creates a new SwissQRBill object for the given payment +data+ (see the class documentation
+        # for details).
+        #
+        # If the arguments +width+ and +height+ are provided, they are ignored since the QR-bill has
+        # a fixed size of 210mm x 105mm.
+        def initialize(data:, **kwargs)
+          super(**kwargs, width: 210.mm, height: 105.mm)
+          validate_data(data)
+        end
+
+        private
+
+        QRR_MODULO10_TABLE = [ #:nodoc:
+          [0, 9, 4, 6, 8, 2, 7, 1, 3, 5],
+          [9, 4, 6, 8, 2, 7, 1, 3, 5, 0],
+          [4, 6, 8, 2, 7, 1, 3, 5, 0, 9],
+          [6, 8, 2, 7, 1, 3, 5, 0, 9, 4],
+          [8, 2, 7, 1, 3, 5, 0, 9, 4, 6],
+          [2, 7, 1, 3, 5, 0, 9, 4, 6, 8],
+          [7, 1, 3, 5, 0, 9, 4, 6, 8, 2],
+          [1, 3, 5, 0, 9, 4, 6, 8, 2, 7],
+          [3, 5, 0, 9, 4, 6, 8, 2, 7, 1],
+          [5, 0, 9, 4, 6, 8, 2, 7, 1, 3]
+        ].freeze
+
+        # Validates the given data and raises an error if the data is not valid
+        def validate_data(data)
+          @data = data
+
+          if @data[:currency] != 'EUR' && @data[:currency] != 'CHF'
+            raise Error, "Data field :currency must be EUR or CHR, not #{@data[:currency].inspect}"
+          end
+
+          if @data[:amount] == 0
+            @data[:message] = text('DO NOT USE FOR PAYMENT')
+          elsif @data[:amount] && (@data[:amount] < 0.01 || @data[:amount] > 999_999_999.99)
+            raise Error, "Data field :amount must be between 0.01 and 999_999_999.99"
+          end
+
+          validate_address = lambda do |hash|
+            hash[:address_type] ||= :structured
+            if hash[:address_type] != :structured && hash[:address_type] != :combined
+              raise Error, "Address type must be :structured or :combined, not #{hash[:address_type]}"
+            end
+            structured = (hash[:address_type] == :structured)
+
+            if (value = hash[:name]) && value.size > 70
+              raise Error, "Name in addresss must not contain more than 70 characters"
+            elsif !value
+              raise Error, "Name in address must be provided"
+            end
+
+            if hash[:address_line1] && hash[:address_line1].size > 70
+              raise Error, "Address line 1 must not contain more than 70 characters"
+            end
+
+            if (value = hash[:address_line2])
+              if structured && value.size > 16
+                raise Error, "Address line 2 of a structured address must not contain " \
+                  "more than 16 characters"
+              elsif value.size > 70
+                raise Error, "Address line 2 of a combined address must not contain " \
+                  "more than 70 characters"
+              end
+            elsif !structured
+              raise Error, "Address line 2 must be provided for a combined address"
+            end
+
+            if (value = hash[:postal_code])
+              if !structured
+                raise Error, "Postal code must not be provided for a combined address"
+              elsif value.size > 16
+                raise Error, "Postal code must not contain more than 16 characters"
+              end
+            elsif structured
+              raise Error, "Postal code must be provided for a structured address"
+            end
+
+            if (value = hash[:town])
+              if !structured
+                raise Error, "Town must not be provided for a combined address"
+              elsif value.size > 35
+                raise Error, "Town must not contain more than 35 characters"
+              end
+            elsif structured
+              raise Error, "Town must be provided for a structured address"
+            end
+
+            if (value = hash[:country]) && value.size != 2
+              raise Error, "Country must be a two-letter ISO-3166-1 code"
+            elsif !value
+              raise Error, "Country must be provided"
+            end
+          end
+          validate_address.call(@data[:creditor])
+          validate_address.call(@data[:debtor]) if @data[:debtor]
+
+          @data[:reference_type] ||= "NON"
+          case @data[:reference_type]
+          when "QRR"
+            value = @data[:reference]
+            unless value
+              raise Error, "Data field :reference must be filled in for QRR reference type"
+            end
+            value.gsub!(/\s*/, '')
+            if value !~ /\A\d{26,27}\z/
+              raise Error, "Data field :reference for QRR must contain 26 or 27 digits"
+            end
+            result = value[0, 26].each_codepoint.inject(0) do |memo, codepoint|
+              QRR_MODULO10_TABLE[memo][codepoint - 48]
+            end
+            check_digit = (10 - result) % 10
+            value << check_digit.to_s if value.size == 26
+            if value[26].to_i != check_digit
+              raise Error, "Data field :reference for QRR contains an invalid check digit, " \
+                "should be #{check_digit}"
+            end
+          when "SCOR"
+            value = @data[:reference]
+            unless value
+              raise Error, "Data field :reference must be filled in for SCOR reference type"
+            end
+            value.gsub!(/\s*/, '')
+            if value !~ /\A\w{5,25}\z/
+              raise Error, "Data field :reference for SCOR must contain between 5 and 25 " \
+                "alpha-numeric characters"
+            elsif value !~ /\ARF\d\d/
+              raise Error, "Data field :reference for SCOR must start with RF and check digits"
+            end
+            # See https://www.mobilefish.com/services/creditor_reference/creditor_reference.php
+            result = "#{value[4..-1]}#{value[0, 4]}".upcase.gsub(/[A-Z]/) {|c| c.ord - 55 }.to_i % 97
+            unless result == 1
+              raise Error, "Data field :reference for SCOR has invalid check digits"
+            end
+          when "NON"
+            if @data[:reference]
+              raise Error, "Data field :reference must not be provided for NON reference type"
+            end
+          else
+            raise Error, "Data field :reference_type must be one of QRR, SCOR or NON"
+          end
+
+          if @data[:message] && @data[:message].size > 140
+            raise Error, "Data field :message must not contain more than 140 characters"
+          end
+          if @data[:billing_information] && @data[:billing_information].size > 140
+            raise Error, "Data field :billing_information must not contain more than 140 characters"
+          end
+          if (@data[:message].to_s + @data[:billing_information].to_s).size > 140
+            raise Error, "Data fields :message and :billing_information together must not " \
+              "contain more than 140 characters"
+          end
+
+          @data[:alternative_schemes] = Array(@data[:alternative_schemes])
+          if @data[:alternative_schemes].any? {|as| as.size > 100 } ||
+              @data[:alternative_schemes].size > 2
+            raise Error, "Data field :alternative_schemes must at most contain 2 strings with " \
+              "not more than 100 characters each"
+          end
+        end
+
+        # Draws the SwissQRBill onto the canvas at position [x, y].
+        def draw_content(canvas, x, y)
+          layout = canvas.context.document.layout
+          frame = HexaPDF::Layout::Frame.new(0, 0, width, height, context: canvas.context)
+          box_fitter = HexaPDF::Layout::BoxFitter.new([frame])
+          styles = set_up_styles(canvas.context.document.config['layout.swiss_qr_bill'], layout)
+
+          box_fitter.fit(receipt(layout, styles))
+          box_fitter.fit(payment(layout, styles, qr_code_cross(canvas.context.document)))
+          unless box_fitter.fit_successful?
+            raise HexaPDF::Error, "The Swiss QR-bill could not be fit"
+          end
+
+          canvas.translate(x, y) do
+            box_fitter.fit_results.each {|fit_result| fit_result.draw(canvas)}
+            canvas.stroke_color(0).line_width(0.5).line_dash_pattern(2).
+              line(62.mm, 0, 62.mm, 105.mm).
+              line(0, 105.mm, 210.mm, 105.mm).stroke
+            canvas.font('ZapfDingbats', size: 15).text("✂", at: [5.mm, 103.1.mm])
+            canvas.font('ZapfDingbats', size: 15).text_matrix(0, -1, 1, 0, 60.175.mm, 100.mm).text("✂")
+          end
+        end
+
+        # Returns a hash with styles that are used throughout the QR-bill creation for consistency.
+        def set_up_styles(config, layout)
+          {
+            section_heading: {font_size: config['section.heading.font_size'],
+                              font: config['section.heading.font']},
+            payment_heading: {font_size: config['payment.heading.font_size'],
+                              font: config['payment.heading.font'],
+                              line_height: config['payment.heading.line_height'],
+                              line_spacing: {type: :fixed, value: config['payment.heading.line_height']}},
+            payment_value: {font_size: config['payment.value.font_size'],
+                            font: config['payment.value.font'],
+                            line_height: config['payment.value.line_height'],
+                            line_spacing: {type: :fixed, value: config['payment.value.line_height']},
+                            padding: [0, 0, config['payment.value.line_height']]},
+            receipt_heading: {font_size: config['receipt.heading.font_size'],
+                              font: config['receipt.heading.font'],
+                              line_height: config['receipt.heading.line_height'],
+                              line_spacing: {type: :fixed, value: config['receipt.heading.line_height']}},
+            receipt_value: {font_size: config['receipt.value.font_size'],
+                            font: config['receipt.value.font'],
+                            line_height: config['receipt.value.line_height'],
+                            line_spacing: {type: :fixed, value: config['receipt.value.line_height']},
+                            padding: [0, 0, config['receipt.value.line_height']]},
+            alternative_procedures_heading: {
+              font_size: config['alternative_procedures.heading.font_size'],
+              font: config['alternative_procedures.heading.font'],
+              line_height: config['alternative_procedures.heading.line_height'],
+              line_spacing: {type: :fixed, value: config['alternative_procedures.heading.line_height']}
+            },
+            alternative_procedures_value: {
+              font_size: config['alternative_procedures.value.font_size'],
+              font: config['alternative_procedures.value.font'],
+              line_height: config['alternative_procedures.value.line_height'],
+              line_spacing: {type: :fixed, value: config['alternative_procedures.value.line_height']},
+              padding: [0, 0, config['alternative_procedures.value.line_height']]
+            },
+          }.transform_values! {|value| layout.style(:base).dup.update(**value) }
+        end
+
+        # Returns a box containing the receipt part of the QR-bill.
+        def receipt(layout, styles)
+          layout.container(width: 62.mm, style: {padding: 5.mm, mask_mode: :fill_vertical}) do |col|
+            col.text(text('Receipt'), height: 7.mm, style: styles[:section_heading])
+            col.container(height: 56.mm) do |info|
+              info.text(text('Account / Payable to'), style: styles[:receipt_heading])
+              info.text("#{@data[:creditor][:iban]}\n#{address(@data[:creditor])}", style: styles[:receipt_value])
+
+              if @data[:reference_type] != 'NON'
+                info.text(text('Reference'), style: styles[:receipt_heading])
+                info.text(@data[:reference], style: styles[:receipt_value])
+              end
+
+              if @data[:debtor]
+                info.text(text('Payable by'), style: styles[:receipt_heading])
+                info.text(address(@data[:debtor]), style: styles[:receipt_value])
+              else
+                info.text(text('Payable by (name/address)'), style: styles[:receipt_heading])
+                blank_field(info, 52.mm, 20.mm)
+              end
+            end
+            receipt_amount(col, styles)
+            col.text(text('Acceptance point'), style: styles[:receipt_heading], text_align: :right)
+          end
+        end
+
+        # Adds the appropriate boxes to the given composer for the amount part of the receipt
+        # section.
+        def receipt_amount(composer, styles)
+          composer.container(height: 14.mm) do |amount|
+            if @data[:amount]
+              amount.column(columns: [26.mm, -1], gaps: 0) do |inner|
+                inner.text(text('Currency'), style: styles[:receipt_heading], padding: [0, 0, 1.mm])
+                inner.text(@data[:currency], style: styles[:receipt_value])
+                inner.text(text('Amount'), style: styles[:receipt_heading], padding: [0, 0, 1.mm])
+                inner.text(formatted_amount, style: styles[:receipt_value])
+              end
+            else
+              amount.column(columns: [-1, 31.mm], gaps: 0) do |inner|
+                inner.text(text('Currency') + "   " + text("Amount"),
+                           style: styles[:receipt_heading], padding: [0, 0, 1.mm])
+                inner.text(@data[:currency], style: styles[:receipt_value], mask_mode: :fill)
+                inner.box(:base, height: 2)
+                blank_field(inner, 30.mm, 10.mm)
+              end
+            end
+          end
+        end
+
+        # Returns a box containing the payment part of the QR-bill.
+        def payment(layout, styles, cross)
+          layout.container(width: 148.mm, style: {padding: 5.mm}) do |col|
+            col.container(width: 51.mm, height: 85.mm, style: {mask_mode: :box}) do |left_col|
+              left_col.text(text('Payment part'), height: 7.mm, style: styles[:section_heading])
+              left_col.box(:qrcode, data: qr_code_data, level: :m, style: {padding: [5.mm, 5.mm, 5.mm, 0.mm]})
+              left_col.image(cross, width: 7.mm, position: [19.5.mm, 46.5.mm])
+              payment_amount(left_col, styles)
+            end
+            col.container(height: 85.mm) do |info|
+              info.text(text('Account / Payable to'), style: styles[:payment_heading])
+              info.text("#{@data[:creditor][:iban]}\n#{address(@data[:creditor])}", style: styles[:payment_value])
+
+              if @data[:reference_type] != 'NON'
+                info.text(text('Reference'), style: styles[:payment_heading])
+                info.text(@data[:reference], style: styles[:payment_value])
+              end
+
+              if @data[:message] || @data[:billing_information]
+                info.text(text('Additional information'), style: styles[:payment_heading])
+                info.text([@data[:message], @data[:billing_information]].compact.join("\n"), style: styles[:payment_value])
+              end
+
+              if @data[:debtor]
+                info.text(text('Payable by'), style: styles[:payment_heading])
+                info.text(address(@data[:debtor]), style: styles[:payment_value])
+              else
+                info.text(text('Payable by (name/address)'), style: styles[:payment_heading])
+                blank_field(info, 65.mm, 25.mm)
+              end
+            end
+            if @data[:alternative_schemes].size > 0
+              @data[:alternative_schemes].each do |as|
+                provider, data = *as.split('/', 2)
+                col.formatted_text([{text: provider, style: styles[:alternative_procedures_heading]},
+                                    {text: data, style: styles[:alternative_procedures_value]}])
+              end
+            end
+          end
+        end
+
+        # Adds the appropriate boxes to the given composer for the amount part of the payment
+        # section.
+        def payment_amount(composer, styles)
+          composer.container(height: 22.mm) do |amount|
+            if @data[:amount]
+              amount.column(columns: [23.mm, -1], gaps: 0) do |inner|
+                inner.text(text('Currency'), style: styles[:payment_heading], padding: [0, 0, 1.mm])
+                inner.text(@data[:currency], style: styles[:payment_value])
+                inner.text(text('Amount'), style: styles[:payment_heading], padding: [0, 0, 1.mm])
+                inner.text(formatted_amount, style: styles[:payment_value])
+              end
+            else
+              amount.text(text('Currency') + "    " + text("Amount"),
+                          style: styles[:payment_heading], padding: [0, 0, 1.mm])
+              amount.column(columns: [-1, 41.mm], gaps: 0) do |inner|
+                inner.text(@data[:currency], style: styles[:payment_value])
+                blank_field(inner, 40.mm, 15.mm)
+              end
+            end
+          end
+        end
+
+        # Returns the correctly localized text for the given string +str+.
+        def text(str)
+          TEXT_LITERALS.dig(@data[:lang], str) || str
+        end
+
+        # Returns a string containing the formatted address for output using the provided data.
+        def address(data)
+          result = +''
+          result << "#{data[:name]}\n"
+          if data[:address_type] == :structured
+            addr = [data[:address_line1], data[:address_line2]].compact
+            result << "#{addr.join(' ')}\n" unless addr.empty?
+            result << "#{data[:country]}-#{data[:postal_code]} #{data[:town]}"
+          else
+            result << "#{data[:address_line1]}\n" if data.key?(:address_line1)
+            result << "#{data[:country]}-#{data[:address_line2]}\n"
+          end
+          result
+        end
+
+        # Returns the amount formatted according to the specification.
+        def formatted_amount
+          a, b = format('%.2f', @data[:amount]).split('.')
+          a.gsub!(/(\d)(?=(\d\d\d)+(?!\d))/, "\\1 ") << '.' << b
+        end
+
+        # Creates the content of the QR code using the information provided in #data.
+        def qr_code_data
+          qr_code_data = []
+          add_address_data = lambda do |hash|
+            qr_code_data << (hash[:address_type] == :structured ? "S" : "K")
+            qr_code_data << hash[:name] <<
+              hash[:address_line1].to_s << hash[:address_line2].to_s <<
+              hash[:postal_code].to_s << hash[:town].to_s << hash[:country]
+          end
+
+          # Header information
+          qr_code_data.concat(["SPC", "0200", "1"])
+
+          # Creditor information
+          qr_code_data << @data[:creditor][:iban]
+          add_address_data.call(@data[:creditor])
+
+          # Ultimate creditor information
+          qr_code_data.concat(["", "", "", "", "", "", ""])
+
+          # Amount information
+          qr_code_data << (@data[:amount] ? format('%.2f', @data[:amount]) : "") << @data[:currency]
+
+          # Debtor information
+          add_address_data.call(@data[:debtor]) if @data[:debtor]
+
+          # Payment reference
+          qr_code_data << @data[:reference_type] << @data[:reference].to_s <<
+            @data[:message].to_s << "EPD"
+          qr_code_data << @data[:billing_information] if @data[:billing_information]
+
+          qr_code_data.join("\r\n")
+        end
+
+        # Creates a Form XObject for the Swiss cross that is to be overlaid over the QR code.
+        #
+        # The measurements are reverse-engineered from the images provided at
+        # https://www.six-group.com/dam/download/banking-services/standardization/qr-bill/swiss-cross-graphic-en.zip
+        def qr_code_cross(document)
+          cross = document.add({Type: :XObject, Subtype: :Form, BBox: [0, 0, 7.mm, 7.mm]})
+          canvas = cross.canvas
+          canvas.fill_color(1.0).rectangle(0, 0, 7.mm, 7.mm).fill
+          canvas.fill_color(0.0).rectangle(0.5.mm, 0.5.mm, 6.mm, 6.mm).fill
+          canvas.fill_color(1.0).
+            rectangle(2.93.mm, 1.67.mm, 1.17.mm, 3.9.mm).
+            rectangle(1.57.mm, 3.04.mm, 3.9.mm, 1.17.mm).
+            fill
+          cross
+        end
+
+        CORNER_MARK_LENGTH = 3.mm # :nodoc:
+
+        # Creates a blank rectangle of the given +width+ and +height+, with corner marks as
+        # specified by the specification.
+        def blank_field(layout, width, height)
+          layout.box(width: width, height: height) do |canvas, box|
+            canvas.stroke_color(0).line_width(0.75).
+              polyline(0, CORNER_MARK_LENGTH, 0, 0, CORNER_MARK_LENGTH, 0).
+              polyline(width - CORNER_MARK_LENGTH, 0, width, 0, width, CORNER_MARK_LENGTH).
+              polyline(width, height - CORNER_MARK_LENGTH, width, height, width - CORNER_MARK_LENGTH, height).
+              polyline(CORNER_MARK_LENGTH, height, 0, height, 0, height - CORNER_MARK_LENGTH).
+              stroke
+          end
+        end
+
+      end
+
+    end
+  end
+end

data/lib/hexapdf/extras/layout.rb

@@ -4,6 +4,7 @@ module HexaPDF
   module Extras
     module Layout
       autoload(:QRCodeBox, 'hexapdf/extras/layout/qr_code_box')
+      autoload(:SwissQRBill, 'hexapdf/extras/layout/swiss_qr_bill')
     end
   end
 end

data/lib/hexapdf/extras/version.rb

@@ -2,6 +2,6 @@
 
 module HexaPDF
   module Extras
-    VERSION = '1.0.1'
+    VERSION = '1.1.0'
   end
 end

data/lib/hexapdf/extras.rb

@@ -14,3 +14,6 @@ HexaPDF::DefaultDocumentConfiguration['graphic_object.map'][:qrcode] =
 
 HexaPDF::DefaultDocumentConfiguration['layout.boxes.map'][:qrcode] =
   'HexaPDF::Extras::Layout::QRCodeBox'
+
+HexaPDF::DefaultDocumentConfiguration['layout.boxes.map'][:swiss_qr_bill] =
+  'HexaPDF::Extras::Layout::SwissQRBill'

data/test/hexapdf/extras/layout/test_qr_code_box.rb

@@ -7,6 +7,10 @@ describe HexaPDF::Extras::Layout::QRCodeBox do
     HexaPDF::Extras::Layout::QRCodeBox.new(**kwargs)
   end
 
+  before do
+    @frame = HexaPDF::Layout::Frame.new(0, 0, 100, 100)
+  end
+
   describe "initialize" do
     it "can take the common box arguments" do
       box = create_box(width: 10, height: 15)
@@ -25,7 +29,7 @@ describe HexaPDF::Extras::Layout::QRCodeBox do
     it "uses the smaller value of width/height for the dimensions if smaller than available_width/height" do
       [{width: 10}, {width: 10, height: 50}, {height: 10}, {width: 50, height: 10}].each do |args|
         box = create_box(**args)
-        assert(box.fit(100, 100, nil))
+        assert(box.fit(100, 100, @frame))
         assert_equal(10, box.width)
         assert_equal(10, box.height)
         assert_equal(10, box.qr_code.size)
@@ -34,12 +38,12 @@ describe HexaPDF::Extras::Layout::QRCodeBox do
 
     it "uses the smaller value of available_width/height for the dimensions" do
       box = create_box
-      assert(box.fit(10, 20, nil))
+      assert(box.fit(10, 20, @frame))
       assert_equal(10, box.width)
       assert_equal(10, box.height)
       assert_equal(10, box.qr_code.size)
 
-      assert(box.fit(20, 15, nil))
+      assert(box.fit(20, 15, @frame))
       assert_equal(15, box.width)
       assert_equal(15, box.height)
       assert_equal(15, box.qr_code.size)
@@ -47,19 +51,19 @@ describe HexaPDF::Extras::Layout::QRCodeBox do
 
     it "takes the border and padding into account for the QR code size" do
       box = create_box(style: {padding: [1, 2], border: {width: [3, 4]}})
-      assert(box.fit(100, 100, nil))
+      assert(box.fit(100, 100, @frame))
       assert_equal(88, box.qr_code.size)
       assert_equal(100, box.width)
       assert_equal(96, box.height)
 
       box = create_box(style: {padding: [2, 1], border: {width: [4, 3]}})
-      assert(box.fit(100, 100, nil))
+      assert(box.fit(100, 100, @frame))
       assert_equal(88, box.qr_code.size)
       assert_equal(96, box.width)
       assert_equal(100, box.height)
 
       box = create_box(style: {padding: [5, 5, 5, 0], border: {width: [2, 2, 2, 0]}})
-      assert(box.fit(50, 100, nil))
+      assert(box.fit(50, 100, @frame))
       assert_equal(43, box.qr_code.size)
       assert_equal(50, box.width)
       assert_equal(57, box.height)
@@ -69,7 +73,7 @@ describe HexaPDF::Extras::Layout::QRCodeBox do
   describe "draw" do
     it "draws the qrcode" do
       box = create_box(width: 10)
-      box.fit(100, 100, nil)
+      box.fit(100, 100, @frame)
 
       canvas = Minitest::Mock.new
       canvas.expect(:draw, nil, [box.qr_code])

data/test/hexapdf/extras/layout/test_swiss_qr_bill.rb

@@ -0,0 +1,233 @@
+require 'test_helper'
+require 'hexapdf'
+require 'hexapdf/extras'
+require 'hexapdf/extras/layout/swiss_qr_bill'
+
+using HexaPDF::Extras::Layout::NumericMeasurementHelper
+
+describe HexaPDF::Extras::Layout::SwissQRBill do
+  def create_box(data, **kwargs)
+    HexaPDF::Extras::Layout::SwissQRBill.new(data: data, **kwargs)
+  end
+
+  def data
+    @data ||= {
+     creditor: {
+       iban: "CH44 3199 9123 0008 8901 2",
+       name: "Max Muster & Söhne",
+       address_line1: "Musterstrasse",
+       address_line2: "123",
+       postal_code: "8000",
+       town: "Seldwyla",
+       country: "CH",
+     },
+     debtor: {
+       address_type: :combined,
+       name: "Simon Muster",
+       address_line1: "Musterstrasse 1",
+       address_line2: "8000 Seldwyla",
+       country: "CH"
+     },
+     lang: :de,
+     amount: 2500.25,
+     currency: 'CHF',
+    }
+  end
+
+  before do
+    @error_class = HexaPDF::Extras::Layout::SwissQRBill::Error
+  end
+
+  describe "initialize" do
+    it "overrides any set width or height" do
+      box = create_box(data, width: 10, height: 15)
+      assert_equal(210.mm, box.width)
+      assert_equal(105.mm, box.height)
+    end
+
+    describe "data validation" do
+      def assert_invalid_data(data = self.data, message)
+        err = assert_raises(@error_class) { create_box(data) }
+        assert_match(message, err.message)
+      end
+
+      it "ensures a correct currency value" do
+        assert_equal('EUR', create_box(data.update(currency: 'EUR')).data[:currency])
+        assert_equal('CHF', create_box(data.update(currency: 'CHF')).data[:currency])
+        assert_invalid_data(data.update(currency: 'USD'), /field :currency/)
+      end
+
+      it "ensure a correct amount value" do
+        assert_invalid_data(data.update(amount: 0.001), /field :amount/)
+        assert_invalid_data(data.update(amount: 1_000_000_000), /field :amount/)
+        data.update(amount: 0.00)
+        assert_equal('NICHT ZUR ZAHLUNG VERWENDEN', create_box(data).data[:message])
+      end
+
+      it "sets the address type to structured by default" do
+        assert_equal(:structured, create_box(data, width: 10, height: 15).data[:creditor][:address_type])
+      end
+
+      it "ensures a correct address type" do
+        data[:creditor].update(address_type: :invalid)
+        assert_invalid_data(/Address type must be/)
+      end
+
+      it "ensures a name for an address exists and has a valid length" do
+        data[:creditor][:name] = 'a' * 71
+        assert_invalid_data(/Name in address.*70/)
+        data[:creditor].delete(:name)
+        assert_invalid_data(/Name in address must be provided/)
+      end
+
+      it "ensures that address line 1 has a valid length" do
+        data[:creditor][:address_line1] = 'a' * 71
+        assert_invalid_data(/Address line 1.*70/)
+      end
+
+      it "ensures a correct country code" do
+        data[:creditor][:country] = 'AMS'
+        assert_invalid_data(/Country must.*ISO-3166-1/)
+        data[:creditor].delete(:country)
+        assert_invalid_data(/Country must be provided/)
+      end
+
+      describe "ensures a correct structured address" do
+        it "ensures that address line 2 has a valid length" do
+          data[:creditor][:address_line2] = 'a' * 17
+          assert_invalid_data(/Address line 2.*structured.*16/)
+        end
+
+        it "ensures that the postal code exists and has a valid length" do
+          data[:creditor][:postal_code] = 'a' * 17
+          assert_invalid_data(/Postal code.*16/)
+          data[:creditor].delete(:postal_code)
+          assert_invalid_data(/Postal code must be provided.*structured/)
+        end
+
+        it "ensures that the town exists and has a valid length" do
+          data[:creditor][:town] = 'a' * 36
+          assert_invalid_data(/Town.*35/)
+          data[:creditor].delete(:town)
+          assert_invalid_data(/Town must be provided.*structured/)
+        end
+      end
+
+      describe "ensures a correct combined address" do
+        it "ensures that address line 2 exists and has a valid length" do
+          data[:debtor][:address_line2] = 'a' * 71
+          assert_invalid_data(/Address line 2.*combined.*70/)
+          data[:debtor].delete(:address_line2)
+          assert_invalid_data(/Address line 2 must be provided.*combined/)
+        end
+
+        it "ensures that the postal code does not exist" do
+          data[:debtor][:postal_code] = 'a'
+          assert_invalid_data(/Postal code must not be provided.*combined/)
+        end
+
+        it "ensures that the town exists and has a valid length" do
+          data[:debtor][:town] = 'a'
+          assert_invalid_data(/Town must not be provided.*combined/)
+        end
+      end
+
+      describe "reference" do
+        it "ensures the QRR reference value exists and is valid" do
+          data[:reference_type] = 'QRR'
+          assert_invalid_data(/:reference must be filled.*QRR/)
+          data[:reference] = 'adsfads'
+          assert_invalid_data(/:reference for QRR.*27/)
+          data[:reference] = '210000000003139471430009011'
+          assert_invalid_data(/:reference for QRR.*invalid check digit.*7/)
+          data[:reference] = '21000000000313947143000901'
+          assert_equal('7', create_box(data).data[:reference][26])
+          data[:reference] = '210000000 0031394 71430009017'
+          assert(create_box(data))
+        end
+
+        it "ensures the SCOR reference value exists and is valid" do
+          data[:reference_type] = 'SCOR'
+          assert_invalid_data(/:reference must be filled.*SCOR/)
+          data[:reference] = 'RF11'
+          assert_invalid_data(/:reference for SCOR.*5 and 25/)
+          data[:reference] = 'RFa' * 9
+          assert_invalid_data(/:reference for SCOR.*5 and 25/)
+          data[:reference] = 'RF123323;ö'
+          assert_invalid_data(/:reference for SCOR.*alpha-numeric/)
+          data[:reference] = 'a' * 20
+          assert_invalid_data(/:reference for SCOR must start.*RF/)
+          data[:reference] = 'RFabcdefgh'
+          assert_invalid_data(/:reference for SCOR must start.*RF and check digits/)
+          data[:reference] = 'RF 48 5000056789012345d'
+          assert_invalid_data(/:reference for SCOR has invalid check digits/)
+          data[:reference] = 'RF 48 5000056789012345'
+          assert(create_box(data))
+        end
+
+        it "ensures that no reference value is specified for a NON type" do
+          data[:reference_type] = 'NON'
+          data[:reference] = 'something'
+          assert_invalid_data(/:reference must not be provided.*NON/)
+        end
+
+        it "ensures a valid reference_type value" do
+          data[:reference_type] = 'OTHER'
+          assert_invalid_data(/:reference_type must be one of/)
+        end
+      end
+
+      it "ensures a correct message value" do
+        data[:message] = 'a' * 141
+        assert_invalid_data(/:message must not contain.*140/)
+      end
+
+      it "ensures a correct billing information value" do
+        data[:billing_information] = 'a' * 141
+        assert_invalid_data(/:billing_information must not contain.*140/)
+      end
+
+      it "ensures a total combined length of message + billing_information of max 140 characters" do
+        data[:message] = 'a' * 80
+        data[:billing_information] = 'a' * 80
+        assert_invalid_data(/:message and :billing_information together.*140/)
+      end
+
+      it "ensures a correct alternative schemes value" do
+        data[:alternative_schemes] = 'a' * 101
+        assert_invalid_data(/alternative_schemes.*not more than 100/)
+        data[:alternative_schemes] = ['a', 'b', 'c']
+        assert_invalid_data(/alternative_schemes.*at most contain 2 strings/)
+      end
+    end
+  end
+
+  describe "draw" do
+    before do
+      @doc = HexaPDF::Document.new
+      @composer = @doc.pages.add.canvas.composer(margin: 0)
+    end
+
+    it "works with all information filled in" do
+      data[:reference_type] = 'QRR'
+      data[:reference] = '210000000 0031394 71430009017'
+      data[:message] = 'Please just pay the bills, Jim!'
+      data[:billing_information] = '//S/hit/30/50/what/do/I/do/'
+      data[:alternative_schemes] = 'ebill/here/comes/data'
+      assert(@composer.box(:swiss_qr_bill, data: data))
+    end
+
+    it "works with no amount and no debtor" do
+      data.delete(:debtor)
+      data.delete(:amount)
+      assert(@composer.box(:swiss_qr_bill, data: data))
+    end
+
+    it "fails if the content is too big for the box" do
+      box = create_box(data)
+      box.data[:message] = 'x' * 1400
+      err = assert_raises(HexaPDF::Error) { @composer.draw_box(box) }
+      assert_match(/Swiss QR-bill could not be fit/, err.message)
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: hexapdf-extras
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.1.0
 platform: ruby
 authors:
 - Thomas Leitner
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-12-16 00:00:00.000000000 Z
+date: 2024-01-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: hexapdf
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.24'
+        version: '0.36'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.24'
+        version: '0.36'
 - !ruby/object:Gem::Dependency
   name: rqrcode_core
   requirement: !ruby/object:Gem::Requirement
@@ -53,9 +53,11 @@ files:
 - lib/hexapdf/extras/graphic_object/qr_code.rb
 - lib/hexapdf/extras/layout.rb
 - lib/hexapdf/extras/layout/qr_code_box.rb
+- lib/hexapdf/extras/layout/swiss_qr_bill.rb
 - lib/hexapdf/extras/version.rb
 - test/hexapdf/extras/graphic_object/test_qr_code.rb
 - test/hexapdf/extras/layout/test_qr_code_box.rb
+- test/hexapdf/extras/layout/test_swiss_qr_bill.rb
 - test/test_helper.rb
 homepage: https://hexapdf-extras.gettalong.org
 licenses:
@@ -76,7 +78,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.10
+rubygems_version: 3.5.3
 signing_key:
 specification_version: 4
 summary: Additional functionality for HexaPDF