htslib 0.2.2 → 0.2.5

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
@@ -195,7 +199,7 @@ module HTS
         :reg,            :string,
         :intervals,      :pointer, # hts_pair_pos_t
         :tid,            :int,
-        :count,          :uint32_t,
+        :count,          :uint32,
         :min_beg,        :hts_pos_t,
         :max_end,        :hts_pos_t
     end
@@ -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
@@ -352,7 +368,7 @@ module HTS
         :qpos,           :int32_t,
         :indel,          :int,
         :level,          :int,
-        :_flags,         :uint32_t, # bit_fields
+        :_flags,         :uint32, # bit_fields
         :cd,             BamPileupCd,
         :cigar_ind,      :int
 
@@ -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
@@ -506,8 +538,8 @@ module HTS
         :rlen,           :hts_pos_t,
         :rid,            :int32_t,
         :qual,           :float,
-        :_n_info_allele, :uint32_t,
-        :_n_fmt_sample,  :uint32_t,
+        :_n_info_allele, :uint32,
+        :_n_fmt_sample,  :uint32,
         :shared,         KString,
         :indiv,          KString,
         :d,              BcfDec,

data/lib/hts/libhts/cram.rb

@@ -7,6 +7,8 @@ module HTS
     typedef :pointer, :cram_block
     typedef :pointer, :cram_metrics
 
+    # cram_fd
+
     attach_function \
       :cram_fd_get_header,
       [:cram_fd],
@@ -82,6 +84,8 @@ module HTS
       [:cram_fd],
       :int
 
+    # cram_block
+
     attach_function \
       :cram_block_get_content_id,
       [:cram_block],
@@ -157,71 +161,88 @@ module HTS
       %i[cram_block size_t],
       :void
 
+    # Computes the size of a cram block, including the block header itself.
     attach_function \
       :cram_block_size,
       [:cram_block],
       :uint32
 
+    # Renumbers RG numbers in a cram compression header.
     attach_function \
       :cram_transcode_rg,
       %i[cram_fd cram_fd cram_container int pointer pointer],
       :int
 
+    # Copies the blocks representing the next num_slice slices from a
+    # container from 'in' to 'out'.
     attach_function \
       :cram_copy_slice,
       %i[cram_fd cram_fd int32],
       :int
 
+    # Returns the number of cram blocks within this slice.
     attach_function \
       :cram_slice_hdr_get_num_blocks,
       [:pointer],
       :int32
 
+    # Returns the block content_id for the block containing an embedded
+    # reference sequence.
     attach_function \
       :cram_slice_hdr_get_embed_ref_id,
       [:pointer],
       :int
 
+    # Returns slice reference ID, start and span (length) coordinates.
     attach_function \
       :cram_slice_hdr_get_coords,
       %i[pointer pointer pointer pointer],
       :void
 
+    # Decodes a slice header from a cram block.
     attach_function \
       :cram_decode_slice_header,
       %i[pointer pointer],
       :pointer
 
+    # Frees a cram_block_slice_hdr structure.
     attach_function \
       :cram_free_slice_header,
       [:pointer],
       :void
 
+    # Allocates a new cram_block structure with a specified content_type
+    # and id.
     attach_function \
       :cram_new_block,
       [CramContentType, :int],
       :cram_block
 
+    # Reads a block from a cram file.
     attach_function \
       :cram_read_block,
       [:cram_fd],
       :cram_block
 
+    # Writes a CRAM block.
     attach_function \
       :cram_write_block,
       %i[cram_fd cram_block],
       :int
 
+    # Frees a CRAM block, deallocating internal data too.
     attach_function \
       :cram_free_block,
       [:cram_block],
       :void
 
+    # Uncompresses a CRAM block, if compressed.
     attach_function \
       :cram_uncompress_block,
       [:cram_block],
       :int
 
+    # Compresses a block.
     attach_function \
       :cram_compress_block,
       %i[cram_fd cram_block cram_metrics int int],
@@ -232,6 +253,8 @@ module HTS
     #   %i[cram_fd cram_slice cram_block cram_metrics int int],
     #   :int
 
+    # Creates a new container, specifying the maximum number of slices
+    # and records permitted.
     attach_function \
       :cram_new_container,
       %i[int int],
@@ -242,16 +265,20 @@ module HTS
       [:cram_container],
       :void
 
+    # Reads a container header.
     attach_function \
       :cram_read_container,
       [:cram_fd],
       :cram_container
 
+    # Writes a container structure.
     attach_function \
       :cram_write_container,
       %i[cram_fd cram_container],
       :int
 
+    # Stores the container structure in dat and returns *size as the
+    # number of bytes written to dat[].
     attach_function \
       :cram_store_container,
       %i[cram_fd cram_container string pointer],
@@ -262,61 +289,73 @@ module HTS
       [:cram_container],
       :int
 
+    # Opens a CRAM file for read (mode "rb") or write ("wb").
     attach_function \
       :cram_open,
       %i[string string],
       :cram_fd
 
