client_for_poslynx 0.2.5 → 0.2.6

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    ZmJmMWFiZTY5MDAyYWRiMDM4ZGUxY2ZhYzJhZjEwNmJmMDc3ODU3NQ==
+    YzhiNDI0YzUzYjUzNTZjMTQ0ZDQ0ZmYzOTk1MmY2ZWUyNjY4ZjNlNw==
   data.tar.gz: !binary |-
-    NmZkZTU4MGVlOGVjY2VkMzgxNjU2MjdhM2E3MDFhOWUyNmQyOWY1Yg==
+    N2Y1MDE0NGU2NDczOWNiYzVjMTU0ODMwMWQ5MDNjNTM3NWE5NDVjNg==
 SHA512:
   metadata.gz: !binary |-
-    YTliZjg2OGE3MjIwYjMwNzFiZmI5ZjVhZGVkMDRmZWE2ZmVkM2E0ZWQwZjk5
-    NjQ4NzUxNzg5OGI0NGZhZGVjNGY3YjI0ZGNiYTZkNDAxMDVlNDE3ZjY0Y2U0
-    ZDkxOThmODRmMWYwMTI5ZjRkMWVlM2YwZGVjNzgxMThiYTliNWY=
+    OWJmOGE4ZWFiZWJkNDIwMDgzYzhkOTdhNDYyOGI5NjA1ZjRhYjllMzM5OGUx
+    MzVjNjkyNmEzOGUyNWQxNThjM2Q0MWM0ZjJjMjNlYWZkODMxNmY0YTA4ZDhh
+    ZDNkOTA1ZTc3NWU1MjA3MWY5OGMwZGFmOWRkYjgxOTExODMxZmI=
   data.tar.gz: !binary |-
-    YmEwNTQ1NzZlM2RhNjc1YzNlZTg0ZDk2NDhhMmQ1OWMxODZhMjY2YWZkYjkw
-    ZDg3NWJiZTJkOWZiMDY2ODY5MTkyODZlMTlmMTlhNmVlODNlNzcwY2UzMTFl
-    NDRmZjlhNGViZWZhNjk2ZjJlZjM4OWE1YzNjZmUxMjkxNmZmY2Q=
+    Mjk2YjA5MWU2Zjg4NTQ3M2YxMDEwOGM5YzJjYjc2MTAwYWNlNDJjMmQwMDM5
+    NGJkNDEzM2I2YmNlZDRkMDNiMWU0YWQ5MmYwYjBiM2JmMWQ5YjdlODI5NDhm
+    MmMwMDlkMTAzMzgzOWExM2ZlNWZiMGE0Mjc2Mzk2YmIzNTE5OTk=

data/CHANGELOG

@@ -24,8 +24,14 @@ Version 0.2.4
 - Fix bug: Fake terminal script crashes during user interaction
   for a debit sale request without a specified cash back amount.
 
-Version 0.2.4
+Version 0.2.5
 - Introduce experimental signature image parsing and conversion
   to SVG.
 - Fix bug: New format of POSLynx response message XML was causing
   client to hang.
+
+Version 0.2.6
+- Add enhanced-format signature data handling.
+- Fix misconception about signed number representation in
+  signature image data.
+- Bring signature image handling out of experimental status.

data/README.md

@@ -20,11 +20,12 @@ unit with IP address 192.168.1.123, listening on port 54321, with
 a registered client MAC of 000000000000, an example poslynx
 client session might look like...
 
-    bundle exec poslynx_client_console 192.168.1.123:54321
-    1.9.3-p545 :001 > poslynx_client.client_mac_for_examples = '0' * 12
-     => "000000000000"
-    1.9.3-p545 :002 > resp = poslynx_client.send_request( poslynx_client.example_pin_pad_display_message_request )
-     => #<ClientForPoslynx::Data::Responses::PinPadDisplayMessage:0x007fbf529a17f8 @result="SUCCESS", @result_text="Success", @error_code="0000", @button_response="2nd button", @source_data="<PLResponse><Command>PPDISPLAY</Command><Result>SUCCESS</Result><ResultText>Success</ResultText><ErrorCode>0000</ErrorCode><Response>2nd button</Response></PLResponse>\n">
+    $ bundle exec poslynx_client_console 173.195.60.144:14270 --client_mac=000000000000
+    1.9.3-p545 :001 > req = poslynx_client.example_pin_pad_display_message_request
+     => #<ClientForPoslynx::Data::Requests::PinPadDisplayMessage:0x007f941b4b1fe8 @client_mac="001C42E644FE", @text_lines=["First example line", "Second example line"], @line_count=2, @button_labels=["1st of optional buttons", "2nd button"]>
+    1.9.3-p545 :002 > resp = poslynx_client.send_request(req)
+    <?xml version="1.0" standalone="yes" ?><PLResponse><Command>PPDISPLAY</Command><Result>Success</Result><ResultText>Success</ResultText><Response>2nd button</Response></PLResponse>
+     => #<ClientForPoslynx::Data::Responses::PinPadDisplayMessage:0x007f941b4b8230 @result="Success", @result_text="Success", @button_response="2nd button", @source_data="<?xml version=\"1.0\" standalone=\"yes\" ?><PLResponse><Command>PPDISPLAY</Command><Result>Success</Result><ResultText>Success</ResultText><Response>2nd button</Response></PLResponse>\r\n">
 
 This gem also provides a fake POS/terminal application that you
 can run in a separate console window when you are working without
