README
¶
xd
xd is tiny command line program written in Go that generates dmenu based on provided easily configurable yaml files.
Install
sudo make install
Uninstall
sudo make uninstall
Usage
xd -config=/path/to/config.yaml -command=system -- -l 10 more dmenu args...
Configuration
The xd utility uses configuration files to define the commands it can run.
If the -config flag is not provided when running xd,
it will look for configuration files in the directory specified by $XDG_CONFIG_HOME/xd/.
If this directory does not contain any configuration files, xd will automatically create a default one.
Importantly, xd supports multiple configuration files.
When loading its configuration,
xd will read all the .yaml files located in the $XDG_CONFIG_HOME/xd/ directory
and merge the commands defined in them.
This allows you to split your commands across multiple files for better organization, if desired.
Here's an example of a configuration file with detailed explanation:
# A top-level command
- name: Mpv # The name of the command that will be displayed on the dmenu
prompt: "Paste URL... [Ctrl+Shift+Y] " # The prompt that will be displayed when this command is selected
cmd: mpv $selected # The actual command to run. '$selected' will be replaced by the user's input
# Another top-level command
- name: WiFi
list: "nmcli device wifi list | sed '1d'" # The 'list' command generates dynamic options for the dmenu
cmd: "device=$(echo $selected | tr -s ' ' | cut -d ' ' -f1); nmcli device wifi connect $device"
# The actual command to run. '$selected' will be replaced by the user's selection from the options generated by 'list'
# A top-level command containing sub-commands
- name: System
commands: # A list of sub-commands nested under 'System'
- name: Reboot # The name of the sub-command that will be displayed on the dmenu
cmd: reboot # The actual command to run when this sub-command is selected
- name: Shutdown
cmd: shutdown now
- name: Suspend
cmd: systemctl suspend
For additional examples of configuration files, please refer to the examples directory in this repository.
Pass Args to Dmenu
You can pass additional arguments to dmenu after specifying the -config or -command flags.
It is crucial to add -- after your flags to indicate the end of command options
and ensure subsequent arguments are passed to dmenu correctly.
For example, to pass the -l argument (which controls the number of lines dmenu displays) to dmenu, you would write:
xd -config=/path/to/config.yaml -- -l 15
License
xd is released under the MIT License.
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Execute ¶
Execute function runs a bash command with the given command string and returns its output as a string. If there's an error running the command, it displays an error message and an exit option using Show.
func Navigate ¶
Navigate function allows the user to navigate through a slice of commands using dmenu. For each command, it checks whether it has a List, nested Commands, or a Cmd. If a command has a List, it calls NavigateList to let the user select an item from the list. If it has nested Commands, it calls Navigate recursively with the nested commands. If it has a Cmd, it executes the command using Execute. The function always includes an "Exit" option in the dmenu for the user to exit the program.
func NavigateList ¶
NavigateList function is used to handle commands that have a List command. It first executes the List command to get a list of items, and shows them to the user using dmenu. The user can then select an item from the list. If the command has nested Commands, it replaces the placeholder "$selected" in the commands with the selected item, and calls Navigate with the nested commands. If the command has a Cmd, it replaces the placeholder "$selected" in the command with the selected item, and executes the command using Execute.
func NavigatePrompt ¶
Types ¶
type Command ¶
type Command struct {
// Name represents the option that the user will see in the dmenu.
Name string `yaml:"name"`
// Cmd defines the actual command that will be executed when the user selects this option.
Cmd string `yaml:"cmd"`
// List represents a command that will be executed to generate dynamic options.
// These dynamic options will be shown to the user and the selected option will replace "$selected"
// in the Cmd or in the Cmd of nested Commands. This is useful for listing available resources (like Bluetooth connections)
// and taking actions based on the user's selection.
List string `yaml:"list"`
// Prompt is used to ask the user for input without showing a list of options.
// The user's input replaces "$selected" in Cmd or in the Cmd of nested Commands.
Prompt string `yaml:"prompt"`
// Commands hold any sub-commands nested under this command.
// These commands will be presented as additional options to the user when the parent command is selected.
Commands []Command `yaml:"commands"`
}
Command is a struct that defines the structure of command configurations.
func LoadConfig ¶
LoadConfig reads configuration files from a provided path or from the default location. It attempts to load configuration file in the following order: 1. From the path provided through the command line flag -config. 2. From the directory specified in XDG_CONFIG_HOME environment variable. If the directory does not exist or is empty, it creates a default configuration file. The function also takes an optional `command` parameter which allows selecting a specific sub-command directly from the configuration.
func ReadConfig ¶
ReadConfig reads a configuration file and unmarshal it into a slice of Command structs. It takes a `command` parameter which, if provided, will filter and return only the sub-commands of the matching command. If `command` is an empty string, it will return all commands from the configuration file.
Source Files
Directories