Merge pull request #1 from awchad/features/gears

feat: add documentation for `gears`

.stylua.toml

@@ -1,6 +1,6 @@
-column_width = 80
+column_width = 140
 line_endings = "Unix"
 indent_type = "Spaces"
-indent_width = 4
+indent_width = 2
 quote_style = "AutoPreferSingle"
 call_parentheses = "Always"

lua/gears/color/init.lua

@@ -0,0 +1,46 @@
+--- ### Description
+--- This module simplifies the creation of cairo pattern objects.
+---
+--- In most places in awesome where a color is needed, the provided argument is passed to [`gears.color`](https://awesomewm.org/apidoc/theme_related_libraries/gears.color.html#),
+--- which actually calls [`create_pattern`](https://awesomewm.org/apidoc/theme_related_libraries/gears.color.html#create_pattern) and creates a pattern from a given string or table.
+---
+--- This function can create solid, linear, radial and png patterns.
+---
+--- A simple example for a solid pattern is a hexadecimal color specification. For example `#ff8000` creates a solid pattern with 100% red, 50% green and 0% blue.
+--- Limited support for named colors (red) is also provided.
+---
+--- In general, patterns are specified as strings formatted as "type:arguments". "arguments" is specific to the pattern being used.
+--- For example, one can use:
+--- ```
+--- 'radial:50,50,10:55,55,30:0,#ff0000:0.5,#00ff00:1,#0000ff'
+--- ```
+--- The above will call [`create_radial_pattern`](https://awesomewm.org/apidoc/theme_related_libraries/gears.color.html#create_radial_pattern)
+--- with the provided string, after stripping the `radial:` prefix.
+---
+--- Alternatively, patterns can be specified via tables. In this case, the table's `type` member specifies the type.
+--- For example:
+--- ```
+--- {
+---   type = 'radial',
+---   from = { 50, 50, 10 },
+---   to = { 55, 55, 30 },
+---   stops = { { 0, '#ff0000' }, { 0.5, '#00ff00' }, { 1, '#0000ff' } },
+--- }
+--- ```
+--- Any argument that cannot be understood is passed to [`create_solid_pattern`](https://awesomewm.org/apidoc/theme_related_libraries/gears.color.html#create_solid_pattern).
+---
+---  Please note that you **MUST NOT** modify the returned pattern, for example by calling `:set_matrix()` on it,
+--- because this function uses a cache and your changes could thus have unintended side effects.
+--- Use [`create_pattern_uncached`](https://awesomewm.org/apidoc/theme_related_libraries/gears.color.html#create_pattern_uncached)
+--- if you need to modify the returned pattern.
+---
+--- ### Information
+--- - **Copyright**: 2010 Uli Schlachter
+--- - **Originally authored by**: Uli Schlachter
+---
+--- [See all contributors on GitHub](https://github.com/awesomeWM/awesome/graphs/contributors)
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.color.html)
+local GColour = {}
+
+return GColour

lua/gears/debug/__emmylua.lua

@@ -0,0 +1,9 @@
+--- ### Description
+--- This file contains the EmmyLua based annotations for `gears.debug`, you should not use `require` in this file.
+--- @module "gears.debug.__emmylua"
+
+--#region DebugDeprecateDescriptor Definition
+
+--- @class DebugDeprecateDescriptor
+--- @field raw boolean Print the message as-is without the automatic context.
+--- @field deprecate_in integer Print the message only when Awesome's version is equal to or greater than `deprecated_in`.

lua/gears/debug/init.lua

@@ -0,0 +1,76 @@
+--- ### Information
+--- - **Copyright**: 2010 Uli Schlachter
+--- - **Originally authored by**: Uli Schlachter
+---
+--- [See all contributors on GitHub](https://github.com/awesomeWM/awesome/graphs/contributors)
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.debug.html)
+--- @module "gears.debug"
+local GDebugging = {}
+
+--- ### Description
+--- Inspect the value in data.
+--- ### Parameters
+--- @generic TArg
+--- @generic TValue
+--- @param data TArg Value to inspect.
+--- @param tag TValue The name of the value.
+--- @param depth? integer Depth of recursion.
+--- ### Returns
+--- @return string result A string that contains the expanded value of data.
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.debug.html#dump_return)
+GDebugging.dump_return = function(data, tag, depth) end
+
+--- ### Description
+--- Print the table (or any other value) to the console.
+--- ### Parameters
+--- @generic TArg
+--- @generic TValue
+--- @param data TArg Value to inspect.
+--- @param tag TValue The name of the value.
+--- @param depth? integer Depth of recursion.
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.debug.html#dump)
+GDebugging.dump = function(data, tag, depth) end
+
+--- ### Description
+--- Print an warning message.
+--- ### Parameters
+--- @param message string The warning message to print.
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.debug.html#print_warning)
+GDebugging.print_warning = function(message) end
+
+--- ### Description
+--- Print an error message.
+--- ### Parameters
+--- @param message string The error message to print.
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.debug.html#print_error)
+GDebugging.print_error = function(message) end
+
+--- ### Description
+--- Display a deprecation notice, but only once per traceback.
+---
+--- This function also emits the `debug::deprecation` signal on the [`awesome`](https://awesomewm.org/apidoc/core_components/awesome.html#) global object.
+--- If the deprecated API has been deprecated for more than one API level, it will also send a non-fatal error.
+--- ### Parameters
+--- @param see? string  The message to a new method / function to use.
+--- @param args DebugDeprecateDescriptor Extra arguments.
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.debug.html#deprecate)
+GDebugging.deprecate = function(see, args) end
+
+--- ### Description
+--- Create a class proxy with deprecation messages.
+--- This is useful when a class has moved somewhere else.
+--- ### Parameters
+--- @param fallback table The new class.
+--- @param old_name string The old class name.
+--- @param new_name string The new class name.
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.debug.html#deprecate_class)
+GDebugging.deprecate_class = function(fallback, old_name, new_name) end
+
+return GDebugging

lua/gears/filesystem/__emmylua.lua

@@ -0,0 +1,11 @@
+--- ### Description
+--- This file contains the EmmyLua based annotations for `gears.filesystem`, you should not use `require` in this file.
+--- @module "gears.filesystem.__emmylua"
+
+--#region GFSUserDirectoryAliases Definition
+
+--- @alias GFSUserDirectoryAliases
+--- | "config" # Configuration folder located in the user's home folder.
+--- | "cache" # Cache folder located in the user's home folder.
+
+--#endregion

lua/gears/filesystem/init.lua

@@ -0,0 +1,153 @@
+--- ### Description
+--- Filesystem module for `gears`.
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.filesystem.html)
+local GFS = {}
+
+--- ### Description
+--- Create a directory, including all missing parent directories.
+--- ### Parameters
+--- @param directory string  The directory.
+--- ### Returns
+--- @return boolean success, nil | string result Returns true and null if successful, otherwise false and error.
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.filesystem.html#make_directories)
+GFS.make_directories = function(directory) end
+
+--- ### Description
+---  Create all parent directories for a given path.
+--- ### Parameters
+--- @param path string The path whose parents should be created.
+--- ### Returns
+--- @return boolean success, nil | string result Returns true and null if successful, otherwise false and error.
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.filesystem.html#make_parent_directories)
+GFS.make_parent_directories = function(path) end
+
+--- ### Description
+--- Check if a file exists, is readable and not a directory.
+--- ### Parameters
+--- @param filename string The file path.
+--- ### Returns
+--- @return boolean result Returns true if the file exists and is readable.
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.filesystem.html#file_readable)
+GFS.file_readable = function(filename) end
+
+--- ### Description
+--- Check if a file exists, is executable and not a directory.
+--- ### Parameters
+--- @param filename string The file path.
+--- ### Returns
+--- @return boolean result Returns true if the file exists and is executable.
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.filesystem.html#file_executable)
+GFS.file_executable = function(filename) end
+
+--- ### Description
+--- Check if a path exists, is readable and a directory.
+--- ### Parameters
+--- @param path string The directory path.
+--- ### Returns
+--- @return boolean result Returns true if the directory exists and is readable.
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.filesystem.html#dir_readable)
+GFS.dir_readable = function(path) end
+
+--- ### Description
+--- Check if a path is a directory.
+--- ### Parameters
+--- @param path string The directory path.
+--- ### Returns
+--- @return boolean result Returns true if the directory exists and is readable.
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.filesystem.html#is_dir)
+GFS.is_dir = function(path) end
+
+--- ### Description
+--- Get the path of the configuration folder located in the user's home folder.
+--- ### Returns
+--- @return string result Returns the configuration folder path with a slash at the end.
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.filesystem.html#get_xdg_config_home)
+GFS.get_xdg_config_home = function() end
+
+--- ### Description
+--- Get the path of the cache folder located in the user's home folder.
+--- ### Returns
+--- @return string result Returns the cache folder path with a slash at the end.
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.filesystem.html#get_xdg_cache_home)
+GFS.get_xdg_cache_home = function() end
+
+--- ### Description
+--- Get the path of the data folder located in the user's home folder.
+--- ### Returns
+--- @return string result Returns the data folder path with a slash at the end.
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.filesystem.html#get_xdg_data_home)
+GFS.get_xdg_data_home = function() end
+
+--- ### Description
+--- Get the list of data directories located in the system folder.
+--- ### Returns
+--- @return string[] result Returns the list of data directories.
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.filesystem.html#get_xdg_data_dirs)
+GFS.get_xdg_data_dirs = function() end
+
+--- ### Description
+--- Get the folder containing the AwesomeWM configuration, this is usually located in `$HOME/.config/awesome`.
+--- ### Returns
+--- @return string result Returns the folder containing the AwesomeWM configuration.
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.filesystem.html#get_configuration_dir)
+GFS.get_configuration_dir = function() end
+
+--- ### Description
+--- Get the path to a directory that should be used to cache data.
+--- ### Returns
+--- @return string result The requested path string with a trailing slash.
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.filesystem.html#get_cache_dir)
+GFS.get_cache_dir = function() end
+
+--- ### Description
+--- Get the path to the directory where the themes are installed.
+--- ### Returns
+--- @return string result The requested path string with a trailing slash.
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.filesystem.html#get_themes_dir)
+GFS.get_themes_dir = function() end
+
+--- ### Description
+--- Get the path to the directory where our icons are installed.
+--- ### Returns
+--- @return string result The requested path string with a trailing slash.
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.filesystem.html#get_awesome_icon_dir)
+GFS.get_awesome_icon_dir = function() end
+
+--- ### Description
+--- Get the user configuration or cache directory.
+--- ### Parameters
+--- @param directory GFSUserDirectoryAliases The directory to get (or `config` or `cache`).
+--- ### Returns
+--- @return string result The string containing the requested path.
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.filesystem.html#get_dir)
+GFS.get_dir = function(directory) end
+
+--- ### Description
+--- Get the name of a random file from a given directory.
+--- ### Parameters
+--- @param path string The directory to search.
+--- @param extensions? string[] Specific extensions to narrow your search. If omitted, all files are considered.
+--- @param absolute_path? boolean Return the absolute path instead of the filename.
+--- ### Returns
+--- @return string | nil result A randomly selected filename from the specified path (with a specified extension if necessary) or null if no suitable file is found. If `absolute_path` is set, a path will be returned instead of a filename.
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.filesystem.html#get_random_file_from_dir)
+GFS.get_random_file_from_dir = function(path, extensions, absolute_path) end
+
+return GFS

lua/gears/geometry/__emmylua.lua

@@ -0,0 +1,23 @@
+--- ### Description
+--- This file contains the EmmyLua based annotations for `gears.geometry`, you should not use `require` in this file.
+--- @module "gears.geometry.__emmylua"
+
+--#region Geometric Objects
+
+--- @class GoRectangle
+--- @field x number The horizontal coordinate.
+--- @field y number The verticate coordinate.
+--- @field width number The rectangle width.
+--- @field height number The rectangle height.
+
+--#endregion
+
+--#region Geometry Aliases
+
+--- @alias GeometryDirection
+--- | "up"
+--- | "down"
+--- | "right"
+--- | "left"
+
+--#endregion

lua/gears/geometry/init.lua

@@ -0,0 +1,130 @@
+--- ### Description
+--- Helper functions used to compute geometries.
+---
+--- When this module refer to a geometry table, this assume a table with at least an `x`, `y`, `width` and `height` keys and numeric values.
+--- ### Information
+--- - **Copyright**: 2008 Julien Danjou
+--- - **Originally authored by**: Julien Danjou <julien@danjou.info>
+---
+--- [See all contributors on GitHub](https://github.com/awesomeWM/awesome/graphs/contributors)
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.geometry.html)
+--- @module "gears.geometry"
+local GGeometry = {}
+local DefRectangle = {}
+
+--- ### Description
+--- Get the square distance between a rectangle and a point.
+--- ### Parameters
+--- @param geometry GoRectangle A rectangle.
+--- @param x number X coordinate of point.
+--- @param y number Y coordinate of point.
+--- ### Returns
+--- @return number result The squared distance of the rectangle to the provided point.
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.geometry.html#gears.geometry.rectangle.get_square_distance)
+DefRectangle.get_square_distance = function(geometry, x, y) end
+
+--- ### Description
+--- Return the closest rectangle from `list` for a given point.
+--- ### Parameters
+--- @param list GoRectangle[] A list of geometry tables.
+--- @param x number The X coordinate.
+--- @param y number The Y coordinate.
+--- ### Returns
+--- @return GoRectangle result The key from the closest geometry.
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.geometry.html#gears.geometry.rectangle.get_closest_by_coord)
+DefRectangle.get_closest_by_coord = function(list, x, y) end
+
+--- ### Description
+--- Return the rectangle containing the `[x, y]` point.
+---
+--- Note that if multiple element from the geometry list contains the point, the returned result is nondeterministic.
+--- ### Parameters
+--- @param list GoRectangle[] A list of geometry tables.
+--- @param x number The X coordinate.
+--- @param y number The Y coordinate.
+--- ### Returns
+--- @return GoRectangle | nil result The key from the closest geometry. In case no result is found, `nil` is returned.
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.geometry.html#gears.geometry.rectangle.get_by_coord)
+DefRectangle.get_by_coord = function(list, x, y) end
+
+--- ### Description
+--- Get the nearest rectangle in the given direction.
+--- Every rectangle is specified as a table with `x`, `y`, `width`, `height` keys, the same as client or screen geometries.
+--- ### Parameters
+--- @param direction GeometryDirection The direction, can be either up, down, left or right.
+--- @param list GoRectangle[] A table of rectangle specifications.
+--- @param current GoRectangle The current rectangle.
+--- ### Returns
+--- @return integer index The index for the rectangle in `list` closer to `current` in the given direction. `nil` if none found.
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.geometry.html#gears.geometry.rectangle.get_in_direction)
+DefRectangle.get_in_direction = function(direction, list, current) end
+
+--- ### Description
+--- Return true if the area are exactly identical.
+---
+--- The areas are table with a `x`, `y`, `width` and `height` keys.
+--- ### Parameters
+--- @param a GoRectangle The area.
+--- @param b GoRectangle The other area.
+--- ### Returns
+--- @return boolean result If the areas are identical.
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.geometry.html#gears.geometry.rectangle.are_equal)
+DefRectangle.are_equal = function(a, b) end
+
+--- ### Description
+--- Return if rectangle `a` is within rectangle `b`.
+---
+---  This includes the edges. 100% of `a` area has to be within `b` for this function to return true.
+--- If you wish to know if any part of a intersect with `b`,
+--- use [`gears.geometry.rectangle.get_intersection`](https://awesomewm.org/apidoc/utility_libraries/gears.geometry.html#gears.geometry.rectangle.get_intersection).
+--- ### Parameters
+--- @param a GoRectangle The smaller area.
+--- @param b GoRectangle The larger area.
+--- ### Returns
+--- @return boolean result If the areas are identical.
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.geometry.html#gears.geometry.rectangle.is_inside)
+DefRectangle.is_inside = function(a, b) end
+
+--- ### Description
+--- Check if an area intersect another area.
+--- ### Parameters
+--- @param a GoRectangle The area.
+--- @param b GoRectangle The other area.
+--- ### Returns
+--- @return boolean result True if they intersect, false otherwise.
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.geometry.html#gears.geometry.rectangle.area_intersect_area)
+DefRectangle.area_intersect_area = function(a, b) end
+
+--- ### Description
+--- Get the intersect area between `a` and `b`.
+--- ### Parameters
+--- @param a GoRectangle The area.
+--- @param b GoRectangle The other area.
+--- ### Returns
+--- @return GoRectangle result The intersect area.
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.geometry.html#gears.geometry.rectangle.get_intersection)
+DefRectangle.get_intersection = function(a, b) end
+
+--- ### Description
+--- Remove an area from a list, splitting the space between several area that can overlap.
+--- ### Parameters
+--- @param areas GoRectangle[] Table of areas.
+--- @param elem GoRectangle Area to remove.
+--- ### Returns
+--- @return GoRectangle[] result The new area list.
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.geometry.html#gears.geometry.rectangle.area_remove)
+DefRectangle.area_remove = function(areas, elem) end
+
+GGeometry.rectangle = DefRectangle
+
+return GGeometry

lua/gears/math/init.lua

@@ -0,0 +1,50 @@
+--- ### Description
+--- Math module for gears.
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.math.html)
+local GMath = {}
+
+--- ### Description
+--- Return all subsets of a specific set. This function, giving a set, will return all subset it.
+--- For example, if we consider a set with value `{ 10, 15, 34 }`,
+--- it will return a table containing `2^n` set: `{ }, { 10 }, { 15 }, { 34 }, { 10, 15 }, { 10, 34 }`, etc.
+--- ### Parameters
+--- @param set table A set.
+--- ### Returns
+--- @return table result A table with all subset.
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.math.html#subsets)
+GMath.subsets = function(set) end
+
+--- ### Description
+--- Make i cycle.
+--- ### Parameters
+--- @param t any A length. Must be greater than zero.
+--- @param i any      An absolute index to fit into `t`.
+--- ### Returns
+--- @return integer | nil result An integer in `(1, t)` or `nil` if `t` is less than or equal to zero.
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.math.html#cycle)
+GMath.cycle = function(t, i) end
+
+--- ### Description
+--- Round a number to an integer.
+--- ### Parameters
+--- @param x integer Undocumented!
+--- ### Returns
+--- @return integer result Undocumented!
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.math.html#round)
+GMath.round = function(x) end
+
+--- ### Description
+--- Return the sign of the number `x`.
+--- ### Parameters
+--- @param x number Undocumented!
+--- ### Returns
+--- @return integer result Return `1` if `x` is positive, `-1` if negative and `0` if `x` is `0`.
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.math.html#sign)
+GMath.sign = function(x) end
+
+return GMath

lua/gears/object/__emmylua.lua

@@ -0,0 +1,14 @@
+--- ### Description
+--- This file contains the EmmyLua based annotations for `gears.object`, you should not use `require` in this file.
+--- @module "gears.object.__emmylua"
+
+--#region ObjectDescriptor Definition
+
+--- ### Description
+--- These are the arguments that will be passed to `gears.object`.
+--- @class ObjectDescriptor
+--- @field enable_properties? boolean Automatically call getters and setters. It is false by default.
+--- @field enable_auto_signals? boolean Generate `property::xxxx` signals when an unknown property is set. It is false by default.
+--- @field class? table It is a table that will be used to create the object. It is null by default.
+
+--#endregion

lua/gears/object/init.lua

@@ -0,0 +1,103 @@
+--- ### Description
+--- The object oriented programming base class used by various Awesome widgets and components.
+---
+--- It provide basic observer pattern, signaling and dynamic properties.
+--- ### Information
+--- - **Copyright**: 2010 Uli Schlachter
+--- - **Originally authored by**: Uli Schlachter
+---
+--- [See all contributors on GitHub](https://github.com/awesomeWM/awesome/graphs/contributors)
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.object.html)
+--- @module "gears.object"
+local GObject = {}
+
+--- ### Description
+--- Creates an AwesomeWM object.
+--- You can call
+--- [`:emit_signal()`](https://awesomewm.org/apidoc/utility_libraries/gears.object.html#emit_signal),
+--- [`:disconnect_signal()`](https://awesomewm.org/apidoc/utility_libraries/gears.object.html#disconnect_signal) and
+--- [`:connect_signal()`](https://awesomewm.org/apidoc/utility_libraries/gears.object.html#connect_signal)
+--- on the resulting object.
+--- ### Parameters
+--- @param args ObjectDescriptor The arguments.
+--- ### Returns
+--- @return Object result A new object.
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.object.html#gears.object)
+GObject.object = function(args) end
+
+--- @class Object
+local Object = {}
+
+--- ### Description
+--- Connect to a signal.
+--- ### Parameters
+--- @param name string The name of the signal.
+--- @param action function The callback to call when the signal is emitted.
+--- ### Usage
+--- ```
+--- local my_object = gears.object({})
+---
+--- -- Function can be attached to signals
+--- local function slot(obj, a, b, c)
+---     print('In slot', obj, a, b, c)
+--- end
+---
+--- my_object:connect_signal('my_signal', slot)
+---
+--- -- Emitting can be done without arguments. In that case, the object will be
+--- -- implicitly added as an argument.
+--- my_object:emit_signal('my_signal')
+---
+--- -- It is also possible to add as many random arguments are required.
+--- my_object:emit_signal('my_signal', 'foo', 'bar', 42)
+---
+--- -- Finally, to allow the object to be garbage collected (the memory freed), it
+--- -- is necessary to disconnect the signal or use weak_connect_signal
+--- my_object:disconnect_signal('my_signal', slot)
+---
+--- -- This time, the slot wont be called as it is no longer connected.
+--- my_object:emit_signal('my_signal')
+--- ```
+--- #### Output
+--- ```
+--- In slot [obj]   nil nil nil
+--- In slot [obj]   foo bar 42
+--- ```
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.object.html#connect_signal)
+function Object:connect_signal(name, action) end
+
+--- ### Description
+--- Connect to a signal weakly.
+---
+--- This allows the callback function to be garbage collected and automatically disconnects the signal when that happens.
+--- ### Parameters
+--- @param name string The name of the signal.
+--- @param action function The callback to call when the signal is emitted.
+--- ### Warnings
+--- > Only use this function if you really, really, really know what you are doing.
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.object.html#weak_connect_signal)
+function Object:weak_connect_signal(name, action) end
+
+--- ### Description
+--- Disconnect from a signal.
+--- ### Parameters
+--- @param name string The name of the signal.
+--- @param action function The callback that should be disconnected.
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.object.html#disconnect_signal)
+function Object:disconnect_signal(name, action) end
+
+--- ### Description
+--- Emit a signal.
+--- ### Parameters
+--- @param name string The name of the signal.
+--- @param ... any 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()`](https://awesomewm.org/apidoc/utility_libraries/gears.object.html#emit_signal).
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.object.html#emit_signal)
+function Object:emit_signal(name, ...) end
+
+return GObject.object

lua/gears/protected_call/init.lua

@@ -0,0 +1,26 @@
+--- ### Description
+--- Call a function in protected mode and handle error reports.
+--- ### Information
+--- - **Copyright**: 2016 Uli Schlachter
+--- - **Originally authored by**: Uli Schlachter
+---
+--- [See all contributors on GitHub](https://github.com/awesomeWM/awesome/graphs/contributors)
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.protected_call.html)
+--- @module "gears.protected_call"
+local GSafety = {}
+
+--- ### Description
+--- Call a function in protected mode and handle error-reporting.
+--- If the function call succeeds, all results of the function are returned.
+--- Otherwise, an error message is printed and nothing is returned.
+--- ### Parameters
+--- @param func function The function to call.
+--- @param ... any Arguments to the function.
+--- ### Returns
+--- @return any result The result of the given function, or nothing if an error occurred.
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.protected_call.html#gears.protected_call)
+GSafety.protected_call = function(func, ...) end
+
+return GSafety

lua/gears/shape/__emmylua.lua

@@ -0,0 +1,9 @@
+--- ### Description
+--- This file contains the EmmyLua based annotations for `gears.shape`, you should not use `require` in this file.
+--- @module "gears.shape.__emmylua"
+
+--#region ShapeFn Definition
+
+--- @alias ShapeFn fun(cairo, width: number, height: number, ...?: any)
+
+--#endregion

lua/gears/shape/init.lua

@@ -0,0 +1,437 @@
+--- ### Description
+--- Module dedicated to gather common shape painters.
+---
+--- It adds the concept of "shape" to Awesome.
+--- A shape can be applied to a background, a margin, a mask or a drawable shape bounding.
+---
+--- The functions exposed by this module always take a cairo context as first parameter followed by a width and height.
+--- Individual functions may take additional parameters for their specific implementions.
+---
+--- The functions provided by this module only create a path in the content.
+--- To actually draw the content, use `cairo:fill()`, `cairo:mask()`, `cairo:clip()` or `cairo:stroke()`.
+---
+--- In many case, it is necessary to apply the shape using a transformation such as a rotation.
+--- The preferred way to do this is to wrap the function in another function calling `cairo:rotate()` (or any other transformation matrix).
+---
+--- To specialize a shape where the API doesn't allows extra arguments to be passed, it is possible to wrap the shape function like:
+--- ```
+--- local new_shape = function(cairo, width, height)
+---   gears.shape.rounded_rect(cairo, width, height, 2)
+--- end
+--- ```
+--- Many elements can be shaped. This include:
+--- - [Client](https://awesomewm.org/apidoc/core_components/client.html#)s (See [`gears.surface.apply_shape_bounding`](https://awesomewm.org/apidoc/libraries/gears.surface.html#apply_shape_bounding))
+--- - [Wibox](https://awesomewm.org/apidoc/popups_and_bars/wibox.html#)es (See [`wibox.shape`](https://awesomewm.org/apidoc/popups_and_bars/wibox.html#shape))
+--- - All widgets (See [`wibox.container.background`](https://awesomewm.org/apidoc/widget_containers/wibox.container.background.html#))
+--- - The progressbar (See [`wibox.widget.progressbar.bar_shape`](https://awesomewm.org/apidoc/widgets/wibox.widget.progressbar.html#bar_shape))
+--- - The graph (See [`wibox.widget.graph.step_shape`](https://awesomewm.org/apidoc/widgets/wibox.widget.graph.html#step_shape))
+--- - The checkboxes (See [`wibox.widget.checkbox.check_shape`](https://awesomewm.org/apidoc/widgets/wibox.widget.checkbox.html#check_shape))
+--- - Images (See [`wibox.widget.imagebox.clip_shape`](https://awesomewm.org/apidoc/widgets/wibox.widget.imagebox.html#clip_shape))
+--- - The taglist tags (See [`awful.widget.taglist`](https://awesomewm.org/apidoc/widgets/awful.widget.taglist.html#))
+--- - The tasklist clients (See [`awful.widget.tasklist`](https://awesomewm.org/apidoc/widgets/awful.widget.tasklist.html#))
+--- - The tooltips (See [`awful.tooltip`](https://awesomewm.org/apidoc/popups_and_bars/awful.tooltip.html#))
+--- ### Information
+--- - **Copyright**: 2011-2016 Emmanuel Lepage Vallee
+--- - **Originally authored by**: Emmanuel Lepage Vallee
+---
+--- [See all contributors on GitHub](https://github.com/awesomeWM/awesome/graphs/contributors)
+---
+--- [View documents](https://awesomewm.org/apidoc/theme_related_libraries/gears.shape.html)
+--- @module "gears.shape"
+local GShape = {}
+
+--- ### Description
+--- Add a squircle shape with only some of the corner are "circled" to the current path. The squircle is not exactly as the definition.
+--- It will expand to the shape's width and height, kinda like an ellipse.
+--- ### Parameters
+--- @param cairo any A cairo context.
+--- @param width number The shape width.
+--- @param height number The shape height.
+--- @param top_left boolean If the top left corner is rounded.
+--- @param top_right boolean If the top right corner is rounded.
+--- @param bottom_right boolean If the bottom right corner is rounded.
+--- @param bottom_left boolean If the bottom left corner is rounded.
+--- @param rate number The "squareness" of the squircle, should be greater than 1.
+--- @param delta number The "smoothness" of the shape, delta must be greater than 0.01 and will be reset to 0.01 if not.
+--- ### Usage
+--- ```
+--- shape.partial_squircle(cairo, 70, 70, false, true)
+--- shape.partial_squircle(cairo, 70, 70, true, false, true)
+--- shape.partial_squircle(cairo, 70, 70, true, false, true, true)
+--- ```
+---
+--- [View documents](https://awesomewm.org/apidoc/theme_related_libraries/gears.shape.html#partial_squircle)
+GShape.partial_squircle = function(cairo, width, height, top_left, top_right, bottom_right, bottom_left, rate, delta) end
+
+--- ### Description
+--- Add a squircle shape to the current path. This will behave the same as [`partial_squircle`](https://awesomewm.org/apidoc/theme_related_libraries/gears.shape.html#partial_squircle).
+--- ### Parameters
+--- @param cairo any A cairo context.
+--- @param width number The shape width.
+--- @param height number The shape height.
+--- @param rate number The "squareness" of the squircle, should be greater than 1.
+--- @param delta number The "smoothness" of the shape, delta must be greater than 0.01 and will be reset to 0.01 if not.
+--- ### Usage
+--- ```
+--- shape.squircle(cairo, 70, 70, 2)
+--- shape.squircle(cairo, 70, 70, 8)
+--- shape.squircle(cairo, 70, 70, 1.5)
+--- ```
+---
+--- [View documents](https://awesomewm.org/apidoc/theme_related_libraries/gears.shape.html#squircle)
+GShape.squircle = function(cairo, width, height, rate, delta) end
+
+--- ### Description
+--- Add a star shape to the current path. The star size will be the minimum of the given width and weight.
+--- ### Parameters
+--- @param cairo any A cairo context.
+--- @param width number The shape width.
+--- @param height number The shape height.
+--- @param number? integer Number of grams. It is 5 by default.
+--- ### Usage
+--- ```
+--- shape.star(cairo, 70, 70, 4)
+--- shape.star(cairo, 70, 70, 9)
+--- shape.transform(shape.star):translate(70 / 2, 70 / 2):rotate(math.pi):scale(0.5, 0.75):translate(-70 / 2, -70 / 2)(cr, 70, 70)
+--- ```
+---
+--- [View documents](https://awesomewm.org/apidoc/theme_related_libraries/gears.shape.html#start)
+GShape.star = function(cairo, width, height, number) end
+
+--- ### Description
+--- Add a rounded rectangle to the current path. Note: If the radius is bigger than either half side, it will be reduced.
+--- ### Parameters
+--- @param cairo any A cairo context.
+--- @param width number The shape width.
+--- @param height number The shape height.
+--- @param radius number The corner radius.
+--- ### Usage
+--- ```
+--- shape.rounded_rect(cairo, 70, 70, 10)
+--- shape.rounded_rect(cairo, 20, 70, 5)
+--- shape.transform(shape.rounded_rect):translate(0, 25)(cairo, 70, 20, 5)
+--- ```
+---
+--- [View documents](https://awesomewm.org/apidoc/theme_related_libraries/gears.shape.html#rounded_rect)
+GShape.rounded_rect = function(cairo, width, height, radius) end
+
+--- ### Description
+--- Add a rectangle delimited by 2 180 degree arcs to the path.
+--- ### Parameters
+--- @param cairo any A cairo context.
+--- @param width number The shape width.
+--- @param height number The shape height.
+--- ### Usage
+--- ```
+--- shape.rounded_bar(cairo, 70, 70)
+--- shape.rounded_bar(cairo, 20, 70)
+--- shape.rounded_bar(cairo, 70, 20)
+--- ```
+---
+--- [View documents](https://awesomewm.org/apidoc/theme_related_libraries/gears.shape.html#rounded_bar)
+GShape.rounded_bar = function(cairo, width, height) end
+
+--- ### Description
+--- A rounded rect with only some of the corners rounded.
+--- ### Parameters
+--- @param cairo any A cairo context.
+--- @param width number The shape width.
+--- @param height number The shape height.
+--- @param top_left boolean If the top left corner is rounded.
+--- @param top_right boolean If the top right corner is rounded.
+--- @param bottom_right boolean If the bottom right corner is rounded.
+--- @param bottom_left boolean If the bottom left corner is rounded.
+--- @param radius number The corner radius.
+--- ### Usage
+--- ```
+--- shape.partially_rounded_rect(cairo, 70, 70)
+--- shape.partially_rounded_rect(cairo, 70, 70, true)
+--- shape.partially_rounded_rect(cairo, 70, 70, true, true, false, true, 30)
+--- ```
+---
+--- [View documents](https://awesomewm.org/apidoc/theme_related_libraries/gears.shape.html#partially_rounded_rect)
+GShape.partially_rounded_rect = function(cairo, width, height, top_left, top_right, bottom_right, bottom_left, radius) end
+
+--- ### Description
+--- A rounded rectangle with a triangle at the top.
+--- ### Parameters
+--- @param cairo any A cairo context.
+--- @param width number The shape width.
+--- @param height number The shape height.
+--- @param corner_radius? number The corner radius. It is 5 by default.
+--- @param arrow_size? number The width and height of the arrow. It is 10 by default.
+--- @param arrow_position? number The position of the arrow. It is `width / 2 - arrow_size / 2` by default.
+--- ### Usage
+--- ```
+--- shape.infobubble(cairo, 70, 70)
+--- shape.transform(shape.infobubble):translate(0, 20):rotate_at(35, 35, math.pi)(cairo, 70, 20, 10, 5, 35 - 5)
+--- shape.transform(shape.infobubble):rotate_at(35, 35, 3 * math.pi / 2)(cairo, 70, 70, nil, nil, 40)
+--- ```
+---
+--- [View documents](https://awesomewm.org/apidoc/theme_related_libraries/gears.shape.html#infobubble)
+GShape.infobubble = function(cairo, width, height, corner_radius, arrow_size, arrow_position) end
+
+--- ### Description
+--- A rectangle terminated by an arrow.
+--- ### Parameters
+--- @param cairo any A cairo context.
+--- @param width number The shape width.
+--- @param height number The shape height.
+--- @param arrow_length? number The length of the arrow part. It is `height / 2` by default.
+--- ### Usage
+--- ```
+--- shape.rectangular_tag(cairo, 70, 70)
+--- shape.transform(shape.rectangular_tag):translate(0, 30)(cairo, 70, 10, 10)
+--- shape.transform(shape.rectangular_tag):translate(0, 30)(cairo, 70, 10, -10)
+--- ```
+---
+--- [View documents](https://awesomewm.org/apidoc/theme_related_libraries/gears.shape.html#rectangular_tag)
+GShape.rectangular_tag = function(cairo, width, height, arrow_length) end
+
+--- ### Description
+--- A simple arrow shape.
+--- ### Parameters
+--- @param cairo any A cairo context.
+--- @param width number The shape width.
+--- @param height number The shape height.
+--- @param head_width? number The width of the head of the arrow. It is `head_width` by default.
+--- @param shaft_width? number The width of the shaft of the arrow. It is `width / 2` by default.
+--- @param shaft_length? number The `head_length` of the shaft. It is `height / 2` by default.
+--- ### Usage
+--- ```
+--- shape.arrow(cairo, 70, 70)
+--- shape.arrow(cairo, 70, 70, 30, 10, 60)
+--- shape.transform(shape.arrow):rotate_at(35, 35, math.pi / 2)(cairo, 70, 70)
+--- ```
+---
+--- [View documents](https://awesomewm.org/apidoc/theme_related_libraries/gears.shape.html#arrow)
+GShape.arrow = function(cairo, width, height, head_width, shaft_width, shaft_length) end
+
+--- ### Description
+--- A squeezed hexagon filling the rectangle.
+--- ### Parameters
+--- @param cairo any A cairo context.
+--- @param width number The shape width.
+--- @param height number The shape height.
+--- ### Usage
+--- ```
+--- shape.hexagon(cairo, 70, 70)
+--- shape.transform(shape.hexagon):translate(0, 15)(cairo, 70, 20)
+--- shape.transform(shape.hexagon):rotate_at(35, 35, math.pi / 2)(cairo, 70, 40)
+--- ```
+---
+--- [View documents](https://awesomewm.org/apidoc/theme_related_libraries/gears.shape.html#hexagon)
+GShape.hexagon = function(cairo, width, height) end
+
+--- @type ShapeFn
+--- ### Description
+--- Double arrow popularized by the `vim-powerline` module.
+--- ### Parameters
+--- @param cairo any A cairo context.
+--- @param width number The shape width.
+--- @param height number The shape height.
+--- @param arrow_depth? number The width of the arrow part of the shape. It is `height / 2` by default.
+--- ### Usage
+--- ```
+--- shape.powerline(cairo, 70, 70)
+--- shape.transform(shape.powerline):translate(0, 25)(cairo, 70, 20)
+--- shape.transform(shape.powerline):translate(0, 25)(cairo, 70, 20, -20)
+--- ```
+---
+--- [View documents](https://awesomewm.org/apidoc/theme_related_libraries/gears.shape.html#powerline)
+GShape.powerline = function(cairo, width, height, arrow_depth) end
+
+--- ### Description
+--- An isosceles triangle.
+--- ### Parameters
+--- @param cairo any A cairo context.
+--- @param width number The shape width.
+--- @param height number The shape height.
+--- ### Usage
+--- ```
+--- shape.isosceles_triangle(cairo, 70, 70)
+--- shape.isosceles_triangle(cairo, 20, 70)
+--- shape.transform(shape.isosceles_triangle):rotate_at(35, 35, math.pi / 2)(cairo, 70, 70)
+--- ```
+---
+--- [View documents](https://awesomewm.org/apidoc/theme_related_libraries/gears.shape.html#isosceles_triangle)
+GShape.isosceles_triangle = function(cairo, width, height) end
+
+--- ### Description
+--- A cross (+) symbol.
+--- ### Parameters
+--- @param cairo any A cairo context.
+--- @param width number The shape width.
+--- @param height number The shape height.
+--- @param thickness? number The cross section thickness. It is `width / 3` by default.
+--- ### Usage
+--- ```
+--- shape.cross(cairo, 70, 70)
+--- shape.cross(cairo, 20, 70)
+--- shape.transform(shape.cross):scale(0.5, 1)(cairo, 70, 70)
+--- ```
+---
+--- [View documents](https://awesomewm.org/apidoc/theme_related_libraries/gears.shape.html#cross)
+GShape.cross = function(cairo, width, height, thickness) end
+
+--- ### Description
+--- A similar shape to the [`rounded_rect`](https://awesomewm.org/apidoc/theme_related_libraries/gears.shape.html#rounded_rect), but with sharp corners.
+--- ### Parameters
+--- @param cairo any A cairo context.
+--- @param width number The shape width.
+--- @param height number The shape height.
+--- @param corner_radius number Undocumented!
+--- ### Usage
+--- ```
+--- shape.circle(cairo, 70, 70)
+--- shape.circle(cairo, 20, 70)
+--- shape.transform(shape.circle):scale(0.5, 1)(cairo, 70, 70)
+--- ```
+---
+--- [View documents](https://awesomewm.org/apidoc/theme_related_libraries/gears.shape.html#octogon)
+GShape.octogon = function(cairo, width, height, corner_radius) end
+
+--- ### Description
+--- A circle shape.
+--- ### Parameters
+--- @param cairo any A cairo context.
+--- @param width number The shape width.
+--- @param height number The shape height.
+--- @param radius? number The radius.
+--- ### Usage
+--- ```
+--- shape.circle(cairo, 70, 70)
+--- shape.circle(cairo, 20, 70)
+--- shape.transform(shape.circle):scale(0.5, 1)(cairo, 70, 70)
+--- ```
+---
+--- [View documents](https://awesomewm.org/apidoc/theme_related_libraries/gears.shape.html#circle)
+GShape.circle = function(cairo, width, height, radius) end
+
+--- ### Description
+--- A simple rectangle.
+--- ### Parameters
+--- @param cairo any A cairo context.
+--- @param width number The shape width.
+--- @param height number The shape height.
+--- ### Usage
+--- ```
+--- shape.rectangle(cr, 70, 70)
+--- shape.rectangle(cr, 20, 70)
+--- shape.transform(shape.rectangle):scale(0.5, 1)(cr, 70, 70)
+--- ```
+---
+--- [View documents](https://awesomewm.org/apidoc/theme_related_libraries/gears.shape.html#rectangle)
+GShape.rectangle = function(cairo, width, height) end
+
+--- ### Description
+--- A diagonal parallelogram with the bottom left corner at `x = 0` and top right at `x = width`.
+--- ### Parameters
+--- @param cairo any A cairo context.
+---@param width number The shape width.
+---@param height number The shape height.
+---@param base_width? number The parallelogram base width. It is `width / 3` by default.
+--- ### Usage
+--- ```
+--- shape.parallelogram(cairo, 70, 70)
+--- shape.parallelogram(cairo, 70, 20)
+--- shape.transform(shape.parallelogram):scale(0.5, 1)(cairo, 70, 70)
+--- ```
+---
+--- [View documents](https://awesomewm.org/apidoc/theme_related_libraries/gears.shape.html#parallelogram)
+GShape.parallelogram = function(cairo, width, height, base_width) end
+
+--- ### Description
+--- A losange
+--- ### Parameters
+--- @param cairo any A cairo context.
+--- @param width number The shape width.
+--- @param height number The shape height.
+--- ### Usage
+--- ```
+--- shape.losange(cairo, 70, 70)
+--- shape.losange(cairo, 20, 70)
+--- shape.transform(shape.losange):scale(0.5, 1)(cairo, 70, 70)
+--- ```
+---
+--- [View documents](https://awesomewm.org/apidoc/theme_related_libraries/gears.shape.html#losange)
+GShape.losange = function(cairo, width, height) end
+
+--- ### Description
+--- A pie.
+---
+--- The pie center is the center of the area.
+--- ### Parameters
+--- @param cairo any A cairo context.
+---@param width number The shape width.
+---@param height number The shape height.
+---@param start_angle? number The start angle (in radians). It is 0 by default.
+---@param end_angle? number The end angle (in radians). It is `math.pi / 2` by default.
+---@param radius number? Undocumented!
+--- ### Usage
+--- ```
+--- shape.pie(cairo, 70, 70)
+--- shape.pie(cairo, 70, 70, 1.0471975511966, 4.1887902047864)
+--- shape.pie(cairo, 70, 70, 0, 2 * math.pi, 10)
+--- ```
+---
+--- [View documents](https://awesomewm.org/apidoc/theme_related_libraries/gears.shape.html#pie)
+GShape.pie = function(cairo, width, height, start_angle, end_angle, radius) end
+
+--- ### Description
+--- A rounded arc.
+--- ### Parameters
+--- @param cairo any A cairo context.
+--- @param width number The shape width.
+--- @param height number The shape height.
+--- @param thickness? number The arc thichness.
+--- @param start_angle? number The start angle (in radians). It is 0 by default.
+--- @param end_angle? number The end angle (in radians). It is `math.pi / 2` by default.
+--- @param start_rounded? boolean If the arc start rounded. It is false by default.
+--- @param end_rounded? boolean If the arc end rounded. It is false by default.
+--- ### Usage
+--- ```
+--- shape.arc(cairo, 70, 70, 10)
+--- shape.arc(cairo, 70, 70, 10, nil, nil, true, true)
+--- shape.arc(cairo, 70, 70, nil, 0, 2 * math.pi)
+--- ```
+---
+--- [View documents](https://awesomewm.org/apidoc/theme_related_libraries/gears.shape.html#arc)
+GShape.arc = function(cairo, width, height, thickness, start_angle, end_angle, start_rounded, end_rounded) end
+
+--- ### Description
+--- A partial rounded bar. How much of the rounded bar is visible depends on the given percentage value.
+---
+--- Note that this shape is not closed and thus filling it doesn't make much sense.
+--- ### Parameters
+--- @param cairo any A cairo context.
+--- @param width number The shape width.
+--- @param height number The shape height.
+--- @param percent number The progressbar percent.
+--- @param hide_left? boolean Do not draw the left side of the shape.
+--- ### Usage
+--- ```
+--- shape.radial_progress(cairo, 70, 20, 0.3)
+--- shape.radial_progress(cairo, 70, 20, 0.6)
+--- shape.radial_progress(cairo, 70, 20, 0.9)
+--- ```
+---
+--- [View documents](https://awesomewm.org/apidoc/theme_related_libraries/gears.shape.html#radial_progress)
+GShape.radial_progress = function(cairo, width, height, percent, hide_left) end
+
+--- ### Description
+--- Adjust the shape using a transformation object.
+--- Apply various transformations to the shape.
+--- ### Parameters
+--- @param shape ShapeFn A shape function.
+--- ### Returns
+--- @return function handle A transformation handle, also act as a shape function
+--- ### Usage
+--- ```
+--- gears.shape.transform(gears.shape.rounded_bar):rotate(math.pi / 2):translate(10, 10)
+--- ```
+---
+--- [View documents](https://awesomewm.org/apidoc/theme_related_libraries/gears.shape.html#transform)
+GShape.transform = function(shape) end
+
+return GShape

lua/gears/sort/init.lua

@@ -0,0 +1,66 @@
+--- ### Description
+--- Extra sorting algorithms.
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.sort.html)
+local GSort = {}
+
+--- ### Description
+--- A topological sorting class.
+---
+--- The object returned by this function allows to create simple dependency graphs.
+--- It can be used for decision making or ordering of complex sequences.
+--- ### Returns
+--- @return GSortTopological result A topological sorting class.
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.sort.html#topological)
+GSort.topological = function() end
+
+--- @class GSortTopological
+local Topological = {}
+
+--- ### Description
+--- Ensure that `node` appears after all `dependencies`.
+--- ### Parameters
+--- @param node any The node that edges are added to.
+--- @param dependencies table List of nodes that have to appear before `node`.
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.sort.html#append)
+function Topological:append(node, dependencies) end
+
+--- ### Description
+--- Ensure that `node` appears before all `subordinates`.
+--- ### Parameters
+--- @param node any The node that edges are added to.
+--- @param surbodinates table List of nodes that have to appear after `node`.
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.sort.html#prepend)
+function Topological:prepend(node, surbodinates) end
+
+--- ### Description
+--- Create a copy of this topological sort.
+--- This is useful to backup it before adding elements that can potentially have circular dependencies and thus render the original useless.
+--- ### Returns
+--- @return GSortTopological result Undocumented!
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.sort.html#clone)
+function Topological:clone() end
+
+--- ### Description
+--- Remove a node from the topological map.
+--- ### Parameters
+--- @param node any The node.
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.sort.html#remove)
+function Topological:remove(node) end
+
+--- ### Description
+--- Try to sort the nodes.
+--- ### Returns
+--- @return table result A sorted list of nodes.
+--- @return nil result Undocumented!
+--- @return any result A node around which a loop exists
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.sort.html#sort)
+function Topological:sort() end
+
+return GSort

lua/gears/string/init.lua

@@ -0,0 +1,100 @@
+--- ### Description
+--- String module for gears.
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.string.html)
+local GString = {}
+
+--- ### Description
+--- Escape a string from XML char. Useful to set raw text in textbox.
+--- ### Parameters
+--- @param text string Text to escape.
+--- ### Returns
+--- @return string result Escaped text.
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.string.html#xml_escape)
+GString.xml_escape = function(text) end
+
+--- ### Description
+--- Unescape a string from entities.
+--- ### Parameters
+--- @param text string Text to unescape.
+--- ### Returns
+--- @return string result Unescaped text.
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.string.html#xml_unescape)
+GString.xml_unescape = function(text) end
+
+--- ### Description
+--- Count number of lines in a string.
+--- ### Parameters
+--- @param text string  Input string.
+--- ### Returns
+--- @return integer result Number of lines.
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.string.html#linecount)
+GString.linecount = function(text) end
+
+--- ### Description
+--- Split a string into multiple lines.
+--- ### Parameters
+--- @param text string String to wrap.
+--- @param width? integer Maximum length of each line. It is 72 by default.
+--- @param indent? integer Number of spaces added before each wrapped line. It is 0 by default.
+--- ### Returns
+--- @return string result The string with lines wrapped to width.
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.string.html#linewrap)
+GString.linewrap = function(text, width, indent) end
+
+--- ### Description
+--- Escape all special pattern-matching characters so that lua interprets them literally instead of as a character class.
+--- ### Parameters
+--- @param str string String to generate pattern for.
+--- ### Returns
+--- @return string result String with escaped characters.
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.string.html#quote_pattern)
+GString.quote_pattern = function(str) end
+
+--- ### Description
+--- Generate a pattern matching expression that ignores case.
+--- ### Parameters
+--- @param query string Original pattern matching expression.
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.string.html#query_to_pattern)
+GString.query_to_pattern = function(query) end
+
+--- ### Description
+--- Split separates a string containing a delimiter into the list of substrings between that delimiter.
+--- ### Parameters
+--- @param str string String to be splitted.
+--- @param delimiter string  Character where the string will be splitted.
+--- ### Returns
+--- @return string[] result List of the substrings.
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.string.html#split)
+GString.split = function(str, delimiter) end
+
+--- ### Description
+--- Check if a string starts with another string.
+--- ### Parameters
+--- @param str string String to search.
+--- @param sub string String to check for.
+--- ### Returns
+--- @return boolean result `true` if string starts with specified string.
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.string.html#startswith)
+GString.startswith = function(str, sub) end
+
+--- ### Description
+--- Check if a string ends with another string.
+--- ### Parameters
+--- @param str string String to search.
+--- @param sub string String to check for.
+--- ### Returns
+--- @return boolean result `true` if string ends with specified string.
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.string.html#endswith)
+GString.endswith = function(str, sub) end
+
+return GString

lua/gears/table/init.lua

@@ -0,0 +1,233 @@
+--- ### Description
+--- Table module for gears.
+--- ### Examples
+--- Using [`cycle_value`](https://awesomewm.org/apidoc/utility_libraries/gears.table.html#cycle_value), you can cycle through values in a table.
+--- When the end of the table is reached, [`cycle_value`](https://awesomewm.org/apidoc/utility_libraries/gears.table.html#cycle_value) loops around to the beginning.
+--- ```
+--- local res = { 'a', 'b', 'c', 'd', 'e' }
+--- for i = 1, #res do
+---   local k = res[i]
+---   local v = gears.table.cycle_value(res, k, 1)
+---   print(v)
+--- end
+--- ```
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.table.html)
+local GTable = {}
+
+--- ### Description
+--- Join all tables given as arguments.
+--- This will iterate over all tables and insert their entries into a new table.
+--- ### Parameters
+--- @param ... table Tables to join.
+--- ### Returns
+--- @return table result A new table containing all entries from the arguments.
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.table.html#join)
+GTable.join = function(...) end
+
+--- ### Description
+--- Override elements in the target table with values from the source table.
+---
+--- Note that this method doesn't copy entries found in `__index`. Nested tables are copied by reference and not recursed into.
+--- ### Parameters
+--- @param target table The target table. Values from `source` will be copied into this table.
+--- @param source table The source table. Its values will be copied into `target`.
+--- @param raw? boolean If true, values will be assigned with [`rawset`](https://www.lua.org/manual/5.3/manual.html#pdf-rawset). This will bypass metamethods on target. It is false by default.
+--- ### Returns
+--- @return table result The target table.
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.table.html#crush)
+GTable.crush = function(target, source, raw) end
+
+--- ### Description
+--- Pack all elements with an integer key into a new table.
+--- While both Lua and LuaJIT implement `__len` over sparse tables, the standard defines it as an implementation detail.
+---
+--- This function removes any entries with non-numeric keys.
+--- ### Parameters
+--- @param table table A potentially sparse table.
+--- ### Returns
+--- @return table A packed table with only numeric keys.
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.table.html#from_sparse)
+GTable.from_sparse = function(table) end
+
+--- ### Description
+--- Check if a table has an item and return its key.
+--- ### Parameters
+--- @generic V
+--- @param table V[] The table.
+--- @param item V The item to look for in values of the table.
+--- ### Returns
+--- @return string | number result The key of the item.
+--- @return nil result Returns null if nothing is found
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.table.html#hasitem)
+GTable.hasitem = function(table, item) end
+
+--- ### Description
+--- Get all matching table keys for a `matcher` function.
+--- ### Parameters
+--- @generic K, V
+--- @param table table<K, V> The table.
+--- @param matcher fun(key: K, value: V) A function taking the key and value as arguments and returning a boolean.
+--- @param ordered? boolean If true, only look for continuous numeric keys. It is false by default.
+--- @param max? number The maximum number of entries to find. It is null by default.
+--- ### Returns
+--- @return table<K, V> | nil result An ordered table with all the keys or `nil` if none were found.
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.table.html#find_keys)
+GTable.find_keys = function(table, matcher, ordered, max) end
+
+--- ### Description
+--- Find the first key that matches a function.
+--- ### Parameters
+--- @generic K, V
+--- @param table table<K, V> The table.
+--- @param matcher fun(key: K, value: V) A function taking the key and value as arguments and returning a boolean.
+--- @param ordered? boolean If true, only look for continuous numeric keys. It is false by default.
+--- ### Returns
+--- @return table<K, V> | nil result The table key or nil.
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.table.html#find_first_key)
+GTable.find_first_key = function(table, matcher, ordered) end
+
+--- ### Description
+--- Get a sorted table with all keys from a table.
+--- ### Parameters
+--- @param table table The table for which the keys to get.
+--- ### Returns
+--- @return table result A table with keys.
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.table.html#keys)
+GTable.keys = function(table) end
+
+--- ### Description
+--- Get the number of keys in a table, both integer and string indicies.
+---
+--- This is functionally equivalent, but faster than [`gears.table.keys`]().
+--- ### Parameters
+--- @param table table The table for which to count the keys.
+--- ### Returns
+--- @return number result The number of keys in the table.
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.table.html#count_keys)
+GTable.count_keys = function(table) end
+
+--- ### Description
+--- Filter a table's keys for certain content type.
+--- ### Parameters
+--- @param table table The table to retrieve the keys for.
+--- @param ... string The types to look for.
+--- ### Returns
+--- @return table result A filtered table.
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.table.html#keys_filter)
+GTable.keys_filter = function(table, ...) end
+
+--- ### Description
+--- Reverse a table.
+--- ### Parameters
+--- @param table table The table to reverse.
+--- ### Returns
+--- @return table result A reversed table.
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.table.html#reverse)
+GTable.reverse = function(table) end
+
+--- ### Description
+--- Clone a table.
+--- ### Parameters
+--- @param table table The table to clone.
+--- @param deep boolean If `true`, recurse into nested tables to create a deep clone. It is true by default.
+--- ### Returns
+--- @return table result A clone of `table`.
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.table.html#clone)
+GTable.clone = function(table, deep) end
+
+--- ### Description
+--- Get the next (or previous) value from a table and cycle if necessary.
+---
+--- If the table contains the same value multiple type (aka, is not a set), the `first_index` has to be specified.
+--- ### Parameters
+--- @generic K, V
+--- @param table table<K, V> The input table.
+--- @param value V The start value. Must be an element of the input table `table`.
+--- @param step_size? number The amount to increment the index by. When this is negative, the function will cycle through the table backwards. It is 1 by deafult.
+--- @param filter? fun(value: V) n optional filter function. It receives a value from the table as parameter and should return a boolean. If it returns `false`, the value is skipped and [`cycle_value`](https://awesomewm.org/apidoc/utility_libraries/gears.table.html#cycle_value) tries the next one. It is null by default.
+--- @param start_at? number Where to start the lookup from. It is 1 by default.
+--- ### Returns
+--- @return V | nil result The next eligible value. If no value matches, nil is returned.
+--- @return number | nil index If a value is found, this is its index within the input table.
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.table.html#cycle_value)
+GTable.cycle_value = function(table, value, step_size, filter, start_at) end
+
+--- ### Description
+--- Iterate over a table.
+---
+--- Returns an iterator to cycle through all elements of a table that match a given criteria, starting from the first element or the given index.
+--- ### Parameters
+--- @param table table The table to iterate.
+--- @param filter function A function that returns true to indicate a positive match.
+--- @param start? integer Index to start iterating from. It is 1 by default.
+--- ### Returns
+--- @return function result Undocumented!
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.table.html#iterate)
+GTable.iterate = function(table, filter, start) end
+
+--- ### Description
+--- Merge items from the source table into the target table.
+---
+--- Note that this only considers the array part of source (same semantics as [`ipairs`](https://www.lua.org/manual/5.3/manual.html#pdf-ipairs)).
+--- Nested tables are copied by reference and not recursed into.
+--- ### Parameters
+--- @param target table The target table. Values from `source` will be copied into this table.
+--- @param source table  The source table. Its values will be copied into `target`.
+--- ### Returns
+--- @return table result The target table.
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.table.html#merge)
+GTable.merge = function(target, source) end
+
+--- ### Description
+--- Update the `target` table with entries from the `new` table.
+---
+--- Compared to [`gears.table.merge`](https://awesomewm.org/apidoc/utility_libraries/gears.table.html#merge),
+--- this version is intended to work using both an `identifier` function and a `merger` function.
+--- This works only for indexed tables.
+---
+--- The main use case is when changing the table reference is not possible or when the `target` contains additional content that must be kept.
+---
+--- Note that calling this function involve a lot of looping and should not be done often.
+--- ### Parameters
+--- @param target table The table to modify.
+--- @param new table The table which contains the new content.
+--- @param identifier function  A function which take the table entry (either from the `target` or `new` table) and return an unique identifier. The identifier type isn't important as long as `==` works to compare them.
+--- @param merger? function A function takes the entry to modify as first parameter and the new entry as second. The function must return the merged value. If none is provided, there is no attempt to merge the content.
+--- ### Returns
+--- @return table output The target table.
+--- @return table added The new entries.
+--- @return table removed The removed entries.
+--- @return table updated The updated entries.
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.table.html#diff_merge)
+GTable.diff_merge = function(target, new, identifier, merger) end
+
+--- ### Description
+--- Map a function to a table.
+---
+--- The function is applied to each value in the table, returning a modified table.
+--- ### Parameters
+--- @param action function The function to be applied to each value in the table.
+--- @param table table The container table whose values will be operated on.
+--- ### Returns
+--- @return table result The resulting table
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.table.html#map)
+GTable.map = function(action, table) end
+
+return GTable

lua/gears/timer/__emmylua.lua

@@ -0,0 +1,39 @@
+--- ### Description
+--- This file contains the EmmyLua based annotations for `gears.timer`, you should not use `require` in this file.
+--- @module "gears.timer.__emmylua"
+
+--#region TimerDescriptor Definition
+
+--- ### Description
+--- These are the arguments that will be passed to `gears.timer`.
+--- @class TimerDescriptor
+--- @field timeout number Timeout in seconds.
+--- @field autostart? boolean Automatically start the timer. It is false by default.
+--- @field call_now? boolean Call the callback at timer creation. It is false by default.
+--- @field single_shot? boolean Run only once then stop. It is false by default.
+--- @field callback? function to connect to the `timeout` signal.
+
+--#endregion
+
+--#region Timer Properties
+
+--- ### Description
+--- The timer timeout value.
+--- ### Emit Signals
+--- ```
+--- -- When the timeout value changes.
+--- property::timeout(self: Timer, new_value: number)
+--- ```
+--- @alias TimerPropertyTimeout number
+
+--#endregion
+
+--#region Timer Signals
+
+--- @alias TimerSignal
+--- | "start" # Emitted when the timer is started.
+--- | "stop" # Emitted when the timer is stopped.
+--- | "timeout" # Emitted when [`timeout`](https://awesomewm.org/apidoc/core_components/gears.timer.html#timeout) seconds have elapsed.
+--- | "property::timeout" # When the [`timeout`](https://awesomewm.org/apidoc/core_components/gears.timer.html#timeout) value changes.
+
+--#endregion

lua/gears/timer/init.lua

@@ -0,0 +1,154 @@
+--- ### Description
+--- Timer objects and functions.
+--- ### Information
+--- - **Copyright**: 2014 Uli Schlachter
+--- - **Originally authored by**: Uli Schlachter
+---
+--- [See all contributors on GitHub](https://github.com/awesomeWM/awesome/graphs/contributors)
+---
+--- [View documents](https://awesomewm.org/apidoc/utility_libraries/gears.timer.html)
+--- @module "gears.timer"
+local GTiming = {
+  timer = {
+    --- ### Description
+    --- Create a simple timer for calling the `callback` function continuously.
+    ---
+    --- This is a small wrapper around [`gears.timer`](https://awesomewm.org/apidoc/core_components/gears.timer.html#), that creates a timer based on callback.
+    --- The timer will run continuously and call callback every [`timeout`](https://awesomewm.org/apidoc/core_components/gears.timer.html#timeout) seconds.
+    --- It is stopped when `callback` returns false,
+    --- when `callback` throws an error or when the `:stop()`
+    --- method is called on the return value.
+    --- ### Parameters
+    --- @param timeout number Timeout in seconds.
+    --- @param callback function Function to run.
+    --- ### Returns
+    --- @return Timer timer The new timer object.
+    ---
+    --- [View documents](https://awesomewm.org/apidoc/core_components/gears.timer.html#start_new)
+    start_new = function(timeout, callback) end,
+
+    --- ### Description
+    --- Create a simple timer for calling the `callback` function continuously.
+    ---
+    --- This function is almost identical to [`gears.timer.start_new`](https://awesomewm.org/apidoc/core_components/gears.timer.html#start_new).
+    --- The only difference is that this does not prevent the callback function from being garbage collected.
+    --- In addition to the conditions in [`gears.timer.start_new`](https://awesomewm.org/apidoc/core_components/gears.timer.html#start_new),
+    --- this timer will also stop if `callback` was garbage collected since the previous run.
+    --- ### Parameters
+    --- @param timeout number Timeout in seconds.
+    --- @param callback function Function to run.
+    --- ### Returns
+    --- @return Timer timer The new timer object.
+    ---
+    --- [View documents](https://awesomewm.org/apidoc/core_components/gears.timer.html#weak_start_new)
+    weak_start_new = function(timeout, callback) end,
+
+    --- ### Description
+    --- Run all pending delayed calls now.
+    --- This function should best not be used at all, because it means that less batching happens and the delayed calls run prematurely.
+    ---
+    --- [View documents](https://awesomewm.org/apidoc/core_components/gears.timer.html#run_delayed_calls_now)
+    run_delayed_calls_now = function() end,
+
+    --- ### Description
+    --- Call the given function at the end of the current GLib event loop iteration.
+    --- ### Parameters
+    --- @param callback function The function that should be called.
+    --- @param ... any Arguments to the callback function
+    ---
+    --- [View documents](https://awesomewm.org/apidoc/core_components/gears.timer.html#delayed_call)
+    delayed_call = function(callback, ...) end,
+  },
+}
+
+--- ### Description
+--- Create a new timer object.
+---
+--- `call_now` only takes effect when a `callback` is provided. `single_shot`, on the other hand, also stops signals connected to the [`timeout`](https://awesomewm.org/apidoc/core_components/gears.timer.html#timeout) signal.
+---
+--- Specifying a function `func` as `args.callback` is equivalent to calling `:connect_signal(func)` on the timer object.
+--- ### Parameters
+--- @param args TimerDescriptor The arguments.
+--- ### Returns
+--- @return Timer timer A new timer.
+---
+--- [View documents](https://awesomewm.org/apidoc/core_components/gears.timer.html#gears.timer)
+GTiming.timer = function(args) end
+
+--- @class Timer : Object
+--- @field started boolean The timer is started.
+--- @field timeout TimerPropertyTimeout The timer timeout value.
+local Timer = {}
+
+--- ### Description
+--- Connect to a signal.
+--- ### Parameters
+--- @param name TimerSignal The name of the signal.
+--- @param action function The callback to call when the signal is emitted.
+--- ### Inherits
+--- - [`Object`](https://awesomewm.org/apidoc/utility_libraries/gears.object.html#gears.object) from [`gears.object`](https://awesomewm.org/apidoc/utility_libraries/gears.object.html).
+---
+--- [View documents](https://awesomewm.org/apidoc/core_components/gears.timer.html#connect_signal)
+function Timer:connect_signal(name, action) end
+
+--- ### Description
+--- Connect to a signal weakly.
+--- ### Parameters
+--- @param name TimerSignal The name of the signal.
+--- @param action function The callback to call when the signal is emitted.
+--- ### Inherits
+--- - [`Object`](https://awesomewm.org/apidoc/utility_libraries/gears.object.html#gears.object) from [`gears.object`](https://awesomewm.org/apidoc/utility_libraries/gears.object.html).
+---
+--- [View documents](https://awesomewm.org/apidoc/core_components/gears.timer.html#weak_connect_signal)
+function Timer:weak_connect_signal(name, action) end
+
+--- ### Description
+--- Emit a signal.
+--- ### Parameters
+--- @param name TimerSignal The name of the signal.
+--- @param ... any 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()`](https://awesomewm.org/apidoc/core_components/gears.timer.html#emit_signal).
+--- ### Inherits
+--- - [`Object`](https://awesomewm.org/apidoc/utility_libraries/gears.object.html#gears.object) from [`gears.object`](https://awesomewm.org/apidoc/utility_libraries/gears.object.html).
+---
+--- [View documents](https://awesomewm.org/apidoc/core_components/gears.timer.html#emit_signal)
+function Timer:emit_signal(name, ...) end
+
+--- ### Description
+--- Start the timer.
+--- ### Emit Signals
+--- ```
+--- -- When the timer starts.
+--- start()
+--- ```
+---
+--- [View documents](https://awesomewm.org/apidoc/core_components/gears.timer.html#start)
+function Timer:start() end
+
+--- ### Description
+--- Stop the timer.
+---
+--- Does nothing if the timer isn't running.
+--- ### Emit Signals
+--- ```
+--- -- When the timer stops.
+--- stop()
+--- ```
+---
+--- [View documents](https://awesomewm.org/apidoc/core_components/gears.timer.html#stop)
+function Timer:stop() end
+
+--- ### Description
+--- Restart the timer.
+--- This is equivalent to stopping the timer if it is running and then starting it.
+--- ### Emit Signals
+--- ```
+--- -- When the timer starts.
+--- start()
+--- -- When the timer stops.
+--- stop()
+--- ```
+---
+--- [View documents](https://awesomewm.org/apidoc/core_components/gears.timer.html#again)
+function Timer:again() end
+
+return GTiming.timer