dmenu

godmenu

A Go library for interacting with the dmenu utility, providing a clean API to display selection menus and retrieve user choices.

Overview

godmenu is a Go wrapper for the dmenu utility that allows you to:

• Display selection menus with custom text
• Use complex Go types as values (not just strings)
• Handle dmenu's selection results in a type-safe way

dmenu is a lightweight dynamic menu for X, originally designed for the dwm window manager. This library makes it easy to integrate dmenu functionality into your Go applications.

Requirements

• The dmenu utility must be installed on your system
• Go 1.18+ (for generics support)

Installation

# Install dmenu if you don't have it already
# Debian/Ubuntu:
sudo apt-get install dmenu

# Arch Linux:
sudo pacman -S dmenu

# Then install the library:
go get codeberg.org/berzdev/godmenu

Usage

Basic String Values (Legacy Mode)

package main

import (
    "fmt"
    "log"
    "codeberg.org/berzdev/godmenu"
)

func main() {
    // Create key-value pairs with string values
    contacts := []dmenu.KeyValuePair{
        {Key: "John Doe", Value: "john@example.com"},
        {Key: "Jane Smith", Value: "jane@example.com"},
    }
    
    // Display dmenu and get the selected item
    selected, err := dmenu.Select(contacts, "Select Contact")
    if err != nil {
        log.Fatalf("Error: %v", err)
    }
    
    fmt.Printf("Selected: %s (%s)\n", selected.Key, selected.Value)
}

Using Custom Structs as Values

package main

import (
    "fmt"
    "log"
    "codeberg.org/berzdev/godmenu"
)

// Define a custom struct
type Contact struct {
    Name  string
    Email string
    Phone string
}

func main() {
    // Create items with complex struct values
    contacts := []dmenu.Item[Contact]{
        {
            DisplayText: "John Doe",
            Value: Contact{
                Name:  "John Doe",
                Email: "john@example.com",
                Phone: "+1-555-123-4567",
            },
        },
        {
            DisplayText: "Jane Smith",
            Value: Contact{
                Name:  "Jane Smith",
                Email: "jane@example.com",
                Phone: "+1-555-234-5678",
            },
        },
    }
    
    // Display dmenu and get the selected item with its Contact struct
    selected, err := dmenu.SelectItem(contacts, "Select Contact")
    if err != nil {
        log.Fatalf("Error: %v", err)
    }
    
    // Access all the struct fields
    contact := selected.Value
    fmt.Printf("Selected: %s\n", contact.Name)
    fmt.Printf("  Email: %s\n", contact.Email)
    fmt.Printf("  Phone: %s\n", contact.Phone)
}

How It Works

godmenu creates an abstraction layer where:

1. Only the display text is sent to dmenu
2. When the user makes a selection, godmenu maps the selected display text back to the associated struct/value
3. Your application receives the full struct with all its fields, not just the displayed text

This approach gives you the simplicity of dmenu's interface while maintaining access to rich data structures in your Go code.

Features

• Type-safe with Go generics
• Backwards compatible with the legacy string-only API
• Simple and clean interface
• Support for custom prompt text
• Error handling for dmenu execution

License

MIT License