FvwmPerl(1)

💖 FvwmPerl(1) 💖

Bestie, this is the Fvwm Modules page for the FvwmPerl manipulator and preprocessor 🧚

---

✨ NAME ✨

FvwmPerl, the fvwm perl manipulator and preprocessor 🌸

🎀 SYNOPSIS 🎀

okay so FvwmPerl is supposed to be spawned by fvwm(1) for normal functionality 💅

To run this module, drop this command somewhere in your config:

Module FvwmPerl [params]

or this one:

ModuleSynchronize FvwmPerl [params]

use the second one if you want to start sending commands to FvwmPerl right away 🦋

💜 DESCRIPTION 💜

This module is giving extend fvwm commands with perl scripting power energy ⭐ It lets you embed perl expressions in your fvwm config files and build fvwm commands out of them. main character energy, literally 👑

🦋 INVOCATION 🦋

if you want the unique and persistent instance of FvwmPerl, the move is to call it from the StartFunction 🌈 You can call it from the top too, but that comes with some issues that we're not getting into here 💀

AddToFunc StartFunction I Module FvwmPerl

there are a bunch of command line switches:

FvwmPerl [ --eval line ] [ --load file ] [ --preprocess [ --quote char ]
[ --winid wid ] [ --cmd ] [ --nosend ] [ --noremove ] [ line | file ] ]
[ --export [names] ] [ --stay ] [ --nolock ] [ alias ]

long switches can be shortened down to their one-letter versions, so you don't have to type the whole thing every time 🫶

• -e, --eval line — evaluates the perl code you hand it 🔥
• -l, --load file — evaluates perl code living in the file you point at 📜
• -p, --preprocess [ file ] — preprocesses the fvwm config file you give it 🌸

these next 5 options only work together with --preprocess, so don't try them solo 🙈

• -c, --cmd line — an fvwm command to preprocess instead of a file 💖
• -q, --quote char — swaps out the default '%' quote for a different one ✨
• -w, --winid wid — sets an explicit window context 🪄 The wid should start with a digit, and it can be in oct or hex form. Whatever you pass here overwrites any implicit window context that's floating around.
• --nosend — doesn't send the preprocessed file over to fvwm to read. The default is to send it. This is super handy for preprocessing non fvwm config files 🍓
• --noremove — keeps the preprocessed file around after it's been sent to fvwm. The default is to remove it. Useful for debugging 🐛

and now the rest of the crew 💅

• -x, --export [names] — defines fvwm shortcut functions. By default you get two, named "Eval" and ".". This option implies --stay, so it sticks around 🧚
• -s, --stay — keeps things going after --eval, --load or --preprocess have been processed. By default the module is not persistent in this case, which is the same as saying --nostay is assumed 🦋
• --nolock — when one of the 3 action options is given, this option unlocks fvwm immediately. By default the requested action runs synchronously. That only makes a difference when you invoke it like this:

ModuleSynchronous FvwmPerl --preprocess someconfig.ppp

if --nolock is added there, ModuleSynchronous returns right away. Just know that Module returns immediately regardless of this option 🌸

👑 USING ALIAS 👑

aliases let you run several module invocations at once and work with each one separately. here's a little example, slay 💖

ModuleSynchronous FvwmPerl FvwmPerl-JustTest
SendToModule FvwmPerl-JustTest eval $a = 2 + 2; $b = $a
SendToModule FvwmPerl-JustTest eval cmd("Echo 2 + 2 = $b")
KillModule FvwmPerl FvwmPerl-JustTest

🔥 PREPROCESSING EXAMPLE 🔥

one of the most effective preprocessing moves is to pass your whole fvwm config, with the embedded perl code, to "FvwmPerl --preprocess" 🫶 Another option is to write a perl script that spits out fvwm commands and sends them off to run, and you can load that script with "FvwmPerl --load" ✨ There are also in-between solutions that only preprocess separate config lines, or that run separate perl commands which produce fvwm commands 🦋

this snippet adds arithmetic and string scripting to the lines that need it 🧮 To use it, make FvwmPerl your very first command so that other commands can be asked to get preprocessed 💅

ModuleSynchronize FvwmPerl

