<commit_before><?xml version="1.0"?>
<!--
   Licensed to the Apache Software Foundation (ASF) under one or more
   contributor license agreements.  See the NOTICE file distributed with
   this work for additional information regarding copyright ownership.
   The ASF licenses this file 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 KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
-->
<!DOCTYPE document
[
<!ENTITY sect-num '20'>
]>
<document prev="functions.html" next="hints_and_tips.html" id="$Id$">

<properties>
  <title>User's Manual: Regular Expressions</title>
</properties>

<body>

<section name="&sect-num;. Regular Expressions" anchor="regex">
<subsection name="&sect-num;.1 Overview" anchor="overview">
<p>
JMeter includes the pattern matching software <a href="http://jakarta.apache.org/oro/">Apache Jakarta ORO</a>
<br/>
There is some documentation for this on the Jakarta web-site, for example 
<a href="http://jakarta.apache.org/oro/api/org/apache/oro/text/regex/package-summary.html">
a summary of the pattern matching characters</a>
</p>
<p>
There is also documentation on an older incarnation of the product at 
<a href="http://www.savarese.org/oro/docs/OROMatcher/index.html">OROMatcher User's guide</a>, which might prove useful. 
</p>
<p>
The pattern matching is very similar to the pattern matching in Perl. 
A full installation of Perl will include plenty of documentation on regular expressions - look for perlrequick, perlretut, perlre, perlreref.
</p>
<p>
It is worth stressing the difference between "contains" and "matches", as used on the Response Assertion test element:
</p>
<ul>
<li>
"contains" means that the regular expression matched at least some part of the target, 
so 'alphabet' "contains" 'ph.b.' because the regular expression matches the substring 'phabe'.
</li>
<li>
"matches" means that the regular expression matched the whole target. 
So 'alphabet' is "matched" by 'al.*t'. 
</li>
</ul>
<p>In this case, it is equivalent to wrapping the regular expression in ^ and $, viz '^al.*t$'. 
</p>
<p>However, this is not always the case. 
For example, the regular expression 'alp|.lp.*' is "contained" in 'alphabet', but does not match 'alphabet'.
</p>
<p>Why? Because when the pattern matcher finds the sequence 'alp' in 'alphabet', it stops trying any other combinations - and 'alp' is not the same as 'alphabet', as it does not include 'habet'.
</p>
<p>
Note: unlike Perl, there is no need to (i.e. do not) enclose the regular expression in //. 
</p>
<p>
So how does one use the modifiers ismx etc if there is no trailing /? 
The solution is to use <i>extended regular expressions</i>, i.e. /abc/i becomes (?i)abc.
See also <a href="placement">Placement of modifiers</a> below.
</p>
</subsection>
<subsection name="&sect-num;.2 Examples" anchor="examples">
<h3>Extract single string</h3>
<p>
Suppose you want to match the following portion of a web-page: 
<br/>
<code>name="file" value="readme.txt"></code>
<br/>
and you want to extract <code>readme.txt</code>.
<br/>
A suitable regular expression would be:
<br/>
<code>name="file" value="(.+?)"></code>
<p>
The special characters above are:
</p>
<ul>
<li>( and ) - these enclose the portion of the match string to be returned</li>
<li>. - match any character</li>
<li>+ - one or more times</li> 
<li>? - don't be greedy, i.e. stop when first match succeeds</li>
</ul>
<p>
Note: without the ?, the .+ would continue past the first <code>"></code>
until it found the last possible <code>"></code> - which is probably not what was intended.
</p>
<p>
Note: although the above expression works, it's more efficient to use the following expression:
<br/>
<code>name="file" value="([^"]+)"></code><commit_msg>fixed typo in doc<commit_after><?xml version="1.0"?>
<!--
   Licensed to the Apache Software Foundation (ASF) under one or more
   contributor license agreements.  See the NOTICE file distributed with
   this work for additional information regarding copyright ownership.
   The ASF licenses this file 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 KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
