Update changelog and docs for vicious.call

CHANGELOG.rst

@@ -1,8 +1,16 @@
 Changelog
 =========
 
-Changes in 2.5.0 (WIP)
-----------------------
+Changes in 2.5.0
+----------------
+
+Fixed:
+
+- ``vicious.call`` freezing awesome when used with asynchronous widget types
+
+Added:
+
+- ``vicious.call_async`` asynchronous analogous to ``vicious.call``
 
 Moved:
 

docs/requirements.txt

@@ -1,2 +1,3 @@
 Sphinx >= 3
+sphinx_rtd_theme
 sphinxcontrib-luadomain

docs/source/conf.py

@@ -28,10 +28,7 @@ templates_path = ['_templates']
 exclude_patterns = []
 
 # Options for HTML output
-html_theme = 'alabaster'
-html_theme_options = {
-    'github_user': 'vicious-widgets', 'github_repo': 'vicious',
-    'github_button': True, 'github_count': False}
+html_theme = 'sphinx_rtd_theme'
 html_show_copyright = False
 
 # Add any paths that contain custom static files (such as style sheets)

docs/source/usage-awesome.rst

@@ -31,8 +31,7 @@ call ``vicious.register`` to register it with Vicious:
    :param widget: awesome widget created from
                   ``awful.widget`` or ``wibox.widget``
 
-   :param wtype:
-      either of
+   :param wtype: either of
 
       * Vicious widget type: any widget type
         :ref:`provided by Vicious <widgets>` or customly defined.
@@ -40,8 +39,7 @@ call ``vicious.register`` to register it with Vicious:
         awesome configuration can be registered as widget types
         (see :ref:`custom-wtype`).
 
-   :param format:
-      either of
+   :param format: either of
 
       * string: ``$key`` will be replaced by respective value in the table
         ``t`` returned by the widget type, i.e. use ``$1``, ``$2``, etc.
@@ -105,25 +103,23 @@ vicious.force
 
    :param wtable: table of one or more widgets to be updated
 
-vicious.call
-------------
+vicious.call[_async]
+--------------------
 
 .. lua:function:: vicious.call(wtype, format, warg)
 
-   Fetch data from the widget type to use it outside of the widget
+   Get formatted data from a synchronous widget type
    (:ref:`example <call-example>`).
 
-   :param wtype:
-      either of
+   :param wtype: either of
 
-      * Vicious widget type: any widget type
+      * Vicious widget type: any synchronous widget type
         :ref:`provided by Vicious <widgets>` or customly defined.
       * ``function``: custom function from your own
         awesome configuration can be registered as widget types
         (see :ref:`custom-wtype`).
 
-   :param format:
-      either of
+   :param format: either of
 
       * string: ``$key`` will be replaced by respective value in the table
         ``t`` returned by the widget type, i.e. use ``$1``, ``$2``, etc.
@@ -132,7 +128,32 @@ vicious.call
       * ``function (widget, args)`` can be used to manipulate data returned
         by the widget type (see :ref:`format-func`).
 
-   :param warg: arguments to be passed to widget types, e.g. the battery ID.
+   :param warg: arguments to be passed to the widget type, e.g. the battery ID.
+
+   :return: ``nil`` if the widget type is asynchronous,
+            otherwise the formatted data from with widget type.
+
+.. lua:function:: vicious.call_async(wtype, format, warg, callback)
+
+   Get formatted data from an asynchronous widget type.
+
+   :param wtype: any asynchronous widget type
+                 :ref:`provided by Vicious <widgets>` or customly defined.
+
+   :param format: either of
+
+      * string: ``$key`` will be replaced by respective value in the table
+        ``t`` returned by the widget type, i.e. use ``$1``, ``$2``, etc.
+        to retrieve data from an integer-indexed table (a.k.a. array);
+        ``${foo bar}`` will be substituted by ``t["{foo bar}"]``.
+      * ``function (widget, args)`` can be used to manipulate data returned
+        by the widget type (see :ref:`format-func`).
+
+   :param warg: arguments to be passed to the widget type.
+
+   :param callback: function taking the formatted data from with widget type.
+                    If the given widget type happens to be synchronous,
+                    ``nil`` will be passed to ``callback``.
 
 .. _awesome: https://awesomewm.org/
 .. _awful.widget.watch:

init.lua

@@ -1,20 +1,16 @@
 -- Vicious module initialization
 -- Copyright (C) 2009  Lucas de Vries <lucas@glacicle.com>
 -- Copyright (C) 2009-2013  Adrian C. (anrxc) <anrxc@sysphere.org>
--- Copyright (C) 2011  Joerg T. (Mic92) <jthalheim@gmail.com>
+-- Copyright (C) 2011-2017  Joerg Thalheim <joerg@thalheim.io>
 -- Copyright (C) 2012  Arvydas Sidorenko <asido4@gmail.com>
--- Copyright (C) 2012  Jörg Thalheim <jthalheim@gmail.com>
 -- Copyright (C) 2013  Dodo <dodo.the.last@gmail.com>
--- Copyright (C) 2013-2014,2017  Jörg Thalheim <joerg@higgsboson.tk>
 -- Copyright (C) 2014  blastmaster <blastmaster@tuxcode.org>
--- Copyright (C) 2015  Daniel Hahler <git@thequod.de>
+-- Copyright (C) 2015,2019  Daniel Hahler <github@thequod.de>
 -- Copyright (C) 2017  James Reed <supplantr@users.noreply.github.com>
--- Copyright (C) 2017  Joerg Thalheim <joerg@thalheim.io>
 -- Copyright (C) 2017  getzze <getzze@gmail.com>
 -- Copyright (C) 2017  mutlusun <mutlusun@github.com>
 -- Copyright (C) 2018  Beniamin Kalinowski <beniamin.kalinowski@gmail.com>
--- Copyright (C) 2018  Nguyễn Gia Phong <vn.mcsinyx@gmail.com>
--- Copyright (C) 2019  Daniel Hahler <github@thequod.de>
+-- Copyright (C) 2018,2020  Nguyễn Gia Phong <mcsinyx@disroot.org>
 --
 -- This file is part of Vicious.
 --
@@ -322,16 +318,39 @@ function vicious.activate(widget)
 end
 -- }}}
 
--- {{{ Get custom widget format data
-function vicious.call(myw, format, warg)
-    local mydata = myw(format, warg)
+-- {{{ Get formatted data from a synchronous widget type
+function vicious.call(wtype, format, warg)
+    if wtype.async ~= nil then return nil end
+
+    local data = wtype(format, warg)
     if type(format) == "string" then
-        return helpers.format(format, mydata)
+        return helpers.format(format, data)
     elseif type(format) == "function" then
-        return format(myw, mydata)
+        return format(wtype, data)
     end
 end
 -- }}}
 
+-- {{{ Get formatted data from an asynchronous widget type
+function vicious.call_async(wtype, format, warg, callback)
+    if wtype.async == nil then
+        callback()
+        return
+    end
+
+    wtype.async(
+        format, warg,
+        function (data)
+            if type(format) == "string" then
+                callback(helpers.format(format, data))
+            elseif type(format) == "function" then
+                callback(format(wtype, data))
+            else
+                callback()
+            end
+        end)
+end
+-- }}}
+
 return vicious
 -- }}}