htslib 0.2.3 → 0.2.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ea47a473d63b90fd2b1db4ecd65aa1ef38d47bbe5624e24ac583b5329301e5cb
-  data.tar.gz: aab96376972d7b0a587978484b22e41ee049ea742cba937cd57c66a9c0c42f2a
+  metadata.gz: 2a49c4758453c5c39915d9d17ccc33ce104699fca39c4083d4b2801767b655f1
+  data.tar.gz: 46ee49f6b452471e26afedfce70489cd24eebf86b1a18240bab125d465921fb8
 SHA512:
-  metadata.gz: 76d9aa699d0176557d8e44171018b132fc4df2c0e1f47a9784388693103799cf920c2ae437fb97f8429422a1edb5ebd43eae7b28a1f18452a5eeeac38244a981
-  data.tar.gz: f2f1d50099a66e71574c4019e66452dd100371cbdc7d08b144856bab8f59f04aac4e207585534f26e29a06342a7fafe5c3ea0fb0d0e2e8dd9ed1822ddbcbdfe8
+  metadata.gz: 918c0919750eb3d436cf19b1011ffed0a8d0760b29e0a3c2e675a9efa563a3f5c3b9a9ae38232e67192df4d066c446bbc0443f00d07cab9ac0c3401b38bd3fb7
+  data.tar.gz: 343fbaec89a2e60a54feadd29856b26b772baa65ef52d181cd5845ed53a8e549504ddcdcc739dff716f9069a5b0b3e6f22f5136c2a612cc6014eb79ee225ab2b

data/README.md

