diff website/src/manual.html.luan @ 1716:b82767112d8e

add String.regex
author Franklin Schmidt <fschmidt@gmail.com>
date Sun, 24 Jul 2022 23:43:03 -0600
parents 19df8abc9805
children c637a2a1023d
line wrap: on
line diff
--- a/website/src/manual.html.luan	Sat Jul 23 21:53:04 2022 -0600
+++ b/website/src/manual.html.luan	Sun Jul 24 23:43:03 2022 -0600
@@ -2415,6 +2415,16 @@
 <%
 						end
 					}
+					["String.contains"] = {
+						title = "<code>String.contains (s, s2)</code>"
+						content = function()
+%>
+<p>
+Returns a boolean indicating whether the <code>s</code> contains <code>s2</code>.
+</p>
+<%
+						end
+					}
 					["String.encode"] = {
 						title = "<code>String.encode (s)</code>"
 						content = function()
@@ -2425,6 +2435,16 @@
 <%
 						end
 					}
+					["String.ends_with"] = {
+						title = "<code>String.ends_with (s, s2)</code>"
+						content = function()
+%>
+<p>
+Returns a boolean indicating whether the <code>s</code> ends with <code>s2</code>.
+</p>
+<%
+						end
+					}
 					["String.find"] = {
 						title = "<code>String.find (s, pattern [, init [, plain]])</code>"
 						content = function()
@@ -2634,6 +2654,16 @@
 <%
 						end
 					}
+					["String.regex"] = {
+						title = "<code>String.regex (s)</code>"
+						content = function()
+%>
+<p>
+Returns a <a href="#regex_table">regex</a> table for the pattern <code>s</code>.
+</p>
+<%
+						end
+					}
 					["String.regex_quote"] = {
 						title = "<code>String.regex_quote (s)</code>"
 						content = function()
@@ -2678,6 +2708,16 @@
 <%
 						end
 					}
+					["String.starts_with"] = {
+						title = "<code>String.starts_with (s, s2)</code>"
+						content = function()
+%>
+<p>
+Returns a boolean indicating whether the <code>s</code> starts with <code>s2</code>.
+</p>
+<%
+						end
+					}
 					["String.sub"] = {
 						title = "<code>String.sub (s, i [, j])</code>"
 						content = function()
@@ -2785,6 +2825,205 @@
 					}
 				}
 			}
