From patchwork Mon Apr  8 08:23:49 2019
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Subject: [5,of,8] match: add doctest examples in match()
From: Denis Laxalde <denis@laxalde.org>
X-Patchwork-Id: 39526
Message-Id: <c7e9ddf8b24e9768d331.1554711829@steppe.logilab.fr>
To: mercurial-devel@mercurial-scm.org
Date: Mon, 08 Apr 2019 10:23:49 +0200

# HG changeset patch
# User Denis Laxalde <denis@laxalde.org>
# Date 1554708890 -7200
#      Mon Apr 08 09:34:50 2019 +0200
# Node ID c7e9ddf8b24e9768d331872af1e61cd5d65c3668
# Parent  043ca8235e56dec170c7feee51c59d4150d94a2f
match: add doctest examples in match()

Make the docstring raw, as it now includes escape characters.

diff --git a/mercurial/match.py b/mercurial/match.py
--- a/mercurial/match.py
+++ b/mercurial/match.py
@@ -116,7 +116,7 @@ def _buildkindpatsmatcher(matchercls, ro
 def match(root, cwd, patterns=None, include=None, exclude=None, default='glob',
           auditor=None, ctx=None, listsubrepos=False, warn=None,
           badfn=None, icasefs=False):
-    """build an object to match a set of file patterns
+    r"""build an object to match a set of file patterns
 
     arguments:
     root - the canonical root of the tree you're matching against
@@ -148,6 +148,52 @@ def match(root, cwd, patterns=None, incl
     'subinclude:<path>' - a file of patterns to match against files under
                           the same directory
     '<something>' - a pattern of the specified default type
+
+    Usually a patternmatcher is returned:
+    >>> match('foo', '.', ['re:.*\.c$', 'path:foo/a', '*.py'])
+    <patternmatcher patterns='.*\\.c$|foo/a(?:/|$)|[^/]*\\.py$'>
+
+    Combining 'patterns' with 'include' (resp. 'exclude') gives an
+    intersectionmatcher (resp. a differencematcher):
+    >>> type(match('foo', '.', ['re:.*\.c$'], include=['path:lib']))
+    <class 'mercurial.match.intersectionmatcher'>
+    >>> type(match('foo', '.', ['re:.*\.c$'], exclude=['path:build']))
+    <class 'mercurial.match.differencematcher'>
+
+    Notice that, if 'patterns' is empty, an alwaysmatcher is returned:
+    >>> match('foo', '.', [])
+    <alwaysmatcher>
+
+    The 'default' argument determines which kind of pattern is assumed if a
+    pattern has no prefix:
+    >>> match('foo', '.', ['.*\.c$'], default='re')
+    <patternmatcher patterns='.*\\.c$'>
+    >>> match('foo', '.', ['main.py'], default='relpath')
+    <patternmatcher patterns='main\\.py(?:/|$)'>
+    >>> match('foo', '.', ['main.py'], default='re')
+    <patternmatcher patterns='main.py'>
+
+    The primary use of matchers is to check whether a value (usually a file
+    name) matches againset one of the patterns given at initialization. There
+    are two ways of doing this check.
+
+    >>> m = match('foo', '', ['re:.*\.c$', 'relpath:a'])
+
+    1. Calling the matcher with a file name returns True if any pattern
+    matches that file name:
+    >>> bool(m('a'))
+    True
+    >>> bool(m('main.c'))
+    True
+    >>> bool(m('test.py'))
+    False
+
+    2. Using the exact() method only returns True if the file name matches one
+    of the exact patterns (i.e. not re: or glob: patterns):
+    >>> m.exact('a')
+    True
+    >>> m.exact('main.c')
+    False
     """
     normalize = _donormalize
     if icasefs: