ruby-zint 1.1.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ccdb5e197e8d714e8f2d336b7448a1e104a69a5969b2d811ee6b0ef8998e6cac
-  data.tar.gz: 547681f881a38f9168ac6330f07f300f578e2655eb3241633992e619394239e9
+  metadata.gz: 486ea5eb1e9c5382337612a19ce2101cbbcba980dc30b9d1ff702f2dbc4beba9
+  data.tar.gz: 0be779d097b3e9f99d7c79d4f8da8895c2e8931ea6be84165f77d40bc9f0a5a8
 SHA512:
-  metadata.gz: 772885463ca263b7a44405a78851961817a04d97b7e2fe2bb7691a5f5b06c0a7c2055bcf5f9dcfc07e1c2b5d235dbf75dcd8a161d5b0d2d2f04629fb4fb603b4
-  data.tar.gz: 565dcf8defee2948e4a4335e9681111056b7ee81a5dd03134f77cb030425131829964f7e2847813ee8866e61de3210e1796f855ae9c09ad601b623a8609dd9e4
+  metadata.gz: a33d8244d461e0dac91b66f086aa153d26ed188ae418fa3b1ba1d03139e424d678b2ef92a988f8db7c23d6e46627912e2f04a753c66e77b7c5b1b51e9383f3e5
+  data.tar.gz: c97890ca409f5393478f14b4630147229c8e4f282b640a51ff781d98fc8f4c31f42eaed3167d9e16d6b2dc021884af14fd92a75234f573bcbb46562db62d326d

data/.yardopts

@@ -0,0 +1,9 @@
+--readme          README.md
+--title           'Ruby FFI binding for libzint'
+--exclude         '/ext.ruby-zint/'
+--no-private
+--charset utf-8
+lib/**/*.rb
+-
+README.md
+LICENSE.txt

data/README.md

