zxing_ffi 0.1.0

data/lib/zxing_ffi/config.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module ZXingFFI
+  # Global configuration. Per-call options override these values.
+  #
+  # Config is read at call time: do not mutate it while a scan is running.
+  #
+  # @example
+  #   ZXingFFI.configure do |c|
+  #     c.max_pixels = 32_000_000
+  #     c.pdf_loaders = %i[poppler]
+  #   end
+  class Config
+    # Default executable names for external tools. +magick: nil+ means auto-detect
+    # (+magick+ for ImageMagick 7, +convert+/+identify+ for ImageMagick 6).
+    DEFAULT_TOOL_PATHS = {
+      pdftoppm: "pdftoppm",
+      pdfinfo: "pdfinfo",
+      pdfimages: "pdfimages",
+      magick: nil
+    }.freeze
+
+    # @return [String, nil] explicit path to libZXing (defaults to ENV["ZXING_LIB"])
+    attr_accessor :library_path
+    # @return [Array<Symbol>] PDF loaders in order of preference
+    attr_accessor :pdf_loaders
+    # @return [Array<Symbol>] raster loaders in order of preference
+    attr_accessor :image_loaders
+    # @return [Array<Symbol>] transformers (resize/rotate) in order of preference
+    attr_accessor :transformers
+    # @return [Integer] render DPI for born-digital PDF pages
+    attr_accessor :default_dpi
+    # @return [Integer] upper bound for any render DPI
+    attr_accessor :max_dpi
+    # @return [Integer] maximum pixels per bitmap
+    attr_accessor :max_pixels
+    # @return [Integer, nil] maximum number of pages per document (nil = unlimited)
+    attr_accessor :max_pages
+    # @return [Numeric] seconds allowed per page render
+    attr_accessor :render_timeout
+    # @return [Integer] address-space limit in bytes for subprocesses (Linux only)
+    attr_accessor :subprocess_memory_limit
+    # @return [Hash{Symbol => String, nil}] executable names/paths for external tools
+    attr_accessor :tool_paths
+    # @return [Boolean] block libvips "untrusted" loaders when the installed libvips supports it
+    attr_accessor :vips_block_untrusted
+
+    def initialize
+      @library_path = ENV["ZXING_LIB"]
+      @pdf_loaders = %i[poppler vips]
+      @image_loaders = %i[vips image_magick pnm]
+      @transformers = %i[vips image_magick]
+      @default_dpi = 300
+      @max_dpi = 600
+      @max_pixels = 64_000_000
+      @max_pages = nil
+      @render_timeout = 60
+      @subprocess_memory_limit = 2 * 1024**3
+      @tool_paths = DEFAULT_TOOL_PATHS.dup
+      @vips_block_untrusted = true
+    end
+
+    # Executable configured for +tool+, falling back to the default name.
+    # @param tool [Symbol] e.g. +:pdftoppm+
+    # @return [String, nil]
+    def tool_path(tool)
+      tool_paths.fetch(tool) { DEFAULT_TOOL_PATHS[tool] }
+    end
+
+    # A copy of this config with some attributes replaced. Unknown keys raise ArgumentError.
+    # @return [Config]
+    def with(**overrides)
+      copy = dup
+      copy.tool_paths = tool_paths.dup
+      overrides.each do |key, value|
+        raise ArgumentError, "unknown config key: #{key.inspect}" unless respond_to?(:"#{key}=")
+        copy.public_send(:"#{key}=", value)
+      end
+      copy
+    end
+
+    # @return [Hash]
+    def to_h
+      {
+        library_path: library_path,
+        pdf_loaders: pdf_loaders,
+        image_loaders: image_loaders,
+        transformers: transformers,
+        default_dpi: default_dpi,
+        max_dpi: max_dpi,
+        max_pixels: max_pixels,
+        max_pages: max_pages,
+        render_timeout: render_timeout,
+        subprocess_memory_limit: subprocess_memory_limit,
+        tool_paths: tool_paths,
+        vips_block_untrusted: vips_block_untrusted
+      }
+    end
+  end
+
+  class << self
+    # @return [Config] the global configuration
+    def config
+      @config ||= Config.new
+    end
+
+    # Yields the global configuration for modification.
+    # @yieldparam config [Config]
+    def configure
+      yield config
+      config
+    end
+
+    # Restores the default configuration (mainly for tests).
+    def reset_config!
+      @config = Config.new
+    end
+  end
+end

