htslib 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ea68a4c331c9a404cfce2bf86fea386985e96ee3b76ae25e9d9b701593294880
-  data.tar.gz: d826e59f66e20bc40bc47c2033295abe2b3aceab8cb9d5af3d4d41309e448732
+  metadata.gz: e1bf158506931c62ffae1a524158de9fbb451796a68a7586cf788203f67a8cc4
+  data.tar.gz: d3289551dac8783cfa23f1f8d44e1b4be44b6dab3d6369f816491ceea653188f
 SHA512:
-  metadata.gz: 646dca4eb44c96a67020f57a090c26715b003521c9c6afffad1becf031576c334ea03c99b61f795a35932935535c53a1899a960ab986480cb3f5eef5b9913b96
-  data.tar.gz: e1cc5d9357932e04cebae1aaa5a8dc7024e0755584ea21999b18004dba76726c10b23276ee6d98fc1580ffb5aad45aeb12fd3e1bf94cfc45fdee70aefda87f91
+  metadata.gz: d1c316a599c2dc08e6589f980e9dd4ae6d8d6bababbfef424f35e5c25453b667bdc48570578e88a9eba142553fffb25b49ae4de54a061f99f7cbf286988ec618
+  data.tar.gz: 8529c6a02c354419dd722abc0bd6f27ec514ffe980f4b0d7014914de11551a45c4e96b803bc77255c3b423129a8743a3c39556d9d3d44ec6c6692556485379cf

data/README.md

