repo/luan: website/src/manual.html.luan comparison

comparison website/src/manual.html.luan @ 555:e25ba7a2e816

some String documentation and fixes

author	Franklin Schmidt <fschmidt@gmail.com>
date	Fri, 19 Jun 2015 04:29:06 -0600
parents	b1256e2d19a3
children	d02f43598ba3

comparison

equal deleted inserted replaced

-:18504c41b0be
+:e25ba7a2e816
 	<a href="#libs">Standard Libraries</a>
 	<ul>
 		<li><a href="#default_lib">Default Environment</a></li>
 		<li><a href="#luan_lib">Basic Functions</a></li>
 		<li><a href="#package_lib">Modules</a></li>
+		<li><a href="#string_lib">String Manipulation</a></li>
 	</ul>
 </div>
 <hr/>
-<h2>6.4 &ndash; <a name="6.4">String Manipulation</a></h2>
+<h3 <%=heading_options%> ><a name="string_lib">String Manipulation</a></h3>
+<p>
+Include this library by:
+<p><tt><pre>
+	local String = require "luan:String"
+</pre></tt></p>
 <p>
 This library provides generic functions for string manipulation,
 such as finding and extracting substrings, and pattern matching.
-When indexing a string in Lua, the first character is at position&nbsp;1
+When indexing a string in Luan, the first character is at position&nbsp;1
-(not at&nbsp;0, as in C).
+(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>
-The string library provides all its functions inside the table
-<a name="pdf-string"><code>string</code></a>.
-It also sets a metatable for strings
-where the <code>__index</code> field points to the <code>string</code> table.
-Therefore, you can use the string functions in object-oriented style.
-For instance, <code>string.byte(s,i)</code>
-can be written as <code>s:byte(i)</code>.
-<p>
-The string library assumes one-byte character encodings.
 <p>
 <hr><h3><a name="pdf-string.byte"><code>string.byte (s [, i [, j]])</code></a></h3>
 Returns the internal numerical codes of the characters <code>s[i]</code>,
 <p>
 Numerical codes are not necessarily portable across platforms.
+<h4 <%=heading_options%> ><a name="String.char"><tt>String.char (&middot;&middot;&middot;)</tt></a></h4>
-<p>
-<hr><h3><a name="pdf-string.char"><code>string.char (&middot;&middot;&middot;)</code></a></h3>
+<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>
+<h4 <%=heading_options%> ><a name="String.concat"><tt>String.concat (&middot;&middot;&middot;)</tt></a></h4>
-Numerical codes are not necessarily portable across platforms.
+<p>
+Concatenates the <a href="#Luan.to_string"><tt>to_string</tt></a> value of all arguments.
-<p>
-<hr><h3><a name="pdf-string.dump"><code>string.dump (function [, strip])</code></a></h3>
+<h4 <%=heading_options%> ><a name="String.encode"><tt>String.encode (s)</tt></a></h4>
+<p>
-<p>
+Encodes argument <tt>s</tt> into a string that can be placed in quotes so as to return the original value of the string.
-Returns a string containing a binary representation
-(a <em>binary chunk</em>)
-of the given function,
-so that a later <a href="#pdf-load"><code>load</code></a> on this string returns
-a copy of the function (but with new upvalues).
+<h4 <%=heading_options%> ><a name="String.find"><tt>String.find (s, pattern [, init [, plain]])</tt></a></h4>
-If <code>strip</code> is a true value,
-the binary representation is created without debug information
-about the function
-(local variable names, lines, etc.).
-<p>
-Functions with upvalues have only their number of upvalues saved.
-When (re)loaded,
-those upvalues receive fresh instances containing <b>nil</b>.
-(You can use the debug library to serialize
-and reload the upvalues of a function
-in a way adequate to your needs.)
-<p>
-<hr><h3><a name="pdf-string.find"><code>string.find (s, pattern [, init [, plain]])</code></a></h3>
 <p>
 Looks for the first match of
-<code>pattern</code> (see <a href="#6.4.1">&sect;6.4.1</a>) in the string <code>s</code>.
+<tt>pattern</tt> (see <a href="#6.4.1">&sect;6.4.1</a>) in the string <tt>s</tt>.
-If it finds a match, then <code>find</code> returns the indices of&nbsp;<code>s</code>
+If it finds a match, then <tt>find</tt> returns the indices of&nbsp;<tt>s</tt>
 where this occurrence starts and ends;
 otherwise, it returns <b>nil</b>.
-A third, optional numerical argument <code>init</code> specifies
+A third, optional numerical argument <tt>init</tt> 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>
+A value of <b>true</b> as a fourth, optional argument <tt>plain</tt>
 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.
+with no characters in <tt>pattern</tt> being considered magic.
-Note that if <code>plain</code> is given, then <code>init</code> must be given as well.
+Note that if <tt>plain</tt> is given, then <tt>init</tt> must be given as well.
 <p>
 If the pattern has captures,
 then in a successful match
 the captured values are also returned,
 after the two indices.
-<p>
+<h4 <%=heading_options%> ><a name="String.format"><tt>String.format (formatstring, &middot;&middot;&middot;)</tt></a></h4>
-<hr><h3><a name="pdf-string.format"><code>string.format (formatstring, &middot;&middot;&middot;)</code></a></h3>
 <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 ISO&nbsp;C function <code>sprintf</code>.
+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...)"><tt>String.format</tt></a> because Luan calls this internally.
-The only differences are that the options/modifiers
-<code>*</code>, <code>h</code>, <code>L</code>, <code>l</code>, <code>n</code>,
+<p>
-and <code>p</code> are not supported
+Note that Java's <tt>String.format</tt> is too stupid to convert between ints and floats, so you must provide the right kind of number.
-and that there is an extra option, <code>q</code>.
-The <code>q</code> option formats a string between double quotes,
-using escape sequences when necessary to ensure that
-it can safely be read back by the Lua interpreter.
+<h4 <%=heading_options%> ><a name="String.gmatch"><tt>String.gmatch (s, pattern)</tt></a></h4>
-For instance, the call
+<p>
-<pre>
-string.format('%q', 'a string with "quotes" and \n new line')
-</pre><p>
-may produce the string:
-<pre>
-"a string with \"quotes\" and \
-new line"
-</pre>
-<p>
-Options
-<code>A</code> and <code>a</code> (when available),
-<code>E</code>, <code>e</code>, <code>f</code>,
-<code>G</code>, and <code>g</code> all expect a number as argument.
-Options <code>c</code>, <code>d</code>,
-<code>i</code>, <code>o</code>, <code>u</code>, <code>X</code>, and <code>x</code>
-expect an integer.
-Option <code>q</code> expects a string;
-option <code>s</code> expects a string without embedded zeros.
-If the argument to option <code>s</code> is not a string,
-it is converted to one following the same rules of <a href="#pdf-tostring"><code>tostring</code></a>.
-<p>
-<hr><h3><a name="pdf-string.gmatch"><code>string.gmatch (s, pattern)</code></a></h3>
 Returns an iterator function that,
 each time it is called,