data/lib/zxing_ffi/dedupe.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module ZXingFFI
+  # Removes barcodes reported more than once for the same page, e.g. by several passes.
+  #
+  # Two barcodes are duplicates when they have the same +format+, the same +bytes+, and either
+  # - quad centers (in base-image coordinates) at most +max(10 px, 0.25 × s)+ apart, where +s+ is the size of the
+  #   smaller quad — a quad's size is its shorter side, except for degenerate quads whose shorter side is under 10%
+  #   of the longer one (linear codes located on a single scan line): their size is the longer side; or
+  # - the center of one lies inside the other's quad. This catches partial reads of wide symbols: a PDF417
+  #   cut by a tile boundary in the tiles pass can still decode, but its quad covers only part of the symbol.
+  # Identical content at different, non-overlapping positions is not a duplicate: repeated labels are legitimate.
+  #
+  # Barcodes are duck-typed: anything with +#format+, +#bytes+ and a {Geometry::Quad} +#position+ works.
+  module Dedupe
+    # Center distance in pixels within which equal barcodes are always duplicates.
+    MIN_DISTANCE = 10
+    # Center distance, as a fraction of the smaller quad's size, within which equal barcodes are duplicates.
+    RELATIVE_DISTANCE = 0.25
+    # A quad whose shorter side is below this fraction of its longer side is degenerate.
+    DEGENERATE_RATIO = 0.1
+
+    class << self
+      # Drops duplicates, keeping the first occurrence of each barcode and the order of the input.
+      #
+      # Each barcode is compared only with the barcodes kept so far that have the same format and bytes.
+      #
+      # @param barcodes [Enumerable<Barcode>] in pass order (earliest pass first)
+      # @return [Array<Barcode>] a new Array
+      def call(barcodes)
+        kept = Hash.new { |groups, key| groups[key] = [] }
+        barcodes.select do |barcode|
+          group = kept[key(barcode)]
+          next false if group.any? { |other| near?(other.position, barcode.position) }
+
+          group << barcode
+          true
+        end
+      end
+
+      # @param a [Barcode]
+      # @param b [Barcode]
+      # @return [Boolean] whether +a+ and +b+ are the same symbol reported twice (symmetric)
+      def duplicate?(a, b)
+        key(a) == key(b) && near?(a.position, b.position)
+      end
+
+      private
+
+      def key(barcode)
+        bytes = barcode.bytes
+        [barcode.format, bytes.is_a?(String) ? bytes.b : bytes]
+      end
+
+      def near?(quad, other)
+        quad.center.distance_to(other.center) <= [MIN_DISTANCE, RELATIVE_DISTANCE * [size(quad), size(other)].min].max ||
+          inside?(quad.center, other) || inside?(other.center, quad)
+      end
+
+      # Whether +point+ lies inside +quad+ (edges included). Symbol quads are convex, so the point must be on the
+      # same side of all four edges. Degenerate quads (linear codes found on a single scan line) contain nothing.
+      def inside?(point, quad)
+        return false if quad.area < 1
+
+        corners = quad.points
+        sides = corners.each_with_index.map do |corner, i|
+          following = corners[(i + 1) % corners.size]
+          (following.x - corner.x) * (point.y - corner.y) - (following.y - corner.y) * (point.x - corner.x)
+        end
+        sides.all? { |side| side >= 0 } || sides.all? { |side| side <= 0 }
+      end
+
+      def size(quad)
+        shorter, longer = quad.side_lengths.minmax
+        (shorter < DEGENERATE_RATIO * longer) ? longer : shorter
+      end
+    end
+  end
+end

