250 lines
7.2 KiB
Groff
250 lines
7.2 KiB
Groff
.TH RIVERGUILE 1 2023-11-25 "git.sr.ht/~leon_plickat/riverguile" "General Commands Manual"
|
|
.
|
|
.SH NAME
|
|
.P
|
|
riverguile \- scheme powered scripting layer for river
|
|
.
|
|
.
|
|
.SH SYNOPSIS
|
|
.SY riverguile
|
|
path-to-script
|
|
.YS
|
|
.
|
|
.
|
|
.SH DESCRIPTION
|
|
.P
|
|
Scripting layer for the
|
|
.BR river (1)
|
|
Wayland server.
|
|
Allows the user to send commands to the Wayland server (probably river) and
|
|
install handlers for events from a scheme script.
|
|
The scheme implementation is provided by
|
|
.BR guile (1).
|
|
.P
|
|
The canonical way to use riverguile is as an interpreter for the river init
|
|
script.
|
|
To do so place the following expression at the very top of your init script:
|
|
.P
|
|
.RS
|
|
.EX
|
|
#!/bin/env riverguile
|
|
!#
|
|
.EE
|
|
.RE
|
|
.P
|
|
Do not leave out the second line, as the octothorpe plus exclamation-mark
|
|
combination indicates a multi-line comment in scheme.
|
|
Do not forget to mark your init script as executable.
|
|
Your custom scheme code to configure the river session may follow after these
|
|
two lines.
|
|
.P
|
|
By default, riverguile will exit after the script has been loaded.
|
|
However if certain handlers are installed it will run continuously to provide
|
|
that functionality.
|
|
.
|
|
.
|
|
.SH COMMANDS
|
|
.P
|
|
Riverguile exposes the special procedure
|
|
\fB(riverctl \fR\fIfirst\fR . \fIrest\fR\fB)\fR, which can be used to send
|
|
commands to the server in a similar fashion to
|
|
.BR riverctl (1).
|
|
All arguments must be strings.
|
|
.P
|
|
Here is an example of using this procedure to instruct river to spawn an
|
|
instance of the
|
|
.BR foot (1)
|
|
terminal emulator:
|
|
.P
|
|
.RS
|
|
.EX
|
|
(\fBriverctl\fR "spawn" "foot")
|
|
.EE
|
|
.RE
|
|
.P
|
|
To make using this procedure more ergonomic you likely want to wrap it in a
|
|
macro like this:
|
|
.P
|
|
.RS
|
|
.EX
|
|
(\fBdefine-syntax\fR R
|
|
(\fBsyntax-rules\fR ()
|
|
((R first) (riverctl (\fBsymbol->string\fR 'first)))
|
|
((R first . rest) (\fBapply\fR riverctl
|
|
(\fBmap\fR \fBsymbol->string\fR
|
|
(\fBappend\fR '(first) 'rest))))))
|
|
|
|
(R spawn foot)
|
|
(R spawn \fB#{\fRnotify-send notification!\fB}#\fR)
|
|
.EE
|
|
.RE
|
|
.P
|
|
This macro can of course be further modified to suit your specific needs.
|
|
.
|
|
.
|
|
.SH EVENT HANDLERS
|
|
.P
|
|
Riverguile exposes the special procedure
|
|
\fB(install-handler \fR\fIkey\fR \fIproc\fR\fB)\fR, which can be used to install
|
|
event handlers.
|
|
The parameter \fIkey\fR is a symbol indicating for which event to install
|
|
the procedure \fIproc\fR.
|
|
The following keys are currently available:
|
|
.
|
|
.P
|
|
\fBlayout-demand\fR
|
|
.P
|
|
.RS
|
|
Installing a handler for this key allows the user to provide window layouts.
|
|
All limitations of the river-layout-v3 protocol apply.
|
|
The server will trigger this event when a new layout is required ("demanded").
|
|
.P
|
|
Installing a layout-demand handler will cause riverguile to run continuously.
|
|
.P
|
|
The handler procedure must accept five required arguments, which are, in order:
|
|
The amount of views in the layout (integer), the available width (integer), the
|
|
available height (integer), the currently active tag set (integer representing a
|
|
bitfield of size 32) and the global name of the output the layout is needed for
|
|
(integer).
|
|
The procedure must return a list containing exactly as many lists as there are
|
|
views in the layout.
|
|
Each of those sublists must contains exactly four numerical values, which are
|
|
the x and y coordinates of the window as well as its width and height.
|
|
Window positions and dimensions get applied to the window list top to bottom.
|
|
.P
|
|
Note that the numerical values do not need to be exact, riverguile takes care
|
|
of rounding and casting for you.
|
|
.P
|
|
Here is an example of a simple layout-demand handler which simply makes all
|
|
windows use all available space:
|
|
.P
|
|
.RS
|
|
.EX
|
|
(\fBinstall-handler\fR 'layout-demand
|
|
(\fBlambda\fR (view-count width height tags output)
|
|
(\fBletrec\fR ((iter (\fBlambda\fR (n)
|
|
(if (eq? 0 n)
|
|
'()
|
|
(\fBappend\fR (\fBlist\fR (\fBlist\fR 0 0 width height))
|
|
(iter (1- n)))))))
|
|
(iter view-count))))
|
|
.EE
|
|
.RE
|
|
.RE
|
|
.
|
|
.P
|
|
\fBuser-command\fR
|
|
.P
|
|
.RS
|
|
User commands are intended to allowing the user to update parameters of the
|
|
layout live.
|
|
The user sends a command - a string - to the server, which relays is to the
|
|
layout generator.
|
|
Of course, nothing is stopping you from (ab-)using this event to trigger
|
|
arbitrary scheme code on key presses or on outside events, or from simply not
|
|
using it at all.
|
|
Please see
|
|
.BR riverctl (1)
|
|
regarding how to send user commands and how to configure the server to send them
|
|
on key presses (note that usage of the riverctl executable maps one-to-one to
|
|
the usage of the riverguile procedure of the same name).
|
|
After a user-command has been received, the server will trigger a layout-demand
|
|
if there are visible windows.
|
|
.P
|
|
Installing a user-command handler will \fInot\fR cause riverguile to run continuously.
|
|
This event is an extension to the layout-demand event and as such it is invalid
|
|
to install a user-command handler without also installing a layout-demand
|
|
handler.
|
|
.P
|
|
The handler procedure must accept three arguments, which are, in order:
|
|
The command (string), the currently active tags (integer representing a
|
|
bitfield of size 32) and the global name of the output (integer).
|
|
.P
|
|
Here is an example of a simple user-command handler which simply evaluates the
|
|
string as scheme code:
|
|
.P
|
|
.RS
|
|
.EX
|
|
(\fBinstall-handler\fR 'user-command
|
|
(\fBlambda\fR (cmd tags output)
|
|
(\fBeval-string\fR cmd)))
|
|
.EE
|
|
.RE
|
|
.P
|
|
Note that this is not necessarily good practice, but serves as a decent example.
|
|
.RE
|
|
.
|
|
.P
|
|
\fBidle:X\fR
|
|
.P
|
|
.RS
|
|
A handler installed for this key will be triggered after the system has been
|
|
idle for \fIX\fR seconds and once more once the system is no longer idle.
|
|
.P
|
|
Installing an idle handler will cause riverguile to run continuously.
|
|
Multiple idle handlers can be installed.
|
|
.P
|
|
Idle state is server policy and may depend on a multitude of factors, but
|
|
usually maps directly to the usage activity of input devices by the user.
|
|
Certain programs may inhibit idle state, like for example video players.
|
|
.P
|
|
The handler procedure must accept one argument, a symbol indicating the type
|
|
of idle event.
|
|
This symbol is either \fBidle\fR, indicating the system has been idle for the
|
|
configured amount of time, or \fBresume\fR, indicating that the system is no
|
|
longer idle.
|
|
.P
|
|
Here is an example which will dim the screen after two minutes of inactivity
|
|
and lock it after five:
|
|
.P
|
|
.RS
|
|
.EX
|
|
(\fBinstall-handler\fR 'idle:120
|
|
(\fBlambda\fR (event)
|
|
(\fBcond\fR ((\fBeq?\fR event 'idle) (riverctl "spawn" "light -S 20"))
|
|
((\fBeq?\fR event 'resume) (riverctl "spawn" "light -S 100")))))
|
|
|
|
(\fBinstall-handler\fR 'idle:300
|
|
(\fBlambda\fR (event)
|
|
(if (\fBeq?\fR event 'idle) (riverctl "spawn" "swaylock"))))
|
|
.EE
|
|
.RE
|
|
.P
|
|
Note: All idle events relate to the first advertised seat.
|
|
As of now, river only supports a single seat anyway.
|
|
.RE
|
|
.
|
|
.P
|
|
\fBexit\fR
|
|
.RE
|
|
.RS
|
|
This key allows you to installs a handler which is called when riverguile exits.
|
|
.P
|
|
The procedure takes no arguments.
|
|
.P
|
|
Here is an example which adds a message to the system log on exit:
|
|
.P
|
|
.RS
|
|
.EX
|
|
(\fBinstall-handler\fR 'exit
|
|
(\fBlambda\fR ()
|
|
(riverctl "spawn" "logger 'goodbye from riverguile'")))
|
|
.EE
|
|
.RE
|
|
.RE
|
|
|
|
.
|
|
.
|
|
.SH SEE ALSO
|
|
.BR river (1),
|
|
.BR riverctl (1),
|
|
.BR rivertile (1),
|
|
.BR guile (1)
|
|
.
|
|
.
|
|
.SH AUTHOR
|
|
.P
|
|
.MT leonhenrik.plickat@stud.uni-goettingen.de
|
|
Leon Henrik Plickat
|
|
.ME
|