@@ -41,7 +42,7 @@ fake POS/terminal instance on the same machine...
 ## Usage
 
 The code in the
-lib/client_for_poslynx/has_client_colsole_support.rb file
+lib/client_for_poslynx/has_client_console_support.rb file
 provides a good example of how to use the facilities that this
 gem provides.
 
@@ -53,7 +54,7 @@ be separately loaded by requiring "client_for_poslynx/experimental'.
 * Only a subset of the possible messages and elements is supported.
   __More will be added. Contributions are welcome and encouraged. :)__
 * Performs serialization of requests and parsing of responses, but
-  does not ecapsulate actually making TCP connections and requests.
+  does not encapsulate actually making TCP connections and requests.
 
 ## Installation
 

data/bin/poslynx_client_console

@@ -12,8 +12,13 @@ end
 # file name for input.
 $*.replace []
 
-# The only option we car about is --help, so we either show usage
-# for --help or because an unrecognized option was given.
+# Take --client_mac=<hexadecimal-value> if present.
+client_mac_opts = option_args.select{ |opt| opt =~ /^--client_mac=[0-9a-fA-F]+$/ }
+option_args -= client_mac_opts
+client_mac_option = client_mac_opts.last
+
+# The only remaining option we care about is --help, so we either
+# show usage for --help or because an unrecognized option was given.
 show_usage = option_args.length > 0
 
 # Should have exactly 1 value argument for the address + port number.
@@ -33,19 +38,27 @@ if show_usage
 
   puts <<-EOS
 
-Usage: poslynx_client_console [<host>]:<port-number> Host is the
-domain name or IP address of the POSLynx or fake POS terminal
-host.  If this is not supplied, then 127.0.0.1 is assumed.
+Usage: poslynx_client_console [<host>]:<port-number>
+
+Host is the domain name or IP address of the POSLynx or fake POS
+terminal host.  If this is not supplied, then 127.0.0.1 is
+assumed.
+
+Options:
+
+  --client_mac=<hexadecimal>  The client MAC value to be assigned
+                              to example-request objects.
+
+  --help                      Prints this usage information.
 
 Opens an interactive Ruby shell with a globally acccessible
 poslynx_client method that returns an object with conveniences
 for making requests to a POSLynx or to your fake
 POSLynx+terminal host.
 
-For example, you might execute the following commands from
+For example, you might execute the following command from
 within the console...
 
-  poslynx_client.client_mac_for_examples = '123456789012'
   resp = poslynx_client.send_request( poslynx_client.example_credit_card_sale_request )
 
 To see what else the poslynx_client object provides, see the
@@ -70,6 +83,10 @@ else
   config.host = host
   config.port = port
 
+  if client_mac_option
+    config.client_mac_for_examples = client_mac_option.split('=').last
+  end
+
   IRB.start
 
 end

data/lib/client_for_poslynx/bit_sequence.rb

@@ -41,15 +41,25 @@ module ClientForPoslynx
         bit_seq
       end
 
-      def from_sign_and_magnitude_of(value, seq_length)
-        magnitude = value.abs
-        magnitude_seq = from_unsigned( magnitude, seq_length - 1 )
-        sign_bit = from_bit_digits( value < 0 ? '1' : '0' )
-        magnitude_seq.unshift( sign_bit )
+      def from_signed(value, seq_length)
+        if seq_length > 64
+          raise TooManyBitsLong, "Can't build a representation more than 64 bits long from a signed number"
+        end
+        max_magnitude = 2 ** (seq_length - 1)
+        if value < -max_magnitude
+          raise NumberOutOfBounds, "The largest negative value representable in #{seq_length} bits is smaller than than #{value}"
+        end
+        if value >= max_magnitude
+          raise NumberOutOfBounds, "The largest positive value representable in #{seq_length} bits is less than #{value}"
+        end
+        packed_bits = [ value ].pack('q>')
+        bit_seq = from_packed_bits( packed_bits )
+        bit_seq.shift( 64 - seq_length )
+        bit_seq
       end
 
-      def from_uuencoded(uuencoded)
-        packed_bits = uuencoded.unpack('u').first
+      def from_base64(encoded)
+        packed_bits = encoded.unpack('m0').first
         from_packed_bits( packed_bits )
       end
     end
@@ -81,8 +91,8 @@ module ClientForPoslynx
       digits_string
     end
 
-    def uuencode
-      [ to_packed_bits ].pack('u')
+    def base64_encode
+      [ to_packed_bits ].pack('m0')
     end
 
     def length
@@ -111,24 +121,25 @@ module ClientForPoslynx
       self
     end
 
-    def as_unsigned
+    def as_signed
       if length > 64
         raise TooManyBitsLong,
-          "Cannot coerce sequence longer than 64 bits to unsigned number"
+          "Cannot coerce sequence longer than 64 bits to signed number"
       end
-      little_endian_digits = digits_string.reverse + '0' * 64
+      fill = first_bit_digit * 64
+      little_endian_digits = digits_string.reverse + fill
       packed_little_endian = [ little_endian_digits ].pack('b*')
-      packed_little_endian.unpack('Q<').first
+      packed_little_endian.unpack('q<').first
     end
 
-    def as_sign_and_magnitude
-      if length > 65
+    def as_unsigned
+      if length > 64
         raise TooManyBitsLong,
-          "Cannot coerce sequence longer than 65 bits to unsigned number"
+          "Cannot coerce sequence longer than 64 bits to unsigned number"
       end
