Adjust subcommand, output writing for basic BED, reporting API

 - granges_adjust and adjust subcommand
 - random granges
 - dev-commands feature & RandomBed
 - to_bed3()
 - empty range iterator
 - cleaner output to standard out
 - reporting API
 - TSV trait and impls

Cargo.toml

@@ -22,8 +22,10 @@ noodles = { version = "0.63.0", features = ["core", "bed"] }
 rand = "0.8.5"
 thiserror = "1.0.57"
 
-# [features]
-# cli = [ "clap" ]
+[features]
+# cli = [ "clap" ] // TODO make feature
+dev-commands = [ ]
+
 
 [[bin]]
 name = "granges"

src/error.rs

@@ -1,4 +1,4 @@
-use std::num::{ParseIntError, ParseFloatError};
+use std::num::{ParseFloatError, ParseIntError};
 
 use genomap::GenomeMapError;
 use thiserror::Error;

src/granges.rs

@@ -1,15 +1,19 @@
+use std::path::PathBuf;
+
 use genomap::GenomeMap;
 use indexmap::IndexMap;
 
 use crate::{
+    io::OutputFile,
+    iterators::{GRangesEmptyIterator, GRangesIterator},
     prelude::GRangesError,
     ranges::{
         coitrees::{COITrees, COITreesIndexed},
         vec::{VecRanges, VecRangesEmpty, VecRangesIndexed},
         RangeEmpty, RangeIndexed, RangeRecord,
     },
-    traits::{RangeContainer, RangesIterable},
-    Position, iterators::GRangesIterator,
+    traits::{RangeContainer, RangesIterable, TsvSerialize},
+    Position,
 };
 
 #[derive(Clone, Debug)]
@@ -145,6 +149,27 @@ impl GRanges<VecRangesEmpty, ()> {
     }
 }
 
+impl<R> GRanges<R, ()>
+where
+    R: RangeContainer + RangesIterable<RangeEmpty>,
+{
+    // TODO: candidate for a trait
+    pub fn to_bed3(&self, output: Option<impl Into<PathBuf>>) -> Result<(), GRangesError> {
+        // output stream -- header is None for now (TODO)
+        let output = output.map_or(OutputFile::new_stdout(None), |file| {
+            OutputFile::new(file, None)
+        });
+        let mut writer = output.writer()?;
+
+        let seqnames = self.seqnames();
+        for range in self.iter_ranges_empty() {
+            let record = range.to_record(&seqnames);
+            writeln!(writer, "{}", record.to_tsv())?;
+        }
+        Ok(())
+    }
+}
+
 impl<T> GRanges<VecRangesIndexed, T> {
     /// Convert this [`VecRangesIndexed`] range container to a cache-oblivious interval tree  
     /// range container, [`COITreesIndexed`]. This is done using the [`coitrees`] library
@@ -163,10 +188,25 @@ impl<T> GRanges<VecRangesIndexed, T> {
     }
 }
 
-impl<R, T> GRanges<R, T> 
-where R: RangesIterable<RangeIndexed> {
+impl<R, T> GRanges<R, T>
+where
+    R: RangesIterable<RangeEmpty>,
+{
+    /// Create a new [`GRangesIterator`] to iterate through all
+    /// the ranges in this [`GRanges`] object. These ranges carry
+    /// no data index, unlike the method [`GRanges.iter_ranges()`]
+    /// available for range type for associated data containers.
+    pub fn iter_ranges_empty(&self) -> GRangesEmptyIterator<'_, R> {
+        GRangesEmptyIterator::new(&self.ranges)
+    }
+}
+
+impl<R, T> GRanges<R, T>
+where
+    R: RangesIterable<RangeIndexed>,
+{
     /// Create a new [`GRangesIterator`] to iterate through all the ranges in this [`GRanges`] object.
-    pub fn iter_ranges<'a>(&'a self) -> GRangesIterator<'a, R> {
+    pub fn iter_ranges(&self) -> GRangesIterator<'_, R> {
         GRangesIterator::new(&self.ranges)
     }
 }

src/io/io.rs → src/io/file.rs

@@ -13,11 +13,13 @@ use std::io::{self, BufWriter};
 use std::io::{BufRead, BufReader, Read};
 use std::path::PathBuf;
 
-use crate::Position;
 use crate::error::GRangesError;
+use crate::Position;
 
 /// Read a tab-delimited *genome file* of sequence (i.e. chromosome) names and their lengths.
-pub fn read_seqlens(filepath: impl Into<PathBuf>) -> Result<IndexMap<String, Position>, GRangesError> {
+pub fn read_seqlens(
+    filepath: impl Into<PathBuf>,
+) -> Result<IndexMap<String, Position>, GRangesError> {
     let input_file = InputFile::new(filepath);
     let reader = input_file.reader()?;
 
@@ -136,12 +138,17 @@ impl InputFile {
     }
 }
 
+enum OutputDestination {
+    File(PathBuf),
+    Stdout,
+}
+
 /// Represents an output file.
 ///
 /// This struct is used to handle operations on an output file, such as writing to the file.
 /// This abstracts writing both plaintext and gzip-compressed files.
 pub struct OutputFile {
-    pub filepath: PathBuf,
+    destination: OutputDestination,
     pub header: Option<Vec<String>>,
 }
 
@@ -155,7 +162,15 @@ impl OutputFile {
     /// * `header` - An optional vector of strings representing commented header lines to be written to the file.
     pub fn new(filepath: impl Into<PathBuf>, header: Option<Vec<String>>) -> Self {
         Self {
-            filepath: filepath.into(),
+            destination: OutputDestination::File(filepath.into()),
+            header,
+        }
+    }
+
+    /// Constructs a new [`OutputFile`] for standard output.
+    pub fn new_stdout(header: Option<Vec<String>>) -> Self {
+        Self {
+            destination: OutputDestination::Stdout,
             header,
         }
     }
@@ -170,15 +185,19 @@ impl OutputFile {
     ///
     /// A result containing a `Box<dyn Write>` on success, or an `io::Error` on failure.
     pub fn writer(&self) -> io::Result<Box<dyn Write>> {
-        let outfile = &self.filepath;
-        let is_gzip = outfile.ends_with(".gz");
-        let mut writer: Box<dyn Write> = if is_gzip {
-            Box::new(BufWriter::new(GzEncoder::new(
-                File::create(outfile)?,
-                Compression::default(),
-            )))
-        } else {
-            Box::new(BufWriter::new(File::create(outfile)?))
+        let mut writer: Box<dyn Write> = match &self.destination {
+            OutputDestination::File(path) => {
+                let is_gzip = path.ends_with(".gz");
+                if is_gzip {
+                    Box::new(BufWriter::new(GzEncoder::new(
+                        File::create(path)?,
+                        Compression::default(),
+                    )))
+                } else {
+                    Box::new(BufWriter::new(File::create(path)?))
+                }
+            }
+            OutputDestination::Stdout => Box::new(io::stdout()),
         };
         // write header if one is set
         if let Some(entries) = &self.header {

src/io/mod.rs

@@ -1,9 +1,9 @@
 //! Input/Output
 //!
 
-pub mod io;
+pub mod file;
 pub mod noodles;
 pub mod parsers;
 
-pub use io::{InputFile, OutputFile};
-pub use parsers::{Bed3RecordIterator, TsvRecordIterator, BedlikeIterator};
+pub use file::{InputFile, OutputFile};
+pub use parsers::{Bed3RecordIterator, BedlikeIterator, TsvRecordIterator};

src/io/parsers.rs

@@ -6,11 +6,11 @@ use std::collections::HashSet;
 use std::io::{BufRead, BufReader, Read};
 use std::path::PathBuf;
 
-use crate::Position;
 use crate::error::GRangesError;
-use crate::io::io::InputFile;
+use crate::io::file::InputFile;
 use crate::ranges::RangeRecord;
 use crate::traits::GeneralRangeRecordIterator;
+use crate::Position;
 
 use super::noodles::convert_noodles_position;
 
@@ -101,6 +101,7 @@ where
 
 /// A BED-like file parser. This works by lazy-parsing the first three
 /// columns, which are standard to all BED files.
+#[allow(clippy::type_complexity)]
 pub struct BedlikeIterator {
     iter: TsvRecordIterator<fn(&str) -> Result<RangeRecord<String>, GRangesError>, String>,
 }
@@ -109,7 +110,7 @@ impl BedlikeIterator {
     pub fn new(filepath: impl Into<PathBuf>) -> Result<Self, GRangesError> {
         // Wrap the parse_bedlike_to_range_record function to conform with TsvRecordIterator's expectations.
         let parser: fn(&str) -> Result<RangeRecord<String>, GRangesError> = parse_bed_lazy;
-        
+
         let iter = TsvRecordIterator::new(filepath, parser)?;
         Ok(Self { iter })
     }
@@ -123,8 +124,6 @@ impl Iterator for BedlikeIterator {
     }
 }
 
-
-
 /// An iterator over [`IntervalRecord`] items that filters based on sequence name.
 ///
 /// Note that that the exclude filter is prioritized over the retain filter. So,
@@ -282,7 +281,11 @@ pub fn parse_bed_lazy(line: &str) -> Result<RangeRecord<String>, GRangesError> {
     let start: Position = parse_column(columns[1], line)?;
     let end: Position = parse_column(columns[2], line)?;
 
-    let data = columns[3].to_string();
+    let data = if columns.len() > 3 {
+        columns[3].to_string()
+    } else {
+        String::new()
+    };
 
     Ok(RangeRecord {
         seqname,
@@ -312,7 +315,7 @@ mod tests {
         // let first_interval = gr_iter.next().unwrap();
         // assert_eq!(first_interval.first, 7);
         // assert_eq!(first_interval.last, 12);
-        // 
+        //
         // let second_interval = gr_iter.next().unwrap();
         // assert_eq!(second_interval.first, 20);
         // assert_eq!(second_interval.last, 33);
@@ -336,9 +339,6 @@ mod tests {
         // note: the Rust LSP thinks this isn't used for some reason, so prefaced with _
         // to silence warnings.
         let _msg = "column '-1' in 'chr1\t-1\t20'".to_string();
-        assert!(matches!(
-                result,
-                Err(GRangesError::InvalidColumnType(_msg))
-                ));
+        assert!(matches!(result, Err(GRangesError::InvalidColumnType(_msg))));
     }
 }

src/iterators.rs

@@ -1,11 +1,11 @@
 use genomap::GenomeMap;
 
 use crate::{
-    ranges::{RangeIndexed, RangeIndexedRecord},
+    ranges::{RangeEmpty, RangeEmptyRecord, RangeIndexed, RangeIndexedRecord},
     traits::{RangeContainer, RangesIterable},
 };
 
-/// An iterator over [`RangeIndexedRecord`], which store
+/// An iterator yielding [`RangeIndexedRecord`], which store
 /// indices to the sequence names and data container.
 ///
 /// # Developer Notes
@@ -63,6 +63,59 @@ where
     }
 }
 
+/// An iterator over [`RangeEmptyRecord`], which store
+/// indices to the sequence names (but carries no data index).
+pub struct GRangesEmptyIterator<'a, R> {
+    ranges: &'a GenomeMap<R>,
+    current_seqname_index: usize,
+    current_range_iter: Box<dyn Iterator<Item = RangeEmpty> + 'a>,
+}
+
+impl<'a, R> GRangesEmptyIterator<'a, R>
+where
+    R: RangesIterable<RangeEmpty>,
+{
+    pub fn new(ranges: &'a GenomeMap<R>) -> Self {
+        let current_range_iter = ranges.get_by_index(0).unwrap().iter_ranges();
+        Self {
+            ranges,
+            current_seqname_index: 0,
+            current_range_iter,
+        }
+    }
+}
+
+impl<'a, R> Iterator for GRangesEmptyIterator<'a, R>
+where
+    R: RangeContainer + RangesIterable<RangeEmpty>,
+{
+    type Item = RangeEmptyRecord;
+
+    fn next(&mut self) -> Option<Self::Item> {
+        loop {
+            if let Some(next_range) = self.current_range_iter.next() {
+                return Some(RangeEmptyRecord {
+                    seqname_index: self.current_seqname_index,
+                    start: next_range.start,
+                    end: next_range.end,
+                });
+            } else {
+                // try to load another sequence's set of ranges.
+                self.current_seqname_index += 1;
+                if self.current_seqname_index >= self.ranges.len() {
+                    // we're out of range container iterators
+                    return None;
+                }
+                self.current_range_iter = self
+                    .ranges
+                    .get_by_index(self.current_seqname_index)
+                    .unwrap()
+                    .iter_ranges();
+            }
+        }
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use crate::{ranges::RangeIndexedRecord, test_utilities::granges_test_case_01};

src/lib.rs

@@ -19,10 +19,13 @@ pub type PositionOffset = i32; // signed variant
 pub mod prelude {
     pub use crate::error::GRangesError;
     pub use crate::granges::GRanges;
-    pub use crate::io::{Bed3RecordIterator, TsvRecordIterator, BedlikeIterator};
+    pub use crate::io::file::read_seqlens;
+    pub use crate::io::{Bed3RecordIterator, BedlikeIterator, TsvRecordIterator};
 
     pub use crate::ranges::vec::{VecRangesEmpty, VecRangesIndexed};
-    pub use crate::traits::{GeneralRangeRecordIterator, RangesIntoIterable, RangesIterable};
+    pub use crate::traits::{
+        GeneralRangeRecordIterator, RangesIntoIterable, RangesIterable, TsvSerialize,
+    };
 
     pub use crate::seqlens;
 }