-returns the next captures from <code>pattern</code> (see <a href="#6.4.1">&sect;6.4.1</a>)
+returns the next captures from <tt>pattern</tt> (see <a href="#6.4.1">&sect;6.4.1</a>)
-over the string <code>s</code>.
+over the string <tt>s</tt>.
-If <code>pattern</code> specifies no captures,
+If <tt>pattern</tt> specifies no captures,
 then the whole match is produced in each call.
 <p>
 As an example, the following loop
-will iterate over all the words from string <code>s</code>,
+will iterate over all the words from string <tt>s</tt>,
 printing one per line:
-<pre>
+<p><tt><pre>
-s = "hello world from Lua"
+	local s = "hello world from Lua"
-for w in string.gmatch(s, "%a+") do
+	for w in String.gmatch(s, [[\w+]]) do
-print(w)
+		print(w)
-end
+	end
-</pre><p>
+</pre></tt></p>
-The next example collects all pairs <code>key=value</code> from the
+<p>
+The next example collects all pairs <tt>key=value</tt> from the
 given string into a table:
-<pre>
+<p><tt><pre>
-t = {}
+	local t = {}
-s = "from=world, to=Lua"
+	local s = "from=world, to=Lua"
-for k, v in string.gmatch(s, "(%w+)=(%w+)") do
+	for k, v in String.gmatch(s, [[(\w+)=(\w+)]]) do
-t[k] = v
+		t[k] = v
-end
+	end
-</pre>
+</pre></tt></p>
 <p>
-For this function, a caret '<code>^</code>' at the start of a pattern does not
+For this function, a caret '<tt>^</tt>' at the start of a pattern does not
 work as an anchor, as this would prevent the iteration.
