htslib 0.4.1 → 0.5.0

data/lib/hts/faidx.rb

@@ -1,21 +1,13 @@
 # frozen_string_literal: true
 
-require_relative "../htslib"
-
-module HTS
-  module LibC
-    extend FFI::Library
-    ffi_lib FFI::Library::LIBC
-    attach_function :free, [:pointer], :void
-  end
-end
+require_relative "native"
 
 module HTS
   class Faidx
     attr_reader :file_name, :format
 
     def self.open(file_name, format: :auto, auto_build: true)
-      file = new(file_name, format:, auto_build:) # do not yield
+      file = new(file_name, format:, auto_build:)
       return file unless block_given?
 
       begin
@@ -27,10 +19,9 @@ module HTS
     end
 
     def self.build_index(file_name, fai_path = nil, gzi_path = nil)
-      case LibHTS.fai_build3(file_name, fai_path, gzi_path)
-      when 0
-      else raise HTS::Error, "Failed to build faidx index for #{file_name}"
-      end
+      return if Native::FaidxHandle.build(file_name, fai_path, gzi_path).zero?
+
+      raise HTS::Error, "Failed to build faidx index for #{file_name}"
     end
 
     def initialize(file_name, format: :auto, auto_build: true)
@@ -38,95 +29,62 @@ module HTS
 
       @file_name = file_name.freeze
       @format = resolve_format(@file_name, format)
-      @fai = load_handle(@file_name, @format, auto_build)
-
-      raise Errno::ENOENT, "Failed to open #{@file_name}" if @fai.null?
-    end
-
-    def struct
-      @fai
-    end
-
-    def close
-      return if closed?
-
-      LibHTS.fai_destroy(@fai)
-      @fai = nil
-    end
-
-    def closed?
-      @fai.nil? || @fai.null?
-    end
-
-    def size
-      check_closed
-      LibHTS.faidx_nseq(@fai)
+      @native = Native::FaidxHandle.open(@file_name, @format == :fastq ? 1 : 0, auto_build)
+    rescue Errno::ENOENT
+      raise Errno::ENOENT, "Failed to open #{@file_name}"
     end
 
+    def close = @native&.close
+    def closed? = @native.nil? || @native.closed?
+    def size = native.size
     alias length size
-
-    def names
-      check_closed
-      Array.new(length) { |i| LibHTS.faidx_iseq(@fai, i) }
-    end
+    def names = native.names
 
     def has_seq?(key)
-      check_closed
       raise ArgumentError, "Expect chrom to be String or Symbol" unless key.is_a?(String) || key.is_a?(Symbol)
 
-      key = key.to_s
-      case LibHTS.faidx_has_seq(@fai, key)
-      when 1 then true
-      when 0 then false
-      else raise HTS::Error, "Unexpected return value from faidx_has_seq"
-      end
+      native.has_seq?(key.to_s)
     end
 
     def seq_len(chrom)
-      check_closed
       raise ArgumentError, "Expect chrom to be String or Symbol" unless chrom.is_a?(String) || chrom.is_a?(Symbol)
 
       chrom = chrom.to_s
-      result = LibHTS.faidx_seq_len64(@fai, chrom)
+      result = native.seq_len(chrom)
       raise ArgumentError, "Sequence not found: #{chrom}" if result == -1
 
       result
     end
 
     def fetch_seq(name, start = nil, stop = nil)
-      check_closed
       name = name.to_s
-
       if start.nil? && stop.nil?
         len = seq_len(name)
         return "" if len.zero?
 
-        fetch_seq(name, 0, len - 1)
+        start = 0
+        stop = len - 1
       else
         validate_range!(name, start, stop)
-        rlen = FFI::MemoryPointer.new(:int64)
-        result = LibHTS.faidx_fetch_seq64(@fai, name, start, stop, rlen)
-        fetch_result(result, rlen.read_int64, "sequence", name, start, stop)
       end
+      fetch_result(native.fetch_seq(name, start, stop), "sequence", name, start, stop)
     end
 
     def fetch_qual(name, start = nil, stop = nil)