@@ -27,7 +27,7 @@ Install the libzint binary with your package manager (e. g. `apt install zint` o
 
 Other platforms require building [from source](https://www.zint.org.uk/manual/chapter/2).
 
-**NOTE:** It is assumed that you are using libzint with the version [2.10](https://sourceforge.net/projects/zint/files/zint/2.10.0/).
+**NOTE:** It is assumed that you are using libzint with the version [2.12](https://sourceforge.net/projects/zint/files/zint/2.12.0/).
 
 Then install this gem and enforce system libzint:
 
@@ -49,7 +49,7 @@ bundle config build.ruby-zint --enable-system-libzint
 ```ruby
 require "zint"
 
-barcode = Zint::Barcode.new(value: "Test", type: Zint::BARCODE_CODE128)
+barcode = Zint::Barcode.new(value: "Test", symbology: Zint::BARCODE_CODE128)
 
 # Export to file
 barcode.to_file(path: "out.png")
@@ -71,8 +71,16 @@ end
 png.save("out.png")
 
 # Use vector export
-vector_struct = barcode.to_vector
-# See manual: https://zint.org.uk/manual/chapter/5#buffering-symbols-in-memory-vector
+vec = Zint::Qr.new(value: "Test").to_vector
+png = ChunkyPNG::Image.new(vec.width.to_i, vec.height.to_i, ChunkyPNG::Color::WHITE)
+vec.each_rectangle do |rec|
+  png.rect(rec.x.to_i, rec.y.to_i,
+      rec.x.to_i+rec.width.to_i-1, rec.y.to_i+rec.height.to_i-1,
+      ChunkyPNG::Color::BLACK, ChunkyPNG::Color::BLACK)
+end
+png.save("out.png")
+
+# See also manual: https://zint.org.uk/manual/chapter/5#buffering-symbols-in-memory-vector
 
 # Use file as input
 barcode = Zint::Barcode.new(input_file: "/tmp/test.txt")
@@ -99,4 +107,4 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/api-wa
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
 
 ## Credits
-The project is based on the work and ideas of Angel Pizarro's [zint](https://github.com/delagoya/zint).
+The project is based on the work and ideas of Angel Pizarro's [zint](https://github.com/delagoya/zint). I would also like to say a big thank you to [Lars Kanis](https://github.com/larskanis) for his great contributions.

data/ext/ruby-zint/extconf.rb

@@ -45,11 +45,11 @@ def libzint_usable?
   m = Module.new do
     extend FFI::Library
 
-    ffi_lib(%w[libzint.so.2.10 libzint zint])
+    ffi_lib(%w[libzint.so.2.12 libzint zint])
     attach_function(:ZBarcode_Version, [], :int32)
   end
 
-  (21000...21100) === m.ZBarcode_Version
+  (21200...21300) === m.ZBarcode_Version
 rescue LoadError
   false
 end

data/lib/zint/aus_post.rb

@@ -1,7 +1,8 @@
 module Zint
+  # Australia Post 4-State Barcode
   class AusPost < Barcode
-    def initialize(value: nil, input_file: nil, options: {})
-      super(value: value, input_file: input_file, type: Zint::BARCODE_AUSPOST, options: options)
+    def initialize(value: nil, input_file: nil, **kwargs)
+      super(value: value, input_file: input_file, symbology: Zint::BARCODE_AUSPOST, **kwargs)
     end
   end
 end

data/lib/zint/aus_redirect.rb

@@ -1,7 +1,8 @@
 module Zint
+  # Australia Post Redirection
   class AusRedirect < Barcode
-    def initialize(value: nil, input_file: nil, options: {})
-      super(value: value, input_file: input_file, type: Zint::BARCODE_AUSREDIRECT, options: options)
+    def initialize(value: nil, input_file: nil, **kwargs)
+      super(value: value, input_file: input_file, symbology: Zint::BARCODE_AUSREDIRECT, **kwargs)
     end
   end
 end

data/lib/zint/aus_reply.rb

@@ -1,7 +1,8 @@
 module Zint
+  # Australia Post Reply Paid
   class AusReply < Barcode
-    def initialize(value: nil, input_file: nil, options: {})
-      super(value: value, input_file: input_file, type: Zint::BARCODE_AUSREPLY, options: options)
+    def initialize(value: nil, input_file: nil, **kwargs)
+      super(value: value, input_file: input_file, symbology: Zint::BARCODE_AUSREPLY, **kwargs)
     end
   end
 end

data/lib/zint/aus_route.rb

@@ -1,7 +1,8 @@
 module Zint
+  # Australia Post Routing
   class AusRoute < Barcode
-    def initialize(value: nil, input_file: nil, options: {})
-      super(value: value, input_file: input_file, type: Zint::BARCODE_AUSROUTE, options: options)
+    def initialize(value: nil, input_file: nil, **kwargs)
+      super(value: value, input_file: input_file, symbology: Zint::BARCODE_AUSROUTE, **kwargs)
     end
   end
 end

data/lib/zint/azrune.rb

@@ -1,7 +1,8 @@
 module Zint
+  # Aztec Runes
   class Azrune < Barcode
-    def initialize(value: nil, input_file: nil, options: {})
-      super(value: value, input_file: input_file, type: Zint::BARCODE_AZRUNE, options: options)
+    def initialize(value: nil, input_file: nil, **kwargs)
+      super(value: value, input_file: input_file, symbology: Zint::BARCODE_AZRUNE, **kwargs)
     end
   end
 end

data/lib/zint/aztec.rb

@@ -1,7 +1,8 @@
 module Zint
+  # Aztec Code
   class Aztec < Barcode
-    def initialize(value: nil, input_file: nil, options: {})
-      super(value: value, input_file: input_file, type: Zint::BARCODE_AZTEC, options: options)
+    def initialize(value: nil, input_file: nil, **kwargs)
+      super(value: value, input_file: input_file, symbology: Zint::BARCODE_AZTEC, **kwargs)
     end
   end
 end

data/lib/zint/barcode.rb

@@ -2,11 +2,13 @@ module Zint
   # Base class to represent the barcode
   #
   # @example Create new barcode
-  #   barcode = Zint::Barcode.new(value: "Test", type: Zint::BARCODE_QRCODE, options: {option_1: 1})
+  #   barcode = Zint::Barcode.new(value: "Test", symbology: Zint::BARCODE_QRCODE, option_1: 1)
   #   barcode.to_file(path: "qr.png")
   class Barcode
     include Native
 
+    class AlreadyGenerated < Error; end
+
     # @return [String, NilClass] Content of the barcode
     attr_accessor :value
     # @return [String, NilClass] Path to input file with content of the barcode
@@ -14,15 +16,16 @@ module Zint
 
     # @param value [String, NilClass] Content of the barcode
     # @param input_file [String, NilClass] Path to input file with content of the barcode
-    # @param type [Integer] Type of barcode
-    # @param options [Hash] Specific options for Zint symbol
-    def initialize(value: nil, input_file: nil, type: Zint::BARCODE_CODE128, options: {})
+    # @param symbology [Integer] Type of barcode
+    # @param kwargs [Hash] Specific options for zint symbol (height, scale, ...)
+    def initialize(value: nil, input_file: nil, symbology: Zint::BARCODE_CODE128, **kwargs)
       raise ArgumentError, "value or input_file must be given!" if value&.empty? && input_file&.empty?
       raise ArgumentError, "input_file not found!" if input_file && !File.exist?(input_file)
 
-      @zint_symbol = create_symbol(type)
-      options.each do |key, value|
-        @zint_symbol[key] = value
+      @zint_symbol = Native.ZBarcode_Create
+      self.symbology = symbology
+      kwargs.each do |k, v|
+        send("#{k}=", v)
       end
 
       @value = value
@@ -31,9 +34,14 @@ module Zint
 
     # Exports barcode to file
     #
-    # @param path [String] Path to export file
+    # @param path [String] Path to export file.
+    #                      Contains the name of the file to output a resulting barcode symbol to.
+    #                      Must end in .png, .gif, .bmp, .emf, .eps, .pcx, .svg, .tif or .txt
     # @param rotate_angle [Integer] Rotate angle in degrees (0, 90, 180, 270)
     def to_file(path:, rotate_angle: 0)
+      unless outfile == 'out.png'
+        raise AlreadyGenerated, "to_file was already executed"
+      end
       @zint_symbol[:outfile] = path
 
       if input_file
@@ -67,6 +75,9 @@ module Zint
     # @param rotate_angle [Integer] Rotate angle in degrees (0, 90, 180, 270)
     # @return [String] Exported barcode buffer
     def to_buffer(rotate_angle: 0)
+      unless @zint_symbol[:bitmap].null?
+        raise AlreadyGenerated, "to_vector was already executed"
+      end
       @zint_symbol[:output_options] = Zint::OUT_BUFFER_INTERMEDIATE
 
       if input_file
@@ -100,6 +111,9 @@ module Zint
     # @param rotate_angle [Integer] Rotate angle in degrees (0, 90, 180, 270)
     # @return [Zint::Structs::Vector] Vector data of barcode
     def to_vector(rotate_angle: 0)
+      unless @zint_symbol[:vector].pointer.null?
+        raise AlreadyGenerated, "to_vector was already executed"
+      end
       if input_file
         call_function(:ZBarcode_Encode_File_and_Buffer_Vector, @zint_symbol, input_file, rotate_angle)
       else
@@ -113,6 +127,9 @@ module Zint
     end
 
     # Free barcode and all memory associated with it.
+    #
+    # Note: This method is dangerous insofar, that previously exported vectors (by #to_vector ) are no longer usable and any access to them will result in a segfault.
+    # It is better to not call this method and leave cleaning up to the garbage collector.
     def free
       @zint_symbol.pointer.free
     end
@@ -124,12 +141,10 @@ module Zint
       @zint_symbol[:symbology]
     end
 
-    # Sets type of barcode
+    # Sets symbol to use (see BARCODE_XXX below)
     #
     # @param type [Integer] Type of barcode
     def symbology=(type)
-      reset_symbol
-
       @zint_symbol[:symbology] = type
     end
 
@@ -138,68 +153,58 @@ module Zint
       @zint_symbol[:height]
     end
 
-    # Sets height of barcode
+    # Sets height in X-dimensions (ignored for fixed-width barcodes)
     #
     # @param height [Float] Height of barcode
     def height=(height)
-      reset_symbol
-
       @zint_symbol[:height] = height
     end
 
-    # Gets scale of barcode
+    # Gets scale factor of barcode
     def scale
       @zint_symbol[:scale]
     end
 
-    # Sets scale of barcode
+    # Sets scale factor when printing barcode
     #
     # @param scale [Float] Scale of barcode
     def scale=(scale)
-      reset_symbol
-
       @zint_symbol[:scale] = scale
     end
 
-    # Gets whitespace width of barcode
+    # Gets width in X-dimensions of whitespace to left & right of barcode
     def whitespace_width
       @zint_symbol[:whitespace_width]
     end
 
-    # Sets whitespace width of barcode
+    # Sets width in X-dimensions of whitespace to left & right of barcode
     #
-    # @param whitespace width [Integer] Whitespace width of barcode
+    # @param whitespace_width [Integer] Whitespace width of barcode
     def whitespace_width=(whitespace_width)
-      reset_symbol
-
       @zint_symbol[:whitespace_width] = whitespace_width
     end
 
-    # Gets whitespace height of barcode
+    # Gets height in X-dimensions of whitespace above & below the barcode
     def whitespace_height
       @zint_symbol[:whitespace_height]
     end
 
-    # Sets whitespace height of barcode
+    # Sets height in X-dimensions of whitespace above & below the barcode
     #
-    # @param whitespace height [Integer] Whitespace height of barcode
+    # @param whitespace_height [Integer] Whitespace height of barcode
     def whitespace_height=(whitespace_height)
-      reset_symbol
-
       @zint_symbol[:whitespace_height] = whitespace_height
     end
 
-    # Gets border width of barcode
+    # Gets size of border in X-dimensions
     def border_width
       @zint_symbol[:border_width]
     end
 
-    # Sets border width of barcode
+    # Sets size of border in X-dimensions
     #
-    # @param border width [Integer] Border width of barcode
+    # @param border_width [Integer] Border width of barcode
     def border_width=(border_width)
-      reset_symbol
-
       @zint_symbol[:border_width] = border_width
     end
 
@@ -208,46 +213,42 @@ module Zint
       @zint_symbol[:output_options]
     end
 
-    # Sets output options of barcode
+    # Set various output parameters (bind, box etc, see below) of barcode
     #
-    # @param output options [Integer] Output options of barcode
+    # @param output_options [Integer] Output options of barcode
     def output_options=(output_options)
-      reset_symbol
-
       @zint_symbol[:output_options] = output_options
     end
 
     # Gets foreground colour of barcode
     def fgcolour
-      @zint_symbol[:fgcolour]
+      @zint_symbol[:fgcolour].to_s
     end
 
-    # Sets foreground colour of barcode
+    # Sets foreground as RGB/RGBA hexadecimal string, 6 or 8 characters, NUL-terminated
     #
     # @param fgcolour [String] Foreground colour of barcode
     def fgcolour=(fgcolour)
-      reset_symbol
-
       @zint_symbol[:fgcolour] = fgcolour
     end
 
     # Gets background colour of barcode
     def bgcolour
-      @zint_symbol[:bgcolour]
+      @zint_symbol[:bgcolour].to_s
     end
 
-    # Sets background colour of barcode
+    # Sets background as RGB/RGBA hexadecimal string, 6 or 8 characters, NUL-terminated
     #
     # @param bgcolour [String] Background color of barcode
     def bgcolour=(bgcolour)
-      reset_symbol
-
       @zint_symbol[:bgcolour] = bgcolour
     end
 
-    # Gets outfile of barcode
+    # Contains the name of the file to output a resulting barcode symbol to.
+    #
+    # Must end in .png, .gif, .bmp, .emf, .eps, .pcx, .svg, .tif or .txt
     def outfile
-      @zint_symbol[:outfile]
+      @zint_symbol[:outfile].to_s
     end
 
     # Gets option 1 of barcode
@@ -255,12 +256,10 @@ module Zint
       @zint_symbol[:option_1]
     end
 
-    # Sets option 1 of barcode
+    # Sets option 1 (symbol-specific options (see "../docs/manual.txt"))
     #
     # @param option_1 [Integer] Option 1 of barcode
     def option_1=(option_1)
-      reset_symbol
-
       @zint_symbol[:option_1] = option_1
     end
 
@@ -269,12 +268,10 @@ module Zint
       @zint_symbol[:option_2]
     end
 
-    # Sets option 2 of barcode
+    # Sets option 2 (symbol-specific options) of barcode
     #
-    # @param option 2 [Integer] Option 2 of barcode
+    # @param option_2 [Integer] Option 2 of barcode
     def option_2=(option_2)
-      reset_symbol
-
       @zint_symbol[:option_2] = option_2
     end
 
@@ -283,12 +280,10 @@ module Zint
       @zint_symbol[:option_3]
     end
 
-    # Sets option 3 of barcode
+    # Sets option 3 (symbol-specific options) of barcode
     #
-    # @param option 3 [Integer] Option 3 of barcode
+    # @param option_3 [Integer] Option 3 of barcode
     def option_3=(option_3)
-      reset_symbol
-
       @zint_symbol[:option_3] = option_3
     end
 
@@ -298,12 +293,10 @@ module Zint
     end
 
     # Sets show_hrt of barcode
-    # Set to 0 to hide text.
+    # show = 1 or hide = 0 Human Readable Text. Default is show (1)
     #
     # @param show_hrt [Integer] show_hrt of barcode
     def show_hrt=(show_hrt)
-      reset_symbol
-
       @zint_symbol[:show_hrt] = show_hrt
     end
 
@@ -312,12 +305,10 @@ module Zint
       @zint_symbol[:fontsize]
     end
 
-    # Sets font size of barcode
+    # Sets font size of barcode (Unused)
     #
-    # @param font size [Integer] Font size of barcode
+    # @param fontsize [Integer] Font size of barcode
     def fontsize=(fontsize)
-      reset_symbol
-
       @zint_symbol[:fontsize] = fontsize
     end
 
@@ -326,12 +317,10 @@ module Zint
       @zint_symbol[:input_mode]
     end
 
-    # Sets input mode of barcode
+    # Sets encoding of input data (see DATA_MODE etc below). Default DATA_MODE
     #
     # @param input_mode [Integer] Input mode of barcode
     def input_mode=(input_mode)
-      reset_symbol
-
       @zint_symbol[:input_mode] = input_mode
     end
 
@@ -340,26 +329,58 @@ module Zint
       @zint_symbol[:eci]
     end
 
-    # Sets ECI of barcode
+    # Sets extended Channel Interpretation. Default 0 (none)
     #
     # @param eci [Integer] ECI of barcode
     def eci=(eci)
-      reset_symbol
-
       @zint_symbol[:eci] = eci
     end
 
-    # Gets text of barcode
+    # Gets resolution of output in dots per mm (BMP/EMF/PCX/PNG/TIF only). Default 0 (none)
+    def dpmm
+      @zint_symbol[:dpmm]
+    end
+
+    # Sets resolution of output in dots per mm (BMP/EMF/PCX/PNG/TIF only). Default 0 (none)
+    #
+    # @param dpmm [Float] Resolution of output in dots per mm
+    def dpmm=(dpmm)
+      @zint_symbol[:dpmm] = dpmm
+    end
+
+    # Gets height in X-dimensions that EAN/UPC guard bars descend. Default 5
+    def guard_descent
+      @zint_symbol[:guard_descent]
+    end
+
+    # Sets height in X-dimensions that EAN/UPC guard bars descend. Default 5
+    #
+    # @param guard_descent [Float] Height in X-dimensions that EAN/UPC guard bars descend
+    def guard_descent=(guard_descent)
+      @zint_symbol[:guard_descent] = guard_descent
+    end
+
+    # Gets structured append info. Default structapp.count 0 (none)
+    def structapp
+      @zint_symbol[:structapp]
+    end
+
+    # Sets structured append info. Default structapp.count 0 (none)
+    #
+    # @param structapp [Structs::Structapp] Structured append info
+    def structapp=(structapp)
+      @zint_symbol[:structapp] = structapp
+    end
+
+    # Human Readable Text, which usually consists of input data plus one more check digit. Uses UTF-8 formatting.
     def text
-      @zint_symbol[:text]
+      @zint_symbol[:text].to_s.force_encoding(Encoding::UTF_8)
     end
 
-    # Sets text of barcode
+    # Sets Human Readable Text (if any), UTF-8, NUL-terminated (output only) of barcode
     #
     # @param text [String] Text of barcode
     def text=(text)
-      reset_symbol
-
       @zint_symbol[:text] = text
     end
 
@@ -373,31 +394,27 @@ module Zint
       @zint_symbol[:width]
     end
 
-    # Gets primary message data for more complex symbols, with a terminating NUL, of barcode
+    # Gets primary message data for more complex symbols
     def primary
-      @zint_symbol[:primary]
+      @zint_symbol[:primary].to_s
     end
 
-    # Sets primary message of barcode
+    # Sets primary message data (MaxiCode, Composite), NUL-terminated of barcode
     #
     # @param primary [String] Primary of barcode
     def primary=(primary)
-      reset_symbol
-
       @zint_symbol[:primary] = primary
     end
 
-    # Gets encoded_data of barcode
+    # Gets encoded data of barcode
     def encoded_data
       @zint_symbol[:encoded_data]
     end
 
-    # Sets encoded_data of barcode
+    # Sets encoded data (output only). Allows for rows of 1144 modules of barcode
     #
     # @param encoded_data [String] Encoded data of barcode
     def encoded_data=(encoded_data)
-      reset_symbol
-
       @zint_symbol[:encoded_data] = encoded_data
     end
 
@@ -406,9 +423,9 @@ module Zint
       @zint_symbol[:row_height]
     end
 
-    # Gets error text of barcode
+    # Gets error message in the event that an error occurred
     def errtxt
-      @zint_symbol[:errtxt]
+      @zint_symbol[:errtxt].to_s.force_encoding(Encoding::UTF_8)
     end
 
     # Gets bitmap width of barcode
@@ -431,26 +448,22 @@ module Zint
       @zint_symbol[:dot_size]
     end
 
-    # Sets dot size of barcode
+    # Sets size of dots used in BARCODE_DOTTY_MODE
     #
-    # @param dot size [Float] Dot size of barcode
+    # @param dot_size [Float] Dot size of barcode
     def dot_size=(dot_size)
-      reset_symbol
-
       @zint_symbol[:dot_size] = dot_size
     end
 
-    # Gets debug level of barcode
+    # Gets debugging flags
     def debug
       @zint_symbol[:debug]
     end
 
-    # Sets debug level of barcode
+    # Sets debugging flags
     #
     # @param debug [Integer] Debug level of barcode
     def debug=(debug)
-      reset_symbol
-
       @zint_symbol[:debug] = debug
     end
 
@@ -459,12 +472,10 @@ module Zint
       @zint_symbol[:warn_level]
     end
 
-    # Sets warn level of barcode
+    # Sets warn level (affects error/warning value returned by Zint API (see WARN_XXX below)) of barcode
     #
     # @param warn_level [Integer] Warn level of barcode
     def warn_level=(warn_level)
-      reset_symbol
-
       @zint_symbol[:warn_level] = warn_level
     end
 
@@ -483,12 +494,5 @@ module Zint
 
       error_code
     end
-
-    def create_symbol(type)
-      symbol = Native.ZBarcode_Create
-      symbol[:symbology] = type
-
-      symbol
-    end
   end
 end

data/lib/zint/bc_412.rb

@@ -0,0 +1,8 @@
+module Zint
+  # IBM BC412 (SEMI T1-95)
+  class Bc412 < Barcode
+    def initialize(value: nil, input_file: nil, **kwargs)
+      super(value: value, input_file: input_file, symbology: Zint::BARCODE_BC412, **kwargs)
+    end
+  end
+end

data/lib/zint/c25iata.rb

@@ -1,7 +1,8 @@
 module Zint
+  # 2 of 5 IATA
   class C25iata < Barcode
-    def initialize(value: nil, input_file: nil, options: {})
-      super(value: value, input_file: input_file, type: Zint::BARCODE_C25IATA, options: options)
+    def initialize(value: nil, input_file: nil, **kwargs)
+      super(value: value, input_file: input_file, symbology: Zint::BARCODE_C25IATA, **kwargs)
     end
   end
 end

data/lib/zint/c25ind.rb

@@ -1,7 +1,8 @@
 module Zint
+  #  2 of 5 Industrial
   class C25ind < Barcode
-    def initialize(value: nil, input_file: nil, options: {})
-      super(value: value, input_file: input_file, type: Zint::BARCODE_C25IND, options: options)
+    def initialize(value: nil, input_file: nil, **kwargs)
+      super(value: value, input_file: input_file, symbology: Zint::BARCODE_C25IND, **kwargs)
     end
   end
 end