Beyond Theory: Building Practical Tools with Guile Scheme

Introduction

A few months ago, I shared my journey into learning Scheme through building stash, a symlink manager. Since then, I've discovered that the gap between learning Scheme and applying it to real-world problems is where the most valuable lessons emerge. This post explores what I've learned about building practical tools with Guile Scheme, sharing both successes and challenges along the way.

The Power of Modular Design

One of the most important lessons I learned was the value of modular design. Breaking down a program into focused, single-responsibility modules not only makes the code more maintainable but also helps in reasoning about the program's behavior. Here's how I structured stash:

(use-modules (ice-9 getopt-long)
             (stash help)         ;; Help module
             (stash colors)       ;; ANSI colors
             (stash log)          ;; Logging module
             (stash paths)        ;; Path handling module
             (stash conflict)     ;; Conflict resolution module
             (stash file-ops))    ;; File and symlink operations module

Each module has a specific responsibility:

colors.scm: Handles ANSI color formatting for terminal output
conflict.scm: Manages conflict resolution when files already exist
file-ops.scm: Handles file system operations
help.scm: Provides usage information
log.scm: Manages logging operations
paths.scm: Handles path manipulation and normalization

Robust Path Handling

One of the first challenges in building a file management tool is handling paths correctly. Here's how I approached it:

(define (expand-home path)
  "Expand ~ to the user's home directory."
  (if (string-prefix? "~" path)
      (string-append (getenv "HOME") (substring path 1))
      path))

(define (concat-path base path)
  "Concatenate two paths, ensuring there are no double slashes."
  (if (string-suffix? "/" base)
      (string-append (string-drop-right base 1) "/" path)
      (string-append base "/" path)))

(define (ensure-config-path target-dir)
  "Ensure that the target directory has .config appended, avoiding double slashes."
  (let ((target-dir (expand-home target-dir)))
    (if (string-suffix? "/" target-dir)
        (set! target-dir (string-drop-right target-dir 1)))
    (if (not (string-suffix? "/.config" target-dir))
        (string-append target-dir "/.config")
        target-dir)))

This approach ensures that:

Home directory references (~) are properly expanded
Path concatenation doesn't create double slashes
Configuration paths are consistently structured

Interactive Conflict Resolution

Real-world tools often need to handle conflicts. I implemented an interactive conflict resolution system:

(define (prompt-user-for-action)
  "Prompt the user to decide how to handle a conflict: overwrite (o), skip (s), or cancel (c)."
  (display (color-message 
    "A conflict was detected. Choose action - Overwrite (o), Skip (s), or Cancel (c): " 
    yellow-text))
  (let ((response (read-line)))
    (cond
      ((string-ci=? response "o") 'overwrite)
      ((string-ci=? response "s") 'skip)
      ((string-ci=? response "c") 'cancel)
      (else
       (display "Invalid input. Please try again.\n")
       (prompt-user-for-action)))))

This provides a user-friendly interface for resolving conflicts while maintaining data safety.

Logging for Debugging and Auditing

Proper logging is crucial for debugging and auditing. I implemented a simple but effective logging system:

(define (current-timestamp)
  "Return the current date and time as a formatted string."
  (let* ((time (current-time))
         (seconds (time-second time)))
    (strftime "%Y-%m-%d-%H-%M-%S" (localtime seconds))))

(define (log-action message)
  "Log an action with a timestamp to the stash.log file."
  (let ((log-port (open-file "stash.log" "a")))
    (display (color-message 
      (string-append "[" (current-timestamp) "] " message) 
      green-text) log-port)
    (newline log-port)
    (close-port log-port)))

This logging system:

Timestamps each action
Uses color coding for better readability
Maintains a persistent log file
Properly handles file operations

File Operations with Safety

When dealing with file system operations, safety is paramount. Here's how I handle moving directories:

(define (move-source-to-target source-dir target-dir)
  "Move the entire source directory to the target directory, ensuring .config in the target path."
  (let* ((target-dir (ensure-config-path target-dir))
         (source-dir (expand-home source-dir))
         (source-name (basename source-dir))
         (target-source-dir (concat-path target-dir source-name)))
    (if (not (file-exists? target-dir))
        (mkdir target-dir #o755))
    (if (file-exists? target-source-dir)
        (handle-conflict target-source-dir source-dir delete-directory log-action)
        (begin
          (rename-file source-dir target-source-dir)
          (display (format #f "Moved ~a to ~a\n" source-dir target-source-dir))
          (log-action (format #f "Moved ~a to ~a" source-dir target-source-dir))))
    target-source-dir))

This implementation:

Ensures paths are properly formatted
Creates necessary directories
Handles conflicts gracefully
Logs all operations
Returns the new path for further operations

Lessons Learned

What Worked Well

Modular Design: Breaking the code into focused modules made it easier to maintain and test
Functional Approach: Using pure functions where possible made the code more predictable
Interactive Interface: Providing clear user prompts and colored output improved usability
Robust Logging: Detailed logging helped with debugging and understanding program flow

Challenges Faced

Path Handling: Dealing with different path formats and edge cases required careful attention
Error States: Managing various error conditions while keeping the code clean
User Interface: Balancing between automation and user control
Documentation: Writing clear documentation that helps users understand the tool

Moving Forward

Building stash has taught me that while functional programming principles are valuable, pragmatism is equally important. The key is finding the right balance between elegant functional code and practical solutions.

Resources

The code examples in this post are from my actual implementation of stash. Feel free to explore, use, and improve upon them!