criteria: Add. Learn for_window command.

A criteria is a string in the form of `[class="regex.*" title="str"]`.
It is stored in a struct with a list of *tokens* which is a
attribute/value pair (stored as a `crit_token` struct). Most tokens will
also have a precompiled regex stored that will be used during criteria
matching.

for_window command: When a new view is created its metadata is tested
against all stored criteria, and if a match is found the associated
command list is executed.

Unfortunately some metadata is not available in sway at the moment
(specifically `instance`, `window_role` and `urgent`). Any criteria
string that tries to match an unsupported attribute will fail.

(Note that while the criteria code can be used to parse any criteria
string it is currently only used by the `for_window` command.)

1 files changed, 35 insertions, 0 deletions

diff --git a/sway.5.txt b/sway.5.txt
index 5e9dbb1e..700de8b2 100644
--- a/sway.5.txt
+++ b/sway.5.txt
@@ -68,6 +68,10 @@ Commands
 **fullscreen**::
         Toggles fullscreen status for the focused view.
 
+**for_window** <criteria> <command>::
+        Whenever a window that matches _criteria_ appears, run list of commands. See
+        **Criteria** section below.
+
 **gaps** edge_gaps <on|off|toggle>::
         Whether or not to add gaps between views and workspace edges if amount of
         inner gap is not zero. When _no_, no gap is added where the view is aligned to
@@ -175,3 +179,34 @@ Commands
 **workspace** <name> output <output>::
         Specifies that the workspace named _name_ should appear on the specified
         _output_.
+
+Criteria
+--------
+
+A criteria is a string in the form of e.g.:
+
+        [class="[Rr]egex.*" title="some title"]
+
+The string contains one or more (space separated) attribute/value pairs and they
+are used by some commands filter which views to execute actions on. All attributes
+must match for the criteria string to match.
+
+Currently supported attributes:
+
+**class**::
+        Compare value against the window class. Can be a regular expression. If value
+        is _focused_ then the window class must be the same as that of the currently
+        focused window.
+
+**id**::
+        Compare value against the app id. Can be a regular expression.
+
+**title**::
+        Compare against the window title. Can be a regular expression. If value is
+        _focused_ then the window title must be the same as that of the currently
+        focused window.
+
+**workspace**::
+        Compare against the workspace name for this view. Can be a regular expression.
+        If value is _focused_ then all the views on the currently focused workspace
+        matches.