Previous chapter To contents Next chapter

Chapter 14, Other modules

Pike also include a number of smaller modules. These modules implement support for various algorithms, data structures and system routines.

14.1 System

The system module contains some system-specific functions that may or may not be available on your system. Most of these functions do exactly the same thing as their UNIX counterpart. See the UNIX man pages for detailed information about what these functions do on your system.

Please note that these functions are available globally, you do not need to import System to use these functions.

FUNCTION
chroot - change the root directory

SYNTAX
int chroot(string newroot);
int chroot(object(File) obj);

DESCRIPTION
Changes the root directory for this process to the indicated directory.

NOTE
Since this function modifies the directory structure as seen from Pike, you have to modify the environment variables PIKE_MODULE_PATH and PIKE_INCLUDE_PATH to compensate for the new root-directory.

This function only exists on systems that have the chroot(2) system call. The second variant only works on systems that also have the fchroot(2) system call.

FUNCTION
getegid - get the effective group ID

SYNTAX
int getegid();

DESCRIPTION
Get the effective group ID.

SEE ALSO
setuid, getuid, setgid, getgid, seteuid, geteuid and setegid

FUNCTION
geteuid - get the effective user ID

SYNTAX
int geteuid();

DESCRIPTION
Get the effective user ID.

SEE ALSO
setuid, getuid, setgid, getgid, seteuid, setegid and getegid

FUNCTION
getgid - get the group ID

SYNTAX
int getgid();

DESCRIPTION
Get the real group ID.

SEE ALSO
setuid, getuid, setgid, seteuid, geteuid, setegid and getegid

FUNCTION
getgroups - get the supplemental group access list

SYNTAX
array(int) getgroups();

DESCRIPTION
Get the current supplemental group access list for this process.

SEE ALSO
initgroups, setgroups, getgid, setgid, getegid and setegid

FUNCTION
gethostbyaddr - gets information about a host given its address

SYNTAX
array gethostbyaddr(string addr);

DESCRIPTION
Returns an array with information about the specified IP address.

The returned array contains the same information as that returned by gethostbyname().

NOTE
This function only exists on systems that have the gethostbyaddr(2) or similar system call.

SEE ALSO
gethostbyname

FUNCTION
gethostbyname - gets information about a host given its name

SYNTAX
array gethostbyname(string hostname);

DESCRIPTION
Returns an array with information about the specified host.

The array contains three elements:

The first element is the hostname.

The second element is an array(string) of IP numbers for the host.

The third element is an array(string) of aliases for the host.

NOTE
This function only exists on systems that have the gethostbyname(2) or similar system call.

SEE ALSO
gethostbyaddr

FUNCTION
gethostname - get the name of this host

SYNTAX
string gethostname();

DESCRIPTION
Returns a string with the name of the host.

NOTE
This function only exists on systems that have the gethostname(2) or uname(2) system calls.

FUNCTION
getpgrp - get the process group ID

SYNTAX
int getpgrp();
int getpgrp(int pid);

DESCRIPTION
With no arguments or with pid equal to zero, returns the process group ID of this process.

If pid is specified, returns the process group ID of that process.

SEE ALSO
getpid and getppid

FUNCTION
getpid - get the process ID

SYNTAX
int getpid();

DESCRIPTION
Returns the process ID of this process.

SEE ALSO
getppid and getpgrp

FUNCTION
getppid - get the parent process ID

SYNTAX
int getppid();

DESCRIPTION
Returns the process ID of the parent process.

SEE ALSO
getpid and getpgrp

FUNCTION
getuid - get the user ID

SYNTAX
int getuid();

DESCRIPTION
Get the real user ID.

SEE ALSO
setuid, setgid, getgid, seteuid, geteuid, setegid and getegid

FUNCTION
hardlink - create a hardlink

SYNTAX
void hardlink(string from, string to);

DESCRIPTION
Creates a hardlink named to from the file from.

SEE ALSO
symlink, mv and rm

FUNCTION
initgroups - initialize the group access list

SYNTAX
void initgroups(string username, int base_gid);

DESCRIPTION
Initializes the group access list according to the system group database. base_gid is also added to the group access list.

SEE ALSO
setuid, getuid, setgid, getgid, seteuid, geteuid, setegid, getegid, getgroups and setgroups

FUNCTION
openlog - initializes the connection to syslogd

SYNTAX
void openlog(string ident, int options, facility);

DESCRIPTION
Initializes the connection to syslogd.

The ident argument specifies an identifier to tag all log entries with.

options is a bit field specifying the behavior of the message logging. Valid options are:

LOG_PID Log the process ID with each message.
LOG_CONS Write messages to the console if they can't be sent to syslogd.
LOG_NDELAY Open the connection to syslogd now and not later.
LOG_NOWAIT Do not wait for subprocesses talking to syslogd.

facility specifies what subsystem you want to log as. Valid facilities are:

LOG_AUTH Authorization subsystem
LOG_AUTHPRIV
LOG_CRON Crontab subsystem
LOG_DAEMON System daemons
LOG_KERN Kernel subsystem (NOT USABLE)
LOG_LOCAL For local use
LOG_LOCAL[1-7] For local use
LOG_LPR Line printer spooling system
LOG_MAIL Mail subsystem
LOG_NEWS Network news subsystem
LOG_SYSLOG
LOG_USER
LOG_UUCP UUCP subsystem

NOTE
Only available on systems with syslog(3).

BUGS
LOG_NOWAIT should probably always be specified.

SEE ALSO
syslog, closelog and setlogmask

FUNCTION
readlink - read a symbolic link

SYNTAX
string readlink(string linkname);

DESCRIPTION
Returns what the symbolic link linkname points to.

SEE ALSO
symlink

FUNCTION
setegid - set the effective group ID

SYNTAX
void setegid(int uid);

DESCRIPTION
Sets the effective group ID to gid.

SEE ALSO
setuid, getuid, setgid, getgid, seteuid, geteuid and getegid

FUNCTION
seteuid - set the effective user ID

SYNTAX
void seteuid(int uid);

DESCRIPTION
Sets the effective user ID to uid.

SEE ALSO
setuid, getuid, setgid, getgid, geteuid, setegid and getegid

FUNCTION
setgid - set the group ID

SYNTAX
void setgid(int gid);

DESCRIPTION
Sets the real group ID, effective group ID and saved group ID to gid.

SEE ALSO
setuid, getuid, getgid, seteuid, geteuid, setegid and getegid

FUNCTION
setgroups - set the supplemental group access list

SYNTAX
void getgroups(array(int) gids);

DESCRIPTION
Set the supplemental group access list for this process.

SEE ALSO
initgroups, getgroups, getgid, setgid, getegid and setegid

FUNCTION
setuid - set the user ID

SYNTAX
void setuid(int uid);

DESCRIPTION
Sets the real user ID, effective user ID and saved user ID to uid.

SEE ALSO
getuid, setgid, getgid, seteuid, geteuid, setegid and getegid

FUNCTION
symlink - create a symbolic link

SYNTAX
void symlink(string from, string to);

DESCRIPTION
Creates a symbolic link for an original file from with the new name to.

SEE ALSO
hardlink, readlink, mv and rm

FUNCTION
uname - get operating system information

SYNTAX
mapping(string:string) uname();

DESCRIPTION
Returns a mapping describing the operating system.

The mapping contains the following fields:

"sysname": Operating system name
"nodename": "release": "version": "machine": Host name Release of this OS Version number of this OS Machine architecture

NOTE
This function only exists on systems that have the uname(2) system call.

14.2 Process

The Process module contains functions to start and control other programs from Pike.

CLASS
Process.create_process - Create a new process

SYNTAX
Process.create_process Process.create_process(array(string) command, void | mapping(string:mixed) modifiers);