+    # Opens an existing stream for reading or writing.
     attach_function \
       :cram_dopen,
       %i[pointer string string],
       :cram_fd
 
+    # Closes a CRAM file.
     attach_function \
       :cram_close,
       [:cram_fd],
       :int
 
+    # Seek within a CRAM file.
     attach_function \
       :cram_seek,
       %i[pointer off_t int],
       :int # FIXME: pointer should be :cram_fd
 
+    # Flushes a CRAM file.
     attach_function \
       :cram_flush,
       [:cram_fd],
       :int
 
+    # Checks for end of file on a cram_fd stream.
     attach_function \
       :cram_eof,
       [:cram_fd],
       :int
 
+    # Sets options on the cram_fd.
     attach_function \
       :cram_set_option,
       [:cram_fd, HtsFmtOption, :varargs],
       :int
 
+    # Sets options on the cram_fd.
     attach_function \
       :cram_set_voption,
       [:cram_fd, HtsFmtOption, :pointer], # va_list
       :int
 
+    # Attaches a header to a cram_fd.
     attach_function \
       :cram_set_header,
       [:cram_fd, SamHdr.by_ref],
       :int
 
+    # Check if this file has a proper EOF block
     attach_function \
       :cram_check_EOF,
       [:cram_fd],
       :int
 
+    # As int32_decoded/encode, but from/to blocks instead of cram_fd
     attach_function \
       :int32_put_blk,
       %i[cram_block int32_t],
       :int
 
+    # Returns the refs_t structure used by a cram file handle.
     attach_function \
       :cram_get_refs,
       [HtsFile.by_ref],

data/lib/hts/libhts/sam_funcs.rb

@@ -58,58 +58,72 @@ module HTS
     # macros
     # function-like macros
     class << self
+      # Get whether the query is on the reverse strand
       def bam_is_rev(b)
         b[:core][:flag] & BAM_FREVERSE != 0
       end
 
+      # Get whether the query's mate is on the reverse strand
       def bam_is_mrev(b)
         b[:core][:flag] & BAM_FMREVERSE != 0
       end
 
+      # Get the name of the query
       def bam_get_qname(b)
         b[:data]
       end
 
+      # Get the CIGAR array
       def bam_get_cigar(b)
         b[:data] + b[:core][:l_qname]
       end
 
+      # Get query sequence
       def bam_get_seq(b)
         b[:data] + (b[:core][:n_cigar] << 2) + b[:core][:l_qname]
       end
 
+      # Get query quality
       def bam_get_qual(b)
         b[:data] + (b[:core][:n_cigar] << 2) + b[:core][:l_qname] + ((b[:core][:l_qseq] + 1) >> 1)
       end
 
+      # Get auxiliary data
       def bam_get_aux(b)
         b[:data] + (b[:core][:n_cigar] << 2) + b[:core][:l_qname] + ((b[:core][:l_qseq] + 1) >> 1) + b[:core][:l_qseq]
       end
 
+      # Get length of auxiliary data
       def bam_get_l_aux(b)
         b[:l_data] - (b[:core][:n_cigar] << 2) - b[:core][:l_qname] - b[:core][:l_qseq] - ((b[:core][:l_qseq] + 1) >> 1)
       end
 
+      # Get a base on read
       def bam_seqi(s, i)
         (s[i >> 1].read_uint8 >> ((~i & 1) << 2)) & 0xf
       end
 
+      # Modifies a single base in the bam structure.
       def bam_set_seqi(s, i, b)
         s[i >> 1] = (s[i >> 1] & (0xf0 >> ((~i & 1) << 2))) | ((b) << ((~i & 1) << 2))
       end
 
+      # Returns the SAM formatted text of the \@HD header line
       def sam_hdr_find_hd(h, ks)
         sam_hdr_find_line_id(h, "HD", nil, nil, ks)
       end
 
+      # Returns the value associated with a given \@HD line tag
       def sam_hdr_find_tag_hd(h, key, ks)
         sam_hdr_find_tag_id(h, "HD", nil, nil, key, ks)
       end
 
+      # Adds or updates tags on the header \@HD line
       def sam_hdr_update_hd(h, *args)
         sam_hdr_update_line(h, "HD", nil, nil, *args, nil)
       end
 
+      # Removes the \@HD line tag with the given key
       def sam_hdr_remove_tag_hd(h, key)
         sam_hdr_remove_tag_id(h, "HD", nil, nil, key)
       end
@@ -122,6 +136,8 @@ module HTS
       alias bam_itr_querys sam_itr_querys
       alias bam_itr_next sam_itr_next
 
+      # Load/build .csi or .bai BAM index file.  Does not work with CRAM.
+      # It is recommended to use the sam_index_* functions below instead.
       def bam_index_load(fn)
         hts_idx_load(fn, HTS_FMT_BAI)
       end

data/lib/hts/libhts/tbx_funcs.rb

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