@@ -8,9 +8,7 @@
 
 Ruby-htslib is the [Ruby](https://www.ruby-lang.org) bindings to [HTSlib](https://github.com/samtools/htslib), a C library for high-throughput sequencing data formats. It allows you to read and write file formats commonly used in genomics, such as [SAM, BAM, VCF, and BCF](http://samtools.github.io/hts-specs/), in the Ruby language.
 
-:apple: Feel free to fork it out if you can develop it! 
-
-:bowtie: Alpha stage.
+:apple: Feel free to fork it! 
 
 ## Requirements
 
@@ -18,6 +16,7 @@ Ruby-htslib is the [Ruby](https://www.ruby-lang.org) bindings to [HTSlib](https:
 * [HTSlib](https://github.com/samtools/htslib)
   * Ubuntu : `apt install libhts-dev`
   * macOS : `brew install htslib`
+  * Windows : [mingw-w64-htslib](https://packages.msys2.org/base/mingw-w64-htslib) is automatically fetched when installing the gem ([RubyInstaller](https://rubyinstaller.org) only).
   * Build from source code (see Development section)
 
 ## Installation
@@ -34,11 +33,13 @@ Alternatively, you can specify the directory of the shared library by setting th
 export HTSLIBDIR="/your/path/to/htslib" # libhts.so
 ```
 
+ruby-htslib also works on Windows; if you use RubyInstaller, htslib will be prepared automatically.
+
 ## Overview
 
-### High level API
+### High-level API
 
-Read SAM / BAM / CRAM - Sequence Alignment Map file
+HTS::Bam - SAM / BAM / CRAM - Sequence Alignment Map file
 
 ```ruby
 require 'htslib'
@@ -56,14 +57,14 @@ bam.each do |r|
      mpos: r.mpos + 1,
      isiz: r.isize,
      seqs: r.seq,
-     qual: r.qual.map { |i| (i + 33).chr }.join,
+     qual: r.qual_string,
      MC:   r.aux("MC")
 end
 
 bam.close
 ```
 
-Read VCF / BCF - Variant Call Format file
+HTS::Bcf - VCF / BCF - Variant Call Format file
 
 ```ruby
 bcf = HTS::Bcf.open("b.bcf")
@@ -96,9 +97,18 @@ fa.close
 
 </details>
 
-### Low level API
+<details>
+<summary><b>Tbx</b></summary>
+
+```ruby
+
+```
 
-`HTS::LibHTS` provides native C functions. 
+</details>
+
+### Low-level API
+
+`HTS::LibHTS` provides native C functions.
 
 ```ruby
 require 'htslib'
@@ -109,11 +119,17 @@ p b[:category]
 p b[:format]
 ```
 
-Note: htslib makes extensive use of macro functions for speed. You cannot use C macro functions in Ruby if they are not reimplemented in ruby-htslib. Only small number of C structs are implemented with FFI's ManagedStruct, which frees memory when Ruby's garbage collection fires. Other structs will need to be freed manually. 
+Macro functions
+
+htslib has a lot of macro functions for speed. Ruby-FFI cannot call C macro functions. However, essential functions are reimplemented in Ruby, and you can call them.
+
+Structs
+
+Only a small number of C structs are implemented with FFI's ManagedStruct, which frees memory when Ruby's garbage collection fires. Other structs will need to be freed manually.
 
 ### Need more speed?
 
-Try Crystal. [htslib.cr](https://github.com/bio-crystal/htslib.cr) is implemented in Crystal language and provides an API compatible with ruby-htslib. Crystal language is not as flexible as Ruby language. You can not use `eval` methods, and you must always be careful with the data types. Writing one-time scripts in Crystal or playing with REPL may not be as much fun. However, if you have a clear idea of what you want to do in your mind, have already written code in Ruby, and need to run them over and over, try creating a command line tool in Crystal.  The Crystal language is fast, as fast as the Rust and C languages. It will give you great power to create tools.
+Try Crystal. [HTS.cr](https://github.com/bio-cr/hts.cr) is implemented in Crystal language and provides an API compatible with ruby-htslib. Crystal language is not as flexible as Ruby language. You can not use `eval` methods and must always be careful with the types. Writing one-time scripts in Crystal may be less fun. However, if you have a clear idea of what you want to do in your mind, have already written code in Ruby, and need to run them over and over, try creating a command line tool in Crystal. The Crystal language is as fast as the Rust and C languages. It will give you incredible power to make tools.
 
 ## Documentation
 
@@ -134,26 +150,29 @@ bundle exec rake test
 
 [GNU Autotools](https://en.wikipedia.org/wiki/GNU_Autotools) is required to compile htslib.
 
-Many macro functions are used in HTSlib. Since these macro functions cannot be called using FFI, they must be reimplemented in Ruby.
+HTSlib has many macro functions. These macro functions cannot be called from FFI and must be reimplemented in Ruby.
 
 * Use the new version of Ruby to take full advantage of Ruby's potential.
-  * This is possible because we have a small number of users. What a deal!
-* Remain compatible with [htslib.cr](https://github.com/bio-crystal/htslib.cr).
-  * The most challenging part is the return value. In the Crystal language, methods are expected to return only one type. On the other hand, in the Ruby language, methods that return multiple classes are very common. For example, in the Crystal language, the compiler gets confused if the return value is one of six types: Int32, Int64, Float32, Float64, Nil, or String. In fact Crystal can do this. But the code gets a little messy. In Ruby, this is very common and doesn't cause any problems. 
+  * This is possible because we have a small number of users.
+* Remain compatible with [HTS.cr](https://github.com/bio-cr/hts.cr).
+  * The most challenging part is the return value. In the Crystal language, methods are expected to return only one type. On the other hand, in the Ruby language, methods that return multiple classes are very common. For example, in the Crystal language, the compiler gets confused if the return value is one of six types: Int32, Int64, Float32, Float64, Nil, or String. In fact Crystal allows you to do that. But the code gets a little messy. In Ruby, this is very common and doesn't cause any problems.
+  * Ruby and Crystal are languages that use garbage collection. However, the memory release policy for allocated C structures is slightly different: in Ruby-FFI, you can define a `self.release` method in `FFI::Struct`. This method is called when GC. So you don't have to worry about memory in high-level APIs like Bam::Record or Bcf::Record, etc. Crystal requires you to define a finalize method on each class. So you need to define it in Bam::Record or Bcf::Record.
 
-In the script directory, there are several tools to help implement ruby-htslib. These tools may be forked into independent repository in the future.
+Method naming generally follows the Rust-htslib API. 
 
 #### FFI Extensions
 
 * [ffi-bitfield](https://github.com/kojix2/ffi-bitfield) : Extension of Ruby-FFI to support bitfields.
 
-#### Automatic generation or automatic validation (Future plan)
+#### Automatic validation
+
+In the `script` directory, there are several tools to help implement ruby-htslib. Scripts using c2ffi can check the coverage of htslib functions in Ruby-htslib. They are useful when new versions of htslib are released.
 
-+ [c2ffi](https://github.com/rpav/c2ffi) is a tool to create JSON format metadata from C header files. It is planned to use c2ffi to automatically generate bindings or tests.
+* [c2ffi](https://github.com/rpav/c2ffi) is a tool to create JSON format metadata from C header files. 
 
 ## Contributing
 
-Ruby-htslib is a library under development, so even small improvements like typofix are welcome! Please feel free to send us your pull requests.
+Ruby-htslib is a library under development, so even minor improvements like typo fixes are welcome! Please feel free to send us your pull requests.
 
 * [Report bugs](https://github.com/kojix2/ruby-htslib/issues)
 * Fix bugs and [submit pull requests](https://github.com/kojix2/ruby-htslib/pulls)
@@ -165,14 +184,14 @@ Ruby-htslib is a library under development, so even small improvements like typo
 ```
 # Ownership and Commitment Rights
 
-Do you need commit rights to ruby-htslib repository?
+Do you need commit rights to the ruby-htslib repository?
 Do you want to get admin rights and take over the project?
 If so, please feel free to contact us @kojix2.
 ```
 
-#### Why do you implement htslib in a language like Ruby, which is not widely used in the bioinformatics?
+#### Why do you implement htslib in a language like Ruby, which is not widely used in bioinformatics?
 
-One of the greatest joys of using a minor language like Ruby in bioinformatics is that there is nothing stopping you from reinventing the wheel. Reinventing the wheel can be fun. But with languages like Python and R, where many bioinformatics masters work, there is no chance left for beginners to create htslib bindings. Bioinformatics file formats, libraries and tools are very complex and I don't know how to understand them. So I wanted to implement the HTSLib binding myself to better understand how the pioneers of bioinformatics felt when establishing the file format and how they created their tools. I hope one day we can work on bioinformatics using Ruby and Crystal languages, not to replace other languages such as Python and R, but to add new power and value to this advancing field.
+One of the greatest joys of using a minor language like Ruby in bioinformatics is that nothing stops you from reinventing the wheel. Reinventing the wheel can be fun. But with languages like Python and R, where many bioinformatics masters work, there is no chance for beginners to create htslib bindings. Bioinformatics file formats, libraries, and tools are very complex, and I need to learn how to understand them. So I started to implement the HTSLib binding myself to better understand how the pioneers of bioinformatics felt when establishing the file format and how they created their tools. I hope one day we can work on bioinformatics using Ruby and Crystal languages, not to replace other languages such as Python and R, but to add new power and value to this advancing field.
 
 ## Links
 
@@ -182,6 +201,7 @@ One of the greatest joys of using a minor language like Ruby in bioinformatics i
 ## Funding support
 
 This work was supported partially by [Ruby Association Grant 2020](https://www.ruby.or.jp/en/news/20201022).
+
 ## License
 
 [MIT License](https://opensource.org/licenses/MIT).

data/lib/hts/bam/header.rb

@@ -1,11 +1,26 @@
 # frozen_string_literal: true
 
+require_relative "header_record"
+
 module HTS
   class Bam < Hts
     # A class for working with alignment header.
     class Header
-      def initialize(hts_file)
-        @sam_hdr = LibHTS.sam_hdr_read(hts_file)
+      def self.parse(str)
+        new(LibHTS.sam_hdr_parse(str.size, str))
+      end
+
+      def initialize(arg = nil)
+        case arg
+        when LibHTS::HtsFile
+          @sam_hdr = LibHTS.sam_hdr_read(arg)
+        when LibHTS::SamHdr
+          @sam_hdr = arg
+        when nil
+          @sam_hdr = LibHTS.sam_hdr_init
+        else
+          raise TypeError, "Invalid argument"
+        end
       end
 
       def struct
@@ -17,6 +32,7 @@ module HTS
       end
 
       def target_count
+        # FIXME: sam_hdr_nref
         @sam_hdr[:n_targets]
       end
 
@@ -32,6 +48,41 @@ module HTS
         end
       end
 
+      # experimental
+      def add_lines(str)
+        LibHTS.sam_hdr_add_lines(@sam_hdr, str, 0)
+      end
+
+      # experimental
+      def add_line(type, *args)
+        args = args.flat_map { |arg| [:string, arg] }
+        LibHTS.sam_hdr_add_line(@sam_hdr, type, *args, :pointer, FFI::Pointer::NULL)
+      end
+
+      # experimental
+      def find_line(type, key, value)
+        ks = LibHTS::KString.new
+        r = LibHTS.sam_hdr_find_line_id(@sam_hdr, type, key, value, ks)
+        r == 0 ? ks[:s] : nil
+      end
+
+      # experimental
+      def find_line_at(type, pos)
+        ks = LibHTS::KString.new
+        r = LibHTS.sam_hdr_find_line_pos(@sam_hdr, type, pos, ks)
+        r == 0 ? ks[:s] : nil
+      end
+
+      # experimental
+      def remove_line(type, key, value)
+        LibHTS.sam_hdr_remove_line_id(@sam_hdr, type, key, value)
+      end
+
+      # experimental
+      def remove_line_at(type, pos)
+        LibHTS.sam_hdr_remove_line_pos(@sam_hdr, type, pos)
+      end
+
       def to_s
         LibHTS.sam_hdr_str(@sam_hdr)
       end

data/lib/hts/bam/header_record.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module HTS
+  class Bam < Hts
+    class HeaderRecord
+      def initialize
+        @bam_hrec
+      end
+    end
+  end
+end

data/lib/hts/bam/record.rb

@@ -17,6 +17,7 @@ module HTS
         @header = header
       end
 
+      # Return the FFI::Struct object.
       def struct
         @bam1
       end
@@ -25,17 +26,14 @@ module HTS
         @bam1.to_ptr
       end
 
-      # returns the query name.
+      # Get the read name. (a.k.a QNAME)
+      # @return [String] query template name
       def qname
         LibHTS.bam_get_qname(@bam1).read_string
       end
 
-      # Set (query) name.
-      # def qname=(name)
-      #   raise 'Not Implemented'
-      # end
-
-      # returns the tid of the record or -1 if not mapped.
+      # Get the chromosome ID of the alignment. -1 if not mapped.
+      # @return [Integer] chromosome ID
       def tid
         @bam1[:core][:tid]
       end
@@ -44,7 +42,8 @@ module HTS
         @bam1[:core][:tid] = tid
       end
 
-      # returns the tid of the mate or -1 if not mapped.
+      # Get the chromosome ID of the mate. -1 if not mapped.
+      # @return [Integer] chromosome ID
       def mtid
         @bam1[:core][:mtid]
       end
@@ -53,7 +52,8 @@ module HTS
         @bam1[:core][:mtid] = mtid
       end
 
-      # returns 0-based start position.
+      # Get the 0-based leftmost coordinate of the alignment.
+      # @return [Integer] 0-based leftmost coordinate
       def pos
         @bam1[:core][:pos]
       end
@@ -62,7 +62,8 @@ module HTS
         @bam1[:core][:pos] = pos
       end
 
-      # returns 0-based mate position
+      # Get the 0-based leftmost coordinate of the mate.
+      # @return [Integer] 0-based leftmost coordinate
       def mate_pos
         @bam1[:core][:mpos]
       end
@@ -74,6 +75,8 @@ module HTS
       alias mpos mate_pos
       alias mpos= mate_pos=
 
+      # Get the bin calculated by bam_reg2bin().
+      # @return [Integer] bin
       def bin
         @bam1[:core][:bin]
       end
@@ -82,12 +85,15 @@ module HTS
         @bam1[:core][:bin] = bin
       end
 
-      # returns end position of the read.
+      # Get the rightmost base position of the alignment on the reference genome.
+      # @return [Integer] 0-based rightmost coordinate
       def endpos
         LibHTS.bam_endpos @bam1
       end
 
-      # returns the chromosome or '' if not mapped.
+      # Get the reference sequence name of the alignment. (a.k.a RNAME)
+      # '' if not mapped.
+      # @return [String] reference sequence name
       def chrom
         return "" if tid == -1
 
@@ -96,7 +102,9 @@ module HTS
 
       alias contig chrom
 
-      # returns the chromosome of the mate or '' if not mapped.
+      # Get the reference sequence name of the mate.
+      # '' if not mapped.
+      # @return [String] reference sequence name
       def mate_chrom
         return "" if mtid == -1
 
@@ -105,12 +113,20 @@ module HTS
 
       alias mate_contig mate_chrom
 
-      # Get strand information.
+      # Get whether the query is on the reverse strand.
+      # @return [String] strand "+" or "-"
       def strand
         LibHTS.bam_is_rev(@bam1) ? "-" : "+"
       end
 
-      # insert size
+      # Get whether the query's mate is on the reverse strand.
+      # @return [String] strand "+" or "-"
+      def mate_strand
+        LibHTS.bam_is_mrev(@bam1) ? "-" : "+"
+      end
+
+      # Get the observed template length. (a.k.a TLEN)
+      # @return [Integer] isize
       def insert_size
         @bam1[:core][:isize]
       end
@@ -122,7 +138,8 @@ module HTS
       alias isize insert_size
       alias isize= insert_size=
 
-      # mapping quality
+      # Get the mapping quality of the alignment. (a.k.a MAPQ)
+      # @return [Integer] mapping quality
       def mapq
         @bam1[:core][:qual]
       end
@@ -131,11 +148,14 @@ module HTS
         @bam1[:core][:qual] = mapq
       end
 
-      # returns a `Cigar` object.
+      # Get the Bam::Cigar object.
+      # @return [Bam::Cigar] cigar
       def cigar
         Cigar.new(LibHTS.bam_get_cigar(@bam1), @bam1[:core][:n_cigar])
       end
 
+      # Calculate query length from CIGAR.
+      # @return [Integer] query length
       def qlen
         LibHTS.bam_cigar2qlen(
           @bam1[:core][:n_cigar],
@@ -143,6 +163,8 @@ module HTS
         )
       end
 
+      # Calculate reference length from CIGAR.
+      # @return [Integer] reference length
       def rlen
         LibHTS.bam_cigar2rlen(
           @bam1[:core][:n_cigar],
@@ -150,7 +172,8 @@ module HTS
         )
       end
 
-      # return the read sequence
+      # Get the sequence. (a.k.a SEQ)
+      # @return [String] sequence
       def seq
         r = LibHTS.bam_get_seq(@bam1)
         seq = String.new
@@ -161,11 +184,15 @@ module HTS
       end
       alias sequence seq
 
+      # Get the length of the query sequence.
+      # @return [Integer] query length
       def len
         @bam1[:core][:l_qseq]
       end
 
-      # return only the base of the requested index "i" of the query sequence.
+      # Get the base of the requested index "i" of the query sequence.
+      # @param [Integer] i index
+      # @return [String] base
       def base(n)
         n += @bam1[:core][:l_qseq] if n < 0
         return "." if (n >= @bam1[:core][:l_qseq]) || (n < 0) # eg. base(-1000)
@@ -174,13 +201,23 @@ module HTS
         SEQ_NT16_STR[LibHTS.bam_seqi(r, n)]
       end
 
-      # return the base qualities
+      # Get the base qualities.
+      # @return [Array] base qualities
       def qual
         q_ptr = LibHTS.bam_get_qual(@bam1)
         q_ptr.read_array_of_uint8(@bam1[:core][:l_qseq])
       end
 
-      # return only the base quality of the requested index "i" of the query sequence.
+      # Get the base qualities as a string. (a.k.a QUAL)
+      # ASCII of base quality + 33.
+      # @return [String] base qualities
+      def qual_string
+        qual.map { |q| (q + 33).chr }.join
+      end
+
+      # Get the base quality of the requested index "i" of the query sequence.
+      # @param [Integer] i index
+      # @return [Integer] base quality
       def base_qual(n)
         n += @bam1[:core][:l_qseq] if n < 0
         return 0 if (n >= @bam1[:core][:l_qseq]) || (n < 0) # eg. base_qual(-1000)
@@ -189,7 +226,8 @@ module HTS
         q_ptr.get_uint8(n)
       end
 
-      # returns a `Flag` object.
+      # Get Bam::Flag object of the alignment.
+      # @return [Bam::Flag] flag
       def flag
         Flag.new(@bam1[:core][:flag])
       end
@@ -205,7 +243,9 @@ module HTS
         end
       end
 
-      # retruns the auxillary fields.
+      # Get the auxiliary data.
+      # @param [String] key tag name
+      # @return [String] value
       def aux(key = nil)
         aux = Aux.new(self)
         if key
@@ -230,6 +270,7 @@ module HTS
         end
       end
 
+      # @return [String] a string representation of the alignment.
       def to_s
         kstr = LibHTS::KString.new
         raise "Failed to format bam record" if LibHTS.sam_format1(@header.struct, @bam1, kstr) == -1

data/lib/hts/bam.rb

@@ -57,7 +57,6 @@ module HTS
       build_index(index) if build_index
       @idx = load_index(index)
       @start_position = tell
-      super # do nothing
     end
 
     def build_index(index_name = nil, min_shift: 0)
@@ -90,18 +89,21 @@ module HTS
       !@idx.null?
     end
 
-    # Close the current file.
     def close
       LibHTS.hts_idx_destroy(@idx) if @idx&.null?
       @idx = nil
       super
     end
 
+    def fai=(fai)
+      check_closed
+      LibHTS.hts_set_fai_filename(@hts_file, fai) > 0 || raise
+    end
+
     def write_header(header)
       check_closed
 
       @header = header.dup
-      LibHTS.hts_set_fai_filename(@hts_file, @file_name)
       LibHTS.sam_hdr_write(@hts_file, header)
     end
 
@@ -109,7 +111,8 @@ module HTS
       check_closed
 
       aln_dup = aln.dup
-      LibHTS.sam_write1(@hts_file, header, aln_dup) > 0 || raise
+      r = LibHTS.sam_write1(@hts_file, header, aln_dup)
+      raise "Failed to write record" if r < 0
     end
 
     def each(copy: false, &block)
@@ -120,29 +123,6 @@ module HTS
       end
     end
 
-    private def each_record_copy
-      check_closed
-      return to_enum(__method__) unless block_given?
-
-      while LibHTS.sam_read1(@hts_file, header, bam1 = LibHTS.bam_init1) != -1
-        record = Record.new(bam1, header)
-        yield record
-      end
-      self
-    end
-
-    private def each_record_reuse
-      check_closed
-      # Each does not always start at the beginning of the file.
-      # This is the common behavior of IO objects in Ruby.
-      return to_enum(__method__) unless block_given?
-
-      bam1 = LibHTS.bam_init1
-      record = Record.new(bam1, header)
-      yield record while LibHTS.sam_read1(@hts_file, header, bam1) != -1
-      self
-    end
-
     def query(region, copy: false, &block)
       if copy
         query_copy(region, &block)
@@ -151,45 +131,6 @@ module HTS
       end
     end
 
-    private def query_copy(region)
-      check_closed
-      raise "Index file is required to call the query method." unless index_loaded?
-      return to_enum(__method__, region) unless block_given?
-
-      qiter = LibHTS.sam_itr_querys(@idx, header, region)
-
-      begin
-        loop do
-          bam1 = LibHTS.bam_init1
-          slen = LibHTS.sam_itr_next(@hts_file, qiter, bam1)
-          break if slen == -1
-          raise if slen < -1
-
-          yield Record.new(bam1, header)
-        end
-      ensure
-        LibHTS.hts_itr_destroy(qiter)
-      end
-      self
-    end
-
-    private def query_reuse(region)
-      check_closed
-      raise "Index file is required to call the query method." unless index_loaded?
-      return to_enum(__method__, region) unless block_given?
-
-      qiter = LibHTS.sam_itr_querys(@idx, header, region)
-
-      bam1 = LibHTS.bam_init1
-      record = Record.new(bam1, header)
-      begin
-        yield record while LibHTS.sam_itr_next(@hts_file, qiter, bam1) > 0
-      ensure
-        LibHTS.hts_itr_destroy(qiter)
-      end
-      self
-    end
-
     # @!macro [attach] define_getter
     #   @method $1
     #   Get $1 array
@@ -247,5 +188,71 @@ module HTS
 
       self
     end
+
+    private
+
+    def query_reuse(region)
+      check_closed
+      raise "Index file is required to call the query method." unless index_loaded?
+      return to_enum(__method__, region) unless block_given?
+
+      qiter = LibHTS.sam_itr_querys(@idx, header, region)
+      raise "Failed to query region: #{region}" if qiter.null?
+
+      bam1 = LibHTS.bam_init1
+      record = Record.new(bam1, header)
+      begin
+        yield record while LibHTS.sam_itr_next(@hts_file, qiter, bam1) > 0
+      ensure
+        LibHTS.hts_itr_destroy(qiter)
+      end
+      self
+    end
+
+    def query_copy(region)
+      check_closed
+      raise "Index file is required to call the query method." unless index_loaded?
+      return to_enum(__method__, region) unless block_given?
+
+      qiter = LibHTS.sam_itr_querys(@idx, header, region)
+      raise "Failed to query region: #{region}" if qiter.null?
+
+      begin
+        loop do
+          bam1 = LibHTS.bam_init1
+          slen = LibHTS.sam_itr_next(@hts_file, qiter, bam1)
+          break if slen == -1
+          raise if slen < -1
+
+          yield Record.new(bam1, header)
+        end
+      ensure
+        LibHTS.hts_itr_destroy(qiter)
+      end
+      self
+    end
+
+    def each_record_reuse
+      check_closed
+      # Each does not always start at the beginning of the file.
+      # This is the common behavior of IO objects in Ruby.
+      return to_enum(__method__) unless block_given?
+
+      bam1 = LibHTS.bam_init1
+      record = Record.new(bam1, header)
+      yield record while LibHTS.sam_read1(@hts_file, header, bam1) != -1
+      self
+    end
+
+    def each_record_copy
+      check_closed
+      return to_enum(__method__) unless block_given?
+
+      while LibHTS.sam_read1(@hts_file, header, bam1 = LibHTS.bam_init1) != -1
+        record = Record.new(bam1, header)
+        yield record
+      end
+      self
+    end
   end
 end

data/lib/hts/bcf/format.rb

@@ -8,22 +8,22 @@ module HTS
         @p1 = FFI::MemoryPointer.new(:pointer) # FIXME: naming
       end
 
-      # For compatibility with htslib.cr.
+      # For compatibility with HTS.cr.
       def get_int(key)
         get(key, :int)
       end
 
-      # For compatibility with htslib.cr.
+      # For compatibility with HTS.cr.
       def get_float(key)
         get(key, :float)
       end
 
-      # For compatibility with htslib.cr.
+      # For compatibility with HTS.cr.
       def get_flag(key)
         get(key, :flag)
       end
 
-      # For compatibility with htslib.cr.
+      # For compatibility with HTS.cr.
       def get_string(key)
         get(key, :string)
       end

data/lib/hts/bcf/header.rb

@@ -1,11 +1,24 @@
 # frozen_string_literal: true
 
+require_relative "header_record"
+
 module HTS
   class Bcf < Hts
     # A class for working with VCF records.
+    # NOTE: This class has a lot of methods that are not stable.
+    # The method names and the number of arguments may change in the future.
     class Header
-      def initialize(hts_file)
-        @bcf_hdr = LibHTS.bcf_hdr_read(hts_file)
+      def initialize(arg = nil)
+        case arg
+        when LibHTS::HtsFile
+          @bcf_hdr = LibHTS.bcf_hdr_read(arg)
+        when LibHTS::BcfHdr
+          @bcf_hdr = arg
+        when nil
+          @bcf_hdr = LibHTS.bcf_hdr_init("w")
+        else
+          raise TypeError, "Invalid argument"
+        end
       end
 
       def struct
@@ -20,6 +33,10 @@ module HTS
         LibHTS.bcf_hdr_get_version(@bcf_hdr)
       end
 
+      def set_version(version)
+        LibHTS.bcf_hdr_set_version(@bcf_hdr, version)
+      end
+
       def nsamples
         LibHTS.bcf_hdr_nsamples(@bcf_hdr)
       end
@@ -31,6 +48,45 @@ module HTS
           .map(&:read_string)
       end
 
+      def add_sample(sample, sync: true)
+        LibHTS.bcf_hdr_add_sample(@bcf_hdr, sample)
+        self.sync if sync
+      end
+
+      def merge(hdr)
+        LibHTS.bcf_hdr_merge(@bcf_hdr, hdr.struct)
+      end
+
+      def sync
+        LibHTS.bcf_hdr_sync(@bcf_hdr)
+      end
+
+      def read_bcf(fname)
+        LibHTS.bcf_hdr_set(@bcf_hdr, fname)
+      end
+
+      def append(line)
+        LibHTS.bcf_hdr_append(@bcf_hdr, line)
+      end
+
+      def delete(bcf_hl_type, key) # FIXME
+        type = bcf_hl_type_to_int(bcf_hl_type)
+        LibHTS.bcf_hdr_remove(@bcf_hdr, type, key)
+      end
+
+      def get_hrec(bcf_hl_type, key, value, str_class = nil)
+        type = bcf_hl_type_to_int(bcf_hl_type)
+        hrec = LibHTS.bcf_hdr_get_hrec(@bcf_hdr, type, key, value, str_class)
+        HeaderRecord.new(hrec)
+      end
+
+      def seqnames
+        n = FFI::MemoryPointer.new(:int)
+        names = LibHTS.bcf_hdr_seqnames(@bcf_hdr, n)
+        names.read_array_of_pointer(n.read_int)
+             .map(&:read_string)
+      end
+
       def to_s
         kstr = LibHTS::KString.new
         raise "Failed to get header string" unless LibHTS.bcf_hdr_format(@bcf_hdr, 0, kstr)
@@ -40,6 +96,27 @@ module HTS
 
       private
 
+      def bcf_hl_type_to_int(bcf_hl_type)
+        return bcf_hl_type if bcf_hl_type.is_a?(Integer)
+
+        case bcf_hl_type.to_s.upcase
+        when "FILTER", "FIL"
+          LibHTS::BCF_HL_FLT
+        when "INFO"
+          LibHTS::BCF_HL_INFO
+        when "FORMAT", "FMT"
+          LibHTS::BCF_HL_FMT
+        when "CONTIG", "CTG"
+          LibHTS::BCF_HL_CTG
+        when "STRUCTURED", "STR"
+          LibHTS::BCF_HL_STR
+        when "GENOTYPE", "GEN"
+          LibHTS::BCF_HL_GEN
+        else
+          raise TypeError, "Invalid argument"
+        end
+      end
+
       def initialize_copy(orig)
         @bcf_hdr = LibHTS.bcf_hdr_dup(orig.struct)
       end

data/lib/hts/bcf/header_record.rb

@@ -3,9 +3,43 @@
 module HTS
   class Bcf < Hts
     class HeaderRecord
-      def initialize
+      def initialize(arg = nil)
+        case arg
+        when LibHTS::BcfHrec
+          @bcf_hrec = arg
+        else
+          raise TypeError, "Invalid argument"
+        end
+      end
+
+      def struct
         @bcf_hrec
       end
+
+      def add_key(key)
+        LibHTS.bcf_hrec_add_key(@bcf_hrec, key, key.length)
+      end
+
+      def set_value(i, val, quote: true)
+        is_quoted = quote ? 1 : 0
+        LibHTS.bcf_hrec_set_val(@bcf_hrec, i, val, val.length, is_quoted)
+      end
+
+      def find_key(key)
+        LibHTS.bcf_hrec_find_key(@bcf_hrec, key)
+      end
+
+      def to_s
+        kstr = LibHTS::KString.new
+        LibHTS.bcf_hrec_format(@bcf_hrec, kstr)
+        kstr[:s]
+      end
+
+      private
+
+      def initialize_copy(orig)
+        @bcf_hrec = LibHTS.bcf_hrec_dup(orig.struct)
+      end
     end
   end
 end

data/lib/hts/bcf/info.rb

@@ -9,22 +9,22 @@ module HTS
         @p1 = FFI::MemoryPointer.new(:pointer) # FIXME: naming
       end
 
-      # For compatibility with htslib.cr.
+      # For compatibility with HTS.cr.
       def get_int(key)
         get(key, :int)
       end
 
-      # For compatibility with htslib.cr.
+      # For compatibility with HTS.cr.
       def get_float(key)
         get(key, :float)
       end
 
-      # For compatibility with htslib.cr.
+      # For compatibility with HTS.cr.
       def get_string(key)
         get(key, :string)
       end
 
-      # For compatibility with htslib.cr.
+      # For compatibility with HTS.cr.
       def get_flag(key)
         get(key, :flag)
       end

data/lib/hts/bcf.rb

@@ -52,7 +52,6 @@ module HTS
       build_index(index) if build_index
       @idx = load_index(index)
       @start_position = tell
-      super # do nothing
     end
 
     def build_index(index_name = nil, min_shift: 14)
@@ -85,11 +84,16 @@ module HTS
       !@idx.null?
     end
 
-    def write_header
+    def close
+      LibHTS.hts_idx_destroy(@idx) unless @idx&.null?
+      @idx = nil
+      super
+    end
+
+    def write_header(header)
       check_closed
 
       @header = header.dup
-      LibHTS.hts_set_fai_filename(header, @file_name)
       LibHTS.bcf_hdr_write(@hts_file, header)
     end
 
@@ -97,7 +101,8 @@ module HTS
       check_closed
 
       var_dup = var.dup
-      LibHTS.bcf_write(@hts_file, header, var_dup) > 0 || raise
+      r = LibHTS.bcf_write(@hts_file, header, var_dup)
+      raise "Failed to write record" if r < 0
     end
 
     # Close the current file.
@@ -122,29 +127,6 @@ module HTS
       end
     end
 
-    private def each_record_copy
-      check_closed
-
-      return to_enum(__method__) unless block_given?
-
-      while LibHTS.bcf_read(@hts_file, header, bcf1 = LibHTS.bcf_init) != -1
-        record = Record.new(bcf1, header)
-        yield record
-      end
-      self
-    end
-
-    private def each_record_reuse
-      check_closed
-
-      return to_enum(__method__) unless block_given?
-
-      bcf1 = LibHTS.bcf_init
-      record = Record.new(bcf1, header)
-      yield record while LibHTS.bcf_read(@hts_file, header, bcf1) != -1
-      self
-    end
-
     def query(...)
       querys(...) # Fixme
     end
@@ -166,55 +148,6 @@ module HTS
     # private def queryi_reuse
     # end
 
-    private def querys_copy(region)
-      check_closed
-
-      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?
-      return to_enum(__method__, region) unless block_given?
-
-      qitr = LibHTS.bcf_itr_querys(@idx, header, region)
-
-      begin
-        loop do
-          bcf1 = LibHTS.bcf_init
-          slen = LibHTS.hts_itr_next(@hts_file[:fp][:bgzf], qitr, bcf1, ::FFI::Pointer::NULL)
-          break if slen == -1
-          raise if slen < -1
-
-          yield Record.new(bcf1, header)
-        end
-      ensure
-        LibHTS.bcf_itr_destroy(qitr)
-      end
-      self
-    end
-
-    private def querys_reuse(region)
-      check_closed
-
-      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?
-      return to_enum(__method__, region) unless block_given?
-
-      qitr = LibHTS.bcf_itr_querys(@idx, header, region)
-
-      bcf1 = LibHTS.bcf_init
-      record = Record.new(bcf1, header)
-      begin
-        loop do
-          slen = LibHTS.hts_itr_next(@hts_file[:fp][:bgzf], qitr, bcf1, ::FFI::Pointer::NULL)
-          break if slen == -1
-          raise if slen < -1
-
-          yield record
-        end
-      ensure
-        LibHTS.bcf_itr_destroy(qitr)
-      end
-      self
-    end
-
     # @!macro [attach] define_getter
     #   @method $1
     #   Get $1 array
@@ -285,5 +218,81 @@ module HTS
         yield r.format(key)
       end
     end
+
+    private
+
+    def querys_reuse(region)
+      check_closed
+
+      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?
+      return to_enum(__method__, region) unless block_given?
+
+      qiter = LibHTS.bcf_itr_querys(@idx, header, region)
+      raise "Failed to query region #{region}" if qiter.null?
+
+      bcf1 = LibHTS.bcf_init
+      record = Record.new(bcf1, header)
+      begin
+        loop do
+          slen = LibHTS.hts_itr_next(@hts_file[:fp][:bgzf], qiter, bcf1, ::FFI::Pointer::NULL)
+          break if slen == -1
+          raise if slen < -1
+
+          yield record
+        end
+      ensure
+        LibHTS.bcf_itr_destroy(qiter)
+      end
+      self
+    end
+
+    def querys_copy(region)
+      check_closed
+
+      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?
+      return to_enum(__method__, region) unless block_given?
+
+      qiter = LibHTS.bcf_itr_querys(@idx, header, region)
+      raise "Failed to query region #{region}" if qiter.null?
+
+      begin
+        loop do
+          bcf1 = LibHTS.bcf_init
+          slen = LibHTS.hts_itr_next(@hts_file[:fp][:bgzf], qiter, bcf1, ::FFI::Pointer::NULL)
+          break if slen == -1
+          raise if slen < -1
+
+          yield Record.new(bcf1, header)
+        end
+      ensure
+        LibHTS.bcf_itr_destroy(qiter)
+      end
+      self
+    end
+
+    def each_record_reuse
+      check_closed
+
+      return to_enum(__method__) unless block_given?
+
+      bcf1 = LibHTS.bcf_init
+      record = Record.new(bcf1, header)
+      yield record while LibHTS.bcf_read(@hts_file, header, bcf1) != -1
+      self
+    end
+
+    def each_record_copy
+      check_closed
+
+      return to_enum(__method__) unless block_given?
+
+      while LibHTS.bcf_read(@hts_file, header, bcf1 = LibHTS.bcf_init) != -1
+        record = Record.new(bcf1, header)
+        yield record
+      end
+      self
+    end
   end
 end

data/lib/hts/hts.rb

@@ -31,8 +31,8 @@ module HTS
       end
     end
 
-    def initialize(*args)
-      # do nothing
+    def initialize(*_args)
+      raise TypeError, "Can't make instance of HTS abstract class"
     end
 
     def struct

data/lib/hts/libhts/constants.rb

@@ -188,6 +188,10 @@ module HTS
           :n_mapped,     :uint64,
           :n_unmapped,   :uint64
         )
+
+      def self.release(ptr)
+        LibHTS.hts_idx_destroy(ptr) unless ptr.null?
+      end
     end
 
     class HtsReglist < FFI::Struct
@@ -213,6 +217,10 @@ module HTS
         :sdict,          :pointer,
         :hrecs,          :pointer,
         :ref_count,      :uint32
+
+      def self.release(ptr)
+        LibHTS.sam_hdr_destroy(ptr) unless ptr.null?
+      end
     end
 
     BamHdr = SamHdr
@@ -251,6 +259,10 @@ module HTS
       layout \
         :pool,           :pointer,
         :qsize,          :int
+
+      def self.release(ptr)
+        LibHTS.hts_tpool_destroy(ptr) unless ptr.null?
+      end
     end
 
     class HtsOpt < FFI::Struct
@@ -300,6 +312,10 @@ module HTS
                  :nocoor,    1,
                  :multi,     1,
                  :dummy,     27
+
+      def self.release(ptr)
+        LibHTS.hts_itr_destroy(ptr) unless ptr.null?
+      end
     end
 
     class Bam1Core < FFI::Struct
@@ -380,6 +396,10 @@ module HTS
         :conf,           TbxConf.ptr,
         :idx,            HtsIdx.ptr,
         :dict,           :pointer
+
+      def self.release(ptr)
+        LibHTS.tbx_destroy(ptr) unless ptr.null?
+      end
     end
 
     # faidx
@@ -393,6 +413,10 @@ module HTS
              :name,      :pointer,
              :hash,      :pointer,
              :format,    FaiFormatOptions
+
+      def self.release(ptr)
+        LibHTS.fai_destroy(ptr) unless ptr.null?
+      end
     end
 
     # bcf
@@ -412,6 +436,10 @@ module HTS
         :nkeys,          :int,
         :keys,           :pointer,
         :vals,           :pointer
+
+      def self.release(ptr)
+        LibHTS.bcf_hrec_destroy(ptr) unless ptr.null?
+      end
     end
 
     class BcfInfo < FFI::BitStruct
@@ -461,6 +489,10 @@ module HTS
         :keep_samples,   :pointer,
         :mem,            KString,
         :m,              [:int, 3]
+
+      def self.release(ptr)
+        LibHTS.bcf_hdr_destroy(ptr) unless ptr.null?
+      end
     end
 
     class BcfFmt < FFI::BitStruct

data/lib/hts/libhts/tbx_funcs.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module HTS
   module LibHTS
     class << self

data/lib/hts/libhts/vcf_funcs.rb

@@ -294,15 +294,23 @@ module HTS
       end
 
       # Typed value I/O
-      def bcf_int8_vector_end  = -127                       # INT8_MIN  + 1
-      def bcf_int16_vector_end = -32_767                    # INT16_MIN + 1
-      def bcf_int32_vector_end = -2_147_483_647             # INT32_MIN + 1
-      def bcf_int64_vector_end = -9_223_372_036_854_775_807 # INT64_MIN + 1
+      # INT8_MIN  + 1
+      def bcf_int8_vector_end  = -127
+      # INT16_MIN + 1
+      def bcf_int16_vector_end = -32_767
+      # INT32_MIN + 1
+      def bcf_int32_vector_end = -2_147_483_647
+      # INT64_MIN + 1
+      def bcf_int64_vector_end = -9_223_372_036_854_775_807
       def bcf_str_vector_end   = 0
-      def bcf_int8_missing     = -128                             # INT8_MIN
-      def bcf_int16_missing    = (-32_767 - 1)                    # INT16_MIN
-      def bcf_int32_missing    = (-2_147_483_647 - 1)             # INT32_MIN
-      def bcf_int64_missing    = (-9_223_372_036_854_775_807 - 1) # INT64_MIN
+      # INT8_MIN
+      def bcf_int8_missing     = -128
+      # INT16_MIN
+      def bcf_int16_missing    = (-32_767 - 1)
+      # INT32_MIN
+      def bcf_int32_missing    = (-2_147_483_647 - 1)
+      # INT64_MIN
+      def bcf_int64_missing    = (-9_223_372_036_854_775_807 - 1)
       def bcf_str_missing      = 0x07
 
       BCF_MAX_BT_INT8  = 0x7f           # INT8_MAX  */

data/lib/hts/tbx.rb

@@ -45,8 +45,6 @@ module HTS
 
       # build_index(index) if build_index
       @idx = load_index(index)
-
-      super # do nothing
     end
 
     def build_index
@@ -68,9 +66,7 @@ module HTS
     def seqnames
       nseq = FFI::MemoryPointer.new(:int)
       LibHTS.tbx_seqnames(@idx, nseq).then do |pts|
-        pts.read_array_of_pointer(nseq.read_int).map do |pt|
-          pt.read_string
-        end
+        pts.read_array_of_pointer(nseq.read_int).map(&:read_string)
       end
     end
   end

data/lib/hts/version.rb

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

data/lib/htslib.rb

@@ -52,6 +52,7 @@ module HTS
   # before calling the LibHTS module.
   autoload :LibHTS, "hts/libhts"
 
+  autoload :Hts,    "hts/hts"
   autoload :Bam,    "hts/bam"
   autoload :Bcf,    "hts/bcf"
   autoload :Tbx,    "hts/tbx"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: htslib
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  version: 0.2.5
 platform: ruby
 authors:
 - kojix2
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-09-03 00:00:00.000000000 Z
+date: 2022-10-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ffi
@@ -136,6 +136,7 @@ files:
 - lib/hts/bam/cigar.rb
 - lib/hts/bam/flag.rb
 - lib/hts/bam/header.rb
+- lib/hts/bam/header_record.rb
 - lib/hts/bam/record.rb
 - lib/hts/bcf.rb
 - lib/hts/bcf/format.rb