-      magnitude_seq = self.class.from_bit_digits( digits_string[1..-1] )
-      magnitude = magnitude_seq.as_unsigned
-      first_bit_digit == '1' ? - magnitude : magnitude
+      little_endian_digits = digits_string.reverse + '0' * 64
+      packed_little_endian = [ little_endian_digits ].pack('b*')
+      packed_little_endian.unpack('Q<').first
     end
 
     private

data/lib/client_for_poslynx/data/properties_xml_parser.rb

@@ -15,12 +15,6 @@ module ClientForPoslynx
       def initialize(root_element_name)
         @root_element_name = root_element_name
       end
-
-#      def parse(source_xml)
-#        xml_document = XmlDocument.new( source_xml )
-#        xml_document.property_element_values
-#      end
-
     end
 
   end

data/lib/client_for_poslynx/data/responses/credit_card_sale.rb

@@ -27,6 +27,13 @@ module ClientForPoslynx
         attr_element_mapping attribute: :receipt,                  element: 'Receipt',         numbered_lines: 'Receipt%d'
         attr_element_mapping attribute: :customer_receipt,         element: 'ReceiptCustomer', numbered_lines: 'Receipt%d'
 
+        def signature=(value)
+          if value =~ /^<!\[CDATA\[(.*)\]\]>$/
+            @signature = $1
+          else
+            @signature = value
+          end
+        end
       end
 
     end

data/lib/client_for_poslynx/experimental.rb

@@ -3,14 +3,4 @@
 # Require this file to load experimental features that
 # are not yet expected to be fully usable.
 
-# Bit sequence is actually in pretty good shape, but it's
-# here because it is only used by SignatureImage.
-require "client_for_poslynx/bit_sequence"
-
-# SignatureImage currently only supports the legacy
-# Hypercom/Equinox signature data format, which is useful
-# to approximately 0% of POSLynx users. It has also not
-# been tested with real data produced by a payment terminal,
-# so it is possible that some understandings about the
-# format are incorrect.
-require "client_for_poslynx/signature_image"
+# No experimental features at this time.

data/lib/client_for_poslynx/has_client_console_support.rb

@@ -12,8 +12,6 @@ module ClientForPoslynx
     end
 
     class Client
-      attr_accessor :client_mac_for_examples
-
       def config
         @config ||= Config.new
       end
@@ -95,13 +93,13 @@ module ClientForPoslynx
       end
 
       def assign_common_example_request_attrs_to(request)
-        request.client_mac = client_mac_for_examples if client_mac_for_examples
+        request.client_mac = config.client_mac_for_examples if config.client_mac_for_examples
       end
 
     end
 
     class Config
-      attr_accessor :host, :port
+      attr_accessor :host, :port, :client_mac_for_examples
     end
 
   end

data/lib/client_for_poslynx/message_handling/xml_extractor.rb

@@ -23,7 +23,6 @@ module ClientForPoslynx
         root_name = nil
         while true
           line = stream.gets
-          puts line
           message << line
           if (! root_name) && line =~ /^(?:<\?.+?\?>)?<([A-Za-z_][^\s>]*)[ >]/
             root_name = $1

data/lib/client_for_poslynx/signature_image/draw.rb

@@ -7,16 +7,16 @@ module ClientForPoslynx
       DELTA_BITS_LONG = 6
       BIT_SEQUENCE_LENGTH = 1 + DELTA_BITS_LONG * 2
 
-      def self.first_in_bit_sequence(bit_seq)
+      def self.first_in_bit_sequence(bit_seq, format=nil)
         bit_seq.first_bit_digit == '0' &&
           bit_seq.length >= BIT_SEQUENCE_LENGTH
       end
 
-      def self.parse_from_bit_sequence!(bit_seq)
+      def self.parse_from_bit_sequence!(bit_seq, format=nil)
         bit_seq.shift 1
         dx_bit_seq = bit_seq.shift( DELTA_BITS_LONG )
         dy_bit_seq = bit_seq.shift( DELTA_BITS_LONG )
-        new( dx_bit_seq.as_sign_and_magnitude, dy_bit_seq.as_sign_and_magnitude )
+        new( dx_bit_seq.as_signed, dy_bit_seq.as_signed )
       end
 
       attr_reader :dx, :dy
@@ -31,10 +31,10 @@ module ClientForPoslynx
         return dx == other.dx && dy == other.dy
       end
 
-      def to_bit_sequence
+      def to_bit_sequence(serialization_format=nil)
         bit_seq = ClientForPoslynx::BitSequence / '0'
-        bit_seq << ClientForPoslynx::BitSequence.from_sign_and_magnitude_of( dx, DELTA_BITS_LONG )
-        bit_seq << ClientForPoslynx::BitSequence.from_sign_and_magnitude_of( dy, DELTA_BITS_LONG )
+        bit_seq << ClientForPoslynx::BitSequence.from_signed( dx, DELTA_BITS_LONG )
+        bit_seq << ClientForPoslynx::BitSequence.from_signed( dy, DELTA_BITS_LONG )
       end
 
     end

data/lib/client_for_poslynx/signature_image/metrics.rb

@@ -0,0 +1,17 @@
+module ClientForPoslynx
+  class SignatureImage
+
+    class Metrics <
+      Struct.new(
+
+        # [x,y] scaled resolution
+        :resolution,
+
+        # [x,y] pysical size in dekamicrometers
+        # 1 dekamicrometer = 10 micrometers or 0.01 millimeters
+        :size_in_dum,
+      )
+    end
+
+  end
+end

