From dc867ef36d187eb072eb542be38cb4d953e0d0ba Mon Sep 17 00:00:00 2001
From: Emmanuel Lepage Vallee <elv1313@gmail.com>
Date: Sun, 17 Feb 2019 14:30:00 -0500
Subject: [PATCH] tests: Add an example for gears.matcher

---
 tests/examples/text/gears/matcher/default.lua | 80 +++++++++++++++++++
 .../text/gears/matcher/properties.lua         | 24 ++++++
 .../text/gears/matcher/properties.txt         |  0
 3 files changed, 104 insertions(+)
 create mode 100644 tests/examples/text/gears/matcher/default.lua
 create mode 100644 tests/examples/text/gears/matcher/properties.lua
 create mode 100644 tests/examples/text/gears/matcher/properties.txt

diff --git a/tests/examples/text/gears/matcher/default.lua b/tests/examples/text/gears/matcher/default.lua
new file mode 100644
index 000000000..ec60bc96d
--- /dev/null
+++ b/tests/examples/text/gears/matcher/default.lua
@@ -0,0 +1,80 @@
+--DOC_HIDE --DOC_NO_USAGE --DOC_GEN_OUTPUT
+local gears = {matcher = require("gears.matcher")} --DOC_HIDE
+
+    local o = {
+        foo    = "bar",
+        answer = 42,
+    }
+
+--DOC_NEWLINE
+
+    -- This rule will match
+    local rule1 = {
+        rule = {
+            answer = 42,
+        },
+        properties = {
+            name = "baz",
+        },
+    }
+
+--DOC_NEWLINE
+
+    -- 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",
+        },
+    }
+
+--DOC_NEWLINE
+
+    local rules = {
+        rule1,
+        rule2,
+    }
+
+--DOC_NEWLINE
+
+    local matcher = gears.matcher()
+
+--DOC_NEWLINE
+
+    local function first_source(self, object, props, callbacks) --luacheck: no unused args
+        assert(self:matching_rules(object, rules)[1] == rule1) --DOC_HIDE
+        assert(#self:matching_rules(object, rules) == 1) --DOC_HIDE
+        assert(self:matches_rule(object, rule1)) --DOC_HIDE
+        assert(not self:matches_rule(object, rule2)) --DOC_HIDE
+
+        -- 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
+
+--DOC_NEWLINE
+
+    -- This will add a custom function to add properties to the rules.
+    matcher:add_matching_function("first", first_source, {}, {})
+
+--DOC_NEWLINE
+
+    -- This will add the `rules` to this matcher.
+    matcher:add_matching_rules("second", rules, {"first"}, {})
+
+--DOC_NEWLINE
+
+    -- Apply the properties to `o`
+    matcher:apply(o)
+
+assert(o.is_everything) --DOC_HIDE
+assert(o.name == "baz") --DOC_HIDE
+matcher:remove_matching_source("first") --DOC_HIDE
+matcher:remove_matching_source("second") --DOC_HIDE
diff --git a/tests/examples/text/gears/matcher/properties.lua b/tests/examples/text/gears/matcher/properties.lua
new file mode 100644
index 000000000..f96745984
--- /dev/null
+++ b/tests/examples/text/gears/matcher/properties.lua
@@ -0,0 +1,24 @@
+--DOC_HIDE
+local gears = {matcher = require("gears.matcher")} --DOC_HIDE
+
+local o = { --DOC_HIDE
+    foo    = "bar", --DOC_HIDE
+    answer = 42, --DOC_HIDE
+} --DOC_HIDE
+
+local rules = {
+    {
+        rule = {
+            answer = 42,
+        },
+        properties = {
+            name = "baz",
+        },
+    }
+}
+
+--DOC_NEWLINE
+
+local matcher = gears.matcher()--DOC_HIDE
+matcher:add_matching_rules("second", rules, {"first"}, {}) --DOC_HIDE
+matcher:apply(o) --DOC_HIDE
diff --git a/tests/examples/text/gears/matcher/properties.txt b/tests/examples/text/gears/matcher/properties.txt
new file mode 100644
index 000000000..e69de29bb