htslib 0.3.1 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e1bf158506931c62ffae1a524158de9fbb451796a68a7586cf788203f67a8cc4
-  data.tar.gz: d3289551dac8783cfa23f1f8d44e1b4be44b6dab3d6369f816491ceea653188f
+  metadata.gz: 9ed0d57a77d113e37ce3a9c8bf75ad8e35640a82eb51d7af09f39409c26a04ae
+  data.tar.gz: a5a4092321c2245fd4416ffe2b6b50014b5a6af1a40f20a4ca55a1296b96a2ff
 SHA512:
-  metadata.gz: d1c316a599c2dc08e6589f980e9dd4ae6d8d6bababbfef424f35e5c25453b667bdc48570578e88a9eba142553fffb25b49ae4de54a061f99f7cbf286988ec618
-  data.tar.gz: 8529c6a02c354419dd722abc0bd6f27ec514ffe980f4b0d7014914de11551a45c4e96b803bc77255c3b423129a8743a3c39556d9d3d44ec6c6692556485379cf
+  metadata.gz: abd2f5234927ee1ba553c40194865ccfca47e24338c0859b46c370f248d9f7e602068500d6a49bd80b8cb4a12ef3f3e78efb49ff3d30b628bc1fea519d3d3fd6
+  data.tar.gz: af733241e107742ddc702619ac8ab226daa72bdc515c9f591bb3317be1d3f6556070df8afa664066aca6b38466a84cf9c45c4b76e32c68d607ada759818f7f1c

data/TUTORIAL.md

@@ -254,6 +254,51 @@ in.close
 out.close
 ```
 
+Writing and modifying auxiliary tags
+
+```ruby
+# Reading auxiliary tags
+bam = HTS::Bam.open("input.bam")
+record = bam.first
+aux = record.aux
+
+# Read tags
+alignment_score = aux["AS"]           # Auto-detect type
+mc_cigar = aux.get_string("MC")       # Type-specific getter
+edit_distance = aux.get_int("NM")     # Type-specific getter
+
+# Writing/updating auxiliary tags
+in_bam = HTS::Bam.open("input.bam")
+out_bam = HTS::Bam.open("output.bam", "wb")
+out_bam.write_header(in_bam.header)
+
+in_bam.each do |record|
+  aux = record.aux
+  
+  # Update or add tags using type-specific methods
+  aux.update_int("AS", 100)                    # Integer tag
+  aux.update_float("ZQ", 0.95)                 # Float tag
+  aux.update_string("RG", "sample1")           # String tag
+  aux.update_array("BC", [25, 30, 28, 32])     # Array tag
+  
+  # Or use the []= operator (auto-detects type)
+  aux["NM"] = 2                                # Integer
+  aux["ZS"] = "modified"                       # String
+  aux["ZF"] = 3.14                             # Float
+  aux["ZA"] = [1, 2, 3, 4]                     # Array
+  
+  # Check if tag exists
+  if aux.key?("XS")
+    aux.delete("XS")  # Delete tag
+  end
+  
+  out_bam.write(record)
+end
+
+in_bam.close
+out_bam.close
+```
+
 Create index
 
 ```ruby

data/lib/hts/bam/auxi.rb

@@ -55,6 +55,124 @@ module HTS
         get(key)
       end
 
