Merge pull request #13 from saeiddrv/draft

add GitHub button

Author: Saeid Darvish

_templates/sphinx_minoo_theme/includes/header.html

@@ -99,3 +99,5 @@
 
 <script type="text/javascript" src="{{ pathto('_static/minoo.js', 1) }}"></script>
 <script type="text/javascript" src="{{ pathto('_static/modernizr.min.js', 1) }}"></script>
+
+ <script async defer src="https://buttons.github.io/buttons.js"></script>

_templates/sphinx_minoo_theme/includes/top.html

@@ -39,6 +39,10 @@
 		</a>
 	</div>
 
+<div class="top-links" style="direction: ltr;float: right;">
+    <a class="github-button" href="https://github.com/saeiddrv/PythonPersianTutorial" data-size="large" data-show-count="true" aria-label="Star saeiddrv/PythonPersianTutorial on GitHub">Star</a>
+<div>
+
 	<div class="top-links top-blue">
 
 	</div>

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,59 @@
 
 
 
+  * ``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') # Warning!!!
+        '-->\x01---->\x02------>\x03'
+
+        >>> match.expand('-->\\1---->\\2------>\\3')
+        '-->Jazz---->Rock------>Pop'
+
+        >>> match.expand(r'-->\1---->\2------>\3')
+        '-->Jazz---->Rock------>Pop'
+
+
+    ::
+
+          # \1, \2 and \3 are all valid escape characters
+
+          \1  # (U+0001 or 0x01) stands for the ascii start-of-heading character
+          \2  # (U+0002 or 0x02) stands for the ascii start-of-text character
+          \3  # (U+0003 or 0x03) stands for the ascii end-of-text character
+
+    .. note::
+        در نمونه کد بالا، خروجی نخستین استفاده از متد ``expand`` متناسب با انتظار نیست، دلیل هم مربوط به وجود کاراکترهایی با ``\`` است (escape characters) که باعث بروز اخلال در تحلیل رشته قالب شده است. بهتر است همیشه در این مواقع از قوانین **raw string** پیروی نماییم: استفاده از ``\\`` به جای ``\`` (همانند ``n\\``) یا قرار دادن یک کاراکتر ``r`` یا ``R`` در ابتدای رشته (همانند ``'r'\n``). در این صورت کاراکترهایی همچون newline یا ``n\`` در رشته، معنای خود را از دست می‌دهند. (یادآوری از درس هفتم)
+
+        در واقع مفسر پایتون پیش از قراردادن متن مورد نظر ما در قالب یک شی رشته (string) در حافظه (memory) آن را تحلیل و مقادیر متناسب با کاراکترهای ``\`` را در آن جایگذاری می‌کند که این کار ممکن است در هنگام استفاده ماژول ``re`` از آن شی رشته اخلال ایجاد کند. استفاده از **raw string**  باعث می‌شود مفسر پایتون متن مورد نظر را بدون تغییر در حافطه قرار دهد.
+
+
+    .. tip::
+        بلای Backslash [`اسناد پایتون <https://docs.python.org/3/howto/regex.html#the-backslash-plague>`__] 
+
+        همیشه در هنگام کار با RegEx (نه فقط در زبان پایتون!) مواظب escape characters یا همان backslash characters باشید. تا این لحظه برای جلوگیری از پیچیدگی در مثال‌های ارائه شده مبحث RegEx از قرار دادن **raw string** صرف نظر شده بود اما از آنجا که الگوهای RegEx پر از ``\`` است همواره می‌بایست به لزوم استفاده از **raw string** فکر کنیم.
+
+    ::
+
+           >>> match = re.search(r'(?P<num>\d+)', 'Top 100 songs')
+           >>> match.group(1)
+           '100'
+
+           >>> match.expand(r'--- \g<num> ---')
+           '--- 100 ---'
+           >>> match.expand(r'--- \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``  اندیس نقطه پایان را برمی‌گرداند. این دو متد می‌توانند یک آرگومان اختیاری نیز دریافت کنند که معرف اندیس یک گروه مشخص در الگو می‌باشد، با ارسال این آرگومان نتایج بر اساس تکه متن تطبیق داده شده با آن گروه برگردانده خواهد شد::
@@ -291,7 +344,120 @@
        '24.1632'
 
 
+تابع ``match``
+~~~~~~~~~~~~~~~~~~~~~~
+
+
+``match(pattern, string, flags=0)``
+
+تابع ``match`` از ابتدای string انطباق pattern را انجام می‌دهد، در صورت موفقیت یک شی ``Match`` و در غیر این صورت ``None`` برمی‌گرداند [`اسناد پایتون <https://docs.python.org/3/library/re.html#re.match>`__]::
+
+    >>> import re  # Python 3.x
+
+    >>> match = re.match(r'\d+', '123@USERNAME')
+    >>> print(match)
+    <re.Match object; span=(0, 3), match='123'>
+
+    >>> match = re.match(r'\d+', 'USERNAME@123')
+    >>> print(match)
+    None
+
+
+    >>> match = re.search(r'\d+', '123@USERNAME')
+    >>> print(match)
+    <re.Match object; span=(0, 3), match='123'>
+
+    >>> match = re.search(r'\d+', 'USERNAME@123')
+    >>> print(match)
+    <re.Match object; span=(9, 12), match='123'>
+
+
+.. tip::
+
+  تفاوت دو تابع ``match`` و ``search`` [`اسناد پایتون <https://docs.python.org/3/library/re.html#search-vs-match>`__]:
+
+  هنگام استفاده از تابع ``match``، از همان ابتدای متن مورد نظر می‌بایست با الگو تطابق صورت پذیرد (حتی در متن‌های چند سطری) ولی تابع ``search`` انجام انطباق را در هر جایی از متن دنبال می‌کند.
+
+  هنگام استفاده از نشانه ``re.MULTILINE`` در تابع ``search``، کاراکتر ``^`` در الگو از معنای **ابتدای متن** به معنای **ابتدای هر سطر** تغییر می‌کند ولی از نظر تابع ``match`` وجود کاراکتر ``^`` در الگو همواره به معنی ابتدای متن می‌باشد (نه هر سطر)::
+
+      >>> import re
+      >>> string = 'Perl\nPython\nRuby'  # 3 lines
+
+      >>> match = re.search('^Perl', string)
+      >>> print(match)
+      <re.Match object; span=(0, 4), match='Perl'>
+
+      >>> match = re.search('^Python', string)
+      >>> print(match)
+      None
+
+      >>> match = re.search('^Python', string, re.MULTILINE)
+      >>> print(match)
+      <re.Match object; span=(5, 11), match='Python'>
+
+
+      >>> match = re.match('^Perl', string)
+      >>> print(match)
+      <re.Match object; span=(0, 4), match='Perl'>
+
+      >>> match = re.match('^Python', string, re.MULTILINE)
+      >>> print(match)
+      None
+
+
+اجازه بدهید یادآوری کنیم که دو نمونه کد زیر عملکردی معادل یکدیگر دارند::
+
+
+    >>> pattern = re.compile('Py...n')
+    >>> match = pattern.match('Python is great')
+
+::
+
+    >>> match = re.match('Py...n', 'Python is great')
+
+
+تابع ``fullmatch``
+~~~~~~~~~~~~~~~~~~~~~~
+
+
+``fullmatch(pattern, string, flags=0)``
+
+این تابع (``fullmatch``) چنانچه تمام string با pattern انطباق داشته باشد یک شی ``Match`` و در غیر این صورت ``None`` برمی‌گرداند [`اسناد پایتون <https://docs.python.org/3/library/re.html#re.fullmatch>`__] - این تابع از **پایتون نسخه 3.4** به بعد در دسترس است::
+
+    >>> import re  # Python >= 3.4
+
+    >>> match = re.fullmatch(r'\d+', '123@USERNAME')
+    >>> print(match)
+    None
+
+    >>> match = re.fullmatch(r'\d+', '123')
+    >>> print(match)
+    <re.Match object; span=(0, 3), match='123'>
+
+**عملکرد نمونه کدهای زیر برابر هم هستند - به الگو و نام توابع توجه نمایید**::
+
+    >>> match = re.search(r'^\d+$', '123')
+    >>> print(match)
+    <re.Match object; span=(0, 3), match='123'>
+
+    >>> match = re.match(r'\d+$', '123')
+    >>> print(match)
+    <re.Match object; span=(0, 3), match='123'>
+
+    >>> match = re.fullmatch(r'\d+', '123')
+    >>> print(match)
+    <re.Match object; span=(0, 3), match='123'>
+
+
+همچنین باید یادآوری کنیم که دو نمونه کد زیر عملکردی معادل یکدیگر دارند::
+
+
+    >>> pattern = re.compile('Py...n')
+    >>> match = pattern.fullmatch('Python')
+
+::
 
+    >>> match = re.fullmatch('Py...n', 'Python')