Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
FVWMPERL(1)			 FVWM Modules			   FVWMPERL(1)

       FvwmPerl	- the FVWM perl	manipulator and	preprocessor

       FvwmPerl	should be spawned by fvwm(1) for normal	functionality.

       To run this module, place this command somewhere	in the configuration:

	   Module FvwmPerl [params]


	   ModuleSynchronize FvwmPerl [params]

       if you want to immediately start	to send	commands to FvwmPerl.

       This module is intended to extend fvwm commands with the	perl scripting
       power.  It enables to embed perl	expressions in the fvwm	config files
       and construct fvwm commands.

       If you want to invoke the unique	and persistent instance	of FvwmPerl,
       it is suggested to do this from the StartFunction.  Calling it from the
       top is also possible, but involves some issues not discussed here.

	   AddToFunc StartFunction I Module FvwmPerl

       There are several 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 may be abbreviated	to short one-letter switches.

       -e|--eval line -	evaluate the given perl	code

       -l|--load file -	evaluate perl code in the given	file

       -p|--preprocess [ file ]	- preprocess the given fvwm config file

       The following 5 options are only	valid together with --preprocess op-

       -c|--cmd	line - an FVWM command to be preprocessed instead of file

       -q|--quote char - change	the default '%'	quote

       -w|--winid wid -	set explicit window context (should begin with digit,
       may be in oct or	hex form; this window id overwrites implicit window
       context if any)

       --nosend	- do not send the preprocessed file to fvwm for	Reading, the
       default is send.	Useful for preprocessing non fvwm config files.

       --noremove - do not remove the preprocessed file	after sending it to
       fvwm for	Reading, the default is	remove.	Useful for debugging.

       -x|--export [names] - define fvwm shortcut functions (by	default, two
       functions named "Eval" and ".").	 This option implies --stay.

       -s|--stay - continues an	execution after	--eval,	--load or --preprocess
       are processed.  By default, the module is not persistent	in this	case,
       i.e. --nostay is	assumed.

       --nolock	- when one of the 3 action options is given, this option
       causes unlocking	fvwm immediately. By default the requested action is
       executed	synchronously; this only makes difference when invoked like:

	   ModuleSynchronous FvwmPerl --preprocess someconfig.ppp

       If --nolock is added here, ModuleSynchronous returns immediately.  Note
       that Module returns immediately regardless of this option.

       Aliases allow to	have several module invocations	and work separately
       with all	invocations, here is an	example:

	   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

       One of the effective proprocessing solutions is to pass the whole fvwm
       configuration with embeded perl code to "FvwmPerl --preprocess".	 An
       alternative approach is to write	a perl script that produces fvwm com-
       mands and sends them for	execution, this	script may be loaded using
       "FvwmPerl --load". There	are hovewer intermediate solutions that	pre-
       process only separate configuration lines (or alternatively, execute
       separate	perl commands that produce fvwm	commands).

       The following code snippet adds ability of arithmetics and string
       scripting to certain lines that need this. To use this, you want	to
       start FvwmPerl as your first command so that other commands may be
       asked to	be preprosessed.

	   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::showMessage(2 + 2,	"Yet another Calculator"); ""}%

       There are several actions that FvwmPerl may perform:

       eval perl-code
	   Evaluate a line of perl code.

	   A special function cmd("command") may be used in perl code to send
	   commands back to fvwm.

	   If perl code	contains an error, it is printed to the	standard error
	   stream with the [FvwmPerl][eval]: header prepended.

       load file-name
	   Load	a file of perl code.  If the file is not fully qualified, it
	   is searched in the user directory $FVWM_USERDIR (usually ~/.fvwm)
	   and the system wide data directory $FVWM_DATADIR.

	   A special function cmd("command") may be used in perl code to send
	   commands back to fvwm.

	   If perl code	contains an error, it is printed to the	standard error
	   stream with the [FvwmPerl][load]: header prepended.

       preprocess [-q|--quote char] [-c|--cmd] [line | file]
	   Preprocess fvwm config file or (if --cmd is given) line.  This file
	   contains lines that are not touched (usually	FVWM commands) and
	   specially preformatted perl code that is processed and replaced.
	   Text	enclosed in %{ ... }% delimiters, that may start anywhere on
	   the line and	end anywhere on	the same or an other line, is perl

	   The quote parameter changes perl code delimiters.  If a single char
	   is given, like '@', the delimiters are @{ ... }@.  If the given
	   quote is 2 chars, like <>, the quotes are <{	... }>

	   The perl code is substituted	for the	result of its evaluation.
	   I.e.	%{$a = "c"; ++$a}% is replaced with "d".

	   The evaluation is unlike eval and load is done under	the package
	   PreprocessNamespace and without use strict, so you are free to use
	   any variable	names without fear of conflicts. Just don't use	unini-
	   tialized variables to mean undef or empty list (they	may be in fact
	   initialized by the previous preprocess action), and do a clean-up
	   if needed.  The variables and function in the main package are
	   still available, like ::cmd() or ::skip(), but it is	just not a
	   good	idea to	access them while preprocessing.

	   There is a special function include(file) that loads	a file,	pre-
	   processes it	and returns the	preprocessed result. Avoid recursion.

	   If any embedded perl	code contains an error,	it is printed to the
	   standard error stream and prepended with the	[FvwmPerl][prepro-
	   cess]: header.  The result of substitution is empty in this case.

	   The following variables may be used in the perl code:


	   The following line based directives are recognized when preprocess-
	   ing.	 They are processed after the perl code	(if any) is substi-

	   %Repeat count
	       Causes the following lines to be	repeated count times.

	   %ModuleConfig module-name [ destroy ]
	       Causes the following lines to be	interpreted as the given mod-
	       ule configuration.  If "destroy"	is specified the previous mod-
	       ule configuration is destroyed first.

	   %Prefix prefix
	       Prefixes	the following lines with the quoted prefix.

	   %End	any-optional-comment
	       Ends any	of the directives described above, may be nested.


	       %Prefix "AddToFunc SwitchToWindow I"
		   Iconify off
		   WindowShade off
		   WrapToWindow	50 50

	       %ModuleConfig FvwmPager destroy
		   Colorset 0
		   Font	lucidasans-10
		   DeskTopScale	28
	       %End ModuleConfig FvwmPager

	       %Prefix "All (MyWindowToAnimate)	ResizeMove "
	       100 100 %{($WIDTH - 100)	/ 2}% %{($HEIGHT - 100)	/ 2}%
	       %Repeat %{$count}%
	       br w+2c w+2c w-1c w-1c
	       %Repeat %{$count}%
	       br w-2c w-2c w+1c w+1c
	       %End Prefix

	   Additional preprocess parameters --nosend and --noremove may	be
	   given too.  See their description at	the top.

       export [func-names]
	   Send	to fvwm	the definition of shortcut functions that help to ac-
	   tivate different actions of the module (i.e.	eval, load and prepro-

	   Function names (func-names) may be separated	by commas or/and
	   whitespace.	By default, two	functions "Eval" and "." are assumed.

	   The actual action defined in	a function is guessed from the func-
	   tion	name if	possible, where	function name "." is reserved for pre-
	   process action.

	   For example,	any of these two fvwm commands

	      SendToModule MyPerl export PerlEval,PP
	      FvwmPerl --export	PerlEval,PP MyPerl

	   define the following	two shortcut functions:

	     DestroyFunc PerlEval
	     AddToFunc I SendToModule MyPerl eval $*
	     DestroyFunc PP
	     AddToFunc I SendToModule MyPerl preprocess	-c -- $*

       These 4 actions may be requested	in one of 3 ways: 1) in	the command
       line when FvwmPerl is invoked (in this case FvwmPerl is short-lived un-
       less --stay or --export is also given), 2) by sending the corresponding
       message in fvwm config using SendToModule, 3) by	calling	the corre-
       sponding	perl function in perl code.

       There are several functions that	perl code may call:

	   In case of eval or load - send back to fvwm a string	$fvwmCommand.
	   In case of preprocess - append a string $fvwmCommand	to the output
	   of the embedded perl	code.

	   This	function is equivalent to the eval functionality on the	string
	   $perlCode, described	above.

	   This	function is equivalent to the load functionality on the	file
	   $fileName, described	above.

       preprocess(@params, ["-c	$command"] [$fileName])
	   This	function is equivalent to the preprocess functionality with
	   the given parameters	and the	file $fileName described above.

       export($funcNames, [$doUnexport])
	   This	function is equivalent to the export functionality with	the
	   given $funcNames, described above. May also unexport	the function
	   names if the	second parameter is true.

	   Function names should be separated by commas	or/and whitespace.  If
	   $funcNames is empty then functions "Eval" and "." are assumed.

	   Terminates the module.

	   Skips the rest of the event callback	code, i.e. the module returns
	   to listen to	new module events.

	   Unsynchronizes the event callback from fvwm.	This may be useful to
	   prevent deadlocks, i.e. usually fvwm	kills the non-responding mod-
	   ule if the event callback is	not finished in	ModuleTimeout seconds.
	   This	prevents it.

	   This	example	causes FvwmPerl	to suspend its execution for one

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

	   However, verify that	there is no way	a new message is sent by fvwm
	   while the module is busy, and fvwm stays locked on this new message
	   for too long.  See also the detach solution if you need long	last-
	   ing operations.

	   Forks and detaches the rest of the event callback code from the
	   main	process. This may be useful to prevent killing the module if
	   its event callback should take a long time to complete and it may
	   be done in the detached child. The detached child may still send
	   commands to fvwm (don't rely	on this), but not receive the events
	   of course, it exits immediately after the callback execution	is

	   If you use detach(),	better only send commands to fvwm in one
	   process (the	main one or the	detached one), doing otherwise may of-
	   ten cause conflicts.

       showMessage($msg, $title[, $useStderrToo=1])
	   Shows a dialog window with the given	message, using whichever tool
	   is find in the system.

	   See FVWM::Module::Toolkit::showMessage for more information.

       There are several global	variables in the main namespace	that may be
       used in the perl	code:

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

       They all	are initialized	to the empty value and may be used to store a
       state between different calls to	FvwmPerl actions (eval and load).

       If you need more	readable variable names, either	write "no strict
       'vars';"	at the start of	every perl code	or use a hash for this,	like:

	   $h{id} = $h{firstName} . " "	. $h{secondName}

       or use a	package	name, like:

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

       There may be a configuration option to turn strictness on and off.

       FvwmPerl	may receive messages using the fvwm command SendToModule.  The
       names, meanings and parameters of the messages are the same as the cor-
       responding actions, described above.

       Additionally, a message stop causes a module to quit.

       A message unexport [func-names] undoes the effect of export, described
       in the ACTIONS section.

       A message dump dumps the	contents of the	changed	variables (not yet).

       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

       The following example handles root backgrounds in fvwmrc.  All these
       commands	may be added to	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))])

       SendToModule just like any other	fvwm commands expands several dollar
       prefixed	variables.  This may clash with	the dollars perl uses.	You
       may avoid this by prefixing SendToModule	with a leading dash.  The fol-
       lowing 2	lines in each pair are 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 solution	to avoid escaping of special symbols like dollars and
       backslashes is to create	a perl file in ~/.fvwm and then	load it:

	   SendToModule	FvwmPerl load build-menus.fpl

       If you need to preprocess one command starting with a dash, you should
       precede it using	"--".

	   # 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"}%"

       Again, it is suggested to put your command(s) into file and preprocess
       the file	instead.

       FvwmPerl	being written in perl and dealing with perl, follows the fa-
       mous perl motto:	"There's more than one way to do it", so the choice is

       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 may	affect the way FvwmPerl	works by evaluating appropri-
       ate perl	code, this is considered a feature not a bug.  But please
       don't do	this, write your own FVWM module in perl instead.

       The fvwm(1) man page describes all available commands.

       Basically, in your perl code you	may use	any function or	class method
       from the	perl library installed with FVWM, see the man pages of perl
       packages	General::FileSystem, General::Parse and	FVWM::Module.

       Mikhael Goikhman	<>.

perl v5.8.6			  2005-08-11			   FVWMPERL(1)


Want to link to this manual page? Use this URL:

home | help