* parse.y (arg tMATCH arg): call reg_named_capture_assign_gen if regexp

  literal is used.
  (reg_named_capture_assign_gen): assign the result of named capture
  into local variables.
  [ruby-dev:32588]

* re.c: document the assignment by named captures.


git-svn-id: http://svn.ruby-lang.org/repos/ruby/trunk@14297 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

1 files changed, 31 insertions, 0 deletions

diff --git a/re.c b/re.c
index a8774237a..55037856e 100644
--- a/re.c
+++ b/re.c
@@ -2164,6 +2164,37 @@ reg_match_pos(VALUE re, VALUE *strp, long pos)
  *
  *     /at/ =~ "input data"   #=> 7
  *     /ax/ =~ "input data"   #=> nil
+ *
+ *  If <code>=~</code> is used with a regexp literal with named captures,
+ *  captured strings (or nil) is assigned to local variables named by
+ *  the capture names.
+ *
+ *     /(?<lhs>\w+)\s*=\s*(?<rhs>\w+)/ =~ "  x = y  "
+ *     p lhs    #=> "x"
+ *     p rhs    #=> "y"
+ *
+ *  If it is not matched, nil is assigned for the variables.
+ *
+ *     /(?<lhs>\w+)\s*=\s*(?<rhs>\w+)/ =~ "  x = "   
+ *     p lhs    #=> nil
+ *     p rhs    #=> nil
+ *
+ *  This assignment is implemented in the Ruby parser.
+ *  So a regexp literal is required for the assignment. 
+ *  The assignment is not occur if the regexp is not a literal.
+ *
+ *     re = /(?<lhs>\w+)\s*=\s*(?<rhs>\w+)/
+ *     re =~ "  x = "
+ *     p lhs    # undefined local variable
+ *     p rhs    # undefined local variable
+ *
+ *  A regexp interpolation, <code>#{}</code>, also disables
+ *  the assignment.
+ *
+ *     rhs_pat = /(?<rhs>\w+)/
+ *     /(?<lhs>\w+)\s*=\s*#{rhs_pat}/ =~ "x = y"
+ *     p lhs    # undefined local variable
+ *
  */
 
 VALUE