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 <[email protected]> Authored: Fri Mar 3 11:33:55 2017 +0100 Committer: ddekany <[email protected]> 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><#if + res><replaceable>access the groups + here</replaceable></#if></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
