cwc

• Index

Contents

• Constructors
• Object methods
• Signals

Libraries

• cuteful.client
• cuteful.enum
• cuteful.tag
• gears.matcher
• gears.surface

Core components

• cwc
• cwc.client
• cwc.container
• cwc.kbd
• cwc.plugin
• cwc.pointer
• cwc.screen

Plugins

• cwc.cwcle

Utility libraries

• gears.debug
• gears.filesystem
• gears.geometry
• gears.math
• gears.object
• gears.protected_call
• gears.sort
• gears.string
• gears.table

Theme related libraries

• gears.color

Classes

• gears.cache
• gears.matrix

Documentation

• Getting Started
• Custom Layout
• C Plugin

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 ruled.client. 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.

Constructors

gears.matcher ()

Create a new rule solver object.

Object methods

:matches_rule (o, entry) -> boolean	Does a given rule entry match an object?
:matching_rules (o, rules) -> table	Get list of matching rules for an object.
:matches_rules (o, rules) -> boolean	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) -> boolean	Add a set of matching rules.
:add_matching_function (name, callback, depends_on, precede) -> boolean	Add a matching function.
:remove_matching_source (name) -> boolean	Remove a source.
:apply (o)	Apply ruled.client.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) -> boolean	Remove a new rule from the default set.

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.

Constructors

🔗 gears.matcher ()

Create a new rule solver object.

Returns:

A new rule solver object.

Object methods

🔗 :matches_rule (o, entry) -> boolean

Does a given rule entry match an object?

Parameters:

Name		Type(s)	Description
o			The object.
entry		table	Rule entry (with keys rule, rule_any, except and/or except_any).

Returns:

boolean If o matches entry.

🔗 :matching_rules (o, rules) -> table

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:

Name		Type(s)	Description	Default value
o			The object.	Not applicable
rules	Optional	table	The rules to check. List with "rule", "ruleany", "except" and "exceptany" keys. If no rules are provided, all rules registered with a source will be matched.	nil

Returns:

table The matching rules.

🔗 :matches_rules (o, rules) -> boolean

Check if an object matches a given set of rules.

Parameters:

Name		Type(s)	Description
o			The object.
rules		table	The rules to check. List of tables with rule, rule_any, except and except_any keys.

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		Type(s)	Description
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		Type(s)	Description
name		string	The property name.
f		function	The setter function.

🔗 :add_matching_rules (name, rules, depends_on, precede) -> boolean

Add a set of matching rules.

Parameters:

Name		Type(s)	Description	Default value
name		string	The provider name. It must be unique.	Not applicable
rules		table	A set of rules (see how they work at the top of this page).	Not applicable
depends_on	Optional	table	A list of names of sources this source depends on (sources that must be executed before name).	{}
precede	Optional	table	A list of names of sources this source has a priority over.	{}

Returns:

boolean Returns false if a dependency conflict was found.

🔗 :add_matching_function (name, callback, depends_on, precede) -> boolean

Add a matching function.

Parameters:

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

Returns:

boolean Returns false if a dependency conflict was found.

🔗 :remove_matching_source (name) -> boolean

Remove a source.

This removes sources added with add_matching_function or add_matching_rules.

Parameters:

Name		Type(s)	Description
name		string	The source name.

Returns:

boolean If the source has been removed.

🔗 :apply (o)

Apply ruled.client.rules to an object.

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

Parameters:

Name		Type(s)	Description
o			The object.

🔗 :append_rule (source, rule)

Add a new rule to the default set.

Parameters:

Name		Type(s)	Description
source		string	The source name.
rule		table	A valid rule.

🔗 :append_rules (source, rules)

Add a new rules to the default set.

Parameters:

Name		Type(s)	Description
source		string	The source name.
rules		table	A table with rules.

🔗 :remove_rule (source, rule) -> boolean

Remove a new rule from the default set.

Parameters:

Name		Type(s)	Description
source		string	The source name.
rule		string or table	An existing rule or its id.

Returns:

boolean If the rule was removed.

Signals

🔗 rule::appended

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

Arguments:

Name		Type(s)	Description
rule		table	The rule.
source		table	The matching rules source name.
content		table	The matching rules source content.

See also:

append_rule	Add a new rule to the default set.	object methods
append_rules	Add a new rules to the default set.	object methods

🔗 rule::removed

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

Arguments:

Name		Type(s)	Description
rule		table	The rule.
source		table	The matching rules source name.
content		table	The matching rules source content.

See also:

remove_rule	Remove a new rule from the default set.	object methods

🔗 matching_function::added

A matching source function has been added.

Arguments:

Name		Type(s)	Description
callback		function	The callback.

See also:

add_matching_function	Add a matching function.	object methods

🔗 matching_rules::added

A matching source table has been added.

Arguments:

Name		Type(s)	Description
callback		function	The callback.

See also:

add_matching_rules	Add a set of matching rules.	object methods

🔗 matching_source::removed

A matching source function has been removed.

See also:

remove_matching_source	Remove a source.	object methods