DESCRIPTION
This is the recommended and most portable way to start processes in Pike. The command name and arguments are sent as an array of strings so that you do not have to worry about qouting them. The optional mapping modifiers can can contain zero or more of the following parameters:
"cwd" : string dir
This parameter executes the command in another directory than the current directory of this process. Please note that if the command is given is a relative path, it will be relative to this directory rather than the current directory of this process.
"stdin" : Stdio.File stdin
"stdout" : Stdio.File stdout
"stderr" : Stdio.File stderr
These parameters allows you to change the standard input, output and error streams of the newly created process. This is particularly useful in combination with Stdio.File->pipe.
"env" : mapping(string:string) env
This mapping will become the environment variables for the created process. Normally you will want to only add or change variables which can be achived by getting the environment mapping for this process with getenv. Example:
(["env" : getenv() + (["TERM":"vt100"])
.
The following options are only available on some systems.
"uid" : int|string uid
This parameter changes which user the new process will execute as. Note that the current process must be running as root to use this option. The uid can be given either as an integer as a string containing the login name of that user. Please note that using a string here can be noticably slower than using an integer. The "gid" and "groups" for the new process will be set to the right values for that user unless overriden by opions blow. If maximum performance is an issue, you should use the "gid" and "group" options to set those values explicitly. (See setuid and getpwuid for more info)
"gid" : int|string gid
This parameter changes the primary group for the new process. When the new process creates files, they will will be created with this group. The group can either be given as an int or a string containing the name of the group. As with the "uid" parameters, integers are faster than numbers. (See setgid and getgrgid for more info)
"setgroups" : array(int|string) groups
This parameter allows you to the set the list of groups that the new process belongs to. It is recommended that if you use this parameter you supply at least one at no more than 16 groups. (Some system only supports 8 groups even...) The groups can be given as gids or as strings with the group names. If maximum performance is an issue, please use integers.
"noinitgroups" : int(0..1) yesno
This parameter overrides a behaviour of the "uid" parameter. If this parameter is used, the gid and groups of the new process will be inherited from the current process rather than changed to the approperiate values for that uid.
"priority" : string pri
This sets the priority of the new process, see set_priority for more info.
"nice" : int nice
This sets the nice level of the new process. Note that a negative number means higher priority positive numbers means higher priority. Only root may use negative numbers.
"keep_signals" : int(0..1) yesno
This prevents Pike to restore all signal handlers to their default value for the new process. Useful to ignore certain signals in the new process.
"fds" : array(Stdio.File|zero) fds
This parameter allows you to map files to filedescriptors 3 and up. The file fds[0] will be remapped to fd #3 in the new process, etc.
These parameter limits the new process in certain ways, they are not available on all systems. Each of these can either be given as a mapping (["soft":soft_limit,"hard":hard_limit]) or as an integer. If an integer is given both the hard limit and the soft limit will be changed. The new process may change the soft limit, but may not change it any higher than the hard limit.
"cpu" : int|mapping(string:int) seconds
Limit the CPU time of the new process.
"core" : int|mapping(string:int) bytes
Limit the core file size.
"data" : int|mapping(string:int) bytes
Limit the data size of the new process.
"fsize" : int|mapping(string:int) bytes
Limits the maximum file size of the new process.
"nofile" : int|mapping(string:int) num_files
Maximum open files for the new process.
"stack" : int|mapping(string:int) bytes
Limit the stack size of the nwe process.
"map_mem" : int|mapping(string:int) bytes
"vmem" : int|mapping(string:int) vmem
Maximum amount of mmapped memory.
"as" : int|mapping(string:int) memory
"mem" : int|mapping(string:int) memory
Maximum amount of total memory.

SEE ALSO
Process.popen and Process.system

METHOD
Process.create_process.set_priority - Set the priority of this process

SYNTAX
int set_priority(string pri);

DESCRIPTION
This function sets the priority of this process, the string pri should be one of:
"realtime" or "highest" This gives the process realtime priority, this basically gives the process access to the cpu whenever it wants.
"higher" This gives the process higher priority than most other processes on your system.
"high" This gives your proces a little bit higher priority than what is 'normal'.
"normal" This sets the process' priority to whatever is 'normal' for new processes on your system.
"low" This will give the process a lower priority than what is normal on your system.
"lowest" This will give the process a lower priority than most processes on your system.

METHOD
Process.create_process.wait - Wait for this process to finish

SYNTAX
int wait();

DESCRIPTION
This function makes the calling thread wait for the process to finish. It returns the exit code of that process.

METHOD
Process.create_process.status - Check if process is still running

SYNTAX
int status();

DESCRIPTION
This function returns zero if the process is still running. If the process has exited, it will return one.

METHOD
Process.create_process.pid - Get the process id of this process

SYNTAX
int pid();

DESCRIPTION
This function returns the process identifier for the process.

METHOD
Process.create_process.kill - Kill this process

SYNTAX
int kill(int signal);

DESCRIPTION
This function sends the given signal to the process, it returns one if the operation succeded, zero otherwise.

SEE ALSO
signum

FUNCTION
Process.popen - pipe open

SYNTAX
string popen(string cmd);

DESCRIPTION
This function runs the command cmd as in a shell and returns the output. See your Unix/C manual for details on popen.

FUNCTION
Process.system - run an external program

SYNTAX
void system(string cmd);

DESCRIPTION
This function runs the external program cmd and waits until it is finished. Standard /bin/sh completions/redirections/etc. can be used.

SEE ALSO
Process.create_process, Process.popen, Process.exec and Process.spawn

FUNCTION
Process.spawn - spawn a process

SYNTAX
int spawn(string cmd);
int spawn(string cmd, object stdin);
int spawn(string cmd, object stdin, object stdout);
int spawn(string cmd, object stdin, object stdout, object stderr);

DESCRIPTION
This function spawns a process but does not wait for it to finish. Optionally, clones of Stdio.File can be sent to it to specify where stdin, stdout and stderr of the spawned processes should go.

SEE ALSO
Process.popen, fork, Process.exec, Stdio.File->pipe and Stdio.File->dup2

FUNCTION
Process.exece - execute a program

SYNTAX
int exece(string file, array(string) args);
int exece(string file, array(string) args, mapping(string:string) env);

DESCRIPTION
This function transforms the Pike process into a process running the program specified in the argument file with the argument args. If the mapping env is present, it will completely replace all environment variables before the new program is executed. This function only returns if something went wrong during exece(), and in that case it returns zero.

NOTE
The Pike driver _dies_ when this function is called. You must use fork() if you wish to execute a program and still run the Pike driver.

EXAMPLE
exece("/bin/ls", ({"-l"}));
exece("/bin/sh", ({"-c", "echo $HOME"}), (["HOME":"/not/home"]));

SEE ALSO
fork and Stdio.File->pipe

FUNCTION
Process.exec - simple way to use exece()

SYNTAX
int exec(string file, string ... args);

DESCRIPTION
This function destroys the Pike parser and runs the program file instead with the arguments. If no there are no '/' in the filename, the variable PATH will be consulted when looking for the program. This function does not return except when the exec fails for some reason.

EXAMPLE
exec("/bin/echo","hello","world");

CLASS
Process.Spawn - spawn off another program with control structure

SYNTAX
object Process.Spawn(string program, void|array(string) args, void|mapping(string:string) env, void|string cwd);
or object Process.Spawn(string program, void|array(string) args, void|mapping(string:string) env, void|string cwd, array(void|object(Stdio.file)) fds, void|array(void|object(Stdio.file)) fds_to_close);

DESCRIPTION
Spawn off another program (program) and creates the control structure. This does not spawn off a shell to find the program, therefore must program be the full path the the program.

args is per default no argument(s),

env is reset to the given mapping, or kept if the argument is 0. fds is your stdin, stdout and stderr. Default is local pipes (see stdin et al). fds_to_close is file descriptors that are closed in the forked branch when the program is executed (ie, the other end of the pipes).

VARIABLE
Process.Spawn.stdin,
Process.Spawn.stdout,
Process.Spawn.stderr,
Process.Spawn.fd - pipes to the program

SYNTAX
object(Stdio.File) stdin;
object(Stdio.File) stdout;
object(Stdio.File) stderr;
array(void|object(Stdio.File)) fd;

DESCRIPTION
Pipes to the spawned program (if set). fd[0]==stdin, etc.

VARIABLE
Process.Spawn.pid - spawned program pid

SYNTAX
int pid;

DESCRIPTION
pid of the spawned program.

METHOD
Process.Spawn.wait - wait for the spawned program to finish

SYNTAX
void wait();

DESCRIPTION
Returns when the program has exited.

METHOD
Process.Spawn.kill - send a signal to the program

SYNTAX
int kill(int signal);

DESCRIPTION
Sends a signal to the program.

14.3 Regexp

Regexp is short for Regular Expression. A regular expression is a standardized way to make pattern that match certain strings. In Pike you can often use the sscanf, range and index operators to match strings, but sometimes a regexp is both faster and easier.

A regular expression is actually a string, then compiled into an object. The string contains characters that make up a pattern for other strings to match. Normal characters, such as A through Z only match themselves, but some characters have special meaning.
pattern  Matches
.   any one character
[abc]   a, b or c
[a-z]   any character a to z inclusive
[^ac]   any character except a and c
(x)   x (x might be any regexp) If used with split, this also puts the string matching x into the result array.
x*   zero or more occurrences of 'x' (x may be any regexp)
x+   one or more occurrences of 'x' (x may be any regexp)
x|y   x or y. (x or y may be any regexp)
xy   xy (x and y may be any regexp)
^   beginning of string (but no characters)
$   end of string (but no characters)
\<   the beginning of a word (but no characters)
\>   the end of a word (but no characters)
Let's look at a few examples:
Regexp Matches
[0-9]+ one or more digits
[^ \t\n] exactly one non-whitespace character
(foo)|(bar) either 'foo' or 'bar'
\.html$ any string ending in '.html'
^\. any string starting with a period

Note that \ can be used to quote these characters in which case they match themselves, nothing else. Also note that when quoting these something in Pike you need two \ because Pike also uses this character for quoting.

To make make regexps fast, they are compiled in a similar way that Pike is, they can then be used over and over again without needing to be recompiled. To give the user full control over the compilations and use of regexp an object oriented interface is provided.

You might wonder what regexps are good for, hopefully it should be more clear when you read about the following functions:

METHOD
Regexp.create - compile regexp

SYNTAX
void create();
void create(string regexp);
object(Regexp) Regexp();
object(Regexp) Regexp(string regexp);

DESCRIPTION
When create is called, the current regexp bound to this object is cleared. If a string is sent to create(), this string will be compiled to an internal representation of the regexp and bound to this object for later calls to match or split. Calling create() without an argument can be used to free up a little memory after the regexp has been used.

SEE ALSO
clone and Regexp->match

METHOD
Regexp.match - match a regexp

SYNTAX
int match(string s)

DESCRIPTION
Return 1 if s matches the regexp bound to the object regexp, zero otherwise.

SEE ALSO
Regexp->create and Regexp->split

METHOD
Regexp.split - split a string according to a pattern

SYNTAX
array(string) split(string s)

DESCRIPTION
Works as regexp->match, but returns an array of the strings that matched the sub-regexps. Sub-regexps are those contained in ( ) in the regexp. Sub-regexps that were not matched will contain zero. If the total regexp didn't match, zero is returned.

BUGS
You can only have 40 sub-regexps.

SEE ALSO
Regexp->create and Regexp->match

14.4 Gmp

Gmp is short for GNU Multi-Precision library. It is a set of routines that can manipulate very large numbers. Although much slower than regular integers they are very useful when you need to handle extremely large numbers. Billions and billions as Mr Attenborough would have said..

The Gmp library can handle large integers, floats and rational numbers, but currently Pike only has support for large integers. The others will be added later or when demand arises. Large integers are implemented as objects cloned from Gmp.Mpz.

CLASS
Gmp.mpz - bignum program

DESCRIPTION
Gmp.mpz is a builtin program written in C. It implements large, very large integers. In fact, the only limitation on these integers is the available memory.

The mpz object implements all the normal integer operations. (except xor) There are also some extra operators:

NOTE
This module is only available if libgmp.a was available and found when Pike was compiled.

METHOD
Gmp.mpz.create - initialize a bignum

SYNTAX
object Mpz();
object Mpz(int|object|float i);
object Mpz(string digits, int base);

DESCRIPTION
When cloning an mpz it is by default initialized to zero. However, you can give a second argument to clone to initialize the new object to that value. The argument can be an int, float another mpz object, or a string containing an ascii number. You can also give the number in the string in another base by specifying the base as a second argument. Valid bases are 2-36 and 256.

SEE ALSO
clone

METHOD
Gmp.mpz.powm - raise and modulo

SYNTAX
object powm(int|string|float|object a,int|string|float|object b);

DESCRIPTION
This function returns ( mpz ** a ) % b. For example, Mpz(2)->powm(10,42); would return 16 since 2 to the power of 10 is 1024 and 1024 modulo 42 is 16.

METHOD
Gmp.mpz.sqrt - square root

SYNTAX
object sqrt();

DESCRIPTION
This function returns the truncated integer part of the square root of the value of mpz.

METHOD
Gmp.mpz.probably_prime_p - is this number a prime?

SYNTAX
int probably_prime_p();

DESCRIPTION
This function returns 1 if mpz is a prime, and 0 most of the time if it is not.

METHOD
Gmp.mpz.gcd - greatest common divisor

SYNTAX
object gcd(object|int|float|string arg)

DESCRIPTION
This function returns the greatest common divisor for arg and mpz.

METHOD
Gmp.mpz.cast - cast to other type

SYNTAX
object cast( "string" | "int" | "float" );
(string) mpz
(int) mpz
(float) mpz

DESCRIPTION
This function converts an mpz to a string, int or float. This is necessary when you want to view, store or use the result of an mpz calculation.

SEE ALSO
cast

METHOD
Gmp.mpz.digits - convert mpz to a string

SYNTAX
string digits();
string digits(int|void base);

DESCRIPTION
This function converts an mpz to a string. If a base is given the number will be represented in that base. Valid bases are 2-36 and 256. The default base is 10.

SEE ALSO
Gmp.mpz->cast

METHOD
Gmp.mpz.size - how long is a number

SYNTAX
string size();
string size(int|void base);

DESCRIPTION
This function returns how long the mpz would be represented in the specified base. The default base is 2.

SEE ALSO
Gmp.mpz->digits

14.5 Gdbm

Gdbm is short for GNU Data Base Manager. It provides a simple data base similar to a file system. The functionality is similar to a mapping, but the data is located on disk, not in memory. Each gdbm database is one file which contains a key-pair values, both keys and values have to be strings. All keys are always unique, just as with a mapping.

This is the an interface to the gdbm library. This module might or might not be available in your Pike depending on whether the gdbm library was available on your system when Pike was compiled.

METHOD
Gdbm.gdbm.create - open database

SYNTAX
int create();
int create(string file);
int create(string file, string mode);
object(Gdbm) Gdbm(); object(Gdbm) Gdbm(string file); object(Gdbm) Gdbm(string file, string mode);

DESCRIPTION
Without arguments, this function does nothing. With one argument it opens the given file as a gdbm database, if this fails for some reason, an error will be generated. If a second argument is present, it specifies how to open the database using one or more of the follow flags in a string:

r open database for reading
w open database for writing
c create database if it does not exist
t overwrite existing database
f fast mode

The fast mode prevents the database from synchronizing each change in the database immediately. This is dangerous because the database can be left in an unusable state if Pike is terminated abnormally.

The default mode is "rwc".

METHOD
Gdbm.gdbm.close - close database

SYNTAX
void close();

DESCRIPTION
This closes the database.

METHOD
Gdbm.gdbm.store - store a value in the database

SYNTAX
int store(string key, string data);

DESCRIPTION
Associate the contents of data with the key key. If the key key already exists in the database the data for that key will be replaced. If it does not exist it will be added. An error will be generated if the database was not open for writing.

METHOD
Gdbm.gdbm.fetch - fetch a value from the database

SYNTAX
string fetch(string key);

DESCRIPTION
Returns the data associated with the key key in the database. If there was no such key in the database, zero is returned.

METHOD
Gdbm.gdbm.delete - delete a value from the database

SYNTAX
int delete(string key);

DESCRIPTION
Remove a key from the database. Note that no error will be generated if the key does not exist.

METHOD
Gdbm.gdbm.firstkey - get first key in database

SYNTAX
string firstkey();

DESCRIPTION
Returns the first key in the database, this can be any key in the database.

METHOD
Gdbm.gdbm.nextkey - get next key in database

SYNTAX
string nextkey(string key);

DESCRIPTION
This returns the key in database that follows the key key. This is of course used to iterate over all keys in the database.

EXAMPLE
/* Write the contents of the database */
for(key=gdbm->firstkey(); k; k=gdbm->nextkey(k))
write(k+":"+gdbm->fetch(k)+"\n");

METHOD
Gdbm.gdbm.reorganize - reorganize database

SYNTAX
int reorganize();

DESCRIPTION
Deletions and insertions into the database can cause fragmentation which will make the database bigger. This routine reorganizes the contents to get rid of fragmentation. Note however that this function can take a LOT of time to run.

METHOD
Gdbm.gdbm.sync - synchronize database

SYNTAX
void sync();

DESCRIPTION
When opening the database with the 'f' flag writings to the database can be cached in memory for a long time. Calling sync will write all such caches to disk and not return until everything is stored on the disk.

14.6 Getopt

Getopt is a group of function which can be used to find command line options. Command line options come in two flavors: long and short. The short ones consists of a dash followed by a character (-t), the long ones consist of two dashes followed by a string of text (--test). The short options can also be combined, which means that you can write -tda instead of -t -d -a. Options can also require arguments, in which case they cannot be combined. To write an option with an argument you write -t argument or -targument or --test=argument.

FUNCTION
Getopt.find_option - find command line options

SYNTAX

mixed find_option(array(string) argv,

string shortform,
void|string longform,
void|string envvar,
void|mixed def,
void|int throw_errors);

DESCRIPTION
This is a generic function to parse command line options of the type '-f', '--foo' or '--foo=bar'. The first argument should be the array of strings that is sent as second argument to your main() function, the second is a string with the short form of your option. The short form must be only one character long. The 'longform' is an alternative and maybe more readable way to give the same option. If you give "foo" as longform your program will accept '--foo' as argument. The envvar argument specifies what environment variable can be used to specify the same option. The envvar option exists to make it easier to customize program usage. The 'def' has two functions: It specifies that the option takes an argument and it tells find_option what to return if the option is not present. If 'def' is given and the option does not have an argument find_option will print an error message and exit the program.

Also, as an extra bonus: shortform, longform and envvar can all be arrays, in which case either of the options in the array will be accpted.

NOTE
find_option modifies argv.
This function reads options even if they are written after the first non-option on the line.

EXAMPLE
/* This program tests two different options. One is called -f or * --foo and the other is called -b or --bar and can also be given * by using the BAR_OPTION environment variable. */

int main(int argc, array(string) argv)
{
    if(find_option(argv,"f","foo"))
        werror("The FOO option was given.\n");

    werror("The BAR option got the "+
        find_option(argv,"b","bar","BAR_OPTION","default")+
        " argument.\n");
}

SEE ALSO
Getopt.get_args

FUNCTION
Getopt.find_all_options - find command line options

SYNTAX
array find_all_options(array(string) argv, array option, int|void posix_me_harder, int|void throw_errors);

DESCRIPTION
This function does the job of several calls to find_option. The main advantage of this is that it allows it to handle the POSIX_ME_HARDER environment variable better. When the either the argument posix_me_harder or the environment variable POSIX_ME_HARDER is true, no arguments will be parsed after the first non-option on the command line.

Each element in the array options should be an array on the following form:

({
string name,
int type,
string|array(string) aliases,
void|string|array(string) env_var,
void|mixed default
})
Only the first three elements has to be included.
name
Name is a tag used to identify the option in the output.
type
Type is one of Getopt.HAS_ARG, Getopt.NO_ARG and Getopt.MAY_HAVE_ARG and it affects how the error handling and parsing works. You should use HAS_ARG for options that require a path, a number or similar. NO_ARG should be used for options that do not need an argument, such as --version. MAY_HAVE_ARG should be used for options that may or may not need an argument.
aliases
This is a string or an array of string of options that will be looked for. Short and long options can be mixed, and short options can be combined into one string. Note that you must include the dashes in aliases so find_all_options can distinguish between long and short options. Example: ({"-tT","--test"}) This would make find_all_options look for -t, -T and --test.
env_var
This is a string or an array of strings containing names of environment variables that can be used instead of the command line option.
default
This is the default value the option will have in the output from this function. Options without defaults will be omitted from the output if they are not found in argv.
The good news is that the output from this function is a lot simpler. Find_all_options returns an array where each element is an array on this form:
({
string name,
mixed value
})
The name is the identifier from the input and value is the value given to it from the argument, environment variable or default. If no default is given, value will be 1.

NOTE
find_all_options modifies argv.

EXAMPLE
First let's take a look at input and output:
> Getopt.find_all_options(({"test","-dd"}),
>>  ({ ({ "debug", Getopt.NO_ARG, ({"-d","--debug"}), "DEBUG", 1}) }));
Result: ({
  ({ "debug",  1 }),
  ({ "debug",  1 })
})

This is what it would look like in real code:

import Getopt;

int debug=0;

int main(int argc, array(string) argv
{
    foreach(find_all_options(argv, ({
        ({ "debug", MAY_HAVE_ARG, ({"-d","--debug"}), "DEBUG", 1}),
        ({ "version", NO_ARG, ({"-v","--version" }) }) })),
        mixed option)
    {
        switch(option[0])
        {
            case "debug": debug+=option[1]; break;
            case "version":
                write("Test program version 1.0\n");
                exit(1);
        }
    }

    argv=Getopt.get_args(argv);
}

SEE ALSO
Getopt.get_args

FUNCTION
Getopt.get_args - get the non-option arguments

SYNTAX
array(string) get_args(array(string) argv,void|int throw_errors);

DESCRIPTION
This function returns the remaining command line arguments after you have run find_options to find all the options in the argument list. If there are any options left not handled by find_options an error message will be written and the program will exit. Otherwise a new 'argv' array without the parsed options is returned.

EXAMPLE
int main(int argc, array(string) argv)
{
    if(find_option(argv,"f","foo"))
        werror("The FOO option was given.\n");

    argv=get_args(argv);
    werror("The arguments are: "+(argv*" ")+".\n");
}

SEE ALSO
Getopt.find_option

14.7 Gz

The Gz module contains functions to compress and uncompress strings using the same algorithm as the program gzip. Packing can be done in streaming mode or all at once. Note that this module is only available if the gzip library was available when Pike was compiled. The Gz module consists of two classes; Gz.deflate and Gz.inflate. Gz.deflate is used to pack data and Gz.inflate is used to unpack data. (Think "inflatable boat") Note that these functions use the same algorithm as gzip, they do not use the exact same format however, so you cannot directly unzip gzipped files with these routines. Support for this will be added in the future.

CLASS
Gz.deflate - string packer

DESCRIPTION
Gz.inflate is a builtin program written in C. It interfaces the packing routines in the libz library.

NOTE
This program is only available if libz was available and found when Pike was compiled.

SEE ALSO
Gz.inflate

METHOD
Gz.deflate.create - initialize packer

SYNTAX
void create(int X)
object(Gz.deflate) Gz.deflate(int X)

DESCRIPTION
This function is called when a new Gz.deflate is created. If given, X should be a number from 0 to 9 indicating the packing / CPU ratio. Zero means no packing, 2-3 is considered 'fast', 6 is default and higher is considered 'slow' but gives better packing.

This function can also be used to re-initialize a Gz.deflate object so it can be re-used.

METHOD
Gz.deflate.deflate - pack data

SYNTAX
string deflate(string data, int flush);

DESCRIPTION
This function performs gzip style compression on a string and returns the packed data. Streaming can be done by calling this function several times and concatenating the returned data. The optional 'flush' argument should be one f the following:

Gz.NO_FLUSH Only data that doesn't fit in the internal buffers is returned.
Gz.PARTIAL_FLUSH All input is packed and returned.
Gz.SYNC_FLUSH All input is packed and returned.
Gz.FINISH All input is packed and an 'end of data' marker is appended.

Using flushing will degrade packing. Normally NO_FLUSH should be used until the end of the data when FINISH should be used. For interactive data PARTIAL_FLUSH should be used.

SEE ALSO
Gz.inflate->inflate

CLASS
Gz.inflate - string unpacker

DESCRIPTION
Gz.inflate is a builtin program written in C. It interfaces the packing routines in the libz library.

NOTE
This program is only available if libz was available and found when Pike was compiled.

SEE ALSO
Gz.deflate

METHOD
Gz.inflate.create - initialize unpacker

SYNTAX
void create()
object(Gz.inflate) Gz.inflate()

DESCRIPTION
This function is called when a new Gz.inflate is created. It can also be called after the object has been used to re-initialize it.

METHOD
Gz.inflate.inflate - unpack data

SYNTAX
string inflate(string data);

DESCRIPTION
This function performs gzip style decompression. It can inflate a whole file at once or in blocks.

EXAMPLE
import Stdio;
// whole file
write(Gz.inflate()->inflate(stdin->read());

// streaming (blocks)
function inflate=Gz.inflate()->inflate;
while(string s=stdin->read(8192))

write(inflate(s));

SEE ALSO
Gz.deflate->deflate

METHOD
Gz.crc32 - calculate checksum

SYNTAX
string crc32(string data,void|int start_value);

DESCRIPTION
This method is usable for calculating checksums, and presents the standard ISO3309 Cyclic Redundancy Check.

SEE ALSO
Gz

14.8 Yp

This module is an interface to the Yellow Pages functions. Yp is also known as NIS (Network Information System) and is most commonly used to distribute passwords and similar information within a network.

FUNCTION
Yp.default_yp_domain - get the default Yp domain

SYNTAX
string default_yp_domain();

DESCRIPTION
Returns the default yp-domain.

CLASS
Yp.YpDomain - class representing an Yp domain

SYNTAX
object(Yp.YpDomain) Yp.YpDomain(string|void domain);

DESCRIPTION
This creates a new YpDomain object.

If there is no YP server available for the domain, this function call will block until there is one. If no server appears in about ten minutes or so, an error will be returned. The timeout is not configurable from the C interface to Yp either.

If no domain is given, the default domain will be used. (As returned by Yp.default_yp_domain)

METHOD
Yp.YpDomain.bind - bind this object to another domain

SYNTAX
void bind(string|void domain);

DESCRIPTION
Re-bind the object to another (or the same) domain. If no domain is given, the default domain will be used.

METHOD
Yp.YpDomain.match - match a key in a map

SYNTAX
string match(string map, string key);

DESCRIPTION
If 'map' does not exist, an error will be generated. Otherwise the string matching the key will be returned. If there is no such key in the map, 0 will be returned.

arguments is the map Yp-map to search in. This must be a full map name, for example, you should use passwd.byname instead of just passwd. key is the key to search for. The key must match exactly, no pattern matching of any kind is done.

EXAMPLE
object dom = Yp.YpDomain();
write(dom->match("passwd.byname", "root"));

METHOD
Yp.YpDomain.all - return the whole map

SYNTAX
mapping(string:string) all(string map);

DESCRIPTION
Returns the whole map as a mapping. map is the YP-map to search in. This must be the full map name, you have to use passwd.byname instead of just passwd.

METHOD
Yp.YpDomain.map - call a function for each entry in an Yp map

SYNTAX
void map(string map, function(string,string:void) over);

DESCRIPTION
For each entry in 'map', call the function(s) specified by 'over'. Over will get two arguments, the first being the key, and the second the value. map is the YP-map to search in. This must be the full map name, as an example, passwd.byname instead of just passwd.

METHOD
Yp.YpDomain.server - find an Yp server

SYNTAX
string server(string map);

DESCRIPTION
Returns the hostname of the server serving the map map. map is the YP-map to search in. This must be the full map name, as an example, passwd.byname instead of just passwd.

METHOD
Yp.YpDomain.order - get the 'order' for specified map

SYNTAX
int order(string map);

DESCRIPTION
Returns the 'order' number for the map map. This is usually a time_t (see the global function time()). When the map is changed, this number will change as well. map is the YP-map to search in. This must be the full map name, as an example, passwd.byname instead of just passwd.

CLASS
Yp.YpMap - class representing one Yp map

SYNTAX
object(Yp.YpMap) Yp.Ypmap(string map, string|void domain);

DESCRIPTION
This creates a new YpMap object.

If there is no YP server available for the domain, this function call will block until there is one. If no server appears in about ten minutes or so, an error will be returned. The timeout is not configurable from the C-yp interface either. map is the YP-map to bind to. This must be the full map name, as an example, passwd.byname instead of just passwd. If no domain is specified, the default domain will be used. This is usually best.

METHOD
Yp.YpMap.match - find key in map

SYNTAX
string match(string key)
; string Yp.YpMap[string key];

DESCRIPTION
Search for the key key. If there is no key in the map, 0 will be returned, otherwise the string matching the key will be returned. key must match exactly, no pattern matching of any kind is done.

METHOD
Yp.YpMap.all - return the whole map as a mapping

SYNTAX
mapping(string:string) all();
(mapping) Yp.YpMap;

DESCRIPTION
Returns the whole map as a mapping.

METHOD
Yp.YpMap.map - call a function for each entry in the map

SYNTAX
void map(function(string,string:void) over);

DESCRIPTION
For each entry in the map, call the function(s) specified by 'over'. The function will be called like 'void over(string key, string value)'.

METHOD
Yp.YpMap.server - find what server servers this map

SYNTAX
string server();

DESCRIPTION
Returns the hostname of the server serving this map.

METHOD
Yp.YpMap.order - find the 'order' of this map

SYNTAX
int order();

DESCRIPTION
Returns the 'order' number for this map. This is usually a time_t (see the global function time())

METHOD
Yp.YpMap._sizeof - return the number of entries in the map

SYNTAX
int sizeof(Yp.YpMap);

DESCRIPTION
Returns the number of entries in the map. This is equivalent to sizeof((mapping)map);

METHOD
Yp.YpMap._indices - return the indices from the map

SYNTAX
array(string) indices(Yp.YpMap)

DESCRIPTION
Returns the indices of the map. If indices is called first, values must be called immediately after. If values is called first, it is the other way around.

SEE ALSO
Yp.YpMap->_values

METHOD
Yp.YpMap._values - return the values from the map

SYNTAX
array(string) values(Yp.Ypmap)

DESCRIPTION
Returns the values of the map. If values is called first, indices must be called immediately after. If indices is called first, it is the other way around.

SEE ALSO
Yp.YpMap->_indices
Here is an example program using the Yp module, it lists users and their GECOS field from the Yp map "passwd.byname" if your system uses Yp.
import Yp;

void print_entry(string key, string val)
{
    val = (val/":")[4];
    if(strlen(val))
    {
        string q = ".......... ";
        werror(key+q[strlen(key)..]+val+"\n");
    }
}
    
void main(int argc, array(string) argv)
{
    object (YpMap) o = YpMap("passwd.byname");

    werror("server.... "+ o->server() + "\n"
     "age....... "+ (-o->order()+time()) + "\n"
     "per....... "+ o["per"] + "\n"
     "size...... "+ sizeof(o) + "\n");
    
    o->map(print_entry); // Print username/GECOS pairs
}

14.9 ADT.Table

ADT.Table is a generic module for manipulating tables. Each table contains one or several columns. Each column is associated with a name, the column name. Optionally, one can provide a column type. The Table module can do a number of operations on a given table, like computing the sum of a column, grouping, sorting etc.

All column references are case insensitive. A column can be referred to by its position (starting from zero). All operations are non-destructive. That means that a new table object will be returned after, for example, a sort.

An example is available at the end of this section.

METHOD
ADT.Table.table.create - create a table object

SYNTAX
void create(array(array) table, array(string) column_names, array(mapping)|void column_types);

DESCRIPTION
The table class takes two or three arguments:

  1. table is a two-dimensional array consisting of one array of columns per row. All rows must have the same number of columns as specified in column_names.

  2. column_names is an array of column names associated with each column in the table. References by column name are case insensitive. The case used in column_names will be used when the table is displayed. A column can also be referred to by its position, starting from zero.

  3. column_types is an optional array of mappings. The column type information is only used when displaying the table. Currently, only the keyword "type" is recognized. The type can be specified as "text" or "num" (numerical). Text columns are left adjusted, whereas numerical columns are right adjusted. If a mapping in the array is 0 (zero), it will be assumed to be a text column. If column_types is omitted, all columns will displayed as text. See ADT.Table.ASCII.encode on how to display a table.

EXAMPLE
object t = ADT.Table.table( ({ ({ "Blixt", "Gordon" }),
({ "Buck", "Rogers" }) }),
({ "First name", "Last name" }) );

SEE ALSO
ADT.Table.ASCII.encode

METHOD
ADT.Table.table._indices - gives the column names

SYNTAX
array(string) _indices();

DESCRIPTION
This method returns the column names for the table. The case used when the table was created will be returned.

METHOD
ADT.Table.table._values - gives the table contents

SYNTAX
array(array) _values();

DESCRIPTION
This method returns the contents of a table as a two dimensional array. The format is an array of rows. Each row is an array of columns.

METHOD
ADT.Table.table._sizeof - gives the number of table rows

SYNTAX
int _sizeof();

DESCRIPTION
This method returns the number of rows in the table.

METHOD
ADT.Table.table.reverse - reverses the table rows

SYNTAX
object reverse();

DESCRIPTION
This method reverses the rows of the table and returns a new table object.

METHOD
ADT.Table.table.rename - rename a column

SYNTAX
object rename(string|int from, string to);

DESCRIPTION
This method renames the column named from to to and returns a new table object. Note that from can be the column position.

METHOD
ADT.Table.table.type - fetch or set the type for a column

SYNTAX
mapping type(string|int column, mapping|void type);

DESCRIPTION
This method gives the type for the given column. If a second argument is given, the old type will be replaced with type. The column type is only used when the table is displayed. The format is as specified in create.

METHOD
ADT.Table.table.limit - truncate the table

SYNTAX
object limit(int n);

DESCRIPTION
This method truncates the table to the first n rows and returns a new object.

METHOD
ADT.Table.table.sort - sort the table on one or several columns

SYNTAX
object sort(string|int column1, string|int column2, ...);

DESCRIPTION
This method sorts the table in ascendent order on one or several columns and returns a new table object. The left most column is sorted last. Note that the sort is stable.

METHOD
ADT.Table.table.rsort - sort the table in reversed order on one or several columns

SYNTAX
object rsort(string|int column1, string|int column2, ...);

DESCRIPTION
Like sort, but the order is descendent.

METHOD
ADT.Table.table.distinct - keep unique rows only

SYNTAX
object distinct(string|int column1, string|int column2, ...);

DESCRIPTION
This method groups by the given columns and returns a table with only unique rows. When no columns are given, all rows will be unique. A new table object will be returned.

METHOD
ADT.Table.Table.table.sum - computes the sum of equal rows

SYNTAX
object sum(string|int column1, string|int column2, ...);

DESCRIPTION
This method sums all equal rows. The table will be grouped by the columns not listed. The result will be returned as a new table object.

METHOD
ADT.Table.table.group - group the table using functions

SYNTAX
object group(mapping(string|int:funcion) fus, mixed ... arg);
object group(funcion f, array(string|int)|string|int columns, mixed ... arg);

DESCRIPTION
This method calls the function for each column each time a non uniqe row will be joined. The table will be grouped by the columns not listed. The result will be returned as a new table object.

METHOD
ADT.Table.table.map - map columns over a function

SYNTAX
object map(funcion fu, string|int|array(int|string) columns, mixed ... arg);

DESCRIPTION
This method calls the function for all rows in the table. The value returned will replace the values in the columns given as argument to map. If the function returns an array, several columns will be replaced. Otherwise the first column will be replaced. The result will be returned as a new table object.

METHOD
ADT.Table.table.where - filter the table through a function

SYNTAX
object where(array(string|int)|string|int column1, funcion fu, mixed ... arg);

DESCRIPTION
This method calls the function for each row. If the function returns zero, the row will be thrown away. If the function returns something non-zero, the row will be kept. The result will be returned as a new table object.

METHOD
ADT.Table.table.select - keep only the given columns

SYNTAX
object select(string|int column1, string|int column2, ...);

DESCRIPTION
This method returns a new table object with the selected columns only.

METHOD
ADT.Table.table.remove - remove columns

SYNTAX
object remove(string|int column1, string|int column2, ...);

DESCRIPTION
Like select, but the given columns will not be in the resulting table.

METHOD
ADT.Table.table.encode - represent the table as a binary string

SYNTAX
string encode();

DESCRIPTION
This method returns a binary string representation of the table. It is useful when one wants to store a table, for example in a file.

METHOD
ADT.Table.table.decode - decode an encoded table

SYNTAX
string decode(string table_string);

DESCRIPTION
This method returns a table object from a binary string representation of a table.

METHOD
ADT.Table.table.col - fetch a column

SYNTAX
array col(string|int column);

DESCRIPTION
This method returns the contents of a given column as an array.

METHOD
ADT.Table.table.`[] - fetch a column

SYNTAX
array `[](string|int column);

DESCRIPTION
Same as col.

METHOD
ADT.Table.table.row - fetch a row

SYNTAX
array row(int row_number);

DESCRIPTION
This method returns the contents of a given row as an array.

METHOD
ADT.Table.table.`== - compare two tables

SYNTAX
int `==(object table);

DESCRIPTION
This method compares two tables. They are equal if the contents of the tables and the column names are equal. The column name comparison is case insensitive.

METHOD
ADT.Table.table.append_bottom - concatenate two tables

SYNTAX
object append_bottom(object table);

DESCRIPTION
This method appends two tables. The table given as an argument will be added at the bottom of the current table. Note, the column names must be equal. The column name comparison is case insensitive.

METHOD
ADT.Table.table.append_right - concatenate two tables

SYNTAX
object append_right(object table);

DESCRIPTION
This method appends two tables. The table given as an argument will be added on the right side of the current table. Note that the number of rows in both tables must be equal.

METHOD
ADT.Table.ASCII.encode - produces an ASCII formated table

SYNTAX
string encode(object table, mapping|void options);

DESCRIPTION
This method returns a table represented in ASCII suitable for human eyes. options is an optional mapping. If the keyword "indent" is used with a number, the table will be indented with that number of space characters.

EXAMPLE
array(string) cols = ({ "Fruit", "Provider", "Quantity" });
array(mapping) types = ({ 0, 0, ([ "type":"num" ]) });
array(array) table = ({ ({ "Avocado", "Frukt AB", 314 }),
                                                    ({ "Banana", "Banankompaniet", 4276 }),
     ({ "Orange", "Frukt AB", 81 }),
     ({ "Banana", "Frukt AB", 1174 }),
     ({ "Orange", "General Food", 523 }) });

object t = ADT.Table.table(table, cols, types);

write("FRUITS\n\n");
write(ADT.Table.ASCII.encode(t, ([ "indent":4 ])));

write("\nPROVIDERS\n\n");
write(ADT.Table.ASCII.encode(t->select("provider", "quantity")->
         sum("quantity")->rsort("quantity")));

write("\nBIG PROVIDERS\n\n"+
            ADT.Table.ASCII.encode(t->select("provider", "quantity")->
     sum("quantity")->
     where("quantity", `>, 1000)->
     rsort("quantity")));

write("\nASSORTMENT\n\n");

write(ADT.Table.ASCII.encode(t->select("fruit")->distinct("fruit")->
     sort("fruit"), ([ "indent":4 ])));

14.10 Yabu transaction database

Yabu is a all purpose database, used to store data records associated with a unique key. Yabu is very similar to mappings, however, records are stored in files and not in memory. Also, Yabu features tables, which is a way to handle several mapping-like structures in the same database. A characteristic feature of Yabu is that it allows for transactions. A transaction is a sequence of database commands that will be accepted in whole, or not at all.

Some effort has been made to make sure that Yabu is crash safe. This means that the database should survive process kills, core dumps and such -- although this is not something that can be absolutely guaranteed. Also, all non-commited and pending transactions will be cancelled in case of a crash.

Yabu uses three types of objects, listed below:

A simple example is illustrated below.

EXAMPLE
// Create a database called "my.database" in write/create mode.
object db = Yabu.db("my.database", "wc");

// Create a table called "fruit".
object table = db["fruit"];

// Store a record called "orange" with the value "yummy".
table["orange"] = "yummy";

// Store a record called "apple" with the value 42.
table["apple"] = 42;

Transactions are slightly more complex, but not much so. See example below.

EXAMPLE
// Create a database called "my.database"
// in write/create/transaction mode.
object db = Yabu.db("my.database", "wct");

// Create a table called "fruit".
object table = db["fruit"];

// Create a transaction object for table "fruit".
object transaction = table->transaction();

// Store a record called "orange" with
// the value "yummy". Note that this record
// is only visible through the transaction object.
transaction["orange"] = "yummy";

// Store a record called "apple" with the value 42.
// As with "orange", this record is invisible
// for all objects except this transaction object.
transaction["apple"] = 42;

// Commit the records "orange" and "apple".
// These records are now a part of the database.
transaction->commit();

14.10.1 The database

The db object is the main Yabu database object. It is used to open the database and it can create table objects.

A Yabu database can operate in two basic modes:

  • Read mode. In read mode, nothing in the database can be altered, added nor deleted. All Yabu files will be opended in read mode, which means that the database will be in the same state on the disk as it was prior to the opening.
  • Write mode. In write mode, records can be altered, added or deleted. In combination with create mode, new tables can also be added. Transactions can optionally be used with write mode. When compressed mode is enabled, all records will be compressed before stored on to disk.
Compressed databases opened without compress mode enabled will be handled correctly in both modes, provided that the Gz module is available. However, new records will no longer be compressed in write mode.

METHOD
Yabu.db.create - Open a Yabu database

SYNTAX
void create(string directory, string mode);

DESCRIPTION
Create takes two arguments:

  1. directory is a string specifying the directory where Yabu will store its files. Yabu will create the directory if it does not exist, provided Yabu is opened in write and create mode (see below).

  2. mode is a string specifying the mode in which Yabu will operate. There are five switches available:

NOTE
It is very important not to open the same a database more than once at a time. Otherwise there will be conflicts and most likely strange failures and unpredictable behaviours. Yabu does not check weather a database is already open or not.

EXAMPLE
// Open a database in create/write/transaction mode.
object db = Yabu.db("my.database", "cwt");

// Open a database in read mode.
object db = Yabu.db("my.database", "r");

// Open a database in create/write/compress mode.
object db = Yabu.db("my.database", "cwC");

SEE ALSO
Yabu.db->table, Yabu.db->list_tables, Yabu.db->sync and Yabu.db->purge

METHOD
Yabu.db.table - Open a table

SYNTAX
object(table) table(string table_name);
object(table) `[](string table_name);

DESCRIPTION
This method opens a table with table_name. If the table does not exist, it will be created. A table object will be returned.

SEE ALSO
Yabu.db->list_tables, Yabu.db->sync and Yabu.db->purge

METHOD
Yabu.db.list_tables - List all tables

SYNTAX
array(string) list_tables();
array(string) _indices();

DESCRIPTION
This method lists all available tables.

SEE ALSO
Yabu.db->table, Yabu.db->sync, Yabu.db->purge and Yabu.db->_values

METHOD
Yabu.db._values - Get all tables

SYNTAX
array(Yabu.table) _values();

DESCRIPTION
This method returns all available tables.

SEE ALSO
Yabu.db->table, Yabu.db->sync, Yabu.db->purge and Yabu.db->_indices

METHOD
Yabu.db.sync - Synchronize database

SYNTAX
void sync();

DESCRIPTION
This method synchronizes the database on disk. Yabu stores some information about the database in memory for performance reasons. Syncing is recommended when one wants the information on disk to be updated with the current information in memory.

SEE ALSO
Yabu.db->table, Yabu.db->list_tables and Yabu.db->purge

METHOD
Yabu.db.purge - Delete database

SYNTAX
void purge();

DESCRIPTION
This method deletes the whole database and all database files stored on disk.

SEE ALSO
Yabu.db->table, Yabu.db->list_tables and Yabu.db->sync

14.10.2 Tables

The table object is used to store and retrieve information from a table. Table objects are created by the db class. A table object can create a transaction object.

METHOD
Yabu.table.set - Store a record in a table

SYNTAX
mixed set(string key, mixed data);
mixed `[]=(string key, mixed data);

DESCRIPTION
This method stores the contents of data as a record with the name key. If a record with that name already exists, it will be replaced. Records can only be added to the database in write mode.

SEE ALSO
Yabu.table->get, Yabu.table->delete, Yabu.table->list_keys and Yabu.table->purge

METHOD
Yabu.table.get - Fetch a record from a table

SYNTAX
mixed get(string key);
mixed `[](string key);

DESCRIPTION
This method fetches the data associated with the record name key. If a record does not exist, zero is returned.

SEE ALSO
Yabu.table->set, Yabu.table->delete, Yabu.table->list_keys and Yabu.table->purge

METHOD
Yabu.table.list_keys - List the records in a table

SYNTAX
array(string) list_keys();
array(string) _indices();

DESCRIPTION
This method lists all record names in the table.

SEE ALSO
Yabu.table->set, Yabu.table->get, Yabu.table->delete, Yabu.table->purge and Yabu.table->_values

METHOD
Yabu.table._values - Get all the records in a table

SYNTAX
array(mixed) _values();

DESCRIPTION
This method returns all record names in the table.

SEE ALSO
Yabu.table->set, Yabu.table->get, Yabu.table->delete, Yabu.table->purge and Yabu.table->_indices

METHOD
Yabu.table.delete - Delete a record in a table

SYNTAX
void delete(string key);

DESCRIPTION
This method deletes the record with the name key.

SEE ALSO
Yabu.table->set, Yabu.table->get, Yabu.table->list_keys and Yabu.table->purge

METHOD
Yabu.table.purge - Delete a table

SYNTAX
void purge();

DESCRIPTION
This method deletes the whole table and the table files on disk.

SEE ALSO
Yabu.table->set, Yabu.table->get, Yabu.table->list_keys and Yabu.table->delete

METHOD
Yabu.table.transaction - Begin a transaction

SYNTAX
object(transaction) transaction();

DESCRIPTION
A transaction is a sequence of table commands that will be accepted in whole, or not at all. If the program for some reason crashes or makes an abrupt exit during a transaction, the transaction is cancelled.

This method returns a transaction object.

SEE ALSO
Yabu.transaction->commit and Yabu.transaction->rollback

14.10.3 Transactions

Transactions make it possible to alter, add or delete several database records and guarantee that all changes, or no changes, will be accepted by the database. A transaction object is basically a table object with a few restrictions and additions, listed below:

  • Purge is not available in a transaction object.
  • Commit. In order to make all changes take affect, commit must be issued at the end of a transaction sequence. Changes done by a transaction object will never take affect before commit, even if the database is shut down, the program crashes etc.
  • Rollback. A rollback cancels all changes made by the transaction object.

Rollbacks always succeeds. However, with commit that is not always the case. A commit will fail if:

  • A record that is altered by the transaction object is altered again by something else, before commit. This is called a conflict, and will result in an error upon commit.

METHOD
Yabu.transaction.commit - Commit a transaction

SYNTAX
void commit();

DESCRIPTION
This method commits the changes made in a transaction. If a record affected by the transaction is altered during the transaction, a conflict will arise and an error is thrown.

SEE ALSO
Yabu.table->transaction and Yabu.transaction->rollback

METHOD
Yabu.transaction.rollback - Rollback a transaction

SYNTAX
void rollback();

DESCRIPTION
This method cancels a transaction. All changes made in the transaction are lost.

SEE ALSO
Yabu.table->transaction and Yabu.transaction->commit

14.11 MIME

RFC1521, the Multipurpose Internet Mail Extensions memo, defines a structure which is the base for all messages read and written by modern mail and news programs. It is also partly the base for the HTTP protocol. Just like RFC822, MIME declares that a message should consist of two entities, the headers and the body. In addition, the following properties are given to these two entities:
Headers
Body
The MIME module can extract and analyze these two entities from a stream of bytes. It can also recreate such a stream from these entities. To encapsulate the headers and body entities, the class MIME.Message is used. An object of this class holds all the headers as a mapping from string to string, and it is possible to obtain the body data in either raw or encoded form as a string. Common attributes such as message type and text char set are also extracted into separate variables for easy access.

The Message class does not make any interpretation of the body data, unless the content type is multipart. A multipart message contains several individual messages separated by boundary strings. The create method of the Message class will divide a multipart body on these boundaries, and then create individual Message objects for each part. These objects will be collected in the array body_parts within the original Message object. If any of the new Message objects have a body of type multipart, the process is of course repeated recursively. The following figure illustrates a multipart message containing three parts, one of which contains plain text, one containing a graphical image, and the third containing raw uninterpreted data:

14.11.1 Global functions

FUNCTION
MIME.decode - Remove transfer encoding

SYNTAX
string decode(string data, string encoding);

DESCRIPTION
Extract raw data from an encoded string suitable for transport between systems. The encoding can be any of
  • 7bit
  • 8bit
  • base64
  • binary
  • quoted-printable
  • x-uue
  • x-uuencode
The encoding string is not case sensitive.

SEE ALSO
MIME.encode

FUNCTION
MIME.decode_base64 - Decode <tt>base64</tt> transfer encoding

SYNTAX
string decode_base64(string encoded_data);

DESCRIPTION
This function decodes data encoded using the base64 transfer encoding.

SEE ALSO
MIME.encode_base64

FUNCTION
MIME.decode_qp - Decode <tt>quoted-printable</tt> transfer encoding

SYNTAX
string decode_qp(string encoded_data);

DESCRIPTION
This function decodes data encoded using the quoted-printable (a.k.a. quoted-unreadable) transfer encoding.

SEE ALSO
MIME.encode_qp

FUNCTION
MIME.decode_uue - Decode <tt>x-uue</tt> transfer encoding

SYNTAX
string decode_uue(string encoded_data);

DESCRIPTION
This function decodes data encoded using the x-uue transfer encoding. It can also be used to decode generic UUEncoded files.

SEE ALSO
MIME.encode_uue

FUNCTION
MIME.decode_word - De-scramble RFC1522 encoding

SYNTAX
array(string) decode_word(string word);

DESCRIPTION
Extracts the textual content and character set from an encoded word as specified by RFC1522. The result is an array where the first element is the raw text, and the second element the name of the character set. If the input string is not an encoded word, the result is still an array, but the char set element will be set to 0. Note that this function can only be applied to individual encoded words.

EXAMPLE
> Array.map("=?iso-8859-1?b?S2lscm95?= was =?us-ascii?q?h=65re?="/" ",
                        MIME.decode_word);
Result: ({ /* 3 elements */
        ({ /* 2 elements */
                "Kilroy",
                "iso-8859-1"
        }),
        ({ /* 2 elements */
                "was",
                0
        }),
        ({ /* 2 elements */
                "here",
                "us-ascii"
        })
})

SEE ALSO
MIME.encode_word

FUNCTION
MIME.encode - Apply transfer encoding

SYNTAX
string encode(string data, string encoding,
void|string filename,
void|int no_linebreaks);

DESCRIPTION
Encode raw data into something suitable for transport to other systems. The encoding can be any of
  • 7bit
  • 8bit
  • base64
  • binary
  • quoted-printable
  • x-uue
  • x-uuencode
The encoding string is not case sensitive. For the x-uue encoding, an optional filename string may be supplied. If a nonzero value is passed as no_linebreaks, the result string will not contain any linebreaks (base64 and quoted-printable only).

SEE ALSO
MIME.decode

FUNCTION
MIME.encode_base64 - Encode string using <tt>base64</tt> transfer encoding

SYNTAX
string encode_base64(string data, void|int no_linebreaks);

DESCRIPTION
This function encodes data using the base64 transfer encoding. If a nonzero value is passed as no_linebreaks, the result string will not contain any linebreaks.

SEE ALSO
MIME.decode_base64

FUNCTION
MIME.encode_qp - Encode string using <tt>quoted-printable</tt> transfer encoding

SYNTAX
string encode_qp(string data, void|int no_linebreaks);

DESCRIPTION
This function encodes data using the quoted-printable (a.k.a. quoted-unreadable) transfer encoding. If a nonzero value is passed as no_linebreaks, the result string will not contain any linebreaks.

NOTE
Please do not use this function. QP is evil, and there's no excuse for using it.

SEE ALSO
MIME.decode_qp

FUNCTION
MIME.encode_uue - Encode string using <tt>x-uue</tt> transfer encoding

SYNTAX
string encode_uue(string encoded_data, void|string filename);

DESCRIPTION
This function encodes data using the x-uue transfer encoding. The optional argument filename specifies an advisory filename to include in the encoded data, for extraction purposes. This function can also be used to produce generic UUEncoded files.

SEE ALSO
MIME.decode_uue

FUNCTION
MIME.encode_word - Encode word according to RFC1522

SYNTAX
string encode_word(array(string) word, string encoding);

DESCRIPTION
Create an encoded word as specified in RFC1522 from an array containing a raw text string and a char set name. The text will be transfer encoded according to the encoding argument, which can be either "base64" or "quoted-printable" (or either "b" or "q" for short). If either the second element of the array (the char set name), or the encoding argument is 0, the raw text is returned as is.

EXAMPLE
> MIME.encode_word( ({ "Quetzalcoatl", "iso-8859-1" }), "base64" );
Result: =?iso-8859-1?b?UXVldHphbGNvYXRs?=
> MIME.encode_word( ({ "Foo", 0 }), "base64" );
Result: Foo

SEE ALSO
MIME.decode_word

FUNCTION
MIME.generate_boundary - Create a suitable boundary string for multiparts

SYNTAX
string generate_boundary();

DESCRIPTION
This function will create a string that can be used as a separator string for multipart messages. The generated string is guaranteed not to appear in base64, quoted-printable, or x-uue encoded data. It is also unlikely to appear in normal text. This function is used by the cast method of the Message class if no boundary string is specified.

FUNCTION
MIME.guess_subtype - Provide a reasonable default for the subtype field

SYNTAX
string guess_subtype(string type);

DESCRIPTION
Some pre-RFC1521 mailers provide only a type and no subtype in the Content-Type header field. This function can be used to obtain a reasonable default subtype given the type of a message. (This is done automatically by the MIME.Message class.) Currently, the function uses the following guesses:
typesubtype
textplain
messagerfc822
multipartmixed

FUNCTION
MIME.parse_headers - Separate a bytestream into headers and body

SYNTAX
array(mapping(string:string)|string) parse_headers(string message);

DESCRIPTION
This is a low level function that will separate the headers from the body of an encoded message. It will also translate the headers into a mapping. It will however not try to analyze the meaning of any particular header, This also means that the body is returned as is, with any transfer-encoding intact. It is possible to call this function with just the header part of a message, in which case an empty body will be returned.

The result is returned in the form of an array containing two elements. The first element is a mapping containing the headers found. The second element is a string containing the body.

FUNCTION
MIME.quote - Create an RFC822 header field from lexical elements

SYNTAX
string quote(array(string|int) lexical_elements);

DESCRIPTION
This function is the inverse of the tokenize function. A header field value is constructed from a sequence of lexical elements. Characters (ints) are taken to be special-characters, whereas strings are encoded as atoms or quoted-strings, depending on whether they contain any special characters.

EXAMPLE
> MIME.quote( ({ "attachment", ';', "filename", '=', "/usr/dict/words" }) );
Result: attachment;filename="/usr/dict/words"

NOTE
There is no way to construct a domain-literal using this function. Neither can it be used to produce comments.

SEE ALSO
MIME.tokenize

FUNCTION
MIME.reconstruct_partial - Join a fragmented message to its original form

SYNTAX
int|object reconstruct_partial(array(object) collection);

DESCRIPTION
This function will attempt to reassemble a fragmented message from its parts. The array collection should contain MIME.Message objects forming a complete set of parts for a single fragmented message. The order of the messages in this array is not important, but every part must exist at least once.

Should the function succeed in reconstructing the original message, a new MIME.Message object is returned. Note that this message may in turn be a part of another, larger, fragmented message. If the function fails to reconstruct an original message, it returns an integer indicating the reason for its failure:

  • If an empty collection is passed in, or one that contains messages which are not of type message/partial, or parts of different fragmented messages, the function returns 0.
  • If more fragments are needed to reconstruct the entire message, the number of additional messages needed is returned.
  • If more fragments are needed, but the function can't tell exactly how many, -1 is returned.

SEE ALSO
MIME.Message->is_partial

FUNCTION
MIME.tokenize - Separate an RFC822 header field into lexical elements

SYNTAX
array(string|int) tokenize(string header);

DESCRIPTION
A structured header field, as specified by RFC822, is constructed from a sequence of lexical elements. These are:
  • individual special characters
  • quoted-strings
  • domain-literals
  • comments
  • atoms
This function will analyze a string containing the header value, and produce an array containing the lexical elements. Individual special characters will be returned as characters (i.e. ints). Quoted-strings, domain-literals and atoms will be decoded and returned as strings. Comments are not returned in the array at all.

EXAMPLE
> MIME.tokenize("multipart/mixed; boundary=\"foo/bar\" (Kilroy was here)");
Result: ({ /* 7 elements */
    "multipart",
    47,
    "mixed",
    59,
    "boundary",
    61,
    "foo/bar"
})

NOTE
As domain-literals are returned as strings, there is no way to tell the domain-literal [127.0.0.1] from the quoted-string "[127.0.0.1]". Hopefully this won't cause any problems. Domain-literals are used seldom, if at all, anyway...

The set of special-characters is the one specified in RFC1521 (i.e. "<", ">", "@", ",", ";", ":", "\", "/", "?", "="), and not the one specified in RFC822.

SEE ALSO
MIME.quote

14.11.2 The MIME.Message class

CLASS
MIME.Message - The MIME.Message class This class is used to hold a decoded MIME message.

14.11.2.1 Public fields

VARIABLE
MIME.Message.body_parts - Multipart sub-messages

SYNTAX
array(object) msg->body_parts;

DESCRIPTION
If the message is of type multipart, this is an array containing one Message object for each part of the message. If the message is not a multipart, this field is 0.

SEE ALSO
MIME.Message->type and MIME.Message->boundary

VARIABLE
MIME.Message.boundary - Boundary string for multipart messages

SYNTAX
string msg->boundary;

DESCRIPTION
For multipart messages, this Content-Type parameter gives a delimiter string for separating the individual messages. As multiparts are handled internally by the module, you should not need to access this field.

SEE ALSO
MIME.Message->setboundary

VARIABLE
MIME.Message.charset - Character encoding for text bodies

SYNTAX
string msg->charset;

DESCRIPTION
One of the possible parameters of the Content-Type header is the charset attribute. It determines the character encoding used in bodies of type text. If there is no Content-Type header, the value of this field is "us-ascii".

SEE ALSO
MIME.Message->type

VARIABLE
MIME.Message.disposition - Multipart subpart disposition

SYNTAX
string msg->disposition;

DESCRIPTION
The first part of the Content-Disposition header, hinting on how this part of a multipart message should be presented in an interactive application. If there is no Content-Disposition header, this field is 0.

VARIABLE
MIME.Message.disp_params - Content-Disposition parameters

SYNTAX
mapping(string:string) msg->disp_params;

DESCRIPTION
A mapping containing all the additional parameters to the Content-Disposition header.

SEE ALSO
MIME.Message->setdisp_param and MIME.Message->get_filename

VARIABLE
MIME.Message.headers - All header fields of the message

SYNTAX
mapping(string:string) msg->headers;

DESCRIPTION
This mapping contains all the headers of the message. The key is the header name (in lower case) and the value is the header value. Although the mapping contains all headers, some particular headers get special treatment by the module and should not be accessed through this mapping. These fields are currently:
  • content-type
  • content-disposition
  • content-length
  • content-transfer-encoding
The contents of these fields can be accessed and/or modified through a set of variables and methods available for this purpose.

SEE ALSO
MIME.Message->type, MIME.Message->subtype, MIME.Message->charset, MIME.Message->boundary, MIME.Message->transfer_encoding, MIME.Message->params, MIME.Message->disposition, MIME.Message->disp_params, MIME.Message->setencoding, MIME.Message->setparam, MIME.Message->setdisp_param, MIME.Message->setcharset and MIME.Message->setboundary

VARIABLE
MIME.Message.params - Content-Type parameters

SYNTAX
mapping(string:string) msg->params;

DESCRIPTION
A mapping containing all the additional parameters to the Content-Type header. Some of these parameters have fields of their own, which should be accessed instead of this mapping wherever applicable.

SEE ALSO
MIME.Message->charset, MIME.Message->boundary and MIME.Message->setparam

VARIABLE
MIME.Message.subtype - The subtype attribute of the Content-Type header

SYNTAX
string msg->subtype;

DESCRIPTION
The Content-Type header contains a type, a subtype, and optionally some parameters. This field contains the subtype attribute extracted from the header. If there is no Content-Type header, the value of this field is "plain".

SEE ALSO
MIME.Message->type and MIME.Message->params

VARIABLE
MIME.Message.transfer_encoding - Body encoding method

SYNTAX
string msg->transfer_encoding;

DESCRIPTION
The contents of the Content-Transfer-Encoding header. If no Content-Transfer-Encoding header is given, this field is 0. Transfer encoding and decoding is done transparently by the module, so this field should be interesting only to applications wishing to do auto conversion of certain transfer encodings.

SEE ALSO
MIME.Message->setencoding

VARIABLE
MIME.Message.type - The type attribute of the Content-Type header

SYNTAX
string msg->type;

DESCRIPTION
The Content-Type header contains a type, a subtype, and optionally some parameters. This field contains the type attribute extracted from the header. If there is no Content-Type header, the value of this field is "text".

SEE ALSO
MIME.Message->subtype and MIME.Message->params

14.11.2.2 Public methods

METHOD
MIME.Message.cast - Encode message into byte stream

SYNTAX
string (string )MIME.Message;

DESCRIPTION
Casting the message object to a string will yield a byte stream suitable for transmitting the message over protocols such as ESMTP and NNTP. The body will be encoded using the current transfer encoding, and subparts of a multipart will be collected recursively. If the message is a multipart and no boundary string has been set, one is generated using generate_boundary.

EXAMPLE
> object msg = MIME.Message( "Hello, world!",
                ([ "MIME-Version" : "1.0",
                     "Content-Type":"text/plain",
                     "Content-Transfer-Encoding":"base64" ]) );
Result: object
> (string )msg;
Result: Content-Type: text/plain
Content-Length: 20
Content-Transfer-Encoding: base64
MIME-Version: 1.0

SGVsbG8sIHdvcmxkIQ==

SEE ALSO
MIME.Message->create

METHOD
MIME.Message.create - Create a Message object

SYNTAX
object MIME.Message(void | string message,
void | mapping(string:string) headers,
void | array(object) parts);

DESCRIPTION
There are several ways to call the constructor of the Message class;
  • With zero arguments, you will get a dummy message without either headers or body. Not very useful.
  • With one argument, the argument is taken to be a byte stream containing a message in encoded form. The constructor will analyze the string and extract headers and body.
  • With two or three arguments, the first argument is taken to be the raw body data, and the second argument a desired set of headers. The keys of this mapping are not case-sensitive. If the given headers indicate that the message should be of type multipart, an array of Message objects constituting the subparts should be given as a third argument.

EXAMPLE
> object msg = MIME.Message( "Hello, world!", ([ "MIME-Version" : "1.0", "Content-Type" : "text/plain; charset=iso-8859-1" ]) ); Result: object > msg->charset; Result: iso-8859-1

SEE ALSO
MIME.Message->cast

METHOD
MIME.Message.getdata - Obtain raw body data

SYNTAX
string getdata();

DESCRIPTION
This method returns the raw data of the message body entity. The type and subtype attributes indicate how this data should be interpreted.

SEE ALSO
MIME.Message->getencoded

METHOD
MIME.Message.getencoded - Obtain encoded body data

SYNTAX
string getencoded();

DESCRIPTION
This method returns the data of the message body entity, encoded using the current transfer encoding. You should never have to call this function.

SEE ALSO
MIME.Message->getdata

METHOD
MIME.Message.get_filename - Get supplied filename for body data

SYNTAX
string get_filename();

DESCRIPTION
This method tries to find a suitable filename should you want to save the body data to disk. It will examine the filename attribute of the Content-Disposition header, and failing that the name attribute of the Content-Type header. If neither attribute is set, the method returns 0.

NOTE
An interactive application should always query the user for the actual filename to use. This method may provide a reasonable default though.

METHOD
MIME.Message.is_partial - Identify <tt>message/partial</tt> message

SYNTAX
array(string|int) is_partial();

DESCRIPTION
If this message is a part of a fragmented message (i.e. has a Content-Type of message/partial), an array with three elements is returned. The first element is an identifier string. This string should be used to group this message with the other fragments of the message (which will have the same id string). The second element is the sequence number of this fragment. The first part will have number 1, the next number 2 etc. The third element of the array is either the total number of fragments that the original message has been split into, or 0 of this information was not available. If this method is called in a message that is not a part of a fragmented message, it will return 0.

SEE ALSO
MIME.reconstruct_partial

METHOD
MIME.Message.setboundary - Set boundary parameter

SYNTAX
void setboundary(string boundary);

DESCRIPTION
Sets the boundary parameter of the Content-Type header. This is equivalent of calling msg->setparam("boundary", boundary).

SEE ALSO
MIME.Message->setparam

METHOD
MIME.Message.setcharset - Set charset parameter

SYNTAX
void setcharset(string charset);

DESCRIPTION
Sets the charset parameter of the Content-Type header. This is equivalent of calling msg->setparam("charset", charset).

SEE ALSO
MIME.Message->setparam

METHOD
MIME.Message.setdata - Replace body data

SYNTAX
void setdata(string data);

DESCRIPTION
Replaces the body entity of the data with a new piece of raw data. The new data should comply to the format indicated by the type and subtype attributes. Do not use this method unless you know what you are doing.

SEE ALSO
MIME.Message->getdata

METHOD
MIME.Message.setdisp_param - Set Content-Disposition parameters

SYNTAX
void setdisp_param(string param, string value);

DESCRIPTION
Set or modify the named parameter of the Content-Disposition header. A common parameters is e.g. filename. It is not allowed to modify the Content-Disposition header directly, please use this function instead.

SEE ALSO
MIME.Message->setparam and MIME.Message->get_filename

METHOD
MIME.Message.setencoding - Set transfer encoding for message body

SYNTAX
void setencoding(string encoding);

DESCRIPTION
Select a new transfer encoding for this message. The Content-Transfer-Encoding header will be modified accordingly, and subsequent calls to getencoded will produce data encoded using the new encoding. See encode for a list of valid encodings.

SEE ALSO
MIME.Message->getencoded

METHOD
MIME.Message.setparam - Set Content-Type parameters

SYNTAX
void setparam(string param, string value);

DESCRIPTION
Set or modify the named parameter of the Content-Type header. Common parameters include charset for text messages, and boundary for multipart messages. It is not allowed to modify the Content-Type header directly, please use this function instead.

SEE ALSO
MIME.Message->setcharset, MIME.Message->setboundary and MIME.Message->setdisp_param

14.12 Simulate

This module is used to achieve better compatibility with older versions of Pike. It can also be used for convenience, but I would advice against it since some functions defined here are much slower than using similar functions in other modules. The purpose of this section in the manual is to make it easier for the reader to understand code that uses the Simulate module, not to encourage the use of the Simulate module.

Simulate inherits the Array, Stdio, String and Process modules, so importing he Simulate module also imports all identifiers from these modules. In addition, these functions are available:

FUNCTION
Simulate.member_array - find first occurrence of a value in an array

SYNTAX
int member_array(mixed item, array arr);

DESCRIPTION
Returns the index of the first occurrence of item in array arr. If not found, then -1 is returned. This is the same as search(arr, item).

FUNCTION
Simulate.previous_object - return the calling object

SYNTAX
object previous_object();

DESCRIPTION
Returns an object pointer to the object that called current function, if any.

SEE ALSO
backtrace

FUNCTION
Simulate.this_function - return a function pointer to the current function

SYNTAX
function this_function();

DESCRIPTION
Returns a function pointer to the current function, useful for making recursive lambda-functions.

SEE ALSO
backtrace

FUNCTION
Simulate.get_function - fetch a function from an object

SYNTAX
function get_function(object o, string name);

DESCRIPTION
Defined as: return o[name];

FUNCTION
Simulate.map_regexp - filter an array through a regexp

SYNTAX
array(string) map_regexp(array(string) arr, string reg);

DESCRIPTION
Returns those strings in arr that matches the regexp in reg.

SEE ALSO
Regexp

CONSTANT
Simulate.PI - pi

SYNTAX
PI;

DESCRIPTION
This is not a function, it is a constant roughly equal to the mathematical constant Pi.

FUNCTION
Simulate.all_efuns - return all 'efuns'

SYNTAX
mapping all_efuns();

DESCRIPTION
This function is the same as all_constants.

SEE ALSO
all_constants

FUNCTION
Simulate.explode - explode a string on a delimeter

SYNTAX
string explode(string s, string delimiter);

DESCRIPTION
This function is really the same as the division operator. It simly divides the string s into an array by splitting s at every occurance of delimeter.

SEE ALSO
Simulate.implode

FUNCTION
Simulate.filter_array - filter an array through a function

SYNTAX
array filter_array(array arr,function fun,mixed ... args);
array filter_array(array(object) arr,string fun,mixed ... args);
array filter_array(array(function) arr,-1,mixed ... args);

DESCRIPTION
Filter array is the same function as Array.filter.

SEE ALSO
Array.filter

FUNCTION
Simulate.implode - implode an array of strings

SYNTAX
string implode(array(string) a, string delimiter);

DESCRIPTION
This function is the inverse of explode. It concatenates all the strings in a with a delimiter in between each.

This function is the same as multiplication.

EXAMPLE
> implode( ({ "foo","bar","gazonk"}), "-" );
Result: foo-bar-gazonk
> ({ "a","b","c" })*" and ";
Result: a and b and c
>

SEE ALSO
Simulate.explode

FUNCTION
Simulate.m_indices - return all indices from a mapping

SYNTAX
array m_indices(mapping m);

DESCRIPTION
This function is equal to indices.

SEE ALSO
indices

FUNCTION
Simulate.m_sizeof - return the size of a mapping

SYNTAX
int m_sizeof(mapping m);

DESCRIPTION
This function is equal to sizeof.

SEE ALSO
sizeof

FUNCTION
Simulate.m_values - return all values from a mapping

SYNTAX
array m_values(mapping m);

DESCRIPTION
This function is equal to values.

SEE ALSO
values

FUNCTION
Simulate.map_array - map an array over a function

SYNTAX
array map_array(array arr,function fun,mixed ... args);
array map_array(array(object) arr,string fun,mixed ... args);
array map_array(array(function) arr,-1,mixed ... arg);

DESCRIPTION
This function is the same as Array.map.

SEE ALSO
Array.map

FUNCTION
Simulate.strstr - find a string inside a string

SYNTAX
int strstr(string str1,string str2);

DESCRIPTION
Returns the position of str2 in str1, if str2 can't be found in str1 -1 is returned.

SEE ALSO
sscanf, Simulate.explode and search

FUNCTION
Simulate.sum - add values together

SYNTAX
int sum(int ... i);
float sum(float ... f);
string sum(string|float|int ... p);
array sum(array ... a);
mapping sum(mapping ... m);
list sum(multiset ... l);

DESCRIPTION
This function does exactly the same thing as adding all the arguments together with +. It's just here so you can get a function pointer to the summation operator.

FUNCTION
Simulate.add_efun - add an efun or constant

SYNTAX
void add_efun(string func_name, mixed function)
void add_efun(string func_name)

DESCRIPTION
This function is the same as add_constant.

SEE ALSO
Simulate.add_constant

FUNCTION
Simulate.l_sizeof - return the size of a multiset

SYNTAX
int l_sizeof(multiset m);

DESCRIPTION
This function is equal to sizeof.

SEE ALSO
sizeof

FUNCTION
Simulate.listp - is the argument a list? (multiset)

SYNTAX
int listp(mixed l);

DESCRIPTION
This function is the same as multisetp.

SEE ALSO
Simulate.multisetp

FUNCTION
Simulate.mklist - make a multiset

SYNTAX
multiset mklist(array a);

DESCRIPTION
This function creates a multiset from an array.

EXAMPLE
> mklist( ({1,2,3}) ); Result: (< /* 3 elements */ 1, 2, 3 >)

SEE ALSO
aggregate_multiset

FUNCTION
Simulate.aggregate_list - aggregate a multiset

SYNTAX
multiset aggregate_list(mixed ... args);

DESCRIPTION
This function is exactly the same as aggregate_multiset.

SEE ALSO
aggregate_multiset

FUNCTION
Simulate.query_host_name - return the name of the host we are running on

SYNTAX
string query_host_name();

DESCRIPTION
This function returns the name of the machine the interpreter is running on. This is the same thing that the command 'hostname' prints.

DESCRIPTION
This module enables access to the Mysql database from within Pike. Mysql is available from www.tcx.se.

NOTE
$Id: mysql.c,v 1.37 2000/08/13 14:55:14 grubba Exp $

SEE ALSO
Mysql.mysql, Mysql.result and Sql.sql

14.13 Mysql.mysql

CLASS
Mysql.mysql

DESCRIPTION
Mysql.mysql is a pre-compiled Pike program. It enables access to the Mysql database from within Pike. Mysql.mysql is a part of the Mysql module. Mysql is available from www.tcx.se.

SEE ALSO
Mysql.result and Sql.sql

METHOD
Mysql.mysql.affected_rows

SYNTAX
int affected_rows()

DESCRIPTION
Returns the number of rows affected by the last query.

METHOD
Mysql.mysql.big_query

SYNTAX
object(Mysql.mysql_result) big_query(string q)

DESCRIPTION
Make an SQL query

ARGUMENTS
argument(s)description
string q
The SQL query This function sends an SQL query to the Mysql-server. The result of the query is returned as a Mysql.mysql_result object. Returns 0 if the query didn't return any result (e.g. INSERT or similar).

SEE ALSO
mysql_result

METHOD
Mysql.mysql.binary_data

SYNTAX
int binary_data()

DESCRIPTION
Inform if this version of mysql supports binary data This function returns non-zero if binary data can be reliably stored and retreived with this version of the mysql-module. Usually, there is no problem storing binary data in mysql-tables, but data containing '\0' (NUL) couldn't be fetched with old versions (prior to 3.20.5) of the mysql-library.

METHOD
Mysql.mysql.create

SYNTAX
void create()
void create(string host)
void create(string host,  string database)
void create(string host,  string database,  string user)
void create(string host,  string database,  string user,  string password)

DESCRIPTION
Connects to a Mysql database. To access the Mysql database, you must first connect to it. This is done with the function mysql(). If you give no argument, or give "" as hostname it will connect with a UNIX-domain socket, which is a big performance gain.

METHOD
Mysql.mysql.create_db

SYNTAX
void create_db(string database)

DESCRIPTION
Create a new database

ARGUMENTS
argument(s)description
string database
Name of the database to be created This function creates a new database in the Mysql-server.

SEE ALSO
select_db and drop_db

METHOD
Mysql.mysql.drop_db

SYNTAX
void drop_db(string database)

DESCRIPTION
Drop a database

ARGUMENTS
argument(s)description
string database
Name of database to be dropped This function drops a database from a Mysql-server.

SEE ALSO
create_db and select_db

METHOD
Mysql.mysql.error

SYNTAX
string error()

DESCRIPTION
Returns a string describing the last error from the Mysql-server.

METHOD
Mysql.mysql.host_info

SYNTAX
string host_info()

DESCRIPTION
Give information about the Mysql-server connection This function returns a string describing the connection to the Mysql-server.

SEE ALSO
statistics, server_info and protocol_info

METHOD
Mysql.mysql.insert_id

SYNTAX
int insert_id()

DESCRIPTION
Returns the id of the last INSERT query into a table with an AUTO INCREMENT field.

METHOD
Mysql.mysql.list_dbs

SYNTAX
object(Mysql.mysql_result) list_dbs()
object(Mysql.mysql_result) list_dbs(string wild)

DESCRIPTION
List databases Returns a table containing the names of all databases in the Mysql-server. If an argument is specified, only those matching wild are returned.

SEE ALSO
list_tables, list_fields, list_processes and Mysql.mysql_result

METHOD
Mysql.mysql.list_fields

SYNTAX
array(int|mapping(string:mixed)) list_fields(string table)
array(int|mapping(string:mixed)) list_fields(string table,  string wild)

DESCRIPTION
List all fields. Returns an array of mappings with information about the fields in the specified table. The mappings contain the following entries:

 "name":        string  The name of the field.
 "table":       string  The name of the table.
 "default":     string  The default value for the field.
 "type":        string  The type of the field.
 "length":      int     The length of the field.
 "max_length":  int     The length of the longest element in this field.
 "flags":       multiset(string)        Some flags.
 "decimals":    int     The number of decimalplaces.
The type of the field can be any of: "decimal", "char", "short", "long", "float", "double", "null", "time", "longlong", "int24", "tiny blob", "medium blob", "long blob", "var string", "string" or "unknown". The flags multiset can contain any of "primary_key": This field is part of the primary key for this table. "not_null": This field may not be NULL. "blob": This field is a blob field.

ARGUMENTS
argument(s)description
string table
Name of table to list the fields of
string wild
Wildcard to filter the result with

NOTE
Michael Widenius recomends usage of the following query instead:

 show fields in 'table' like "wild"

SEE ALSO
list_dbs, list_tables, list_processes and fetch_fields

METHOD
Mysql.mysql.list_processes

SYNTAX
object(Mysql.mysql_result) list_processes()

DESCRIPTION
List all processes in the Mysql-server Returns a table containing the names of all processes in the Mysql-server.

SEE ALSO
list_dbs, list_tables, list_fields and Mysql.mysql_result

METHOD
Mysql.mysql.list_tables

SYNTAX
object(Mysql.mysql_result) list_tables()
object(Mysql.mysql_result) list_tables(string wild)

DESCRIPTION
List tables in the current database

ARGUMENTS
argument(s)description
string wild
Wildcard to filter with. Returns a table containing the names of all tables in the current database. If an argument is given, only those matching wild are returned.

SEE ALSO
list_dbs, list_fields, list_processes and Mysql.mysql_result

METHOD
Mysql.mysql.protocol_info

SYNTAX
int protocol_info()

DESCRIPTION
Give the Mysql protocol version This function returns the version number of the protocol the Mysql-server uses.

SEE ALSO
statistics, server_info and host_info

METHOD
Mysql.mysql.reload

SYNTAX
void reload()

DESCRIPTION
Reload security tables This function causes the Mysql-server to reload its access tables.

SEE ALSO
shutdown

METHOD
Mysql.mysql.select_db

SYNTAX
void select_db(string database)

DESCRIPTION
The Mysql-server can hold several databases. You select which one you want to access with this function.

SEE ALSO
create, create_db and drop_db

METHOD
Mysql.mysql.server_info

SYNTAX
string server_info()

DESCRIPTION
Give the version number of the Mysql-server This function returns the version number of the Mysql-server.

SEE ALSO
statistics, host_info and protocol_info

METHOD
Mysql.mysql.shutdown

SYNTAX
void shutdown()

DESCRIPTION
Shutdown the Mysql-server This function shuts down a running Mysql-server. reload

METHOD
Mysql.mysql.statistics

SYNTAX
string statistics()

DESCRIPTION
Some Mysql-server statistics This function returns some server statistics. Example:

int main()
{
  write(mysql()->statistics());
  return(0);
}

SEE ALSO
server_info, host_info and protocol_info

14.14 The Pike Crypto Toolkit

14.14.1 Introduction

The Crypto module provides an object-oriented framwork for encryption and related functionality. More specifically, its objects han be classified as follows:
Block ciphers
encrypt data in chunks of typically 8 bytes, using a secret key.
Stream ciphers
operate on the data to be encrypted one byte at a time, for exemple by xoring it with a sequence of pseudorandom bytes.
Cryptographic hash functions
transform a bytesequence of arbitrary length into a short string of a fixed length of typically 16 or 20 bytes, in such a way that it is practically impossible to find two distinct strings with the same hash value.
Public key algorithms
can support both encryption and digital signatures.
Abstract building blocks
for combining ciphers (mainly for block ciphers). These objects behave like block ciphers, but delegate encryption to one or several underlying objects, in some way. For example, block ciphers are often used in a feedback mode. The ciphers by themselves know nothing about these different "modes of operation", instead this knowledge is abstracted into separate objects. If you want IDEA in Cipher Block Chaining mode, you combine an IDEA object and a CBC object.

Randomness
is essential for many cryptographic application. The toolkit includes a few different random number generators, with varying degrees of true randomness.
Frontend objects
that handle things like padding messages, or make it more convenient to use popular combinations of ciphers, feedback modes, etc.

14.14.2 Block ciphers

The block ciphers included in the current version are DES, IDEA and CAST128 (note that IDEA is patented, see
Ascom Tech for details). All block ciphers have a common set of methods.

METHOD
crypt_block

SYNTAX
string o->crypt_block(string blocks);

DESCRIPTION
Encrypts or decrypts an even number of block, using the current key. If more than one block is given, they are encrypted/decrypted independently, i.e. in Electronic Code Book (ECB) mode.

METHOD
query_block_size

SYNTAX
int o->query_block_size();

DESCRIPTION
Returns the block size of the cipher, in octets. A typical block size is 8 octets. A string passed to crypt_block() must have a length that is a multiple of the block size.

METHOD
query_key_length

SYNTAX
int o->query_key_length();

DESCRIPTION
Returns the key size of the cipher, in octets. Note that some block ciphers, e.g. CAST128, have a variable key size. In this case, query_key_length returns the recommended key size, although keys of other lengths are accepted by the set_encrypt_key and set_decrypt_key methods. For DES, the real key length is seven octets (56 bits), but the DES standard mandates the use of parity bits. The query_key_length method lies about DES, and says that the key_size is eight octets (64 bits). See also des_parity.

METHOD
set_encrypt_key

SYNTAX
object o->set_encrypt_key(string key);

DESCRIPTION
Installs a key, and configures the object for doing encryption. For convenience, this method returns the object itself.

METHOD
set_decrypt_key

SYNTAX
object o->set_decrypt_key(string key);

DESCRIPTION
Installs a key, and configures the object for doing decryption. For convenience, this method returns the object itself.
The classes are

CLASS
Crypto.des Crypto.des

CLASS
Crypto.idea Crypto.idea
and

CLASS
Crypto.cast Crypto.cast
. To encrypt the block "Pike des" using the DES-key '0123456789abcdef' (in hex), use
Crypto.des()->set_encrypt_key(Crypto.hex_to_string("0123456789abcdef"))
                        ->crypt_block("Pike DES")
although most applications will not use the Crypto.des class directly.

14.14.3 Stream Ciphers

Currently the only stream cipher in the toolkit is the RC4 cipher (also known as "arcfour").

CLASS
Crypto.rc4

METHOD
Crypto.rc4.crypt

SYNTAX
string Crypto.rc4->crypt(string data);

DESCRIPTION
Encrypts or decrypts a string of data.

METHOD
Crypto.rc4.set_encrypt_key

SYNTAX
object Crypto.rc4->set_encrypt_key(string key);

DESCRIPTION
Installs a key, and configures the object for doing encryption. For convenience, this method returns the object itself.

METHOD
Crypto.rc4.set_decrypt_key

SYNTAX
object Crypto.rc4->set_decrypt_key(string key);

DESCRIPTION
Installs a key, and configures the object for doing decryption. For convenience, this method returns the object itself.
Because of the way RC4 works, set_encrypt_key and set_decrypt_key are actually equivalent.

14.14.4 Hash Functions

Cryptographic hash functions are essential for many cryptographic applications, and are also useful in other contexts. The Toolkit includes the two most common, MD5 and SHA1. They have the same methods.

METHOD
update

SYNTAX
object o->update(string data);

DESCRIPTION
Processes some more data. For convenience, this method returns the object itself.

METHOD
digest

SYNTAX
string o->digest();

DESCRIPTION
Returns the hash value, or message digest, corresponding to all the data that was previously passed to the update method. Also resets the hash object, so that it can be used to process a new message.

METHOD
query_digest_size

SYNTAX
int o->query_digest_size();

DESCRIPTION
Returns the size, in octets, of the digests produced by this hash function.
To get the md5 hash of a string s, you would use
Crypto.md5()->update(s)->digest()

14.14.5 Public key algorithms

The only public key algorithm currently in the toolkit is RSA. As the algorithm uses arithmetic on huge numbers, you must also have the GMP library and the corresponding Pike module installed in order to use RSA.

CLASS
Crypto.rsa

METHOD
Crypto.rsa.set_public_key

SYNTAX
object rsa->set_public_key(object(Gmp.mpz) modulo, object(Gmp.mpz) e)

DESCRIPTION
Sets the modulo and the public exponent. For convenience, returns the object itself.

METHOD
Crypto.rsa.set_private_key

SYNTAX
object rsa->set_public_key(object(Gmp.mpz) d)

DESCRIPTION
Sets the private exponent. For convenience, returns the object itself.

METHOD
Crypto.rsa.generate_key

SYNTAX
object rsa->generate_key(int bits, function|void random)

DESCRIPTION
Generates a new rsa key pair, with a modulo of the given bitsize. random should be a function that takes one integer argument n and returns a string of n random octets. The default function is Crypto.randomness.really_random()->read. For convenience, this method returns the object itself.

METHOD
Crypto.rsa.query_blocksize

SYNTAX
int rsa->query_block_size()

DESCRIPTION
Returns the length of the largest string that can be encrypted in one RSA-operation using the current key.

METHOD
Crypto.rsa.encrypt

SYNTAX
string rsa->encrypt(string message, function|void random)

DESCRIPTION
Encrypts message using PKCS#1-style RSA encryption. The function random is used to generate random message padding. Padding does not require a strong random number generator. The default random function is derived from Pike's builting pseudorandom generator predef::random.

METHOD
Crypto.rsa.decrypt

SYNTAX
string rsa->decrypt(string gibberish)

DESCRIPTION
Decrypts a PKCS#1-style RSA-encrypted message. This operation requires knowledge of the private key. Decryption may fail if the input is not a properly encrypted message for this key. In this case, the method returns zero. The PKCS#1 padding method used is vulnerable to a chosen-ciphertext attack discovered by Daniel Bleichenbacher.
There are several methods for signature creation and verification. I don't quite like the interface, so it may very well change in some future version of the Toolkit.

METHOD
Crypto.rsa.sign

SYNTAX
object(Gmp.mpz) rsa->sign(string message, program hash)

DESCRIPTION
Creates a PKCS#1-style signature. This operation requires knowledge of the private key. hash should be a hash algorithm with an ->identifier method which returns a DER-encoded ASN.1 Object Identifier for the hash algorithm. Currently, this is supported only by Crypto.md5. The function returns the signature as a bignum; applications can use
Standards.ASN1.Types.asn1_bit_string(rsa->sign(...))->get_der()
to convert it a DER-encoded ASN.1 bitstring.

METHOD
Crypto.rsa.verify

SYNTAX
int verify(string message, program hash, object(Gmp.mpz) signature)

DESCRIPTION
Verifies a PKCS#1-style RSA signature. Returns 1 if the signature is valid, 0 if not.

METHOD
Crypto.rsa.sha_sign

SYNTAX
string rsa->sha_sign(string message)

DESCRIPTION
Creates an RSA signature using a simpler but non-standard convention.

METHOD
Crypto.rsa.sha_verify

SYNTAX
int sha_verify(string message, string signature)

DESCRIPTION
Verifies signatures created by sha_sign. Returns 1 if the signature is valid, 0 if not.

14.14.6 Combining block cryptos

14.15 Locale.Gettext

DESCRIPTION
This module enables access to localization functions from within Pike.

NOTE
$Id: gettext.c,v 1.5 2000/08/10 09:51:52 per Exp $

METHOD
Locale.Gettext.bindtextdomain

SYNTAX
string bindtextdomain(string|void domainname,  string|void dirname)

DESCRIPTION
The bindtextdomain() function binds the path predicate for a message domain domainname to the value contained in dirname. If domainname is a non-empty string and has not been bound previously, bindtextdomain() binds domainname with dirname.

If domainname is a non-empty string and has been bound previously, bindtextdomain() replaces the old binding with dirname. The dirname argument can be an absolute or relative pathname being resolved when gettext(), dgettext(), or dcgettext() are called. If domainname is null pointer or an empty string, bindtextdomain() returns 0. User defined domain names cannot begin with the string SYS_. Domain names beginning with this string are reserved for system use. The return value from bindtextdomain() is a string containing dirname or the directory binding associated with domainname if dirname is void. If no binding is found, the default locale path is returned. If domainname is void or an empty string, bindtextdomain() takes no action and returns a 0.

ARGUMENTS
argument(s)description
string domainname
The domain to query or bind a path to.
string dirname
The directory name to bind to the choosen domain.

SEE ALSO
textdomain, gettext, dgettext, dcgettext, setlocale and localeconv

METHOD
Locale.Gettext.dcgettext

SYNTAX
string dcgettext(string domain,  string msg,  int category)

DESCRIPTION
Return a translated version of msg within the context of the specified domain and current locale for the specified category. Calling dcgettext with category Locale.Gettext.LC_MESSAGES gives the same result as dgettext. If there is not translation available, msg is returned.

ARGUMENTS
argument(s)description
string domain
The domain to lookup the message in.
string msg
The message to translate.
int category
The category which locale should be used.

SEE ALSO
bindtextdomain, textdomain, gettext, dgettext, setlocale and localeconv

METHOD
Locale.Gettext.dgettext

SYNTAX
string dgettext(string domain,  string msg)

DESCRIPTION
Return a translated version of msg within the context of the specified domain and current locale. If there is not translation available, msg is returned.

ARGUMENTS
argument(s)description
string domain
The domain to lookup the message in.
string msg
The message to translate.

SEE ALSO
bindtextdomain, textdomain, gettext, dcgettext, setlocale and localeconv

METHOD
Locale.Gettext.gettext

SYNTAX
string gettext(string msg)

DESCRIPTION
Return a translated version of msg within the context of the current domain and locale. If there is not translation available, msg is returned.

ARGUMENTS
argument(s)description
string msg
The message to translate.

SEE ALSO
bindtextdomain, textdomain, dgettext, dcgettext, setlocale and localeconv

METHOD
Locale.Gettext.localeconv

SYNTAX
mapping localeconv()

DESCRIPTION
The localeconv() function returns a mapping with settings for the current locale. This mapping contains all values associated with the locale categories LC_NUMERIC and LC_MONETARY.

string decimal_point: The decimal-point character used to format non-monetary quantities.

string thousands_sep: The character used to separate groups of digits to the left of the decimal-point character in formatted non-monetary quantities.

string int_curr_symbol: The international currency symbol applicable to the current locale, left-justified within a four-character space-padded field. The character sequences should match with those specified in ISO 4217 Codes for the Representation of Currency and Funds.

string currency_symbol: The local currency symbol applicable to the current locale.

string mon_decimal_point: The decimal point used to format monetary quantities.

string mon_thousands_sep: The separator for groups of digits to the left of the decimal point in formatted monetary quantities.

string positive_sign: The string used to indicate a non-negative-valued formatted monetary quantity.

string negative_sign: The string used to indicate a negative-valued formatted monetary quantity.

int int_frac_digits: The number of fractional digits (those to the right of the decimal point) to be displayed in an internationally formatted monetary quantity.

int frac_digits: The number of fractional digits (those to the right of the decimal point) to be displayed in a formatted monetary quantity.

int p_cs_precedes: Set to 1 or 0 if the currency_symbol respectively precedes or succeeds the value for a non-negative formatted monetary quantity.

int p_sep_by_space: Set to 1 or 0 if the currency_symbol respectively is or is not separated by a space from the value for a non-negative formatted monetary quantity.

int n_cs_precedes: Set to 1 or 0 if the currency_symbol respectively precedes or succeeds the value for a negative formatted monetary quantity.

int n_sep_by_space: Set to 1 or 0 if the currency_symbol respectively is or is not separated by a space from the value for a negative formatted monetary quantity.

int p_sign_posn: Set to a value indicating the positioning of the positive_sign for a non-negative formatted monetary quantity. The value of p_sign_posn is interpreted according to the following:

0 - Parentheses surround the quantity and currency_symbol.

1 - The sign string precedes the quantity and currency_symbol.

2 - The sign string succeeds the quantity and currency_symbol.

3 - The sign string immediately precedes the currency_symbol.

4 - The sign string immediately succeeds the currency_symbol.

int n_sign_posn: Set to a value indicating the positioning of the negative_sign for a negative formatted monetary quantity. The value of n_sign_posn is interpreted according to the rules described under p_sign_posn.

SEE ALSO
bindtextdomain, textdomain, gettext, dgettext, dcgettext and setlocale

METHOD
Locale.Gettext.setlocale

SYNTAX
int setlocale(int category,  string locale)

DESCRIPTION
The setlocale() function is used to set the program's current locale. If locale is "C" or "POSIX", the current locale is set to the portable locale.

If locale is "", the locale is set to the default locale which is selected from the environment variable LANG.

The argument category determines which functions are influenced by the new locale: Locale.Gettext.LC_ALL for all of the locale.

Locale.Gettext.LC_COLLATE for the functions strcoll() and strxfrm() (used by pike, but not directly accessible).

Locale.Gettext.LC_CTYPE for the character classification and conversion routines.

Locale.Gettext.LC_MONETARY for localeconv(). Locale.Gettext.LC_NUMERIC for the decimal character. Locale.Gettext.LC_TIME for strftime() (currently not accessible from Pike).

ARGUMENTS
argument(s)description
int category
The category in which to set the locale.
string locale
The locale to change to

RETURNS
1 if the locale setting successed, 0 for failure

SEE ALSO
bindtextdomain, textdomain, gettext, dgettext, dcgettext and localeconv

METHOD
Locale.Gettext.textdomain

SYNTAX
string textdomain(string domain|void)
string textdomain(void)

DESCRIPTION
The textdomain() function sets or queries the name of the current domain of the active LC_MESSAGES locale category. The domainname argument is a string that can contain only the characters allowed in legal filenames.

The domainname argument is the unique name of a domain on the system. If there are multiple versions of the same domain on one system, namespace collisions can be avoided by using bindtextdomain(). If textdomain() is not called, a default domain is selected. The setting of domain made by the last valid call to textdomain() remains valid across subsequent calls to setlocale, and gettext(). The normal return value from textdomain() is a string containing the current setting of the domain. If domainname is void, textdomain() returns a string containing the current domain. If textdomain() was not previously called and domainname is void, the name of the default domain is returned.

ARGUMENTS
argument(s)description
string domainname
The name of the domain to be made the current domain.

SEE ALSO
bindtextdomain, gettext, dgettext, dcgettext, setlocale and localeconv

14.16 Calendar

DESCRIPTION
This module implements calendar calculations, and base classes for time units.

14.16.1 Calendar.time_unit

CLASS
Calendar.time_unit

DESCRIPTION

METHOD
Calendar.time_unit.greater

SYNTAX
array(string) greater()

DESCRIPTION
Gives a list of methods to get greater (longer) time units from this object. For a month, this gives back ({"year"}), thus the method month->year() gives the year object.

METHOD
Calendar.time_unit.lesser

SYNTAX
array(string) lesser()

DESCRIPTION
Gives a list of methods to get lesser (shorter) time units. ie, for a month, this gives back ({"day"}) and the method day(mixed n) gives back that day object. The method days() gives back a list of possible argument values to the method day. Concurrently, Array.map(o->days(),o->day) gives a list of day objects in the object o.

Ie:

array(string) lesser()    - gives back a list of possible xxx's.
object xxxs()             - gives back a list of possible n's.
object xxx(mixed n)       - gives back xxx n
object xxx(object(Xxx) o) - gives back the corresponing xxx

The list of n's (as returned from xxxs) are always in order.

There are two n's with special meaning, 0 and -1. 0 always gives the first xxx, equal to my_obj->xxx(my_obj->xxxs()[0]), and -1 gives the last, equal to my_obj->xxx(my_obj->xxxs()[-1]).

To get all xxxs in the object, do something like Array.map(my_obj->xxxs(),my_obj->xxx).

xxx(object) may return zero, if there was no correspondning xxx.

METHOD
Calendar.time_unit.`+,
Calendar.time_unit.`-,
Calendar.time_unit.next,
Calendar.time_unit.prev

SYNTAX
object next()
object prev()
object `+(int n)
object `-(int n)
object `-(object x)

DESCRIPTION
next and prev gives the logical next and previous object. The + operator gives that logical relative object, ie my_day+14 gives 14 days ahead. - works the same way, but can also take an object of the same type and give the difference as an integer.

14.16.2 Calendar.Gregorian

DESCRIPTION
time units: Year, Month, Week, Day

14.16.2.1 Calendar.Gregorian.

CLASS
Calendar.Gregorian.

14.16.2.2 Calendar.Gregorian.Year

CLASS
Calendar.Gregorian.Year

DESCRIPTION
A Calendar.time_unit.

Lesser units: Month, Week, Day Greater units: none

METHOD
Calendar.Gregorian.Year.parse

SYNTAX
object parse(string fmt, string arg)

DESCRIPTION
parse a date, create relevant object fmt is in the format "abc%xdef..." where abc and def is matched, and %x is one of those time units: %Y absolute year %y year (70-99 is 1970-1999, 0-69 is 2000-2069) %M month (number, name or short name) (needs %y) %W week (needs %y) %D date (needs %y, %m) %a day (needs %y) %e weekday (needs %y, %w) %h hour (needs %d, %D or %W) %m minute (needs %h) %s second (needs %s)

function datetime(int|void unix_time) Replacement for localtime.

function datetime_name(int|void unix_time) Replacement for ctime.

function datetime_short_name(int|void unix_time) Replacement for ctime.

14.16.2.3 Calendar.Gregorian.Stardate

DESCRIPTION
time unit: TNGDate
14.16.2.3.1 Calendar.Gregorian.Stardate.TNGDate

CLASS
Calendar.Gregorian.Stardate.TNGDate

DESCRIPTION
implements ST:TNG stardates can be used as create argument to Day

14.17 Parser

14.18 Math

14.18.1 Math.Matrix

CLASS
Math.Matrix

DESCRIPTION
This class hold Matrix capabilites, and support a range of matrix operations.

It can only - for speed and simplicity - hold floating point numbers and are only in 2 dimensions.

METHOD
Math.Matrix.`+,
Math.Matrix.``+,
Math.Matrix.add

SYNTAX
object `+(object with)
object ``+(object with)
object add(object with)

DESCRIPTION
Add this matrix to another matrix. A new matrix is returned. The matrices must have the same size.

METHOD
Math.Matrix.cast

SYNTAX
array(array(float)) cast(string to_what)
array(array(float)) cast(string to_what)

DESCRIPTION
This is to be able to get the matrix values. (array) gives back a double array of floats. m->vect() gives back an array of floats.

METHOD
Math.Matrix.cast

SYNTAX
array(array(float)) cast(string to_what)

DESCRIPTION
This is to be able to get the matrix values. This gives back a double array of floats.

METHOD
Math.Matrix.create

SYNTAX
void create(array(array(int|float)))
void create(array(int|float))
void create(int n, int m)
void create(int n, int m, string type)
void create(int n, int m, float|int init)
void create("identity", int size)
void create("rotate", int size, float rads, Matrix axis)
void create("rotate", int size, float rads, float x, float y, float z)

DESCRIPTION
This method initializes the matrix. It is illegal to create and hold an empty matrix.

The normal operation is to create the matrix object with a double array, like Math.Matrix( ({({1,2}),({3,4})}) ).

Another use is to create a special type of matrix, and this is told as third argument.

Currently there are only the "identity" type, which gives a matrix of zeroes except in the diagonal, where the number one (1.0) is. This is the default, too.

The third use is to give all indices in the matrix the same value, for instance zero or 42.

The forth use is some special matrixes. First the square identity matrix again, then the rotation matrix.

METHOD
Math.Matrix.cross,
Math.Matrix.``,
Math.Matrix.`

SYNTAX
object `(object with)
object ``(object with)
object cross(object with)

DESCRIPTION
Matrix cross-multiplication.

METHOD
Math.Matrix.`*,
Math.Matrix.``*,
Math.Matrix.mult

SYNTAX
object `*(object with)
object ``*(object with)
object mult(object with)

DESCRIPTION
Matrix multiplication.

METHOD
Math.Matrix.norm2,
Math.Matrix.norm,
Math.Matrix.normv

SYNTAX
float norm()
float norm2()
object normv()

DESCRIPTION
Norm of the matrix, and the square of the norm of the matrix. (The later method is because you may skip a square root sometimes.)

This equals |A| or sqrt( A02 + A12 + ... + An2 ).

It is only usable with 1xn or nx1 matrices.

m->normv() is equal to m*(1.0/m->norm()), with the exception that the zero vector will still be the zero vector (no error).

METHOD
Math.Matrix.`-,
Math.Matrix.``-,
Math.Matrix.sub

SYNTAX
object `-()
object `-(object with)
object ``-(object with)
object sub(object with)

DESCRIPTION
Subtracts this matrix from another. A new matrix is returned. -m is equal to -1*m.

METHOD
Math.Matrix.transpose

SYNTAX
object transpose()

DESCRIPTION
Transpose of the matrix as a new object.

DESCRIPTION
This module implements calendar calculations, and base classes for time units.

14.19 Calendar.time_unit

CLASS
Calendar.time_unit

DESCRIPTION

METHOD
Calendar.time_unit.greater

SYNTAX
array(string) greater()

DESCRIPTION
Gives a list of methods to get greater (longer) time units from this object. For a month, this gives back ({"year"}), thus the method month->year() gives the year object.

METHOD
Calendar.time_unit.lesser

SYNTAX
array(string) lesser()

DESCRIPTION
Gives a list of methods to get lesser (shorter) time units. ie, for a month, this gives back ({"day"}) and the method day(mixed n) gives back that day object. The method days() gives back a list of possible argument values to the method day. Concurrently, Array.map(o->days(),o->day) gives a list of day objects in the object o.

Ie:

array(string) lesser()    - gives back a list of possible xxx's.
object xxxs()             - gives back a list of possible n's.
object xxx(mixed n)       - gives back xxx n
object xxx(object(Xxx) o) - gives back the corresponing xxx

The list of n's (as returned from xxxs) are always in order.

There are two n's with special meaning, 0 and -1. 0 always gives the first xxx, equal to my_obj->xxx(my_obj->xxxs()[0]), and -1 gives the last, equal to my_obj->xxx(my_obj->xxxs()[-1]).

To get all xxxs in the object, do something like Array.map(my_obj->xxxs(),my_obj->xxx).

xxx(object) may return zero, if there was no correspondning xxx.

METHOD
Calendar.time_unit.`+,
Calendar.time_unit.`-,
Calendar.time_unit.next,
Calendar.time_unit.prev

SYNTAX
object next()
object prev()
object `+(int n)
object `-(int n)
object `-(object x)

DESCRIPTION
next and prev gives the logical next and previous object. The + operator gives that logical relative object, ie my_day+14 gives 14 days ahead. - works the same way, but can also take an object of the same type and give the difference as an integer.

14.20 Calendar.Gregorian

DESCRIPTION
time units: Year, Month, Week, Day

14.20.1 Calendar.Gregorian.

CLASS
Calendar.Gregorian.

14.20.2 Calendar.Gregorian.Year

CLASS
Calendar.Gregorian.Year

DESCRIPTION
A Calendar.time_unit.

Lesser units: Month, Week, Day Greater units: none

METHOD
Calendar.Gregorian.Year.parse

SYNTAX
object parse(string fmt, string arg)

DESCRIPTION
parse a date, create relevant object fmt is in the format "abc%xdef..." where abc and def is matched, and %x is one of those time units: %Y absolute year %y year (70-99 is 1970-1999, 0-69 is 2000-2069) %M month (number, name or short name) (needs %y) %W week (needs %y) %D date (needs %y, %m) %a day (needs %y) %e weekday (needs %y, %w) %h hour (needs %d, %D or %W) %m minute (needs %h) %s second (needs %s)

function datetime(int|void unix_time) Replacement for localtime.

function datetime_name(int|void unix_time) Replacement for ctime.

function datetime_short_name(int|void unix_time) Replacement for ctime.

14.20.3 Calendar.Gregorian.Stardate

DESCRIPTION
time unit: TNGDate

14.20.3.1 Calendar.Gregorian.Stardate.TNGDate

CLASS
Calendar.Gregorian.Stardate.TNGDate

DESCRIPTION
implements ST:TNG stardates can be used as create argument to Day

14.21 Crypto.randomness

DESCRIPTION
Assorted stronger or weaker randomnumber generators.

14.21.1 Crypto.randomness.pike_random

CLASS
Crypto.randomness.pike_random

DESCRIPTION
A pseudo random generator based on the ordinary random() function.

METHOD
Crypto.randomness.pike_random.read

SYNTAX
string read(int len)

DESCRIPTION
Returns a string of length len with pseudo random values.

14.21.2 Crypto.randomness.arcfour_random

CLASS
Crypto.randomness.arcfour_random

DESCRIPTION
A pseudo random generator based on the arcfour crypto.

METHOD
Crypto.randomness.arcfour_random.create

SYNTAX
void create(string secret)

DESCRIPTION
Initialize and seed the arcfour random generator.

METHOD
Crypto.randomness.arcfour_random.read

SYNTAX
string read(int len)

DESCRIPTION
Return a string of the next len random characters from the arcfour random generator.

14.22 Geographical.Position

CLASS
Geographical.Position

DESCRIPTION
This class contains a geographical position, ie a point on the earths surface.

variable float lat variable float long Longitude (W--E) and latitude (N--S) of the position, float value in degrees. Positive number is north and east, respectively. Negative number is south and west, respectively.

METHOD
Geographical.Position.cast

SYNTAX
array cast("array")

DESCRIPTION
It is possible to cast the position to an array, ({float lat,float long}).

METHOD
Geographical.Position.create

SYNTAX
void create(float lat, float long)
void create(string lat, string long)
void create(string both)

DESCRIPTION
Constructor for this class. If feeded with strings, it will perform a dwim scan on the strings. If they fails to be understood, there will be an exception.

METHOD
Geographical.Position.latitude,
Geographical.Position.longitude

SYNTAX
string latitude(void|int n)
string longitude(void|int n)

DESCRIPTION
Returns the nicely formatted latitude or longitude.
n    format
-    1742.19'N       4222.2'W
1    17.703N         42.37W
2    1742.18'N       4222.2'W
3    1742'10.4"N     4222'12"W
-1   17.703           -42.37

METHOD
Geographical.Position.`==,
Geographical.Position.`>,
Geographical.Position.`>`<,
Geographical.Position.`>__hash

SYNTAX
int __hash()
int `==(Position pos)
int `<>(Position pos)
int `>(Position pos)

DESCRIPTION
These exist solely for purpose of detecting equal positions, for instance when used as keys in mappings.

14.23 Geographical.Countries

DESCRIPTION
subclass Country variable string iso2 ISO 2-character code aka domain name variable string name variable array(string) aka Country name and as-known-as, if any variable int former Flag that is set if this isn't a country anymore (Like USSR.) constant array(Country) countries All known countries.

METHOD
Geographical.Countries.cast

SYNTAX
string cast("string")

DESCRIPTION
It is possible to cast a country to a string, which will be the same as performing country->name;.

METHOD
Geographical.Countries.from_domain

SYNTAX
Country from_domain(string domain)

DESCRIPTION
Look up a country from a domain name. Returns zero if the domain doesn't map to a country. Note that there are some valid domains that doesn't:
INT
International
MIL
US Military
NET
Network
ORG
Non-Profit Organization
ARPA
Old style Arpanet
NATO
Nato field

And that USA has three domains, Great Britain two:

COM
US Commercial
EDU
US Educational
GOV
US Government
GB
Great Britain (UK)
UK
United Kingdom

METHOD
Geographical.Countries.from_domain

SYNTAX
Country from_domain(string name)

DESCRIPTION
Look up a country from its name or aka. The search is case-insensitive but regards whitespace and interpunctation.

METHOD
Geographical.Countries.`[],
Geographical.Countries.`.

SYNTAX
mixed `[](string what)
mixed `->(string what)

DESCRIPTION
Convenience function for getting a country the name-space way; it looks up whatever it is in the name- and domain-space and

> Geographical.Countries.se;
Result: Country(Sweden)
> Geographical.Countries.djibouti;
Result: Country(Djibouti)
> Geographical.Countries.com;
Result: Country(United States)
> Geographical.Countries.wallis_and_futuna_islands->iso2;
Result: "WF"

RETURNS
that country if possible:

DESCRIPTION
$Id: module.pmod,v 1.8 2000/03/22 18:12:19 peter Exp $

METHOD
Image.load_layer,
Image._load,
Image.load

SYNTAX
object(Image.Image) load()
object(Image.Image) load(object file)
object(Image.Image) load(string filename)
object(Image.Layer) load_layer()
object(Image.Layer) load_layer(object file)
object(Image.Layer) load_layer(string filename)
mapping _load()
mapping _load(object file)
mapping _load(string filename)

DESCRIPTION
Helper function to load an image from a file. If no filename is given, Stdio.stdin is used. The result is the same as from the decode functions in Image.ANY.

NOTE
All data is read, ie nothing happens until the file is closed. Throws upon error.

14.24 Parser.SGML

CLASS
Parser.SGML

DESCRIPTION
This is a handy simple parser of SGML-like syntax like HTML. It doesn't do anything advanced, but finding the corresponding end-tags.

It's used like this:

array res=Parser.SGML()->feed(string)->finish()->result();

The resulting structure is an array of atoms, where the atom can be a string or a tag. A tag contains a similar array, as data.

Example: A string "<gat>&nbsp;<gurka>&nbsp;</gurka>&nbsp;<banan>&nbsp;<kiwi>&nbsp;</gat>" results in

({
tag "gat" object with data:
({
tag "gurka" object with data:
({
" "
})
tag "banan" object with data:
({
" "
tag "kiwi" object with data:
({
" "
})
})
})
})

ie, simple "tags" (not containers) are not detected, but containers are ended implicitely by a surrounding container _with_ an end tag.

The 'tag' is an object with the following variables:

string name;           - name of tag
mapping args;          - argument to tag
int line,char,column;  - position of tag
string file;           - filename (see create)
array(SGMLatom) data;  - contained data

METHOD
Parser.SGML.create

SYNTAX
void create()
void create(string filename)

DESCRIPTION
This object is created with this filename. It's passed to all created tags, for debug and trace purposes.

NOTE
No, it doesn't read the file itself. See feed.

METHOD
Parser.SGML.result,
Parser.SGML.finish,
Parser.SGML.feed

SYNTAX
object feed(string s)
array finish()
array result(string s)

DESCRIPTION
Feed new data to the object, or finish the stream. No result can be used until finish() is called.

Both finish() and result() returns the computed data.

feed() returns the called object.

14.25 Protocols.HTTP

METHOD
Protocols.HTTP.delete_url

SYNTAX
object(Protocols.HTTP.Query) delete_url(string url)
object(Protocols.HTTP.Query) delete_url(string url, mapping query_variables)
object(Protocols.HTTP.Query) delete_url(string url, mapping query_variables,  mapping request_headers)

DESCRIPTION
Sends a HTTP DELETE request to the server in the URL and returns the created and initialized Query object. 0 is returned upon failure.

METHOD
Protocols.HTTP.get_url

SYNTAX
object(Protocols.HTTP.Query) get_url(string url)
object(Protocols.HTTP.Query) get_url(string url, mapping query_variables)
object(Protocols.HTTP.Query) get_url(string url, mapping query_variables,  mapping request_headers)

DESCRIPTION
Sends a HTTP GET request to the server in the URL and returns the created and initialized Query object. 0 is returned upon failure.

METHOD
Protocols.HTTP.get_url_nice,
Protocols.HTTP.get_url_data

SYNTAX
array(string) get_url_nice(string url)
array(string) get_url_nice(string url, mapping query_variables)
array(string) get_url_nice(string url, mapping query_variables,  mapping request_headers)
string get_url_data(string url)
string get_url_data(string url, mapping query_variables)
string get_url_data(string url, mapping query_variables,  mapping request_headers)

DESCRIPTION
Returns an array of ({content_type,data}) and just the data string respective, after calling the requested server for the information. 0 is returned upon failure.

METHOD
Protocols.HTTP.http_encode_query

SYNTAX
string http_encode_query(mapping variables)

DESCRIPTION
Encodes a query mapping to a string; this protects odd - in http perspective - characters like '&' and '#' and control characters, and packs the result together in a HTTP query string.

Example:

> Protocols.HTTP.http_encode_query( (["anna":"eva","lilith":"blue"]) );
Result: "lilith=blue&anna=eva"
> Protocols.HTTP.http_encode_query( (["&amp;":"&","'=\"":"\0\0\0"]) );
Result: "%26amp%3b=%26&%27%3d%22=%00%00%00"

METHOD
Protocols.HTTP.http_encode_string

SYNTAX
string http_encode_string(string in)

DESCRIPTION
This protects all odd - see http_encode_query - characters for transfer in HTTP.

Do not use this function to protect URLs, since it will protect URL characters like '/' and '?'.

METHOD
Protocols.HTTP.post_url_data,
Protocols.HTTP.post_url,
Protocols.HTTP.post_url_nice

SYNTAX
array(string) post_url_nice(string url, mapping query_variables)
array(string) post_url_nice(string url, mapping query_variables,  mapping request_headers)
string post_url_data(string url, mapping query_variables)
string post_url_data(string url, mapping query_variables,  mapping request_headers)
object(Protocols.HTTP.Query) post_url(string url, mapping query_variables)
object(Protocols.HTTP.Query) post_url(string url, mapping query_variables,  mapping request_headers)

DESCRIPTION
Similar to the get_url class of functions, except that the query variables is sent as a post request instead of a get.

METHOD
Protocols.HTTP.put_url

SYNTAX
object(Protocols.HTTP.Query) put_url(string url)
object(Protocols.HTTP.Query) put_url(string url, string file)
object(Protocols.HTTP.Query) put_url(string url, string file, mapping query_variables)
object(Protocols.HTTP.Query) put_url(string url, string file, mapping query_variables,  mapping request_headers)

DESCRIPTION
Sends a HTTP PUT request to the server in the URL and returns the created and initialized Query object. 0 is returned upon failure.

METHOD
Protocols.HTTP.unentity

SYNTAX
string unentity(string s)

DESCRIPTION
Helper function for replacing HTML entities with the corresponding iso-8859-1 characters.

NOTE
All characters isn't replaced, only those with corresponding iso-8859-1 characters.

14.25.1 Protocols.HTTP.Query

CLASS
Protocols.HTTP.Query

DESCRIPTION
Open and execute a HTTP query.

METHOD
Protocols.HTTP.Query.set_callbacks,
Protocols.HTTP.Query.async_request

SYNTAX
object set_callbacks(function request_ok, function request_fail, mixed ...extra)
object async_request(string server, int port, string query);
object async_request(string server, int port, string query, mapping headers, void|string data);

DESCRIPTION
Setup and run an asynchronous request, otherwise similar to thread_request.

request_ok(object httpquery,...extra args) will be called when connection is complete, and headers are parsed.

request_fail(object httpquery,...extra args) is called if the connection fails.

variable int ok Tells if the connection is successfull. variable int errno Errno copied from the connection.

variable mapping headers Headers as a mapping. All header names are in lower case, for convinience.

variable string protocol Protocol string, ie "HTTP/1.0".

variable int status variable string status_desc Status number and description (ie, 200 and "ok").

variable mapping hostname_cache Set this to a global mapping if you want to use a cache, prior of calling *request().

variable mapping async_dns Set this to an array of Protocols.DNS.async_clients, if you wish to limit the number of outstanding DNS requests. Example: async_dns=allocate(20,Protocols.DNS.async_client)();

RETURNS
the called object

METHOD
Protocols.HTTP.Query.cast

SYNTAX
array cast("array")

DESCRIPTION
Gives back ({mapping headers,string data, string protocol,int status,string status_desc});

METHOD
Protocols.HTTP.Query.cast

SYNTAX
mapping cast("mapping")

DESCRIPTION
Gives back headers | (["protocol":protocol, "status":status number, "status_desc":status description, "data":data]);

METHOD
Protocols.HTTP.Query.cast

SYNTAX
string cast("string")

DESCRIPTION
Gives back the answer as a string.

METHOD
Protocols.HTTP.Query.data

SYNTAX
string data()

DESCRIPTION
Gives back the data as a string.

METHOD
Protocols.HTTP.Query.downloaded_bytes

SYNTAX
int downloaded_bytes()

DESCRIPTION
Gives back the number of downloaded bytes.

METHOD
Protocols.HTTP.Query.thread_request

SYNTAX
object thread_request(string server, int port, string query);
object thread_request(string server, int port, string query, mapping headers, void|string data);

DESCRIPTION
Create a new query object and begin the query.

The query is executed in a background thread; call '() in this object to wait for the request to complete.

'query' is the first line sent to the HTTP server; for instance "GET /index.html HTTP/1.1".

headers will be encoded and sent after the first line, and data will be sent after the headers.

RETURNS
the called object

METHOD
Protocols.HTTP.Query.total_bytes

SYNTAX
int total_bytes()

DESCRIPTION
Gives back the size of a file if a content-length header is present and parsed at the time of evaluation. Otherwise returns -1.

object(pseudofile) file() object(pseudofile) file(mapping newheaders,void|mapping removeheaders) object(pseudofile) datafile(); Gives back a pseudo-file object, with the method read() and close(). This could be used to copy the file to disc at a proper tempo.

datafile() doesn't give the complete request, just the data.

newheaders, removeheaders is applied as: (oldheaders|newheaders))-removeheaders Make sure all new and remove-header indices are lower case.

void async_fetch(function done_callback); Fetch all data in background.

METHOD
Protocols.HTTP.Query.`

SYNTAX
int `()()

DESCRIPTION
Wait for connection to complete.

RETURNS
1 on successfull connection, 0 if failed

14.26 Protocols.LysKOM

14.26.1 Protocols.LysKOM.Session

CLASS
Protocols.LysKOM.Session

DESCRIPTION
variable user This variable contains the person that are logged in.

METHOD
Protocols.LysKOM.Session.create

SYNTAX
void create(string server)
void create(string server, mapping options)

DESCRIPTION
Initializes the session object, and opens a connection to that server.

options is a mapping of options,

([
   "login" : int|string    login as this person number
                         (get number from name)
   "create" : string       
                         create a new person and login with it
   "password" : string     send this login password
   "invisible" : int(0..1) if set, login invisible
   advanced
   "port" : int(0..65535)  server port (default is 4894)
   "whoami" : string       present as this user
                         (default is from uid/getpwent and hostname)
])

SEE ALSO
Connection

METHOD
Protocols.LysKOM.Session.create_person

SYNTAX
object create_person(string name, string password)

DESCRIPTION
Create a person, which will be logged in.

RETURNS
the new person object

METHOD
Protocols.LysKOM.Session.create_text

SYNTAX
object create_text(string subject, string body, mapping options)
object create_text(string subject, string body, mapping options, function callback, mixed ...extra)

DESCRIPTION
Creates a new text.

if "callback" are given, this function will be called when the text is created, with the text as first argument. Otherwise, the new text is returned.

options is a mapping that may contain:

([
   "recpt" : Conference|array(Conference) 
        recipient conferences
   "cc" : Conference|array(Conference)    
        cc-recipient conferences
   "bcc" : Conference|array(Conference)   
        bcc-recipient conferences *
   
   "comm_to" : Text|array(Text)           
        what text(s) is commented
   "foot_to" : Text|array(Text)           
        what text(s) is footnoted
   
   "anonymous" : int(0..1)                
        send text anonymously
])

NOTE
The above marked with a '*' is only available on a protocol 10 server. A LysKOM error will be thrown if the call fails.

SEE ALSO
Conference.create_text, Text.comment and Text.footnote

METHOD
Protocols.LysKOM.Session.login

SYNTAX
object login(int user_no, string password)
object login(int user_no, string password, int invisible)

DESCRIPTION
Performs a login. Returns 1 on success or throws a lyskom error.

RETURNS
the called object

METHOD
Protocols.LysKOM.Session.logout

SYNTAX
object logout()

DESCRIPTION
Logouts from the server.

RETURNS
the called object

METHOD
Protocols.LysKOM.Session.send_message

SYNTAX
object send_message(string message,  mapping options)

DESCRIPTION
Sends a message.

options is a mapping that may contain:

([
   "recpt" : Conference recipient conference
])

METHOD
Protocols.LysKOM.Session.try_complete_person

SYNTAX
array(object) try_complete_person(string orig)

DESCRIPTION
Runs a LysKOM completion on the given string, returning an array of confzinfos of the match.

14.26.2 Protocols.LysKOM.Connection

CLASS
Protocols.LysKOM.Connection

DESCRIPTION
This class contains nice abstraction for calls into the server. They are named "call", "async_call" or "async_cb_call", depending on how you want the call to be done.

METHOD
Protocols.LysKOM.Connection./call/,
Protocols.LysKOM.Connection.async_/call/,
Protocols.LysKOM.Connection.async_cb_/call/

SYNTAX
mixed /call/(mixed ...args)
object async_/call/(mixed ...args)
object async_cb_/call/(function callback, mixed ...args)

DESCRIPTION
Do a call to the server. This really clones a request object, and initialises it. /call/ is to be read as one of the calls in the lyskom protocol. ('-' is replaced with '_'.) (ie, logout, async_login or async_cb_get_conf_stat.)

The first method is a synchronous call. This will send the command, wait for the server to execute it, and then return the result.

The last two is asynchronous calls, returning the initialised request object.

variable int protocol_level variable string session_software variable string software_version Description of the connected server.

METHOD
Protocols.LysKOM.Connection.create

SYNTAX
void create(string server)
void create(string server, mapping options)

DESCRIPTION
([
   "login" : int|string    login as this person number
                         (get number from name)
   "password" : string     send this login password
   "invisible" : int(0..1) if set, login invisible
   advanced
   "port" : int(0..65535)  server port (default is 4894)
   "whoami" : string       present as this user
                         (default is from uid/getpwent and hostname)
])

14.26.3 Protocols.LysKOM.Request

DESCRIPTION
This class contains nice abstraction for calls into the server. They are named "call", "async_call" or "async_cb_call", depending on how you want the call to be done.

14.26.3.1 Protocols.LysKOM.Request._Request

CLASS
Protocols.LysKOM.Request._Request

DESCRIPTION
This is the main request class. All lyskom request classes inherits this class.

METHOD
Protocols.LysKOM.Request._Request.sync,
Protocols.LysKOM.Request._Request.async

SYNTAX
void async(mixed ...args)
mixed sync(mixed ...args)

DESCRIPTION
initialise an asynchronous or a synchronous call, the latter is also evaluating the result. This calls 'indata' in itself, to get the correct arguments to the lyskom protocol call.

METHOD
Protocols.LysKOM.Request._Request._reply,
Protocols.LysKOM.Request._Request.reply

SYNTAX
mixed _reply(object|array what)
mixed reply(object|array what)

DESCRIPTION
_reply is called as callback to evaluate the result, and calls reply in itself to do the real work.

METHOD
Protocols.LysKOM.Request._Request.`

SYNTAX
mixed `()()

DESCRIPTION
wait for the call to finish.

variable int ok tells if the call is executed ok variable object error how the call failed The call is completed if (ok||error).

METHOD
Protocols.LysKOM.Request._Request._async,
Protocols.LysKOM.Request._Request._sync

SYNTAX
void _async(int call,  mixed_data)
mixed _sync(int call,  mixed_data)

DESCRIPTION
initialise an asynchronous or a synchronous call, the latter is also evaluating the result. These are called by async and sync respectively.

14.27 Protocols.DNS

DESCRIPTION

14.27.1 Protocols.DNS.client

CLASS
Protocols.DNS.client

DESCRIPTION
Synchronous DNS client.

METHOD
Protocols.DNS.client.create

SYNTAX
void create()
void create(void|string|array server,  void|int|array domain)

DESCRIPTION

METHOD
Protocols.DNS.client.gethostbyname,
Protocols.DNS.client.gethostbyaddr

SYNTAX
array gethostbyname(string hostname)
array gethostbyaddr(string hostip)

DESCRIPTION
Querys the host name or ip from the default or given DNS server. The result is a mapping with three elements,
({
   string hostname  [0] hostname
   array(string) ip [1] ip number(s)
   array(string) ip [2] dns name(s)
})

METHOD
Protocols.DNS.client.get_primary_mx

SYNTAX
string get_primary_mx(string hostname)

DESCRIPTION
Querys the primary mx for the host.

RETURNS
the hostname of the primary mail exchanger

Previous chapter To contents Next chapter