1yambar-modules-script(5) File Formats Manual yambar-modules-script(5)
2
6 script - This module executes a user-provided script (or binary!)
7
9 This module executes a user-provided script (or binary!) that writes
10 tags on its stdout.
11 Scripts can be run in two modes: yambar polled, or continuously. In the
13 yambar polled mode, the script is expected to write one set of tags and
14 then exit. Yambar will execute the script again after a configurable
15 amount of time.
16 In continuous mode, the script is executed once. It will typically run
18 in a loop, sending an updated tag set whenever it needs, or wants to.
19 The last tag set is used (displayed) by yambar until a new tag set is
20 received. This mode is intended to be used by scripts that depends on
21 non-polling methods to update their state.
22 Tag sets, or transactions, are separated by an empty line (e.g. echo
24 ""). The empty line is required to commit (update) the tag even for
25 only one transaction.
26 Each tag is a single line on the format:
28 name|type|value
30 Where name is what you also use to refer to the tag in the yambar con‐
32 figuration, type is one of the tag types defined in yambar-tags(5), and
33 value is the tag’s value.
34 Example:
36 var1|string|hello
38 var2|int|13
39 <empty>
40 var1|string|world
41 var2|int|37
42 <empty>
43 The example above consists of two transactions. Each transaction has
45 two tags: one string tag and one integer tag. The second transaction
46 replaces the tags from the first transaction. Note that both transac‐
47 tions need to be terminated with an empty line.
48 Supported types are:
50 • string
52 • int
53 • bool
54 • float
55 • range:n-m (e.g. var|range:0-100|57)
56
59 User defined.
60
62 ┌──────────────┬─────────────────┬─────┬──────────────────┐
63 │Name │ Type │ Req │ Description │
64 ├──────────────┼─────────────────┼─────┼──────────────────┤
65 │path │ string │ yes │ Path to │
66 │ │ │ │ script/binary to │
67 │ │ │ │ execute. Must be │
68 │ │ │ │ an absolute │
69 │ │ │ │ path. │
70 ├──────────────┼─────────────────┼─────┼──────────────────┤
71 │args │ list of strings │ no │ Arguments to │
72 │ │ │ │ pass to the │
73 │ │ │ │ script/binary. │
74 ├──────────────┼─────────────────┼─────┼──────────────────┤
75 │poll-interval │ integer │ no │ Number of sec‐ │
76 │ │ │ │ onds between │
77 │ │ │ │ each script run. │
78 │ │ │ │ If unset, con‐ │
79 │ │ │ │ tinuous mode is │
80 │ │ │ │ used. │
81 └──────────────┴─────────────────┴─────┴──────────────────┘
82
84 Here is an "hello world" example script:
85 #!/bin/sh
87 while true; do
89 echo "test|string|hello"
90 echo ""
91 sleep 3
92 echo "test|string|world"
94 echo ""
95 sleep 3
96 done
97 This script runs in continuous mode, and will emit a single string tag,
99 test, and alternate its value between hello and world every three sec‐
100 onds.
101 A corresponding yambar configuration could look like this:
103 bar:
105 left:
106 - script:
107 path: /path/to/script.sh
108 args: []
109 content: {string: {text: "{test}"}}
110 Another example use case of this module could be to display currently
112 playing song or other media from players that support MPRIS (Media
113 Player Remote Interfacing Specification):
114 bar:
116 center:
117 - script:
118 path: /usr/bin/playerctl
119 args:
120 - "--follow"
121 - "metadata"
122 - "-f"
123 - |
124 status|string|{{status}}
125 artist|string|{{artist}}
126 title|string|{{title}}
127 content:
128 map:
129 tag: status
130 values:
131 Paused: {empty: {}}
132 Playing:
133 content: {string: {text: "{artist} - {title}"}}
134 The above snippet runs a playerctl utility in --follow mode, reacting
136 to media updates on DBUS and outputting status, artist and title of me‐
137 dia being played in a format that is recognized by yambar. See play‐
138 erctl documentation for more available metadata fields and control over
139 which players get used.
140
142 yambar-modules(5), yambar-particles(5), yambar-tags(5), yambar-decora‐
143 tions(5)
144 2022-08-26 yambar-modules-script(5)