Module: `gears.watcher`

Fetch information at a specific interval.

Info:

Copyright: 2020 Emmanuel Lepage-Vallee
Originally authored by: Emmanuel Lepage-Vallee <elv1313@gmail.com>
(Full contributors list available on our github project)

Constructors

Create a new gears.watcher object.

Object properties

file	string	A file path.
files	table	A list or map of files.
filter	function	A filter to post-process the file or command.
command	table or string	A command.
shell	boolean or string	Use a shell when calling the command.
labels_as_properties	boolean	In files mode, when paths have labels, apply them as properties.
interval	number	The interval between the content refresh.
value	N/A	The current value of the watcher.
strip_newline	boolean	Strip the extra trailing newline.
started	boolean	The timer is started.	Inherited from gears.timer

Object methods

:abort ()	Abort the current transactions.
:append_file (path[, The])	Add a file to the files list.
:remove_file (path)	Remove a file to the files list.
:start ()	Start the timer.	Inherited from gears.timer
:stop ()	Stop the timer.	Inherited from gears.timer
:again ()	Restart the timer.	Inherited from gears.timer
:emit_signal (name, ...)	Emit a signal.	Inherited from gears.object
:connect_signal (name, func)	Connect to a signal.	Inherited from gears.object
:weak_connect_signal (name, func)	Connect to a signal weakly.	Inherited from gears.object

Signals

file::acquired	Emitted when a file is read.
file::failed	When reading a file failed.
files::acquired	Emitted when all files are read.

Constructors

gears.watcher {[args]}

Create a new gears.watcher object.

Parameters:

args
- file string A file path.
- files table A list or map of files.
- filter function A filter to post-process the file or command.
- command table or string A command (without a shell).
- shell boolean Use a shell when calling the command. (default false)
- initial_value The value to use before the first "real" value is acquired.
- interval number The interval between the content refresh.
- labels_as_properties boolean Set the file labels as properties.
- started boolean The timer is started.

Object properties

file string · 1 signal

A file path.

Usage example

Usage:

local mybatterydischarging = gears.watcher {
    file     = "/sys/class/power_supply/BAT0/status",
    interval = 5,
}

Click to display more

Emit signals:

property::gears.watcher.file When the gears.watcher.file value changes.

self gears.watcher The object which changed (useful when connecting many object to the same callback).
new_value file The new value affected to the property.

files table · 1 signal

A list or map of files.

It is often necessary to query multiple files. When reading from proc, some data is split across multiple files, such as the battery charge.

This property accepts 2 format. One uses is a plain table of paths while the other is a label->path map. Depending on what is being read, both make sense.

Simple path list:

Usage example

 local mybatterycharging = gears.watcher {
     files    = {
         "/sys/class/power_supply/AC/online",
         "/sys/class/power_supply/BAT0/status"
     },
     filter   = function(content)
         return content['/sys/class/power_supply/AC/online'  ] == "1"
             or content['/sys/class/power_supply/BAT0/status'] == "Full"
     end,
     interval = 5,
 }

With labels:

Usage example

 local mybatterycharging = gears.watcher {
     files    = {
         plugged = "/sys/class/power_supply/AC/online",
         charged = "/sys/class/power_supply/BAT0/status"
     },
     filter   = function(content)
         return content.plugged == "1" or content.charged == "Full"
     end,
     interval = 5,
 }

Emit signals:

property::gears.watcher.files When the gears.watcher.files value changes.

self gears.watcher The object which changed (useful when connecting many object to the same callback).
new_value files The new value affected to the property.

filter function · 1 signal

A filter to post-process the file or command.

It can be used, for example, to convert the string to a number or turn the various file content into the final value. The filter argument depend on various gears.watcher properties (as documented below).

The callback parameters for a single file: (1) The file content (string)

The callback parameters for a multiple files (paths): (1) Tables with the paths as keys and string content as value.

The callback parameters for a multiple files (labels): (1) Tables with the keys as keys and string content as value.

**The callback when labels_as_properties is true:** (1) The label name (2) The content

The callback parameters for a command: (1) Stdout as first parameter (2) Stderr as second parameter (3) Exitreason (4) Exitcode

Click to display more

Emit signals:

property::gears.watcher.filter When the gears.watcher.filter value changes.

self gears.watcher The object which changed (useful when connecting many object to the same callback).
new_value filter The new value affected to the property.

command table or string · 1 signal

A command.

If you plan to use pipes or any shell features, do not forget to also set shell to true.

Usage example output:

one two three

Usage example:

 local w = gears.watcher {
     interval = 0.05,
     command  = "echo one two three",
 }

 -- [wait some time]

 -- It will be "one two three"
 print(w.value)

Click to display more

Emit signals:

property::gears.watcher.command When the gears.watcher.command value changes.

self gears.watcher The object which changed (useful when connecting many object to the same callback).
new_value command The new value affected to the property.