data/lib/client_for_poslynx/signature_image/move.rb

@@ -4,19 +4,19 @@ module ClientForPoslynx
   class SignatureImage
 
     class Move
-      X_BITS_LONG = 10
-      Y_BITS_LONG = 7
-      BIT_SEQUENCE_LENGTH = 1 + X_BITS_LONG + Y_BITS_LONG
+      X_BITS_LONG = { legacy: 10, enhanced_narrow: 10, enhanced_wide: 11 }
+      Y_BITS_LONG = { legacy: 7,  enhanced_narrow: 10, enhanced_wide: 10 }
 
-      def self.first_in_bit_sequence(bit_seq)
+      def self.first_in_bit_sequence(bit_seq, format=:legacy)
+        bit_sequence_length = 1 + X_BITS_LONG[format] + Y_BITS_LONG[format]
         bit_seq.first_bit_digit == '1' &&
-          bit_seq.length >= BIT_SEQUENCE_LENGTH
+          bit_seq.length >= bit_sequence_length
       end
 
-      def self.parse_from_bit_sequence!(bit_seq)
+      def self.parse_from_bit_sequence!(bit_seq, format=:legacy)
         bit_seq.shift 1
-        x_bit_seq = bit_seq.shift( X_BITS_LONG )
-        y_bit_seq = bit_seq.shift( Y_BITS_LONG )
+        x_bit_seq = bit_seq.shift( X_BITS_LONG[format] )
+        y_bit_seq = bit_seq.shift( Y_BITS_LONG[format] )
         new( x_bit_seq.as_unsigned, y_bit_seq.as_unsigned )
       end
 
@@ -32,10 +32,10 @@ module ClientForPoslynx
         return x == other.x && y == other.y
       end
 
-      def to_bit_sequence
+      def to_bit_sequence(format=:legacy)
         bit_seq = ClientForPoslynx::BitSequence / '1'
-        bit_seq << ClientForPoslynx::BitSequence.from_unsigned( x, X_BITS_LONG )
-        bit_seq << ClientForPoslynx::BitSequence.from_unsigned( y, Y_BITS_LONG )
+        bit_seq << ClientForPoslynx::BitSequence.from_unsigned( x, X_BITS_LONG[format] )
+        bit_seq << ClientForPoslynx::BitSequence.from_unsigned( y, Y_BITS_LONG[format] )
       end
     end
 

data/lib/client_for_poslynx/signature_image/to_svg_converter.rb

@@ -38,9 +38,10 @@ module ClientForPoslynx
       private
 
       def apply_document_characteristics
-        svg_element['width'              ] = '67.17mm'
-        svg_element['height'             ] = '13.434mm'
-        svg_element['viewBox'            ] = '0 0 640 128'
+        metrics = signature_image.metrics || SignatureImage::Metrics.new([6717, 1343], [640, 128])
+        svg_element['width'              ] = '%fmm' % ( metrics.size_in_dum[0] * 0.01 )
+        svg_element['height'             ] = '%fmm' % ( metrics.size_in_dum[1] * 0.01 )
+        svg_element['viewBox'            ] = '0 0 %d %d' % metrics.resolution
         svg_element['preserveAspectRatio'] = 'none'
       end
 

data/lib/client_for_poslynx/signature_image.rb

@@ -1,5 +1,6 @@
 # coding: utf-8
 
+require_relative 'signature_image/metrics'
 require_relative 'signature_image/move'
 require_relative 'signature_image/draw'
 require_relative 'signature_image/to_svg_converter'
@@ -11,30 +12,59 @@ module ClientForPoslynx
     class << self
 
       def deserialize(serialized_data)
-        packed_binary = uudecode( serialized_data )
+        packed_binary = base64_decode( serialized_data )
         bit_seq = ClientForPoslynx::BitSequence.from_packed_bits( packed_binary )
 
         sig_image = new
+
+        if bit_seq.first_bit_digit == '0' then
+          leader_seq = bit_seq.shift( 16 )
+          header_content_length_bytes = leader_seq.as_unsigned
+          if header_content_length_bytes < 8 then
+            # TODO: Should have an exception class for this error.
+            raise "Expected header content length to be >= 8, but got #{header_content_length}."
+          end
+          if header_content_length_bytes > 255 then
+            # TODO: Should have an exception class for this error.
+            byte_0_bit_digits = leader_seq.to_bit_digits[0..7]
+            raise "Expected first byte of leader to be zero, but got #{byte_0_bit_digits}."
+          end
+          header_content_seq = bit_seq.shift( header_content_length_bytes * 8 )
+          x_scaled_res = header_content_seq.shift(16).as_unsigned
+          y_scaled_res = header_content_seq.shift(16).as_unsigned
+          x_phys_size  = header_content_seq.shift(16).as_unsigned
+          y_phys_size  = header_content_seq.shift(16).as_unsigned
+          sig_image.metrics = SignatureImage::Metrics.new(
+            [ x_scaled_res, y_scaled_res ],
+            [ x_phys_size,  y_phys_size  ],
+          )
+        end
+
+        format = sig_image.serialization_format
+
         step_types = [ SignatureImage::Move, SignatureImage::Draw ]
         while true
