aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorChristopher R. Nelson <christopher.nelson@languidnights.com>2026-10-31 23:51:41 -0400
committerChristopher R. Nelson <christopher.nelson@languidnights.com>2026-10-31 23:51:41 -0400
commit0bca7a7eb09f0e094aa721f75d23f771d20c6bf3 (patch)
tree380f0f0d02a504e00bcbdb9c13ca3ba25ca370dc
Initial wallpaper-switcher pipe menu
Common Lisp tool that prints an Openbox pipe menu of the .png/.webp files in ~/.wallpapers, with each item setting the wallpaper via swaybg. Directory, command template and extensions are configurable through ~/.config/wallpaper-switcher/config or command-line options. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
-rw-r--r--.gitignore2
-rw-r--r--Makefile23
-rw-r--r--README.md45
-rw-r--r--src/config.lisp85
-rw-r--r--src/main.lisp67
-rw-r--r--src/menu.lisp94
-rw-r--r--src/package.lisp21
-rw-r--r--t/tests.lisp140
-rw-r--r--wallpaper-switcher.asd24
9 files changed, 501 insertions, 0 deletions
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..6cf53a1
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,2 @@
+/wallpaper-switcher
+*.fasl
diff --git a/Makefile b/Makefile
new file mode 100644
index 0000000..5d95742
--- /dev/null
+++ b/Makefile
@@ -0,0 +1,23 @@
+LISP ?= sbcl
+PREFIX ?= $(HOME)/.local
+SBCL = $(LISP) --non-interactive --no-userinit \
+ --eval '(require "asdf")' \
+ --eval '(asdf:initialize-source-registry (quote (:source-registry (:directory "$(CURDIR)/") :inherit-configuration)))'
+
+.PHONY: all build test install clean
+
+all: build
+
+build: wallpaper-switcher
+
+wallpaper-switcher: wallpaper-switcher.asd $(wildcard src/*.lisp)
+ $(SBCL) --eval '(asdf:make "wallpaper-switcher")'
+
+test:
+ $(SBCL) --eval '(asdf:test-system "wallpaper-switcher")'
+
+install: wallpaper-switcher
+ install -Dm755 wallpaper-switcher $(PREFIX)/bin/wallpaper-switcher
+
+clean:
+ rm -f wallpaper-switcher
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..f43ecd8
--- /dev/null
+++ b/README.md
@@ -0,0 +1,45 @@
+# wallpaper-switcher
+
+An Openbox (or labwc) pipe menu that lists the `.png` and `.webp` files in
+`~/.wallpapers` and sets the one you pick with `swaybg`.
+
+## Build
+
+Needs SBCL. The only dependency is UIOP, which ships with ASDF, so Quicklisp
+is not required.
+
+ make # builds ./wallpaper-switcher
+ make test
+ make install # copies it to ~/.local/bin (override with PREFIX=...)
+
+## Menu setup
+
+In `menu.xml`:
+
+```xml
+<menu id="wallpapers" label="Wallpapers" execute="wallpaper-switcher" />
+```
+
+Then reference `wallpapers` from your root menu and reconfigure Openbox.
+
+## Configuration
+
+Optional. Put it in `$XDG_CONFIG_HOME/wallpaper-switcher/config` (usually
+`~/.config/wallpaper-switcher/config`):
+
+```
+# Where to look (~ and $HOME are expanded). Subdirectories are not searched.
+directory = ~/.wallpapers
+
+# Shell command run when an item is picked. %f is the file (already quoted
+# for the shell), %% is a literal %.
+command = pkill -x swaybg; swaybg -m fill -i %f &
+
+# File extensions to include, matched without regard to case.
+extensions = png webp
+```
+
+Command-line options override the file:
+
+ wallpaper-switcher --directory ~/Pictures/walls --command 'swaybg -m fit -i %f &'
+ wallpaper-switcher --config /path/to/other/config
diff --git a/src/config.lisp b/src/config.lisp
new file mode 100644
index 0000000..ff3baf7
--- /dev/null
+++ b/src/config.lisp
@@ -0,0 +1,85 @@
+(in-package #:wallpaper-switcher)
+
+;;; Configuration
+;;;
+;;; The config file is plain "key = value" lines; blank lines and lines
+;;; starting with # are ignored. Recognised keys:
+;;;
+;;; directory = ~/.wallpapers
+;;; command = pkill -x swaybg; swaybg -m fill -i %f &
+;;; extensions = png webp
+;;;
+;;; COMMAND is a shell command. %f becomes the shell-quoted path of the
+;;; wallpaper and %% becomes a literal %. The command runs under `sh -c`,
+;;; so you can use ;, &&, & and so on.
+
+(defparameter *default-directory* "~/.wallpapers")
+
+(defparameter *default-command* "pkill -x swaybg; swaybg -m fill -i %f &"
+ "Kill any running swaybg, then start a new one in the background.
+swaybg runs until it is killed, so without the pkill each pick would stack
+another swaybg process on top of the last one.")
+
+(defparameter *default-extensions* '("png" "webp"))
+
+(defstruct config
+ (directory *default-directory* :type string)
+ (command *default-command* :type string)
+ (extensions *default-extensions* :type list))
+
+(defun default-config ()
+ (make-config))
+
+(defun default-config-path ()
+ "$XDG_CONFIG_HOME/wallpaper-switcher/config, or ~/.config/... if unset."
+ (uiop:xdg-config-home "wallpaper-switcher/config"))
+
+(defun expand-path (string)
+ "Expand a leading ~ and $HOME / ${HOME} in STRING."
+ (let* ((home (string-right-trim "/" (namestring (user-homedir-pathname))))
+ (s (cond ((string= string "~") home)
+ ((uiop:string-prefix-p "~/" string)
+ (concatenate 'string home (subseq string 1)))
+ (t string))))
+ (dolist (var '("${HOME}" "$HOME") s)
+ (loop for pos = (search var s)
+ while pos
+ do (setf s (concatenate 'string (subseq s 0 pos) home
+ (subseq s (+ pos (length var)))))))))
+
+(defun split-words (string)
+ "Split STRING on whitespace and commas, dropping empty pieces."
+ (remove "" (uiop:split-string string :separator '(#\Space #\Tab #\,))
+ :test #'string=))
+
+(defun parse-config-string (string &optional (config (default-config)))
+ "Apply the settings in STRING on top of CONFIG and return CONFIG.
+Unknown keys and malformed lines produce a warning and are skipped."
+ (loop for raw in (uiop:split-string string :separator '(#\Newline))
+ for lineno from 1
+ for line = (string-trim '(#\Space #\Tab #\Return) raw)
+ unless (or (string= line "") (char= (char line 0) #\#))
+ do (let ((eq (position #\= line)))
+ (if (null eq)
+ (warn "config line ~D: expected key = value, got ~S" lineno line)
+ (let ((key (string-downcase
+ (string-trim '(#\Space #\Tab) (subseq line 0 eq))))
+ (value (string-trim '(#\Space #\Tab) (subseq line (1+ eq)))))
+ (cond ((string= key "directory")
+ (setf (config-directory config) value))
+ ((string= key "command")
+ (setf (config-command config) value))
+ ((string= key "extensions")
+ (setf (config-extensions config)
+ (mapcar (lambda (e)
+ (string-downcase (string-left-trim "." e)))
+ (split-words value))))
+ (t (warn "config line ~D: unknown key ~S" lineno key)))))))
+ config)
+
+(defun load-config (&optional (path (default-config-path)))
+ "Read PATH if it exists; otherwise return the defaults."
+ (let ((config (default-config)))
+ (if (and path (probe-file path))
+ (parse-config-string (uiop:read-file-string path) config)
+ config)))
diff --git a/src/main.lisp b/src/main.lisp
new file mode 100644
index 0000000..27a7dbb
--- /dev/null
+++ b/src/main.lisp
@@ -0,0 +1,67 @@
+(in-package #:wallpaper-switcher)
+
+(defparameter *usage*
+ "Usage: wallpaper-switcher [options]
+
+Print an Openbox pipe menu listing the wallpapers in a directory.
+
+Options:
+ -c, --config FILE Read settings from FILE
+ (default: $XDG_CONFIG_HOME/wallpaper-switcher/config)
+ -d, --directory DIR Wallpaper directory (default: ~/.wallpapers)
+ -e, --command CMD Shell command to set a wallpaper; %f is the file
+ -h, --help Show this help
+")
+
+(defun parse-args (args)
+ "Return a plist of the options in ARGS. Signals an error on bad input."
+ (let ((opts '()))
+ (loop while args
+ do (let ((arg (pop args)))
+ (flet ((value ()
+ (or (pop args)
+ (error "option ~A needs a value" arg))))
+ (cond ((member arg '("-h" "--help") :test #'string=)
+ (setf (getf opts :help) t))
+ ((member arg '("-c" "--config") :test #'string=)
+ (setf (getf opts :config) (value)))
+ ((member arg '("-d" "--directory") :test #'string=)
+ (setf (getf opts :directory) (value)))
+ ((member arg '("-e" "--command") :test #'string=)
+ (setf (getf opts :command) (value)))
+ (t (error "unknown argument ~S" arg))))))
+ opts))
+
+(defun resolve-config (opts)
+ "Defaults, then the config file, then command-line options."
+ (let* ((explicit (getf opts :config))
+ (path (if explicit (expand-path explicit) (default-config-path))))
+ (when (and explicit (not (probe-file path)))
+ (error "config file ~A does not exist" path))
+ (let ((config (load-config path)))
+ (when (getf opts :directory)
+ (setf (config-directory config) (getf opts :directory)))
+ (when (getf opts :command)
+ (setf (config-command config) (getf opts :command)))
+ config)))
+
+(defun run (args)
+ "Do the work for ARGS and return an exit code. Safe to call from a REPL."
+ (handler-case
+ (let ((opts (parse-args args)))
+ (if (getf opts :help)
+ (write-string *usage*)
+ ;; Warnings go to stderr; stdout must contain only the menu XML.
+ (handler-bind ((warning (lambda (w)
+ (format *error-output* "wallpaper-switcher: ~A~%" w)
+ (muffle-warning w))))
+ (render-menu (resolve-config opts))))
+ (finish-output)
+ 0)
+ (error (e)
+ (format *error-output* "wallpaper-switcher: ~A~%" e)
+ 1)))
+
+(defun main ()
+ "Entry point for the built executable."
+ (uiop:quit (run (uiop:command-line-arguments))))
diff --git a/src/menu.lisp b/src/menu.lisp
new file mode 100644
index 0000000..4bae123
--- /dev/null
+++ b/src/menu.lisp
@@ -0,0 +1,94 @@
+(in-package #:wallpaper-switcher)
+
+;;; Finding wallpapers
+
+(defun wallpaper-p (pathname extensions)
+ (let ((type (pathname-type pathname)))
+ (and type (member type extensions :test #'string-equal))))
+
+(defun find-wallpapers (directory extensions)
+ "Image files directly inside DIRECTORY (not subdirectories), sorted by
+name. Returns NIL if DIRECTORY does not exist."
+ (let ((dir (uiop:ensure-directory-pathname (expand-path directory))))
+ (when (uiop:directory-exists-p dir)
+ (sort (remove-if-not (lambda (p) (wallpaper-p p extensions))
+ (uiop:directory-files dir))
+ #'string-lessp
+ :key #'file-namestring))))
+
+;;; Escaping
+
+(defun shell-quote (string)
+ "Quote STRING as one POSIX shell word: wrap it in single quotes and write
+each embedded ' as '\\''."
+ (with-output-to-string (out)
+ (write-char #\' out)
+ (loop for c across string
+ do (if (char= c #\')
+ (write-string "'\\''" out)
+ (write-char c out)))
+ (write-char #\' out)))
+
+(defun xml-escape (string)
+ (with-output-to-string (out)
+ (loop for c across string
+ do (case c
+ (#\& (write-string "&amp;" out))
+ (#\< (write-string "&lt;" out))
+ (#\> (write-string "&gt;" out))
+ (#\" (write-string "&quot;" out))
+ (#\' (write-string "&apos;" out))
+ (t (write-char c out))))))
+
+(defun menu-label (pathname)
+ "Filename without its extension. Openbox reads _ in a label as a keyboard
+shortcut marker, so each _ is doubled to show it as-is."
+ (let ((name (or (pathname-name pathname) (file-namestring pathname))))
+ (with-output-to-string (out)
+ (loop for c across name
+ do (write-char c out)
+ (when (char= c #\_) (write-char c out))))))
+
+;;; Building the Execute command
+
+(defun expand-template (template file)
+ "Replace %f in TEMPLATE with FILE shell-quoted, and %% with %."
+ (with-output-to-string (out)
+ (loop with i = 0
+ with n = (length template)
+ while (< i n)
+ do (let ((c (char template i)))
+ (if (and (char= c #\%) (< (1+ i) n))
+ (let ((next (char template (1+ i))))
+ (case next
+ (#\f (write-string (shell-quote file) out) (incf i 2))
+ (#\% (write-char #\% out) (incf i 2))
+ (t (write-char c out) (incf i))))
+ (progn (write-char c out) (incf i)))))))
+
+(defun build-command (template pathname)
+ "The command line for one menu item. Openbox splits Execute commands
+like a shell does but does not run them through one, so the expanded
+template is passed to `sh -c` as a single quoted argument."
+ (format nil "sh -c ~A"
+ (shell-quote (expand-template template (uiop:native-namestring pathname)))))
+
+;;; Rendering
+
+(defun render-item (stream pathname command)
+ (format stream " <item label=\"~A\">~% <action name=\"Execute\"><command>~A</command></action>~% </item>~%"
+ (xml-escape (menu-label pathname))
+ (xml-escape (build-command command pathname))))
+
+(defun render-menu (config &optional (stream *standard-output*))
+ "Write the Openbox pipe menu XML for CONFIG to STREAM."
+ (let ((files (find-wallpapers (config-directory config)
+ (config-extensions config))))
+ (format stream "<?xml version=\"1.0\" encoding=\"UTF-8\"?>~%<openbox_pipe_menu>~%")
+ (if files
+ (dolist (f files)
+ (render-item stream f (config-command config)))
+ (format stream " <separator label=\"~A\"/>~%"
+ (xml-escape (format nil "No wallpapers in ~A"
+ (expand-path (config-directory config))))))
+ (format stream "</openbox_pipe_menu>~%")))
diff --git a/src/package.lisp b/src/package.lisp
new file mode 100644
index 0000000..3d36565
--- /dev/null
+++ b/src/package.lisp
@@ -0,0 +1,21 @@
+(defpackage #:wallpaper-switcher
+ (:use #:cl)
+ (:export #:main
+ ;; config
+ #:config
+ #:make-config
+ #:config-directory
+ #:config-command
+ #:config-extensions
+ #:default-config
+ #:default-config-path
+ #:parse-config-string
+ #:load-config
+ #:expand-path
+ ;; menu
+ #:find-wallpapers
+ #:shell-quote
+ #:xml-escape
+ #:menu-label
+ #:build-command
+ #:render-menu))
diff --git a/t/tests.lisp b/t/tests.lisp
new file mode 100644
index 0000000..6baf5ed
--- /dev/null
+++ b/t/tests.lisp
@@ -0,0 +1,140 @@
+;;; A small self-contained test runner, so the project needs nothing
+;;; beyond ASDF/UIOP.
+
+(defpackage #:wallpaper-switcher/tests
+ (:use #:cl #:wallpaper-switcher)
+ (:export #:run-tests))
+
+(in-package #:wallpaper-switcher/tests)
+
+(defvar *tests* '())
+(defvar *failures* 0)
+
+(defmacro deftest (name &body body)
+ `(progn
+ (defun ,name () ,@body)
+ (pushnew ',name *tests*)
+ ',name))
+
+(defmacro check (form)
+ `(unless ,form
+ (incf *failures*)
+ (format t "~& FAIL: ~S~%" ',form)))
+
+(defmacro check-equal (expected form)
+ (let ((e (gensym)) (v (gensym)))
+ `(let ((,e ,expected) (,v ,form))
+ (unless (equal ,e ,v)
+ (incf *failures*)
+ (format t "~& FAIL: ~S~% expected ~S~% got ~S~%" ',form ,e ,v)))))
+
+(defun run-tests ()
+ (let ((*failures* 0))
+ (dolist (test (reverse *tests*))
+ (format t "~&~A~%" test)
+ (handler-case (funcall test)
+ (error (e)
+ (incf *failures*)
+ (format t " ERROR: ~A~%" e))))
+ (format t "~&~D test~:P, ~D failure~:P~%" (length *tests*) *failures*)
+ (zerop *failures*)))
+
+(defun call-with-temp-dir (fn)
+ (let ((dir (uiop:ensure-directory-pathname
+ (format nil "~Awallpaper-switcher-test-~36R/"
+ (namestring (uiop:temporary-directory))
+ (random (expt 36 8))))))
+ (ensure-directories-exist dir)
+ (unwind-protect (funcall fn dir)
+ (uiop:delete-directory-tree dir :validate t))))
+
+(defmacro with-temp-dir ((var) &body body)
+ `(call-with-temp-dir (lambda (,var) ,@body)))
+
+(defun touch (dir name)
+ (with-open-file (s (merge-pathnames name dir) :direction :output
+ :if-does-not-exist :create)
+ (declare (ignorable s))))
+
+;;; Tests
+
+(deftest test-shell-quote
+ (check-equal "'plain'" (shell-quote "plain"))
+ (check-equal "'with space'" (shell-quote "with space"))
+ (check-equal "'it'\\''s'" (shell-quote "it's"))
+ (check-equal "''" (shell-quote "")))
+
+(deftest test-xml-escape
+ (check-equal "a &amp; b &lt;c&gt; &quot;d&quot; &apos;e&apos;"
+ (xml-escape "a & b <c> \"d\" 'e'")))
+
+(deftest test-menu-label
+ (check-equal "sunset" (menu-label #p"/x/sunset.png"))
+ (check-equal "my__wall" (menu-label #p"/x/my_wall.webp")))
+
+(deftest test-expand-path
+ (let ((home (string-right-trim "/" (namestring (user-homedir-pathname)))))
+ (check-equal (concatenate 'string home "/.wallpapers") (expand-path "~/.wallpapers"))
+ (check-equal (concatenate 'string home "/pics") (expand-path "$HOME/pics"))
+ (check-equal (concatenate 'string home "/pics") (expand-path "${HOME}/pics"))
+ (check-equal "/abs/path" (expand-path "/abs/path"))))
+
+(deftest test-parse-config
+ (let ((c (parse-config-string
+ "# comment
+
+directory = /srv/walls
+command = feh --bg-fill %f
+extensions = .PNG, jpg webp")))
+ (check-equal "/srv/walls" (config-directory c))
+ (check-equal "feh --bg-fill %f" (config-command c))
+ (check-equal '("png" "jpg" "webp") (config-extensions c))))
+
+(deftest test-parse-config-warns-on-unknown-key
+ (let ((warned nil))
+ (handler-bind ((warning (lambda (w) (setf warned t) (muffle-warning w))))
+ (parse-config-string "colour = blue"))
+ (check warned)))
+
+(deftest test-config-defaults
+ (let ((c (default-config)))
+ (check-equal "~/.wallpapers" (config-directory c))
+ (check-equal '("png" "webp") (config-extensions c))
+ (check (search "swaybg" (config-command c)))))
+
+(deftest test-build-command
+ (check-equal "sh -c 'swaybg -i '\\''/w/a b.png'\\'' 100%'"
+ (build-command "swaybg -i %f 100%%" #p"/w/a b.png")))
+
+(deftest test-find-wallpapers
+ (with-temp-dir (dir)
+ (dolist (n '("b.webp" "A.png" "c.PNG" "notes.txt" "noext"))
+ (touch dir n))
+ (ensure-directories-exist (merge-pathnames "sub/" dir))
+ (touch (merge-pathnames "sub/" dir) "nested.png")
+ (check-equal '("A.png" "b.webp" "c.PNG")
+ (mapcar #'file-namestring
+ (find-wallpapers (namestring dir) '("png" "webp"))))))
+
+(deftest test-find-wallpapers-missing-dir
+ (check-equal nil (find-wallpapers "/nonexistent/wallpaper-switcher/" '("png"))))
+
+(deftest test-render-menu
+ (with-temp-dir (dir)
+ (touch dir "tom & jerry.png")
+ (let ((xml (with-output-to-string (s)
+ (render-menu (make-config :directory (namestring dir)
+ :command "swaybg -i %f")
+ s))))
+ (check (search "<openbox_pipe_menu>" xml))
+ (check (search "label=\"tom &amp; jerry\"" xml))
+ (check (search "<action name=\"Execute\"><command>sh -c &apos;swaybg -i &apos;\\&apos;&apos;"
+ xml))
+ (check (search "</openbox_pipe_menu>" xml)))))
+
+(deftest test-render-menu-empty
+ (with-temp-dir (dir)
+ (let ((xml (with-output-to-string (s)
+ (render-menu (make-config :directory (namestring dir)) s))))
+ (check (search "<separator label=\"No wallpapers in" xml))
+ (check (not (search "<item" xml))))))
diff --git a/wallpaper-switcher.asd b/wallpaper-switcher.asd
new file mode 100644
index 0000000..6df70b7
--- /dev/null
+++ b/wallpaper-switcher.asd
@@ -0,0 +1,24 @@
+(defsystem "wallpaper-switcher"
+ :description "Openbox pipe menu that lists wallpapers and sets them with swaybg."
+ :author "Christopher R. Nelson <christopher.nelson@languidnights.com>"
+ :license "MIT"
+ :version "0.1.0"
+ :depends-on ("uiop")
+ :pathname "src/"
+ :serial t
+ :components ((:file "package")
+ (:file "config")
+ (:file "menu")
+ (:file "main"))
+ :build-operation "program-op"
+ :build-pathname "../wallpaper-switcher"
+ :entry-point "wallpaper-switcher:main"
+ :in-order-to ((test-op (test-op "wallpaper-switcher/tests"))))
+
+(defsystem "wallpaper-switcher/tests"
+ :depends-on ("wallpaper-switcher")
+ :pathname "t/"
+ :components ((:file "tests"))
+ :perform (test-op (o c)
+ (unless (uiop:symbol-call :wallpaper-switcher/tests :run-tests)
+ (error "wallpaper-switcher tests failed"))))