data/lib/zxing_ffi/diagnostics.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module ZXingFFI
+  # Builds the environment report behind {ZXingFFI.diagnostics}. Never raises for a missing
+  # library or tool: problems are reported in the Hash instead.
+  module Diagnostics
+    class << self
+      # @return [Hash]
+      def collect
+        {
+          gem_version: VERSION,
+          ruby: {engine: RUBY_ENGINE, version: RUBY_VERSION, platform: RUBY_PLATFORM},
+          library: library,
+          defaults: defaults,
+          loaders: loaders,
+          transformers: transformers,
+          config: ZXingFFI.config.to_h
+        }
+      end
+
+      # @return [Hash] +{loaded:, path:, source:, version:, optional_symbols:, formats:}+ or +{loaded: false, error:}+;
+      #   +source+ is where discovery found the library (see {LibraryLoader::Found#source}), e.g. +:bundled+
+      def library
+        found = Native.load!
+        {
+          loaded: true,
+          path: found.path,
+          source: found.source,
+          version: found.version,
+          optional_symbols: Native.optional_features,
+          formats: Formats.readable
+        }
+      rescue Error => e
+        {loaded: false, error: "#{e.class.name.split("::").last}: #{e.message}"}
+      end
+
+      # @return [Hash] +{library:, gem:}+ reader defaults
+      def defaults
+        library_defaults =
+          begin
+            LIBRARY_DEFAULTS
+          rescue Error => e
+            {error: e.message.lines.first.strip}
+          end
+        {library: library_defaults, gem: Reader::GEM_DEFAULTS}
+      end
+
+      # Availability, version and supported kinds of each loader.
+      # @return [Hash{Symbol => Hash}]
+      def loaders
+        Loaders::NAMES.keys.to_h { |name| [name, component(Loaders, name)] }
+      end
+
+      # Availability and version of each transformer.
+      # @return [Hash{Symbol => Hash}]
+      def transformers
+        Transformers::NAMES.keys.to_h { |name| [name, component(Transformers, name)] }
+      end
+
+      private
+
+      def component(namespace, name)
+        namespace.fetch(name).diagnostics
+      rescue StandardError, ScriptError => e
+        {available: false, reason: "#{e.class}: #{e.message}"}
+      end
+    end
+  end
+end

data/lib/zxing_ffi/dpi.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module ZXingFFI
+  # DPI selection and pixel-cap math for PDF pages. Pure functions.
+  module Dpi
+    # PDF user-space units per inch.
+    POINTS_PER_INCH = 72.0
+
+    # Native resolutions used by +dpi: :auto+ are clamped to this range.
+    AUTO_RANGE = (150..600)
+
+    # Smallest render resolution used for absurdly large declared pages (see {max_dpi_for}).
+    MIN_FRACTIONAL_DPI = 0.01
+
+    # @!attribute dpi [Integer, Float] DPI to render at (a Float only for pages too large for 1 DPI)
+    # @!attribute requested [Integer, Symbol] what the caller asked for
+    # @!attribute source [Symbol] +:explicit+, +:native+ (scanned page) or +:default+
+    # @!attribute capped [Boolean] lowered to respect max_pixels
+    Choice = Data.define(:dpi, :requested, :source, :capped)
+
+    class << self
+      # Chooses the render DPI for a page.
+      #
+      # @param requested [Integer, :auto, nil] +:auto+/nil: the scan's native ppi clamped to 150..600 (and max_dpi)
+      #   for scanned pages, else +default_dpi+; Integers are honored subject to the pixel cap
+      # @param width_pt [Numeric] displayed page width in points
+      # @param height_pt [Numeric] displayed page height in points
+      # @param native_ppi [Numeric, nil]
+      # @return [Choice]
+      # @raise [LimitExceeded] when even {MIN_FRACTIONAL_DPI} would exceed max_pixels
+      def choose(requested:, width_pt:, height_pt:, native_ppi: nil, default_dpi: 300, max_dpi: 600, max_pixels: 64_000_000)
+        check_size!(width_pt, height_pt)
+        dpi, source =
+          case requested
+          when :auto, nil
+            if native_ppi&.positive?
+              [native_ppi.round.clamp([AUTO_RANGE.min, max_dpi].min, [AUTO_RANGE.max, max_dpi].min), :native]
+            else
+              [[default_dpi, max_dpi].min, :default]
+            end
+          when Integer
+            raise ArgumentError, "dpi must be positive, got #{requested}" unless requested.positive?
+
+            [requested, :explicit]
+          else
+            raise ArgumentError, "dpi must be an Integer or :auto, got #{requested.inspect}"
+          end
+
+        capped = false
+        if max_pixels && pixels(width_pt, height_pt, dpi) > max_pixels
+          dpi = max_dpi_for(width_pt, height_pt, max_pixels)
+          capped = true
+        end
+        Choice.new(dpi: dpi, requested: requested || :auto, source: source, capped: capped)
+      end
+
+      # Highest DPI whose render stays within +max_pixels+: an Integer, or — for absurdly large declared pages where
+      # even 1 DPI is too much — a Float with three decimals (Poppler and libvips accept fractional resolutions).
+      # @raise [LimitExceeded] when not even {MIN_FRACTIONAL_DPI} fits
+      def max_dpi_for(width_pt, height_pt, max_pixels)
+        check_size!(width_pt, height_pt)
+        exact = POINTS_PER_INCH * Math.sqrt(max_pixels.to_f / (width_pt * height_pt))
+        dpi = exact.floor
+        dpi -= 1 while dpi.positive? && pixels(width_pt, height_pt, dpi) > max_pixels
+        return dpi if dpi >= 1
+
+        dpi = exact.floor(3)
+        dpi = (dpi - 0.001).round(3) while dpi >= MIN_FRACTIONAL_DPI && pixels(width_pt, height_pt, dpi) > max_pixels
+        return dpi if dpi >= MIN_FRACTIONAL_DPI
+
+        raise LimitExceeded.new("page of #{width_pt}x#{height_pt} pt exceeds max_pixels #{max_pixels} even at #{MIN_FRACTIONAL_DPI} DPI",
+          limit: :max_pixels, value: pixels(width_pt, height_pt, MIN_FRACTIONAL_DPI))
+      end
+
+      # @raise [ArgumentError] unless both sides are finite and positive
+      def check_size!(width_pt, height_pt)
+        return if [width_pt, height_pt].all? { |side| side.is_a?(Numeric) && side.finite? && side.positive? }
+
+        raise ArgumentError, "page size must be finite and positive, got #{width_pt} x #{height_pt}"
+      end
+
+      # Pixel dimensions of a page rendered at +dpi+ (rounded up, like Poppler).
+      # @return [Array(Integer, Integer)]
+      def dimensions(width_pt, height_pt, dpi)
+        [(width_pt * dpi / POINTS_PER_INCH).ceil, (height_pt * dpi / POINTS_PER_INCH).ceil]
+      end
+
+      # @return [Integer] expected pixel count at +dpi+
+      def pixels(width_pt, height_pt, dpi)
+        w, h = dimensions(width_pt, height_pt, dpi)
+        w * h
+      end
+
+      # DPI for the high-resolution pass: 2× the base, within max_dpi and the pixel cap.
+      # @return [Integer, nil] nil when that would not exceed the base DPI
+      def high_res(base_dpi, width_pt:, height_pt:, max_dpi: 600, max_pixels: 64_000_000)
+        dpi = [base_dpi * 2, max_dpi].min
+        dpi = [dpi, max_dpi_for(width_pt, height_pt, max_pixels)].min if max_pixels
+        (dpi > base_dpi) ? dpi : nil
+      end
+    end
+  end
+end