-          step_type = step_types.detect{ |st| st.first_in_bit_sequence( bit_seq ) }
+          step_type = step_types.detect{ |st| st.first_in_bit_sequence( bit_seq, format ) }
           break if step_type.nil?
-          step = step_type.parse_from_bit_sequence!( bit_seq )
+          step = step_type.parse_from_bit_sequence!( bit_seq, format )
           sig_image << step
         end
 
         sig_image
       end
 
-      def uudecode(uuencoded)
-        uuencoded.unpack('u').first
+      def base64_decode(encoded)
+        encoded.unpack('m').first
       end
 
     end
 
+    attr_accessor :metrics
+
     def ==(other)
       return false unless self.class === other
-      sequence == other.sequence
+      metrics == other.metrics &&
+        sequence == other.sequence
     end
 
     def move(*args)
@@ -66,15 +96,34 @@ module ClientForPoslynx
       groups
     end
 
-    def serialize_legacy
+    def serialize
       unless Move === sequence.first
         raise 'Must have an initial move-type step in order to serialize'
       end
       bit_seq = ClientForPoslynx::BitSequence.new_empty
+      case serialization_format
+      when :enhanced_narrow, :enhanced_wide
+        bit_seq << ClientForPoslynx::BitSequence / '00000000'
+        bit_seq << ClientForPoslynx::BitSequence / '00001000'
+        bit_seq << ClientForPoslynx::BitSequence.from_unsigned( metrics.resolution[0], 16 )
+        bit_seq << ClientForPoslynx::BitSequence.from_unsigned( metrics.resolution[1], 16 )
+        bit_seq << ClientForPoslynx::BitSequence.from_unsigned( metrics.size_in_dum[0], 16 )
+        bit_seq << ClientForPoslynx::BitSequence.from_unsigned( metrics.size_in_dum[1], 16 )
+      end
       sequence.each do |step|
-        bit_seq << step.to_bit_sequence
+        bit_seq << step.to_bit_sequence( serialization_format )
+      end
+      bit_seq.base64_encode
+    end
+
+    def serialization_format
+      if metrics.nil?
+        :legacy
+      else
+        metrics.resolution[0] > 1024 ?
+          :enhanced_wide :
+          :enhanced_narrow
       end
-      bit_seq.uuencode
     end
 
     protected

data/lib/client_for_poslynx/version.rb

@@ -1,5 +1,5 @@
 # coding: utf-8
 
 module ClientForPoslynx
-  VERSION = '0.2.5'
+  VERSION = '0.2.6'
 end

data/lib/client_for_poslynx.rb

@@ -3,6 +3,8 @@
 require "client_for_poslynx/version"
 require "client_for_poslynx/data"
 require "client_for_poslynx/message_handling"
+require "client_for_poslynx/bit_sequence"
+require "client_for_poslynx/signature_image"
 
 module ClientForPoslynx
 

data/spec/client_for_poslynx/bit_sequence_spec.rb

@@ -69,7 +69,7 @@ module ClientForPoslynx
       expect( taken      ).to eq( expected_taken     )
     end
 
-    it "can have another bit sequence unshifted onto its fron" do
+    it "can have another bit sequence unshifted onto its front" do
       bit_target = klass / '000111000'
       bit_target.unshift klass / '111000111'
 
@@ -89,17 +89,17 @@ module ClientForPoslynx
         raise_exception( klass::TooManyBitsLong, /\b64\b/ )
     end
 
-    it "can be (big-endian) interpreted as the sign-bit and magnitude of an integer" do
-      expect( ( klass / '000'                  ).as_sign_and_magnitude ).to eq(   0 )
-      expect( ( klass / '0111000011110000'     ).as_sign_and_magnitude ).to eq(   0x70F0 )
-      expect( ( klass / '1111000011110000'     ).as_sign_and_magnitude ).to eq( - 0x70F0 )
-      expect( ( klass / ('1' + '11110000' * 8) ).as_sign_and_magnitude ).to eq( - 0xF0F0F0F0F0F0F0F0 )
+    it "can be (big-endian) interpreted as a 2s-complement signed integer" do
+      expect( ( klass / '000'              ).as_signed ).to eq(   0 )
+      expect( ( klass / '0111000011110000' ).as_signed ).to eq(   0x70F0 )
+      expect( ( klass / '1000111100010000' ).as_signed ).to eq( - 0x70F0 )
+      expect( ( klass / ('11110000' * 8)   ).as_signed ).to eq( - 0x0F0F0F0F0F0F0F10 )
     end
 
-    it "fails to be interpreted as sign-bit and magnitude if longer than 65 bits" do
-      bit_seq = klass / ( '0' + '11110000' * 8 + '1' )
-      expect{ bit_seq.as_sign_and_magnitude }.
-        to raise_exception( klass::TooManyBitsLong, /\b65\b/ )
+    it "fails to be interpreted as 2s complement if longer than 64 bits" do
+      bit_seq = klass / ( '0' + '11110000' * 8 )
+      expect{ bit_seq.as_signed }.
+        to raise_exception( klass::TooManyBitsLong, /\b64\b/ )
     end
 
     it "can be constructed as the big-endian representation of an unsigned integer" do
@@ -108,13 +108,6 @@ module ClientForPoslynx
       expect( klass.from_unsigned( (2 ** 64) - 1, 64 ) ).to eq( klass / ( '1' * 64  ) )
     end
 
