Mercurial Hosting > luan
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 <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 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 <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") + --> x="hello hello world world" + + local r = String.regex[[(\w+)]] + local x = r.gsub("hello world", "$0 $0", 1) + --> x="hello hello world" + + local r = String.regex[[(\w+)\s*(\w+)]] + local x = r.gsub("hello world from Luan", "$2 $1") + --> x="world hello Luan from" + + local r = String.regex[[\$(.*?)\$]] + local x = r.gsub("4+5 = $return 4+5$", function(s) + return load(s)() + end) + --> 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) + --> 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 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>