data/lib/zxing_ffi/errors.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module ZXingFFI
+  # Base class for every error raised by this gem.
+  class Error < StandardError; end
+
+  # No usable libZXing could be found. The message lists every path that was tried.
+  class LibraryNotFound < Error; end
+
+  # A libZXing was found but its version or symbols are not supported.
+  class IncompatibleLibrary < Error
+    # @return [String, nil] the version reported by the library, if any
+    attr_reader :version
+
+    def initialize(message = nil, version: nil)
+      @version = version
+      super(message)
+    end
+  end
+
+  # An optional native feature is missing (e.g. +try_denoise+ without ZXING_EXPERIMENTAL_API).
+  class NotSupported < Error; end
+
+  # No loader (or transformer) able to handle the input is installed.
+  class LoaderUnavailable < Error; end
+
+  # The input is not a recognised image or PDF.
+  class UnsupportedInput < Error; end
+
+  # The PDF is encrypted and no password was given.
+  class PasswordRequired < Error; end
+
+  # The PDF is encrypted and the given password was rejected.
+  class IncorrectPassword < PasswordRequired; end
+
+  # An external renderer or in-process loader failed.
+  class RenderError < Error
+    # @return [String, nil] (truncated) stderr of the failed subprocess
+    attr_reader :stderr
+    # @return [Integer, nil] exit status of the failed subprocess
+    attr_reader :exit_status
+
+    def initialize(message = nil, stderr: nil, exit_status: nil)
+      @stderr = stderr
+      @exit_status = exit_status
+      super(message)
+    end
+  end
+
+  # A subprocess or page exceeded its time budget.
+  class TimeoutError < Error; end
+
+  # A resource limit (pixels, pages, output size, ...) was exceeded.
+  class LimitExceeded < Error
+    # @return [Symbol, nil] name of the limit, e.g. +:max_pixels+
+    attr_reader :limit
+    # @return [Numeric, nil] the offending value
+    attr_reader :value
+
+    def initialize(message = nil, limit: nil, value: nil)
+      @limit = limit
+      @value = value
+      super(message)
+    end
+  end
+
+  # ZXing_ReadBarcodes returned NULL.
+  class DecodeError < Error; end
+end