-    it "can be constructed as the sign-bit and big-endian magnitude representation of an integer" do
-      expect( klass.from_sign_and_magnitude_of(   0,            10 ) ).to eq( klass / ( '0' * 10   ) )
-      expect( klass.from_sign_and_magnitude_of(   0x23,          8 ) ).to eq( klass / ( '00100011' ) )
-      expect( klass.from_sign_and_magnitude_of( - 0x23,          8 ) ).to eq( klass / ( '10100011' ) )
-      expect( klass.from_sign_and_magnitude_of( -(2 ** 64) + 1, 65 ) ).to eq( klass / ( '1' * 65   ) )
-    end
-
     it "fails to be constructed as a longer than 64-bit representation of an unsigned number" do
       expect{ klass.from_unsigned(0x23, 65) }.
         to raise_exception( klass::TooManyBitsLong, /\b64\b/ )
@@ -130,16 +123,38 @@ module ClientForPoslynx
         to raise_exception( klass::NumberOutOfBounds )
     end
 
-    it "can be build by unpacking bits from a uuencoded string" do
-      actual   = klass.from_uuencoded( "&,C(R,C(R\n" )
+    it "can be constructed as the big-endian, 2's complement representation of a signed integer" do
+      expect( klass.from_signed(   0,         9 ) ).to eq( klass / ( '0' * 9   ) )
+      expect( klass.from_signed(  -0x23,      7 ) ).to eq( klass / ( '1011101' ) )
+      expect( klass.from_signed(  -1,         4 ) ).to eq( klass / ( '1111'    ) )
+      expect( klass.from_signed( -(2 ** 63), 64 ) ).to eq( klass / ( '1' + '0' * 63  ) )
+    end
+
+    it "fails to be constructed as a longer than 64-bit representation of a signed number" do
+      expect{ klass.from_signed(0x23, 65) }.
+        to raise_exception( klass::TooManyBitsLong, /\b64\b/ )
+    end
+
+    it "fails to be constructed as a  an under-sized representation a negative signed number" do
+      expect{ klass.from_signed(-0x23, 6) }.
+        to raise_exception( klass::NumberOutOfBounds )
+    end
+
+    it "fails to be constructed as an under-sized representation of a positive signed number" do
+      expect{ klass.from_signed(0x23, 6) }.
+        to raise_exception( klass::NumberOutOfBounds )
+    end
+
+    it "can be build by unpacking bits from a base-64 encoded string" do
+      actual   = klass.from_base64( "MjIyMjIy" )
       expected = klass ^ "\x32" * 6
 
       expect( actual ).to eq( expected )
     end
 
-    it "can be packed to a uuencoded string" do
+    it "can be packed to a base-64 string" do
       bit_seq = klass ^ "\x32" * 6
-      expect( bit_seq.uuencode ).to eq( "&,C(R,C(R\n" )
+      expect( bit_seq.base64_encode ).to eq( "MjIyMjIy" )
     end
 
   end

data/spec/client_for_poslynx/data/responses/credit_card_sale_spec.rb

@@ -6,6 +6,17 @@ module ClientForPoslynx
 
     it_behaves_like "a data object"
 
+    # At least one revision of the POSLynx returns signature
+    # data surrounded by &lt[CDATA[...]]&gt which is obviously
+    # supposed to be CDATA encoding in XML. Since the angle
+    # brackets are esacped, however, the element contains the
+    # CDATA-encoded XML as its text value instead of the
+    # intended content.
+    it "repairs malformed signature image CDATA" do
+      subject.signature = "<![CDATA[ABC123]]>"
+      expect( subject.signature ).to eq( 'ABC123' )
+    end
+
     it "Serializes to a PLResponse XML document for a CCSALE response" do
       expected_xml = "<PLResponse><Command>CCSALE</Command></PLResponse>\n"
 

data/spec/client_for_poslynx/signature_image_spec.rb

@@ -8,43 +8,82 @@ module ClientForPoslynx
 
     def build_example_image
       described_class.new.tap { |si|
-        si.move  10, 120
-        si.draw   0, -30
-        si.draw   0, -30
-        si.draw   0, -30
-        si.draw   0, -20
-        si.draw  30,  30
-        si.draw -25,  25
-        si.draw   0,  -2
+        si.move  20, 120
+        si.draw  10, -30
+        si.draw  10, -30
+        si.draw  10, -30
+        si.draw  10,  30
+        si.draw  10,  30
+        si.draw  10,  30
+        si.move  35,  75
+        si.draw  30,  -1
       }
     end
 
