rvasm 0.0.1a1__tar.gz

rvasm-0.0.1a1/LICENSE

@@ -0,0 +1,7 @@
+Copyright © 2026 Will Arden
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

rvasm-0.0.1a1/PKG-INFO

@@ -0,0 +1,80 @@
+Metadata-Version: 2.4
+Name: rvasm
+Version: 0.0.1a1
+Summary: A simple RISC-V assembler written in Python
+Author-email: Will Arden <will.ardxn@gmail.com>
+License: Copyright © 2026 Will Arden
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+Project-URL: Homepage, https://github.com/will-arden/rvasm
+Project-URL: Source, https://github.com/will-arden/rvasm
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# rvasm: A Python-Based RISC-V Assembler
+**rvasm** aims to provide a simple and easy-to-use RISC-V assembler, as both a **command-line tool** and a **Python package**. **rvasm** makes it easy to define and use **custom instructions**, simply by providing a JSON file.
+
+## Getting started
+You can install **rvasm** using `pip`, as follows:
+
+> `pip install rvasm`
+
+**rvasm** can be used either as a **command-line tool**, or as a **Python package** which can be used in a Python program.
+
+The command-line tool can be used to assemble an RV32I text file, as demonstrated below:
+> `rvasm my_file.asm`
+
+This will produce an output file `out.mem`, containing your assembled RV32I in hexadecimal. For help on other command-line options, use:
+> `rvasm --help`
+
+Here is an example on how you can use **rvasm** in a Python project:
+>```python
+>import rvasm
+>my_assembler = rvasm.RVAsm()                # Create an Assembler object
+>with open("my_input_file.asm", "r") as f:   # Open the assembly file
+>    my_assembler.Assemble(f)                # Generate the machine code
+>```
+
+## Assembling custom instructions
+**rvasm** makes assembling custom instructions straightforward.
+
+Firstly, create a **JSON file** detailing your custom instructions ([use this reference](https://github.com/will-arden/rvasm/tree/main/src/rvasm/json/RV32I.json)). You can specify one or more RISC-V extensions in the same file, or use multiple files. An example would be like so:
+> ```json
+> {
+>     "MY_CUSTOM_EXTENSION": [
+>         {
+>             "instr": "addi",
+>             "format": "instr rd, rs1, imm",
+>             "width": 32,
+>             "encoding": "imm[11:0] & rs1[4:0] & funct3[2:0] & rd[4:0] & opcode[6:0]",
+>             "opcode": "0010011",
+>             "funct3": "000",
+>             "funct7": null
+>         }
+>     ]
+> }
+> ```
+
+To include the new extension(s) from the command line, use the `--include` option, as below:
+> `rvasm my_file.asm --include my_custom_extension.json`
+
+The following example shows how you can use **rvasm** to assemble custom RISC-V instructions in your Python code:
+> ```python
+> import rvasm
+> asm = rvasm.RVAsm()
+> with open("my_custom_extension.json", "r") as f:
+>     asm.IncludeFromJSON(f)
+> with open("my_file.asm", "r") as f:
+>     asm.Assemble(f)
+> ```
+
+This project is a work-in-progress, so please keep checking in! Feel free to create issues and suggest improvements.
+
+## License
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

rvasm-0.0.1a1/README.md

@@ -0,0 +1,61 @@
+# rvasm: A Python-Based RISC-V Assembler
+**rvasm** aims to provide a simple and easy-to-use RISC-V assembler, as both a **command-line tool** and a **Python package**. **rvasm** makes it easy to define and use **custom instructions**, simply by providing a JSON file.
+
+## Getting started
+You can install **rvasm** using `pip`, as follows:
+
+> `pip install rvasm`
+
+**rvasm** can be used either as a **command-line tool**, or as a **Python package** which can be used in a Python program.
+
+The command-line tool can be used to assemble an RV32I text file, as demonstrated below:
+> `rvasm my_file.asm`
+
+This will produce an output file `out.mem`, containing your assembled RV32I in hexadecimal. For help on other command-line options, use:
+> `rvasm --help`
+
+Here is an example on how you can use **rvasm** in a Python project:
+>```python
+>import rvasm
+>my_assembler = rvasm.RVAsm()                # Create an Assembler object
+>with open("my_input_file.asm", "r") as f:   # Open the assembly file
+>    my_assembler.Assemble(f)                # Generate the machine code
+>```
+
+## Assembling custom instructions
+**rvasm** makes assembling custom instructions straightforward.
+
+Firstly, create a **JSON file** detailing your custom instructions ([use this reference](https://github.com/will-arden/rvasm/tree/main/src/rvasm/json/RV32I.json)). You can specify one or more RISC-V extensions in the same file, or use multiple files. An example would be like so:
+> ```json
+> {
+>     "MY_CUSTOM_EXTENSION": [
+>         {
+>             "instr": "addi",
+>             "format": "instr rd, rs1, imm",
+>             "width": 32,
+>             "encoding": "imm[11:0] & rs1[4:0] & funct3[2:0] & rd[4:0] & opcode[6:0]",
+>             "opcode": "0010011",
+>             "funct3": "000",
+>             "funct7": null
+>         }
+>     ]
+> }
+> ```
+
+To include the new extension(s) from the command line, use the `--include` option, as below:
+> `rvasm my_file.asm --include my_custom_extension.json`
+
+The following example shows how you can use **rvasm** to assemble custom RISC-V instructions in your Python code:
+> ```python
+> import rvasm
+> asm = rvasm.RVAsm()
+> with open("my_custom_extension.json", "r") as f:
+>     asm.IncludeFromJSON(f)
+> with open("my_file.asm", "r") as f:
+>     asm.Assemble(f)
+> ```
+
+This project is a work-in-progress, so please keep checking in! Feel free to create issues and suggest improvements.
+
+## License
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

rvasm-0.0.1a1/pyproject.toml

@@ -0,0 +1,24 @@
+[project]
+name = "rvasm"
+version = "0.0.1a1"
+description = "A simple RISC-V assembler written in Python"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { file = "LICENSE" }
+authors = [
+    { name = "Will Arden", email = "will.ardxn@gmail.com" }
+]
+
+[project.urls]
+Homepage = "https://github.com/will-arden/rvasm"
+Source = "https://github.com/will-arden/rvasm"
+
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[project.scripts]
+rvasm = "rvasm.rvasm:main"

rvasm-0.0.1a1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

rvasm-0.0.1a1/src/rvasm/__init__.py

@@ -0,0 +1 @@
+from .rvasm import RVAsm

rvasm-0.0.1a1/src/rvasm/inspector.py

@@ -0,0 +1,83 @@
+from pathlib import Path
+import json
+
+class Inspector():
+
+    def __init__(self):
+
+        # Inspect all JSON files
+        dir = Path(__file__).parent / "json"
+        for json_file in dir.glob("*.json"):
+            with open(json_file, "r") as f:
+                json_data = json.load(f)
+                self.InspectJSON(json_data)
+
+    class InspectorError(Exception):
+        def __init__(self, message: str):
+            super().__init__(message)
+
+    # Method to inspect a JSON file containing ISA information
+    def InspectJSON(self, json_data: json):
+        
+        # Check if any illegal characters are found in the instruction formats
+        for extension_name, extension_data in json_data.items():
+            for instruction in extension_data:
+                for attr, val in instruction.items():
+                    match attr:
+
+                        case "instr":
+                            legal_chars = ".abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ"
+                            if (val == None or val == ""):
+                                raise self.InspectorError(f"Empty attribute '{attr}' found in instruction '{instruction['instr']} in extension {extension_name}.'")
+                            for c in val:
+                                if (c not in legal_chars):
+                                    raise self.InspectorError(f"Illegal character '{c}' found in attribute '{attr}' of instruction '{instruction['instr']}' in extension '{extension_name}'.")
+
+                        case "format":
+                            legal_chars = " ,()abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
+                            if (val == None or val == ""):
+                                raise self.InspectorError(f"Empty attribute '{attr}' found in instruction '{instruction['instr']} in extension {extension_name}.'")
+                            for c in val:
+                                if (c not in legal_chars):
+                                    raise self.InspectorError(f"Illegal character '{c}' found in attribute '{attr}' of instruction '{instruction['instr']}' in extension '{extension_name}'.")
+
+                        case "width":
+                            if not (isinstance(val, int)) or (val < 8) or (val % 8 != 0):
+                                raise self.InspectorError(f"Illegal width field found for instruction '{instruction['instr']}' in extension '{extension_name}'. Only integers are permitted.")
+
+                        case "encoding":
+                            legal_chars = " ,[:]&abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
+                            if (val == None or val == ""):
+                                raise self.InspectorError(f"Empty attribute '{attr}' found in instruction '{instruction['instr']} in extension {extension_name}.'")
+                            for c in val:
+                                if (c not in legal_chars):
+                                    raise self.InspectorError(f"Illegal character '{c}' found in attribute '{attr}' of instruction '{instruction['instr']}' in extension '{extension_name}'.")
+
+                        case "opcode":
+                            legal_chars = "01"
+                            if (val == None or val == ""):
+                                raise self.InspectorError(f"Empty attribute '{attr}' found in instruction '{instruction['instr']} in extension {extension_name}.'")
+                            for c in val:
+                                if (c not in legal_chars):
+                                    raise self.InspectorError(f"Illegal character '{c}' found in attribute '{attr}' of instruction '{instruction['instr']}' in extension '{extension_name}'.")
+
+                        case "funct3":
+                            legal_chars = "01"
+                            if (val == None or val == ""):
+                                continue
+                            for c in val:
+                                if (c not in legal_chars):
+                                    raise self.InspectorError(f"Illegal character '{c}' found in attribute '{attr}' of instruction '{instruction['instr']}' in extension '{extension_name}'.")
+
+                        case "funct7":
+                            legal_chars = "01"
+                            if (val == None or val == ""):
+                                continue
+                            for c in val:
+                                if (c not in legal_chars):
+                                    raise self.InspectorError(f"Illegal character '{c}' found in attribute '{attr}' of instruction '{instruction['instr']}' in extension '{extension_name}'.")
+
+                        
+                        # Raise an error for unexpected attributes
+                        case _:
+                            raise self.InspectorError(f"Unexpected attribute '{attr}' found for {extension_name} instruction {instruction['instr']} in JSON file")

rvasm-0.0.1a1/src/rvasm/library.py

@@ -0,0 +1,58 @@
+import json
+from typing import TextIO
+import importlib.resources as res 
+from pathlib import Path
+
+class Library():
+
+    # At runtime, this will be populated with declared and included instructions
+    working_lib = []
+
+    # Declared ISAs
+    core_isas = {}          # These ISAs are supported by default - simply include them to use
+    extra_isas = {}         # Extra/custom ISAs must be declared before they can be included for use
+
+    def __init__(self):
+
+        # Declare the core ISAs (within json/ directory)
+        for file in res.files("rvasm.core_ext").iterdir():                              # Iterate through every JSON file
+            if (file.name.endswith(".json")):
+                with file.open("r", encoding="utf-8-sig") as f:
+                    json_data = json.load(f)
+                    for isa_name, isa_data in json_data.items():                        # Add the ISA data to the dictionary
+                        self.core_isas[isa_name] = isa_data
+
+    class LibraryError(Exception):
+        def __init__(self, message: str):
+            super().__init__(message)
+
+    # Method to declare extra/custom ISA(s) using a JSON file
+    def DeclareFromJSONData(self, json_data: json):
+        for isa_name, isa_data in json_data.items():    # Iterate through ISAs
+            self.extra_isas[isa_name] = isa_data        # and add the data to the dictionary
+
+        # Check for duplicate instructions added to the working library
+        seen_instructions = []
+        for entry in self.working_lib:
+            if (entry["instr"] in seen_instructions):
+                raise self.LibraryError(f"Found multiple definitions for the same instruction ({entry['instr']}) when compiling the working library.")
+            seen_instructions.append(entry["instr"])
+
+    # Method to update the working library based on a given include list
+    def UpdateWorkingLibrary(self, include: list[str]):
+        isa_found = False
+        for isa_to_include in include:                                      # Iterate through every ISA in the include list
+            for collection in (self.core_isas, self.extra_isas):                # Repeat for both core and extra ISA dictionaries
+                if (collection.get(isa_to_include)):
+                    isa_found = True
+                    for instruction in collection.get(isa_to_include):
+                        instr_to_add = instruction.copy()
+                        self.working_lib.append(instr_to_add)                   # Append the instruction to the working library
+            if (not isa_found):
+                raise self.LibraryError(f"Could not recognise ISA: {isa_to_include}")
+    
+    # Method to lookup an instruction from the working library
+    def WorkingLibraryLookUp(self, search_term: str):
+        for instruction in self.working_lib:
+            if (instruction["instr"] == search_term):
+                    return instruction

rvasm-0.0.1a1/src/rvasm/processor.py

@@ -0,0 +1,161 @@
+from rvasm.tokeniser import Tokeniser
+
+class Processor():
+
+    def __init__(self, library):
+        self.library = library                  # Shared Library object
+        self.instructions = []                  # Store tokenised instructions
+        self.labels = []                        # Store labels with a program index
+        self.index = 0                          # Program index (program counter / 4)
+        self.tokeniser = Tokeniser(library)     # Object responsible for tokenising instructions
+
+    class ProcessorError(Exception):
+        def __init__(self, message):
+            super().__init__(message)
+
+    # Method to reset the Processor, ready for another file to assemble
+    def Reset(self):
+        self.instructions = []
+        self.labels = []
+
+    # Method to process the next line of the assembly file
+    def ProcessLine(self, line: str):
+
+        line = line.rstrip()                # Strip the newline character from the line
+        line = line.split("#")[0]           # Ignore comments
+        line = line.strip()                 # Remove whitespace
+
+        # Ignore empty lines
+        if (not line):
+            return
+        
+        # Parse labels
+        if (":" in line):
+            label_parts = line.split(":")
+
+            if (label_parts[1].rstrip()):
+                raise self.ProcessorError(f"Unexpected characters following label declaration: {line}")
+
+            label = {"name": label_parts[0], "index": self.index}
+            self.labels.append(label)
+            return
+
+        # Tokenise instructions
+        tokens = self.tokeniser.Tokenise(line)
+
+        # Look-up the library data for this instruction
+        lib_data = self.library.WorkingLibraryLookUp(tokens["instr"])
+        if (lib_data == None):
+            raise self.ProcessorError(f"Could not find instruction {tokens['instr']} in the working library.")
+
+        # Iterate through the tokens
+        for key, value in tokens.items():
+
+            # No need to check the instruction keyword; this must be correct
+            if (key == "instr"):
+                continue
+
+            # Ensure any x's are removed from register fields, then convert to an integer between 0-31
+            if (key in ("rd", "rs1", "rs2")):
+                tokens[key] = tokens[key].replace("x", "")
+                tokens[key] = int(tokens[key])
+                if (tokens[key] < 0 or tokens[key] > 31):
+                    raise self.ProcessorError(f"Register {str(tokens[key])} outside of range 0-31.")
+
+            # Identify keys which have plain-text values (these might be labels)
+            if (value.isalpha()):
+                
+                # TODO: some specific strings might be mappable to some other function
+
+                # Resolve unknown plain-text values to labels
+                for lbl in self.labels:
+                    if (lbl["name"] == tokens[key]):
+                        tokens[key] = lbl["index"] * int(lib_data["width"] / 8)
+
+            # Convert immediate values to integers (if they are not already)
+            if (key == "imm"):
+                tokens[key] = int(tokens[key])
+
+        # Finally, increment the index and append the instruction to the list of parsed instructions
+        self.index += 1
+        self.instructions.append(tokens)
+
+    # Method to generate the final machine code
+    def GenerateBinaries(self):
+        machine_code = []
+
+        # Iterate through each instruction
+        for line in self.instructions:
+            lib_data = self.library.WorkingLibraryLookUp(line["instr"])     # Fetch the relevant library data
+            binary = ""                                                     # Placeholder for binarised instruction
+
+            # Iterate through each field of the encoding
+            fields = [p.strip() for p in lib_data["encoding"].split("&")]
+            for field in fields:
+
+                # Parse fields which use bit-slicing
+                if ("[" in field and "]" in field and ":" in field):
+                    fname, remainder = field.split("[", 1)                  # Get the name of the field
+                    fupper, remainder = remainder.split(":", 1)             # Get the upper bound
+                    flower = remainder.split("]")[0]                        # Get the lower bound
+                    (fupper, flower) = (int(fupper), int(flower))           # Convert bounds to integers
+                    
+                    # Try to retrieve the information from the instruction
+                    if (line.get(fname.strip()) is not None):
+                        fdata = line.get(fname.strip())
+
+                    # Failing that, try to retrieve the information from the library data
+                    elif (lib_data.get(fname.strip()) is not None):
+                        fdata = lib_data.get(fname.strip())
+
+                    # If the information can't be found, raise an error
+                    else:
+                        raise self.ProcessorError(f"Couldn't find information about '{fname.strip()}' in the instruction or in the corresponding library data.")
+
+                    # Add the bits to the binary string of the instruction
+                    fvalue = format(fdata, "064b") if isinstance(fdata, int) else fdata
+                    binary += fvalue[-1 - fupper : len(fvalue) - flower]
+
+                # Parse fields which index single bits
+                elif ("[" in field and "]" in field and not ":" in field):
+                    fname, remainder = field.split("[", 1)                  # Get the name of the field
+                    findex = int(remainder.split("]", 1)[0])                # Get the index of the bit of interest
+
+                    # Try to retrieve the information from the instruction
+                    if (line.get(fname.strip()) is not None):
+                        fdata = line.get(fname.strip())
+                    
+                    # Failing that, try to retrieve the information from the library data
+                    elif (lib_data.get(fname.strip()) is not None):
+                        fdata = lib_data.get(fname.strip())
+                    
+                    # If the information can't be found, raise an error
+                    else:
+                        raise self.ProcessorError(f"Couldn't find information about '{fname.strip()}' in the instruction or in the corresponding library data.")
+                
+                    # Add the bits to the binary string of the instruction
+                    fvalue = format(fdata, "064b") if isinstance(fdata, int) else fdata
+                    binary += fvalue[-1 - findex]
+
+                # Where no bit-indexing or bit-slicing is required
+                elif (not "[" in field and not "]" in field and not ":" in field):
+                    if (line.get(field.strip()) is not None):
+                        binary += line.get(field.strip())
+                    elif (lib_data.get(field.strip()) is not None):
+                        binary += lib_data.get(field.strip())
+                    else:
+                        raise self.ProcessorError(f"Couldn't find information about '{field.strip()}' in the instruction or in the corresponding library data.")
+                
+                # Encoding could not be interpreted
+                else:
+                    raise self.ProcessorError(f"Invalid encoding syntax in JSON data: {field}")
+
+            # Check that the length of the generated binary is valid
+            if (len(binary) != lib_data.get("width")):
+                raise self.ProcessorError(f"Expected the width of the '{lib_data['instr']}' instruction to be {lib_data['width']}; got {len(binary)}.")
+            
+            # Append the binary instruction to the list of machine code instructions
+            machine_code.append(binary)
+        
+        return machine_code
+    

rvasm-0.0.1a1/src/rvasm/rvasm.py

@@ -0,0 +1,136 @@
+import argparse
+import json
+from typing import TextIO
+
+from .inspector import Inspector
+from .library import Library
+from .processor import Processor
+
+def main():
+
+    # Handle arguments
+    parser = argparse.ArgumentParser(description="A Python-based, JSON-driven RISC-V assembler.")
+    parser.add_argument("input", help="input file path")
+    parser.add_argument("-o", "--output", help="output file path")
+    parser.add_argument("-f", "--format", help="output format (binary/hex)")
+    parser.add_argument("-i", "--include", nargs="*", help="specify any number of JSON files detailing extra/custom ISA(s)")
+    args = parser.parse_args()
+
+    # Create a new RVAsm object per command
+    rvasm = RVAsm()
+
+    with open(args.input, "r", encoding="utf-8") as asm_file:
+
+        # Placeholder variables to pass to rvasm object
+        OUTPUT = None
+        OUTPUT_FORMAT = None
+        INCLUDE = None
+
+        # Overwrite placeholders with any arguments (if present)
+        if (args.output):
+            OUTPUT = args.output
+        if (args.format):
+            OUTPUT_FORMAT = args.format
+        if (args.include):
+            INCLUDE = args.include
+
+        # Include ISAs
+        if (INCLUDE and len(INCLUDE) > 0):
+            for json_path in INCLUDE:
+                with open(json_path, "r") as json_file:
+                    rvasm.IncludeFromJSON(json_file)
+        
+        # Go!
+        rvasm.Assemble(asm_file, output=OUTPUT, output_format=OUTPUT_FORMAT)
+
+class RVAsm():
+
+    def __init__(self):
+
+        # Verify the RVAsm setup using the Inspector class
+        try:
+            self.inspector = Inspector()
+        except Exception as e:
+            print(f"Failed to created the RVAsm object; setup could not be verified.")
+            print(f"{e}")
+            exit()
+        self.library = Library()                                                # Create a new Library object
+
+        self.default_includes = ["RV32I"]                                       # Specify ISAs to include by default
+        self.user_includes = []                                                 # Placeholder for user-specified inclusions
+        self._UpdateWorkingLibrary(self.default_includes + self.user_includes)  # Update and compile the working library based on the include list
+
+        self.processor = Processor(self.library)                                # Create a Processor object with the shared library
+        self.bin = None                                                         # Placeholder for the assembled machine code
+
+    class RVAsmError(Exception):
+        def __init__(self, message: str):
+            super().__init__(message)
+
+    # Method to assemble a '.asm' file
+    def Assemble(self, file: TextIO, output:str=None, output_format:str=None):
+
+        # Internally set default arguments (easier for argparse)
+        if (not output):
+            output = "out.mem"
+        if (not output_format):
+            output_format = "hex"
+
+        # Reset the processor
+        self.processor.Reset()
+        
+        # Process each line of the .asm file, catching any exceptions and reporting as debug information
+        for i, line in enumerate(file):
+            try:
+                self.processor.ProcessLine(line)
+            except Exception as e:
+                print(f"\n{type(e).__name__} caused the following line to fail:")
+                print(line.rstrip("\n"))
+                print(f"{e}")
+                exit()
+
+        self.bin = self.processor.GenerateBinaries()        # Create the machine code
+        self._WriteOutput(                                  # Output the file to the current directory
+                filename=output,
+                output_format=output_format
+            )
+
+    # Method to reset the assembler
+    def Reset(self):
+        self.processor.Reset()
+        self.user_includes = []
+        self._UpdateWorkingLibrary()
+
+    # Method to include ISA data from a JSON file
+    def IncludeFromJSON(self, json_file: TextIO):
+        json_data = json.load(json_file)
+        self.library.DeclareFromJSONData(json_data)
+
+        # Update the include list
+        for isa_name, isa_data in json_data.items():
+            if not (isa_name in self.user_includes):
+                self._IncludeISA(isa_name)
+        
+    # Method to include an ISA of a particular name for use
+    def _IncludeISA(self, name):
+        if not (name in self.user_includes):                                    # Avoid double-inclusions
+            self.user_includes.append(name)                                     # Append the name of the ISA to the user includes
+        self._UpdateWorkingLibrary(self.default_includes + self.user_includes)  # Update the working library
+
+    # Method to update the working library following changes to the include list
+    def _UpdateWorkingLibrary(self, total_include_list: list[str]):
+        self.library.UpdateWorkingLibrary(total_include_list)
+
+    # Method to write the to an output file
+    def _WriteOutput(self, filename="out.mem", output_format="hex"):
+        write_content = self.bin
+
+        with open(filename, "w") as f:
+            for line in write_content:
+
+                # If "hex" is selected as the format, convert each line to a hexadecimal number
+                if (output_format.lower() == "hex"):
+                    line = format(int(line, 2), "0" + str(int(len(line) / 4)) + "x")
+
+                # Write each line to the output file
+                f.write(line + "\n")

rvasm-0.0.1a1/src/rvasm/tokeniser.py

@@ -0,0 +1,41 @@
+import re
+
+from rvasm.library import Library
+
+class Tokeniser():
+
+    def __init__(self, library):
+        self.library = library
+
+    class TokeniserError(Exception):
+        def __init__(self, message: str):
+            super().__init__(message)
+
+    # Method to tokenise an instruction
+    def Tokenise(self, line: str):
+        tokenised_instruction = {}
+        library_data = None
+        instr = None
+
+        # Split the instruction into parts
+        parts = re.split(r"[,()\s]+", line)                 # Split for whitespace, commas and brackets
+        parts = [p.strip() for p in parts if p.strip()]     # Prune separators and useless parts
+        instr = parts[0]                                    # Identify the instruction keyword
+
+        # Firstly, retrieve the data about the instruction from the library
+        library_data = self.library.WorkingLibraryLookUp(instr)
+
+        # Throw an error if the instruction can't be found in the working library
+        if (library_data == None):
+            raise self.TokeniserError(f"Unknown instruction {instr} which cannot be found in the working library.")
+
+        # Tokenise the format string
+        fparts = re.split(r"[,()\s]+", library_data["format"])      # Split for whitespace, commas and brackets
+        fparts = [fp.strip() for fp in fparts if fp.strip()]        # Prune separators and useless parts
+        
+        # Match together each field with the corresponding value in the written instruction
+        for i, fp in enumerate(fparts):
+            tokenised_instruction[fp] = parts[i].lower()
+
+        return tokenised_instruction
+    

rvasm-0.0.1a1/src/rvasm.egg-info/PKG-INFO

@@ -0,0 +1,80 @@
+Metadata-Version: 2.4
+Name: rvasm
+Version: 0.0.1a1
+Summary: A simple RISC-V assembler written in Python
+Author-email: Will Arden <will.ardxn@gmail.com>
+License: Copyright © 2026 Will Arden
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+Project-URL: Homepage, https://github.com/will-arden/rvasm
+Project-URL: Source, https://github.com/will-arden/rvasm
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# rvasm: A Python-Based RISC-V Assembler
+**rvasm** aims to provide a simple and easy-to-use RISC-V assembler, as both a **command-line tool** and a **Python package**. **rvasm** makes it easy to define and use **custom instructions**, simply by providing a JSON file.
+
+## Getting started
+You can install **rvasm** using `pip`, as follows:
+
+> `pip install rvasm`
+
+**rvasm** can be used either as a **command-line tool**, or as a **Python package** which can be used in a Python program.
+
+The command-line tool can be used to assemble an RV32I text file, as demonstrated below:
+> `rvasm my_file.asm`
+
+This will produce an output file `out.mem`, containing your assembled RV32I in hexadecimal. For help on other command-line options, use:
+> `rvasm --help`
+
+Here is an example on how you can use **rvasm** in a Python project:
+>```python
+>import rvasm
+>my_assembler = rvasm.RVAsm()                # Create an Assembler object
+>with open("my_input_file.asm", "r") as f:   # Open the assembly file
+>    my_assembler.Assemble(f)                # Generate the machine code
+>```
+
+## Assembling custom instructions
+**rvasm** makes assembling custom instructions straightforward.
+
+Firstly, create a **JSON file** detailing your custom instructions ([use this reference](https://github.com/will-arden/rvasm/tree/main/src/rvasm/json/RV32I.json)). You can specify one or more RISC-V extensions in the same file, or use multiple files. An example would be like so:
+> ```json
+> {
+>     "MY_CUSTOM_EXTENSION": [
+>         {
+>             "instr": "addi",
+>             "format": "instr rd, rs1, imm",
+>             "width": 32,
+>             "encoding": "imm[11:0] & rs1[4:0] & funct3[2:0] & rd[4:0] & opcode[6:0]",
+>             "opcode": "0010011",
+>             "funct3": "000",
+>             "funct7": null
+>         }
+>     ]
+> }
+> ```
+
+To include the new extension(s) from the command line, use the `--include` option, as below:
+> `rvasm my_file.asm --include my_custom_extension.json`
+
+The following example shows how you can use **rvasm** to assemble custom RISC-V instructions in your Python code:
+> ```python
+> import rvasm
+> asm = rvasm.RVAsm()
+> with open("my_custom_extension.json", "r") as f:
+>     asm.IncludeFromJSON(f)
+> with open("my_file.asm", "r") as f:
+>     asm.Assemble(f)
+> ```
+
+This project is a work-in-progress, so please keep checking in! Feel free to create issues and suggest improvements.
+
+## License
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

rvasm-0.0.1a1/src/rvasm.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+src/rvasm/__init__.py
+src/rvasm/inspector.py
+src/rvasm/library.py
+src/rvasm/processor.py
+src/rvasm/rvasm.py
+src/rvasm/tokeniser.py
+src/rvasm.egg-info/PKG-INFO
+src/rvasm.egg-info/SOURCES.txt
+src/rvasm.egg-info/dependency_links.txt
+src/rvasm.egg-info/entry_points.txt
+src/rvasm.egg-info/top_level.txt

rvasm-0.0.1a1/src/rvasm.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

rvasm-0.0.1a1/src/rvasm.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+rvasm = rvasm.rvasm:main

rvasm-0.0.1a1/src/rvasm.egg-info/top_level.txt

@@ -0,0 +1 @@
+rvasm