Chapter 14, Other modules

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

FUNCTION: getppid - get the parent process ID
SYNTAX: int getppid();
DESCRIPTION: Returns the process ID of the parent process.
SEE ALSO

FUNCTION: getuid - get the user ID
SYNTAX: int getuid();
DESCRIPTION: Get the real user ID.
SEE ALSO

FUNCTION: hardlink - create a hardlink
SYNTAX: void hardlink(string from, string to);
DESCRIPTION: Creates a hardlink named to from the file from.
SEE ALSO

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

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

FUNCTION: setegid - set the effective group ID
SYNTAX: void setegid(int uid);
DESCRIPTION: Sets the effective group ID to gid.
SEE ALSO

FUNCTION: seteuid - set the effective user ID
SYNTAX: void seteuid(int uid);
DESCRIPTION: Sets the effective user ID to uid.
SEE ALSO

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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:

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.

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.

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

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

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

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

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:

The db object is the main database object. It can create table objects. The methods available in the db object are: table (the [] operator), list_tables (indices), sync and purge.
The table object handles tables. It is used in order to store and fetch records from the database. It can create transaction objects. The methods available in the table object are: set (the []= operator), get (the [] operator), list_keys (indices), delete, transaction and purge.
The transaction object handles transactions. It works like the table object. The difference is that a sequence of commands must end with commit or rollback. The methods available in the table object are: set (the []= operator), get (the [] operator), list_keys (indices), delete, commit and rollback.

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:

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).
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");

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

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

METHOD: Yabu.db._values - Get all tables
SYNTAX: array(Yabu.table) _values();
DESCRIPTION: This method returns all available tables.
SEE ALSO

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

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

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

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

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

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

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

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

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.

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

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

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

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

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

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

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

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:

type	subtype
text	plain
message	rfc822
multipart	mixed

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

14.14.6 Combining block cryptos

14.15 Locale.Gettext

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

14.16 Calendar

DESCRIPTION

14.17 Parser

14.18 Math

14.18.1 Math.Matrix

CLASS: Math.Matrix
DESCRIPTION

DESCRIPTION

14.21 Crypto.randomness

DESCRIPTION

14.22 Geographical.Position

CLASS: Geographical.Position
DESCRIPTION

14.23 Geographical.Countries

DESCRIPTION

DESCRIPTION

14.24 Parser.SGML

CLASS: Parser.SGML
DESCRIPTION

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

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

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

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

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

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

14.26 Protocols.LysKOM

14.26.1 Protocols.LysKOM.Session

CLASS: Protocols.LysKOM.Session
DESCRIPTION

14.26.2 Protocols.LysKOM.Connection

CLASS: Protocols.LysKOM.Connection
DESCRIPTION

14.26.3 Protocols.LysKOM.Request

DESCRIPTION

14.27 Protocols.DNS

DESCRIPTION

Previous chapter

To contents

Next chapter

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).

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

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

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

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.

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

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

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.

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.

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.

Chapter 14, Other modules

14.1 System

14.2 Process

14.3 Regexp

14.4 Gmp

14.5 Gdbm

14.6 Getopt

14.7 Gz

14.8 Yp

14.9 ADT.Table

14.10 Yabu transaction database

14.10.1 The database

14.10.2 Tables

14.10.3 Transactions

14.11 MIME

14.11.1 Global functions

14.11.2 The MIME.Message class

14.11.2.1 Public fields

14.11.2.2 Public methods

14.12 Simulate

14.13 Mysql.mysql

14.14 The Pike Crypto Toolkit

14.14.1 Introduction

14.14.2 Block ciphers

14.14.3 Stream Ciphers

14.14.4 Hash Functions

14.14.5 Public key algorithms

14.14.6 Combining block cryptos

14.15 Locale.Gettext

14.16 Calendar

14.16.1 Calendar.time_unit

14.16.2 Calendar.Gregorian

14.16.2.1 Calendar.Gregorian.

14.16.2.2 Calendar.Gregorian.Year

14.16.2.3 Calendar.Gregorian.Stardate

14.16.2.3.1 Calendar.Gregorian.Stardate.TNGDate

14.17 Parser

14.18 Math

14.18.1 Math.Matrix

14.19 Calendar.time_unit

14.20 Calendar.Gregorian

14.20.1 Calendar.Gregorian.

14.20.2 Calendar.Gregorian.Year

14.20.3 Calendar.Gregorian.Stardate

14.20.3.1 Calendar.Gregorian.Stardate.TNGDate

14.21 Crypto.randomness

14.21.1 Crypto.randomness.pike_random

14.21.2 Crypto.randomness.arcfour_random

14.22 Geographical.Position

14.23 Geographical.Countries

14.24 Parser.SGML

14.25 Protocols.HTTP

14.25.1 Protocols.HTTP.Query

14.26 Protocols.LysKOM

14.26.1 Protocols.LysKOM.Session

14.26.2 Protocols.LysKOM.Connection

14.26.3 Protocols.LysKOM.Request

14.26.3.1 Protocols.LysKOM.Request._Request

14.27 Protocols.DNS

14.27.1 Protocols.DNS.client