htslib 0.3.0 → 0.3.2

data/lib/hts/bcf/info.rb

@@ -74,6 +74,164 @@ module HTS
         get(key)
       end
 
+      # Set INFO field value with automatic type detection.
+      # @param key [String] INFO tag name
+      # @param value [Integer, Float, String, Array, true, false, nil] value to set
+      #   - Integer or Array<Integer> -> update_int
+      #   - Float or Array<Float,Integer> -> update_float
+      #   - String -> update_string
+      #   - true/false -> update_flag
+      #   - nil -> delete the INFO field
+      def []=(key, value)
+        case value
+        when nil
+          delete(key)
+        when true, false
+          update_flag(key, value)
+        when Integer
+          update_int(key, [value])
+        when Float
+          update_float(key, [value])
+        when String
+          update_string(key, value)
+        when Array
+          if value.empty?
+            raise ArgumentError, "Cannot set INFO field to empty array. Use nil to delete."
+          elsif value.all? { |v| v.is_a?(Integer) }
+            update_int(key, value)
+          elsif value.all? { |v| v.is_a?(Numeric) }
+            update_float(key, value)
+          else
+            raise ArgumentError, "INFO array must contain only integers or floats, got: #{value.map(&:class).uniq}"
+          end
+        else
+          raise ArgumentError, "Unsupported INFO value type: #{value.class}"
+        end
+      end
+
+      # Update INFO field with integer value(s).
+      # For compatibility with HTS.cr.
+      # @param key [String] INFO tag name
+      # @param values [Array<Integer>] integer values (use single-element array for scalar)
+      def update_int(key, values)
+        values = Array(values)
+        ptr = FFI::MemoryPointer.new(:int32, values.size)
+        ptr.write_array_of_int32(values)
+        ret = LibHTS.bcf_update_info(
+          @record.header.struct,
+          @record.struct,
+          key,
+          ptr,
+          values.size,
+          LibHTS::BCF_HT_INT
+        )
+        raise "Failed to update INFO int field '#{key}': #{ret}" if ret < 0
+
+        ret
+      end
+
+      # Update INFO field with float value(s).
+      # For compatibility with HTS.cr.
+      # @param key [String] INFO tag name
+      # @param values [Array<Float>] float values (use single-element array for scalar)
+      def update_float(key, values)
+        values = Array(values).map(&:to_f)
+        ptr = FFI::MemoryPointer.new(:float, values.size)
+        ptr.write_array_of_float(values)
+        ret = LibHTS.bcf_update_info(
+          @record.header.struct,
+          @record.struct,
+          key,
+          ptr,
+          values.size,
+          LibHTS::BCF_HT_REAL
+        )
+        raise "Failed to update INFO float field '#{key}': #{ret}" if ret < 0
+
+        ret
+      end
+
+      # Update INFO field with string value.
+      # For compatibility with HTS.cr.
+      # @param key [String] INFO tag name
+      # @param value [String] string value
+      def update_string(key, value)
+        ret = LibHTS.bcf_update_info(
+          @record.header.struct,
+          @record.struct,
+          key,
+          value.to_s,
+          1,
+          LibHTS::BCF_HT_STR
+        )
+        raise "Failed to update INFO string field '#{key}': #{ret}" if ret < 0
+
+        ret
+      end
+
+      # Update INFO flag field.
+      # For compatibility with HTS.cr.
+      # @param key [String] INFO tag name
+      # @param present [Boolean] true to set flag, false to remove it
+      def update_flag(key, present = true)
+        ret = if present
+                LibHTS.bcf_update_info(
+                  @record.header.struct,
+                  @record.struct,
+                  key,
+                  FFI::Pointer::NULL,
+                  1,
+                  LibHTS::BCF_HT_FLAG
+                )
+              else
+                # Remove flag by setting n=0
+                LibHTS.bcf_update_info(
+                  @record.header.struct,
+                  @record.struct,
+                  key,
+                  FFI::Pointer::NULL,
+                  0,
+                  LibHTS::BCF_HT_FLAG
+                )
+              end
+        raise "Failed to update INFO flag field '#{key}': #{ret}" if ret < 0
+
+        ret
+      end
+
+      # Delete an INFO field.
+      # @param key [String] INFO tag name
+      # @return [Boolean] true if field was deleted, false if it didn't exist
+      def delete(key)
+        # Try to get current type to check existence
+        type = get_info_type(key)
+        return false if type.nil?
+
+        # Delete by setting n=0
+        ret = LibHTS.bcf_update_info(
+          @record.header.struct,
+          @record.struct,
+          key,
+          FFI::Pointer::NULL,
+          0,
+          type
+        )
+        return false if ret < 0
+
+        true
+      end
+
+      # Check if an INFO field exists.
+      # @param key [String] INFO tag name
+      # @return [Boolean] true if the field exists
+      def key?(key)
+        # Use get() to check if value is actually present
+        # (get_info_type only checks header, not actual value)
+        !get(key).nil?
+      end
+
+      alias include? key?
+
       # FIXME: naming? room for improvement.
       def fields
         keys.map do |key|