AddToFunc .
+ I SendToModule FvwmPerl preprocess -c -- $*

. Exec exec xterm -name xterm-%{++$i}%   # use unique name

. GotoDesk 0 %{ $[desk.n] + 1 }%         # go to next desk

. Exec exec %{ -x "/usr/bin/X11/aterm" ? "aterm" : "xterm" }% -sb

# center a window
Next (MyWindow) . Move \
  %{($WIDTH - $[w.width]) / 2}%p %{($HEIGHT - $[w.height]) / 2}%p

. Exec exec xmessage %{2 + 2}%           # simple calculator

. %{main::show_message(2 + 2, "Yet another Calculator"); ""}%

✨ FUNCTIONS ✨

okay so these are the functions your perl code can call 💅 they're lowkey the best part of the whole module 🫶

cmd($fvwm_command)

bestie, this one's a multitasker 🦋 during an eval or load, it sends the string $fvwm_command back to fvwm. during a preprocess, it tacks $fvwm_command onto the output of the embedded perl code instead 🎀

do_eval($perl_code)

this is basically the eval functionality but on the string $perl_code, same as described above ✨

load($filename)

same energy as the load functionality, but it works on the file $filename 🌸

preprocess(@params, ["-c $command"] [$filename])

this one is the preprocess functionality with whatever parameters you hand it, plus the file $filename we talked about earlier 💜

export($func_names, [$do_unexport])

the export functionality, using the $func_names you give it 🔥 if the second parameter is true, it'll unexport the function names instead, so it's giving two jobs in one 👑

function names can be separated by commas or/and whitespace, so do whatever is cutest to you 🍓 and if $func_names is empty, it just assumes the functions "Eval" and "." 🧚

stop()

terminates the module. bye bye 👋💀

skip()

skips the rest of the event callback code. the module goes right back to listening for new module events 🦋

unlock()

this one unsynchronizes the event callback from fvwm 🫶 it's super useful for preventing deadlocks. normally fvwm kills a non-responding module if the event callback isn't done within ModuleTimeout seconds, and unlock stops that from happening ✨

here's an example that makes FvwmPerl suspend for one minute:

SendModule FvwmPerl eval unlock(); sleep(60);

⚠️ be careful with this one, bestie 😭 verify that there's no way fvwm can send a new message while the module is busy, and that fvwm won't stay locked on that new message for too long. if you need long-lasting operations, check out the detach solution too 💖

detach()