-      check_closed
+      native
       raise HTS::Error, "Quality is only available for FASTQ indexes" unless format == :fastq
 
       name = name.to_s
-
       if start.nil? && stop.nil?
         len = seq_len(name)
         return "" if len.zero?
 
-        fetch_qual(name, 0, len - 1)
+        start = 0
+        stop = len - 1
       else
         validate_range!(name, start, stop)
-        rlen = FFI::MemoryPointer.new(:int64)
-        result = LibHTS.faidx_fetch_qual64(@fai, name, start, stop, rlen)
-        fetch_result(result, rlen.read_int64, "quality", name, start, stop)
       end
+      fetch_result(native.fetch_qual(name, start, stop), "quality", name, start, stop)
     end
 
     def build_index(fai_path = nil, gzi_path = nil)
@@ -136,8 +94,10 @@ module HTS
 
     private
 
-    def check_closed
+    def native
       raise IOError, "closed Faidx" if closed?
+
+      @native
     end
 
     def validate_range!(name, start, stop)
@@ -149,34 +109,15 @@ module HTS
       raise ArgumentError, "Expect stop to be < seq_len (#{len})" if stop >= len
     end
 
-    def fetch_result(ptr, len, kind, name, start, stop)
+    def fetch_result(result, kind, name, start, stop)
+      len, string = result
       case len
       when -2 then raise ArgumentError, "Sequence not found: #{name}"
       when -1 then raise HTS::Error, "Error fetching #{kind}: #{name}:#{start}-#{stop}"
       end
+      raise HTS::Error, "Error fetching #{kind}: #{name}:#{start}-#{stop}" unless string
 
-      raise HTS::Error, "Error fetching #{kind}: #{name}:#{start}-#{stop}" if ptr.null?
-
-      begin
-        ptr.read_string_length(len)
-      ensure
-        HTS::LibC.free(ptr)
-      end
-    end
-
-    def load_handle(file_name, format, auto_build)
-      case [format, auto_build]
-      when [:fasta, true]
-        LibHTS.fai_load_format(file_name, :FAI_FASTA)
-      when [:fastq, true]
-        LibHTS.fai_load_format(file_name, :FAI_FASTQ)
-      when [:fasta, false]
-        LibHTS.fai_load3_format(file_name, nil, nil, 0, :FAI_FASTA)
-      when [:fastq, false]
-        LibHTS.fai_load3_format(file_name, nil, nil, 0, :FAI_FASTQ)
-      else
-        raise ArgumentError, "Unsupported format: #{format}"
-      end
+      string
     end
 
     def resolve_format(file_name, format)

data/lib/hts/hts.rb

@@ -3,7 +3,8 @@
 require_relative "../htslib"
 
 module HTS
-  # A base class for hts files.
+  # Shared behavior for HTS-backed file classes. Native handles remain private
+  # implementation details of the concrete classes.
   class Hts
     class << self
       private
@@ -12,10 +13,11 @@ module HTS
         define_method(name) do
           check_closed
           position = tell
-          ary = map(&name)
+          values = map(&name)
           seek(position) if position
-          ary
+          values
         end
+        alias_method "#{name}_array", name
       end
 
       def define_iterator(name)
@@ -23,9 +25,7 @@ module HTS
           check_closed
           return to_enum(__method__) unless block
 
-          each do |record|
-            block.call(record.public_send(name))
-          end
+          each { |record| block.call(record.public_send(name)) }
           self
         end
       end
@@ -35,94 +35,6 @@ module HTS
       raise TypeError, "Can't make instance of HTS abstract class"
     end
 
