Add pattern matching documentation

Add separate doc/syntax/pattern_matching.rdoc, add
link to control_expressions.rdoc.

The documentation is "reverse-engineered" from Ruby 2.7
behavior and early preview presentations, and corrected
by pattern-matching feature author @k-tsj.

1 files changed, 15 insertions, 1 deletions

diff --git a/doc/syntax/control_expressions.rdoc b/doc/syntax/control_expressions.rdoc
index f7e6d54924..e91b03e72d 100644
--- a/doc/syntax/control_expressions.rdoc
+++ b/doc/syntax/control_expressions.rdoc
@@ -232,7 +232,7 @@ You may use +then+ after the +when+ condition.  This is most frequently used
 to place the body of the +when+ on a single line.
 
   case a
-  when 1, 2 then puts "a is one or two
+  when 1, 2 then puts "a is one or two"
   when 3    then puts "a is three"
   else           puts "I don't know what a is"
   end
@@ -255,6 +255,20 @@ Again, the +then+ and +else+ are optional.
 The result value of a +case+ expression is the last value executed in the
 expression.
 
+Since Ruby 2.7, +case+ expressions also provide a more powerful experimental
+pattern matching feature via the +in+ keyword:
+
+  case {a: 1, b: 2, c: 3}
+  in a: Integer => m
+    "matched: #{m}"
+  else
+    "not matched"
+  end
+  # => "matched: 1"
+
+The pattern matching syntax is described on
+{its own page}[rdoc-ref:syntax/pattern_matching.rdoc].
+
 == +while+ Loop
 
 The +while+ loop executes while a condition is true: