Module: gears.matcher

A module to build a set of properties based on a graph of rules.

Sources

This module holds the business logic used by awful.rules. It provides an object on which one can add sets of rules or, alternatively, functions. In this module, the sets of rules or custom functions are called sources.

The sources are used to build a property table. Once all sources are evaluated, the :apply() method will set the properties on the target object.

Sources can have dependencies between them and the property table can only be built if the sources graph can be resolved.

Rules

The rules sources themselves are composed, as the name imply, of a set of rule. A rule is a table with a properties or callbacks attribute along with either rule or rule_any. It is also possible to add an except or except_any attribute to narrow the scope in which the rule is applied. Here’s a basic example of a minimal gears.matcher.

Usage example output:

local o = {
    foo    = 'bar',
    answer = 42,
}

-- This rule will match
local rule1 = {
    rule = {
        answer = 42,
    },
    properties = {
        name = 'baz',
    },
}

-- This rule will **not** match
local rule2 = {
    -- When the rule properties are strings, the Lua
    --pattern matching is used.
    rule = {
        foo = '[f]+',
    },
    properties = {
        name = 'foobar',
    },
}

local rules = {
    rule1,
    rule2,
}

local matcher = gears.matcher()

local function first_source(self, object, props, callbacks) --luacheck: no unused args
    -- In this callback, you can add new elements to the props and
    -- callbacks tables. It is not recommended the modify object in
    -- this callback.
    if object.answer == 42 then
        props.is_everything = true
    end
end

-- This will add a custom function to add properties to the rules.
matcher:add_matching_function('first', first_source, {}, {})

-- This will add the rules to this matcher.
matcher:add_matching_rules('second', rules, {'first'}, {})

-- Apply the properties to o
matcher:apply(o)

More examples are available in awful.rules.

See also:

Info:

Functions

gears.matcher.matches_rule (o, entry) Does a given rule entry match an object?
gears.matcher.matching_rules (o[, rules=nil]) Get list of matching rules for an object.
gears.matcher.matches_rules (o, rules) Check if an object matches a given set of rules.
gears.matcher.add_matching_rules (name, rules[, depends_on={}[, precede={}]]) Add a set of matching rules.
gears.matcher.add_matching_function (name, callback, depends_on, precede) Add a matching function.
gears.matcher.remove_matching_source (name) Remove a source.
gears.matcher.apply (o) Apply awful.rules.rules to an object.
gears.matcher () Create a new rule solver object.

Object methods

:emit_signal (name, ...) Emit a signal.
:connect_signal (name, func) Connect to a signal.
:weak_connect_signal (name, func) Connect to a signal weakly.

Rule components

properties A table which content will be used to set the target object properties.
callbacks A list of callback function to call after the properties have been apploed.
rule A table which content will be compared to the target object current properties.
rule_any Similar to rule, but each entry is a table with multiple values.
except The negative equivalent of rule.
except_any The negative equivalent of rule_any.


Functions

gears.matcher.matches_rule (o, entry)
Does a given rule entry match an object?

Parameters:

Returns:

    boolean If o matches entry.
gears.matcher.matching_rules (o[, rules=nil])
Get list of matching rules for an object.

If the rules argument is not provided, the rules added with add_matching_rules will be used.

Parameters:

  • o The object.
  • rules table The rules to check. List with “rule”, “rule_any”, “except” and “except_any” keys. (default nil)

Returns:

    table The list of matched rules.
gears.matcher.matches_rules (o, rules)
Check if an object matches a given set of rules.

Parameters:

Returns:

    boolean True if at least one rule is matched, false otherwise.
gears.matcher.add_matching_rules (name, rules[, depends_on={}[, precede={}]])
Add a set of matching rules.

Parameters:

  • name string The provider name. It must be unique.
  • rules table A set of rules (see how they work at the top of this page).
  • depends_on table A list of names of sources this source depends on (sources that must be executed before name). (default {})
  • precede table A list of names of sources this source has a priority over. (default {})

Returns:

    boolean Returns false if a dependency conflict was found.
gears.matcher.add_matching_function (name, callback, depends_on, precede)
Add a matching function.

Parameters:

  • name string The provider name. It must be unique.
  • callback The callback that is called to produce properties.
    • self gears.matcher The matcher object.
    • o The object.
    • properties table The current properties. The callback should add to and overwrite properties in this table.
    • callbacks table A table of all callbacks scheduled to be executed after the main properties are applied.
  • depends_on table A list of names of sources this source depends on (sources that must be executed before name). (default {})
  • precede table A list of names of sources this source has a priority over. (default {})

Returns:

    boolean Returns false if a dependency conflict was found.
gears.matcher.remove_matching_source (name)
Remove a source.

This removes sources added with add_matching_function or add_matching_rules.

Parameters:

  • name string The source name.

Returns:

    boolean If the source has been removed.
gears.matcher.apply (o)
Apply awful.rules.rules to an object.

Calling this will apply all properties provided by the matching functions and rules.

Parameters:

  • o The object.
gears.matcher ()
Create a new rule solver object.

Returns:

    A new rule solver object.

Object methods

:emit_signal (name, ...)
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)
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)
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.

Rule components

properties
A table which content will be used to set the target object properties.

foo

Type:

  • table

See also:

callbacks
A list of callback function to call after the properties have been apploed.

Type:

  • table

See also:

rule
A table which content will be compared to the target object current properties.

Type:

  • table

See also:

rule_any
Similar to rule, but each entry is a table with multiple values.

Type:

  • table

See also:

except
The negative equivalent of rule.

Type:

  • table

See also:

except_any
The negative equivalent of rule_any.

Type:

  • table

See also:

generated by LDoc 1.4.6 Last updated 2030-01-01 00:00:00