small update

Don't throw away the right hand time of changes

Cargo.toml

@@ -1,5 +1,5 @@
 [package]
-name = "fastwave"
+name = "fastwave_backend"
 version = "0.1.0"
 edition = "2021"
 
@@ -10,7 +10,7 @@ debug = 1
 
 [dependencies]
 num = "0.4"
-clap = { version = "3.1.8", features = ["derive"] }
+clap = { version = "4.4.6", features = ["derive"] }
 chrono = "0.4"
 # TODO : remove itertools once date parser is reworked.
-itertools = "0.10.3"
+itertools = "0.11"

LICENSE-YEHOWSHUA

@@ -0,0 +1,2 @@
+This codebase is also licensed to Yehowshua Immanuel to use
+in any manner Yehowshua Immanuel sees fit.

README.md

@@ -1,7 +1,24 @@
-Copyright - Yehowshua Immanuel
+Copyright(2023) - Yehowshua Immanuel
+
+# Vision
+Imagine being able to visualize a CPU pipeline diagram by merely loading a simulation waveform dump, sprinkling in a bit of code, and dragging and dropping some diagram blocks into the visualizer. This project aims to offer such an experience.
+
+Since this project is written in Rust, it should also be able to run in the browser via web-assembly.
+
+# Status
+As of January 2024, work on the Fastwave Backend is stalled. It has been a fun journey watching Fastwave enable the first iterations of the [surfer waveform viewer](https://surfer-project.org). Now surfer uses an even better backend called [Wellen](https://github.com/ekiwi/wellen?tab=readme-ov-file). Go check it out! I hear it's really good. Perhaps I will soon archive the Fastwave Backend.
+
+Browser demo: https://app.surfer-project.org/
+
+Screenshot of surfer frontend below:
+<img width="1609" alt="image" src="https://github.com/ThePerfectComputer/FastWaveBackend/assets/103011002/63deffc0-98b0-405f-b093-74d10b422b01">
 
 # A High performance, VCD Parser written in Rust
 
+I hope for a GUI that eventually looks like the following...
+
+![](assets/FastWaveMockup.png)
+
 # Current Features
 
  - Robust Error Handling
@@ -35,6 +52,8 @@ slower.
 
 ## Results
 
+LZ4 should really improve memory usage once I add it. Note that GTKWave uses LZ4 on the fly.
+
 | Software | Time(s) | Memory(MB) |
 |----------|---------|------------|
 | FastWave | ~27.30  | 1100+      |
@@ -51,9 +70,11 @@ This repository comes with several smaller VCD files emitted from
 various EDA tools. If you want a larger VCD file, grab one from
 [here](https://drive.google.com/file/d/1pfm2qo2l8fGTHHJ8TLrg1vSGaV_TUbp2/view?usp=sharing).
 
+Here are some examples you can run:
 The first build of the program may take some time.
 
-``cargo run --release test-vcd-files/aldec/SPI_Write.vcd``
+1. ``cargo run --release --example parse_vcd tests/vcd-files/aldec/SPI_Write.vcd``
+2. ``cargo run --release --example vcd``
 
 You can run all the tests with ``cargo test``
 
@@ -62,26 +83,38 @@ You may wish to test the parser on a malformed VCD just to make
 sure that the parser gives useful/sane errors.
 
 Here's a command to test on a malformed VCD:
-`cargo run --release test-vcd-files/VCD_file_with_errors.vcd`
+``cargo run --release --example parse_vcd tests/vcd-files/VCD_file_with_errors.vcd``
 
 
 # TODO
 
 ## Features and Other
- - [ ] add timeline value scanner code
+ - [ ] add documenting comments
- - [ ] test against large waveform directly within SpinalHDL
+ - [ ] make signal query private until later?
+ - [ ] add signal query code to example once interface is finalized
+ - [ ] change crate name to vcd_fast_parse
+ - [ ] perhaps we should be looking up signal values on the VCD class
+ - [ ] perhaps we should be returning signal trees from the VCD class
+ - [ ] add lz4 compression support and compare memory perf before and after
+       - [ ] may need to refactor with allow for get_mut for dynamic
+             compression-decompression for multiple signal structs 
+             at once to allow for multi-threading
+ - [ ] test against large waveforms from the
+       [verilog-vcd-parser](https://github.com/ben-marshall/verilog-vcd-parser)
+       tool
  - [ ] (a bit of work) consolidate error messages in validation phase
- - [ ] be explicit with imports, remove exports as possible
+ - [ ] once the access patterns of the GUI frontend are well understood,
-       once FastWave is known to be fairly stable.
+       create specific functions and restrict as many types to private
- - [ ] do a read through all the code
+       as possible
-    - make contents of src/types.rs public as necessary.
  - [ ] Print out git commit or release number.
- - [ ] Take a look at GTKWave parser to compare efficiency.
+ - [ ] do a read through all the code - look for uneeded code
  - [ ] Move part of the performance section to another markdown file.
 
 ## Repairs
+ - [ ] replace str bracket indices with get(slice)
  - [ ] make a custom date parser for possibly up to 18 different versions(that is, for each possible tool).
  - [ ] Consolidate error messages and add cursors throughout.
+ - [ ] Add file and line to the enum errors.
  - [ ] Fix warnings especially usage and restriction warnings once I'm
        able to successfully parse all sample VCDs.
 
@@ -95,4 +128,4 @@ Here's a command to test on a malformed VCD:
  - [ ] Document indexing structure with diagram and possibly include the rational
 
 ## Marketing
- - [ ] Send survey to community 
+ - [ ] Send survey to community 

examples/parse_vcd.rs

@@ -0,0 +1,33 @@
+// Copyright (C) 2022 Yehowshua Immanuel
+// This program is distributed under both the GPLV3 license
+// and the YEHOWSHUA license, both of which can be found at
+// the root of the folder containing the sources for this program.
+use clap::Parser;
+use std::fs::File;
+
+use fastwave_backend::parse_vcd;
+
+#[derive(Parser)]
+struct Cli {
+    /// The path to the file to read
+    path: std::path::PathBuf,
+}
+
+fn main() -> std::io::Result<()> {
+    let args = Cli::parse();
+
+    use std::time::Instant;
+
+    let now = Instant::now();
+    let file = File::open(&args.path)?;
+    parse_vcd(file).unwrap();
+    let elapsed = now.elapsed();
+
+    println!(
+        "Parsed VCD file {} : {:.2?}",
+        &args.path.as_os_str().to_str().unwrap(),
+        elapsed
+    );
+
+    Ok(())
+}

examples/vcd.rs

@@ -0,0 +1,81 @@
+// Copyright (C) 2022 Yehowshua Immanuel
+// This program is distributed under both the GPLV3 license
+// and the YEHOWSHUA license, both of which can be found at
+// the root of the folder containing the sources for this program.
+use std::fs::File;
+
+use fastwave_backend::{parse_vcd, ScopeIdx, SignalIdx, VCD};
+
+fn indented_print(indent: u8, name: &String) {
+    for _ in 0..indent {
+        print!("  |");
+    }
+    print!("---");
+    println!("{name}");
+}
+
+// TODO: refactor into more general visitor pattern that takes a
+// function as an argument.
+fn visit_all_scopes(vcd: &VCD) {
+    fn visit_all_scope_children(root_idx: ScopeIdx, vcd: &VCD, indent: u8) {
+        if vcd.child_scopes_by_idx(root_idx).is_empty() {
+        } else {
+            for child_scope_idx in vcd.child_scopes_by_idx(root_idx) {
+                indented_print(indent, vcd.scope_name_by_idx(child_scope_idx));
+                for signal_idx in vcd.get_children_signal_idxs(child_scope_idx) {
+                    let signal = vcd.signal_from_signal_idx(signal_idx);
+                    let SignalIdx(idx) = signal_idx;
+                    indented_print(indent + 1, &format!("{},{}", signal.name(), idx));
+                }
+                visit_all_scope_children(child_scope_idx, vcd, indent + 1);
+            }
+        }
+    }
+    for root_scope_idx in vcd.root_scopes_by_idx() {
+        indented_print(0, vcd.scope_name_by_idx(root_scope_idx));
+        visit_all_scope_children(root_scope_idx, vcd, 1u8);
+    }
+}
+
+fn main() -> std::io::Result<()> {
+    use std::time::Instant;
+
+    // we start by printing out the entire signal tree of
+    // a parsed VCD
+    let now = Instant::now();
+    let file_path = "tests/vcd-files/icarus/CPU.vcd";
+    let file = File::open(file_path)?;
+    let vcd = parse_vcd(file).unwrap();
+    let elapsed = now.elapsed();
+    println!("Parsed VCD file {} : {:.2?}", file_path, elapsed);
+
+    println!("Printing Scopes");
+    visit_all_scopes(&vcd);
+    println!("Done Printing Scopes");
+    println!();
+
+    // we then parse another VCD, print its signal tree and
+    // query some values on its timeline
+    let now = Instant::now();
+    let file_path = "tests/vcd-files/amaranth/up_counter.vcd";
+    let file = File::open(file_path)?;
+    let vcd = parse_vcd(file).unwrap();
+    let elapsed = now.elapsed();
+    println!("Parsed VCD file {} : {:.2?}", file_path, elapsed);
+
+    println!("Printing Scopes");
+    visit_all_scopes(&vcd);
+    println!("Done Printing Scopes");
+
+    let state_signal = vcd.signal_from_signal_idx(SignalIdx(4));
+    let name = state_signal.name();
+
+    let timestamps = vec![31499_000u32, 31500_000u32, 57760_000u32];
+    for timestamp in timestamps {
+        let time = num::BigUint::from(timestamp);
+        let val = state_signal.query_string_val_on_tmln(&time, &vcd).unwrap();
+        println!("Signal `{name}` has value `{val}` at time `{time}`");
+    }
+
+    Ok(())
+}

src/lib.rs

@@ -0,0 +1,12 @@
+// Copyright (C) 2022 Yehowshua Immanuel
+// This program is distributed under both the GPLV3 license
+// and the YEHOWSHUA license, both of which can be found at
+// the root of the folder containing the sources for this program.
+
+mod vcd;
+pub use vcd::parse::parse_vcd;
+pub use vcd::signal::{Signal, SignalType, SignalValue, SignalErrors};
+pub use vcd::types::{Metadata, Timescale, Version};
+pub use vcd::types::{ScopeIdx, SignalIdx, VCD};
+
+pub use num::BigUint;

src/main.rs

@@ -1,31 +0,0 @@
-use clap::Parser;
-use std::fs::File;
-
-pub mod test;
-
-pub mod vcd;
-use vcd::parse_vcd;
-
-#[derive(Parser)]
-struct Cli {
-    /// The path to the file to read
-    #[clap(parse(from_os_str))]
-    path: std::path::PathBuf,
-}
-
-fn main() -> std::io::Result<()> {
-    let args = Cli::parse();
-
-    use std::time::Instant;
-    let now = Instant::now();
-
-    let file = File::open(&args.path)?;
-    parse_vcd(file).unwrap();
-
-    let elapsed = now.elapsed();
-    println!("Elapsed: {:.2?}", elapsed);
-
-    // std::thread::sleep(std::time::Duration::from_secs(10));
-
-    Ok(())
-}

src/test.rs

@@ -1,2 +0,0 @@
-mod files;
-pub use files::*;

src/test/files.rs

@@ -1,71 +0,0 @@
-// TODO: we should eventually be able to only test on just
-// the files const
-pub const FILES : [&str; 30] = [
-    "./test-vcd-files/aldec/SPI_Write.vcd",
-    "./test-vcd-files/ghdl/alu.vcd",
-    "./test-vcd-files/ghdl/idea.vcd",
-    "./test-vcd-files/ghdl/pcpu.vcd",
-    "./test-vcd-files/gtkwave-analyzer/perm_current.vcd",
-    "./test-vcd-files/icarus/CPU.vcd",
-    "./test-vcd-files/icarus/rv32_soc_TB.vcd",
-    "./test-vcd-files/icarus/test1.vcd",
-    "./test-vcd-files/model-sim/CPU_Design.msim.vcd",
-    "./test-vcd-files/model-sim/clkdiv2n_tb.vcd",
-    "./test-vcd-files/my-hdl/Simple_Memory.vcd",
-    "./test-vcd-files/my-hdl/sigmoid_tb.vcd",
-    "./test-vcd-files/my-hdl/top.vcd",
-    "./test-vcd-files/ncsim/ffdiv_32bit_tb.vcd",
-    "./test-vcd-files/quartus/mipsHardware.vcd",
-    "./test-vcd-files/quartus/wave_registradores.vcd",
-    "./test-vcd-files/questa-sim/dump.vcd",
-    "./test-vcd-files/questa-sim/test.vcd",
-    "./test-vcd-files/riviera-pro/dump.vcd",
-    "./test-vcd-files/systemc/waveform.vcd",
-    "./test-vcd-files/treadle/GCD.vcd",
-    "./test-vcd-files/vcs/Apb_slave_uvm_new.vcd",
-    "./test-vcd-files/vcs/datapath_log.vcd",
-    "./test-vcd-files/vcs/processor.vcd",
-    "./test-vcd-files/verilator/swerv1.vcd",
-    "./test-vcd-files/verilator/vlt_dump.vcd",
-    "./test-vcd-files/vivado/iladata.vcd",
-    "./test-vcd-files/xilinx_isim/test.vcd",
-    "./test-vcd-files/xilinx_isim/test1.vcd",
-    // TODO : add signal ignore list to handle bitwidth mismatches
-    "./test-vcd-files/xilinx_isim/test2x2_regex22_string1.vcd"
-];
-
-pub const GOOD_DATE_FILES : [&str; 24] = [
-    "./test-vcd-files/aldec/SPI_Write.vcd",
-    "./test-vcd-files/ghdl/alu.vcd",
-    "./test-vcd-files/ghdl/idea.vcd",
-    "./test-vcd-files/ghdl/pcpu.vcd",
-    "./test-vcd-files/gtkwave-analyzer/perm_current.vcd",
-    "./test-vcd-files/icarus/CPU.vcd",
-    "./test-vcd-files/icarus/rv32_soc_TB.vcd",
-    "./test-vcd-files/icarus/test1.vcd",
-    "./test-vcd-files/model-sim/CPU_Design.msim.vcd",
-    "./test-vcd-files/model-sim/clkdiv2n_tb.vcd",
-    "./test-vcd-files/my-hdl/Simple_Memory.vcd",
-    "./test-vcd-files/my-hdl/sigmoid_tb.vcd",
-    "./test-vcd-files/my-hdl/top.vcd",
-    "./test-vcd-files/questa-sim/dump.vcd",
-    "./test-vcd-files/questa-sim/test.vcd",
-    "./test-vcd-files/riviera-pro/dump.vcd",
-    "./test-vcd-files/vcs/Apb_slave_uvm_new.vcd",
-    "./test-vcd-files/vcs/datapath_log.vcd",
-    "./test-vcd-files/vcs/processor.vcd",
-    "./test-vcd-files/verilator/swerv1.vcd",
-    "./test-vcd-files/verilator/vlt_dump.vcd",
-    "./test-vcd-files/xilinx_isim/test.vcd",
-    "./test-vcd-files/xilinx_isim/test1.vcd",
-    "./test-vcd-files/xilinx_isim/test2x2_regex22_string1.vcd"
-];
-
-pub const BAD_DATE_FILES : [&str; 6] = [
-    "./test-vcd-files/ncsim/ffdiv_32bit_tb.vcd",
-    "./test-vcd-files/quartus/mipsHardware.vcd",
-    "./test-vcd-files/quartus/wave_registradores.vcd",
-    "./test-vcd-files/systemc/waveform.vcd",
-    "./test-vcd-files/treadle/GCD.vcd",
-    "./test-vcd-files/vivado/iladata.vcd",
-];

src/vcd.rs

@@ -1,14 +1,10 @@
+// Copyright (C) 2022 Yehowshua Immanuel
+// This program is distributed under both the GPLV3 license
+// and the YEHOWSHUA license, both of which can be found at
+// the root of the folder containing the sources for this program.
+
+pub(crate) mod parse;
 mod reader;
-use reader::*;
+pub(crate) mod signal;
-
+pub(crate) mod types;
-mod types;
-use types::*;
-
-mod parse;
-pub use parse::*;
-
-mod signal;
-use signal::*;
-
 mod utilities;
-use utilities::*;

src/vcd/parse.rs

@@ -1,100 +1,35 @@
-use num::BigUint;
+// Copyright (C) 2022 Yehowshua Immanuel
-use std::collections::HashMap;
+// This program is distributed under both the GPLV3 license
-use std::fs::File;
+// and the YEHOWSHUA license, both of which can be found at
-
+// the root of the folder containing the sources for this program.
-use super::*;
 
 mod combinator_atoms;
-use combinator_atoms::*;
-
-mod types;
-use types::*;
-
-mod metadata;
-use metadata::*;
-
-mod scopes;
-use scopes::*;
-
 mod events;
-use events::*;
+mod metadata;
+mod scopes;
+mod types;
 
-pub fn parse_vcd(file: File) -> Result<VCD, String> {
+pub fn parse_vcd(file: impl std::io::Read) -> Result<super::types::VCD, String> {
-    let mut word_gen = WordReader::new(file);
+    let mut word_gen = super::reader::WordReader::new(file);
 
-    let header = parse_metadata(&mut word_gen)?;
+    let header = metadata::parse_metadata(&mut word_gen)?;
 
     // later, we'll need to map parsed ascii symbols to their
     // respective signal indexes
     let mut signal_map = std::collections::HashMap::new();
 
     // after we parse metadata, we form the VCD object
-    let mut vcd = VCD {
+    let mut vcd = super::types::VCD {
         metadata: header,
         tmstmps_encoded_as_u8s: vec![],
         all_signals: vec![],
         all_scopes: vec![],
         root_scopes: vec![],
+        largest_timestamp: None,
     };
 
-    parse_scopes(&mut word_gen, &mut vcd, &mut signal_map)?;
+    scopes::parse_scopes(&mut word_gen, &mut vcd, &mut signal_map)?;
-    parse_events(&mut word_gen, &mut vcd, &mut signal_map)?;
+    events::parse_events(&mut word_gen, &mut vcd, &mut signal_map)?;
-    let signal = vcd.try_dereference_alias(signal_map.get("Q").unwrap())?;
-    let name = match signal {
-        Signal::Data { name, .. } => name,
-        _ => "ERROR",
-    };
-    let val = signal
-        .query_num_val_on_tmln(
-            BigUint::from(4687u32),
-            &vcd.tmstmps_encoded_as_u8s,
-            &vcd.all_signals,
-        )
-        .unwrap();
-    dbg!(format!("{val:#X}"));
-    dbg!(name);
 
     Ok(vcd)
 }
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-    use crate::test;
-    use std::fs::File;
-    #[test]
-    fn headers() {
-        // TODO: eventually, once all dates pass, merge the following
-        // two loops
-        // testing dates
-        for file in test::GOOD_DATE_FILES {
-            let metadata = parse_metadata(&mut WordReader::new(File::open(file).unwrap()));
-            assert!(metadata.is_ok());
-            assert!(metadata.unwrap().date.is_some());
-        }
-
-        for file in test::FILES {
-            let metadata = parse_metadata(&mut WordReader::new(File::open(file).unwrap()));
-            assert!(metadata.is_ok());
-
-            let (scalar, _timescale) = metadata.unwrap().timescale;
-            assert!(scalar.is_some());
-        }
-    }
-
-    #[test]
-    fn scopes() {
-        // see if we can parse all signal trees successfully
-        for file_name in test::FILES {
-            let file = File::open(file_name).unwrap();
-            let vcd = parse_vcd(file);
-
-            if !vcd.is_ok() {
-                dbg!(file_name);
-                vcd.unwrap();
-            }
-
-            // assert!(vcd.is_ok());
-        }
-    }
-}

src/vcd/parse/combinator_atoms.rs

@@ -1,16 +1,18 @@
-use super::reader::{next_word, WordReader};
+// Copyright (C) 2022 Yehowshua Immanuel
+// This program is distributed under both the GPLV3 license
+// and the YEHOWSHUA license, both of which can be found at
+// the root of the folder containing the sources for this program.
+use super::super::reader::{next_word, WordReader};
 use super::types::ParseResult;
 
 pub(super) fn digit(chr: u8) -> bool {
-    let zero = b'0' as u8;
+    let zero = b'0';
-    let nine = b'9' as u8;
+    let nine = b'9';
 
-    let between_zero_and_nine = (chr >= zero) && (nine >= chr);
+    (chr >= zero) && (nine >= chr)
-
-    return between_zero_and_nine;
 }
 
-pub(super) fn take_until<'a>(word: &'a str, pattern: u8) -> ParseResult<'a> {
+pub(super) fn take_until(word: &str, pattern: u8) -> ParseResult<'_> {
     let mut new_start = 0;
 
     for chr in word.as_bytes() {
@@ -21,13 +23,13 @@ pub(super) fn take_until<'a>(word: &'a str, pattern: u8) -> ParseResult<'a> {
         }
     }
 
-    return ParseResult {
+    ParseResult {
         matched: &word[0..new_start],
         residual: &word[new_start..],
-    };
+    }
 }
 
