htslib 0.3.2 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9ed0d57a77d113e37ce3a9c8bf75ad8e35640a82eb51d7af09f39409c26a04ae
-  data.tar.gz: a5a4092321c2245fd4416ffe2b6b50014b5a6af1a40f20a4ca55a1296b96a2ff
+  metadata.gz: 86838244ad390e04fb293d3db9fd639c837dcd7b2309cc0c83da0b5925e7185c
+  data.tar.gz: 547063279b934706efcf919d287217f4231fe76d2e8fb3ae6df8e4dd7b6040ad
 SHA512:
-  metadata.gz: abd2f5234927ee1ba553c40194865ccfca47e24338c0859b46c370f248d9f7e602068500d6a49bd80b8cb4a12ef3f3e78efb49ff3d30b628bc1fea519d3d3fd6
-  data.tar.gz: af733241e107742ddc702619ac8ab226daa72bdc515c9f591bb3317be1d3f6556070df8afa664066aca6b38466a84cf9c45c4b76e32c68d607ada759818f7f1c
+  metadata.gz: 787f9167abef88ddbd758d3155f1f3568bb99d8a5a340086a1cc677be46e0e77ec5a0ef56d201610f06143d0f54a20a1f2563ae3e080996564b5b5545e3e8a2a
+  data.tar.gz: d07ae5e437c9729a39e32adb12ff694560eaa33e44094679199bc8b742ccaab4c5a111c7e6391a314a8b6a19fae82acea549123b57497690678e1b2b1746f2c7

data/TUTORIAL.md

@@ -254,6 +254,23 @@ in.close
 out.close
 ```
 
+Update INFO fields
+
+```ruby
+bcf = HTS::Bcf.open("in.vcf")
+record = bcf.first
+info = record.info
+
+info.update_int("DP", [30])
+# info.update_int64("DP", [2**40])     # Backend-dependent (BCF_HT_LONG)
+info.update_float("AF", [0.25])
+info.update_string("STR", "sample")
+info.update_flag("SOMATIC", true)
+
+info["DP"] = 100
+# Out-of-int32 integers require explicit update_int64
+```
+
 Writing and modifying auxiliary tags
 
 ```ruby
@@ -277,9 +294,14 @@ in_bam.each do |record|
   
   # Update or add tags using type-specific methods
   aux.update_int("AS", 100)                    # Integer tag
+  aux.update_uint8("XI", 255)                  # Exact unsigned 8-bit integer tag
   aux.update_float("ZQ", 0.95)                 # Float tag
+  aux.update_double("ZD", 0.125)               # Double tag
+  aux.update_char("XC", "Y")                  # Character tag
+  aux.update_hex("XH", "DEADBEEF")            # Hex string tag
   aux.update_string("RG", "sample1")           # String tag
-  aux.update_array("BC", [25, 30, 28, 32])     # Array tag
+  aux.update_array("BC", [25, 30, 28, 32])     # Array tag (default subtype: i)
+  aux.update_array("BQ", [25, 30, 28, 32], type: "C") # Array tag with explicit subtype
   
   # Or use the []= operator (auto-detects type)
   aux["NM"] = 2                                # Integer

data/lib/hts/bam/auxi.rb

@@ -79,17 +79,49 @@ module HTS
       # @param key [String] tag name (2 characters)
       # @param value [Integer] integer value
       def update_int(key, value)
+        validate_tag!(key)
         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 signed 8-bit integer tag.
+      def update_int8(key, value)
+        update_exact_integer(key, value, "c", -128, 127)
+      end
+
+      # Update or add an unsigned 8-bit integer tag.
+      def update_uint8(key, value)
+        update_exact_integer(key, value, "C", 0, 255)
+      end
+
+      # Update or add a signed 16-bit integer tag.
+      def update_int16(key, value)
+        update_exact_integer(key, value, "s", -32_768, 32_767)
+      end
+
+      # Update or add an unsigned 16-bit integer tag.
+      def update_uint16(key, value)
+        update_exact_integer(key, value, "S", 0, 65_535)
+      end
+
+      # Update or add a signed 32-bit integer tag.
+      def update_int32(key, value)
+        update_exact_integer(key, value, "i", -2_147_483_648, 2_147_483_647)
+      end
+
+      # Update or add an unsigned 32-bit integer tag.
+      def update_uint32(key, value)
+        update_exact_integer(key, value, "I", 0, 4_294_967_295)
+      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)
+        validate_tag!(key)
         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
 
@@ -101,10 +133,43 @@ module HTS
       # @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)
+        validate_tag!(key)
+        string = value.to_s
+        validate_string_value!(string)
+        ret = LibHTS.bam_aux_update_str(@record.struct, key, -1, string)
         raise "Failed to update string tag '#{key}': errno #{FFI.errno}" if ret < 0
 
