changeset 1668:ef75d9ad5ce9

manual work
author Franklin Schmidt <fschmidt@gmail.com>
date Mon, 09 May 2022 23:30:25 -0600
parents c55373c3a0ce
children fdeb1879fe02
files website/src/m.html.luan
diffstat 1 files changed, 693 insertions(+), 0 deletions(-) [+]
line wrap: on
line diff
--- a/website/src/m.html.luan	Sun May 08 22:50:48 2022 -0600
+++ b/website/src/m.html.luan	Mon May 09 23:30:25 2022 -0600
@@ -2368,6 +2368,699 @@
 					}
 				}
 			}
+			string_lib = {
+				title = "String Manipulation"
+				content = function()
+%>
+<p>
+Include this library by:
+</p>
+<pre>
+	local String = require "luan:String.luan"
+</pre>
+
+<p>
+This library provides generic functions for string manipulation,
+such as finding and extracting substrings, and pattern matching.
+When indexing a string in Luan, the first character is at position&nbsp;1
+(not at&nbsp;0, as in Java).
+Indices are allowed to be negative and are interpreted as indexing backwards,
+from the end of the string.
+Thus, the last character is at position -1, and so on.
+</p>
+<%
+				end
+				subs = {
+					["String.char"] = {
+						title = "<code>String.char (&middot;&middot;&middot;)</code>"
+						content = function()
+%>
+<p>
+Receives zero or more integers.
+Returns a string with length equal to the number of arguments,
+in which each character has the internal numerical code equal
+to its corresponding argument.
+</p>
+<%
+						end
+					}
+					["String.encode"] = {
+						title = "<code>String.encode (s)</code>"
+						content = function()
+%>
+<p>
+Encodes argument <code>s</code> into a string that can be placed in quotes so as to return the original value of the string.
+</p>
+<%
+						end
+					}
+					["String.find"] = {
+						title = "<code>String.find (s, pattern [, init [, plain]])</code>"
+						content = function()
+%>
+<p>
+Looks for the first match of
+<code>pattern</code> (see <a href="http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html">Pattern</a>) 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.
+A value of <b>true</b> as a fourth, optional argument <code>plain</code>
+turns off the pattern matching facilities,
+so the function does a plain "find substring" operation,
+with no characters in <code>pattern</code> being considered magic.
+Note that if <code>plain</code> is given, then <code>init</code> must be given as well.
+</p>
+
+<p>
+If the pattern has captures,
+then in a successful match
+the captured values are also returned,
+after the two indices.
+</p>
+<%
+						end
+					}
+					["String.format"] = {
+						title = "<code>String.format (formatstring, &middot;&middot;&middot;)</code>"
+						content = function()
+%>
+<p>
+Returns a formatted version of its variable number of arguments
+following the description given in its first argument (which must be a string).
+The format string follows the same rules as the Java function <a href="http://docs.oracle.com/javase/7/docs/api/java/lang/String.html#format(java.lang.String,%20java.lang.Object...)"><code>String.format</code></a> because Luan calls this internally.
+</p>
+
+<p>
+Note that Java's <code>String.format</code> is too stupid to convert between ints and floats, so you must provide the right kind of number.
+</p>
+<%
+						end
+					}
+					["String.gmatch"] = {
+						title = "<code>String.gmatch (s, pattern)</code>"
+						content = function()
+%>
+<p>
+Returns an iterator function that,
+each time it is called,
+returns the next captures from <code>pattern</code> (see <a href="http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html">Pattern</a>)
+over the string <code>s</code>.
+If <code>pattern</code> 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 s = "hello world from Lua"
+	for w in String.gmatch(s, [[\w+]]) 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 s = "from=world, to=Lua"
+	for k, v in String.gmatch(s, [[(\w+)=(\w+)]]) 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
+					}
+					["String.gsub"] = {
+						title = "<code>String.gsub (s, pattern, 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 <code>pattern</code> (see <a href="http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html">Pattern</a>) 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 pattern specifies no captures,
+then it behaves as if the whole pattern 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>
+     x = String.gsub("hello world", [[(\w+)]], "$1 $1")
+     --&gt; x="hello hello world world"
+     
+     x = String.gsub("hello world", [[\w+]], "$0 $0", 1)
+     --&gt; x="hello hello world"
+     
+     x = String.gsub("hello world from Luan", [[(\w+)\s*(\w+)]], "$2 $1")
+     --&gt; x="world hello Luan from"
+          
+     x = String.gsub("4+5 = $return 4+5$", [[\$(.*?)\$]], function (s)
+           return load(s)()
+         end)
+     --&gt; x="4+5 = 9"
+     
+     local t = {name="lua", version="5.3"}
+     x = String.gsub("$name-$version.tar.gz", [[\$(\w+)]], t)
+     --&gt; x="lua-5.3.tar.gz"
+</pre>
+<%
+						end
+					}
+					["String.lower"] = {
+						title = "<code>String.lower (s)</code>"
+						content = function()
+%>
+<p>
+Receives a string and returns a copy of this string with all
+uppercase letters changed to lowercase.
+All other characters are left unchanged.
+</p>
+<%
+						end
+					}
+					["String.match"] = {
+						title = "<code>String.match (s, pattern [, init])</code>"
+						content = function()
+%>
+<p>
+Looks for the first <em>match</em> of
+<code>pattern</code> (see <a href="http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html">Pattern</a>) in the string <code>s</code>.
+If it finds one, then <code>match</code> returns
+the captures from the pattern;
+otherwise it returns <b>nil</b>.
+If <code>pattern</code> 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
+					}
+					["String.matches"] = {
+						title = "<code>String.matches (s, pattern)</code>"
+						content = function()
+%>
+<p>
+Returns a boolean indicating whether the <code>pattern</code> can be found in string <code>s</code>.
+This function is equivalent to
+</p>
+<pre>
+     return String.match(s,pattern) ~= nil
+</pre>
+<%
+						end
+					}
+					["String.regex_quote"] = {
+						title = "<code>String.regex_quote (s)</code>"
+						content = function()
+%>
+<p>
+Returns a string which matches the literal string <code>s</code> in a regular expression.  This function is simply the Java method <a href="http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html#quote(java.lang.String)"><code>Pattern.quote</code></a>.
+</p>
+<%
+						end
+					}
+					["String.rep"] = {
+						title = "<code>String.rep (s, n [, sep])</code>"
+						content = function()
+%>
+<p>
+Returns a string that is the concatenation of <code>n</code> copies of
+the string <code>s</code> separated by the string <code>sep</code>.
+The default value for <code>sep</code> is the empty string
+(that is, no separator).
+Returns the empty string if <code>n</code> is not positive.
+</p>
+<%
+						end
+					}
+					["String.reverse"] = {
+						title = "<code>String.reverse (s)</code>"
+						content = function()
+%>
+<p>
+Returns a string that is the string <code>s</code> reversed.
+</p>
+<%
+						end
+					}
+					["String.split"] = {
+						title = "<code>String.split (s, pattern [, limit])</code>"
+						content = function()
+%>
+<p>
+Splits <code>s</code> using regex <code>pattern</code> and returns the results.  If <code>limit</code> is positive, then only returns at most that many results.  If <code>limit</code> is zero, then remove trailing empty results.
+</p>
+<%
+						end
+					}
+					["String.sub"] = {
+						title = "<code>String.sub (s, i [, j])</code>"
+						content = function()
+%>
+<p>
+Returns the substring of <code>s</code> that
+starts at <code>i</code>  and continues until <code>j</code>;
+<code>i</code> and <code>j</code> can be negative.
+If <code>j</code> is absent, then it is assumed to be equal to -1
+(which is the same as the string length).
+In particular,
+the call <code>string.sub(s,1,j)</code> returns a prefix of <code>s</code>
+with length <code>j</code>,
+and <code>string.sub(s, -i)</code> returns a suffix of <code>s</code>
+with length <code>i</code>.
+</p>
+
+<p>
+If, after the translation of negative indices,
+<code>i</code> is less than 1,
+it is corrected to 1.
+If <code>j</code> is greater than the string length,
+it is corrected to that length.
+If, after these corrections,
+<code>i</code> is greater than <code>j</code>,
+the function returns the empty string.
+</p>
+<%
+						end
+					}
+					["String.to_binary"] = {
+						title = "<code>String.to_binary (s)</code>"
+						content = function()
+%>
+<p>
+Converts a string to a binary by calling the Java method <a href="http://docs.oracle.com/javase/7/docs/api/java/lang/String.html#getBytes()"><code>String.getBytes</code></a>.
+</p>
+<%
+						end
+					}
+					["String.to_number"] = {
+						title = "<code>String.to_number (s [, base])</code>"
+						content = function()
+%>
+<p>
+When called with no <code>base</code>,
+<code>to_number</code> tries to convert its argument to a number.
+If the argument is
+a string convertible to a number,
+then <code>to_number</code> returns this number;
+otherwise, it returns <b>nil</b>.
+The conversion of strings can result in integers or floats.
+</p>
+
+<p>
+When called with <code>base</code>,
+then <code>s</code> must be a string to be interpreted as
+an integer numeral in that base.
+In bases above&nbsp;10, the letter '<code>A</code>' (in either upper or lower case)
+represents&nbsp;10, '<code>B</code>' represents&nbsp;11, and so forth,
+with '<code>Z</code>' representing 35.
+If the string <code>s</code> is not a valid numeral in the given base,
+the function returns <b>nil</b>.
+</p>
+<%
+						end
+					}
+					["String.trim"] = {
+						title = "<code>String.trim (s)</code>"
+						content = function()
+%>
+<p>
+Removes the leading and trailing whitespace by calling the Java method <a href="http://docs.oracle.com/javase/7/docs/api/java/lang/String.html#trim()"><code>String.trim</code></a>.
+</p>
+<%
+						end
+					}
+					["String.unicode"] = {
+						title = "<code>String.unicode (s [, i [, j]])</code>"
+						content = function()
+%>
+<p>
+Returns the internal numerical codes of the characters <code>s[i]</code>,
+<code>s[i+1]</code>, ..., <code>s[j]</code>.
+The default value for <code>i</code> is&nbsp;1;
+the default value for <code>j</code> is&nbsp;<code>i</code>.
+These indices are corrected
+following the same rules of function <a href="#String.sub"><code>String.sub</code></a>.
+</p>
+<%
+						end
+					}
+					["String.upper"] = {
+						title = "<code>String.upper (s)</code>"
+						content = function()
+%>
+<p>
+Receives a string and returns a copy of this string with all
+lowercase letters changed to uppercase.
+All other characters are left unchanged.
+The definition of what a lowercase letter is depends on the current locale.
+</p>
+<%
+						end
+					}
+				}
+			}
+			binary_lib = {
+				title = "Binary Manipulation"
+				content = function()
+%>
+<p>
+Include this library by:
+</p>
+<pre>
+	local Binary = require "luan:Binary.luan"
+</pre>
+<%
+				end
+				subs = {
+					["Binary.binary"] = {
+						title = "<code>Binary.binary (&middot;&middot;&middot;)</code>"
+						content = function()
+%>
+<p>
+Receives zero or more bytes (as integers).
+Returns a binary with length equal to the number of arguments,
+in which each byte has the internal numerical code equal
+to its corresponding argument.
+</p>
+<%
+						end
+					}
+					["Binary.byte"] = {
+						title = "<code>Binary.byte (b [, i [, j]])</code>"
+						content = function()
+%>
+<p>
+Returns the internal numerical codes of the bytes <code>b[i]</code>,
+<code>b[i+1]</code>, ..., <code>b[j]</code>.
+The default value for <code>i</code> is&nbsp;1;
+the default value for <code>j</code> is&nbsp;<code>i</code>.
+These indices are corrected
+following the same rules of function <a href="#String.sub"><code>String.sub</code></a>.
+</p>
+<%
+						end
+					}
+					["Binary.to_string"] = {
+						title = "<code>Binary.to_string (b [,charset])</code>"
+						content = function()
+%>
+<p>
+If <code>charset</code> is not nil then converts the binary <code>b</code> to a string using the Java <a href="http://docs.oracle.com/javase/7/docs/api/java/lang/String.html#String(byte[],%20java.lang.String)">String constructor</a>, else makes each byte a char.
+</p>
+<%
+						end
+					}
+				}
+			}
+			table_lib = {
+				title = "Table Manipulation"
+				content = function()
+%>
+<p>
+Include this library by:
+</p>
+<pre>
+	local Table = require "luan:Table.luan"
+</pre>
+
+<p>
+This library provides generic functions for table manipulation.
+It provides all its functions inside the table <code>Table</code>.
+</p>
+<%
+				end
+				subs = {
+					["Table.clear"] = {
+						title = "<code>Table.clear (tbl)</code>"
+						content = function()
+%>
+<p>
+Clears the table.
+</p>
+<%
+						end
+					}
+					["Table.concat"] = {
+						title = "<code>Table.concat (list [, sep [, i [, j]]])</code>"
+						content = function()
+%>
+<p>
+Given a list,
+returns the string <code>list[i]..sep..list[i+1] &middot;&middot;&middot; sep..list[j]</code>.
+The default value for <code>sep</code> is the empty string,
+the default for <code>i</code> is 1,
+and the default for <code>j</code> is <code>#list</code>.
+If <code>i</code> is greater than <code>j</code>, returns the empty string.
+</p>
+<%
+						end
+					}
+					["Table.copy"] = {
+						title = "<code>Table.copy (tbl [, i [, j]])</code>"
+						content = function()
+%>
+<p>
+If <code>i</code> is <code>nil</code>, returns a shallow copy of <code>tbl</code>.
+Otherwise returns a new table which is a list of the elements <code>tbl[i] &middot;&middot;&middot; tbl[j]</code>.
+By default, <code>j</code> is <code>#tbl</code>.
+</p>
+<%
+						end
+					}
+					["Table.insert"] = {
+						title = "<code>Table.insert (list, pos, value)</code>"
+						content = function()
+%>
+<p>
+Inserts element <code>value</code> at position <code>pos</code> in <code>list</code>,
+shifting up the elements
+<code>list[pos], list[pos+1], &middot;&middot;&middot;, list[#list]</code>.
+</p>
+<%
+						end
+					}
+					["Table.is_empty"] = {
+						title = "<code>Table.is_empty (tbl)</code>"
+						content = function()
+%>
+<%
+						end
+					}
+					["Table.pack"] = {
+						title = "<code>Table.pack (&middot;&middot;&middot;)</code>"
+						content = function()
+%>
+<p>
+Returns a new table with all parameters stored into keys 1, 2, etc.
+and with a field "<code>n</code>" with the total number of parameters.
+Note that the resulting table may not be a sequence.
+</p>
+<%
+						end
+					}
+					["Table.remove"] = {
+						title = "<code>Table.remove (list, pos)</code>"
+						content = function()
+%>
+<p>
+Removes from <code>list</code> the element at position <code>pos</code>,
+returning the value of the removed element.
+When <code>pos</code> is an integer between 1 and <code>#list</code>,
+it shifts down the elements
+<code>list[pos+1], list[pos+2], &middot;&middot;&middot;, list[#list]</code>
+and erases element <code>list[#list]</code>;
+The index <code>pos</code> can also be 0 when <code>#list</code> is 0,
+or <code>#list + 1</code>;
+in those cases, the function erases the element <code>list[pos]</code>.
+</p>
+<%
+						end
+					}
+					["Table.size"] = {
+						title = "<code>Table.size (tbl)</code>"
+						content = function()
+%>
+<%
+						end
+					}
+					["Table.sort"] = {
+						title = "<code>Table.sort (list [, comp])</code>"
+						content = function()
+%>
+<p>
+Sorts list elements in a given order, <em>in-place</em>,
+from <code>list[1]</code> to <code>list[#list]</code>.
+If <code>comp</code> is given,
+then it must be a function that receives two list elements
+and returns true when the first element must come
+before the second in the final order
+(so that <code>not comp(list[i+1],list[i])</code> will be true after the sort).
+If <code>comp</code> is not given,
+then the standard Lua operator <code>&lt;</code> is used instead.
+</p>
+
+<p>
+The sort algorithm is not stable;
+that is, elements considered equal by the given order
+may have their relative positions changed by the sort.
+</p>
+<%
+						end
+					}
+					["Table.unpack"] = {
+						title = "<code>Table.unpack (list [, i [, j]])</code>"
+						content = function()
+%>
+<p>
+Returns the elements from the given list.
+This function is equivalent to
+</p>
+<pre>
+     return list[i], list[i+1], &middot;&middot;&middot;, list[j]
+</pre>
+
+<p>
+By default, <code>i</code> is 1 and <code>j</code> is <code>list.n or #list</code>.
+</p>
+<%
+						end
+					}
+				}
+			}
+			number_lib = {
+				title = "Number Manipulation"
+				content = function()
+%>
+<p>
+Include this library by:
+</p>
+<pre>
+	local Number = require "luan:Number.luan"
+</pre>
+<%
+				end
+				subs = {
+					["Number.double"] = {
+						title = "<code>Number.double (x)</code>"
+						content = function()
+%>
+<p>
+Returns <code>x</code> as a double.
+</p>
+<%
+						end
+					}
+					["Number.float"] = {
+						title = "<code>Number.float (x)</code>"
+						content = function()
+%>
+<p>
+Returns <code>x</code> as a float.
+</p>
+<%
+						end
+					}
+					["Number.integer"] = {
+						title = "<code>Number.integer (x)</code>"
+						content = function()
+%>
+<p>
+If the value <code>x</code> is convertible to an integer,
+returns that integer.
+Otherwise throws an error.
+</p>
+<%
+						end
+					}
+					["Number.long"] = {
+						title = "<code>Number.long (x)</code>"
+						content = function()
+%>
+<p>
+If the value <code>x</code> is convertible to an long,
+returns that long.
+Otherwise throws an error.
+</p>
+<%
+						end
+					}
+					["Number.long_to_string"] = {
+						title = "<code>Number.long_to_string (i, radix)</code>"
+						content = function()
+%>
+<p>
+Converts long value <code>i</code> to a string by calling <code><a href="http://docs.oracle.com/javase/7/docs/api/java/lang/Long.html#toString(long,%20int)">Long.toString</a></code>.
+</p>
+<%
+						end
+					}
+					["Number.type"] = {
+						title = "<code>Number.type (x)</code>"
+						content = function()
+%>
+<p>
+Returns a string for the numeric type of <code>x</code>.  Possible return values include "<code>integer</code>", "<code>long</code>", "<code>double</code>", and "<code>float</code>".
+</p>
+<%
+						end
+					}
+				}
+			}
 		}
 	}
 }