.\" 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 "yambar-modules-script" "5" "2024-04-20"
.PP
.SH NAME
script - This module executes a user-provided script (or binary!\&)
.PP
.SH DESCRIPTION
.PP
This module executes a user-provided script (or binary!\&) that writes
tags on its stdout.\&
.PP
Scripts can be run in two modes: yambar polled, or continuously.\& In the
yambar polled mode, the script is expected to write one set of tags
and then exit.\& Yambar will execute the script again after a
configurable amount of time.\&
.PP
In continuous mode, the script is executed once.\& It will typically run
in a loop, sending an updated tag set whenever it needs, or wants
to.\& The last tag set is used (displayed) by yambar until a new tag set
is received.\& This mode is intended to be used by scripts that depends
on non-polling methods to update their state.\&
.PP
Tag sets, or \fItransactions\fR, are separated by an empty line
(e.\&g.\& \fBecho ""\fR).\& The empty line is required to commit (update) the
tag even for only one transaction.\&
.PP
Each \fItag\fR is a single line on the format:
.PP
.nf
.RS 4
name|type|value
.fi
.RE
.PP
Where \fIname\fR is what you also use to refer to the tag in the yambar
configuration, \fItype\fR is one of the tag types defined in
\fByambar-tags\fR(5), and \fIvalue\fR is the tag’s value.\&
.PP
Example:
.PP
.nf
.RS 4
var1|string|hello
var2|int|13
  <empty>
var1|string|world
var2|int|37
  <empty>
.fi
.RE
.PP
The example above consists of two transactions.\& Each transaction has
two tags: one string tag and one integer tag.\& The second transaction
replaces the tags from the first transaction.\& Note that \fB\fRboth\fB\fR
transactions need to be terminated with an empty line.\&
.PP
Supported \fItypes\fR are:
.PP
.PD 0
.IP \(bu 4
string
.IP \(bu 4
int
.IP \(bu 4
bool
.IP \(bu 4
float
.IP \(bu 4
range:n-m (e.\&g.\& \fBvar|range:0-100|57\fR)
.PD
.PP
.SH TAGS
.PP
User defined.\&
.PP
.SH CONFIGURATION
.PP
.TS
allbox;l l l lx
l l l lx
l l l lx
l l l lx.
T{
\fBName\fR
T}	T{
\fBType\fR
T}	T{
\fBReq\fR
T}	T{
\fBDescription\fR
T}
T{
path
T}	T{
string
T}	T{
yes
T}	T{
Path to script/binary to execute.\& Must either be an absolute path, or start with \fB~/\fR.\&
T}
T{
args
T}	T{
list of strings
T}	T{
no
T}	T{
Arguments to pass to the script/binary.\&
T}
T{
poll-interval
T}	T{
integer
T}	T{
no
T}	T{
Number of milliseconds between each script run.\& If unset, or set to 0, continuous mode is used.\&
T}
.TE
.sp 1
.SH EXAMPLES
.PP
Here is an "hello world" example script:
.PP
.nf
.RS 4
#!/bin/sh

while true; do
    echo "test|string|hello"
    echo ""
    sleep 3

    echo "test|string|world"
    echo ""
    sleep 3
done
.fi
.RE
.PP
This script runs in continuous mode, and will emit a single string tag,
\fItest\fR, and alternate its value between \fBhello\fR and \fBworld\fR every
three seconds.\&
.PP
A corresponding yambar configuration could look like this:
.PP
.nf
.RS 4
bar:
  left:
    - script:
        path: /path/to/script\&.sh
        args: []
        content: {string: {text: "{test}"}}
.fi
.RE
.PP
Another example use case of this module could be to display currently playing
song or other media from players that support MPRIS (Media Player Remote
Interfacing Specification):
.PP
.nf
.RS 4
bar:
  center:
    - script:
        path: /usr/bin/playerctl
        args:
          - "--follow"
          - "metadata"
          - "-f"
          - |
            status|string|{{status}}
            artist|string|{{artist}}
            title|string|{{title}}
        content:
          map:
            conditions:
              status == Paused: {empty: {}}
              status == Playing:
                content: {string: {text: "{artist} - {title}"}}
.fi
.RE
.PP
The above snippet runs a \fIplayerctl\fR utility in \fI--follow\fR mode, reacting to
media updates on DBUS and outputting status, artist and title of media being
played in a format that is recognized by yambar.\& See \fIplayerctl\fR documentation
for more available metadata fields and control over which players get used.\&
.PP
.SH SEE ALSO
.PP
\fByambar-modules\fR(5), \fByambar-particles\fR(5), \fByambar-tags\fR(5), \fByambar-decorations\fR(5)
.PP