-        value
+        string
+      end
+
+      # Update or add a character tag.
+      def update_char(key, value)
+        validate_tag!(key)
+
+        string = value.to_s
+        validate_char_value!(string)
+
+        replace_with_append(key, "A", string.b)
+        string
+      end
+
+      # Update or add a hexadecimal string tag.
+      def update_hex(key, value)
+        validate_tag!(key)
+
+        string = value.to_s
+        validate_hex_value!(string)
+
+        replace_with_append(key, "H", string.b + "\0")
+        string
+      end
+
+      # Update or add a double-precision floating-point tag.
+      def update_double(key, value)
+        validate_tag!(key)
+
+        replace_with_append(key, "d", [Float(value)].pack("E"))
+        value.to_f
       end
 
       # Update or add an array tag
@@ -113,6 +178,7 @@ module HTS
       # @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)
+        validate_tag!(key)
         raise ArgumentError, "Array cannot be empty" if value.empty?
 
         # Auto-detect type if not specified
@@ -127,21 +193,10 @@ module HTS
           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
+        payload = pack_array_payload(value, type)
+        ptr = FFI::MemoryPointer.new(:uint8, payload.bytesize)
+        ptr.put_bytes(0, payload)
+        ret = LibHTS.bam_aux_update_array(@record.struct, key, type.ord, value.size, ptr)
 
         raise "Failed to update array tag '#{key}': errno #{FFI.errno}" if ret < 0
 
@@ -180,7 +235,7 @@ module HTS
         get_ruby_aux(aux_ptr)
       end
 
-      def each
+      def each_value
         return enum_for(__method__) unless block_given?
 
         aux_ptr = first_pointer
@@ -193,6 +248,45 @@ module HTS
         end
       end
 
+      # Iterate auxiliary tags as key-value pairs.
+      #
+      # @yieldparam tag [String] 2-byte AUX tag name
+      # @yieldparam value [Object] Ruby representation of the AUX value
+      def each
+        return enum_for(__method__) unless block_given?
+
+        aux_ptr = first_pointer
+        return nil if aux_ptr.null?
+
+        loop do
+          tag = FFI::Pointer.new(aux_ptr.address - 2).read_string(2)
+          yield tag, get_ruby_aux(aux_ptr)
+          aux_ptr = LibHTS.bam_aux_next(@record.struct, aux_ptr)
+          break if aux_ptr.null?
+        end
+      end
+
+      alias each_pair each
+
+      # Iterate auxiliary tags with their SAM/BAM type.
+      #
+      # @yieldparam tag [String] 2-byte AUX tag name
+      # @yieldparam type [String] AUX type, e.g. "i", "Z", or "B:C"
+      # @yieldparam value [Object] Ruby representation of the AUX value
+      def each_with_type
+        return enum_for(__method__) unless block_given?
+
+        aux_ptr = first_pointer
+        return nil if aux_ptr.null?
+
+        loop do
+          tag = FFI::Pointer.new(aux_ptr.address - 2).read_string(2)
+          yield tag, aux_type(aux_ptr), get_ruby_aux(aux_ptr)
+          aux_ptr = LibHTS.bam_aux_next(@record.struct, aux_ptr)
+          break if aux_ptr.null?
+        end
+      end
+
       def to_h
         h = {}
         aux_ptr = first_pointer
@@ -213,8 +307,120 @@ module HTS
         LibHTS.bam_aux_first(@record.struct)
       end
 