-    let( :bit_sequence ) {
-      BitSequence.from_bit_digits( bit_digit_sequence )
+    let( :legacy_bit_sequence ) {
+      BitSequence.from_bit_digits( legacy_bit_digit_sequence )
     }
 
-    let( :bit_digit_sequence ) {
-      # TODO: Currently assuming that deltas for move are
-      # expressed as sign bit and magnitude, where sign bit
-      # of 1 means negative. Documentation is unclear about
-      # this though except to say that there is a sign bit,
-      # and that values can range from -31 to 31.
-      # Once I can connect to the virtual POSLynx again, I
-      # need to do a test, and find out whether this
-      # assumption is true or not.
-      
-      '1' + '0000001010' + '1111000' + # move  10, 120
-      '0' + '000000' + '111110' +      # draw   0, -30
-      '0' + '000000' + '111110' +      # draw   0, -30
-      '0' + '000000' + '111110' +      # draw   0, -30
-      '0' + '000000' + '110100' +      # draw   0, -20
-      '0' + '011110' + '011110' +      # draw  30,  30
-      '0' + '111001' + '011001' +      # draw -25,  25
-      '0' + '000000' + '100010' +      # draw   0,  -2
-      '000'                            # remaining bits in last byte
+    let( :legacy_bit_digit_sequence ) {
+      '1' + '0000010100' + '1111000' + # move  20, 120 (10-bit, 7-bit)
+      '0' + '001010' + '100010' +      # draw  10, -30
+      '0' + '001010' + '100010' +      # draw  10, -30
+      '0' + '001010' + '100010' +      # draw  10, -30
+      '0' + '001010' + '011110' +      # draw  10,  30
+      '0' + '001010' + '011110' +      # draw  10,  30
+      '0' + '001010' + '011110' +      # draw  10,  30
+      '1' + '0000100011' + '1001011' + # move  35,  75  64+8+2+1
+      '0' + '011110' + '111111' +      # draw  30,  -1
+      '0'                              # remaining bit in last byte
     }
 
-    it "is unequal to another instance with a different sequence of steps" do
+    let( :enhanced_narrow_bit_sequence ) {
+      BitSequence.from_bit_digits( enhanced_narrow_bit_digit_sequence )
+    }
+
+    let( :enhanced_narrow_bit_digit_sequence ) {
+      '00000000' +                        # 1st byte all 0s: Indicates enhanced format.
+      '00001000' +                        # Header content length: 8 bytes
+      '0000010000000000' +                # X scaled resolution: 1024 (maximum to be treated as narrow)
+      '0000000110000000' +                # Y scaled resolution: 384
+      '0001111101000000' +                # X physical size in 0.01 mm units: 8000
+      '0000101110111000' +                # Y physical size in 0.01 mm units: 3000
+      '1' + '0000010100' + '0001111000' + # move  20, 120 (10-bit, 10-bit)
+      '0' + '001010' + '100010' +         # draw  10, -30
+      '0' + '001010' + '100010' +         # draw  10, -30
+      '0' + '001010' + '100010' +         # draw  10, -30
+      '0' + '001010' + '011110' +         # draw  10,  30
+      '0' + '001010' + '011110' +         # draw  10,  30
+      '0' + '001010' + '011110' +         # draw  10,  30
+      '1' + '0000100011' + '0001001011' + # move  35,  75
+      '0' + '011110' + '111111' +         # draw  30,  -1
+      '000'                               # remaining bits in last byte
+    }
+
+    let( :enhanced_wide_bit_sequence ) {
+      BitSequence.from_bit_digits( enhanced_wide_bit_digit_sequence )
+    }
+
+    let( :enhanced_wide_bit_digit_sequence ) {
+      '00000000' +                         # 1st byte all 0s: Indicates enhanced format.
+      '00001000' +                         # Header content length: 8 bytes
+      '0000010000000001' +                 # X scaled resolution: 1025 (minimum to be treated as wide)
+      '0000000110011010' +                 # Y scaled resolution: 410
+      '0001111101000000' +                 # X physical size in 0.01 mm units: 8000
+      '0000110010000000' +                 # Y physical size in 0.01 mm units: 3200
+      '1' + '00000010100' + '0001111000' + # move  20, 120 (11-bit, 10-bit)
+      '0' + '001010' + '100010' +          # draw  10, -30
+      '0' + '001010' + '100010' +          # draw  10, -30
+      '0' + '001010' + '100010' +          # draw  10, -30
+      '0' + '001010' + '011110' +          # draw  10,  30
+      '0' + '001010' + '011110' +          # draw  10,  30
+      '0' + '001010' + '011110' +          # draw  10,  30
+      '1' + '00000100011' + '0001001011' + # move  35,  75
+      '0' + '011110' + '111111' +          # draw  30,  -1
+      '0'                                  # remaining bit in last byte
+    }
+
+    it "is unequal to another instance with a different sequence of steps and no metrics" do
       subject = build_example_image
 
       other_sig = described_class.new
@@ -54,35 +93,129 @@ module ClientForPoslynx
       expect( subject ).not_to eq( other_sig )
     end
 
-    it "is equal to another instance with the same sequence of steps" do
+    it "is unequal to another instance with a different sequence of steps and same metrics" do
+      subject = build_example_image
+      subject.metrics = SignatureImage::Metrics.new([1000, 250], [6080, 1520])
+
+      other_sig = described_class.new
+      other_sig.metrics = SignatureImage::Metrics.new([1000, 250], [6080, 1520])
+      other_sig.move 10, 120
+      other_sig.draw  0, -29
+
+      expect( subject ).not_to eq( other_sig )
+    end
+
+    it "is unequal to another instance with the same sequence of steps and different metrics" do
+      subject   = build_example_image
+      subject.metrics = SignatureImage::Metrics.new([1000, 250], [6080, 1520])
+
+      other_sig = build_example_image
+      other_sig.metrics = SignatureImage::Metrics.new([999, 250], [6080, 1520])
+
+      expect( subject ).not_to eq( other_sig )
+    end
+
+    it "is equal to another instance with the same sequence of steps and no metrics" do
       subject   = build_example_image
       other_sig = build_example_image
 
       expect( subject ).to eq( other_sig )
     end
 
-    context "serializing" do
-      subject{ build_example_image }
+    it "is equal to another instance with the same sequence of steps and same metrics" do
+      subject   = build_example_image
+      subject.metrics = SignatureImage::Metrics.new([1000, 250], [6080, 1520])
 
-      it "serializes data in legacy format" do
-        actual_serialized = subject.serialize_legacy
-        actual_bit_sequence = BitSequence.from_uuencoded( actual_serialized )
+      other_sig = build_example_image
+      other_sig.metrics = SignatureImage::Metrics.new([1000, 250], [6080, 1520])
+
+      expect( subject ).to eq( other_sig )
+    end
+
+    context "legacy serialized format" do
+      context "serializing" do
+        subject{ build_example_image }
+
+        it "serializes data" do
+          actual_serialized = subject.serialize
+          actual_bit_sequence = BitSequence.from_base64( actual_serialized )
 
-        expect( actual_bit_sequence ).to eq( bit_sequence )
+          expect( actual_bit_sequence ).to eq( legacy_bit_sequence )
+        end
+      end
+
+      context "deserializing" do
+        subject{ described_class.new(serialized_data) }
+        let( :serialized_data ) {
+          legacy_bit_sequence.base64_encode
+        }
+
+        it "deserializes data" do
+          actual = described_class.deserialize( serialized_data )
+          expected = build_example_image
+
+          expect( actual ).to eq( expected )
+        end
       end
     end
 
-    context "deserializing" do
-      subject{ described_class.new(serialized_data) }
-      let( :serialized_data ) {
-        bit_sequence.uuencode
-      }
+    context "enhanced format with narrow resolution" do
+      context "serializing" do
+        subject{ build_example_image.tap{ |img|
+          img.metrics = SignatureImage::Metrics.new([1024,384], [8000,3000])
+        } }
+
+        it "serializes data" do
+          actual_serialized = subject.serialize
+          actual_bit_sequence = BitSequence.from_base64( actual_serialized )
+
+          expect( actual_bit_sequence ).to eq( enhanced_narrow_bit_sequence )
+        end
+      end
+
+      context "deserializing" do
+        subject{ described_class.new(serialized_data) }
+        let( :serialized_data ) {
+          enhanced_narrow_bit_sequence.base64_encode
+        }
+
+        it "deserializes data" do
+          actual = described_class.deserialize( serialized_data )
+          expected = build_example_image
+          expected.metrics = SignatureImage::Metrics.new([1024,384], [8000,3000])
+
+          expect( actual ).to eq( expected )
+        end
+      end
+    end
+
+    context "enhanced format with wide resolution" do
+      context "serializing" do
+        subject{ build_example_image.tap{ |img|
+          img.metrics = SignatureImage::Metrics.new([1025,410], [8000,3200])
+        } }
+
+        it "serializes data" do
+          actual_serialized = subject.serialize
+          actual_bit_sequence = BitSequence.from_base64( actual_serialized )
+
+          expect( actual_bit_sequence ).to eq( enhanced_wide_bit_sequence )
+        end
+      end
+
+      context "deserializing" do
+        subject{ described_class.new(serialized_data) }
+        let( :serialized_data ) {
+          enhanced_wide_bit_sequence.base64_encode
+        }
 
-      it "deserializes data from legacy format" do
-        actual = described_class.deserialize( serialized_data )
-        expected = build_example_image
+        it "deserializes data" do
+          actual = described_class.deserialize( serialized_data )
+          expected = build_example_image
+          expected.metrics = SignatureImage::Metrics.new([1025,410], [8000,3200])
 
-        expect( actual ).to eq( expected )
+          expect( actual ).to eq( expected )
+        end
       end
     end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: client_for_poslynx
 version: !ruby/object:Gem::Version
-  version: 0.2.5
+  version: 0.2.6
 platform: ruby
 authors:
 - Steve Jorgensen
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-11-07 00:00:00.000000000 Z
+date: 2014-11-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nokogiri
@@ -86,7 +86,6 @@ files:
 - bin/fake_pos_terminal
 - bin/poslynx_client_console
 - client_for_poslynx.gemspec
-- foo.svg
 - lib/client_for_poslynx.rb
 - lib/client_for_poslynx/bit_sequence.rb
 - lib/client_for_poslynx/data.rb
@@ -135,6 +134,7 @@ files:
 - lib/client_for_poslynx/message_handling/xml_extractor.rb
 - lib/client_for_poslynx/signature_image.rb
 - lib/client_for_poslynx/signature_image/draw.rb
+- lib/client_for_poslynx/signature_image/metrics.rb
 - lib/client_for_poslynx/signature_image/move.rb
 - lib/client_for_poslynx/signature_image/to_svg_converter.rb
 - lib/client_for_poslynx/version.rb

data/foo.svg

@@ -1,20 +0,0 @@
-<svg version="1.1"
-     width="67.17mm" height="13.434mm"
-     viewBox="0 0 640 128"
-     preserveAspectRatio='none'
-     xmlns="http://www.w3.org/2000/svg"
->
-
-  <path d='M 40,10 l 0,30 0,30 -5,5 -3,1 -3,-1 -5,-5
-           M 24,10 l 30,0
-           M 65,40 l 10,0 6,4 4,6 0,15 -4,6 -6,4 -10,0 -6,-4 -4,-6 0,-15, 4,-6
-           M 93,40 l 14,28 5,10
-           M 130,40 l -15,30 -15,30 M 160,50 l 0,0'
-        stroke='black'
-        stroke-width='1mm'
-        stroke-linejoin='round'
-        stroke-linecap='square'
-        fill='none'
-  />
-
-</svg>