data/lib/hts/bcf.rb

@@ -215,13 +215,20 @@ module HTS
       raise "query is only available for BCF files" unless file_format == "bcf"
       raise "Index file is required to call the query method." unless index_loaded?
 
-      if beg && end_
-        tid = header.name2id(region)
-        queryi(tid, beg, end_, copy:, &block)
-      elsif beg.nil? && end_.nil?
-        querys(region, copy:, &block)
+      case region
+      when Array
+        raise ArgumentError, "beg and end must not be specified when region is an Array" unless beg.nil? && end_.nil?
+
+        query_regions(region, copy:, &block)
       else
-        raise ArgumentError, "beg and end must be specified together"
+        if beg && end_
+          tid = header.name2id(region)
+          queryi(tid, beg, end_, copy:, &block)
+        elsif beg.nil? && end_.nil?
+          querys(region, copy:, &block)
+        else
+          raise ArgumentError, "beg and end must be specified together"
+        end
       end
     end
 
@@ -243,6 +250,14 @@ module HTS
       end
     end
 
+    def query_regions(regions, copy: false, &block)
+      if copy
+        query_regions_copy(regions, &block)
+      else
+        query_regions_reuse(regions, &block)
+      end
+    end
+
     def queryi_reuse(tid, beg, end_, &block)
       return to_enum(__method__, tid, beg, end_) unless block_given?
 
@@ -263,6 +278,15 @@ module HTS
       self
     end
 
+    def query_regions_reuse(regions, &block)
+      return to_enum(__method__, regions) unless block_given?
+
+      regions.each do |region|
+        querys_reuse(region, &block)
+      end
+      self
+    end
+
     def query_reuse_yield(qiter)
       bcf1 = LibHTS.bcf_init
       record = Record.new(header, bcf1)
@@ -299,6 +323,15 @@ module HTS
       self
     end
 
+    def query_regions_copy(regions, &block)
+      return to_enum(__method__, regions) unless block_given?
+
+      regions.each do |region|
+        querys_copy(region, &block)
+      end
+      self
+    end
+
     def query_copy_yield(qiter)
       loop do
         bcf1 = LibHTS.bcf_init

data/lib/hts/faidx/sequence.rb

@@ -4,7 +4,7 @@ module HTS
       attr_reader :name, :faidx
 
       def initialize(faidx, name)
-        raise unless faidx.has_key?(name)
+        raise ArgumentError, "Sequence not found: #{name}" unless faidx.has_key?(name)
 
         @faidx = faidx
         @name = name

data/lib/hts/faidx.rb

@@ -5,6 +5,8 @@ require_relative "faidx/sequence"
 
 module HTS
   class Faidx
+    include Enumerable
+
     attr_reader :file_name
 
     def self.open(*args, **kw)
@@ -20,12 +22,9 @@ module HTS
     end
 
     def initialize(file_name)
-      if block_given?
-        message = "HTS::Faidx.new() does not take block; Please use HTS::Faidx.open() instead"
-        raise message
-      end
+      raise ArgumentError, "HTS::Faidx.new() does not take block; Please use HTS::Faidx.open() instead" if block_given?
 
-      @file_name = file_name
+      @file_name = file_name.freeze
       @fai = case File.extname(@file_name)
              when ".fq", ".fastq"
                LibHTS.fai_load_format(@file_name, 2)
@@ -52,75 +51,102 @@ module HTS
     end
 
     def file_format
+      check_closed
       @fai[:format]
     end
 
+    # Iterate over each sequence in the index.
+    # @yield [Sequence] each sequence object
+    # @return [Enumerator] if no block given
+    def each
+      return to_enum(__method__) unless block_given?
+
+      check_closed
+      names.each { |name| yield self[name] }
+    end
+
     # the number of sequences in the index.