+      def aux_type(aux_ptr)
+        type = aux_ptr.read_string(1)
+        return type unless type == "B"
+
+        "#{type}:#{aux_ptr.read_string(2)[1]}"
+      end
+
+      def validate_tag!(key)
+        return if key.is_a?(String) && key.bytesize == 2 && key.ascii_only?
+
+        raise ArgumentError, "AUX tag must be a 2-byte ASCII String"
+      end
+
+      def validate_string_value!(string)
+        return unless string.include?("\0")
+
+        raise ArgumentError, "String AUX tags must not contain NUL bytes"
+      end
+
+      def validate_char_value!(string)
+        return if string.bytesize == 1 && string.ascii_only? && /\A[!-~]\z/.match?(string)
+
+        raise ArgumentError, "Character AUX tags must be a single printable ASCII byte"
+      end
+
+      def validate_hex_value!(string)
+        raise ArgumentError, "Hex AUX tags must contain an even number of characters" if string.bytesize.odd?
+
+        return if string.ascii_only? && /\A[0-9A-Fa-f]*\z/.match?(string)
+
+        raise ArgumentError,
+              "Hex AUX tags must contain only ASCII hexadecimal characters"
+      end
+
+      def update_exact_integer(key, value, type, min, max)
+        validate_tag!(key)
+
+        integer = Integer(value)
+        raise RangeError, "Value #{integer} is out of range for AUX type #{type}" unless integer.between?(min, max)
+
+        replace_with_append(key, type, pack_scalar_payload(integer, type))
+        integer
+      end
+
+      def replace_with_append(key, type, payload)
+        delete(key) if key?(key)
+
+        ptr = FFI::MemoryPointer.new(:uint8, payload.bytesize)
+        ptr.put_bytes(0, payload)
+        ret = LibHTS.bam_aux_append(@record.struct, key, type.ord, payload.bytesize, ptr)
+        raise "Failed to update #{type} tag '#{key}': errno #{FFI.errno}" if ret < 0
+
+        true
+      end
+
+      def pack_scalar_payload(value, type)
+        case type
+        when "c"
+          [value].pack("c")
+        when "C"
+          [value].pack("C")
+        when "s"
+          [value].pack("s<")
+        when "S"
+          [value].pack("S<")
+        when "i"
+          [value].pack("l<")
+        when "I"
+          [value].pack("L<")
+        else
+          raise ArgumentError, "Unsupported scalar AUX type: #{type}"
+        end
+      end
+
+      def pack_array_payload(value, type)
+        case type
+        when "c"
+          validate_integer_array_range!(value, -128, 127, type)
+          value.pack("c*")
+        when "C"
+          validate_integer_array_range!(value, 0, 255, type)
+          value.pack("C*")
+        when "s"
+          validate_integer_array_range!(value, -32_768, 32_767, type)
+          value.pack("s<*")
+        when "S"
+          validate_integer_array_range!(value, 0, 65_535, type)
+          value.pack("S<*")
+        when "i"
+          validate_integer_array_range!(value, -2_147_483_648, 2_147_483_647, type)
+          value.pack("l<*")
+        when "I"
+          validate_integer_array_range!(value, 0, 4_294_967_295, type)
+          value.pack("L<*")
+        when "f"
+          value.map(&:to_f).pack("e*")
+        else
+          raise ArgumentError, "Invalid array type: #{type}"
+        end
+      end
+
+      def validate_integer_array_range!(value, min, max, type)
+        value.each do |element|
+          integer = Integer(element)
+          unless integer.between?(min, max)
+            raise RangeError, "Array element #{integer} is out of range for AUX array type #{type}"
+          end
+        end
+      end
+
       def get_ruby_aux(aux_ptr, type = nil)
-        type = type ? type.to_s : aux_ptr.read_string(1)
+        actual_type = aux_ptr.read_string(1)
+        type = type ? type.to_s : actual_type
+        validate_aux_type!(actual_type, type)
 
         # A (character), B (general array),
         # f (real number), H (hexadecimal array),
@@ -246,6 +452,27 @@ module HTS
           raise NotImplementedError, "type: #{type}"
         end
       end
+
+      def validate_aux_type!(actual_type, requested_type)
+        return if aux_type_compatible?(actual_type, requested_type)
+
+        raise TypeError, "AUX type mismatch: requested #{requested_type.inspect}, actual #{actual_type.inspect}"
+      end
+
+      def aux_type_compatible?(actual_type, requested_type)
+        case requested_type
+        when "i", "I", "c", "C", "s", "S"
+          %w[i I c C s S].include?(actual_type)
+        when "f", "d"
+          %w[f d].include?(actual_type)
+        when "Z", "H"
+          %w[Z H].include?(actual_type)
+        when "A", "B"
+          actual_type == requested_type
+        else
+          true
+        end
+      end
     end
   end
 end

data/lib/hts/bam/cigar.rb

@@ -15,11 +15,19 @@ module HTS
       def self.parse(str)
         c = FFI::MemoryPointer.new(:pointer)
         m = FFI::MemoryPointer.new(:size_t)
-        LibHTS.sam_parse_cigar(str, FFI::Pointer::NULL, c, m)
-        cigar_array = c.read_pointer.read_array_of_uint32(m.read(:size_t))
+        c.write_pointer(FFI::Pointer::NULL)
+        m.write(:size_t, 0)
+        ptr = nil
+        n_cigar = LibHTS.sam_parse_cigar(str, FFI::Pointer::NULL, c, m)
+        raise "sam_parse_cigar failed: #{n_cigar}" if n_cigar.negative?
+
+        ptr = c.read_pointer
+        cigar_array = ptr.null? ? [] : ptr.read_array_of_uint32(n_cigar)
         obj = new
         obj.array = cigar_array
         obj
+      ensure
+        LibHTS.hts_free(ptr) if ptr && !ptr.null?
       end
 
       def initialize(record = nil)