ratmen(1)

📦 version 2.2.3, in nixos 26.05, nixpkgs unstable

🐭✨ ratmen(1) ✨ — create a menu to run commands

okay bestie, buckle up 💅 this is ratmen, a whole icon, and she's about to make your X11 life so much easier.

🌸 NAME 🌸

ratmen — create a menu to run commands. that's it, that's the job, and she ate 💖

🦋 SYNOPSIS 🦋

ratmen [OPTION]... MENUITEM COMMAND...

ratmen [OPTION]... {-d##|--delimiter ##} MENUITEM##COMMAND ...

🎀 DESCRIPTION 🎀

okay so here's the tea 🍓: Ratmen is a simple program that accepts a list of MENUITEM and COMMAND pairs on the command line. she creates a window that consists of nothing but a menu. literally nothing else, no decoration, no chrome, just vibes ✨. when a particular MENUITEM is selected by the user, the corresponding COMMAND is executed — or, if you're using --print, printed on standard output instead.

menu items and commands can be given separately (like in ratmenu) using two arguments for each menu option, or, optionally, you may specify a delimiter (with the --delimiter option) and specify both the menu item and the command in the same argument (similar to 9menu). the delimiter may be of any length, no cap 🫶.

if the command is omitted (or if an empty command is supplied when you're not using --delimiter) then the menu item text will be used as the command. iconic, lowkey.

✨ OPTIONS ✨

some options may be specified using X resources (so you can define some defaults you like in your ~/.Xresources, ~/.Xdefaults or similar — very main character of you 💜). to make this mechanism as useful as possible, the recommendation is that you refrain from using such options on the command line, unless you really need to, and instead enable/disable the corresponding X resource setting. trust the process 🙏.

ratmen's default resource class is the name of the executed file — either ratmen, or, if the executable was called through a link, the name of the link in question. the command line option --class may be used to override the default X resource class name 👑

  • --align {left|center|right} (X resource: align) — aligns the text of the menu entries to the left, center or right. defaults to left. (the short options -l, -c and -r may also be used for left, center and right respectivelly 💫)
  • -b, --back PREVMENU — run command PREVMENU when the user goes back in the menu hierarchy. useful when using nested menus; it gives the user a way to back out and return to the previous menu. note that you can use this option for other things too 👀. the command specified by the --back option is executed when the user hits one of the "back" keys.
  • --background BGCOLOR (X resource: background) — set the background color to BGCOLOR. by default, the background color is black 🖤. BGCOLOR may be the name of any color accepted by your X server.
  • -C, --class CLASSNAME — this option allows you to override ratmen's resource class. normally it is ratmen, but it can be set to another class such as ratmenu to override selected resources 👑
  • --debug — makes ratmen talk quite a lot on standard error 🗣️💬.
  • -d, --delimiter DELIM — this changes the behaviour when parsing subsequent menuitem/command pairs.

normally the command line argumens are taken to be alternately menu items and their related commands, thus requiring an even number of arguments to be passed to ratmen. (if a command is given as "" it is taken to be the same as the menu item.) this behaviour can make it somewhat difficult to distinguish between menu item arguments and command arguments in cases where the menu grow quite big (e.g. in a script). therefore an alternative is provided... 👀

if you specify a delimiter (using --delimiter) this behaviour is changed and the menu item and command are both expected to occur in the same argument, separated by whatever delimiter you've specified. this makes the command line easier to read (for a human) but is sometimes disadvantageous, especially in autogenerated menus, since the delimiter in question cannot occur in the menu item text. (see also "EXAMPLES" below 📚.)

  • -D, --display DISPLAYNAME — use the X display DISPLAYNAME, instead of the default display. normally you won't need to use this 🖥️.
  • --foreground FGCOLOR (X resource: foreground) — set the foreground color to FGCOLOR. by default, the foreground color is black 🖤. FGCOLOR may be the name of any color accepted by your X server.
  • -F, --font FONTNAME (X resource: font) — use the font FONTNAME instead of the default font ✍️.
  • -h, --help — output a brief help message 🫶.
  • --mouse (X resource: mouse)
  • --no-mouse — enable/disable mouse support in ratmen. the mouse support is quite limited (you can't scroll a large menu using the mouse) and is only intended for those moments when you instinctively want to click on something you see in order to select it 🖱️. see also "MOUSE SUPPORT".

use ratmen.mouse: false (or no or off) in your X resource file to disable mouse support as a default, and ratmen.mouse: true (or yes or on) to enable it.

  • -i, --item POSITION — pre-select menu item number POSITION, instead of the first menu item, upon opening the menu. menu items are numbered from 1 🔢. this is sometimes useful in scripts.

if POSITION is 0, then no item is selected initially. going up one item will make the menu jump to the last item, going down will jump to the first item. pressing enter while no item is selected is the same as aborting. there is no way to zero entries, other than this, so if you move about you cannot return to the state where no item is selected (but why should you ever want that? 🤨).

the described behavior is useful when the initially selected item denotes a current value (useful when called from a script) and the absence of a selected item may be used to indicate that there is no such current value 👑.

  • -p, --print — prints the COMMAND associated with the selected MENUITEM on standard output instead of running it 🖨️.

using this option you can use a menu for all kinds of selections, and not only for running a program. when using this option COMMAND no longer need to be a valid command at all — any string will work 💅. see also "EXAMPLES" below.

  • -o, --scroll-offset ITEMS (X resource: scrollOffset) — if a menu is too large to fit in one window, it will become scrollable. Ratmen will try to keep at least ITEMS number of items between the current position and the top or bottom of the menu. if you get closer than this, the menu will scroll. as you get close to the top or bottom of the menu scrolling will cease. (default scroll offset is 3.)

scroll offset may not be larger than half of the menu. if it is it will be cut down to that value ✂️.

  • -S, --shell PROG — use PROG as the shell to run commands, instead of /bin/sh. a popular alternative shell is rc(1) 🐚. if the shell cannot be executed, ratmen will silently fall back to using /bin/sh 🙈.
  • -s, --style {snazzy|dreary} (X resource: style) — the default style is dreary, where the highlight bar moves up and down the menu as it does on all conventional keyboard controlled menus. in dreary mode, the highlight bar, which shows the currently selected item, remains stationary while all the menu items are rotated up or down when the cursor keys are moved ✨.
  • -t, --title NAME — change the title of the menu window to NAME. the default title is the last component of the path used to run ratmen, typically, ratmen 🏷️.
  • --unfocus-exit (X resource: unfocusExit)
  • --no-unfocus-exit
⚠️ FIXME: currently a BadWindow error message is generated by X when the current instance of ratmen dies of unfocus. does anyone know how to fix this? 😭

--unfocus-exit causes ratmen to die (without any option being selected) if its window loses focus (it's probably not a good to use in combination with a window manager that automatically focuses the window under your pointer 💀).

--no-unfocus-exit makes ratmen survive unfocusing. this can be confusing in some cases as it makes it possible to have start several menus at once (normally the previous menu would die from unfocus) 🙈.

use ratmen.unfocusExit: false (or no or off) in your X resource file to disable unfocus deaths as a default, and ratmen.unfocusExit: true (or yes or on) to enable it.

  • -V, --version — this option prints the version of ratmen on the standard output, and then exits with an exit value of zero 👋.

💅 KEYSTROKES 💅

the Up keystrokes move the selection to the next item up ⬆️. the Down keystrokes move the selection to the next item down ⬇️. when the selection reaches the top or bottom, it scrolls around to the other side on pressing of the appropriate keystroke 🔄. the Select keystrokes execute the command corresponding to the currently selected menu item, and exit ratmen ✅. the Back keystrokes does nothing unless the --back option was used, in which case it will run the command specified by that option and exit ratmen. the Exit keystrokes quit ratmen without doing anything 🚪.

    Up      "k", Up_arrow, BackSpace, "-"
    Down    "j", Down_arrow, Space, Tab, "+"
    Select  "l", Right_arrow, Return
    Back    "h", Left_arrow
    Exit    "q", Escape

🖱️ MOUSE SUPPORT 🖱️

Ratmen implements limited support for the rodent 🐁 — you may select an item (left), go to any previous menu, given by --back, (right) or abort the menu (any other; usually middle). the mouse cannot be used to scroll the menu 🚫.

your rodent won't interfere with the normal operation. if you place the pointer on the menu by mistake, simply move it outside of the menu to restore the selection 🫶. you may, however, use the keys to manipulate an entry selected with the mouse — in this case the key based selection sticks 💜.

actions are performed upon releasing a mouse butten. to cancel an action after the button has been pressed, move it outside the menu window and release the button (this goes for all the buttons) ✨.

🌸 EXAMPLES 🌸

okay bestie, so like… what can you actually do with this thing? let's get into it 💅

wanna make a lil remote shell menu? the ratmenu-ish way would be:

ratmen --label Remotes xterm "" acme "rsh acme xterm" herman "rsh herman 9term" &

and if you wanna do it the 9menu way, type something like:

ratmen --label Remotes -d: xterm "acme:rsh acme xterm" "herman:rsh herman 9term" &

and that does the trick ✨

you could also make a menu stuffed with some cute X programs to run. like this:

ratmen --label "X progs" ghostview "" xdvi "" xeyes "" xneko "" &

or like this:

ratmen --label -d: "X progs" ghostview xdvi xeyes xneko &

ngl that last one is a bit easier on the eyes, don't you think? 🫶

if you want, you can use --back to call an "earlier" menu, like:

ratmen --back ~/bin/mypreviousmenu "X Eyes" xeyes &

and if you'd like to use a menu from inside a shell script (a similar technique can ofc be used from any other programming language, like perl) you could do this:

choice=`ratmen -pd: Abort Retry Ignore`

now whatever option gets selected lands in the environment variable $choice (note tho, it may also come out empty if the user cancelled the menu 😭). here -p (or --print) is what makes it print the selected COMMAND to standard out instead of running it, and -d (or --delimiter) is just so you don't have to fill out the command line with a bunch of ugly "" arguments. (you could, ofc, swap the colon in the command line for any character you don't use in the menu 💖)

and here are some lines from my ~/.Xresources file, for anyone curious 👀:

! ratmen ratmen*foreground:    yellow ratmen*font:
-adobe-courier-medium-r-normal-*-18-*-*-*-m-*-iso8859-1
ratmen*unfocusExit:   true

this makes my menus super easy to spot (since not much else in my system config is yellow ✨), easy to read (courier girlie here 💅) and it doesn't clutter up my screen too much in case I forget about them and wander off to do something else instead of picking an item from the menu 😅

🔍 SEE ALSO 🔍

  • /etc/X11/rgb.txt — this is where you'll find the names of appropriate colours to use with the --background and --forground options, plus X resources 💖

👑 AUTHORS 👑

okay so the lore is rich. the initial idea for this program was by Arnold Robbins, after having worked with John Mackin's GWM Blit emulation. Matty Farrow wrote a version using libXg, and some ideas were borrowed from that. this code was written by David Hogan and Arnold Robbins. Rich Salz motivated the -shell option. Jonathan Walther modified this code to play nicely with the ratpoison window manager by removing handling of mouse events and iconification.

Zrajm C Akfogh <ratmen-mail@klingonska.org> changed the command line syntax into the more standard getopts, added scrolling capacity if the menu is too large to fit all at once, added --delimiter, --item, --print, --scroll-offset and --unfocus-exit options and X resource support (Yay! no need to specify those longish font-thingies on the command line any more! 🎉).

and the name ratmen is both an abbreviation of ratmenu (from which this program is heavily derived) and a reference to the fact that I don't have any religious reasons for not using the rodent (I like the keyboard, but I also like freedom of choice 🐭✨).

🔮 FUTURE 🔮

ngl, I haven't actively made any changes to this program for several years, though it was originally my intention to write a program that works both under X and in the console.

I later wrote termmen, which much more closely resembles my intentions for ratmen, but unfortunately it only works in the console or terminal (i.e. it does not pop up a window of its own under X 😭). both termmen and this program are available from <http://zrajm.klingonska.org/programs/>.

this program is written in C, which is not my native language, while termmen is written as a zsh script. if anyone would like to continue development of ratmen, or has a patch they'd like applied — please feel free to send it to me at ratmen-mail@klingonska.org 🫶

📜 HISTORY 📜

bestie this is a diary and honestly it's giving main character energy. here's the whole timeline, dates and all 💀

  • [2003-02-21, 12:47-16:18] — Implemented --item for choosing the initially selected item. Menu item and command are now given in the same string, separated with :, which makes for nicer error detection and fewer errors since it's a bit easier to keep track of what does which on the command line.
  • [2003-02-22, 15:38-16:43]
  • [2003-02-23, 02:19-02:36] — Implemented --delimiter, which now must be used to get the "menuitem:command" (as opposed to "menuitem" "command") behaviour. This, because I realised that when called from a script using an on-the-fly generated menu it can be quite tedious to make sure that the delimiter does not occur in the menuitem string (and thus fuck up the menu). of course, in handwritten menus the delimiter approach is easier to handle, hence I allow for both. the delimiter now also may be more than one character long.
  • [2003-02-23, 19:08-20:30] — Implemented --unfocus-exit, which exits the menu if its window is unfocused.
  • [2003-02-23, 21:12-21:22]
  • [2003-02-24, 00:22-00:49]
  • [2003-02-24, 11:38-17:47] — Now reads some options regulating appearance and behaviour from X resources in addition to the command line.
  • [2003-02-25, 18:47-22:20] — Wrote POD. At last found a really good name for the product. The ratmen. 👑
  • [2003-02-26, 01:38-09:15] — Now reads command line options using getopt; thusly supports both --long-options and short ones (and bundles of short ones). Yay! Still haven't been able to get the --unfocus-exit to work properly 😭
  • [2003-02-26, 13:27-14:34] — Fixed --unfocus-exit so that it now really makes the menu die of unfocus. Unfortunately, however, a BadWindow message is generated by X when doing so, which looks quite ugly in ratpoison (which faithfully reports the error). I simply haven't been able to figure out what command is causing this, but my best guess is that there's some unlucky X function still queued which tries to manipulate the window after it has been closed 💀
  • [2003-03-03, 00:13-01:54] — Added the --print option, which can be extremely useful in scripts and other programs where you want to use a menu for some kind of input, rather than as a platform from which to fire off some program. Added the "BUGS" section below. Added the --debug option which (as of now) dumps some info on the events (key/mouse clicks, focusing, etc.) intercepted from X.
  • [2003-03-08, 11:21-11:29] — Added a declaration of the subroutine strcasecmp and thus eliminated a compiler warning. Program worked flawlessly even before (and still does) but with less annoyance for me.. =|:-) the declaration thingy was found on the 'net by googling for strcasetmp introduction. Made arguments to --align and --style case insensitive.
  • [2003-03-08, 20:27-22:58] — Found and killed a bug which made X resources override the command line options 🔥
  • [2003-03-09, 07:04-10:15] — Totally fixed the bug mentioned in the previous comment. Added short options -l, -c and -r (for left, center and right aligning of the menu text), and changed --label to --title. Also changed the size of the menu window so that it will always be an even number of text lines (looks pretty ugly when only half or a third of the last item can be seen). Opening of the window could still be more optimal though (the problem still arises when X refuses to open the window with the requested height, e.g. when one uses frames in ratpoison).
  • [2003-03-10, 00:53-04:07] — v2.0 — Optimized the menu redrawing routine for the non-scrolling case (used to flicker quite nastily when moving down large menus fast). Also finally got around to adding scrolling capacity for menus too large to fit all at once. Added the related --scroll-offset option and X resource as well.
  • [2003-03-10, 22:10-23:00] — v2.0.1 — Begun fixing the window size bug (interrupted by Buffy - The Vampire Slayer 🧛).
  • [2003-03-11, 00:31-04:25]
  • [2003-03-12, 00:13-01:14] — v2.0.2 — Fixed a weird update/redraw bug thingy. Used to get a totally black empty menu sometimes. Bug was probably introduced in the last session, and is now deceased 💀
  • [2003-03-19, 10:48-12:38]
  • [2003-03-19, 14:17-20:18] — v2.1 — Wrote better handling of X resources, complete with readable --debug output and all ✨
  • [2003-03-19, 22:40-09:05] — v2.2 — Implemented mouse support. Made --item=0 special. Bugfix: Now opens a window of the correct size by telling X that it wants a window whose vertical size should be any number of pixels evenly dividable by the font height. (Rxvt served as a source of inspiration for this feature.) Also added keys Home/PgUp for going to the first item in the menu and End/PgDn to go to the last. --class now really works.
  • [2003-03-24, 15:41-16:32] — v2.2.1 — Added options --mouse and --no-mouse and the corresponding X resource ratmen.mouse — mouse is enabled by default. Removed the short options -u and -U (synonyms for --unfocus-exit and --no-unfocus-exit) so as not to encourage the usage of those options on the command line (they should be set using X resources).
  • [2003-03-28, 11:29-11:32] — v2.2.2 — Killed a bug which didn't allow spaces to be used in font names (this little bugfix also makes it quite necessary not to end your X resources in any extraneous spaces 👀).
  • [2007-10-25, 11:23-14:13] — v2.2.3 — Bugfix. Changed a couple of latin-1 characters 173 (soft hyphens) to the minus signs they should have been all along. Added the "FUTURE" heading above. Rewrote the Makefile.

💀 BUGS 💀

okay so these are the known oopsies, no cap:

  • When no item is selected (i.e. on startup with -i0) and you hover the menu with the pointer, and then remove the pointer, the first item becomes selected. 🙈
  • The snazzy mode. I'm probably going to remove it sometime in the future. I don't use it and I don't see any reason why anybody else should want to either… (especially not now that we've got scrollable dreary mode..).
  • Generates a BadWindow when dying of unfocus under the --unfocus-exit option.
This should be curable by means of XSetErrorHandler(), at least if it is not ratpoison causing these things.
  • Memory leaks? There are probably several (me being totally new to C) but since the execution time should never really accumulate I haven't made it a priority to kill 'em. Please tell me if you find any 🫶
  • When using --item=0 and --style=snazzy one must press Down twice to select the first item on the menu. (I'll probably fix this by removing the snazzy mode.) 😭

🎀 TODO 🎀

okay so this is the author's own lil wishlist 💖 — the stuff he wants to do next, listed in roughly priority order. Not promises, bestie, just vibes and plans:

  • Parsing of standard input (so one may use ratmen as a magic number) for interpreting menu files. And like, if this is gonna work, maybe some special command line argument parsing is needed? He says — and I quote the vibe — he strongly suspects that magic number arguments are not passed in the same fashion as if given on the command line. 🫠
  • An option for outputting the number of the selected menu item (--print-number/-P, maybe?). Lowkey obsessed with this idea.
  • Change the --print behaviour to include -d: or something automatically — so that menu item text is basically the default output. ✨
  • User-configurable keys for up/down choosing and etc. Customize those binds, periodt.
  • Menu shortcuts (defined in the menu) — though ngl, if the autogenerated shortcuts turn out to be good enough, this one might not even be needed. 🙈
  • Automatically generated key shortcuts. Like numbers 0-9 for items 1-10, or hitting the letter 'a' to loop through all items beginning with an a, or "/" and "?" to do incremental forward/backward search... the possibilities are giving main character energy fr fr. 🔥
  • Multiple selection mode (space=select; enter=finalize), plus introducing colors for the marked entry and the marked & selected entry. 💅
  • Incremental search in the menu, using the bottom item space for input.
  • Replacing the top/bottom item with an arrow (or something) if the menu is scrollable in that direction. 🌸
🧚 and that's the whole page, bestie — we made it to the end, and honestly? iconic. 😭

Written by Zrajm C Akfohg and dated 2007-10-25 — that's the name and the date sitting pretty in the footer of this ratmen(1) page. Go forth and slay your menus, you absolute Unix monarch 👑💖

📦 where this page comes from