+    # @return [Integer] the number of sequences
     def length
+      check_closed
       LibHTS.faidx_nseq(@fai)
     end
     alias size length
 
-    # return the length of the requested chromosome.
+    # Return the list of sequence names in the index.
+    # @return [Array<String>] sequence names
     def names
+      check_closed
       Array.new(length) { |i| LibHTS.faidx_iseq(@fai, i) }
     end
 
     alias keys names
 
+    # Check if a sequence exists in the index.
+    # @param key [String, Symbol] sequence name
+    # @return [Boolean] true if the sequence exists
     def has_key?(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
+      else raise HTS::Error, "Unexpected return value from faidx_has_seq"
       end
     end
 
+    # Get a Sequence object by name or index.
+    # @param name [String, Symbol, Integer] sequence name or index
+    # @return [Sequence] the sequence object
+    # @raise [ArgumentError] if the sequence does not exist
     def [](name)
+      check_closed
       name = LibHTS.faidx_iseq(@fai, name) if name.is_a?(Integer)
       Sequence.new(self, name)
     end
 
-    # return the length of the requested chromosome.
+    # Return the length of the requested chromosome.
+    # @param chrom [String, Symbol] chromosome name
+    # @return [Integer] sequence length
+    # @raise [ArgumentError] if the sequence does not exist
     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_len(@fai, chrom)
-      result == -1 ? nil : result
+      raise ArgumentError, "Sequence not found: #{chrom}" if result == -1
+
+      result
     end
 
-    # @overload seq(name)
+    # @overload fetch_seq(name)
     #   Fetch the sequence as a String.
-    #   @param name [String] chr1:0-10
-    # @overload seq(name, start, stop)
+    #   @param name [String, Symbol] chr1:0-10
+    #   @return [String] the sequence
+    # @overload fetch_seq(name, start, stop)
     #   Fetch the sequence as a String.
-    #   @param name [String] the name of the chromosome
+    #   @param name [String, Symbol] the name of the chromosome
     #   @param start [Integer] the start position of the sequence (0-based)
     #   @param stop [Integer] the end position of the sequence (0-based)
     #   @return [String] the sequence
-
     def fetch_seq(name, start = nil, stop = nil)
+      check_closed
       name = name.to_s
       rlen = FFI::MemoryPointer.new(:int)
 
       if start.nil? && stop.nil?
         result = LibHTS.fai_fetch64(@fai, name, rlen)
       else
-        start < 0    && raise(ArgumentError, "Expect start to be >= 0")
-        stop  < 0    && raise(ArgumentError, "Expect stop to be >= 0")
-        start > stop && raise(ArgumentError, "Expect start to be <= stop")
-        stop >= seq_len(name) && raise(ArgumentError, "Expect stop to be < seq_len")
-
+        validate_range!(name, start, stop)
         result = LibHTS.faidx_fetch_seq64(@fai, name, start, stop, rlen)
       end
 
       case rlen.read_int
-      when -2 then raise "Invalid chromosome name: #{name}"
-      when -1 then raise "Error fetching sequence: #{name}:#{start}-#{stop}"
+      when -2 then raise ArgumentError, "Invalid chromosome name: #{name}"
+      when -1 then raise HTS::Error, "Error fetching sequence: #{name}:#{start}-#{stop}"
       end
 
       result
@@ -128,29 +154,57 @@ module HTS
 
     alias seq fetch_seq
 
+    # @overload fetch_qual(name)
+    #   Fetch the quality string.
+    #   @param name [String, Symbol] sequence name
+    #   @return [String] the quality string
+    # @overload fetch_qual(name, start, stop)
+    #   Fetch the quality string.
+    #   @param name [String, Symbol] the name of the chromosome
+    #   @param start [Integer] the start position of the sequence (0-based)
+    #   @param stop [Integer] the end position of the sequence (0-based)
+    #   @return [String] the quality string
     def fetch_qual(name, start = nil, stop = nil)
+      check_closed
       name = name.to_s
       rlen = FFI::MemoryPointer.new(:int)
 
       if start.nil? && stop.nil?
         result = LibHTS.fai_fetchqual64(@fai, name, rlen)
       else
-        start < 0    && raise(ArgumentError, "Expect start to be >= 0")
-        stop  < 0    && raise(ArgumentError, "Expect stop to be >= 0")
-        start > stop && raise(ArgumentError, "Expect start to be <= stop")
-        stop >= seq_len(name) && raise(ArgumentError, "Expect stop to be < seq_len")
-
+        validate_range!(name, start, stop)
         result = LibHTS.faidx_fetch_qual64(@fai, name, start, stop, rlen)
       end
 
       case rlen.read_int
-      when -2 then raise "Invalid chromosome name: #{name}"
-      when -1 then raise "Error fetching sequence: #{name}:#{start}-#{stop}"
+      when -2 then raise ArgumentError, "Invalid chromosome name: #{name}"
+      when -1 then raise HTS::Error, "Error fetching quality: #{name}:#{start}-#{stop}"
       end
 
       result
     end
 
     alias qual fetch_qual
+
+    private
+
+    def check_closed
+      raise IOError, "closed Faidx" if closed?
+    end
+
+    # Validate range parameters.
+    # @param name [String] sequence name
+    # @param start [Integer] start position (0-based)
+    # @param stop [Integer] stop position (0-based)
+    # @raise [ArgumentError] if range is invalid
+    def validate_range!(name, start, stop)
+      raise ArgumentError, "Expect start to be >= 0" if start < 0
+      raise ArgumentError, "Expect stop to be >= 0" if stop < 0
+      raise ArgumentError, "Expect start to be <= stop" if start > stop
+
+      len = seq_len(name)
+      raise ArgumentError, "Sequence not found: #{name}" if len.nil?
+      raise ArgumentError, "Expect stop to be < seq_len (#{len})" if stop >= len
+    end
   end
 end

data/lib/hts/hts.rb

@@ -13,7 +13,7 @@ module HTS
           check_closed
           position = tell
           ary = map(&name)
-          seek(position)
+          seek(position) if position
           ary
         end
       end

data/lib/hts/libhts/constants.rb

@@ -4,7 +4,6 @@ module HTS
   # Module for working with C HTSlib.
   module LibHTS
     typedef :int64, :hts_pos_t
-    typedef :pointer, :bam_plp_auto_f
 
     # kstring
 
@@ -352,6 +351,36 @@ module HTS
       end
     end
 
+    # Internal: Non-owning view of bam1_t used when the pointer is managed by HTSlib
+    # (e.g., pileup/mpileup). This struct mirrors the layout of bam1_t and MUST NOT
+    # free memory on GC. Do not expose publicly; use only for read-only access.
+    class Bam1View < FFI::Struct
+      layout \
+        :core,           Bam1Core,
+        :id,             :uint64,
+        :data,           :pointer, # uint8_t
+        :l_data,         :int,
+        :m_data,         :uint32,
+        :_mempolicy,     :uint32 # bit_fields
+    end
+
+    # Base modification structure
+    class HtsBaseMod < FFI::Struct
+      layout \
+        :modified_base,   :int,
+        :canonical_base,  :int,
+        :strand,          :int,
+        :qual,            :int
+    end
+
+    # Base modification state (opaque pointer)
+    # Use AutoPointer since the structure is opaque and we only need custom release.
+    class HtsBaseModState < FFI::AutoPointer
+      def self.release(ptr)
+        LibHTS.hts_base_mod_state_free(ptr) unless ptr.null?
+      end
+    end
+
     typedef :pointer, :bam_plp
     typedef :pointer, :bam_mplp
 
@@ -364,7 +393,7 @@ module HTS
 
     class BamPileup1 < FFI::BitStruct
       layout \
-        :b,              Bam1.ptr,
+        :b,              :pointer,
         :qpos,           :int32,
         :indel,          :int,
         :level,          :int,
@@ -410,7 +439,13 @@ module HTS
 
     FaiFormatOptions = enum(:FAI_NONE, :FAI_FASTA, :FAI_FASTQ)
 
-    class Faidx < FFI::Struct # FIXME: ManagedStruct
+    # Faidx represents a faidx_t handle which is treated as a
+    # file-level RAII object in HTS::Faidx. It is intentionally
+    # kept as a plain Struct and is destroyed explicitly via
+    # LibHTS.fai_destroy in HTS::Faidx#close. Do not convert this
+    # to ManagedStruct; that would interfere with the explicit
+    # lifetime managed by the Ruby wrapper.
+    class Faidx < FFI::Struct
       layout :bgzf,      BGZF.ptr,
              :n,         :int,
              :m,         :int,