Mailing-List: contact notifications-help@freemarker.incubator.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@freemarker.incubator.apache.org
Content-Type: text/plain; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
From: ddekany@apache.org
To: notifications@freemarker.incubator.apache.org
Date: Mon, 13 Mar 2017 10:43:17 -0000
Message-Id: <64aed908ef5a4717b02391d4dc4723f5@git.apache.org>
Subject: [01/25] incubator-freemarker git commit: Manual: Document ?groups in
 more detail
archived-at: Mon, 13 Mar 2017 10:43:23 -0000

Repository: incubator-freemarker
Updated Branches:
  refs/heads/2.3 617ad6fc0 -> 0254eca3f


Manual: Document ?groups in more detail


Project: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/commit/779e74a8
Tree: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/tree/779e74a8
Diff: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/diff/779e74a8

Branch: refs/heads/2.3
Commit: 779e74a844364820a4fefb5531218469ccd6e44b
Parents: 83eac15
Author: ddekany <ddekany@apache.org>
Authored: Fri Mar 3 11:33:55 2017 +0100
Committer: ddekany <ddekany@apache.org>
Committed: Fri Mar 3 11:33:55 2017 +0100

----------------------------------------------------------------------
 src/manual/en_US/book.xml | 49 +++++++++++++++++++++++++++++++++++++-----
 1 file changed, 44 insertions(+), 5 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/779e74a8/src/manual/en_US/book.xml
----------------------------------------------------------------------
diff --git a/src/manual/en_US/book.xml b/src/manual/en_US/book.xml
index c3e683a..48b754e 100644
--- a/src/manual/en_US/book.xml
+++ b/src/manual/en_US/book.xml
@@ -7,9 +7,9 @@
   to you under the Apache License, Version 2.0 (the
   "License"); you may not use this file except in compliance
   with the License.  You may obtain a copy of the License at
-
+  
     http://www.apache.org/licenses/LICENSE-2.0
-
+  
   Unless required by applicable law or agreed to in writing,
   software distributed under the License is distributed on an
   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
@@ -13848,9 +13848,48 @@ Matching sub-strings:
   - "aa/rx;" is "a" per "a/rx"
   - " ab/r;" is " " per "ab/r"</programlisting>
 
-          <para>Note above that <literal>groups</literal> has worked both with
-          substring matches and with the result of entire string
-          matching.</para>
+          <para>Notes regarding the behavior of the <literal>groups</literal>
+          built-in:</para>
+
+          <itemizedlist>
+            <listitem>
+              <para>It works both with substring matches and with the result
+              of entire string matching (as it was shown in the above
+              example)</para>
+            </listitem>
+
+            <listitem>
+              <para>The first item in the sequence that
+              <literal>groups</literal> returns is the whole substring matched
+              by the regular expression. Hence, the index of the first
+              explicit regular expression group (with other words, of the
+              first <literal>(<replaceable>...</replaceable>)</literal> in the
+              regular expression) is 1, and not 0. Also, because of this, the
+              size of the sequence is one more than the number of explicit
+              regular expression groups.</para>
+            </listitem>
+
+            <listitem>
+              <para>The size of the sequence returned by
+              <literal>groups</literal> only depends on the number of explicit
+              groups in the regular expression, and so it will be the same
+              (non-0) even if there was no match found for the regular
+              expression. Attempting to access an item of the sequence (as in
+              <literal>res?groups[1]</literal>) when there was match will
+              cause an error. Thus, before accessing the groups, you should
+              always check if there was any match (as in <literal>&lt;#if
+              res&gt;<replaceable>access the groups
+              here</replaceable>&lt;/#if&gt;</literal>).</para>
+            </listitem>
+
+            <listitem>
+              <para>When there's a match for the regular expression, but not
+              for a certain explicit group inside the regular expression, then
+              for that group the sequence will contain a 0 length string. So
+              accessing a group that matches nothing is safe, as far as the
+              containing regular expression has matched something.</para>
+            </listitem>
+          </itemizedlist>
 
           <para><literal>matches</literal> accepts an optional 2nd parameter,
           the <link linkend="ref_builtin_string_flags">flags</link>. Note that