@@ -165,8 +165,6 @@ Try Crystal. [HTS.cr](https://github.com/bio-cr/hts.cr) is implemented in Crysta
 
 ## Development
 
-![Diagram](diagram.svg)
-
 #### Compile from source code
 
 [GNU Autotools](https://en.wikipedia.org/wiki/GNU_Autotools) is required to compile htslib.

data/lib/hts/bam/base_mod.rb

@@ -0,0 +1,343 @@
+# frozen_string_literal: true
+
+module HTS
+  class Bam < Hts
+    # Base modification information from MM/ML tags
+    #
+    # This class provides access to DNA/RNA base modifications such as methylation.
+    # It wraps the htslib base modification API and provides a Ruby-friendly interface.
+    #
+    # @note BaseMod is a view object that references data in a Record.
+    #   The state is maintained in hts_base_mod_state structure.
+    class BaseMod
+      include Enumerable
+
+      class NotParsedError < StandardError; end
+
+      attr_reader :record
+
+      # Individual base modification information
+      class Modification
+        attr_reader :modified_base, :canonical_base, :strand, :qual
+
+        # @param modified_base [Integer] Modification code as char or -ChEBI
+        # @param canonical_base [Integer] Canonical base (A, C, G, T, N)
+        # @param strand [Integer] 0 or 1 for +/- strand
+        # @param qual [Integer] Quality (256*probability) or -1 if unknown
+        def initialize(modified_base:, canonical_base:, strand:, qual:)
+          @modified_base = modified_base
+          @canonical_base = canonical_base
+          @strand = strand
+          @qual = qual
+        end
+
+        # Get modification code as character or ChEBI number as string
+        # @return [String] Single character code or ChEBI number as string
+        def code
+          @modified_base > 0 ? @modified_base.chr : @modified_base.to_s
+        end
+
+        # Get canonical base as character
+        # @return [String] Single character (A, C, G, T, N)
+        def canonical
+          @canonical_base.chr
+        end
+
+        # Get likelihood as a probability (0.0-1.0)
+        # @return [Float, nil] Probability or nil if qual is -1
+        def probability
+          return nil if @qual == -1
+
+          @qual / 256.0
+        end
+
+        # Convert to hash representation
+        # @return [Hash] Hash with modification information
+        def to_h
+          {
+            modified_base: @modified_base,
+            code: code,
+            canonical_base: @canonical_base,
+            canonical: canonical,
+            strand: @strand,
+            qual: @qual,
+            probability: probability
+          }
+        end
+
+        # String representation
+        # @return [String] String representation of the modification
+        def to_s
+          if @qual >= 0
+            "#{canonical}->#{code}(#{probability.round(3)})"
+          else
+            "#{canonical}->#{code}"
+          end
+        end
+
+        # Inspect string
+        # @return [String] Inspect string
+        def inspect
+          "#<HTS::Bam::BaseMod::Modification #{self}>"
+        end
+      end
+
+      # Position-specific modification information
+      class Position
+        attr_reader :position, :modifications
+
+        # @param position [Integer] Position in query sequence
+        # @param modifications [Array<Modification>] Array of modifications at this position
+        def initialize(position, modifications)
+          @position = position
+          @modifications = modifications
+        end
+
+        # Check if this position has methylation
+        # @return [Boolean] true if any modification is methylation ('m')
+        def methylated?
+          @modifications.any? { |m| m.code == "m" }
+        end
+
+        # Check if this position has hydroxymethylation
+        # @return [Boolean] true if any modification is hydroxymethylation ('h')
+        def hydroxymethylated?
+          @modifications.any? { |m| m.code == "h" }
+        end
+
+        # Convert to hash representation
+        # @return [Hash] Hash with position information
+        def to_h
+          {
+            position: @position,
+            modifications: @modifications.map(&:to_h)
+          }
+        end
+
+        # String representation
+        # @return [String] String representation
+        def to_s
+          mods_str = @modifications.map(&:to_s).join(", ")
+          "pos=#{@position} [#{mods_str}]"
+        end
+
+        # Inspect string
+        # @return [String] Inspect string
+        def inspect
+          "#<HTS::Bam::BaseMod::Position #{self}>"
+        end
+      end
+
+      # Initialize a new BaseMod object
+      # @param record [Record] The BAM record to extract modifications from
+      # @param auto_parse [Boolean] If true, parse MM/ML lazily on first access
+      def initialize(record, auto_parse: true)
+        @record = record
+        @state = LibHTS.hts_base_mod_state_alloc
+        @closed = false
+        @auto_parse = !!auto_parse
+        @parsed = false
+        raise Error, "Failed to allocate hts_base_mod_state" if @state.null?
+      end
+
+      # Explicitly free the state
+      # @return [void]
+      def close
+        return if @closed
+
+        # With HtsBaseModState as an AutoPointer, releasing the Ruby object
+        # is sufficient. Avoid manual free to prevent double-free.
+        @state = nil
+        @closed = true
+      end
+
+      # Whether this object has parsed MM/ML tags already
+      # @return [Boolean]
+      def parsed?
+        @parsed
+      end
+
+      # Ensure MM/ML have been parsed, performing lazy parse if enabled.
+      # @param flags [Integer]
+      # @return [void]
+      def ensure_parsed!(flags = 0)
+        return if @parsed
+
+        raise NotParsedError, "BaseMod is not parsed. Call #parse first (auto_parse is disabled)." unless @auto_parse
+
+        parse(flags)
+      end
+
+      # Parse MM and ML tags from the record
+      # @param flags [Integer] Parsing flags (default: 0)
+      # @return [Integer] Number of modification types found, or -1 on error
+      # @raise [Error] If parsing fails
+      def parse(flags = 0)
+        ret = LibHTS.bam_parse_basemod2(@record.struct, @state, flags)
+        raise Error, "Failed to parse base modifications" if ret < 0
+
+        @parsed = true
+        ret
+      end
+
+      # Get modification information at a specific query position
+      # @param position [Integer] Query position (0-based)
+      # @param max_mods [Integer] Maximum number of modifications to retrieve
+      # @return [Position, nil] Position object with modifications, or nil if none
+      def at_pos(position, max_mods: 10)
+        # Reset state to ensure deterministic results even after prior iteration
+        parsed? ? parse : ensure_parsed!
+
+        mods_ptr = FFI::MemoryPointer.new(LibHTS::HtsBaseMod, max_mods)
+
+        ret = LibHTS.bam_mods_at_qpos(@record.struct, position, @state,
+                                      mods_ptr, max_mods)
+        return nil if ret <= 0
+
+        build_position(position, mods_ptr, [ret, max_mods].min)
+      end
+
+      # Array-style access to modifications at a position
+      # @param position [Integer] Query position (0-based)
+      # @return [Position, nil] Position object with modifications, or nil if none
+      def [](position)
+        at_pos(position)
+      end
+
+      # Iterate over all positions with modifications
+      # @param max_mods [Integer] Maximum number of modifications per position
+      # @yield [Position] Position object for each modified position
+      # @return [Enumerator] If no block given
+      def each_position(max_mods: 10)
+        return enum_for(__method__, max_mods: max_mods) unless block_given?
+
+        # Reset state at the start of iteration to allow repeated enumerations
+        parsed? ? parse : ensure_parsed!
+
+        pos_ptr = FFI::MemoryPointer.new(:int)
+        mods_ptr = FFI::MemoryPointer.new(LibHTS::HtsBaseMod, max_mods)
+
+        loop do
+          ret = LibHTS.bam_next_basemod(@record.struct, @state,
+                                        mods_ptr, max_mods, pos_ptr)
+          break if ret <= 0
+
+          position = pos_ptr.read_int
+          yield build_position(position, mods_ptr, [ret, max_mods].min)
+        end
+      end
+
+      alias each each_position
+
+      # Get list of modification types present in this record
+      # @return [Array<Integer>] Array of modification codes (char code or -ChEBI)
+      def modification_types
+        ensure_parsed!
+
+        ntype_ptr = FFI::MemoryPointer.new(:int)
+        codes_ptr = LibHTS.bam_mods_recorded(@state, ntype_ptr)
+
+        ntype = ntype_ptr.read_int
+        return [] if ntype <= 0 || codes_ptr.null?
+
+        codes_ptr.read_array_of_int(ntype)
+      end
+
+      alias recorded_types modification_types
+
+      # Query information about a specific modification type by code
+      # @param code [Integer, String] Modification code (char code or -ChEBI, or single char string)
+      # @return [Hash, nil] Hash with canonical, strand, implicit info, or nil if not found
+      def query_type(code)
+        ensure_parsed!
+
+        code = code.ord if code.is_a?(String)
+
+        strand_ptr = FFI::MemoryPointer.new(:int)
+        implicit_ptr = FFI::MemoryPointer.new(:int)
+        canonical_ptr = FFI::MemoryPointer.new(:char, 1)
+
+        ret = LibHTS.bam_mods_query_type(@state, code, strand_ptr,
+                                         implicit_ptr, canonical_ptr)
+        return nil if ret < 0
+
+        {
+          canonical: canonical_ptr.read_char.chr,
+          strand: strand_ptr.read_int,
+          implicit: implicit_ptr.read_int != 0
+        }
+      end
+
+      # Query information about i-th modification type
+      # @param index [Integer] Modification type index (0-based)
+      # @return [Hash, nil] Hash with code, canonical, strand, implicit info
+      def query_type_at(index)
+        ensure_parsed!
+
+        strand_ptr = FFI::MemoryPointer.new(:int)
+        implicit_ptr = FFI::MemoryPointer.new(:int)
+        canonical_ptr = FFI::MemoryPointer.new(:char, 1)
+
+        ret = LibHTS.bam_mods_queryi(@state, index, strand_ptr,
+                                     implicit_ptr, canonical_ptr)
+        return nil if ret < 0
+
+        types = modification_types
+        {
+          code: types[index],
+          canonical: canonical_ptr.read_char.chr,
+          strand: strand_ptr.read_int,
+          implicit: implicit_ptr.read_int != 0
+        }
+      end
+
+      # Get all modifications as an array
+      # @return [Array<Position>] Array of all positions with modifications
+      def to_a
+        each_position.to_a
+      end
+
+      # String representation for debugging
+      # @return [String] String representation
+      def to_s
+        return "#<HTS::Bam::BaseMod (not parsed)>" unless @parsed
+
+        mods = []
+        each_position do |pos|
+          mods << pos.to_s
+        end
+        "#<HTS::Bam::BaseMod #{mods.join(' ')}>"
+      end
+
+      # Inspect string
+      # @return [String] Inspect string
+      def inspect
+        to_s
+      end
+
+      private
+
+      # Build Position object from hts_base_mod array
+      # @param position [Integer] Query position
+      # @param mods_ptr [FFI::Pointer] Pointer to array of HtsBaseMod structures
+      # @param n_mods [Integer] Number of modifications
+      # @return [Position] Position object
+      def build_position(position, mods_ptr, n_mods)
+        modifications = []
+
+        n_mods.times do |i|
+          mod_struct = LibHTS::HtsBaseMod.new(mods_ptr + i * LibHTS::HtsBaseMod.size)
+
+          modifications << Modification.new(
+            modified_base: mod_struct[:modified_base],
+            canonical_base: mod_struct[:canonical_base],
+            strand: mod_struct[:strand],
+            qual: mod_struct[:qual]
+          )
+        end
+
+        Position.new(position, modifications)
+      end
+    end
+  end
+end

data/lib/hts/bam/header.rb

@@ -111,6 +111,23 @@ module HTS
         name2tid(name)
       end
 
+      # Add a @PG (program) line to the header
+      # @param program_name [String] Name of the program
+      # @param options [Hash] Key-value pairs for @PG tags (ID, PN, VN, CL, PP, etc.)
+      # @return [Integer] 0 on success, -1 on failure
+      #
+      # This is a convenience wrapper around sam_hdr_add_pg that automatically:
+      # - Generates a unique ID if the specified one clashes
+      # - Manages PP (previous program) chains automatically
+      #
+      # @example
+      #   header.add_pg("bwa", VN: "0.7.17", CL: "bwa mem ref.fa read.fq")
+      #   header.add_pg("samtools", VN: "1.15", PP: "bwa")
+      def add_pg(program_name, **options)
+        args = options.flat_map { |k, v| [:string, k.to_s, :string, v.to_s] }
+        LibHTS.sam_hdr_add_pg(@sam_hdr, program_name, *args, :pointer, FFI::Pointer::NULL)
+      end
+
       private
 
       def name2tid(name)

data/lib/hts/bam/mpileup.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+module HTS
+  class Bam < Hts
+    # High-level mpileup iterator over multiple BAM/CRAM inputs
+    class Mpileup
+      include Enumerable
+
+      # Usage:
+      #   HTS::Bam::Mpileup.open([bam1, bam2], region: "chr1:1-100") do |mpl|
+      #     mpl.each { |cols| ... }
+      #   end
+      def self.open(*args, **kw)
+        m = new(*args, **kw)
+        return m unless block_given?
+
+        begin
+          yield m
+        ensure
+          m.close
+        end
+        m
+      end
+
+      # Normalize inputs to HTS::Bam instances
+      # Accepts array of HTS::Bam or filenames (String)
+      def initialize(inputs, region: nil, beg: nil, end_: nil, maxcnt: nil, overlaps: false)
+        raise ArgumentError, "inputs must be non-empty" if inputs.nil? || inputs.empty?
+
+        @owned_bams = [] # Bams we opened here; will be closed on close
+        @bams = inputs.map do |x|
+          case x
+          when HTS::Bam
+            x
+          when String
+            b = HTS::Bam.open(x)
+            @owned_bams << b
+            b
+          else
+            raise ArgumentError, "Unsupported input type: #{x.class}"
+          end
+        end
+
+        n = @bams.length
+        @iters       = []
+        @data_blocks = [] # per-input packed pointers kept alive
+
+        # Prepare optional region iterators for each input
+        @bams.each_with_index do |bam, i|
+          itr = nil
+          if region && beg.nil? && end_.nil?
+            raise "Index required for region mpileup" unless bam.index_loaded?
+
+            itr = HTS::LibHTS.sam_itr_querys(bam.instance_variable_get(:@idx), bam.header.struct, region)
+            raise "Failed to query region on input ##{i}: #{region}" if itr.null?
+          elsif region && beg && end_
+            raise "Index required for region mpileup" unless bam.index_loaded?
+
+            tid = bam.header.get_tid(region)
+            itr = HTS::LibHTS.sam_itr_queryi(bam.instance_variable_get(:@idx), tid, beg, end_)
+            raise "Failed to query region on input ##{i}: #{region} #{beg} #{end_}" if itr.null?
+          elsif beg || end_
+            raise ArgumentError, "beg and end_ must be specified together"
+          end
+          @iters << itr
+        end
+
+        # Build per-input packed pointer blocks so C passes them back to the callback.
+        # Layout per input: [0] hts_fp (htsFile*), [1] hdr_struct (bam_hdr_t*), [2] itr (hts_itr_t* or NULL)
+        ptr_size = FFI.type_size(:pointer)
+        data_array = FFI::MemoryPointer.new(:pointer, n)
+        @bams.each_with_index do |bam, i|
+          hts_fp     = bam.instance_variable_get(:@hts_file)
+          hdr_struct = bam.header.struct
+          itr        = @iters[i]
+          block = FFI::MemoryPointer.new(:pointer, 3)
+          block.put_pointer(0 * ptr_size, hts_fp)
+          block.put_pointer(1 * ptr_size, hdr_struct)
+          block.put_pointer(2 * ptr_size, itr && !itr.null? ? itr : FFI::Pointer::NULL)
+          @data_blocks << block
+          data_array.put_pointer(i * ptr_size, block)
+        end
+        # Keep the array of per-input blocks alive while the C side holds on to them
+        @data_array = data_array
+
+        @cb = FFI::Function.new(:int, %i[pointer pointer]) do |data, b|
+          # Unpack pointers from the per-input block
+          hts_fp     = data.get_pointer(0 * ptr_size)
+          hdr_struct = data.get_pointer(1 * ptr_size)
+          itr        = data.get_pointer(2 * ptr_size)
+          # HTSlib contract: return same as sam_itr_next/sam_read1 (>= 0 on success, -1 on EOF, < -1 on error)
+          if itr && !itr.null?
+            HTS::LibHTS.sam_itr_next(hts_fp, itr, b)
+          else
+            HTS::LibHTS.sam_read1(hts_fp, hdr_struct, b)
+          end
+        end
+
+        @iter = HTS::LibHTS.bam_mplp_init(n, @cb, @data_array)
+        raise "bam_mplp_init failed" if @iter.null?
+
+        HTS::LibHTS.bam_mplp_set_maxcnt(@iter, maxcnt) if maxcnt
+        return unless overlaps
+
+        rc = HTS::LibHTS.bam_mplp_init_overlaps(@iter)
+        raise "bam_mplp_init_overlaps failed" if rc < 0
+      end
+
+      # Yields an array of Pileup::PileupColumn (one per input) for each position
+      def each
+        return to_enum(__method__) unless block_given?
+
+        n = @bams.length
+        tid_ptr = FFI::MemoryPointer.new(:int)
+        pos_ptr = FFI::MemoryPointer.new(:long_long)
+        n_ptr   = FFI::MemoryPointer.new(:int, n)
+        plp_ptr = FFI::MemoryPointer.new(:pointer, n)
+        plp1_size = HTS::LibHTS::BamPileup1.size
+        headers   = @bams.map(&:header)
+
+        while HTS::LibHTS.bam_mplp64_auto(@iter, tid_ptr, pos_ptr, n_ptr, plp_ptr) > 0
+          tid = tid_ptr.read_int
+          pos = pos_ptr.read_long_long
+
+          counts = n_ptr.read_array_of_int(n)
+          plp_arr = plp_ptr.read_array_of_pointer(n)
+
+          cols = Array.new(n)
+          i = 0
+          while i < n
+            c = counts[i]
+            if c <= 0 || plp_arr[i].null?
+              cols[i] = HTS::Bam::Pileup::PileupColumn.new(tid: tid, pos: pos, alignments: [])
+            else
+              base_ptr = plp_arr[i]
+              aligns = Array.new(c)
+              j = 0
+              while j < c
+                e_ptr = base_ptr + (j * plp1_size)
+                entry = HTS::LibHTS::BamPileup1.new(e_ptr)
+                aligns[j] = HTS::Bam::Pileup::PileupRecord.new(entry, headers[i])
+                j += 1
+              end
+              cols[i] = HTS::Bam::Pileup::PileupColumn.new(tid: tid, pos: pos, alignments: aligns)
+            end
+            i += 1
+          end
+
+          yield cols
+        end
+
+        self
+      end
+
+      def close
+        if @iter && !@iter.null?
+          HTS::LibHTS.bam_mplp_destroy(@iter)
+          @iter = FFI::Pointer::NULL
+        end
+        @iters.each do |itr|
+          HTS::LibHTS.hts_itr_destroy(itr) if itr && !itr.null?
+        end
+        @iters.clear
+        # Keep references to callback and data blocks to prevent GC
+        @_keepalive = [@cb, @data_array, *@data_blocks]
+        # Close owned bams opened by this object
+        @owned_bams.each do |b|
+          b.close
+        rescue StandardError
+        end
+        @owned_bams.clear
+      end
+    end
+  end
+end

data/lib/hts/bam/pileup.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+module HTS
+  class Bam < Hts
+    # High-level pileup iterator for a single SAM/BAM/CRAM
+    class Pileup
+      include Enumerable
+
+      # Usage:
+      #   HTS::Bam::Pileup.open(bam, region: "chr1:1-100") do |pl|
+      #     pl.each { |col| ... }
+      #   end
+      def self.open(*args, **kw)
+        pu = new(*args, **kw)
+        return pu unless block_given?
+
+        begin
+          yield pu
+        ensure
+          pu.close
+        end
+        pu
+      end
+
+      # A column at a reference position with pileup alignments
+      PileupColumn = Struct.new(:tid, :pos, :alignments, keyword_init: true) do
+        def depth
+          alignments.length
+        end
+      end
+
+      # A wrapper of one bam_pileup1_t entry
+      class PileupRecord
+        def initialize(entry, header)
+          @entry  = entry
+          @header = header
+          @record = nil
+        end
+
+        # Return Bam::Record. On the first call, duplicate the underlying bam1_t (bam_dup1)
+        # so the record becomes safe to keep beyond the current pileup step. Subsequent calls
+        # return the cached Bam::Record instance.
+        # NOTE: Without duplication, bam1_t memory may be reused by HTSlib on the next step.
+        def record
+          return @record if @record
+
+          # Normalize to a raw pointer and duplicate to obtain owned memory.
+          b_ptr = @entry[:b].is_a?(FFI::Pointer) ? @entry[:b] : @entry[:b].to_ptr
+          dup_ptr = HTS::LibHTS.bam_dup1(b_ptr)
+          raise "bam_dup1 failed" if dup_ptr.null?
+
+          # Build a Bam::Record backed by the duplicated bam1_t.
+          @record = HTS::Bam::Record.new(@header, dup_ptr)
+        end
+
+        def query_position
+          @entry[:qpos]
+        end
+
+        def indel
+          @entry[:indel]
+        end
+
+        def del?
+          @entry[:is_del] == 1
+        end
+
+        def head?
+          @entry[:is_head] == 1
+        end
+
+        def tail?
+          @entry[:is_tail] == 1
+        end
+
+        def refskip?
+          @entry[:is_refskip] == 1
+        end
+      end
+
+      # Create a Pileup iterator
+      # @param bam [HTS::Bam]
+      # @param region [String, nil] Optional region string (requires index)
+      # @param beg [Integer, nil] Optional begin when using tid/beg/end form
+      # @param end_ [Integer, nil] Optional end when using tid/beg/end form
+      # @param maxcnt [Integer, nil] Max per-position depth (capped)
+      def initialize(bam, region: nil, beg: nil, end_: nil, maxcnt: nil)
+        @bam    = bam
+        @header = bam.header
+        @itr    = nil
+        @cb     = nil
+        @plp    = nil
+
+        # Optional region iterator
+        if region && beg.nil? && end_.nil?
+          raise "Index file is required to use region pileup." unless bam.index_loaded?
+
+          @itr = HTS::LibHTS.sam_itr_querys(bam.instance_variable_get(:@idx), @header.struct, region)
+          raise "Failed to query region: #{region}" if @itr.null?
+        elsif region && beg && end_
+          raise "Index file is required to use region pileup." unless bam.index_loaded?
+
+          tid = @header.get_tid(region)
+          @itr = HTS::LibHTS.sam_itr_queryi(bam.instance_variable_get(:@idx), tid, beg, end_)
+          raise "Failed to query region: #{region} #{beg} #{end_}" if @itr.null?
+        elsif beg || end_
+          raise ArgumentError, "beg and end_ must be specified together"
+        end
+
+        # Build the auto callback for bam_plp_init (micro-optimized)
+        # - Hoist ivar/constant lookups out of the callback to reduce per-call overhead.
+        # - Specialize callbacks to avoid branching in the hot path.
+        hts_fp     = @bam.instance_variable_get(:@hts_file)
+        hdr_struct = @header.struct
+        itr_local  = @itr
+
+        @cb = if itr_local && !itr_local.null?
+                FFI::Function.new(:int, %i[pointer pointer]) do |_data, b|
+                  # HTSlib contract: return same as sam_itr_next (>= 0 on success, -1 on EOF, < -1 on error)
+                  HTS::LibHTS.sam_itr_next(hts_fp, itr_local, b)
+                end
+              else
+                FFI::Function.new(:int, %i[pointer pointer]) do |_data, b|
+                  # HTSlib contract: return same as sam_read1 (>= 0 on success, -1 on EOF, < -1 on error)
+                  HTS::LibHTS.sam_read1(hts_fp, hdr_struct, b)
+                end
+              end
+
+        @plp = HTS::LibHTS.bam_plp_init(@cb, nil)
+        raise "bam_plp_init failed" if @plp.null?
+
+        HTS::LibHTS.bam_plp_set_maxcnt(@plp, maxcnt) if maxcnt
+      end
+
+      def each
+        return to_enum(__method__) unless block_given?
+
+        tid_ptr = FFI::MemoryPointer.new(:int)
+        pos_ptr = FFI::MemoryPointer.new(:long_long) # hts_pos_t
+        n_ptr   = FFI::MemoryPointer.new(:int)
+
+        # Micro-optimizations:
+        # - Compute constant struct size once
+        # - Hoist header reference outside the loop
+        plp1_size    = HTS::LibHTS::BamPileup1.size
+        header_local = @header
+
+        loop do
+          base_ptr = HTS::LibHTS.bam_plp64_auto(@plp, tid_ptr, pos_ptr, n_ptr)
+
+          # When base_ptr is NULL, check n to distinguish EOF (n == 0) from error (n < 0)
+          if base_ptr.null?
+            n = n_ptr.read_int
+            raise "HTSlib pileup error (bam_plp64_auto)" if n < 0
+
+            break
+          end
+
+          tid = tid_ptr.read_int
+          pos = pos_ptr.read_long_long
+          n   = n_ptr.read_int
+
+          # Construct alignment entries with minimal allocations
+          if n.zero?
+            alignments = []
+          else
+            alignments = Array.new(n)
+            i = 0
+            while i < n
+              e_ptr = base_ptr + (i * plp1_size)
+              entry = HTS::LibHTS::BamPileup1.new(e_ptr)
+              alignments[i] = PileupRecord.new(entry, header_local)
+              i += 1
+            end
+          end
+
+          yield PileupColumn.new(tid: tid, pos: pos, alignments: alignments)
+        end
+
+        self
+      end
+
+      def reset
+        HTS::LibHTS.bam_plp_reset(@plp) if @plp && !@plp.null?
+      end
+
+      def close
+        if @plp && !@plp.null?
+          HTS::LibHTS.bam_plp_destroy(@plp)
+          @plp = FFI::Pointer::NULL
+        end
+        if @itr && !@itr.null?
+          HTS::LibHTS.hts_itr_destroy(@itr)
+          @itr = FFI::Pointer::NULL
+        end
+        # Keep @cb referenced by instance to avoid GC during iteration.
+        @cb
+      end
+    end
+  end
+end

data/lib/hts/bam/record.rb

@@ -326,6 +326,13 @@ module HTS
         end
       end
 
+      # Get base modification information from MM/ML tags
+      # @param auto_parse [Boolean] If true (default), parse lazily on first access
+      # @return [BaseMod] Base modification object
+      def base_mod(auto_parse: true)
+        BaseMod.new(self, auto_parse: auto_parse)
+      end
+
       # TODO: add a method to get the auxiliary fields as a hash.
 
       # TODO: add a method to set the auxiliary fields.
@@ -352,8 +359,13 @@ module HTS
       private
 
       def initialize_copy(orig)
+        super
         @header = orig.header
-        @bam = LibHTS.bam_dup1(orig.struct)
+        # Deep-copy underlying bam1_t to detach from original buffer
+        dup_bam1 = LibHTS.bam_dup1(orig.struct)
+        raise "bam_dup1 failed" if dup_bam1.null?
+
+        @bam1 = dup_bam1
       end
     end
   end

data/lib/hts/bam.rb

@@ -7,7 +7,9 @@ require_relative "bam/header"
 require_relative "bam/cigar"
 require_relative "bam/flag"
 require_relative "bam/record"
-# require_relative "bam/pileup"
+require_relative "bam/base_mod"
+require_relative "bam/pileup"
+require_relative "bam/mpileup"
 # require_relative "bam/pileup_entry"
 
 module HTS
@@ -160,7 +162,7 @@ module HTS
 
       position = tell
       ary = map { |r| r.aux(tag) }
-      seek(position)
+      seek(position) if position
       ary
     end
 
@@ -194,6 +196,13 @@ module HTS
       self
     end
 
+    # Iterate alignment records in this file.
+    #
+    # Performance and memory semantics:
+    # - copy: false (default) reuses a single Record instance and its underlying bam1_t buffer.
+    #   The yielded Record MUST NOT be stored beyond the block; its content will be overwritten
+    #   by the next iteration. If you need to retain it, call `rec = rec.dup`.
+    # - copy: true yields a fresh Record per iteration (deep-copied via bam_dup1). Slower, safe to keep.
     def each(copy: false, &block)
       if copy
         each_record_copy(&block)
@@ -202,23 +211,65 @@ module HTS
       end
     end
 
+    # Iterate records in a genomic region or multiple regions.
+    # See {#each} for copy semantics. When copy: false, the yielded Record is reused and should not be stored.
+    #
+    # @param region [String, Array<String>] Region specification(s)
+    #   - Single region: "chr1:100-200" or "chr1" with beg/end parameters
+    #   - Multiple regions: ["chr1:100-200", "chr2:500-600", ...]
+    # @param beg [Integer, nil] Start position (used with single string region)
+    # @param end_ [Integer, nil] End position (used with single string region)
+    # @param copy [Boolean] Whether to deep-copy records (see {#each})
+    #
+    # @example Single region query
+    #   bam.query("chr1:100-200") { |r| puts r.qname }
+    #   bam.query("chr1", 100, 200) { |r| puts r.qname }
+    #
+    # @example Multi-region query
+    #   bam.query(["chr1:100-200", "chr2:500-600"]) { |r| puts r.qname }
     def query(region, beg = nil, end_ = nil, copy: false, &block)
       check_closed
       raise "Index file is required to call the query method." unless index_loaded?
 
-      if beg && end_
-        tid = header.get_tid(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_ cannot be used with array of regions" if beg || end_
+
+        query_regions(region, copy:, &block)
+      when String
+        if beg && end_
+          tid = header.get_tid(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
       else
-        raise ArgumentError, "beg and end_ must be specified together"
+        raise ArgumentError, "region must be String or Array"
       end
     end
 
-    # def pileup
-    #   Pileup.new(self)
-    # end
+    # Pileup iterator over this file. Optional region can be specified.
+    # When a block is given, uses RAII-style and ensures the iterator is closed at block end.
+    # Without a block, returns an Enumerator over a live Pileup instance; caller should close when done.
+    #
+    # @param region [String, nil] region string like "chr1:100-200"
+    # @param beg [Integer, nil]
+    # @param end_ [Integer, nil]
+    # @param maxcnt [Integer, nil] cap on depth per position
+    def pileup(region = nil, beg = nil, end_: nil, maxcnt: nil, &block)
+      check_closed
+      if block_given?
+        Pileup.open(self, region:, beg:, end_: end_, maxcnt: maxcnt) do |piter|
+          piter.each(&block)
+        end
+        self
+      else
+        piter = Pileup.new(self, region:, beg:, end_: end_, maxcnt: maxcnt)
+        piter.to_enum(:each)
+      end
+    end
 
     private
 
@@ -238,6 +289,17 @@ module HTS
       end
     end
 
+    # Multi-region query implementation
+    def query_regions(regions, copy: false, &block)
+      if copy
+        query_regions_copy(regions, &block)
+      else
+        query_regions_reuse(regions, &block)
+      end
+    end
+
+    # Internal: yield a single reused Record over the entire file.
+    # The underlying bam1_t is mutated on each iteration for speed.
     def each_record_reuse
       check_closed
       # Each does not always start at the beginning of the file.
@@ -250,6 +312,7 @@ module HTS
       self
     end
 
+    # Internal: yield deep-copied Records so callers may retain them safely.
     def each_record_copy
       check_closed
       return to_enum(__method__) unless block_given?
@@ -301,6 +364,7 @@ module HTS
       self
     end
 
+    # Internal: reused-Record iterator over a query iterator.
     def query_reuse_yield(qiter)
       bam1 = LibHTS.bam_init1
       record = Record.new(header, bam1)
@@ -323,5 +387,27 @@ module HTS
     ensure
       LibHTS.hts_itr_destroy(qiter)
     end
+
+    # Multi-region query using sequential single-region queries
+    # Note: This is a fallback implementation. Ideally we would use sam_itr_regarray
+    # but there seem to be issues with the multi-region iterator in the current setup.
+    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
+
+    # Multi-region query with copied Records using sequential queries
+    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
   end
 end

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/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,

data/lib/hts/libhts/sam.rb

@@ -2,6 +2,11 @@
 
 module HTS
   module LibHTS
+    # Callback type for bam_plp_auto_f: int (*)(void *data, bam1_t *b)
+    # Use raw pointer for bam1_t to avoid creating ManagedStruct wrappers (which would double-free)
+    callback :bam_plp_auto_f, %i[pointer pointer], :int
+    # callback :bam_plp_auto_f, [:pointer, Bam1.by_ref], :int
+
     # Generates a new unpopulated header structure.
     attach_function \
       :sam_hdr_init,
@@ -414,24 +419,24 @@ module HTS
 
     attach_function \
       :sam_parse1,
-      [KString, SamHdr, Bam1],
+      [KString, SamHdr, :pointer], # [KString, SamHdr, (Bam1 | Bam1View)]
       :int
 
     attach_function \
       :sam_format1,
-      [SamHdr, Bam1, KString],
+      [SamHdr, :pointer, KString], # [SamHdr, (Bam1 | Bam1View), KString]
       :int
 
     # Read a record from a file
     attach_function \
       :sam_read1,
-      [HtsFile, SamHdr, Bam1],
+      [HtsFile, SamHdr, :pointer], # [HtsFile, SamHdr, (Bam1 | Bam1View)]
       :int
 
     # Write a record to a file
     attach_function \
       :sam_write1,
-      [HtsFile, SamHdr, Bam1],
+      [HtsFile, SamHdr, :pointer], # [HtsFile, SamHdr, (Bam1 | Bam1View)]
       :int
 
     # Checks whether a record passes an hts_filter.
@@ -555,28 +560,28 @@ module HTS
 
     attach_function \
       :bam_plp_push,
-      [:bam_plp, Bam1],
+      [:bam_plp, Bam1.by_ref],
       :int
 
     attach_function \
       :bam_plp_next,
       %i[bam_plp pointer pointer pointer],
-      BamPileup1.by_ref
+      :pointer # BamPileup1.by_ref
 
     attach_function \
       :bam_plp_auto,
       %i[bam_plp pointer pointer pointer],
-      BamPileup1.by_ref
+      :pointer # BamPileup1.by_ref
 
     attach_function \
       :bam_plp64_next,
       %i[bam_plp pointer pointer pointer],
-      BamPileup1.by_ref
+      :pointer # BamPileup1.by_ref
 
     attach_function \
       :bam_plp64_auto,
       %i[bam_plp pointer pointer pointer],
-      BamPileup1.by_ref
+      :pointer # BamPileup1.by_ref
 
     attach_function \
       :bam_plp_set_maxcnt,
@@ -588,7 +593,9 @@ module HTS
       [:bam_plp],
       :void
 
-    callback :bam_plp_callback_function, [:pointer, Bam1, BamPileupCd], :int
+    # Callback type for constructor/destructor: int (*)(void *data, const bam1_t *b, bam_pileup_cd *cd)
+    callback :bam_plp_callback_function, [:pointer, :pointer, BamPileupCd.by_ref], :int
+    # callback :bam_plp_callback_function, [:pointer, Bam1.by_ref, BamPileupCd.by_ref], :int
 
     # sets a callback to initialise any per-pileup1_t fields.
     attach_function \
@@ -602,17 +609,21 @@ module HTS
       :void
 
     # Get pileup padded insertion sequence
+    # Make pointer passing explicit by using by_ref for structs
     attach_function \
       :bam_plp_insertion,
-      [BamPileup1, KString, :pointer],
+      [BamPileup1.by_ref, KString.by_ref, :pointer],
       :int
 
     # Get pileup padded insertion sequence, including base modifications
     attach_function \
       :bam_plp_insertion_mod,
-      [BamPileup1, :pointer, KString, :pointer],
+      [BamPileup1.by_ref, HtsBaseModState, KString.by_ref, :pointer],
       :int
 
+    # NOTE: There is no bam_plp_init_overlaps in HTSlib (only bam_mplp_init_overlaps exists).
+    # The incorrect binding is removed to avoid undefined symbol errors.
+
     attach_function \
       :bam_mplp_init,
       %i[int bam_plp_auto_f pointer],
@@ -672,61 +683,61 @@ module HTS
     attach_function \
       :hts_base_mod_state_alloc,
       [],
-      :pointer # hts_base_mod_state
+      HtsBaseModState
 
     # Destroys an  hts_base_mode_state.
     attach_function \
       :hts_base_mod_state_free,
-      [:pointer], # hts_base_mod_state
+      [HtsBaseModState],
       :void
 
     # Parses the MM and ML tags out of a bam record.
     attach_function \
       :bam_parse_basemod,
-      [Bam1, :pointer],
+      [Bam1, HtsBaseModState],
       :int
 
     # Parses the MM and ML tags out of a bam record.
     attach_function \
       :bam_parse_basemod2,
-      [Bam1, :pointer, :uint32],
+      [Bam1, HtsBaseModState, :uint32],
       :int
 
     # Returns modification status for the next base position in the query seq.
     attach_function \
       :bam_mods_at_next_pos,
-      [Bam1, :pointer, :pointer, :int],
+      [Bam1, HtsBaseModState, :pointer, :int],
       :int
 
     # Finds the next location containing base modifications and returns them
     attach_function \
       :bam_next_basemod,
-      [Bam1, :pointer, :pointer, :int, :pointer],
+      [Bam1, HtsBaseModState, :pointer, :int, :pointer],
       :int
 
     # Returns modification status for a specific query position.
     attach_function \
       :bam_mods_at_qpos,
-      [Bam1, :int, :pointer, :pointer, :int],
+      [Bam1, :int, HtsBaseModState, :pointer, :int],
       :int
 
     # Returns data about a specific modification type for the alignment record.
     attach_function \
       :bam_mods_query_type,
-      %i[pointer int pointer pointer string],
+      [HtsBaseModState, :int, :pointer, :pointer, :pointer],
       :int
 
     # Returns data about the i^th modification type for the alignment record.
     attach_function \
       :bam_mods_queryi,
-      %i[pointer int pointer pointer string],
+      [HtsBaseModState, :int, :pointer, :pointer, :pointer],
       :int
 
     # Returns the list of base modification codes provided for this
     attach_function \
       :bam_mods_recorded,
-      %i[pointer pointer],
-      :int
+      [HtsBaseModState, :pointer],
+      :pointer
   end
 end
 

data/lib/hts/libhts.rb

@@ -23,6 +23,12 @@ module HTS
     rescue FFI::NotFoundError => e
       warn e.message if $VERBOSE
     end
+
+    def self.attach_variable(*)
+      super
+    rescue FFI::NotFoundError => e
+      warn e.message if $VERBOSE
+    end
   end
 end
 

data/lib/hts/tabix.rb

@@ -44,8 +44,27 @@ module HTS
       @idx = load_index(index)
     end
 
-    def build_index
-      raise "Not implemented yet"
+    def build_index(index_name = nil, min_shift: 0)
+      check_closed
+
+      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)
+        when 0 # successful
+        when -1 then raise "general failure"
+        when -2 then raise "compression not BGZF"
+        else raise "unknown error"
+        end
+      else
+        warn "Create index for #{@file_name}"
+        case LibHTS.tbx_index_build(@file_name, min_shift, LibHTS.tbx_conf_vcf)
+        when 0 # successful
+        when -1 then raise "general failure"
+        when -2 then raise "compression not BGZF"
+        else raise "unknown error"
+        end
+      end
+      self # for method chaining
     end
 
     def load_index(index_name = nil)

data/lib/hts/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: htslib
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - kojix2
@@ -62,10 +62,13 @@ files:
 - TUTORIAL.md
 - lib/hts/bam.rb
 - lib/hts/bam/auxi.rb
+- lib/hts/bam/base_mod.rb
 - lib/hts/bam/cigar.rb
 - lib/hts/bam/flag.rb
 - lib/hts/bam/header.rb
 - lib/hts/bam/header_record.rb
+- lib/hts/bam/mpileup.rb
+- lib/hts/bam/pileup.rb
 - lib/hts/bam/record.rb
 - lib/hts/bcf.rb
 - lib/hts/bcf/format.rb
@@ -116,7 +119,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.7.1
+rubygems_version: 3.6.9
 specification_version: 4
 summary: HTSlib bindings for Ruby
 test_files: []