updated README

Author: lh3

README.md

@@ -1,64 +1,87 @@
-Bioawk is an extension to Brian Kernighan's awk acquired from [1], adding the
-support of several common biological data formats, including optionally gzip'ed
-BED, GFF, SAM, VCF, FASTA/Q and TAB-delimited formats with the column names. It
-also adds a few built-in functions including, as of now, and(), or(), xor(),
-reverse() and revcomp(). The following are a few examples demonstrating the new
-functionality:
+###Introduction
 
-0. List the supported format:
+Bioawk is an extension to [Brian Kernighan's awk][1], adding the support of
+several common biological data formats, including optionally gzip'ed BED, GFF,
+SAM, VCF, FASTA/Q and TAB-delimited formats with the column names. It also adds
+a few built-in functions and an command line option to use TAB as the
+input/output delimiter. When the new functionality is not used, bioawk is
+intended to behave exactly the same as the original BWK awk.
 
-   bioawk -c help
+###New functionality
 
-1. Extract unmapped reads without header:
+#####Command line option `-t`
 
-   bioawk -c sam 'and($flag,4)' aln.sam.gz
+Using this option is equivalent to
 
-2. Extract mapped reads with header:
+    bioawk -F'\t' -v OFS="\t"
 
-   bioawk -c sam -H '!and($flag,4)'
+#####Command line option `-c arg`
 
-3. Reverse complement FASTA:
+This option specifies the input format. When this option is in use, bioawk will
+seamlessly add variables that name the fields, based on either the format or
+the first line of the input, depending *arg*. This option also enables bioawk
+to read gzip'd files. The argument *arg* may take the following values:
 
-   bioawk -c fastx '{print ">"$name;print revcomp($seq)}' seq.fa.gz
+* `help`. List the supported formats and the naming variables.
 
-4. Create FASTA from SAM (uses revcomp if FLAG & 16)
+* `hdr` or `header`. Name each column based on the first line in the input.
+  Special characters in the first are converted to underscore. For example:
 
-   samtools view aln.bam | \
-      bioawk -c sam '{s=$seq; if(and($flag, 16)) {s=revcomp($seq)} print ">"$qname"\n"s}'
+        grep -v ^## in.vcf | bioawk -tc hdr '{print $_CHROM,$POS}'
 
-5. Get the %GC from FASTA:
+  prints the `CHROM` and `POS` columns of the input VCF file.
 
-   bioawk -c fastx '{print ">"$name;print gc($seq)}' seq.fa.gz
+* `sam`, `vcf`, `bed` and `gff`. SAM, VCF, BED and GFF formats.
 
-6. Get the mean Phred quality score from FASTQ:
+* `fastx`. This option regards a FASTA or FASTQ as a TAB delimited file with
+  four columns: sequence name, sequence, quality and FASTA/Q comment, such that
+  various fields can be retrieved with column names. See also example 4 in the
+  following.
 
-   bioawk -c fastx '{print ">"$name;print meanqual($qual)}' seq.fq.gz
+#####New built-in functions
 
-7. Take column name from the first line (where "age" appears in the first line
-   of input.txt):
+See `awk.1`.
 
-   bioawk -c header '{print $age}' input.txt
+###Examples
 
+1. List the supported formats:
 
-Note that when "-c" is not specified and the new built-in functions are not
-used, bioawk should behave exactly the same as the original BWK awk. At least
-this is the intention. Bioawk also tries to minimize the modification to the
-original code base such that improvements in the future versions of BWK awk
-can be readily incorporated into bioawk (yes, Brian Kernighan is still
-maintaining his code).
+        bioawk -c help
 
+2. Extract unmapped reads without header:
 
-Bioawk may have the following limitations:
+        bioawk -c sam 'and($flag,4)' aln.sam.gz
 
-1. To parse FASTA and FASTQ formats, bioawk replaces the line reading module of
-   awk, which also allows bioawk to seamlessly parse gzip'ed files. However,
-   the new line reading code does not fully mimic the original code. It may
-   fail in corner cases. Thus when "-c" is not specified, awk falls back to the
-   original line reading code and does not support gzip'ed input.
+3. Extract mapped reads with header:
 
-2. When "-c" is in use, several strings allocated in the new line reading
+        bioawk -Hc sam '!and($flag,4)'
+
+4. Reverse complement FASTA:
+
+        bioawk -c fastx '{print ">"$name;print revcomp($seq)}' seq.fa.gz
+
+5. Create FASTA from SAM (uses revcomp if FLAG & 16)
+
+        samtools view aln.bam | \
+            bioawk -c sam '{s=$seq; if(and($flag, 16)) {s=revcomp($seq)} print ">"$qname"\n"s}'
+
+6. Print the genotypes of sample `foo` and `bar` from a VCF:
+
+        grep -v ^## in.vcf | bioawk -tc hdr '{print $foo,$bar}'
+
+
+###Potential limitations
+
+1. When option `-c` is in use, bioawk replaces the line reading module of awk.
+   The new line reading function parses FASTA and FASTQ files and seamlessly
+   reads gzip'ed files. However, the new code does not fully mimic the original
+   code. It may fail in corner cases (though this has not happened yet). Thus
+   when `-c` is not specified, awk falls back to the original line reading code
+   and does not support gzip'ed input.
+
+2. When `-c` is in use, several strings allocated in the new line reading
    module are not freed in the end. These will be reported by valgrind as
-   "still reachable". To some extend, these are not memory leaks.
+   "still reachable". To some extent, these are not memory leaks.
 
 
-[1] http://www.cs.princeton.edu/~bwk/btl.mirror/
+[1]: http://www.cs.princeton.edu/~bwk/btl.mirror/

addon.c

@@ -217,7 +217,7 @@ Cell *bio_func(int f, Cell *x, Node **a)
 		if (v) { setfval(v, end); tempfree(v); }
 	} else if (f == BIO_FQUALCOUNT) {
 		if (a[1]->nnext == 0) {
-			WARNING("xor requires two arguments; returning 0.0");
+			WARNING("qualcount requires two arguments; returning 0.0");
 			setfval(y, 0.0);
 		} else {
 			char *buf;