-    def struct
-      @hts_file
-    end
-
-    def to_ptr
-      @hts_file.to_ptr
-    end
-
-    def file_format
-      LibHTS.hts_get_format(@hts_file)[:format].to_s
-    end
-
-    def file_format_version
-      v = LibHTS.hts_get_format(@hts_file)[:version]
-      major = v[:major]
-      minor = v[:minor]
-      if minor == -1
-        major.to_s
-      else
-        "#{major}.#{minor}"
-      end
-    end
-
-    def close
-      return if closed?
-
-      LibHTS.hts_close(@hts_file)
-      @hts_file = nil
-    end
-
-    def closed?
-      @hts_file.nil? || @hts_file.null?
-    end
-
-    def fai=(fai)
-      check_closed
-      r = LibHTS.hts_set_fai_filename(@hts_file, fai)
-      raise "Failed to load fasta index: #{fai}" if r.negative?
-
-      self
-    end
-
-    def set_threads(n = nil)
-      if n.nil?
-        require "etc"
-        n = [Etc.nprocessors - 1, 1].max
-      end
-      raise TypeError unless n.is_a?(Integer)
-      raise ArgumentError, "Number of threads must be positive" if n < 1
-
-      r = LibHTS.hts_set_threads(@hts_file, n)
-      raise "Failed to set number of threads: #{threads}" if r < 0
-
-      @nthreads = n
-      self
-    end
-
-    def seek(offset)
-      if @hts_file[:is_cram] == 1
-        LibHTS.cram_seek(@hts_file[:fp][:cram], offset, IO::SEEK_SET)
-      elsif @hts_file[:is_bgzf] == 1
-        LibHTS.bgzf_seek(@hts_file[:fp][:bgzf], offset, IO::SEEK_SET)
-      else
-        LibHTS.hseek(@hts_file[:fp][:hfile], offset, IO::SEEK_SET)
-      end
-    end
-
-    def tell
-      if @hts_file[:is_cram] == 1
-        # LibHTS.cram_tell(@hts_file[:fp][:cram])
-        # warn 'cram_tell is not implemented in c htslib'
-        nil
-      elsif @hts_file[:is_bgzf] == 1
-        LibHTS.bgzf_tell(@hts_file[:fp][:bgzf])
-      else
-        LibHTS.htell(@hts_file[:fp][:hfile])
-      end
-    end
-
-    def rewind
-      raise "Cannot rewind: no start position" unless @start_position
-
-      r = seek(@start_position)
-      raise "Failed to rewind: #{r}" if r < 0
-
-      tell
-    end
-
     private
 
     def check_closed

data/lib/hts/native.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+begin
+  require "htslib_native_ext"
+rescue LoadError => e
+  raise LoadError, <<~MESSAGE
+    #{e.message}
+    ruby-htslib requires its native extension linked against HTSlib.
+    Install the HTSlib development package and reinstall the gem. If HTSlib is
+    in a non-standard prefix, use --with-htslib-dir or set HTSLIBDIR while
+    building the gem.
+  MESSAGE
+end

data/lib/hts/tabix.rb

@@ -3,6 +3,7 @@
 require_relative "../htslib"
 
 require_relative "hts"
+require_relative "native"
 
 module HTS
   class Tabix < Hts
@@ -34,14 +35,13 @@ module HTS
       @index_name = index
       @mode       = "r"
       @nthreads   = threads
-      @hts_file   = LibHTS.hts_open(@file_name, @mode)
-
-      raise Errno::ENOENT, "Failed to open #{@file_name}" if @hts_file.null?
+      @index_load_attempted = false
+      @native = Native::TabixHandle.open(@file_name)
 
       set_threads(threads) if threads
 
       # build_index(index) if build_index
-      @idx = load_index(index)
+      load_index(index) if index
     end
 
     def build_index(index_name = nil, min_shift: 0)
@@ -49,7 +49,7 @@ module HTS
 
       if index_name
         warn "Create index for #{@file_name} to #{index_name}"
-        case LibHTS.tbx_index_build2(@file_name, index_name, min_shift, LibHTS.tbx_conf_vcf)
+        case Native::TabixHandle.build(@file_name, index_name, min_shift)
         when 0 # successful
         when -1 then raise "general failure"
         when -2 then raise "compression not BGZF"
@@ -57,104 +57,149 @@ module HTS
         end
       else
         warn "Create index for #{@file_name}"
-        case LibHTS.tbx_index_build(@file_name, min_shift, LibHTS.tbx_conf_vcf)
+        case Native::TabixHandle.build(@file_name, nil, min_shift)
         when 0 # successful
         when -1 then raise "general failure"
         when -2 then raise "compression not BGZF"
         else raise "unknown error"
         end
       end
