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,
        everything = true,
    },
    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'}, {})

-- Some properties cannot be checked with the == operator (like those
-- with multiple possible types). In that case, it is possible to define
-- special comparator function.
matcher:add_property_matcher('everything', function(obj, value)
    return value and obj.answer == 42
end)

-- The same can be done for the property section.
matcher:add_property_setter('multiply_by', function(obj, value)
    obj.answer = (obj.answer or 1) * value
end)

-- It is possible to append rules to existing (or new) sources.
matcher:append_rule( 'second', {
    id   = 'rule_with_id',
    rule = {
        has_elite = true,
    },
    properties = {
        multiply_by = '1337',
    },
})

-- Or remove them.
matcher:remove_rule('second', 'rule_with_id')

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

This example shows the different matching sections:

local matcher = gears.matcher()

matcher:append_rule( 'my.source', {
    rule = {
        my_any_rule = true,
    },
    rule_every = {
        every1 = {1, 42},
        every2 = {2, 42},
        every3 = {3, 42},
    },
    except = {
        except1 = 1,
    },
    properties = {
        was_a_match = true,
    },
})

local candidate1 = {
    my_any_rule = true,
    every1      = 1,
    every2      = 2,
    every3      = 3,
    was_a_match = false,
}

local candidate2 = {
    every2      = 2,
    was_a_match = false,
}

local candidate3 = {
    my_any_rule = true,
    was_a_match = false,
    every1      = 1,
    every2      = 2,
    every3      = 3,
    except1     = 1,
}

matcher:apply(candidate1)
matcher:apply(candidate2)
matcher:apply(candidate3)

-- Only candidate1 fits all criteria.
assert(candidate1.was_a_match == true )
assert(candidate2.was_a_match == false)
assert(candidate3.was_a_match == false)

-- It is also possible to match number property by range.
matcher:append_rule( 'my.source', {
    rule_greater = {
        value = 50,
    },
    rule_lesser = {
        value = 100,
    },
    properties = {
        was_a_match = true,
    },
})

local candidate4 = { value = 40 , was_a_match = false }
local candidate5 = { value = 75 , was_a_match = false }
local candidate6 = { value = 101, was_a_match = false }

matcher:apply(candidate4)
matcher:apply(candidate5)
matcher:apply(candidate6)

-- Only candidate5 fits all criteria.
assert(candidate4.was_a_match == false)
assert(candidate5.was_a_match == true )
assert(candidate6.was_a_match == false)

More examples are available in awful.rules.

See also:

Info:

Constructors

gears.matcher () Create a new rule solver object.

Object methods

:matches_rule (o, entry) Does a given rule entry match an object?
:matching_rules (o[, rules=nil]) Get list of matching rules for an object.
:matches_rules (o, rules) Check if an object matches a given set of rules.
:add_property_matcher (name, f) Assign a function to match an object property against a value.
:add_property_setter (name, f) Add a special setter for a property.
:add_matching_rules (name, rules[, depends_on={}[, precede={}]]) Add a set of matching rules.
:add_matching_function (name, callback, depends_on, precede) Add a matching function.
:remove_matching_source (name) Remove a source.
:apply (o) Apply awful.rules.rules to an object.
:append_rule (source, rule) Add a new rule to the default set.
:append_rules (source, rules) Add a new rules to the default set.
:remove_rule (source, rule) Remove a new rule from the default set.
:emit_signal (name, ...) Emit a signal.
:connect_signal (name, func) Connect to a signal.
:weak_connect_signal (name, func) Connect to a signal weakly.

Signals

rule::appended A rule has been added to a set of matching rules.
rule::removed A rule has been removed to a set of matching rules.
matching_function::added A matching source function has been added.
matching_rules::added A matching source table has been added.
matching_source::removed A matching source function has been removed.

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.
rule_every Matches when one of every \“category\” of components match.
id An identifier for this rule.


Constructors

gears.matcher ()
Create a new rule solver object.

Returns:

    A new rule solver object.

Object methods

:matches_rule (o, entry)
Does a given rule entry match an object?

Parameters:

Returns:

    boolean If o matches entry.
: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. If no rules are provided, all rules registered with a source will be matched. (default nil)
: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.
:add_property_matcher (name, f)
Assign a function to match an object property against a value.

The default matcher uses the == operator for all types. It also uses the :match() method for string and allows pattern matching. If the value is a function, then that function is called with the object and the current properties to be applied. If the function returns true, the match is accepted.

Custom property matcher are useful when objects are compared. This avoids having to implement custom metatable for everything.

The f function receives 3 arguments:

  • The object to match against (anything)
  • The value to compare
  • The property/field name.

It should return true if it matches and false otherwise.

Parameters:

  • name string The property name.
  • f function The matching function.

Usage:

    -- Manually match the screen in various ways.
    matcher:add_property_matcher("screen", function(c, value)
       return c.screen == value
           or screen[c.screen] == value
           or c.screen.outputs[value] ~= nil
           or value == "any"
           or (value == "primary" and c.screen == screen.primary)
    end)
:add_property_setter (name, f)
Add a special setter for a property.

This is useful to add more properties to object which only make sense within the context of a rule.

Parameters:

  • name string The property name.
  • f function The setter function.
: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.
: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.
: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.
: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.
:append_rule (source, rule)
Add a new rule to the default set.

Parameters:

  • source string The source name.
  • rule table A valid rule.
:append_rules (source, rules)
Add a new rules to the default set.

Parameters:

  • source string The source name.
  • rules table A table with rules.
:remove_rule (source, rule)
Remove a new rule from the default set.

Parameters:

Returns:

    boolean If the rule was removed.
: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.

Signals

rule::appended
A rule has been added to a set of matching rules.

Arguments:

  • rule table The rule.
  • source table The matching rules source name.
  • content table The matching rules source content.

See also:

rule::removed
A rule has been removed to a set of matching rules.

Arguments:

  • rule table The rule.
  • source table The matching rules source name.
  • content table The matching rules source content.

See also:

matching_function::added
A matching source function has been added.

Arguments:

  • callback function The callback.

See also:

matching_rules::added
A matching source table has been added.

Arguments:

  • callback function The callback.

See also:

matching_source::removed
A matching source function has been removed.

See also:

Rule components

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

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:

rule_every
Matches when one of every \“category\” of components match.

Type:

  • table

See also:

id
An identifier for this rule.

It can be anything. It will be compared with the == operator. Strings are highly recommended.

Setting an id is useful to be able to remove the rule by using its id instead of a table reference. Modules can also listen to rule::appended and modify or disable a rule.

Type:

  • table |string|number|function
generated by LDoc 1.4.6 Last updated 2030-01-01 00:00:00