From 41b0e1290df6e37e54b9b1469887a91be7745e36 Mon Sep 17 00:00:00 2001
From: rudolfkoenig <>
Date: Fri, 20 Jan 2023 11:41:39 +0000
Subject: [PATCH] commandref: add Regexp paragraph (Forum #131676)

git-svn-id: https://svn.fhem.de/fhem/trunk@27089 2b470e98-0d58-463d-a4d8-8e2adae1ed80
---
 fhem/FHEM/01_FHEMWEB.pm            | 11 ++++--
 fhem/docs/commandref_frame.html    | 52 +++++++++++++++++++++++++
 fhem/docs/commandref_frame_DE.html | 61 ++++++++++++++++++++++++++++++
 3 files changed, 120 insertions(+), 4 deletions(-)

diff --git a/fhem/FHEM/01_FHEMWEB.pm b/fhem/FHEM/01_FHEMWEB.pm
index 5a1c0f20c..2ffe162df 100644
--- a/fhem/FHEM/01_FHEMWEB.pm
+++ b/fhem/FHEM/01_FHEMWEB.pm
@@ -4057,7 +4057,7 @@ FW_log($$)
 
     <a id="FHEMWEB-attr-hiddengroupRegexp"></a>
     <li>hiddengroupRegexp<br>
-        One regexp for the same purpose as hiddengroup.
+        One <a href="#regexp">regexp</a> for the same purpose as hiddengroup.
         </li>
         <br>
 
@@ -4075,7 +4075,8 @@ FW_log($$)
 
     <a id="FHEMWEB-attr-hiddenroomRegexp"></a>
     <li>hiddenroomRegexp<br>
-        One regexp for the same purpose as hiddenroom. Example:
+        One <a href="#regexp">regexp</a> for the same purpose as hiddenroom.
+        Example:
         <ul>
           attr WEB hiddenroomRegexp .*config
         </ul>
@@ -4908,7 +4909,8 @@ FW_log($$)
 
     <a id="FHEMWEB-attr-hiddengroupRegexp"></a>
     <li>hiddengroupRegexp<br>
-        Ein regul&auml;rer Ausdruck, um Gruppen zu verstecken.
+        Ein <a href="#regexp">regul&auml;rer Ausdruck</a>, um Gruppen zu
+        verstecken.
         </li>
         <br>
 
@@ -4925,7 +4927,8 @@ FW_log($$)
 
     <a id="FHEMWEB-attr-hiddenroomRegexp"></a>
     <li>hiddenroomRegexp<br>
-        Ein regul&auml;rer Ausdruck, um R&auml;ume zu verstecken. Beispiel:
+        Ein <a href="#regexp">regul&auml;rer Ausdruck</a>, um R&auml;ume zu
+        verstecken. Beispiel:
         <ul>
           attr WEB hiddenroomRegexp .*config
         </ul>
diff --git a/fhem/docs/commandref_frame.html b/fhem/docs/commandref_frame.html
index 380a40ae6..51dd72e82 100644
--- a/fhem/docs/commandref_frame.html
+++ b/fhem/docs/commandref_frame.html
@@ -112,6 +112,7 @@
 
   <br>
   <a href="#perl">Perl specials</a><br>
+  <a href="#regexp">Regexp</a><br>
   <a href="#gnuplot-syntax">gnuplot file syntax</a><br>
 </ul>
 
@@ -2038,6 +2039,57 @@ The following local attributes are used by a wider range of devices:
   <br>
 <!-- perl end - diese Zeile nicht entfernen! -->
 
+<a name="regexp"></a>
+<h3>Regexp</h3>
+  FHEM makes heavy use of regexp, which is short for regular expressions.
+  Other shorthands are regex or re.<br>
+
+  With a regexp you can check if a text/string contains the substrings what you
+  are looking for, or extract parts of this string for later usage.<br>
+
+  Regexp is not to be confused with glob, which is used in the shell: .* is the
+  regexp equivalent of the glob *<br>
+
+  Some examples:<ul>
+  <table>
+    <tr><th>Regexp</th><th>Explanation</th></tr>
+    <tr><td>.</td>
+        <td>Matches one arbitrary character.</td></tr>
+    <tr><td>x</td>
+        <td>Matches a string containing x: x, xy, but not abc</td></tr>
+    <tr><td>^x</td>
+        <td>Matches a string starting with x: x, xy, but not yx</td></tr>
+    <tr><td>x$</td>
+        <td>Matches a string ending with x: x, yx, but not xy</td></tr>
+    <tr><td>^x?$</td>
+        <td>Matches zero or one x: "", x, but not xx</td></tr>
+    <tr><td>^x*$</td>
+        <td>Matches zero or more x: "", x, xxxx, but not xy or yx</td></tr>
+    <tr><td>^x+$</td>
+        <td>Matches one or more x: x, xxxx, but not ""</td></tr>
+    <tr><td>^(xy|yx)$</td>
+        <td>Matches xy or yx</td></tr>
+    <tr><td>*</td><td>Not a valid regexp! This is a glob</td></tr>
+  </table>
+  </ul>
+  There is a lot more to know about regexps. There is an extensive
+  documentation coming with your perl installation: try in the OS commandline
+  perldoc perlretut first, and perldoc perlre for details.<br>
+
+  If unsure, test your regexp in an online regexp tester, like
+    <a target="_blank" href="https://regex101.com">regex101.com</a>,
+    <a target="_blank" href="https://regexr.com">regexr.com</a> or
+    <a target="_blank" href="https://regextester.com">regextester.com</a>
+  .<br>
+
+  You can also test your regexp in the FHEM commandline:<br>
+  <ul>
+    { "StringToTest" =~ m/^Str/ }<br>
+    { "StringToTest" =~ m/^str$/ }<br>
+    { "StringToTest" =~ m/(To|From)/ }<br>
+  </ul>
+  <br>
+
 <a name="gnuplot-syntax"></a>
 <h3>gnuplot file syntax</h3>
 
diff --git a/fhem/docs/commandref_frame_DE.html b/fhem/docs/commandref_frame_DE.html
index 24c6b6135..61aaf3d97 100644
--- a/fhem/docs/commandref_frame_DE.html
+++ b/fhem/docs/commandref_frame_DE.html
@@ -2190,6 +2190,67 @@ Die folgenden lokalen Attribute werden von mehreren Ger&auml;ten verwendet:
   <br>
 <!-- perl end - diese Zeile nicht entfernen! -->
 
+<a name="regexp"></a>
+<h3>Regexp</h3>
+  FHEM verwendet an vielen Stellen Regexps, womit Regul&auml;re Ausdr&uuml;cke
+  gemeint sind. Weitere Bezeichner sind regex oder re.<br>
+
+  Mit einem Regexp kann man pr&uuml;fen, ob eine Zeichenkette eine Andere
+  enth&auml;lt, oder man kann Teile einer Zeichenkette extrahieren.<br>
+
+  Regexp ist nicht mit dem aus dem Shell bekannten Globbing zu verwechseln:
+  zBsp. ist .* die Regexp &auml;quivalente von *, was man in dem Dateisystem
+  verwendet.</br>
+
+  Einige Beispiele:<ul>
+  <table>
+    <tr><th>Regexp</th><th>Erkl&auml;rung</th></tr>
+    <tr><td>.</td>
+        <td>Trifft f&uuml;r ein beliebiges Zeichen/Buchstabe zu.</td></tr>
+    <tr><td>x</td>
+        <td>Trifft f&uuml;r eine Zeichenkette zu, die x enth&auml;lt: x, xy,
+        aber nicht abc</td></tr>
+    <tr><td>^x</td>
+        <td>Trifft f&uuml;r eine Zeichenkette zu, die mit x anf&auml;ngt: x,
+            xy, aber nicht yx</td></tr>
+    <tr><td>x$</td>
+        <td>Trifft f&uuml;r eine Zeichenkette zu, die mit x endet: x, yx, aber
+            nicht xy</td></tr>
+    <tr><td>^x?$</td>
+        <td>Trifft f&uuml;r eine Zeichenkette zu, die leer ist, oder nur ein x
+            enth&auml;lt</td></tr>
+    <tr><td>^x*$</td>
+        <td>Trifft f&uuml;r eine Zeichenkette zu, die leer ist oder nur x
+        enht&auml;lt: "", x, xxxx, aber nicht xy oder yx</td></tr>
+    <tr><td>^x+$</td>
+        <td>Trifft f&uuml;r eine Zeichenkette zu, die x mindestens einmal
+            enthaelt: x, xxxx, aber nicht ""</td></tr>
+    <tr><td>^(xy|yx)$</td>
+        <td>Trifft f&uuml;r xy or yx zu.</td></tr>
+    <tr><td>*</td><td>Das ist kein Regexp! Das ist ein Glob.</td></tr>
+  </table>
+  </ul>
+  Das ist nicht mal die Spitze des Eisbergs, wenn man mehr wissen will, kann
+  man z.Bsp. die in der perl Installation vorhandene Dokumentation verwenden:
+  die Shell Befehle "perldoc perlretut" oder "perldoc perlre" (in dieser
+  Reihenfolge) liefern Seitenweise mehr Info.<br>
+
+  Falls man unsicher ist, sollte man die Regexps testen, z.Bsp. in einen der
+  online Tester wie
+    <a target="_blank" href="https://regex101.com">regex101.com</a>,
+    <a target="_blank" href="https://regexr.com">regexr.com</a> or
+    <a target="_blank" href="https://regextester.com">regextester.com</a>
+  .<br>
+
+  Man kann ein Regexp auch offline in FHEM testen, z.Bsp. wenn man es in der
+  Kommandozeile so eingibt:<br>
+  <ul>
+    { "StringToTest" =~ m/^Str/ }<br>
+    { "StringToTest" =~ m/^str$/ }<br>
+    { "StringToTest" =~ m/(To|From)/ }<br>
+  </ul>
+  <br>
+
 <a name="gnuplot-syntax"></a>
 <h3>gnuplot file syntax</h3>