l16: compelete match object section

Saeid Darvish · Saeid Darvish · commit 7b5cb6dca664 · 2021-02-22T21:41:18.000+03:30
diff --git a/lessons/l16.rst b/lessons/l16.rst
@@ -112,7 +112,7 @@
 
   این متد از شی ``Match``، گروه (های) تطبیق داده شده بر اساس الگو مورد نظر را برمی‌گرداند. این متد می‌تواند یک یا چند آرگومان عددی دریافت کند که معرف اندیس گروه مورد نظر می‌باشد. در حالت فراخوانی بدون آرگومان تمامی گروه‌های تطبیق داده شده به صورت یک مقدار رشته برگردانده می‌شود و در صورتی تنها یک مقدار به آن ارسال گردد، گروه تطبیق داده شده متناظر با آن اندیس (شمارش اندیس‌ها از یک است) در قالب یک شی رشته برگردانده می‌شود و در صورتی که بیش از یک اندیس به عنوان آرگومان ارسال گردد یک شی تاپل محتوی گروه‌های تطبیق داده شده برگردانده خواهد شد. چنانچه آرگومان ارسالی عددی منفی باشد یا اندیسی بالاتر از تعداد گروه‌های تطبیق داده شده باشد، یک استثنا ``IndexError`` رخ خواهد داد::
 
-    >>> match = re.search(r"(\w+) (\w+)", "Isaac Newton, physicist") 
+    >>> match = re.search("(\w+) (\w+)", "Isaac Newton, physicist") 
     >>> match.group()        # The entire match
     'Isaac Newton'
     >>> match.group(0)       # The entire match
@@ -181,7 +181,7 @@
 
       >>> import re
 
-      >>> match = re.search(r"(?P<first_name>\w+) (?P<last_name>\w+)", "Elvis Presley")
+      >>> match = re.search("(?P<first_name>\w+) (?P<last_name>\w+)", "Elvis Presley")
       >>> match.groupdict()
       {'first_name': 'Elvis', 'last_name': 'Presley'}
 
@@ -212,6 +212,49 @@
 
 
 
+  * ``Match.expand(template)`` [`اسناد پایتون <https://docs.python.org/3/library/re.html#re.Match.expand>`__]
+
+    این متد حاصل انطباق را در قالب ``template`` جایگذاری کرده و یک شی رشته جدید برمی‌گرداند. قالب در اینجا یک رشته است که در آن می‌توان به حاصل انطباق گروهبندی‌های موجود در الگو ارجاع داد به این صورت کرد که می‌توان گروه‌های بی‌نام موجود در الگو را با استفاده از ارجاع عددی به شماره اندیس آن‌ها به مانند ``1\``، ``2\`` و گروه‌های بانام را با استفاده از نام گروه به مانند ``<g<name\`` یا ``<g<1\`` در قالب موجود جایگذاری کرد. Escape character‌های موجود در قالب به کاراکترهای مناسب خود در متن خروجی تبدیل می‌شوند و از **نسخه 3.5 پایتون** گروه‌هایی که هیچ انطباقی نداشته‌اند با هیچی (empty string) جایگذاری می‌شوند::
+
+        >>> import re
+
+        >>> match = re.search('(\w+),(\w+),(\w+)', 'Jazz,Rock,Pop')
+        >>> match.groups()
+        ('Jazz', 'Rock', 'Pop')
+        
+        >>> match.expand('-->\1---->\2------>\3') # Wrong result!!!
+        '-->\x01---->\x02------>\x03'
+
+        >>> match.expand('-->\\1---->\\2------>\\3')
+        '-->Jazz---->Rock------>Pop'
+
+        >>> match.expand(r'-->\1---->\2------>\3')
+        '-->Jazz---->Rock------>Pop'
+
+
+    .. note::
+        در نمونه کد بالا، خروجی نخستین استفاده از متد ``expand`` متناسب با انتظار نیست، دلیل هم مربوط به وجود کاراکترهایی با ``\`` است (escape characters) که باعث بروز اخلال در تحلیل رشته قالب شده است. بهتر است همیشه در این مواقع از قوانین **raw string** پیروی نماییم: استفاده از ``\\`` به جای ``\`` (همانند ``n\\``) یا قرار دادن یک کاراکتر ``r`` یا ``R`` در ابتدای رشته (همانند ``'r'\n``). در این صورت کاراکترهایی همچون newline یا ``n\`` در رشته، معنای خود را از دست می‌دهند. (یادآوری از درس هفتم)
+
+
+    .. tip::
+        بلای Backslash [`اسناد پایتون <https://docs.python.org/3/howto/regex.html#the-backslash-plague>`__] 
+
+        همیشه در هنگام کار با RegEx (نه فقط در زبان پایتون!) مواظب escape characters یا backslash characters باشید.
+
+    ::
+
+           >>> match = re.search('(?P<num>\d+)', 'Top 100 songs')
+           >>> match.group(1)
+           '100'
+
+           >>> match.expand('--- \g<num> ---')
+           '--- 100 ---'
+           >>> match.expand('--- \g<1> ---')
+           '--- 100 ---'
+
+
+
+
   * ``Match.start([group])`` [`اسناد پایتون <https://docs.python.org/3/library/re.html#re.Match.start>`__]    ``Match.end([group])`` [`اسناد پایتون <https://docs.python.org/3/library/re.html#re.Match.end>`__]
 
   متن رشته خروجی (تطبیق یافته بر اساس الگو مورد نظر) را در نظر بگیرید، متد ``start`` اندیس شروع این متن از رشته ورودی و متد ``end``  اندیس نقطه پایان را برمی‌گرداند. این دو متد می‌توانند یک آرگومان اختیاری نیز دریافت کنند که معرف اندیس یک گروه مشخص در الگو می‌باشد، با ارسال این آرگومان نتایج بر اساس تکه متن تطبیق داده شده با آن گروه برگردانده خواهد شد::
@@ -229,7 +272,7 @@
 
   ::
 
-       >>> match = re.search(r"(\d+)\.(\d+)", "24.1632")
+       >>> match = re.search("(\d+)\.(\d+)", "24.1632")
 
        >>> match.start()
        0
@@ -252,7 +295,7 @@
 
   این متد یک شی تاپل دوتایی از خروجی دو متد ``start``  و ``end``  را بر می‌گرداند و همانند آنها نیز یک آرگومان اختیاری دارد - نمونه خروجی: ``(m.start(group), m.end(group))``::
 
-    >>> match = re.search(r"(\d+)\.(\d+)", "24.1632")
+    >>> match = re.search("(\d+)\.(\d+)", "24.1632")
     >>> match.span()
     (0, 7)
     >>> match.span(1)
@@ -282,7 +325,7 @@
 
   ::
 
-       >>> match = re.search(r"(\d+)\.(\d+)", "24.1632")
+       >>> match = re.search("(\d+)\.(\d+)", "24.1632")
 
        >>> match.re
        re.compile('(\\d+)\\.(\\d+)')