+      @index_name = index_name
+      @index_load_attempted = false
       self # for method chaining
     end
 
     def load_index(index_name = nil)
       check_closed
-      if index_name
-        LibHTS.tbx_index_load2(@file_name, index_name)
-      else
-        LibHTS.tbx_index_load3(@file_name, nil, 2)
-      end
+      @index_name = index_name
+      @index_load_attempted = true
+      @native.load_index(index_name)
     end
 
     def index_loaded?
       check_closed
-      !@idx.null?
+      @native.index_loaded?
     end
 
     def name2id(name)
       check_closed
-      LibHTS.tbx_name2id(@idx, name)
+      raise "Index file is required to call the name2id method." unless ensure_index_loaded
+
+      @native.name2id(name)
     end
 
     def seqnames
       check_closed
-      nseq = FFI::MemoryPointer.new(:int)
-      pts = LibHTS.tbx_seqnames(@idx, nseq)
-      begin
-        pts.read_array_of_pointer(nseq.read_int).map(&:read_string)
-      ensure
-        LibHTS.hts_free(pts) unless pts.null?
-      end
+      raise "Index file is required to call the seqnames method." unless ensure_index_loaded
+
+      @native.seqnames
     end
 
     def query(region, start = nil, end_ = nil, &block)
+      query_with_mode(region, start, end_, :fields, nil, &block)
+    end
+
+    # Explicit name for the legacy split-fields API.
+    def each_fields(region, start = nil, end_ = nil, &block)
+      query_with_mode(region, start, end_, :fields, nil, &block)
+    end
+
+    # Iterate raw rows, allocating one String per row and no field Array.
+    def each_line(region, start = nil, end_ = nil, &block)
+      query_with_mode(region, start, end_, :line, nil, &block)
+    end
+
+    # Extract only requested zero-based columns without materializing unused
+    # field strings. This Ruby implementation scans tab delimiters once.
+    def each_selected_fields(region, *columns, &block)
+      raise ArgumentError, "at least one column index is required" if columns.empty?
+
+      normalized = columns.map do |column|
+        index = Integer(column)
+        raise ArgumentError, "column indices must be non-negative" if index.negative?
+
+        index
+      end
+      query_with_mode(region, nil, nil, :selected, normalized, &block)
+    end
+
+    def query_with_mode(region, start, end_, mode, columns, &block)
       check_closed
-      raise "Index file is required to call the query method." unless index_loaded?
+      raise "Index file is required to call the query method." unless ensure_index_loaded
 
       if start && end_
-        queryi(name2id(region), start, end_, &block)
+        queryi(name2id(region), start, end_, mode, columns, &block)
+      elsif start.nil? && end_.nil?
+        querys(region, mode, columns, &block)
       else
-        querys(region, &block)
+        raise ArgumentError, "start and end must be specified together"
       end
     end
 
     def close
       return if closed?
 
-      @idx.close if @idx && !@idx.null?
-      @idx = nil
-      super
+      @native.close
     end
 
     def closed?
-      @hts_file.nil? || @hts_file.null?
+      @native.nil? || @native.closed?
+    end
+
+    def file_format = @native.file_format
+    def file_format_version = @native.file_format_version
+
+    def set_threads(n = nil)
+      if n.nil?
+        require "etc"
+        n = [Etc.nprocessors - 1, 1].max
+      end
+      raise TypeError unless n.is_a?(Integer)
+      raise ArgumentError, "Number of threads must be positive" if n < 1
+      raise "Failed to set number of threads: #{n}" if @native.set_threads(n).negative?
+
+      @nthreads = n
+      self
     end
 
     private
 
-    def queryi(id, start, end_, &block)
-      return to_enum(__method__, id, start, end_) unless block_given?
+    def ensure_index_loaded
+      return true if index_loaded?
+      return false if @index_load_attempted
 
-      qiter = LibHTS.tbx_itr_queryi(@idx, id, start, end_)
-      raise "Failed to query region: #{id}:#{start}-#{end_}" if qiter.null?
+      load_index(@index_name)
+    end
 