-->
<!DOCTYPE document
[
<!ENTITY sect-num '20'>
]>
<document prev="functions.html" next="hints_and_tips.html" id="$Id$">

<properties>
  <title>User's Manual: Regular Expressions</title>
</properties>

<body>

<section name="&sect-num;. Regular Expressions" anchor="regex">
<subsection name="&sect-num;.1 Overview" anchor="overview">
<p>
JMeter includes the pattern matching software <a href="http://jakarta.apache.org/oro/">Apache Jakarta ORO</a>
<br/>
There is some documentation for this on the Jakarta web-site, for example 
<a href="http://jakarta.apache.org/oro/api/org/apache/oro/text/regex/package-summary.html">
a summary of the pattern matching characters</a>
</p>
<p>
There is also documentation on an older incarnation of the product at 
<a href="http://www.savarese.org/oro/docs/OROMatcher/index.html">OROMatcher User's guide</a>, which might prove useful. 
</p>
<p>
The pattern matching is very similar to the pattern matching in Perl. 
A full installation of Perl will include plenty of documentation on regular expressions - look for perlrequick, perlretut, perlre, perlreref.
</p>
<p>
It is worth stressing the difference between "contains" and "matches", as used on the Response Assertion test element:
</p>
<ul>
<li>
"contains" means that the regular expression matched at least some part of the target, 
so 'alphabet' "contains" 'ph.b.' because the regular expression matches the substring 'phabe'.
</li>
<li>
"matches" means that the regular expression matched the whole target. 
So 'alphabet' is "matched" by 'al.*t'. 
</li>
</ul>
<p>In this case, it is equivalent to wrapping the regular expression in ^ and $, viz '^al.*t$'. 
</p>
<p>However, this is not always the case. 
For example, the regular expression 'alp|.lp.*' is "contained" in 'alphabet', but does not match 'alphabet'.
</p>
<p>Why? Because when the pattern matcher finds the sequence 'alp' in 'alphabet', it stops trying any other combinations - and 'alp' is not the same as 'alphabet', as it does not include 'habet'.
</p>
<p>
Note: unlike Perl, there is no need to (i.e. do not) enclose the regular expression in //. 
</p>
<p>
So how does one use the modifiers ismx etc if there is no trailing /? 
The solution is to use <i>extended regular expressions</i>, i.e. /abc/i becomes (?i)abc.
See also <a href="#placement">Placement of modifiers</a> below.
</p>
</subsection>
<subsection name="&sect-num;.2 Examples" anchor="examples">
<h3>Extract single string</h3>
<p>
Suppose you want to match the following portion of a web-page: 
<br/>
<code>name="file" value="readme.txt"></code>
<br/>
and you want to extract <code>readme.txt</code>.
<br/>
A suitable regular expression would be:
<br/>
<code>name="file" value="(.+?)"></code>
<p>
The special characters above are:
</p>
<ul>
<li>( and ) - these enclose the portion of the match string to be returned</li>
<li>. - match any character</li>
<li>+ - one or more times</li> 
<li>? - don't be greedy, i.e. stop when first match succeeds</li>
</ul>
<p>
Note: without the ?, the .+ would continue past the first <code>"></code>
until it found the last possible <code>"></code> - which is probably not what was intended.
</p>
<p>
Note: although the above expression works, it's more efficient to use the following expression:
<br/>
<code>name="file" value="([^"]+)"></code>
{'fraction_non_alphanumeric': 0.12558699578567128, 'fraction_numerical': 0.0028898254063816978, 'mean_word_length': 4.379533678756476, 'pattern_counts': {'":': 0, '<': 171, '<?xml version=': 2, '>': 181, 'https://': 0, 'lorem ipsum': 0, 'www.': 4, 'xml': 2}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3507269', 'n_tokens_mistral': 2556, 'n_tokens_neox': 2503, 'n_words': 1094}