+      # Set auxiliary tag value (auto-detects type from value)
+      # For compatibility with HTS.cr.
+      # @param key [String] tag name (2 characters)
+      # @param value [Integer, Float, String, Array] tag value
+      def []=(key, value)
+        case value
+        when Integer
+          update_int(key, value)
+        when Float
+          update_float(key, value)
+        when String
+          update_string(key, value)
+        when Array
+          update_array(key, value)
+        else
+          raise ArgumentError, "Unsupported type: #{value.class}"
+        end
+      end
+
+      # Update or add an integer tag
+      # For compatibility with HTS.cr.
+      # @param key [String] tag name (2 characters)
+      # @param value [Integer] integer value
+      def update_int(key, value)
+        ret = LibHTS.bam_aux_update_int(@record.struct, key, value.to_i)
+        raise "Failed to update integer tag '#{key}': errno #{FFI.errno}" if ret < 0
+
+        value
+      end
+
+      # Update or add a floating-point tag
+      # For compatibility with HTS.cr.
+      # @param key [String] tag name (2 characters)
+      # @param value [Float] floating-point value
+      def update_float(key, value)
+        ret = LibHTS.bam_aux_update_float(@record.struct, key, value.to_f)
+        raise "Failed to update float tag '#{key}': errno #{FFI.errno}" if ret < 0
+
+        value
+      end
+
+      # Update or add a string tag
+      # For compatibility with HTS.cr.
+      # @param key [String] tag name (2 characters)
+      # @param value [String] string value
+      def update_string(key, value)
+        ret = LibHTS.bam_aux_update_str(@record.struct, key, -1, value.to_s)
+        raise "Failed to update string tag '#{key}': errno #{FFI.errno}" if ret < 0
+
+        value
+      end
+
+      # Update or add an array tag
+      # For compatibility with HTS.cr.
+      # @param key [String] tag name (2 characters)
+      # @param value [Array] array of integers or floats
+      # @param type [String, nil] element type ('c', 'C', 's', 'S', 'i', 'I', 'f'). Auto-detected if nil.
+      def update_array(key, value, type: nil)
+        raise ArgumentError, "Array cannot be empty" if value.empty?
+
+        # Auto-detect type if not specified
+        if type.nil?
+          if value.all? { |v| v.is_a?(Integer) }
+            # Use 'i' for signed 32-bit integers by default
+            type = "i"
+          elsif value.all? { |v| v.is_a?(Float) || v.is_a?(Integer) }
+            type = "f"
+          else
+            raise ArgumentError, "Array must contain only integers or floats"
+          end
+        end
+
+        # Convert array to appropriate C type
+        case type
+        when "c", "C", "s", "S", "i", "I"
+          # Integer types
+          ptr = FFI::MemoryPointer.new(:int32, value.size)
+          ptr.write_array_of_int32(value.map(&:to_i))
+          ret = LibHTS.bam_aux_update_array(@record.struct, key, type.ord, value.size, ptr)
+        when "f"
+          # Float type
+          ptr = FFI::MemoryPointer.new(:float, value.size)
+          ptr.write_array_of_float(value.map(&:to_f))
+          ret = LibHTS.bam_aux_update_array(@record.struct, key, type.ord, value.size, ptr)
+        else
+          raise ArgumentError, "Invalid array type: #{type}"
+        end
+
+        raise "Failed to update array tag '#{key}': errno #{FFI.errno}" if ret < 0
+
+        value
+      end
+
+      # Delete an auxiliary tag
+      # For compatibility with HTS.cr.
+      # @param key [String] tag name (2 characters)
+      # @return [Boolean] true if tag was deleted, false if tag was not found
+      def delete(key)
+        aux_ptr = LibHTS.bam_aux_get(@record.struct, key)
+        return false if aux_ptr.null?
+
+        ret = LibHTS.bam_aux_del(@record.struct, aux_ptr)
+        raise "Failed to delete tag '#{key}': errno #{FFI.errno}" if ret < 0
+
+        true
+      end
+
+      # Check if a tag exists
+      # For compatibility with HTS.cr.
+      # @param key [String] tag name (2 characters)
+      # @return [Boolean] true if tag exists
+      def key?(key)
+        aux_ptr = LibHTS.bam_aux_get(@record.struct, key)
+        !aux_ptr.null?
+      end
+
+      alias include? key?
+
       def first
         aux_ptr = first_pointer
         return nil if aux_ptr.null?

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/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/libhts/constants.rb

@@ -439,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,

data/lib/hts/tabix.rb

@@ -68,6 +68,7 @@ module HTS
     end
 
     def load_index(index_name = nil)
+      check_closed
       if index_name
         LibHTS.tbx_index_load2(@file_name, index_name)
       else
@@ -76,14 +77,17 @@ module HTS
     end
 
     def index_loaded?
+      check_closed
       !@idx.null?
     end
 
     def name2id(name)
+      check_closed
       LibHTS.tbx_name2id(@idx, name)
     end
 
     def seqnames
+      check_closed
       nseq = FFI::MemoryPointer.new(:int)
       LibHTS.tbx_seqnames(@idx, nseq).then do |pts|
         pts.read_array_of_pointer(nseq.read_int).map(&:read_string)
@@ -101,6 +105,20 @@ module HTS
       end
     end
 
+    def close
+      return if closed?
+
+      # @idx is an internal index (LibHTS::Tbx, a ManagedStruct).
+      # Do not call tbx_destroy here; the FFI finalizer will
+      # release the underlying C struct when @idx becomes unreachable.
+      @idx = nil
+      super
+    end
+
+    def closed?
+      @hts_file.nil? || @hts_file.null?
+    end
+
     private
 
     def queryi(id, start, end_, &block)
@@ -131,5 +149,9 @@ module HTS
         LibHTS.hts_itr_destroy(qiter)
       end
     end
+
+    def check_closed
+      raise IOError, "closed Tabix" if closed?
+    end
   end
 end

data/lib/hts/version.rb

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

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: htslib
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.3.2
 platform: ruby
 authors:
 - kojix2
 bindir: bin
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2025-11-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ffi
@@ -119,7 +119,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 3.6.2
 specification_version: 4
 summary: HTSlib bindings for Ruby
 test_files: []