+			regex_table = {
+				title = "Regular Expressions"
+				content = function()
+%>
+<p>
+Regular expressions are handled using a regex table generated by <a href="#String.regex">String.regex</a>.
+</p>
+
+<p>
+Pattern matching is based on the Java <a href="http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html">Pattern</a> class.
+</p>
+<%
+				end
+				subs = {
+					["regex.find"] = {
+						title = "<code>regex.find (s [, init])</code>"
+						content = function()
+%>
+<p>
+Looks for the first match of
+the regex in the string <code>s</code>.
+If it finds a match, then <code>find</code> returns the indices of&nbsp;<code>s</code>
+where this occurrence starts and ends;
+otherwise, it returns <b>nil</b>.
+A third, optional numerical argument <code>init</code> specifies
+where to start the search;
+its default value is&nbsp;1 and can be negative.
+</p>
+
+<p>
+If the regex has captures,
+then in a successful match
+the captured values are also returned,
+after the two indices.
+</p>
+<%
+						end
+					}
+					["regex.gmatch"] = {
+						title = "<code>regex.gmatch (s)</code>"
+						content = function()
+%>
+<p>
+Returns an iterator function that,
+each time it is called,
+returns the next captures from the regex
+over the string <code>s</code>.
+If the regex specifies no captures,
+then the whole match is produced in each call.
+</p>
+
+<p>
+As an example, the following loop
+will iterate over all the words from string <code>s</code>,
+printing one per line:
+</p>
+<pre>
+	local r = String.regex[[\w+]]
+	local s = "hello world from Lua"
+	for w in r.gmatch(s) do
+		print(w)
+	end
+</pre>
+
+<p>
+The next example collects all pairs <code>key=value</code> from the
+given string into a table:
+</p>
+<pre>
+	local t = {}
+	local r = String.regex[[(\w+)=(\w+)]]
+	local s = "from=world, to=Lua"
+	for k, v in r.gmatch(s) do
+		t[k] = v
+	end
+</pre>
+
+<p>
+For this function, a caret '<code>^</code>' at the start of a pattern does not
+work as an anchor, as this would prevent the iteration.
+</p>
+<%
+						end
+					}
+					["regex.gsub"] = {
+						title = "<code>regex.gsub (s, repl [, n])</code>"
+						content = function()
+%>
+<p>
+Returns a copy of <code>s</code>
+in which all (or the first <code>n</code>, if given)
+occurrences of the regex have been
+replaced by a replacement string specified by <code>repl</code>,
+which can be a string, a table, or a function.
+<code>gsub</code> also returns, as its second value,
+the total number of matches that occurred.
+The name <code>gsub</code> comes from <em>Global SUBstitution</em>.
+</p>
+
+<p>
+If <code>repl</code> is a string, then its value is used for replacement.
+The character&nbsp;<code>\</code> works as an escape character.
+Any sequence in <code>repl</code> of the form <code>$<em>d</em></code>,
+with <em>d</em> between 1 and 9,
+stands for the value of the <em>d</em>-th captured substring.
+The sequence <code>$0</code> stands for the whole match.
+</p>
+
+<p>
+If <code>repl</code> is a table, then the table is queried for every match,
+using the first capture as the key.
+</p>
+
+<p>
+If <code>repl</code> is a function, then this function is called every time a
+match occurs, with all captured substrings passed as arguments,
+in order.
+</p>
+
+<p>
+In any case,
+if the regex specifies no captures,
+then it behaves as if the whole regex was inside a capture.
+</p>
+
+<p>
+If the value returned by the table query or by the function call
+is not <b>nil</b>,
+then it is used as the replacement string;
+otherwise, if it is <b>nil</b>,
+then there is no replacement
+(that is, the original match is kept in the string).
+</p>
+
+<p>
+Here are some examples:
+</p>
+<pre>
+	local r = String.regex[[(\w+)]]
+	local x = r.gsub("hello world", "$1 $1")
+	--&gt; x="hello hello world world"
+
+	local r = String.regex[[(\w+)]]
+	local x = r.gsub("hello world", "$0 $0", 1)
+	--&gt; x="hello hello world"
+
+	local r = String.regex[[(\w+)\s*(\w+)]]
+	local x = r.gsub("hello world from Luan", "$2 $1")
+	--&gt; x="world hello Luan from"
+	     
+	local r = String.regex[[\$(.*?)\$]]
+	local x = r.gsub("4+5 = $return 4+5$", function(s)
+		return load(s)()
+	end)
+	--&gt; x="4+5 = 9"
+
+	local r = String.regex[[\$(\w+)]]
+	local t = {name="lua", version="5.3"}
+	local x = r.gsub("$name-$version.tar.gz", t)
+	--&gt; x="lua-5.3.tar.gz"
+</pre>
+<%
+						end
+					}
+					["regex.match"] = {
+						title = "<code>regex.match (s [, init])</code>"
+						content = function()
+%>
+<p>
+Looks for the first <em>match</em> of
+the regex in the string <code>s</code>.
+If it finds one, then <code>match</code> returns
+the captures from the regex;
+otherwise it returns <b>nil</b>.
+If the regex specifies no captures,
+then the whole match is returned.
+A third, optional numerical argument <code>init</code> specifies
+where to start the search;
+its default value is&nbsp;1 and can be negative.
+</p>
+<%
+						end
+					}
+					["regex.matches"] = {
+						title = "<code>regex.matches (s)</code>"
+						content = function()
+%>
+<p>
+Returns a boolean indicating whether the regex can be found in string <code>s</code>.
+This function is equivalent to
+</p>
+<pre>
+     return regex.match(s) ~= nil
+</pre>
+<%
+						end
+					}
+				}
+			}
 			binary_lib = {
 				title = "Binary Manipulation"
 				content = function()
@@ -3375,6 +3614,14 @@
 				display: inline-block;
 				width: 100px;
 			}
+			code {
+				font-size: 16px;
+				font-weight: bold;
+			}
+			div[toc] code {
+				font-size: inherit;
+				font-weight: inherit;
+			}
 		</style>
 	</head>
 	<body>