-pub(super) fn take_while<'a>(word: &'a str, cond: fn(u8) -> bool) -> ParseResult<'a> {
+pub(super) fn take_while(word: &str, cond: fn(u8) -> bool) -> ParseResult<'_> {
     let mut new_start = 0;
 
     for chr in word.as_bytes() {
@@ -38,10 +40,10 @@ pub(super) fn take_while<'a>(word: &'a str, cond: fn(u8) -> bool) -> ParseResult
         }
     }
 
-    return ParseResult {
+    ParseResult {
         matched: &word[0..new_start],
         residual: &word[new_start..],
-    };
+    }
 }
 
 pub(super) fn tag<'a>(word: &'a str, pattern: &'a str) -> ParseResult<'a> {
@@ -59,20 +61,23 @@ pub(super) fn tag<'a>(word: &'a str, pattern: &'a str) -> ParseResult<'a> {
         new_start += 1;
     }
 
-    return ParseResult {
+    ParseResult {
         matched: &word[0..new_start],
         residual: &word[new_start..],
-    };
+    }
 }
 
-pub(super) fn ident(word_reader: &mut WordReader, keyword: &str) -> Result<(), String> {
+pub(super) fn ident<R: std::io::Read>(
+    word_reader: &mut WordReader<R>,
+    keyword: &str,
+) -> Result<(), String> {
     // let keyword = "module";
     let (word, cursor) = next_word!(word_reader)?;
 
     if word == keyword {
-        return Ok(());
+        Ok(())
     } else {
         let err = format!("found keyword `{word}` but expected `{keyword}` on {cursor:?}");
-        return Err(err);
+        Err(err)
     }
 }

src/vcd/parse/events.rs

@@ -1,15 +1,23 @@
-use num::Zero;
+// Copyright (C) 2022 Yehowshua Immanuel
+// This program is distributed under both the GPLV3 license
+// and the YEHOWSHUA license, both of which can be found at
+// the root of the folder containing the sources for this program.
 
-use super::*;
+use num::BigUint;
+use std::collections::HashMap;
 
-pub(super) fn parse_events<'a>(
+use super::super::reader::{next_word, Cursor, Line, Word, WordReader};
-    word_reader: &mut WordReader,
+use super::super::signal::{LsbIdxOfTmstmpValOnTmln, SignalEnum};
-    vcd: &'a mut VCD,
+use super::super::types::{SignalIdx, VCD};
+use super::super::utilities::{binary_str_to_vec_u8, BinaryParserErrTypes};
+
+pub(super) fn parse_events<R: std::io::Read>(
+    word_reader: &mut WordReader<R>,
+    vcd: &mut VCD,
     signal_map: &mut HashMap<String, SignalIdx>,
 ) -> Result<(), String> {
     let mut curr_tmstmp_lsb_idx = 0u32;
     let mut curr_tmstmp_len_u8 = 0u8;
-    let mut curr_time = BigUint::zero();
     loop {
         let next_word = word_reader.next_word();
 
@@ -31,15 +39,14 @@ pub(super) fn parse_events<'a>(
             "#" => {
                 let value = &word[1..];
                 let (f, l) = (file!(), line!());
-                let value = BigUint::parse_bytes(value.as_bytes(), 10)
+                let value_biguint = BigUint::parse_bytes(value.as_bytes(), 10)
                     .ok_or(())
                     .map_err(|_| {
                         format!(
                             "Error near {f}:{l}. Failed to parse {value} as BigInt at {cursor:?}"
                         )
                     })?;
-                curr_time = value.clone();
+                let mut value = value_biguint.to_bytes_le();
-                let mut value = value.to_bytes_le();
                 // TODO : u32 helps with less memory, but should ideally likely be
                 // configurable.
                 curr_tmstmp_len_u8 = u8::try_from(value.len()).map_err(|_| {
@@ -58,15 +65,16 @@ pub(super) fn parse_events<'a>(
                         )
                     })?;
                 vcd.tmstmps_encoded_as_u8s.append(&mut value);
+                vcd.largest_timestamp = Some(value_biguint);
             }
 
             // handle the case of an n bit signal whose value must be parsed
             "b" => {
                 let binary_value = &word[1..];
-                let observed_num_bits = u16::try_from(binary_value.len()).map_err(|_| {
+                let observed_num_bits = u32::try_from(binary_value.len()).map_err(|_| {
                     format!(
                         "Error near {}:{}, {cursor:?}. \
-                        Found signal with more than 2^16 - 1 bits.",
+                        Found signal with more than 2^32 - 1 bits.",
                         file!(),
                         line!()
                     )
@@ -77,9 +85,9 @@ pub(super) fn parse_events<'a>(
 
                 let mut store_as_string = false;
 
-                // If we encounter x or z in a value, we can recover from
+                // If we encounter other values than 0 or 1, we can recover from
                 // the error and store the value as a string.
-                // Or else, we we propagate up other errors.
+                // Or else, we propagate up other errors.
                 match binary_str_to_vec_u8(binary_value) {
                     Ok(result) => {
                         value_u8 = result;
@@ -87,10 +95,15 @@ pub(super) fn parse_events<'a>(
                     Err(
                         BinaryParserErrTypes::XValue
                         | BinaryParserErrTypes::ZValue
-                        | BinaryParserErrTypes::UValue,
+                        | BinaryParserErrTypes::UValue
+                        | BinaryParserErrTypes::WValue
+                        | BinaryParserErrTypes::HValue
+                        | BinaryParserErrTypes::DashValue
+                        | BinaryParserErrTypes::LValue,
                     ) => {
                         store_as_string = true;
-                        value_string = binary_value.to_string();
+                        // Turn to lower case for consistency
+                        value_string = binary_value.to_ascii_lowercase();
                     }
                     Err(e) => {
                         let (f, l) = (file!(), line!());
@@ -112,12 +125,12 @@ pub(super) fn parse_events<'a>(
                     )
                 })?;
 
-                let signal = vcd.try_dereference_alias_mut(signal_idx)?;
+                let signal = vcd.dealiasing_signal_idx_to_signal_lookup_mut(signal_idx)?;
 
                 match signal {
-                    Signal::Data {
+                    SignalEnum::Data {
                         name,
-                        sig_type,
+                        signal_type,
                         ref mut signal_error,
                         num_bits,
                         num_bytes,
@@ -126,6 +139,7 @@ pub(super) fn parse_events<'a>(
                         lsb_indxs_of_num_tmstmp_vals_on_tmln,
                         byte_len_of_num_tmstmp_vals_on_tmln,
                         lsb_indxs_of_string_tmstmp_vals_on_tmln,
+                        byte_len_of_string_tmstmp_vals_on_tmln,
                         ..
                     } => {
                         // we've already identified in a prior loop iteration that the signal has
@@ -144,7 +158,7 @@ pub(super) fn parse_events<'a>(
                                     let (f, l) = (file!(), line!());
                                     let msg = format!("\
                                         Error near {f}:{l}. The bitwidth for signal {name} \
-                                        of sig_type {sig_type:?} is expected to be `{num_bits}` not \
+                                        of signal_type {signal_type:?} is expected to be `{num_bits}` not \
                                         `{observed_num_bits}`. \
                                         This error occurred while parsing the vcd file at \
                                         {cursor:?}");
@@ -157,7 +171,7 @@ pub(super) fn parse_events<'a>(
                                 let msg = format!(
                                     "\
                                     Error near {f}:{l}. The bitwidth for signal {name} \
-                                    must be specified for a signal of type {sig_type:?}. \
+                                    must be specified for a signal of type {signal_type:?}. \
                                     This error occurred while parsing the vcd file at \
                                     {cursor:?}"
                                 );
@@ -168,6 +182,7 @@ pub(super) fn parse_events<'a>(
                         if store_as_string {
                             lsb_indxs_of_string_tmstmp_vals_on_tmln
                                 .push(LsbIdxOfTmstmpValOnTmln(curr_tmstmp_lsb_idx));
+                            byte_len_of_string_tmstmp_vals_on_tmln.push(curr_tmstmp_len_u8);
                             string_vals.push(value_string);
                             Ok(())
                         } else {
@@ -185,11 +200,11 @@ pub(super) fn parse_events<'a>(
                                 format!("Error near {}:{}. num_bytes empty.", file!(), line!())
                             })?;
                             let mut curr_num_bytes =
-                                u8::try_from(value_u8.len()).map_err(|_| {
+                                u16::try_from(value_u8.len()).map_err(|_| {
                                     format!(
                                         "Error near {}:{}. \
                                      Found signal {name} with with value change of greater \
-                                     than 2^16 - 1 bits on {cursor:?}.",
+                                     than 2^32 - 1 bits on {cursor:?}.",
                                         file!(),
                                         line!()
                                     )
@@ -203,7 +218,7 @@ pub(super) fn parse_events<'a>(
                             Ok(())
                         }
                     }
-                    Signal::Alias { .. } => {
+                    SignalEnum::Alias { .. } => {
                         let (f, l) = (file!(), line!());
                         let msg = format!(
                             "Error near {f}:{l}, a signal alias should not point to a signal alias.\n\
@@ -225,12 +240,12 @@ pub(super) fn parse_events<'a>(
                     )
                 })?;
 
-                let signal = vcd.try_dereference_alias_mut(signal_idx)?;
+                let signal = vcd.dealiasing_signal_idx_to_signal_lookup_mut(signal_idx)?;
 
                 match signal {
-                    Signal::Data {
+                    SignalEnum::Data {
                         name,
-                        sig_type,
+                        signal_type,
                         ref mut signal_error,
                         num_bits,
                         num_bytes,
@@ -253,7 +268,7 @@ pub(super) fn parse_events<'a>(
                                     let msg = format!(
                                         "\
                                         Error near {f}:{l}. The bitwidth for signal {name} \
-                                        of sig_type {sig_type:?} is expected to be `1` not \
+                                        of signal_type {signal_type:?} is expected to be `1` not \
                                         `{num_bits}`. \
                                         This error occurred while parsing the vcd file at \
                                         {cursor:?}"
@@ -267,7 +282,7 @@ pub(super) fn parse_events<'a>(
                                 let msg = format!(
                                     "\
                                     Error near {f}:{l}. The bitwidth for signal {name} \
-                                    must be specified for a signal of type {sig_type:?}. \
+                                    must be specified for a signal of type {signal_type:?}. \
                                     This error occurred while parsing the vcd file at \
                                     {cursor:?}"
                                 );
@@ -295,7 +310,7 @@ pub(super) fn parse_events<'a>(
                         }
                         Ok(())
                     }
-                    Signal::Alias { .. } => {
+                    SignalEnum::Alias { .. } => {
                         let (f, l) = (file!(), line!());
                         let msg = format!(
                             "Error near {f}:{l}, a signal alias should not point to a signal alias.\n\
@@ -316,12 +331,12 @@ pub(super) fn parse_events<'a>(
                     )
                 })?;
 
-                let signal = vcd.try_dereference_alias_mut(signal_idx)?;
+                let signal = vcd.dealiasing_signal_idx_to_signal_lookup_mut(signal_idx)?;
 
                 match signal {
-                    Signal::Data {
+                    SignalEnum::Data {
                         name,
-                        sig_type,
+                        signal_type,
                         ref mut signal_error,
                         num_bits,
                         num_bytes,
@@ -344,7 +359,7 @@ pub(super) fn parse_events<'a>(
                                     let msg = format!(
                                         "\
                                         Error near {f}:{l}. The bitwidth for signal {name} \
-                                        of sig_type {sig_type:?} is expected to be `1` not \
+                                        of signal_type {signal_type:?} is expected to be `1` not \
                                         `{num_bits}`. \
                                         This error occurred while parsing the vcd file at \
                                         {cursor:?}"
@@ -358,7 +373,7 @@ pub(super) fn parse_events<'a>(
                                 let msg = format!(
                                     "\
                                     Error near {f}:{l}. The bitwidth for signal {name} \
-                                    must be specified for a signal of type {sig_type:?}. \
+                                    must be specified for a signal of type {signal_type:?}. \
                                     This error occurred while parsing the vcd file at \
                                     {cursor:?}"
                                 );
@@ -386,7 +401,7 @@ pub(super) fn parse_events<'a>(
                         }
                         Ok(())
                     }
-                    Signal::Alias { .. } => {
+                    SignalEnum::Alias { .. } => {
                         let (f, l) = (file!(), line!());
                         let msg = format!(
                             "Error near {f}:{l}, a signal alias should not point to a signal alias.\n\
@@ -396,9 +411,10 @@ pub(super) fn parse_events<'a>(
                 }?;
             }
 
-            // // other one bit cases
+            // other one bit cases
-            "x" | "X" | "z" | "Z" | "u" | "U" => {
+            "x" | "X" | "z" | "Z" | "u" | "U" | "h" | "H" | "l" | "L" | "w" | "W" | "-" => {
-                let val = word.to_string();
+                // Select value and turn to lowercase for consistency
+                let val = word[0..1].to_ascii_lowercase();
                 // lokup signal idx
                 let hash = &word[1..];
                 let signal_idx = signal_map.get(hash).ok_or(()).map_err(|_| {
@@ -409,16 +425,15 @@ pub(super) fn parse_events<'a>(
                     )
                 })?;
 
-                let signal = vcd.try_dereference_alias_mut(signal_idx)?;
+                let signal = vcd.dealiasing_signal_idx_to_signal_lookup_mut(signal_idx)?;
 
                 match signal {
-                    Signal::Data {
+                    SignalEnum::Data {
                         name,
-                        sig_type,
+                        signal_type,
                         ref mut signal_error,
                         num_bits,
                         string_vals,
-                        byte_len_of_num_tmstmp_vals_on_tmln,
                         byte_len_of_string_tmstmp_vals_on_tmln,
                         lsb_indxs_of_string_tmstmp_vals_on_tmln,
                         ..
@@ -437,7 +452,7 @@ pub(super) fn parse_events<'a>(
                                     let msg = format!(
                                         "\
                                         Error near {f}:{l}. The bitwidth for signal {name} \
-                                        of sig_type {sig_type:?} is expected to be `1` not \
+                                        of signal_type {signal_type:?} is expected to be `1` not \
                                         `{num_bits}`. \
                                         This error occurred while parsing the vcd file at \
                                         {cursor:?}"
@@ -451,7 +466,7 @@ pub(super) fn parse_events<'a>(
                                 let msg = format!(
                                     "\
                                     Error near {f}:{l}. The bitwidth for signal {name} \
-                                    must be specified for a signal of type {sig_type:?}. \
+                                    must be specified for a signal of type {signal_type:?}. \
                                     This error occurred while parsing the vcd file at \
                                     {cursor:?}"
                                 );
@@ -468,7 +483,53 @@ pub(super) fn parse_events<'a>(
                         string_vals.push(val);
                         Ok(())
                     }
-                    Signal::Alias { .. } => {
+                    SignalEnum::Alias { .. } => {
+                        let (f, l) = (file!(), line!());
+                        let msg = format!(
+                            "Error near {f}:{l}, a signal alias should not point to a signal alias.\n\
+                             This error occurred while parsing vcd file at {cursor:?}");
+                        Err(msg)
+                    }
+                }?;
+            }
+            // Store real values as a string as well and let the user parse it to an f64
+            "s" | " S" | "r" | "R" => {
+                let val = word[1..].to_string();
+                let (hash, cursor) = next_word!(word_reader)?;
+                // lokup signal idx
+                let signal_idx = signal_map.get(hash).ok_or(()).map_err(|_| {
+                    format!(
+                        "Error near {}:{}. Failed to lookup signal {hash} at {cursor:?}",
+                        file!(),
+                        line!()
+                    )
+                })?;
+
+                let signal = vcd.dealiasing_signal_idx_to_signal_lookup_mut(signal_idx)?;
+
+                match signal {
+                    SignalEnum::Data {
+                        ref mut signal_error,
+                        string_vals,
+                        byte_len_of_string_tmstmp_vals_on_tmln,
+                        lsb_indxs_of_string_tmstmp_vals_on_tmln,
+                        ..
+                    } => {
+                        // if this is a bad signal, go ahead and skip it
+                        if signal_error.is_some() {
+                            continue;
+                        }
+
+                        // record timestamp at which this event occurs
+                        lsb_indxs_of_string_tmstmp_vals_on_tmln
+                            .push(LsbIdxOfTmstmpValOnTmln(curr_tmstmp_lsb_idx));
+                        byte_len_of_string_tmstmp_vals_on_tmln.push(curr_tmstmp_len_u8);
+
+                        // record string value
+                        string_vals.push(val);
+                        Ok(())
+                    }
+                    SignalEnum::Alias { .. } => {
                         let (f, l) = (file!(), line!());
                         let msg = format!(
                             "Error near {f}:{l}, a signal alias should not point to a signal alias.\n\

src/vcd/parse/metadata.rs

@@ -1,7 +1,15 @@
-use chrono::prelude::*;
+// Copyright (C) 2022 Yehowshua Immanuel
+// This program is distributed under both the GPLV3 license
+// and the YEHOWSHUA license, both of which can be found at
+// the root of the folder containing the sources for this program.
+use chrono::prelude::{DateTime, Utc};
 use itertools::Itertools;
 
-use super::*;
+use super::super::reader::{next_word, Cursor, WordReader};
+use super::super::types::{Metadata, Timescale, Version};
+
+use super::combinator_atoms::{digit, tag, take_until, take_while};
+use super::types::ParseResult;
 
 pub(super) fn parse_date(
     word_and_ctx1: (&str, &Cursor),
@@ -125,9 +133,9 @@ pub(super) fn parse_date(
     // unfortunately, the minutes, seconds, and hour could occur in an
     // unexpected order
     let full_date = format!("{day} {month} {date} {hh}:{mm}:{ss} {year}");
-    let full_date = Utc.datetime_from_str(full_date.as_str(), "%a %b %e %T %Y");
+    let full_date = DateTime::parse_from_str(full_date.as_str(), "%a %b %e %T %Y");
     if full_date.is_ok() {
-        return Ok(full_date.unwrap());
+        return Ok(full_date.unwrap().into());
     }
 
     Err(format!(
@@ -137,7 +145,9 @@ pub(super) fn parse_date(
     ))
 }
 
-pub(super) fn parse_version(word_reader: &mut WordReader) -> Result<Version, String> {
+pub(super) fn parse_version<R: std::io::Read>(
+    word_reader: &mut WordReader<R>,
+) -> Result<Version, String> {
     let mut version = String::new();
 
     loop {
@@ -149,13 +159,13 @@ pub(super) fn parse_version(word_reader: &mut WordReader) -> Result<Version, Str
             return Ok(Version(version));
         } else {
             version.push_str(word);
-            version.push_str(" ");
+            version.push(' ');
         }
     }
 }
 
-pub(super) fn parse_timescale(
+pub(super) fn parse_timescale<R: std::io::Read>(
-    word_reader: &mut WordReader,
+    word_reader: &mut WordReader<R>,
 ) -> Result<(Option<u32>, Timescale), String> {
     // we might see `1ps $end` or `1 ps $end`
     // first get timescale
@@ -169,7 +179,7 @@ pub(super) fn parse_timescale(
         .map_err(|e| format!("Error near {}:{}. {e}", file!(), line!()))?;
 
     let timescale = {
-        if residual == "" {
+        if residual.is_empty() {
             let (word, _) = next_word!(word_reader)?;
             let unit = match word {
                 "fs" => Ok(Timescale::Fs),
@@ -209,10 +219,12 @@ pub(super) fn parse_timescale(
     let (word, _) = next_word!(word_reader)?;
     tag(word, "$end").assert_match()?;
 
-    return Ok(timescale);
+    Ok(timescale)
 }
 
-pub(super) fn parse_metadata(word_reader: &mut WordReader) -> Result<Metadata, String> {
+pub(super) fn parse_metadata<R: std::io::Read>(
+    word_reader: &mut WordReader<R>,
+) -> Result<Metadata, String> {
     let mut metadata = Metadata {
         date: None,
         version: None,
@@ -319,5 +331,5 @@ pub(super) fn parse_metadata(word_reader: &mut WordReader) -> Result<Metadata, S
             _ => {}
         }
     }
-    return Ok(metadata);
+    Ok(metadata)
 }

src/vcd/parse/scopes.rs

@@ -1,36 +1,71 @@
-//! part of the vcd parser that handles parsing the signal tree and
+// Copyright (C) 2022 Yehowshua Immanuel
-//! building the resulting signal tree
+// This program is distributed under both the GPLV3 license
-use super::*;
+// and the YEHOWSHUA license, both of which can be found at
+// the root of the folder containing the sources for this program.
 
-pub(super) fn parse_var<'a>(
+/// part of the vcd parser that handles parsing the signal tree and
-    word_reader: &mut WordReader,
+/// building the resulting signal tree
+use std::collections::HashMap;
+
+use super::super::reader::{curr_word, next_word, WordReader};
+use super::super::signal::{SignalEnum, SignalType};
+use super::super::types::{Scope, ScopeIdx, SignalIdx, VCD};
+
+use super::combinator_atoms::{ident, tag};
+use super::types::ParseResult;
+
+pub(super) fn parse_var<R: std::io::Read>(
+    word_reader: &mut WordReader<R>,
     parent_scope_idx: ScopeIdx,
-    vcd: &'a mut VCD,
+    vcd: &mut VCD,
     signal_map: &mut HashMap<String, SignalIdx>,
+    path: &Vec<String>,
 ) -> Result<(), String> {
     let (word, cursor) = next_word!(word_reader)?;
     let expected_types = [
+        "event",
         "integer",
         "parameter",
         "real",
+        "realtime",
         "reg",
         "string",
-        "wire",
+        "supply0",
-        "tri1",
+        "supply1",
         "time",
+        "tri",
+        "triand",
+        "trior",
+        "trireg",
+        "tri0",
+        "tri1",
+        "wand",
+        "wire",
+        "wor",
     ];
 
     // $var parameter 3 a IDLE $end
     //      ^^^^^^^^^ - var_type
     let var_type = match word {
-        "integer" => Ok(SigType::Integer),
+        "event" => Ok(SignalType::Event),
-        "parameter" => Ok(SigType::Parameter),
+        "integer" => Ok(SignalType::Integer),
-        "real" => Ok(SigType::Real),
+        "parameter" => Ok(SignalType::Parameter),
-        "reg" => Ok(SigType::Reg),
+        "real" => Ok(SignalType::Real),
-        "string" => Ok(SigType::Str),
+        "realtime" => Ok(SignalType::RealTime),
-        "wire" => Ok(SigType::Wire),
+        "reg" => Ok(SignalType::Reg),
-        "tri1" => Ok(SigType::Tri1),
+        "string" => Ok(SignalType::Str),
-        "time" => Ok(SigType::Time),
+        "supply0" => Ok(SignalType::Supply0),
+        "supply1" => Ok(SignalType::Supply1),
+        "tri" => Ok(SignalType::Tri),
+        "triand" => Ok(SignalType::TriAnd),
+        "trior" => Ok(SignalType::TriOr),
+        "trireg" => Ok(SignalType::TriReg),
+        "tri0" => Ok(SignalType::Tri0),
+        "tri1" => Ok(SignalType::Tri1),
+        "time" => Ok(SignalType::Time),
+        "wand" => Ok(SignalType::WAnd),
+        "wire" => Ok(SignalType::Wire),
+        "wor" => Ok(SignalType::WOr),
         _ => {
             let err = format!(
                 "Error near {}:{} \
@@ -50,25 +85,36 @@ pub(super) fn parse_var<'a>(
     // $var parameter 3 a IDLE $end
     //                ^ - num_bits
     let num_bits = match var_type {
-        SigType::Integer
+        SignalType::Event
-        | SigType::Parameter
+        | SignalType::Integer
-        | SigType::Real
+        | SignalType::Parameter
-        | SigType::Reg
+        | SignalType::Reg
-        | SigType::Wire
+        | SignalType::Supply0
-        | SigType::Tri1
+        | SignalType::Supply1
-        | SigType::Time => {
+        | SignalType::Tri
-            let num_bits = word.parse::<usize>().expect(parse_err.as_str());
+        | SignalType::TriAnd
-            let num_bits = u16::try_from(num_bits).map_err(|_| {
+        | SignalType::TriOr
+        | SignalType::TriReg
+        | SignalType::Tri0
+        | SignalType::Tri1
+        | SignalType::Time
+        | SignalType::WAnd
+        | SignalType::Wire
+        | SignalType::WOr => {
+            let num_bits = word
+                .parse::<usize>()
+                .unwrap_or_else(|_| panic!("{}", parse_err));
+            let num_bits = u32::try_from(num_bits).map_err(|_| {
                 format!(
                     "Error near {}:{} while parsing vcd file at {cursor:?}. \
-                     This signal has {num_bits} > 2^16 - 1 bits.",
+                     This signal has {num_bits} > 2^32 - 1 bits.",
                     file!(),
                     line!()
                 )
             })?;
             Some(num_bits)
         }
-        // for strings, we don't really care what the number of bits is
+        // for strings, reals, and realtimes we don't really care what the number of bits is
         _ => None,
     };
 
@@ -80,17 +126,19 @@ pub(super) fn parse_var<'a>(
     // $var parameter 3 a IDLE $end
     //                    ^^^^ - full_signal_name(can extend until $end)
     let mut full_signal_name = Vec::<String>::new();
+    let mut size = None;
     loop {
         let (word, _) = next_word!(word_reader)?;
         match word {
             "$end" => break,
+            other if other.starts_with('[') => size = Some(other.to_string()),
             _ => full_signal_name.push(word.to_string()),
         }
     }
     let full_signal_name = full_signal_name.join(" ");
 
     let num_bytes = if num_bits.is_some() {
-        let bytes_required = Signal::bytes_required(num_bits.unwrap(), &full_signal_name)?;
+        let bytes_required = SignalEnum::bytes_required(num_bits.unwrap(), &full_signal_name)?;
         Some(bytes_required)
     } else {
         None
@@ -102,8 +150,13 @@ pub(super) fn parse_var<'a>(
     let (signal, signal_idx) = match signal_map.get(&signal_alias) {
         Some(ref_signal_idx) => {
             let signal_idx = SignalIdx(vcd.all_signals.len());
-            let signal = Signal::Alias {
+            let signal = SignalEnum::Alias {
-                name: full_signal_name,
+                name: full_signal_name.clone(),
+                path: path
+                    .iter()
+                    .cloned()
+                    .chain([full_signal_name])
+                    .collect::<Vec<String>>(),
                 signal_alias: *ref_signal_idx,
             };
             (signal, signal_idx)
@@ -111,12 +164,18 @@ pub(super) fn parse_var<'a>(
         None => {
             let signal_idx = SignalIdx(vcd.all_signals.len());
             signal_map.insert(signal_alias.to_string(), signal_idx);
-            let signal = Signal::Data {
+            let signal = SignalEnum::Data {
-                name: full_signal_name,
+                name: full_signal_name.clone(),
-                sig_type: var_type,
+                path: path
+                    .iter()
+                    .cloned()
+                    .chain([full_signal_name])
+                    .collect::<Vec<String>>(),
+                signal_type: var_type,
+                index: size,
                 signal_error: None,
-                num_bits: num_bits,
+                num_bits,
-                num_bytes: num_bytes,
+                num_bytes,
                 self_idx: signal_idx,
                 nums_encoded_as_fixed_width_le_u8: vec![],
                 string_vals: vec![],
@@ -124,7 +183,6 @@ pub(super) fn parse_var<'a>(
                 byte_len_of_num_tmstmp_vals_on_tmln: vec![],
                 byte_len_of_string_tmstmp_vals_on_tmln: vec![],
                 lsb_indxs_of_string_tmstmp_vals_on_tmln: vec![],
-                scope_parent: parent_scope_idx,
             };
             (signal, signal_idx)
         }
@@ -140,9 +198,9 @@ pub(super) fn parse_var<'a>(
 
 /// Sometimes, variables can be listed outside of scopes.
 /// We call these orphaned vars.
-fn parse_orphaned_vars<'a>(
+fn parse_orphaned_vars<R: std::io::Read>(
-    word_reader: &mut WordReader,
+    word_reader: &mut WordReader<R>,
-    vcd: &'a mut VCD,
+    vcd: &mut VCD,
     signal_map: &mut HashMap<String, SignalIdx>,
 ) -> Result<(), String> {
     // create scope for unscoped signals if such a scope does not
@@ -168,7 +226,6 @@ fn parse_orphaned_vars<'a>(
     if !scope_already_exists {
         vcd.all_scopes.push(Scope {
             name: scope_name.to_string(),
-            parent_idx: None,
             self_idx: scope_idx,
             child_signals: vec![],
             child_scopes: vec![],
@@ -178,14 +235,14 @@ fn parse_orphaned_vars<'a>(
 
     // we can go ahead and parse the current var as we've already encountered
     // "$var" before now.
-    parse_var(word_reader, scope_idx, vcd, signal_map)?;
+    parse_var(word_reader, scope_idx, vcd, signal_map, &vec![])?;
 
     loop {
         let (word, cursor) = next_word!(word_reader)?;
 
         match word {
             "$var" => {
-                parse_var(word_reader, scope_idx, vcd, signal_map)?;
+                parse_var(word_reader, scope_idx, vcd, signal_map, &vec![])?;
             }
             "$scope" => break,
             _ => {
@@ -204,17 +261,18 @@ fn parse_orphaned_vars<'a>(
     Ok(())
 }
 
-fn parse_scopes_inner<'a>(
+fn parse_scopes_inner<R: std::io::Read>(
-    word_reader: &mut WordReader,
+    word_reader: &mut WordReader<R>,
     parent_scope_idx: Option<ScopeIdx>,
-    vcd: &'a mut VCD,
+    vcd: &mut VCD,
     signal_map: &mut HashMap<String, SignalIdx>,
+    path: &Vec<String>,
 ) -> Result<(), String> {
     // $scope module reg_mag_i $end
     //        ^^^^^^ - module keyword
     let (keyword, cursor) = next_word!(word_reader)?;
 
-    let expected = ["module", "begin", "task", "function"];
+    let expected = ["module", "begin", "task", "function", "fork"];
     if expected.contains(&keyword) {
         Ok(())
     } else {
@@ -231,79 +289,154 @@ fn parse_scopes_inner<'a>(
     // $scope module reg_mag_i $end
     //               ^^^^^^^^^ - scope name
     let (scope_name, _) = next_word!(word_reader)?;
+    // In some cases there are VCD files which have scopes without names.
+    // since these occur in the wild, we'll tolerate them even if it is unclear
+    // if it is supported or not by the spec.
+    if scope_name != "$end" {
+        let mut path = path.clone();
+        path.push(scope_name.to_string());
 
-    let curr_scope_idx = ScopeIdx(vcd.all_scopes.len());
+        let curr_scope_idx = ScopeIdx(vcd.all_scopes.len());
 
-    // register this scope as a child of the current parent scope
+        // register this scope as a child of the current parent scope
-    // if there is a parent scope, or else we register this scope as
+        // if there is a parent scope, or else we register this scope as
-    // root scope
+        // root scope
-    match parent_scope_idx {
+        match parent_scope_idx {
-        Some(ScopeIdx(parent_scope_idx)) => {
+            Some(ScopeIdx(parent_scope_idx)) => {
-            let parent_scope = vcd.all_scopes.get_mut(parent_scope_idx).unwrap();
+                let parent_scope = vcd.all_scopes.get_mut(parent_scope_idx).unwrap();
-            parent_scope.child_scopes.push(curr_scope_idx);
+                parent_scope.child_scopes.push(curr_scope_idx);
+            }
+            None => vcd.root_scopes.push(curr_scope_idx),
         }
-        None => vcd.root_scopes.push(curr_scope_idx),
-    }
 
-    // add this scope to list of existing scopes
+        // add this scope to list of existing scopes
-    vcd.all_scopes.push(Scope {
+        vcd.all_scopes.push(Scope {
-        name: scope_name.to_string(),
+            name: scope_name.to_string(),
-        parent_idx: parent_scope_idx,
+            self_idx: curr_scope_idx,
-        self_idx: curr_scope_idx,
+            child_signals: vec![],
-        child_signals: vec![],
+            child_scopes: vec![],
-        child_scopes: vec![],
+        });
-    });
 
-    // $scope module reg_mag_i $end
+        // $scope module reg_mag_i $end
-    //                         ^^^^ - end keyword
+        //                         ^^^^ - end keyword
-    ident(word_reader, "$end")?;
+        ident(word_reader, "$end")?;
 
-    loop {
+        loop {
-        let (word, cursor) = next_word!(word_reader)?;
+            let (word, cursor) = next_word!(word_reader)?;
-        let ParseResult { matched, residual } = tag(word, "$");
+            let ParseResult { matched, residual } = tag(word, "$");
-        match matched {
+            match matched {
-            // we hope that this word starts with a `$`
+                // we hope that this word starts with a `$`
-            "$" => {
+                "$" => {
-                match residual {
+                    match residual {
-                    "scope" => {
+                        "scope" => {
-                        // recursive - parse inside of current scope tree
+                            // recursive - parse inside of current scope tree
-                        parse_scopes_inner(word_reader, Some(curr_scope_idx), vcd, signal_map)?;
+                            parse_scopes_inner(
-                    }
+                                word_reader,
-                    "var" => {
+                                Some(curr_scope_idx),
-                        parse_var(word_reader, curr_scope_idx, vcd, signal_map)?;
+                                vcd,
-                    }
+                                signal_map,
-                    "upscope" => {
+                                &path,
-                        ident(word_reader, "$end")?;
+                            )?;
-                        break;
+                        }
-                    }
+                        "var" => {
-                    // we ignore comments
+                            parse_var(word_reader, curr_scope_idx, vcd, signal_map, &path)?;
-                    "comment" => loop {
+                        }
-                        if ident(word_reader, "$end").is_ok() {
+                        "upscope" => {
+                            ident(word_reader, "$end")?;
                             break;
                         }
-                    },
+                        // we ignore comments
-                    _ => {
+                        "comment" => loop {
-                        let err = format!(
+                            if ident(word_reader, "$end").is_ok() {
-                            "Error near {}:{}. \
+                                break;
-                                           found keyword `{residual}` but expected \
+                            }
-                                           `$scope`, `$var`, `$comment`, or `$upscope` \
+                        },
-                                           on {cursor:?}",
+                        _ => {
-                            file!(),
+                            let err = format!(
-                            line!()
+                                "Error near {}:{}. \
-                        );
+                                               found keyword `{residual}` but expected \
-                        return Err(err);
+                                               `$scope`, `$var`, `$comment`, or `$upscope` \
+                                               on {cursor:?}",
+                                file!(),
+                                line!()
+                            );
+                            return Err(err);
+                        }
                     }
                 }
+                _ => {
+                    let err = format!(
+                        "Error near {}:{}. \
+                                      found keyword `{matched}` but \
+                                      expected `$` on {cursor:?}",
+                        file!(),
+                        line!()
+                    );
+                    return Err(err);
+                }
             }
-            _ => {
+        }
-                let err = format!(
+    } else {
-                    "Error near {}:{}. \
+        // We'll be conservative and only allow new scopes in this case, and make the nameless
-                                  found keyword `{matched}` but \
+        // scope completely transparent. I.e.
-                                  expected `$` on {cursor:?}",
+        // $scope module a $end
-                    file!(),
+        //   $scope module $end
-                    line!()
+        //     $scope module b $end
-                );
+        //       ...
-                return Err(err);
+        //     $upscope
+        //   $upscope
+        // $upscope
+        // will create `a.b`
+        loop {
+            let (word, cursor) = next_word!(word_reader)?;
+            let ParseResult { matched, residual } = tag(word, "$");
+            match matched {
+                // we hope that this word starts with a `$`
+                "$" => {
+                    match residual {
+                        "scope" => {
+                            // recursive - parse inside of current scope tree
+                            parse_scopes_inner(
+                                word_reader,
+                                parent_scope_idx,
+                                vcd,
+                                signal_map,
+                                &path,
+                            )?;
+                        }
+                        "upscope" => {
+                            ident(word_reader, "$end")?;
+                            break;
+                        }
+                        // we ignore comments
+                        "comment" => loop {
+                            if ident(word_reader, "$end").is_ok() {
+                                break;
+                            }
+                        },
+                        _ => {
+                            let err = format!(
+                                "Error near {}:{}. \
+                                               found keyword `{residual}` in annonyoums scope but expected \
+                                               `$scope`, `$comment`, or `$upscope` \
+                                               on {cursor:?}",
+                                file!(),
+                                line!()
+                            );
+                            return Err(err);
+                        }
+                    }
+                }
+                _ => {
+                    let err = format!(
+                        "Error near {}:{}. \
+                                      found keyword `{matched}` but \
+                                      expected `$` on {cursor:?}",
+                        file!(),
+                        line!()
+                    );
+                    return Err(err);
+                }
             }
         }
     }
@@ -311,13 +444,13 @@ fn parse_scopes_inner<'a>(
     Ok(())
 }
 
-pub(super) fn parse_scopes<'a>(
+pub(super) fn parse_scopes<R: std::io::Read>(
-    word_reader: &mut WordReader,
+    word_reader: &mut WordReader<R>,
-    vcd: &'a mut VCD,
+    vcd: &mut VCD,
     signal_map: &mut HashMap<String, SignalIdx>,
 ) -> Result<(), String> {
     // get the current word
-    let (word, cursor) = curr_word!(word_reader)?;
+    let (word, _) = curr_word!(word_reader)?;
 
     // we may have orphaned vars that occur before the first scope
     if word == "$var" {
@@ -343,7 +476,7 @@ pub(super) fn parse_scopes<'a>(
     }
 
     // now for the interesting part
-    parse_scopes_inner(word_reader, None, vcd, signal_map)?;
+    parse_scopes_inner(word_reader, None, vcd, signal_map, &vec![])?;
 
     // let err = format!("reached end of file without parser leaving {}", function_name!());
     let expected_keywords = ["$scope", "$enddefinitions"];
@@ -357,13 +490,13 @@ pub(super) fn parse_scopes<'a>(
 
         match word {
             "$scope" => {
-                parse_scopes_inner(word_reader, None, vcd, signal_map)?;
+                parse_scopes_inner(word_reader, None, vcd, signal_map, &vec![])?;
             }
             "$enddefinitions" => {
                 ident(word_reader, "$end")?;
                 break;
             }
-            "comment" => {
+            "$comment" => {
                 // although we don't store comments, we still need to advance the
                 // word_reader cursor to the end of the comment
                 loop {

src/vcd/parse/types.rs

@@ -1,25 +1,27 @@
+// Copyright (C) 2022 Yehowshua Immanuel
+// This program is distributed under both the GPLV3 license
+// and the YEHOWSHUA license, both of which can be found at
+// the root of the folder containing the sources for this program.
 #[derive(Debug)]
 pub(super) struct ParseResult<'a> {
-    pub(super) matched : &'a str, 
+    pub(super) matched: &'a str,
-    pub(super) residual : &'a str}
+    pub(super) residual: &'a str,
+}
 
 impl<'a> ParseResult<'a> {
-
+    pub(super) fn assert_match(&self) -> Result<&str, String> {
-    pub(super) fn assert_match(& self) -> Result<&str, String> {
+        if self.matched.is_empty() {
-        if self.matched == "" {
+            Err("no match".to_string())
-            return Err("no match".to_string())
+        } else {
-        }
+            Ok(self.matched)
-        else {
-            return Ok(self.matched)
         }
     }
 
-    pub(super) fn assert_residual(& self) -> Result<&str, String> {
+    pub(super) fn assert_residual(&self) -> Result<&str, String> {
-        if self.residual == "" {
+        if self.residual.is_empty() {
-            return Err("no residual".to_string())
+            Err("no residual".to_string())
-        }
+        } else {
-        else {
+            Ok(self.residual)
-            return Ok(self.residual)
         }
     }
-}
+}

src/vcd/reader.rs

@@ -1,7 +1,10 @@
+// Copyright (C) 2022 Yehowshua Immanuel
+// This program is distributed under both the GPLV3 license
+// and the YEHOWSHUA license, both of which can be found at
+// the root of the folder containing the sources for this program.
 use std::collections::VecDeque;
-use std::fs::File;
 use std::io;
-use std::io::prelude::*;
+use std::io::BufRead;
 use std::slice;
 use std::str;
 
@@ -12,8 +15,8 @@ pub(super) struct Word(pub(super) usize);
 #[derive(Debug, Clone)]
 pub(super) struct Cursor(pub(super) Line, pub(super) Word);
 
-pub(super) struct WordReader {
+pub(super) struct WordReader<R: io::Read> {
-    reader: io::BufReader<File>,
+    reader: io::BufReader<R>,
     eof: bool,
     buffers: Vec<String>,
     curr_line: usize,
@@ -21,11 +24,11 @@ pub(super) struct WordReader {
     curr_slice: Option<(*const u8, usize, Cursor)>,
 }
 
-impl WordReader {
+impl<R: std::io::Read> WordReader<R> {
-    pub(super) fn new(file: File) -> WordReader {
+    pub(super) fn new(file: R) -> WordReader<R> {
         let reader = io::BufReader::new(file);
         WordReader {
-            reader: reader,
+            reader,
             eof: false,
             buffers: vec![],
             curr_line: 0,

src/vcd/signal.rs

@@ -1,81 +1,237 @@
-use super::{ScopeIdx, SignalIdx};
+// Copyright (C) 2022 Yehowshua Immanuel
-use num::{BigUint, Zero};
+// This program is distributed under both the GPLV3 license
+// and the YEHOWSHUA license, both of which can be found at
+// the root of the folder containing the sources for this program.
+use super::types;
+use super::types::SignalIdx;
+use num::BigUint;
 
 // Index to the least significant byte of a timestamp
 // value on the timeline
 #[derive(Debug, Copy, Clone)]
 pub struct LsbIdxOfTmstmpValOnTmln(pub(super) u32);
 
-#[derive(Debug)]
+#[derive(Debug, Eq, PartialEq, Clone)]
-pub(super) enum SigType {
+pub enum SignalType {
+    Event,
     Integer,
     Parameter,
     Real,
+    RealTime,
     Reg,
     Str,
-    Wire,
+    Supply0,
-    Tri1,
+    Supply1,
     Time,
+    Tri,
+    TriAnd,
+    TriOr,
+    TriReg,
+    Tri0,
+    Tri1,
+    WAnd,
+    Wire,
+    WOr,
 }
 
-#[derive(Debug)]
+#[derive(Debug, PartialEq)]
-pub(super) enum TimelineQueryResults {
+pub enum SignalValue {
     BigUint(BigUint),
     String(String),
 }
 
+pub struct QueryResult<T> {
+    pub current: Option<(TimeStamp, T)>,
+    pub next: Option<TimeStamp>,
+}
+
+pub struct Signal<'a>(pub(super) &'a SignalEnum);
+
+impl<'a> Signal<'a> {
+    pub fn name(&self) -> String {
+        let Signal(signal_enum) = &self;
+        signal_enum.name()
+    }
+
+    pub fn name_with_index(&self) -> String {
+        let Signal(signal_enum) = &self;
+        signal_enum.name_with_index()
+    }
+
+    pub fn index(&self) -> Option<String> {
+        let Signal(signal_enum) = &self;
+        signal_enum.index()
+    }
+
+    pub fn path(&self) -> &[String] {
+        match self.0 {
+            SignalEnum::Data { path, .. } => path,
+            SignalEnum::Alias { path, .. } => path,
+        }
+    }
+
+    pub fn signal_type(&self) -> Option<&SignalType> {
+        let Signal(signal_enum) = &self;
+        signal_enum.signal_type()
+    }
+
+    pub fn real_idx(&self) -> SignalIdx {
+        match self.0 {
+            SignalEnum::Data { self_idx, .. } => *self_idx,
+            SignalEnum::Alias { signal_alias, .. } => *signal_alias,
+        }
+    }
+
+    pub fn num_bits(&self) -> Option<u32> {
+        let Signal(signal_enum) = &self;
+        signal_enum.bits_required()
+    }
+
+    // NOTE: (zoq) I am removing thse because they aren't used in Surfer so I can't test them
+    // properly
+    /*
+    pub fn query_string_val_on_tmln(
+        &self,
+        desired_time: &BigUint,
+        vcd: &types::VCD,
+    ) -> Result<String, SignalErrors> {
+        let Signal(signal_enum) = &self;
+        signal_enum
+            .query_string_val_on_tmln(desired_time, &vcd.tmstmps_encoded_as_u8s, &vcd.all_signals)
+            .map(|QueryResult{current, next: _}| current.map(|c| c.1))
+    }
+
+    pub fn query_num_val_on_tmln(
+        &self,
+        desired_time: &BigUint,
+        vcd: &types::VCD,
+    ) -> Result<Option<BigUint>, SignalErrors> {
+        let Signal(signal_enum) = &self;
+        signal_enum
+            .query_num_val_on_tmln(desired_time, &vcd.tmstmps_encoded_as_u8s, &vcd.all_signals)
+            .map(|QueryResult{current, next: _}| current.map(|c| c.1))
+    }
+    */
+
+    pub fn query_val_on_tmln(
+        &self,
+        desired_time: &BigUint,
+        vcd: &types::VCD,
+    ) -> Result<QueryResult<SignalValue>, SignalErrors> {
+        let Signal(signal_enum) = &self;
+        let num_query_out = signal_enum.query_num_val_on_tmln(
+            desired_time,
+            &vcd.tmstmps_encoded_as_u8s,
+            &vcd.all_signals,
+        );
+        let str_query_out = signal_enum.query_string_val_on_tmln(
+            desired_time,
+            &vcd.tmstmps_encoded_as_u8s,
+            &vcd.all_signals,
+        );
+
+        // Both num and str will return the newest value that is closest to
+        // the desired time. If both have valid values, select the most recent
+        // one
+        match (num_query_out, str_query_out) {
+            (Ok(num_result), Ok(str_result)) => {
+                let next = match (num_result.next, str_result.next) {
+                    (Some(n), Some(s)) => Some(n.min(s)),
+                    (Some(n), None) => Some(n),
+                    (None, Some(s)) => Some(s),
+                    (None, None) => None,
+                };
+
+                match (num_result.current, str_result.current) {
+                    (Some((num_time, num_value)), Some((str_time, str_value))) => {
+                        if num_time > str_time {
+                            Ok(QueryResult {
+                                current: Some((num_time, SignalValue::BigUint(num_value))),
+                                next,
+                            })
+                        } else {
+                            Ok(QueryResult {
+                                current: Some((str_time, SignalValue::String(str_value))),
+                                next,
+                            })
+                        }
+                    }
+                    (Some((num_time, num_val)), None) => Ok(QueryResult {
+                        current: Some((num_time, SignalValue::BigUint(num_val))),
+                        next,
+                    }),
+                    (None, Some((str_time, str_value))) => Ok(QueryResult {
+                        current: Some((str_time, SignalValue::String(str_value))),
+                        next,
+                    }),
+                    (None, None) => Ok(QueryResult {
+                        current: None,
+                        next,
+                    }),
+                }
+            }
+            (_e, Err(e)) => Err(e),
+            (Err(e), _e) => Err(e),
+        }
+    }
+}
+
 #[derive(Debug)]
-pub(super) enum Signal {
+pub(super) enum SignalEnum {
     Data {
         name: String,
-        sig_type: SigType,
+        path: Vec<String>,
-        // I've seen a 0 bit signal parameter in a xilinx
+        signal_type: SignalType,
-        // simulation before that gets assigned 1 bit values.
+        /// The optional [start:end] part of the signal name that is sometimes
-        // I consider this to be bad behavior. We capture such
+        /// added to signals
-        // errors in the following type:
+        index: Option<String>,
+        /// I've seen a 0 bit signal parameter in a xilinx
+        /// simulation before that gets assigned 1 bit values.
+        /// I consider this to be bad behavior. We capture such
+        /// errors in the following type:
         signal_error: Option<String>,
-        num_bits: Option<u16>,
+        num_bits: Option<u32>,
-        num_bytes: Option<u8>,
+        num_bytes: Option<u16>,
-        // TODO : may be able to remove self_idx
+        /// TODO : may be able to remove self_idx
         self_idx: SignalIdx,
-        // A signal may take on a new value and hold that value
+        /// A signal may take on a new value and hold that value
-        // for sometime. We only need to record the value of a signal
+        /// for sometime. We only need to record the value of a signal
-        // when it changes(the is what VCDs tend to do).
+        /// when it changes(the is what VCDs tend to do).
-        // A signal may need x amount of bytes to record its largest possible
+        /// A signal may need x amount of bytes to record its largest
-        // value, so we record every single value of a given signal as a sequence
+        /// possible value, so we record every single value of a given
-        // of x number of u8s.
+        /// signal as a sequence of x number of u8s.
-        // For example, we might find that `my_signal.nums_encoded_as_fixed_width_le_u8`
+        /// For example, we might find that `my_signal.
-        // has two 32 bit values, namely, 1 and 2, encoded as follows:
+        /// nums_encoded_as_fixed_width_le_u8`
-        // my_signal.nums_encoded_as_fixed_width_le_u8 = vec![1u8, 0u8, 0u8, 0u8, 2u8, 0u8, 0u8, 0u8];
+        /// has two 32 bit values, namely, 1 and 2, encoded as follows:
+        /// my_signal.nums_encoded_as_fixed_width_le_u8 = vec![1u8, 0u8,
+        /// 0u8, 0u8, 2u8, 0u8, 0u8, 0u8];
         nums_encoded_as_fixed_width_le_u8: Vec<u8>,
         string_vals: Vec<String>,
-        // we could do Vec<(LsbIdxOfTmstmpValOnTmln, u8)>, but I suspect that
+        /// we could do Vec<(LsbIdxOfTmstmpValOnTmln, u8)>, but I
-        // Vec<LsbIdxOfTmstmpValOnTmln> is more cache friendly.
+        /// suspect that Vec<LsbIdxOfTmstmpValOnTmln> is more cache
-        // We use ``LsbIdxOfTmstmpValOnTmln`` to index into the LSB of a particular
+        /// friendly. We use ``LsbIdxOfTmstmpValOnTmln`` to index into
-        // timestamp encoded as the minimu length u8 sequence within
+        /// the LSB of a particular timestamp encoded as the
-        // ``vcd.tmstmps_encoded_as_u8s``, and we use the values in
+        /// minimum length u8 sequence within
-        // ``byte_len_of_num_tmstmp_vals_on_tmln`` to determine how many u8 values
+        /// ``vcd.tmstmps_encoded_as_u8s``, and we use the values in
-        // a particular timestamp is composed of.
+        /// ``byte_len_of_num_tmstmp_vals_on_tmln`` to determine how
+        /// many u8 values a particular timestamp is composed of.
         lsb_indxs_of_num_tmstmp_vals_on_tmln: Vec<LsbIdxOfTmstmpValOnTmln>,
         byte_len_of_num_tmstmp_vals_on_tmln: Vec<u8>,
         byte_len_of_string_tmstmp_vals_on_tmln: Vec<u8>,
         lsb_indxs_of_string_tmstmp_vals_on_tmln: Vec<LsbIdxOfTmstmpValOnTmln>,
-        scope_parent: ScopeIdx,
     },
     Alias {
         name: String,
+        path: Vec<String>,
         signal_alias: SignalIdx,
     },
 }
 
 #[derive(Debug)]
-pub(super) enum SignalErrors {
+pub enum SignalErrors {
-    PreTimeline {
-        desired_time: BigUint,
-        timeline_start_time: BigUint,
-    },
     EmptyTimeline,
     TimelineNotMultiple,
+    StrTmlnLenMismatch,
     OrderingFailure {
         lhs_time: BigUint,
         mid_time: BigUint,
@@ -90,20 +246,124 @@ pub(super) enum SignalErrors {
 type TimeStamp = BigUint;
 type SignalValNum = BigUint;
 
-impl Signal {
+// getter functions
-    pub(super) fn bytes_required(num_bits: u16, name: &String) -> Result<u8, String> {
+impl SignalEnum {
+    pub fn name(&self) -> String {
+        match self {
+            SignalEnum::Data { name, .. } => name,
+            SignalEnum::Alias { name, .. } => name,
+        }
+        .clone()
+    }
+
+    pub fn signal_type(&self) -> Option<&SignalType> {
+        match self {
+            SignalEnum::Data { signal_type, .. } => Some(signal_type),
+            // TODO: Follow aliases?
+            SignalEnum::Alias { .. } => None,
+        }
+        .clone()
+    }
+
+    pub fn name_with_index(&self) -> String {
+        match self {
+            SignalEnum::Data {
+                name, index: None, ..
+            } => format!("{name}"),
+            SignalEnum::Data {
+                name,
+                index: Some(size),
+                ..
+            } => format!("{name} {size}"),
+            SignalEnum::Alias { name, .. } => name.clone(),
+        }
+    }
+
+    pub fn index(&self) -> Option<String> {
+        match self {
+            SignalEnum::Data { index, .. } => index.clone(),
+            SignalEnum::Alias { .. } => None,
+        }
+    }
+}
+
+// helper functions ultimately used by Signal's query functions later on
+impl SignalEnum {
+    /// Computes the bytes required to store a signal's numerical value
+    /// using the num_bits which another function would provide from
+    /// the num_bits field of the Signal::Data variant.
+    pub(super) fn bytes_required(num_bits: u32, name: &String) -> Result<u16, String> {
         let bytes_required = (num_bits / 8) + if (num_bits % 8) > 0 { 1 } else { 0 };
-        let bytes_required = u8::try_from(bytes_required).map_err(|_| {
+        let bytes_required = u16::try_from(bytes_required).map_err(|_| {
             format!(
                 "Error near {}:{}. Signal {name} of length num_bits requires \
-                        {bytes_required} > 256 bytes.",
+                        {bytes_required} > 65536 bytes.",
                 file!(),
                 line!()
             )
         })?;
         Ok(bytes_required)
     }
-    pub(super) fn lookup_time_and_val(
+    /// This function takes an event_idx which(is used to index into the
+    /// global timeline field of a VCD struct instance) and computes
+    /// the time pointed at by event_idx.
+    /// This function also uses the same idx to index into the
+    /// string_vals field of an instance of the Signal::Data variant
+    ///  and gets a string value.
+    /// The function returns a tuple of the timestamp and string value.
+    fn time_and_str_val_at_event_idx(
+        &self,
+        event_idx: usize,
+        tmstmps_encoded_as_u8s: &Vec<u8>,
+    ) -> Result<(TimeStamp, &str), SignalErrors> {
+        let (
+            string_vals,
+            lsb_indxs_of_string_tmstmp_vals_on_tmln,
+            byte_len_of_string_tmstmp_vals_on_tmln,
+        ) = match self {
+            SignalEnum::Data {
+                string_vals,
+                lsb_indxs_of_string_tmstmp_vals_on_tmln,
+                byte_len_of_string_tmstmp_vals_on_tmln,
+                ..
+            } => Ok((
+                string_vals,
+                lsb_indxs_of_string_tmstmp_vals_on_tmln,
+                byte_len_of_string_tmstmp_vals_on_tmln,
+            )),
+            SignalEnum::Alias { .. } => Err(SignalErrors::PointsToAlias),
+        }?;
+
+        // get index
+        let LsbIdxOfTmstmpValOnTmln(timestamp_idx) =
+            lsb_indxs_of_string_tmstmp_vals_on_tmln[event_idx];
+        let timestamp_idx = timestamp_idx as usize;
+
+        if byte_len_of_string_tmstmp_vals_on_tmln.is_empty() {
+            return Err(SignalErrors::EmptyTimeline);
+        }
+
+        // form timestamp
+        let byte_len = byte_len_of_string_tmstmp_vals_on_tmln[event_idx] as usize;
+        let timestamp = &tmstmps_encoded_as_u8s[timestamp_idx..(timestamp_idx + byte_len)];
+        let timestamp = BigUint::from_bytes_le(timestamp);
+
+        // get signal value
+        let signal_val = string_vals[event_idx].as_str();
+
+        Ok((timestamp, signal_val))
+    }
+    /// This function takes an event_idx which(is used to index into the
+    /// global timeline field of a VCD struct instance) and computes
+    /// the time pointed at by event_idx.
+    /// This function also uses the same idx to index into the
+    /// nums_encoded_as_fixed_width_le_u8 and
+    /// byte_len_of_num_tmstmp_vals_on_tmln fields of an instance
+    /// of the Signal::Data variant to compute the signal's corresponding
+    /// numerical value at the time pointed at by event_didx.
+    /// The function returns a tuple of the timestamp and numerical
+    /// value.
+    fn time_and_num_val_at_event_idx(
         &self,
         event_idx: usize,
         tmstmps_encoded_as_u8s: &Vec<u8>,
@@ -114,7 +374,7 @@ impl Signal {
             lsb_indxs_of_num_tmstmp_vals_on_tmln,
             byte_len_of_num_tmstmp_vals_on_tmln,
         ) = match self {
-            Signal::Data {
+            SignalEnum::Data {
                 num_bytes,
                 nums_encoded_as_fixed_width_le_u8,
                 lsb_indxs_of_num_tmstmp_vals_on_tmln,
@@ -126,7 +386,7 @@ impl Signal {
                 lsb_indxs_of_num_tmstmp_vals_on_tmln,
                 byte_len_of_num_tmstmp_vals_on_tmln,
             )),
-            Signal::Alias { .. } => Err(SignalErrors::PointsToAlias),
+            SignalEnum::Alias { .. } => Err(SignalErrors::PointsToAlias),
         }?;
 
         // get index
@@ -149,12 +409,27 @@ impl Signal {
 
         Ok((timestamp, signal_val))
     }
-    pub fn query_num_val_on_tmln(
+
+    fn bits_required(&self) -> Option<u32> {
+        match self {
+            SignalEnum::Data { num_bits, .. } => *num_bits,
+            // TODO: Follow aliases?
+            SignalEnum::Alias { .. } => None,
+        }
+    }
+}
+
+// Val and string query functions.
+// Function that take in a desired time on the timeline for a
+// specific signal and return a numerical or string value in a Result,
+// or an error in a Result.
+impl SignalEnum {
+    pub fn query_string_val_on_tmln(
         &self,
-        desired_time: BigUint,
+        desired_time: &BigUint,
         tmstmps_encoded_as_u8s: &Vec<u8>,
-        all_signals: &Vec<Signal>,
+        all_signals: &Vec<SignalEnum>,
-    ) -> Result<BigUint, SignalErrors> {
+    ) -> Result<QueryResult<String>, SignalErrors> {
         let signal_idx = match self {
             Self::Data { self_idx, .. } => {
                 let SignalIdx(idx) = self_idx;
@@ -163,15 +438,157 @@ impl Signal {
             Self::Alias {
                 name: _,
                 signal_alias,
+                path: _,
             } => {
                 let SignalIdx(idx) = signal_alias;
                 *idx
             }
         };
 
+        // if the signal idx points to data variant of the signal,
+        // extract:
+        // 1. the vector of string values
+        // 2. the vector of indices into timeline where events occur
+        //    for this signal
+        // else we propagate Err(..).
+        let (string_vals, lsb_indxs_of_string_tmstmp_vals_on_tmln) = match &all_signals[signal_idx]
+        {
+            SignalEnum::Data {
+                ref string_vals,
+                ref lsb_indxs_of_string_tmstmp_vals_on_tmln,
+                ..
+            } => Ok((string_vals, lsb_indxs_of_string_tmstmp_vals_on_tmln)),
+            SignalEnum::Alias { .. } => Err(SignalErrors::PointsToAlias),
+        }?;
+        // this signal should at least have some events, otherwise, trying to index into
+        // an empty vector later on would fail
+        if lsb_indxs_of_string_tmstmp_vals_on_tmln.is_empty() {
+            return Ok(QueryResult {
+                current: None,
+                next: None
+            });
+        }
+
+        // the vector of string timeline lsb indices should have the same
+        // length as the vector of string values
+        if string_vals.len() != lsb_indxs_of_string_tmstmp_vals_on_tmln.len() {
+            return Err(SignalErrors::StrTmlnLenMismatch);
+        }
+
+        // check if we're requesting a value that occurs before the recorded
+        // start of the timeline
+        let (timeline_start_time, _) =
+            self.time_and_str_val_at_event_idx(0, tmstmps_encoded_as_u8s)?;
+        if *desired_time < timeline_start_time {
+            return Ok(QueryResult {
+                current: None,
+                next: Some(timeline_start_time),
+            });
+        }
+
+        let mut lower_idx = 0usize;
+        let mut upper_idx = lsb_indxs_of_string_tmstmp_vals_on_tmln.len() - 1;
+        let (timeline_end_time, timeline_end_val) =
+            self.time_and_str_val_at_event_idx(upper_idx, tmstmps_encoded_as_u8s)?;
+
+        // check if we're requesting a value that occurs beyond the end of the timeline,
+        // if so, return the last value in this timeline
+        if *desired_time > timeline_end_time {
+            return Ok(QueryResult {
+                current: Some((timeline_end_time, timeline_end_val.to_string())),
+                next: None,
+            });
+        }
+
+        // This while loop is the meat of the lookup. Performance is log2(n),
+        // where n is the number of events on the timeline.
+        // We can assume that by the time we get here, that the desired_time
+        // is an event that occurs on the timeline, given that we handle any events
+        // occuring after or before the recorded tiimeline in the code above.
+        while lower_idx <= upper_idx {
+            let mid_idx = lower_idx + ((upper_idx - lower_idx) / 2);
+            let (curr_time, curr_val) =
+                self.time_and_str_val_at_event_idx(mid_idx, tmstmps_encoded_as_u8s)?;
+            let ordering = curr_time.cmp(desired_time);
+
+            match ordering {
+                std::cmp::Ordering::Less => {
+                    lower_idx = mid_idx + 1;
+                }
+                std::cmp::Ordering::Equal => {
+                    let next_time = if mid_idx < lsb_indxs_of_string_tmstmp_vals_on_tmln.len() - 1 {
+                        Some(
+                            self.time_and_str_val_at_event_idx(
+                                mid_idx + 1,
+                                tmstmps_encoded_as_u8s,
+                            )?
+                            .0,
+                        )
+                    } else {
+                        None
+                    };
+                    return Ok(QueryResult {
+                        current: Some((curr_time, curr_val.to_string())),
+                        next: next_time,
+                    });
+                }
+                std::cmp::Ordering::Greater => {
+                    upper_idx = mid_idx - 1;
+                }
+            }
+        }
+
+        let (left_time, left_val) =
+            self.time_and_str_val_at_event_idx(lower_idx - 1, tmstmps_encoded_as_u8s)?;
+        let (right_time, _) =
+            self.time_and_str_val_at_event_idx(lower_idx, tmstmps_encoded_as_u8s)?;
+
+        let ordered_left = left_time < *desired_time;
+        let ordered_right = *desired_time < right_time;
+        if !(ordered_left && ordered_right) {
+            return Err(SignalErrors::OrderingFailure {
+                lhs_time: left_time,
+                mid_time: desired_time.clone(),
+                rhs_time: right_time,
+            });
+        }
+
+        Ok(QueryResult {
+            current: Some((left_time, left_val.to_string())),
+            next: Some(right_time),
+        })
+    }
+    pub fn query_num_val_on_tmln(
+        &self,
+        desired_time: &BigUint,
+        tmstmps_encoded_as_u8s: &Vec<u8>,
+        all_signals: &Vec<SignalEnum>,
+    ) -> Result<QueryResult<BigUint>, SignalErrors> {
+        let signal_idx = match self {
+            Self::Data { self_idx, .. } => {
+                let SignalIdx(idx) = self_idx;
+                *idx
+            }
+            Self::Alias {
+                name: _,
+                path: _,
+                signal_alias,
+            } => {
+                let SignalIdx(idx) = signal_alias;
+                *idx
+            }
+        };
+
+        // if the signal idx points to data variant of the signal,
+        // extract:
+        // 1. the vector of LE u8 compressed values
+        // 2. the vector of indices into timeline where events occur
+        //    for this signal
+        // 3. the number of bytes per value for this signal
+        // else we propagate Err(..).
         let (nums_encoded_as_fixed_width_le_u8, lsb_indxs_of_num_tmstmp_vals_on_tmln, num_bytes) =
             match &all_signals[signal_idx] {
-                Signal::Data {
+                SignalEnum::Data {
                     num_bytes,
                     ref nums_encoded_as_fixed_width_le_u8,
                     ref lsb_indxs_of_num_tmstmp_vals_on_tmln,
@@ -186,12 +603,15 @@ impl Signal {
                         num_bytes,
                     ))
                 }
-                Signal::Alias { .. } => Err(SignalErrors::PointsToAlias),
+                SignalEnum::Alias { .. } => Err(SignalErrors::PointsToAlias),
             }?;
         // this signal should at least have some events, otherwise, trying to index into
         // an empty vector later on would fail
         if lsb_indxs_of_num_tmstmp_vals_on_tmln.is_empty() {
-            return Err(SignalErrors::EmptyTimeline);
+            return Ok(QueryResult {
+                current: None,
+                next: None
+            });
         }
 
         // assertion that value_sequence is a proper multiple of
@@ -206,32 +626,32 @@ impl Signal {
         if nums_encoded_as_fixed_width_le_u8.len()
             != (lsb_indxs_of_num_tmstmp_vals_on_tmln.len() * (bytes_required as usize))
         {
-            dbg!((
-                nums_encoded_as_fixed_width_le_u8.len(),
-                (lsb_indxs_of_num_tmstmp_vals_on_tmln.len() * (bytes_required as usize))
-            ));
             return Err(SignalErrors::TimelineNotMultiple);
         }
 
         // check if we're requesting a value that occurs before the recorded
         // start of the timeline
-        let (timeline_start_time, _) = self.lookup_time_and_val(0, tmstmps_encoded_as_u8s)?;
+        let (timeline_start_time, _) =
-        if desired_time < timeline_start_time {
+            self.time_and_num_val_at_event_idx(0, tmstmps_encoded_as_u8s)?;
-            return Err(SignalErrors::PreTimeline {
+        if *desired_time < timeline_start_time {
-                desired_time: desired_time,
+            return Ok(QueryResult {
-                timeline_start_time: timeline_start_time,
+                current: None,
+                next: Some(timeline_start_time),
             });
         }
 
         let mut lower_idx = 0usize;
         let mut upper_idx = lsb_indxs_of_num_tmstmp_vals_on_tmln.len() - 1;
         let (timeline_end_time, timeline_end_val) =
-            self.lookup_time_and_val(upper_idx, tmstmps_encoded_as_u8s)?;
+            self.time_and_num_val_at_event_idx(upper_idx, tmstmps_encoded_as_u8s)?;
 
         // check if we're requesting a value that occurs beyond the end of the timeline,
         // if so, return the last value in this timeline
-        if desired_time > timeline_end_time {
+        if *desired_time > timeline_end_time {
-            return Ok(timeline_end_val);
+            return Ok(QueryResult {
+                current: Some((timeline_end_time, timeline_end_val)),
+                next: None,
+            });
         }
 
         // This while loop is the meat of the lookup. Performance is log2(n),
@@ -242,15 +662,29 @@ impl Signal {
         while lower_idx <= upper_idx {
             let mid_idx = lower_idx + ((upper_idx - lower_idx) / 2);
             let (curr_time, curr_val) =
-                self.lookup_time_and_val(mid_idx, tmstmps_encoded_as_u8s)?;
+                self.time_and_num_val_at_event_idx(mid_idx, tmstmps_encoded_as_u8s)?;
-            let ordering = curr_time.cmp(&desired_time);
+            let ordering = curr_time.cmp(desired_time);
 
             match ordering {
                 std::cmp::Ordering::Less => {
                     lower_idx = mid_idx + 1;
                 }
                 std::cmp::Ordering::Equal => {
-                    return Ok(curr_val);
+                    let next_time = if mid_idx < lsb_indxs_of_num_tmstmp_vals_on_tmln.len() - 1 {
+                        Some(
+                            self.time_and_num_val_at_event_idx(
+                                mid_idx + 1,
+                                tmstmps_encoded_as_u8s,
+                            )?
+                            .0,
+                        )
+                    } else {
+                        None
+                    };
+                    return Ok(QueryResult {
+                        current: Some((curr_time, curr_val)),
+                        next: next_time,
+                    });
                 }
                 std::cmp::Ordering::Greater => {
                     upper_idx = mid_idx - 1;
@@ -259,19 +693,23 @@ impl Signal {
         }
 
         let (left_time, left_val) =
-            self.lookup_time_and_val(lower_idx - 1, tmstmps_encoded_as_u8s)?;
+            self.time_and_num_val_at_event_idx(lower_idx - 1, tmstmps_encoded_as_u8s)?;
-        let (right_time, _) = self.lookup_time_and_val(lower_idx, tmstmps_encoded_as_u8s)?;
+        let (right_time, _) =
+            self.time_and_num_val_at_event_idx(lower_idx, tmstmps_encoded_as_u8s)?;
 
-        let ordered_left = left_time < desired_time;
+        let ordered_left = left_time < *desired_time;
-        let ordered_right = desired_time < right_time;
+        let ordered_right = *desired_time < right_time;
         if !(ordered_left && ordered_right) {
             return Err(SignalErrors::OrderingFailure {
                 lhs_time: left_time,
-                mid_time: desired_time,
+                mid_time: desired_time.clone(),
                 rhs_time: right_time,
             });
         }
 
-        return Ok(left_val);
+        return Ok(QueryResult {
+            current: Some((left_time, left_val)),
+            next: Some(right_time),
+        });
     }
 }

src/vcd/types.rs

@@ -1,11 +1,19 @@
-use super::Signal;
+// use crate::Signal;
-use chrono::prelude::*;
 
-#[derive(Debug)]
+// Copyright (C) 2022 Yehowshua Immanuel
-pub(super) struct Version(pub String);
+// This program is distributed under both the GPLV3 license
+// and the YEHOWSHUA license, both of which can be found at
+// the root of the folder containing the sources for this program.
+use super::signal::{Signal, SignalEnum};
+use chrono::prelude::{DateTime, Utc};
+use num::BigUint;
+use std::fmt;
 
-#[derive(Debug)]
+#[derive(Debug, Clone)]
-pub(super) enum Timescale {
+pub struct Version(pub String);
+
+#[derive(Debug, Clone, Copy, Eq, PartialEq)]
+pub enum Timescale {
     Fs,
     Ps,
     Ns,
@@ -15,25 +23,38 @@ pub(super) enum Timescale {
     Unit,
 }
 
+impl fmt::Display for Timescale {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Timescale::Fs => write!(f, "fs"),
+            Timescale::Ps => write!(f, "ps"),
+            Timescale::Ns => write!(f, "ns"),
+            Timescale::Us => write!(f, "μs"),
+            Timescale::Ms => write!(f, "ms"),
+            Timescale::S => write!(f, "s"),
+            Timescale::Unit => write!(f, "unit"),
+        }
+    }
+}
+
 #[derive(Debug)]
-pub(super) struct Metadata {
+pub struct Metadata {
-    pub(super) date: Option<DateTime<Utc>>,
+    pub date: Option<DateTime<Utc>>,
-    pub(super) version: Option<Version>,
+    pub version: Option<Version>,
-    pub(super) timescale: (Option<u32>, Timescale),
+    pub timescale: (Option<u32>, Timescale),
 }
 
 // We do a lot of arena allocation in this codebase.
-#[derive(Debug, Copy, Clone)]
+#[derive(Debug, Copy, Clone, PartialEq, Eq, Hash, PartialOrd, Ord)]
-pub(super) struct ScopeIdx(pub(super) usize);
+pub struct ScopeIdx(pub usize);
 
-#[derive(Debug, Copy, Clone, PartialEq)]
+#[derive(Debug, Copy, Clone, PartialEq, Eq, Hash, PartialOrd, Ord)]
-pub(super) struct SignalIdx(pub(super) usize);
+pub struct SignalIdx(pub usize);
 
 #[derive(Debug)]
 pub(super) struct Scope {
     pub(super) name: String,
 
-    pub(super) parent_idx: Option<ScopeIdx>,
     pub(super) self_idx: ScopeIdx,
 
     pub(super) child_signals: Vec<SignalIdx>,
@@ -42,7 +63,7 @@ pub(super) struct Scope {
 
 #[derive(Debug)]
 pub struct VCD {
-    pub(super) metadata: Metadata,
+    pub metadata: Metadata,
     // Since we only need to store values when there is an actual change
     // in the timeline, we keep a vector that stores the time at which an
     // event occurs. Time t is always stored/encoded as the minimum length sequence
@@ -53,38 +74,62 @@ pub struct VCD {
     // vector of u8s that constitute a timestamp value. Signals don't have to
     // keep track of all timestamp values, a given signal only needs to keep
     // track of the timestamps at which the given signal value changes.
-    pub tmstmps_encoded_as_u8s: Vec<u8>,
+    pub(super) tmstmps_encoded_as_u8s: Vec<u8>,
-    pub(super) all_signals: Vec<Signal>,
+    pub(super) all_signals: Vec<SignalEnum>,
     pub(super) all_scopes: Vec<Scope>,
     pub(super) root_scopes: Vec<ScopeIdx>,
+    pub(super) largest_timestamp: Option<BigUint>,
 }
 
 impl VCD {
-    /// We take in a Signal and attempt to dereference that signal if it is of
+    pub fn root_scopes_by_idx(&self) -> Vec<ScopeIdx> {
+        self.root_scopes.clone()
+    }
+    pub fn child_scopes_by_idx(&self, scope_idx: ScopeIdx) -> Vec<ScopeIdx> {
+        let ScopeIdx(idx) = scope_idx;
+        let scope = &self.all_scopes[idx];
+        scope.child_scopes.clone()
+    }
+    pub fn get_children_signal_idxs(&self, scope_idx: ScopeIdx) -> Vec<SignalIdx> {
+        let ScopeIdx(idx) = scope_idx;
+        let scope = &self.all_scopes[idx];
+        scope.child_signals.clone()
+    }
+    pub fn scope_name_by_idx(&self, scope_idx: ScopeIdx) -> &String {
+        let ScopeIdx(idx) = scope_idx;
+        let scope = &self.all_scopes[idx];
+        &scope.name
+    }
+    pub fn signal_from_signal_idx(&self, idx: SignalIdx) -> Signal<'_> {
+        let SignalIdx(idx) = idx;
+        let signal_enum = &self.all_signals[idx];
+        return Signal(signal_enum);
+    }
+    /// We take in a Signal and attempt to de-alias that signal if it is of
     /// variant ``Signal::Alias``. If it is of variant ``Signal::Alias`` and points to
     /// another alias, that's an error. Otherwise, we return the ``Signal::Data``
     /// pointed to by the ``Signal::Alias``.
     /// If the Signal is of varint ``Signal::Data``, then that can be returned directly.
-    pub(super) fn try_dereference_alias_mut<'a>(
+    pub(super) fn dealiasing_signal_idx_to_signal_lookup_mut<'a>(
         &'a mut self,
         idx: &SignalIdx,
-    ) -> Result<&'a mut Signal, String> {
+    ) -> Result<&'a mut SignalEnum, String> {
         // get the signal pointed to be SignalIdx from the arena
         let SignalIdx(idx) = idx;
         let signal = &self.all_signals[*idx];
 
         // dereference signal if Signal::Alias, or keep idx if Signal::Data
         let signal_idx = match signal {
-            Signal::Data { self_idx, .. } => *self_idx,
+            SignalEnum::Data { self_idx, .. } => *self_idx,
-            Signal::Alias { name, signal_alias } => *signal_alias,
+            SignalEnum::Alias { signal_alias, .. } => *signal_alias,
         };
 
         // Should now  point to Signal::Data variant, or else there's an error
         let SignalIdx(idx) = signal_idx;
         let signal = self.all_signals.get_mut(idx).unwrap();
         match signal {
-            Signal::Data { .. } => Ok(signal),
+            SignalEnum::Data { .. } => Ok(signal),
-            Signal::Alias { .. } => Err(format!(
+            SignalEnum::Alias { .. } => Err(format!(
                 "Error near {}:{}. A signal alias shouldn't \
                  point to a signal alias.",
                 file!(),
@@ -92,31 +137,8 @@ impl VCD {
             )),
         }
     }
-    pub(super) fn try_dereference_alias<'a>(
-        &'a self,
-        idx: &SignalIdx,
-    ) -> Result<&'a Signal, String> {
-        // get the signal pointed to be SignalIdx from the arena
-        let SignalIdx(idx) = idx;
-        let signal = &self.all_signals[*idx];
 
-        // dereference signal if Signal::Alias, or keep idx if Signal::Data
+    pub fn max_timestamp(&self) -> &Option<BigUint> {
-        let signal_idx = match signal {
+        &self.largest_timestamp
-            Signal::Data { self_idx, .. } => *self_idx,
-            Signal::Alias { name, signal_alias } => *signal_alias,
-        };
-
-        // Should now  point to Signal::Data variant, or else there's an error
-        let SignalIdx(idx) = signal_idx;
-        let signal = self.all_signals.get(idx).unwrap();
-        match signal {
-            Signal::Data { .. } => Ok(signal),
-            Signal::Alias { .. } => Err(format!(
-                "Error near {}:{}. A signal alias shouldn't \
-                 point to a signal alias.",
-                file!(),
-                line!()
-            )),
-        }
     }
 }

src/vcd/utilities.rs

@@ -1,8 +1,16 @@
+// Copyright (C) 2022 Yehowshua Immanuel
+// This program is distributed under both the GPLV3 license
+// and the YEHOWSHUA license, both of which can be found at
+// the root of the folder containing the sources for this program.
 #[derive(Debug)]
 pub(super) enum BinaryParserErrTypes {
     XValue,
     ZValue,
     UValue,
+    HValue,
+    LValue,
+    DashValue,
+    WValue,
     OtherValue(char),
     TooLong,
 }
@@ -30,11 +38,15 @@ fn base2_str_to_byte(word: &[u8]) -> Result<u8, BinaryParserErrTypes> {
 
     for (idx, chr) in word.iter().rev().enumerate() {
         match chr {
-            b'1' => val = bit_lut[idx] | val,
+            b'1' => val |= bit_lut[idx],
             b'0' => {}
             b'x' | b'X' => return Err(BinaryParserErrTypes::XValue),
             b'z' | b'Z' => return Err(BinaryParserErrTypes::ZValue),
             b'u' | b'U' => return Err(BinaryParserErrTypes::UValue),
+            b'l' | b'L' => return Err(BinaryParserErrTypes::LValue),
+            b'h' | b'H' => return Err(BinaryParserErrTypes::HValue),
+            b'w' | b'W' => return Err(BinaryParserErrTypes::WValue),
+            b'-' => return Err(BinaryParserErrTypes::DashValue),
             _ => return Err(BinaryParserErrTypes::OtherValue(*chr as char)),
         }
     }
@@ -61,13 +73,13 @@ pub(super) fn binary_str_to_vec_u8(binary_str: &str) -> Result<Vec<u8>, BinaryPa
         if head_idx < 8 {
             head_idx = 0
         } else {
-            head_idx = head_idx - 8;
+            head_idx -= 8;
         }
 
         if tail_idx < 8 {
             tail_idx = 0
         } else {
-            tail_idx = tail_idx - 8;
+            tail_idx -= 8;
         }
     }
     Ok(vec_u8)

tests/files.rs

@@ -0,0 +1,77 @@
+// Copyright (C) 2022 Yehowshua Immanuel
+// This program is distributed under both the GPLV3 license
+// and the YEHOWSHUA license, both of which can be found at
+// the root of the folder containing the sources for this program.
+
+// TODO: we should eventually be able to only test on just
+// the files const
+pub const FILES: [&str; 31] = [
+    "./tests/vcd-files/aldec/SPI_Write.vcd",
+    "./tests/vcd-files/ghdl/alu.vcd",
+    "./tests/vcd-files/ghdl/idea.vcd",
+    "./tests/vcd-files/ghdl/pcpu.vcd",
+    "./tests/vcd-files/gtkwave-analyzer/perm_current.vcd",
+    "./tests/vcd-files/icarus/CPU.vcd",
+    "./tests/vcd-files/icarus/rv32_soc_TB.vcd",
+    "./tests/vcd-files/icarus/test1.vcd",
+    "./tests/vcd-files/model-sim/CPU_Design.msim.vcd",
+    "./tests/vcd-files/model-sim/clkdiv2n_tb.vcd",
+    "./tests/vcd-files/my-hdl/Simple_Memory.vcd",
+    "./tests/vcd-files/my-hdl/sigmoid_tb.vcd",
+    "./tests/vcd-files/my-hdl/top.vcd",
+    "./tests/vcd-files/ncsim/ffdiv_32bit_tb.vcd",
+    "./tests/vcd-files/quartus/mipsHardware.vcd",
+    "./tests/vcd-files/quartus/wave_registradores.vcd",
+    "./tests/vcd-files/questa-sim/dump.vcd",
+    "./tests/vcd-files/questa-sim/test.vcd",
+    "./tests/vcd-files/riviera-pro/dump.vcd",
+    "./tests/vcd-files/systemc/waveform.vcd",
+    "./tests/vcd-files/treadle/GCD.vcd",
+    "./tests/vcd-files/vcs/Apb_slave_uvm_new.vcd",
+    "./tests/vcd-files/vcs/datapath_log.vcd",
+    "./tests/vcd-files/vcs/processor.vcd",
+    "./tests/vcd-files/verilator/swerv1.vcd",
+    "./tests/vcd-files/verilator/vlt_dump.vcd",
+    "./tests/vcd-files/vivado/iladata.vcd",
+    "./tests/vcd-files/xilinx_isim/test.vcd",
+    "./tests/vcd-files/xilinx_isim/test1.vcd",
+    // TODO : add signal ignore list to handle bitwidth mismatches
+    "./tests/vcd-files/xilinx_isim/test2x2_regex22_string1.vcd",
+    "./tests/vcd-files/scope_with_comment.vcd",
+];
+
+pub const GOOD_DATE_FILES: [&str; 24] = [
+    "./test-vcd-files/aldec/SPI_Write.vcd",
+    "./test-vcd-files/ghdl/alu.vcd",
+    "./test-vcd-files/ghdl/idea.vcd",
+    "./test-vcd-files/ghdl/pcpu.vcd",
+    "./test-vcd-files/gtkwave-analyzer/perm_current.vcd",
+    "./test-vcd-files/icarus/CPU.vcd",
+    "./test-vcd-files/icarus/rv32_soc_TB.vcd",
+    "./test-vcd-files/icarus/test1.vcd",
+    "./test-vcd-files/model-sim/CPU_Design.msim.vcd",
+    "./test-vcd-files/model-sim/clkdiv2n_tb.vcd",
+    "./test-vcd-files/my-hdl/Simple_Memory.vcd",
+    "./test-vcd-files/my-hdl/sigmoid_tb.vcd",
+    "./test-vcd-files/my-hdl/top.vcd",
+    "./test-vcd-files/questa-sim/dump.vcd",
+    "./test-vcd-files/questa-sim/test.vcd",
+    "./test-vcd-files/riviera-pro/dump.vcd",
+    "./test-vcd-files/vcs/Apb_slave_uvm_new.vcd",
+    "./test-vcd-files/vcs/datapath_log.vcd",
+    "./test-vcd-files/vcs/processor.vcd",
+    "./test-vcd-files/verilator/swerv1.vcd",
+    "./test-vcd-files/verilator/vlt_dump.vcd",
+    "./test-vcd-files/xilinx_isim/test.vcd",
+    "./test-vcd-files/xilinx_isim/test1.vcd",
+    "./test-vcd-files/xilinx_isim/test2x2_regex22_string1.vcd",
+];
+
+pub const BAD_DATE_FILES: [&str; 6] = [
+    "./test-vcd-files/ncsim/ffdiv_32bit_tb.vcd",
+    "./test-vcd-files/quartus/mipsHardware.vcd",
+    "./test-vcd-files/quartus/wave_registradores.vcd",
+    "./test-vcd-files/systemc/waveform.vcd",
+    "./test-vcd-files/treadle/GCD.vcd",
+    "./test-vcd-files/vivado/iladata.vcd",
+];

tests/integration_test.rs

@@ -0,0 +1,22 @@
+// Copyright (C) 2022 Yehowshua Immanuel
+// This program is distributed under both the GPLV3 license
+// and the YEHOWSHUA license, both of which can be found at
+// the root of the folder containing the sources for this program.
+use std::fs::File;
+
+mod files;
+use files::*;
+
+#[test]
+fn parse_all_VCDs() {
+    // see if we can parse all signal trees successfully
+    for file_name in FILES {
+        let file = File::open(file_name).unwrap();
+        let vcd = fastwave_backend::parse_vcd(file);
+
+        if !vcd.is_ok() {
+            dbg!(file_name);
+            vcd.unwrap();
+        }
+    }
+}

tests/vcd-files/scope_with_comment.vcd

@@ -0,0 +1,296 @@
+$date
+	Sat Dec 26 15:33:14 2020
+$end
+$version
+	ModelSim Version 10.5b
+$end
+$timescale
+	1ns
+$end
+
+$scope module clkdiv2n_tb $end
+$comment foo $end
+$var reg 1 ! clk $end
+$var reg 1 " reset $end
+$var wire 1 # clk_out $end
+
+$scope module t1 $end
+$var parameter 32 $ WIDTH $end
+$var parameter 32 % N $end
+$var wire 1 & clk $end
+$var wire 1 ' reset $end
+$var wire 1 # clk_out $end
+$var reg 3 ( r_reg [2:0] $end
+$var wire 1 ) r_nxt [2] $end
+$var wire 1 * r_nxt [1] $end
+$var wire 1 + r_nxt [0] $end
+$var reg 1 , clk_track $end
+$upscope $end
+$comment foo $end
+$upscope $end
+$comment foo $end
+$enddefinitions $end
+#0
+$comment foo $end
+$dumpvars
+0!
+x"
+bx (
+x,
+b11 $
+b110 %
+x#
+x+
+x*
+x)
+x'
+0&
+$end
+#5
+1"
+1'
+b0 (
+0,
+1+
+0*
+0)
+0#
+#10
+1!
+1&
+#15
+0"
+0'
+#20
+0!
+0&
+#30
+1!
+1&
+b1 (
+0+
+1*
+#40
+0!
+0&
+#50
+1!
+1&
+b10 (
+1+
+#60
+0!
+0&
+#70
+1!
+1&
+b11 (
+0+
+0*
+1)
+#80
+0!
+0&
+#90
+1!
+1&
+b100 (
+1+
+#100
+0!
+0&
+#110
+1!
+1&
+b101 (
+0+
+1*
+#120
+0!
+0&
+#130
+1!
+1&
+b0 (
+1,
+1+
+0*
+0)
+1#
+#140
+0!
+0&
+#150
+1!
+1&
+b1 (
+0+
+1*
+#160
+0!
+0&
+#170
+1!
+1&
+b10 (
+1+
+#180
+0!
+0&
+#190
+1!
+1&
+b11 (
+0+
+0*
+1)
+#200
+0!
+0&
+#210
+1!
+1&
+b100 (
+1+
+#220
+0!
+0&
+#230
+1!
+1&
+b101 (
+0+
+1*
+#240
+0!
+0&
+#250
+1!
+1&
+b0 (
+0,
+1+
+0*
+0)
+0#
+#260
+0!
+0&
+#270
+1!
+1&
+b1 (
+0+
+1*
+#280
+0!
+0&
+#290
+1!
+1&
+b10 (
+1+
+#300
+0!
+0&
+#310
+1!
+1&
+b11 (
+0+
+0*
+1)
+#320
+0!
+0&
+#330
+1!
+1&
+b100 (
+1+
+#340
+0!
+0&
+#350
+1!
+1&
+b101 (
+0+
+1*
+#360
+0!
+0&
+#370
+1!
+1&
+b0 (
+1,
+1+
+0*
+0)
+1#
+#380
+0!
+0&
+#390
+1!
+1&
+b1 (
+0+
+1*
+#400
+0!
+0&
+#410
+1!
+1&
+b10 (
+1+
+#420
+0!
+0&
+#430
+1!
+1&
+b11 (
+0+
+0*
+1)
+#440
+0!
+0&
+#450
+1!
+1&
+b100 (
+1+
+#460
+0!
+0&
+#470
+1!
+1&
+b101 (
+0+
+1*
+#480
+0!
+0&
+#490
+1!
+1&
+b0 (
+0,
+1+
+0*
+0)
+0#
+#500
+0!
+0&
+#510
+1!
+1&
+b1 (
+0+
+1*