+<h4 <%=heading_options%> ><a name="String.gsub"><tt>String.gsub (s, pattern, repl [, n])</tt></a></h4>
-<p>
-<hr><h3><a name="pdf-string.gsub"><code>string.gsub (s, pattern, repl [, n])</code></a></h3>
+<p>
-Returns a copy of <code>s</code>
+Returns a copy of <tt>s</tt>
-in which all (or the first <code>n</code>, if given)
+in which all (or the first <tt>n</tt>, if given)
-occurrences of the <code>pattern</code> (see <a href="#6.4.1">&sect;6.4.1</a>) have been
+occurrences of the <tt>pattern</tt> (see <a href="#6.4.1">&sect;6.4.1</a>) have been
-replaced by a replacement string specified by <code>repl</code>,
+replaced by a replacement string specified by <tt>repl</tt>,
 which can be a string, a table, or a function.
-<code>gsub</code> also returns, as its second value,
+<tt>gsub</tt> also returns, as its second value,
 the total number of matches that occurred.
-The name <code>gsub</code> comes from <em>Global SUBstitution</em>.
+The name <tt>gsub</tt> comes from <i>Global SUBstitution</i>.
 <p>
-If <code>repl</code> is a string, then its value is used for replacement.
+If <tt>repl</tt> is a string, then its value is used for replacement.
-The character&nbsp;<code>%</code> works as an escape character:
+The character&nbsp;<tt>\</tt> works as an escape character.
-any sequence in <code>repl</code> of the form <code>%<em>d</em></code>,
+Any sequence in <tt>repl</tt> of the form <tt>$<i>d</i></tt>,
-with <em>d</em> between 1 and 9,
+with <i>d</i> between 1 and 9,
-stands for the value of the <em>d</em>-th captured substring.
+stands for the value of the <i>d</i>-th captured substring.
-The sequence <code>%0</code> stands for the whole match.
+The sequence <tt>$0</tt> stands for the whole match.
-The sequence <code>%%</code> stands for a single&nbsp;<code>%</code>.
+<p>
-<p>
+If <tt>repl</tt> is a table, then the table is queried for every match,
-If <code>repl</code> is a table, then the table is queried for every match,
 using the first capture as the key.
 <p>
-If <code>repl</code> is a function, then this function is called every time a
+If <tt>repl</tt> is a function, then this function is called every time a
 match occurs, with all captured substrings passed as arguments,
 in order.
 <p>
 then it behaves as if the whole pattern was inside a capture.
 <p>
 If the value returned by the table query or by the function call
-is a string or a number,
+is not <b>nil</b>,
 then it is used as the replacement string;
-otherwise, if it is <b>false</b> or <b>nil</b>,
+otherwise, if it is <b>nil</b>,
 then there is no replacement
 (that is, the original match is kept in the string).
 <p>
 Here are some examples:
-<pre>
+<p><tt><pre>
-x = string.gsub("hello world", "(%w+)", "%1 %1")
+x = String.gsub("hello world", [[(\w+)]], "$1 $1")
 --&gt; x="hello hello world world"
-x = string.gsub("hello world", "%w+", "%0 %0", 1)
+x = String.gsub("hello world", [[\w+]], "$0 $0", 1)
 --&gt; x="hello hello world"
-x = string.gsub("hello world from Lua", "(%w+)%s*(%w+)", "%2 %1")
+x = String.gsub("hello world from Luan", [[(\w+)\s*(\w+)]], "$2 $1")
---&gt; x="world hello Lua from"
+--&gt; x="world hello Luan from"
-x = string.gsub("home = $HOME, user = $USER", "%$(%w+)", os.getenv)
+x = String.gsub("4+5 = $return 4+5$", [[\$(.*?)\$]], function (s)
---&gt; x="home = /home/roberto, user = roberto"
-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)
+x = String.gsub("$name-$version.tar.gz", [[\$(\w+)]], t)
 --&gt; x="lua-5.3.tar.gz"
-</pre>
+</pre></tt></p>
-<p>
+<h4 <%=heading_options%> ><a name="String.lower"><tt>String.lower (s)</tt></a></h4>
-<hr><h3><a name="pdf-string.len"><code>string.len (s)</code></a></h3>
+<p>
-Receives a string and returns its length.
-The empty string <code>""</code> has length 0.
-Embedded zeros are counted,
-so <code>"a\000bc\000"</code> has length 5.
-<p>
-<hr><h3><a name="pdf-string.lower"><code>string.lower (s)</code></a></h3>
 Receives a string and returns a copy of this string with all
 uppercase letters changed to lowercase.
 All other characters are left unchanged.
-The definition of what an uppercase letter is depends on the current locale.
 <p>

Mercurial Hosting > luan

comparison website/src/manual.html.luan @ 555:e25ba7a2e816