Log of autodoc.git/traditional_manual/chapter

2017-07-21

2017-07-21 11:36:32 by Pontus Östlund <ponost@roxen.com>

ed0ac87e886843632bb72a561ff258015501d656 (10098 lines) (+4586/-5512) ^{[

Show
| Annotate

]}
Branch: master

There was an XML syntax error in this file.

1: <!doctype html><html><head><title>Pike Reference Manual</title> <meta charset='utf-8'></head> - <body><dl><dt><h1 class='header'>9. Specific Datatype Modules</h1></dt><dd><dl><dt><h2 class='header'>Module String</h2> - </dt><dd> - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Constant - __HAVE_SPRINTF_NEGATIVE_F__ - </dt> - <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> String.<code class='constant'>__HAVE_SPRINTF_NEGATIVE_F__</code></code></dd> - + <body><dl><dt><h1 class='header'>9. I/O</h1></dt><dd><dl><dt><h2 class='header'>Class Stdio.File</h2> + </dt><dd><dl class='group--doc'> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Presence of this symbol indicates that <code>sprintf()</code> supports - little endian output for the <tt>'F'</tt>-format specifier. + <dd class='body--doc'>This is the basic I/O object, it provides socket and pipe + communication as well as file access. It does not buffer reads and + writes by default, and provides no line-by-line reading, that is done + with <code>Stdio.FILE</code> object. </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>sprintf()</code>, <code>lfun::_sprintf()</code> - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Constant - __HAVE_SPRINTF_STAR_MAPPING__ - </dt> - <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> String.<code class='constant'>__HAVE_SPRINTF_STAR_MAPPING__</code></code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Presence of this symbol indicates that <code>sprintf()</code> supports - mappings for the <tt>'*'</tt>-modifier syntax. + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>The file or stream will normally be closed when this object is + destructed (unless there are more objects that refer to the same + file through use of <code>assign</code> or <code>dup</code>). Objects do not contain + cyclic references in themselves, so they will be destructed timely + when they run out of references. </dd> <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>sprintf()</code>, <code>lfun::_sprintf()</code> + <dd class='body--doc'><code>Stdio.FILE</code> </dd></dl> - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - capitalize + assign </dt> - <dd><code><code class='datatype'>string</code> capitalize(<code class='datatype'>string</code> <code class='argument'>str</code>)</code></dd> + <dd><code><code class='datatype'>int</code> assign(<code class='object unresolved'>File</code>|<code class='object unresolved'>Fd</code> <code class='argument'>o</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Convert the first character in <code>str</code> to upper case, and return the - new string. + <dd class='body--doc'>This function takes a clone of Stdio.File and assigns all + variables of this file from it. It can be used together with <code>dup()</code> + to move files around. </dd> <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>lower_case()</code>, <code>upper_case()</code> + <dd class='body--doc'><code>dup()</code> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - common_prefix + async_connect </dt> - <dd><code><code class='datatype'>string</code> common_prefix(<code class='datatype'>array</code>(<code class='datatype'>string</code>) <code class='argument'>strs</code>)</code></dd> + <dd><code><code class='datatype'>int</code> async_connect(<code class='datatype'>string</code> <code class='argument'>host</code>, <code class='datatype'>int</code>|<code class='datatype'>string</code> <code class='argument'>port</code>, <code class='datatype'>function</code>(<code class='datatype'>int</code>, <code class='datatype'>mixed</code> ... :<code class='datatype'>void</code>) <code class='argument'>callback</code>, <code class='datatype'>mixed</code> ... <code class='argument'>args</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Find the longest common prefix from an array of strings. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - count - </dt> - <dd><code><code class='datatype'>int</code> count(<code class='datatype'>string</code> <code class='argument'>haystack</code>, <code class='datatype'>string</code> <code class='argument'>needle</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Count the number of non-overlapping times the string <code>needle</code> - occurs in the string <code>haystack</code>. The special cases for the needle - <code class='expr'>""</code> is that it occurs one time in the empty string, zero - times in a one character string and between every character - (length-1) in any other string. + <dd class='body--doc'>Open a TCP/IP connection asynchronously. + This function is similar to <code>connect()</code>, but works asynchronously. </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>search()</code>, <code>`/()</code> - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - expand_tabs - </dt> - <dd><code><code class='datatype'>string</code> expand_tabs(<code class='datatype'>string</code> <code class='argument'>s</code>, <code class='datatype'>int</code>|<code class='datatype'>void</code> <code class='argument'>tab_width</code>, <code class='datatype'>string</code>|<code class='datatype'>void</code> <code class='argument'>substitute_tab</code>, <code class='datatype'>string</code>|<code class='datatype'>void</code> <code class='argument'>substitute_space</code>, <code class='datatype'>string</code>|<code class='datatype'>void</code> <code class='argument'>substitute_newline</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Expands tabs in a string to ordinary spaces, according to common - tabulation rules. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - fuzzymatch - </dt> - <dd><code><code class='datatype'>int(0..100)</code> fuzzymatch(<code class='datatype'>string</code> <code class='argument'>a</code>, <code class='datatype'>string</code> <code class='argument'>b</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>This function compares two strings using a fuzzy matching - routine. The higher the resulting value, the better the strings match. + <dt class='head--doc'>Parameter <code class='parameter'>host</code></dt> + <dd></dd><dd class='body--doc'>Hostname or IP to connect to. </dd> - + <dt class='head--doc'>Parameter <code class='parameter'>port</code></dt> + <dd></dd><dd class='body--doc'>Port number or service name to connect to. + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>callback</code></dt> + <dd></dd><dd class='body--doc'>Function to be called on completion. + The first argument will be <code class='expr'>1</code> if a connection was + successfully established, and <code class='expr'>0</code> (zero) on failure. + The rest of the arguments to <code>callback</code> are passed + verbatim from <code>args</code>. + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>args</code></dt> + <dd></dd><dd class='body--doc'>Extra arguments to pass to <code>callback</code>. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>Returns <code class='expr'>0</code> on failure to open a socket, and <code class='expr'>1</code> + if <code>callback</code> will be used. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>The socket may be opened with <code>open_socket()</code> ahead of + the call to this function, but it is not required. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>This object is put in callback mode by this function. For + <code>callback</code> to be called, the backend must be active. See e.g. + <code>set_read_callback</code> for more details about backends and + callback mode. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>The socket will be in nonblocking state if the connection is + successful, and any callbacks will be cleared. + </dd> <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>Array.diff()</code>, <code>Array.diff_compare_table()</code> - <code>Array.diff_longest_sequence()</code> + <dd class='body--doc'><code>connect()</code>, <code>open_socket()</code>, <code>set_nonblocking()</code> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - hex2string + close </dt> - <dd><code><code class='datatype'>string(8bit)</code> hex2string(<code class='datatype'>string(8bit)</code> <code class='argument'>hex</code>)</code></dd> + <dd><code><code class='datatype'>int</code> close()</code> + <code><code class='datatype'>int</code> close(<code class='datatype'>string</code> <code class='argument'>direction</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Convert a string of hexadecimal digits to binary - data. Non-hexadecimal characters will be ignored when between - tuples. Eg. "00 00" is ok, but "0 000" isn't. + <dd class='body--doc'>Close the file. Optionally, specify "r", "w" or "rw" to close just + the read, just the write or both read and write directions of the file + respectively. + An exception is thrown if an I/O error occurs. </dd> - + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>Nonzero is returned if the file wasn't open in the specified + direction, zero otherwise. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>This function will not call the <tt>close_callback</tt>. + </dd> <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>string2hex()</code> + <dd class='body--doc'><code>open</code>, <code>open_socket</code> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - implode_nicely + connect </dt> - <dd><code><code class='datatype'>string</code> implode_nicely(<code class='datatype'>array</code>(<code class='datatype'>string</code>|<code class='datatype'>int</code>|<code class='datatype'>float</code>) <code class='argument'>foo</code>, <code class='datatype'>string</code>|<code class='datatype'>void</code> <code class='argument'>separator</code>)</code></dd> + <dd><code><code class='modifier'>variant</code> <code class='datatype'>int</code> connect(<code class='datatype'>string</code> <code class='argument'>host</code>, <code class='datatype'>int(0..)</code>|<code class='datatype'>string</code> <code class='argument'>port</code>)</code> + <code><code class='modifier'>variant</code> <code class='datatype'>int</code> connect(<code class='datatype'>string</code> <code class='argument'>host</code>, <code class='datatype'>int(0..)</code>|<code class='datatype'>string</code> <code class='argument'>port</code>, <code class='datatype'>string</code> <code class='argument'>client</code>, <code class='datatype'>int(0..)</code>|<code class='datatype'>string</code> <code class='argument'>client_port</code>)</code> + <code><code class='modifier'>variant</code> <code class='datatype'>string</code> connect(<code class='datatype'>string</code> <code class='argument'>host</code>, <code class='datatype'>int(0..)</code>|<code class='datatype'>string</code> <code class='argument'>port</code>, <code class='datatype'>string</code> <code class='argument'>data</code>)</code> + <code><code class='modifier'>variant</code> <code class='datatype'>string</code> connect(<code class='datatype'>string</code> <code class='argument'>host</code>, <code class='datatype'>int(0..)</code>|<code class='datatype'>string</code> <code class='argument'>port</code>, <code class='datatype'>int(0..0)</code>|<code class='datatype'>string</code> <code class='argument'>client</code>, <code class='datatype'>int(0..)</code>|<code class='datatype'>string</code> <code class='argument'>client_port</code>, <code class='datatype'>string</code> <code class='argument'>data</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>This function implodes a list of words to a readable string, e.g. - <code class='expr'>({"straw","berry","pie"})</code> becomes - <code class='expr'>"straw, berry and pie"</code>. If the separator is omitted, the - default is <code class='expr'>"and"</code>. If the words are numbers they are - converted to strings first. + <dd class='body--doc'>Open a TCP/IP connection to the specified destination. + In nonblocking mode, success is indicated with the write-callback, + and failure with the close-callback or the read_oob-callback. + The <code>host</code> argument is the hostname or IP number of the remote + machine. + A local IP and port can be explicitly bound by specifying + <code>client</code> and <code>client_port</code>. + If the <code>data</code> argument is included the socket will use + TCP_FAST_OPEN if posible. In this mode the the function will + return the part of the data that has not been sent to the remote + server yet instead of 1 (you will have to use <code>write</code> to send + this data). + Note that TCP_FAST_OPEN requires server support, the connection + might fail even though the remote server exists. It might be + advisable to retry without TCP_FAST_OPEN (and remember this + fact) </dd> - + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>This function returns 1 or the remaining <code>data</code> for success, 0 + otherwise. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>In nonblocking mode <code class='expr'>0</code> (zero) may be returned and + <code>errno()</code> set to <code class='expr'>EWOULDBLOCK</code> or <code class='expr'>WSAEWOULDBLOCK</code>. + This should not be regarded as a + connection failure. In nonblocking mode you need to wait for a + write or close callback before you know if the connection failed + or not. + </dd> <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>`*()</code> + <dd class='body--doc'><code>query_address()</code>, <code>async_connect()</code>, <code>connect_unix()</code> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - int2char + connect_unix </dt> - <dd><code><code class='datatype'>string</code> int2char(<code class='datatype'>int</code> <code class='argument'>x</code>)</code></dd> + <dd><code><code class='datatype'>int</code> connect_unix(<code class='datatype'>string</code> <code class='argument'>path</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Same as sprintf("%c",x); + <dd class='body--doc'>Open a UNIX domain socket connection to the specified destination. </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>sprintf()</code> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>Returns <code class='expr'>1</code> on success, and <code class='expr'>0</code> on failure. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>Nonblocking mode is not supported while connecting </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - int2hex + create </dt> - <dd><code><code class='datatype'>string</code> int2hex(<code class='datatype'>int</code> <code class='argument'>x</code>)</code></dd> + <dd><code>Stdio.File Stdio.File()</code> + <code>Stdio.File Stdio.File(<code class='datatype'>string</code> <code class='argument'>filename</code>)</code> + <code>Stdio.File Stdio.File(<code class='datatype'>string</code> <code class='argument'>filename</code>, <code class='datatype'>string</code> <code class='argument'>mode</code>)</code> + <code>Stdio.File Stdio.File(<code class='datatype'>string</code> <code class='argument'>filename</code>, <code class='datatype'>string</code> <code class='argument'>mode</code>, <code class='datatype'>int</code> <code class='argument'>mask</code>)</code> + <code>Stdio.File Stdio.File(<code class='datatype'>string</code> <code class='argument'>descriptorname</code>)</code> + <code>Stdio.File Stdio.File(<code class='datatype'>int</code> <code class='argument'>fd</code>)</code> + <code>Stdio.File Stdio.File(<code class='datatype'>int</code> <code class='argument'>fd</code>, <code class='datatype'>string</code> <code class='argument'>mode</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Same as <code class='expr'>sprintf("%x",x);</code>, i.e. returns the integer <code>x</code> in - hexadecimal base using lower cased symbols. + <dd class='body--doc'>There are four basic ways to create a Stdio.File object. + The first is calling it without any arguments, in which case the you'd + have to call <code>open()</code>, <code>connect()</code> or some other method which connects + the File object with a stream. + The second way is calling it with a <code>filename</code> and open <code>mode</code>. This is + the same thing as cloning and then calling <code>open()</code>, except shorter and + faster. + The third way is to call it with <code>descriptorname</code> of <code class='expr'>"stdin"</code>, + <code class='expr'>"stdout"</code> or <code class='expr'>"stderr"</code>. This will open the specified + standard stream. + For the advanced users, you can use the file descriptors of the + systems (note: emulated by pike on some systems - like NT). This is + only useful for streaming purposes on unix systems. This is not + recommended at all if you don't know what you're into. Default + <code>mode</code> for this is <code class='expr'>"rw"</code>. </dd> - + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>Open mode will be filtered through the system UMASK. You + might need to use <code>chmod()</code> later. + </dd> <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>sprintf()</code> + <dd class='body--doc'><code>open()</code>, <code>connect()</code>, <code>Stdio.FILE</code>, </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - int2roman + dup </dt> - <dd><code><code class='datatype'>string</code> int2roman(<code class='datatype'>int</code> <code class='argument'>m</code>)</code></dd> + <dd><code><code class='object unresolved'>File</code> dup()</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Converts the provided integer to a roman integer (i.e. a string). + <dd class='body--doc'>This function returns a clone of Stdio.File with all variables + copied from this file. </dd> - <dt class='head--doc'>Throws</dt> - <dd class='body--doc'>Throws an error if <code>m</code> is outside the range 0 to 10000. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - int2size - </dt> - <dd><code><code class='datatype'>string</code> int2size(<code class='datatype'>int</code> <code class='argument'>size</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Returns the size as a memory size string with suffix, - e.g. 43210 is converted into "42.2 kB". To be correct - to the latest standards it should really read "42.2 KiB", - but we have chosen to keep the old notation for a while. - The function knows about the quantifiers kilo, mega, giga, - tera, peta, exa, zetta and yotta. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - levenshtein_distance - </dt> - <dd><code><code class='datatype'>int</code> levenshtein_distance(<code class='datatype'>string</code> <code class='argument'>a</code>, <code class='datatype'>string</code> <code class='argument'>b</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>This function calculates the Levenshtein distance between two strings a - and b. The Levenshtein distance describes the minimal number of character - additions, removals or substitutions to apply to convert a to b. - Mathematically, the Levenshtein distance between two strings a, b is given - by lev_a,b(|a|,|b|) where - lev_a,b(i, j) == max(i, j), if min(i, j) == 0 - lev_a,b(i, j) == min( lev_a,b(i, j-1)+1, - lev_a,b(i-1, j)+1, - lev_a,b(i-1, j-1) + a_i!=b_j ), else - Note that the first element in the minimum corresponds to inserting a - character to a (or deleting a character from b), the second to deleting a - character from a and the third to match or mismatch, depending on whether - the respective characters are equal. - Example: For example, the Levenshtein distance between "pike" and - "bikes" is 2, since the following two edits change one into the other, - and there is no way to do it with fewer than two edits: - - "pike" -> "bike" (substitute "p" with "b") - - "bike" -> "bikes" (add "s" at the end) - Note that the cost to compute the Levenshtein distance is roughly - proportional to the product of the two string lengths. So this function - is usually used to aid in fuzzy string matching, when at least one of the - strings is short. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - normalize_space - </dt> - <dd><code><code class='datatype'>string</code> normalize_space(<code class='datatype'>string</code> <code class='argument'>s</code>, <code class='datatype'>string</code>|<code class='datatype'>void</code> <code class='argument'>whitespace</code>)</code></dd> - - <dt class='head--doc'>Parameter <code class='parameter'>s</code></dt> - <dd></dd><dd class='body--doc'>Is returned after white space in it has been normalised. - White space is normalised by stripping leading and trailing white space - and replacing sequences of white space characters with a single space. - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>whitespace</code></dt> - <dd></dd><dd class='body--doc'>Defines what is considered to be white space eligible for normalisation. - It has a default value that starts with <code class='expr'>" \t\r\n\v\f"</code> and in - addition to that contains all whitespace characters part of Unicode. - The first character denotes the character for replacing whitespace - sequences. - </dd> + <dt class='head--doc'>Note</dt> - <dd class='body--doc'>Trailing and leading whitespace around \r and \n characters - is stripped as well (only useful if they're not in the <code>whitespace</code> set). + <dd class='body--doc'>All variables, even <tt>id</tt>, are copied. </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>This function is a lot faster with just one argument (i.e. the builtin - whitespace set has an optimised code path). + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>assign()</code> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - range + errno </dt> - <dd><code><code class='datatype'>array</code>(<code class='datatype'>int</code>) range(<code class='datatype'>string</code> <code class='argument'>s</code>)</code></dd> + <dd><code><code class='datatype'>int</code> errno()</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Returns the character range of a string in an array of two - elements. The first element contains the lower bound and the - second the upper. The precision is only 8 bits, so for wide - strings only character blocks are known. + <dd class='body--doc'>Returns the error code for the last command on this file. + Error code is normally cleared when a command is successful. </dd></dl> <hr /> <dl class='group--doc'> - <dt class='head--type'>Method - secure + <dt class='head--type'>Inherit + Fd </dt> - <dd><code><code class='datatype'>string</code> secure(<code class='datatype'>string</code> <code class='argument'>str</code>)</code></dd> + <dd><code><code class='modifier'>optional</code> inherit Fd : Fd</code></dd> + </dl> - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Marks the string as secure, which will clear the memory area - before freeing the string. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>Object.secure()</code> - </dd></dl> + - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - sillycaps + line_iterator </dt> - <dd><code><code class='datatype'>string</code> sillycaps(<code class='datatype'>string</code> <code class='argument'>str</code>)</code></dd> + <dd><code><code class='object unresolved'>String.SplitIterator</code>|<code class='object unresolved'>LineIterator</code> line_iterator(<code class='datatype'>int</code>|<code class='datatype'>void</code> <code class='argument'>trim</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Convert the first character in each word (separated by spaces) in - <code>str</code> to upper case, and return the new string. + <dd class='body--doc'>Returns an iterator that will loop over the lines in this file. + If trim is true, all <tt>'\r'</tt> characters will be removed from + the input. </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - soundex + open </dt> - <dd><code><code class='datatype'>string</code> soundex(<code class='datatype'>string</code> <code class='argument'>word</code>)</code></dd> + <dd><code><code class='datatype'>int</code> open(<code class='datatype'>string</code> <code class='argument'>filename</code>, <code class='datatype'>string</code> <code class='argument'>mode</code>)</code> + <code><code class='datatype'>int</code> open(<code class='datatype'>string</code> <code class='argument'>filename</code>, <code class='datatype'>string</code> <code class='argument'>mode</code>, <code class='datatype'>int</code> <code class='argument'>mask</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Returns the soundex value of <code>word</code> according to - the original Soundex algorithm, patented by Margaret O´Dell - and Robert C. Russel in 1918. The method is based on the phonetic - classification of sounds by how they are made. It was only intended - for hashing of english surnames, and even at that it isn't that - much of a help. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - status - </dt> - <dd><code><code class='datatype'>string</code> status(<code class='datatype'>int</code> <code class='argument'>verbose</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Get string table statistics. + <dd class='body--doc'>Open a file for read, write or append. The parameter <code>mode</code> should + contain one or more of the following letters: + <table class='box'><tr><td><code><code class='key'>"r"</code></code></td><td>Open file for reading. + </td></tr> + <tr><td><code><code class='key'>"w"</code></code></td><td>Open file for writing. + </td></tr> + <tr><td><code><code class='key'>"a"</code></code></td><td>Open file for append (use with <code class='expr'>"w"</code>). + </td></tr> + <tr><td><code><code class='key'>"t"</code></code></td><td>Truncate file at open (use with <code class='expr'>"w"</code>). + </td></tr> + <tr><td><code><code class='key'>"c"</code></code></td><td>Create file if it doesn't exist (use with <code class='expr'>"w"</code>). + </td></tr> + <tr><td><code><code class='key'>"x"</code></code></td><td>Fail if file already exists (use with <code class='expr'>"c"</code>). + </td></tr> + </table><code>mode</code> should always contain at least one of the letters + <code class='expr'>"r"</code> or <code class='expr'>"w"</code>. + The parameter <code>mask</code> is protection bits to use if the file is + created. Default is <code class='expr'>0666</code> (read+write for all in octal + notation). </dd> <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>Returns a string with an ASCII table containing - the current string table statistics. + <dd class='body--doc'>This function returns <code class='expr'>1</code> for success, <code class='expr'>0</code> otherwise. </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>Currently returns the empty string (<code class='expr'>""</code>) - if <code>verbose</code> is zero. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>The formatting and contents of the result - may vary between different versions of Pike. + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>close()</code>, <code>create()</code> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - string2hex + open_socket </dt> - <dd><code><code class='datatype'>string</code> string2hex(<code class='datatype'>string</code> <code class='argument'>data</code>, <code class='datatype'>void</code>|<code class='datatype'>int</code> <code class='argument'>uppercase</code>)</code></dd> + <dd><code><code class='datatype'>int</code> open_socket(<code class='datatype'>int</code>|<code class='datatype'>string</code>|<code class='datatype'>void</code> <code class='argument'>port</code>, <code class='datatype'>string</code>|<code class='datatype'>void</code> <code class='argument'>address</code>, <code class='datatype'>int</code>|<code class='datatype'>string</code>|<code class='datatype'>void</code> <code class='argument'>family_hint</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Convert a string of binary data to a hexadecimal string. + <dd class='body--doc'>This makes this file into a socket ready for connections. The reason + for this function is so that you can set the socket to nonblocking + or blocking (default is blocking) before you call <code>connect()</code>. </dd> - <dt class='head--doc'>Parameter <code class='parameter'>uppercase</code></dt> - <dd></dd><dd class='body--doc'>If set, the string will use upper cased characters. + <dt class='head--doc'>Parameter <code class='parameter'>port</code></dt> + <dd></dd><dd class='body--doc'>If you give a port number to this function, the socket will be + bound to this port locally before connecting anywhere. This is + only useful for some silly protocols like FTP. The port can + also be specified as a string, giving the name of the service + associated with the port. Pass -1 to not specify a port (eg to + bind only to an address). </dd> - + <dt class='head--doc'>Parameter <code class='parameter'>address</code></dt> + <dd></dd><dd class='body--doc'>You may specify an address to bind to if your machine has many IP + numbers. + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>family_hint</code></dt> + <dd></dd><dd class='body--doc'>A protocol family for the socket can be specified. If no family is + specified, one which is appropriate for the address is automatically + selected. Thus, there is normally no need to specify it. If you + do not want to specify a bind address, you can provide the address + as a hint here instead, to allow the automatic selection to work + anyway. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>This function returns 1 for success, 0 otherwise. + </dd> <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>hex2string()</code> + <dd class='body--doc'><code>connect()</code>, <code>set_nonblocking()</code>, <code>set_blocking()</code> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - trim + openat </dt> - <dd><code><code class='datatype'>string</code> trim(<code class='datatype'>string</code> <code class='argument'>s</code>)</code></dd> + <dd><code><code class='object unresolved'>File</code> openat(<code class='datatype'>string</code> <code class='argument'>filename</code>, <code class='datatype'>string</code> <code class='argument'>mode</code>)</code> + <code><code class='object unresolved'>File</code> openat(<code class='datatype'>string</code> <code class='argument'>filename</code>, <code class='datatype'>string</code> <code class='argument'>mode</code>, <code class='datatype'>int</code> <code class='argument'>mask</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Trim leading and trailing white spaces characters (space, tab, - newline, carriage return, form feed, vertical tab and all the - white spaces defined in Unicode) from the string <code>s</code>. + <dd class='body--doc'>Open a file relative to an open directory. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>File.statat()</code>, <code>File.unlinkat()</code> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - trim_whites + openpt </dt> - <dd><code><code class='datatype'>string</code> trim_whites(<code class='datatype'>string</code> <code class='argument'>s</code>)</code></dd> + <dd><code><code class='datatype'>int</code> openpt(<code class='datatype'>string</code> <code class='argument'>mode</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Trim leading and trailing spaces and tabs from the string <code>s</code>. + <dd class='body--doc'>Open the master end of a pseudo-terminal pair. The parameter + <code>mode</code> should contain one or more of the following letters: + <table class='box'><tr><td><code><code class='key'>"r"</code></code></td><td>Open terminal for reading. + </td></tr> + <tr><td><code><code class='key'>"w"</code></code></td><td>Open terminal for writing. + </td></tr> + </table><code>mode</code> should always contain at least one of the letters + <code class='expr'>"r"</code> or <code class='expr'>"w"</code>. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>grantpt()</code> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - width + pipe </dt> - <dd><code><code class='datatype'>int(8..8)</code>|<code class='datatype'>int(16..16)</code>|<code class='datatype'>int(32..32)</code> width(<code class='datatype'>string</code> <code class='argument'>s</code>)</code></dd> + <dd><code><code class='object unresolved'>File</code> pipe(<code class='datatype'>void</code>|<code class='datatype'>int</code> <code class='argument'>required_properties</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Returns the width of a string. + <dd class='body--doc'>This function creates a pipe between the object it was called in + and an object that is returned. </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>Three return values are currently possible: - <table class='box'><tr><td><code><code class='key'>8</code></code></td><td>The string <code>s</code> only contains characters <= 255. + <dt class='head--doc'>Parameter <code class='parameter'>required_properties</code></dt> + <dd></dd><dd class='body--doc'>Binary or (<code>predef::`|()</code>) of required <code class='expr'>PROP_</code> properties. + <table class='box'><tr><td><code><code class='key'>PROP_IPC</code></code></td><td>The resulting pipe may be used for inter process communication. </td></tr> - <tr><td><code><code class='key'>16</code></code></td><td>The string <code>s</code> only contains characters <= 65535. + <tr><td><code><code class='key'>PROP_NONBLOCK</code></code></td><td>The resulting pipe supports nonblocking I/O. </td></tr> - <tr><td><code><code class='key'>32</code></code></td><td>The string <code>s</code> contains characters >= 65536. + <tr><td><code><code class='key'>PROP_SHUTDOWN</code></code></td><td>The resulting pipe supports shutting down transmission in either + direction (see <code>close()</code>). </td></tr> - </table> + <tr><td><code><code class='key'>PROP_BUFFERED</code></code></td><td>The resulting pipe is buffered (usually 4KB). + </td></tr> + <tr><td><code><code class='key'>PROP_BIDIRECTIONAL</code></code></td><td>The resulting pipe is bi-directional. + </td></tr> + <tr><td><code><code class='key'>PROP_SEND_FD</code></code></td><td>The resulting pipe might support sending of file descriptors + (see <code>send_fd()</code> and <code>receive_fd()</code> for details). + </td></tr> + <tr><td><code><code class='key'>PROP_REVERSE</code></code></td><td>The resulting pipe supports communication "backwards" (but + not necessarily "forwards", see <code>PROP_BIDIRECTIONAL</code>). + </td></tr> + </table>The default is <code class='expr'>PROP_NONBLOCK|PROP_BIDIRECTIONAL</code>. + If <code>PROP_BIDIRECTIONAL</code> isn't specified, the read-end is this + object, and the write-end is the returned object (unless + <code>PROP_REVERSE</code> has been specified, in which case it is the other + way around). + The two ends of a bi-directional pipe are indistinguishable. + If the File object this function is called in was open to begin with, + it will be closed before the pipe is created. </dd> <dt class='head--doc'>Note</dt> - <dd class='body--doc'>It is possible that a future version of Pike may return - further values. In particular the width <code class='expr'>7</code> seems - like it could be useful. - </dd></dl> - <dl><dt><h2 class='header'>Class String.Bootstring</h2> - </dt><dd><dl class='group--doc'> - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>This class implements the "Bootstring" string transcoder described in - <a href='ftp://ftp.rfc-editor.org/in-notes/rfc3492.txt'>ftp://ftp.rfc-editor.org/in-notes/rfc3492.txt</a>. - </dd></dl> - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - create - </dt> - <dd><code>String.Bootstring String.Bootstring(<code class='datatype'>int</code> <code class='argument'>base</code>, <code class='datatype'>int</code> <code class='argument'>tmin</code>, <code class='datatype'>int</code> <code class='argument'>tmax</code>, <code class='datatype'>int</code> <code class='argument'>skew</code>, <code class='datatype'>int</code> <code class='argument'>damp</code>, <code class='datatype'>int</code> <code class='argument'>initial_bias</code>, <code class='datatype'>int</code> <code class='argument'>initial_n</code>, <code class='datatype'>int</code> <code class='argument'>delim</code>, <code class='datatype'>string</code> <code class='argument'>digits</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Creates a Bootstring transcoder instance using the specified parameters. + <dd class='body--doc'>Calling this function with an argument of <tt>0</tt> is not the + same as calling it with no arguments. </dd> - <dt class='head--doc'>Parameter <code class='parameter'>base</code></dt> - <dd></dd><dd class='body--doc'>The base used by the variable-length integers. - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>tmin</code></dt> - <dd></dd><dd class='body--doc'>The minimum threshold digit value for the variable-length integers. - Must be >=0 and <= tmax. - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>tmax</code></dt> - <dd></dd><dd class='body--doc'>The maximum threshold digit value for the variable-length integers. - Must be <= base-1. - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>skew</code></dt> - <dd></dd><dd class='body--doc'>The skew term for the bias adapation. Must be >= 1. - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>damp</code></dt> - <dd></dd><dd class='body--doc'>The damping factor for the bias adaption. Must be >= 2. - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>initial_bias</code></dt> - <dd></dd><dd class='body--doc'>The initial bias for the variable-length integer thresholding. - initial_bias % base must be <= base - tmin. - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>initial_n</code></dt> - <dd></dd><dd class='body--doc'>The first code point outside the "basic" set of code points. - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>delim</code></dt> - <dd></dd><dd class='body--doc'>The "basic" code point used as the delimiter. - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>digits</code></dt> - <dd></dd><dd class='body--doc'>The "basic" code points used as digits. The length of the string - should be the same as the base parameter. + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>Process.create_process()</code>, <code>send_fd()</code>, <code>receive_fd()</code>, + <code>PROP_IPC</code>, <code>PROP_NONBLOCK</code>, <code>PROP_SEND_FD</code>, + <code>PROP_SHUTDOWN</code>, <code>PROP_BUFFERED</code>, <code>PROP_REVERSE</code>, + <code>PROP_BIDIRECTIONAL</code> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - decode + query_buffer_mode </dt> - <dd><code><code class='datatype'>string</code> decode(<code class='datatype'>string</code> <code class='argument'>s</code>)</code></dd> + <dd><code><code class='datatype'>array</code>(<code class='object unresolved'>Stdio.Buffer</code>|<code class='datatype'>int(0..0)</code>) query_buffer_mode()</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Decodes a Bootstring encoded string of "basic" code points back - to the original string space. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - encode - </dt> - <dd><code><code class='datatype'>string</code> encode(<code class='datatype'>string</code> <code class='argument'>s</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Encodes a string using Bootstring encoding into a string constisting - only of "basic" code points (< initial_n). - </dd></dl> - </dd></dl><dl><dt><h2 class='header'>Class String.Buffer</h2> - </dt><dd><dl class='group--doc'> - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>A buffer, used for building strings. It's - conceptually similar to a string, but you can only <code>add</code> - strings to it, and you can only <code>get</code> the value from it once. - There is a reason for those seemingly rather odd limitations, - it makes it possible to do some optimizations that really speed - things up. - You do not need to use this class unless you add very many - strings together, or very large strings. + <dd class='body--doc'>Get the active input and output buffers that have been + set with <code>set_buffer_mode()</code> (if any). </dd> - <dt class='head--doc'>Example</dt> - <dd class='example'><pre>For the fastest possible operation, write your code like this: - <pre><code>String.Buffer b = String.Buffer( ); - - function add = b->add; - - .. call add several times in code ... - - string result = b->get(); // also clears the buffer - </code></pre></pre></dd></dl> - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - _search - </dt> - <dd><code><code class='datatype'>int(0..)</code> search(String.Buffer from, <code class='datatype'>int</code> <code class='argument'>character</code>, <code class='datatype'>int</code>|<code class='datatype'>void</code> <code class='argument'>start</code>, <code class='datatype'>int</code>|<code class='datatype'>void</code> <code class='argument'>end</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Search for a <code>character</code> in the buffer, starting the scan - from <code>start</code> and ending at <code>end</code> (inclusive). - </dd> + <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>Returns to position in the buffer where the character was found - on success, and <code>UNDEFINED</code> on failure. + <dd class='body--doc'>Returns an array with two elements: + <table class='box'><tr><td colspan='2'>Array</td></tr> + <tr><td><code><code class='object unresolved'>Stdio.Buffer</code> <code class='key'>0</code></code></td><td>The current input buffer. + </td></tr> + <tr><td><code><code class='object unresolved'>Stdio.Buffer</code> <code class='key'>1</code></code></td><td>The current output buffer. + </td></tr> + </table> </dd> <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>Stdio.Buffer()->_search()</code>, <code>search()</code>, <code>lfun::_search()</code> + <dd class='body--doc'><code>set_buffer_mode()</code> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - _search + query_read_callback + Method + query_write_callback + Method + query_read_oob_callback + Method + query_write_oob_callback + Method + query_close_callback + Method + query_callbacks </dt> - <dd><code><code class='datatype'>int(0..)</code> search(String.Buffer from, <code class='datatype'>string</code> <code class='argument'>substring</code>, <code class='datatype'>int</code>|<code class='datatype'>void</code> <code class='argument'>start</code>, <code class='datatype'>int</code>|<code class='datatype'>void</code> <code class='argument'>end</code>)</code></dd> + <dd><code><code class='object unresolved'>read_callback_t</code> query_read_callback()</code> + <code><code class='object unresolved'>write_callback_t</code> query_write_callback()</code> + <code><code class='datatype'>function</code>(<code class='datatype'>mixed</code>, <code class='datatype'>string</code>:<code class='datatype'>int</code>) query_read_oob_callback()</code> + <code><code class='datatype'>function</code>(<code class='datatype'>mixed</code>:<code class='datatype'>int</code>) query_write_oob_callback()</code> + <code><code class='datatype'>function</code>(<code class='datatype'>mixed</code>:<code class='datatype'>int</code>) query_close_callback()</code> + <code><code class='datatype'>array</code>(<code class='datatype'>function</code>(<code class='datatype'>mixed</code>, <code class='datatype'>void</code>|<code class='datatype'>string</code>:<code class='datatype'>int</code>)) query_callbacks()</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Search for a <code>substring</code> in the buffer, starting the scan - from <code>start</code> and ending at <code>end</code> (inclusive). + <dd class='body--doc'>These functions return the currently installed callbacks for the + respective events. + <code>query_callbacks</code> returns the callbacks in the same order as + <code>set_callbacks</code> and <code>set_nonblocking</code> expect them. </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>Returns to position in the buffer where the substring was found - on success, and <code>UNDEFINED</code> on failure. - </dd> + <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>Stdio.Buffer()->_search()</code>, <code>search()</code>, <code>lfun::_search()</code> + <dd class='body--doc'><code>set_nonblocking()</code>, <code>set_read_callback</code>, + <code>set_write_callback</code>, <code>set_read_oob_callback</code>, + <code>set_write_oob_callback</code>, <code>set_close_callback</code>, + <code>set_callbacks</code> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - _sizeof + query_id </dt> - <dd><code><code class='datatype'>int</code> sizeof( String.Buffer arg )</code></dd> + <dd><code><code class='datatype'>mixed</code> query_id()</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Returns the size of the buffer. + <dd class='body--doc'>This function returns the <tt>id</tt> that has been set with <code>set_id()</code>. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>set_id()</code> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - _sprintf + read </dt> - <dd><code>string sprintf(string format, ... String.Buffer arg ... )</code></dd> + <dd><code><code class='datatype'>string(8bit)</code> read(<code class='datatype'>int</code>|<code class='datatype'>void</code> <code class='argument'>nbytes</code>, <code class='datatype'>bool</code>|<code class='datatype'>void</code> <code class='argument'>not_all</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>It is possible to <code>sprintf</code> a String.Buffer object - as <tt>%s</tt> just as if it was a string. + <dd class='body--doc'>Read (optionally buffered) data from a file or a stream. + Proxy function for <code>Fd::read()</code>, that adds support for + the buffering configured by <code>set_buffer_mode()</code> + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>read_function()</code>, <code>write()</code>, <code>Fd::read()</code> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - `+ + read_function </dt> - <dd><code><code class='object unresolved'>String.Buffer</code> res = <code class='class'>String.Buffer()</code> + <code class='class'>what</code></code></dd> - </dl> + <dd><code><code class='datatype'>function</code>(:<code class='datatype'>string</code>) read_function(<code class='datatype'>int</code> <code class='argument'>nbytes</code>)</code></dd> - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - `+= - </dt> - <dd><code><code class='class'>String.Buffer()</code> += <code class='class'>what</code></code></dd> - </dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - add - </dt> - <dd><code><code class='datatype'>int</code> add(<code class='datatype'>string</code>|<code class='object unresolved'>String.Buffer</code> ... <code class='argument'>data</code>)</code></dd> - + <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Adds <code>data</code> to the buffer. - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>Returns the size of the buffer. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>Pike 7.8 and earlier did not support adding <code>String.Buffer</code>s - directly. + <dd class='body--doc'>Returns a function that when called will call <code>read</code> with + nbytes as argument. Can be used to get various callback + functions, eg for the fourth argument to + <code>String.SplitIterator</code>. </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - cast + send_fd </dt> - <dd><code>(int)String.Buffer() (float)String.Buffer() (string)String.Buffer() (array)String.Buffer() (mapping)String.Buffer() (multiset)String.Buffer()</code></dd> + <dd><code><code class='datatype'>void</code> send_fd(<code class='object unresolved'>File</code>|<code class='object unresolved'>Fd</code> <code class='argument'>file</code>)</code></dd> + </dl> - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>It is possible to cast a String.Buffer object to - a <code class='expr'>string</code> and an <code class='expr'>int</code>. - </dd></dl> + - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - clear + set_blocking </dt> - <dd><code><code class='datatype'>void</code> clear()</code></dd> + <dd><code><code class='datatype'>void</code> set_blocking()</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Empty the buffer, and don't care about the old content. + <dd class='body--doc'>This function clears all callbacks and sets a stream to blocking + mode. i.e. reading, writing and closing will wait until data has + been transferred before returning. </dd> <dt class='head--doc'>Note</dt> - <dd class='body--doc'>This function was not available in Pike 7.8 and earlier. + <dd class='body--doc'>The callbacks are cleared and blocking mode is set in one atomic + operation, so no callback gets called in between if the backend + is running in another thread. + Even so, if the stream is in callback mode (i.e. if any + callbacks are installed) then only the backend thread can use + this function reliably; it might otherwise already be running in + a callback which is about to call e.g. <code>write</code> when the stream + becomes blocking. </dd> <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>get()</code> + <dd class='body--doc'><code>set_nonblocking()</code>, <code>set_nonblocking_keep_callbacks()</code>, + <code>set_blocking_keep_callbacks()</code> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - create + set_nonblocking_keep_callbacks + Method + set_blocking_keep_callbacks </dt> - <dd><code>String.Buffer String.Buffer(<code class='datatype'>int</code> <code class='argument'>initial_size</code>)</code></dd> + <dd><code><code class='datatype'>void</code> set_nonblocking_keep_callbacks()</code> + <code><code class='datatype'>void</code> set_blocking_keep_callbacks()</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Initializes a new buffer. - If no <code>initial_size</code> is specified, 256 is used. If you - know approximately how big the buffer will be, you can optimize - the operation of <code>add()</code> (slightly) by passing the size to this - function. + <dd class='body--doc'>Toggle between blocking and nonblocking, + without changing the callbacks. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>set_nonblocking()</code>, <code>set_blocking()</code> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - get + set_buffer_mode </dt> - <dd><code><code class='datatype'>string</code> get()</code></dd> + <dd><code><code class='datatype'>void</code> set_buffer_mode(<code class='object unresolved'>Stdio.Buffer</code>|<code class='datatype'>int(0..0)</code> <code class='argument'>in</code>, <code class='object unresolved'>Stdio.Buffer</code>|<code class='datatype'>int(0..0)</code> <code class='argument'>out</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Get the data from the buffer. + <dd class='body--doc'>Toggle the file to Buffer mode. + In this mode reading and writing will be done via Buffer + objects, in the directions you included buffers. </dd> - + <dt class='head--doc'>Parameter <code class='parameter'>in</code></dt> + <dd></dd><dd class='body--doc'>Input buffer. If this buffer is non-empty, its contents + will be returned after any already received data. + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>out</code></dt> + <dd></dd><dd class='body--doc'>Output buffer. If this buffer is non-empty, its contents + will be sent after any data already queued for sending. + </dd> <dt class='head--doc'>Note</dt> - <dd class='body--doc'>This will clear the data in the buffer + <dd class='body--doc'>Normally you call <code>write</code> to re-trigger the write callback if + you do not output anything in it (which will stop it from + re-occuring again). + This will work with buffered output mode as well, but simply + adding more data to the output buffer will work as well. </dd> <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>get_copy()</code>, <code>clear()</code> + <dd class='body--doc'><code>query_buffer_mode()</code> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - get_copy + set_callbacks </dt> - <dd><code><code class='datatype'>string</code> get_copy()</code></dd> + <dd><code><code class='datatype'>void</code> set_callbacks(<code class='object unresolved'>read_callback_t</code>|<code class='datatype'>void</code> <code class='argument'>read_cb</code>, <code class='object unresolved'>write_callback_t</code>|<code class='datatype'>void</code> <code class='argument'>write_cb</code>, <code class='datatype'>void</code>|<code class='datatype'>function</code>(<code class='datatype'>mixed</code>:<code class='datatype'>int</code>) <code class='argument'>close_cb</code>, <code class='datatype'>void</code>|<code class='datatype'>function</code>(<code class='datatype'>mixed</code>, <code class='datatype'>string</code>:<code class='datatype'>int</code>) <code class='argument'>read_oob_cb</code>, <code class='datatype'>void</code>|<code class='datatype'>function</code>(<code class='datatype'>mixed</code>:<code class='datatype'>int</code>) <code class='argument'>write_oob_cb</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Get the data from the buffer. Significantly slower than <code>get</code>, - but does not clear the buffer. + <dd class='body--doc'>Installs all the specified callbacks at once. Use <code>UNDEFINED</code> + to keep the current setting for a callback. + Like <code>set_nonblocking</code>, the callbacks are installed atomically. + As opposed to <code>set_nonblocking</code>, this function does not do + anything with the stream, and it doesn't even have to be open. </dd> <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>get()</code> + <dd class='body--doc'><code>set_read_callback</code>, <code>set_write_callback</code>, + <code>set_read_oob_callback</code>, <code>set_write_oob_callback</code>, + <code>set_close_callback</code>, <code>query_callbacks</code> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - putchar + set_read_callback + Method + set_write_callback + Method + set_read_oob_callback + Method + set_write_oob_callback + Method + set_close_callback + Method + set_fs_event_callback </dt> - <dd><code><code class='datatype'>void</code> putchar(<code class='datatype'>int</code> <code class='argument'>c</code>)</code></dd> + <dd><code><code class='datatype'>void</code> set_read_callback(<code class='datatype'>function</code>(<code class='datatype'>mixed</code>, <code class='datatype'>string</code>:<code class='datatype'>int</code>) <code class='argument'>read_cb</code>)</code> + <code><code class='datatype'>void</code> set_read_callback(<code class='datatype'>function</code>(<code class='datatype'>mixed</code>, <code class='object unresolved'>Buffer</code>:<code class='datatype'>int</code>) <code class='argument'>read_cb</code>)</code> + <code><code class='datatype'>void</code> set_write_callback(<code class='datatype'>function</code>(<code class='datatype'>mixed</code>:<code class='datatype'>int</code>) <code class='argument'>write_cb</code>)</code> + <code><code class='datatype'>void</code> set_write_callback(<code class='datatype'>function</code>(<code class='datatype'>mixed</code>, <code class='object unresolved'>Buffer</code>:<code class='datatype'>int</code>) <code class='argument'>write_cb</code>)</code> + <code><code class='datatype'>void</code> set_read_oob_callback(<code class='datatype'>function</code>(<code class='datatype'>mixed</code>, <code class='datatype'>string</code>:<code class='datatype'>int</code>) <code class='argument'>read_oob_cb</code>)</code> + <code><code class='datatype'>void</code> set_write_oob_callback(<code class='datatype'>function</code>(<code class='datatype'>mixed</code>:<code class='datatype'>int</code>) <code class='argument'>write_oob_cb</code>)</code> + <code><code class='datatype'>void</code> set_close_callback(<code class='datatype'>function</code>(<code class='datatype'>mixed</code>:<code class='datatype'>int</code>) <code class='argument'>close_cb</code>)</code> + <code><code class='datatype'>void</code> set_fs_event_callback(<code class='datatype'>function</code>(<code class='datatype'>mixed</code>, <code class='datatype'>int</code>:<code class='datatype'>int</code>) <code class='argument'>fs_event_cb</code>, <code class='datatype'>int</code> <code class='argument'>event_mask</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Appends the character <code>c</code> at the end of the string. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - sprintf - </dt> - <dd><code><code class='datatype'>int</code> sprintf(<code class='object unresolved'>strict_sprintf_format</code> <code class='argument'>format</code>, <code class='object unresolved'>sprintf_args</code> ... <code class='argument'>args</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Appends the output from <code>sprintf</code> at the end of the string. - Returns the resulting size of the String.Buffer. - </dd></dl> - </dd></dl><dl><dt><h2 class='header'>Class String.Iterator</h2> - </dt><dd><dl class='group--doc'> - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>An object of this class is returned by <code>get_iterator()</code> when - called with a string. + <dd class='body--doc'>These functions set the various callbacks, which will be called + when various events occur on the stream. A zero as argument will + remove the callback. + A <code>Pike.Backend</code> object is responsible for calling the + callbacks. It requires a thread to be waiting in it to execute + the calls. That means that only one of the callbacks will be + running at a time, so you don't need mutexes between them. + Unless you've specified otherwise with the <code>set_backend</code> + function, the default backend <code>Pike.DefaultBackend</code> will be + used. It's normally activated by returning <code class='expr'>-1</code> from the + <tt>main</tt> function and will then execute in the main thread. + <ul> + <li>When data arrives on the stream, <code>read_cb</code> will be called with + some or all of that data as the second argument. + If the file is in buffer mode, the second argument will be a Buffer. + This will always be the same buffer, so data you do not use in + one read callback can be simply left in the buffer, when new + data arrives it will be appended + </li><li>When the stream has buffer space over for writing, <code>write_cb</code> + will be called so that you can write more data to it. + This callback is also called after the remote end of a socket + connection has closed the write direction. An attempt to write + data to it in that case will generate a <code>System.EPIPE</code> errno. + If the remote end has closed both directions simultaneously + (the usual case), Pike will first attempt to call <code>close_cb</code>, + then this callback (unless <code>close_cb</code> has closed the stream). + If the file is in buffer mode, the second argument will be a Buffer. + You should add data to write to this buffer. + </li><li>When out-of-band data arrives on the stream, <code>read_oob_cb</code> + will be called with some or all of that data as the second + argument. + </li><li>When the stream allows out-of-band data to be sent, + <code>write_oob_cb</code> will be called so that you can write more + out-of-band data to it. + If the OS doesn't separate the write events for normal and + out-of-band data, Pike will try to call <code>write_oob_cb</code> first. + If it doesn't write anything, then <code>write_cb</code> will be tried. + This also means that <code>write_oob_cb</code> might get called when the + remote end of a connection has closed the write direction. + </li><li>When an error or an end-of-stream in the read direction + occurs, <code>close_cb</code> will be called. <code>errno</code> will return the + error, or zero in the case of an end-of-stream. + The name of this callback is rather unfortunate since it + really has nothing to do with a close: The stream is still + open when <code>close_cb</code> is called (you might not be able to read + and/or write to it, but you can still use things like + <code>query_address</code>, and the underlying file descriptor is still + allocated). Also, this callback will not be called for a local + close, neither by a call to <code>close</code> or by destructing this + object. + Also, <code>close_cb</code> will not be called if a remote close only + occurs in the write direction; that is handled by <code>write_cb</code> + (or possibly <code>write_oob_cb</code>). + Events to <code>read_cb</code> and <code>close_cb</code> will be automatically + deregistered if an end-of-stream occurs, and all events in the + case of an error. I.e. there won't be any more calls to the + callbacks unless they are reinstalled. This doesn't affect the + callback settings - <code>query_read_callback</code> et al will still + return the installed callbacks. + </li></ul>If the stream is a socket performing a nonblocking connect (see + <code>open_socket</code> and <code>connect</code>), a connection failure will call + <code>close_cb</code>, and a successful connect will call either + <code>read_cb</code> or <code>write_cb</code> as above. + All callbacks will receive the <tt>id</tt> set by <code>set_id</code> as + first argument. + If a callback returns <code class='expr'>-1</code>, no other callback or call out + will be called by the backend in that round. I.e. the caller of + the backend will get control back right away. For the default + backend that means it will immediately start another round and + check files and call outs anew. </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>get_iterator</code> - </dd></dl> - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Inherit - predef::Iterator - </dt> - <dd><code>inherit predef::Iterator : predef::Iterator</code></dd> - </dl> - </dd></dl><dl><dt><h2 class='header'>Class String.Replace</h2> - </dt><dd><dl class='group--doc'> - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>This is a "compiled" version of the <code>replace</code> function applied on - a string, with more than one replace string. The replace strings - are given to the create method as a from and to array - and are then analyzed. The <code class='expr'>`()</code> is then called with a - string and the replace rules in the Replace object will be - applied. The Replace object is used internally by the Pike - optimizer and need not be used manually. - </dd></dl> - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - _decode - </dt> - <dd><code>String.Replace decode_value(string(8bit) data)</code></dd> - </dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - _encode - </dt> - <dd><code>string(8bit) encode_value(String.Replace data)</code></dd> - </dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - `() - </dt> - <dd><code><code class='datatype'>string</code> res = <code class='class'>String.Replace()</code>()</code></dd> - </dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - create - </dt> - <dd><code>String.Replace String.Replace()</code> - <code>String.Replace String.Replace(<code class='datatype'>mapping</code>(<code class='datatype'>string</code>:<code class='datatype'>string</code>))</code> - <code>String.Replace String.Replace(<code class='datatype'>array</code>(<code class='datatype'>string</code>) <code class='argument'>from</code>, <code class='datatype'>array</code>(<code class='datatype'>string</code>)|<code class='datatype'>string</code> <code class='argument'>to</code>)</code></dd> - </dl> - </dd></dl><dl><dt><h2 class='header'>Class String.SingleReplace</h2> - </dt><dd><dl class='group--doc'> - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>This is a "compiled" version of the <code>replace</code> function applied on - a string, with just one replace string. The replace strings are - given to the create method as a from and tom string and - are then analyzed. The <code class='expr'>`()</code> is then called with a string - and the replace rule in the Replace object will be applied. The - Replace object is used internally by the Pike optimizer and need - not be used manually. - </dd></dl> - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - _decode - </dt> - <dd><code>String.SingleReplace decode_value(string(8bit) data)</code></dd> - </dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - _encode - </dt> - <dd><code>string(8bit) encode_value(String.SingleReplace data)</code></dd> - </dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - `() - </dt> - <dd><code><code class='datatype'>string</code> res = <code class='class'>String.SingleReplace()</code>()</code></dd> - </dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - create - </dt> - <dd><code>String.SingleReplace String.SingleReplace(<code class='datatype'>string</code>|<code class='datatype'>void</code> <code class='argument'>from</code>, <code class='datatype'>string</code>|<code class='datatype'>void</code> <code class='argument'>to</code>)</code></dd> - + <dt class='head--doc'>Parameter <code class='parameter'>event_mask</code></dt> + <dd></dd><dd class='body--doc'>An event mask specifing bitwise OR of one or more event types to + monitor, selected from <code>Stdio.NOTE_WRITE</code> and friends. + </dd> <dt class='head--doc'>Note</dt> - <dd class='body--doc'>May be called with either zero or two arguments. - </dd></dl> - </dd></dl><dl><dt><h2 class='header'>Class String.SplitIterator</h2> - </dt><dd><dl class='group--doc'> - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>An iterator that iterates over substrings of a string, separated - by a character or several different characters. + <dd class='body--doc'>These functions do not set the file nonblocking. </dd> <dt class='head--doc'>Note</dt> - <dd class='body--doc'>Typically you don't need to explicitly use the SplitIterator. - Expressions like the following are automatically optimized into - using a SplitIterator. - <pre><code>foreach(str/"\n", string line) - write("%s\n", line); - </code></pre></dd></dl> - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - create - </dt> - <dd><code>String.SplitIterator String.SplitIterator(<code class='datatype'>string</code> <code class='argument'>buffer</code>, <code class='datatype'>int</code>|<code class='datatype'>array</code>(<code class='datatype'>int</code>)|<code class='datatype'>multiset</code>(<code class='datatype'>int</code>) <code class='argument'>split_set</code>, <code class='datatype'>int</code>|<code class='datatype'>void</code> <code class='argument'>flags</code>, <code class='datatype'>function</code>(:<code class='datatype'>string</code>)|<code class='datatype'>void</code> <code class='argument'>feed</code>)</code></dd> - - <dt class='head--doc'>Parameter <code class='parameter'>buffer</code></dt> - <dd></dd><dd class='body--doc'>The string to split. + <dd class='body--doc'>Callbacks are also set by <code>set_callbacks</code> and + <code>set_nonblocking()</code>. </dd> - <dt class='head--doc'>Parameter <code class='parameter'>split_set</code></dt> - <dd></dd><dd class='body--doc'>The character or characters to split on. + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>After a callback has been called, it's disabled until it has + accessed the stream accordingly, i.e. the <code>write_cb</code> callback + is disabled after it's been called until something has been + written with <code>write</code>, and the <code>write_oob_cb</code> callback is + likewise disabled until something has been written with + <code>write_oob</code>. Since the data already has been read when the read + callbacks are called, this effect is not noticeable for them. </dd> - <dt class='head--doc'>Parameter <code class='parameter'>flags</code></dt> - <dd></dd><dd class='body--doc'>Skip empty elements if set. + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>Installing callbacks means that you will start doing I/O on the + stream from the thread running the backend. If you are running + these set functions from another thread you must be prepared + that the callbacks can be called immediately by the backend + thread, so it might not be safe to continue using the stream in + this thread. + Because of that, it's useful to talk about "callback mode" when + any callback is installed. In callback mode the stream should be + seen as "bound" to the backend thread. For instance, it's only + the backend thread that reliably can end callback mode before + the stream is "handed over" to another thread. </dd> - <dt class='head--doc'>Parameter <code class='parameter'>feed</code></dt> - <dd></dd><dd class='body--doc'>Callback function that is called once the <code>buffer</code> is used up - and the SplitIterator wants more data. + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>Callback mode has nothing to do with nonblocking mode - although + the two often are used together they don't have to be. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>The file object will stay referenced from the backend object as + long as there are callbacks that can receive events. + </dd> + <dt class='head--doc'>Bugs</dt> + <dd class='body--doc'>Setting a close callback without a read callback currently only + works when there's no risk of getting more data on the stream. + Otherwise the close callback will be silently deregistered if + data arrives. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>fs_event callbacks only trigger on systems that support these events. + Currently, this includes systems that use kqueue, such as Mac OS X, + and various flavours of BSD. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>set_callbacks</code>, <code>set_nonblocking()</code>, <code>set_id()</code>, + <code>set_backend</code>, <code>query_read_callback</code>, <code>query_write_callback</code>, + <code>query_read_oob_callback</code>, <code>query_write_oob_callback</code>, + <code>query_close_callback</code> </dd></dl> <hr /> <dl class='group--doc'> - <dt class='head--type'>Inherit - predef::Iterator - </dt> - <dd><code>inherit predef::Iterator : predef::Iterator</code></dd> - </dl> - </dd></dl><dl><dt><h2 class='header'>Module String.Elite</h2> - </dt><dd> - - <hr /> - <dl class='group--doc'> + <dt class='head--type'>Method - elite_string + set_id </dt> - <dd><code><code class='datatype'>string</code> elite_string(<code class='datatype'>string</code> <code class='argument'>in</code>, <code class='datatype'>void</code>|<code class='datatype'>int(0..100)</code> <code class='argument'>leetp</code>, <code class='datatype'>void</code>|<code class='datatype'>bool</code> <code class='argument'>eightbit</code>)</code></dd> + <dd><code><code class='datatype'>void</code> set_id(<code class='datatype'>mixed</code> <code class='argument'>id</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Translates a string to 1337. The optional - argument leetp is the maximum percentage of - leetness (100=max leet, 0=no leet). - The translation is performed in three steps, - first the neccesary elite translations (picture -> pic, - cool->kewl etc), then optional translations - (ok->k, dude->dood, -ers -> -orz), then - calls elite_word on the resulting words. + <dd class='body--doc'>This function sets the <tt>id</tt> of this file. The <tt>id</tt> is mainly + used as an identifier that is sent as the first argument to all + callbacks. The default <tt>id</tt> is <code class='expr'>0</code> (zero). Another possible + use of the <tt>id</tt> is to hold all data related to this file in a + mapping or array. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>query_id()</code> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - elite_word + set_nonblocking </dt> - <dd><code><code class='datatype'>string</code> elite_word(<code class='datatype'>string</code> <code class='argument'>in</code>, <code class='datatype'>void</code>|<code class='datatype'>int(0..100)</code> <code class='argument'>leetp</code>, <code class='datatype'>void</code>|<code class='datatype'>int(0..2)</code> <code class='argument'>eightbit</code>)</code></dd> + <dd><code><code class='datatype'>void</code> set_nonblocking(<code class='object unresolved'>read_callback_t</code> <code class='argument'>read_callback</code>, <code class='object unresolved'>write_callback_t</code> <code class='argument'>write_callback</code>, <code class='datatype'>function</code>(<code class='datatype'>mixed</code>:<code class='datatype'>int</code>) <code class='argument'>close_callback</code>)</code> + <code><code class='datatype'>void</code> set_nonblocking(<code class='object unresolved'>read_callback_t</code> <code class='argument'>read_callback</code>, <code class='object unresolved'>write_callback_t</code> <code class='argument'>write_callback</code>, <code class='datatype'>function</code>(<code class='datatype'>mixed</code>:<code class='datatype'>int</code>) <code class='argument'>close_callback</code>, <code class='datatype'>function</code>(<code class='datatype'>mixed</code>, <code class='datatype'>string</code>:<code class='datatype'>int</code>) <code class='argument'>read_oob_callback</code>, <code class='datatype'>function</code>(<code class='datatype'>mixed</code>:<code class='datatype'>int</code>) <code class='argument'>write_oob_callback</code>)</code> + <code><code class='datatype'>void</code> set_nonblocking()</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Translates one word to 1337. The optional - argument leetp is the maximum percentage of - leetness (100=max leet, 0=no leet). - elite_word only do character-based translation, - for instance from "k" to "|<", but no language - translation (no "cool" to "kewl"). - </dd></dl> - </dd></dl><dl><dt><h2 class='header'>Module String.HTML</h2> - </dt><dd><dl class='group--doc'> - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Functions that helps generating HTML. All functions generates - HTML that is XHTML compliant as well as backwards compatible - with old HTML standards in what extent is possible. - </dd></dl> - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - pad_rows - </dt> - <dd><code><code class='datatype'>array</code>(<code class='datatype'>array</code>(<code class='datatype'>string</code>)) pad_rows(<code class='datatype'>array</code>(<code class='datatype'>array</code>(<code class='datatype'>string</code>)) <code class='argument'>rows</code>, <code class='datatype'>void</code>|<code class='datatype'>string</code> <code class='argument'>padding</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Pads out the rows in a array of rows to equal length. The new elements in - the rows will have the value provided in <code>padding</code>, or "&nbsp;". - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - select - </dt> - <dd><code><code class='datatype'>string</code> select(<code class='datatype'>string</code> <code class='argument'>name</code>, <code class='datatype'>array</code>(<code class='datatype'>string</code>)|<code class='datatype'>array</code>(<code class='datatype'>array</code>(<code class='datatype'>string</code>)) <code class='argument'>choices</code>, <code class='datatype'>void</code>|<code class='datatype'>string</code> <code class='argument'>selected</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Creates an HTML select list. + <dd class='body--doc'>This function sets a stream to nonblocking mode and installs the + specified callbacks. See the <code class='expr'>set_*_callback</code> functions + for details about them. If no arguments are given, the callbacks + will be cleared. </dd> - <dt class='head--doc'>Parameter <code class='parameter'>name</code></dt> - <dd></dd><dd class='body--doc'>The name of the select list. Will be used in the name attribute - of the select element. + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>As opposed to calling the set callback functions separately, + this function will set all the callbacks and nonblocking mode + atomically so that no callback gets called in between. That + avoids races in case the backend is executed by another thread. </dd> - <dt class='head--doc'>Parameter <code class='parameter'>choices</code></dt> - <dd></dd><dd class='body--doc'>May either be an array of strings, where each string is a choice, - or an array of pairs. A pair is an array with two strings. The - first string is the value of the choice while the second string - is the presentation text associated with the value. + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>Out-of-band data was not be supported on Pike 0.5 and earlier, + and not on Pike 0.6 through 7.4 if they were compiled with the + option <tt>'--without-oob'</tt>. </dd> - <dt class='head--doc'>Parameter <code class='parameter'>selected</code></dt> - <dd></dd><dd class='body--doc'>The value that should be selected by default, if any. - </dd> - <dt class='head--doc'>Example</dt> - <dd class='example'><pre>select("language", - ({ ({ "eng", "English" }), - ({ "swe", "Swedish" }), - ({ "nor", "Norwegian" }) }), - "swe"); - </pre></dd></dl> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>set_blocking()</code>, <code>set_callbacks</code>, <code>set_read_callback()</code>, + <code>set_write_callback()</code>, <code>set_read_oob_callback()</code>, + <code>set_write_oob_callback()</code>, <code>set_close_callback()</code> + <code>set_nonblocking_keep_callbacks()</code>, + <code>set_blocking_keep_callbacks()</code> + </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - simple_obox + tcgetattr + Method + tcsetattr </dt> - <dd><code><code class='datatype'>string</code> simple_obox(<code class='datatype'>array</code>(<code class='datatype'>array</code>(<code class='datatype'>string</code>)) <code class='argument'>rows</code>, <code class='datatype'>void</code>|<code class='datatype'>string</code> <code class='argument'>frame_color</code>, <code class='datatype'>void</code>|<code class='datatype'>string</code> <code class='argument'>cell_color</code>, <code class='datatype'>void</code>|<code class='datatype'>string</code> <code class='argument'>width</code>, <code class='datatype'>void</code>|<code class='datatype'>string</code> <code class='argument'>padding</code>, <code class='datatype'>void</code>|<code class='datatype'>function</code>(<code class='datatype'>int</code>, <code class='datatype'>int</code>, <code class='datatype'>string</code>, <code class='datatype'>string</code>:<code class='datatype'>string</code>) <code class='argument'>cell_callback</code>)</code></dd> + <dd><code><code class='datatype'>mapping</code> tcgetattr()</code> + <code><code class='datatype'>int</code> tcsetattr(<code class='datatype'>mapping</code> <code class='argument'>attr</code>)</code> + <code><code class='datatype'>int</code> tcsetattr(<code class='datatype'>mapping</code> <code class='argument'>attr</code>, <code class='datatype'>string</code> <code class='argument'>when</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>This function should solve most of the obox needs that arises. It - creates a table out of the array of arrays of strings fed into it. - The tables will (with default settings) have a thin black outline - around the table and between its cells. Much effort has gone into - finding a simple HTML reresentation of such obox that is rendered - in a similar way in all popular browsers. The current - implementation has been tested against IE, Netscape, Mozilla, - Opera and Konquest. + <dd class='body--doc'>Gets/sets term attributes. The returned value/the <code>attr</code> parameter + is a mapping on the form + <table class='box'><tr><td><code><code class='key'>"ispeed"</code> : <code class='datatype'>int(-1..)</code></code></td><td>In baud rate. + </td></tr> + <tr><td><code><code class='key'>"ospeed"</code> : <code class='datatype'>int(-1..)</code></code></td><td>Out baud rate. + </td></tr> + <tr><td><code><code class='key'>"csize"</code> : <code class='datatype'>int(-1..-1)</code>|<code class='datatype'>int(5..8)</code></code></td><td>Character size in bits. + </td></tr> + <tr><td><code><code class='key'>"rows"</code> : <code class='datatype'>int</code></code></td><td>Terminal rows. + </td></tr> + <tr><td><code><code class='key'>"columns"</code> : <code class='datatype'>int</code></code></td><td>Terminal columns. + </td></tr> + <tr><td><code><code class='key'>flag_name</code> : <code class='datatype'>bool</code></code></td><td>The value of a named flag. The flag name is + the string describing the termios flags (IGNBRK, BRKINT, + IGNPAR, PARMRK, INPCK, ISTRIP, INLCR, IGNCR, ICRNL, IUCLC, + IXON, IXANY, IXOFF, IMAXBEL, OPOST, OLCUC, ONLCR, OCRNL, + ONOCR, ONLRET, OFILL, OFDEL, OXTABS, ONOEOT, CSTOPB, CREAD, + PARENB, PARODD, HUPCL, CLOCAL, CRTSCTS, ISIG, ICANON, XCASE, + ECHO, ECHOE, ECHOK, ECHONL, ECHOCTL, ECHOPRT, ECHOKE, FLUSHO, + NOFLSH, TOSTOP, PENDIN). See the manpage for termios or + other documentation for more information. All flags are not + available on all platforms. + </td></tr> + <tr><td><code><code class='key'>character_name</code> : <code class='datatype'>int(8bit)</code></code></td><td>Sets the value of a control character (VINTR, VQUIT, VERASE, + VKILL, VEOF, VTIME, VMIN, VSWTC, VSTART, VSTOP, VSUSP, VEOL, + VREPRINT, VDISCARD, VWERASE, VLNEXT, VEOL2). All control + characters are not available on all platforms. + </td></tr> + </table>Negative values are not allowed as indata, but might appear in the + result from <code>tcgetattr</code> when the actual value is unknown. <code>tcsetattr</code> + returns 0 if failed. + The argument <code>when</code> to <code>tcsetattr</code> describes when the + changes are to take effect: + <table class='box'><tr><td><code><code class='key'>"TCSANOW"</code></code></td><td>The change occurs immediately (default). + </td></tr> + <tr><td><code><code class='key'>"TCSADRAIN"</code></code></td><td>The change occurs after all output has been written. + </td></tr> + <tr><td><code><code class='key'>"TCSAFLUSH"</code></code></td><td>The change occurs after all output has been written, + and empties input buffers. + </td></tr> + </table> </dd> - <dt class='head--doc'>Parameter <code class='parameter'>rows</code></dt> - <dd></dd><dd class='body--doc'>Simply an array of arrays with strings. The strings are the - values that should appear in the table cells. All rows should - have equal number of cells, otherwise the result will not be - very eye pleasing. - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>frame_color</code></dt> - <dd></dd><dd class='body--doc'>The color of the surrounding frame. Defaults to "#000000". - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>cell_color</code></dt> - <dd></dd><dd class='body--doc'>The background color of the cells. Defaults to "#ffffff". - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>width</code></dt> - <dd></dd><dd class='body--doc'>The border width. Defaults to "1". - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>padding</code></dt> - <dd></dd><dd class='body--doc'>The amount of padding in each cell. Defaults to "3". - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>cell_callback</code></dt> - <dd></dd><dd class='body--doc'>If provided, the cell callback will be called for each cell. As - in parameters it will get the current x and y coordinates in the - table. The upper left cell is 0,0. In addition to the - coordinates it will also receive the background color and the - contents of the current cell. It is expected to return a - td-element. - </dd> + <dt class='head--doc'>Example</dt> - <dd class='example'><pre>function cb = lambda(int x, int y, string bgcolor, string contents) { - if(y%2) return "<td bgcolor='#aaaaff'>"+contents+"</td>"; - return "<td bgcolor='"+bgcolor+"'>"+contents+"</td>"; - } - simple_obox(my_rows, "#0000a0", 0, "1", "3", cb); + <dd class='example'><pre>// setting the terminal in raw mode: + Stdio.stdin->tcsetattr((["ECHO":0,"ICANON":0,"VMIN":0,"VTIME":0])); </pre></dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>pad_rows</code> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>Unknown flags are ignored by <code>tcsetattr()</code>. <code>tcsetattr</code> always + changes the attribute, so only include attributes that actually + should be altered in the attribute mapping. + </dd> + <dt class='head--doc'>Bugs</dt> + <dd class='body--doc'>Terminal rows and columns setting by <code>tcsetattr()</code> is not + currently supported. </dd></dl> - <dl><dt><h2 class='header'>Class String.HTML.OBox</h2> + </dd></dl><dl><dt><h2 class='header'>Class Stdio.FILE</h2> </dt><dd><dl class='group--doc'> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Provides the same functionality as the <code>simple_obox</code> function, - in a "streaming" way. The real gain is different addtition methods - as well as the possibility to change the cell callback at any time. + <dd class='body--doc'><code>Stdio.FILE</code> is a buffered version of <code>Stdio.File</code>, it inherits + <code>Stdio.File</code> and has most of the functionality of <code>Stdio.File</code>. + However, it has an input buffer that allows line-by-line input. + It also has support for automatic charset conversion for both input + and output (see <code>Stdio.FILE()->set_charset()</code>). </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'>simple_obox + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>The output part of <code>Stdio.FILE</code> is currently not buffered. </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - add_cell + _get_iterator </dt> - <dd><code><code class='datatype'>void</code> add_cell(<code class='datatype'>string</code> <code class='argument'>contents</code>)</code></dd> + <dd><code>Stdio.FILE a; + foreach( a; index; value ) or </code><code><code class='modifier'>protected</code> <code class='datatype'>object</code> _get_iterator()</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Adds a cell with the provided content. + <dd class='body--doc'>Returns an iterator that will loop over the lines in this file. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>line_iterator()</code> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - add_raw_cell + getchar </dt> - <dd><code><code class='datatype'>void</code> add_raw_cell(<code class='datatype'>string</code> <code class='argument'>cell</code>)</code></dd> + <dd><code><code class='modifier'>local</code> <code class='datatype'>int</code> getchar()</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Adds this cell to the table unmodified, e.g. it should have an enclosing - td or th element. + <dd class='body--doc'>This function returns one character from the input stream. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>Returns the ISO-10646 (Unicode) value of the character. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>Returns an <code class='expr'>int</code> and not a <code class='expr'>string</code> of length 1. </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - add_row + gets </dt> - <dd><code><code class='datatype'>void</code> add_row(<code class='datatype'>array</code>(<code class='datatype'>string</code>) <code class='argument'>cells</code>)</code></dd> + <dd><code><code class='datatype'>string</code> gets(<code class='datatype'>bool</code>|<code class='datatype'>void</code> <code class='argument'>not_all</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Adds a complete row. If the current row is nonempty a - new row will be started. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - add_tagdata_cell - </dt> - <dd><code><code class='datatype'>void</code> add_tagdata_cell(<code class='datatype'>string</code> <code class='argument'>tag</code>, <code class='datatype'>mapping</code>(<code class='datatype'>string</code>:<code class='datatype'>string</code>) <code class='argument'>args</code>, <code class='datatype'>string</code> <code class='argument'>contents</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Creates a cell from the provided arguments and adds it to the table. + <dd class='body--doc'>Read one line of input with support for input conversion. </dd> - <dt class='head--doc'>Parameter <code class='parameter'>tag</code></dt> - <dd></dd><dd class='body--doc'>The name of the element that should be produces. Typically - "td" or "th". + <dt class='head--doc'>Parameter <code class='parameter'>not_all</code></dt> + <dd></dd><dd class='body--doc'>Set this parameter to ignore partial lines at EOF. This + is useful for eg monitoring a growing logfile. </dd> - <dt class='head--doc'>Parameter <code class='parameter'>args</code></dt> - <dd></dd><dd class='body--doc'>A mapping with the elements attributes. + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>This function returns the line read if successful, and <code class='expr'>0</code> if + no more lines are available. </dd> - <dt class='head--doc'>Parameter <code class='parameter'>contents</code></dt> - <dd></dd><dd class='body--doc'>The element contents. + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>ngets()</code>, <code>read()</code>, <code>line_iterator()</code>, <code>set_charset()</code> </dd></dl> <hr /> <dl class='group--doc'> - <dt class='head--type'>Method - cast + <dt class='head--type'>Inherit + file </dt> - <dd><code>(int)String.HTML.OBox() (float)String.HTML.OBox() (string)String.HTML.OBox() (array)String.HTML.OBox() (mapping)String.HTML.OBox() (multiset)String.HTML.OBox()</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>It is possible to case this object to a string, which does the same - as calling <code>render</code>, and to an array, which returns the cells in an - array of rows. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - create - </dt> - <dd><code>String.HTML.OBox String.HTML.OBox(<code class='datatype'>void</code>|<code class='datatype'>string</code> <code class='argument'>frame_color</code>, <code class='datatype'>void</code>|<code class='datatype'>string</code> <code class='argument'>cell_color</code>, <code class='datatype'>void</code>|<code class='datatype'>string</code> <code class='argument'>width</code>, <code class='datatype'>void</code>|<code class='datatype'>string</code> <code class='argument'>padding</code>, <code class='datatype'>void</code>|<code class='datatype'>function</code>(<code class='datatype'>int</code>, <code class='datatype'>int</code>, <code class='datatype'>string</code>, <code class='datatype'>string</code>:<code class='datatype'>string</code>) <code class='argument'>cell_callback</code>)</code></dd> + <dd><code>inherit File : file</code></dd> </dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - new_row + line_iterator </dt> - <dd><code><code class='datatype'>void</code> new_row()</code></dd> + <dd><code><code class='datatype'>object</code> line_iterator(<code class='datatype'>int</code>|<code class='datatype'>void</code> <code class='argument'>trim</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Begin a new row. Succeeding cells will be added to this - row instead of the current. + <dd class='body--doc'>Returns an iterator that will loop over the lines in this file. + If <code>trim</code> is true, all <tt>'\r'</tt> characters will be removed + from the input. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>It's not supported to call this method more than once + unless a call to <code>seek</code> is done in advance. Also note that it's + not possible to intermingle calls to <code>read</code>, <code>gets</code> or other + functions that read data with the line iterator, it will produce + unexpected results since the internal buffer in the iterator will not + contain sequential file-data in those cases. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>_get_iterator()</code> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - pad_rows + ngets </dt> - <dd><code><code class='datatype'>void</code> pad_rows()</code></dd> + <dd><code><code class='datatype'>array</code>(<code class='datatype'>string</code>) ngets(<code class='datatype'>void</code>|<code class='datatype'>int(1..)</code> <code class='argument'>n</code>, <code class='datatype'>bool</code>|<code class='datatype'>void</code> <code class='argument'>not_all</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Ensures that all rows have the same number of cells. + <dd class='body--doc'>Get <code>n</code> lines. + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>n</code></dt> + <dd></dd><dd class='body--doc'>Number of lines to get, or all remaining if zero. + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>not_all</code></dt> + <dd></dd><dd class='body--doc'>Set this parameter to ignore partial lines at EOF. This + is useful for eg monitoring a growing logfile. </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - render + openat </dt> - <dd><code><code class='datatype'>string</code> render()</code></dd> + <dd><code><code class='object unresolved'>FILE</code> openat(<code class='datatype'>string</code> <code class='argument'>filename</code>, <code class='datatype'>string</code> <code class='argument'>mode</code>)</code> + <code><code class='object unresolved'>FILE</code> openat(<code class='datatype'>string</code> <code class='argument'>filename</code>, <code class='datatype'>string</code> <code class='argument'>mode</code>, <code class='datatype'>int</code> <code class='argument'>mask</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Returns the result. + <dd class='body--doc'>Same as <code>Stdio.File()->openat()</code>, but returns an <code>Stdio.FILE</code> + object. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>Stdio.File()->openat()</code> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - set_cell_callback + pipe </dt> - <dd><code><code class='datatype'>void</code> set_cell_callback(<code class='datatype'>function</code>(<code class='datatype'>int</code>, <code class='datatype'>int</code>, <code class='datatype'>string</code>, <code class='datatype'>string</code>:<code class='datatype'>string</code>) <code class='argument'>cell_callback</code>)</code></dd> - </dl> + <dd><code><code class='object unresolved'>FILE</code> pipe(<code class='datatype'>void</code>|<code class='datatype'>int</code> <code class='argument'>flags</code>)</code></dd> - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - set_extra_args - </dt> - <dd><code><code class='datatype'>void</code> set_extra_args(<code class='datatype'>array</code>(<code class='datatype'>mapping</code>(<code class='datatype'>string</code>:<code class='datatype'>string</code>)) <code class='argument'>extra_args</code>)</code></dd> - + <dt class='head--doc'>Description</dt> - <dd class='body--doc'>The argument in the mappings will be added to the cell in the - cooresponding column of the table. + <dd class='body--doc'>Same as <code>Stdio.File()->pipe()</code>, but returns an <code>Stdio.FILE</code> + object. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>Stdio.File()->pipe()</code> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - set_extra_args + printf </dt> - <dd><code><code class='datatype'>void</code> set_extra_args(<code class='datatype'>mapping</code>(<code class='datatype'>string</code>:<code class='datatype'>string</code>) <code class='argument'>extra_args</code>)</code></dd> + <dd><code><code class='datatype'>int</code> printf(<code class='datatype'>string</code> <code class='argument'>format</code>, <code class='datatype'>mixed</code> ... <code class='argument'>data</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>The argument in the mapping will be added to all created table cells. + <dd class='body--doc'>This function does approximately the same as: + <code class='expr'><code>write</code>(<code>sprintf</code>(<code>format</code>,@<code>data</code>))</code>. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>write()</code>, <code>sprintf()</code> </dd></dl> - </dd></dl></dd></dl></dd></dl><dl><dt><h2 class='header'>Module Array</h2> - </dt><dd><dl class='group--doc'> - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>General functions to operate on arrays. - </dd></dl> + - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - all + read </dt> - <dd><code><code class='datatype'>bool</code> all(<code class='datatype'>array</code> <code class='argument'>a</code>, <code class='datatype'>function</code>(<code class='datatype'>int(0..0)</code>, <code class='datatype'>mixed</code> ... :<code class='datatype'>mixed</code>) <code class='argument'>predicate</code>, <code class='datatype'>mixed</code> ... <code class='argument'>extra_args</code>)</code></dd> + <dd><code><code class='datatype'>string</code> read(<code class='datatype'>int</code>|<code class='datatype'>void</code> <code class='argument'>bytes</code>, <code class='datatype'>void</code>|<code class='datatype'>bool</code> <code class='argument'>now</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Returns 1 if all of the elements in <code>a</code> fulfills the requirement - <code>predicate</code>( <code>a</code>[i], @<code>extra_args</code> ), otherwise 0. The - predicate should return non-zero for an element that meets the - requirements and zero for those that do not. + <dd class='body--doc'>Read <code>bytes</code> (wide-) characters with buffering and support for + input conversion. </dd> - <dt class='head--doc'>Example</dt> - <dd class='example'><pre>Array.all( ({ 2, 4, 6, 8 }), `<, 17 ) - </pre></dd> + <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>any</code>, <code>has_value</code> + <dd class='body--doc'><code>Stdio.File()->read()</code>, <code>set_charset()</code>, <code>unread()</code> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - any + set_charset </dt> - <dd><code><code class='datatype'>bool</code> any(<code class='datatype'>array</code> <code class='argument'>a</code>, <code class='datatype'>function</code>(<code class='datatype'>int(0..0)</code>, <code class='datatype'>mixed</code> ... :<code class='datatype'>mixed</code>) <code class='argument'>predicate</code>, <code class='datatype'>mixed</code> ... <code class='argument'>extra_args</code>)</code></dd> + <dd><code><code class='datatype'>void</code> set_charset(<code class='datatype'>string</code>|<code class='datatype'>void</code> <code class='argument'>charset</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Returns 1 if any of the elements in <code>a</code> fulfills the requirement - <code>predicate</code>( <code>a</code>[i], @<code>extra_args</code> ), otherwise 0. The - predicate should return non-zero for an element that meets the - requirements and zero for those that do not. - </dd> - <dt class='head--doc'>Example</dt> - <dd class='example'><pre>Array.any( ({ 2, 4, 6, 8 }), `>, 5 ) - </pre></dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>all</code>, <code>has_value</code> + <dd class='body--doc'>Sets the input and output charset of this file to the specified + <code>charset</code>. If <code>charset</code> is 0 or not specified the environment + is used to try to detect a suitable charset. + The default charset if this function is not called is + <tt>"ISO-8859-1"</tt>. + </dd><dt class='head--fixme'>FIXME</dt> + <dd class='body--fixme'>Consider using one of + ISO-IR-196 (<tt>"\e%G"</tt> - switch to UTF-8 with return) + or ISO-IR-190 (<tt>"\e%/G"</tt> - switch to UTF-8 level 1 no return) + or ISO-IR-191 (<tt>"\e%/H"</tt> - switch to UTF-8 level 2 no return) + or ISO-IR-192 (<tt>"\e%/I"</tt> - switch to UTF-8 level 3 no return) + or ISO-IR-193 (<tt>"\e%/J"</tt> - switch to UTF-16 level 1 no return) + or ISO-IR-194 (<tt>"\e%/K"</tt> - switch to UTF-16 level 2 no return) + or ISO-IR-195 (<tt>"\e%/L"</tt> - switch to UTF-16 level 3 no return) + or ISO-IR-162 (<tt>"\e%/@"</tt> - switch to UCS-2 level 1) + or ISO-IR-163 (<tt>"\e%/A"</tt> - switch to UCS-4 level 1) + or ISO-IR-174 (<tt>"\e%/C"</tt> - switch to UCS-2 level 2) + or ISO-IR-175 (<tt>"\e%/D"</tt> - switch to UCS-4 level 2) + or ISO-IR-176 (<tt>"\e%/E"</tt> - switch to UCS-2 level 3) + or ISO-IR-177 (<tt>"\e%/F"</tt> - switch to UCS-4 level 3) + or ISO-IR-178 (<tt>"\e%B"</tt> - switch to UTF-1) + automatically to encode wide strings. </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - arrayify + ungets </dt> - <dd><code><code class='datatype'>array</code> arrayify(<code class='datatype'>void</code>|<code class='datatype'>array</code>|<code class='datatype'>mixed</code> <code class='argument'>x</code>)</code></dd> + <dd><code><code class='datatype'>void</code> ungets(<code class='datatype'>string</code> <code class='argument'>s</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Make an array of the argument, if it isn't already. An undefined - argument gives the empty array. This is useful when something is - either an array or a basic datatype, for instance in headers from - the MIME module or Protocols.HTTP.Server. + <dd class='body--doc'>This function puts a line back in the input buffer. The line + can then be read with eg <code>read()</code>, <code>gets()</code> or <code>getchar()</code>. </dd> - <dt class='head--doc'>Parameter <code class='parameter'>x</code></dt> - <dd></dd><dd class='body--doc'>Result depends of the argument type: - <dl class='group--doc'><dt>arrayp(x)</dt> - <dd>arrayify(x) => x + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>The string is autoterminated by an extra line-feed. </dd> - <dt>undefinedp(x)</dt> - <dd>arrayify(x) => ({}) - </dd> - <dt>otherwise</dt> - <dd>arrayify(x) => ({ x }) - </dd> - </dl> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>read()</code>, <code>gets()</code>, <code>getchar()</code>, <code>unread()</code> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - columns + unread </dt> - <dd><code><code class='datatype'>array</code>(<code class='datatype'>array</code>) columns(<code class='datatype'>array</code> <code class='argument'>x</code>, <code class='datatype'>array</code> <code class='argument'>ind</code>)</code></dd> + <dd><code><code class='datatype'>void</code> unread(<code class='datatype'>string</code> <code class='argument'>s</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Get multiple columns from an array. - This function is equvivalent to - <pre> - map(ind, lambda(mixed i) { return column(x, i); }) - </pre> + <dd class='body--doc'>This function puts a string back in the input buffer. The string + can then be read with eg <code>read()</code>, <code>gets()</code> or <code>getchar()</code>. </dd> <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>column()</code> + <dd class='body--doc'><code>read()</code>, <code>gets()</code>, <code>getchar()</code>, <code>ungets()</code> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - combinations + write </dt> - <dd><code><code class='datatype'>array</code>(<code class='datatype'>array</code>) combinations(<code class='datatype'>array</code> <code class='argument'>arr</code>, <code class='datatype'>int</code> <code class='argument'>len</code>)</code></dd> + <dd><code><code class='datatype'>int</code> write(<code class='datatype'>array</code>(<code class='datatype'>string</code>)|<code class='datatype'>string</code> <code class='argument'>what</code>, <code class='datatype'>mixed</code> ... <code class='argument'>fmt</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Returns an array of all combinations of length <code>len</code> of - elements from <code>arr</code>. + <dd class='body--doc'>Write <code>what</code> with support for output_conversion. </dd> <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>permute()</code> + <dd class='body--doc'><code>Stdio.File()->write()</code> </dd></dl> - + </dd></dl><dl><dt><h2 class='header'>Class Stdio.Port</h2> + </dt><dd><dl class='group--doc'> + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Handles listening to socket ports. Whenever you need a bound + socket that is open and listens for connections you should + use this program. + </dd></dl> - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - common_prefix + accept </dt> - <dd><code><code class='datatype'>array</code> common_prefix(<code class='datatype'>array</code>(<code class='datatype'>array</code>) <code class='argument'>arrs</code>)</code></dd> + <dd><code><code class='object unresolved'>File</code> accept()</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Find the longest common prefix from an array of arrays. + <dd class='body--doc'>This function completes a connection made from a remote machine to + this port. It returns a two-way stream in the form of a clone of + <code>Stdio.File</code>. The new file is by initially set to blocking mode. </dd> <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>String.common_prefix</code> + <dd class='body--doc'><code>Stdio.File</code> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - compact_diff3 + accept </dt> - <dd><code><code class='datatype'>array</code>(<code class='datatype'>array</code>(<code class='datatype'>array</code>)) compact_diff3(<code class='datatype'>array</code> <code class='argument'>a</code>, <code class='datatype'>array</code> <code class='argument'>b</code>, <code class='datatype'>array</code> <code class='argument'>old</code>)</code></dd> + <dd><code><code class='object unresolved'>Stdio.File</code> accept()</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Given three arrays like those returned from <code>diff3</code>, this - function "compacts" the diff3 result by removing all differences - where <tt>a</tt> and <tt>b</tt> agrees against <tt>old</tt>. The result is - on the same form as the result from <code>diff</code>, and doesn't - include the sequence from <tt>old</tt>. + <dd class='body--doc'>Get the first connection request waiting for this port and return + it as a connected socket. + If no connection request is waiting and the port is in nonblocking + mode (i.e. an accept callback is installed) then zero is returned. + Otherwise this function waits until a connection has arrived. + In Pike 7.8 and later the returned object is created via <code>fd_factory()</code>. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>In Pike 7.7 and later the resulting file object will be assigned + to the same backend as the port object. </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - count + bind </dt> - <dd><code><code class='datatype'>int</code> count(<code class='datatype'>array</code>|<code class='datatype'>mapping</code>|<code class='datatype'>multiset</code> <code class='argument'>haystack</code>, <code class='datatype'>mixed</code> <code class='argument'>needle</code>)</code> - <code><code class='datatype'>mapping</code>(<code class='datatype'>mixed</code>:<code class='datatype'>int</code>) count(<code class='datatype'>array</code>|<code class='datatype'>mapping</code>|<code class='datatype'>multiset</code> <code class='argument'>haystack</code>)</code></dd> + <dd><code><code class='datatype'>int</code> bind(<code class='datatype'>int</code>|<code class='datatype'>string</code> <code class='argument'>port</code>, <code class='datatype'>void</code>|<code class='datatype'>function</code>(:<code class='datatype void'>void</code>) <code class='argument'>accept_callback</code>, <code class='datatype'>void</code>|<code class='datatype'>string</code> <code class='argument'>ip</code>, <code class='datatype'>void</code>|<code class='datatype'>string</code> <code class='argument'>reuse_port</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Returns the number of occurrences of <code>needle</code> in <code>haystack</code>. - If the optional <code>needle</code> argument is omitted, <code>count</code> instead - works similar to the unix command <tt>sort|uniq -c</tt>, returning - a mapping with the number of occurrences of each element in - <code>haystack</code>. For array or mapping <code>haystack</code>s, it's the values - that are counted, for multisets the indices, as you'd expect. + <dd class='body--doc'>Opens a socket and binds it to port number on the local machine. + If the second argument is present, the socket is set to + nonblocking and the callback funcition is called whenever + something connects to it. The callback will receive the id for + this port as argument and should typically call <code>accept</code> to + establish a connection. + If the optional argument <code>ip</code> is given, <code>bind</code> will try to bind + to an interface with that host name or IP number. Omitting this + will bind to all available IPv4 addresses; specifying "::" will + bind to all IPv4 and IPv6 addresses. + If the OS supports TCP_FASTOPEN it is enabled automatically. + If the OS supports SO_REUSEPORT it is enabled if the fourth argument is true. </dd> - + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>1 is returned on success, zero on failure. <code>errno</code> provides + further details about the error in the latter case. + </dd> <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>String.count</code>, <code>search</code>, <code>has_value</code> + <dd class='body--doc'><code>accept</code>, <code>set_id</code> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - diff + bind_unix </dt> - <dd><code><code class='datatype'>array</code>(<code class='datatype'>array</code>(<code class='datatype'>array</code>)) diff(<code class='datatype'>array</code> <code class='argument'>a</code>, <code class='datatype'>array</code> <code class='argument'>b</code>)</code></dd> + <dd><code><code class='datatype'>int</code> bind_unix(<code class='datatype'>string</code> <code class='argument'>path</code>, <code class='datatype'>void</code>|<code class='datatype'>function</code>(:<code class='datatype void'>void</code>) <code class='argument'>accept_callback</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Calculates which parts of the arrays that are common to both, and - which parts that are not. + <dd class='body--doc'>Opens a Unix domain socket at the given path in the file system. + If the second argument is present, the socket is set to + nonblocking and the callback funcition is called whenever + something connects to it. The callback will receive the id for + this port as argument and should typically call <code>accept</code> to + establish a connection. </dd> <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>Returns an array with two elements, the first is an array of parts in - array <code>a</code>, and the second is an array of parts in array <code>b</code>. + <dd class='body--doc'>1 is returned on success, zero on failure. <code>errno</code> provides + further details about the error in the latter case. </dd> - + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>This function is only available on systems that support Unix domain + sockets. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'><code>path</code> had a quite restrictive length limit (~100 characters) + prior to Pike 7.8.334. + </dd> <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>diff_compare_table()</code>, <code>diff_longest_sequence()</code>, - <code>String.fuzzymatch()</code> + <dd class='body--doc'><code>accept</code>, <code>set_id</code> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - diff3 + close </dt> - <dd><code><code class='datatype'>array</code>(<code class='datatype'>array</code>(<code class='datatype'>array</code>)) diff3(<code class='datatype'>array</code> <code class='argument'>a</code>, <code class='datatype'>array</code> <code class='argument'>b</code>, <code class='datatype'>array</code> <code class='argument'>c</code>)</code></dd> + <dd><code><code class='datatype'>void</code> close()</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Return the three-way difference between the arrays. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>Array.diff()</code>, <code>Array.diff_longest_sequence()</code> + <dd class='body--doc'>Closes the socket. </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - diff_compare_table + create </dt> - <dd><code><code class='datatype'>array</code>(<code class='datatype'>array</code>(<code class='datatype'>int</code>)) diff_compare_table(<code class='datatype'>array</code> <code class='argument'>a</code>, <code class='datatype'>array</code> <code class='argument'>b</code>)</code></dd> + <dd><code>Stdio.Port Stdio.Port()</code> + <code>Stdio.Port Stdio.Port(<code class='datatype'>int</code>|<code class='datatype'>string</code> <code class='argument'>port</code>)</code> + <code>Stdio.Port Stdio.Port(<code class='datatype'>int</code>|<code class='datatype'>string</code> <code class='argument'>port</code>, <code class='datatype'>function</code>(:<code class='datatype void'>void</code>) <code class='argument'>accept_callback</code>)</code> + <code>Stdio.Port Stdio.Port(<code class='datatype'>int</code>|<code class='datatype'>string</code> <code class='argument'>port</code>, <code class='datatype'>function</code>(:<code class='datatype void'>void</code>) <code class='argument'>accept_callback</code>, <code class='datatype'>string</code> <code class='argument'>ip</code>)</code> + <code>Stdio.Port Stdio.Port(<code class='argument'>"stdin"</code>)</code> + <code>Stdio.Port Stdio.Port(<code class='argument'>"stdin"</code>, <code class='datatype'>function</code>(:<code class='datatype void'>void</code>) <code class='argument'>accept_callback</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Returns an array which maps from index in <code>a</code> to corresponding - indices in <code>b</code>. - <pre> - > Array.diff_compare_table( ({ "a","b","c" }), ({ "b", "b", "c", "d", "b" })); - Result: ({ - ({ }), - ({ - 0, - 1, - 4 - }), - ({ - 2 - }) - }) - </pre> + <dd class='body--doc'>If the first argument is other than <code class='expr'>"stdin"</code> the arguments will + be passed to <code>bind()</code>. + When create is called with <code class='expr'>"stdin"</code> as the first argument, a + socket is created out of the file descriptor <code class='expr'>0</code>. This is only + useful if it actually is a socket to begin with, and is equivalent to + creating a port and initializing it with <code>listen_fd</code>(0). </dd> <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>diff()</code>, <code>diff_longest_sequence()</code>, <code>String.fuzzymatch()</code> + <dd class='body--doc'><code>bind</code> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - diff_dyn_longest_sequence + create </dt> - <dd><code><code class='datatype'>array</code>(<code class='datatype'>int</code>) diff_dyn_longest_sequence(<code class='datatype'>array</code> <code class='argument'>a</code>, <code class='datatype'>array</code> <code class='argument'>b</code>)</code></dd> + <dd><code>Stdio.Port Stdio.Port(<code class='datatype'>int</code>|<code class='datatype'>string</code> <code class='argument'>port</code>, <code class='datatype'>void</code>|<code class='datatype'>function</code>(:<code class='datatype void'>void</code>) <code class='argument'>accept_callback</code>, <code class='datatype'>void</code>|<code class='datatype'>string</code> <code class='argument'>ip</code>)</code> + <code>Stdio.Port Stdio.Port(<code class='argument'>"stdin"</code>, <code class='datatype'>void</code>|<code class='datatype'>function</code>(:<code class='datatype void'>void</code>) <code class='argument'>accept_callback</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Gives the longest sequence of indices in <code>b</code> that have corresponding - values in the same order in <code>a</code>. - This function performs the same operation as <code>diff_longest_sequence()</code>, - but uses a different algorithm, which in some rare cases might be faster - (usually it's slower though). + <dd class='body--doc'>When called with an int or any string except <code class='expr'>"stdin"</code> as + first argument, this function does the same as <code>bind()</code> would do + with the same arguments. + When called with <code class='expr'>"stdin"</code> as argument, a socket is created + out of the file descriptor 0. This is only useful if that actually + IS a socket to begin with, and is equivalent to creating a port and + initializing it with <code>listen_fd</code>(0). </dd> <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>diff_longest_sequence()</code>, <code>diff()</code>, <code>diff_compare_table()</code>, - <code>String.fuzzymatch()</code> + <dd class='body--doc'><code>bind</code>, <code>listen_fd</code> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - diff_longest_sequence + errno </dt> - <dd><code><code class='datatype'>array</code>(<code class='datatype'>int</code>) diff_longest_sequence(<code class='datatype'>array</code> <code class='argument'>a</code>, <code class='datatype'>array</code> <code class='argument'>b</code>)</code></dd> + <dd><code><code class='datatype'>int</code> errno()</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Gives the longest sequence of indices in <code>b</code> that have corresponding - values in the same order in <code>a</code>. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>diff()</code>, <code>diff_compare_table()</code>, <code>String.fuzzymatch()</code> + <dd class='body--doc'>If the last call done on this port failed, this function will + return an integer describing what went wrong. Refer to your unix + manual for further information. </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - dwim_sort_func + fd_factory </dt> - <dd><code><code class='datatype'>int(-1..1)</code> dwim_sort_func(<code class='datatype'>string</code> <code class='argument'>a</code>, <code class='datatype'>string</code> <code class='argument'>b</code>)</code></dd> + <dd><code><code class='modifier'>protected</code> <code class='object unresolved'>Fd</code> fd_factory()</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Sort without respect to number formatting (most notably leading - zeroes). + <dd class='body--doc'>Factory creating empty <code>Fd</code> objects. + This function is called by <code>accept()</code> when it needs to create + a new file. </dd></dl> <hr /> <dl class='group--doc'> - <dt class='head--type'>Method - everynth + <dt class='head--type'>Inherit + _port </dt> - <dd><code><code class='datatype'>array</code>(<code class='datatype'>mixed</code>) everynth(<code class='datatype'>array</code>(<code class='datatype'>mixed</code>) <code class='argument'>a</code>, <code class='datatype'>void</code>|<code class='datatype'>int</code> <code class='argument'>n</code>, <code class='datatype'>void</code>|<code class='datatype'>int</code> <code class='argument'>start</code>)</code></dd> + <dd><code>inherit _port : _port</code></dd> + </dl> - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Return an array with every <code>n</code>:th element of the array <code>a</code>. - If <code>n</code> is zero every other element will be returned. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>splice()</code>, <code>`/()</code> - </dd></dl> + - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - flatten + listen_fd </dt> - <dd><code><code class='datatype'>array</code> flatten(<code class='datatype'>array</code> <code class='argument'>a</code>, <code class='datatype'>mapping</code>(<code class='datatype'>array</code>:<code class='datatype'>array</code>)|<code class='datatype'>void</code> <code class='argument'>state</code>)</code></dd> + <dd><code><code class='datatype'>int</code> listen_fd(<code class='datatype'>int</code> <code class='argument'>fd</code>, <code class='datatype'>void</code>|<code class='datatype'>function</code>(:<code class='datatype void'>void</code>) <code class='argument'>accept_callback</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Flatten a multi-dimensional array to a one-dimensional array. + <dd class='body--doc'>This function does the same as <code>bind</code>, except that instead of + creating a new socket and bind it to a port, it expects the file + descriptor <code>fd</code> to be an already open port. </dd> <dt class='head--doc'>Note</dt> - <dd class='body--doc'>Prior to Pike 7.5.7 it was not safe to call this function - with cyclic data-structures. + <dd class='body--doc'>This function is only for the advanced user, and is generally used + when sockets are passed to Pike at exec time. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>bind</code>, <code>accept</code> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - greedy_diff + query_address </dt> - <dd><code><code class='datatype'>array</code>(<code class='datatype'>array</code>(<code class='datatype'>array</code>)) greedy_diff(<code class='datatype'>array</code> <code class='argument'>from</code>, <code class='datatype'>array</code> <code class='argument'>to</code>)</code></dd> + <dd><code><code class='datatype'>string</code> query_address()</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Like <code>Array.diff</code>, but tries to generate bigger continuous chunks of the - differences, instead of maximizing the number of difference chunks. More - specifically, <code>greedy_diff</code> optimizes the cases where <code>Array.diff</code> returns - <code class='expr'>({ ..., A, Z, B, ({}), C, ... })</code> - <code class='expr'>({ ..., A, X, B,  Y+B, C, ... })</code> - into the somewhat shorter diff arrays - <code class='expr'>({ ..., A, Z,     B+C, ... })</code> - <code class='expr'>({ ..., A, X+B+Y, B+C, ... })</code> + <dd class='body--doc'>Get the address and port of the local socket end-point. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>This function returns the address and port of a socket end-point + on the form <code class='expr'>"x.x.x.x port"</code> (IPv4) or + <code class='expr'>"x:x:x:x:x:x:x:x port"</code> (IPv6). + If there is some error querying or formatting the address, + <code class='expr'>0</code> (zero) is returned and <code>errno()</code> will return the + error code. + </dd> + <dt class='head--doc'>Throws</dt> + <dd class='body--doc'>An error is thrown if the socket isn't bound. </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - interleave_array + query_backend </dt> - <dd><code><code class='datatype'>array</code>(<code class='datatype'>int</code>) interleave_array(<code class='datatype'>array</code>(<code class='datatype'>mapping</code>(<code class='datatype'>int</code>:<code class='datatype'>mixed</code>)) <code class='argument'>tab</code>)</code></dd> + <dd><code><code class='object unresolved'>Pike.Backend</code> query_backend()</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Interleave a sparse matrix. - Returns an array with offsets that describe how to shift the - rows of <code>tab</code> so that only at most one non-zero value exists in - every column. + <dd class='body--doc'>Return the backend used for the accept callback. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>set_backend</code> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - longest_ordered_sequence + query_fd </dt> - <dd><code><code class='datatype'>array</code>(<code class='datatype'>int</code>) longest_ordered_sequence(<code class='datatype'>array</code> <code class='argument'>a</code>)</code></dd> + <dd><code><code class='datatype'>int</code> query_fd()</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Find the longest ordered sequence of elements. - This function returns an array of the indices in the longest - ordered sequence of elements in the array. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>diff()</code> + <dd class='body--doc'>Returns the file descriptor number associated with this object. </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - lyskom_sort_func + query_id </dt> - <dd><code><code class='datatype'>int(-1..1)</code> lyskom_sort_func(<code class='datatype'>string</code> <code class='argument'>a</code>, <code class='datatype'>string</code> <code class='argument'>b</code>)</code></dd> + <dd><code><code class='datatype'>mixed</code> query_id()</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Sort comparison function that does not care about case, nor about - the contents of any parts of the string enclosed with '()' - Example: "Foo (bar)" is given the same weight as "foo (really!)" + <dd class='body--doc'>This function returns the id for this port. The id is normally the + first argument to accept_callback. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>set_id</code> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - oid_sort_func + set_backend </dt> - <dd><code><code class='datatype'>int(-1..1)</code> oid_sort_func(<code class='datatype'>string</code> <code class='argument'>a</code>, <code class='datatype'>string</code> <code class='argument'>b</code>)</code></dd> + <dd><code><code class='datatype'>void</code> set_backend(<code class='object unresolved'>Pike.Backend</code> <code class='argument'>backend</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Sort with care of numerical sort for OID values, e.g. - "1.2.1" before "1.11.1". + <dd class='body--doc'>Set the backend used for the accept callback. </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'><table class='box'><tr><td><code><code class='key'>-1</code></code></td><td><code class='expr'>a<b</code> - </td></tr> - <tr><td><code><code class='key'>0</code></code></td><td><code class='expr'>a==b</code> - </td></tr> - <tr><td><code><code class='key'>1</code></code></td><td><code class='expr'>a>b</code> - </td></tr> - </table></dd> + <dt class='head--doc'>Note</dt> - <dd class='body--doc'>In Pike 7.6 and older this function returned <code class='expr'>0</code> both when - <code class='expr'>a<b</code> and <code class='expr'>a==b</code>. + <dd class='body--doc'>The backend keeps a reference to this object as long as the port + is accepting connections, but this object does not keep a + reference to the backend. </dd> <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>sort_array</code> + <dd class='body--doc'><code>query_backend</code> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - partition + set_id </dt> - <dd><code><code class='datatype'>array</code>(<code class='datatype'>array</code>) partition(<code class='datatype'>array</code> <code class='argument'>a</code>, <code class='datatype'>function</code>(<code class='datatype'>int(0..0)</code>, <code class='datatype'>mixed</code> ... :<code class='datatype'>mixed</code>) <code class='argument'>arbiter</code>, <code class='datatype'>mixed</code> ... <code class='argument'>extra_args</code>)</code></dd> + <dd><code><code class='datatype'>mixed</code> set_id(<code class='datatype'>mixed</code> <code class='argument'>id</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Splits an array in two, according to an arbitration function - <code>arbiter</code>. The elements in <code>a</code> who return non-zero for the - expression <code>arbiter</code>( <code>a</code>[i], @<code>extra_args</code> ) end up in - the first sub-array, the others in the second. The order is - preserved from the original array. + <dd class='body--doc'>This function sets the id used for accept_callback by this port. + The default id is <code>this_object()</code>. </dd> - <dt class='head--doc'>Example</dt> - <dd class='example'><pre>Array.partition( enumerate( 9 ), lambda(int n) { return n>3 && n<7; } ); - > ({ ({ 4, 5, 6 }), ({ 0, 1, 2, 3, 7, 8 }) }) - </pre></dd> + <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>filter</code>, <code>`/</code>, <code>`%</code> + <dd class='body--doc'><code>query_id</code> </dd></dl> - + </dd></dl><dl><dt><h2 class='header'>Class Stdio.UDP</h2> + </dt><dd><dl class='group--doc'> + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>UDP (User Datagram Protocol) handling. + </dd></dl> - + <hr /> <dl class='group--doc'> - <dt class='head--type'>Method - permute + <dt class='head--type'>Constant + MSG_OOB </dt> - <dd><code><code class='datatype'>array</code> permute(<code class='datatype'>array</code> <code class='argument'>in</code>, <code class='datatype'>int(0..)</code> <code class='argument'>number</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Give a specified permutation of an array. - The number of permutations is equal to <code class='expr'>sizeof(<code>in</code>)!</code> - (the factorial of the size of the given array). - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>shuffle()</code> + <dd><code><code class='datatype'>constant</code> Stdio.UDP.<code class='constant'>MSG_OOB</code></code></dd> + <dt class='head--fixme'>FIXME</dt> + <dd class='body--fixme'>Document this constant. </dd></dl> <hr /> <dl class='group--doc'> - <dt class='head--type'>Method - pop + <dt class='head--type'>Constant + MSG_PEEK </dt> - <dd><code><code class='datatype'>array</code> pop(<code class='datatype'>array</code> <code class='argument'>list</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Pops and returns the last value of the array, shortening the - array by one element. - If there are no elements in the array then 0 is returned otherwise - an array is returned where the first returned element is the popped - value, and the second element is the modified array. - </dd> - <dt class='head--doc'>Example</dt> - <dd class='example'><pre>Array.pop(({ "a", "b", "c", "d" })); - > ({ "d", ({ "a", "b", "c" }) }) - </pre></dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>ADT.Stack</code>, <code>ADT.Stack.pop</code>, <code>ADT.Stack.quick_pop</code> + <dd><code><code class='datatype'>constant</code> Stdio.UDP.<code class='constant'>MSG_PEEK</code></code></dd> + <dt class='head--fixme'>FIXME</dt> + <dd class='body--fixme'>Document this constant. </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - push + add_membership </dt> - <dd><code><code class='datatype'>array</code> push(<code class='datatype'>array</code> <code class='argument'>list</code>, <code class='datatype'>mixed</code> <code class='argument'>element</code>)</code></dd> + <dd><code><code class='datatype'>int</code> add_membership(<code class='datatype'>string</code> <code class='argument'>group</code>, <code class='datatype'>void</code>|<code class='datatype'>string</code> <code class='argument'>address</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Threats an Array as a stack and pushes the element onto the - end. + <dd class='body--doc'>Join a multicast group. </dd> - <dt class='head--doc'>Example</dt> - <dd class='example'><pre>Array.push(({ "a", "b", "c", "d" }), "e"); - > ({ "a", "b", "c", "d", "e" }) - </pre></dd> + <dt class='head--doc'>Parameter <code class='parameter'>group</code></dt> + <dd></dd><dd class='body--doc'><code>group</code> contains the address of the multicast group the + application wants to join. It must be a valid multicast address. + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>address</code></dt> + <dd></dd><dd class='body--doc'><code>address</code> is the address of the local interface with which + the system should join to the multicast group. If not provided + the system will select an appropriate interface. + See also the Unix man page for setsocketopt IPPROTO_IP IP_ADD_MEMBERSHIP + and IPPROTO_IPV6 IPV6_JOIN_GROUP. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>The <code>address</code> parameter is currently not supported for IPv6. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>This function did not support IPv6 in Pike 7.8 and earlier. + </dd> <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>ADT.Stack</code>, <code>ADT.Stack.push</code> + <dd class='body--doc'><code>drop_membership()</code> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - reduce + bind </dt> - <dd><code><code class='datatype'>mixed</code> reduce(<code class='datatype'>function</code>(:<code class='datatype void'>void</code>) <code class='argument'>fun</code>, <code class='datatype'>array</code> <code class='argument'>arr</code>, <code class='datatype'>mixed</code>|<code class='datatype'>void</code> <code class='argument'>zero</code>)</code></dd> + <dd><code><code class='object unresolved'>UDP</code> bind(<code class='datatype'>int</code>|<code class='datatype'>string</code> <code class='argument'>port</code>, <code class='datatype'>string</code>|<code class='datatype'>void</code> <code class='argument'>address</code>, <code class='datatype'>string</code>|<code class='datatype'>bool</code> <code class='argument'>no_reuseaddr</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'><code>reduce()</code> sends the first two elements in <code>arr</code> to <code>fun</code>, - then the result and the next element in <code>arr</code> to <code>fun</code> and - so on. Then it returns the result. The function will return - <code>zero</code> if <code>arr</code> is the empty array. If <code>arr</code> has - only one element, that element will be returned. + <dd class='body--doc'>Binds a port for receiving or transmitting UDP. </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>rreduce()</code> + <dt class='head--doc'>Parameter <code class='parameter'>port</code></dt> + <dd></dd><dd class='body--doc'>Either a port number or the name of a service as listed in + <tt>/etc/services</tt>. + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>address</code></dt> + <dd></dd><dd class='body--doc'>Local address to bind to. + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>no_reuseaddr</code></dt> + <dd></dd><dd class='body--doc'>If set to <code class='expr'>1</code>, Pike will not set the <code class='expr'>SO_REUSEADDR</code> option + on the UDP port. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'><code class='expr'>SO_REUSEADDR</code> is never applied when binding a random port + (<code class='expr'>bind(0)</code>). + In general, <code class='expr'>SO_REUSEADDR</code> is not desirable on UDP ports. + Unless used for receiving multicast, be sure to never bind a + non-random port without setting <code class='expr'>no_reuseaddr</code> to <code class='expr'>1</code>. + </dd> + <dt class='head--doc'>Throws</dt> + <dd class='body--doc'>Throws error when unable to bind port. </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - rreduce + close </dt> - <dd><code><code class='datatype'>mixed</code> rreduce(<code class='datatype'>function</code>(:<code class='datatype void'>void</code>) <code class='argument'>fun</code>, <code class='datatype'>array</code> <code class='argument'>arr</code>, <code class='datatype'>mixed</code>|<code class='datatype'>void</code> <code class='argument'>zero</code>)</code></dd> + <dd><code><code class='datatype'>bool</code> close()</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'><code>rreduce()</code> sends the last two elements in <code>arr</code> to <code>fun</code>, - then the third last element in <code>arr</code> and the result to <code>fun</code> and - so on. Then it returns the result. The function will return - <code>zero</code> if <code>arr</code> is the empty array. If <code>arr</code> has - only one element, that element will be returned. + <dd class='body--doc'>Closes an open UDP port. </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>reduce()</code> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>This method was introduced in Pike 7.5. </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - search_array + connect </dt> - <dd><code><code class='datatype'>int</code> search_array(<code class='datatype'>array</code> <code class='argument'>arr</code>, <code class='datatype'>string</code>|<code class='datatype'>function</code>(:<code class='datatype void'>void</code>)|<code class='datatype'>int</code> <code class='argument'>fun</code>, <code class='datatype'>mixed</code> ... <code class='argument'>args</code>)</code></dd> + <dd><code><code class='datatype'>bool</code> connect(<code class='datatype'>string</code> <code class='argument'>address</code>, <code class='datatype'>int</code>|<code class='datatype'>string</code> <code class='argument'>port</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'><code>search_array()</code> works like <code>map()</code>, only it returns the index - of the first call that returnes true instead. - If no call returns true, -1 is returned. + <dd class='body--doc'>Establish an UDP connection. + This function connects an UDP socket previously created with + <code>Stdio.UDP()</code> to a remote socket. The <code>address</code> is the IP name or + number for the remote machine. </dd> - + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>Returns <code class='expr'>1</code> on success, <code class='expr'>0</code> (zero) otherwise. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>If the socket is in nonblocking mode, you have to wait + for a write or close callback before you know if the connection + failed or not. + </dd> <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>sum()</code>, <code>map()</code> + <dd class='body--doc'><code>bind()</code>, <code>query_address()</code> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - shift + drop_membership </dt> - <dd><code><code class='datatype'>array</code> shift(<code class='datatype'>array</code> <code class='argument'>list</code>)</code></dd> + <dd><code><code class='datatype'>int</code> drop_membership(<code class='datatype'>string</code> <code class='argument'>group</code>, <code class='datatype'>void</code>|<code class='datatype'>string</code> <code class='argument'>address</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Shifts the first value of the array off and returns it, shortening - the array by 1 and moving everything down. If there are no elements - in the array it returns 0. - Returns an array where the first element is the shifted value and the - second element is the modified array. + <dd class='body--doc'>Leave a multicast group. </dd> - <dt class='head--doc'>Example</dt> - <dd class='example'><pre>Array.shift(({ "a", "b", "c", "d"})); - > ({ "a", ({ "b", "c", "d" }) }) - </pre></dd> + <dt class='head--doc'>Parameter <code class='parameter'>group</code></dt> + <dd></dd><dd class='body--doc'><code>group</code> contains the address of the multicast group the + application wants to join. It must be a valid multicast address. + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>address</code></dt> + <dd></dd><dd class='body--doc'><code>address</code> is the address of the local interface with which + the system should join to the multicast group. If not provided + the system will select an appropriate interface. + See also the Unix man page for setsocketopt IPPROTO_IP IP_DROP_MEMBERSHIP + and IPPROTO_IPV6 IPV6_LEAVE_GROUP. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>The <code>address</code> parameter is currently not supported for IPv6. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>This function did not support IPv6 in Pike 7.8 and earlier. + </dd> <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>ADT.Stack</code> + <dd class='body--doc'><code>add_membership()</code> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - shuffle + enable_broadcast </dt> - <dd><code><code class='datatype'>array</code> shuffle(<code class='datatype'>array</code> <code class='argument'>arr</code>)</code></dd> + <dd><code><code class='datatype'>bool</code> enable_broadcast()</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'><code>shuffle()</code> gives back the same elements, but in random order. - The array is modified destructively. + <dd class='body--doc'>Set the broadcast flag. + If enabled then sockets receive packets sent to a broadcast + address and they are allowed to send packets to a + broadcast address. </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>permute()</code> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>Returns <code class='expr'>1</code> on success, <code class='expr'>0</code> (zero) otherwise. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>This is normally only avalable to root users. </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - sort_array + enable_multicast </dt> - <dd><code><code class='datatype'>array</code> sort_array(<code class='datatype'>array</code> <code class='argument'>arr</code>, <code class='datatype'>function</code>(:<code class='datatype void'>void</code>)|<code class='datatype'>void</code> <code class='argument'>cmp</code>, <code class='datatype'>mixed</code> ... <code class='argument'>args</code>)</code></dd> + <dd><code><code class='datatype'>bool</code> enable_multicast(<code class='datatype'>string</code> <code class='argument'>reply_address</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>This function sorts the array <code>arr</code> after a compare-function - <code>cmp</code> which takes two arguments and should return <code class='expr'>1</code> if the - first argument is larger then the second. Returns the sorted array - - <code>arr</code> is not sorted destructively. - The remaining arguments <code>args</code> will be sent as 3rd, 4th etc. argument - to <code>cmp</code>. - If <code>cmp</code> is omitted, <code>`>()</code> is used instead. + <dd class='body--doc'>Set the local device for a multicast socket. </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>map()</code>, <code>sort()</code>, <code>`>()</code>, <code>dwim_sort_func</code>, <code>lyskom_sort_func</code>, - <code>oid_sort_func</code> + <dt class='head--doc'>Parameter <code class='parameter'>reply_address</code></dt> + <dd></dd><dd class='body--doc'>Local address that should appear in the multicast packets. + See also the Unix man page for setsocketopt IPPROTO_IP IP_MULTICAST_IF + and IPPROTO_IPV6 IPV6_MULTICAST_IF. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>This function did not support IPv6 in Pike 7.8. </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - splice + errno </dt> - <dd><code><code class='datatype'>array</code>(<code class='datatype'>mixed</code>) splice(<code class='datatype'>array</code>(<code class='datatype'>mixed</code>) <code class='argument'>arr1</code>, <code class='datatype'>array</code>(<code class='datatype'>mixed</code>) <code class='argument'>arr2</code>, <code class='datatype'>array</code>(<code class='datatype'>mixed</code>) ... <code class='argument'>more_arrays</code>)</code></dd> + <dd><code><code class='datatype'>int</code> errno()</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Splice two or more arrays. - This means that the returned array has the first element in the - first given array, then the first argument in next array and so - on for all arrays. Then the second elements are added, etc. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>`/()</code>, <code>`*()</code>, <code>`+()</code>, <code>`-()</code>, <code>everynth()</code> + <dd class='body--doc'>Returns the error code for the last command on this object. + Error code is normally cleared when a command is successful. </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - sum + get_type </dt> - <dd><code><code class='datatype'>mixed</code> sum(<code class='datatype'>array</code> <code class='argument'>a</code>)</code></dd> + <dd><code><code class='datatype'>array</code>(<code class='datatype'>int</code>) get_type()</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Sum the elements of an array using `+. The empty array - results in 0. + <dd class='body--doc'>Returns socket type and protocol family. </dd></dl> <hr /> <dl class='group--doc'> - <dt class='head--type'>Method - sum_arrays + <dt class='head--type'>Inherit + UDP </dt> - <dd><code><code class='datatype'>array</code> sum_arrays(<code class='datatype'>function</code>(<code class='datatype'>int(0..0)</code> ... :<code class='datatype'>mixed</code>) <code class='argument'>sum</code>, <code class='datatype'>array</code> ... <code class='argument'>args</code>)</code></dd> + <dd><code>inherit _Stdio.UDP : UDP</code></dd> + </dl> - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Applies the function <code>sum</code> columnwise on the elements in the - provided arrays. E.g. <code class='expr'>sum_array(`+,a,b,c)</code> does the same - as <code class='expr'>`+(a[*],b[*],c[*])</code>. - </dd></dl> + - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - transpose + query_address </dt> - <dd><code><code class='datatype'>array</code>(<code class='datatype'>array</code>) transpose(<code class='datatype'>array</code>(<code class='datatype'>array</code>) <code class='argument'>matrix</code>)</code></dd> + <dd><code><code class='datatype'>string</code> query_address()</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Takes an array of equally sized arrays (essentially a matrix of size M*N) - and returns the transposed (N*M) version of it, where rows and columns - are exchanged for one another. + <dd class='body--doc'>Returns the local address of a socket on the form "x.x.x.x port". + If this file is not a socket, not connected or some other error occurs, + zero is returned. </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - uniq + query_backend </dt> - <dd><code><code class='datatype'>array</code> uniq(<code class='datatype'>array</code> <code class='argument'>a</code>)</code></dd> + <dd><code><code class='object unresolved'>Pike.Backend</code> query_backend()</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Remove elements that are duplicates. + <dd class='body--doc'>Return the backend used for the read callback. </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>This function returns an copy of the array <code>a</code> with all - duplicate values removed. The order of the values is kept in the - result; it's always the first of several equal elements that is - kept. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>Elements are compared with <code>`==</code>. They are also hashed (see - <code>lfun::__hash</code> for further details if the array contains - objects). + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>set_backend</code> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - uniq2 + query_fd </dt> - <dd><code><code class='datatype'>array</code> uniq2(<code class='datatype'>array</code> <code class='argument'>a</code>)</code></dd> + <dd><code><code class='datatype'>int</code> query_fd()</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Perform the same action as the Unix uniq command on an array, - that is, fold consecutive occurrences of the same element into - a single element of the result array: - aabbbcaababb -> abcabab. - See also the <code>uniq</code> function. + <dd class='body--doc'>Gets the file descriptor for this UDP port. </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - unshift + read </dt> - <dd><code><code class='datatype'>array</code> unshift(<code class='datatype'>array</code> <code class='argument'>list</code>, <code class='datatype'>mixed</code> <code class='argument'>element</code>)</code></dd> + <dd><code><code class='datatype'>mapping</code>(<code class='datatype'>string</code>:<code class='datatype'>int</code>|<code class='datatype'>string</code>) read()</code> + <code><code class='datatype'>mapping</code>(<code class='datatype'>string</code>:<code class='datatype'>int</code>|<code class='datatype'>string</code>) read(<code class='datatype'>int</code> <code class='argument'>flag</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Does the opposite of "shift". Or the opposite of a "push", - depending on how you look at it. Prepends the element to - the front of the array and returns the new array. + <dd class='body--doc'>Read from the UDP socket. + Flag <code>flag</code> is a bitfield, 1 for out of band data and 2 for peek </dd> - <dt class='head--doc'>Example</dt> - <dd class='example'><pre>Array.unshift(({ "b", "c", "d" }), "a"); - > ({ "a", "b", "c", "d" }) - </pre></dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>ADT.Stack</code> - </dd></dl> - <dl><dt><h2 class='header'>Class Array.Iterator</h2> - </dt><dd><dl class='group--doc'> - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>An object of this class is returned by <code>get_iterator()</code> when - called with an array. + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>mapping(string:int|string) in the form + ([ + "data" : string received data + "ip" : string received from this ip + "port" : int ...and this port + ]) </dd> <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>get_iterator</code> + <dd class='body--doc'><code>set_read_callback()</code>, <code>MSG_OOB</code>, <code>MSG_PEEK</code> </dd></dl> - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Inherit - predef::Iterator - </dt> - <dd><code>inherit predef::Iterator : predef::Iterator</code></dd> - </dl> - </dd></dl></dd></dl><dl><dt><h2 class='header'>Module Mapping</h2> - </dt><dd> + <hr /> <dl class='group--doc'> - <dt class='head--type'>Constant - delete + <dt class='head--type'>Method + send </dt> - <dd><code><code class='datatype'>constant</code> Mapping.<code class='constant'>delete</code></code></dd> + <dd><code><code class='datatype'>int</code> send(<code class='datatype'>string</code> <code class='argument'>to</code>, <code class='datatype'>int</code>|<code class='datatype'>string</code> <code class='argument'>port</code>, <code class='datatype'>string</code> <code class='argument'>message</code>)</code> + <code><code class='datatype'>int</code> send(<code class='datatype'>string</code> <code class='argument'>to</code>, <code class='datatype'>int</code>|<code class='datatype'>string</code> <code class='argument'>port</code>, <code class='datatype'>string</code> <code class='argument'>message</code>, <code class='datatype'>int</code> <code class='argument'>flags</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Alias for <code>m_delete()</code> - </dd></dl> - <dl><dt><h2 class='header'>Class Mapping.Iterator</h2> - </dt><dd><dl class='group--doc'> - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>An object of this class is returned by <code>get_iterator()</code> when - called with a mapping. + <dd class='body--doc'>Send data to a UDP socket. The recipient address will be <code>to</code> + and port will be <code>port</code>. + Flag <code>flag</code> is a bitfield, 1 for out of band data and + 2 for don't route flag. </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>get_iterator</code> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'><table class='box'><tr><td><code><code class='key'>(0..)</code></code></td><td>The number of bytes that were actually written. + </td></tr> + <tr><td><code><code class='key'>(..-1)</code></code></td><td>Failed to send the <code>message</code>. Check <code>errno()</code> for + the cause. Common causes are: + <table class='box'><tr><td><code><code class='key'>System.EMSGSIZE</code></code></td><td>The <code>message</code> is too large to send unfragmented. + </td></tr> + <tr><td><code><code class='key'>System.EWOULDBLOCK</code></code></td><td>The send buffers are full. + </td></tr> + </table></td></tr> + </table> + </dd> + <dt class='head--doc'>Throws</dt> + <dd class='body--doc'>Throws errors on invalid arguments and uninitialized object. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>Versions of Pike prior to 8.1.5 threw errors also on EMSGSIZE + (<code class='expr'>"Too big message"</code>) and EWOULDBLOCK + .(<code class='expr'>"Message would block."</code>). These versions of Pike also + did not update the object errno on this function failing. </dd></dl> - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Inherit - predef::Iterator - </dt> - <dd><code>inherit predef::Iterator : predef::Iterator</code></dd> - </dl> - </dd></dl><dl><dt><h2 class='header'>Class Mapping.ShadowedMapping</h2> - </dt><dd><dl class='group--doc'> - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>A mapping look-alike that overrides (ie shadows) another <code>parent</code> mapping. - The class implements most of the usual mapping operations. - </dd></dl> + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - create + set_backend </dt> - <dd><code>Mapping.ShadowedMapping Mapping.ShadowedMapping(<code class='datatype'>mapping</code>|<code class='object unresolved'>ShadowedMapping</code> <code class='argument'>parent</code>, <code class='datatype'>mapping</code>|<code class='datatype'>void</code> <code class='argument'>shadow</code>, <code class='datatype'>bool</code>|<code class='datatype'>void</code> <code class='argument'>modify_parent</code>)</code></dd> + <dd><code><code class='datatype'>void</code> set_backend(<code class='object unresolved'>Pike.Backend</code> <code class='argument'>backend</code>)</code></dd> - <dt class='head--doc'>Parameter <code class='parameter'>parent</code></dt> - <dd></dd><dd class='body--doc'>Mapping to be shadowed. + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Set the backend used for the read callback. </dd> - <dt class='head--doc'>Parameter <code class='parameter'>shadow</code></dt> - <dd></dd><dd class='body--doc'>Initial shadow of <code>parent</code>. + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>The backend keeps a reference to this object as long as there can + be calls to the read callback, but this object does not keep a + reference to the backend. </dd> - <dt class='head--doc'>Parameter <code class='parameter'>modify_parent</code></dt> - <dd></dd><dd class='body--doc'>Modifications should be done to <code>parent</code> rather than - to <code>shadow</code>. If this is set, only entries that are - already present in <code>shadow</code> can be modified by later - operations. + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>query_backend</code> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - create + set_blocking </dt> - <dd><code>Mapping.ShadowedMapping Mapping.ShadowedMapping(<code class='datatype'>mapping</code>|<code class='object unresolved'>ShadowedMapping</code> <code class='argument'>parent</code>)</code></dd> - </dl> + <dd><code><code class='datatype'>object</code> set_blocking()</code></dd> - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Variable - parent - </dt> - <dd><code><code class='modifier'>protected</code> <code class='datatype'>mapping</code>|<code class='object unresolved'>ShadowedMapping</code> Mapping.ShadowedMapping.parent</code></dd> - </dl> - </dd></dl></dd></dl><dl><dt><h2 class='header'>Module Multiset</h2> - </dt><dd><dl class='group--doc'> + <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Multiset handling. - </dd></dl><dl><dt><h2 class='header'>Class Multiset.Iterator</h2> - </dt><dd><dl class='group--doc'> - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>An object of this class is returned by <code>get_iterator()</code> when - called with a multiset. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>get_iterator</code> + <dd class='body--doc'>Sets this object to be blocking. </dd></dl> - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Inherit - predef::Iterator - </dt> - <dd><code>inherit predef::Iterator : predef::Iterator</code></dd> - </dl> - </dd></dl></dd></dl><dl><dt><h2 class='header'>Module Int</h2> - </dt><dd> + <hr /> <dl class='group--doc'> - <dt class='head--type'>Constant - NATIVE_MIN - Constant - NATIVE_MAX + <dt class='head--type'>Method + set_buffer </dt> - <dd><code><code class='datatype'>constant</code> Int.<code class='constant'>NATIVE_MIN</code></code> - <code><code class='datatype'>constant</code> Int.<code class='constant'>NATIVE_MAX</code></code></dd> + <dd><code><code class='datatype'>void</code> set_buffer(<code class='datatype'>int</code> <code class='argument'>bufsize</code>, <code class='datatype'>string</code> <code class='argument'>mode</code>)</code> + <code><code class='datatype'>void</code> set_buffer(<code class='datatype'>int</code> <code class='argument'>bufsize</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>The limits for using the native representation of integers on the - current architecture. Any integer that is outside this range uses - a more complex and slower representation. Also, some builtin - functions that don't expect very large integers might start to - complain about invalid argument type when given values outside - this range (they typically say something like "Expected integer, - got object"). - <code>NATIVE_MIN</code> is not greater than <code class='expr'>-2147483648</code> - (<code class='expr'>-0x80000000</code>). - <code>NATIVE_MAX</code> is not less than <code class='expr'>2147483647</code> - (<code class='expr'>0x7fffffff</code>). + <dd class='body--doc'>Set internal socket buffer. + This function sets the internal buffer size of a socket or stream. + The second argument allows you to set the read or write buffer by + specifying <code class='expr'>"r"</code> or <code class='expr'>"w"</code>. </dd> <dt class='head--doc'>Note</dt> - <dd class='body--doc'>The size of the native integers can be controlled when Pike is - compiled with the configure flags <code class='expr'>--with-int-int</code>, - <code class='expr'>--with-long-int</code>, and <code class='expr'>--with-long-long-int</code>. The - default is to use the longest available integer type that fits - inside a pointer, which typically means that it's 64 bit on "true" - 64 bit architectures. + <dd class='body--doc'>It is not guaranteed that this function actually does anything, + but it certainly helps to increase data transfer speed when it does. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>open_socket()</code>, <code>accept()</code> </dd></dl> <hr /> <dl class='group--doc'> - <dt class='head--type'>Variable - inf - </dt> - <dd><code><code class='object unresolved'>Inf</code> Int.inf</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>An object that behaves like positive infinity. - </dd></dl> - - - <hr /> - <dl class='group--doc'> + <dt class='head--type'>Method - parity + set_fd </dt> - <dd><code><code class='datatype'>bool</code> parity(<code class='datatype'>int(0..)</code> <code class='argument'>value</code>)</code></dd> + <dd><code><code class='object unresolved'>UDP</code> set_fd(<code class='datatype'>int</code> <code class='argument'>fd</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Returns the parity of the integer <code>value</code>. If the - parity is odd 1 is returned. If it is even 0 is - returned. + <dd class='body--doc'>Use the file descriptor <code>fd</code> for UDP. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>bind</code> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - reflect + set_multicast_ttl </dt> - <dd><code><code class='datatype'>int(0..)</code> reflect(<code class='datatype'>int</code> <code class='argument'>value</code>, <code class='datatype'>int(0..)</code> <code class='argument'>bits</code>)</code></dd> + <dd><code><code class='datatype'>int</code> set_multicast_ttl(<code class='datatype'>int</code> <code class='argument'>ttl</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Reverses the order of the low order <code>bits</code> number of bits - of the value <code>value</code>. + <dd class='body--doc'>Set the time-to-live value of outgoing multicast packets + for this socket. </dd> - + <dt class='head--doc'>Parameter <code class='parameter'>ttl</code></dt> + <dd></dd><dd class='body--doc'>The number of router hops sent multicast packets should + survive. + It is very important for multicast packets to set the + smallest TTL possible. The default before calling this + function is 1 which means that multicast packets don't + leak from the local network unless the user program + explicitly requests it. + See also the Unix man page for setsocketopt IPPROTO_IP IP_MULTICAST_TTL + and IPPROTO_IPV6 IPV6_MULTICAST_HOPS. + </dd> <dt class='head--doc'>Note</dt> - <dd class='body--doc'>Any higher order bits of the value will be cleared. - The returned value will thus be unsigned. + <dd class='body--doc'>This function did not support IPv6 in Pike 7.8 and earlier. </dd> <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>reverse()</code>, <code>swap_word()</code>, <code>swap_long()</code> + <dd class='body--doc'><code>add_membership()</code> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - swap_long + set_nonblocking </dt> - <dd><code><code class='datatype'>int(32bit)</code> swap_long(<code class='datatype'>int(32bit)</code> <code class='argument'>i</code>)</code></dd> + <dd><code><code class='object unresolved'>UDP</code> set_nonblocking()</code> + <code><code class='object unresolved'>UDP</code> set_nonblocking(<code class='datatype'>function</code>(<code class='datatype'>mapping</code>(<code class='datatype'>string</code>:<code class='datatype'>int</code>|<code class='datatype'>string</code>), <code class='datatype'>mixed</code> ... :<code class='datatype'>void</code>) <code class='argument'>read_cb</code>, <code class='datatype'>mixed</code> ... <code class='argument'>extra_args</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Swaps the upper and lower word in a longword, and the upper and - lower bytes in the words. Simply put, the bytes are reversed. + <dd class='body--doc'>Set this object to nonblocking mode. + If <code>read_cb</code> and <code>extra_args</code> are specified, they will be passed on + to <code>set_read_callback()</code>. </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>swap_word()</code> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>The called object. </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - swap_word + set_read_callback </dt> - <dd><code><code class='datatype'>int(16bit)</code> swap_word(<code class='datatype'>int(16bit)</code> <code class='argument'>i</code>)</code></dd> + <dd><code><code class='object unresolved'>UDP</code> set_read_callback(<code class='datatype'>function</code>(<code class='datatype'>mapping</code>(<code class='datatype'>string</code>:<code class='datatype'>int</code>|<code class='datatype'>string</code>), <code class='datatype'>mixed</code> ... :<code class='datatype void'>void</code>) <code class='argument'>read_cb</code>, <code class='datatype'>mixed</code> ... <code class='argument'>extra_args</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Swaps the upper and lower byte in a word. + <dd class='body--doc'>The <code>read_cb</code> function will receive a mapping similar to the mapping + returned by <code>read()</code>: + <table class='box'><tr><td><code><code class='key'>"data"</code> : <code class='datatype'>string</code></code></td><td>Received data. + </td></tr> + <tr><td><code><code class='key'>"ip"</code> : <code class='datatype'>string</code></code></td><td>Data was sent from this IP. + </td></tr> + <tr><td><code><code class='key'>"port"</code> : <code class='datatype'>int</code></code></td><td>Data was sent from this port. + </td></tr> + </table> </dd> - + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>The called object. + </dd> <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>swap_long()</code> + <dd class='body--doc'><code>read()</code> </dd></dl> - <dl><dt><h2 class='header'>Class Int.Inf</h2> - </dt><dd><dl class='group--doc'> - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>The type of <code>Int.inf</code>. Do not create more instances of this. - </dd></dl></dd></dl></dd></dl><dl><dt><h2 class='header'>Module Float</h2> - </dt><dd> + - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Constant - DIGITS_10 - Constant - MIN_10_EXP - Constant - MAX_10_EXP - Constant - MIN - Constant - MAX - Constant - EPSILON - </dt> - <dd><code><code class='datatype'>constant</code> Float.<code class='constant'>DIGITS_10</code></code> - <code><code class='datatype'>constant</code> Float.<code class='constant'>MIN_10_EXP</code></code> - <code><code class='datatype'>constant</code> Float.<code class='constant'>MAX_10_EXP</code></code> - <code><code class='datatype'>constant</code> Float.<code class='constant'>MIN</code></code> - <code><code class='datatype'>constant</code> Float.<code class='constant'>MAX</code></code> - <code><code class='datatype'>constant</code> Float.<code class='constant'>EPSILON</code></code></dd> + - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>These constants define the limits for floats on the current - architecture: - <dl class='group--doc'><dt>DIGITS_10</dt> - <dd>The number of decimal digits that can be represented. Any number - with this many decimal digits can be stored in a float and - converted back to decimal form without change. <code>DIGITS_10</code> is - not less than <code class='expr'>6</code>. - </dd> - <dt>MIN_10_EXP</dt> - <dt>MAX_10_EXP</dt> - <dd>Limits of the exponent in decimal base. 10 raised to any number - within this range can be represented in normalized form. - <code>MIN_10_EXP</code> is not greater than <code class='expr'>-37</code>. <code>MAX_10_EXP</code> is - not less than <code class='expr'>37</code>. - </dd> - <dt>MIN</dt> - <dd>The smallest normalized float greater than zero. It's not - greater than <code class='expr'>1e-37</code>. - </dd> - <dt>MAX</dt> - <dd>The largest finite float. It's not less than <code class='expr'>1e37</code>. - </dd> - <dt>EPSILON</dt> - <dd>The difference between 1 and the smallest value greater than 1 - that can be represented. It's not greater than <code class='expr'>1e-5</code>. - </dd> - </dl> - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>The size of the float type can be controlled when Pike is compiled - with the configure flags <code class='expr'>--with-double-precision</code> and - <code class='expr'>--with-long-double-precision</code>. The default is to use the - longest available float type that fits inside a pointer. - </dd></dl> - - + <hr /> <dl class='group--doc'> - <dt class='head--type'>Constant - FLOAT_PRECISION - Constant - DOUBLE_PRECISION - Constant - LONG_DOUBLE_PRECISION + <dt class='head--type'>Method + set_type </dt> - <dd><code><code class='datatype'>constant</code> Float.<code class='constant'>FLOAT_PRECISION</code></code> - <code><code class='datatype'>constant</code> Float.<code class='constant'>DOUBLE_PRECISION</code></code> - <code><code class='datatype'>constant</code> Float.<code class='constant'>LONG_DOUBLE_PRECISION</code></code></dd> + <dd><code><code class='object unresolved'>UDP</code> set_type(<code class='datatype'>int</code> <code class='argument'>sock_type</code>)</code> + <code><code class='object unresolved'>UDP</code> set_type(<code class='datatype'>int</code> <code class='argument'>sock_type</code>, <code class='datatype'>int</code> <code class='argument'>family</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Tells which C compiler float type that is used for Pike floats. - Only one of these constants will exist (with the value <code class='expr'>1</code>) - at runtime. - <dl class='group--doc'><dt>FLOAT_PRECISION</dt> - <dd>The <code class='expr'>float</code> type of the C compiler is used. - </dd> - <dt>DOUBLE_PRECISION</dt> - <dd>The <code class='expr'>double</code> type of the C compiler is used. - </dd> - <dt>LONG_DOUBLE_PRECISION</dt> - <dd>The <code class='expr'>long double</code> type of the C compiler is used. - </dd> - </dl> - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>The float type can be controlled when Pike is compiled with the - configure flags <code class='expr'>--with-double-precision</code> and - <code class='expr'>--with-long-double-precision</code>. The default is to use the - longest available float type that fits inside a pointer. + <dd class='body--doc'>Sets socket type and protocol family. </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - isnan + wait </dt> - <dd><code><code class='datatype'>bool</code> isnan(<code class='datatype'>float</code> <code class='argument'>x</code>)</code></dd> + <dd><code><code class='datatype'>bool</code> wait(<code class='datatype'>int</code>|<code class='datatype'>float</code> <code class='argument'>timeout</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Returns true if <code>x</code> is nan. + <dd class='body--doc'>Check for data and wait max. <code>timeout</code> seconds. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>Returns <code class='expr'>1</code> if data are ready, <code class='expr'>0</code> (zero) otherwise. </dd></dl> - </dd></dl><dl><dt><h2 class='header'>Module Function</h2> + </dd></dl><dl><dt><h2 class='header'>Module Stdio.Terminfo</h2> </dt><dd> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - Y + getFallbackTerm </dt> - <dd><code><code class='datatype'>function</code>(:<code class='datatype void'>void</code>) Y(<code class='datatype'>function</code>(:<code class='datatype void'>void</code>) <code class='argument'>f</code>)</code></dd> + <dd><code><code class='modifier'>protected</code> <code class='object unresolved'>Termcap</code> getFallbackTerm(<code class='datatype'>string</code> <code class='argument'>term</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>The dreaded fixpoint combinator "Y". - The Y combinator is useful when writing recursive lambdas. It - converts a lambda that expects a self-reference as its first argument - into one which can be called without this argument. + <dd class='body--doc'>Returns an object describing the fallback terminal for the terminal + <code>term</code>. This is usually equvivalent to <code>Stdio.Terminfo.getTerm("dumb")</code>. </dd> - <dt class='head--doc'>Example</dt> - <dd class='example'><pre>This example creates a lambda that computes the faculty function. - <pre><code>Function.Y(lambda(function f, int n) { return n>1? n*f(n-1) : 1; }) - </code></pre> - </pre></dd> + <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>this_function</code> + <dd class='body--doc'>Stdio.Terminfo.getTerm </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - call_callback + getTerm </dt> - <dd><code><code class='datatype'>void</code> call_callback(<code class='datatype'>function</code>(:<code class='datatype void'>void</code>) <code class='argument'>f</code>, <code class='datatype'>mixed</code> ... <code class='argument'>args</code>)</code></dd> + <dd><code><code class='object unresolved'>Termcap</code> getTerm(<code class='datatype'>string</code>|<code class='datatype'>void</code> <code class='argument'>term</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Call a callback function, but send throws from the callback - function (ie, errors) to master()->handle_error. - Also accepts if f is zero (0) without error. + <dd class='body--doc'>Returns an object describing the terminal term. If term is not specified, it will + default to <code>getenv("TERM")</code> or if that fails to "dumb". + Lookup of terminal information will first be done in the systems terminfo + database, and if that fails in the termcap database. If neither database exists, a + hardcoded entry for "dumb" will be used. </dd> - <dt class='head--doc'>Example</dt> - <dd class='example'><pre><pre><code>Functions.call_callback(the_callback,some,arguments);</code></pre>equals - <pre><code>{ - mixed err=catch { if (the_callback) the_callback(some,arguments); }; - if (err) master()->handle_error(err); - } - </code></pre>(Approximately, since call_callback also calls handle_error - if 0 were thrown.) - </pre></dd></dl> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'>Stdio.Terminfo.getTerminfo, Stdio.Terminfo.getTermcap, Stdio.getFallbackTerm + </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - composite + getTermcap </dt> - <dd><code><code class='datatype'>function</code>(:<code class='datatype void'>void</code>) composite(<code class='datatype'>function</code>(:<code class='datatype void'>void</code>) ... <code class='argument'>f</code>)</code></dd> + <dd><code><code class='object unresolved'>Termcap</code> getTermcap(<code class='datatype'>string</code> <code class='argument'>term</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Creates a composite function of the provided functions. The - composition function of f() and g(), q(x)=f(g(x)), is created by - <code class='expr'>function q = Function.composite(f, g);</code>. + <dd class='body--doc'>Returns the terminal description object for <code>term</code> from the + systems termcap database. Returns 0 if not found. </dd> - <dt class='head--doc'>Example</dt> - <dd class='example'><pre><pre><code>map(input/",", - Function.composite(String.trim, upper_case)); - </code></pre> - </pre></dd></dl> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'>Stdio.Terminfo.getTerm, Stdio.Terminfo.getTerminfo + </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - curry + getTerminfo </dt> - <dd><code><code class='datatype'>function</code>(<code class='datatype'>mixed</code> ... :<code class='datatype'>function</code>(<code class='datatype'>mixed</code> ... :<code class='datatype'>mixed</code>|<code class='datatype'>void</code>)) curry(<code class='datatype'>function</code>(:<code class='datatype void'>void</code>) <code class='argument'>f</code>)</code></dd> + <dd><code><code class='object unresolved'>Terminfo</code> getTerminfo(<code class='datatype'>string</code> <code class='argument'>term</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Partially evaluate a function call. - This function allows N parameters to be given to a function taking - M parameters (N<=M), yielding a new function taking M-N parameters. - What is actually returned from this function is a function taking N - parameters, and returning a function taking M-N parameters. + <dd class='body--doc'>Returns the terminal description object for <code>term</code> from the + systems terminfo database. Returns 0 if not found. </dd> - <dt class='head--doc'>Example</dt> - <dd class='example'><pre>This example creates a function adding 7 to its argument. - <pre><code>Function.curry(`+)(7)</code></pre> - </pre></dd></dl> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'>Stdio.Terminfo.getTerm, Stdio.Terminfo.getTermcap + </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - defined + is_tty </dt> - <dd><code><code class='datatype'>string</code> defined(<code class='datatype'>function</code>(:<code class='datatype void'>void</code>) <code class='argument'>fun</code>)</code></dd> + <dd><code><code class='datatype'>int</code> is_tty()</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Returns a string with filename and linenumber where <code>fun</code> - was defined. - Returns <code class='expr'>0</code> (zero) when no line can be found, e.g. for - builtin functions and functions in destructed objects. + <dd class='body--doc'>Returns 1 if <code>Stdio.stdin</code> is connected to an interactive + terminal that can handle backspacing, carriage return without + linefeed, and the like. </dd></dl> - + <dl><dt><h2 class='header'>Class Stdio.Terminfo.MetaTerminfoDB</h2> + </dt><dd><dl class='group--doc'> + <dt class='head--doc'>Description</dt> + <dd class='body--doc'><code>TerminfoDB</code> that merges several directorys. + </dd></dl> - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - splice_call + create </dt> - <dd><code><code class='datatype'>mixed</code> splice_call(<code class='datatype'>array</code> <code class='argument'>args</code>, <code class='datatype'>function</code>(:<code class='datatype void'>void</code>) <code class='argument'>f</code>, <code class='datatype'>mixed</code>|<code class='datatype'>void</code> ... <code class='argument'>extra</code>)</code></dd> + <dd><code>Stdio.Terminfo.MetaTerminfoDB Stdio.Terminfo.MetaTerminfoDB(<code class='datatype'>array</code>(<code class='object unresolved'>TerminfoDB</code>|<code class='datatype'>string</code>)|<code class='datatype'>void</code> <code class='argument'>dbs</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Calls the given function with the <code>args</code> array plus the optional - extra arguments as its arguments and returns the result. - Most useful in conjunction with <code>map</code>, and particularly in combination - with <code>sscanf</code> with <code class='expr'>"...%{...%}..."</code> scan strings (which indeed - was what it was invented for in the first place). + <dd class='body--doc'>Create a new Meta <code>TerminfoDB</code>. </dd> - <dt class='head--doc'>Parameter <code class='parameter'>args</code></dt> - <dd></dd><dd class='body--doc'>The first arguments the function <code>f</code> expects. + <dt class='head--doc'>Parameter <code class='parameter'>dbs</code></dt> + <dd></dd><dd class='body--doc'>Array with elements in priority order. Elements may be either + <table class='box'><tr><td><code><code class='object unresolved'>TerminfoDB</code></code></td><td>An active <code>TerminfoDB</code>. + </td></tr> + <tr><td><code><code class='datatype'>string</code></code></td><td>A directory that may exist and contain a terminfo database. + </td></tr> + </table> </dd> - <dt class='head--doc'>Parameter <code class='parameter'>f</code></dt> - <dd></dd><dd class='body--doc'>The function to apply the arguments on. - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>extra</code></dt> - <dd></dd><dd class='body--doc'>Optional extra arguments to send to <code>f</code>. - </dd> + <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>Whatever the supplied function <code>f</code> returns. - </dd> - <dt class='head--doc'>Example</dt> - <dd class='example'><pre><pre><code>class Product(string name, string version) - { - string _sprintf() - { - return sprintf("Product(%s/%s)", name, version); - } - } - map(({ ({ "pike", "7.1.11" }), - ({ "whitefish", "0.1" }) }), - Function.splice_call, Product); - ({ /* 2 elements */ - Product(pike/7.1.11), - Product(whitefish/0.1) - }) - </code></pre> - </pre></dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - uncurry - </dt> - <dd><code><code class='datatype'>function</code>(<code class='datatype'>mixed</code> ... :<code class='datatype'>mixed</code>) uncurry(<code class='datatype'>function</code>(:<code class='datatype void'>void</code>) <code class='argument'>f</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>This function, given a function taking N parameters, returns a new - function taking N+1 parameters. The first argument will be - ignored. - </dd> - <dt class='head--doc'>Example</dt> - <dd class='example'><pre><pre><code>> Function.uncurry(`+)(7,2,3) - Result: 5</code></pre> - </pre></dd></dl> - <dl><dt><h2 class='header'>Class Function.bind</h2> + <dd class='body--doc'>If the resulting set of <code>TerminfoDB</code>'s is empty, + the object will be destructed. + </dd></dl> + </dd></dl><dl><dt><h2 class='header'>Class Stdio.Terminfo.Termcap</h2> </dt><dd><dl class='group--doc'> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Partially evaluate a function call. - This function returns a function that when called will do the - specified argument mapping. It is similar to <code>curry</code>, but allows - more dynamic changes of the argument evaluation, you can leave the - first argument unspecified while setting others, or simply change - the argument order. - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>f</code></dt> - <dd></dd><dd class='body--doc'>The first argument is the function to be called. - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>bind_args</code></dt> - <dd></dd><dd class='body--doc'>All other arguments are either a generic value, which will be sent - as-is to the function or one of the placeholder values defined in - <code>Function.Placeholder</code>, or one of your own implementation (inherit - <code>Function.Placeholder.Base</code> and implement the value function.). - </dd> - <dt class='head--doc'>Example</dt> - <dd class='example'><pre>This example returns a function that limits the given argument - to between 0 and 99. - <pre><code>import Function.Placeholder; - function clip = Function.bind(limit, 0, arg0, 100); - </code></pre> - </pre></dd></dl> + <dd class='body--doc'>Termcap terminal description object. + </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Variable - f - Variable - bind_args + aliases </dt> - <dd><code><code class='datatype'>function</code>(:<code class='datatype void'>void</code>) Function.bind.f</code> - <code><code class='datatype'>array</code>(<code class='datatype'>mixed</code>) Function.bind.bind_args</code></dd> + <dd><code><code class='datatype'>array</code>(<code class='datatype'>string</code>) Stdio.Terminfo.Termcap.aliases</code></dd> </dl>
2455: <dt class='head--type'>Method create </dt> - <dd><code>Function.bind Function.bind(<code class='datatype'>function</code>(:<code class='datatype void'>void</code>) <code class='argument'>f</code>, <code class='datatype'>mixed</code> ... <code class='argument'>bind_args</code>)</code></dd> + <dd><code>Stdio.Terminfo.Termcap Stdio.Terminfo.Termcap(<code class='datatype'>string</code> <code class='argument'>cap</code>, <code class='object unresolved'>TermcapDB</code>|<code class='datatype'>void</code> <code class='argument'>tcdb</code>, <code class='datatype'>int</code>|<code class='datatype'>void</code> <code class='argument'>maxrecurse</code>)</code></dd> </dl> - </dd></dl><dl><dt><h2 class='header'>Module Function.Placeholder</h2> - </dt><dd><dl class='group--doc'> - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Placeholder arguments for <code>Function.bind</code> - </dd></dl> + - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Constant - arg0 - Constant - arg1 - Constant - arg2 - Constant - arg3 - Constant - arg4 - Constant - arg5 - Constant - arg6 - Constant - arg7 - Constant - arg8 - Constant - arg9 - </dt> - <dd><code><code class='datatype'>constant</code> Function.Placeholder.<code class='constant'>arg0</code></code> - <code><code class='datatype'>constant</code> Function.Placeholder.<code class='constant'>arg1</code></code> - <code><code class='datatype'>constant</code> Function.Placeholder.<code class='constant'>arg2</code></code> - <code><code class='datatype'>constant</code> Function.Placeholder.<code class='constant'>arg3</code></code> - <code><code class='datatype'>constant</code> Function.Placeholder.<code class='constant'>arg4</code></code> - <code><code class='datatype'>constant</code> Function.Placeholder.<code class='constant'>arg5</code></code> - <code><code class='datatype'>constant</code> Function.Placeholder.<code class='constant'>arg6</code></code> - <code><code class='datatype'>constant</code> Function.Placeholder.<code class='constant'>arg7</code></code> - <code><code class='datatype'>constant</code> Function.Placeholder.<code class='constant'>arg8</code></code> - <code><code class='datatype'>constant</code> Function.Placeholder.<code class='constant'>arg9</code></code></dd> + - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>arg<n> will return an instance of <code>Arg</code> that returns the n:th arg. - For convenience for c++11 developers _0, _1 etc also works. - Note that arg0 is the first argument, not arg1 - </dd></dl> - - + <hr /> <dl class='group--doc'> - <dt class='head--type'>Variable - rest - </dt> - <dd><code><code class='object unresolved'>Arg</code> Function.Placeholder.rest</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Return all arguments not used by any <code>Arg</code> or <code>Splice</code>. - Unlike <code>Splice</code> this will return non-continous unused arguments. - </dd> - <dt class='head--doc'>Example</dt> - <dd class='example'><pre>This creates a version of call_out that has the function argument as - the last argument - <pre><code>import Function.Placeholder; - Function.bind( call_out, Arg(-1), rest)</code></pre> - </pre></dd></dl> - <dl><dt><h2 class='header'>Class Function.Placeholder.Arg</h2> - </dt><dd><dl class='group--doc'> - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Arg(x) returns the value of argument X - </dd></dl> - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - create - </dt> - <dd><code>Function.Placeholder.Arg Function.Placeholder.Arg(<code class='datatype'>int</code> <code class='argument'>num</code>)</code></dd> - </dl> - - - <hr /> - <dl class='group--doc'> + <dt class='head--type'>Inherit - Base + TermMachine </dt> - <dd><code>inherit Base : Base</code></dd> + <dd><code>inherit TermMachine : TermMachine</code></dd> </dl> <hr /> <dl class='group--doc'> - <dt class='head--type'>Variable - num - </dt> - <dd><code><code class='datatype'>int</code> Function.Placeholder.Arg.num</code></dd> - </dl> - - - <hr /> - <dl class='group--doc'> + <dt class='head--type'>Method - value + tputs </dt> - <dd><code><code class='datatype'>mixed</code> value(<code class='object unresolved'>bind</code> <code class='argument'>x</code>, <code class='datatype'>array</code> <code class='argument'>args</code>)</code></dd> + <dd><code><code class='datatype'>string</code> tputs(<code class='datatype'>string</code> <code class='argument'>s</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>The function that is called to return the argument value. + <dd class='body--doc'>Put termcap string </dd></dl> - </dd></dl><dl><dt><h2 class='header'>Class Function.Placeholder.Expr</h2> + </dd></dl><dl><dt><h2 class='header'>Class Stdio.Terminfo.TermcapDB</h2> </dt><dd><dl class='group--doc'> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Expr(x) returns the result of calling <code>x</code>. - The function will be passed the list of arguments. - If _splice is true, zero or more argument is returned in an array - Function.Placeholder.arg1 is thus more or less equivalent to - <pre><code>Expr(lambda(array args){return args[1];}); - </code></pre> + <dd class='body--doc'>Termcap database + </dd></dl></dd></dl><dl><dt><h2 class='header'>Class Stdio.Terminfo.Terminfo</h2> + </dt><dd><dl class='group--doc'> + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Terminfo terminal description object </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Variable - func - Variable - _splice + aliases </dt> - <dd><code><code class='datatype'>function</code>(:<code class='datatype void'>void</code>) Function.Placeholder.Expr.func</code> - <code><code class='datatype'>void</code>|<code class='object unresolved'>bool</code> Function.Placeholder.Expr._splice</code></dd> + <dd><code><code class='datatype'>array</code>(<code class='datatype'>string</code>) Stdio.Terminfo.Terminfo.aliases</code></dd> </dl>
2592: <dt class='head--type'>Method create </dt> - <dd><code>Function.Placeholder.Expr Function.Placeholder.Expr(<code class='datatype'>function</code>(:<code class='datatype void'>void</code>) <code class='argument'>func</code>, <code class='datatype'>void</code>|<code class='object unresolved'>bool</code> <code class='argument'>_splice</code>)</code></dd> + <dd><code>Stdio.Terminfo.Terminfo Stdio.Terminfo.Terminfo(<code class='datatype'>string</code> <code class='argument'>filename</code>)</code></dd> </dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Inherit - Base + TermMachine </dt> - <dd><code>inherit Base : Base</code></dd> + <dd><code>inherit TermMachine : TermMachine</code></dd> </dl> - </dd></dl><dl><dt><h2 class='header'>Class Function.Placeholder.Splice</h2> - </dt><dd><dl class='group--doc'> - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Splice(from) adds all arguments starting with argument number <code class='expr'>from</code>, - optionally ending with end. - Equivalent to <code class='expr'>args[from .. end]</code> - </dd></dl> + - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - create - </dt> - <dd><code>Function.Placeholder.Splice Function.Placeholder.Splice(<code class='datatype'>int</code> <code class='argument'>from</code>, <code class='datatype'>void</code>|<code class='datatype'>int</code> <code class='argument'>end</code>)</code></dd> - </dl> + - + <hr /> <dl class='group--doc'> - <dt class='head--type'>Variable - from - Variable - end - </dt> - <dd><code><code class='datatype'>int</code> Function.Placeholder.Splice.from</code> - <code><code class='datatype'>void</code>|<code class='datatype'>int</code> Function.Placeholder.Splice.end</code></dd> - </dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Inherit - Base - </dt> - <dd><code>inherit Base : Base</code></dd> - </dl> - </dd></dl></dd></dl></dd></dl><dl><dt><h2 class='header'>Module Program</h2> - </dt><dd> - - <hr /> - <dl class='group--doc'> + <dt class='head--type'>Method - all_inherits + tputs </dt> - <dd><code><code class='datatype'>array</code>(<code class='datatype'>program</code>) all_inherits(<code class='datatype'>program</code> <code class='argument'>p</code>)</code></dd> - + <dd><code><code class='datatype'>string</code> tputs(<code class='datatype'>string</code> <code class='argument'>s</code>)</code></dd> + <dt class='head--fixme'>FIXME</dt> + <dd class='body--fixme'>Document this function + </dd></dl> + </dd></dl><dl><dt><h2 class='header'>Class Stdio.Terminfo.TerminfoDB</h2> + </dt><dd><dl class='group--doc'> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Enumerate all programs this program inherits, directly or indirectly. - Similar to inherit_tree() but returns a flat array. - </dd> - <dt class='head--doc'>Example</dt> - <dd class='example'><pre>> class a{} - > class b{} - > class c{ inherit a; } - > class d{ inherit b; inherit c; } - > Program.inherit_tree(d); - Result: ({ /* 3 elements */ - b, - c, - a - }) - </pre></dd></dl> + <dd class='body--doc'>Terminfo database for a single directory. + </dd></dl></dd></dl></dd></dl><dl><dt><h2 class='header'>Class Stdio.Readline</h2> + </dt><dd> - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - defined + add_to_kill_ring </dt> - <dd><code><code class='datatype'>string</code> defined(<code class='datatype'>program</code> <code class='argument'>p</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Returns a string with filename and linenumber describing where - the program <code>p</code> was defined. - The returned string is of the format <code class='expr'>"filename:linenumber"</code>. - If it cannot be determined where the program was defined, <code class='expr'>0</code> - (zero) will be returned. + <dd><code><code class='datatype'>void</code> add_to_kill_ring(<code class='datatype'>string</code> <code class='argument'>s</code>)</code></dd> + <dt class='head--fixme'>FIXME</dt> + <dd class='body--fixme'>Document this function </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - defined + create </dt> - <dd><code><code class='datatype'>string</code> defined(<code class='datatype'>program</code> <code class='argument'>x</code>, <code class='datatype'>string</code> <code class='argument'>identifier</code>)</code></dd> + <dd><code>Stdio.Readline Stdio.Readline(<code class='datatype'>object</code>|<code class='datatype'>void</code> <code class='argument'>infd</code>, <code class='datatype'>object</code>|<code class='datatype'>string</code>|<code class='datatype'>void</code> <code class='argument'>interm</code>, <code class='datatype'>object</code>|<code class='datatype'>void</code> <code class='argument'>outfd</code>, <code class='datatype'>object</code>|<code class='datatype'>string</code>|<code class='datatype'>void</code> <code class='argument'>outterm</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Returns a string with filename and linenumber where <code>idenfifier</code> - in <code>x</code> was defined. - Returns <code class='expr'>0</code> (zero) when no line can be found, e.g. for - builtin functions. - If <code>idenfier</code> can not be found in <code>x</code> this function returns - where the program is defined. + <dd class='body--doc'>Creates a Readline object, that takes input from <code>infd</code> and has output + on <code>outfd</code>. + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>infd</code></dt> + <dd></dd><dd class='body--doc'>Defaults to <code>Stdio.stdin</code>. + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>interm</code></dt> + <dd></dd><dd class='body--doc'>Defaults to <code>Stdio.Terminfo.getTerm()</code>. + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>outfd</code></dt> + <dd></dd><dd class='body--doc'>Defaults to <code>infd</code>, unless <code>infd</code> is 0, in which case + <code>outfd</code> defaults to <code>Stdio.stdout</code>. + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>outterm</code></dt> + <dd></dd><dd class='body--doc'>Defaults to <code>interm</code>. </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - implements + delete </dt> - <dd><code><code class='datatype'>int</code> implements(<code class='datatype'>program</code> <code class='argument'>prog</code>, <code class='datatype'>program</code> <code class='argument'>api</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Returns 1 if <code>prog</code> implements <code>api</code>. + <dd><code><code class='datatype'>void</code> delete(<code class='datatype'>int</code> <code class='argument'>p1</code>, <code class='datatype'>int</code> <code class='argument'>p2</code>)</code></dd> + <dt class='head--fixme'>FIXME</dt> + <dd class='body--fixme'>Document this function </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - inherit_list + delta_history </dt> - <dd><code><code class='datatype'>array</code>(<code class='datatype'>program</code>) inherit_list(<code class='datatype'>program</code> <code class='argument'>p</code>)</code></dd> + <dd><code><code class='datatype'>void</code> delta_history(<code class='datatype'>int</code> <code class='argument'>d</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Returns an array with the programs that <code>p</code> has inherited. + <dd class='body--doc'>Changes the line to a line from the history <code>d</code> steps from the + current entry (0 being the current line, negative values older, + and positive values newer). + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>Only effective if you have a history object. </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - inherit_tree + edit </dt> - <dd><code><code class='datatype'>array</code> inherit_tree(<code class='datatype'>program</code> <code class='argument'>p</code>)</code></dd> + <dd><code><code class='datatype'>string</code> edit(<code class='datatype'>string</code> <code class='argument'>data</code>, <code class='datatype'>string</code>|<code class='datatype'>void</code> <code class='argument'>local_prompt</code>, <code class='datatype'>array</code>(<code class='datatype'>string</code>)|<code class='datatype'>void</code> <code class='argument'>attrs</code>)</code></dd> + <dt class='head--fixme'>FIXME</dt> + <dd class='body--fixme'>Document this function + </dd></dl> - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Recursively builds a inheritance tree by - fetching programs inheritance lists. - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>Returns an array with programs or arrays - as elements. - </dd> - <dt class='head--doc'>Example</dt> - <dd class='example'><pre>> class a{} - > class b{} - > class c{ inherit a; } - > class d{ inherit b; inherit c; } - > Program.inherit_tree(d); - Result: ({ /* 3 elements */ - d, - ({ /* 1 element */ - program - }), - ({ /* 2 elements */ - c, - ({ /* 1 element */ - program - }) - }) - }) - </pre></dd></dl> + - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - inherits + enable_history </dt> - <dd><code><code class='datatype'>int</code> inherits(<code class='datatype'>program</code>|<code class='datatype'>object</code> <code class='argument'>child</code>, <code class='datatype'>program</code> <code class='argument'>parent</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Returns 1 if <code>child</code> has inherited <code>parent</code>. + <dd><code><code class='datatype'>void</code> enable_history(<code class='datatype'>array</code>(<code class='datatype'>string</code>)|<code class='object unresolved'>History</code>|<code class='datatype'>int</code> <code class='argument'>hist</code>)</code></dd> + <dt class='head--fixme'>FIXME</dt> + <dd class='body--fixme'>Document this function </dd></dl> - </dd></dl><dl><dt><h2 class='header'>Module ADT</h2> - </dt><dd><dl class='group--doc'> - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Various Abstract Data Types. - </dd></dl> + - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Inherit - _ADT - </dt> - <dd><code>inherit _ADT : _ADT</code></dd> - </dl> - <dl><dt><h2 class='header'>Class ADT.BitBuffer</h2> - </dt><dd><dl class='group--doc'> - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Implements a FIFO bit buffer, i.e. a buffer that operates on bits - instead of bytes. It is not designed for performance, but as a way - to handle complicated file formats and other standards where you - may need to work on unaligned data units of sub byte size, without - having to fry your brain while keeping track of all the bits - yourself. - </dd> - <dt class='head--doc'>Example</dt> - <dd class='example'><pre>> ADT.BitBuffer b=ADT.BitBuffer(); - > b->put1(2); - (1) Result: ADT.BitBuffer(11) - > b->put0(15); - (2) Result: ADT.BitBuffer("\300\0"0) - > b->drain(); - (3) Result: "\300\0" - > sizeof(b); - (4) Result: 1 - </pre></dd></dl> + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - _sizeof + eof </dt> - <dd><code><code class='datatype'>int</code> sizeof( ADT.BitBuffer arg )</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'><code>sizeof()</code> will return the number of bits in the buffer. + <dd><code><code class='datatype'>void</code> eof()</code></dd> + <dt class='head--fixme'>FIXME</dt> + <dd class='body--fixme'>Document this function </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - create + get_history </dt> - <dd><code>ADT.BitBuffer ADT.BitBuffer(<code class='datatype'>void</code>|<code class='datatype'>string</code> <code class='argument'>data</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>The buffer can be initialized with initial data during creation. + <dd><code><code class='object unresolved'>History</code> get_history()</code></dd> + <dt class='head--fixme'>FIXME</dt> + <dd class='body--fixme'>Document this function </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - drain + get_input_controller </dt> - <dd><code><code class='datatype'>string</code> drain()</code></dd> + <dd><code><code class='object unresolved'>InputController</code> get_input_controller()</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Drains the buffer of all full (8-bits wide) bytes. + <dd class='body--doc'>get current input control object + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>Terminal input controller object </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - feed + get_output_controller </dt> - <dd><code><code class='object unresolved'>this_program</code> feed(<code class='datatype'>string</code> <code class='argument'>x</code>)</code></dd> + <dd><code><code class='object unresolved'>OutputController</code> get_output_controller()</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Adds full bytes to the buffer. + <dd class='body--doc'>get current output control object + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>Terminal output controller object </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - get + get_prompt </dt> - <dd><code><code class='datatype'>int</code> get(<code class='datatype'>int</code> <code class='argument'>bits</code>)</code></dd> + <dd><code><code class='datatype'>string</code> get_prompt()</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Get <code>bits</code> from the buffer. - </dd> - <dt class='head--doc'>Throws</dt> - <dd class='body--doc'>Throws an error in case of data underflow. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>The bits are extracted with the most significant bit first. + <dd class='body--doc'>Return the current prompt string. </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - put + getcursorpos </dt> - <dd><code><code class='object unresolved'>this_program</code> put(<code class='datatype'>int</code> <code class='argument'>value</code>, <code class='datatype'>int</code> <code class='argument'>bits</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Put <code>bits</code> number of bits with the value <code>value</code> into the - buffer. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'><code>value</code> must not be larger than what can be stored with the - number of bits given in <code>bits</code>. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>The bits are added to the buffer with the most significant - bit first. + <dd><code><code class='datatype'>int</code> getcursorpos()</code></dd> + <dt class='head--fixme'>FIXME</dt> + <dd class='body--fixme'>Document this function </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - put0 + getmark </dt> - <dd><code><code class='object unresolved'>this_program</code> put0(<code class='datatype'>int</code> <code class='argument'>bits</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Put <code>bits</code> number of 0 bits into the buffer. + <dd><code><code class='datatype'>int</code> getmark()</code></dd> + <dt class='head--fixme'>FIXME</dt> + <dd class='body--fixme'>Document this function </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - put1 + gettext </dt> - <dd><code><code class='object unresolved'>this_program</code> put1(<code class='datatype'>int</code> <code class='argument'>bits</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Put <code>bits</code> number of 1 bits into the buffer. + <dd><code><code class='datatype'>string</code> gettext()</code></dd> + <dt class='head--fixme'>FIXME</dt> + <dd class='body--fixme'>Document this function </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - read + history </dt> - <dd><code><code class='datatype'>string</code> read(<code class='datatype'>void</code>|<code class='datatype'>int</code> <code class='argument'>bytes</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Reads <code>bytes</code> (or less) bytes from the buffer and returns as - string. + <dd><code><code class='datatype'>void</code> history(<code class='datatype'>int</code> <code class='argument'>n</code>)</code></dd> + <dt class='head--fixme'>FIXME</dt> + <dd class='body--fixme'>Document this function </dd></dl> - </dd></dl><dl><dt><h2 class='header'>Class ADT.CircularList</h2> - </dt><dd><dl class='group--doc'> - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>This is an circular list implemented by an array. It has a constant time - complexity for pop and push. It has a limited max size but it can be - increased with the method allocate. - </dd></dl> + - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - _equal + insert </dt> - <dd><code><code class='datatype'>bool</code> equal(ADT.CircularList from, <code class='datatype'>mixed</code> <code class='argument'>coll</code>)</code></dd> - - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>Returns <tt>true</tt> if the object <code>coll</code> is a <code>CircularList</code> - and contains the same values in the same order. + <dd><code><code class='datatype'>void</code> insert(<code class='datatype'>string</code> <code class='argument'>s</code>, <code class='datatype'>int</code> <code class='argument'>p</code>)</code></dd> + <dt class='head--fixme'>FIXME</dt> + <dd class='body--fixme'>Document this function </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - _get_iterator + kill </dt> - <dd><code>ADT.CircularList a; - foreach( a; index; value ) or </code><code><code class='object unresolved'>CircularListIterator</code> _get_iterator(<code class='datatype'>void</code>|<code class='datatype'>int</code> <code class='argument'>ind</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Create and initiate a new CircularListIterator that could be used - to iterate over this list. - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>ind</code></dt> - <dd></dd><dd class='body--doc'>If an <code>ind</code> value is supplied the iterator will be positioned at - that index. - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>An iterator. + <dd><code><code class='datatype'>void</code> kill(<code class='datatype'>int</code> <code class='argument'>p1</code>, <code class='datatype'>int</code> <code class='argument'>p2</code>)</code></dd> + <dt class='head--fixme'>FIXME</dt> + <dd class='body--fixme'>Document this function </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - _indices + kill_ring_yank </dt> - <dd><code><code class='datatype'>array</code> indices( ADT.CircularList arg )</code></dd> - - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>The indices in this list as an array. + <dd><code><code class='datatype'>string</code> kill_ring_yank()</code></dd> + <dt class='head--fixme'>FIXME</dt> + <dd class='body--fixme'>Document this function </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - _insert_element + list_completions </dt> - <dd><code><code class='datatype'>void</code> _insert_element(<code class='datatype'>int</code> <code class='argument'>index</code>, <code class='datatype'>mixed</code> <code class='argument'>value</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Insert an element in the list at the position <code>index</code>, the value - at the position <code>index</code> and all above will have their index increased - by one. - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>index</code></dt> - <dd></dd><dd class='body--doc'>The index to insert the value at. - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>value</code></dt> - <dd></dd><dd class='body--doc'>The new value. - </dd> - <dt class='head--doc'>Throws</dt> - <dd class='body--doc'>An error if the index is out of range. + <dd><code><code class='datatype'>void</code> list_completions(<code class='datatype'>array</code>(<code class='datatype'>string</code>) <code class='argument'>c</code>)</code></dd> + <dt class='head--fixme'>FIXME</dt> + <dd class='body--fixme'>Document this function </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - _remove_element + message </dt> - <dd><code><code class='datatype'>mixed</code> _remove_element(<code class='datatype'>int</code> <code class='argument'>index</code>)</code></dd> + <dd><code><code class='datatype'>void</code> message(<code class='datatype'>string</code> <code class='argument'>msg</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Remove the values at index <code>index</code> from the list. - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>index</code></dt> - <dd></dd><dd class='body--doc'>The index to remove. - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>The removed value. - </dd> - <dt class='head--doc'>Throws</dt> - <dd class='body--doc'>An error if the index is out of range. + <dd class='body--doc'>Print a message to the output device </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - _search + newline </dt> - <dd><code><code class='datatype'>int</code> search(ADT.CircularList from, <code class='datatype'>mixed</code> <code class='argument'>value</code>, <code class='datatype'>void</code>|<code class='datatype'>int</code> <code class='argument'>start</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Search the list for a specific value. Return the index of the first - value that is equal to <code>value</code>. If no value was found <code class='expr'>UNDEFINED</code> - is returned instead - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>value</code></dt> - <dd></dd><dd class='body--doc'>The value to find - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>start</code></dt> - <dd></dd><dd class='body--doc'>If a start value is supplied it will start searching at the index - <code>start</code>. - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>Returns the index of the found value or <code class='expr'>UNDEFINED</code>. - </dd> - <dt class='head--doc'>Throws</dt> - <dd class='body--doc'>An error if the start is out of range. + <dd><code><code class='datatype'>string</code> newline()</code></dd> + <dt class='head--fixme'>FIXME</dt> + <dd class='body--fixme'>Document this function </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - _sizeof + pointmark </dt> - <dd><code><code class='datatype'>int</code> sizeof( ADT.CircularList arg )</code></dd> - - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>The number of elements in this list. + <dd><code><code class='datatype'>array</code>(<code class='datatype'>int</code>) pointmark()</code></dd> + <dt class='head--fixme'>FIXME</dt> + <dd class='body--fixme'>Document this function </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - _values + read </dt> - <dd><code><code class='datatype'>array</code> values( ADT.CircularList arg )</code></dd> - - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>The values in this list as an array. + <dd><code><code class='datatype'>string</code> read(<code class='datatype'>string</code>|<code class='datatype'>void</code> <code class='argument'>prompt</code>, <code class='datatype'>array</code>(<code class='datatype'>string</code>)|<code class='datatype'>void</code> <code class='argument'>attrs</code>)</code></dd> + <dt class='head--fixme'>FIXME</dt> + <dd class='body--fixme'>Document this function </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - `+ + redisplay </dt> - <dd><code><code class='object unresolved'>CircularList</code> res = <code class='class'>ADT.CircularList()</code> + <code class='class'>coll</code></code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Addition operator - Append the content of this CircularList and @<code>coll</code> and - return the results as a new <code>CircularList</code>. - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>coll</code></dt> - <dd></dd><dd class='body--doc'>The lists to append to this list - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>The result of the append as a new <code>CircularList</code>. + <dd><code><code class='datatype'>void</code> redisplay(<code class='datatype'>int</code> <code class='argument'>clear</code>, <code class='datatype'>int</code>|<code class='datatype'>void</code> <code class='argument'>nobackup</code>)</code></dd> + <dt class='head--fixme'>FIXME</dt> + <dd class='body--fixme'>Document this function </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - `[] + region </dt> - <dd><code><code class='datatype'>mixed</code> res = <code class='class'>ADT.CircularList()</code>[ <code class='class'>index</code> ]</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Index operator - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>index</code></dt> - <dd></dd><dd class='body--doc'>The index to get the value for, could be negative to index from the end. - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>The value at the index <code>index</code> - </dd> - <dt class='head--doc'>Throws</dt> - <dd class='body--doc'>An error if the index is out of range. + <dd><code><code class='datatype'>string</code> region(<code class='datatype'>int</code> ... <code class='argument'>args</code>)</code></dd> + <dt class='head--fixme'>FIXME</dt> + <dd class='body--fixme'>Document this function </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - `[]= + set_blocking </dt> - <dd><code><code class='class'>ADT.CircularList()</code>[ <code class='class'>index</code> ] = <code class='class'>value</code></code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Index assign operator. - Set the value at the index <code>index</code> to be <code>value</code> - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>index</code></dt> - <dd></dd><dd class='body--doc'>The index to set - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>value</code></dt> - <dd></dd><dd class='body--doc'>The new value - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>The new value at the index <code>index</code> - </dd> - <dt class='head--doc'>Throws</dt> - <dd class='body--doc'>An error if the index is out of range. + <dd><code><code class='datatype'>void</code> set_blocking()</code></dd> + <dt class='head--fixme'>FIXME</dt> + <dd class='body--fixme'>Document this function </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - add + set_echo </dt> - <dd><code><code class='datatype'>void</code> add(<code class='datatype'>mixed</code> <code class='argument'>value</code>)</code></dd> + <dd><code><code class='datatype'>void</code> set_echo(<code class='datatype'>int</code> <code class='argument'>onoff</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Add a value at the front of the list + <dd class='body--doc'>Set text echo on or off. </dd> - <dt class='head--doc'>Parameter <code class='parameter'>value</code></dt> - <dd></dd><dd class='body--doc'>The value to add. - </dd> - <dt class='head--doc'>Throws</dt> - <dd class='body--doc'>An error if the list is full. + <dt class='head--doc'>Parameter <code class='parameter'>onoff</code></dt> + <dd></dd><dd class='body--doc'>1 for echo, 0 for no echo. </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - allocate + set_nonblocking </dt> - <dd><code><code class='datatype'>void</code> allocate(<code class='datatype'>int</code> <code class='argument'>elements</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Increase the maxsize of the CircularlList. - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>elements</code></dt> - <dd></dd><dd class='body--doc'>Add this number of new elements to the list. + <dd><code><code class='datatype'>void</code> set_nonblocking(<code class='datatype'>function</code>(:<code class='datatype void'>void</code>) <code class='argument'>f</code>)</code></dd> + <dt class='head--fixme'>FIXME</dt> + <dd class='body--fixme'>Document this function </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - cast + set_prompt </dt> - <dd><code>(<code class='datatype'>array</code>)ADT.CircularList()</code></dd> + <dd><code><code class='datatype'>string</code> set_prompt(<code class='datatype'>string</code> <code class='argument'>newp</code>, <code class='datatype'>array</code>(<code class='datatype'>string</code>)|<code class='datatype'>void</code> <code class='argument'>newattrs</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Cast operator. + <dd class='body--doc'>Set the prompt string. </dd> - <dt class='head--doc'>Parameter <code class='parameter'>type</code></dt> - <dd></dd><dd class='body--doc'>Casts to this type. - Casts to the following types are supported: - <table class='box'><tr><td><code><code class='key'>"array"</code></code></td><td>Cast the content of this list to an array. - </td></tr> - </table> + <dt class='head--doc'>Parameter <code class='parameter'>newp</code></dt> + <dd></dd><dd class='body--doc'>New prompt string </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>An array with the contents of this list. + <dt class='head--doc'>Parameter <code class='parameter'>newattrs</code></dt> + <dd></dd><dd class='body--doc'>Terminal attributes </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - clear + setcursorpos </dt> - <dd><code><code class='datatype'>void</code> clear()</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Clear the contents of the list. + <dd><code><code class='datatype'>int</code> setcursorpos(<code class='datatype'>int</code> <code class='argument'>p</code>)</code></dd> + <dt class='head--fixme'>FIXME</dt> + <dd class='body--fixme'>Document this function </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - create + setmark </dt> - <dd><code>ADT.CircularList ADT.CircularList(<code class='datatype'>array</code>|<code class='datatype'>int</code> <code class='argument'>arg</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Creates a new <code>CircularList</code> around the array arg or a new - <code>CircularList</code> with the maximum size of arg. + <dd><code><code class='datatype'>int</code> setmark(<code class='datatype'>int</code> <code class='argument'>p</code>)</code></dd> + <dt class='head--fixme'>FIXME</dt> + <dd class='body--fixme'>Document this function </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - delete_value + write </dt> - <dd><code><code class='datatype'>int</code> delete_value(<code class='datatype'>mixed</code> <code class='argument'>value</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Remove the first occurrence of the value <code>value</code> from the list. - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>value</code></dt> - <dd></dd><dd class='body--doc'>The value to remove from the list. - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>The index of the removed element or -1 if there was no value to - remove. + <dd><code><code class='datatype'>void</code> write(<code class='datatype'>string</code> <code class='argument'>msg</code>, <code class='datatype'>void</code>|<code class='datatype'>int</code> <code class='argument'>word_wrap</code>)</code></dd> + <dt class='head--fixme'>FIXME</dt> + <dd class='body--fixme'>Document this function </dd></dl> - + <dl><dt><h2 class='header'>Class Stdio.Readline.DefaultEditKeys</h2> + </dt><dd> - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - first + backward_char </dt> - <dd><code><code class='object unresolved'>CircularListIterator</code> first()</code></dd> + <dd><code><code class='datatype'>void</code> backward_char()</code></dd> + </dl> - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Create and initiate a new CircularListIterator that could be used - to iterate over this list. - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>An iterator positioned at the first element in the list. - </dd></dl> + - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - is_empty + backward_delete_char </dt> - <dd><code><code class='datatype'>bool</code> is_empty()</code></dd> + <dd><code><code class='datatype'>void</code> backward_delete_char()</code></dd> + </dl> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>Returns <code class='expr'>1</code> if the list is empty otherwise <code class='expr'>0</code>. - </dd></dl> + - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - last + backward_kill_word </dt> - <dd><code><code class='object unresolved'>CircularListIterator</code> last()</code></dd> + <dd><code><code class='datatype'>void</code> backward_kill_word()</code></dd> + </dl> - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Create and initiate a new CircularListIterator that could be used - to iterate over this list. - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>An iterator positioned after the last element in the list. - </dd></dl> + - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - max_size + backward_word </dt> - <dd><code><code class='datatype'>int</code> max_size()</code></dd> + <dd><code><code class='datatype'>void</code> backward_word()</code></dd> + </dl> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>Returns the maximal size of this list. - </dd></dl> + - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - peek_back + beginning_of_line </dt> - <dd><code><code class='datatype'>mixed</code> peek_back()</code></dd> + <dd><code><code class='datatype'>void</code> beginning_of_line()</code></dd> + </dl> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>The value at the back of the list but do not remove it from the list. - </dd></dl> + - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - peek_front + capitalize_word </dt> - <dd><code><code class='datatype'>mixed</code> peek_front()</code></dd> + <dd><code><code class='datatype'>void</code> capitalize_word()</code></dd> + </dl> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>The value at the front of the list but do not remove it from the list. - </dd></dl> + - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - pop_back + clear_screen </dt> - <dd><code><code class='datatype'>mixed</code> pop_back()</code></dd> + <dd><code><code class='datatype'>void</code> clear_screen()</code></dd> + </dl> - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Remove the value at the back of the list and return it. - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>The value at the back of the list. - </dd></dl> + - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - pop_front + create </dt> - <dd><code><code class='datatype'>mixed</code> pop_front()</code></dd> + <dd><code>Stdio.Readline.DefaultEditKeys Stdio.Readline.DefaultEditKeys(<code class='datatype'>object</code> <code class='argument'>readline</code>)</code></dd> + </dl> - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Remove the value at the front of the list and return it. - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>The value at the front of the list. - </dd></dl> + - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - push_back + delete_char </dt> - <dd><code><code class='datatype'>void</code> push_back(<code class='datatype'>mixed</code> <code class='argument'>value</code>)</code></dd> + <dd><code><code class='datatype'>void</code> delete_char()</code></dd> + </dl> - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Add a new value at the end of the list. - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>value</code></dt> - <dd></dd><dd class='body--doc'>The value to add. - </dd></dl> + - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - push_front + delete_char_or_eof </dt> - <dd><code><code class='datatype'>void</code> push_front(<code class='datatype'>mixed</code> <code class='argument'>value</code>)</code></dd> + <dd><code><code class='datatype'>void</code> delete_char_or_eof()</code></dd> + </dl> - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Add a new value at the end of the list. - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>value</code></dt> - <dd></dd><dd class='body--doc'>The value to add. - </dd></dl> - <dl><dt><h2 class='header'>Class ADT.CircularList.CircularListIterator</h2> - </dt><dd><dl class='group--doc'> - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>This is the iterator for the CircularList. It implements the - IndexIterator and the OutputIterator. - </dd></dl> + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - _equal + down_history </dt> - <dd><code><code class='datatype'>bool</code> equal(ADT.CircularList.CircularListIterator from, <code class='datatype'>mixed</code> <code class='argument'>iter</code>)</code></dd> + <dd><code><code class='datatype'>void</code> down_history()</code></dd> + </dl> - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Compare this iterator with another iterator. - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>iter</code></dt> - <dd></dd><dd class='body--doc'>The iterator to compare with - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>Returns <tt>true</tt> if both iterators iterates over the same - objects and are positioned at the same spot. - </dd></dl> + - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - `! + downcase_word </dt> - <dd><code><code class='datatype'>bool</code> res = !<code class='class'>ADT.CircularList.CircularListIterator()</code></code></dd> + <dd><code><code class='datatype'>void</code> downcase_word()</code></dd> + </dl> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>Returns <tt>false</tt> if the iterator has reached the end. - </dd></dl> + - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - `+ + end_of_line </dt> - <dd><code><code class='object unresolved'>CircularListIterator</code> res = <code class='class'>ADT.CircularList.CircularListIterator()</code> + <code class='class'>steps</code></code></dd> + <dd><code><code class='datatype'>void</code> end_of_line()</code></dd> + </dl> - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Move the iterator <code>steps</code> steps forward (negative value on <code>steps</code> - will cause the iterator to move backwards) and return the result - as a new iterator. - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>A new iterator positioned <code>steps</code> steps forward. - </dd></dl> + - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - `+= + forward_char </dt> - <dd><code><code class='class'>ADT.CircularList.CircularListIterator()</code> += <code class='class'>steps</code></code></dd> + <dd><code><code class='datatype'>void</code> forward_char()</code></dd> + </dl> - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Move this iterator <code>steps</code> steps forward (negative value on <code>steps</code> - will cause the iterator to move backwards) and return the result. - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>This iterator positioned <code>steps</code> steps forward. - </dd></dl> + - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - `- + forward_word </dt> - <dd><code><code class='object unresolved'>CircularListIterator</code> res = <code class='class'>ADT.CircularList.CircularListIterator()</code> - <code class='class'>steps</code></code></dd> + <dd><code><code class='datatype'>void</code> forward_word()</code></dd> + </dl> - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Move the iterator <code>steps</code> steps backwards (negative value on - <code>steps</code> will cause the iterator to move forwards) and return - the result as a new iterator. - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>A new iterator positioned <code>steps</code> steps backwards. - </dd></dl> + - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - `< + kill_line </dt> - <dd><code><code class='datatype'>bool</code> res = <code class='class'>ADT.CircularList.CircularListIterator()</code> < <code class='class'>iter</code></code></dd> + <dd><code><code class='datatype'>void</code> kill_line()</code></dd> + </dl> - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Less then operator - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>Returns <tt>true</tt> if this iterator has a lower index - then <code>iter</code>. - </dd></dl> + - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - `> + kill_region </dt> - <dd><code><code class='datatype'>bool</code> res = <code class='class'>ADT.CircularList.CircularListIterator()</code> > <code class='class'>iter</code></code></dd> + <dd><code><code class='datatype'>void</code> kill_region()</code></dd> + </dl> - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Greater then operator - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>Returns <tt>true</tt> if this iterator has a higher index - then <code>iter</code>. - </dd></dl> + - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - create + kill_ring_save </dt> - <dd><code>ADT.CircularList.CircularListIterator ADT.CircularList.CircularListIterator(<code class='datatype'>object</code> <code class='argument'>list</code>, <code class='datatype'>void</code>|<code class='datatype'>int</code> <code class='argument'>start</code>)</code></dd> + <dd><code><code class='datatype'>void</code> kill_ring_save()</code></dd> + </dl> - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Creates a new iterator for the CircularList <code>list</code>. If <code>start</code> is - supplied it will try to position the iterator at <code>start</code>. - </dd></dl> + - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - distance + kill_whole_line </dt> - <dd><code><code class='datatype'>int</code> distance(<code class='datatype'>object</code> <code class='argument'>iter</code>)</code></dd> + <dd><code><code class='datatype'>void</code> kill_whole_line()</code></dd> + </dl> - <dt class='head--doc'>Parameter <code class='parameter'>iter</code></dt> - <dd></dd><dd class='body--doc'>The iterator to measure the distance to. - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>Returns distance between this iterator and <code>iter</code>. - </dd> - <dt class='head--doc'>Throws</dt> - <dd class='body--doc'>An error if the two iterator could not be compared. - </dd></dl> + - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - get_collection + kill_word </dt> - <dd><code><code class='object unresolved'>CircularList</code> get_collection()</code></dd> + <dd><code><code class='datatype'>void</code> kill_word()</code></dd> + </dl> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>Returns the CircularList this iterator currently iterates over. - </dd></dl> + - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - has_next + newline </dt> - <dd><code><code class='datatype'>bool</code> has_next(<code class='datatype'>void</code>|<code class='datatype'>int</code> <code class='argument'>steps</code>)</code></dd> + <dd><code><code class='datatype'>void</code> newline()</code></dd> + </dl> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>Returns <tt>true</tt> if it is possible to move <code>steps</code> steps - forwards, if <code>steps</code> weren't supplied it check if it is - possible to move one step forward. - </dd></dl> + - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - has_previous + quoted_insert </dt> - <dd><code><code class='datatype'>bool</code> has_previous(<code class='datatype'>void</code>|<code class='datatype'>int</code> <code class='argument'>steps</code>)</code></dd> + <dd><code><code class='datatype'>void</code> quoted_insert()</code></dd> + </dl> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>Returns <tt>true</tt> if it is possible to move <code>steps</code> steps - backwards, if <code>steps</code> weren't supplied it check if it is - possible to move one step backward. - </dd></dl> + - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - index + redisplay </dt> - <dd><code><code class='datatype'>int</code> index()</code></dd> + <dd><code><code class='datatype'>void</code> redisplay()</code></dd> + </dl> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>The index at the current position. - </dd></dl> + - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - set_value + self_insert_command </dt> - <dd><code><code class='datatype'>mixed</code> set_value(<code class='datatype'>mixed</code> <code class='argument'>val</code>)</code></dd> + <dd><code><code class='datatype'>void</code> self_insert_command(<code class='datatype'>string</code> <code class='argument'>str</code>)</code></dd> + </dl> - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Set the value at the current position. - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>val</code></dt> - <dd></dd><dd class='body--doc'>The new value - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>Returns the old value - </dd></dl> + - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - value + set_default_bindings </dt> - <dd><code><code class='datatype'>mixed</code> value()</code></dd> + <dd><code><code class='modifier'>protected</code> <code class='datatype'>void</code> set_default_bindings()</code></dd> + </dl> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>The value at the current position. - </dd></dl> - </dd></dl></dd></dl><dl><dt><h2 class='header'>Class ADT.Heap</h2> - </dt><dd><dl class='group--doc'> - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>This class implements a (min-)heap. The value of a child node will - always be greater than or equal to the value of its parent node. - Thus, the top node of the heap will always hold the smallest value. - </dd></dl> + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - _sizeof + set_mark </dt> - <dd><code><code class='datatype'>int</code> sizeof( ADT.Heap arg )</code></dd> + <dd><code><code class='datatype'>void</code> set_mark()</code></dd> + </dl> - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Returns the number of elements in the heap. - </dd></dl> + - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - adjust + swap_mark_and_point </dt> - <dd><code><code class='object unresolved'>Element</code> adjust(<code class='datatype'>mixed</code> <code class='argument'>value</code>)</code></dd> + <dd><code><code class='datatype'>void</code> swap_mark_and_point()</code></dd> + </dl> - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Takes a value in the heap and sorts it through the heap to maintain - its sort criteria (increasing order). - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>value</code></dt> - <dd></dd><dd class='body--doc'>Either the element handle returned by <code>push()</code>, or the pushed - value itself. - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>Returns the element handle for the value (if present in the heap), - and <code class='expr'>0</code> (zero) otherwise. - </dd></dl> + - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - low_peek + transpose_chars </dt> - <dd><code><code class='object unresolved'>Element</code> low_peek()</code></dd> + <dd><code><code class='datatype'>void</code> transpose_chars()</code></dd> + </dl> - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Returns the <code>Element</code> on top of the heap (which is also the one with - the smallest value in the heap) without removing it. - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>Returns the smallest <code>Element</code> on the heap if any, and - <code class='expr'>UNDEFINED</code> otherwise. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>peek()</code>, <code>low_pop()</code>, <code>pop()</code> - </dd></dl> + - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - low_pop + up_history </dt> - <dd><code><code class='object unresolved'>Element</code> low_pop()</code></dd> + <dd><code><code class='datatype'>void</code> up_history()</code></dd> + </dl> - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Removes and returns the <code>Element</code> on top of the heap, - which also is the smallest value in the heap. - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>Returns <code>UNDEFINED</code> if the heap is empty. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>pop()</code>, <code>peek()</code>, <code>push()</code>, <code>remove()</code> - </dd></dl> + - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - peek + upcase_word </dt> - <dd><code><code class='datatype'>mixed</code> peek()</code></dd> + <dd><code><code class='datatype'>void</code> upcase_word()</code></dd> + </dl> - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Returns the item on top of the heap (which is also the smallest value - in the heap) without removing it. - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>Returns the smallest value on the heap if any, and - <code class='expr'>UNDEFINED</code> otherwise. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>low_peek()</code>, <code>pop()</code> - </dd></dl> + - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - pop + yank </dt> - <dd><code><code class='datatype'>mixed</code> pop()</code></dd> + <dd><code><code class='datatype'>void</code> yank()</code></dd> + </dl> + </dd></dl><dl><dt><h2 class='header'>Class Stdio.Readline.History</h2> + </dt><dd> - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Removes and returns the item on top of the heap, - which also is the smallest value in the heap. - </dd> - <dt class='head--doc'>Throws</dt> - <dd class='body--doc'>Throws an error if the heap is empty. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>low_pop()</code>, <code>peek()</code>, <code>push()</code>, <code>remove()</code> - </dd></dl> - - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - push + create </dt> - <dd><code><code class='object unresolved'>Element</code> push(<code class='datatype'>mixed</code> <code class='argument'>value</code>)</code></dd> + <dd><code>Stdio.Readline.History Stdio.Readline.History(<code class='datatype'>int</code> <code class='argument'>maxhist</code>, <code class='datatype'>void</code>|<code class='datatype'>array</code>(<code class='datatype'>string</code>) <code class='argument'>hist</code>)</code></dd> + </dl> - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Push an element onto the heap. The heap will automatically sort itself - so that the smallest value will be at the top. - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>Returns an element handle, which can be used with - <code>adjust()</code> and <code>remove()</code>. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>If <code>value</code> is a <code>Heap.Element</code> and already present on the heap - this is equivalent to calling <code>adjust()</code>. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>pop()</code>, <code>remove()</code> - </dd></dl> + - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - remove + encode </dt> - <dd><code><code class='datatype'>void</code> remove(<code class='datatype'>mixed</code> <code class='argument'>value</code>)</code></dd> + <dd><code><code class='datatype'>string</code> encode()</code></dd> + </dl> - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Remove a value from the heap. - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>value</code></dt> - <dd></dd><dd class='body--doc'>Value to remove. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>push()</code>, <code>pop()</code> - </dd></dl> - <dl><dt><h2 class='header'>Class ADT.Heap.Element</h2> - </dt><dd><dl class='group--doc'> - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Heap element. - </dd></dl> + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - create + finishline </dt> - <dd><code>ADT.Heap.Element ADT.Heap.Element(<code class='datatype'>mixed</code> <code class='argument'>value</code>)</code></dd> + <dd><code><code class='datatype'>void</code> finishline(<code class='datatype'>string</code> <code class='argument'>text</code>)</code></dd> </dl> <hr /> <dl class='group--doc'> - <dt class='head--type'>Variable - value + <dt class='head--type'>Method + get_history_num </dt> - <dd><code><code class='datatype'>mixed</code> ADT.Heap.Element.value</code></dd> + <dd><code><code class='datatype'>int</code> get_history_num()</code></dd> </dl> - </dd></dl></dd></dl><dl><dt><h2 class='header'>Class ADT.History</h2> - </dt><dd><dl class='group--doc'> - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>A history is a stack where you can only push entries. When the stack has - reached a certain size the oldest entries are removed on every push. - Other proposed names for this data type is leaking stack and table - (where you push objects onto the table in one end and objects are falling - off the table in the other. - </dd></dl> + - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - _indices - </dt> - <dd><code><code class='datatype'>array</code>(<code class='datatype'>int</code>) indices( ADT.History arg )</code></dd> + - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Returns the index numbers of the history entries - available. - </dd></dl> - - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - _sizeof + history </dt> - <dd><code><code class='datatype'>int</code> sizeof( ADT.History arg )</code></dd> + <dd><code><code class='datatype'>string</code> history(<code class='datatype'>int</code> <code class='argument'>n</code>, <code class='datatype'>string</code> <code class='argument'>text</code>)</code></dd> + </dl> - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>A <code>sizeof</code> operation on this object returns the number - of elements currently in the history, e.g. <= the current - max size. - </dd></dl> +

autodoc.git/ traditional_manual/ chapter_9.html

2017-07-21

2017-07-21 11:36:32 by Pontus Östlund <ponost@roxen.com>