refactor parse a bit

src/vcd/parse/scopes.rs

@@ -104,6 +104,80 @@ pub(super) fn parse_var<'a>(
     Ok(())
 }
 
+/// Sometimes, variables can be listed outside of scopes.
+/// We call these orphaned vars.
+fn parse_orphaned_vars<'a>(
+    word_reader      : &mut WordReader,
+    vcd              : &'a mut VCD,
+    signal_map       : &mut HashMap<String, Signal_Idx>
+) -> Result<(), String> {
+    // create scope for unscoped signals if such a scope does not
+    // yet exist
+    let scope_name = "Orphaned Signals";
+
+    // set default scope_idx to the count of existing scope as we
+    // generally set scope.self_idx to the number of existing scopes
+    // when that particular scope was inserted
+    let mut scope_idx = Scope_Idx(vcd.all_scopes.len());
+
+    // Override scope_idx if we find a scope named "Orphaned Signals"
+    // already exists
+    let mut scope_already_exists = false;
+    for scope in &vcd.all_scopes {
+        if scope.name == scope_name {
+            scope_idx = scope.self_idx;
+            scope_already_exists = true;
+            break
+        }
+    }
+
+    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![]
+            }
+        );
+        vcd.scope_roots.push(scope_idx);
+    }
+    
+    // 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)?;
+
+    loop {
+        let next_word = word_reader.next_word();
+
+        // we shouldn't reach the end of the file here...
+        if next_word.is_none() {
+            let (f, l )= (file!(), line!());
+            let msg = format!("Error near {f}:{l}.\
+                               Reached end of file without terminating parser");
+            Err(msg)?;
+        };
+
+        let (word, cursor) = next_word.unwrap();
+
+        match word {
+            "$var" => {
+                parse_var(word_reader, scope_idx, vcd, signal_map)?;
+            }
+            "$scope" => {break}
+            _ => {
+                let (f, l )= (file!(), line!());
+                let msg = format!("Error near {f}:{l}.\
+                Expected $scope or $var, found {word} at {cursor:?}");
+                Err(msg)?;
+            }
+        };
+    }
+
+    Ok(())
+}
+
 #[named]
 pub(super) fn parse_signal_tree<'a>(
     word_reader      : &mut WordReader,
@@ -207,12 +281,42 @@ pub(super) fn parse_scopes<'a>(
     vcd              : &'a mut VCD,
     signal_map       : &mut HashMap<String, Signal_Idx>
 ) -> Result<(), String> {
-    // we've already seen `$scope`, so here we just jump right in
+    // get the current word
+    let (f, l ) = (file!(), line!());
+    let msg = format!("Error near {f}:{l}. Current word empty!");
+    let (word, cursor) = word_reader.curr_word().ok_or(msg)?;
+
+    // we may have orphaned vars that occur before the first scope
+    if word == "$var" {
+        parse_orphaned_vars(word_reader, vcd, signal_map)?;
+    } 
+    
+    // get the current word
+    let (f, l ) = (file!(), line!());
+    let msg = format!("Error near {f}:{l}. Current word empty!");
+    let (word, cursor) = word_reader.curr_word().ok_or(msg)?;
+
+    // the current word should be "scope", as `parse_orphaned_vars`(if it
+    // was called), should have terminated upon encountering "$scope".
+    // If `parse_orphaned_vars` was not called, `parse_scopes` should still
+    // have only been called if the caller encountered the word "$scope"
+    if word != "$scope" {
+        let (f, l )= (file!(), line!());
+        let msg = format!("Error near {f}:{l}.\
+                            Expected $scope or $var, found {word} at {cursor:?}");
+        return Err(msg)
+    }
+
+    // now for the interesting part
     parse_signal_tree(word_reader, None, vcd, signal_map)?;
 
     let err = format!("reached end of file without parser leaving {}", function_name!());
     let expected_keywords = ["$scope", "$enddefinitions"];
 
+    // there could be multiple signal trees, and unfortunately, we
+    // can't merge the earlier call to `parse_signal_tree` into this loop
+    // because this loop gets a word from `next_word` instead of 
+    // `curr_word()`.
     loop {
         let (word, cursor) = word_reader.next_word().ok_or(&err)?;
         match word {
@@ -223,14 +327,16 @@ pub(super) fn parse_scopes<'a>(
                 ident(word_reader, "$end")?;
                 break
             }
-            // we ignore comments
             "comment" => {
+                // although we don't store comments, we still need to advance the
+                // word_reader cursor to the end of the comment
                 loop {
                     if ident(word_reader, "$end").is_ok() {break}
                 }
             }
             _ => {
-                let err = format!("found keyword `{word}` but expected oneof `{expected_keywords:?}` on {cursor:?}");
+                let err = format!("found keyword `{word}` but expected one \
+                of `{expected_keywords:?}` on {cursor:?}");
                 return Err(err)
     
             }