Describe matching patterns (WIP)

reference/plugin/matching-pattern/index.md

@@ -39,7 +39,7 @@ This matches to messages like:
       }
     }
 
-Not matches to:
+Doesn't match to:
 
     {
       "type": "add.result",
@@ -53,7 +53,7 @@ Not matches to:
     pattern = [
                  ["type", :equal, "table_create"],
                  :or,
-                 ["type", :equal, "column_create"]
+                 ["body.success", :equal, true]
               ]
 
 This matches to both:
@@ -68,16 +68,151 @@ and:
     {
       "type": "column_create",
       ...
+      "body": {
+        "success": true
+      }
     }
 
 
 ## Syntax {#syntax}
 
+There are two typeos of matching patterns: "basic pattern" and "nested pattern".
+
+### Basic pattern {#syntax-basic}
+
+#### Structure {#syntax-basic-structure}
+
+A basic pattern is described as an array including 2 or more elements, like following:
+
+    ["type", :equal, "search"]
+
+ * The first element is a *target path*. It means the location of the information to be checked, in the [message][].
+ * The second element is an *operator*. It means how the information specified by the target path should be checked.
+ * The third element is an *argument for the oeprator*. It is a primitive value (string, numeric, or boolean) or an array of values. Some operators require no argument.
+
+#### Target path {#syntax-basic-target-path}
+
+The target path is specified as a string.
+
+#### Avialable operators {#syntax-basic-operators}
+
+The operator is specified as a symbol.
+
+`:equal`
+: Returns `true`, if the target value is equal to the given value. Otherwise `false`.
+  For example,
+
+      ["type", :equal, "search"]
+
+  The pattern above matches to a message like following:
+
+      {
+        "type": "search",
+        ...
+      }
+
+`:in`
+: Returns `true`, if the target value is in the given array of values. Otherwise `false`.
+  For example,
+
+      ["type", :in, ["search", "select"]]
+
+  The pattern above matches to a message like following:
+
+      {
+        "type": "select",
+        ...
+      }
+
+  But it doesn't match to:
+
+      {
+        "type": "find",
+        ...
+      }
+
+`:include`
+: Returns `true` if the target array of values includes the given value. Otherwise `false`.
+  In other words, this is the opposite of the `:in` operator.
+  For example,
+
+      ["body.tags", :include, "News"]
+
+  The pattern above matches to a message like following:
+
+      {
+        "type": "my.notification",
+        "body": {
+          "tags": ["News", "Groonga", "Droonga", "Fluentd"]
+        }
+      }
+
+`:exist`
+: Returns `true` if the target exists. Otherwise `false`.
+  For example,
+
+      ["body.comments", :exist, "News"]
+
+  The pattern above matches to a message like following:
+
+      {
+        "type": "my.notification",
+        "body": {
+          "title": "Hello!",
+          "comments": []
+        }
+      }
+
+  But it doesn't match to:
+
+      {
+        "type": "my.notification",
+        "body": {
+          "title": "Hello!"
+        }
+      }
+
+`:start_with`
+: Returns `true` if the target string value starts with the given string. Otherwise `false`.
+  For example,
+
+      ["body.path", :start_with, "/archive/"]
+
+  The pattern above matches to a message like following:
+
+      {
+        "type": "my.notification",
+        "body": {
+          "path": "/archive/2014/02/28.html"
+        }
+      }
+
+
+### Nested pattern {#syntax-nested}
+
+#### Structure {#syntax-nested-structure}
+
+A nested pattern is described as an array including 3 elements, like following:
+
+    [
+      ["type", :equal, "table_create"],
+      :or,
+      ["type", :equal, "column_create"]
+    ]
+
+ * The first and the third elements are patterns, basic or nested. (In other words, you can nest patterns recursively.)
+ * The second element is a *logical operator*.
+
+#### Avialable operators {#syntax-nested-operators}
+
+`:and`
+: Returns `true` if both given patterns are evaluated as `true`. Otherwise `false`.
+
+`:or`
+: Returns `true` if one of given patterns (the first or the third element) is evaluated as `true`. Otherwise `false`.
+
+
+
 
- * `PATTERN` = [`TARGET_PATH`, `OPERATOR`, `ARGUMENTS*`]
- * `PATTERN` = [`PATTERN`, `LOGICAL_OPERATOR`, `PATTERN`]
- * `TARGET_PATH` = `"COMPONENT(.COMPONENT)*"`
- * `OPERATOR` = `:equal`, `:in`, `:include`, `:exist`, `:start_with`
- * `ARGUMENTS` = `OBJECT_DEFINED_IN_JSON*`
- * `LOGICAL_OPERATOR` = `:or`
+  [message]:../../message/