-      query_yield(qiter, &block)
+    def queryi(id, start, end_, mode = :fields, columns = nil, &block)
+      return to_enum(__method__, id, start, end_, mode, columns) unless block_given?
+
+      @native.query_interval(id, start, end_) { |line| yield_line(line, mode, columns, &block) }
       self
     end
 
-    def querys(region, &block)
-      return to_enum(__method__, region) unless block_given?
-
-      qiter = LibHTS.tbx_itr_querys(@idx, region)
-      raise "Failed to query region: #{region}" if qiter.null?
+    def querys(region, mode = :fields, columns = nil, &block)
+      return to_enum(__method__, region, mode, columns) unless block_given?
 
-      query_yield(qiter, &block)
+      @native.query_region(region) { |line| yield_line(line, mode, columns, &block) }
       self
     end
 
-    def query_yield(qiter)
-      r = LibHTS::KString.new
-      begin
-        while (slen = LibHTS.tbx_itr_next(@hts_file, @idx, qiter, r)) >= 0
-          yield r.read_string_copy.split("\t")
-        end
-        raise if slen < -1
-      ensure
-        r.free_buffer
-        LibHTS.hts_itr_destroy(qiter)
+    def yield_line(line, mode, columns)
+      case mode
+      when :line
+        yield line
+      when :selected
+        yield selected_fields(line, columns)
+      else
+        yield line.split("\t")
       end
     end
 
+    def selected_fields(line, columns)
+      HTS::Native.selected_fields(line, columns)
+    end
+
     def check_closed
       raise IOError, "closed Tabix" if closed?
     end

data/lib/hts/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module HTS
-  VERSION = "0.4.1"
+  VERSION = "0.5.0"
 end

data/lib/htslib.rb

@@ -1,60 +1,14 @@
 # frozen_string_literal: true
 
-require "ffi"
-
 require "hts/version"
+require "hts/native"
 
 module HTS
   class Error < StandardError; end
 
-  class << self
-    attr_accessor :lib_path
-
-    def search_htslib(name = nil)
-      name ||= "libhts.#{FFI::Platform::LIBSUFFIX}"
-      lib_path = if ENV["HTSLIBDIR"]
-                   File.expand_path(name, ENV["HTSLIBDIR"])
-                 else
-                   File.expand_path("../vendor/#{name}", __dir__)
-                 end
-      return lib_path if File.exist?(lib_path)
-
-      begin
-        require "pkg-config"
-        lib_dir = PKGConfig.variable("htslib", "libdir")
-        lib_path = File.expand_path(name, lib_dir)
-      rescue PackageConfig::NotFoundError
-        warn "htslib.pc was not found in the pkg-config search path."
-      end
-      return lib_path if File.exist?(lib_path)
-
-      warn "htslib shared library '#{name}' not found."
-    end
-
-    def search_htslib_windows
-      ENV["HTSLIBDIR"] ||= [
-        RubyInstaller::Runtime.msys2_installation.msys_path,
-        RubyInstaller::Runtime.msys2_installation.mingwarch
-      ].join(File::ALT_SEPARATOR)
-      path = File.expand_path("bin/hts-3.dll", ENV["HTSLIBDIR"])
-      RubyInstaller::Runtime.add_dll_directory(File.dirname(path))
-      path
-    end
-  end
-
-  self.lib_path = if Object.const_defined?(:RubyInstaller)
-                    search_htslib_windows
-                  else
-                    search_htslib
-                  end
-
-  # You can change the path of the shared library with `HTS.lib_path=`
-  # before calling the LibHTS module.
-  autoload :LibHTS, "hts/libhts"
-
-  autoload :Hts,    "hts/hts"
-  autoload :Bam,    "hts/bam"
-  autoload :Bcf,    "hts/bcf"
-  autoload :Faidx,  "hts/faidx"
-  autoload :Tabix,  "hts/tabix"
+  autoload :Hts,   "hts/hts"
+  autoload :Bam,   "hts/bam"
+  autoload :Bcf,   "hts/bcf"
+  autoload :Faidx, "hts/faidx"
+  autoload :Tabix, "hts/tabix"
 end