this one forks and detaches the rest of the event callback code from the main process 🧚 it's a lifesaver if your callback takes forever, since the work can happen in the detached child and the module won't get killed 💅 the detached child can still send commands to fvwm (but don't rely on that, ngl), and it won't receive events obviously. it exits right after the callback finishes 💀

🚨 if you use detach(), it's better to only send commands to fvwm from one process, either the main one or the detached one. doing both often causes conflicts, so don't be that girl 🙈

show_message($msg, $title[, $use_stderr_too=1])

shows a dialog window with your message, using whichever X tool it finds on the system 🌈

see FVWM::Module::Toolkit::show_message for more info 💜

---

✨ VARIABLES ✨

there are a bunch of global variables in the main namespace you can use in your perl code, and they're all giving main character energy 👑

$a, $b, ... $h
@a, @b, ... @h
%a, %b, ... %h

they all start out as the empty value 🫧 you can use them to store state between different calls to FvwmPerl actions (eval and load) 🦋

if you want more readable variable names, you've got options 💖 you can write no strict 'vars'; at the start of every perl code, or use a hash, like this:

$h{id} = $h{first_name} . " " . $h{second_name}

or use a package name, like this:

@MyMenu::terminals = qw( xterm rxvt );
$MyMenu::item_num = @MyMenu::terminals;

also there may be a configuration option to turn strictness on and off, so keep an eye out 👀✨

---

✨ MESSAGES ✨

FvwmPerl can receive messages using the fvwm command SendToModule 💌 the names, meanings and parameters of the messages are the same as the corresponding actions we covered earlier, so no new homework 🎀

a stop message makes the module quit 🫡

a message unexport [func-names] undoes the effect of export (that's the one from the ACTIONS section) 🔄

and a dump message dumps the contents of the changed variables... well, not yet 🙈 so don't hold your breath 💀

---

✨ EXAMPLES ✨

okay, first up is a simple test 🧪

SendToModule FvwmPerl eval $h{dir} = $ENV{HOME}
SendToModule FvwmPerl eval load($h{dir} . "/test.fpl")
SendToModule FvwmPerl load $[HOME]/test.fpl
SendToModule FvwmPerl preprocess config.ppp
SendToModule FvwmPerl export Eval,PerlEval,PerlLoad,PerlPP
SendToModule FvwmPerl unexport PerlEval,PerlLoad,PerlPP
SendToModule FvwmPerl stop

this next one handles root backgrounds in fvwmrc 🌅 all of these commands can go in StartFunction 🫶

Module FvwmPerl --export PerlEval

# find all background pixmaps for a later use
PerlEval $a = $ENV{HOME} . "/bg"; \
  opendir DIR, $a; @b = grep { /xpm$/ } readdir(DIR); closedir DIR

# build a menu of background pixmaps
AddToMenu MyBackgrounds "My Backgrounds" Title
PerlEval foreach $b (@b) \
  { cmd("AddToMenu MyBackgrounds '$b' Exec fvwm-root $a/$b") }

# choose a random background to load on start-up
PerlEval cmd("AddToFunc \
  InitFunction + I Exec exec fvwm-root $a/" . $b[int(random(@b))])

---

✨ ESCAPING ✨

okay this part is important, bestie 🚨 SendToModule, just like any other fvwm command, expands several dollar prefixed variables 💲 and that can clash with the dollars perl uses 😭 you can avoid this by putting a leading dash in front of SendToModule. each pair below is equivalent 💖

SendToModule FvwmPerl eval $$d = "$[DISPLAY]"
-SendToModule FvwmPerl eval $d = "$ENV{DISPLAY}"

SendToModule FvwmPerl eval \
    cmd("Echo desk=$d, display=$$d")
SendToModule FvwmPerl preprocess -c \
    Echo desk=%("$d")%, display=%{$$d}%

another way to dodge escaping special symbols like dollars and backslashes is to make a perl file in ~/.fvwm and load it 🧚

SendToModule FvwmPerl load build-menus.fpl

and if you need to preprocess a command that starts with a dash, precede it with -- 🎀

# this prints the current desk, i.e. "0"
SendToModule FvwmPerl preprocess -c Echo "$%{$a = "c"; ++$a}%"
# this prints "$d"
SendToModule FvwmPerl preprocess -c -- -Echo "$%{"d"}%"
# this prints "$d" (SendToModule expands $$ to $)
SendToModule FvwmPerl preprocess -c -- -Echo "$$%{"d"}%"
# this prints "$$d"
-SendToModule FvwmPerl preprocess -c -- -Echo "$$%{"d"}%"

and once again, it's honestly suggested to put your commands into a file and preprocess the file instead 🫶

---

✨ CAVEATS ✨

FvwmPerl is written in perl and deals with perl, so it follows the famous perl motto: "There's more than one way to do it" 🌈 the choice is yours, queen 👑

here are more pairs of equivalent lines 🦋

Module FvwmPerl --load "my.fpl" --stay
Module FvwmPerl -e 'load("my.fpl")' -s

SendToModule FvwmPerl preprocess --quote '@' my.ppp
SendToModule FvwmPerl eval preprocess({quote => '@'}, "my.ppp");

⚠️ warning, you can change the way FvwmPerl works by evaluating the right perl code. this is considered a feature, not a bug 💅 but PLEASE don't do this, bestie 😭 write your own fvwm module in perl instead 🙏

---

✨ SEE ALSO ✨

the fvwm(1) man page describes all the available commands 📖

basically, in your perl code you can use any function or class method from the perl library installed with fvwm. check out the man pages of the perl packages General::FileSystem, General::Parse and FVWM::Module 💜

---

✨ AUTHOR ✨

this module was made by Mikhael Goikhman <migo@homemail.com> 🫶 iconic, honestly 👑

---

Version 2.5.28 (from cvs), dated 2009-03-22, is the FvwmPerl(1) era 🌸 thanks for reading, bestie, you're literally the best 💖✨