High-level wrappers for SAM header API

[charlesgregory]

Along with the new htslib changes in 1.10, there is a new SAM header API that we should wrap. I think getting compatibility in #35 is more important, but this is useful functionality that we should take advantage of.

[jblachly]

WIP: https://github.com/blachlylab/dhtslib/commit/0504a8023e7f9349e8943ca5f9a8f9a06c474b2c

[jblachly]

Implemented many new functions. Not implemented (will only implement ad hoc/PRN) include:

(apologies for vim cut n paste)

int sam_hdr_find_line_pos(sam_hdr_t *h, const char *type,                                                                 139                           int pos, kstring_t *ks);
140     */
141
142     /* int sam_hdr_remove_line_id(sam_hdr_t *h, const char *type, const char *ID_key, const char *ID_value); */
143
144     /* int sam_hdr_remove_line_pos(sam_hdr_t *h, const char *type, int position); */
145
146     /* int sam_hdr_update_line(sam_hdr_t *h, const char *type,
147         const char *ID_key, const char *ID_value, ...); */
148
149     /* int sam_hdr_remove_except(sam_hdr_t *h, const char *type, const char *ID_key, const char *ID_value); */
150
151     /* int sam_hdr_remove_lines(sam_hdr_t *h, const char *type, const char *id, void *rh); */
152
153     /+
154     int sam_hdr_count_lines(sam_hdr_t *h, const char *type);
155     int sam_hdr_line_index(sam_hdr_t *bh, const char *type, const char *key);
156     const char *sam_hdr_line_name(sam_hdr_t *bh, const char *type, int pos);
157     +/
158
159     //// //// int sam_hdr_find_tag_id(sam_hdr_t *h, const char *type, const char *ID_key, const char *ID_value, const char     *key, kstring_t *ks);

886 /*
 887  * Macros for changing the \@HD line. They eliminate the need to use NULL method arguments.
 888  */
 889
 890 /// Returns the SAM formatted text of the \@HD header line
 891 extern (D) auto sam_hdr_find_hd(T0, T1)(auto ref T0 h, auto ref T1 ks)
 892 {
 893     return sam_hdr_find_line_id(h, "HD", NULL, NULL, ks);
 894 }
 895
 896 /// Returns the value associated with a given \@HD line tag
 897 extern (D) auto sam_hdr_find_tag_hd(T0, T1, T2)(auto ref T0 h, auto ref T1 key, auto ref T2 ks)
 898 {
 899     return sam_hdr_find_tag_id(h, "HD", NULL, NULL, key, ks);
 900 }
 901
 902 /// Adds or updates tags on the header \@HD line
 903 extern (D) auto sam_hdr_update_hd(T, A...)(auto ref T h, auto ref A a)
 904 {                                                                                                                         905     // NOTE: This macro was dropped by dstep due to variadic args
 906     static assert (a.length %2 == 0);   // K-V pairs => even number of variadic args
 907     return sam_hdr_update_line(h, "HD", null, null, a, null);
 908 }
 909
 910 /// Removes the \@HD line tag with the given key
 911 extern (D) auto sam_hdr_remove_tag_hd(T0, T1)(auto ref T0 h, auto ref T1 key)
 912 {
 913     return sam_hdr_remove_tag_id(h, "HD", NULL, NULL, key);
 914 }

840 /// Generate a unique \@PG ID: value
 841 /*!
 842  * @param name  Name of the program. Eg. samtools
 843  * @return      Valid ID on success, NULL on failure
 844  *
 845  * Returns a unique ID from a base name.  The string returned will remain
 846  * valid until the next call to this function, or the header is destroyed.
 847  * The caller should not attempt to free() or realloc() it.
 848  */
 849 const(char)* sam_hdr_pg_id(sam_hdr_t* h, const(char)* name);
 850
 851 /// Add an \@PG line.
 852 /*!
 853  * @param name  Name of the program. Eg. samtools
 854  * @return      0 on success, -1 on failure
 855  *
 856  * If we wish complete control over this use sam_hdr_add_line() directly. This
 857  * function uses that, but attempts to do a lot of tedious house work for
 858  * you too.
 859  *
 860  * - It will generate a suitable ID if the supplied one clashes.
 861  * - It will generate multiple \@PG records if we have multiple PG chains.
 862  *
 863  * Call it as per sam_hdr_add_line() with a series of key,value pairs ending
 864  * in NULL.
 865  */
 866 int sam_hdr_add_pg(sam_hdr_t* h, const(char)* name, ...);