data/lib/zxing_ffi/formats.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+module ZXingFFI
+  # Runtime map between ZXing_BarcodeFormat values and Ruby symbols.
+  #
+  # Values are never hardcoded: the table is built from +ZXing_BarcodeFormatsList+ and
+  # +ZXing_BarcodeFormatToString+ when first needed. Symbols derive from the library's human-readable
+  # names ("EAN-13" → +:ean_13+, "QR Code" → +:qr_code+).
+  module Formats
+    # Library names of meta-formats (sets of formats), resolved at runtime; absent ones are skipped.
+    META_NAMES = %w[All AllReadable AllCreatable AllLinear AllMatrix AllGS1 AllRetail AllIndustrial].freeze
+
+    # One concrete format.
+    # @!attribute value [Integer] ZXing_BarcodeFormat value
+    # @!attribute symbol [Symbol] e.g. +:ean_13+
+    # @!attribute name [String] library name, e.g. "EAN-13"
+    # @!attribute symbology [Integer] value of the symbology family (e.g. EAN/UPC for EAN-13)
+    Info = Data.define(:value, :symbol, :name, :symbology)
+
+    # Immutable lookup tables built from the loaded library.
+    Table = Data.define(:by_value, :by_symbol, :meta, :readable, :linear, :invalid) do
+      # @return [Info, nil]
+      def info(value) = by_value[value]
+    end
+
+    @mutex = Mutex.new
+    @table = nil
+
+    class << self
+      # Normalizes a library name to our symbol: downcase, non-alphanumerics to "_", squeeze.
+      # @param name [String]
+      # @return [Symbol]
+      def normalize(name)
+        name.to_s.downcase.gsub(/[^a-z0-9]+/, "_").gsub(/\A_+|_+\z/, "").to_sym
+      end
+
+      # @return [Array<Symbol>] every readable concrete format
+      def readable
+        table.readable
+      end
+
+      # @return [Array<Symbol>] readable linear (1D) formats, from the library's AllLinear meta-format
+      def linear
+        table.linear
+      end
+
+      # @return [Array<Symbol>] every concrete format known to the library, readable or not
+      def all
+        table.by_symbol.keys
+      end
+
+      # @return [Hash{Symbol => Integer}] meta-formats (+:all+, +:all_readable+, +:all_linear+, …)
+      def meta
+        table.meta
+      end
+
+      # @return [Symbol] our symbol for a library value (+:unknown+ when the library has no name for it)
+      def symbol_for(value)
+        info_for(value).symbol
+      end
+
+      # @return [String] the library's human-readable name for a value
+      def name_for(value)
+        info_for(value).name
+      end
+
+      # @return [Integer] library value of a concrete or meta format symbol
+      # @raise [ArgumentError] for unknown formats
+      def value_for(format)
+        return meta.fetch(:all_readable) if all?(format)
+
+        values = resolve(format)
+        raise ArgumentError, "#{format.inspect} is not a single format" unless values&.size == 1
+
+        values.first
+      end
+
+      # Converts a +formats:+ option into library values for ReaderOptions_setFormats.
+      #
+      # Accepts symbols (+:qr_code+, +:all+, +:all_linear+), the library's own strings ("QR Code", "EAN-13",
+      # "QRCode", "]Q1"), comma/pipe-separated strings, and arrays of those. +:all+ maps to AllReadable.
+      #
+      # @return [Array<Integer>, nil] nil for +:all+/+nil+ (keep the library default: every format)
+      # @raise [ArgumentError] when a name is not a known format
+      def resolve(formats)
+        return nil if formats.nil? || all?(formats)
+
+        items = Array(formats).flat_map { |f| f.is_a?(String) ? f.split(/[,|]/).map(&:strip).reject(&:empty?) : [f] }
+        raise ArgumentError, "formats must not be empty" if items.empty?
+        return nil if items.any? { |f| all?(f) }
+
+        items.map { |item| resolve_one(item) }.uniq
+      end
+
+      # Concrete readable format symbols covered by a +formats:+ option (e.g. +:ean_upc+ → +[:ean_13, :ean_8, …]+).
+      # @return [Array<Symbol>]
+      def expand(formats)
+        values = resolve(formats)
+        return readable if values.nil?
+
+        readable_set = readable
+        covered = values.flat_map do |value|
+          Native.take_formats { |count| Native.ZXing_BarcodeFormatsList(value, count) } || []
+        end
+        covered.map { |v| symbol_for(v) }.uniq.select { |s| readable_set.include?(s) }
+      end
+
+      # The subset of +formats+ that is linear, for the rotated pass.
+      # @return [Array<Symbol>] empty when the selection contains no linear format
+      def linear_subset(formats)
+        expand(formats) & linear
+      end
+
+      # The lookup tables (built on first use; requires the native library).
+      # @return [Table]
+      def table
+        @table || @mutex.synchronize { @table ||= build_table }
+      end
+
+      private
+
+      def all?(format)
+        (format.is_a?(Symbol) || format.is_a?(String)) && format.to_s.strip.casecmp?("all")
+      end
+
+      def info_for(value)
+        table.info(value) || unknown_info(value)
+      end
+
+      def unknown_info(value)
+        name = Native.take_string(Native.ZXing_BarcodeFormatToString(value)) || "Unknown"
+        Info.new(value: value, symbol: normalize(name), name: name, symbology: value)
+      end
+
+      def resolve_one(item)
+        case item
+        when Symbol
+          lookup_symbol(item) || library_value(item.to_s) || unknown_format!(item)
+        when String
+          lookup_symbol(normalize(item)) || library_value(item) || unknown_format!(item)
+        when Integer
+          return item if table.by_value.key?(item) || table.meta.value?(item)
+
+          unknown_format!(item)
+        else
+          raise ArgumentError, "formats must be symbols or strings, got #{item.inspect}"
+        end
+      end
+
+      def lookup_symbol(symbol)
+        table.by_symbol[symbol]&.value || table.meta[symbol]
+      end
+
+      # The library's own parser also accepts "QRCode", "qrcode", "]Q1", "EAN/UPC", …
+      def library_value(string)
+        value = Native.ZXing_BarcodeFormatFromString(string)
+        Native.last_error_message # clear the thread-local error set on failure
+        (value == table.invalid) ? nil : value
+      end
+
+      def unknown_format!(item)
+        raise ArgumentError, "unknown barcode format #{item.inspect}. Valid formats: #{readable.join(", ")}; " \
+          "meta-formats: #{meta.keys.join(", ")}"
+      end
+
+      def build_table
+        Native.load!
+        # A name that cannot parse yields ZXing_BarcodeFormat_Invalid, whose value we learn instead of hardcoding it.
+        invalid = Native.ZXing_BarcodeFormatFromString("\u0001not-a-barcode-format")
+        Native.last_error_message
+
+        meta = META_NAMES.each_with_object({}) do |name, h|
+          value = Native.ZXing_BarcodeFormatFromString(name)
+          Native.last_error_message
+          next if value == invalid
+
+          h[normalize(Native.take_string(Native.ZXing_BarcodeFormatToString(value)) || name)] = value
+        end
+        raise IncompatibleLibrary, "libZXing lacks the All/AllReadable meta-formats" unless meta[:all] && meta[:all_readable]
+
+        by_value = list(meta[:all]).to_h do |value|
+          name = Native.take_string(Native.ZXing_BarcodeFormatToString(value))
+          [value, Info.new(value: value, symbol: normalize(name), name: name, symbology: Native.ZXing_BarcodeFormatSymbology(value))]
+        end
+        by_symbol = by_value.values.to_h { |info| [info.symbol, info] }
+        raise IncompatibleLibrary, "format names are not unique after normalization" if by_symbol.size != by_value.size
+
+        readable = list(meta[:all_readable]).map { |v| by_value.fetch(v).symbol }
+        linear = meta[:all_linear] ? list(meta[:all_linear]).map { |v| by_value.fetch(v).symbol } & readable : []
+
+        Table.new(
+          by_value: by_value.freeze,
+          by_symbol: by_symbol.freeze,
+          meta: meta.freeze,
+          readable: readable.freeze,
+          linear: linear.freeze,
+          invalid: invalid
+        )
+      end
+
+      def list(filter)
+        Native.take_formats { |count| Native.ZXing_BarcodeFormatsList(filter, count) } ||
+          raise(IncompatibleLibrary, "ZXing_BarcodeFormatsList failed: #{Native.last_error_message}")
+      end
+    end
+  end
+end