shell boolean or string · 1 signal

Use a shell when calling the command.

This means you can use |, &&, $? in your command.

Usage example output:

three

Usage example:

 local w = gears.watcher {
     interval = 0.05,
     command  = "echo one two three | cut -f3 -d ' '",
     shell    = true,
 }

 -- [wait some time]

 -- It will be "one two three"
 print(w.value)

Click to display more

Emit signals:

property::gears.watcher.shell When the gears.watcher.shell value changes.

self gears.watcher The object which changed (useful when connecting many object to the same callback).
new_value shell The new value affected to the property.

labels_as_properties boolean

In files mode, when paths have labels, apply them as properties.

Usage example

 local battery = gears.watcher {
     labels_as_properties = true,
     interval             = 5,
     files                = {
         capacity = "/sys/class/power_supply/BAT0/energy_full",
         current  = "/sys/class/power_supply/BAT0/energy_now"
     },
     filter               = function(label, content)
         return tonumber(content)
     end,
 }

 -- Use the above in a widget.
 local w = wibox.widget {
     text = gears.reactive(function()
         return (battery.current / battery.capacity) .. "%"
     end),
     widget = wibox.widget.textbox
 }

Emit signals:

property::gears.watcher.interval When the gears.watcher.interval value changes.

self gears.watcher The object which changed (useful when connecting many object to the same callback).
new_value interval The new value affected to the property.

value N/A · 1 signal

The current value of the watcher.

If there is no filter, this will be a string. If a filter is used, then it is whatever it returns.

Click to display more

Emit signals:

property::gears.watcher.value When the gears.watcher.value value changes.

self gears.watcher The object which changed (useful when connecting many object to the same callback).

strip_newline boolean · 1 signal

Strip the extra trailing newline.

All posix compliant text file and commands end with a newline. Most of the time, this is inconvinient, so gears.watcher removes them by default. Set this to false if this isn't the desired behavior.

Click to display more

Emit signals:

property::gears.watcher.strip_newline When the gears.watcher.strip_newline value changes.

self gears.watcher The object which changed (useful when connecting many object to the same callback).
new_value strip_newline The new value affected to the property.

started boolean · Inherited from gears.timer · 1 signal

The timer is started.
Click to display more

Emit signals:

property::gears.watcher.started When the gears.watcher.started value changes.

self gears.watcher The object which changed (useful when connecting many object to the same callback).

Object methods

:abort ()

Abort the current transactions.

If files are currently being read or commands executed, abort it. This does prevent new transaction from being started. Use :stop() for that.

Parameters:

path string The path.
The string key. (optional)

:remove_file (path)

Remove a file to the files list.

Parameters:

path string The path or the key.

:start () · Inherited from gears.timer · 1 signal

Start the timer.

Emit signals:

start

:stop () · Inherited from gears.timer · 1 signal

Stop the timer.

Emit signals:

stop

:again () · Inherited from gears.timer · 2 signals

Restart the timer. This is equivalent to stopping the timer if it is running and then starting it.
Click to display more

Emit signals:

start
stop

:emit_signal (name, ...) · Inherited from gears.object

Emit a signal.

Parameters:

name string The name of the signal.
... Extra arguments for the callback functions. Each connected function receives the object as first argument and then any extra arguments that are given to emit_signal().

:connect_signal (name, func) · Inherited from gears.object

Connect to a signal.

Parameters:

name string The name of the signal.
func function The callback to call when the signal is emitted.

:weak_connect_signal (name, func) · Inherited from gears.object

Connect to a signal weakly.

This allows the callback function to be garbage collected and automatically disconnects the signal when that happens.

Warning: Only use this function if you really, really, really know what you are doing.

Parameters:

name string The name of the signal.
func function The callback to call when the signal is emitted.

Signals

file::acquired

Emitted when a file is read.

Arguments:

path string The path.
content string The file content.

Arguments:

path string The path.

files::acquired

Emitted when all files are read.

Arguments:

contents table Path as keys and content as values.
failed table The list of files which could not be read.

awesome

Contents

Classes

Core components

Input handling

Declarative rules

Widgets

Widget containers

Widget layouts

Popups and bars

Utility libraries

Theme related libraries

Client tiling

Libraries

Sample files

Documentation

Module: gears.watcher

Info:

Constructors

Object properties

Object methods

Signals

Constructors

Parameters:

Object properties

See also:

Usage:

Emit signals:

See also:

Emit signals:

Emit signals:

Emit signals:

Emit signals:

See also:

See also:

Emit signals:

Emit signals:

Emit signals:

Emit signals:

Object methods

See also:

Parameters:

Parameters:

See also:

Emit signals:

See also:

Emit signals:

Emit signals:

Parameters:

Parameters:

Parameters:

Signals

Arguments:

See also:

Arguments:

Arguments:

Module: `gears.watcher`