Mercurial Hosting > luan
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 1 +(not at 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 (···)</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 <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. +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, ···)</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 <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") + --> x="hello hello world world" + + x = String.gsub("hello world", [[\w+]], "$0 $0", 1) + --> x="hello hello world" + + x = String.gsub("hello world from Luan", [[(\w+)\s*(\w+)]], "$2 $1") + --> x="world hello Luan from" + + x = String.gsub("4+5 = $return 4+5$", [[\$(.*?)\$]], function (s) + return load(s)() + end) + --> x="4+5 = 9" + + local t = {name="lua", version="5.3"} + x = String.gsub("$name-$version.tar.gz", [[\$(\w+)]], t) + --> 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 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 10, the letter '<code>A</code>' (in either upper or lower case) +represents 10, '<code>B</code>' represents 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 1; +the default value for <code>j</code> is <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 (···)</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 1; +the default value for <code>j</code> is <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] ··· 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] ··· 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], ···, list[#list]</code>. +</p> +<% + end + } + ["Table.is_empty"] = { + title = "<code>Table.is_empty (tbl)</code>" + content = function() +%> +<% + end + } + ["Table.pack"] = { + title = "<code>Table.pack (···)</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], ···, 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><</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], ···, 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 + } + } + } } } }