.\" Generated by scdoc 1.11.3
.\" Complete documentation for this program is not available as a GNU info page
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.nh
.ad l
.\" Begin generated content:
.TH "UWSM-PLUGINS" "3" "2025-01-30"
.PP
.SH NAME
.PP
\fBUWSM-plugins\fR - Plugins for Universal Wayland Session Manager.\&
.PP
.SH DESCRIPTION
.PP
Shell plugins provide compositor-specific functions during environment
preparation.\&
.PP
Located in \fI${PREFIX}\fR\fB/share/uwsm/plugins/\fR and named
\fI${__WM_BIN_ID__}\fR\fB.\&sh\fR, they should only contain specifically named
functions.\&
.PP
\fB${__WM_BIN_ID__}\fR is derived from the item 0 of compositor command line
by applying \fBs/(^[^a-zA-Z]|[^a-zA-Z0-9_])+/_/\fR and converting to lower case.\&
.PP
It is used as plugin id and suffix in function names.\&
.PP
.SS Variables available to plugins
.PP
\fB__WM_ID__\fR
.RS 4
compositor ID, effective first argument of \fBstart\fR.\&
.RE
\fB__WM_ID_UNIT_STRING__\fR
.RS 4
compositor ID escaped for systemd unit name.\&
.RE
\fB__WM_BIN_ID__\fR
.RS 4
processed first item of compositor argv.\&
.RE
\fB__WM_DESKTOP_NAMES__\fR
.RS 4
\fB:\fR-separated desktop names from \fBDesktopNames=\fR of entry and
\fB-D\fR CLI argument.\&
.RE
\fB__WM_FIRST_DESKTOP_NAME__\fR
.RS 4
first of the above.\&
.RE
\fB__WM_DESKTOP_NAMES_LOWERCASE__\fR
.RS 4
same as \fB__WM_DESKTOP_NAMES__\fR, but in lower case.\&
.RE
\fB__WM_FIRST_DESKTOP_NAME_LOWERCASE__\fR
.RS 4
first of the above.\&
.RE
\fB__WM_DESKTOP_NAMES_EXCLUSIVE__\fR
.RS 4
(\fBtrue\fR|\fBfalse\fR) indicates that
\fB__WM_DESKTOP_NAMES__\fR came from CLI argument and are
marked as exclusive.\&
.RE
\fB__OIFS__\fR
.RS 4
contains shell default field separator (\fIspace\fR, \fItab\fR, \fInewline\fR)
for convenient restoring.\&
.PP
.RE
.SS Standard functions
.PP
\fBload_wm_env\fR
.RS 4
standard function for loading env files
.RE
\fBprocess_config_dirs\fR
.RS 4
iterates over XDG Config hierarchy and system part of XDG Data hierarchy
(decreasing priority)
.RE
\fBprocess_config_dirs_reversed\fR
.RS 4
(called by \fBload_wm_env\fR), same as \fBprocess_config_dirs\fR but in
reverse (increasing priority)
.RE
\fBin_each_config_dir_reversed\fR
.RS 4
called by \fBprocess_config_dirs_reversed\fR for each config dir
as \fB$1\fR, loads \fBuwsm/env\fR, \fBuwsm/env-\fR\fI${desktop}\fR files
.RE
\fBin_each_config_dir\fR
.RS 4
called by \fBprocess_config_dirs\fR for each config dir as \fB$1\fR,
does nothing ATM
.RE
\fBsource_file\fR
.RS 4
sources \fB$1\fR file if exists, providing messages for log.\&
.PP
.RE
See code inside \fBuwsm/main.\&py\fR for more auxillary funcions.\&
.PP
.SS Functions that can be added by plugins
.PP
\fBquirks__\fR$\fI{__WM_BIN_ID__}\fR
.br
	called before env loading.\&
.PP
These functions will be called instead of standard funcions if defined:
.PP
\fBload_wm_env__\fR$\fI{__WM_BIN_ID__}\fR
.br
\fBprocess_config_dirs_reversed__\fR$\fI{__WM_BIN_ID__}\fR
.br
\fBin_each_config_dir_reversed__\fR$\fI{__WM_BIN_ID__}\fR
.br
\fBprocess_config_dirs__\fR$\fI{__WM_BIN_ID__}\fR
.br
\fBin_each_config_dir__\fR$\fI{__WM_BIN_ID__}\fR
.PP
Original functions are still available for calling explicitly if combined effect
is needed.\&
.PP
Example:
.PP
.nf
.RS 4
#!/bin/false

# function to make arbitrary actions before loading environment
quirks__my_cool_wm() {
  # here additional vars can be set or unset
  export I_WANT_THIS_IN_SESSION=yes
  unset I_DO_NOT_WANT_THAT
  # or prepare a config for compositor
  # or set a var to modify what sourcing uwsm/env, uwsm/env-${__WM_ID__}
  # in the next stage will do
  \&.\&.\&.
}

in_each_config_dir_reversed__my_cool_wm() {
  # custom mechanism for loading of env files (or a stub)
  # replaces standard function, but we want it also
  # so call it explicitly
  in_each_config_dir_reversed "$1"
  # and additionally source our file
  source_file "${1}/${__WM_ID__}/env"
}
.fi
.RE