📖 Dictionary in Assembly (Pet Project)

A lightweight dictionary implementation built in x86 Assembly using linked lists as the underlying data structure. This project demonstrates low-level memory management, macro definitions, and efficient searching mechanisms. It also includes a modular I/O library developed in Assembly for handling input and output operations.

---

✨ Features

• 🧩 Macro-powered dictionary creation: Automatically build linked list dictionaries using assembly macros.
• 🔍 Efficient word search: Search keys in the dictionary using null-terminated strings.
• 🛠️ Modular structure: Well-structured, maintainable assembly code.
• ✅ Automated testing and Makefile support: Ensure correctness with provided test cases.

---

📁 Project Structure

/dictionary
    ├── lib.asm         # I/O library implementation (from Assignment 1)
    ├── lib.inc         # Header file for I/O library
    ├── dict.asm        # Linked list search function
    ├── dict.inc        # Header for the search function
    ├── colon.inc       # Macro definitions for dictionary entries
    ├── words.inc       # Dictionary entries
    ├── main.asm        # Main program with user input and search logic
    ├── Makefile        # Build system with dependencies
    └── tests/          # Test cases for the dictionary

---

📚 Inside the Project: Core Components

1. I/O Library (lib.asm)

The project includes an I/O library implemented in Assembly to handle basic input/output operations. Originally developed as part of Assignment 1, this library can:

• Read strings and integers from input.
• Parse integers.
• Print strings and numbers to output.

This library demonstrates key low-level programming concepts such as:

• System calls (e.g., read, write).
• Register management and stack alignment.
• Efficient memory access and manipulation.

---

📄 I/O Library Documentation

Assignment 1: Input/Output Library in Assembly

This I/O library provides essential low-level functions for working with strings and numbers in Assembly. Here’s what you need to know:

---

🔧 Preparation

Before implementing the library, you should be familiar with:

• Basics of Assembly instructions:

  • xor, jmp, cmp, mov
  • Arithmetic instructions like add, imul, sub, idiv
  • Control flow (call, ret)
  • Stack management (push, pop)

• System calls in Linux (e.g., read and write using syscall).

• Register usage and memory alignment (e.g., aligning rsp to 16 bytes).

---

🛠️ Key Implemented Functions

The following functions are part of the library and available for use in the dictionary project:

Function	Description
print_string	Prints a null-terminated string to stdout.
print_int	Prints an integer to stdout.
read_word	Reads a word (up to 255 characters) from stdin and stores it in memory.
parse_int	Converts a string of digits into an integer.
parse_uint	Converts a string of digits into an unsigned integer.

Common Errors and Solutions

• Ensure that strings have an extra byte for the null-terminator (n + 1 bytes).
• Use caller-saved and callee-saved registers correctly.
• Always maintain stack alignment before calling any function (rsp aligned to 16 bytes).
• Don’t store temporary buffers in the .data section; use the stack (rsp).

---

2. Macro Definition: colon

The colon macro simplifies the creation of dictionary entries by automatically linking new entries to the front of the list.

Example:

section .data

colon "first word", first_word
db "first word explanation", 0

colon "second word", second_word
db "second word explanation", 0 

colon "third word", third_word
db "third word explanation", 0

3. Dictionary Search: find_word

Implemented in dict.asm, the find_word function searches through the dictionary using a provided key.

find_word:
    ; Receives: pointer to key and pointer to dictionary
    ; Returns: address of the matching dictionary entry or 0 if not found

---

🚀 How to Use

Once built, the program allows you to search for words in the dictionary via a simple console interface.

1. Enter a word you want to search:

   Enter a word: first word

2. If found, the program will display the associated explanation:

   first word explanation

3. If the word is not found, an error message will be displayed:

   Error: Word not found.

---

🔧 Building and Running the Project

1. Building

Use the provided Makefile to build the project. Make sure NASM is installed on your machine:

make

2. Running

./main

3. Running Tests

The project includes automated tests that validate dictionary creation, searching, and input handling.

make test

---

🌟 Extending the Project

• Expand the I/O library: Add functions to handle file-based I/O, formatted printing, or additional numeric parsing.
• Enhance data structures: Experiment with more complex structures, such as hash maps or AVL trees.
• Improve the search algorithm: Optimize the find_word function for faster lookups.

---

📜 Makefile Overview

• make: Build the project.
• make test: Run tests to validate functionality.
• make clean: Clean up build artifacts.

---

📚 Further Reading

• NASM Documentation
• Low-Level Programming Concepts
• Linux ABI Reference

---

🏅 Why This Project?

This project is an excellent exercise in:

• Low-level memory management.
• System-level programming using Assembly.
• Building maintainable, modular software at the lowest levels.

It’s ideal for developers who want to dive deeper into how computers work and gain hands-on experience with Assembly.

---

🤝 Contributing

Contributions are welcome! Feel free to:

• Fork the repository.
• Open issues or submit pull requests.

Let’s collaborate to make this project even more exciting! 😊