feat: add subcommand to force-poll variable (#1227)

* feat: add subcommand for force-polling variable

* docs: document the new `eww poll` subcommand

CHANGELOG.md

@@ -19,6 +19,7 @@ All notable changes to eww will be listed here, starting at changes since versio
 - `get_locale` now follows POSIX standard for locale selection (By: mirhahn, w-lfchen)
 
 ### Features
+- Add `eww poll` subcommand to force-poll a variable (By: kiana-S)
 - Add OnDemand support for focusable on wayland (By: GallowsDove)
 - Add jq `raw-output` support (By: RomanHargrave)
 - Update rust toolchain to 1.81.0 (By: w-lfchen)

crates/eww/src/app.rs

@@ -45,6 +45,7 @@ use yuck::{
 pub enum DaemonCommand {
     NoOp,
     UpdateVars(Vec<(VarName, DynVal)>),
+    PollVars(Vec<VarName>),
     ReloadConfigAndCss(DaemonResponseSender),
     OpenInspector,
     OpenMany {
@@ -167,6 +168,11 @@ impl<B: DisplayBackend> App<B> {
                     self.update_global_variable(var_name, new_value);
                 }
             }
+            DaemonCommand::PollVars(names) => {
+                for var_name in names {
+                    self.force_poll_variable(var_name);
+                }
+            }
             DaemonCommand::ReloadConfigAndCss(sender) => {
                 let mut errors = Vec::new();
 
@@ -336,6 +342,23 @@ impl<B: DisplayBackend> App<B> {
         }
     }
 
+    fn force_poll_variable(&mut self, name: VarName) {
+        match self.eww_config.get_script_var(&name) {
+            Err(err) => error_handling_ctx::print_error(err),
+            Ok(var) => {
+                if let ScriptVarDefinition::Poll(poll_var) = var {
+                    log::debug!("force-polling var {}", &name);
+                    match script_var_handler::run_poll_once(&poll_var) {
+                        Err(err) => error_handling_ctx::print_error(err),
+                        Ok(value) => self.update_global_variable(name, value),
+                    }
+                } else {
+                    error_handling_ctx::print_error(anyhow!("Script var '{}' is not polling", name))
+                }
+            }
+        }
+    }
+
     /// Close a window and do all the required cleanups in the scope_graph and script_var_handler
     fn close_window(&mut self, instance_id: &str) -> Result<()> {
         if let Some(old_abort_send) = self.window_close_timer_abort_senders.remove(instance_id) {

crates/eww/src/opts.rs

@@ -98,6 +98,16 @@ pub enum ActionWithServer {
         mappings: Vec<(VarName, DynVal)>,
     },
 
+    /// Update a polling variable using its script.
+    ///
+    /// This will force the variable to be updated even if its
+    /// automatic polling is disabled.
+    #[command(name = "poll")]
+    Poll {
+        /// Variables to be polled
+        names: Vec<VarName>,
+    },
+
     /// Open the GTK debugger
     #[command(name = "inspector", alias = "debugger")]
     OpenInspector,
@@ -254,6 +264,7 @@ impl ActionWithServer {
     pub fn into_daemon_command(self) -> (app::DaemonCommand, Option<daemon_response::DaemonResponseReceiver>) {
         let command = match self {
             ActionWithServer::Update { mappings } => app::DaemonCommand::UpdateVars(mappings),
+            ActionWithServer::Poll { names } => app::DaemonCommand::PollVars(names),
             ActionWithServer::OpenInspector => app::DaemonCommand::OpenInspector,
 
             ActionWithServer::KillServer => app::DaemonCommand::KillServer,

crates/eww/src/script_var_handler.rs

@@ -196,7 +196,7 @@ impl PollVarHandler {
     }
 }
 
-fn run_poll_once(var: &PollScriptVar) -> Result<DynVal> {
+pub fn run_poll_once(var: &PollScriptVar) -> Result<DynVal> {
     match &var.command {
         VarSource::Shell(span, command) => {
             script_var::run_command(command).map_err(|e| anyhow!(create_script_var_failed_warn(*span, &var.name, &e.to_string())))

docs/src/configuration.md

@@ -209,6 +209,9 @@ and thus are the perfect choice for showing your time, date, as well as other bi
 You can also specify an initial-value. This should prevent eww from waiting for the result of a given command during startup, thus
 making the startup time faster.
 
+To externally update a polling variable, `eww update` can be used like with basic variables to assign a value.
+You can also call `eww poll` to poll the variable outside of its usual interval, or even while it isn't running at all.
+
 **Listening variables (`deflisten`)**
 
 ```lisp