feat: add assembly SourceLocation & SourceToken

This commit introduces new data structures that will associate metadata
with a token.

The introduced SourceLocation struct will allow the link between a
source path; either from a library or a disk MASM file, into a parsed
token - hence, also to its Instruction, Operation, and AST location.

SourceLocation is split from SourceToken because the former is intended
to be used globally, and the latter is specific to the parsing process.

related issue: #857

assembly/src/tokens/location.rs

@@ -0,0 +1,28 @@
+// SOURCE LOCATION
+// ================================================================================================
+
+/// A struct containing information about the location of a source item.
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub struct SourceLocation {
+    line: u32,
+    column: u32,
+}
+
+impl SourceLocation {
+
+    // CONSTRUCTORS
+    // -------------------------------------------------------------------------------------------------
+
+    /// Creates a new instance of [SourceLocation].
+    pub const fn new(line: u32, column: u32) -> Self {
+        Self { line, column }
+    }
+
+    // PUBLIC ACCESSORS
+    // -------------------------------------------------------------------------------------------------
+
+    /// Returns the line of the location.
+    pub const fn line(&self) -> u32 {
+        self.line
+    }
+}

assembly/src/tokens/mod.rs

@@ -3,8 +3,11 @@ use super::{
 };
 use core::fmt;
 
+mod location;
+pub use location::SourceLocation;
+
 mod tokenizer;
-pub use tokenizer::Tokenizer;
+use tokenizer::Tokenizer;
 
 mod stream;
 pub use stream::TokenStream;

assembly/src/tokens/stream.rs

@@ -32,25 +32,29 @@ impl<'a> TokenStream<'a> {
         let mut proc_comments = BTreeMap::new();
 
         // fetch all tokens
-        for (token, docs, line) in Tokenizer::from(source) {
-            match token {
+        for source in Tokenizer::from(source) {
+            match source.token() {
                 Some(token) => {
                     if token.starts_with(Token::EXPORT) || token.starts_with(Token::PROC) {
-                        let doc_comment = build_comment(&docs);
+                        let doc_comment = build_comment(source.docs());
                         proc_comments.insert(tokens.len(), doc_comment);
-                    } else if !docs.is_empty() {
-                        return Err(ParsingError::dangling_procedure_comment(line as usize));
+                    } else if !source.docs().is_empty() {
+                        return Err(ParsingError::dangling_procedure_comment(
+                            source.line() as usize
+                        ));
                     }
 
                     tokens.push(token);
-                    lines.push(line as usize);
+                    lines.push(source.line() as usize);
                 }
 
                 None if tokens.is_empty() => {
-                    module_comment = build_comment(&docs);
+                    module_comment = build_comment(source.docs());
                 }
 
-                None => return Err(ParsingError::dangling_procedure_comment(line as usize)),
+                None => {
+                    return Err(ParsingError::dangling_procedure_comment(source.line() as usize))
+                }
             }
         }