This object is used to represent a BNF-rule in the LR parser.

Non-terminal this rule reduces to.

The actual rule

Action to do when reducing this rule. function - call this function. string - call this function by name in the object given to the parser. The function is called with arguments corresponding to the values of the elements of the rule. The return value of the function will be the value of this non-terminal. The default rule is to return the first argument.

``

This rule contains tokens

This rule has this many non-nullable symbols at the moment.

Sequence number of this rule (used for conflict resolving) Also used to identify the rule.

Priority and associativity of this rule.

Create a BNF rule.

The rule

rule : nonterminal ":" symbols ";" { add_rule };

might be created as

rule(4, ({ 9, ";", 5, ";" }), "add_rule");

where 4 corresponds to the nonterminal "rule", 9 to "nonterminal" and 5 to "symbols", and the function "add_rule" is too be called when this rule is reduced.

Non-terminal to reduce to.

Symbol sequence that reduces to nt.

Action to do when reducing according to this rule. function - Call this function. string - Call this function by name in the object given to the parser. The function is called with arguments corresponding to the values of the elements of the rule. The return value of the function will become the value of this non-terminal. The default rule is to return the first argument.

``

An LR(0) item, a partially parsed rule.

LR

The rule

rule

How long into the rule the parsing has come.

The state we will get if we shift according to this rule

Item representing this one (used for shifts).

Look-ahead set for this item.

Look-ahead set used for detecting conflicts

Relation to other items (used when compiling).

Depth counter (used when compiling).

Item identification number (used when compiling).

Used to identify the item. Equal to r->number + offset.

Specifies the priority and associativity of a rule.

Priority value

Associativity

-1

Left

0

None

1

Right

Create a new priority object.

Priority.

Associativity.

This module generates an LR parser from a grammar specified according to the following grammar:

            directives : directive ;
    	   directives : directives directive ;
    	   directive : declaration ;
    	   directive : rule ;
    	   declaration : "%token" terminals ";" ;
    	   rule : nonterminal ":" symbols ";" ;
    	   rule : nonterminal ":" symbols action ";" ;
    	   symbols : symbol ;
    	   symbols : symbols symbol ;
    	   terminals : terminal ;
    	   terminals : terminals terminal ;
    	   symbol : nonterminal ;
    	   symbol : "string" ;
    	   action : "{" "identifier" "}" ;
    	   nonterminal : "identifier" ;
    	   terminal : "string";

LR

Error code from the parsing.

Compiles the parser-specification given in the first argument. Named actions are taken from the object if available, otherwise left as is.

Returns error-code in both Grammar_parser.error and return_value->error.

parser

Compiles the file specified in the first argument into an LR parser.

make_parser

parser

This object implements an LALR(1) parser and compiler.

Normal use of this object would be:

     {add_rule, set_priority, set_associativity}*
     set_symbol_to_string
     compile
     {parse}*

Implements an LR(1) state

Used to check if a rule already has been added when doing closures.

rule

Contains the items in this state.

item

Used to lookup items given rule and offset

item

Contains the items whose next symbol is this non-terminal.

item

The action table for this state

     object(kernel)    SHIFT to this state on this symbol.
     object(rule)      REDUCE according to this rule on this symbol.

kernel rule

The symbols that closure has been called on.

Add an item to the state.

item

Make the closure of this state.

Nonterminal to make the closure on.

Make the goto-set of this state.

Generates the state reached when doing goto on the specified symbol. i.e. it compiles the LR(0) state.

Symbol to make goto on.

kernel

This is a queue, which keeps the elements even after they are retrieved.

Index of the head of the queue.

Index of the tail of the queue.

The queue itself.

kernel

Pushes the state on the queue.

State to push.

kernel
kernel

Return the next state from the queue.

kernel
Array
LR

The grammar itself.

rule

The initial LR0 state.

kernel

Verbosity level

0

None

1

Some

Error code

LR0 states that are already known to the compiler.

kernel

Pretty-prints a rule to a string.

Rule to print.

rule

Pretty-prints an item to a string.

Item to pretty-print.

item

Pretty-prints a state to a string.

State to pretty-print.

kernel

Pretty-prints the current grammar to a string.

Implements casting.

Type to cast to.

Sets the priority of a terminal.

Terminal to set the priority for.

Priority; higher = prefer this terminal.

Sets the associativity of a terminal.

Terminal to set the associativity for.

Associativity; negative - left, positive - right, zero - no associativity.

Sets the symbol to string conversion function. The conversion function is used by the various *_to_string functions to make comprehensible output.

Symbol to string conversion function. If zero or not specified, use the built-in function.

``

Add a rule to the grammar.

Rule to add.

rule

Contains all states used. In the queue-part are the states that remain to be compiled.

state_queue

Compiles the grammar into a parser, so that parse() can be called.

Parse the input according to the compiled grammar. The last value reduced is returned.

The parser must have been compiled (with compile()) prior to calling this function.

Errors should be throw()n.

The scanner function. It returns the next symbol from the input. It should either return a string (terminal) or an array with a string (terminal) and a mixed (value). EOF is indicated with the empty string.

Object used to resolve those actions that have been specified as strings.

``

Pike 7.2 compatibility.

The symbols in this namespace will appear in programs that use #pike 7.2 or lower.

7.4::

Remove the last segment from path.

This implementation differs from predef::dirname() in that it will return "" for the input "/" while predef::dirname() will return "/".

predef::dirname()

High-resolution sleep (Pike 7.2 compatibility).

Sleep t seconds. This function was renamed to delay() in Pike 7.3.

This function will busy-wait if the sleep-interval is short.

delay

predef::sleep(), delay()

Get the default YP domain (Pike 7.2 compatibility). This function was removed in Pike 7.3, use Yp.default_domain() instead.

Yp.default_domain

Yp.default_domain()

Instantiate a program (Pike 7.2 compatibility).

A new instance of the class prog will be created. All global variables in the new object be initialized, and then lfun::create() will be called with args as arguments.

This function was removed in Pike 7.3, use ((program)prog)(@args) instead.

destruct(), compile_string(), compile_file(), clone()

Alternate name for the function new() (Pike 7.2 compatibility).

This function was removed in Pike 7.3, use ((program)prog)(@args) instead.

destruct(), compile_string(), compile_file(), new()

A helper class to optimize iterative string build-up for speed. Can help up performance noticably when dealing with buildup of huge strings by reducing the time needed for rehashing the string every time it grows.

String.Buffer

Get the contents of the buffer.

Append the string s to the buffer.

Clear the buffer.

This function counts the number of times the needle can be found in haystack.

Intersections between needles are not counted, ie count("....","..") is 2.

Returns the width in bits (8, 16 or 32) of the widest character in s.

This function implodes a list of words to a readable string. If the separator is omitted, the default is <tt>"and"</tt>. If the words are numbers they are converted to strings first.

`*()

Convert the first character in str to upper case, and return the new string.

lower_case(), upper_case()

Convert the first character in each word (separated by spaces) in str to upper case, and return the new string.

This function multiplies str by num. The return value is the same as appending str to an empty string num times.

This function is obsolete, since this functionality has been incorporated into `*().

`*()

Find the longest common prefix from an array of strings.

This function compares two strings using a fuzzy matching routine. The higher the resulting value, the better the strings match.

Array.diff(), Array.diff_compare_table() Array.diff_longest_sequence()

Trim leading and trailing spaces and tabs from the string s.

Trim leading and trailing white spaces characters (" \t\r\n") from the string s.

Base class for cache expiration policies.

Expire callback.

This function is called to expire parts of storage.

All Storage.Policy classes must MUST implement this method.

Cache.Storage.Base

An access-time-based expiration policy manager.

Cache.Policy.Base

Base class for cache storage managers.

All Cache.Storage managers must provide these methods.

These two functions are an iterator over the cache. There is an internal cursor, which is reset by each call to first(). Subsequent calls to next() will iterate over all the contents of the cache.

These functions are not meant to be exported to the user, but are solely for the policy managers' benefit.

0
0
0
0

Data-object creation is performed here if necessary, or in get() depending on the backend.

This allows the storage managers to have their own data class implementation.

Fetch some data from the cache synchronously.

Be careful, as with some storage managers it might block the calling thread for some time.

0 1
0
0
Cache.Data

Fetch some data from the cache asynchronously.

callback() will get as first argument key, and as second argument 0 (cache miss) or an Cache.Data object, plus any additional argument that the user may have supplied.

`00Cache.Data`

Delete the entry specified by key from the cache (if present).

If hard is 1, some backends may force a destruct() on the deleted value.

Dependants (if present) are automatically deleted.

Returns the deleted entry.

0 1

This module serves as a front-end to different kinds of caching systems. It uses two helper objects to actually store data, and to determine expiration policies. Mechanisms to allow for distributed caching systems will be added in time, or at least that is the plan.

Looks in the cache for an element with the given key and, if available, returns it. Returns 0 if the element is not available

Asynchronously look the cache up. The callback will be given as arguments the key, the value, and then any user-supplied arguments. If the timeout (in seconds) expires before any data could be retrieved, the callback is called anyways, with 0 as value.

``

Sets some value in the cache. Notice that the actual set operation might even not happen at all if the set data doesn't make sense. For instance, storing an object or a program in an SQL-based backend will not be done, and no error will be given about the operation not being performed.

Notice that while max_life will most likely be respected (objects will be garbage-collected at pre-determined intervals anyways), the preciousness . is to be seen as advisory only for the garbage collector If some data was stored with the same key, it gets returned. Also notice that max_life is relative and in seconds. dependants are not fully implemented yet. They are implemented after a request by Martin Stjerrholm, and their purpose is to have some weak form of referential integrity. Simply speaking, they are a list of keys which (if present) will be deleted when the stored entry is deleted (either forcibly or not). They must be handled by the storage manager.

Forcibly removes some key. If the 'hard' parameter is supplied and true, deleted objects will also have their lfun::destroy method called upon removal by some backends (i.e. memory)

0 1

Creates a new cache object. Required are a storage manager, and an expiration policy object.

Cache.Storage.Base
Cache.Policy.Base

Flags for use together with set_weak_flag and get_weak_flag. See set_weak_flag for details.

Virtual class for User objects, used in Creds objects.

This callback gets called when a new file is to be opened (and the Creds object has BIT_CONDITIONAL_IO set).

The type of file operation requested. Can either be "read" or "write".

The current object, i.e. the Fd object the user is trying to open.

The file name requested.

The flag string passed to open, e.g. "cwt".

The access flags requested for the file, e.g. 0666.

The function can either return a string, which means that the user is allowed to open a file, but the returned file should be opened instead, or it can return an integer. The integers are intepreted as follows.

0

The user was not allowed to open the file. ERRNO will be set to EPERM and an exception is thrown.

1

Do nothing, i.e. valid_open has initilized the current object with an open file. This can (natuarally) only be returned if a current object was given, which is not always the case.

2

The user was allowed to open the file and the open code proceeds.

3

The user was not allowed to open the file and an exception is thrown.

0
3

This callback gets called when I/O operations not performed on file objects are performed.

0
3

Pike has an optional internal security system, which can be enabled with the configure-option --with-security.

The security system is based on attaching credential objects (Pike.Security.Creds) to objects, programs, arrays, mappings or multisets.

A credential object in essence holds three values:

user -- The owner.

allow_bits -- Run-time access permissions.

data_bits -- Data access permissions.

The credentials object.

Get the default credentials.

Returns the default credentials object if it has been set. Returns 0 (zero) if it has not been set.

set_default_creds()

Creds

Set the default credentials

The current creds must have the allow bit BIT_SECURITY set.

get_default_creds()

Creds

Initialize a new credentials object.

Any of the flags BIT_SECURITY and BIT_CONDITIONAL_IO or:ed together.

Any of the flags BIT_INDEX, BIT_SET_INDEX, BIT_CALL, BIT_NOT_SETUID and BIT_DESTRUCT or:ed together.

Throws an exception if the current creds doesn't have the allow bit BIT_SECURITY set.

User

Get the user part.

Get the allow_bit bitmask.

Get the data_bits bitmask.

Set the credentials for o to this credentials object.

To perform this operation the current credentials needs to have the bit BIT_SECURITY set, or have the same user as the old credentials and not change the user by performing the operation.

``

Call with credentials.

Sets the current credentials to creds, and calls func(@args). If creds is 0 (zero), the credentials from the current object will be used.

The current creds or the current object must have the allow bit BIT_SECURITY set to allow calling with creds other than 0 (zero).

Creds

Get the current credentials

Returns the credentials that are currently active. Returns 0 (zero) if no credentials are active.

call_with_creds()

Creds

Get the credentials from o.

Returns 0 if o does not have any credentials.

``
Creds

Allow indexing.

Allow setting of indices.

Allow calling of functions.

Allow usage of security related functions.

Don't change active credentials on function call.

Allow conditional useage of I/O. The callbacks valid_open and valid_io will be called in the User object in the current Creds object to determine if the I/O is allowed or not.

Allow use of destruct.

Make a delayed call to a function.

call_out() places a call to the function f with the argument args in a queue to be called in about delay seconds.

If f returns -1, no other call out or callback will be called by the backend in this round. I.e. `() will return right away. For the main backend that means it will immediately start another round and check files and call outs anew.

Returns a call_out identifier that identifies this call_out. This value can be sent to eg find_call_out() or remove_call_out().

remove_call_out(), find_call_out(), call_out_info()

``

Do all pending call_outs.

This function runs all pending call_outs that should have been run if Pike returned to the backend. It should not be used in normal operation.

As a side-effect, this function sets the value returned by time(1) to the current time.

Zero if no call outs were called, nonzero otherwise.

call_out(), find_call_out(), remove_call_out()

Find a call out in the queue.

This function searches the call out queue. If given a function as argument, it looks for the first call out scheduled to that function.

The argument can also be a call out id as returned by call_out(), in which case that call_out will be found (Unless it has already been called).

find_call_out() returns the remaining time in seconds before that call_out will be executed. If no call_out is found, zero_type(find_call_out(f)) will return 1.

call_out(), remove_call_out(), call_out_info()

``

Remove a call out from the call out queue.

This function finds the first call to the function f in the call_out queue and removes it. You can also give a call out id as argument (as returned by call_out).

The remaining time in seconds left to that call out will be returned. If no call_out was found, zero_type(remove_call_out(f)) will return 1.

call_out_info(), call_out(), find_call_out()

``
``

Get info about all call_outs.

This function returns an array with one entry for each entry in the call out queue. The first in the queue will be at index 0. Each index contains an array that looks like this:

time_left

Time remaining in seconds until the call_out is to be performed.

caller

The object that scheduled the call_out.

`` fun

Function to be called.

args

Arguments to the function.

call_out(), find_call_out(), remove_call_out()

Perform one pass through the backend.

Wait at most sleep_time seconds. The default when unspecified or the integer 0 is no time limit.

If the backend did call any callbacks or call outs then the time spent in the backend is returned as a float. Otherwise the integer 0 is returned.

0 0
0
0

Return the thread currently executing in the backend. I.e. the thread that has called `() and haven't exited from that call. Zero is returned if there's no thread in the backend.

If Pike is compiled without thread support then 1 is returned if we're inside the backend, 0 otherwise.

Thread.Thread

Add f to this backend. This simply does f->set_backend(backend) where backend is this object.

Stdio.File Stdio.FILE

Return an integer that uniquely identifies this backend. For the default backend that integer is 0.

This is the Backend object that files and call_outs are handled by by default.

This is also the Backend object that will be used if main() returns -1.

Backend, Stdio.File()->set_nonblocking(), call_out()

This object claims to be an array for backward compatibility.

0
1
3

The BacktraceFrame object can be indexed as an array.

Set and get various parameters that control the operation of the garbage collector. The passed mapping contains the parameters to set. If a parameter is missing from the mapping, the current value will be filled in instead. The same mapping is returned. Thus an empty mapping, or no argument at all, causes a mapping with all current settings to be returned.

The following parameters are recognized:

- "enabled"

If this is 1 then the gc is enabled as usual. If it's 0 then all automatically scheduled gc runs are disabled and the parameters below have no effect, but explicit runs through the gc function still works as usual. If it's -1 then the gc is completely disabled so that even explicit gc calls won't do anything.

- "garbage_ratio_low"

As long as the gc time is less than gc_time_ratio, aim to run the gc approximately every time the ratio between the garbage and the total amount of allocated things is this.

- "time_ratio"

When more than this fraction of the cpu time is spent in the gc, aim for gc_garbage_ratio_high instead of gc_garbage_ratio_low.

- "garbage_ratio_high"

Upper limit for the garbage ratio - run the gc as often as it takes to keep it below this.

- "average_slowness"

When predicting the next gc interval, use a decaying average with this slowness factor. It should be a value between 0.0 and 1.0 that specifies the weight to give to the old average value. The remaining weight up to 1.0 is given to the last reading.

gc, Debug.gc_status

Graph sub-module for drawing pie-charts.

"polyline.pike"
"create_graph.pike"
"create_bars.pike"

Graph sub-module for drawing bars.

Image
"polyline.pike"
"create_graph.pike"
.polyline
.create_graph
.create_bars
.create_pie

This function sets all unset elements in diagram_data to its default value as well as performing some simple sanity checks. This function is called from within pie, bars, sumbars, line, norm and graph.

Document this function

Image.Image

Document this function

Image.Image

Document this function

Image.Image

Document this function

Image.Image

Document this function

Image.Image

Document this function

Image.Image

Graph sub-module for drawing graphs.

create_graph draws a graph but there are also some other functions used by create_pie and create_bars.

Image
"polyline.pike"

Graph sub-module providing draw functions.

$Id: polyline.pike,v 1.6 2003/11/22 15:00:54 grubba Exp $

The SQL module is a unified interface between pike and all its supported databases. The parts of this module that is usuable for all normal uses is the Sql class and the sql_result class.

string people_in_group(string group) { Sql.Sql db = Sql.Sql("mysql://localhost/testdb"); return db->query("SELECT name FROM users WHERE " "group=%s", group)->name * ","; }

Implements the glue needed to access the Msql-module from the generic SQL module.

Msql.msql

Implements the generic result of the SQL-interface. Used for return results from SQL.sql->big_query().

The actual result.

This is the number of the current row. (0 <= index < num_rows())

Create a new Sql.sql_result object

Result to use as base.

Returns the number of rows in the result.

Returns the number of fields in the result.

Returns non-zero if there are no more rows.

Return information about the available fields.

Skip past a number of rows.

Number of rows to skip.

Fetch the next row from the result.

Sql.postgres_result contains the result of a Postgres-query. See Sql.postgres for a description of this program's functions.

Postgres.postgres_result

Some SQL utility functions

Result object wrapper performing utf8 decoding of all fields.

Returns the number of rows in the result.

Returns the number of fields in the result.

Returns 1 if there are no more rows in the result.

0
1

Cached fetch_fields() result.

Returns Information about the fields in the result.

The following fields are converted from UTF8 if present:

- "name"

The name of the field. Always present.

- "table"

The table the field is from. Not present from all databases.

- "default"

The default value for the column. Not available from all databases.

Skip ahead the specified number of rows.

Fetch the next row from the result.

All strings in the result are decoded from UTF8.

Result wrapper for MySQL that performs UTF-8 decoding of all nonbinary fields. Useful if the result charset of the connection has been set to UTF-8.

There's normally no need to use this class directly. It's used automatically when Mysql.set_unicode_decode_mode is activated.

UnicodeWrapper

Quote a string so that it can safely be put in a query.

String to quote.

Throw an error in case an unimplemented function is called.

Build a raw SQL query, given the cooked query and the variable bindings It's meant to be used as an emulation engine for those drivers not providing such a behaviour directly (i.e. Oracle). The raw query can contain some variables (identified by prefixing a colon to a name or a number (i.e. ":var" or ":2"). They will be replaced by the corresponding value in the mapping.

The query.

Optional mapping containing the variable bindings. Make sure that no confusion is possible in the query. If necessary, change the variables' names.

Implements those functions that need not be present in all SQL-modules.

Object to use for the actual SQL-queries.

Convert all field names in mappings to lower_case. Only relevant to databases which only implement big_query(), and use upper/mixed-case fieldnames (eg Oracle).

0

No (default)

1

Yes

0 1

Quote a string s so that it can safely be put in a query.

All input that is used in SQL-querys should be quoted to prevent SQL injections.

Consider this harmfull code:

string my_input = "rob' OR name!='rob"; string my_query = "DELETE FROM tblUsers WHERE name='"+my_input+"'"; my_db->query(my_query);

This type of problems can be avoided by quoting my_input. my_input would then probably read something like rob\' OR name!=\'rob

Usually this is done - not by calling quote explicitly - but through using a sprintf like syntax

string my_input = "rob' OR name!='rob"; my_db->query("DELETE FROM tblUsers WHERE name=%s",my_input);

Converts a system time value to an appropriately formatted time spec for the database.

Time to encode.

If nonzero then time is taken as a "full" unix time spec (where the date part is ignored), otherwise it's converted as a seconds-since-midnight value.

Converts a database time spec to a system time value.

Time spec to decode.

Take the date part from this system time value. If zero, a seconds-since-midnight value is returned.

Converts a system time value to an appropriately formatted date-only spec for the database.

Time to encode.

Converts a database date-only spec to a system time value.

Date spec to decode.

Converts a system time value to an appropriately formatted date and time spec for the database.

Time to encode.

Converts a database date and time spec to a system time value.

Date and time spec to decode.

Create a new generic SQL object.

Use this object to access the SQL-database.

Connect to the server specified. The string should be on the format: dbtype://[user[:password]@]hostname[:port][/database] Use the dbtype protocol to connect to the database server on the specified host. If the hostname is "" then the port can be a file name to access through a UNIX-domain socket or similar, e g "mysql://root@:/tmp/mysql.sock/".

There is a special dbtype "mysqls" which works like "mysql" but sets the CLIENT_SSL option and loads the /etc/my.cnf config file to find the SSL parameters. The same function can be achieved using the "mysql" dbtype.

0 0

Access through a UNIX-domain socket or similar.

Select this database.

User name to access the database as.

Password to access the database.

Optional mapping of options. See the SQL-database documentation for the supported options. (eg Mysql.mysql()->create()).

In versions of Pike prior to 7.2 it was possible to leave out the dbtype, but that has been deprecated, since it never worked well.

Support for options was added in Pike 7.3.

Changes the charset that the connection uses for queries and returned text strings.

The charset to use. The valid values and their meanings depends on the database brand. However, the special value "unicode" (if supported) selects a mode where the query and result strings are unencoded (and possibly wide) unicode strings.

An error is thrown if the connection doesn't support the specified charset, or doesn't support charsets being set this way at all.

See the set_charset functions for each database connection type for further details about the effects on the connection.

get_charset, Sql.mysql.set_charset

Returns the (database dependent) name of the charset used for (at least) query strings. Returns zero if the connection doesn't support charsets this way (typically means that a call to set_charset will throw an error).

set_charset, Sql.mysql.get_charset

Return last error message.

Select database to access.

Compiles the query (if possible). Otherwise returns it as is. The resulting object can be used multiple times in query() and big_query().

SQL-query to compile.

Handle sprintf-based quoted arguments

Send an SQL query to the underlying SQL-server.

Query to send to the SQL-server. This can either be a string with the query, or a previously compiled query (see compile_query()).

This parameter, if specified, can be in two forms:

A mapping containing bindings of variables used in the query. A variable is identified by a colon (:) followed by a name or number. Each index in the mapping corresponds to one such variable, and the value for that index is substituted (quoted) into the query wherever the variable is used.

res = query("SELECT foo FROM bar WHERE gazonk=:baz", ([":baz":"value"]));

Binary values (BLOBs) may need to be placed in multisets.

Arguments as you would use in sprintf. They are automatically quoted.

res = query("select foo from bar where gazonk=%s","value");

Returns one of the following on success:

The result as an array of mappings indexed on the name of the columns

The value 0 (zero) if the query didn't return any result (eg INSERT or similar).

Throws an exception if the query fails.

Send an SQL query to the underlying SQL-server. The result is returned as a Sql.sql_result object. This allows for having results larger than the available memory, and returning some more info about the result. Returns 0 if the query didn't return any result (e.g. INSERT or similar). For the other arguments, they are the same as for the query() function.

Create a new database.

Name of database to create.

Drop database

Name of database to drop.

Shutdown a database server.

Reload the tables.

Return info about the current SQL-server.

Return info about the connection to the SQL-server.

List available databases on this SQL-server.

Optional wildcard to match against.

List tables available in the current database.

Optional wildcard to match against.

List fields available in the specified table

Table to list the fields of.

Optional wildcard to match against.

This is an interface to the Postgres (Postgres95, pgsql) database server. This module may or may not be availible on your Pike, depending whether the appropriate include and library files could be found at compile-time. Note that you do not need to have a Postgres server running on your host to use this module: you can connect to the database over a TCP/IP socket.

Also note that this module uses blocking I/O I/O to connect to the server. Postgres is quite slow, and so you might want to consider this particular aspect. It is (at least should be) thread-safe, and so it can be used in a multithread environment.

The behavior of the Postgres C API also depends on certain environment variables defined in the environment of the Pike interpreter.

"PGHOST"

Sets the name of the default host to connect to. It defaults to "localhost".

"PGOPTIONS"

Sets some extra flags for the frontend-backend connection. do not set unless you're sure of what you're doing.

"PGPORT"

Sets the default port to connect to, otherwise it will use compile-time defaults (that is: the time you compiled the postgres library, not the Pike driver).

"PGTTY"

Sets the file to be used for Postgres frontend debugging. Do not use, unless you're sure of what you're doing.

"PGDATABASE"

Sets the default database to connect to.

"PGREALM"

Sets the default realm for Kerberos authentication. I never used this, so I can't help you.

Refer to the Postgres documentation for further details.

Sql.Sql, Postgres.postgres, Sql.postgres_result

Postgres.postgres

This function allows you to connect to a database. Due to restrictions of the Postgres frontend-backend protocol, you always have to be connected to a database, so in fact this function just allows you to connect to a different database on the same server.

This function can raise exceptions if something goes wrong (backend process not running, not enough permissions..)

create

This function returns the textual description of the last server-related error. Returns 0 if no error has occurred yet. It is not cleared upon reading (can be invoked multiple times, will return the same result until a new error occurs).

big_query

This function returns a string describing what host are we talking to, and how (TCP/IP or UNIX sockets).

This function resets the connection to the backend. Can be used for a variety of reasons, for example to detect the status of a connection.

This function is Postgres-specific, and thus it is not availible through the generic SQL-interface.

Should you need to report a bug to the author, please submit along with the report the driver version number, as returned by this call.

With no arguments, this function initializes (reinitializes if a connection had been previously set up) a connection to the Postgres backend. Since Postgres requires a database to be selected, it will try to connect to the default database. The connection may fail however for a variety of reasons, in this case the most likely of all is because you don't have enough authority to connect to that database. So use of this particular syntax is discouraged.

The host argument can have the syntax "hostname" or "hostname:portname". This allows to specify the TCP/IP port to connect to. If it is 0 or "", it will try to connect to localhost, default port.

The database argument specifies the database to connect to. If 0 or "", it will try to connect to the specified database.

The username and password arguments are silently ignored, since the Postgres C API doesn't allow to connect to the server as any user different than the user running the interface.

You need to have a database selected before using the sql-object, otherwise you'll get exceptions when you try to query it. Also notice that this function can raise exceptions if the db server doesn't respond, if the database doesn't exist or is not accessible by you.

You don't need bothering about syncronizing the connection to the database: it is automatically closed (and the database is sync-ed) when the object is destroyed.

Postgres.postgres, Sql.Sql, postgres->select_db

With Postgres you can associate events and notifications to tables. This function allows you to detect and handle such events.

With no arguments, resets and removes any callback you might have put previously, and any polling cycle.

With one argument, sets the notification callback (there can be only one for each sqlobject).

With two arguments, sets a notification callback and sets a polling cycle.

The polling cycle is necessary because of the way notifications are delivered, that is piggyback with a query result. This means that if you don't do any query, you'll receive no notification. The polling cycle starts a call_out cycle which will do an empty query when the specified interval expires, so that pending notifications may be delivered.

The callback function must return no value, and takes a string argument, which will be the name of the table on which the notification event has occured. In future versions, support for user-specified arguments will be added.

The polling cycle can be run only if your process is in "event-driven mode" (that is, if 'main' has returned a negative number).

This function is Postgres-specific, and thus it is not availible through the generic SQL-interface.

An integer can be passed as first argument, but it's effect is not documented.

``
``

This function creates a new database with the given name (assuming we have enough permissions to do this).

drop_db

This function destroys a database and all the data it contains (assuming we have enough permissions to do so).

create_db

This function returns a string describing the server we are talking to. It has the form "servername/serverversion" (like the HTTP protocol description) and is most useful in conjunction with the generic SQL-server module.

Lists all the databases available on the server. If glob is specified, lists only those databases matching it.

Returns an array containing the names of all the tables in the currently selected database. If a glob is specified, it will return only those tables whose name matches it.

Returns a mapping, indexed on the column name, of mappings describing the attributes of a table of the current database. If a glob is specified, will return descriptions only of the columns matching it.

The currently defined fields are:

- "has_rules"
- "is_shared"
- "owner"

The textual representation of a Postgres uid.

- "length"
- "text"

A textual description of the internal (to the server) type-name

- "default"
- "expires"

The "relexpires" attribute for the table. Obsolescent; modern versions of Postgres don't seem to use this feature, so don't count on this field to contain any useful value.

This is the only provided interface which allows you to query the database. If you wish to use the simpler "query" function, you need to use the Sql.Sql generic SQL-object.

It returns a postgres_result object (which conforms to the Sql.sql_result standard interface for accessing data). I recommend using query() for simpler queries (because it is easier to handle, but stores all the result in memory), and big_query() for queries you expect to return huge amounts of data (it's harder to handle, but fectches results on demand).

This function can raise exceptions.

Sql.Sql, Sql.sql_result

Implements SQL-urls for mysqls://[user[:password]@][hostname][:port][/database]

Sets the connection to SSL-mode, and sets the default configuration file to "/etc/my.cnf".

Ought to load a suitable default configuration file for Win32 too.

This connection method only exists if the Mysql-module has been compiled with SSL-support.

Sql.mysql

Implements the glue needed to access the Mysql-module from the generic SQL module.

Mysql.mysql

Enables or disables unicode encode mode.

In this mode, if the server supports UTF-8 and the connection charset is latin1 (the default) or unicode then big_query handles wide unicode queries. Enabled by default.

Unicode encode mode works as follows: Eight bit strings are sent as latin1 and wide strings are sent using utf8. big_query sends SET character_set_client statements as necessary to update the charset on the server side. If the server doesn't support that then it fails, but the wide string query would fail anyway.

To make this transparent, string literals with introducers (e.g. _binary 'foo') are excluded from the UTF-8 encoding. This means that big_query needs to do some superficial parsing of the query when it is a wide string.

1

Unicode encode mode is enabled.

0

Unicode encode mode couldn't be enabled because an incompatible connection charset is set. You need to do set_charset("latin1") or set_charset("unicode") to enable it.

Note that this mode doesn't affect the MySQL system variable character_set_connection, i.e. it will still be set to latin1 by default which means server functions like UPPER() won't handle non-latin1 characters correctly in all cases.

To fix that, do set_charset("unicode"). That will allow unicode encode mode to work while utf8 is fully enabled at the server side.

Tip: If you enable utf8 on the server side, you need to send raw binary strings as _binary'...'. Otherwise they will get UTF-8 encoded by the server.

When unicode encode mode is enabled and the connection charset is latin1, the charset accepted by big_query is not quite Unicode since latin1 is based on cp1252. The differences are in the range 0x80..0x9f where Unicode have control chars.

This small discrepancy is not present when the connection charset is unicode.

set_unicode_decode_mode, set_charset

0
1

Returns nonzero if unicode encode mode is enabled, zero otherwise.

set_unicode_encode_mode

Enable or disable unicode decode mode.

In this mode, if the server supports UTF-8 then non-binary text strings in results are automatically decoded to (possibly wide) unicode strings. Not enabled by default.

The statement "SET character_set_results = utf8" is sent to the server to enable the mode. When the mode is disabled, "SET character_set_results = xxx" is sent, where xxx is the connection charset that get_charset returns.

Nonzero enables this feature, zero disables it.

Throws an exception if the server doesn't support this, i.e. if the statement above fails. The MySQL system variable character_set_results was added in MySQL 4.1.1.

This function is only available if Pike has been compiled with MySQL client library 4.1.0 or later, or if the environment variable PIKE_BROKEN_MYSQL_UNICODE_MODE is set.

set_unicode_encode_mode

Returns nonzero if unicode decode mode is enabled, zero otherwise.

set_unicode_decode_mode

Changes the connection charset. Works similar to sending the query SET NAMES charset but also records the charset on the client side so that various client functions work correctly.

charset is a MySQL charset name or the special value "unicode" (see below). You can use SHOW CHARACTER SET to get a list of valid charsets.

Specifying "unicode" as charset is the same as "utf8" except that unicode encode and decode modes are enabled too. Briefly, this means that you can send queries as unencoded unicode strings and will get back non-binary text results as unencoded unicode strings. See set_unicode_encode_mode and set_unicode_decode_mode for further details.

Throws an exception if the server doesn't support this, i.e. if the statement SET NAMES fails. Support for it was added in MySQL 4.1.0.

If charset is "latin1" and unicode encode mode is enabled (the default) then big_query can send wide unicode queries transparently if the server supports UTF-8. See set_unicode_encode_mode.

If unicode decode mode is already enabled (see set_unicode_decode_mode) then this function won't affect the result charset (i.e. the MySQL system variable character_set_results).

Actually, a query SET character_set_results = utf8 will be sent immediately after setting the charset as above if unicode decode mode is enabled and charset isn't "utf8".

You should always use either this function or the "mysql_charset_name" option to create to set the connection charset, or more specifically the charset that the server expects queries to have (i.e. the MySQL system variable character_set_client). Otherwise big_query might not work correctly.

Afterwards you may change the system variable character_set_connection, and also character_set_results if unicode decode mode isn't enabled.

The MySQL latin1 charset is close to Windows cp1252. The difference from ISO-8859-1 is a bunch of printable chars in the range 0x80..0x9f (which contains control chars in ISO-8859-1). For instance, the euro currency sign is 0x80.

You can use the mysql-latin1 encoding in the Locale.Charset module to do conversions, or just use the special "unicode" charset instead.

get_charset, set_unicode_encode_mode, set_unicode_decode_mode

Returns the MySQL name for the current connection charset.

Returns "unicode" if unicode encode mode is enabled and UTF-8 is used on the server side (i.e. in character_set_connection).

In servers with full charset support (i.e. MySQL 4.1.0 or later), this corresponds to the MySQL system variable character_set_client (with one exception - see next note) and thus controls the charset in which queries are sent. The charset used for text strings in results might be something else (and typically is if unicode decode mode is enabled; see set_unicode_decode_mode).

If the returned charset is latin1 or unicode and unicode encode mode is enabled (the default) then character_set_client in the server might be either latin1 or utf8, depending on the last sent query. See set_unicode_encode_mode for more info.

set_charset

Quote a string so that it can safely be put in a query.

String to quote.

Converts a string in MySQL latin1 format to UTF-8.

Encodes the appropriate sections of the query with encode_fn. Everything except strings prefixed by an introducer (i.e. _something or N) is encoded.

``

Converts a system time value to an appropriately formatted time spec for the database.

Time to encode.

If nonzero then time is taken as a "full" unix time spec (where the date part is ignored), otherwise it's converted as a seconds-since-midnight value.

Converts a system time value to an appropriately formatted date-only spec for the database.

Time to encode.

Converts a system time value to an appropriately formatted date and time spec for the database.

Time to encode.

Converts a database time spec to a system time value.

Time spec to decode.

Take the date part from this system time value. If zero, a seconds-since-midnight value is returned.

Converts a database date-only spec to a system time value. Assumes 4-digit years.

Date spec to decode.

Converts a database date and time spec to a system time value. Can decode strings missing the time part.

Date and time spec to decode.

Return 1 if the argument name is a mysql keyword.

0
1

BLOWFISH is a block cipher designed by Bruce Schneier. It uses a block size of 64 bits (8 octets), and a variable key size, up to 448 bits. It has some weak keys.

Nettle.BLOWFISH_Info
.Cipher

The IDEA(tm) block cipher is covered by patents held by ETH and a Swiss company called Ascom-Tech AG. The Swiss patent number is PCT/CH91/00117, the European patent number is EP 0 482 154 B1, and the U.S. patent number is US005214703. IDEA(tm) is a trademark of Ascom-Tech AG. There is no license fee required for noncommercial use.

Nettle.IDEA_Info
.Cipher

AES (American Encryption Standard) is a quite new block cipher, specified by NIST as a replacement for the older DES standard. The standard is the result of a competition between cipher designers. The winning design, also known as RIJNDAEL, was constructed by Joan Daemen and Vincent Rijnmen.

Like all the AES candidates, the winning design uses a block size of 128 bits, or 16 octets, and variable key-size, 128, 192 and 256 bits (16, 24 and 32 octets) being the allowed key sizes. It does not have any weak keys.

Nettle.AES_Info
.Cipher

MD2 is a message digest function constructed by Burton Kaliski, and is described in RFC 1319. It outputs message digests of 128 bits, or 16 octets.

Nettle.MD2_Info
.Hash

SERPENT is one of the AES finalists, designed by Ross Anderson, Eli Biham and Lars Knudsen. Thus, the interface and properties are similar to AES'. One peculiarity is that it is quite pointless to use it with anything but the maximum key size, smaller keys are just padded to larger ones.

Nettle.Serpent_Info
.Cipher

Quote from Koremutake home page http://shorl.com/koremutake:

In an attempt to temporarily solve the fact that human beings seem to be inable to remember important things (such as their names, car keys and seemingly random numbers with fourteen digits in 'em), we invented Koremutake.

It is, in plain language, a way to express any large number as a sequence of syllables. The general idea is that word-sounding pieces of information are a lot easier to remember than a sequence of digits.

Encode an integer as a koremutake string.

Decode a koremutake string into an integer.

MD5 is a message digest function constructed by Ronald Rivest, and is described in RFC 1321. It outputs message digests of 128 bits, or 16 octets.

Nettle.MD5_Info
.Hash

SHA256 is another hash function specified by NIST, intended as a replacement for SHA, generating larger digests. It outputs hash values of 256 bits, or 32 octets.

Nettle.SHA256_Info
.Hash

This module contains stuff to that tries to give you the best possible random generation.

Returns a string of length len with random content. The content is generated by a Yarrow random generator that is constantly updated with output from /dev/random on UNIX and CryptGenRandom on NT. The Yarrow random generator is fed at least the amount of random data from its sources as it outputs, thus doing its best to give at least good pseudo- random data on operating systems with bad /dev/random.

Returns a Gmp.mpz object with a random value between 0 and top. Uses random_string.

Gmp.mpz

Works as random_string, but may block in order to gather enough entropy to make a truely random output. Using this function is probably overkill for about all applications.

Inject additional entropy into the random generator.

The random string.

The number of bits in the random string that is truely random.

DES is the old Data Encryption Standard, specified by NIST. It uses a block size of 64 bits (8 octets), and a key size of 56 bits. However, the key bits are distributed over 8 octets, where the least significant bit of each octet is used for parity. A common way to use DES is to generate 8 random octets in some way, then set the least significant bit of each octet to get odd parity, and initialize DES with the resulting key.

The key size of DES is so small that keys can be found by brute force, using specialized hardware or lots of ordinary work stations in parallel. One shouldn't be using plain DES at all today, if one uses DES at all one should be using DES3 or "triple DES".

DES also has some weak keys.

Nettle.DES_Info
.Cipher

MD4 is a message digest function constructed by Ronald Rivest, and is described in RFC 1320. It outputs message digests of 128 bits, or 16 octets.

Nettle.MD4_Info
.Hash

SHA1 is a hash function specified by NIST (The U.S. National Institute for Standards and Technology). It outputs hash values of 160 bits, or 20 octets.

Nettle.SHA1_Info
.Hash

CAST-128 is a block cipher, specified in RFC 2144. It uses a 64 bit (8 octets) block size, and a variable key size of up to 128 bits.

Nettle.CAST128_Info
.Cipher

Another AES finalist, this one designed by Bruce Schneier and others.

Nettle.Twofish_Info
.Cipher

Arcfour is a stream cipher, also known under the trade marked name RC4, and it is one of the fastest ciphers around. A problem is that the key setup of Arcfour is quite weak, you should never use keys with structure, keys that are ordinary passwords, or sequences of keys like "secret:1", "secret:2", ..... If you have keys that don't look like random bit strings, and you want to use Arcfour, always hash the key before feeding it to Arcfour.

Nettle.ARCFOUR_Info
.Cipher

A wrapper class that connects several cipher algorithms into one algorithm. E.g. triple DES can be emulated with Crypto.Pipe(Crypto.DES, Crypto.DES, Crypto.DES).

HMAC, defined by RFC-2104

Calling the HMAC object with a password returns a new object that can perform the actual HMAC hashing. E.g. doing a HMAC hash with MD5 and the password "bar" of the string "foo" would require the code Crypto.HMAC(Crypto.MD5)("bar")("foo").

The secret password (K).

Hashes the text according to the HMAC algorithm and returns the hash value.

Hashes the text according to the HMAC algorithm and returns the hash value as a PKCS-1 digestinfo block.

The hash object on which the HMAC object should base its operations. Typical input is Crypto.MD5.

The block size of one compression block, in octets. Defaults to 64.

.Hash

Calls the hash function given to create and returns the hash value of s.

Makes a PKCS-1 digestinfo block with the message s.

Standards.PKCS.Signature.build_digestinfo

Implements a simple substitution crypto, ie. one of the first crypto systems ever invented and thus one of the least secure ones available.

Sets the encryption and decryption key. The decryption key is derived from the encryption key by reversing the mapping. If one index maps to an array of strings, one element from the array will be chosen at random in such substitution.

An error is thrown if the encryption key can not be made reversible.

this_program

Set null characters (fillers). Characters from chars will be inserted into the output stream with a probability p.

A float between 0.0 and 1.0 or an integer between 0 and 100.

An array of one character strings.

this_program

Sets the key to a ROT substitution system. steps defaults to 13 and alphabet defaults to A-Z, i.e. this function defaults to set the substitution crypto to be ROT13. If no alphabet is given the key will be case insensitive, e.g. the key will really be two ROT13 alphabets, one a-z and one A-Z, used simultaneously.

this_program

Sets the key according to ACA K1 key generation. The plaintext alphabet is prepended with a keyword key that shifts the alphabet positions compared to the cryptogram alphabet. The plaintext alphabet is then reduced with the characters in the keyword. It is also optionally rotated offset number of steps.

this_program

Sets the key according to ACA K2 key generation. The cryptogram alphabet is prepended with a keyword key that shifts the alphabet positions compared to the plaintext alphabet. The cryptogram alphabet is then reduced with the characters in the keyword. It is als optionally reotated offset number of steps.

this_program

Sets the key according to ACA K3 key generation. Both the plaintext and the cryptogram alphabets are prepended with a keyword key, which characters are removed from the rest of the alphabet. The plaintext alphabet is then rotated offset number of steps.

this_program

Sets the key according to ACA K4 key generation. Both the plaintext and the cryptogram alphabets are prepended with the keywords key1 and key2. The plaintext alphabet is then rotated offset number of steps.

this_program

Encrypts the message m.

Decrypts the cryptogram c.

Removes characters not in the encryption key or in the save multiset from the message m.

Returns the RSA modulo.

Gmp.mpz

Returns the RSA public exponent.

Gmp.mpz

Returns the RSA private exponent (if known).

Gmp.mpz

Returns the first RSA prime (if known).

Gmp.mpz

Returns the second RSA prime (if known).

Gmp.mpz

Returns the RSA modulo as a binary string.

Returns the RSA public exponent as a binary string.

Returns the RSA private exponent (if known) as a binary string.

Returns the first RSA prime (if known) as a binary string.

Returns the second RSA prime (if known) as a binary string.

Sets the public key.

Gmp.mpz
Gmp.mpz
this_program

Sets the private key.

Gmp.mpz 0

The first prime.

Gmp.mpz 1

The second prime.

Gmp.mpz
Gmp.mpz
this_program

Returns the crypto block size, or zero if not yet set.

Pads the message to the current block size with method type and returns the result as an integer.

1

The message is padded with 0xff bytes.

2

The message is padded with random data, using the random function if provided. Otherwise Crypto.Random.random_string will be used.

1 2
``
Gmp.mpz

Reverse the effect of rsa_pad.

Gmp.mpz

Pads the digest with rsa_pad type 1 and signs it.

Gmp.mpz

Signs digest as raw_sign and returns the signature as a byte string.

Verifies the digest against the signature s, assuming pad type 1.

rsa_pad, raw_sign

Gmp.mpz
0
1

Pads the message s with rsa_pad type 2, signs it and returns the signature as a byte string.

Optional random function to be passed down to rsa_pad.

``

Decrypt a message encrypted with encrypt.

Returns the size of the key in terms of number of bits.

0

Compares the public key of this RSA object with another RSA object.

this_program
0
1

Signs the message with a PKCS-1 signature using hash algorithm h.

.Hash
Gmp.mpz

Verify PKCS-1 signature sign of message msg using hash algorithm h.

.Hash
Gmp.mpz
0
1

Document this function.

Document this function.

Document this function.

Document this function.

Generate a prime with bits number of bits using random function r.

``
Gmp.mpz

Generate a valid RSA key pair with the size bits. A random function may be provided as arguemnt r, otherwise Crypto.Random.random_string will be used. Keys must be at least 128 bits.

128
``
this_program

Sets the public key to key and the mode to encryption.

set_decrypt_key, crypt

Gmp.mpz
this_program

Sets the public key to keyand the mod to decryption.

set_encrypt_key, crypt

Gmp.mpz
this_program

Encrypt or decrypt depending on set mode.

set_encrypt_key, set_decrypt_key

Returns the string "RSA".

PGP stuff. See RFC 2440.

Decodes PGP data.

Verify text against signature sig with the public key pubkey.

Encode PGP data with ASCII armour.

Decode ASCII armour.

Various cryptographic classes and functions.

Hash functions These are based on the Hash API; MD2, MD4, MD5, SHA1, SHA256.

Stream cipher functions These are based on the Cipher API; AES, Arcfour, Blowfish, CAST, DES, DES3, IDEA, Serpent, Twofish. The Substitution program is compatible with the CipherState. Also conforming to the API are the helper programs Buffer, CBC and Pipe.

Abstract class for hash algorithms. Contains some tools useful for all hashes.

Nettle.HashInfo

Calling `() will return a Nettle.HashState object.

HashState

Works as a shortcut for obj->update(data)->digest().

HashState()->update() and HashState()->digest().

Abstract class for crypto algorithms. Contains some tools useful for all ciphers.

Nettle.CipherInfo

Calling `() will return a Nettle.CipherState object.

CipherState

Works as a shortcut for obj->set_encrypt_key(key)->crypt(data)

Works as a shortcut for obj->set_decrypt_key(key)->crypt(data)

Hashes a password together with a salt with the crypt_md5 algorithm and returns the result.

verify_crypt_md5

Verifies the password against the crypt_md5 hash.

May throw an exception if the hash value is bad.

make_crypt_md5

0
1

The inadequate key size of DES has already been mentioned. One way to increase the key size is to pipe together several DES boxes with independent keys. It turns out that using two DES ciphers is not as secure as one might think, even if the key size of the combination is a respectable 112 bits.

The standard way to increase DES's key size is to use three DES boxes. The mode of operation is a little peculiar: the middle DES box is wired in the reverse direction. To encrypt a block with DES3, you encrypt it using the first 56 bits of the key, then decrypt it using the middle 56 bits of the key, and finally encrypt it again using the last 56 bits of the key. This is known as "ede" triple-DES, for "encrypt-decrypt-encrypt".

The "ede" construction provides some backward compatibility, as you get plain single DES simply by feeding the same key to all three boxes. That should help keeping down the gate count, and the price, of hardware circuits implementing both plain DES and DES3.

DES3 has a key size of 168 bits, but just like plain DES, useless parity bits are inserted, so that keys are represented as 24 octets (192 bits). As a 112 bit key is large enough to make brute force attacks impractical, some applications uses a "two-key" variant of triple-DES. In this mode, the same key bits are used for the first and the last DES box in the pipe, while the middle box is keyed independently. The two-key variant is believed to be secure, i.e. there are no known attacks significantly better than brute force.

Nettle.DES3_Info
.Cipher

The Digital Signature Algorithm (aka DSS, Digital Signature Standard).

Returns the modulo.

Gmp.mpz

Returns the group order.

Gmp.mpz

Returns the generator.

Gmp.mpz

Returns the public key.

Gmp.mpz

Returns the private key.

Gmp.mpz

Sets the public key in this DSA object.

Gmp.mpz
Gmp.mpz
Gmp.mpz
Gmp.mpz
this_program

Sets the private key in this DSA object.

Gmp.mpz
this_program

Sets the random function, used to generate keys and parameters, to the function r. Default is Crypto.Random.random_string.

``
this_program

Makes a DSA hash of the messge msg.

Gmp.mpz

Sign the message h. Returns the signature as two Gmp.mpz objects.

Gmp.mpz
Gmp.mpz
Gmp.mpz

Verify the signature r,s against the message h.

Gmp.mpz
Gmp.mpz
Gmp.mpz
0
1

Make a RSA ref signature of message msg.

Verify a RSA ref signature s of message msg.

0
1

Make an SSL signatrue of message msg.

Verify an SSL signature s of message msg.

0
1

The (slow) NIST method of generating a DSA prime pair. Algorithm 4.56 of Handbook of Applied Cryptography.

Gmp.mpz

Generate key parameters using nist_primes.

this_program

Generates a public/private key pair. Needs the public parameters p, q and g set, either through set_public_key or generate_parameters.

this_program

Compares the public key in this object with that in the provided DSA object.

.DSA
0
1

Returns the string "DSA".

Class representing an HCRYPTPROV handle.

Key container name. When flags is set to CRYPT_VERIFYCONTEXT the name must be 0.

The name of the Crypto Service Provider to use. If set to 0 the user default CSP will be used.

Retreive some random data. Calls CryptGenRandom in the NT API.

Implementation of the cipher block chaining mode (CBC). Works as a wrapper for the cipher algorithm put in create.

Initialize the CBC wrapper with a cipher algorithm. If it is a program, an object will be instantiated with args as arguments. If it is an object that doesn't conform to the cipher API, but has an LFUN::`(), that LFUN will be called. If it is a function, that function will be called with args as arguments.

``

Returns the string "CBC(x)" where x is the encapsulated algorithm.

Reurns the block size of the encapsulated cipher.

Returns the key size of the encapsulated cipher.

Prepare the cipher and the wrapper for encrypting with the given key.

this_program

Prepare the cipher and the wrapper for decrypting with the given key.

this_program

Set the initialization vector to iv.

this_program

Encrypt/decrypt data and return the result. data must be an integral number of blocks.

Acts as a buffer so that data can be fed to a cipher in blocks that doesn't correspond to cipher block sizes.

Initialize the Proxy wrapper with a cipher algorithm. If it is a program, an object will be instantiated with args as arguments. If it is an object that doesn't conform to the cipher API, but has an LFUN::`(), that LFUN will be called. If it is a function, that function will be called with args as arguments.

``

Returns the string "CBC(x)" where x is the encapsulated algorithm.

Get the block size of the contained block crypto.

Get the key size of the contained block crypto.

Set the encryption key.

As a side-effect any buffered data will be cleared.

this_program

Set the decryption key.

As a side-effect any buffered data will be cleared.

this_program

Encrypt some data.

Adds data to be encrypted to the buffer. If there's enough data to en/decrypt a block, that will be done, and the result returned. Any uncrypted data will be left in the buffer.

Pad and de/encrypt any data left in the buffer.

unpad()

De/encrypt and unpad a block of data.

This performs the reverse operation of pad().

pad()

GL Universal Environment

A display list abstraction. Automatically allocates a display list id upon creation and correctly deallocate it upon destruction.

DynList

When creating a new list, the list code can be compiled upon creation by supplying a function f that performs the GL operations.

call

List list = List() { // GL code };

``

Deletes this list and frees the list id from the id pool.

Returns this lists' id.

List objects can be sorted according to list id.

get_id

0
1

Start defining the list. If run is provided, the list will be executed as it is compiled (GL.GL_COMPILE_AND_EXECUTE).

end, compile

0 1

Finish the list definition.

begin, compile

Compile a list be executing the list code f. Exceptions in f will be thrown after GL.glEndList has been called.

begin

``

Execute the commands in the list.

A displaylist that is generated on demand.

On Windows lists needs to be regenerated when the video driver mode is changed. Thus the DynList is to prefer over List, since regeneration is done automatically upon video mode change.

List

Called by videodriver when a video mode change occurs.

Sets a function which can generate a displaylist. Hint: Use implicit lambda...

``

Generates the displaylist, ie calls the function set in set_generator. Called only when the display list needs to be generated.

Call the displaylist, ie draw it.

Create a new DynList object and optionally set a function that can generate the displaylist

Function which contains the GL commands that generates the displaylist.

``

The texture base class. Using e.g. Texture might be more convenient.

Texture dimensions

Image dimensions

Utilization in percent.

The texture type, e.g. GL.GL_TEXTURE_2D.

A string to identify the texture.

Construct a new texture. Processes _alpha, _mode and debug_text and calls resize.

The alpha mode the texture is operating in.

0

RGB

1

RGBA

2

ALPHA

3

LUM

4

LUM+ALPHA

The mode the texture is operating in. Autoselected wrt _alpha if 0.

A string that can be used to identify this texture.

0 1

Calls construct with args.

Properly deallocates the texture.

Resizes/creates a texture to meet the dimensions width and height. If nocreate isn't given, create_texture is called to actually perform the resize/creation.

construct

0 1
0 1

Actually creates the texture.

If zero, a black texture with the dimensions width * height will be generated. Otherwise imgs should be a mapping as follows.

- Image.Image "image"

The actual image to be used as texture. It will be cropped/padded to meet the dimensions given in width and height.

- Image.Image "alpha"

Optional image to be used as alpha channel, depending on the alpha value given to create/construct.

If 1, the texture will be mipmapped.

The dimensions of the texture. If omitted the dimensions of the images in imgs will be used.

resize

0 1

Renders a mipmap of the image/partial image imgs.

Image data mapping to feed GL.glTexImage2D or GL.glTexSubImage2D.

Internal format to feed GL.glTexImage2D, or UNDEFINED for partial images.

Xoffs, yoffs to feed GL.glTexSubImage2D for partial images.

create_texture

Clears the texture.

Paste the image i with alpha channel a at coordinates x and y in the current texture.

Image.Image
Image.Image

Returns the size of memory allocated by the texture.

Returns the id of this texture.

Textures can be sorted according to texture id.

0
1

Draw the texture at x,y,z with dimensions w*h.

Draw texture region s0,q0 - ss,qs at x,y,z with dimensions w*h.

Use the generated texture (GL.glBindTexture).

Sets the texture coordinates to x*width,y*height.

Set the contents (and size) of the texture from the supplied data. The data is identical to what would normally be sent as the last argument to glTex[Sub]Image2D() or an Image.Image object.

If no_resize is specified, it is assumed that the data will fit in the texture, otherwise the parts that extend beyond it will be discarded.

Besides being an Image.Image object, data can be either of two types of mappins. First it can be a mapping with Image data.

- Image.Image "rgb"

Texture image data.

- Image.Image "alpha"

Optional alpha channel.

- Image.Image "luminance"

Optional luminance channel.

Second it can be a mapping pointing out a shared memory segment.

- System.Memory "mem"

The shared memory segment.

- "mem_w"
- "mem_h"

The width and height of the memory segment.

- "mem_format"

The format of the memory segment, e.g. GL.GL_RGB.

- "mem_type"

The low level format of the memory segment, e.g. GL.GL_UNSIGNED_BYTE.

Image.Image
0 1

Uses the NVidia RECT texture extension for non-power-of-two textures.

BaseTexture

A mixin class with a dwim create function.

This create function has the following heuristic:

If a mapping is encountered, the following information will be attempted to be extracted.

- Image.Image "image"

The texture image.

- "xsize"
- "ysize"
- "height"
- "width"

The image dimensions. If not provided, the dimensions of the "image" member will be used.

- "alpha"

The alpha mode.

- 0 1 "mipmap"

Should the texture be mipmapped or not.

- "mode"

The texture mode.

- "debug"

The debug name associated with this texture.

If an object is encountered in the argument list, the first object will be used as texture image and the second as texture alpha.

If a string is encountered in the argument list, it will be used as debug name associated with this texture.

Once all mappings, strings and objects are removed from the argument list, the remaining integers will be interpreted as width, height, alpha, mipmap and mode, unless there is only one argument. In that case it will be interpreted as the alpha mode.

Convenience version of the Texture class.

Texture base

BaseTexture

Convenience methods

BaseDWIM

Convenience version of the RectangleTexture class.

Texture base

RectangleTexture

Convenience methods

BaseDWIM

A rectangle. Used by the text routines to avoid drawing outside the current region.

All region objects have this constant.

Move the region xp units right and yp units down.

Make the region xs units wider and ys units higher.

Returns 1 if the region R is fully outside this region.

Region
0
1

Returns 1 if the region R is fully inside this region.

Region
0
1

Creates a new region with the intersection of this region and R.

Region

A font.

A character to draw.

Region

Character position in texture txt.

Region

Texture holding the character.

BaseTexture

Slice of character to be shown.

Region

Set character to be region _slice of region _pos of texture _txt.

Region
BaseTexture
Region

Draw the character using the texture txt with the texture-coordinates indicated in pos, possible cropped with slice.

Image.Fonts.Font

Returns the advance (in pixels), the texture and the texture coordinates for the specified character, or 0 if it's nonprintable.

If the font->write call fails, the backtrace will be written to stderr.

BaseTexture
Region

Get the width and height of the area that the string text in size h would cover.

Write the text in size [h], possibly restricted by region roi. Return the width and height of the resulting text area. If roi is a float, Region(0.0, 0.0, roi, 10000.0) will be used.

Region

Create a display list that writes text.

The text to write.

The font height

The region, if supplied, to restrict writing to.

The text justification; "left" (default), "center" or "right".

Region
List

A mesh of squares.

Recalculate the mesh.

Return the normal for the surface at coordinates x,y. Used internally.

Math.Matrix

Set a texture to be mapped on the mesh.

BaseTexture

Draw the mesh.

Indicate whether or not lighting is used. If it is, the normals of each vertex will be calculated as well as the coordinates.

0 1

Set the size of the mesh

The calculator will be called for each corner and should return a 1x3 matrix describing the coordinates for the given spot om the surface.

`Math.Matrix`
GL

Returns the name of the available drivers.

init

Add a callback that will be called every time the resolution is about to change.

remove_reinit_callback

``

Removes a reinitialization callback.

add_reinit_callback

``

Returns 1 if in fullscreen mode, otherwise 0.

toggle_fullscreen

0
1

Toggles between fullscreen and window mode. If a screen mode is provided, that mode will be assumed.

get_screen_mode

0 1

Returns the GL flags currently used.

set_gl_flags

Sets the GL flags.

get_gl_flags

Returns the current color depth.

set_depth

Sets the color depth.

get_depth

Returns the screen width/height.

set_resolution

Sets the resolution to wxh pixels.

xsize, ysize

Returns the screen aspect.

set_aspect

Set the aspect of the draw area. Does nothing if the provided aspect is equal to the one currently used.

get_aspect

Rotates the drawing area deg degrees. Useful e.g. when drawing for tilted monitors.

Mirrors the screen in x and/or y axis. Useful e.g. when drawing for backlight projection.

A string that contains the mirror axis, e.g. "x" or "xy".

Initializes GLUE and loads a driver from a list of drivers. If a driver fails to load or initialize, the next driver is tried.

driver_names not listed in the result from get_drivers will cause an error to be thrown.

- "driver_names"

The name of a driver or a list of drivers to try, in given order. If no driver name is given, the list given by get_drivers is used.

- `.Events.Event` "event_callback"

This callback is called with a Events.Event object whenever an event is trapped by the driver.

- `01` "resize_callback"

This callback is called with the aspect whenever the drawing area is resized, either by an event or explicitly by the program.

- 0 1 "fullscreen"

Set fullscreen/window mode. 1 is fullscreen, 0 is window. Defaults to fullscreen.

- "resolution"

Sets the resolution of the drawing area. Defaults to ({ 800, 600 }).

- "aspect"

Sets the aspect of the drawing area. Defaults to 1.333333 (4:3).

- "depth"

Sets the color depth of the drawing area. Defaults to 32.

- "title"

Sets the window title to this string.

- "icon_title"

Sets the icon title to this string.

- 0 1 "fast_mipmap"

Use GL_NEAREST_MIMAP_NEAREST instead of GL_LINEAR_MIPMAP_LINEAR, which also is the default.

- "rotation"

The rotation in z-axis of the drawing field.

- "mirror"

Mirroring in x and/or y axis.

get_drivers

Swap the drawing buffer and the viewing buffer.

Show the mouse cursor.

Hide the mouse cursor.

Allocate a hardwareaccelerated lightsource from OpenGL.

an id which may be added to the GL.GL_LIGHT0 constant.

free_light

Call this function to free a lightsource that has been allocated with allocate_light.

Id which has been allocated using allocate_light.

allocate_light

Returns the PushPop depth, i.e. the number of pushes awaiting corresponding pops.

0

Performs function f between GL.glPushMatrix and GL.glPopMatrix calls.

PushPop() { GL.glTranslate( 0.01, -0.9, 0.0 ); write_text( "Press esc to quit" ); };

``

Returns all defined lists. Only available on Windows.

List

Returns 1 if all defined lists are DynList lists.

0
1

Create a texture. Mainly here for symetry with make_rect_texture

Texture, make_rect_texture

Image.Image
BaseTexture

Create a texture with the specified image as contents. Will try to use the TEXTURE_RECTANGLE_NV extension if available, otherwise normal textures will be used (like make_texture).

make_texture

Image.Image
BaseTexture

Returns a list of all current textures.

BaseTexture

Returns the number of bytes used by the textures.

Image.Color.Color
Image.Color.Color

Draw a box outline around the specified coordinates. c is either a single color, in which case it will be used for all corners, or an array of four colors, which will be used for each corner.

a is similar to c, but is the alpha values for each coordinate.

Image.Color.Color Image.Color.Color

Draw a box at the specified coordinates. c is either a single color, in which case it will be used for all corners, or an array of four colors, which will be used for each corner.

a is similar to c, but is the alpha values for each coordinate.

Image.Color.Color Image.Color.Color
Image.Color.Color

Returns some internal states for debug purposes. The actual content may change.

GLUE Event abstraction.

Contains an event.

Returns a copy of this Event object.

this_program

The pressure of the key stroke. A value between 0.0 and 1.0. Unknown values are represented as 0.

Press event or release event.

0 1
0 1

Integer constant representing shift.

Integer constant representing control.

Integer constant representing alternate.

Integer constant with the union of all known modifiers, i.e. _SHFT | _CTRL | _ALT.

Adds the _CTRL modifier to an Event, key or array of Events and/or keys.

Event
Event
Event
Event

Adds the _SHFT modifier to an Event, key or array of Events and/or keys.

Event
Event
Event
Event

Adds the _ALT modifier to an Event, key or array of Events and/or keys.

Event
Event
Event
Event

Numeric constant representing a key.

Numeric constant representing a mouse button.

Numeric constant representing a mouse movement.

Numeric constant representing a modifier key.

Mapping that maps a modifier key to any of the symbolic modifiers _SHFT, _CTRL and _ALT.

Numeric constant representing an exit event.

Mapping that maps key identifiers with a printable name, e.g. LSHIFT to "Left shift".

Returns 1 if the key code k is a modifier key, e.g. LSHIFT or RSHIFT.

0
1

A string wrapper that pretends to be a Stdio.File object.

This constant can be used to distinguish a FakeFile object from a real Stdio.File object.

Stdio.File()->close()

Stdio.File()->create()

Stdio.File()->dup()

this_program

Always returns 0.

Stdio.File()->errno()

Returns size and the creation time of the string.

Stdio.Stat

Stdio.File()->line_iterator()

String.SplitIterator

Stdio.File()->query_id()

Stdio.File()->set_id()

Stdio.File()->read_function()

Stdio.File()->peek()

-1
1

Always returns 0.

Stdio.File()->query_address()

0 1

Stdio.File()->read()

0
0 1

Stdio.File()->seek()

Always returns 1.

Stdio.File()->sync()

1
1

Stdio.File()->tell()

Stdio.File()->truncate()

0
1

Stdio.File()->write()

-1

Stdio.File()->set_blocking

Stdio.File()->set_blocking_keep_callbacks

Stdio.File()->set_blocking

``
``
``
``
``

Stdio.File()->set_blocking_keep_callbacks

Stdio.File()->set_close_callback

``

Stdio.File()->set_read_callback

``

Stdio.File()->set_read_oob_callback

``

Stdio.File()->set_write_callback

``

Stdio.File()->set_write_oob_callback

``

Stdio.File()->query_close_callback

Stdio.File()->query_read_callback

Stdio.File()->query_read_oob_callback

Stdio.File()->query_write_callback

Stdio.File()->query_write_oob_callback

A FakeFile can be casted to a string.

Sizeof on a FakeFile returns the size of its contents.

0

The Stdio.Stream API.

This class exists purely for typing reasons.

Use in types in place of Stdio.File where only blocking stream-oriented I/O is done with the object.

NonblockingStream, BlockFile, File, FILE

The Stdio.NonblockingStream API.

This class exists purely for typing reasons.

Use in types in place of Stdio.File where nonblocking and/or blocking stream-oriented I/O is done with the object.

Stream, BlockFile, File, FILE

Stream

The Stdio.BlockFile API.

This class exists purely for typing reasons.

Use in types in place of Stdio.File where only blocking I/O is done with the object.

Stream, NonblockingStream, File, FILE

Stream

This is the basic I/O object, it provides socket and pipe communication as well as file access. It does not buffer reads and writes or provide line-by-line reading, that is done with Stdio.FILE object.

The file or stream will normally be closed when this object is destructed (unless there are more objects that refer to the same file through use of assign or dup). Objects do not contain cyclic references in themselves, so they will be destructed timely when they run out of references.

Stdio.FILE

Fd_ref

Returns the error code for the last command on this file. Error code is normally cleared when a command is successful.

Open a file for read, write or append. The parameter mode should contain one or more of the following letters:

"r"

Open file for reading.

"w"

Open file for writing.

"a"

Open file for append (use with "w").

"t"

Truncate file at open (use with "w").

"c"

Create file if it doesn't exist (use with "w").

"x"

Fail if file already exists (use with "c").

mode should always contain at least one of the letters "r" or "w".

The parameter mask is protection bits to use if the file is created. Default is 0666 (read+write for all in octal notation).

This function returns 1 for success, 0 otherwise.

close(), create()

Open the master end of a pseudo-terminal pair. The parameter mode should contain one or more of the following letters:

"r"

Open terminal for reading.

"w"

Open terminal for writing.

mode should always contain at least one of the letters "r" or "w".

grantpt()

This makes this file into a socket ready for connections. The reason for this function is so that you can set the socket to nonblocking or blocking (default is blocking) before you call connect().

If you give a port number to this function, the socket will be bound to this port locally before connecting anywhere. This is only useful for some silly protocols like FTP. You may also specify an address to bind to if your machine has many IP numbers.

port can also be specified as a string, giving the name of the service associated with the port.

Finally, a protocol family for the socket can be specified. If no family is specified, one which is appropriate for the address is automatically selected. Thus, there is normally no need to specify it.

This function returns 1 for success, 0 otherwise.

connect(), set_nonblocking(), set_blocking()

This function connects a socket previously created with open_socket() to a remote socket through TCP/IP. The host argument is the hostname or IP number of the remote machine. A local IP and port can be explicitly bound by specifying client and client_port.

This function returns 1 for success, 0 otherwise.

In nonblocking mode 0 (zero) may be returned and errno() set to EWOULDBLOCK or WSAEWOULDBLOCK. This should not be regarded as a connection failure. In nonblocking mode you need to wait for a write or close callback before you know if the connection failed or not.

query_address(), async_connect(), connect_unix()

Open a UNIX domain socket connection to the specified destination.

Returns 1 on success, and 0 on failure.

Nonblocking mode is not supported while connecting

Returns a function that when called will call read with nbytes as argument. Can be used to get various callback functions, eg for the fourth argument to String.SplitIterator.

Returns an iterator that will loop over the lines in this file. If trim is true, all '\r' characters will be removed from the input.

String.SplitIterator
LineIterator

Open a TCP/IP connection asynchronously.

This function is similar to connect(), but works asynchronously.

Hostname or IP to connect to.

Port number or service name to connect to.

Function to be called on completion. The first argument will be 1 if a connection was successfully estabished, and 0 (zero) on failure. The rest of the arguments to callback are passed verbatim from args.

Extra arguments to pass to callback.

Returns 0 on failure, and 1 if callback will be used.

The socket may be opened with open_socket() ahead of the call to this function, but it is not required.

This object is put in callback mode by this function. For callback to be called, the backend must be active. See e.g. set_read_callback for more details about backends and callback mode.

The socket will be in nonblocking state if the connection is successful, and any callbacks will be cleared.

connect(), open_socket(), set_nonblocking()

``

This function creates a pipe between the object it was called in and an object that is returned.

Binary or (predef::`|()) of required PROP_ properties.

PROP_IPC

The resulting pipe may be used for inter process communication.

PROP_NONBLOCK

The resulting pipe supports nonblocking I/O.

PROP_SHUTDOWN

The resulting pipe supports shutting down transmission in either direction (see close()).

PROP_BUFFERED

The resulting pipe is buffered (usually 4KB).

PROP_BIDIRECTIONAL

The resulting pipe is bi-directional.

PROP_REVERSE

The resulting pipe supports communication "backwards" (but not necessarily "forwards", see PROP_BIDIRECTIONAL).

The default is PROP_NONBLOCK|PROP_BIDIRECTIONAL.

If PROP_BIDIRECTIONAL isn't specified, the read-end is this object, and the write-end is the returned object (unless PROP_REVERSE has been specified, in which case it is the other way around).

The two ends of a bi-directional pipe are indistinguishable.

If the File object this function is called in was open to begin with, it will be closed before the pipe is created.

Calling this function with an argument of 0 is not the same as calling it with no arguments.

Process.create_process(), PROP_IPC, PROP_NONBLOCK, PROP_SHUTDOWN, PROP_BUFFERED, PROP_REVERSE, PROP_BIDIRECTIONAL

File

There are four basic ways to create a Stdio.File object. The first is calling it without any arguments, in which case the you'd have to call open(), connect() or some other method which connects the File object with a stream.

The second way is calling it with a filename and open mode. This is the same thing as cloning and then calling open(), except shorter and faster.

The third way is to call it with descriptorname of "stdin", "stdout" or "stderr". This will open the specified standard stream.

For the advanced users, you can use the file descriptors of the systems (note: emulated by pike on some systems - like NT). This is only useful for streaming purposes on unix systems. This is not recommended at all if you don't know what you're into. Default mode for this is "rw".

Open mode will be filtered through the system UMASK. You might need to use chmod() later.

open(), connect(), Stdio.FILE,

This function takes a clone of Stdio.File and assigns all variables of this file from it. It can be used together with dup() to move files around.

dup()

File Fd

This function returns a clone of Stdio.File with all variables copied from this file.

All variables, even id, are copied.

assign()

File

Close the file. Optionally, specify "r", "w" or "rw" to close just the read, just the write or both read and write directions of the file respectively.

An exception is thrown if an I/O error occurs.

Nonzero is returned if the file wasn't open in the specified direction, zero otherwise.

This function will not call the close_callback.

open, open_socket

These functions set the various callbacks, which will be called when various events occur on the stream. A zero as argument will remove the callback.

A Pike.Backend object is responsible for calling the callbacks. It requires a thread to be waiting in it to execute the calls. That means that only one of the callbacks will be running at a time, so you don't need mutexes between them.

Unless you've specified otherwise with the set_backend function, the default backend Pike.DefaultBackend will be used. It's normally activated by returning -1 from the main function and will then execute in the main thread.

When data arrives on the stream, read_cb will be called with some or all of that data as the second argument.

When the stream has buffer space over for writing, write_cb will be called so that you can write more data to it.

When out-of-band data arrives on the stream, read_oob_cb will be called with some or all of that data as the second argument.

When the stream allows out-of-band data to be sent, write_oob_cb will be called so that you can write more out-of-band data to it.

When the stream has been shut down, either due to an error or a close from the other end, close_cb will be called. errno will return the error that has occurred or zero in the case of a normal close. Note that close_cb will not be called for a local close, neither by a call to close or by destructing this object.

All callbacks will receive the id set by set_id as first argument.

If a callback returns -1, no other callback or call out will be called by the backend in that round. I.e. the caller of the backend will get control back right away. For the default backend that means it will immediately start another round and check files and call outs anew.

These functions do not set the file nonblocking.

Callbacks are also set by set_nonblocking().

After a callback has been called, it's disabled until it has accessed the stream accordingly, i.e. the write_cb callback is disabled after it's been called until something has been written with write, and the write_oob_cb callback is likewise disabled until something has been written with write_oob. Since the data already has been read when the read callbacks are called, this effect is not noticeable for them.

Installing callbacks means that you will start doing I/O on the stream from the thread running the backend. If you are running these set functions from another thread you must be prepared that the callbacks can be called immediately by the backend thread, so it might not be safe to continue using the stream in this thread.

Because of that, it's useful to talk about "callback mode" when any callback is installed. In callback mode the stream should be seen as "bound" to the backend thread. For instance, it's only the backend thread that reliably can end callback mode before the stream is "handed over" to another thread.

Callback mode has nothing to do with nonblocking mode - although the two often are used together they don't have to be.

The file object will stay referenced from the backend object as long as there are callbacks that can receive events.

Setting a close callback without a read callback currently only works when there's no risk of getting more data on the stream. Otherwise the close callback will be silently deregistered if data arrives.

set_nonblocking(), set_id(), set_backend, query_read_callback, query_write_callback, query_read_oob_callback, query_write_oob_callback, query_close_callback

``
``
``
``
``

These functions return the currently installed callbacks for the respective events.

set_nonblocking(), set_read_callback, set_write_callback, set_read_oob_callback, set_write_oob_callback, set_close_callback

This function sets the id of this file. The id is mainly used as an identifier that is sent as the first argument to all callbacks. The default id is 0 (zero). Another possible use of the id is to hold all data related to this file in a mapping or array.

query_id()

This function returns the id that has been set with set_id().

set_id()

This function sets a stream to nonblocking mode and installs the specified callbacks. See the set_*_callback functions for details about them. If no arguments are given, the callbacks will be cleared.

As opposed to calling the set callback functions separately, this function will set all the callbacks and nonblocking mode atomically so that no callback gets called in between. That avoids races in case the backend is executed by another thread.

Out-of-band data was not be supported on Pike 0.5 and earlier, and not on Pike 0.6 through 7.4 if they were compiled with the option '--without-oob'.

set_blocking(), set_read_callback(), set_write_callback(), set_read_oob_callback(), set_write_oob_callback(), set_close_callback() set_nonblocking_keep_callbacks(), set_blocking_keep_callbacks()

``
``
``
``
``
``
``
``

This function clears all callbacks and sets a stream to blocking mode. i.e. reading, writing and closing will wait until data has been transferred before returning.

The callbacks are cleared and blocking mode is set in one atomic operation, so no callback gets called in between if the backend is running in another thread.

Even so, if the stream is in callback mode (i.e. if any callbacks are installed) then only the backend thread can use this function reliably; it might otherwise already be running in a callback which is about to call e.g. write when the stream becomes blocking.

set_nonblocking(), set_nonblocking_keep_callbacks(), set_blocking_keep_callbacks()

Toggle between blocking and nonblocking, without changing the callbacks.

set_nonblocking(), set_blocking()

Gets/sets term attributes. The returned value/the attr parameter is a mapping on the form

- -1 "ispeed"

In baud rate.

- -1 "ospeed"

Out baud rate.

- -1-1 5 8 "csize"

Character size.

- "rows"

Terminal rows.

- "columns"

Terminal columns.

- 0 1 flag_name

The value of a named flag. The flag name is the string describing the termios flags (IGNBRK, BRKINT, IGNPAR, PARMRK, INPCK, ISTRIP, INLCR, IGNCR, ICRNL, IUCLC, IXON, IXANY, IXOFF, IMAXBEL, OPOST, OLCUC, ONLCR, OCRNL, ONOCR, ONLRET, OFILL, OFDEL, OXTABS, ONOEOT, CSTOPB, CREAD, PARENB, PARODD, HUPCL, CLOCAL, CRTSCTS, ISIG, ICANON, XCASE, ECHO, ECHOE, ECHOK, ECHONL, ECHOCTL, ECHOPRT, ECHOKE, FLUSHO, NOFLSH, TOSTOP, PENDIN). See the manpage for termios or other documentation for more information. All flags are not available on all platforms.

- 0 255 character_name

Sets the value of a control character (VINTR, VQUIT, VERASE, VKILL, VEOF, VTIME, VMIN, VSWTC, VSTART, VSTOP, VSUSP, VEOL, VREPRINT, VDISCARD, VWERASE, VLNEXT, VEOL2). All control characters are not available on all platforms.

Negative values are not allowed as indata, but might appear in the result from tcgetattr when the actual value is unknown. tcsetattr returns 0 if failed.

The argument when to tcsetattr describes when the changes are to take effect:

"TCSANOW"

The change occurs immediately (default).

"TCSADRAIN"

The change occurs after all output has been written.

"TCSAFLUSH"

The change occurs after all output has been written, and empties input buffers.

// setting the terminal in raw mode: Stdio.stdin->tcsetattr((["ECHO":0,"ICANON":0,"VMIN":0,"VTIME":0]));

Unknown flags are ignored by tcsetattr(). tcsetattr always changes the attribute, so only include attributes that actually should be altered in the attribute mapping.

Terminal rows and columns setting by tcsetattr() is not currently supported.

Read data from a file or a stream.

Attempts to read len bytes from the file, and return it as a string. Less than len bytes can be returned if:

end-of-file is encountered for a normal file, or

it's a stream that has been closed from the other end, or

it's a stream in nonblocking mode, or

it's a stream and not_all is set, or

not_all isn't set and an error occurred (see below).

If not_all is nonzero, read() will not try its best to read as many bytes as you have asked for, but will merely return as much as the system read function will return. This mainly useful with stream devices which can return exactly one row or packet at a time. If not_all is used in blocking mode, read() will only block if there's no data at all available.

If something goes wrong and not_all is set, zero will be returned. If something goes wrong and not_all is zero or left out, then either zero or a string shorter than len is returned. If the problem persists then a later call to read() will fail and return zero, however.

If everything went fine, a call to errno() directly afterwards will return zero. That includes an end due to end-of-file or remote close.

If no arguments are given, read() will read to the end of the file or stream.

It's not necessary to set not_all to avoid blocking reading when nonblocking mode is used.

When at the end of a file or stream, repeated calls to read() will return the empty string since it's not considered an error. The empty string is never returned in other cases, unless nonblocking mode is used or len is zero.

read_oob(), write()

0 1

Check if there is data available to read, or wait some time for available data to read.

Returns 1 if there is data available to read, 0 (zero) if there is no data available, and -1 if something went wrong.

errno(), read()

The function may be interrupted prematurely of the timeout (due to signals); check the timing manually if this is imporant.

-1
1
-1
1

Attempts to read len bytes of out-of-band data from the stream, and returns it as a string. Less than len bytes can be returned if:

the stream has been closed from the other end, or

nonblocking mode is used, or

not_all is set, or

not_all isn't set and an error occurred (see below).

If not_all is nonzero, read_oob() will only return as many bytes of out-of-band data as are currently available.

If something goes wrong and not_all is set, zero will be returned. If something goes wrong and not_all is zero or left out, then either zero or a string shorter than len is returned. If the problem persists then a later call to read_oob() will fail and return zero, however.

If everything went fine, a call to errno() directly afterwards will return zero. That includes an end due to remote close.

If no arguments are given, read_oob() will read to the end of the stream.

Out-of-band data was not be supported on Pike 0.5 and earlier, and not on Pike 0.6 through 7.4 if they were compiled with the option '--without-oob'.

It is not guaranteed that all out-of-band data sent from the other end will be received. Most streams only allow for a single byte of out-of-band data at a time.

It's not necessary to set not_all to avoid blocking reading when nonblocking mode is used.

When at the end of a file or stream, repeated calls to read() will return the empty string since it's not considered an error. The empty string is never returned in other cases, unless nonblocking mode is used or len is zero.

read(), write_oob()

0 1

Write data to a file or a stream.

Writes data and returns the number of bytes that were actually written. It can be less than the size of the given data if

some data was written successfully and then something went wrong, or

nonblocking mode is used and not all data could be written without blocking.

-1 is returned if something went wrong and no bytes were written. If only some data was written due to an error and that error persists, then a later call to write() will fail and return -1.

If everything went fine, a call to errno() directly afterwards will return zero.

If data is an array of strings, they will be written sequence.

If more than one argument is given, sprintf() will be used to format them using format. If format is an array, the strings in it are concatenated and the result is used as format string.

Writing of wide strings is not supported. You have to encode the data somehow, e.g. with string_to_utf8 or with one of the charsets supported by Locale.Charset.encoder.

read(), write_oob()

Write out-of-band data to a stream.

Writes out-of-band data to a stream and returns how many bytes that were actually written. It can be less than the size of the given data if some data was written successfully and then something went wrong.

-1 is returned if something went wrong and no bytes were written. If only some data was written due to an error and that error persists, then a later call to write_oob() will fail and return -1.

If everything went fine, a call to errno() directly afterwards will return zero.

If more than one argument is given, sprintf() will be used to format them.

Out-of-band data was not be supported on Pike 0.5 and earlier, and not on Pike 0.6 through 7.4 if they were compiled with the option '--without-oob'.

It is not guaranteed that all out-of-band data sent from the other end will be received. Most streams only allow for a single byte of out-of-band data at a time. Some streams will send the rest of the data as ordinary data.

read_oob(), write()

If this file has been created by calling openpt(), return the filename of the associated pts-file. This function should only be called once.

This function is only available on some platforms.

Close a file or stream.

If direction is not specified, both the read and the write direction will be closed. Otherwise only the directions specified will be closed.

Nonzero is returned if the file or stream wasn't open in the specified direction, zero otherwise.

An exception is thrown if an I/O error occurs.

close() has no effect if this file object has been associated with an already opened file, i.e. if open() was given an integer as the first argument.

open(), open_socket()

Open a file, or use an existing fd.

If filename is given, attempt to open the named file. If fd is given instead, it should be the file descriptor for an already opened file, which will then be used by this object.

mode describes how the file will be opened. It's a case-insensitive string consisting of one or more of the following letters:

Open for reading.

Open for writing.

Append new data to the end.

Create the file if it doesn't exist already.

Truncate the file to zero length if it already contains data. Use only together with "w".

Open exclusively - the open will fail if the file already exists. Use only together with "c". Note that it's not safe to assume that this is atomic on some systems.

access specifies the permissions to use if a new file is created. It is a UNIX style permission bitfield:

User has read permission.

User has write permission.

User has execute permission.

Group has read permission.

Group has write permission.

Group has execute permission.

Others have read permission.

Others have write permission.

Others have execute permission.

It's system dependent on which of these bits that are actually heeded. If access is not specified, it will default to 00666, but note that on UNIX systems it's masked with the process umask before use.

close()

Open the master end of a pseudo-terminal pair.

This function returns 1 for success, 0 otherwise.

grantpt()

Flush buffers to disk.

Returns 0 (zero) and sets errno on failure.

Returns 1 on success.

0
1

Seek to a specified offset in a file.

If mult or add are specified, pos will be calculated as pos = unit*mult + add.

If pos is negative it will be relative to the start of the file, otherwise it will be an absolute offset from the start of the file.

Returns the new offset, or -1 on failure.

The arguments mult and add are considered obsolete, and should not be used.

tell()

Returns the current offset in the file.

seek()

Truncate a file.

Truncates the file to the specified length length.

Returns 1 on success, and 0 (zero) on failure.

open()

0
1

Get status for an open file.

This function returns the same information as the function file_stat(), but for the file it is called in. If file is not an open file, 0 (zero) will be returned. Zero is also returned if file is a pipe or socket.

See file_stat() for a description of the return value.

Prior to Pike 7.1 this function returned an array(int).

file_stat()

Stat

Return the errno for the latest failed file operation.

Returns the open mode for the file.

0x1000

FILE_READ

0x2000

FILE_WRITE

0x4000

FILE_APPEND

0x8000

FILE_CREATE

0x0100

FILE_TRUNC

0x0200

FILE_EXCLUSIVE

0x0400

FILE_NONBLOCKING

0x0800

FILE_SET_CLOSE_ON_EXEC

0x0001

FILE_HAS_INTERNAL_REF

0x0002

FILE_NO_CLOSE_ON_DESTRUCT

0x0004

FILE_LOCK_FD

0x0010

FILE_NOT_OPENED

open()

Set the backend used for the callbacks.

The backend keeps a reference to this object only when it is in callback mode. So if this object hasn't got any active callbacks and it runs out of other references, it will still be destructed quickly (after closing, if necessary).

Also, this object does not keep a reference to the backend.

query_backend, set_nonblocking, set_read_callback, set_write_callback

Pike.Backend

Return the backend used for the callbacks.

set_backend

Pike.Backend

Sets this file to nonblocking operation.

Nonblocking operation is not supported on all Stdio.File objects. Notably it is not guaranteed to be supported on objects returned by pipe() unless PROP_NONBLOCK was specified in the call to pipe().

set_blocking()

Sets this file to blocking operation.

This is the inverse operation of set_nonblocking().

set_nonblocking()

Marks the file as to be closed in spawned processes.

This function determines whether this file will be closed when calling exec().

Default is that the file WILL be closed on exec except for stdin, stdout and stderr.

Process.create_process(), exec()

0 1

Returns true if the file is open.

Most methods can't be called for a file descriptor that isn't open. Notable exceptions errno, mode, and the set and query functions for callbacks and backend.

Returns the file descriptor number associated with this object.

Returns the file descriptor number associated with this object, in addition to releasing it so that this object behaves as if closed. Other settings like callbacks and backend remain intact. take_fd can later be used to reinstate the file descriptor so that the state is restored.

query_fd(), take_fd()

Rehooks the given file descriptor number to be associated with this object. As opposed to using open with a file descriptor number, it will be closed by this object upon destruct or when close is called.

release_fd()

Set internal socket buffer.

This function sets the internal buffer size of a socket or stream.

The second argument allows you to set the read or write buffer by specifying "r" or "w".

It is not guaranteed that this function actually does anything, but it certainly helps to increase data transfer speed when it does.

open_socket(), accept()

Stdio.File
Stdio.File

Duplicate a file over another.

This function works similarly to assign(), but instead of making the argument a reference to the same file, it creates a new file with the same properties and places it in the argument.

assign(), dup()

Stdio.File
Stdio.Fd
0
1
0 1
0
1

Open a UNIX domain socket connection to the specified destination.

In nonblocking mode, success is indicated with the write-callback, and failure with the close-callback or the read_oob-callback.

Returns 1 on success, and 0 on failure.

In nonblocking mode 0 (zero) may be returned and errno() set to EWOULDBLOCK or WSAEWOULDBLOCK. This should not be regarded as a connection failure.

0
1

Open a TCP/IP connection to the specified destination.

In nonblocking mode, success is indicated with the write-callback, and failure with the close-callback or the read_oob-callback.

Returns 1 on success, and 0 on failure.

In nonblocking mode 0 (zero) may be returned and errno() set to EWOULDBLOCK or WSAEWOULDBLOCK. This should not be regarded as a connection failure.

0
1
0
1

Get address and port of a socket end-point.

If the argument local is not specified, or is 0 (zero), the remote end-point will be returned. Otherwise, if local is 1, the local end-point will be returned.

This function returns the address and port of a socket end-point on the form "x.x.x.x port" (IPv4) or "x:x:x:x:x:x:x:x port" (IPv6).

If this file is not a socket, is not connected, or some other error occurrs, 0 (zero) will be returned.

connect()

0 1

Write some data to a file.

If data is not a string, it will be casted to string, and then written to the file.

Throws an error if not all data could be written.

write()

Stdio.File
Stdio.File

See open().

open()

in

Starts a thread that asynchronously copies data from from to this file.

Stdio.sendfile()

Stdio.File

Makes an exclusive file lock on this file.

trylock()

Stdio.FileLockKey
0 1
Stdio.FileLockKey

Attempts to place a file lock on this file.

lock()

Stdio.FileLockKey
0 1
Stdio.FileLockKey

Handles listening to socket ports. Whenever you need a bound socket that is open and listens for connections you should use this program.

_port

If the first argument is other than "stdin" the arguments will be passed to bind().

When create is called with "stdin" as the first argument, a socket is created out of the file descriptor 0. This is only useful if it actually is a socket to begin with.

bind

``
``
"stdin"
"stdin"
``

This function completes a connection made from a remote machine to this port. It returns a two-way stream in the form of a clone of Stdio.File. The new file is by initially set to blocking mode.

Stdio.File

File

This function sets the id used for accept_callback by this port. The default id is this_object().

query_id

This function returns the id for this port. The id is normally the first argument to accept_callback.

set_id

If the last call done on this port failed, errno will return an integer describing what went wrong. Refer to your unix manual for further information.

This function does the same as port->bind, except that instead of creating a new socket and bind it to a port, it expects that the filedescriptor 'fd' is an already open port.

This function is only for the advanced user, and is generally used when sockets are passed to Pike at exec time.

bind, accept

``

Bind opens a socket and binds it to port number on the local machine. If the second argument is present, the socket is set to nonblocking and the callback funcition is called whenever something connects to it. The callback will receive the id for this port as argument. Bind returns 1 on success, and zero on failiure.

If the optional argument 'ip' is given, bind will try to bind to this ip name or number.

accept

``

Bind opens a Unix domain socket at the filesystem location path. If the second argument is present, the socket is set to nonblocking and the callback funcition is called whenever something connects to it. The callback will receive the id for this port as argument.

1 on success, and zero on failiure.

this function is only available on systems that support Unix domain sockets.

accept

``

Closes the socket.

Stdio.File

Document this function.

Set the backend used for the accept callback.

The backend keeps a reference to this object as long as the port is accepting connections, but this object does not keep a reference to the backend.

query_backend

Pike.Backend

Return the backend used for the accept callback.

set_backend

Pike.Backend

Stdio.FILE is a buffered version of Stdio.File, it inherits Stdio.File and has most of the functionality of Stdio.File. However, it has an input buffer that allows line-by-line input.

It also has support for automatic charset conversion for both input and output (see Stdio.FILE()->set_charset()).

The output part of Stdio.FILE is currently not buffered.

File

Sets the input and output charset of this file to the specified charset.

The default charset is "ISO-8859-1".

Read one line of input with support for input conversion.

This function returns the line read if successful, and 0 if no more lines are available.

ngets(), read(), line_iterator(), set_charset()

Get n lines.

Number of lines to get, or all remaining if zero.

1

Same as Stdio.File()->pipe().

Returns an Stdio.File object, NOT a Stdio.FILE object.

File

Write what with support for output_conversion.

Stdio.File()->write()

This function does approximately the same as: write(sprintf(format,@data)).

write(), sprintf()

Returns an iterator that will loop over the lines in this file.

line_iterator()

Returns an iterator that will loop over the lines in this file. If trim is true, all '\r' characters will be removed from the input.

_get_iterator()

Read bytes (wide-) characters with buffering and support for input conversion.

Stdio.File()->read(), set_charset()

0 1

This function puts a string back in the input buffer. The string can then be read with eg read(), gets() or getchar().

The string must not contain line-feeds.

read(), gets(), getchar()

This function returns one character from the input stream.

Returns the ISO-10646 (Unicode) value of the character.

Returns an int and not a string of length 1.

UDP (User Datagram Protocol) handling.

files.UDP

Set this object to nonblocking mode.

If read_cb and extra_args are specified, they will be passed on to set_read_callback().

The called object.

UDP
``
UDP

The read_cb function will receive a mapping similar to the mapping returned by read():

- "data"

Received data.

- "ip"

Data was sent from this IP.

- "port"

Data was sent from this port.

The called object.

read()

``
UDP

Closes an open UDP port.

This method was introduced in Pike 7.5.

0
1

Binds a port for recieving or transmitting UDP.

Set the broadcast flag. If enabled then sockets receive packets sent to a broadcast address and they are allowed to send packets to a broadcast address.

Returns 1 on success, 0 (zero) otherwise.

This is normally only avalable to root users.

0
1

Check for data and wait max. timeout seconds.

Returns 1 if data are ready, 0 (zero) otherwise.

0
1

Read from the UDP socket.

Flag flag is a bitfield, 1 for out of band data and 2 for peek

mapping(string:int|string) in the form ([ "data" : string received data "ip" : string received from this ip "port" : int ...and this port ])

set_read_callback()

Send data to a UDP socket. The recepient address will be to and port will be port.

Flag flag is a bitfield, 1 for out of band data and 2 for don't route flag.

The number of bytes that were actually written.

Sets this object to be blocking.

Establish an UDP connection.

This function connects an UDP socket previously created with Stdio.UDP() to a remote socket. The address is the IP name or number for the remote machine.

Returns 1 on success, 0 (zero) otherwise.

If the socket is in nonblocking mode, you have to wait for a write or close callback before you know if the connection failed or not.

bind(), query_address()

0
1

Returns the local address of a socket on the form "x.x.x.x port". If this file is not a socket, not connected or some other error occurs, zero is returned.

Set the backend used for the read callback.

The backend keeps a reference to this object as long as there can be calls to the read callback, but this object does not keep a reference to the backend.

query_backend

Pike.Backend

Return the backend used for the read callback.

set_backend

Pike.Backend

Returns the error code for the last command on this object. Error code is normally cleared when a command is successful.

Sets socket type and protocol family.

Returns socket type and protocol family.

Document this constant.

Document this constant.

files

An instance of FILE("stderr"), the standard error stream. Use this when you want to output error messages.

predef::werror()

File

An instance of FILE("stdout"), the standatd output stream. Use this when you want to write anything to the standard output.

predef::write()

File

An instance of FILE("stdin"), the standard input stream. Use this when you want to read anything from the standard input. This example will read lines from standard input for as long as there are more lines to read. Each line will then be written to stdout together with the line number. We could use Stdio.stdout.write() instead of just write(), since they are the same function.

int main() { int line; while(string s=Stdio.stdin.gets()) write("%5d: %s\n", line++, s); }

FILE

Read len lines from a file filename after skipping start lines and return those lines as a string. If both start and len are omitted the whole file is read.

read_bytes(), write_file()

Read len number of bytes from the file filename starting at byte start, and return it as a string.

If len is omitted, the rest of the file will be returned.

If start is also omitted, the entire file will be returned.

Throws an error if filename isn't a regular file.

Returns 0 (zero) on failure to open filename.

Returns a string with the requested data otherwise.

read_file, write_file(), append_file()

Write the string str onto the file filename. Any existing data in the file is overwritten.

For a description of access, see Stdio.File()->open().

Throws an error if filename couldn't be opened for writing.

Returns the number of bytes written.

append_file(), read_bytes(), Stdio.File()->open()

Append the string str onto the file filename.

For a description of access, see Stdio.File->open().

Throws an error if filename couldn't be opened for writing.

Returns the number of bytes written.

write_file(), read_bytes(), Stdio.File()->open()

Give the size of a file. Size -1 indicates that the file either does not exist, or that it is not readable by you. Size -2 indicates that it is a directory.

file_stat(), write_file(), read_bytes()

Append relative paths to an absolute path and remove any "//", "../" or "/." to produce a straightforward absolute path as a result.

"../" is ignorded in the relative paths if it makes the created path begin with something else than the absolute path (or so far created path).

Warning: This does not work on NT. (Consider paths like: k:/fnord)

combine_path()

Returns a canonic representation of path (without /./, /../, // and similar path segments).

This function prints a message to stderr along with a description of what went wrong if available. It uses the system errno to find out what went wrong, so it is only applicable to IO errors.

werror()

Check if a path is a file.

Returns true if the given path is a file, otherwise false.

exist(), is_dir(), is_link(), file_stat()

Check if a path is a directory.

Returns true if the given path is a directory, otherwise false.

exist(), is_file(), is_link(), file_stat()

Check if a path is a symbolic link.

Returns true if the given path is a symbolic link, otherwise false.

exist(), is_dir(), is_file(), file_stat()

Check if a path exists.

Returns true if the given path exists (is a directory or file), otherwise false.

May fail with eg errno() EFBIG if the file exists, but the filesystem doesn't support the file size.

is_dir(), is_file(), is_link(), file_stat()

Copies the file from to the new position to. If there is no system function for cp, a new file will be created and the old one copied manually in chunks of 65536 bytes.

Returns nonzero if the given paths are files with identical content, returns zero otherwise. Zero is also returned for any sort of I/O error.

Copy a file asynchronously.

This function is similar to cp(), but works asynchronously.

Name of file to copy.

Name of file to create or replace with a copy of from.

Function to be called on completion. The first argument will be 1 on success, and 0 (zero) otherwise. The rest of the arguments to callback are passed verbatim from args.

Extra arguments to pass to callback.

For callback to be called, the backend must be active (ie main() must have returned -1, or Pike.DefaultBackend get called in some other way). The actual copying may start before the backend has activated.

Currently the file sizes are not compared, so the destination file (to) may be truncated.

cp(), sendfile()

``

Creates zero or more directories to ensure that the given pathname is a directory.

If a mode is given, it's used for the new directories after being &'ed with the current umask (on OS'es that support this).

Returns zero on failure and nonzero on success.

mkdir()

Remove a file or directory a directory tree.

Returns 0 on failure, nonzero otherwise.

rm

Sends headers followed by len bytes starting at offset from the file from followed by trailers to the file to. When completed callback will be called with the total number of bytes sent as the first argument, followed by args.

Any of headers, from and trailers may be left out by setting them to 0.

Setting offset to -1 means send from the current position in from.

Setting len to -1 means send until from's end of file is reached.

The sending is performed asynchronously, and may complete before or after the function returns.

For callback to be called, the backend must be active (ie main() must have returned -1, or Pike.DefaultBackend get called in some other way).

In some cases, the backend must also be active for any sending to be performed at all.

FIXME: Support for timeouts?

Stdio.File->set_nonblocking()

File
File
File
File
``

Write a message to stderr. Stderr is normally the console, even if the process output has been redirected to a file or pipe.

This function is identical to predef::werror().

predef::werror()

Ought to have support for charset conversion.

Set the provided attributes to on.

Set the provided attributes to off.

Check and return the terminal width.

In Pike 7.4 and earlier this function returned void.

get_number_of_columns

Returns the width of the terminal.

Does not check the width of the terminal.

check_columns

.File
.Terminfo.Termcap

Ought to have support for charset conversion.

``

Clears the bindings.

``
``
``
``

get current output control object

Terminal output controller object

OutputController

get current input control object

Terminal input controller object

InputController

Return the current prompt string.

Set the prompt string.

New prompt string

Terminal attributes

Set text echo on or off.

1 for echo, 0 for no echo.

Document this function

Document this function

Document this function

Document this function

Document this function

Document this function

Document this function

Document this function

Document this function

Document this function

Document this function

Document this function

Document this function

Changes the line to a line from the history d steps from the current entry (0 being the current line, negative values older, and positive values newer).

Only effective if you have a history object.

Document this function

Document this function

Document this function

Print a message to the output device

Document this function

Document this function

Document this function

``

Document this function

Document this function

Document this function

Document this function

History

Document this function

History

Creates a Readline object, that takes input from infd and has output on outfd.

Defaults to Stdio.stdin.

Defaults to Stdio.Terminfo.getTerm().

Defaults to infd, unless infd is 0, in which case outfd defaults to Stdio.stdout.

Defaults to interm.

Termcap terminal description object.

TermMachine

Put termcap string

TermcapDB

Terminfo terminal description object

TermMachine

Document this function

Returns the terminal description object for term from the systems termcap database. Returns 0 if not found.

Stdio.Terminfo.getTerm, Stdio.Terminfo.getTerminfo

Termcap

Returns the terminal description object for term from the systems terminfo database. Returns 0 if not found.

Stdio.Terminfo.getTerm, Stdio.Terminfo.getTermcap

Terminfo

Returns an object describing the terminal term. If term is not specified, it will default to getenv("TERM") or if that fails to "dumb".

Lookup of terminal information will first be done in the systems terminfo database, and if that fails in the termcap database. If neither database exists, a hardcoded entry for "dumb" will be used.

Stdio.Terminfo.getTerminfo, Stdio.Terminfo.getTermcap, Stdio.getFallbackTerm

Termcap

Returns an object describing the fallback terminal for the terminal term. This is usually equvivalent to Stdio.Terminfo.getTerm("dumb").

Stdio.Terminfo.getTerm

Termcap

Returns 1 if Stdio.stdin is connected to an interactive terminal that can handle backspacing, carriage return without linefeed, and the like.

Proxy class that contains stub functions that call the corresponding functions in Fd.

Used by File.

Object to which called functions are relayed.

Fd

Low level I/O operations. Use File instead.

Returns the id of all the active file descriptors.

Receive notification when change occur within the fd. To use, create a Stdio.File object of a directory like Stdio.File(".") and then call notify() with the appropriate parameters.

When a program registers for some notification, only the first notification will be received unless DN_MULTISHOT is specified as part of the notification argument.

At present, this function is Linux-specific and requires a kernel which supports the F_NOTIFY fcntl() call.

What to notify the callback of. See the Stdio.DN_* constants for more information about possible notifications.

Function which should be called when notification is received. The function gets the signal used to indicate the notification as its argument and shouldn't return anyting.

``

Document this constant.

Document this constant.

Document this constant.

Document this constant.

Document this constant.

Document this constant.

Document this constant.

Implementation level of nonblocking I/O OOB support.

0

Nonblocking OOB support is not supported.

1

Nonblocking OOB works a little.

2

Nonblocking OOB almost works.

3

Nonblocking OOB works as intended.

-1

Unknown level of nonblocking OOB support.

This constant only exists when OOB operations are available, i.e. when __HAVE_OOB__ is 1.

Exists and has the value 1 if OOB operations are available.

In Pike 7.5 and later OOB operations are always present.

Used in File.notify() to get a callback when files within a directory are accessed.

Used in File.notify() to get a callback when files within a directory are modified.

Used in File.notify() to get a callback when new files are created within a directory.

Used in File.notify() to get a callback when files are deleted within a directory.

Used in File.notify() to get a callback when files within a directory are renamed.

Used in File.notify() to get a callback when attributes of files within a directory are changed.

Used in File.notify(). If DN_MULTISHOT is used, signals will be sent for all notifications the program has registred for. Otherwise only the first event the program is listening for will be received and then the program must reregister for the events to receive futher events.

This object is used to represent file status information from e.g. file_stat().

It contains the following items usually found in a C struct stat:

File mode (see mknod(2)).

File size in bytes.

User ID of the file's owner.

Group ID of the file's owner.

Time of last access in seconds since 00:00:00 UTC, 1970-01-01.

Time of last data modification.

Time of last file status change.

Inode number.

Number of links.

ID of the device containing a directory entry for this file.

ID of the device.

It also contains some items that correspond to the C IS* macros:

Set if the file is a regular file.

Set if the file is a directory.

Set if the file is a symbolic link. Note that symbolic links are normally followed by the stat functions, so this might only be set if you turn that off, e.g. by giving a nonzero second argument to file_stat().

Set if the file is a FIFO (aka named pipe).

Set if the file is a socket.

Set if the file is a character device.

Set if the file is a block device.

There are also some items that provide alternative representations of the above:

The type as a string, can be any of "reg", "dir", "lnk", "fifo", "sock", "chr", "blk", and "unknown".

The file mode encoded as a string in ls -l style, e.g. "drwxr-xr-x".

Note that some items might not exist or have meaningful values on some platforms.

Additionally, the object may be initialized from or casted to an array on the form of a 'traditional' LPC stat-array, and it's also possible to index the object directly with integers as if it were such an array. The stat-array has this format:

0

File mode, same as mode.

1

If zero or greater, the file is a regular file and this is its size in bytes. If less than zero it gives the type: -2=directory, -3=symlink and -4=device.

2

Time of last access, same as atime.

3

Time of last data modification, same as mtime.

4

Time of last file status change, same as ctime.

5

User ID of the file's owner, same as uid.

6

Group ID of the file's owner, same as gid.

It's possible to modify the stat struct by assigning values to the items. They essentially work as variables, although some of them affect others, e.g. setting isdir clears isreg and setting mode_string changes many of the other items.

A new Stdio.Stat object can be initialized in two ways:

stat is an object, typically another Stdio.Stat. The stat info is copied from the object by getting the values of mode, size, atime, mtime, ctime, uid, gid, dev, ino, nlink, and rdev.

stat is a seven element array on the 'traditional' LPC stat-array form (see the class doc).

Construct a PKCS-1 digestinfo

message to digest

crypto hash object such as Crypto.SHA or Crypto.MD5

Crypto.Hash

Various ASN.1 identifiers used by PKCS.

Standards.ASN1.Types

RSA operations and types as described in PKCS-1.

Standards.ASN1.Types

Create a DER-coded RSAPublicKey structure

Crypto.RSA object

ASN1 coded RSAPublicKey structure

Crypto.RSA

Create a DER-coded RSAPrivateKey structure

Crypto.RSA object

ASN1 coded RSAPrivateKey structure

Crypto.RSA

Decode a DER-coded RSAPublicKey structure

RSAPublicKey provided in ASN1 encoded format

Crypto.RSA object

Crypto.RSA

Decode a DER-coded RSAPrivateKey structure

RSAPrivateKey provided in ASN1 encoded format

Crypto.RSA object

Crypto.RSA

DSA operations as defined in RFC-2459.

Standards.ASN1.Types
Crypto.DSA
Sequence
Crypto.DSA
Crypto.DSA
Crypto.DSA

Handle PKCS-6 and PKCS-10 certificates and certificate requests.

Standards.ASN1.Types
.Identifiers
Sequence

Return the certificate issuer RDN from a certificate string.

A string containing an X509 certificate.

Note that the certificate normally must be decoded using MIME.decode_base64.

An Standards.ASN1.Sequence object containing the certificate issuer Distinguished Name (DN).

Sequence

Converts an RDN (relative distinguished name) Seqeunce object to a human readable string in X500 format.

A string containing an X509 certificate.

Note that the certificate normally must be decoded using MIME.decode_base64.

A string containing the certificate issuer Distinguished Name (DN) in human readable X500 format.

We don't currently handle attributes with multiple values, not all attribute types are understood.

Sequence

Return the certificate subject RDN from a certificate string.

A string containing an X509 certificate.

Note that the certificate normally must be decoded using MIME.decode_base64.

An Standards.ASN1.Sequence object containing the certificate subject Distinguished Name (DN).

Sequence

Handling of Certifikate Signing Requests (PKCS-10)

Standards.ASN1.Types
Crypto.RSA
Sequence

Helper module for generating Windows Installer XML structures.

Parser.XML.Tree.SimpleNode

Modifies dir if it contains files at the root level.

Directory
WixNode

Decodes a DER object.

Primitive unconstructed ASN1 data type.

Types.Object

get raw encoded contents of object

get tag

get class

constructed type

Types.Object

raw encoded contents

elements of object

get tag

get class

.Types

an instance of ADT.struct

a mapping from combined tag numbers to classes from or derived from Standards.ASN1.Types. Combined tag numbers may be generated using Standards.ASN1.Types.make_combined_tag.

an object from Standards.ASN1.Types or either Standards.ASN1.Decode.primitive or Standards.ASN1.Decode.constructed if the type is unknown. Throws an exception if the data could not be decoded.

Handling of implicit and explicit ASN.1 tagging, as well as other context dependence, is next to non_existant.

ADT.struct
Object

decode a DER encoded object using universal data types

a DER encoded object

an object from Standards.ASN1.Types or either Standards.ASN1.Decode.primitive or Standards.ASN1.Decode.constructed if the type is unknown.

Object

Encodes various asn.1 objects according to the Distinguished Encoding Rules (DER)

Generic, abstract base class for ASN1 data types.

Get the class of this object.

The class of this object.

Get the tag for this object.

The tag for this object.

Get the combined tag (tag + class) for this object.

the combined tag header

Get the DER encoded version of this object.

DER encoded representation of this object.

Compound object primitive

Object

contents of compound object, elements are from Standards.ASN1.Types

Object

string object primitive

Object

value of object

boolean object

Object

value of object

Integer object All integers are represented as bignums, for simplicity

Object

value of object

Gmp.mpz

Enumerated object

Integer

Bit string object

Object

value of object

Set the bitstring value as a string with "1" and "0".

this_program

Sets the length of the bit string to len number of bits.

Octet string object

String

Null object

Object

Object identifier object

Object

value of object

Returns a new Identifier object with args appended to the ID path.

this_program

UTF8 string object

Character set: ISO/IEC 10646-1 (compatible with Unicode).

Variable width encoding, see rfc2279.

String

Sequence object

Compound

Set object

Compound

PrintableString object

String

TeletexString object

Avoid this one; it seems to be common that this type is used to label strings encoded with the ISO 8859-1 character set (use asn1_broken_teletex_string for that). From http://www.mindspring.com/~asn1/nlsasn.htm:

/.../ Types GeneralString, VideotexString, TeletexString (T61String), and GraphicString exist in earlier versions [pre-1994] of ASN.1. They are considered difficult to use correctly by applications providing national language support. Varying degrees of application support for T61String values seems to be most common in older applications. Correct support is made more difficult, as character values available in type T61String have changed with the addition of new register entries from the 1984 through 1997 versions.

This implementation is based on the description of T.61 and T.51 in "Some functions for representing T.61 characters from the X.500 Directory Service in ISO 8859 terminals (Version 0.2. July 1994.)" by Enrique Silvestre Mora (mora@si.uji.es), Universitat Jaume I, Spain, found in the package ftp://pereiii.uji.es/pub/uji-ftp/unix/ldap/iso-t61.translation.tar.Z

The translation is only complete for 8-bit latin 1 strings. It encodes strictly to T.61, but decodes from the superset T.51.

String

(broken) TeletexString object

Encodes and decodes latin1, but labels it TeletexString, as is common in many broken programs (e.g. Netscape 4.0X).

String

IA5 String object

Character set: ASCII. Fixed width encoding with 1 octet per character.

String
String
String

Universal String object

Character set: ISO/IEC 10646-1 (compatible with Unicode). Fixed width encoding with 4 octets per character.

The encoding is very likely UCS-4, but that's not yet verified.

OctetString

BMP String object

Character set: ISO/IEC 10646-1 (compatible with Unicode). Fixed width encoding with 2 octets per character.

FIXME: The encoding is very likely UCS-2, but that's not yet verified.

OctetString

Meta-instances handle a particular explicit tag and set of types.

document me!

Combines tag and class as a single integer, in a somewhat arbitrary way. This works also for tags beyond 31 (although not for tags beyond 2^30.

ASN1 type class

ASN1 type tag

combined tag

Standards.ASN1.Types.extract_tag Standards.ASN1.Types.extract_cls

extract ASN1 type tag from a combined tag

Standards.ASN1.Types.make_combined_tag

extract ASN1 type class from a combined tag

Standards.ASN1.Types.make_combined_tag

Checks if a Pike string can be encoded with UTF8. That is always the case...

1
1

Checks if a Pike string can be encoded as a PrintableString.

0
1
0
1
0
1
0
1
0
0
0
1

This module implements various algorithms specified by the Internationalizing Domain Names in Applications (IDNA) memo by the Internet Engineering Task Force (IETF), see ftp://ftp.rfc-editor.org/in-notes/rfc3490.txt.

Punycode transcoder, see ftp://ftp.rfc-editor.org/in-notes/rfc3492.txt. Punycode is used by to_ascii as an "ASCII Compatible Encoding" when needed.

Prepare a Unicode string for ACE transcoding. Used by to_ascii. Nameprep is a profile of Stringprep, which is described in RFC 3454.

The string to prep.

Set this flag the the string to transform is a "query string", and not a "stored string". See RFC 3454.

0 1

The to_ascii operation takes a sequence of Unicode code points that make up one label and transforms it into a sequence of code points in the ASCII range (0..7F). If to_ascci succeeds, the original sequence and the resulting sequence are equivalent labels.

The sequence of Unicode code points to transform.

Set this flag if the the string to transform is a "query string", and not a "stored string". See RFC 3454.

Set this flag to enforce the restrictions on ASCII characters in host names imposed by STD3.

0 1
0 1

The to_unicode operation takes a sequence of Unicode code points that make up one label and returns a sequence of Unicode code points. If the input sequence is a label in ACE form, then the result is an equivalent internationalized label that is not in ACE form, otherwise the original sequence is returned unaltered.

The sequence of Unicode code points to transform.

Takes a sequence of labels separated by '.' and applies to_ascii on each.

0 1
0 1

Takes a sequence of labels separated by '.' and applies to_unicode on each.

This module implements EXIF (Exchangeable image file format for Digital Still Cameras) 2.2 parsing.

Retrieve the EXIF properties of the given file.

The Stdio.File object containing wanted EXIF properties.

A mapping with all found EXIF properties.

Stdio.File

This class implements URI parsing and resolving of relative references to absolute form, as defined in RFC 2396

Scheme component of URI

Authority component of URI (formerly called net_loc, from RFC 2396 known as authority)

Path component of URI. May be empty, but not undefined.

Query component of URI. May be 0 if not present.

The fragment part of URI. May be 0 if not present.

Certain classes of URI (e.g. URL) may have these defined

If no port number is present in URI, but the scheme used has a default port number, this number is put here.

The base URI object, if present

this_program

Compare this URI to something, in a canonical way.

Compare the URI to this

Reparse the URI with respect to a new base URI. If no base_uri was supplied, the old base_uri is thrown away. The resolving is performed according to the guidelines outlined by RFC 2396, Uniform Resource Identifiers (URI): Generic Syntax.

Set the new base URI to this.

URI

When supplied, will root the URI a the given location. This is needed to correctly verify relative URIs, but may be left out otherwise. If left out, and uri is a relative URI, an error is thrown.

When uri is another URI object, the created URI will inherit all properties of the supplied uri except, of course, for its base_uri.

URI
URI
URI
URI
URI

Assign a new value to a property of URI

When any of the following properties are used, properties that depend on them are recalculated: user, password, host, port, authority, base_uri.

The value to assign to property

When cast to string, return the URI (in a canonicalized form). When cast to mapping, return a mapping with scheme, authority, user, password, host, port, path, query, fragment, raw_uri, base_uri as documented above.

Returns path and query part of the URI if present.

ID3 decoder/encoder. Supports versions 1.0, 1.1, 2.2-2.4. For more info see http://www.id3.org

Note that this implementation is far from complete and that interface changes might be neccessary during the implementation of the full standard.

A wrapper around a Stdio.File object that provides a read limit capability.

Stdio.File
Stdio.File

Read bytes bytes from the buffer. Throw an exception if bytes is bigger than the number of bytes left in the buffer before reaching the limit set by set_limit.

Preview the next byte. Technically it is read from the encapsulated buffer and put locally to avoid seeking.

Set an artificial EOF bytes bytes further into the buffer.

The number of bytes left before reaching the limit set by set_limit.

Represents an ID3v2 header.

Buffer

Decode a tag header from buffer and store its data in this object.

Buffer

Encode the data in this tag and return as a string.

Should the unsynchronisation flag be set or not?

Frame
0
1
Buffer
Buffer

Abstract class for frame data.

Is the content altered?

0
1

ID3 version 2 (2.2, 2.3, 2.4) Tags

Buffer Stdio.File
0 1

ID3 version 1.0 or 1.1 tag. This is really a clumsy way of reading ID3v1 tags, but it has the same interface as the v2 reader.

This is a ID3 tag super object, which encapsulates all versions ID3 tags. This is useful if you are only interested in the metadata of a file, and care not about how it is stored or have no interest in changing the data.

Version 1 tag is searched only if version 2 isn't found.

Tagv2, Tagv1

The file object fd is searched for version 2 tags, and if not found, version 1 tags.

If no tag was found in the file an error is thrown.

Stdio.File

The index operators are overloaded to index the encapsulated Tagv1 or Tagv2 object.

The version of the encapsulated tag in the form "%d.%d.%d".

Indices will return the indices of the tag object.

Values will return the values of the tag object.

Returns tag values in a mapping. Only tag values that exists in ID3v1.1 is used. Nonexisting or undefined values will not appear in the mapping.

- "artist"

Takes its value from TPE1 or TP1 frames.

- "album"

Takes its value from TALB or TAL frames.

- "title"

Takes its value from TIT2 or TT2 frames.

- "genre"

Takes its value from TCON or TCM frames.

- "year"

Takes its value from TYER or TYE frames.

- "track"

Takes its value from TRCK or TRK frames. The string may be either in the "%d" form or in the "%d/%d" form.

Decodes a synchsafe integer, generated according to ID3v2.4.0-structure section 6.2.

int_to_synchsafe

Encodes a integer to a synchsafe integer according to ID3v2.4.0-structure section 6.2.

synchsafe_to_int

Reverses the effects of unsyncronisation done according to ID3v2.4.0-structure section 6.1.

unsynchronise

Unsynchronises the string according to ID3v2.4.0-structure section 6.1.

resynchronise

Decodes the string in from the type, according to ID3v2.4.0-structure section 4, into a wide string.

encode_string

Encodes the string in to an int-string pair, where the integer is the encoding mode, according to ID3v2.4.0-structure, and the string is the encoded string. This function tries to minimize the size of the encoded string by selecting the most apropriate encoding method.

decode_string, encode_strings

Encodes several strings in the same way as encode_string, but encodes all the strings with the same method, selected as in encode_string. The first element in the resulting array is the selected method, while the following elements are the encoded strings.

decode_string, encode_string

Support for Universal Unique Identifiers (UUID) and Globally Unique Identifiers (GUID).

Represents an UUID

60 bit value representing the time stamp.

Returns the posix time of the UUID.

The version of the UUID.

Returns a string representation of the version, e.g. "Name-based".

The variant of the UUID.

Returns a string representation of the variant, e.g. "IETF draft variant".

The clock sequence. Should be 13 to 15 bits depending on UUID version.

The UUID node. Should be 48 bit.

Validates the current UUID.

Returns the time_low field.

Returns the time_mid field.

Returns the time_hi_and_version field.

Encodes a binary representation of the UUID.

Creates a string representation of the UUID.

Creates a URN representation of the UUID.

Optionally created with a string or binary representation of a UUID.

Returns the internal clock state. Can be used for persistent storage when an application is terminated.

set_clock_state

Sets the internal clock state.

get_clock_state

Creates a new version 1 UUID.

Either the 48 bit IEEE 802 (aka MAC) address of the system or -1.

UUID

Creates a version 3 UUID with a name string and a binary representation of a name space UUID.

UUID

Creates a version 4 (random) UUID.

UUID

Return a new binary UUID.

Returns the string representation of the binary UUID uuid.

Returns the binary representation of the UUID uuid.

Return a new UUID string.

The Nil UUID.

Name space UUID for DNS.

Name space UUID for URL.

Name space UUID for OID.

Name space UUID for X500.

Creates a null UUID object.

UUID

Creates a DNS UUID with the given DNS name.

UUID

Creates a URL UUID with the given URL.

UUID

Creates an OID UUID with the given OID.

UUID

Creates an X500 UUID with the gived X500 address.

UUID

Look up the language name given an ISO 639-2 code in lower case. It will first be looked up in the ISO 639-2/T table and then in ISO 639-2/B if the first lookup failed. Returns zero typed zero on failure.

Look up the language name given an ISO 639-2/T code in lower case. Returns zero typed zero on failure.

Look up the language name given an ISO 639-2/B code in lower case. Returns zero typed zero on failure.

Return a mapping from ISO 639-2/T + ISO 639-2/B codes to language names.

Return a mapping from ISO 639-2/T codes to language names.

Return a mapping from ISO 639-2/B codes to language names.

Converts an ISO 639-2/B code to an ISO 639-2/T code.

Converts an ISO 639-2/T code to an ISO 639-2/B code.

Look up the ISO 639-2/T code given an ISO 639-1 code in lower case.

Look up the ISO 639-1 code given an ISO 639-2/T code in lower case.

Return a mapping from ISO 639-1 code to ISO 639-2/T code.

The Discordian calendar, as described on page 34 in the fourth edition of Principia Discordia.

Chaotic enough, it's quite simpler then the Gregorian calendar; weeks are 5 days, and evens up on a year. Months are 73 days.

The leap day is inserted at the 60th day of the first month (Chaos), giving the first month 74 days. The description of the calendar is a "perpetual date converter from the gregorian to the POEE calendar", so the leap years are the same as the gregorians.

The Principia calls months "seasons", but for simplicity I call them months in this calendar.

If anyone know more about how to treat the leap day - now it is inserted in the month and week where it lands, rather then being separated from month and weeks, I'm interested to know.

- Mirar, Pope of POEE.

.Gregorian

This is the container class for rules.

.Rule.Timezone
this_program
.Rule.Language
this_program

Sets the guess-mapping for timezones. Default is the mapping:

Abbreviation Interpretation UTC AMT America/Manaus UTC-4 AST America/Curacao UTC-4 CDT America/Costa_Rica UTC-5 CST America/El Salvador UTC-6 EST America/Panama UTC-5 GST Asia/Dubai UTC+4 IST Asia/Jerusalem UTC+2 WST Australia/Perth UTC+8

YMD.parse

this_program
.Rule.Language.Rule.Timezone
this_program
this_program
this_program
0
1

Event is an abstract class, defining what methods an Event need to have.

This constant may be used to identify an event object.

This calculates the next or previous occurance of the event, from the given timerange's start, including any event occuring at the start if that flag is set.

It returns zero if there is no next event.

These methods are virtual in the base class.

.TimeRanges.TimeRange
0 1
.TimeRanges.TimeRange
.TimeRanges.TimeRange
0 1
.TimeRanges.TimeRange

This calculates the eventual events that is contained or overlapped by the given timerange. scan uses next, if not overloaded.

Calendar.Event.Easter()->scan(Calendar.Year(2000)) => ({ Day(Sun 23 Apr 2000) })

scan can return an array of overlapping timeranges.

This method must use in->calendar_object->type to create the returned timeranges, and must keep the ruleset.

.TimeRanges.TimeRange
.TimeRanges.TimeRange

Returns a mapping with time ranges mapped to events.

.TimeRanges.TimeRange
.TimeRanges.TimeRange
Event

Joins several events into one SuperEvent.

Event
SuperEvent
Event
SuperEvent

Returns a description of the event.

A non-event.

Event

This constant may be used to identify a NullEvent.

Day_Event is an abstract class, extending Event for events that are single days, using julian day numbers for the calculations.

Event

This constant may be used to identify Day_Event objects.

Returned from scan_jd if the even searched for did not exist.

These methods has to be defined, and is what really does some work. It should return the next or previos julian day (>jd) when the event occurs, or the constant NODAY if it doesn't.

1

Forward (next),

-1

Backward (previous).

.Calendar
-1-1 1 1

Uses the virtual method scan_jd.

Event.next

.TimeRanges.TimeRange
0 1
.TimeRanges.TimeRange

Uses the virtual method scan_jd.

Event.previous

.TimeRanges.TimeRange
0 1
.TimeRanges.TimeRange

This is created by the Namedays classes to represent an event for a name.

Day_Event

This constant may be used to identify Nameday objects.

This contains a ruleset about namedays.

Event

This constant may be used to identify Namedays.

Gives back an array of names that occur during the time period, in no particular order.

.TimeRanges.TimeRange

Gives back an table of days with names that occur during the time period. Note that days without names will not appear in the returned mapping.

.TimeRanges.TimeRange
.TimeRanges.TimeRange

Container for merged Namedays objects.

Event

A set date of year, counting leap day in February, used for the Gregorian fixed events in the events list.

Julian_Fixed

Day_Event

This constant may be used to identify Gregorian_Fixed objects.

1 31
1 12

A set date of year, counting leap day in February, used for the Gregorian fixed events in the events list.

Gregorian_Fixed

Gregorian_Fixed

This constant may be used to identify Julian_Fixed objects.

This class represents the event of a given gregorian date. For instance, Event.Date(12,10)->next(Day()) finds the next 12 of October.

Day_Event

The event is created by a given month day and a month number (1=January, 12=December).

1 31
1 12

This class represents the event that a given gregorian date appears a given weekday. For instance, Event.Date_Weekday(12,10,5)->next(Day()) finds the next 12 of October that is a friday.

Day_Event

The event is created by a given month day, a month number (1=January, 12=December), and a weekday number (1=Monday, 7=Sunday).

The week day numbers used are the same as the day of week in the ISO calendar - the Gregorian calendar has 1=Sunday, 7=Saturday.

This class represents the event that a given gregorian day of month appears a given weekday. For instance, Event.Monthday_Weekday(13,5)->next(Day()) finds the next friday the 13th.

Day_Event

The event is created by a given month day, and a weekday number (1=Monday, 7=Sunday).

The week day numbers used are the same as the day of week in the ISO calendar - the Gregorian calendar has 1=Sunday, 7=Saturday.

This class represents any given weekday. For instance, Event.Weekday(5)->next(Day()) finds the next friday.

These are also available as the pre-defined events Events.monday, Events.tuesday, Events.wednesday, Events.thursday, Events.friday, Events.saturday and Events.sunday.

Day_Event

The event is created by a given weekday number (1=Monday, 7=Sunday).

The week day numbers used are the same as the day of week in the ISO calendar - the Gregorian calendar has 1=Sunday, 7=Saturday.

This class represents an easter.

Day_Event

shift is the year to shift from old to new style easter calculation. Default is 1582.

Calculates the year day for the easter.

This class represents an easter relative event.

Easter

This class represents an orthodox easter relative event.

Easter_Relative

This class represents a monthday weekday relative event or n:th special weekday event, e.g. "fourth sunday before 24 dec" => md=24,mn=12,wd=7,n=-4

Gregorian_Fixed
1 31
1 12
1 7
0 1

This class holds any number of events, and adds the functionality of event flags.

Scanning (scan_events,next,etc) will drop flag information. Dig out what you need with holidays et al first.

Event

Filter out the events that has a certain flag set. Holidays (flag "h") are the days that are marked red in the calendar (non-working days), Flagdays (flag "f") are the days that the flag should be visible in (only some countries).

SuperEvent
SuperEvent
SuperEvent

Event containing information about when a timezone is changed.

Event
.Rule.Timezone
.TimeRanges.TimeRange
.TimeRanges.TimeRange
.Rule.Timezone
.TimeRanges.TimeRange
0 1
.TimeRanges.TimeRange
.Rule.Timezone
.TimeRanges.TimeRange
.TimeRanges.TimeRange

Same as the ISO calendar, but with austrian as the default language.

This calendar exist only for backwards compatible purposes.

.ISO

This module contains listnings of available timezones, in some different ways

This constant is a mapping that can be used to loop over to get all the region-based timezones.

It looks like this:

    ([ "America": ({ "Los_Angeles", "Chicago", [...] }),
       "Europe":  ({ "Stockholm", [...] }),
       [...] }),

Please note that loading all the timezones can take some time, since they are generated and compiled on the fly.

This mapping is used to look up abbreviation to the possible regional zones.

It looks like this:

    ([ "CET": ({ "Europe/Stockholm", [...] }),
       "CST": ({ "America/Chicago", "Australia/Adelaide", [...] }),
       [...] }),

Note this: Just because it's noted "CST" doesn't mean it's a unique timezone. There is about 7 *different* timezones that uses "CST" as abbreviation; not at the same time, though, so the DWIM routines checks this before it's satisfied. Same with some other timezones.

For most timezones, there is a number of region timezones that for the given time are equal. This is because region timezones include rules about local summer time shifts and possible historic shifts.

The YMD.parse functions can handle timezone abbreviations by guessing.

This reads the zone.tab file and returns name of all standard timezones, like "Europe/Belgrade".

This returns the raw respectively parsed zone tab file from the timezone data files.

The parsed format is an array of zone tab line arrays,

    ({ string country_code,
       string position,
       string zone_name,
       string comment })

To convert the position to a Geography.Position, simply feed it to the constructor.

This is the Julian calendar, conjured up by the old Romans when their calendar were just too weird. It was used by the christians as so far as the 18th century in some parts of the world. (Especially the protestantic and orthodox parts.)

Don't confuse the julian day with the Julian calendar. The former is just a linear numbering of days, used in the Calendar module as a common unit for absolute time.

.Gregorian

This is the base class of the calendars.

Give the zero-length time period of the current time.

.TimeRanges.TimeRange

base for all Roman-kind of Calendars, ie, one with years, months, weeks and days

inherits TimeRange

Base (virtual) time period of the Roman-kind of calendar.

Format the object into nice strings;

    iso_ymd        "2000-06-02 (Jun) -W22-5 (Fri)" [2]
    ext_ymd        "Friday, 2 June 2000" [2]
    ymd            "2000-06-02"
    ymd_short      "20000602"
    ymd_xshort     "000602" [1]
    iso_week       "2000-W22"
    iso_week_short "2000W22"
    week           "2000-w22" [2]
    week_short     "2000w22" [2]
    month          "2000-06"
    month_short    "200006" [1]
    iso_time       "2000-06-02 (Jun) -W22-5 (Fri) 00:00:00 UTC+1" [2]
    ext_time       "Friday, 2 June 2000, 00:00:00" [2]
    ctime          "Fri Jun  2 00:00:00 2000\n" [2] [3]
    http           "Fri, 02 Jun 2000 00:00:00 GMT" [4]
    time           "2000-06-02 00:00:00"
    time_short     "20000602 00:00:00"
    time_xshort    "000602 00:00:00"
    iso_short      "2000-06-02T00:00:00"
    mtime          "2000-06-02 00:00"
    xtime          "2000-06-02 00:00:00.000000"
    tod            "00:00:00"
    tod_short      "000000"
    todz           "00:00:00 CET"
    todz_iso       "00:00:00 UTC+1"
    xtod           "00:00:00.000000"
    mod            "00:00"

[1] note conflict (think 1 February 2003)
[2] language dependent
[3] as from the libc function ctime()
[4] as specified by the HTTP standard; not language dependent.

function method int unix_time() Returns the unix time integer corresponding to the start of the time range object. (An unix time integer is UTC.) function method datetime() This gives back a mapping with the relevant time information (representing the start of the period);

         ([ "year":     int        // year number (2000 AD=2000, 1 BC==0)
            "month":    int(1..)   // month of year
            "day":      int(1..)   // day of month
            "yearday":  int(0..)   // day of year
            "week":     int(1..)   // week of year
            "week_day": int(0..)   // day of week
            "timezone": int        // offset to utc, including dst

            "unix":     int        // unix time
            "julian":   int        // julian day
         // for compatibility:
            "hour":     0          // hour of day, including dst
            "minute":   0          // minute of hour
            "second":   0          // second of minute
            "fraction": 0.0        // fraction of second
         ]);

Day of week is compatible with old versions, ie, 0 is sunday, 6 is saturday, so it shouldn't be used to calculate the day of the week with the given week number. Year day is also backwards compatible, ie, one (1) less then from the year_day() function.

Second
Second
Minute
Second
Second
Minute
Minute
Minute
Minute
Minute
Hour
Hour
Hour
Hour
inherits TimeRange
inherits YMD

This is the time period of a year.

"unix"
"julian"

It's possible to create the standard week by using three different methods; either the normal way - from standard unix time or the julian day, and also, for more practical use, from the year number.

Month
Month
Month

The Year type overloads the month() method, so it is possible to get a specified month by string:

year->month("April")

The integer and no argument behavior is inherited from YMD().

Week
Week
Week

The Year type overloads the week() method, so it is possible to get a specified week by name:

year->week("17") year->week("w17")

The integer and no argument behavior is inherited from YMD().

This is useful, since the first week of a year not always (about half the years, in the ISO calendar) is numbered '1'.

The Calendar week represents a standard time period of a week. In the Gregorian calendar, the standard week starts on a sunday and ends on a saturday; in the ISO calendar, it starts on a monday and ends on a sunday.

The week are might not be aligned to the year, and thus the week may cross year borders and the year of the week might not be the same as the year of all the days in the week. The basic rule is that the week year is the year that has the most days in the week, but since week number only is specified in the ISO calendar - and derivates - the week number of most calendars is the week number of most of the days in the ISO calendar, which modifies this rule for the Gregorian calendar; the week number and year is the same as for the ISO calendar, except for the sundays.

When adding, moving and subtracting months to a week, it falls back to using days.

When adding, moving or subtracting years, if tries to place the moved week in the resulting year.

"unix"
"julian"

It's possible to create the standard week by using three different methods; either the normal way - from standard unix time or the julian day, and also, for more practical use, from year and week number.

"unix"
"julian"

It's possible to create the day by using five different methods; either the normal way - from standard unix time or the julian day, and also, for more practical use, from year, month and day, from year and day of year, and from julian day without extra fuzz.

Day
Day
Day

The Week type overloads the day() method, so it is possible to get a specified weekday by string:

week->day("sunday")

The integer and no argument behavior is inherited from YMD().

the weekday-from-string routine is language dependent.

inherits Time.Hour
inherits YMD

global convinience functions

TimeRange

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 dwim 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)
    %d short date (20000304, 000304)
    %a day (needs %y)
    %e weekday (needs %y, %w)
    %h hour (needs %d, %D or %W)
    %m minute (needs %h)
    %s second (needs %m)
    %S seconds since the Epoch (only combines with %f)
    %f fraction of a second (needs %s or %S)
    %t short time (205314, 2053)
    %z zone
    %p "am" or "pm"
    %n empty string (to be put at the end of formats)

0 if format doesn't match data, or the appropriate time object.

The zone will be a guess if it doesn't state an exact regional timezone (like "Europe/Stockholm") - most zone abbriviations (like "CET") are used by more then one region with it's own daylight saving rules. Also beware that for instance CST can be up to four different zones, central Australia or America being the most common.

        Abbreviation Interpretation
        AMT          America/Manaus       [UTC-4]
        AST          America/Curacao      [UTC-4]
        CDT          America/Costa_Rica   [UTC-6]
        CST          America/El Salvador  [UTC-6]
        EST          America/Panama       [UTC-5]
        GST          Asia/Dubai           [UTC+4]
        IST          Asia/Jerusalem       [UTC+2]
        WST          Australia/Perth      [UTC+8]

This mapping is modifiable in the ruleset, see Ruleset.set_abbr2zone. function Day dwim_day(string date) function Day dwim_day(string date,TimeRange context) Tries a number of different formats on the given date (in order):

        parse format                  as in
        "%y-%M-%D (%M) -W%W-%e (%e)"  "2000-03-20 (Mar) -W12-1 (Mon)"
        "%y-%M-%D"                    "2000-03-20", "00-03-20"
        "%M%/%D/%y"                   "3/20/2000"
        "%D%*[ /]%M%*[ /-,]%y"        "20/3/2000" "20 mar 2000" "20/3 -00"
        "%e%*[ ]%D%*[ /]%M%*[ /-,]%y" "Mon 20 Mar 2000" "Mon 20/3 2000"
        "-%y%*[ /]%D%*[ /]%M"         "-00 20/3" "-00 20 mar"
        "-%y%*[ /]%M%*[ /]%D"         "-00 3/20" "-00 march 20"
        "%y%*[ /]%D%*[ /]%M"          "00 20 mar" "2000 20/3"
        "%y%*[ /]%M%*[ /]%D"          "2000 march 20"
        "%D%.%M.%y"                   "20.3.2000"
        "%D%*[ -/]%M"                 "20/3" "20 mar" "20-03"
        "%M%*[ -/]%D"                 "3/20" "march 20"
        "%M-%D-%y"                    "03-20-2000"
        "%D-%M-%y"                    "20-03-2000"
        "%e%*[- /]%D%*[- /]%M"        "mon 20 march"
        "%e%*[- /]%M%*[- /]%D"        "mon/march/20"
        "%e%*[ -/wv]%W%*[ -/]%y"      "mon w12 -00" "1 w12 2000"
        "%e%*[ -/wv]%W"               "mon w12"
        "%d"                          "20000320", "000320"
        "today"                       "today"
        "last %e"                     "last monday"
        "next %e"                     "next monday"

Casts exception if it fails to dwim out a day. "dwim" means do-what-i-mean.

function datetime(int|void unix_time) Replacement for localtime; gives back a mapping:

         ([ "year":     int        // year number (2000 AD=2000, 1 BC==0)
            "month":    int(1..)   // month of year
            "day":      int(1..)   // day of month
            "yearday":  int(1..)   // day of year
            "week":     int(1..)   // week of year
            "week_day": int(1..)   // day of week (depending on calendar)
            "unix":     int        // unix time
            "julian":   float      // julian day
            "hour":     int(0..)   // hour of day, including dst
            "minute":   int(0..59) // minute of hour
            "second":   int(0..59) // second of minute
            "fraction": float      // fraction of second
            "timezone": int        // offset to utc, including dst
         ]);

This is the same as calling Second()->datetime().

function datetime_name(int|void unix_time) function datetime_short_name(int|void unix_time) Compat functions; same as format_iso and format_iso_short.

function string format_iso(void|int unix_time) function string format_iso_short(void|int unix_time) function string format_iso_tod(void|int unix_time) function string format_day_iso(void|int unix_time) function string format_day_iso_short(void|int unix_time) Format the object into nice strings;

        iso    "2000-06-02 (Jun) -W22-5 (Fri) 11:57:18 CEST"
        iso_short   "2000-06-02 11:57:18"
        iso_tod     "11:57:18"

Contains a time zone.

Offset to UTC, not counting DST.

The name of the time zone.

This method takes one integer argument, ignores it and returns an array with the UTC offset and the timezone name.

This method takes one integer argument, ignores it and returns an array with the UTC offset and the timezone name.

Returns the offset to UTC, not counting DST.

This is the standard western calendar, which is a derivate of the Gregorian calendar, but with weeks that starts on Monday instead of Sunday.

.Gregorian
TimeRange

This represents the null time range, which, to differ from the zero time range (the zero-length time range), isn't placed in time. This is the result of for instance `& between two strict non-overlapping timeranges - no time at all.

It has a constant, is_nulltimerange, which is non-zero. `! on this timerange is true.

This is the base class (usually implemented by e.g. Calendar subclasses like Calendar.Second) for any time measurement and calendrar information. It defines all the things you can do with a time range or any time period.

A TimeRange doubles as both a fixed period in time, and an amount of time. For instance, a week plus a day moves the week-period one day ahead (unaligning it with the week period, and thereby reducing it to just 7 days), no matter when in time the actual day were.

TimeRange
TimeRange

calculates the (promoted) time period n steps away; if no step is given, the step's length is of the same length as the called time period.

It is not recommended to loop by adding the increment time period to a shorter period; this can cause faults, if the shorter time period doesn't exist in the incremented period. (Like week 53, day 31 of a month or the leap day of a year.)

Recommended use are like this:

       // loop over the 5th of the next 10 months
       TimeRange month=Month()+1;
       TimeRange orig_day=month()->day(5);
       for (int i=0; i<10; i++)
       {
          month++;
          TimeRange day=month->place(orig_day);
          ...use day...
       }

TimeRange
TimeRange

This gives back the zero-sized beginning or end of the called time period.

rule: range(t->beginning(),t->end())==t

Calendar

Simply gives back the calendar in use, for instance Calendar.ISO or Calendar.Discordian.

0
1
TimeRange
0
1
TimeRange
0
1
TimeRange
0
1
TimeRange
0
1
TimeRange
0
1
TimeRange
0
1
TimeRange
0
1
TimeRange
0
1
TimeRange

These methods exists to compare two periods of time on the timeline.

              case            predicates

     <-- past       future ->

     |----A----|              A strictly preceeds B,
                  |----B----| A preceeds B

     |----A----|              A strictly preceeds B, A preceeds B,
               |----B----|    A is previous to B, A touches B

         |----A----|          A preceeds B,
               |----B----|    A overlaps B, A touches B

         |-------A-------|    A preceeds B, A ends with B
               |----B----|    A overlaps B, A contains B, A touches B,

         |-------A-------|    A preceeds B,  A succeeds B,
             |---B---|        A overlaps B, A contains B, A touches B

            |----A----|       A overlaps B, A touches B, A contains B
            |----B----|       A equals B, A starts with B, A ends with B

         |-------A-------|    A succeeds B, A starts with B
         |----B----|          A overlaps B, A contains B, A touches B

               |----A----|    A succeeds B,
         |----B----|          A overlaps B, A touches B

               |----A----|    A strictly succeeds B, A succeeds B
     |----B----|              A is next to B, A touches B

                 |----A----|  A strictly succeeds B,
     |----B----|              A succeeds B

These methods only check the range of the first to the last time in the period; use of combined time periods (SuperTimeRanges) might not give you the result you want.

`&amp;

"unix"
"unix"

Create the timerange from unix time (as given by time(2)), with eventually the size of the time range in the same unit, seconds.

"julian"

Create the timerange from a julian day, the standardized method of counting days. If the timerange is more then a day, it will at least enclose the day.

TimeRange

Create the timerange from another timerange.

This is useful when converting objects from one calendar to another. Note that the ruleset will be transferred to the new object, so this method can't be used to convert between timezones or languges - use set_timezone, set_language or set_ruleset to achieve this.

The size of the new object may be inexact; a Month object can't comprehend seconds, for instance.

TimeRange
TimeRange
TimeRange
TimeRange
TimeRange
TimeRange

Derives different time periods in between the called timerange and the parameter timerange.

    >- the past          the future -<
     |--called--|         |--other--|
     >------------ range -----------<
                >--space--<
     >----- distance -----<

See also: add, TimeRanges.range, TimeRanges.space, TimeRanges.distance

TimeRange
TimeRange

This calculates how many instances of the given timerange has passed during the called timerange.

For instance, to figure out your age, create the timerange of your lifespan, and divide with the instance of a Year.

TimeRange
Rule.Language
TimeRange
Language

Set or get the current language rule.

TimeRange
TimeRange

Next and prev are compatible and convinience functions; a->next() is exactly the same as a+1; a=a->next() is a++.

TimeRange

Calculates offset to x; this compares two timeranges and gives the integer offset between the two starting points.

This is true for suitable a and b: a+a->offset_to(b)==b

By suitable means that a and b are of the same type and size. This is obviously true only if a+n has b as a possible result for any n.

TimeRange
TimeRange
TimeRange
TimeRange
0 1

This will place the given timerange in this timerange, for instance, day 37 in the year - Year(1934)->place(Day(1948 d37)) => Day(1934 d37).

The rules how to place things in different timeranges can be somewhat 'dwim'.

TimeRange
Ruleset
TimeRange
Ruleset

Set or get the current ruleset.

this may include timezone shanges, and change the time of day.

TimeRange
TimeRange
TimeRange
TimeRange

Gives back a new (or the same, if the size matches) timerange with the new size. If n are given, the resulting size will be n amounts of the given size.

A negative size is not permitted; a zero one are.

TimeRange
Timezone
TimeRange
TimeZone

Set or get the current timezone (including dst) rule.

The time-of-day may very well change when you change timezone.

To get the time of day for a specified timezone, select the timezone before getting the time of day:

Year(2003)->...->set_timezone(TimeZone.CET)->...->hour(14)->...

TimeRange
TimeRange

This divides the called timerange into n pieces. The returned timerange type is not neccesarily of the same type as the called one.

known bugs: These are currently not defined for supertimeranges.

TimeRange
TimeRange

This subtracts a period of time from another;

    >- the past          the future -<
    |-------called-------|
         |-------other--------|
    <---->  <- called->subtract(other)

    |-------called-------|
         |---third---|
    <---->           <---> <- called->subtract(third)

TimeRange
TimeRange

Gives the cut on the called time period with another time period. The result is zero if the two periods doesn't overlap.

    >- the past          the future -<
     |-------called-------|
          |-------other--------|
          >----- cut -----<

TimeRange

This changes the amount of time in the time period. t*17 is the same as doing t->set_size(t,17).

TimeRange
TimeRange
TimeRange
TimeRange
TimeRange
TimeRange

This calculates the (promoted) time period either n step away or with a given offset. These functions does use add to really do the job:

    t+n         t->add(n)             t is a time period
    t-n         t->add(-n)            offset is a time period
    t+offset    t->add(1,offset)      n is an integer
    t-offset    t->add(-1,offset)
    n+t         t->add(n)
    n-t         illegal
    offset+t    offset->add(1,t)      | note this!
    offset-t    offset->add(-1,t)     |

Mathematic rules:

    x+(t-x) == t    x is an integer or a time period
    (x+t)-x == t    t is a time period
    (t+x)-x == t
    o-(o-t) == t    o is a time period
    t++ == t+1
    t-- == t-1

a-b does not give the distance between the start of a and b. Use the distance() function to calculate that.

The integer used to `+, `- and add are the number of steps the motion will be. It does never represent any fixed amount of time, like seconds or days.

0
1
TimeRange
0
1
TimeRange

These operators sorts roughty on the periods place in time. The major use might be to get multiset to work, besides sorting events clearly defined in time.

0
1
TimeRange
0
1
TimeRange

These two overloads the operator `== and the result of the equal function.

a==b is considered true if the two timeranges are of the same type, have the same rules (language, timezone, etc) and are the same timerange.

equal(a,b) are considered true if a and b are the same timerange, exactly the same as the equals method.

The __hash method is also present, to make timeranges possible to use as keys in mappings.

known bugs: _equal is not currently possible to overload, due to weird bugs, so equal uses `== for now.

TimeRange
TimeRange

Gives the exclusive-or on the called time period and another time period, ie the union without the cut. The result is zero if the two periods were the same.

    >- the past          the future -<
     |-------called-------|
          |-------other--------|
     <----|               |---->   - exclusive or

TimeRange
TimeRange

Gives the union on the called time period and another time period.

    >- the past          the future -<
     |-------called-------|
          |-------other--------|
     <----------union---------->

inherits TimeRange

This class handles the cases where you have a time period with holes. These can be created by the ^ or | operators on time ranges.

TimeRange

A SuperTimeRange must have at least two parts, two time ranges. Otherwise, it's either not a time period at all or a normal time period.

This implements TNG stardates.

Calendar.TimeRange

Apart from the standard creation methods (julian day, etc), you can create a stardate from the stardate number. The length of the period will then be zero.

You can also omit any arguments to create now.

Since the precision is limited to the float type of Pike you can get non-precise results:

> Calendar.Second(Calendar.Stardate.Day(Calendar.Year())); Result: Second(Fri 31 Dec 1999 23:59:18 CET - Sun 31 Dec 2000 23:59:18 CET)

This gives back the start of the stardate period, as a float.

This gives back the number of stardate tics in the period.

This gives back the Gregorian/Earth/ISO number of seconds, for convinience and conversion to other calendars.

This gives back the Gregorian/Earth/ISO number of days, for convinience and conversion to other calendars.

Format the stardate tick nicely. Precision is the number of decimals. Defaults to 3. long"-322537.312" short"77463.312"(w/o >100000-component) vshort"7463.312"(w/o >10000-component)

Give the zero-length time period of the current time.

cTick

Base for time of day in calendars, ie calendars with hours, minutes, seconds

This module can't be used by itself, but is inherited by other modules (ISO by YMD, for instance).

inherits TimeRange

Virtual class used by e.g. Hour.

``

Creates a call_out to this point in time.

In addition to the wide range of construction arguments for a normal TimeRange (see TimeRange.create), a time of day can also be constructed with unixtime as single argument consisting of the unix time - as returned from time(2) - of the time unit start.

It can also be constructed without argument, which then means "now", as in "this minute".

Format the object into nice strings;

    iso_ymd        "2000-06-02 (Jun) -W22-5 (Fri)" [2]
    ext_ymd        "Friday, 2 June 2000" [2]
    ymd            "2000-06-02"
    ymd_short      "20000602"
    ymd_xshort     "000602" [1]
    iso_week       "2000-W22"
    iso_week_short "2000W22"
    week           "2000-w22" [2]
    week_short     "2000w22" [2]
    month          "2000-06"
    month_short    "200006" [1]
    iso_time       "2000-06-02 (Jun) -W22-5 (Fri) 20:53:14 UTC+1" [2]
    ext_time       "Friday, 2 June 2000, 20:53:14" [2]
    ctime          "Fri Jun  4 20:53:14 2000\n" [2] [3]
    http           "Fri, 02 Jun 2000 19:53:14 GMT" [4]
    time           "2000-06-02 20:53:14"
    time_short     "20000602 20:53:14"
    time_xshort    "000602 20:53:14"
    iso_short      "20000602T20:53:14"
    mtime          "2000-06-02 20:53"
    xtime          "2000-06-02 20:53:14.000000"
    todz           "20:53:14 CET"
    todz_iso       "20:53:14 UTC+1"
    tod            "20:53:14"
    tod_short      "205314"
    xtod           "20:53:14.000000"
    mod            "20:53"
    nice           "2 Jun 20:53", "2 Jun 2000 20:53:14" [2][5]
    nicez          "2 Jun 20:53 CET" [2][5]
    smtp           "Fri, 2 Jun 2000 20:53:14 +0100" [6]
    commonlog      "02/Jun/2000:20:53:14 +0100" [2]

[1] note conflict (think 1 February 2003)
[2] language dependent
[3] as from the libc function ctime()
[4] as specified by the HTTP standard; this is always in GMT, ie, UTC. The timezone calculations needed will be executed implicitly. It is not language dependent.
[5] adaptive to type and with special cases for yesterday, tomorrow and other years
[6] as seen in Date: headers in mails

This gives back the number of the time unit, on this day. Fraction is a float number, 0<=fraction<1. function mapping datetime() This gives back a mapping with the relevant time information (representing the start of the period);

         ([ "year":     int        // year number (2000 AD=2000, 1 BC==0)
            "month":    int(1..)   // month of year
            "day":      int(1..)   // day of month
            "yearday":  int(1..)   // day of year
            "week":     int(1..)   // week of year
            "week_day": int(1..)   // day of week (depending on calendar)

            "hour":     int(0..)   // hour of day, including dst
            "minute":   int(0..59) // minute of hour
            "second":   int(0..59) // second of minute
            "fraction": float      // fraction of second
            "timezone": int        // offset to utc, including dst

            "unix":     int        // unix time
            "julian":   float      // julian day
         ]);

Hour
Hour
Hour
Hour

hour() gives back the timerange representing the first or nth Hour of the called object. Note that hours normally starts to count at zero, so ->hour(2) gives the third hour within the range.

An Hour is in the Calendar perspective as any other time range not only 60 minutes, but also one of the (normally) 24 hours of the day, precisely.

hours() give back an array of all the hours containing the time periods called. With arguments, it will give back a range of those hours, in the same enumeration as the n to hour().

number_of_hours() simple counts the number of hours containing the called time period.

Note: The called object doesn't have to *fill* all the hours it will send back, it's enough if it exist in those hours:

        > object h=Calendar.Time.Hour();
        Result: Hour(265567)
        > h->hours();
        Result: ({ /* 1 element */
                    Hour(265567)
                })
        > h+=Calendar.Time.Minute();
        Result: Minute(265567:01+60m)
        > h->hours();
        Result: ({ /* 2 elements */
                    Hour(265567),
                    Hour(265568)
                })

This calculates the corresponding julian day, from the time range. Note that the calculated day is the beginning of the period, and is a float - julian day standard says .00 is midday, 12:00 pm.

Normal pike (ie, 32 bit) floats (without --with-double-precision) has a limit of about 7 digits, and since we are about julian day 2500000, the precision on time of day is very limited.

Minute
Minute
Minute
Minute

minute() gives back the timerange representing the first or nth Minute of the called object. Note that minutes normally starts to count at zero, so ->minute(2) gives the third minute within the range.

An Minute is in the Calendar perspective as any other time range not only 60 seconds, but also one of the (normally) 60 minutes of the Hour, precisely.

minutes() give back an array of all the minutes containing the time periods called. With arguments, it will give back a range of those minutes, in the same enumeration as the n to minute().

number_of_minutes() simple counts the number of minutes containing the called time period.

TimeRange
TimeRange

These two methods gives back the time range called moved the specified amount of time, with the length intact.

The motion is relative to the original position in time; 10 seconds ahead of 10:42:32 is 10:42:42, etc.

Second
Second
Second
Second

second() gives back the timerange representing the first or nth Second of the called object. Note that seconds normally starts to count at zero, so ->second(2) gives the third second within the range.

seconds() give back an array of all the seconds containing the time periods called. With arguments, it will give back a range of those seconds, in the same enumeration as the n to second().

number_of_seconds() simple counts the number of seconds containing the called time period.

TimeRange
TimeRange

These two methods allows the time range to be edited by size of specific units.

This calculates the corresponding unix time, - as returned from time(2) - from the time range. Note that the calculated unix time is the beginning of the period.

Second
Second
Second
Second
Minute
Minute
Minute
Minute
Hour
Hour
Hour
Hour

Similar to TimeofDay, the Time::SuperTimeRange has a number of methods for digging out time parts of the range. Since a SuperTimeRange is a bit more complex - the major reason for its existance it that it contains holes, this calculation is a bit more advanced too.

If a range contains the seconds, say, 1..2 and 4..5, the third second (number 2, since we start from 0) in the range would be number 4, like this:

    no   means this second
    0    1
    1    2
    2    4      <- second three is missing,
    3    5         as we don't have it in the example range

number_of_seconds() will in this example therefore also report 4, not 5, even if the time from start of the range to the end of the range is 5 seconds.

inherits TimeofDay

A Fraction is a part of a second, and/or a time period with higher resolution then a second.

It contains everything that is possible to do with a Second, and also some methods of grabbing the time period with higher resolution.

Internally, the fraction time period is measured in nanoseconds. A shorter or more precise time period then in nanoseconds is not possible within the current Fraction class.

"unix"
"unix"

It is possible to create a Fraction in three ways, either "now" with no arguments or from a unix time (as from time(2)), or the convenience way from ymd-hms integers.

If created from unix time, both the start of the period and the size of the period can be given in floats, both representing seconds. Note that the default float precision in pike is rather low (same as 'float' in C, the 32 bit floating point precision, normally about 7 digits), so beware that the resolution might bite you. (Internally in a Fraction, the representation is an integer.)

If created without explicit length, the fraction will always be of zero length.

TimeofDay

Give the zero-length time period of the current time.

Calendar
Ruleset
Ruleset

Set or read the ruleset for the calendar. set_ruleset returns a new calendar object, but with the new ruleset.

Calendar
Timezone
Calendar
Timezone
TimeZone

Set or get the current timezone (including dst) rule. set_timezone returns a new calendar object, as the called calendar but with another set of rules.

Example:

    > Calendar.now();
    Result: Fraction(Fri 2 Jun 2000 18:03:22.010300 CET)
    > Calendar.set_timezone(Calendar.Timezone.UTC)->now();
    Result: Fraction(Fri 2 Jun 2000 16:03:02.323912 UTC)

This is the standard conservative christian calendar, used regularly in some countries - USA, for instance - and which derivate - the ISO calendar - is used in most of Europe.

.YMD

This module contains all the predefined timezones. Index it with whatever timezone you want to use.

Example: Calendar.Calendar my_cal= Calendar.ISO->set_timezone(Calendar.Timezone["Europe/Stockholm"]);

A simpler way of selecting timezones might be to just give the string to set_timezone; it indexes by itself:

Calendar.Calendar my_cal= Calendar.ISO->set_timezone("Europe/Stockholm");

Do not confuse this module with Ruleset.Timezone, which is the base class of a timezone object.

"CET" and some other standard abbreviations work too, but not all of them (due to more then one country using them).

Do not call set_timezone too often, but remember the result if possible. It might take some time to initialize a timezone object.

There are about 504 timezones with 127 different daylight saving rules. Most of them historic.

The timezone information comes from ftp://elsie.nci.nih.gov/pub/ and are not made up from scratch. Timezone bugs may be reported to the timezone mailing list, tz@elsie.nci.nih.gov, preferable with a cc to mirar+pike@mirar.org. /Mirar

TZnames

Rule.Timezone

This contains the local timezone, found from various parts of the system, if possible.

Rule.Timezone

This is a special timezone, that uses localtime() and tzname to find out what current offset and timezone string to use.

locale uses this if there is no other way of finding a better timezone to use.

This timezone is limited by localtime and libc to the range of time_t, which is a MAXINT on most systems - 13 Dec 1901 20:45:52 to 19 Jan 2038 3:14:07, UTC.

This is the islamic calendar. Due to some sources, they decide the first day of the new months on a month-to-month basis (sightings of the new moon), so it's probably not that accurate. If someone can confirm (or deny) accuracy better than that, please contact me so I can change this statement.

It's vaugely based on rules presented in algorithms by Dershowitz, Reingold and Clamen, 'Calendrical Calculations'. It is the same that's used in Emacs calendar mode.

I have currently no idea how the arabic countries count the week. Follow the same rules as ISO for now... The time is also suspicious; the day really starts at sunrise (sunset?) and not midnight, the hours of the day is not correct. Also don't know what to call years before 1 - go for "BH"; positive years are "AH", anno Hegirac.

.YMD

Same as the ISO calendar, but with Swedish as the default language.

This calendar exist only for backwards compatible purposes.

.ISO

This is the Coptic Orthodox Church calendar, that starts the 11th or 12th September and has 13 months.

The (default) names of the months are different then other the emacs calendar; I do not know which ones are used - the difference seem to be only the transcription of the phonetic sounds (B <-> P, etc).

I do not know for how long back the calendar is valid, either. My sources claim that the calendar is synchronized with the Gregorian calendar, which is odd.

.Gregorian

PLIS, Permuted Lisp. A Lisp language somewhat similar to scheme.

Adds the special functions quote, set!, setq, while, define, defmacro, lambda, if, and, or, begin and catch to the environment.

Environment

Adds the functions +, *, -, =, <, >, concat, read-string, eval, apply, global-environment, var, cdr, null?, setcar!, setcdr!, cons and list to the environment.

Environment

Creates a new environment on which it runs init_functions, init_specials and the following boot code.

(begin (defmacro (cddr x) (list (quote cdr) (list (quote cdr) x))) (defmacro (cadr x) (list (quote car) (list (quote cdr) x))) (defmacro (cdar x) (list (quote cdr) (list (quote car) x))) (defmacro (caar x) (list (quote car) (list (quote car) x)))

(defmacro (when cond . body) (list (quote if) cond (cons (quote begin) body)))

(define (map fun list) (if (null? list) (quote ()) (cons (fun (car list)) (map fun (cdr list)))))

(defmacro (let decl . body) (cons (cons (quote lambda) (cons (map car decl) body)) (map cadr decl))))

Environment

Instantiates a copy of the default environment and starts an interactive main loop that connects to standard I/O. The main loop is as follows:

(begin (define (loop) (let ((line (read-line \"PLIS: \"))) (if line (let ((res (catch (eval (read-string line) (global-environment))))) (display res) (loop))))) (loop))

Boilerplate to quickly whip up rsif-like hacks for creating file processing to churn away at stdin, or files and/or directories provided on the command line, recursively or not, creating backup files or not, listing the paths of all files action was taken for, and returning an exit status of how many files that would have been taken action on which could not be written back.

The all-round quickest way of making one of these tools is nicking the top portion of lib/modules/Tools.pmod/Standalone.pmod/process_files.pike or copying rsif.pike from the same directory. (The latter is 20 lines long, including docs, or about four lines of code.) Inherit process_files, and define your own version, description, usage, process, and, if you want arguments, want_args.

Toole.Standalone.process_files

Your hack's version number. If you version control your file with cvs, we suggest you set the contents of this variable to something that that will automatically expand to a number for every new revision, for instance

string version = ("$Revision: 1.3 $"/" ")[1];

One-liner that gets shown for this tool when running pike -x without additional options. (Assuming your tool resides in Standalone.pmod.) Does not include the name of the tool itself; just provide a nice, terse description, ending with a period for conformity.

Long description of the purpose and usage of your tool, for --help and the case where not enough options are given on the command line. Its invocation mode (for instance "pike -x yourtool", when invoked that way) is prepended, and a list of available flags appended to this description.

The number of (mandatory) command-line options your hack needs and which your process callback wants (beside the input file). By default 0.

Gets called with the contents of a file (or stdin). Return your output, or 0 if you didn't do anything. args are the first want_args command-line options provided, before the list of files to process.

0 in quiet mode, 1 by default, above = more output

0

0 to make backups, 1 to overwrite (default)

0 1

1 to recurse into directories, 0 not to (default)

0 1

Flag docs to append to your usage description. Explains default options.

Takes the path to a file and the first want_args command-line options provided, before the list of files to process. You might want to override this method if your tool needs to see file paths.

process_path

0
1

Takes the path to a file or directory and the first want_args first command-line options provided, before the list of files to process. You might want to override this method if your tool needs to see all paths.

process_file

0

Base implementation of main program, handling basic flags and returning an exit status matching the number of failures during operation.

No easy way of adding your own command-line flags implemented yet. This would be a rather natural next feature to add, once somebody needs some.

0

set the username and password for accessing the remote repository.

specify an alternate repository location.

this should be a URL specifying the XMLRPC endpoint for the repository.

sets the default repository location (modules.gotpike.org)

sets the monger directory to use for working and storing configurations.

sets the default directory for working and storing configurations ($HOME/.monger)

0 1

Returns all the licenses as a string, suitable for saving as a file.

Contains functions and information to store and present copyright information about Pike and it's components.

Adds a copyright message for the copyright holders for the component what.

An error is thrown if the copyrighted component what is already in the list of copyrights.

Return the latest copyright holder of Pike.

Returns a mapping containing all the stored copyrights. The mapping maps component name to an array of copyright holders.

Returns the copyrights as a string, suitable for saving as a file.

Parser.XML.Tree
"module.pmod"

This function extracts documentation from a file. The parameters type, name, and parentModules are used only when pikeMode != 0 and no C-style doc comments are present.

The file to extract from.

Non-zero if it is a Pike file. If the file contains style doc comments, C-mode is used despite pikeMode != 0.

"class", "module" or "namespace".

The name of the class/module/namespace.

The ancestors of the class/module/namespace.

// To extract doc for Foo.Bar.Ippa: string xml = extractXML("lib/modules/Foo.pmod/Bar.pmod/Ippa.pike", 1, "class", "Ippa", ({ "Foo", "Bar" }));

Copy all images to canonical files in a flat directory.

The contents of the XML file. The XML file is the result of extraction from a single C or Pike file, for example the result of calling extractXML.

The directory that is the base of the relative paths to images. This should be the directory of the source file that was the input to extract the XML file.

The directory where the images should be copied.

Quiet operation.

The XML file contents (with decorated <image>-tags)

Puts all children of source into the tree dest, in their right place module-hierarchically. Used to merge the results of extractions of different Pike and C files.

The nodes source and dest are <class>, <module>, <namespace> or <autodoc> nodes that are identical in the sense that they represent the same module, class or namespace. Typically they both represent <autodoc> nodes.

After calling this method, any <class> or <module> nodes that have been marked with @appears or @belongs, are still in the wrong place in the tree, so handleAppears() (or postProcess()) must be called on the whole documentation tree to relocate them once the tree has been fully merged.

Node
Node

Take care of all the @appears and @belongs directives everywhere, and rearranges the nodes in the tree accordingly

The root (<autodoc>) node of the documentation tree.

Node

Perform the last steps on a completed documentation tree.

Root <autodoc> node of the completed documentation tree.

Calls handleAppears(), cleanUndocumented() and resolveRefs() in turn.

handleAppears(), cleanUndocumented(), resolveRefs()

Node

The name of the test.

perform() is the function called in the tests, when it returns the test is complete.

The test call/result class. Instantiated with a test id and the test object itself.

Test
Test

This function runs the actual test, by spawning off a new pike and call it until at least one of these conditions: maximum_seconds has passed, or the number of runs is at least maximum_runs.

0
1
"."

This function is called in the spawned pike, to perform the test but also to write some important data to stdout. id is the current test.

Abstract class for Hilfe commands.

Returns a one line description of the command. This help should be shorter than 54 characters.

A more elaborate documentation of the command. This should be less than 68 characters per line.

The actual command callback. Messages to the user should be written out by using the safe_write method in the Evaluator object.

Evaluator

Variable reset command. Put ___Hilfe->commands->reset = Tools.Hilfe.CommandReset(); in your .hilferc to have this command defined when you open Hilfe.

Command

In every Hilfe object (Evaluator) there is a ParserState object that manages the current state of the parser. Essentially tokens are entered in one end and complete expressions are outputted in the other. The parser object is accessible as ___Hilfe->state from Hilfe expressions.

Feed more tokens into the state.

Read out completed expressions. Returns an array where every element is an expression represented as an array of tokens.

Expression

Prints out any error that might have occured while push_string was executed. The error will be printed with the print function w.

``

Sends the input line to Parser.Pike for tokenization, but keeps a state between each call to handle multiline /**/ comments and multiline #"" strings.

Returns true if there is any waiting expression that can be fetched with read.

Are we in the middle of an expression. Used e.g. for changing the Hilfe prompt when entering multiline expressions.

0
1

Clear the current state.

Returns the current parser state. Used by "dump state".

In every Hilfe object (Evaluator) there is a HilfeHistory object that manages the result history. That history object is accessible both from __ and ___Hilfe->history in Hilfe expressions.

ADT.History

This class implements the actual Hilfe interpreter. It is accessible as ___Hilfe from Hilfe expressions.

This mapping contains the available Hilfe commands, including the built in ones (dump, exit, help, new, quit), so it is possible to replace or remove them. The name of a command should be 10 characters or less.

Command

Keeps the state, e.g. multiline input in process etc.

ParserState

The locally defined variables (name:value).

The types of the locally defined variables (name:type).

The locally defined constants (name:value).

The locally defined functions (name:value).

``

The locally defined programs (name:value).

The current imports.

The current inherits.

The current result history.

HilfeHistory

The function to use when writing to the user.

`0`

Adds another output function.

`0`

Removes an output function.

``

An output method that shouldn't crash.

Adds a function to the input hook, making all user data be fed into the function.

remove_input_hook

``

Removes a function from the input hook.

add_input_hook

``

Displays the current version of Hilfe.

Clears the current state, history and removes all locally defined variables, constants, functions and programs. Removes all imports and inherits. It does not reset the command mapping nor reevaluate the .hilferc file.

Input a line of text into Hilfe. It checks if s is ".", in which case it calls state->flush(). Otherwise just calls add_buffer.

Add buffer tokenizes the input string and determines if the new line is a Hilfe command. If not, it updates the current state with the new tokens and sends any and all complete expressions to evaluation in parse_expression.

Parses a Pike expression. Returns 0 if everything went well, or a string with an error message otherwise.

Expression

The last created wrapper in which an expression was evaluated.

The last compile time;

0

The last evaluation time;

0

Strict types?

0 1

Show warnings?

0 1

The current trace level.

The current assembler debug level. Only available if Pike is compiled with RTL debug.

The current compiler trace level. Only available if Pike is compiled with RTL debug.

The current debug level. Only available if Pike is compiled with RTL debug.

The standard reswrite function.

``

The function used to write results. Gets as arguments in order: The safe_write function (function(string, mixed ...:int), the result as a string (string), the history entry number (int), the result (mixed), the compilation time (int) and the evaulation time (int). If the evaluated expression didn't return anything (e.g. a for loop) then 0 will be given as the result string.

``

Creates a wrapper and compiles the pike code f in it. If a new variable is compiled to be tested, its name should be given in new_var so that magically defined entities can be undefined and a warning printed.

Compiles the Pike code a and evaluates it by calling ___HilfeWrapper in the generated object. If show_result is set the result will be displayed and the result buffer updated with its value.

0 1

This is a wrapper containing a user interface to the Hilfe Evaluator so that it can actually be used. This wrapper uses the Stdio.Readline module to interface with the user. All input history is handled by that module, and as a consequence loading and saving .hilfe_history is handled in this class. Also .hilferc is handled by this class.

Evaluator

The readline object,

Stdio.Readline

Saves the user input history, if possible, when called.

Any hilfe statements given in the init array will be executed once .hilferc has been executed.

Evaluator
Stdio.FILE
Stdio.File
Evaluator
Stdio.File
Stdio.File

Helper function that formats a time span in nanoseconds to something more human readable (ns, ms or s).

Support for parsing PEM-style messages.

contains the boundary string

contains the body of the message

decodes a base 64 encoded message body

converts the message body and headers to the standard message format.

EncapsulatedMsg

decodes an RFC 934 encoded message.

Disassembles PGP and PEM style messages with parts separated by "-----BEGIN FOO-----" and "-----END FOO-----".

Contains any text preceeding the PEM message.

Contains any text following the PEM message.

The decoded PEM message, as an array of EncapsulatedMsg objects indexed by message name, such as "CERTIFICATE".

EncapsulatedMsg

Creates a decoded PEM message

a string containing a PEM encoded message to be decoded.

Common routines which are useful for various install scripts based on Pike.

A class keeping some methods and state to conveniently render ASCII progress bars to stdout.

Change the amount of progress without updating on stdout.

Change the name of the progress bar without updating on stdout.

Write the current look of the progressbar to stdout.

the number of increments closer to completion since last call

the length (in characters) of the line with the progressbar

The name (printed in the first 13 columns of the row)

How much progress has been made so far

The amount of progress signifying 100% done. Must be greater than zero.

Stdio.Readline

edit commands supported:

     <firstline>,<lastline><edit command>
        ^^ numeral (17) ^^
           or relative (+17, -17)
           or a search regexp (/regexp/)
           or multiple (17/regexp//regexp/+2)

Command Action D Delete first line in space G Insert hold space H Append current space to hold space P Print current data a<string>Insert c<string>Change current space d Delete current space h Copy current space to hold space i<string>Print string l Print current space p Print first line in data q Quit evaluating s/regexp/with/x Replace y/chars/chars/Replace chars

where line is numeral, first 'line'==0

Display a image on the screen. Requires GTK.

The alpha combination modes.

Use set_alpha_mode() to change the mode.

Checkerboard pattern (default).

Solid color.

Ignore alpha.

Only show the alpha channel (if any).

GTK.Window

The image types accepted. If the image is a string, it is assumed to be a filename of a image that can be loaded with Image.load. This includes URLs.

Standards.URI Image.Image Image.Layer Image.Layer

Set the alpha combining mode. m is one of Squares, Solid, None and AlphaOnly.

AlphaMode

Set the colors used for the alpha combination. c2 is only used for the Squares alpha mode.

set_alpha_mode()

Image.Color.Color
Image.Color.Color

Return the current image as a Image object, with the alpha combining done.

PVImage
Image.Image

Change the image.

PVImage

Scale the image before display with the specified factor.

Write the image to a file. If no format is specified, PNG is used. The alpha combination is done on the image before it's saved.

Verifier
this_program
Sequence
0
1
Gmp.mpz
Sequence
Sequence
Sequence
Verifier

optional

BitString

optional

BitString

optional

Object
this_program
Standards.ASN1.Types
Standards.PKCS

Creates a Standards.ASN1.Types.UTC object from the posix time t.

UTC

Returns a mapping similar to that returned by gmtime

- "year"
- "mon"
- "mday"
- "hour"
- "min"
- "sec"
UTC

Comparision function between two "date" mappings of the kind that parse_time returns.

-1
1
Sequence
Crypto.DSA
Crypto.RSA
Crypto.RSA
0
1
Crypto.RSA
Object
Verifier
TBSCertificate

Decodes a certificate, checks the signature. Returns the TBSCertificate structure, or 0 if decoding or verification failes.

Authorities is a mapping from (DER-encoded) names to a verifiers.

This function allows self-signed certificates, and it doesn't check that names or extensions make sense.

TBSCertificate

Decodes a certificate chain, checks the signatures. Verifies that the chain is unbroken, and that all certificates are in effect (time-wise.)

Returns a mapping with the following contents, depending on the verification of the certificate chain:

- "error_code"

Error describing type of verification failure, if verification failed. May be one of the following: CERT_TOO_NEW, CERT_TOO_OLD, CERT_ROOT_UNTRUSTED, CERT_BAD_SIGNATURE, CERT_INVALID, CERT_UNAUTHORIZED_CA or CERT_CHAIN_BROKEN

- "error_cert"

Index number of the certificate that caused the verification failure.

- 0 1 "self_signed"

Non-zero if the certificate is self-signed.

- 0 1 "verified"

Non-zero if the certificate is verified.

- "authority"

Standards.ASN1.Sequence of the authority RDN that verified the chain.

- "cn"

Standards.ASN1.Sequence of the common name RDN of the leaf certificate.

An array of certificates, with the relative-root last. Each certificate should be a DER-encoded certificate.

A mapping from (DER-encoded) names to verifiers.

Require that the certificate be traced to an authority, even if it is self signed.

See Standards.PKCS.Certificate.get_dn_string for converting the RDN to an X500 style string.

Interface similar to Stdio.File.

Handles blocking and nonblocking mode.

Handles callback mode in an arbitrary backend (also in blocking mode).

Read and write operations might each do both reading and writing. In callback mode that means that installing either a read or a write callback might install both internally. It also means that reading in one thread while writing in another doesn't work.

Callback changing operations like set_blocking and set_nonblocking aren't atomic.

Apart from the above, thread safety/atomicity characteristics are retained.

Blocking characterstics are retained for all functions.

is_open, connection init (create) and close (close) can do both reading and writing.

destroy attempts to close the stream properly by sending the close packet, but since it can't do blocking I/O it's not certain that it will succeed. The stream should therefore always be closed with an explicit close call.

Abrupt remote close without the proper handshake gets the errno System.EPIPE.

Objects do not contain cyclic references, so they are closed and destructed timely when dropped.

Create a connection over stream, which should be an open socket or pipe. ctx is the SSL context. If is_client is set then a client-side connection is started, server-side otherwise. If is_blocking is set then the stream is initially set in blocking mode, nonblocking mode otherwise.

The backend used by stream is taken over and restored after the connection is closed (see close). The callbacks and id in stream are overwritten.

Stdio.File
SSL.context

returns peer certificate information, if any.

returns the peer certificate chain, if any.

Close the connection. Both the read and write ends are always closed - the argument how is only for Stdio.File compatibility and must be either "rw" or 0.

If clean_close is set then close messages are exchanged to shut down the SSL connection but not the underlying stream. It may then continue to be used for other communication afterwards. The default is to send a close message and then close the stream without waiting for a response.

I/O errors are normally thrown, but that can be turned off with dont_throw. In that case errno is set instead and 0 is returned. 1 is always returned otherwise. It's not an error to close an already closed connection.

In nonblocking mode the stream might not be closed right away and the backend might be used for a while afterwards. This means that if there's an I/O problem it might not be signalled immediately by close.

I/O errors from both reading and writing might occur in blocking mode.

If a clean close is requested and data following the close message is received at the same time, then this object will read it and has no way to undo that. That data can be retrieved with read afterwards.

Shut down the SSL connection without sending any more packets. The underlying stream is returned if the connection isn't shut down already and if a nonclean close hasn't been requested.

Stdio.File

Try to close down the connection properly since it's customary to close files just by dropping them. No guarantee can be made that the close packet gets sent successfully though, because we can't risk blocking I/O here. You should call close explicitly.

Read some (decrypted) data from the connection. Works like Stdio.File.read.

I/O errors from both reading and writing might occur in blocking mode.

0 1

Write some (unencrypted) data to the connection. Works like Stdio.File.write except that this function often buffers some data internally, so there's no guarantee that all the consumed data has been successfully written to the stream in nonblocking mode. It keeps the internal buffering to a minimum, however.

This function returns zero if attempts are made to write data during the handshake phase and the mode is nonblocking.

I/O errors from both reading and writing might occur in blocking mode.

Renegotiate the connection by starting a new handshake. Note that the accept callback will be called again when the handshake is finished.

Returns zero if there are any I/O errors. errno() will give the details.

The read buffer is not cleared - a read() afterwards will return data from both before and after the renegotiation.

Data in the write queue in nonblocking mode is not properly written before resetting the connection. Do a blocking write("") first to avoid problems with that.

Set the stream in nonblocking mode, installing the specified callbacks. The alert callback isn't touched.

Prior to version 7.5.12, this function didn't set the accept callback.

read_oob and write_oob are currently ignored.

``
``
``
``
``
``

Set nonblocking mode like set_nonblocking, but don't alter any callbacks.

Set the stream in blocking mode. All but the alert callback are zapped.

There might be some data still waiting to be written to the stream. That will be written in the next blocking call, regardless what it is.

This function doesn't solve the case when the connection is used nonblocking in some backend thread and another thread switches it to blocking and starts using it. To solve that, put a call out in the backend from the other thread that switches it to blocking, and then wait until that call out has run.

Prior to version 7.5.12, this function didn't clear the accept callback.

Set blocking mode like set_blocking, but don't alter any callbacks.

Install a function that will be called when an alert packet is received. It doesn't affect the callback mode - it's called both from backends and from within normal function calls like read and write.

This object is part of a cyclic reference whenever this is set, just like setting any other callback.

``

Install a function that will be called when the handshake is finished and the connection is ready for use.

The callback function will be called with the sslfile object and the additional id arguments (set with set_id).

Like the read, write and close callbacks, installing this callback implies callback mode, even after the handshake is done.

``

Install a function to be called when data is available.

``

Install a function to be called when data can be written.

``

Install a function to be called when the connection is closed, either normally or due to an error (use errno to retrieve it).

``

Set the backend used for the file callbacks.

Pike.Backend

Return the backend used for the file callbacks.

Pike.Backend

Return nonzero if the stream currently is open, zero otherwise. This function does nonblocking I/O to check for a close packet in the input buffer.

Return the underlying stream.

Avoid any temptation to do destruct(sslfile_obj->query_stream()). That almost certainly creates more problems than it solves.

Stdio.File

Return the SSL connection object.

SSL.connection

Return the SSL context object.

SSL.context

The most important information in a session object is a choice of encryption algorithms and a "master secret" created by keyexchange with a client. Each connection can either do a full key exchange to established a new session, or reuse a previously established session. That is why we have the session abstraction and the session cache. Each session is used by one or more connections, in sequence or simultaneously.

It is also possible to change to a new session in the middle of a connection.

.Constants

Identifies the session to the server

Always COMPRESSION_null.

Constant defining a choice of keyexchange, encryption and mac algorithm.

Information about the encryption method derived from the cipher_suite.

.Cipher.CipherSpec

Key exchange method, also derived from the cipher_suite.

48 byte secret shared between the client and the server. Used for deriving the actual keys.

information about the certificate in use by the peer, such as issuing authority, and verification status.

Sets the proper authentication method and cipher specification for the given cipher suite and verison.

Sets the compression method. Currently only COMPRESSION_null is supported.

Generates keys appropriate for the SSL version given in version, based on the client_random and server_random.

0

Client write MAC secret

1

Server write MAC secret

2

Client write key

3

Server write key

4

Client write IV

5

Server write IV

Computes a new set of encryption states, derived from the client_random, server_random and master_secret strings.

SSL.state read_state

Read state

SSL.state write_state

Write state

.state

Computes a new set of encryption states, derived from the client_random, server_random and master_secret strings.

SSL.state read_state

Read state

SSL.state write_state

Write state

.state

Keeps the state that is shared by all SSL-connections for one server (or one port). It includes policy configuration, a server certificate, the server's private key(s), etc. It also includes the session cache.

.Constants

The server's private key

Crypto.RSA

Policy for client authentication. One of SSL.Constants.AUTHLEVEL_none, SSL.Constants.AUTHLEVEL_ask and SSL.Constants.AUTHLEVEL_require.

Array of authorities that are accepted for client certificates. The server will only accept connections from clients whose certificate is signed by one of these authorities. The string is a DER-encoded certificate, which typically must be decoded using MIME.decode_base64 or Tools.PEM.Msg first.

Note that it is presumed that the issuer will also be trusted by the server. See trusted_issuers for details on specifying trusted issuers.

If empty, the server will accept any client certificate whose issuer is trusted by the server.

When set, require the chain to be known, even if the root is self signed.

Note that if set, and certificates are set to be verified, trusted issuers must be provided, or no connections will be accepted.

Get the list of allowed authorities. See set_authorities.

Sets the list of trusted certificate issuers.

An array of certificate chains whose root is self signed (ie a root issuer), and whose final certificate is an issuer that we trust. The root of the certificate should be first certificate in the chain. The string is a DER-encoded certificate, which typically must be decoded using MIME.decode_base64 or Tools.PEM.Msg first.

If this array is left empty, and the context is set to verify certificates, a certificate chain must have a root that is self signed.

Get the list of trusted issuers. See set_trusted_issuers.

Determines whether certificates presented by the peer are verified, or just accepted as being valid.

Temporary, non-certified, private keys, used with a server_key_exchange message. The rules are as follows:

If the negotiated cipher_suite has the "exportable" property, and short_rsa is not zero, send a server_key_exchange message with the (public part of) the short_rsa key.

If the negotiated cipher_suite does not have the exportable property, and long_rsa is not zero, send a server_key_exchange message with the (public part of) the long_rsa key.

Otherwise, dont send any server_key_exchange message.

Crypto.RSA
Crypto.RSA

Servers dsa key.

Crypto.DSA

Parameters for dh keyexchange.

.Cipher.DHParameters

Used to generate random cookies for the hello-message. If we use the RSA keyexchange method, and this is a server, this random number generator is not used for generating the master_secret.

``

The server's certificate, or a chain of X509.v3 certificates, with the server's certificate first and root certificate last.

For client authentication. Used only if auth_level is AUTH_ask or AUTH_require.

Cipher suites we want the server to support, best first.

Set preferred_suites to RSA based methods.

Set preferred_suites to DSS based methods.

Always ({ COMPRESSION_null })

Non-zero to enable cahing of sessions

Sessions are removed from the cache when they are older than this limit (in seconds). Sessions are also removed from the cache if a connection using the session dies unexpectedly.

Maximum number of sessions to keep in the cache.

Lookup a session identifier in the cache. Returns the corresponding session, or zero if it is not found or caching is disabled.

.session

Create a new session.

.session

Add a session to the cache (if caching is enabled).

.session

Remove a session from the cache.

Encryption and MAC algorithms used in SSL.

Cipher algorithm interface.

Set the key used for encryption/decryption, and enter encryption mode.

this_program
this_program

Return the block size for this crypto.

0

Message Authentication Code interface.

Cipher specification.

MAC using SHA.

Gmp.mpz

MAC using MD5.

MACsha
Gmp.mpz
MAChmac_sha
Crypto.CBC
Crypto.CBC

Diffie-Hellman parameters.

Gmp.mpz
Gmp.mpz
Gmp.mpz
.Constants
ADT.struct
ADT.struct
ADT.struct
Gmp.mpz
0
1
ADT.struct
ADT.struct
ADT.struct
ADT.struct

Protocol constants

Key exchange methods.

Rivest-Shamir-Adelman

Diffie-Hellman

Compression methods.

No compression.

SSL packet layer. SSL.connection inherits SSL.handshake, and in addition to the state in the handshake super class, it contains the current read and write states, packet queues. This object is responsible for receiving and sending packets, processing handshake packets, and providing a clear text packages for some application.

.Constants
.handshake
ADT.Queue
ADT.Queue
ADT.Queue

Called with alert object, sequence number of bad packet, and raw data as arguments, if a bad packet is received.

Can be used to support a fallback redirect https->http.

``

Low-level receive handler. Returns a packet, an alert, or zero if more data is needed to get a complete packet.

Queues a packet for write. Handshake and and change cipher must use the same priority, so must application data and close_notifies.

Extracts data from the packet queues. Returns a string of data to be written, "" if there are no pending packets, 1 of the connection is being closed politely, and -1 if the connection died unexpectedly.

This function is intended to be called from an i/o write callback.

Initiate close.

Send an application data packet. If the data block is too large then as much as possible of the beginning of it is sent. The size of the sent data is returned.

Main receive handler. Returns a string of received application data, or 1 if a close was received, or -1 if an error occured.

This function is intended to be called from an i/o read callback.

Interface similar to Stdio.Port.

Stdio.Port
.context
ADT.Queue

A connection switches from one set of state objects to another, one or more times during its lifetime. Each state object handles a one-way stream of packets, and operates in either decryption or encryption mode.

.Constants

Information about the used algorithms.

Message Authentication Code

.Cipher.MACAlgorithm

Encryption or decryption object.

.Cipher.CipherAlgorithm

64-bit sequence number.

Gmp.mpz

Destructively decrypts a packet (including inflating and MAC-verification, if needed). On success, returns the decrypted packet. On failure, returns an alert packet. These cases are distinguished by looking at the is_alert attribute of the returned packet.

.packet
Alert
.packet

Encrypts a packet (including deflating and MAC-generation).

.packet
Alert
.packet

Alert package.

.Constants
.packet

SSL.handshake keeps the state relevant for SSL handshaking. This includes a pointer to a context object (which doesn't change), various buffers, a pointer to a session object (reuse or created as appropriate), and pending read and write states being negotiated.

Each connection will have two sets or read and write state: The current read and write states used for encryption, and pending read and write states to be taken into use when the current keyexchange handshake is finished.

.Constants

Random cookies, sent and received with the hello-messages.

Do handshake processing. Type is one of HANDSHAKE_*, data is the contents of the packet, and raw is the raw packet received (needed for supporting SSLv2 hello messages).

This function returns 0 if hadshake is in progress, 1 if handshake is finished, and -1 if a fatal error occured. It uses the send_packet() function to trasnmit packets.

-1
1

SSL Record Layer. Handle formatting and parsing of packets.

.Constants

Dummy HTTPS server

Stdio
SSL.sslport

Implements an abstraction of the normal filesystem.

Filesystem.Base

Instanciate a new object representing the filesystem.

The directory (in the real filesystem) that should become the root of the filesystemobject.

Internal

Internal

Internal

Filesystem.Base

Filesystem which can be used to mount a Tar file.

The tar file to mount.

The parent filesystem. If non is given, the normal system filesystem is assumed. This allows mounting a TAR-file within a tarfile.

If specified, this should be an open file descriptor. This object could e.g. be a Stdio.File, Gz.File or Bz2.File object.

Filesystem.Base

Describes the stat of a file

Is the file a FIFO?

Is the file a character device?

Is the file (?) a directory?

Is the file a block device?

Is the file a regular file?

Is the file a link to some other file or directory?

Is the file a socket?

Document this function.

1 if the file is of a specific type 0 if the file is not.

[set_type]

0
1
0
1
0
1
0
1
0
1
0
1
0
1
0
1

Set a type for the stat-object.

This call doesnot change the filetype in the underlaying filesystem.

Type to set. Type is one of the following:

[isfifo], [ischr], [isdir], [isblk], [isreg], [islnk], [issock], [isdoor]

Fills the stat-object with data from a Stdio.File.stat() call.

Open the stated file within the filesystem

a [Stdio.File] object

[Stdio.File]

Stdio.File

Change to the stated directory.

the directory if the stated object was a directory, 0 otherwise.

Returns the date of the stated object as cleartext.

Baseclass that can be extended to create new filesystems. Is used by the Tar and System filesystem classes.

Change directory within the filesystem. Returns a new filesystem object with the given directory as cwd.

Base

Returns the current working directory within the filesystem.

Change the root of the filesystem.

Base

Return a stat-object for a file or a directory within the filesystem.

Stat

Returns an array of all files and directories within a given directory.

Directory where the search should be made within the filesystem. CWD is assumed if none (or 0) is given.

Return only files and dirs matching the glob (if given).

[get_stats]

Returns stat-objects for the files and directories matching the given glob within the given directory.

[get_dir]

Stat

Open a file within the filesystem

A Stdio.File object.

Stdio.File

Document this function

Change mode of a file or directory.

Change ownership of the file or directory

Create a new directory

Remove a file from the filesystem.

Document this function

`Stat`

Iterator object that traverses a directory tree and returns files as values and paths as indices. Example that uses the iterator to create a really simple sort of make:

object i=Filesystem.Traversion("."); foreach(i; string dir; string file) { if(!has_suffix(file, ".c")) continue; file = dir+file; string ofile = file; ofile[-1]='o'; object s=file_stat(ofile); if(s && i->stat()->mtime<s->mtime) continue; // compile file }

Returns the current progress of the traversion as a value between 0.0 and 1.0. Note that this value isn't based on the number of files, but the directory structure.

The root path from which to traverse.

Don't traverse symlink directories.

0 1

Returns the stat for the current index-value-pair.

Stdio.Stat

Document this function

Document this function

Document this function

Country

ISO 2-character code aka domain name

FIPS 10-character code; "Federal Information Processing Standards 10-3" etc, used by some goverments in the US.

Country name and as-known-as, if any

Flag that is set if this country doesn't exist anymore. (eg USSR.)

Returns the continent of the country.

Some countries are geographically in more then one continent; any of the continents might be returned then, but probably the continent in which the capital is resident - Europe for Russia, for instance.

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

"string"

All known countries.

Country

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 don't:

International

US Military

Network

Non-Profit Organization

Old style Arpanet

Nato field

And that US has five domains, Great Britain and france two: <dl compact> <dt>EDU <dd>US Educational <dt>MIL <dd>US Military <dt>GOV <dd>US Government <dt>UM <dd>US Minor Outlying Islands <dt>US <dd>US <dt>GB <dd>Great Britain (UK) <dt>UK <dd>United Kingdom <dt>FR <dd>France <dt>FX <dd>France, Metropolitan <dt>There's also three domains that for convinience maps to US: <dt>NET <dd>Network <dt>ORG <dd>Organization <dt>COM <dd>Commercial </dl>

Country

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

Country

Gives back a mapping from continent name to an array of the countries on that continent.

The continents are:

        	  "Europe"
        	  "Africa"
        	  "Asia"
        	  "North America"
        	  "South America"
        	  "Oceania"
    	  "Antarctica"

Some countries are considered to be on more than one continent.

Country

Convenience functions for getting a country the name-space way; it looks up whatever it is in the name- and domain-space and returns that country if possible:

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

Create a Position object from a RT38 coordinate

.Position

This class contains a geographical position, ie a point on the earths surface. The resulting position object implements comparision methods (__hash, `==, `< and `>) so that you can compare and sort positions as well as using them as index in mappings. Comparision is made primary on latidue and secondly on longitude. It does not currently take the ellipsoid into account.

It is possible to cast a position into an array, which will yield ({ float latitude, float longitude }), as well as into a string.

Latitude (N--S) of the position, in degrees. Positive number is north, negative number is south.

Longitude (W--E) of the position, in degrees. Positive number is east, negative number is west.

Altitud of the position, in meters. Positive numbers is up. Zero is the shell of the current ellipsoid.

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

Returns the nicely formatted latitude or longitude.

0

"17°42.19'N" / "42°22.2'W"

1

"17.703°N" / "42.37°W"

2

"17°42.18'N" / "42°22.2'W"

3

"17°42'10.4"N" / "42°22'12"W"

-1

"17.703" / "-42.37"

Returns the standard map grid system for the current position. Can either be "UPS" or "UTM".

The polar radius is how many meters the earth radius is at the poles (north-south direction).

The equatorial radius is how many meters the earth radius is at the equator (east-west direction).

Returns the flattening factor for the selected earth approximation ellipsoid.

Returns the first eccentricity squared for the selected earth approximation ellipsoid.

A mapping with reference ellipsoids, which can be fed to the UTM converter. The mapping maps the name of the ellipsoid to an array where the first element is a float describing the equatorial radius and the second element is a float describing the polar radius.

Sets the equatorial and polar radius to the provided values. A name can also be provided, in which case the radius will be looked up in the ellipsoid mapping. The function returns 1 upon success, 0 on failure.

"Airy 1830"
"ATS77"
"Australian National"
"Bessel 1841"
"Bessel 1841 Namibia"
"Clarke 1866"
"Clarke 1880"
"Everest"
"Everest 1830"
"Everest 1848"
"Everest 1856"
"Everest 1869"
"Everest Pakistan"
"Fisher 1960"
"Fisher 1968"
"G R S 1967"
"G R S 1975"
"G R S 1980"
"Helmert 1906"
"Hough 1956"
"Indonesian 1974"
"Krassovsky 1940"
"Mercury"
"Modified Airy"
"Modified Fisher 1960"
"New International 1967"
"SGS 85"
"South American 1969"
"Sphere"
"WGS 60"
"WGS 66"
"WGS 72"
"WGS 84"

The longitude and lattitude are not converted to the new ellipsoid.

0
1
0
1

Returns the UTM zone number for the current longitude, with correction for the Svalbard deviations.

Returns the UTM letter designator for the current latitude. Returns "Z" if latitude is outside the UTM limits of 84N to 80S.

Returns the offset within the present UTM cell. The result will be returned in an array of floats, containing easting and northing.

Returns the current UTM coordinates position. An example output is "32T 442063.562 5247479.500" where the parts are zone number + zone designator, easting and northing.

Sets the longitude and lattitude from the given UTM coordinates.

Gives the full GEOREF position for the current position, e.g. "LDJA0511".

Sets the longitude and lattitude from the given RT38 coordinates.

Returns a very crude approximation of where the ground level is at the current position, compared against the ellipsoid shell. WGS-84 is assumed, but the approximation is so bad that it doesn't matter which of the standard ellipsoids is used.

Returns the current position as Earth Centered Earth Fixed Cartesian Coordinates.

({ X, Y, Z })

Calculate the euclidian distance between two Geography.Position. Result is in meter. This uses the ECEF function.

this_program

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:

A MIME-Version header must be present to signal MIME compatibility

A Content-Type header should be present to describe the nature of the data in the message body. Seven major types are defined, and an extensive number of subtypes are available. The header can also contain attributes specific to the type and subtype.

A Content-Transfer-Encoding may be present to notify that the data of the body is encoded in some particular encoding.

Raw data to be interpreted according to the Content-Type header

Can be encoded using one of several Content-Transfer-Encodings to allow transport over non 8bit clean channels

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

This class is used to hold a decoded MIME message.

Array

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.

type, subtype, charset, boundary, transfer_encoding, params, disposition, disp_params, setencoding(), setparam(), setdisp_param(), setcharset(), setboundary()

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

type, boundary

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.

setboundary()

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

type

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

subtype, params

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

type, params

The contents of the Content-Transfer-Encoding header.

If no Content-Transfer-Encoding header is given, this field is 0 (zero).

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.

setencoding()

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.

charset, boundary, setparam()

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.

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

setdisp_param(), get_filename()

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.

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

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 is not available.

If this method is called in a message that is not a part of a fragmented message, it will return 0.

MIME.reconstruct_partial()

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.

getdata()

This method returns the raw data of the message body entity.

The type and subtype attributes indicate how this data should be interpreted.

getencoded()

This method returns the data of the message body entity, encoded using the current transfer encoding.

You should never have to call this function.

getdata()

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 MIME.encode() for a list of valid encodings.

getencoded(), MIME.encode()

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.

setcharset(), setboundary(), setdisp_param()

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.

setparam(), get_filename()

Sets the charset parameter of the Content-Type header.

This is equivalent of calling setparam("charset", charset).

setparam()

Sets the boundary parameter of the Content-Type header.

This is equivalent of calling setparam("boundary", boundary).

setparam()

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 will be generated using generate_boundary().

create()

There are several ways to call the constructor of the Message class:

With zero arguments, you will get a dummy message with neither headers nor 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.

With the guess argument set to 1 (headers and parts may be 0 if you don't want to give any), you get a more forgiving MIME Message that will do its best to guess what broken input data really meant. It won't always guess right, but for applications like mail archives and similar where you can't get away with throwing an error at the user, this comes in handy. Only use the guess mode only for situations where you need to process broken MIME messages silently; the abuse of overly lax tools is what poisons standards.

cast()

0 1
___MIME

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.

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.

MIME.encode()

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

MIME.decode()

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.

MIME.encode_word()

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.

MIME.decode_word()

Separates a header value containing text into units and calls MIME.decode_word() on them. The result is an array where each element is a result from decode_word().

MIME.decode_words_tokenized MIME.decode_words_text_remapped

Like MIME.decode_words_text(), but the extracted strings are also remapped from their specified character encoding into UNICODE, and then pasted together. The result is thus a string in the original text format, without RFC1522 escapes, and with all characters in UNICODE encoding.

MIME.decode_words_tokenized_remapped

Tokenizes a header value just like MIME.tokenize(), but also converts encoded words using MIME.decode_word(). The result is an array where each element is either an int representing a special character, or an array as returned by decode_word() representing an atom or a quoted string.

MIME.decode_words_tokenized_labled MIME.decode_words_tokenized_remapped MIME.decode_words_text

Like MIME.decode_words_tokenized(), but the extracted atoms are also remapped from their specified character encoding into UNICODE. The result is thus identical to that of MIME.tokenize(), but without RFC1522 escapes, and with all characters in UNICODE encoding.

MIME.decode_words_tokenized_labled_remapped MIME.decode_words_text_remapped

Tokenizes and labels a header value just like MIME.tokenize_labled(), but also converts encoded words using MIME.decode_word(). The result is an array where each element is an array of two or more elements, the first being the label. The rest of the array depends on the label:

"special"

One additional element, containing the character code for the special character as an int.

"word"

Two additional elements, the first being the word, and the second being the character set of this word (or 0 if it did not originate from an encoded word).

"domain-literal"

One additional element, containing the domain literal as a string.

"comment"

One additional element, containing an array as returned by MIME.decode_words_text().

MIME.decode_words_tokenized_labled_remapped

Like MIME.decode_words_tokenized_labled(), but the extracted words are also remapped from their specified character encoding into UNICODE. The result is identical to that of MIME.tokenize_labled(), but without RFC1522 escapes, and with all characters in UNICODE encoding.

The inverse of decode_words_text(), this function accepts an array of strings or pairs of strings which will each be encoded by encode_word(), after which they are all pasted together.

Either "base64" or "quoted-printable" (or either "b" or "q" for short).

The inverse of decode_words_tokenized(), this functions accepts an array like the argument to quote(), but instead of simple strings for atoms and quoted-strings, it will also accept pairs of strings to be passed to encode_word().

Either "base64" or "quoted-printable" (or either "b" or "q" for short).

MIME.encode_words_quoted_labled()

The inverse of decode_words_tokenized_labled(), this functions accepts an array like the argument to quote_labled(), but "word" labled elements can optionally contain an additional string element specifying a character set, in which case an encoded-word will be used. Also, the format for "comment" labled elements is entirely different; instead of a single string, an array of strings or pairs like the first argument to encode_words_text() is expected.

Either "base64" or "quoted-printable" (or either "b" or "q" for short).

MIME.encode_words_quoted()

Provide a reasonable default for the subtype field.

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:

"text"

"plain"

"message"

"rfc822"

"multipart"

"mixed"

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

Headers that occurr multiple times will have their contents NUL separated, unless use_multiple has been specified, in which case the contents will be arrays.

1 1

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 the 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 will be returned.

If the function fails to reconstruct an original message, an integer indicating the reason for the failure will be returned:

0

Returned if empty collection is passed in, or one that contains messages which are not of type message/partial, or parts of different fragmented messages.

1

If more fragments are needed to reconstruct the entire message, the number of additional messages needed is returned.

-1

If more fragments are needed, but the function can't determine exactly how many.

Note that the returned message may in turn be a part of another, larger, fragmented message.

MIME.Message->is_partial()

This function decodes data encoded using the base64 transfer encoding.

MIME.encode_base64(), MIME.decode()

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.

MIME.decode_base64(), MIME.encode()

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

MIME.encode_qp(), MIME.decode()

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.

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

MIME.decode_qp(), MIME.encode()

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

MIME.encode_uue(), MIME.decode()

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.

MIME.decode_uue(), MIME.encode()

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.

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 set specified in RFC822.

MIME.quote(), tokenize_labled(), decode_words_tokenized_remapped().

Similar to tokenize(), but labels the contents, by making arrays with two elements; the first a label, and the second the value that tokenize() would have put there, except for that comments are kept.

The following labels exist:

"encoded-word"

Word encoded according to =?...

"special"

Special character.

"word"

Word.

"domain-literal"

Domain literal.

"comment"

Comment.

MIME.quote(), tokenize(), decode_words_tokenized_labled_remapped()

This function is the inverse of the MIME.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.

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

MIME.tokenize()

This function performs the reverse operation of tokenize_labled().

MIME.quote(), MIME.tokenize_labled()

Returns the MIME media type for the provided filename extension. Currently 469 file extensions are known to this method. Zero will be returned on unknown file extensions.

This module implements a generic web crawler.

Features:

Fully asynchronous operation (Several hundred simultaneous requests)

Supports the /robots.txt exclusion standard

Extensible

URI Queues

Allow/Deny rules

Configurable

Number of concurrent fetchers

Bits per second (bandwidth throttling)

Number of concurrent fetchers per host

Delay between fetches from the same host

Supports HTTP and HTTPS

Statistics.

This callback is called when data has arrived for a presently crawled URI, but no more often than once a second.

Standards.URI

This callback is called whenever the crawling of a URI is finished or fails.

Standards.URI

The crawler policy object.

Maximum number of fetchers. Defaults to 100.

Maximum number of bits per second. Defaults to off (0).

Maximum number of bits per second, per host. Defaults to off (0).

Bandwidth throttling floating window width. Defaults to 30.

Maximum concurrent fetchers per host. Defaults to 1.

Minimum delay per host. Defaults to 0.

A crawler queue. Does not need to be reentrant safe. The Crawler always runs in just one thread.

Get the next URI to index. Returns -1 if there are no URIs to index at the time of the function call, with respect to bandwidth throttling and other limits. Returns 0 if there are no more URIs to index.

Standards.URI

Put one or several URIs in the queue. Any URIs that were already present in the queue are silently disregarded.

Standards.URI Standards.URI

Abstract rule class.

Standards.URI

A rule that uses glob expressions

a glob pattern that the rule will match against.

GlobRule("http://pike.ida.liu.se/*.xml");

Rule

A rule that uses Regexp expressions

Rule

a string describing the Regexp expression

A set of rules

add a rule to the ruleset

Rule

remove a rule from the ruleset

Rule
Queue
Stats
Policy
RuleSet
RuleSet

Memory queue

Queue
Stats
Policy
RuleSet
RuleSet

Get the next URI to index. Returns -1 if there are no URIs to index at the time of the function call, with respect to bandwidth throttling, outstanding requests and other limits. Returns 0 if there are no more URIs to index.

Standards.URI

Put one or several URIs in the queue. Any URIs that were already present in the queue are silently disregarded.

Standards.URI Standards.URI
Queue
Stats
Policy
Stats
Policy

function called when a page is retreived. Arguments are: Standards.URI uri, mixed data, mapping headers, mixed ... args. should return an array containing additional links found within data that will be analyzed for insertion into the crawler queue (assuming they are allowed by the allow/deny rulesets.

function called when an error is received from a server. Arguments are: Standards.URI real_uri, int status_code, mapping headers, mixed ... args. Returns void.

function called when crawl is complete. Accepts mixed ... args and returns void.

argument called before a uri is retrieved. may be used to alter the request. Argument is Standards.URI uri. Returns array with element 0 of Standards.URI uri, element 1 is a header mapping for the outgoing request.

location to start the crawl from.

optional arguments sent as the last argument to the callback functions.

Queue
``
``
``
``
Standards.URI Standards.URI

Represents a RSS (RDF Site Summary) file.

The base class for the RSS resources.

Creates an RSS resource.

.RDF.Resource

Returns the RDF.Resource that identifies this RSS resource.

.RDF.Resource

Represents an RSS image resource.

Thing

Represents an RSS item resource.

Thing

Represents an RSS textinput resource.

Thing

Represents an RSS channel.

Thing
Standards.URI
Standards.URI
Item

Adds the Item i to the Channel.

Item

Removes the Item i from the Channel.

Item

Represents the top level of an RSS index.

The underlying RDF representation of the RSS index.

.RDF

The RSS channels.

Channel

The RSS images.

Image

The RSS items.

Item

The RSS textinputs.

Textinput
.RDF

Returns an Index object, populated with the rss information given in the rss file n.

Parser.XML.Tree.Node
Index

Represents an RDF tuple set from an OWL perspective.

.RDFS

Represents an RDF domain which can contain any number of complete statements.

Instances of this class represents resources as defined in RDF: All things being described by RDF expressions are called resources. A resource may be an entire Web page; such as the HTML document "http://www.w3.org/Overview.html" for example. A resource may be a part of a Web page; e.g. a specific HTML or XML element within the document source. A resource may also be a whole collection of pages; e.g. an entire Web site. A resource may also be an object that is not directly accessible via the Web; e.g. a printed book. This general resource is anonymous and has no URI or literal id.

Resources instantiated from this class should not be used in other RDF domain objects.

URIResource, LiteralResource

Returns the nodes' N-triple serialized ID.

Returns the nodes' 3-tuple serialized ID.

Resource identified by literal.

Resource

Used to contain rdf:datatype value.

The resource will be identified by literal.

Returns the literal as an XML string.

Returns the literal string.

Resource identified by URI.

Resource

Creates an URI resource with the uri as identifier.

Throws an error if another resource with the same URI already exists in the RDF domain.

Returns the URI the resource references to.

Returns the qualifying name, or zero.

Returns the namespace this resource URI references to.

Resource used for RDF-technical reasons like reification.

URIResource

The resource will be identified by the identifier rdf_id

Returns the qualifying name.

Statement resource.

RDFResource

predicate resource.

RDFResource

subject resource.

RDFResource

object resource.

RDFResource

type resource.

RDFResource

Seq resource.

RDFResource

first resource.

RDFResource

rest resource.

RDFResource

nil resource.

RDFResource

Adds a statement to the RDF set.

Throws an exception if any argument isn't a Resouce object.

Resource
Resource
Resource

Returns 1 if the RDF domain contains the relation {subj, pred, obj}, otherwise 0.

Resource
Resource
Resource
0
1

Removes the relation from the RDF set. Returns 1 if the relation did exist in the RDF set.

Resource
Resource
Resource
0
1

Reifies the statement { pred, subj, obj } and returns the resource that denotes the reified statement. There will not be any check to see if the unreified statement is already in the domain, making it possible to define the relation twice. The original statement will not be removed.

The subject of the reified statement.

Resource
Resource
Resource
Resource

Returns a resource that is the subject of the reified statement {subj, pred, obj}, if such a resource exists in the RDF domain.

Resource
Resource
Resource
Resource

Returns the result of get_reify, if any. Otherwise calls reify_low followed by remove_statement of the provided statement {subj, pred, obj}.

The subject of the reified statement.

Resource
Resource
Resource
Resource

Turns the reified statement r into a normal statement, if possible.

1 for success, 0 for failure.

Resource
0
1

Dereifies as many statements as possible. Returns the number of dereified statements.

0

Returns all properties in the domain, e.g. all resources that has been used as predicates.

Resource

Returns a mapping with all the domains subject resources as indices and a mapping with that subjects predicates and objects as value.

Resource
Resource
Resource

Returns an RDF resource with the given URI as identifier, or zero.

URIResource

Returns an RDF resource with the given URI as identifier, or if no such resrouce exists, creates it and returns it.

URIResource

Returns an array with the statements that matches the given subject subj, predicate pred and object obj. Any and all of the resources may be zero to disregard from matching that part of the statement, i.e. find_statements(0,0,0) returns all statements in the domain.

An array with arrays of three elements.

Resource 0

The subject of the statement

Resource 1

The predicate of the statement

Resource 2

The object of the statement

Resource 0 0
Resource 0 0
Resource 0 0
Resource

Returns 1 if resource r is used as a subject, otherwise 0.

Resource
0
1

Returns 1 if resource r is used as a predicate, otherwise 0.

Resource
0
1

Returns 1 if resource r is used as an object, otherwise 0.

Resource
0
1

Returns a 3-tuple serialization of all the statements in the RDF set.

Returns an N-triples serialization of all the statements in the RDF set.

Parses an N-triples string and adds the found statements to the RDF set. Returns the number of added relations.

The parser will throw errors on invalid N-triple input.

Decodes a string that has been encoded for N-triples serialization.

Doesn't correctly decode backslashes that has been encoded with with \u- or \U-notation.

Encodes a string for use as tring in N-triples serialization.

Adds the statements represented by the string or tree in to the RDF domain. If in is a tree the in-node should be the RDF node of the XML serialization. RDF documents take its default namespace from the URI of the document, so if the RDF document relies such ingenious mechanisms, pass the document URI in the base variable.

Parser.XML.NSTree.NSNode
Web.RDF

Serialize the RDF domain as an XML string.

Returns the number of statements in the RDF domain.

Modifies the current object to create a union of the current object and the object x.

Web.RDF
Web.RDF

Returns a pretty printed version of the output from memory_usage.

A class that when instatiated will turn on trace, and when it's destroyed will turn it off again.

Sets the level of debug trace to level.

This wrapper can be placed around another object to get printouts about what is happening to it. Only a few LFUNs are currently supported.

> object x=Debug.Wrapper(Crypto.MD5()); Debug.Wrapper is proxying ___Nettle.MD5_State() > x->name(); ___Nettle.MD5_State()->name (1) Result: "md5" > !x; !___Nettle.MD5_State() (2) Result: 0

0
1

This is a probe subject which you can send in somewhere to get probed (not to be confused with a probe object, which does some active probing). All calls to LFUNs will be printed to stderr. It is possible to name the subject by passing a string as the first and only argument when creating the subject object.

> object s = Debug.Subject(); create() > random(s); _random() (1) Result: 0 > abs(s); `<(0) _sprintf(79, ([ "indent":2 ])) (2) Result: Debug.Subject > abs(class { inherit Debug.Subject; int `<(mixed ... args) { return 1; } }()); create() `-() destroy() (3) Result: 0 > pow(s,2); `[]("pow") Attempt to call the NULL-value Unknown program: 0(2)

Debug function for showing the symbol table of a program.

Perform sanity checks.

This function goes through most of the internal Pike structures and generates a fatal error if one of them is found to be out of order. It is only used for debugging.

This function does a more thorough check if the Pike runtime has been compiled with RTL debug.

Set the run-time debug level.

The old debug level will be returned.

This function is only available if the Pike runtime has been compiled with RTL debug.

0

Set the optimizer debug level.

The old optimizer debug level will be returned.

This function is only available if the Pike runtime has been compiled with RTL debug.

0

Set the assembler debug level.

The old assembler debug level will be returned.

This function is only available if the Pike runtime has been compiled with RTL debug.

0

Set the compiler trace level.

The old compiler trace level will be returned.

This function is only available if the Pike runtime has been compiled with RTL debug.

0

Check memory usage.

This function is mostly intended for debugging. It delivers a mapping with information about how many arrays/mappings/strings etc. there are currently allocated and how much memory they use.

Exactly what this function returns is version dependant.

_verify_internals()

Only available when compiled with dmalloc.

Only available when compiled with dmalloc.

Only available when compiled with dmalloc.

This function is mostly intended for debugging. It will search through all data structures in Pike looking for o and print the locations on stderr. o can be anything but int or float.

This function only exists if the Pike runtime has been compiled with RTL debug.

``

Prints out a description of the thing x to standard error. The description contains various internal info associated with x.

This function only exists if the Pike runtime has been compiled with RTL debug.

Sets a watch on the given thing, so that the gc will print a message whenever it's encountered. Intended to be used together with breakpoints to debug the garbage collector.

This function only exists if the Pike runtime has been compiled with RTL debug.

``

Dumps the 1024 latest executed opcodes, along with the source code lines, to standard error. The backlog is only collected on debug level 1 or higher, set with _debug or with the -d argument on the command line.

This function only exists if the Pike runtime has been compiled with RTL debug.

Get statistics from the garbage collector.

A mapping with the following content will be returned:

- "num_objects"

Number of arrays, mappings, multisets, objects and programs.

- "num_allocs"

Number of memory allocations since the last gc run.

- "alloc_threshold"

Threshold for "num_allocs" when another automatic gc run is scheduled.

- "projected_garbage"

Estimation of the current amount of garbage.

- "objects_alloced"

Decaying average over the number of allocated objects between gc runs.

- "objects_freed"

Decaying average over the number of freed objects in each gc run.

- "last_garbage_ratio"

Garbage ratio in the last gc run.

- "non_gc_time"

Decaying average over the CPU milliseconds spent outside the garbage collector.

- "gc_time"

Decaying average over the CPU milliseconds spent inside the garbage collector.

- "last_garbage_strategy"

The garbage accumulation goal that the gc aimed for when setting "alloc_threshold" in the last run. The value is either "garbage_ratio_low" or "garbage_ratio_high", which corresponds to the gc parameters with the same names in Pike.gc_parameters.

- "last_gc"

Time when the garbage-collector last ran.

gc(), Pike.gc_parameters()

If set, no errors will be thrown.

This function is called by clients to connect to a server.

This function is called by servers when they have got a connection from a client. The first argument is the connection file object, and the second argument is the context to be used.

Add a function that is called when the connection is closed.

``

Remove a function that is called when the connection is closed.

Closes the connection nicely, after waiting in outstanding calls in both directions.

Make a call and wait for the result

Make a call but don't wait for the result

Get a named object provided by the server.

``

Looks up the file extension in a table to return a suitable MIME type.

Makes a time notification suitable for the HTTP protocol. @param time The time in seconds since the 00:00:00 UTC, January 1, 1970 @returns The date in the HTTP standard date format. Example : Thu, 03 Aug 2000 05:40:39 GMT

Decode a HTTP date to seconds since 1970 (UTC) @returns zero (UNDEFINED) if the given string isn't a HTTP date

Decodes an URL-encoded query into a mapping.

Fast HTTP header parser.

raw unparsed full request (headers and body)

raw unparsed body of the request (raw minus request line and headers)

full request line (request_type + full_query + protocol)

HTTP request method, eg. POST, GET, etc.

full resource requested, including attached GET query

resource requested minus any attached query

query portion of requested resource, starting after the first "?"

request protocol and version, eg. HTTP/1.0

all headers included as part of the HTTP request, ie content-type.

all variables included as part of a GET or POST request.

cookies set by client

external use only

send timeout (no activity for this period with data in send buffer) in seconds, default is 180

connection timeout, delay until connection is closed while waiting for the correct headers:

return a properly formatted response to the HTTP client

Contains elements for generating a response to the client.

- "data"

Data to be returned to the client.

- "file"

File object, the contents of which will be returned to the client.

- "error"

HTTP error code

- "length"

length of content returned. If file is provided, size bytes will be returned to client.

- "modified"

contains optional modification date.

- "type"

contains optional content-type

- "extra_heads"

contains a mapping of additional headers to be returned to client.

- "server"

contains the server identification header.

``

The simplest server possible. Binds a port and calls a callback with Server.Request objects.

`.Request`
`.Request`

Closes the HTTP port.

The simplest SSL server possible. Binds a port and calls a callback with Request objects.

Stdio
SSL.sslport
"."

Create a HTTPS (HTTP over SSL) server.

The function run when a request is received. takes one argument of type Request.

The port number to bind to, defaults to 443.

The interface address to bind to.

An optional SSL secret key, provided in binary format, such as that created by Standards.PKCS.RSA.private_key().

An optional SSL certificate or chain of certificates with the host certificate first, provided in binary format.

`Request`

Closes the HTTP port.

The port accept callback

Open and execute an HTTP query.

HTTP.Query o=HTTP.Query();

void ok() { write("ok...\n"); write("%O\n", o->headers); exit(0); }

void fail() { write("fail\n"); exit(0); }

int main() { o->set_callbacks(ok, fail); o->async_request("pike.ida.liu.se", 80, "HEAD / HTTP/1.0"); return -1; }

SSL.Constants

Errno copied from the connection.

Tells if the connection is successfull.

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

Protocol string, ie "HTTP/1.0".

Status number and description (eg 200 and "ok").

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

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

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

request_fail(Protocols.HTTP.Query httpquery,...extra args) is called if the connection fails.

Returns the called object

``
``
Protocols.HTTP.Query
Protocols.HTTP.Query
Protocols.HTTP.Query

Create a new query object and begin the query.

The query is executed in a background thread; call `() in the 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.

Protocols.HTTP.Query
Protocols.HTTP.Query

Wait for connection to complete.

Returns 1 on successfull connection, 0 on failure.

Gives back the data as a string.

Gives back the number of downloaded bytes.

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

0

Headers

1

Data

2

Protocol

3

Status

4

Status description

"array"

The header mapping ORed with the following mapping.

- "protocol"

The protocol.

- "status"

The status code.

- "status_desc"

The status description.

- "data"

The returned data.

"mapping"

Gives back the answer as a string.

"string"

Gives back a pseudo-file object, with the methods read() and close(). This could be used to copy the file to disc at a proper tempo.

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

datafile()

Protocols.HTTP.Query.PseudoFile
Protocols.HTTP.Query.PseudoFile

Gives back a pseudo-file object, with the methods 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.

file()

Protocols.HTTP.Query.PseudoFile

Fetch all data in background.

timed_async_fetch(), async_request(), set_callbacks()

``

Like async_fetch(), except with a timeout and a corresponding fail callback function

async_fetch(), async_request(), set_callbacks()

``
``

Low level HTTP call method.

The HTTP method to use, e.g. "GET".

The URL to perform method on. Should be a complete URL, including protocol, e.g. "https://pike.ida.liu.se/".

Calls http_encode_query and appends the result to the URL.

The HTTP headers to be added to the request. By default the headers User-agent, Host and, if needed by the url, Authorization will be added, with generated contents. Providing these headers will override the default. Setting the value to 0 will remove that header from the request.

Old connection object.

Data payload to be transmitted in the request.

Standards.URI
Protocols.HTTP.Query
.Query

Sends a HTTP GET request to the server in the URL and returns the created and initialized Query object. 0 is returned upon failure. If a query object having request_headers->Connection=="Keep-Alive" from a previous request is provided and the already established server connection can be used for the next request, you may gain some performance.

Standards.URI
Protocols.HTTP.Query
.Query

Sends a HTTP PUT request to the server in the URL and returns the created and initialized Query object. 0 is returned upon failure. If a query object having request_headers->Connection=="Keep-Alive" from a previous request is provided and the already established server connection can be used for the next request, you may gain some performance.

Standards.URI
Protocols.HTTP.Query
.Query

Sends a HTTP DELETE request to the server in the URL and returns the created and initialized Query object. 0 is returned upon failure. If a query object having request_headers->Connection=="Keep-Alive" from a previous request is provided and the already established server connection can be used for the next request, you may gain some performance.

Standards.URI
Protocols.HTTP.Query
.Query

Returns an array of ({content_type, data}) after calling the requested server for the information. 0 is returned upon failure. Redirects (HTTP 302) are automatically followed.

Standards.URI
Protocols.HTTP.Query

Returns the returned data after calling the requested server for information through HTTP GET. 0 is returned upon failure. Redirects (HTTP 302) are automatically followed.

Standards.URI
Protocols.HTTP.Query

Similar to get_url, except that query variables is sent as a POST request instead of a GET request.

Standards.URI
Protocols.HTTP.Query
.Query

Similar to get_url_nice, except that query variables is sent as a POST request instead of a GET request.

Standards.URI
Protocols.HTTP.Query

Similar to get_url_data, except that query variables is sent as a POST request instead of a GET request.

Standards.URI
Protocols.HTTP.Query

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

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

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"

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 '?'.

The string to encode

The HTTP encoded string

Encode the specified string in as to the HTTP cookie standard.

The string to encode.

The HTTP cookie encoded string.

Request

Raw connection object

Query

URL requested (set by prepare_method). This will update according to followed redirects.

Standards.URI

Number of redirects to follow; the request will perform another request if the HTTP answer is a 3xx redirect. Default from the parent Session.follow_redirects.

A redirect automatically turns into a GET request, and all header, query, post or put information is dropped.

Loops will currently not be detected, only the limit works to stop loops.

Cookie callback. When a request is performed, the result is checked for cookie changes and additions. If a cookie is encountered, this function is called. Default is to call set_http_cookie in the Session object.

`Standards.URI`

Prepares the HTTP Query object for the connection, and returns the parameters to use with do_sync, do_async or do_thread.

This method will also use cookie information from the parent Session, and may reuse connections (keep-alive).

URL

Perform a request synchronously. Get arguments from prepare_method.

0 upon failure, this object upon success

prepare_method, do_async, do_thread

Request

Start a request in the background, using a thread. Call wait to wait for the thread to finish. Get arguments from prepare_method.

The called object.

prepare_method, do_sync, do_async, wait

do_thread does not rerun redirections automatically

Request

Wait for the request thread to finish.

0 upon failure, or the called object upon success.

do_thread

Request

Setup callbacks for async mode, headers will be called when the request got connected, and got data headers; data will be called when the request got the amount of data it's supposed to get and fail is called whenever the request failed.

Note here that an error message from the server isn't considered a failure, only a failed TCP connection.

``
``
``

Start a request asyncroneously. It will perform in the background using callbacks (make sure the backend thread is free). Call set_callbacks to setup the callbacks. Get arguments from prepare_method.

The called object.

set_callbacks, prepare_method, do_sync, do_thread

Request

destroy is called when an object is destructed. But since this clears the HTTP connection from the Request object, it can also be used to reuse a Request object.

Class to store URL+referer

Standards.URI

the referer to this URL

URL

instantiate a SessionURL object; when fed to Protocols.HTTP.Session calls, will add referer to the HTTP handshaking variables

URL
URL
URL
Protocols.HTTP

The number of redirects to follow, if any. This is the default to the created Request objects.

A redirect automatically turns into a GET request, and all header, query, post or put information is dropped.

Default is 20 redirects. A negative number will mean infinity.

Loops will currently not be detected, only the limit works to stop loops.

Request.follow_redirects

Default HTTP headers.

Parse and set a cookie received in the HTTP protocol. The cookie will be checked against current security levels et al.

Standards.URI

Set a cookie. The cookie will be checked against current security levels et al, using the parameter who. If who is zero, no security checks will be performed.

Cookie
Standards.URI

Dump all cookies to a string and read them back. This is useful to store cookies in between sessions (on disk, for instance). decode_cookies will throw an error upon parse failures. Also note, decode_cookies will clear out any previously learned cookies from the Session object, unless no_clear is given and true.

Get the cookies that we should send to this server, for this url. They are presented in the form suitable for HTTP headers (as an array). This will also take in count expiration of cookies, and delete expired cookies from the Session unless no_delete is true.

Standards.URI SessionURL
0 1

Cache of hostname to IP lookups. Given to and used by the Query objects.

The time to keep unused connections in seconds. Set to zero to never save any kept-alive connections. (Might be good in a for instance totaly synchroneous script that keeps the backend thread busy and never will get call_outs.) Defaults to 10 seconds.

Maximum number of connections to the same server. Used only by async requests. Defaults to 10 connections.

Maximum total number of connections. Limits only async requests, and the number of kept-alive connections (live connections + kept-alive connections <= this number) Defaults to 50 connections.

Maximum times a connection is reused. Defaults to 1000000. <2 means no reuse at all.

Request a Query object suitable to use for the given URL. This may be a reused object from a keep-alive connection.

Standards.URI
Query

Return a previously used Query object to the keep-alive storage. This function will determine if the given object is suitable to keep or not by checking status and headers.

Standards.URI
Query

Sends a HTTP GET, POST, PUT or DELETE request to the server in the URL and returns the created and initialized Request object. 0 is returned upon failure.

URL
Request
URL
Request
URL
Request
URL
Request

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.

post* is similar to the get_url() class of functions, except that the query variables is sent as a POST request instead of as a GET.

URL
URL
URL
URL

Sends a HTTP GET, POST, PUT or DELETE request to the server in the URL asynchroneously, and call the corresponding callbacks when result arrives (or not). The callbacks will receive the created Request object as first argument, then the given callback_arguments, if any.

callback_headers_ok is called when the HTTP request has received headers.

callback_data_ok is called when the HTTP request has been received completely, data and all.

callback_fail is called when the HTTP request has failed, on a TCP/IP or DNS level, or has received a forced timeout.

The created Request object is returned.

URL
``
``
``
Request
URL
``
``
``
Request
URL
``
``
``
Request
URL
``
``
``
Request

Abstract class for a person.

User nickname, e.g. "Mirar".

User name, e.g. "mirar".

User domain, e.g. "mistel.idonex.se".

Time of last action, represented as posix time.

Abstract class for a IRC channel.

The name of the channel.

"."

The IRC server to connect to.

An optional mapping with additional IRC client options.

- "port"

Defaults to 6667.

- "user"

Defaults to "unknown" on systems without getpwuid and getuid and to getpwuid(getuid())[0] on systems with.

- "nick"

Defaults to "Unknown" on systems without getpwuid and getuid and to String.capitalize(getpwuid(getuid())[0]) on systems with.

- "realname"

Defaults to "Mr. Anonymous" on systems without getpwuid and getuid and to getpwuid(getuid())[4] on systems with.

- "host"

Defaults to "localhost" on systems without uname and to uname()->nodename on systems with.

- "ping_interval"

Defaults to 120.

- "ping_timeout"

Defaults to 120.

- `` "connection_lost"

This function is called when the connection to the IRC server is lost or when a ping isn't answered with a pong within the time set by the ping_timeout option. The default behaviour is to complain on stderr and self destruct.

- `` "error_notify"

This function is called when a KILL or ERROR command is recieved from the IRC server.

- `` "system_notify"
- `` "motd_notify"
- `` "error_nickinuse"
- `` "generic_notify"

The arguments are from, type, to, message and extra.

- `` "quit_notify"

The arguments are who and why.

- `Person` "privmsg_notify"

The arguments are originator, message and to.

- `Person` "notice_notify"

The arguments are originator, message and to.

- `Person` "nick_notify"

The arguments are originator and to.

Closes the connection to the server.

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.

"."

Do a call to the server. This really clones a Protocols.LysKOM.Request object, and initialises it. XXX 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 are asynchronous calls, returning an initialised Protocols.LysKOM.Request object.

``

Description of the connected server.

The options argument is a mapping with the following members:

- "login"

login as this person number (get number from name).

- "password"

send this login password.

- 0 1 "invisible"

if set, login invisible.

- 0 65535 "port"

server port (default is 4894).

- "whoami"

present as this user (default is from uid/getpwent and hostname).

Data types as defined by the LysKOM protocol specification.

.Helper

This module 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.

This is the main request class. All lyskom request classes inherit this class.

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.

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

mixed_data
mixed_data

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

Wait for the call to finish.

Tells if the call has executed ok

0 1

How the call failed. The call has completed if (ok||error).

.Helper
.ProtocolTypes

Undocumented

ProtocolTypes.AuxItemInput

Undocumented

All variables in this class is read only.

Undocumented

The text number, as spicified to create.

Undocumented

Initializes a Text object.

Undocumented.

Undocumented

The actual text (or body if you wish).

The message subject.

The author of the text.

Misc info, including what conferences the message is posted to.

Needs a more complete description.

The number of marks on this text.

The time the text was created on the server.

All variables in this class is read only.

0 255

Undocumented

Undocumented

Text
0 0
"."

This variable contains the Protocols.LysKOM.Session.Person that is logged in.

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

options is a mapping of options:

- "login"

login as this person number (get number from name).

- "create"

create a new person and login with it.

- "password"

send this login password.

- 0 1 "invisible"

if set, login invisible.

- 0 65535 "port"

server port (default is 4894).

- "whoami"

present as this user (default is from uid/getpwent and hostname).

Connection

Returns the text no.

Text

Returns the person no.

Person

Returns conference number no.

Conference

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

ProtocolTypes.ConfZInfo

Performs a login. Throws a lyskom error if unsuccessful.

The session object logged in.

Create a person, which will be logged in. returns the new person object

Logouts from the server. returns the called object

this_program

Creates a new text.

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

options is a mapping that may contain:

- Conference Conference "recpt"

recipient conferences.

- Conference Conference "cc"

cc-recipient conferences.

- Conference Conference "bcc"

bcc-recipient conferences*.

- Text Text "comm_to"

The text(s) to be commented.

- Text Text "foot_to"

The text(s) to be footnoted.

- 0 1 "anonymous"

send text anonymously.

- AuxItemInput "aux_items"

AuxItems you want to set for the text*.

The items above marked with '*' are only available on protocol 10 servers. A LysKOM error will be thrown if the call fails.

Conference.create_text(), Text.comment(), Text.footnote()

``

Sends a message.

options is a mapping that may contain:

- Conference "recpt"

recipient conference.

``
Protocol

Creates an SMTP mail client and connects it to the the server provided. The server parameter may either be a string witht the hostnam of the mail server, or it may be a file object acting as a mail server. If server is a string, than an optional port parameter may be provided. If no port parameter is provided, port 25 is assumed. If no parameters at all is provided the client will look up the mail host by searching for the DNS MX record.

Throws an exception if the client fails to connect to the mail server.

Stdio.File

Sends a mail message from from to the mail addresses listed in to with the mail body body. The body should be a correctly formatted mail DATA block, e.g. produced by MIME.Message.

simple_mail

If the mail server returns any other return code than 200-399 an exception will be thrown.

Sends an e-mail. Wrapper function that uses send_message.

Some important headers are set to: "Content-Type: text/plain; charset=iso-8859-1" and "Content-Transfer-Encoding: 8bit". "Date:" header isn't used at all.

If the mail server returns any other return code than 200-399 an exception will be thrown.

Verifies the mail address addr against the mail server.

code

The numerical return code from the VRFY call.

message

The textual answer to the VRFY call.

Some mail servers does not answer truthfully to verfification queries in order to prevent spammers and others to gain information about the mail addresses present on the mail server.

If the mail server returns any other return code than 200-399 an exception will be thrown.

Class to store configuration variable for the SMTP server

Message max size

Maximum number of recipients (default 1000)

Verify sender domain for MX

Lamme check email from validity

Give raw data and normal MIME data, if set to yes your cb_data function should take an extra string argument

The low-level class for the SMTP server

This function is called whenever the SMTP server logs something. By default the log function is werror.

``

The use of Protocols.SMTP.server is quite easy and allow you to design custom functions to process mail. This module does not handle mail storage nor relaying to other domains. So it is your job to provide mail storage and relay mails to other servers

Create a receiving SMTP server. It implements RFC 2821, 2822 and 1854.

Domains name this server relay, you need to provide at least one domain (the first one will be used for MAILER-DAEMON address). if you want to relay everything you can put a '*' after this first domain.

Port this server listen on

IP on which server listen

Mailfrom callback function, this function will be called when a client send a mail from command. This function must take a string as argument (corresponding to the sender's email) and return int corresponding to the SMTP code to output to the client. If you return an array the first element is the SMTP code and the second is the error string to display.

Same as cb_mailfrom but called when a client sends a rcpt to.

This function is called each time a client send a data content. It must have the following synopsis: int cb_data(object mime, string sender, array(string) recipients, void|string rawdata) object mime : the mime data object string sender : sender of the mail (from the mailfrom command) array(string) recipients : one or more recipients given by the rcpt to command return : SMTP code to output to the client. If you return an array the first element is the SMTP code and the second is the error string to display.

Here is an example of silly program that does nothing except outputing informations to stdout. int cb_mailfrom(string mail) { return 250; }

int cb_rcptto(string email) { // check the user's mailbox here return 250; }

int cb_data(object mime, string sender, array(string) recipients) { write(sprintf("smtpd: mailfrom=%s, to=%s, headers=%O\ndata=%s\n", sender, recipients * ", ", mime->headers, mime->getdata())); // check the data and deliver the mail here if(mime->body_parts) { foreach(mime->body_parts, object mpart) write("smtpd: mpart data = %O\n", mpart->getdata()); } return 250; }

int main(int argc, array(string) argv) { Protocols.SMTP.Server(({ "ece.fr" }), 2500, "127.0.0.1", cb_mailfrom, cb_rcptto, cb_data); return -1; }

``
``
``

A mapping(int:string) that maps SMTP return codes to english textual messages.

SNMP protocol implementation for Pike

RFCs:

implemented (yet): 1155-7 : v1

1901-4 : v2/community (Bulk ops aren't implemented!)

planned: 2742 : agentX

2570 : v3 description

Stdio.UDP

SNMP version

currently version 1 and 2 are supported.

SNMP community string

should be set to the appropriate SNMP community before sending a request.

Set to "public" by default.

create a new SNMP protocol object

remote address and UDP port (optional)

local address and UDP port (optional)

return the whole SNMP message in raw format

decode ASN1 data, if garbaged ignore it

decode raw pdu message and place in message pool

read decoded message from pool

GetRequest-PDU call

an array of OIDs to GET

remote address an UDP port to send request to (optional)

request ID

GetResponse-PDU call

a mapping containing data to return

- oid1
type

data type such as tick, oid, gauge, etc

data

data to return for oid1

- oid2
type

data type such as tick, oid, gauge, etc

data

data to return for oid2

- oidn
type

data type such as tick, oid, gauge, etc

data

data to return for oidn

original received decoded pdu that this response corresponds to

error code

error index

request ID

GetNextRequest-PDU call

an array of OIDs to GET

remote address an UDP port to send request to (optional)

request ID

SetRequest-PDU call

a mapping of OIDs to SET

- oid1
type

data type such as tick, oid, gauge, etc

data

data to return for oid1

- oid2
type

data type such as tick, oid, gauge, etc

data

data to return for oid2

- oidn
type

data type such as tick, oid, gauge, etc

data

data to return for oidn

remote address an UDP port to send request to (optional)

request ID

// set the value of 1.3.6.1.4.1.1882.2.1 to "blah". object s=Protocols.SNMP.protocol(); s->snmp_community="mysetcommunity"; mapping req=(["1.3.6.1.4.1.1882.2.1": ({"str", "blah"})]); int id=s->set_request(req, "172.21.124.32");

send an SNMP-v1 trap

a mapping of OIDs to include in trap

- oid1
type

data type such as tick, oid, gauge, etc

data

data to return for oid1

- oid2
type

data type such as tick, oid, gauge, etc

data

data to return for oid2

- oidn
type

data type such as tick, oid, gauge, etc

data

data to return for oidn

generic trap-type

specific trap-type

uptime

originating ip address of the trap

address and UDP to send trap to

request id

SNMPv1 and v2c

Error tooBig

Error noError

Error noSuchName

Error badValue

Error readOnly

Error genError

PDU type Get

PDU type GetNext

PDU type Set

PDU type GetResponse

PDU type Trap

A simple SNMP agent with support for SNMP Get requests

"protocol"

create a new instance of the agent

the port number to listen for requests on

the address to bind to for listening

only one agent may be bound to a port at one time the agent does not currently support SMUX or AGENTX or other agent multiplexing protocols.

Run the agent event loop in a thread, if available.

enable manager access limits

1 to allow only managers to submit requests 0 to allow any host to submit requests

default setting allows all requests from all hosts

set the valid community strings for Get requests

an array of valid Get communities

send an empty array to disable Get requests

set the valid community strings for Set requests

an array of valid Set communities

send an empty array to disable Set requests

set the valid manager list for requests

an array of valid management hosts

send an empty array to disable all requests

set the Set request callback function for an Object Identifier

the string object identifier, such as 1.3.6.1.4.1.132.2 or an asterisk (*) to serve as the handler for all requests for which a handler is specified.

the function to call when oid is requested by a manager the function should take 3 arguments: a string containing the requested oid, the desired value, and the body of the request as a mapping. The function should return an array containing 3 elements: The first is a boolean indicating success or failure. If success, the next 2 elements should be the SNMP data type of the result followed by the result itself. If failure, the next 2 elements should be the error-status such as Protocols.SNMP.ERROR_TOOBIG and the second is the error-index, if any.

there can be only one callback per object identifier. calling this function more than once with the same oid will result in the new callback replacing the existing one.

``

clear the Set callback function for an Object Identifier

the string object identifier, such as 1.3.6.1.4.1.132.2 or an asterisk (*) to indicate the default handler.

1 if the callback existed, 0 otherwise

get the Set request callback function for an Object Identifier

the string object identifier, such as 1.3.6.1.4.1.132.2 or an asterisk (*) to indicate the default handler

the function associated with oid, if any

set the Get request callback function for an Object Identifier

the string object identifier, such as 1.3.6.1.4.1.132.2 or an asterisk (*) to serve as the handler for all requests for which a handler is specified.

the function to call when oid is requested by a manager the function should take 2 arguments: a string containing the requested oid and the body of the request as a mapping. The function should return an array containing 3 elements: The first is a boolean indicating success or failure. If success, the next 2 elements should be the SNMP data type of the result followed by the result itself. If failure, the next 2 elements should be the error-status such as Protocols.SNMP.ERROR_TOOBIG and the second is the error-index, if any.

there can be only one callback per object identifier. calling this function more than once with the same oid will result in the new callback replacing the existing one.

``

clear the Get callback function for an Object Identifier

the string object identifier, such as 1.3.6.1.4.1.132.2 or an asterisk (*) to indicate the default handler.

1 if the callback existed, 0 otherwise

get the Get request callback function for an Object Identifier

the string object identifier, such as 1.3.6.1.4.1.132.2 or an asterisk (*) to indicate the default handler

the function associated with oid, if any

Decodes a Bittorrent bencoded data chunk.

data

The decoded data. UNDEFINED if no data could be decoded.

remainder

The trailing data that wasn't decoded.

Decodes a Bittorrent bencoded data chunk and ignores the remaining string. Returns UNDEFINED if the data is incomplete.

Encodes a Bittorrent bencoded data chunk.

Convert an array of int(0..1) to a Bittorrent style bitstring. Input will be padded to even bytes.

0 1

Convert a Bittorrent style bitstring to an array of int(0..1).

0
1

Convert a Bittorrent style bitstring to an array of indices.

Bind a port for this Torrent.

.Torrent

Returns true if we can connect to this peer, when new or disconnected but not fatally.

Returns true if this peer is online and connected.

Returns true if this peer is completed, as in has downloaded everything already - and we shouldn't need to upload to get stuff.

Returns true if this peer is available, as in we can use it to download stuff.

Returns true if this peer is activated, as in we're downloading from it.

Returns true if this peer is strangled; as in we don't want to upload more, because we're not getting any back.

Returns true if this peer is choking, as in doesn't send more data to us.

Returns as multiset what this peer is downloading.

Connect to the peer; this is done async. status/mode will change from "connecting" to "dead" or to "connected" depending on result. Will throw error if already online.

Upon connect, protocol will be initiated in choked mode. When the protocol is up, status will change to "online" (or "failed" if the handshake failed).

Disconnect a peer. Does nothing if we aren't online. status/mode will change to "disconnected",1 if we were online.

Send a have message to tell I now have piece n. Ignored if not online.

Called to request a chunk from this peer.

``

Called whenever there is a status change for this peer. Always called with "created" when the object is created.

Does not need to call inherited function.

Bittorrent peer - download and share. Read more about bittorrent at http://bitconjurer.org/BitTorrent/introduction.html

The smallest usable torrent downloader. As first argument, it expects a filename to a .torrent file.

int main(int ac,array am) { // initialize Torrent from file: Protocols.Bittorrent.Torrent t=Protocols.Bittorrent.Torrent(); t->load_metainfo(am[1]);

// Callback when download status changes: // t->downloads_update_status=...;

// Callback when pieces status change (when we get new stuff): // t->pieces_update_status=...;

// Callback when peer status changes (connect, disconnect, choked...): // t->peer_update_status=...;

// Callback when download is completed: t->download_completed_callback= lambda() { call_out(exit,3600,0); // share for an hour, then exit };

// Callback to print warnings (same args as sprintf): // t->warning=werror;

// type of progress function used below: void progress(int n,int of) { /* ... */ };

// Initiate targets from Torrent, // if target was created, no need to verify: if (t->fix_targets(1,0,progress)==1) t->verify_targets(progress);

// Open port to listen on, // we want to do this to be able to talk to firewalled peers: t->my_port=6881; t->open_port();

// Ok, start calling tracker to get peers, // and tell about us: t->start_update_tracker();

// Finally, start the download: t->start_download();

return -1; }

Each bittorrent has one or more target files. This represents one of those.

.Bencoding

Function to determine if we should strangle this peer. Default is to allow 100000 bytes of data over the ratio, which is 2:1 per default; upload twice as much as we get.

Arguments are the peer, bytes in (downloaded) and bytes out (uploaded). Return 1 to strangle and 0 to allow the peer to proceed downloading again.

`.Peer01`

If set, called when we got another piece downloaded (no args).

``

If set, called when we start to download another piece (no args).

``

If set, called when peer status changes.

``

If set, called when download is completed.

``

Called if there is a protocol error.

``

Loads the metainfo from a file.

Opens target datafile(s).

If all files are created, the verify info will be filled as well, but if it isn't created, a call to verify_target() is necessary after this call.

Determines allocation procedure if the file doesn't exist:

0

Don't allocate.

1

Allocate virtual file size (seek, write end byte).

2

Allocate for real (will call progress_callback(pos,length)).

-1

Means never create a file, only open old files.

A new base filename to substitute the metainfo base target filename with.

1

The (a) file was already there.

2

All target files were created.

-1 2
``

Verify the file and fill file_got (necessary after load_info, but needs open_file before this call). [ progress_callback(at chunk,total chunks) ]

``

Open the port we're listening on.

Calculate the bytes successfully downloaded (full pieces).

Calculate the bytes left to download.

Contact and update the tracker with current status will fill the peer list.

Starts to contact the tracker at regular intervals, giving it the status and recieving more peers to talk to. Will also contact these peers. The default interval is 5 minutes. If given an event, will update tracker with it.

Stops updating the tracker; will send the event as a last event, if set. It will not contact new peers.

Contact all or n peers.

Returns the file got field as a string bitfield (cached).

Initiate the downloading scheme.

Generate a .torrent binary string from files in the filesystem

// usage: thisprogram [<file/dir>] [<file/dir>...] <target .torrent> int main(int ac,array am) { Generator g=Generator(); foreach (am[1..sizeof(am)-2];;string f) g->add(f);

string dest=am[-1]; if (-1==search(dest,"torrent")) dest+=".torrent";

Stdio.write_file(dest,g->digest()); return 0; }

.Torrent

Create a generator.

The base filename/path in the torrent.

The size of the pieces that the SHA hashes are calculated on. Default 262144 and this value should probably be 2^n.

Add one or multiple announcers (trackers). This is needed to get a valid .torrent file. If this is called more then once, more announcers (trackers) will be added with lower priority.

this_program

Add a file to the torrent. The second argument is what the file will be called in the torrent.

this_program

Add a directory tree to the torrent. The second argument is what the directory will be called in the torrent. This will call add_file on all non-directories in the tree.

this_program

Add a file, or a directory tree to the torrent. This will call add_directory_tree or add_file.

this_program

Build the SHA hashes from the files.

``

Finally make a torrent string out of this information. Will call build_sha1's if the sha1's aren't generated already.

progress_callback is called with (pos,of) arguments, similar to Torrent.verify_targets.

``
Stdio.File

Returns error number of last transaction.

LDAP.protocol.error_string

Returns error description of search result.

LDAP.protocol.error_number

Contains the client implementation of the LDAP protocol. All of the version 2 protocol features are implemented but only the base parts of the version 3.

Contains the result of a LDAP search.

LDAP.client.search, LDAP.client.result.fetch

You can't create instances of this object yourself. The only way to create it is via a search of a LDAP server.

Returns error number of search result.

LDAP.client.result.error_string

Returns error description of search result.

LDAP.client.result.error_number

Returns the number of entries.

LDAP.client.result.count_entries

Returns the number of entries from current cursor possition till end of the list.

LDAP.client.result.first, LDAP.client.result.next

Returns a mapping with an entry for each attribute. Each entry is an array of values of the attribute.

Optional argument can be used for direct access to the entry other then currently pointed by cursor.

Returns distinguished name (DN) of the current entry in the result list. Notice that this is the same as fetch()->dn[0].

Initialized the result cursor to the first entry in the result list.

LDAP.client.result.next

Moves the result cursor to the next entry in the result list. Returns number of remained entries in the result list. Returns 0 at the end.

LDAP.client.result.next

SSL.Constants
.protocol

Several information about code itself and about active connection too

Create object. The first optional argument can be used later for subsequence operations. The second one can specify TLS context of connection. The default context only allows 128-bit encryption methods, so you may need to provide your own context if your LDAP server supports only export encryption.

LDAP server URL in form "ldap://hostname/basedn?attrlist?scope?ext"

TLS context of connection

LDAP.client.bind, LDAP.client.search

Authenticates connection to the direcory.

First form uses default value previously entered in create.

Second form uses value from parameters:

The distinguished name (DN) of an entry aginst which will be made authentication.

Password used for authentication.

Third form allows specify the version of LDAP protocol used by connection to the LDAP server.

Only 2 or 3 can be entered.

Returns 1 on success, 0 otherwise.

Only simple authentication type is implemented. So be warned clear text passwords are sent to the directory server.

The API change: the returning code was changed in Pike 7.3+ to follow his logic better.

Unbinds from the directory and close the connection.

Deletes entry from the LDAP server.

The distinguished name of deleted entry.

Returns 1 on success, 0 otherwise.

The API change: the returning code was changed in Pike 7.3+ to follow his logic better.

Compares given attribute value with one in the directory.

The distinguished name of compared entry.

The mapping of compared attributes and theirs values.

Returns 1 on success, 0 otherwise.

The API change: the returning code was changed in Pike 7.3+ to follow his logic better.

The Add Operation allows a client to request the addition of an entry into the directory

The Distinguished Name of the entry to be added.

The mapping of attributes and their values that make up the content of the entry being added.

Returns 1 on success, 0 otherwise.

The API change: the returning code was changed in Pike 7.3+ to follow his logic better.

Search LDAP directory.

Search filter used when searching directory objects.

The array of attribute names which will be returned by server. for every entry.

The flag causes server return only attribute name but not the attribute values.

Returns object LDAP.client.result on success, 0 otherwise.

For syntax of search filter see at RFC 1960 (http://community.roxen.com/developers/idocs/rfc/rfc1960.html).

The API change: the returning code was changed in Pike 7.3+ to follow his logic better.

LDAP.client.result, LDAP.client.result.fetch

base DN for search

Sets value of scope for search operation.

Value can be integer or its corresponding string value. 0: base, 1: one, 2: sub

LDAP_OPT_xxx

new value for option

LDAP_OPT_xxx

The Modify DN Operation allows a client to change the leftmost (least significant) component of the name of an entry in the directory, or to move a subtree of entries to a new location in the directory.

DN of source object

RDN of destination

The parameter controls whether the old RDN attribute values are to be retained as attributes of the entry, or deleted from the entry.

If present, this is the Distinguished Name of the entry which becomes the immediate superior of the existing entry.

Returns 1 on success, 0 otherwise.

The API change: the returning code was changed in Pike 7.3+ to follow his logic better.

The Modify Operation allows a client to request that a modification of an entry be performed on its behalf by a server.

The distinguished name of modified entry.

The mapping of attributes with requested operation and attribute's values.

attropval=([ attribute: ({operation, value1, value2, ...}) ])

where operation is one of the following: 0 (LDAP_OPERATION_ADD) - add values listed to the given attribute, creating the attribute if necessary 1 (LDAP_OPERATION_DELETE) - delete values listed from the given attribute, removing the entire attribute if no values are listed, or if all current values of the attribute are listed for deletion 2 (LDAP_OPERATION_REPLACE) - replace all existing values of the given attribute with the new values listed, creating the attribute if it did not already exist. A replace with no value will delete the entire attribute if it exists, and is ignored if the attribute does not exist

Returns 1 on uccess, 0 otherwise.

The API change: the returning code was changed in Pike 7.3+ to follow his logic better.

Gets referrals.

Returns array of referrals or 0.

LDAP URL

an abstract class used to provide features for implimenting X11 extensions. Provides no useful functionality on its own.

initialize the extension.

An object of type Protocols.X.Xlib.Display

Provides support for the X11 XTEST extension.

extension

Create object.

Initialize the XTEST extension. Returns 1 if successful.

Protocols.X.Display object

Send a synthetic event to an X server.

Type of event to send. Possible values: KeyPress: 2, KeyRelease: 3, ButtonPress: 4, ButtonRelease: 5, MotionNotify: 6

Button (for Button events) or Keycode (for Key events) to send

Delay before the X server simulates event. 0 indicates zero delay.

Window object that a motion event occurrs in. If no window is provided, the root window will be used.

For motion events, this is the relative X distance or absolute X coordinates.

For motion events, this is the relative Y distance or absolute Y coordinates.

Cause the executing client to become impervious to server grabs. That is, it can continue to execute requests even if another client grabs the server.

A true (non zero) value causes the client to perform as described above. If false (zero), server returns to the normal state of being susceptible to server grabs.

This module implements most features of the XML-RPC standard (see http://xml-rpc.org/).

Translation rules for conversions from Pike datatypes to XML-RPC datatypes:

Pike int is translated to XML-RPC <int>. Pike string is translated to XML-RPC <string>. Pike float is translated to XML-RPC <double>. Pike mapping is translated to XML-RPC <struct>. Pike array is translated to XML-RPC <array>.

Translation rules for conversions from XML-RPC datatypes to Pike datatypes:

XML-RPC <i4>, <int> and <boolean> are translated to Pike int. XML-RPC <string> and <base64> are translated to Pike string. XML_RPC <double> is translated to Pike float. XML-RPC <struct> is translated to Pike mapping. XML-RPC <array> is translated to Pike array. XML-RPC <dateTime.iso8601> is translated to Pike Calendar object.

The XML-RPC <dateTime.iso8601> datatype is currently only partially implemented. It is decoded but cannot be encoded. Also, the code here does not assume any particular timezone (which is correct according to the specification). The Calendar module, however, seems to assume localtime.

Represents a function call made to a XML-RPC server.

decode_call()

Represents <methodName> in the XML-RPC standard.

Represents <params> in the XML-RPC standard where all datatypes have been converted to equivalent or similar datatypes in Pike.

Represents a fault response which can be one of the return values from a XML-RPC function call.

decode_response()

Represents faultCode in the XML-RPC standard.

Represents faultString in the XML-RPC standard.

This class implements an XML-RPC client that uses HTTP transport.

       > Protocols.XMLRPC.Client client = Protocols.XMLRPC.Client("http://www.oreillynet.com/meerkat/xml-rpc/server.php");
       Result: Protocols.XMLRPC.Client("http://www.oreillynet.com/meerkat/xml-rpc/server.php");
       > client["system.listMethods"]();
       Result: ({ /* 1 element */
      		    ({ /* 9 elements */
      			"meerkat.getChannels",
      			"meerkat.getCategories",
      			"meerkat.getCategoriesBySubstring",
      			"meerkat.getChannelsByCategory",
      			"meerkat.getChannelsBySubstring",
      			"meerkat.getItems",
      			"system.listMethods",
      			"system.methodHelp",
      			"system.methodSignature"
      		    })
      		})

Standards.URI
Standards.URI

Decodes a XML-RPC representation of a function call and returns a Call object.

Call

Call

Decodes a XML-RPC representation of a response and returns an array containing response values, or a Fault object.

Fault

Fault

Encodes a function call with the name method_name and the arguments params and returns the XML-RPC string representation.

Encodes a response containing the multiple values in params and returns the XML-RPC string representation.

Encodes a response fault containing a fault_code and a fault_string and returns the XML-RPC string representation.

NNTP protocol

Stdio.FILE

reads the server result code for last request used internally by command().

reads the message from the server as an array of lines

reads the message from the server

send the body of a message to the server.

send a command to the server

the result code sent by the server

gets the result message supplied by the server for the last response

send a command and require an ok response (200 series). throws an error if the command result was not success.

send a command that should return a message body.

the message body

An NNTP client

protocol

Returns a list of all active groups.

Group

The current news group.

Group

Sets the current news group to o.

Group

Sets the current group to group.

Group

Domain Name System RFC 1035

Resource classes

Class Internet

Class CSNET (Obsolete)

Class CHAOS

Class Hesiod

Class ANY

Entry types

Type - host address

Type - authoritative name server

Type - mail destination (Obsolete - use MX)

Type - mail forwarder (Obsolete - use MX)

Type - canonical name for an alias

Type - start of a zone of authority

Type - mailbox domain name (EXPERIMENTAL)

Type - mail group member (EXPERIMENTAL)

Type - mail rename domain name (EXPERIMENTAL)

Type - null RR (EXPERIMENTAL)

Type - well known service description

Type - domain name pointer

Type - host information

Type - mailbox or mail list information

Type - mail exchange

Type - text strings

Type - IPv6 address record (RFC 1886, deprecated)

Type - Location Record (RFC 1876)

Type - Service location record (RFC 2782)

Type - IPv6 address record (RFC 2874, incomplete support)

Low level DNS protocol

create a DNS query PDU

record class such as Protocols.DNS.C_IN

query type such Protocols.DNS.T_A

data suitable for use with Protocols.DNS.client.do_sync_query

// generate a query PDU for a address lookup on the hostname pike.ida.liu.se string q=Protocols.DNS.protocol()->mkquery("pike.ida.liu.se", Protocols.DNS.C_IN, Protocols.DNS.T_A);

Implements a Domain Name Service (DNS) server.

protocol
Stdio.UDP

Reply to a query (stub).

Parsed query.

Raw UDP data.

Overload this function to implement the proper lookup.

Returns 0 (zero) on failure, or a result mapping on success:

- "rcode"
- "qd"
entry
- "name"
- "type"
- "cl"
- "an"
- "ns"
- "ar"

Synchronous DNS client.

protocol

perform a syncronous query

result of Protocols.DNS.protocol.mkquery

mapping containing query result or 0 on failure/timeout

// perform a hostname lookup, results stored in r->an object d=Protocols.DNS.client(); mapping r=d->do_sync_query(d->mkquery("pike.ida.liu.se", C_IN, T_A));

Queries the host name from the default or given DNS server. The result is an array with three elements,

An array with the requested information about the specified host.

hostname

Hostname.

ip

IP number(s).

aliases

DNS name(s).

Queries the service record (RFC 2782) from the default or given DNS server. The result is an array of arrays with the following six elements for each record. The array is sorted according to the priority of each record.

Each element of the array returned represents a service record. Each service record contains the following:

An array with the requested information about the specified service.

priority

Priority

weight

Weight in event of multiple records with same priority.

port

port number

target

target dns name

Queries the host name or ip from the default or given DNS server. The result is an array with three elements,

The requested data about the specified host.

hostip

The host IP.

ip

IP number(s).

aliases

DNS name(s).

Queries the primary mx for the host.

Returns the hostname of the primary mail exchanger.

``
``
``
``

A client for communicating with printers and print spoolers that support the BSD lpd protocol (RFC 1179).

Set the type of job to be sent to the printer to type. Valid types are: text, postscript and raw.

Sets the name of the print job to name.

Start the queue queue if not already printing.

Returns 0 if unable to connect, 1 otherwise.

Send print job consisting of data job to printer queue.

Returns 1 if success, 0 otherwise.

Delete job job from printer queue.

Returns 1 on success, 0 otherwise.

Check the status of queue queue.

Returns 0 on failure, otherwise returns the status response from the printer.

Create a new LPD client connection.

Contains the hostname or ipaddress of the print host. if not provided, defaults to localhost.

Contains the port the print host is listening on. if not provided, defaults to port 515, the RFC 1179 standard.

The IrDA® Object Exchange Protocol. OBEX is a protocol for sending and receiving binary objects to mobile devices using transports such as IR and Bluetooth.

A request opcode, for use with the client.do_request() function.

Establish a new OBEX connection

Terminate an OBEX connection

Send an object to the mobile device

Receive an object from the mobile devuce

Change the working directory

Manage a session

Abort the request currently being processed

For REQ_PUT and REQ_GET requests, REQ_FINAL must be set for the request block containing the last portion of the headers. Other requests must be sent as a single block and have the REQ_FINAL bit encoded in their request opcode.

An identifier for a request or response header

Number of objects to transfer (used by REQ_CONNECT)

Name of the object (string)

Type of the object (IANA media type)

Length of the object transferred, in octets

ISO 8601 timestamp (string)

Text description of the object

Name of service that operation is targeted to

Any HTTP 1.x header

A chunk of the object body

The final chunk of the object body

Identifies the OBEX application (string)

An identifier used for OBEX connection multiplexing

Extended application request & response information

Authentication digest-challenge

Authentication digest-response

Indicates the creator of an object

Uniquely identifies the OBEX server

OBEX object class of object

Parameters used in session commands/responses

Sequence number used in each OBEX packet for reliability

An OBEX client

ATclient

Perform a request/response exchange with the server. No interpretation is preformed of either the request or response data, they are just passed literally.

Request opcode

Raw request data

An array with the response information

returncode

An HTTP response code

data

Response data, if any

do_request()

Request

Perform a request/response exchange with the server, including processing of headers and request splitting.

Request opcode

Request headers

Any request data that should appear before the headers, but after the opcode

An array with the response information

returncode

An HTTP response code

Headers headers

Response headers

low_do_request(), do_abort(), do_put(), do_get(), do_setpath(), do_session()

Request
Headers
Headers

Perform a REQ_ABORT request.

do_request()

Headers
Headers

Perform a REQ_PUT request.

Body data to send, or a stream to read the data from

Any additional headers to send (HI_LENGTH and HI_BODY are generated by this function)

do_get(), do_request()

Stdio.Stream
Headers
Headers

Perform a REQ_GET request.

A stream to write the body data to

Headers for the request

See do_request(). The Headers do not contain any HI_BODY headers, they are written to the data stream.

do_put(), do_request()

Stdio.Stream
Headers
Headers

Perform a REQ_SETPATH request.

The directory to set as current working directory

"/"

Go to the root directory

".."

Go to the parent directory

Logical or of zero or more of SETPATH_BACKUP and SETPATH_NOCREATE

Any additional request headers (the HI_NAME header is generated by this function)

do_request()

Headers
Headers

Perform a REQ_SESSION request.

do_request()

Headers
Headers

Establish a new connection using the REQ_CONNECT opcode to negotiate transfer parameters

If the connection succeeds, 1 is returned. Otherwise, 0 is returned.

0
1

Terminate a connection using the REQ_DISCONNECT opcode

If the disconnection succeeds, 1 is returned. Otherwise, 0 is returned.

0
1

Initialize the client by establishing a connection to the server at the other end of the provided transport stream

A stream for writing requests and reading back responses. Typically this is some kind of serial port.

Stdio.Stream

An extension of the client which uses the AT*EOBEX modem command to enter OBEX mode. Use together with Sony Ericsson data cables.

Client

A flag for the REQ_SETPATH command indicating that the parent directory should be selected

A flag for the REQ_SETPATH command indicating that the selected directory should not be created if it doesn't exist

A set of request or response headers. Each HI can be associated with either a single value (int or string, depending on the HI in question) or an array with multiple such values.

HeaderIdentifier

Serialize a set of headers to wire format

split_headers()

Headers

Deserialize a set of headers from wire format

Headers

Given a set of headers in wire format, divide them into portions of no more than chunklen octets each (if possible). No individual header definition will be split into two portions.

Simple nonblocking line-oriented I/O.

The sequence separating lines from eachother. "\r\n" by default.

If this variable has been set, multiple lines will be accumulated, until a line with a single "." (period) is received. handle_data() will then be called with the accumulated data as the argument.

handle_data() is one-shot, ie it will be cleared when it is called.

The line with the single "." (period) will not be in the accumulated data.

handle_command()

``

This function will be called once for every line that is received.

Overload this function as appropriate.

It will not be called if handle_data() has been set.

line will not contain the line separator.

handle_data()

Queue some data to send.

handle_command(), handle_data(), disconnect()

This function is called when a timeout occurrs.

Overload this function as appropriate.

The default action is to shut down the connection immediately.

create(), touch_time()

Reset the timeout timer.

create(), do_timeout()

Read a line from the input.

Returns 0 when more input is needed. Returns the requested line otherwise.

The returned line will not contain the line separator.

handle_command(), line_separator

Called when data has been received.

Overload as appropriate.

Calls the handle callbacks repeatedly until no more lines are available.

handle_data(), handle_command(), read_line()

Queue of data that is pending to send.

The elements in the queue are either strings with data to send, or 0 (zero) which is the end of file marker. The connection will be closed when the end of file marker is reached.

send(), disconnect()

ADT.Queue

Disconnect the connection.

Pushes an end of file marker onto the send queue send_q.

Note that the actual closing of the connection is delayed until all data in the send queue has been sent.

No more data will be read from the other end after this function has been called.

This function is called when the connection has been closed at the other end.

Overload this function as appropriate.

The default action is to shut down the connection on this side as well.

Create a simple nonblocking line-based protocol handler.

con is the connection.

timeout is an optional timeout in seconds after which the connection will be closed if there has been no data sent or received.

If timeout is 0 (zero), no timeout will be in effect.

touch_time(), do_timeout()

Stdio.File

Nonblocking line-oriented I/O with support for sending SMTP-style codes.

simple

Mapping from return-code to error-message.

Overload this constant as apropriate.

Send an SMTP-style return-code.

code is an SMTP-style return-code.

If lines is omitted, errorcodes will be used to lookup an appropriate error-message.

If lines is a string, it will be split on "\n" (newline), and the error-code interspersed as appropriate.

errorcodes

100 999

Nonblocking line-oriented I/O with support for reading literals.

simple

Length in bytes of the literal to read.

If this variable has been set, literal_length bytes will be accumulated, and this function will be called with the resulting data.

handle_literal() is one-shot, ie it will be cleared when it is called.

``

This function will be called once for every line that is received.

This API is provided for backward compatibility; overload handle_command() instead.

Protocols.Line.simple()->handle_command()

``

Function called once for every received line.

Enter literal reading mode.

Sets literal_length and handle_literal().

literal_length, handle_literal()

``

A LMTP server. It has been fairly well tested against Postfix client. Actually this module is only an extention to the SMTP server.

Create a receiving LMTP server. It implements RFC 2821, 2822, 2033 and 1854.

Domains name this server relay, you need to provide at least one domain (the first one will be used for MAILER-DAEMON address). if you want to relay everything you can put a '*' after this first domain.

Port this server listen on

IP on which server listen

Mailfrom callback function, this function will be called when a client send a mail from command. This function must take a string as argument (corresponding to the sender's email) and return int corresponding to the SMTP code to output to the client. If you return an array the first element is the SMTP code and the second is the error string to display.

Same as cb_mailfrom but called when a client sends a rcpt to.

This function is called for each recipient in the "rcpt to" command after the client sends the "data" command It must have the following synopsis: int|array cb_data(object mime, string sender, array(string) recipients, void|string rawdata) object mime : the mime data object string sender : sender of the mail (from the mailfrom command) string recipient : one recipient given by one rcpt command. return : SMTP code to output to the client. If you return an array the first element is the SMTP code and the second is the error string to display. Note that to comply with LMTP protocol you must output a code each time this function is called.

Here is an example of silly program that does nothing except outputing informations to stdout. int cb_mailfrom(string mail) { return 250; }

int cb_rcptto(string email) { // check the user's mailbox here return 250; }

int cb_data(object mime, string sender, array(string) recipients) { write(sprintf("smtpd: mailfrom=%s, to=%s, headers=%O\ndata=%s\n", sender, recipients * ", ", mime->headers, mime->getdata())); // check the data and deliver the mail here if(mime->body_parts) { { foreach(mime->body_parts, object mpart) write(sprintf("smtpd: mpart data = %O\n", mpart->getdata())); } return 250; }

int main(int argc, array(string) argv) { Protocols.LMTP.Server(({ "ece.fr" }), 2500, "127.0.0.1", cb_mailfrom, cb_rcptto, cb_data); return -1; }

``
``
``

Implements TELNET as described by RFC 764 and RFC 854

Also implements the Q method of TELNET option negotiation as specified by RFC 1143.

Table of IAC-codes.

interpret as command.

you are not to use option

please, you use option

I won't use option

I will use option

interpret as subnegotiation

you may reverse the line

erase the current line

erase the current character

are you there

abort output--but let prog finish

interrupt process--permanently

break

data mark--for connect. cleaning

nop

end sub negotiation

end of record (transparent mode)

Abort process

Suspend process

End of file: EOF is already used...

for telfunc calls

Table of TELNET options.

8-bit data path

echo

prepare to reconnect

suppress go ahead

approximate message size

give status

timing mark

remote controlled transmission and echo

negotiate about output line width

negotiate about output page size

negotiate about CR disposition

negotiate about horizontal tabstops

negotiate about horizontal tab disposition

negotiate about formfeed disposition

negotiate about vertical tab stops

negotiate about vertical tab disposition

negotiate about output LF disposition

extended ascic character set

force logout

byte macro

data entry terminal

supdup protocol

supdup output

send location

terminal type

end or record

TACACS user identification

output marking

terminal location number

3270 regime

X.3 PAD

window size

terminal speed

remote flow control

Linemode option

X Display Location

Old - Environment variables

Authenticate

Encryption option

New - Environment variables

extended-options-list

Implementation of the TELNET protocol.

The connection.

Mapping containing extra callbacks.

Value to send to the callbacks.

Write callback.

``

Read callback.

``

Close callback.

``

Negotiation states of all WILL/WON'T options. See RFC 1143 for a description of the states.

Data queued to be sent.

Indicates that connection should be closed

Tells if we have set the nonblocking write callback or not.

Turns on the write callback if apropriate.

Turns off the write callback if apropriate.

Queues data to be sent to the other end of the connection.

String to send.

Queues raw data to be sent to the other end of the connection.

String with raw telnet data to send.

Closes the connetion neatly

Callback called when it is clear to send data over the connection. This function does the actual sending.

Sends a TELNET synch command.

Starts negotiation to enable a TELNET option.

The option to enable.

Starts negotiation to disable a TELNET option.

The option to disable.

Indicates whether we are in synch-mode or not.

Callback called when Out-Of-Band data has been received.

The id from the connection.

The Out-Of-Band data received.

Calls read_cb().

Specifically provided for overloading

Callback called when normal data has been received. This function also does most of the TELNET protocol parsing.

The id from the connection.

The received data.

Sets the callback to be called when it is clear to send.

The new write callback.

``

Called when the initial setup is done.

Created specifically for overloading

Creates a TELNET protocol handler, and sets its callbacks.

File to use for the connection.

Function to call when data has arrived.

Function to call when data can be sent.

Function to call when the connection is closed.

Mapping with callbacks for the various TELNET commands.

Value to send to the various callbacks.

``
``
``

Line-oriented TELNET protocol handler.

protocol

Line-oriented TELNET protocol handler with Stdio.Readline support.

LineMode
TelnetCodes
Telopts

option is...

send option

ENVIRON: informational version of IS

AUTHENTICATION: client version of IS

AUTHENTICATION: client version of IS

Disable remote flow control

Enable remote flow control

Restart output on any char

Restart output only on XON

Client authenticating server

Server authenticating client

An implementation of the IDENT protocol, specified in RFC 931.

``

Throws exception upon any error.

A MP3 file parser with ID3 tag support.

.module.ANY

Gets next frame from file

Frame is represented by the following mapping. It contains from parsed frame headers and frame data itself.

([ "bitrate": int "copyright": int(0..1), "data": frame_data, "emphasis": emphasis, "extension": "channels":0, "id":1, "layer":3, "original": int(0..1), "padding": int(0..1), "private": int(0..1), "sampling": int ])

Audio data format handling

API remains marked "unstable".

Reads data from file

read_streamed

this_program

Reads data from stream

Ie. for packetized data source the beggining of data is searched.

read_file

this_program

Reads data from string

this_program

Returns frame for current position and moves cursor forward.

The operation is destructive. Ie. current data cursor is moved over.

get_data, get_sample

Returns sample for current position and moves cursor forward.

The operation is destructive. Ie. current data cursor is moved over.

get_frame, get_data

Returns data only.

The operation is destructive. Ie. current data cursor is moved over.

get_frame, get_sample

Check if data are correctly formated.

Decoder object.

It needs _Ffmpeg.ffmpeg module for real work.

Creates decoder object

Some of supported codec, like _Ffmpeg.CODEC_ID_*

The low level object will be used for decoder. By default _Ffmpeg.ffmpeg object will be used.

Until additional library is implemented the second parameter _codec hasn't effect.

_Ffmpeg.ffmpeg, _Ffmpeg.CODEC_ID_MP2

Set codec type from file

It uses Audio.Format.ANY's method get_map() to determine which codec should be used.

The object Audio.Format.ANY.

Audio.Format.ANY
this_program

Decodes audio data

Only one frame will be decoded per call.

If successfull a mapping with decoded data and byte number of used input data is returned, 0 otherwise.

Returns decoder status

An iterator which makes all the left/right entities in the relation available as index/value pairs.

Return true/false: does the relation "left R right" exist?

Does the same as the contains function: returns true if the relation "left R right" exists, and otherwise false.

Adds "left R right" as a member of the relation. Returns the same relation.

this_program

Removes "left R right" as a member of the relation. Returns the same relation.

this_program

Maps every entry in the relation. The function f gets two arguments: the left and the right relation value. Returns an array with the return values of f for each and every mapped entry.

Note: since the entries in the relation are not ordered, the returned array will have its elements in no particular order. If you need to know which relation entry produced which result in the array, you have to make that information part of the value that f returns.

``

Filters the entries in the relation, and returns a relation with all those entries for which the filtering function f returned true. The function f gets two arguments: the left and the right value for every entry in the relation.

``

Filters the entries in the relation destructively, removing all entries for which the filtering function f returns false. The function f gets two arguments: the left and the right value for each entry in the relation.

``
this_program

Returns the number of relation entries in the relation. (Or with other words: the number of relations in the relation set.)

The expression `rel1 <= rel2' returns true if every relation entry in rel1 is also present in rel2.

The expression `rel1 & rel2' returns a new relation which has those and only those relation entries that are present in both rel1 and rel2.

The expression `rel1 | rel2' and `rel1 + rel2' returns a new relation which has all the relation entries present in rel1, or rel2, or both.

The expression `rel1 - rel2' returns a new relation which has those and only those relation entries that are present in rel1 and not present in rel2.

Makes the relation symmetric, i.e. makes sure that if xRy is part of the relation set, then yRx should also be a part of the relation set.

this_program

Assuming the relation's domain and range sets are equal, and that the relation xRy means "there is a path from node x to node y", find_shortest_path attempts to find a path with a minimum number of steps from one given node to another. The path is returned as an array of nodes (including the starting and ending node), or 0 if no path was found. If several equally short paths exist, one of them will be chosen pseudorandomly.

Trying to find a path from a node to itself will always succeed, returning an array of one element: the node itself. (Or in other words, a path with no steps, only a starting/ending point).

The argument avoiding is either 0 (or omitted), or a multiset of nodes that must not be part of the path.

Return the ID value which was given as first argument to create().

This class implements a priority queue. Each element in the priority queue is assigned a priority value, and the priority queue always remains sorted in increasing order of the priority values. The top of the priority queue always holds the element with the smallest priority. The priority queue is realized as a (min-)heap.

.Heap

Push an element val into the priority queue and assign a priority value pri to it. The priority queue will automatically sort itself so that the element with the smallest priority will be at the top.

Adjust the priority value new_pri of an element handle in the priority queue. The priority queue will automatically sort itself so that the element with the smallest priority value will be at the top.

Removes and returns the item on top of the heap, which also is the smallest value in the heap.

Returns the item on top of the priority queue (which is also the element with the smallest priority value) without removing it.

Implements a struct which can be used for serialization and deserialization of data.

class ID3 { inherit ADT.Struct; Item head = Chars(3); Item title = Chars(30); Item artist = Chars(30); Item album = Chars(30); Item year = Chars(4); Item comment = Chars(30); Item genre = Byte(); }

Stdio.File f = Stdio.File("foo.mp3"); f->seek(-128); ADT.Struct tag = ID3(f); if(tag->head=="TAG") { write("Title: %s\n", tag->title); tag->title = "A new title" + "\0"*19; f->seek(-128); f->write( (string)tag ); }

Interface class for struct items.

One byte, integer value between 0 and 255.

Item

The byte can be initialized with an optional value.

0 255

One word (2 bytes) in network order, integer value between 0 and 65535.

Drow

Item

The byte can be initialized with an optional value.

0

One word (2 bytes) in intel order, integer value between 0 and 65535.

Word

Word

One longword (4 bytes) in network order, integer value between 0 and 2^32.

Gnol

Word

One longword (4 bytes) in intel order, integer value between 0 and 2^32.

Long

Drow

A string of bytes.

Item

The number of bytes that are part of this struct item. The initial value of the char string is value or, if not provided, a string of zero bytes.

Data to be decoded and populate the struct. Can either be a file object or a string.

Stdio.File

Decodes data according to the struct and populates the struct variables. The data can either be a file object or a string.

Stdio.File

Serializes the struct into a string. This string is equal to the string fed to decode if nothing in the struct has been altered.

The struct can be indexed by item name to get the associated value.

It is possible to assign a new value to a struct item by indexing it by name and assign a value.

The indices of a struct is the name of the struct items.

The values of a struct is the values of the struct items.

The size of the struct object is the number of bytes allocated for the struct.

The struct can be casted into a string, which is eqivivalent to running encode, or into an array. When casted into an array each array element is the encoded value of that struct item.

A simple FIFO queue.

Creates a queue with the initial items args in it.

Adds the item to the queue.

Returns the next element from the queue.

Returns the next element from the queue without removing it from the queue.

Returns true if the queue is empty, otherwise zero.

0
1

Empties the queue.

It is possible to cast ADT.Queue to an array.

Various Abstract Data Types.

String buffer with the possibility to read and write data as they would be formatted in structs.

Create a new buffer, optionally initialized with the value s.

Trims the buffer to only contain the data after the read pointer and returns the contents of the buffer.

Adds the data s verbatim to the end of the buffer.

Return all the data in the buffer and empties it.

Appends an unsigned integer in network order to the buffer.

Unsigned integer to append.

Length of integer in bytes.

Appends a variable string s preceded with an unsigned integer of the size len_width declaring the length of the string. The string s should be 8 bits wide.

Appends a bignum i as a variable string preceded with an unsigned integer of the size len_width declaring the length of the string. len_width defaults to 2.

Gmp.mpz

Appends the fix sized string s to the buffer.

Appends an array of unsigned integers of width item_size to the buffer.

Appends an array of unsigned integers of width item_size to the buffer, preceded with an unsigned integer len declaring the size of the array.

Reads an unsigned integer from the buffer.

0

Reads a fixed sized string of length len from the buffer.

Reads a string written by put_var_string from the buffer.

Reads a bignum written by put_bignum from the buffer.

Gmp.mpz

Get the remaining data from the buffer and clears the buffer.

Reads an array of integers as written by put_fix_uint_array from the buffer.

Reads an array of integers as written by put_var_uint_array from the buffer.

Returns one of there is any more data to read.

0
1
_ADT

A history is a stack where you can only push entries. When the stack has reached a certain size the oldest entries are removed on every push. Other proposed names for this data type is leaking stack and table (where you push objects onto the table in one end and objects are falling off the table in the other.

max_size is the maximum number of entries that can reside in the history at the same time.

Change how the History object should treat two identical values in a row. If 1 than only unique values are allowed after each other.

query_no_adjacent_duplicates

0 1

Tells if the History object allows adjacent equal values. 1 means that only uniqe values are allowed adter each other.

set_no_adjacent_duplicates

0
1

Push a new value into the history.

A sizeof operation on this object returns the number of elements currently in the history, e.g. <= the current max size.

Returns the maximum number of values in the history

set_maxsize

Returns the absolute sequence number of the latest result inserted into the history.

Returns the absolute sequence number of the oldest result still in the history. Returns 0 if there are no results in the history.

Get a value from the history as if it was an array, e.g. both positive and negative numbers may be used. The positive numbers are however offset with 1, so [1] is the first entry in the history and [-1] is the last.

Overwrite one value in the history. The history position may be identified either by positive or negative offset, like `[].

Set the maximume number of entries that can be stored in the history simultaneous.

get_maxsize

Empties the history. All entries in the history are removed, to allow garbage collect to remove them. The entry sequence counter is not reset.

Returns the index numbers of the history entries available.

Returns the values of the available history entries.

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.

The table base-class.

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

This method returns a table object from a binary string representation of a table, as returned by encode().

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

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.

This method returns the number of rows in the table.

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

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

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

Same as col().

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.

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.

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.

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

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

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.

``

This method calls the function f 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.

````
this_program

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.

this_program

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.

this_program

This method calls the function f 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.

``

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.

rsort()

Like sort(), but in descending order.

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

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

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

The ADT.Table.table class takes two or three arguments:

The first argument 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.

This argument 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.

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

ADT.Table.ASCII.encode()

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.

This class implements a (min-)heap. The value of a child node will always be greater than or equal to the value of its parent node. Thus, the top node of the heap will always hold the smallest value.

Push an element onto the heap. The heap will automatically sort itself so that the smallest value will be at the top.

Takes a value in the heap and sorts it through the heap to maintain its sort criteria (increasing order).

Removes and returns the item on top of the heap, which also is the smallest value in the heap.

Returns the number of elements in the heap.

Removes and returns the item on top of the heap, which also is the smallest value in the heap.

Returns the number of elements in the heap.

Returns the item on top of the heap (which is also the smallest value in the heap) without removing it.

Implements a FIFO bit buffer, i.e. a buffer that operates on bits instead of bytes. It is not designed for performance, but as a way to handle complicated file formats and other standards where you may need to work on unaligned data units of sub byte size, without having to fry your brain while keeping track of all the bits yourself.

> ADT.BitBuffer b=ADT.BitBuffer(); > b->put1(2); (1) Result: ADT.BitBuffer(11) > b->put0(15); (2) Result: ADT.BitBuffer("À\0"0) > b->drain(); (3) Result: "À\0" > sizeof(b); (4) Result: 1

The buffer can be initialized with initial data during creation.

Adds full bytes to the buffer.

this_program

Drains the buffer of all full (8-bits wide) bytes.

Get bits from the buffer.

Throws an error in case of data underflow.

Put bits number of bits with the value value into the buffer.

value must not be larger than what can be stored with the number of bits given in bits.

this_program

Put bits number of 0 bits into the buffer.

this_program

Put bits number of 1 bits into the buffer.

this_program

sizeof() will return the number of bits in the buffer.

This class implements a simple stack. Instead of adding and removing elements to an array, and thus making it vary in size for every push and pop operation, this stack tries to keep the stack size constant. If however the stack risks to overflow, it will allocate double its current size, i.e. pushing an element on an full 32 slot stack will result in a 64 slot stack with 33 elements.

Push an element on the top of the stack.

Returns the top element from the stack, without popping it.

Throws an error if called on an empty stack.

Pops val entries from the stack, or one entry if no value is given. The popped entries are not actually freed, only the stack pointer is moved.

Pops and returns entry val from the stack, counting from the top. If no value is given the top element is popped and returned. All popped entries are freed from the stack.

Empties the stack, resets the stack pointer and shrinks the stack size to the given value or 32 if none is given.

create

An initial stack size can be given when a stack is cloned. The default value is 32.

Sets the stacks content to the provided array.

sizeof on a stack returns the number of entries in the stack.

values on a stack returns all the entries in the stack, in order.

A stack added with another stack yields a third a third stack will all the stack elements from the two first stacks.

this_program
this_program

The sequence work similar to an array but has the possibilities to insert and remove elements. It also has a more powerful iterator.

This is the iterator for the Sequence. It implements the IndexIterator and the OutputIterator

Creates a new iterator for the sequence sequence. If start is supplied it will try to position the iterator at start.

The index at the current position.

The value at the current position.

Move the iterator steps steps forward (negative value on steps will cause the iterator to move backwards) and return the result as a new iterator.

A new iterator positioned steps steps forward.

SequenceIterator

Move this iterator steps steps forward (negative value on steps will cause the iterator to move backwards) and return the result.

This iterator positioned steps steps forward.

SequenceIterator

Move the iterator steps steps backwards (negative value on steps will cause the iterator to move forwards) and return the result as a new iterator.

A new iterator positioned steps steps backwards.

SequenceIterator

Returns true if it is possible to move steps steps forwards, if steps weren't supplied it check if it is possible to move one step forward.

0
1

Returns true if it is possible to move steps steps backwards, if steps weren't supplied it check if it is possible to move one step backward.

0
1

Returns false if the iterator has reached the end.

0
1

Compare this iterator with another iterator.

The iterator to compare with.

Returns true if both iterators iterates over the same objects and are positioned at the same spot.

0
1

Less then operator.

Returns true if this iterator has a lower index then iter.

0
1

Greater then operator.

Returns true if this iterator has a higher index then iter.

0
1

The iterator to measure the distance to.

Returns distance between this iterator and iter.

An error if the two iterator could not be compared.

Returns the Sequence this iterator currently iterates over.

Sequence

Set the value at the current position.

The new value.

Returns the old value.

Index operator.

The index to get the value for, could be negative to index from the end.

The value at the index index.

An error if the index is out of range.

Index assign operator. Set the value at the index index to be value.

The index to set.

The new value.

The new value at the index index.

Addition operator Append the content of coll to thies sequence and return the results as a new Sequence.

The sequence to append to his sequence.

The result of the append as a new Sequence.

Sequence
Sequence

Subtraction operator Removes those values in this sequence that also are present in coll and return the results as a new Sequence.

The sequence to subtract from this sequence.

The result of the subtraction as a new Sequence.

Sequence
Sequence

And operator Perform an and on this sequence and the coll sequence by only returning those values that is present in both sequences as a new Sequence. The remaining values is in the same order as they are in this sequence and the values are compared using `==.

The sequence to and to this sequence.

The result of the and as a new Sequence.

Sequence
Sequence

Or operator Perform an or on this sequence and the coll sequence by returning those values that is present in both sequences as a new Sequence. The values are compared using `==.

The sequence to or with this sequence.

The result of the or as a new Sequence.

Sequence
Sequence

Xor operator Perform a xor on this sequence and the coll sequence by returning those values that is present in one of the sequences but not in both adapters as a new Sequence. The values are compared using `==.

The sequence to xor with this sequence.

The result of the xor as a new Sequence.

Sequence
Sequence

Returns true if the object coll is a Sequence and contains the same values in the same order.

0
1

The indices in this adapter as an array.

Insert an element in the sequence at the position index, the value at the position index and all above will have their index increased with one.

The index to insert the value at.

The new value.

Remove the values at index index from the sequence.

The index to remove.

The removed value.

Search the sequence for a specific value. Return the index of the first value that is equal to value. If no value was found UNDEFINED is returned instead.

The value to find.

If a start value is supplied it will start searching at the index start.

Returns the index of the found value or UNDEFINED.

The number of elements in this adapter.

The values in this adapter as an array.

Add a value at the end of the sequence.

The value to add.

Cast operator.

Casts to this type.

Casts to the following types are supported:

"array"

Cast the content of this sequence to an array.

An array with the contents of this sequence.

Clear the contents of the sequence.

Remove the first occurrence of the value value from the sequence.

The value to remove from the sequence.

The index of the removed element or -1 if there was no value to remove.

Returns 1 if the sequence is empty otherwise 0.

0
1

Returns -1.

Creates a new Sequence around the array arg or a new Sequence with the size of arg.

Create and initiate a new SequenceIterator that could be used to iterate over this sequence.

If an ind value is supplied the iterator will be positioned at that index.

An iterator.

SequenceIterator

Create and initiate a new SequenceIterator that could be used to iterate over this sequence.

An iterator positioned at the first element in the sequence.

SequenceIterator

Create and initiate a new SequenceIterator that could be used to iterate over this sequence.

An iterator positioned after the last element in the sequence.

SequenceIterator

This is an circular list implemented by an array. It has a constant time complexity for pop and push. It has a limited max size but it can be increased with the method allocate.

This is the iterator for the CircularList. It implements the IndexIterator and the OutputIterator.

Creates a new iterator for the CircularList list. If start is supplied it will try to position the iterator at start.

The index at the current position.

The value at the current position.

Move the iterator steps steps forward (negative value on steps will cause the iterator to move backwards) and return the result as a new iterator.

A new iterator positioned steps steps forward.

CircularListIterator

Move this iterator steps steps forward (negative value on steps will cause the iterator to move backwards) and return the result.

This iterator positioned steps steps forward.

CircularListIterator

Move the iterator steps steps backwards (negative value on steps will cause the iterator to move forwards) and return the result as a new iterator.

A new iterator positioned steps steps backwards.

CircularListIterator

Returns true if it is possible to move steps steps forwards, if steps weren't supplied it check if it is possible to move one step forward.

0
1

Returns true if it is possible to move steps steps backwards, if steps weren't supplied it check if it is possible to move one step backward.

0
1

Returns false if the iterator has reached the end.

0
1

Compare this iterator with another iterator.

The iterator to compare with

Returns true if both iterators iterates over the same objects and are positioned at the same spot.

0
1

Less then operator

Returns true if this iterator has a lower index then iter.

0
1

Greater then operator

Returns true if this iterator has a higher index then iter.

0
1

The iterator to measure the distance to.

Returns distance between this iterator and iter.

An error if the two iterator could not be compared.

Returns the CircularList this iterator currently iterates over.

CircularList

Set the value at the current position.

The new value

Returns the old value

Index operator

The index to get the value for, could be negative to index from the end.

The value at the index index

An error if the index is out of range.

Index assign operator. Set the value at the index index to be value

The index to set

The new value

The new value at the index index

An error if the index is out of range.

Addition operator Append the content of this CircularList and coll and return the results as a new CircularList.

The list to append to his list

The result of the append as a new CircularList.

CircularList
CircularList

Returns true if the object coll is a CircularList and contains the same values in the same order.

0
1

The indices in this list as an array.

Insert an element in the list at the position index, the value at the position index and all above will have thier index increased with one.

The index to insert the value at.

The new value.

An error if the index is out of range.

Remove the values at index index from the list.

The index to remove.

The removed value.

An error if the index is out of range.

Search the list for a specific value. Return the index of the first value that is equal to value. If no value was found UNDEFINED is returned instead

The value to find

If a start value is supplied it will start searching at the index start.

Returns the index of the found value or UNDEFINED.

An error if the start is out of range.

The number of elements in this list.

The values in this list as an array.

Add a value at the front of the list

The value to add.

An error if the list is full.

Increase the maxsize of the CircularlList.

Add this number of new elements to the list.

Cast operator.

Casts to this type.

Casts to the following types are supported:

"array"

Cast the content of this list to an array.

An array with the contents of this list.

Clear the contents of the list.

Remove the first occurrence of the value value from the list.

The value to remove from the list.

The index of the removed element or -1 if there was no value to remove.

Returns 1 if the list is empty otherwise 0.

0
1

Returns the maximal size of this list.

The value at the back of the list but do not remove it from the list.

The value at the front of the list but do not remove it from the list.

Remove the value at the back of the list and return it.

The value at the back of the list.

Remove the value at the front of the list and return it.

The value at the front of the list.

Add a new value at the end of the list.

The value to add.

Add a new value at the end of the list.

The value to add.

Creates a new CircularList around the array arg or a new CircularList with the maximum size of arg.

Create and initiate a new CircularListIterator that could be used to iterate over this list.

If an ind value is supplied the iterator will be positioned at that index.

An iterator.

CircularListIterator

Create and initiate a new CircularListIterator that could be used to iterate over this list.

An iterator positioned at the first element in the list.

CircularListIterator

Create and initiate a new CircularListIterator that could be used to iterate over this list.

An iterator positioned after the last element in the list.

CircularListIterator

This module generates an LR parser from a grammar specified according to the following grammar:

            directives : directive ;
    	   directives : directives directive ;
    	   directive : declaration ;
    	   directive : rule ;
    	   declaration : "%token" terminals ";" ;
    	   rule : nonterminal ":" symbols ";" ;
    	   rule : nonterminal ":" symbols action ";" ;
    	   symbols : symbol ;
    	   symbols : symbols symbol ;
    	   terminals : terminal ;
    	   terminals : terminals terminal ;
    	   symbol : nonterminal ;
    	   symbol : "string" ;
    	   action : "{" "identifier" "}" ;
    	   nonterminal : "identifier" ;
    	   terminal : "string";

Parser.LR

Error code from the parsing.

Compiles the parser-specification given in the first argument. Named actions are taken from the object if available, otherwise left as is.

Returns error-code in both GrammarParser.error and return_value->lr_error.

Parser

Compiles the file specified in the first argument into an LR parser.

make_parser

Parser

Specifies the priority and associativity of a rule.

Priority value

Associativity

-1

Left

0

None

1

Right

Create a new priority object.

Priority.

Associativity.

This object is used to represent a BNF-rule in the LR parser.

Non-terminal this rule reduces to.

The actual rule

Action to do when reducing this rule. function - call this function. string - call this function by name in the object given to the parser. The function is called with arguments corresponding to the values of the elements of the rule. The return value of the function will be the value of this non-terminal. The default rule is to return the first argument.

``

This rule contains tokens

This rule has this many non-nullable symbols at the moment.

Sequence number of this rule (used for conflict resolving) Also used to identify the rule.

Priority and associativity of this rule.

Priority

Create a BNF rule.

The rule

rule : nonterminal ":" symbols ";" { add_rule };

might be created as

rule(4, ({ 9, ":", 5, ";" }), "add_rule");

where 4 corresponds to the nonterminal "rule", 9 to "nonterminal" and 5 to "symbols", and the function "add_rule" is too be called when this rule is reduced.

Non-terminal to reduce to.

Symbol sequence that reduces to nt.

Action to do when reducing according to this rule. function - Call this function. string - Call this function by name in the object given to the parser. The function is called with arguments corresponding to the values of the elements of the rule. The return value of the function will become the value of this non-terminal. The default rule is to return the first argument.

``

Severity level

Class handling reporting of errors and warnings.

Verbosity level

-1

Just errors.

0

Errors and warnings.

1

Also notices.

-1 1

Create a new error handler.

Level of verbosity.

verbose

-1 1

This object implements an LALR(1) parser and compiler.

Normal use of this object would be:

     set_error_handler
     {add_rule, set_priority, set_associativity}*
     set_symbol_to_string
     compile
     {parse}*

An LR(0) item, a partially parsed rule.

The rule

Rule

How long into the rule the parsing has come.

The state we will get if we shift according to this rule

Kernel

Item representing this one (used for shifts).

Item

Look-ahead set for this item.

Look-ahead set used for detecting conflicts

Relation to other items (used when compiling).

Item

Depth counter (used when compiling).

Item identification number (used when compiling).

Used to identify the item. Equal to r->number + offset.

Implements an LR(1) state

Used to check if a rule already has been added when doing closures.

Rule

Contains the items in this state.

Item

Used to lookup items given rule and offset

Item

Contains the items whose next symbol is this non-terminal.

Item

The action table for this state

     object(kernel)    SHIFT to this state on this symbol.
     object(rule)      REDUCE according to this rule on this symbol.

Kernel Rule

The symbols that closure has been called on.

Add an item to the state.

Item

Make the closure of this state.

Nonterminal to make the closure on.

Make the goto-set of this state.

Generates the state reached when doing goto on the specified symbol. i.e. it compiles the LR(0) state.

Symbol to make goto on.

Kernel

This is a queue, which keeps the elements even after they are retrieved.

Index of the head of the queue.

Index of the tail of the queue.

The queue itself.

Kernel

Pushes the state on the queue.

State to push.

Kernel
Kernel

Return the next state from the queue.

Kernel

The grammar itself.

Rule

The initial LR0 state.

Kernel

Error code

LR0 states that are already known to the compiler.

Kernel

Compile error and warning handler.

`SeverityLevel`

Pretty-prints a rule to a string.

Rule to print.

Rule

Pretty-prints an item to a string.

Item to pretty-print.

Item

Pretty-prints a state to a string.

State to pretty-print.

Kernel

Pretty-prints the current grammar to a string.

Implements casting.

Type to cast to.

Sets the priority of a terminal.

Terminal to set the priority for.

Priority; higher = prefer this terminal.

Sets the associativity of a terminal.

Terminal to set the associativity for.

Associativity; negative - left, positive - right, zero - no associativity.

Sets the symbol to string conversion function. The conversion function is used by the various *_to_string functions to make comprehensible output.

Symbol to string conversion function. If zero or not specified, use the built-in function.

``

Sets the error report function.

Function to call to report errors and warnings. If zero or not specifier, use the built-in function.

`SeverityLevel`

Add a rule to the grammar.

Rule to add.

Rule

Contains all states used. In the queue section are the states that remain to be compiled.

StateQueue

Compiles the grammar into a parser, so that parse() can be called.

Parse the input according to the compiled grammar. The last value reduced is returned.

The parser must have been compiled (with compile()) prior to calling this function.

Errors should be throw()n.

The scanner function. It returns the next symbol from the input. It should either return a string (terminal) or an array with a string (terminal) and a mixed (value). EOF is indicated with the empty string.

Object used to resolve those actions that have been specified as strings.

``

Validating XML parser.

Validates an XML file according to a DTD.

cf http://wwww.w3.org/TR/REC-xml/ cf RFC3023

$Id: Validating.pike,v 1.5 2006/07/19 12:34:57 grubba Exp $

Parser.XML.Simple

Document this function

``

Document this function

``

XML parser that generates node-trees.

Has some support for XML namespaces http://www.w3.org/TR/REC-xml-names/ RFC 2518 23.4.

This module defines two sets of node trees; the SimpleNode-based, and the Node-based. The main difference between the two, is that the Node-based trees have parent pointers, which tend to generate circular data references and thus garbage.

There are some more subtle differences between the two. Please read the documentation carefully.

Namespace aware parser.

Check attrs for namespaces.

Returns the namespace expanded version of attrs.

Base class for nodes.

Returns all the nodes children.

AbstractSimpleNode

Returns the number of children of the node.

Returns an initialized copy of the node.

The returned node has no children.

AbstractSimpleNode

Returns a clone of the sub-tree rooted in the node.

AbstractSimpleNode

Returns the last childe node or zero.

AbstractSimpleNode

The [] operator indexes among the node children, so node[0] returns the first node and node[-1] the last.

The [] operator will select a node from all the nodes children, not just its element children.

AbstractSimpleNode

Adds a child node to this node. The child node is added last in the child list.

The return value differs from the one returned by Node()->add_child().

The current node.

AbstractSimpleNode
AbstractSimpleNode

Removes all occurrences of the provided node from the called nodes list of children.

AbstractSimpleNode

Replaces the nodes children with the provided ones.

AbstractSimpleNode

Replaces the first occurrence of the old node child with the new node child.

The return value differs from the one returned by Node()->replace_child().

Returns the current node on success, and 0 (zero) if the node old wasn't found.

AbstractSimpleNode
AbstractSimpleNode
AbstractSimpleNode

Destruct the tree recursively. When the inheriting AbstractNode or Node is used, which have parent pointers, this function should be called for every tree that no longer is in use to avoid frequent garbage collector runs.

Traverse the node subtree in preorder, root node first, then subtrees from left to right, calling the callback function for every node. If the callback function returns STOP_WALK the traverse is promptly aborted and STOP_WALK is returned.

`AbstractSimpleNode`

Traverse the node subtree in preorder, root node first, then subtrees from left to right. For each node we call cb_1 before iterating through children, and then cb_2 (which always gets called even if the walk is aborted earlier). If the callback function returns STOP_WALK the traverse decend is aborted and STOP_WALK is returned once all waiting cb_2 functions have been called.

`AbstractSimpleNode`
`AbstractSimpleNode`

Traverse the node subtree in inorder, left subtree first, then root node, and finally the remaining subtrees, calling the function callback for every node. If the function callback returns STOP_WALK the traverse is promptly aborted and STOP_WALK is returned.

`AbstractSimpleNode`

Traverse the node subtree in postorder, first subtrees from left to right, then the root node, calling the function callback for every node. If the function callback returns STOP_WALK the traverse is promptly aborted and STOP_WALK is returned.

`AbstractSimpleNode`

Iterates over the nodes children from left to right, calling the function callback for every node. If the callback function returns STOP_WALK the iteration is promptly aborted and STOP_WALK is returned.

`AbstractSimpleNode`

Returns a list of all descendants in document order. Includes this node if include_self is set.

0 1
AbstractSimpleNode

Base class for nodes with parent pointers.

AbstractSimpleNode

Sets the parent node to parent.

AbstractNode

Returns the parent node.

AbstractNode

Returns an initialized copy of the node.

The returned node has no children, and no parent.

AbstractNode

Clones the node, optionally connected to parts of the tree. If direction is -1 the cloned nodes parent will be set, if direction is 1 the clone nodes childen will be set.

-1 1
AbstractNode

Follows all parent pointers and returns the root node.

AbstractNode

Adds a child node to this node. The child node is added last in the child list and its parent reference is updated.

Returns the child node, NOT the current node.

The updated child node is returned.

AbstractNode
AbstractNode

Variant of add_child that doesn't set the parent pointer in the child.

This is useful while building a node tree, to get efficient refcount garbage collection if the build stops abruptly. fix_tree has to be called on the root node when the building is done.

AbstractNode
AbstractNode

Fix all parent pointers recursively in a tree that has been built with tmp_add_child.

Removes all occurrences of the provided node from the called nodes list of children. The removed nodes parent reference is set to null.

AbstractNode

Removes this node from its parent. The parent reference is set to null.

Replaces the nodes children with the provided ones. All parent references are updated.

AbstractNode

Replaces the first occurrence of the old node child with the new node child. All parent references are updated.

The returned value is NOT the current node.

Returns the new child node.

AbstractNode
AbstractNode
AbstractNode

Replaces this node with the provided one.

Returns the new node.

AbstractNode
AbstractNode

Returns all preceding siblings, i.e. all siblings present before this node in the parents children list.

AbstractNode

Returns all following siblings, i.e. all siblings present after this node in the parents children list.

AbstractNode

Returns all siblings, including this node.

AbstractNode

Returns a list of all ancestors, with the top node last. The list will start with this node if include_self is set.

0 1
AbstractNode

Returns all preceding nodes, excluding this nodes ancestors.

AbstractNode

Returns all the nodes that follows after the current one.

AbstractNode

Node in XML tree

Returns this nodes attributes, which can be altered destructivly to alter the nodes attributes.

Returns this nodes name-space adjusted attributes.

set_short_namespaces() must have been called before calling this function.

Returns the node type. See defined node type constants.

Returns text content in node.

Returns the name of the element node, or the nearest element above if an attribute node.

Return name of tag or name of attribute node.

Change the tag name destructively. Can only be used on element and processing-instruction nodes.

Return fully qualified name of the element node.

If the node is an attribute node or a text node, its value is returned. Otherwise the child text nodes are concatenated and returned.

Returns the first element child to this node.

If provided, the first element child with that name is returned.

If specified, name matching will be done against the full name.

Returns the first matching node, and 0 if no such node was found.

0 1
AbstractNode

Returns all element children to this node.

If provided, only elements with that name is returned.

If specified, name matching will be done against the full name.

Returns an array with matching nodes.

0 1
AbstractNode

It is possible to cast a node to a string, which will return render_xml() for that node.

Creates an XML representation of the node sub tree. If the flag preserve_roxen_entities is set, entities on the form &foo.bar; will not be escaped.

Mapping from namespace prefix to namespace symbol prefix.

0 1

Creates an XML representation fo the node sub tree and streams the output to the file f. If the flag preserve_roxen_entities is set, entities on the form &foo.bar; will not be escaped.

Stdio.File
0 1

XML node without parent pointers and attribute nodes.

AbstractSimpleNode
VirtualNode

XML node with parent pointers.

AbstractNode
VirtualNode

Returns the name of the element node, or the nearest element above if an attribute node.

Returns the name of the attribute node.

Creates and returns an array of new nodes; they will not be added as proper children to the parent node, but the parent link in the nodes are set so that upwards traversal is made possible.

Node

Attribute nodes are created on demand

Quotes the string given in data by escaping &, < and >.

Quotes strings just like text_quote, but entities in the form &foo.bar; will not be quoted.

Quotes the string given in data by escaping &, <, >, ' and ".

Quotes strings just like attribute_quote, but entities in the form &foo.bar; will not be quoted.

Takes an XML string and produces a SimpleNode tree.

ParseFlags
SimpleNode

Loads the XML file path, creates a SimpleNode tree representation and returns the root node.

ParseFlags
SimpleNode

Takes an XML string and produces a node tree.

flags is not used for PARSE_WANT_ERROR_CONTEXT, PARSE_FORCE_LOWERCASE or PARSE_ENABLE_NAMESPACES since they are covered by the separate flag arguments.

0 1
0 1
0 1
ParseFlags
Node

Loads the XML file path, creates a node tree representation and returns the root node.

0 1
Node

A namespace aware version of Parser.XML.Tree. This implementation does as little validation as possible, so e.g. you can call your namespace xmlfoo without complaints.

Namespace aware node.

Node

Returns the namespace in which the current element is defined in.

Returns the default namespace in the current scope.

Returns a mapping with all the namespaces defined in the current scope, except the default namespace.

The returned mapping is the same as the one in the node, so destructive changes will affect the node.

Returns the attributes in this node that is declared in the provided namespace.

Returns all the attributes in all namespaces that is associated with this node.

The returned mapping is the same as the one in the node, so destructive changes will affect the node.

Adds a new namespace to this node. The preferred symbol to use to identify the namespace can be provided in the symbol argument. If chain is set, no attempts to overwrite an already defined namespace with the same identifier will be made.

0 1

Returns the difference between this nodes and its parents namespaces.

Returns the element name as it occurs in xml files. E.g. "zonk:name" for the element "name" defined in a namespace denoted with "zonk". It will look up a symbol for the namespace in the symbol tables for the node and its parents. If none is found a new label will be generated by hashing the namespace.

The remove_child is a not updated to take care of name space issues. To properly remove all the parents name spaces from the chid, call remove_node in the child.

NSNode
Parser.XML.Tree

Takes a XML string data and produces a namespace node tree. If default_ns is given, it will be used as the default namespace.

Throws an error when an error is encountered during XML parsing.

NSNode

Makes a visualization of a node graph suitable for printing out on a terminal.

> object x = parse_input("<a><b><c/>d</b><b><e/><f>g</f></b></a>"); > write(visualize(x)); Node(ROOT) NSNode(ELEMENT,"a") NSNode(ELEMENT,"b") NSNode(ELEMENT,"c") NSNode(TEXT) NSNode(ELEMENT,"b") NSNode(ELEMENT,"e") NSNode(ELEMENT,"f") NSNode(TEXT) Result 1: 201

Node
``
``
0 1

Set whether the parser should allow certain errors for compatibility with earlier versions. version can be:

"7.2"

Allow more data after the root element.

"7.6"

Allow multiple and invalidly placed "<?xml ... ?>" and "<!DOCTYPE ... >" declarations (invalid "<?xml ... ?>" declarations are otherwise treated as normal PI:s). Allow "<![CDATA[ ... ]]>" outside the root element. Allow the root element to be absent. This is the default in 7.6.

version can also be zero to enable all error checks.

``

A RCS file parser that eats a RCS *,v file and presents nice pike data structures of its contents.

Iterator for the deltatext sections of the RCS file. Typical usage:

string raw = Stdio.read_file(my_rcs_filename); Parser.RCS rcs = Parser.RCS(my_rcs_filename, 0); raw = rcs->parse_delta_sections(rcs->parse_admin_section(raw)); foreach(rcs->DeltatextIterator(raw); int n; Parser.RCS.Revision rev) do_something(rev);

the deltatext section of the RCS file in its entirety

This optional callback is invoked with the revision of the deltatext about to be parsed (useful for progress indicators).

Optional extra trailing arguments to be sent to progress_callback

the rcsfile(5) manpage outlines the sections of an RCS file

``

Drops the leading whitespace before next revision's deltatext entry and sets this_rev to the revision number we're about to read.

0
1

the number of deltatext entries processed so far (0..N-1, N being the total number of revisions in the rcs file)

the Revision at whose deltatext data we are, updated with its info

Revision

1 if the iterator has processed all deltatext entries, 0 otherwise.

0
1

Advance nsteps sections.

Returns the iterator object.

this_program

like `+=(1), but returns 0 if the iterator is finished

0
1

Restart not implemented; always returns 0 (==failed)

0
1

Chops off the first deltatext section from the token array raw and returns the rest of the string, or the value 0 (zero) if we had already visited the final deltatext entry. The deltatext's data is stored destructively in the appropriate entry of the revisions array.

raw must start with a deltatext entry for this method to work

does not handle rcsfile(5) newphrase skipping

if the rcs file is truncated, this method writes a descriptive error to stderr and then returns 0 - some nicer error handling wouldn't hurt

All data tied to a particular revision of the file.

the revision number (i e RCS->revisions["1.1"]->revision == "1.1")

the name of the user that committed the revision

when there are branches from this revision, an array of the revision numbers where each branch starts, otherwise 0

the state of the revision - typically "Exp" or "dead"

the (UTC) date and time when the revision was committed (second precision)

Calendar.TimeRange

the branch name on which this revision was committed (calculated according to how cvs manages branches)

the revision stored next in the rcs file, or 0 if none exists

the revision of the ancestor of this revision, or 0 if this was the initial revision

the revision that succeeds this revision, or 0 if none exists

the log message associated with the revision

the number of lines this revision contained, altogether (not of particular interest for binary files)

the number of lines that were added from the previous revision to make this revision (for the initial revision too)

the number of lines that were removed from the previous revision to make this revision

Parser._RCS

Version number of the head version of the file

The default branch (or revision), if present, 0 otherwise

0 0

The usernames listed in the ACCESS section of the RCS file

The RCS file comment if present, 0 otherwise

0 0

The keyword expansion options (as named by RCS) if present, 0 otherwise

The RCS file description

Maps from username to revision for users that have acquired locks on this file

1 if strict locking is set, 0 otherwise

0 1

Maps tag names (indices) to tagged revision numbers (values)

Maps branch numbers (indices) to branch names (values)

Data for all revisions of the file. The indices of the mapping are the revision numbers, whereas the values are the data from the corresponding revision.

Revision

Data for all revisions on the trunk, sorted in the same order as the RCS file stored them - ie descending, most recent first, I'd assume (rcsfile(5), of course, fails to state such irrelevant information).

Initializes the RCS object.

The path to the raw RCS file (includes trailing ",v"). Used mainly for error reporting (truncated RCS file).

If a string is provided, that string will be parsed to initialize the RCS object. If a zero (0) is sent, no initialization will be performed at all. If no value is given at all, but file_name was provided, that file will be loaded and parsed for object initialization.

0 0

Lower-level API function for parsing only the admin section (the initial chunk of an RCS file, see manpage rcsfile(5)) of an RCS file. After running parse_admin_section, the RCS object will be initialized with the values for head, branch, access, branches, tokenize, tags, locks, strict_locks, comment and expand.

The tokenized RCS file, or the raw RCS-file data.

The rest of the RCS file, admin section removed.

parse_delta_sections, parse_deltatext_sections, parse, create

Does not handle rcsfile(5) newphrase skipping.

Lower-level API function for parsing only the delta sections (the second chunk of an RCS file, see manpage rcsfile(5)) of an RCS file. After running parse_delta_sections, the RCS object will be initialized with the value of description and populated revisions mapping and trunk array. Their Revision members are however only populated with the members Revision->revision, Revision->branch, Revision->time, Revision->author, Revision->state, Revision->branches, Revision->rcs_next, Revision->ancestor and Revision->next.

The tokenized RCS file, with admin section removed. (See parse_admin_section.)

The rest of the RCS file, delta sections removed.

parse_admin_section, tokenize, parse_deltatext_sections, parse, create

Does not handle rcsfile(5) newphrase skipping.

Tokenize an RCS file into tokens suitable as argument to the various parse functions

The RCS file data

An array with arrays of tokens

Lower-level API function for parsing only the deltatext sections (the final and typically largest chunk of an RCS file, see manpage rcsfile(5)) of an RCS file. After a parse_deltatext_sections run, the RCS object will be fully populated.

The tokenized RCS file, with admin and delta sections removed. (See parse_admin_section, tokenize and parse_delta_sections.)

This optional callback is invoked with the revision of the deltatext about to be parsed (useful for progress indicators).

Optional extra trailing arguments to be sent to progress_callback

parse_admin_section, parse_delta_sections, parse, create

Does not handle rcsfile(5) newphrase skipping.

``

Parse the RCS file raw and initialize all members of this object fully initialized.

The unprocessed RCS file.

Passed on to parse_deltatext_sections.

The fully initialized object (only returned for API convenience; the object itself is destructively modified to match the data extracted from raw)

parse_admin_section, parse_delta_sections, parse_deltatext_sections, create

``
this_program

Returns the file contents from the revision rev, without performing any keyword expansion.

expand_keywords_for_revision

Revision

Expand keywords and return the resulting text according to the expansion rules set for the file.

The revision to apply the expansion for.

If supplied, substitute keywords for that text instead using values that would apply for the given revision. Otherwise, revision rev is used.

If 1, perform expansion even if the file was checked in as binary.

The Log keyword (which lacks sane quoting rules) is not expanded. Keyword expansion rules set in CVSROOT/cvswrappers are ignored. Only implements the -kkv and -kb expansion modes.

get_contents_for_revision

Revision

Returns the provided string with Python code as an array with tokens.

Returns a Parser.HTML initialized for parsing XML. It has all the flags set properly for XML syntax and callbacks to ignore comments, CDATA blocks and unknown PI tags, but it has no registered tags and doesn't decode any entities.

HTML

Decodes the numeric XML entity chref, e.g. "&#x34;" and returns the character as a string. chref is the name part of the entity, i.e. without the leading '&' and trailing ';'. Returns zero if chref isn't on a recognized form or if the character number is too large to be represented in a string.

Parse any HTML entities in the string to unicode characters. Either return a complete parser (to build on or use) or parse a string. Throw an error if there is an unrecognized entity in the string if noerror is not set.

Currently using XHTML 1.0 tables.

HTML
HTML

This module parses and tokenizes Pike source code.

"C.pmod"

Splits the data string into an array of tokens. An additional element with a newline will be added to the resulting array of tokens. If the optional argument state is provided the split function is able to pause and resume splitting inside #"" and /**/ tokens. The state argument should be an initially empty mapping, in which split will store its state between successive calls.

Represents a C token, along with a selection of associated data and operations.

The line where the token was found.

The actual token.

The file in which the token was found.

Trailing whitespaces.

If the object is printed as %s it will only output its text contents.

Tokens are considered equal if the text contents are equal. It is also possible to compare the Token object with a text string directly.

A string can be added to the Token, which will be added to the text contents.

A string can be added to the Token, which will be added to the text contents.

It is possible to case a Token object to a string. The text content will be returned.

Characters and ranges may be indexed from the text contents of the token.

Splits the data string into an array of tokens. An additional element with a newline will be added to the resulting array of tokens. If the optional argument state is provided the split function is able to pause and resume splitting inside /**/ tokens. The state argument should be an initially empty mapping, in which split will store its state between successive calls.

Returns an array of Token objects given an array of string tokens.

Token

Fold sub blocks of an array of tokens into sub arrays, for grouping purposes.

The token array to fold.

Supplies the tokens marking the boundaries of blocks to fold. The indices of the mapping mark the start of a block, the corresponding values mark where the block ends. The sub arrays will start and end in these tokens. If no groupings mapping is provided, {}, () and [] are used as block boundaries.

Token
Token

Strips off all (preprocessor) line statements from a token array.

Token
Token

Folds all whitespace tokens into the previous token's trailing_whitespaces.

Reconstitutes the token array into a plain string again; essentially reversing split() and whichever of the tokenize, group and hide_whitespaces methods may have been invoked.

Token

Like simple_reconstitute, but adding additional #line n "file" preprocessor statements in the output whereever a new line or file starts.

Token

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.

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 <ref>create</ref>)
    	 array(SGMLatom) data;  - contained data

SGMLatom

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

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

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

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

feed() returns the called object.

SGMLatom
SGMLatom

This is a simple parser for SGML structured markups. It's not really HTML, but it's useful for that *! purpose.

The simple way to use it is to give it some information about available tags and containers, and what callbacks those is to call.

The object is easily reused, by calling the clone() function.

add_tag, add_container, finish

These functions set up the parser object to call the given callbacks upon tags, entities and/or data. The callbacks will only be called if there isn't another tag/container/entity handler for these.

The callback function will be called with the parser object as first argument, and the active string as second. Note that no parsing of the contents has been done. Both endtags and normal tags are called; there is no container parsing.

The return values from the callbacks are handled in the same way as the return values from callbacks registered with add_tag and similar functions.

The data callback will be called as seldom as possible with the longest possible string, as long as it doesn't get called out of order with any other callback. It will never be called with a zero length string.

Returns the object being called.

``
Parser.HTML
``
Parser.HTML
``
Parser.HTML

Registers the actions to take when parsing various things. Tags, containers, entities are as usual. add_quote_tag() adds a special kind of tag that reads any data until the next occurrence of the end string immediately before a tag end.

This argument can be any of the following.

``

The function will be called as a callback function. It will get the following arguments, depending on the type of callback.

     mixed tag_callback(Parser.HTML parser,mapping args,mixed ... extra)
     mixed container_callback(Parser.HTML parser,mapping args,string content,mixed ... extra)
     mixed entity_callback(Parser.HTML parser,mixed ... extra)
     mixed quote_tag_callback(Parser.HTML parser,string content,mixed ... extra)

This tag/container/entity is then replaced by the string. The string is normally not reparsed, i.e. it's equivalent to writing a function that returns the string in an array (but a lot faster). If reparse_strings is set the string will be reparsed, though.

The first element is a function as above. It will receive the rest of the array as extra arguments. If extra arguments are given by set_extra(), they will appear after the ones in this array.

0

If there is a tag/container/entity with the given name in the parser, it's removed.

The callback function can return:

This string will be pushed on the parser stack and be parsed. Be careful not to return anything in this way that could lead to a infinite recursion.

The element(s) of the array is the result of the function. This will not be parsed. This is useful for avoiding infinite recursion. The array can be of any size, this means the empty array is the most effective to return if you don't care about the result. If the parser is operating in mixed_mode, the array can contain anything. Otherwise only strings are allowed.

0 0

This means "don't do anything", ie the item that generated the callback is left as it is, and the parser continues.

1 1

Reparse the last item again. This is useful to parse a tag as a container, or vice versa: just add or remove callbacks for the tag and return this to jump to the right callback.

Returns the object being called.

tags, containers, entities

Parser.HTML
Parser.HTML
Parser.HTML
Parser.HTML
Parser.HTML
Parser.HTML
Parser.HTML

Removes all registered definitions in the different categories.

Returns the object being called.

add_tag, add_tags, add_container, add_containers, add_entity, add_entities

Parser.HTML
Parser.HTML
Parser.HTML
Parser.HTML

Returns the current callback settings. When matching is done case insensitively, all names will be returned in lowercase.

Implementation note: These run in constant time since they return copy-on-write mappings.

add_tag, add_tags, add_container, add_containers, add_entity, add_entities

Returns the current callback settings. The values are arrays ({callback, end_quote}). When matching is done case insensitively, all names will be returned in lowercase.

Implementation note: quote_tags() allocates a new mapping for every call and thus, unlike e.g. tags() runs in linear time.

add_quote_tag

Feed new data to the Parser.HTML object. This will start a scan and may result in callbacks. Note that it's possible that all data fed isn't processed - to do that, call finish().

If the function is called without arguments, no data is fed, but the parser is run. If the string argument is followed by a 0, ->feed(s,0);, the string is fed, but the parser isn't run.

Returns the object being called.

finish, read, feed_insert

Parser.HTML
Parser.HTML

This pushes a string on the parser stack.

Returns the object being called.

Don't use!

Parser.HTML

Finish a parser pass. A string may be sent here, similar to feed().

Returns the object being called.

Parser.HTML
Parser.HTML

Read parsed data from the parser object.

Returns a string of parsed data if the parser isn't in mixed_mode, an array of arbitrary data otherwise.

Send data to the output stream, i.e. it won't be parsed and it won't be sent to the data callback, if any.

Any data is allowed when the parser is running in mixed_mode. Only strings are allowed otherwise.

Returns the object being called.

Parser.HTML

Returns the current position. Characters and columns count from 0, lines count from 1.

at() gives an array with the following layout.

0

Line.

1

Character.

2

Column.

Gives the current range of data, ie the whole tag/entity/etc being parsed in the current callback. Returns zero if there's no current range, i.e. when the function is not called in a callback.

Gives the name of the current tag, or zero. If used from an entity callback, it gives the string inside the entity.

Gives the arguments of the current tag, parsed to a convenient mapping consisting of key:value pairs. If the current thing isn't a tag, it gives zero. default_value is used for arguments which have no value in the tag. If default_value isn't given, the value is set to the same string as the key.

Gives the content of the current tag, if it's a container or quote tag. Otherwise returns zero.

Returns the equivalent of the following calls.

0

tag_name()

1

tag_args(default_value)

2

tag_content()

Returns the current output context as a string.

"data"

In top level data. This is always returned when called from tag or container callbacks.

"arg"

In an unquoted argument.

"splice_arg"

In a splice argument.

The return value can also be a single character string, in which case the context is a quoted argument. The string contains the starting quote character.

This function is typically only useful in entity callbacks, which can be called both from text and argument values of different sorts.

splice_arg

Parses the tag name from a tag string without the surrounding brackets, i.e. a string on the form "tagname some='tag' args".

Returns the tag name or an empty string if none.

Parses the tag arguments from a tag string without the name and surrounding brackets, i.e. a string on the form "some='tag' args".

Returns a mapping containing the tag arguments.

tag_args

This is a low-level way of debugging a parser. This gives a mapping of the internal state of the Parser.HTML object.

The format and contents of this mapping may change without further notice.

Clones the Parser.HTML object. A new object of the same class is created, filled with the parse setup from the old object.

This is the simpliest way of flushing a parse feed/output.

The arguments to clone is sent to the new object, simplifying work for custom classes that inherits Parser.HTML.

Returns the new object.

create is called _before_ the setup is copied.

Parser.HTML

Sets the extra arguments passed to all tag, container and entity callbacks.

Returns the object being called.

Parser.HTML

Gets the extra arguments set by set_extra().

Returns the object being called.

If given a string, it sets the splice argument name to it. It returns the old splice argument name.

If a splice argument name is set, it's parsed in all tags, both those with callbacks and those without. Wherever it occurs, its value (after being parsed for entities in the normal way) is inserted directly into the tag. E.g:

    <foo arg1="val 1" splice="arg2='val 2' arg3" arg4>

becomes

    <foo arg1="val 1" arg2='val 2' arg3 arg4>

if "splice" is set as the splice argument name.

All tags and containers are matched case insensitively, and argument names are converted to lowercase. Tags added with add_quote_tag() are not affected, though. Switching to case insensitive mode and back won't preserve the case of registered tags and containers.

Do not look for tags at all. Normally tags are matched even when there's no callbacks for them at all. When this is set, the tag delimiters '<' and '>' will be treated as any normal character.

Treat unknown tags and entities as text data, continuing parsing for tags and entities inside them.

When functions are specified with _set_tag_callback() or _set_entity_callback(), all tags or entities, respectively, are considered known. However, if one of those functions return 1 and ignore_unknown is set, they are treated as text data instead of making another call to the same function again.

A '>' in a tag argument closes both the argument and the tag, even if the argument is quoted.

Normally, the parser search indefinitely for the entity end character (i.e. ';'). When this flag is set, the characters '&', '<', '>', '"', ''', and any whitespace breaks the search for the entity end, and the entity text is then ignored, i.e. treated as data.

Unquoted nested tag starters and enders will be balanced when parsing tags. This is the default.

Maximum recursion depth during parsing. Recursion occurs when a tag/container/entity/quote tag callback function returns a string to be reparsed. The default value is 10.

Allow callbacks to return arbitrary data in the arrays, which will be concatenated in the output.

When a plain string is used as a tag/container/entity/quote tag callback, it's not reparsed if this flag is unset. Setting it causes all such strings to be reparsed.

Allow whitespace between the tag start character and the tag name.

Whether or not to use XML syntax to tell empty tags and container tags apart.

0

Use HTML syntax only. If there's a '/' last in a tag, it's just treated as any other argument.

1

Use HTML syntax, but ignore a '/' if it comes last in a tag. This is the default.

2

Use XML syntax, but when a tag that does not end with '/>' is found which only got a non-container tag callback, treat it as a non-container (i.e. don't start to seek for the container end).

3

Use XML syntax only. If a tag got both container and non-container callbacks, the non-container callback is called when the empty element form (i.e. the one ending with '/>') is used, and the container callback otherwise. If only a container callback exists, it gets the empty string as content when there's none to be parsed. If only a non-container callback exists, it will be called (without the content argument) for both kinds of tags.

Serbian language locale by Goran Opacic 1996/12/11

"abstract"

Spanish language locale

"abstract"

Italian language locale by Francesco Chemolli

"abstract"

Russian language locale

"abstract"

Dutch language locale by Stephen R. van den Berg

"abstract"

Finnish language locale created by Janne Edelman, Turku Unix Users Group ry, Turku, Finland

"abstract"

Norwegian language locale

"abstract"

Croatian language locale by Klara Makovac 1997/07/02

"abstract"

Abstract language locale class, inherited by all the language locale classes.

Array(string) with the months of the year, beginning with January.

Array(string) with the days of the week, beginning with Sunday.

String with the language code in ISO-639-1 (two character code). Note that all languages does not have a ISO-639-1 code.

String with the language code in ISO-639-2/T (three character code).

String with the language code in ISO-639-2/B (three character code). This is usually the same as the ISO-639-2/T code (iso_639_2).

The name of the language in english.

The name of the langauge. E.g. "svenska" for Swedish.

Mapping(string:string) that maps an ISO-639-2/T id code to the name of that language.

Returns the name of month number num.

1 12

Returns the name of weekday number num.

1 7

Returns the number i as a string.

Returns the ordered number i as a string.

Returns the date for posix time timestamp as a textual string.

Determines what kind of textual string should be produced.

"time"

I.e. "06:36"

"date"

I.e. "January the 17th in the year of 2002"

"full"

I.e. "06:37, January the 17th, 2002"

> Locale.Language.eng()->date(time()); Result: "today, 06:36"

French language locale by Patrick Kremer.

"abstract"

Slovenian language locale by Iztok Umek 7. 8. 1997

"abstract"

Japanese language locale.

"abstract"

Maaori (New Zealand) language locale by Jason Rumney

"abstract"

Czech language locale by Jan Petrous 16.10.1997, based on Slovenian language module by Iztok Umek.

"abstract"

English language locale.

"abstract"

Catalan language locale.

"abstract"

Hungarian language locale by Zsolt Varga.

"abstract"

Swedish language locale

"abstract"

Polish language locale by Piotr Klaban.

"abstract"

German language locale by Tvns Böker.

"abstract"

Portuguese language locale

"abstract"

The functions and classes in the top level of the Locale module implements a dynamic localization system, suitable for programs that needs to change locale often. It is even possible for different threads to use different locales at the same time.

The highest level of the locale system is called projects. Usually one program consists of only one project, but for bigger applications, or highly modular applications it is possible for several projects to coexist.

Every project in turn contains several unique tokens, each one representing an entity that is different depending on the currently selected locale.

// The following line tells the locale extractor what to // look for. // <locale-token project="my_project">LOCALE</locale-token>

// The localization macro. #define LOCALE(X,Y) Locale.translate("my_project", \ get_lang(), X, Y)

string get_lang() { return random(2)?"eng":"swe"; }

int(0..0) main() { write(LOCALE(0, "This is a line.")+"\n"); write(LOCALE(0, "This is another one.\n"); return 0; }

This class simulates a multi-language "string". The actual language to use is determined as late as possible.

``
``

Return the data nessesary to recreate this "string".

Make a connection between a project name and where its localization files can be found. The mapping from project name to locale file is stored in projects.

In the event that a translation is requested in an unregistered project, this path will be used as the project path. %P will be replaced with the requested projects name.

Returns a list of all registered languages for a specific project.

Reads in and returns a mapping with all the registred projects' LocaleObjects in the language 'lang'

Returns a translation for the given id, or the fallback string

Returns a localized function If function not found, tries fallback function fb, or fallback language fb instead

``

This module enables access to localization functions from within Pike.

Message to be translated.

Domain from within the message should be translated. Defaults to the current domain.

Category from which the translation should be taken. Defaults to Locale.Gettext.LC_MESSAGES.

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

Prior to Pike 7.3 this function only accepted one argument, and the other functionality was provided by dgettext() and dcgettext().

bindtextdomain, textdomain, setlocale, localeconv

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

Obsoleted by gettext() in Pike 7.3.

bindtextdomain, textdomain, gettext, setlocale, localeconv

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 no translation available, msg is returned.

Obsoleted by gettext() in Pike 7.3.

bindtextdomain, textdomain, gettext, setlocale, localeconv

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

The domain 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.

bindtextdomain, gettext, setlocale, localeconv

Binds the path predicate for a message domainname domainname to the directory name specified by 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 zero 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 unspecified. If no binding is found, the default locale path is returned. If domainname is unspecified or is an empty string, bindtextdomain() takes no action and returns a 0.

textdomain, gettext, setlocale, localeconv

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 are LC_ALL, LC_COLLATE, LC_CTYPE, LC_MONETARY, LC_NUMERIC and LC_TIME.

Returns 1 if the locale setting successed, 0 for failure

bindtextdomain, textdomain, gettext, dgettext, dcgettext, localeconv

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.

- "decimal_point"

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

- "thousands_sep"

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

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

- "currency_symbol"

The local currency symbol applicable to the current locale.

- "mon_decimal_point"

The decimal point used to format monetary quantities.

- "mon_thousands_sep"

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

- "positive_sign"

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

- "negative_sign"

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

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

- "frac_digits"

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

- 0 1 "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.

- 0 1 "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.

- 0 1 "n_cs_precedes"

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

- 0 1 "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.

- 0 4 "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.

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

bindtextdomain, textdomain, gettext, dgettext, dcgettext, setlocale

Locale category for all of the locale.

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

Locale category for the character classification and conversion routines.

Document this constant.

This category isn't available on all platforms.

Locale category for localeconv().

Locale category for the decimal character.

Locale category for strftime() (currently not accessible from Pike).

The Charset module supports a wide variety of different character sets, and it is flexible in regard of the names of character sets it accepts. The character case is ignored, as are the most common non-alaphanumeric characters appearing in character set names. E.g. "iso-8859-1" works just as well as "ISO_8859_1". All encodings specified in RFC 1345 are supported.

First of all the Charset module is capable of handling the following encodings of Unicode:

UTF encodings

Most, if not all, of the relevant code pages are represented, as the following list shows. Prefix the numbers as noted in the list to get the wanted codec:

These may be prefixed with "cp" or "ibm".

These may be prefixed with "cp", "ibm" or "windows".

+359 more.

Virtual base class for charset decoders.

string win1252_to_string( string data ) { return Locale.Charset.decoder("windows-1252")->feed( data )->drain(); }

Feeds a string to the decoder.

String to be decoded.

Returns the current object, to allow for chaining of calls.

this_program

Get the decoded data, and reset buffers.

Returns the decoded string.

Clear buffers, and reset all state.

Returns the current object to allow for chaining of calls.

this_program

Virtual base class for charset encoders.

An encoder only differs from a decoder in that it has an extra function.

Decoder

Change the replacement callback function.

Function that is called to encode characters outside the current character encoding.

``

Returns a charset decoder object.

The name of the character set to decode from. Supported charsets include (not all supported charsets are enumerable): "iso_8859-1:1987", "iso_8859-1:1998", "iso-8859-1", "iso-ir-100", "latin1", "l1", "ansi_x3.4-1968", "iso_646.irv:1991", "iso646-us", "iso-ir-6", "us", "us-ascii", "ascii", "cp367", "ibm367", "cp819", "ibm819", "iso-2022" (of various kinds), "utf-7", "utf-8" and various encodings as described by RFC1345.

If the asked-for name was not supported, an error is thrown.

Decoder

Returns a charset encoder object.

The name of the character set to encode to. Supported charsets include (not all supported charsets are enumerable): "iso_8859-1:1987", "iso_8859-1:1998", "iso-8859-1", "iso-ir-100", "latin1", "l1", "ansi_x3.4-1968", "iso_646.irv:1991", "iso646-us", "iso-ir-6", "us", "us-ascii", "ascii", "cp367", "ibm367", "cp819", "ibm819", "iso-2022" (of various kinds), "utf-7", "utf-8" and various encodings as described by RFC1345.

The string to use for characters that cannot be represented in the charset. It's used when repcb is not given or when it returns zero. If no replacement string is given then an error is thrown instead.

A function to call for every character that cannot be represented in the charset. If specified it's called with one argument - a string containing the character in question. If it returns a string then that one will replace the character in the output. If it returns something else then the replacement argument will be used to decide what to do.

If the asked-for name was not supported, an error is thrown.

``
Encoder

Returns a decoder for the encoding schema denoted by MIB mib.

Decoder

Returns an encoder for the encoding schema denoted by MIB mib.

``
Encoder

This module exist only for backwards compatibility issues with earlier Pike releases. Use the Calendar module instead.

This code can be used to simulate the old calendar for now (it might be removed in later Pike's):

This module has been totally rewritten in Pike 7.1+. To be forward compatible the lazy way, you can do something like this, though:

#if constant(Calendar.II) #define Calendar Calendar_I #endif ... import Calendar or whatever ...

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

Base class for units of time.

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.

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.

next() and prev() give 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.

time units: Year, Month, Week, Day

A Calendar_I.time_unit

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

_TimeUnit

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)

Replacement for localtime.

Replacement for ctime.

Replacement for ctime.

time unit: TNGDate

Implements ST:TNG stardates. Can be used as create argument to Day.

Calendar_I._TimeUnit

Translates one word to 1337. The optional argument leetp is the maximum percentage of leetness (100=max leet, 0=no leet). elite_word only do character-based translation, for instance from "k" to "|<", but no language translation (no "cool" to "kewl").

0 100
0 2

Translates a string to 1337. The optional argument leetp is the maximum percentage of leetness (100=max leet, 0=no leet).

The translation is performed in three steps, first the neccesary elite translations (picture -> pic, cool->kewl etc), then optional translations (ok->k, dude->dood, -ers -> -orz), then calls elite_word on the resulting words.

0 100
0 1

Functions that helps generating HTML. All functions generates HTML that is XHTML compliant as well as backwards compatible with old HTML standards in what extent is possible.

Provides the same functionality as the simple_obox function, in a "streaming" way. The real gain is different addtition methods as well as the possibility to change the cell callback at any time.

simple_obox

``
``

The argument in the mapping will be added to all created table cells.

The argument in the mappings will be added to the cell in the cooresponding column of the table.

Adds this cell to the table unmodified, e.g. it should have an enclosing td or th element.

Creates a cell from the provided arguments and adds it to the table.

The name of the element that should be produces. Typically "td" or "th".

A mapping with the elements attributes.

The element contents.

Adds a cell with the provided content.

Begin a new row. Succeeding cells will be added to this row instead of the current.

Adds a complete row. If the current row is nonempty a new row will be started.

Ensures that all rows have the same number of cells.

Returns the result.

It is possible to case this object to a string, which does the same as calling render, and to an array, which returns the cells in an array of rows.

Creates an HTML select list.

The name of the select list. Will be used in the name attribute of the select element.

May either be an array of strings, where each string is a choice, or an array of pairs. A pair is an array with two strings. The first string is the value of the choice while the second string is the presentation text associated with the value.

The value that should be selected by default, if any.

select("language", ({ ({ "eng", "English" }), ({ "swe", "Swedish" }), ({ "nor", "Norwegian" }) }), "swe");

This function should solve most of the obox needs that arises. It creates a table out of the array of arrays of strings fed into it. The tables will (with default settings) have a thin black outline around the table and between its cells. Much effort has gone into finding a simple HTML reresentation of such obox that is rendered in a similar way in all popular browsers. The current implementation has been tested against IE, Netscape, Mozilla, Opera and Konquest.

Simply an array of arrays with strings. The strings are the values that should appear in the table cells. All rows should have equal number of cells, otherwise the result will not be very eye pleasing.

The color of the surrounding frame. Defaults to "#000000".

The background color of the cells. Defaults to "#ffffff".

The border width. Defaults to "1".

The amount of padding in each cell. Defaults to "3".

If provided, the cell callback will be called for each cell. As in parameters it will get the current x and y coordinates in the table. The upper left cell is 0,0. In addition to the coordinates it will also receive the background color and the contents of the current cell. It is expected to return a td-element.

function cb = lambda(int x, int y, string bgcolor, string contents) { if(y%2) return "<td bgcolor='#aaaaff'>"+contents+"</td>"; return "<td bgcolor='"+bgcolor+"'>"+contents+"</td>"; } simple_obox(my_rows, "#0000a0", 0, "1", "3", cb);

pad_rows

``

Pads out the rows in a array of rows to equal length. The new elements in the rows will have the value provided in padding, or "&nbsp;".

This function implodes a list of words to a readable string, e.g. ({"straw","berry","pie"}) becomes "straw, berry and pie". If the separator is omitted, the default is "and". If the words are numbers they are converted to strings first.

`*()

Convert the first character in str to upper case, and return the new string.

lower_case(), upper_case()

Convert the first character in each word (separated by spaces) in str to upper case, and return the new string.

Find the longest common prefix from an array of strings.

This function compares two strings using a fuzzy matching routine. The higher the resulting value, the better the strings match.

Array.diff(), Array.diff_compare_table() Array.diff_longest_sequence()

0
100

Returns the soundex value of word according to the original Soundex algorithm, patented by Margaret O´Dell and Robert C. Russel in 1918. The method is based on the phonetic classification of sounds by how they are made. It was only intended for hashing of english surnames, and even at that it isn't that much of a help.

Converts the provided integer to a roman integer (i.e. a string).

Throws an error if m is outside the range 0 to 10000.

Returns the size as a memory size string with suffix, e.g. 43210 is converted into "42.2 kb". To be correct to the latest standards it should really read "42.2 KiB", but we have chosen to keep the old notation for a while. The function knows about the quantifiers kilo, mega, giga, tera, peta, exa, zetta and yotta.

Throws an error is size is less than zero.

Expands tabs in a string to ordinary spaces, according to common tabulation rules.

An object of this class is returned by get_iterator() when called with a string.

get_iterator

predef::Iterator

An iterator that iterates over substrings of a string, separated by a character or several different characters.

Typically you don't need to explicitly use the SplitIterator. Expressions like the following are automatically optimized into using a SplitIterator.

foreach(str/"\n", string line) write("%s\n", line);

predef::Iterator

The string to split.

The character or characters to split on.

Skip empty elements if set.

Callback function that is called once the buffer is used up and the SplitIterator wants more data.

``

A buffer, used for building strings. It's conceptually similar to a string, but you can only add strings to it, and you can only get the value from it once.

There is a reason for those seemingly rather odd limitations, it makes it possible to do some optimizations that really speed things up.

You do not need to use this class unless you add very many strings together, or very large strings.

For the fastest possible operation, write your code like this:

String.Buffer b = String.Buffer( );

function add = b->add;

.. call add several times in code ...

string result = b->get(); // also clears the buffer

Initializes a new buffer.

If no initial_size is specified, 256 is used. If you know approximately how big the buffer will be, you can optimize the operation of add() (slightly) by passing the size to this function.

It is possible to sprintf a String.Buffer object as %s just as if it was a string.

It is possible to cast a String.Buffer object to a string and an int.

String.Buffer
String.Buffer

Adds data to the buffer. Returns the size of the buffer.

Appends the character c at the end of the string.

Get the data from the buffer. Significantly slower than get, but does not clear the buffer.

Get the data from the buffer.

This will clear the data in the buffer

Returns the size of the buffer.

0 0

This class implements the "Bootstring" string transcoder described in ftp://ftp.rfc-editor.org/in-notes/rfc3492.txt.

Decodes a Bootstring encoded string of "basic" code points back to the original string space.

Encodes a string using Bootstring encoding into a string constisting only of "basic" code points (< initial_n).

Creates a Bootstring transcoder instance using the specified parameters.

The base used by the variable-length integers.

The minimum threshold digit value for the variable-length integers. Must be >=0 and <= tmax.

The maximum threshold digit value for the variable-length integers. Must be <= base-1.

The skew term for the bias adapation. Must be >= 1.

The damping factor for the bias adaption. Must be >= 2.

The initial bias for the variable-length integer thresholding. initial_bias % base must be <= base - tmin.

The first code point outside the "basic" set of code points.

The "basic" code point used as the delimiter.

The "basic" code points used as digits. The length of the string should be the same as the base parameter.

Same as sprintf("%c",x);

sprintf()

Same as sprintf("%x",x);, i.e. returns the integer x in hexadecimal base using lower cased symbols.

sprintf()

Convert a string of binary data to a hexadecimal string.

hex2string()

Convert a string of hexadecimal digits to binary data.

string2hex()

Count the number of non-overlapping times the string needle occurrs in the string haystack.

search(), `/()

Trim leading and trailing spaces and tabs from the string s.

Trim leading and trailing white spaces characters (space, tab, newline and carriage return) from the string s.

Returns the width of a string.

Three return values are possible:

8

The string s only contains characters <= 255.

16

The string s only contains characters <= 65535.

32

The string s contains characters >= 65536.

8
8
16
16
32
32

These constants define the limits for floats on the current architecture:

The number of decimal digits that can be represented. Any number with this many decimal digits can be stored in a float and converted back to decimal form without change. DIGITS_10 is not less than 6.

Limits of the exponent in decimal base. 10 raised to any number within this range can be represented in normalized form. MIN_10_EXP is not greater than -37. MAX_10_EXP is not less than 37.

The smallest normalized float greater than zero. It's not greater than 1e-37.

The largest finite float. It's not less than 1e37.

The difference between 1 and the smallest value greater than 1 that can be represented. It's not greater than 1e-5.

The size of the float type can be controlled when Pike is compiled with the configure flags --with-double-precision and --with-long-double-precision. The default is to use the longest available float type that fits inside a pointer.

Tells which C compiler float type that is used for Pike floats. Only one of these constants will exist (with the value 1) at runtime.

The float type of the C compiler is used.

The double type of the C compiler is used.

The long double type of the C compiler is used.

The float type can be controlled when Pike is compiled with the configure flags --with-double-precision and --with-long-double-precision. The default is to use the longest available float type that fits inside a pointer.

GTK

This widget provides the facilities to select an icon. An icon is displayed inside a button, when the button is pressed, an Icon selector (a dialog with a W(GnomeIconSelection) widget) pops up to let the user choose an icon. It also allows one to Drag and Drop the images to and from the preview button.

GTK.Vbox

Creates a new icon entry widget

Gnome.IconEntry

Gets the file name of the image if it was possible to load it into the preview. That is, it will only return a filename if the image exists and it was possible to load it as an image.

Get the W(GnomeEntry) widget that's part of the entry

Gnome.Entry

Get the W(GnomeFileEntry) widget that's part of the entry

Gnome.FileEntry

Get the W(Entry) widget that's part of the entry

GTK.Entry

Sets the subdirectory below gnome's default pixmap directory to use as the default path for the file entry.

Gnome.IconEntry

GnomeFontPicker - Button that displays current font; click to select new font. Gnome.FontPicker(); ../images/gnome_fontpicker.png

Gnome.FontPicker()->set_mode( Gnome.FontPickerModeFontInfo ); ../images/gnome_fontpicker_2.png

Signals: font_set

GTK.Button

Create a new font pick button

Gnome.FontPicker

If show_size is TRUE, font size will be displayed along with font chosen by user. This only applies if current button mode is Gnome.FontPickerModeFontInfo.

Gnome.FontPicker

If use_font_in_label is TRUE, font name will be written using font chosen by user and using size passed to this function. This only applies if current button mode is Gnome.FontPickerModeFontInfo.

Gnome.FontPicker

Retrieves the font from the font selection dialog.

GDK.Font

Retrieve name of font from font selection dialog.

Returns current font picker button mode (or what to show).

Retrieve preview text from font selection dialog if available.

Set or update the currently displayed font in the font picker dialog

Set value of subsequent font picker button mode (or what to show). Mode is one of GNOME_FONT_PICKER_MODE_FONT_INFO, GNOME_FONT_PICKER_MODE_PIXMAP, GNOME_FONT_PICKER_MODE_UNKNOWN and GNOME_FONT_PICKER_MODE_USER_WIDGET

Gnome.FontPicker

Set preview text in font picker, and in font selection dialog if one is being displayed.

Gnome.FontPicker

Sets the title for the font selection dialog.

Gnome.FontPicker

Set the user-supplied widget as the inside of the font picker. This only applies with Gnome.FontPickerModeUserWidget.

GTK.Widget
Gnome.FontPicker

This widget provides an entry box with history (a W(GnomeEntry)) and a button which can pop up a file selector dialog box W(GtkFileSelection). It also accepts DND drops from the filemanager and other sources. Gnome.FileEntry("","") ../images/gnome_fileentry.png

Signals: browse_clicked Signal emitted when the "browse" button is clicked. This is so that you can add stuff to the file selector or to override this method.

GTK.Hbox

Creates a new Gnome.FileEntry widget.

Gnome.FileEntry

Gets the full absolute path of the file from the entry. If file_must_exist is false, nothing is tested and the path is returned. If file_must_exist is true, then the path is only returned if the path actually exists. In case the entry is a directory entry (see set_directory), then if the path exists and is a directory then it's returned; if not, it is assumed it was a file so we try to strip it, and try again.

Get the W(GnomeEntry) component of the widget for lower-level manipulation.

Gnome.Entry

Get the W(Entry) component of the widget for lower-level manipulation.

GTK.Entry

Set the default path of browse dialog to path. The default path is only used if the entry is empty or if the current path of the entry is not an absolute path, in which case the default path is prepended to it before the dialog is started.

Gnome.FileEntry

Sets whether this is a directory only entry. If directory_entry is true, then get_full_path will check for the file being a directory, and the browse dialog will have the file list disabled.

Gnome.FileEntry

Sets the modality of the browse dialog.

Gnome.FileEntry

Set the title of the browse dialog to browse_dialog_title. The new title will go into effect the next time the browse button is pressed.

Gnome.FileEntry

The GnomeDateEdit widget provides a way to enter dates and times with a helper calendar to let the user select the date. Gnome.DateEdit(time(),1,1); ../images/gnome_dateedit.png

Gnome.DateEdit(time(),0,1); ../images/gnome_dateedit_2.png

Signals: date_changed

time_changed

GTK.Hbox

Creates a new GnomeDateEdit widget which can be used to provide an easy to use way for entering dates and times.

Gnome.DateEdit

Returns the configured time

Sets the range of times that will be provide by the time popup selectors.

Gnome.DateEdit

Changes the displayed date and time in the GnomeDateEdit widget to be the one represented by the_time.

Gnome.DateEdit

Gnome.DockBand is a widget implementing a "dock band", i.e. a horizontal or vertical stripe containing dockable widgets.

The application programmer does not normally need to use Gnome.DockBand directly; they are mostly used by the W(GnomeDock) widget to implement its functionality. For an explanation of the way dock bands are used within a dock, check out the documentation for the W(GnomeDock) widget.

GTK.Container

Add child to the band with the specified offset as the last element.

Gnome.DockItem

Create a new Gnome.DockBand widget.

Gnome.DockBand

Retrieve the offset of the child

GTK.Widget

Retrieve a named item from the band.

Gnome.DockItem

Retrieve the number of children

Retrieve the orientation

Add child to the band at the specified position, with the specified offset from the previous item (or from the beginning of the band, if this is the first item).

Gnome.DockItem
Gnome.DockLayout
Gnome.DockBand

Add child to the band with the specified offset as the first element.

Gnome.DockItem

Set the offset for the specified child of the band.

GTK.Widget
Gnome.DockBand

Set the orientation.

Gnome.DockBand
GTK.Vbox

Adds the default pixmap directory into the selection widget.

Gnome.IconSelection

Adds the icons from the directory dir to the selection widget.

Gnome.IconSelection

Clear the currently shown icons, the ones that weren't shown yet are not cleared unless the not_shown parameter is given, in which case even those are cleared.

Gnome.IconSelection

reates a new icon selection widget, it uses a W(GnomeIconList) for the listing of icons

Gnome.IconSelection

Gets the currently selected icon name, if full_path is true, it returns the full path to the icon, if none is selected it returns 0.

Selects the icon filename. This icon must have already been added and shown

Gnome.IconSelection

Shows the icons inside the widget that were added with add_defaults and add_directory. Before this function isf called the icons aren't actually added to the listing and can't be picked by the user.

Gnome.IconSelection

Applets are basically GNOME applications whose window sits inside the panel. Also the panel "takes care" of the applets by providing them with session saving and restarting, window management (inside of the panel), and a context menu.

The simplest applet one can write would be along the lines of:

     int main( int argc, array argv )
     {
       Gnome.init( "hello", "1.0", argv, 0 );
       Gnome.AppletWidget("hello")-&gt;add(GTK.Label("Hello World!"))-&gt;show_all();
       GTK.applet_widget_gtk_main();
     }

This creates an applet which just sits on the panel, not really doing anything, in real life the label would be substituted by something which actually does something useful. As you can see the applet doesn't really take care of restarting itself.

For the applet to be added to the menus, you need to install two files. Your x.gnorba file goes into $sysconfdir/CORBA/servers/ and the x.desktop file goes into $prefix/share/applets/&lt;category&gt;/.

Example hello.desktop:

     [Desktop Entry]
      Name=Hello Applet
      Comment=An example Hello World type Applet
      Type=PanelApplet
      Exec=hello.pike
      Icon=gnome-hello.png
      Terminal=0

Example hello.gnorba:

     [hello]
      type=exe
      repo_id=IDL:GNOME/Applet:1.0
      description=Hello Applet
      location_info=hello.pike

One thing to keep in mind is that the Exec line for the .desktop doesn't actually get executed when the Type is PanelApplet. The Exec line should be the GOAD ID specified in the .gnorba file (the "hello" enclosed by brackets). For a simple applet all you need to do is replace the hello.pike with the name of your applet executable.

When the user right clicks on the applet, a menu appears, this is all handeled by the panel, so in order to add items to it you use a special interface to "add callbacks" to the menu. A very simple example would be (making our hello applet even more feature full):

     void hello_there()
     {
       write( "Hello there, indeed!\n" );
     }

     int main( int argc, array argv )
     {
       Gnome.AppletWidget w;
       Gnome.init( "hello", "1.0", argv, 0 );
       w = Gnome.AppletWidget("hello");
       w-&gt;add(GTK.Label("Hello World!"))-&gt;show_all();
       w-&gt;register_callback( "hello", "Hello there", hello_there, 0 );
       GTK.applet_widget_gtk_main();
     }

Now the user will see a "Hello There" menu item on the applet menu, and when selected, the applet will print "Hello There". Useful huh?

Note that the first argument to the register_callback is just a string identifier of this callback, and can really be whatever you want. But it should NOT be translated as the label (the 2nd argument) should be.

Signals: back_change

change_orient

change_pixel_size

change_position

tooltip_state

GTK.Plug

Abort the applet loading, once applet has been created, this is a way to tell the panel to forget about us if we decide we want to quit before we add the actual applet to the applet-widget. This is only useful before before add() is called.

Gnome.AppletWidget

Add a child (widget) to the applet. This finishes the handshaking with the panel started in applet_widget_new. You should never call this function twice for the same applet. If you have already created an applet widget, but need to cancel the loading of the applet, use abort_load.

GTK.Widget
Gnome.AppletWidget

Sets the sensitivity of a menu item in the applet's context menu.

Gnome.AppletWidget

Make a new applet and register us with the panel, if you decide to cancel the load before calling add, you should call abort_load.

Gnome.AppletWidget

Gets the free space left that you can use for your applet. This is the number of pixels around your applet to both sides. If you strech by this amount you will not disturb any other applets. If you are on a packed panel 0 will be returned.

Gets the orientation of the panel this widget is on. it can be one of GNOME_Panel_ORIENT_DOWN, GNOME_Panel_ORIENT_LEFT, GNOME_Panel_ORIENT_RIGHT and GNOME_Panel_ORIENT_UP. This is not the position of the panel, but rather the direction that the applet should be "reaching out". So any arrows should for example point in this direction. It will be OrientUp or OrientDown for horizontal panels and OrientLeft or OrientRight for vertical panels

Gets the width of the panel in pixels. This is not the actual size, but the recomended one. The panel may be streched if the applets use larger sizes then this.

Adds a menu item to the applet's context menu. The name should be a path that is separated by '/' and ends in the name of this item. You need to add any submenus with register_callback_dir.

``
Gnome.AppletWidget

Adds a submenu to the applet's context menu. The name should be the full path of the new submenu with the name of the new submenu as the last part of the path. The name can, but doesn't have to be terminated with a '/'.

Gnome.AppletWidget

Adds a menu item to the applet's context menu with a stock GNOME pixmap. This works almost exactly the same as register_callback.

``
Gnome.AppletWidget

Adds a submenu to the applet's context menu with a stock GNOME pixmap. This is similiar to register_callback_dir.

Gnome.AppletWidget

Remove the plug from the panel, this will destroy the applet. You can only call this once for each applet.

Gnome.AppletWidget

If you need to get a signal everytime this applet changes position relative to the screen, you need to run this function with TRUE for enable and bind the change_position signal on the applet. This signal can be quite CPU/bandwidth consuming so only applets which need it should use it. By default change_position is not sent.

Gnome.AppletWidget

Set a tooltip on the entire applet that will follow the tooltip setting from the panel configuration.

Gnome.AppletWidget

Set a tooltip on the widget that will follow the tooltip setting from the panel configuration.

GTK.Widget
Gnome.AppletWidget

Tell the panel to save our session here (just saves, no shutdown). This should be done when you change some of your config and want the panel to save it's config, you should NOT call this in the session_save handler as it will result in a locked panel, as it will actually trigger another session_save signal for you. However it also asks for a complete panel save, so you should not do this too often, and only when the user has changed some preferences and you want to sync them to disk. Theoretically you don't even need to do that if you don't mind loosing settings on a panel crash or when the user kills the session without logging out properly, since the panel will always save your session when it exists.

Gnome.AppletWidget

Remove a menu item from the applet's context menu. The name should be the full path to the menu item. This will not remove any submenus.

Gnome.AppletWidget

Removes a submenu from the applet's context menu. Use this instead of unregister_callback to remove submenus. The name can be, but doesn't have to be terminated with a '/'. If you have not removed the subitems of this menu, it will still be shown but without it's title or icon. So make sure to first remove any items and submenus before calling this function.

Gnome.AppletWidget

This widget implements a graphical "more" command. It allows the user to view a text file. There are various possible ways to specify the contents to display: loading the data from a file (by providing a filename) or by loading it from an open file data stream or from the output of a Unix command.

Gnome.Less()->show_string("Example string\nshown in this\nwidget") ../images/gnome_less.png

Gnome.Less()->show_file("/usr/dict/words" ); ../images/gnome_less_2.png

Gnome.Less()->show_command( "psrinfo -v" ) ../images/gnome_less_3.png

GTK.Vbox

Clears all the text

Gnome.Less

Creates a new GnomeLess widget.

Gnome.Less

Re-displays all of the text in the GnomeLess widget gl. If the font has changed since the last show/reshow of text, it will update the current text to the new font.

Gnome.Less

Specifies whether or not new text should be displayed using a fixed font. Pass TRUE in fixed to use a fixed font, or FALSE to revert to the default GtkText font.

Note: This will not affect text already being displayed. If you use this function after adding text to the widget, you must show it again by using gnome_less_reshow or one of the gnome_less_show commands.

Gnome.Less

Sets the font of the text to be displayed in the GnomeLess widget gl to font. Note: This will not affect text already being displayed. If you use this function after adding text to the widget, you must show it again by using reshow or one of the show commands.

GDK.Font
Gnome.Less

Runs the shell command specified in command_line, and places the output of that command in the GnomeLess widget specified by gl. Replaces any text already being displayed in the widget.

Gnome.Less

Displays a file in a GnomeLess widget. Replaces any text already being displayed in the widget.

Gnome.Less
Stdio.File
Gnome.Less

Displays a string in the GnomeLess widget gl. Replaces any text already being displayed.

Gnome.Less

Writes the text displayed in the GnomeLess widget gl to the file specified by path.

Stdio.File

This is a W(GnomeDruidPage).

Gnome.DruidPage

Creates a new Gnome.DruidPageStandard widget.

Gnome.DruidPageFinish

This will set the background color to be the specified color.

GDK.Color
Gnome.DruidPageFinish

This will set the background color of the logo

GDK.Color
Gnome.DruidPageFinish

Set the text

Gnome.DruidPageFinish

Set the text color

GDK.Color
Gnome.DruidPageFinish

This will set the textbox color to be the specified color.

GDK.Color
Gnome.DruidPageFinish

Set the title

Gnome.DruidPageFinish

Set the title color

GDK.Color
Gnome.DruidPageFinish

The GNOME icon list widget can hold a number of icons with captions. The icons on the list can be selected (various selection methods are supported). The programmer can enable caption-editing for the icons. This parameters is configured when you create the icon list widget. You can control the type of selection mode you desire by using the set_selection_mode() function.

Signals: select_icon

text_changed

unselect_icon

GTK.Widget

Appends an icon to the specified icon list. The icon's image is loaded from the specified file, and it is inserted at the pos index.

Gnome.IconList

Clears the contents for the icon list by removing all the icons. If destroy handlers were specified for any of the icons, they will be called with the appropriate data.

Gnome.IconList

Creates a new icon list widget. The icon columns are allocated a width of icon_width pixels. Icon captions will be word-wrapped to this width as well.

If flags has the Gnome.IconListIsEditable flag set, then the user will be able to edit the text in the icon captions, and the "text_changed" signal will be emitted when an icon's text is changed.

Gnome.IconList

Find a icon in the list that has the given user data. If no icon is found, -1 is returned.

Freezes an icon list so that any changes made to it will not be reflected on the screen until it is thawed with thaw(). It is recommended to freeze the icon list before inserting or deleting many icons, for example, so that the layout process will only be executed once, when the icon list is finally thawed.

You can call this function multiple times, but it must be balanced with the same number of calls to thaw() before the changes will take effect.

Gnome.IconList

Returns the index of the icon that is under the specified coordinates, which are relative to the icon list's window. If there is no icon in that position, -1 is returned.

Return the data associated with a icon, or 0.

Return an array with the currently selected icons

returns 1 if the icon whose index is pos is visible.

Inserts an icon in the specified icon list. The icon's image is loaded from the specified file, and it is inserted at the pos index.

Gnome.IconList

Makes the icon whose index is pos be visible on the screen. The icon list gets scrolled so that the icon is visible. An alignment of 0.0 represents the top of the visible part of the icon list, and 1.0 represents the bottom. An icon can be centered on the icon list using 0.5 as the yalign.

Gnome.IconList

Removes the icon at index position pos. If a destroy handler was specified for that icon, it will be called with the appropriate data.

Gnome.IconList

Selects the specified icon.

Gnome.IconList

Sets the spacing to be used between columns of icons.

Gnome.IconList

Sets the adjustment to be used for horizontal scrolling. This is normally not required, as the icon list can be simply inserted in a W(ScrolledWindow) and scrolling will be handled automatically.

GTK.Adjustment
Gnome.IconList

Set the width of the border to be displayed around an icon's image. This is currently not implemented.

Gnome.IconList

Set the user data associated with the specified icon. This data can be used to find icons, and when an icon is selected it can be easily retrieved using get_icon_data.

You can only use objects as icon data right now

Gnome.IconList

Sets the amount of horizontal space allocated to the icons, i.e. the column width of the icon list

Gnome.IconList

Sets the spacing to be used between rows of icons.

Gnome.IconList

One of SELECTION_BROWSE, SELECTION_EXTENDED, SELECTION_MULTIPLE and SELECTION_SINGLE.

Gnome.IconList

Set the characters that can be used as word separators when doing word-wrapping of the text captions.

Gnome.IconList

Sets the spacing to be used between the icon and its caption

Gnome.IconList

Sets the adjustment to be used for vertical scrolling. This is normally not required, as the icon list can be simply inserted in a W(ScrolledWindow) and scrolling will be handled automatically.

GTK.Adjustment
Gnome.IconList

Unfreeze the icon list

Gnome.IconList

Unselect all icons.

Gnome.IconList

Unselects the specified icon.

Gnome.IconList

The Gnome.DockLayout widget is meant to make it simple for programmers to handle the layout of a GnomeDock widget.

Gnome.DockLayout can contain an arbitrary number of W(Gnome.DockItem) widgets, each of them with its own placement information. It is possible to "extract" a layout from an existing W(GnomeDock) widget, as well as adding the items present in a Gnome.DockLayout to it. Moreover, Gnome.DockLayout is able to create a layout configuration string that can be later used to re-construct the layout on a brand new Gnome.DockLayout widget.

As a consequence, Gnome.DockLayout is very useful to save and retrieve W(GnomeDock) configurations into files. For example, W(GnomeApp) uses Gnome.DockLayout to create a default layout configuration, override it with the user-specific configuration file, and finally apply it to it's W(GnomeDock).

GTK.Object

Add item to the layout as a floating item with the specified (x, y) position and orientation.

Gnome.DockItem

Add item to the layout with the specified parameters.

Gnome.DockItem

Add all the items in this layout to the specified dock

Gnome.Dock

Create a new Gnome.DockLayout widget.

Gnome.DockLayout

Generate a string describing the layout

Retrieve a dock layout item.

Gnome.DockItem
Gnome.DockLayoutItem

Retrieve the dock layout item named name

Gnome.DockLayoutItem

Parse the layout string str, and move around the items in layout accordingly.

Gnome.DockLayout

Remove the specified item from the layout.

Gnome.DockItem

Remove the specified item from the layout.

Gnome.PaperSelector() ../images/gnome_paperselector.png

GTK.Vbox
Gnome.PaperSelector

Provides an entry line for numbers. This routine does not attempt to do any validation on the valid number ranges, but provides a button that will let the user bring up a calculator to fill in the value of the entry widget. Gnome.NumberEntry("", "Select a number..."); ../images/gnome_numberentry.png

GTK.Hbox

Creates a new number entry widget, with a history id and title for the calculator dialog.

Gnome.NumberEntry

Get the current number from the entry

Get the W(GnomeEntry) component of the Gnome.NumberEntry for lower-level manipulation.

Gnome.Entry

Get the W(Entry) component of the Gnome.NumberEntry for Gtk+-level manipulation.

GTK.Entry

Set the title of the calculator dialog to calc_dialog_title. Takes effect the next time the calculator button is pressed.

Gnome.NumberEntry

This widget is a wrapper around the GtkEntry widget, but it provides a history mechanism for all the input entered into the widget. The way this works is that a special identifier is provided when creating the GnomeEntry widget, and this identifier is used to load and save the history of the text.

Gnome.Entry( "history" ) ../images/gnome_entry.png

GTK.Combo

Adds a history item of the given text to the tail of the history list inside gentry. If save is TRUE, the history item will be saved in the config file (assuming that gentry's history id is not 0).

Gnome.Entry

Creates a new GnomeEntry widget. If history_id is not 0, then the history list will be saved and restored between uses under the given id.

Gnome.Entry

Obtain pointer to Gnome.Entry's internal GTK.Entry text entry

GTK.Entry

Loads a stored history list from the GNOME config file, if one is available. If the history id of gentry is 0, nothing occurs.

Gnome.Entry

Adds a history item of the given text to the head of the history list inside gentry. If save is TRUE, the history item will be saved in the config file (assuming that gentry's history id is not 0).

Gnome.Entry

Force the history items of the widget to be stored in a configuration file. If the history id of gentry is 0, nothing occurs.

Gnome.Entry

Set or clear the history id of the GnomeEntry widget. If history_id is 0, the widget's history id is cleared. Otherwise, the given id replaces the previous widget history id.

Gnome.Entry

This widget provides color selection facilities to your application. The widget appears as a button which contains a "color swatch" of the currently selected color. When the button is pressed, the widget presents the user with a color selection dialog where the color can be selected.

You can select the color to be displayed in a number of ways: floating point values for the red, green and blue channels, integers in the range 0 to 65,535, or integers in the range 0 to 255, depending on your needs. Gnome.ColorPicker(); ../images/gnome_colorpicker.png

Signals: color_set This signal is emitted when the user changes the color on the color selector. The values passed to this signal are the red, green, blue and alpha channels selected in integer form in the range 0 to 65535.

GTK.Button

Creates a new GNOME color picker widget. This returns a widget in the form of a small button containing a swatch representing the current selected color. When the button is clicked, a color-selection dialog will open, allowing the user to select a color. The swatch will be updated to reflect the new color when the user finishes.

Gnome.ColorPicker

Returns a mapping ([ "d":([ "r":rvalue, "g":gvalue, "b":bvalue, "a":avalue ]), "i8":([ ... ]), "i16":([ .. ]) ]);

Set color shown in the color picker widget using floating point values. The values range between 0.0 and 1.0.

Gnome.ColorPicker

Sets whether the picker should dither the color sample or just paint a solid rectangle.

Gnome.ColorPicker

Set color shown in the color picker widget using integer values. The values range between 0 and 65535.

Gnome.ColorPicker

Set color shown in the color picker widget using integer values. The values range between 0 and 255.

Gnome.ColorPicker

Sets the title for the color selection dialog

Gnome.ColorPicker

Sets whether or not the picker should use the alpha channel.

Gnome.ColorPicker

This is a high-scores dialog box. The GNOME libraries also handle loading/saving systemwide high scores in a secure way.

Gnome.Scores( 17, ({ "per" })*17, map((array(float))indices(allocate(17)),`*,42), map(indices(allocate(17)), `*, 10 ), 1 ) ../images/gnome_scores.png

Gnome.Dialog
Gnome.Scores
GDK.Color
Gnome.Scores
Gnome.Scores
GDK.Color
Gnome.Scores
Gnome.Scores
Gnome.Scores
GTK.Widget
Gnome.Scores

GnomeDock is a container widget designed to let users move around widgets such as toolbars, menubars and so on.

Every GnomeDock contains a widget called the "client area". On the four sides of the client area, there are four "dock areas", which can contain an arbitrary number of dockable widgets. All the dockable widgets should be GnomeDockItem widgets; the GnomeDockItem widget can in turn contain any kind of widget, and implements the dragging functionality: every GnomeDockItem has a handle that users can use to move them within the dock, or even move them outside it, so that they become "floating items".

Every "dock area" is implemented by means of zero or more "dock bands": a dock band is a horizontal or vertical stripe containing one or more dock items, and is implemented by the GnomeDockBand widget. Items are ordered from top to bottom in vertical bands, and from left to right in horizontal bands. Every dock item in a band is given an offset value that defines the distance, in pixels, from the previous item in the same band; if the item is first in the band, the offset defines the distance from the start of the band.

As a consequence, the position of an item in the dock can be specified by means of the following values: a "placement" specifying what area is being used (top, bottom, left, right), a "band number" specifying the number of the band within the specified area, a "position" within the band and a "offset" from the previous item in the same band.

Signals: layout_changed

GTK.Container

Add item to dock and make it floating at the specified (x, y) coordinates (relative to the root window of the screen).

Gnome.DockItem
Gnome.Dock

Add item to dock. placement can be either Gnome.DOCK_TOP, Gnome.DOCK_RIGHT, Gnome.DOCK_BOTTOM or Gnome.DOCK_LEFT, and specifies what area of the dock should contain the item. If in_new_band is TRUE, a new dock band is created at the position specified by band_num; otherwise, the item is added to the band_num'th band.

Gnome.DockItem
Gnome.Dock
Gnome.Dock
Gnome.Dock
GTK.Widget
Gnome.DockItem

Specify a widget for the dock's client area.

GTK.Widget
Gnome.Dock

The GNOME druid is a system for assisting the user with installing a service. It is roughly equivalent in functionality to the "Wizards" available in Windows.

There are two major parts of the druid, the Gnome.Druid widget, and the set of W(Gnome.DruidPage) widgets. The Gnome.Druid widget is the main widget that interacts with the user. It has a Next, a Prev, and a Cancel button, and acts as a container for the pages. It is not a top-level window, so it needs to be put in a W(GTK.Window) in almost all cases. The W(Gnome.DruidPage) is a virtual widget, from which all of the actual content of the page inherits from. There are currently three of these available within gnome-libs.

GNOME druids are fairly simple to program with. You start by creating a GnomeDruid into which you put all of your pages. This widget will handle the presentation of the W(GnomeDruidPage) widgets.

You then create all appropriate W(GnomeDruidPage) widgets. There are three implementations of these, although there is no reason why more couldn't be written. They are the W(GnomeDruidPageStart), the W(GnomeDruidPageStandard), and the W(GnomeDruidPageFinish). The W(GnomeDruidPageStandard) acts as a W(Container), and is probably the most commonly used druid page. The other ones, as their names might suggest, are used at the endpoints of the druid. More information on the specific properties of these widgets can be found on their respective pages.

You will need to add the pages to the druid in order for them to appear. The druid itself keeps an internal list of all pages, and using the prepend_page(), append_page(), and insert_page() functions will place them into it.

Signals: cancel This signal is emitted when the "cancel" button has been pressed. Note that the current druid page has the option to trap the signal and use it, if need be, preventing this signal from being emitted.

GTK.Container

This will append a GnomeDruidPage into the internal list of pages that the druid has.

Gnome.DruidPage
Gnome.Druid

Create a new druid

Gnome.Druid

This will insert page after back_page into the list of internal pages that the druid has. If back_page is not present in the list or is 0, page will be prepended to the list.

Gnome.DruidPage
Gnome.DruidPage
Gnome.Druid

This will prepend a GnomeDruidPage into the internal list of pages that the druid has.

Gnome.DruidPage
Gnome.Druid

Sets the sensitivity of the druid's control-buttons. If the variables are TRUE, then they will be clickable. This function is used primarily by the actual W(GnomeDruidPage) widgets.

Gnome.Druid

This will make page the currently showing page in the druid. page must already be in the druid.

Gnome.DruidPage
Gnome.Druid

Sets the text on the last button on the druid. If show_finish is TRUE, then the text becomes "Finish". If show_finish is FALSE, then the text becomes "Cancel".

Gnome.Druid

This widget provides a simple calculator that you can embed in your applications for doing quick computations.

The widget consists of a fully functional calculator including standard arithmetic functions as well as trigonometric capabilities, exponents, factorials, nested equations, and others. Gnome.Calculator() ../images/gnome_calculator.png

Signals: result_changed This signal is emited by the widget when the result has been changed.

GTK.Vbox

Resets the calculator back to zero. If reset is TRUE, results stored in memory and the calculator mode are cleared also.

Gnome.Calculator

Create a new calculator widget

Gnome.Calculator

Value currently stored in calculator buffer.

Sets the value stored in the calculator's result buffer to the given result.

Gnome.Calculator

Entry for large images with a preview. Unlike GnomeIconEntry, it does not scale the images to a specific size and shows them 1:1. This is perfect for selection of backgrounds and such. It also allows DND to be performed on the preview box. It also provides all the GnomeEntry functionality as well. Gnome.PixmapEntry("","browse...",1); ../images/gnome_pixmapentry.png

GTK.Vbox

Creates a new pixmap entry widget, if do_preview is false, the preview is hidden but the files are still loaded so that it's easy to show it. For a pixmap entry without preview, use the W(GnomeFileEntry) widget.

Gnome.PixmapEntry

Gets the filename of the image if the preview successfully loaded.

Get the W(GnomeEntry) component of the W(GnomePixmapEntry) widget for lower-level manipulation.

Gnome.Entry

Get the W(GnomeFileEntry) component of the W(GnomePixmapEntry) widget for lower-level manipulation.

Gnome.FileEntry

Sets the default path for the file entry. The new subdirectory should be specified relative to the default GNOME pixmap directory.

Gnome.PixmapEntry

Sets whether or not previews of the currently selected pixmap should be shown in the file selector.

Gnome.PixmapEntry

Sets the minimum size of the preview frame in pixels.

Gnome.PixmapEntry

Gnome.Dialog gives dialogs a consistent look and feel, while making them more convenient to program. Gnome.Dialog makes it easy to use stock buttons, makes it easier to handle delete_event, and adds some cosmetic touches (such as a separator above the buttons, and a bevel around the edge of the window).

Signals: clicked

close

GTK.Window
Gnome.Dialog

Simply a signal_connect to the "clicked" signal of the specified button.

``
Gnome.Dialog

See also close_hides(). This function emits the "close" signal( which either hides or destroys the dialog (destroy by default). If you connect to the "close" signal, and your callback returns TRUE, the hide or destroy will be blocked. You can do this to avoid closing the dialog if the user gives invalid input, for example.

Using close() in place of hide() or destroy() allows you to easily catch all sources of dialog closure, including delete_event and button clicks, and handle them in a central location.

Gnome.Dialog

Creates a new Gnome.Dialog, with the given title, and any button names in the arg list. Buttons can be simple names, such as "My Button", or gnome-stock defines such as GNOME.StockButtonOK, etc. The last argument should be NULL to terminate the list.

Buttons passed to this function are numbered from left to right, starting with 0. So the first button in the arglist is button 0, then button 1, etc. These numbers are used throughout the Gnome.Dialog API.

Gnome.Dialog

Normally if there's an editable widget (such as GtkEntry) in your dialog, pressing Enter will activate the editable rather than the default dialog button. However, in most cases, the user expects to type something in and then press enter to close the dialog. This function enables that behavior.

GTK.Editable
Gnome.Dialog
GTK.Vbox

Blocks until the user clicks a button or closes the dialog with the window manager's close decoration (or by pressing Escape).

You need to set up the dialog to do the right thing when a button is clicked or delete_event is received; you must consider both of those possibilities so that you know the status of the dialog when run() returns. A common mistake is to forget about Escape and the window manager close decoration; by default, these call close(), which by default destroys the dialog. If your button clicks do not destroy the dialog, you don't know whether the dialog is destroyed when run() returns. This is bad.

So you should either close the dialog on button clicks as well, or change the close() behavior to hide instead of destroy. You can do this with close_hides().

See run(). The only difference is that this function calls close() before returning if the dialog was not already closed.

Gnome.Dialog

This is a convenience function so you don't have to connect callbacks to each button just to close the dialog. By default, Gnome.Dialog has this parameter set the FALSE and it will not close on any click. (This was a design error.) However, almost all the Gnome.Dialog subclasses, such as Gnome.MessageBox and Gnome.PropertyBox, have this parameter set to TRUE by default.

Gnome.Dialog

The default button will be activated if the user just presses return. Usually you should make the least-destructive button the default. Otherwise, the most commonly-used button.

Gnome.Dialog

Dialogs have "parents," usually the main application window which spawned them. This function will let the window manager know about the parent-child relationship. Usually this means the dialog must stay on top of the parent, and will be minimized when the parent is. Gnome also allows users to request dialog placement above the parent window (vs. at the mouse position, or at a default window manger location).

GTK.Window
Gnome.Dialog

Calls set_sensitive() on the specified button number.

Gnome.Dialog

Toplevel GNOME applications would normally use one Gnome.App widget as their toplevel window. You can create as many Gnome.App widgets as you want, for example, some people use one GnomeApp per document their application loads.

Once you have created one instance of this widget, you would add your main application view information to this window by using set_contents() routine.

The GnomeApp has support for including a menubar, one or more toolbars and a statusbar for your application. It also takes care of intalling the accelerators for you when used in conjuction with the gnome-app-helper routines. The toolbars are inserted into Gnome.Dock widgets.

The gnome-app-helper module provides various helper routines to simplify the configuration of your menus and toolbars, but you can create those yourself and use the set_menus(), add_toolbar(), set_toolbar(), add_dock_item() and add_docked().

GTK.Window

Create a new Gnome.DockItem widget containing widget, and add it to app's dock with the specified layout information. Notice that, if automatic layout configuration is enabled, the layout is overridden by the saved configuration, if any.

item : Item to be added to app's dock placement : Placement for the new dock item, one of Gnome.DockTop, Gnome.DockRight, Gnome.DockBottom, Gnome.DockLeft and Gnome.DockFloating band_num : Number of the band where the dock item should be placed band_position : Position of the new dock item in band band_num offset : Offset from the previous dock item in the band; if there is no previous item, offset from the beginning of the band.

Gnome.DockItem
Gnome.App

Create a new Gnome.DockItem widget containing widget, and add it to app's dock with the specified layout information. Notice that, if automatic layout configuration is enabled, the layout is overridden by the saved configuration, if any.

widget : Widget to be added to app's dock name : Name for the dock item that will contain toolbar behavior : Behavior for the new dock item. One of GNOME_DOCK_ITEM_BEH_EXCLUSIVE, GNOME_DOCK_ITEM_BEH_LOCKED, GNOME_DOCK_ITEM_BEH_NEVER_FLOATING, GNOME_DOCK_ITEM_BEH_NEVER_HORIZONTAL, GNOME_DOCK_ITEM_BEH_NEVER_VERTICAL and GNOME_DOCK_ITEM_BEH_NORMAL placement : Placement for the new dock item, one of Gnome.DockTop, Gnome.DockRight, Gnome.DockBottom, Gnome.DockLeft and Gnome.DockFloating band_num : Number of the band where the dock item should be placed band_position : Position of the new dock item in band band_num offset : Offset from the previous dock item in the band; if there is no previous item, offset from the beginning of the band.

GTK.Widget
Gnome.App

Create a new Gnome.DockItem widget containing toolbar, and add it to app's dock with the specified layout information. Notice that, if automatic layout configuration is enabled, the layout is overridden by the saved configuration, if any.

toolbar : Toolbar to be added to app's dock name : Name for the dock item that will contain toolbar behavior : Behavior for the new dock item. One or more of GNOME_DOCK_ITEM_BEH_EXCLUSIVE, GNOME_DOCK_ITEM_BEH_LOCKED, GNOME_DOCK_ITEM_BEH_NEVER_FLOATING, GNOME_DOCK_ITEM_BEH_NEVER_HORIZONTAL, GNOME_DOCK_ITEM_BEH_NEVER_VERTICAL and GNOME_DOCK_ITEM_BEH_NORMAL placement : Placement for the new dock item, one of Gnome.DockTop, Gnome.DockRight, Gnome.DockBottom, Gnome.DockLeft and Gnome.DockFloating band_num : Number of the band where the dock item should be placed band_position : Position of the new dock item in band band_num offset : Offset from the previous dock item in the band; if there is no previous item, offset from the beginning of the band.

GTK.Toolbar
Gnome.App

Create a new (empty) application window. You must specify the application's name (used internally as an identifier). title can be left as 0, in which case the window's title will not be set.

Gnome.App

Specify whether the the dock's layout configuration should be automatically saved via gnome-config whenever it changes, or not.

Gnome.App

An important fatal error; if it appears in the statusbar, it might gdk_beep() and require acknowledgement.

Gnome.Dialog

Flash the message in the statusbar for a few moments; if no statusbar, do nothing. For trivial little status messages, e.g. "Auto saving..."

Gnome.App

retrieved the Gnome.Dock widget contained in the App

Gnome.Dock
Gnome.DockItem

A simple message, in an OK dialog or the status bar. Requires confirmation from the user before it goes away. Returns 0 or a dialog widget. If 0, the message is displayed in the status bar.

Gnome.Dialog

Ask a ok or cancel question and call the callback when it's answered.

``
Gnome.App

Ask a ok or cancel question, block the application while it is asked, and call the callback when it's answered.

``
Gnome.App
Gnome.AppProgressKey
``
Gnome.AppProgressKey

Ask a yes or no question, and call the callback when it's answered.

``
Gnome.App

Ask a yes or no question, block the application while it is asked, and call the callback when it's answered.

``
Gnome.App

As request string, but do not show the string

``
Gnome.App

Request a string, and call the callback when it's answered.

``
Gnome.App

Sets the status bar of the application window.

GTK.Widget
Gnome.App

Sets the menu bar of the application window.

GTK.MenuBar
Gnome.App

Sets the status bar of the application window.

GTK.Widget
Gnome.App

Sets the main toolbar of the application window.

GTK.Toolbar
Gnome.App

A not-so-important error, but still marked better than a flash

Gnome.Dialog

The Gnome.PropertyBox widget simplifies coding a consistent dialog box for configuring properties of any kind.

The Gnome.PropertyBox is a toplevel widget (it will create its own window), inside it contains a GtkNotebook which is used to hold the various property pages.

The box will include ok, cancel, apply and help buttons (the actual buttons depends on the settings the user has, for example, apply can be hidden). The ok and apply buttons will start up in non-sensitive state, the programmer needs to configure the widgets inserted into the property box to inform the widget of any state changes to enable the ok and apply buttons. This is done by calling the changed() function.

To use this widget, you create the widget and then you call append_page() for each property page you want in the property box.

The widget emits two signals: "apply" and "help". To make a functional dialog box you will want to connect to at least the "apply" signal. Your function will be invoked once for each page and one more time at the end, passing a special value of -1 for the page number.

Signals: apply This signal is invoked with the page number that is being applied. The signal is emited with the special page number -1 when it has finished emiting the signals for all of the property pages.

help This signal is invoked when the user clicks on the help button in the property box. An argument is passed that identifies the currently active page number.

Gnome.Dialog

Appends a new page to the Gnome.PropertyBox. widget is the widget that is being inserted, and tab_label will be used as the label for this configuration page.

GTK.Widget
GTK.Widget

When a setting has changed, the code needs to invoke this routine to make the Ok/Apply buttons sensitive.

Gnome.PropertyBox

Creates a new Gnome.PropertyBox widget.

Gnome.PropertyBox
Gnome.PropertyBox

Information about an item in a gnome_dock_layout

The W(gnome_dock_item) this information applies to.

Gnome.DockItem

One of

Get the position of the item

The GnomeMessageBox widget creates dialog boxes (of type GnomeDialog) that contain a severity level (indicated by an icon and a title), a message to be displayed and a list of buttons that will be in the dialog.

The programmer will use strings desired for each button. If the strings are any of the GNOME_STOCK macros, then instead of creating a button with the text, the button will be a GNOME stock button with a stock icon.

The list of known types for message boxes are: GNOME_MESSAGE_BOX_ERROR, GNOME_MESSAGE_BOX_GENERIC, GNOME_MESSAGE_BOX_INFO, GNOME_MESSAGE_BOX_QUESTION and GNOME_MESSAGE_BOX_WARNING. Gnome.MessageBox( "This is a nice message", Gnome.MessageBoxInfo, Gnome.StockButtonOk, Gnome.StockButtonCancel ); ../images/gnome_messagebox.png

Gnome.MessageBox( "This is another not so nice message", Gnome.MessageBoxError, Gnome.StockButtonClose, Gnome.StockButtonCancel ); ../images/gnome_messagebox_2.png

Gnome.Dialog

Creates a dialog box of type message_box_type with message. A number of buttons are inserted on it. You can use the GNOME stock identifiers to create gnome stock buttons.

Gnome.MessageBox

A standard way of providing a small about box for your application. You provide the name of your application, version, copyright, a list of authors and some comments about your application. It also allows the programmer to provide a logo to be displayed.

Gnome.About( "Example", "1.0", "(c) Roxen IS 2000\n(c) IDA, LiU 2002", ({"Per Hedbor"}), "Some nice documentation\nabout this example" ); ../images/gnome_about.png

Gnome.Dialog

Creates a new GNOME About dialog. title, version, copyright, and authors are displayed first, in that order. comments is typically the location for multiple lines of text, if necessary. (Separate with "\n".) logo is the filename of a optional pixmap to be displayed in the dialog, typically a product or company logo of some sort; omit this argument if no logo file is available.

Gnome.About

A bar that GNOME applications put on the bottom of the windows to display status, progress, hints for menu items or a minibuffer for getting some sort of response. It has a stack for status messages Gnome.Appbar( 1, 1, Gnome.PreferencesUser )->set_progress( 0.4 ); ../images/gnome_appbar.png

Signals: clear_prompt Emitted when the prompt is cleared

user_response Emitted when the user hits enter after a prompt

GTK.Hbox

Remove any prompt.

Gnome.Appbar

Remove all status messages from appbar, and display default status message (if present).

Gnome.Appbar

Create a new GNOME application status bar. If has_progress is TRUE, a small progress bar widget will be created, and placed on the left side of the appbar. If has_status is TRUE, a status bar, possibly an editable one, is created.

interactivity determines whether the appbar is an interactive "minibuffer" or just a status bar. If it is set to Gnome.PREFERENCES_NEVER, it is never interactive. If it is set to Gnome.PREFERENCES_USER we respect user preferences from ui-properties. If it's Gnome.PREFERENCES_ALWAYS we are interactive whether the user likes it or not. Basically, if your app supports both interactive and not (for example, if you use the gnome-app-util interfaces), you should use Gnome.PREFERENCES_USER. Otherwise, use the setting you support. Please note that "interactive" mode is not functional now; GtkEntry is inadequate and so a custom widget will be written eventually.

Gnome.Appbar

Returns GTK.Progress widget pointer, so that the progress bar may be manipulated further.

GTK.Progress

Get the response to the prompt, if any.

Remove current status message, and display previous status message, if any. It is OK to call this with an empty stack.

Gnome.Appbar

Push a new status message onto the status bar stack, and display it.

Gnome.Appbar

Reflect the current state of stack/default. Useful to force a set_status to disappear.

Gnome.Appbar

What to show when showing nothing else; defaults to "".

Gnome.Appbar

Sets progress bar to the given percentage. Pure sugar - with a bad name, in light of the get_progress name which is not the opposite of set_progress. Maybe this function should die.

Gnome.Appbar

Put a prompt in the appbar and wait for a response. When the user responds or cancels, a user_response signal is emitted.

Gnome.Appbar

Sets the status label without changing widget state; next set or push will destroy this permanently.

Gnome.Appbar

This widget is a GtkButton button that contains a URL. When clicked it invokes the configured browser for the URL you provided.

Gnome.Href( "http://www.gnome.org", "GNOME Web Site" ) ../images/gnome_href.png

Gnome.Href( "http://www.gnome.org" ) ../images/gnome_href_2.png

GTK.Button

Created a GNOME href object, a label widget with a clickable action and an associated URL. If label is set to 0, url is used as the label.

Gnome.Href

Returns the contents of the label widget used to display the link text.

Return the url

Sets the internal label widget text (used to display a URL's link text) to the given value.

Gnome.Href

Sets the internal URL

Gnome.Href

This widget is a virtual widget to define the interface to a druid page. It's descendants are placed in a W(Gnome.Druid) widget.

Signals: back

cancel

finish

next

prepare

GTK.Bin

This is a W(GnomeDruidPage).

Gnome.DruidPage

Creates a new Gnome.DruidPageStandard widget.

Gnome.DruidPageStandard

This will set the background color to be the specified color.

GDK.Color
Gnome.DruidPageStandard

This will set the background color of the logo

GDK.Color
Gnome.DruidPageStandard

Set the title

Gnome.DruidPageStandard

Set the title color

GDK.Color
Gnome.DruidPageStandard

This is a W(GnomeDruidPage). It is meant to be used to introduce the user to what is being installed in a consistent manner.

Gnome.DruidPage

Creates a new Gnome.DruidPageStart widget.

Gnome.DruidPageStart

This will set the background color to be the specified color.

GDK.Color
Gnome.DruidPageStart

This will set the background color of the logo

GDK.Color
Gnome.DruidPageStart

Set the text

Gnome.DruidPageStart

Set the text color

GDK.Color
Gnome.DruidPageStart

This will set the textbox color to be the specified color.

GDK.Color
Gnome.DruidPageStart

Set the title

Gnome.DruidPageStart

Set the title color

GDK.Color
Gnome.DruidPageStart
GTK.Bin

Create a new GnomeDockItem named name, with the specified behavior. Gnome.DockItemBehExclusive specifies that the dock item is always the only one in its band. Gnome.DockItemBehNeverFloating specifies that users cannot detach the dock item from the dock. Gnome.DockItemBehNeverVertical specifies that the dock item must be kept horizontal, and users cannot move it to a vertical band. Gnome.DockItemBehNeverHorizontal specifies that the dock item must be kept horizontal, and users cannot move it to a vertical band. Gnome.DockItemBehLocked specifies that users cannot drag the item around.

Gnome.DockItem

Retrieve the child of the item.

GTK.Widget

Retrieve the name

One of SHADOW_ETCHED_IN, SHADOW_ETCHED_OUT, SHADOW_IN, SHADOW_NONE and SHADOW_OUT

Gnome.DockItem

One of SHADOW_ETCHED_IN, SHADOW_ETCHED_OUT, SHADOW_IN, SHADOW_NONE and SHADOW_OUT

Gnome.DockItem

Wrapper for the opaque GnomeAppProgressKey type

Gnome.AppProgressKey
Gnome.AppProgressKey
Gnome.AppProgressKey

Some apps want to embed a very small icon or widget in the panel to display the status of the app. This can be done without the operational overhead of an applet. The status docklet will embed a 22 by 22 window inside the panel. This is not a separate applet and thus is minimally intrusive to the user and is meant for very temporary status displays for which a full applet would not be appropriate.

The way StatusDocklet works is a little different from how the AppletWidget works. Firstly, StatusDocklet object is not a widget, it is just an abstract GTK+ object. You create a new StatusDocklet object and then bind the "build_plug" signal which is emitted when the panel was contacted and a widget must be built. After binding the "build_plug" signal, you call run() to actually start trying to contacting the panel. StatusDocklet is safe to use without a panel. By default it will try to locate a panel for 15 minutes and after that it will give up. It will also handle panel restarts by default. If it does, your widget will be destroyed and "build_plug" will be emitted again when the new panel starts. Even though the panel will never restart by itself, the user might not run session management and thus might restart panel by hand, or due to a bug, the panel might crash and restart itself.

Docklets are not available in GNOME 1.0.

Signals: build_plug This signal is emitted when you actually need to build the widget that you want to place inside the plug in the status docklet. It should be 22 by 22, and if it is larger it will be cropped.

GTK.Object

Creates a new status docklet object with the default parameters. By default the docklet object will try to contact a panel 20 times. It will try to find a panel every 15 seconds. You need to bind the build_plug signal in which you build your own widget and add it to the provided container. By default the docklet object will handle a panel restart, in which case your widget will be destroyed and when the panel is contacted again the build_plug signal will be emitted again. You also must call the status_docklet_run function after you bind the build_plug signal.

Gnome.StatusDocklet

the current W(plug) holding the docklet

GTK.Plug

Search for the panel and add the plug if it finds it. This function is also called internally from the timeout. If called externally more times, a panel lookup will be forced and one try will be wasted. You need to call this function at least once after binding the build_plug signal to tell the status docklet to start looking for the panel. If the status docklet handles restarts you don't have to call this function ever again.

Gnome.StatusDocklet

Getopt is a group of functions 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.

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 was sent as the 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. It can also be an array of strings, in which case any of the options in the array will be accepted.

This 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. This argument can also be an array of strings, in which case any of the options in the array will be accepted.

This argument specifies an environment variable that can be used to specify the same option, to make it easier to customize program usage. It can also be an array of strings, in which case any of the mentioned variables in the array may be used.

This argument has two functions: It specifies if the option takes an argument or not, and it informs 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 fail. def can be specified as UNDEFINED or left out if the option does not take an argument.

If throw_errors has been specified find_option() will throw errors on failure. If it has been left out, or is 0 (zero), it will instead print an error message on Stdio.stderr and exit the program with result code 1 on failure.

Returns the value the option has been set to if any.

If the option is present, but has not been set to anything 1 will be returned.

Otherwise if any of the environment variables specified in envvars has been set, that value will be returned.

If all else fails, def will be returned.

If an option that requires an argument lacks an argument and throw_errors is set an error will be thrown.

find_option() modifies argv. Parsed options will be removed from argv. Elements of argv that have been removed entirely will be replaced with zeroes.

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

Index 0 (zero) of argv is not scanned for options, since it is reserved for the program name.

Only the first ocurrance of an option will be parsed. To parse multiple ocurrances, call find_option() multiple times.

Getopt.get_args()

0 1
0
1

Used with find_all_options() to indicate that an option requires an argument.

find_all_options()

Used with find_all_options() to indicate that an option does not take an argument.

find_all_options()

Used with find_all_options() to indicate that an option takes an optional argument.

find_all_options()

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.

The should be the array of strings that was sent as the second argument to your main() function.

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

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 so that 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 a MAY_HAVE_ARG option will have in the output if it was set but not assigned any value.

Only the first three elements need to be included.

Don't scan for arguments after the first non-option.

If throw_errors has been specified find_all_options() will throw errors on failure. If it has been left out, or is 0 (zero), it will instead print an error message on Stdio.stderr and exit the program with result code 1 on failure.

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:

name

Option identifier name from the input.

value

Value given. If no value was specified, and no default has been specified, the value will be 1.

find_all_options() modifies argv.

Index 0 (zero) of argv is not scanned for options, since it is reserved for the program name.

Getopt.get_args(), Getopt.find_option()

-1 1

This function returns the remaining command line arguments after you have run find_option() or find_all_options() to find all the options in the argument list. If there are any options left not handled by find_option() or find_all_options() this function will fail.

If throw_errors has been specified get_args() will throw errors on failure. If it has been left out, or is 0 (zero), it will instead print an error message on Stdio.stderr and exit the program with result code 1 on failure.

On success a new argv array without the parsed options is returned.

Getopt.find_option(), Getopt.find_all_options()

-1 1

Fifo implements a fixed length first-in, first-out queue. A fifo is a queue of values and is often used as a stream of data between two threads.

Queue

Condition
Condition
Mutex

This function returns the number of elements currently in the fifo.

read(), write()

This function retrieves a value from the fifo. Values will be returned in the order they were written. If there are no values present in the fifo the current thread will sleep until some other thread writes one.

try_read(), read_array(), write()

This function retrieves a value from the fifo if there is any there. Values will be returned in the order they were written. If there are no values present in the fifo then UNDEFINED will be returned.

read()

This function returns all values in the fifo as an array. The values in the array will be in the order they were written. If there are no values present in the fifo the current thread will sleep until some other thread writes one.

read(), try_read_array()

This function returns all values in the fifo as an array but doesn't wait if there are no values there. The values in the array will be in the order they were written.

read_array()

Append a value to the end of the fifo. If there is no more room in the fifo the current thread will sleep until space is available. The number of items in the queue after the write is returned.

read()

Append a value to the end of the fifo. If there is no more room in the fifo then zero will be returned, otherwise the number of items in the fifo after the write is returned.

read()

Create a fifo. If the optional size argument is present it sets how many values can be written to the fifo without blocking. The default size is 128.

Queue implements a queue, or a pipeline. The main difference between Queue and Fifo is that Queue will never block in write(), only allocate more memory.

Fifo

Condition
Mutex

This function returns the number of elements currently in the queue.

read(), write()

This function retrieves a value from the queue. Values will be returned in the order they were written. If there are no values present in the queue the current thread will sleep until some other thread writes one.

try_read(), write()

This function retrieves a value from the queue if there is any there. Values will be returned in the order they were written. If there are no values present in the fifo then UNDEFINED will be returned.

write()

This function returns all values in the queue as an array. The values in the array will be in the order they were written. If there are no values present in the queue the current thread will sleep until some other thread writes one.

read(), try_read_array()

This function returns all values in the queue as an array but doesn't wait if there are no values there. The values in the array will be in the order they were written.

read_array()

This function puts a value last in the queue. If the queue is too small to hold the value it will be expanded to make room. The number of items in the queue after the write is returned.

read()

Thread

This function creates a new thread which will run simultaneously to the rest of the program. The new thread will call the function f with the arguments args. When f returns the thread will cease to exist.

All Pike functions are 'thread safe' meaning that running a function at the same time from different threads will not corrupt any internal data in the Pike process.

The returned value will be the same as the return value of this_thread() for the new thread.

This function is only available on systems with POSIX or UNIX or WIN32 threads support.

Mutex, Condition, this_thread()

``

Returns the current call stack for the thread.

The result has the same format as for predef::backtrace().

predef::backtrace()

Returns the status of the thread.

Thread.THREAD_NOT_STARTED
Thread.THREAD_RUNNING
Thread.THREAD_EXITED

Returns a string identifying the thread.

Returns an id number identifying the thread.

This function was added in Pike 7.2.204.

Waits for the thread to complete, and then returns the value returned from the thread function.

Mutex is a class that implements mutual exclusion locks. Mutex locks are used to prevent multiple threads from simultaneously execute sections of code which access or change shared data. The basic operations for a mutex is locking and unlocking. If a thread attempts to lock an already locked mutex the thread will sleep until the mutex is unlocked.

This class is simulated when Pike is compiled without thread support, so it's always available.

In POSIX threads, mutex locks can only be unlocked by the same thread that locked them. In Pike any thread can unlock a locked mutex.

This function attempts to lock the mutex. If the mutex is already locked by a different thread the current thread will sleep until the mutex is unlocked. The value returned is the 'key' to the lock. When the key is destructed or has no more references the mutex will automatically be unlocked.

The type argument specifies what lock() should do if the mutex is already locked by this thread:

0

Throw an error.

1

Sleep until the mutex is unlocked. Useful if some other thread will unlock it.

2

Return zero. This allows recursion within a locked region of code, but in conjunction with other locks it easily leads to unspecified locking order and therefore a risk for deadlocks.

If the mutex is destructed while it's locked or while threads are waiting on it, it will continue to exist internally until the last thread has stopped waiting and the last MutexKey has disappeared, but further calls to the functions in this class will fail as is usual for destructed objects.

Pike 7.4 and earlier destructed any outstanding lock when the mutex was destructed, but threads waiting in lock still got functioning locks as discussed above. This is inconsistent no matter how you look at it, so it was changed in 7.6. The old behavior is retained in compatibility mode for applications that explicitly destruct mutexes to unlock them.

trylock()

MutexKey
MutexKey

This function performs the same operation as lock(), but if the mutex is already locked, it will return zero instead of sleeping until it's unlocked.

lock()

MutexKey
MutexKey

This mutex method returns the object that identifies the thread that has locked the mutex. 0 is returned if the mutex isn't locked.

Thread()

Thread.Thread

This mutex method returns the key object currently governing the lock on this mutex. 0 is returned if the mutex isn't locked.

Thread()

Thread.MutexKey

Objects of this class are returned by Mutex()->lock() and Mutex()->trylock(). They are also passed as arguments to Condition()->wait().

As long as they are held, the corresponding mutex will be locked.

The corresponding mutex will be unlocked when the object is destructed (eg by not having any references left).

Mutex, Condition

Implementation of condition variables.

Condition variables are used by threaded programs to wait for events happening in other threads.

Condition variables are only available on systems with thread support. The Condition class is not simulated otherwise, since that can't be done accurately without continuations.

Mutex

Wait for contition.

This function makes the current thread sleep until the condition variable is signalled. The argument should be a Thread.MutexKey object for a Thread.Mutex. It will be unlocked atomically before waiting for the signal and then relocked atomically when the signal is received.

The thread that sends the signal should have the mutex locked while sending it. Otherwise it's impossible to avoid races where signals are sent while the listener(s) haven't arrived to the wait calls yet.

In Pike 7.2 and earlier it was possible to call wait() without arguments. This possibility was removed in later versions since it unavoidably leads to programs with races and/or deadlocks.

Mutex->lock()

Thread.MutexKey

signal() wakes up one of the threads currently waiting for the condition.

Sometimes more than one thread is woken up.

broadcast()

broadcast() wakes up all threads currently waiting for this condition.

signal()

Thread local variable storage.

This class allows you to have variables which are separate for each thread that uses it. It has two methods: get() and set(). A value stored in an instance of Local can only be retrieved by that same thread.

This class is simulated when Pike is compiled without thread support, so it's always available.

Get the thread local value.

This returns the value prevoiusly stored in the Local object by the set() method by this thread.

set()

Set the thread local value.

This sets the value returned by the get method.

Calling this method does not affect the value returned by get() when it's called by another thread (ie multiple values can be stored at the same time, but only one value per thread).

This function returns its argument.

Note that the value set can only be retreived by the same thread.

get()

This function returns an array with the thread ids of all threads.

Thread()

Thread.Thread

Document this function

This function returns the object that identifies this thread.

Thread()

Thread.Thread

Alias for m_delete()

An object of this class is returned by get_iterator() when called with a mapping.

get_iterator

predef::Iterator

This function returns the HSV value of the color described by the provided RGB value. It is essentially calling Image.Color.rgb(r,g,b)->hsv().

Colors.hsv_to_rgb() Image.Color.Color.hsv()

0 255
0
255
0 255
0 255
0 255
0
255

This function returns the RGB value of the color described by the provided HSV value. It is essentially calling Image.Color.hsv(h,s,v)->rgb().

Colors.rgb_to_hsv() Image.Color.hsv()

0 255
0
255
0 255
0 255
0 255
0
255

This function returns the CMYK value of the color described by the provided RGB value. It is essentially calling Image.Color.rgb(r,g,b)->cmyk().

Colors.cmyk_to_rgb() Image.Color.Color.cmyk()

0 255
0
100
0 255
0 255
0 255
0
100

This function return the RGB value of the color describe by the provided CMYK value. It is essentially calling Image.Color.cmyk(c,m,y,k)->rgb()

Colors.rgb_to_cmyk() Image.Color.cmyk()

0 100
0
255
0 100
0 100
0 100
0 100
0
255

This function returns the RGB values that corresponds to the color that is provided by name to the function. It is essentially calling Image.Color.guess(), but returns the default value (or black if none is provided) if it failes.

0
255

Tries to find a name to color described by the provided RGB values. Partially an inverse function to Colors.parse_color(), although it can not find all the names that Colors.parse_color() can find RGB values for. Returns the colors rgb hex value prepended with "#" upon failure.

0 255

Returns the parity of the integer value. If the parity is odd 1 is returned. If it is even 0 is returned.

0
0
1

The limits for using the native representation of integers on the current architecture. Any integer that is outside this range uses a more complex and slower representation. Also, some builtin functions that don't expect very large integers might start to complain about invalid argument type when given values outside this range (they typically say something like "Expected integer, got object").

NATIVE_MIN is not greater than -2147483648 (-0x80000000).

NATIVE_MAX is not less than 2147483647 (0x7fffffff).

The size of the native integers can be controlled when Pike is compiled with the configure flags --with-int-int, --with-long-int, and --with-long-long-int. The default is to use the longest available integer type that fits inside a pointer, which typically means that it's 64 bit on "true" 64 bit architectures.

If Pike is compiled with the configure flag --without-bignum (which is discouraged), then all arithmetic operations will instead silently wrap around at these limits.

Swaps the upper and lower byte in a word.

0 65535
0
65535

Swaps the upper and lower word in a longword, and the upper and lower bytes in the words. Simply put, the bytes are reversed.

0 4294967295
0
4294967295

General functions to operate on arrays.

reduce() sends the first two elements in arr to fun, then the result and the next element in arr to fun and so on. Then it returns the result. The function will return zero if arr is the empty array. If arr has only one element, that element will be returned.

rreduce()

``

rreduce() sends the last two elements in arr to fun, then the third last element in arr and the result to fun and so on. Then it returns the result. The function will return zero if arr is the empty array. If arr has only one element, that element will be returned.

reduce()

``

shuffle() gives back the same elements, but in random order. The array is modified destructively.

permute()

search_array() works like map(), only it returns the index of the first call that returnes true instead.

If no call returns true, -1 is returned.

sum(), map()

``

Applies the function sum columnwise on the elements in the provided arrays. E.g. sum_array(`+,a,b,c) does the same as `+(a[*],b[*],c[*]).

``

This function sorts the array arr after a compare-function cmp which takes two arguments and should return 1 if the first argument is larger then the second. Returns the sorted array - arr is not sorted destructively.

The remaining arguments args will be sent as 3rd, 4th etc. argument to cmp.

If cmp is omitted, `>() is used instead.

map(), sort(), `>(), dwim_sort_func, lyskom_sort_func, oid_sort_func

``

Get multiple columns from an array.

This function is equvivalent to

       map(ind, lambda(mixed i) { return column(x, i); })

column()

Return the three-way difference between the arrays.

Array.diff(), Array.diff_longest_sequence()

Sort without respect to number formatting (most notably leading zeroes).

-1
1

Sort comparison function that does not care about case, nor about the contents of any parts of the string enclosed with '()'

Example: "Foo (bar)" is given the same weight as "foo (really!)"

-1
1

Flatten a multi-dimensional array to a one-dimensional array.

Prior to Pike 7.5.7 it was not safe to call this function with cyclic data-structures.

Sum the elements of an array using `+. The empty array results in 0.

Perform the same action as the Unix uniq command on an array, that is, fold consecutive occurrences of the same element into a single element of the result array:

aabbbcaababb -> abcabab.

See also the uniq function.

Make an array of the argument, if it isn't already. A zero_type argument gives the empty array. This is useful when something is either an array or a basic datatype, for instance in headers from the MIME module or Protocols.HTTP.Server.

Result depends of the argument type:

arrayify(x) => x

arrayify(x) => ({})

arrayify(x) => ({ x })

Sort with care of numerical sort for OID values: "1.2.1" before "1.11.1"

sort_array

Like Array.diff, but tries to generate bigger continuous chunks of the differences, instead of maximizing the number of difference chunks. More specifically, greedy_diff optimizes the cases where Array.diff returns ({ ..., A, Z, B, ({}), C, ... }) ({ ..., A, X, B, Y+B, C, ... }) into the somewhat shorter diff arrays ({ ..., A, Z, B+C, ... }) ({ ..., A, X+B+Y, B+C, ... })

Returns the number of occurrences of needle in haystack. If the optional needle argument is omitted, count instead works similar to the unix command sort|uniq -c, returning a mapping with the number of occurrences of each element in haystack. For array or mapping haystacks, it's the values that are counted, for multisets the indices, as you'd expect.

String.count, search, has_value

Find the longest common prefix from an array of arrays.

String.common_prefix

Returns 1 if all of the elements in a fulfills the requirement predicate( a[i], @extra_args ), otherwise 0. The predicate should return non-zero for an element that meets the requirements and zero for those that do not.

Array.all( ({ 2, 4, 6, 8 }), `<, 17 )

any, has_value

``
0
1

Returns 1 if any of the elements in a fulfills the requirement predicate( a[i], @extra_args ), otherwise 0. The predicate should return non-zero for an element that meets the requirements and zero for those that do not.

Array.any( ({ 2, 4, 6, 8 }), `>, 5 )

all, has_value

``
0
1

Splits an array in two, according to an arbitration function arbiter. The elements in a who return non-zero for the expression arbiter( a[i], @extra_args ) end up in the first sub-array, the others in the second. The order is preserved from the original array.

Array.partition( enumerate( 9 ), lambda(int n) { return n>3 && n<7; } ); > ({ ({ 4, 5, 6 }), ({ 0, 1, 2, 3, 7, 8 }) })

filter, `/, `%

``

An object of this class is returned by get_iterator() when called with an array.

get_iterator

predef::Iterator

Interleave a sparse matrix.

Returns an array with offsets that describe how to interleave the rows of tab.

Find the longest ordered sequence of elements.

This function returns an array of the indices in the longest ordered sequence of elements in the array.

diff()

Give a specified permutation of an array.

The number of permutations is equal to sizeof(in)! (the factorial of the size of the given array).

shuffle()

Calculates which parts of the arrays that are common to both, and which parts that are not.

Returns an array with two elements, the first is an array of parts in array a, and the second is an array of parts in array b.

diff_compare_table(), diff_longest_sequence(), String.fuzzymatch()

Returns an array which maps from index in a to corresponding indices in b.

     > Array.diff_compare_table( ({ "a","b","c" }), ({ "b", "b", "c", "d", "b" }));
     Result: ({
                 ({ }),
                 ({
                     0,
                     1,
                     4
                 }),
                 ({
                     2
     	        })
             })

diff(), diff_longest_sequence(), String.fuzzymatch()

Gives the longest sequence of indices in b that have corresponding values in the same order in a.

diff(), diff_compare_table(), String.fuzzymatch()

Gives the longest sequence of indices in b that have corresponding values in the same order in a.

This function performs the same operation as diff_longest_sequence(), but uses a different algorithm, which in some rare cases might be faster (usually it's slower though).

diff_longest_sequence(), diff(), diff_compare_table(), String.fuzzymatch()

Remove elements that are duplicates.

This function returns an copy of the array a with all duplicate values removed. The order of the values is kept in the result; it's always the first of several equal elements that is kept.

Elements are compared with `==. They are also hashed (see lfun::__hash for further details if the array contains objects).

Splice two or more arrays.

This means that the returned array has the first element in the first given array, then the first argument in next array and so on for all arrays. Then the second elements are added, etc.

`/(), `*(), `+(), `-(), everynth()

Return an array with every n:th element of the array a.

If n is zero every other element will be returned.

splice(), `/()

Takes an array of equally sized arrays (essentially a matrix of size M*N) and returns the transposed (N*M) version of it, where rows and columns are exchanged for one another.

The GL Utilities module is a partial implementation of the GLU library. This module only contains functions that someone at some point actually needed to get his work done. If you need a GLU function that isn't in here, copy the C code from the GLU library (Mesa was used last time), tweak it so that it compiles as Pike code and then check it in into the CVS.

GL

gluLookAt creates a viewing matrix derived from an eye point, a reference point indicating the center of the scene, and an up vector. The matrix maps the reference point to the negative z axis and the eye point to the origin, so that, when a typical projection matrix is used, the center of the scene maps to the center of the viewport. Similarly, the direction described by the up vector projected onto the viewing plane is mapped to the positive y axis so that it points upward in the viewport. The up vector must not be parallel to the line of sight from the eye to the reference point.

The matrix generated by gluLookAt postmultiplies the current matrix.

The relation between the matrix objects and the float values are

Math.Matrix eye = Math.Matrix( ({ eyex, eyey, eyez }) );

GL.glFrustum, gluPerspective

Math.Matrix
Math.Matrix
Math.Matrix

gluOrtho2D sets up a two-dimensional orthographic viewing region. This is equivalent to calling

glOrtho(left, right, bottom, top, -1.0, 1.0);

The GLU manual says glOrtho(a,b,c,d, 0, 1).

GL.glOrtho, gluPerspective

gluPerspective specifies a viewing frustum into the world coordinate system. In general, the aspect ratio in gluPerspective should match the aspect ratio of the associated viewport. For example, aspect = 2.0 means the viewer's angle of view is twice as wide in x as it is in y. If the viewport is twice as wide as it is tall, it displays the image without distortion.

The matrix generated by gluPerspective is multipled by the current matrix, just as if GL.glMultMatrix were called with the generated matrix. To load the perspective matrix onto the current matrix stack instead, precede the call to gluPerspective with a call to GL.glLoadIdentity.

gluPickMatrix creates a projection matrix that can be used to restrict drawing to a small region of the viewport. This is typically useful to determine what objects are being drawn near the cursor. Use gluPickMatrix to restrict drawing to a small region around the cursor. Then, enter selection mode (with GL.glRenderMode and rerender the scene. All primitives that would have been drawn near the cursor are identified and stored in the selection buffer.

The matrix created by gluPickMatrix is multiplied by the current matrix just as if GL.glMultMatrix is called with the generated matrix. To effectively use the generated pick matrix for picking, first call GL.glLoadIdentity to load an identity matrix onto the perspective matrix stack. Then call gluPickMatrix, and finally, call a command (such as gluPerspective) to multiply the perspective matrix by the pick matrix.

When using gluPickMatrix to pick NURBS, be careful to turn off the NURBS property GLU_AUTO_LOAD_MATRIX. If GLU_AUTO_LOAD_MATRIX is not turned off, then any NURBS surface rendered is subdivided differently with the pick matrix than the way it was subdivided without the pick matrix.

The viewport is an array with four integers.

Does the NURB remark apply?

GL.glGet, gluLoadIdentity, gluMultMatrix, gluRenderMode, gluPerspective

gluProject transforms the specified object coordinates into window coordinates using model, proj, and viewport. The result is returned in a three valued array.

Calls the given function with the args array plus the optional extra arguments as its arguments and returns the result.

Most useful in conjunction with map, and particularly in combination with sscanf with "...%{...%}..." scan strings (which indeed was what it was invented for in the first place).

The first arguments the function f expects.

The function to apply the arguments on.

Optional extra arguments to send to f.

Whatever the supplied function f returns.

class Product(string name, string version) { string _sprintf() { return sprintf("Product(%s/%s)", name, version); } } map(({ ({ "pike", "7.1.11" }), ({ "whitefish", "0.1" }) }), Function.splice_call, Product); ({ /* 2 elements */ Product(pike/7.1.11), Product(whitefish/0.1) })

``

The dreaded fixpoint combinator "Y".

The Y combinator is useful when writing recursive lambdas. It converts a lambda that expects a self-reference as its first argument into one which can be called without this argument.

This example creates a lambda that computes the faculty function.

Function.Y(lambda(function f, int n) { return n>1? n*f(n-1) : 1; })

``

Partially evaluate a function call.

This function allows N parameters to be given to a function taking M parameters (N<=M), yielding a new function taking M-N parameters.

What is actually returned from this function is a function taking N parameters, and returning a function taking M-N parameters.

This example creates a function adding 7 to its argument.

Function.curry(`+)(7)

``

Call a callback function, but send throws from the callback function (ie, errors) to master()->handle_error. Also accepts if f is zero (0) without error.

Functions.call_callback(the_callback,some,arguments);

equals

{ mixed err=catch { if (the_callback) the_callback(some,arguments); }; if (err) master()->handle_error(err); }

(Approximately, since call_callback also calls handle_error if 0 were thrown.)

``

Returns a string with filename and linenumber where fun was defined.

Returns 0 (zero) when no line can be found, e.g. for builtin functions and functions in destructed objects.

``

Local gives a local module namespace used for locally installed pike modules. Modules are searched for in the directory pike_modules which can be located in the user's home directory or profile directory, or in any of the system directories /opt/share, /usr/local/share, /opt or /usr/local/. The user's home directory is determined by examining the environment variable HOME, and if that fails the environment variable USERPROFILE. If the environment variable PIKE_LOCAL_PATH is set, the paths specified there will be searched first.

Local.add_path(), Local.remove_path()

This function prepends path to the Local module searchpath.

The path to the directory to be added.

Returns 1 on success, otherwise 0.

0
1

This function removes path from the Local module searchpath. If path is not in the search path, this is a noop.

The path to be removed.

Document this function.

Recursively builds a inheritance tree by fetching programs inheritance lists.

Returns an array with programs or arrays as elements.

> class a{} > class b{} > class c{ inherit a; } > class d{ inherit b; inherit c; } > Program.inherit_tree(d); Result: ({ /* 3 elements */ d, ({ /* 1 element */ program }), ({ /* 2 elements */ c, ({ /* 1 element */ program }) }) })

Returns an array with the programs that p has inherited.

Returns 1 if prog implements api.

Returns 1 if child has inherited parent.

Returns a string with filename and linenumber describing where the program p was defined.

The returned string is of the format "filename:linenumber".

If it cannot be determined where the program was defined, 0 (zero) will be returned.

Slightly polished version of create_process.

create_process

create_process

Either a command line array, as the command_args argument to create_process(), or a string that will be splitted into a command line array by calling split_quoted_string() in an operating system dependant mode.

In addition to the modifiers that create_process accepts, this object also accepts

- `Process` "read_callback"

This callback is called when there is data to be read from the process.

- `Process` "timeout_callback"

This callback is called if the process times out.

- "timeout"

The time it takes for the process to time out. Default is 15 seconds.

create_process, split_quoted_string

Stdio.File
Stdio.File
0 1
``
Process

This is the recommended and most portable way to start processes in Pike. The process object is a pike abstraction of the running system process, with methods for various process housekeeping.

Waits for the process to end.

0

The exit code of the process.

-1

The process was killed by a signal.

TraceProcess()->wait()

Returns the status of the process:

-1

Unknown

0

Running

1

Stopped

2

Exited

Prior to Pike 7.5 the value 1 was returned for exited processes.

-1
2

Returns the last signal that was sent to the process.

0

Returns the process identifier of the process.

Sets the priority of the process. priority is one of the strings

Each limit_value may be either of:

sets current limit, max is left as it is.

([ "hard":int, "soft":int ]) Both values are optional, hard <= soft.

({ hard, soft }), both can be set to the string "unlimited". A value of -1 means 'keep the old value'.

The string "unlimited" sets both the hard and soft limit to unlimited

The command name and its command-line arguments. You do not have to worry about quoting them; pike does this for you.

This optional mapping can can contain zero or more of the following parameters:

- "cwd"

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

- "chroot"

Chroot to this directory before executing the command.

- Stdio.File "stdin"
- Stdio.File "stdout"
- 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"

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. See the examples section.

- "uid"

This parameter changes which user the new process will execute as. Note that the current process must be running as UID 0 to use this option. The uid can be given either as an integer as a string containing the login name of that user.

The "gid" and "groups" for the new process will be set to the right values for that user unless overriden by options below.

(See setuid and getpwuid for more info.)

- "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. (See setuid and getgrgid for more info.)

- 0 1 Stdio.File "setsid"

Set this to 1 to create a new session group. It is also possible to set it to a File object, in which case a new session group will be created with this file as the controlling terminal.

- "setgroups"

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 and no more than 16 groups. (Some system only support up to 8...) The groups can be given as gids or as strings with the group names.

- 0 1 "noinitgroups"

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"

This sets the priority of the new process, see set_priority for more info.

- "nice"

This sets the nice level of the new process; the lower the number, the higher the priority of the process. Note that only UID 0 may use negative numbers.

- 0 1 "keep_signals"

This prevents Pike from restoring all signal handlers to their default values for the new process. Useful to ignore certain signals in the new process.

- Stdio.File 0 0 "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.

- limit_value "rlimit"

There are two values for each limit, the soft limit and the hard limit. Processes that do not have UID 0 may not raise the hard limit, and the soft limit may never be increased over the hard limit. The indices of the mapping indicate what limit to impose, and the values dictate what the limit should be. (See also System.setrlimit)

- limit_value "core"

maximum core file size in bytes

- limit_value "cpu"

maximum amount of cpu time used by the process in seconds

- limit_value "data"

maximum heap (brk, malloc) size in bytes

- limit_value "fsize"

maximum size of files created by the process in bytes

- limit_value "map_mem"

maximum size of the process's mapped address space (mmap() and heap size) in bytes

- limit_value "mem"

maximum size of the process's total amount of available memory (mmap, heap and stack size) in bytes

- limit_value "nofile"

maximum number of file descriptors the process may create

- limit_value "stack"

maximum stack size in bytes

Process.create_process(({ "/usr/bin/env" }), (["env" : getenv() + (["TERM":"vt100"]) ]));

//! Spawn a new process with the args @[args] and optionally a //! standard input if you provide such a @[Stdio.File] object. //! @returns //! Returns the new process and a pipe from which you can read //! its output. array(Process.Process|Stdio.File) spawn(Stdio.File|void stdin, string ... args) { Stdio.File stdout = Stdio.File(); mapping opts = ([ "stdout" : stdout->pipe() ]); if( stdin ) opts->stdin = stdin; return ({ Process.create_process( args, opts ), stdout }); }

All parameters that accept both string or int input can be noticeably slower using a string instead of an integer; if maximum performance is an issue, please use integers.

The modifiers "fds", "uid", "gid", "nice", "noinitgroups", "setgroups", "keep_signals" and "rlimit" only exist on unix.

This function is only available on platforms that support signals.

Class that enables tracing of processes.

The new process will be started in stopped state. Use cont() to let it start executing.

This class currently only exists on systems that implement ptrace().

Interface to the current register contents of a stopped process.

TraceProcess

Get the contents of register regno.

create_process

Waits for the process to stop.

0

The exit code of the process.

-1

The process was killed by a signal.

-2

The process has stopped.

create_process::wait()

Allow a traced process to continue.

Deliver this signal to the process.

This function may only be called for stopped processes.

wait()

Cause the traced process to exit.

This function may only be called for stopped processes.

cont(), wait()

GTK

The GDK.Color object is used to represent a color. When you call GDK.Color(r,g,b) the color will be allocated from the X-server. The constructor can return an exception if there are no more colors to allocate. NOIMG

Returns the blue color component.

r g and b are in the range 0 to 255, inclusive. If color is specified, it should be an Image.Color object, and the only argument.

GDK.Color

Destroys the color object. Please note that this function does not free the color from the X-colormap (in case of pseudocolor) right now.

GDK.Color

Returns the green color component.

Return a Image.Color.Color instance. This gives better precision than the rgb function.

Image.Color.Color

Returns the pixel value of the color. See GDK.Image->set_pixel.

Returns the red color component.

Returns the red green and blue color components as an array.

A bitmap is a black and white pixmap. Most commonly used as masks for images, widgets and pixmaps.

NOIMG

GDK.Drawable

Create a new GDK.Bitmap object. Argument is either an Image.image object, or {xsisze,ysize,xbitmapdata}.

Image.Image
GDK.Bitmap

Destructor. Destroys the bitmap. This will free the bitmap on the X-server.

GDK.Bitmap

Add a reference

GDK.Bitmap

Remove a reference

GDK.Bitmap

Create a new (empty) region

NOIMG

GDK.Region
GDK.Region

Return true if the region used as an argument is equal to the current region. Also available as a==b when a is a region.

GDK.Region

Computes the intersection of the given region and the region. Also available as region &amp; region

GDK.Region
GDK.Region

Offset(move) the region by dx,dy pixels.

GDK.Region

Returns true if the given point resides in the given region

Returns true if the given rectangle resides inside the given region

GDK.Rectangle

reduces the size of a region by a specified amount. Positive values shrink the size of the region, and negative values expand the region.

GDK.Region

Computes the difference of the given region and the region. Also available as region - region

GDK.Region
GDK.Region

Computes the union of the given rectangle or region and the region. Also available as region | rectangle, region | region, region + region and region + rectangle.

GDK.Region
GDK.Region

Computes the exlusive or of the given region and the region. Also available as region ^ region

GDK.Region
GDK.Region

This class creates a GDK.Pixmap from either an GDK.Image or Image.image object (or a numeric ID, see your X-manual for XIDs). The GDK.Pixmap object can be used in a lot of different GTK widgets. The most notable is the W(Pixmap) widget.

NOIMG

GDK.Drawable

Create a new GDK.Pixmap object. Argument is a GDK.Image object or a Image.Image object

GDK.Pixmap

Destructor. Destroys the pixmap.

GDK.Pixmap
GDK.Pixmap

Argument is a GDK.Image object or an Image.image object. It is much faster to use an gdkImage object, especially one allocated in shared memory. This is only an issue if you are going to change the contents of the pixmap often, toggling between a small number of images.

GDK.Image
GDK.Pixmap
GDK.Pixmap

The GDK.Bitmap, GDK.Window and GDK.Pixmap classes are all GDK drawables.

This means that you can use the same set of functions to draw in them.

Pixmaps are offscreen drawables. They can be drawn upon with the standard drawing primitives, then copied to another drawable (such as a GDK.Window) with window->draw_pixmap(), set as the background for a window or widget, or otherwise used to show graphics (in a W(Pixmap), as an example). The depth of a pixmap is the number of bits per pixels. Bitmaps are simply pixmaps with a depth of 1. (That is, they are monochrome bitmaps - each pixel can be either on or off).

Bitmaps are mostly used as masks when drawing pixmaps, or as a shape for a GDK.Window or a W(Widget)

Either clears the rectangle defined by the arguments, of if no arguments are specified, the whole drawable.

GDK.Drawable

Copies the rectangle defined by xsource,ysource and width,height from the source drawable, and places the results at xdest,ydest in the drawable in which this function is called.

GDK.GC
GTK.Widget
GDK.Drawable

Draws a single circular or elliptical arc. Each arc is specified by a rectangle and two angles. The center of the circle or ellipse is the center of the rectangle, and the major and minor axes are specified by the width and height. Positive angles indicate counterclockwise motion, and negative angles indicate clockwise motion. If the magnitude of angle2 is greater than 360 degrees, it is truncated to 360 degrees.

GDK.GC
GDK.Drawable

Draw a GDK(Bitmap) in this drawable. NOTE: This drawable must be a bitmap as well. This will be fixed in GTK 1.3

GDK.GC
GDK.Bitmap
GDK.Drawable

Draw the rectangle specified by xsrc,ysrc+width,height from the GDK(Image) at xdest,ydest in the destination drawable

GDK.GC
GDK.Image
GDK.Drawable

img_begin w = GTK.DrawingArea()->set_usize(100,100); delay: g = GDK.GC(w)->set_foreground( GDK.Color(255,0,0) ); delay: for(int x = 0; x<10; x++) w->draw_line(g,x*10,0,100-x*10,99); img_end

GDK.GC
GDK.Drawable

Draw the rectangle specified by xsrc,ysrc+width,height from the GDK(Pixmap) at xdest,ydest in the destination drawable

GDK.GC
GDK.Pixmap
GDK.Drawable

img_begin w = GTK.DrawingArea()->set_usize(10,10); delay: g = GDK.GC(w)->set_foreground( GDK.Color(255,0,0) ); delay: for(int x = 0; x<10; x++) w->draw_point(g, x, x); img_end

GDK.GC
GDK.Drawable

img_begin w = GTK.DrawingArea()->set_usize(100,100); delay: g = GDK.GC(w)->set_foreground( GDK.Color(255,0,0) ); delay: for(int x = 0; x<10; x++) w->draw_rectangle(g,0,x*10,0,100-x*10,99); img_end img_begin w = GTK.DrawingArea()->set_usize(100,100); delay: g = GDK.GC(w); delay: for(int x = 0; x<30; x++) { delay: g->set_foreground(GDK.Color(random(255),random(255),random(255)) ); delay: w->draw_rectangle(g,1,x*10,0,100-x*10,99); delay: } img_end

GDK.GC
GDK.Drawable

y is used as the baseline for the text. If forcewide is true, the string will be expanded to a wide string even if it is not already one. This is useful when writing text using either unicode or some other 16 bit font.

GDK.GC
GDK.Font
GDK.Drawable

Get width, height position and depth of the drawable as a mapping.

([ "x":xpos, "y":ypos, "width":xsize, "height":ysize, "depth":bits_per_pixel ])

Returns the width of the drawable specified in pixels

Returns the height of the drawable specified in pixels

The GdkFont data type represents a font for drawing on the screen. These functions provide support for loading fonts, and also for determining the dimensions of characters and strings when drawn with a particular font.

Fonts in X are specified by a X Logical Font Description. The following description is considerably simplified. For definitive information about XLFD's see the X reference documentation. A X Logical Font Description (XLFD) consists of a sequence of fields separated (and surrounded by) '-' characters. For example, Adobe Helvetica Bold 12 pt, has the full description: "-adobe-helvetica-bold-r-normal--12-120-75-75-p-70-iso8859-1"

The fields in the XLFD are: Foundry the company or organization where the font originated. Family the font family (a group of related font designs). Weight A name for the font's typographic weight For example, 'bold' or 'medium'). Slant The slant of the font. Common values are 'R' for Roman, 'I' for italoc, and 'O' for oblique. Set Width A name for the width of the font. For example, 'normal' or 'condensed'. Add Style Additional information to distinguish a font from other fonts of the same family. Pixel Size The body size of the font in pixels. Point Size The body size of the font in 10ths of a point. (A point is 1/72.27 inch) Resolution X The horizontal resolution that the font was designed for. Resolution Y The vertical resolution that the font was designed for . Spacing The type of spacing for the font - can be 'p' for proportional, 'm' for monospaced or 'c' for charcell. Average Width The average width of a glyph in the font. For monospaced and charcell fonts, all glyphs in the font have this width Charset Registry The registration authority that owns the encoding for the font. Together with the Charset Encoding field, this defines the character set for the font. Charset Encoding An identifier for the particular character set encoding.

When specifying a font via a X logical Font Description, '*' can be used as a wildcard to match any portion of the XLFD. For instance, the above example could also be specified as "-*-helvetica-bold-r-normal--*-120-*-*-*-*-iso8859-1"

It is generally a good idea to use wildcards for any portion of the XLFD that your program does not care about specifically, since that will improve the chances of finding a matching font.

Return the width, in pixels, of the specified character, if rendered with this font. The character can be between 0 and 65535, the character encoding is font specific.

Create a new font object. The string is the font XLFD.

GDK.Font

Free the font, called automatically by pike when the object is destroyed.

GDK.Font

The drag context contains all information about the drag'n'drop connected to the signal to which it is an argument.

NOIMG

Abort the drag

GDK.DragContext
GDK.DragContext

If success is true, the drag succeded. If del is true, the source should be deleted. time is the current time.

GDK.DragContext

Use the default drag icon associated with the source widget.

GDK.DragContext

Set the drag pixmap, and optionally mask. The hot_x and hot_y coordinates will be the location of the mouse pointer, relative to the upper left corner of the pixmap.

GDK.Pixmap
GDK.Bitmap
GDK.DragContext

Set the drag widget. This is a widget that will be shown, and then dragged around by the user during this drag.

GTK.Widget
GDK.DragContext

Setting action to -1 means use the suggested action

GDK.DragContext
GDK.DragContext

One of GDK_ACTION_ASK, GDK_ACTION_COPY, GDK_ACTION_DEFAULT, GDK_ACTION_LINK, GDK_ACTION_MOVE and GDK_ACTION_PRIVATE;

A bitwise or of one or more of GDK_ACTION_ASK, GDK_ACTION_COPY, GDK_ACTION_DEFAULT, GDK_ACTION_LINK, GDK_ACTION_MOVE and GDK_ACTION_PRIVATE;

Is this application the source?

One of GDK_DRAG_PROTO_MOTIF, GDK_DRAG_PROTO_ROOTWIN and GDK_DRAG_PROTO_XDND

Return the drag source widget.

GTK.Widget

The start time of this drag, as a unix time_t (seconds since 0:00 1/1 1970)

One of GDK_ACTION_ASK, GDK_ACTION_COPY, GDK_ACTION_DEFAULT, GDK_ACTION_LINK, GDK_ACTION_MOVE and GDK_ACTION_PRIVATE;

An X-atom. You most likely want to use GDK.Atom.atom_name instead of GDK._Atom(name).

Create a new low-level atom. You should normally not call this function directly. Use GDK.Atom[name] instead of GDK._Atom(name,0).

GDK._Atom

Returns the name of the atom.

A GC, or Graphics Context, is used for most low-level drawing operation.

As an example, the foreground color, background color and drawing function is stored in the GC.

NOIMG

The argument is a either a W(Widget) or a GDK(Drawable) in which the gc will be valid.

GTK.Widget
GDK.GC

Free the gc, called automatically by pike when the object is destroyed.

GDK.GC

Get all (or rather most) values from the GC.

Set the background to the specified GDK.Color.

GDK.Color
GDK.GC

Set the clip mask to the specified GDK.Bitmap

GDK.Bitmap
GDK.GC

Set the clip mask origin to the specified point.

GDK.GC

Set the font to the specified GDK.Font.

GDK.Font
GDK.GC

Set the foreground to the specified GDK.Color.

GDK.Color
GDK.GC

Set the function to the specified one. One of GDK.Xor, GDK.Invert and GDK.Copy.

GDK.GC

If set, anything drawn with this GC will draw on subwindows as well as the window in which the drawing is done.

GDK.GC
GDK.Event

A gdk (low level) image. Mainly used for W(Image) objects.

NOIMG

Create a new GDK.Image object. The firstargument is either 0, which indicates that you want a 'slow' image. If you use '1', you indicate that you want a 'fast' image. Fast images are stored in shared memory, and thus are not sent over any network. But please limit your usage of fast images, they use up a possibly limited system resource set. See the man page for shmget(2) for more information on the limits on shared segments on your system.

A 'fast' image will automatically revert back to 'slow' mode if no shared memory is available.

If the second argument is specified, it is the actual image data.

Image.Image
GDK.Image

Destructor. Destroys the image. Automatically called by pike when the object is destructed.

GDK.Image

Get the pixel value of a pixel as a X-pixel value. It is usualy not very easy to convert this value to a rgb triple. See get_pnm.

Returns the data in the image as a pnm object. Currently, this is always a P6 (true color raw) image. This could change in the future. To get a pike image object do 'Image.PNM.decode( gdkimage->get_pnm() )'

Call this function to grab a portion of a widget (argument 1) to the image. Grabbing non-toplevel widgets may produce unexpected results. To get the size of a widget use -&gt;xsize() and -&gt;ysize(). To get the offset of the upper left corner of the widget, relative to it's X-window (this is what you want for the offset arguments), use -&gt;xoffset() and -&gt;yoffset().

GTK.Widget
GDK.Image

Call this to set this image to either the contents of a pike image or a blank image of a specified size.

Image.Image
GDK.Image

Set the pixel value of a pixel. Please note that the pixel argument is a X-pixel value, which is not easily gotten from a RGB color. See get_pixel and set.

GDK.Image

Normally used like (mapping)rectangle or (array)rectangle.

Create a new rectangle

NOIMG

GDK.Rectangle
GDK.Rectangle

Set the upper left corner and the size of the rectangle.

GDK.Rectangle

a GDK.Window object.

NOIMG

GDK.Drawable

mode is one of GDK_PROP_MODE_APPEND, GDK_PROP_MODE_PREPEND and GDK_PROP_MODE_REPLACE

GDK.Atom
GDK.Atom
GDK.Window

Returns an array of GDK.Window objects.

Not for non-experts. I promise.

GDK.Window
GDK.Window
GDK.Atom
GDK.Window

Returns ([ "x":xpos, "y":ypos, "width":width, "height":height, "depth":bits_per_pixel ])

Returns the value (as a string) of the specified property. The arguments are:

property: The property atom, as an example GDK.Atom.__SWM_VROOT offset (optional): The starting offset, in elements delete_when_done (optional): If set, the property will be deleted when it has been fetched.

Example usage: Find the 'virtual' root window (many window managers put large windows over the screen)

       GDK.Window root = GTK.root_window();
       array maybe=root->children()->
                   get_property(GDK.Atom.__SWM_VROOT)-({0});
       if(sizeof(maybe))
         root=GDK.Window( maybe[0]->data[0] );

GDK.Atom

Return 1 if the window is mapped.

Return 1 if the window, or a part of the window, is visible right now.

Lower this window if the window manager allows that.

GDK.Window

Move and resize the window in one call.

GDK.Window

Raise this window if the window manager allows that.

GDK.Window

Set the background color or image. The argument is either a GDK.Pixmap or a GDK.Color object.

GDK.Color
GDK.Window

xhot,yhot are the locations of the x and y hotspot relative to the upper left corner of the cursor image.

GDK.Bitmap
GDK.Bitmap
GDK.Color
GDK.Color
GDK.Window

Change the window cursor.<table border="0" cellpadding="3" cellspacing="0"> CURS(GDK.Arrow) CURS(GDK.BasedArrowDown) CURS(GDK.BasedArrowUp) CURS(GDK.Boat) CURS(GDK.Bogosity) CURS(GDK.BottomLeftCorner) CURS(GDK.BottomRightCorner) CURS(GDK.BottomSide) CURS(GDK.BottomTee) CURS(GDK.BoxSpiral) CURS(GDK.CenterPtr) CURS(GDK.Circle) CURS(GDK.Clock) CURS(GDK.CoffeeMug) CURS(GDK.Cross) CURS(GDK.CrossReverse) CURS(GDK.Crosshair) CURS(GDK.DiamondCross) CURS(GDK.Dot) CURS(GDK.Dotbox) CURS(GDK.DoubleArrow) CURS(GDK.DraftLarge) CURS(GDK.DraftSmall) CURS(GDK.DrapedBox) CURS(GDK.Exchange) CURS(GDK.Fleur) CURS(GDK.Gobbler) CURS(GDK.Gumby) CURS(GDK.Hand1) CURS(GDK.Hand2) CURS(GDK.Heart) CURS(GDK.Icon) CURS(GDK.IronCross) CURS(GDK.LeftPtr) CURS(GDK.LeftSide) CURS(GDK.LeftTee) CURS(GDK.Leftbutton) CURS(GDK.LlAngle) CURS(GDK.LrAngle) CURS(GDK.Man) CURS(GDK.Middlebutton) CURS(GDK.Mouse) CURS(GDK.Pencil) CURS(GDK.Pirate) CURS(GDK.Plus) CURS(GDK.QuestionArrow) CURS(GDK.RightPtr) CURS(GDK.RightSide) CURS(GDK.RightTee) CURS(GDK.Rightbutton) CURS(GDK.RtlLogo) CURS(GDK.Sailboat) CURS(GDK.SbDownArrow) CURS(GDK.SbHDoubleArrow) CURS(GDK.SbLeftArrow) CURS(GDK.SbRightArrow) CURS(GDK.SbUpArrow) CURS(GDK.SbVDoubleArrow) CURS(GDK.Shuttle) CURS(GDK.Sizing) CURS(GDK.Spider) CURS(GDK.Spraycan) CURS(GDK.Star) CURS(GDK.Target) CURS(GDK.Tcross) CURS(GDK.TopLeftArrow) CURS(GDK.TopLeftCorner) CURS(GDK.TopRightCorner) CURS(GDK.TopSide) CURS(GDK.TopTee) CURS(GDK.Trek) CURS(GDK.UlAngle) CURS(GDK.Umbrella) CURS(GDK.UrAngle) CURS(GDK.Watch) CURS(GDK.Xterm) </table>

GDK.Window

events is a bitwise or of one or more of the following constants: GDK.ExposureMask, GDK.PointerMotionMask, GDK.PointerMotion_HINTMask, GDK.ButtonMotionMask, GDK.Button1MotionMask, GDK.Button2MotionMask, GDK.Button3MotionMask, GDK.ButtonPressMask, GDK.ButtonReleaseMask, GDK.KeyPressMask, GDK.KeyReleaseMask, GDK.EnterNotifyMask, GDK.LeaveNotifyMask, GDK.FocusChangeMask, GDK.StructureMask, GDK.PropertyChangeMask, GDK.VisibilityNotifyMask, GDK.ProximityInMask, GDK.ProximityOutMask and GDK.AllEventsMask

GDK.Window

Set the icon to the specified image (with mask) or the specified GDK.Window. It is up to the window manager to display the icon. Most window manager handles window and pixmap icons, but only a few can handle the mask argument. If you want a shaped icon, the only safe bet is a shaped window.

GDK.Pixmap
GDK.Bitmap
GDK.Window
GDK.Window

Set the icon name to the specified string.

GDK.Window

Set the shape of the widget, or, rather, it's window, to that of the supplied bitmap.

GDK.Bitmap
GDK.Window

Module node representing a single directory.

joinnode

Module node holding possibly multiple directories, and optionally falling back to another level.

dirnode

Actual resolver

joinnode

Lookup from handler module to corresponding root_module.

joinnode

The pike system module path, not including any set by the user.

The complete module search path

The complete include search path

The complete program search path

If we fail to resolv, try the fallback.

Typical configuration:

    0.6->7.0->7.2->7.4->master

CompatResolver

The CompatResolver is initialized with a value that can be casted into a "%d.%d" string, e.g. a version object.

It can also optionally be initialized with a fallback resolver.

CompatResolver

Add a directory to search for include files.

This is the same as the command line option -I.

Note that the added directory will only be searched when using < > to quote the included file.

remove_include_path()

Remove a directory to search for include files.

This function performs the reverse operation of add_include_path().

add_include_path()

Add a directory to search for modules.

This is the same as the command line option -M.

remove_module_path()

Remove a directory to search for modules.

This function performs the reverse operation of add_module_path().

add_module_path()

Add a directory to search for programs.

This is the same as the command line option -P.

remove_program_path()

Remove a directory to search for programs.

This function performs the reverse operation of add_program_path().

add_program_path()

Add a define (without arguments) which will be implicitly defined in cpp calls.

Remove a define from the set that are implicitly defined in cpp calls.

Returns a mapping with the current predefines.

Instantiate static modules in the same way that dynamic modules are instantiated.

Same as resolv, but throws an error instead of returning UNDEFINED if the resolv failed.

This function is called whenever an #include directive is encountered. It receives the argument for #include and should return the file name of the file to include

CompatResolver

In Pike 0.6 the current directory was implicitly searched.

Codec for use with encode_value. It understands all the standard references to builtin functions and pike modules.

The format of the produced identifiers are documented here to allow extension of this class:

The produced names are either strings or arrays. The string variant specifies the thing to look up according to the first character:

'c' Look up in all_constants(). 's' Look up in _static_modules. 'r' Look up with resolv(). 'p' Look up in programs. 'o' Look up in programs, then look up the result in objects. 'f' Look up in fc.

In the array format, the first element is a string as above and the rest specify a series of things to do with the result:

A string Look up this string in the result. 'm' Get module object in dirnode. 'p' Do object_program(result).

All lowercase letters and the symbols ':', '/' and '.' are reserved for internal use in both cases where characters are used above.

When module_object is set and the name would end with an object_program step (i.e. 'p'), then drop that step so that the name corresponds to the object instead. module_object[0] will receive the found object.

Creates an encoder instance. If encoded is specified, it's encoded instead of being reverse resolved to a name. That's necessary to encode programs.

Codec for use with decode_value. This is the decoder corresponding to Encoder. See that one for more details.

Encoder and Decoder rolled into one. This is for mainly compatibility; there's typically no use combining encoding and decoding into the same object.

Encoder
Decoder

The optional argument is the thing to encode; it's passed on to Encoder.

Contains version information about a Pike version.

The major and minor parts of the version.

Set the version in the object.

Methods define so that version objects can be compared and ordered.

The version object can be casted into a string.

CompatResolver
Codec

This constant contains the maximum length of a function entry in a backtrace. Defaults to 200 if no BT_MAX_STRING_LEN define has been given.

Should Pike complain about out of date compiled files. 1 means yes and 0 means no. Controlled by the OUT_OF_DATE_WARNING define.

If not zero compilation warnings will be written out on stderr.

Mapping containing the environment variables.

The mapping currently has the following structure:

- index

Note that the index is lower_case()'d on NT.

varname

Variable name with case intact.

value

Variable value.

This mapping should not be accessed directly; use getenv() and putenv() instead.

This mapping is not compatible with Process.create_process(); use the mapping returned from calling getenv() without arguments instead.

Mapping containing the cache of currently compiled files.

This mapping currently has the following structure:

- filename

The filename path seperator is / on both NT and UNIX.

As a special case the current master program is available under the name "/master".

NoValue

Returns the path for prog in programs, if it got any.

Returns the program for obj in objects, if it got any.

Returns the path for obj in fc, if it got any.

This function is called when the driver wants to cast a string to a program, this might be because of an explicit cast, an inherit or a implict cast. In the future it might receive more arguments, to aid the master finding the right program.

This function is called when an error occurs that is not caught with catch().

This function is called whenever a inherit is called for. It is supposed to return the program to inherit. The first argument is the argument given to inherit, and the second is the file name of the program currently compiling. Note that the file name can be changed with #line, or set by compile_string, so it can not be 100% trusted to be a filename. previous_object(), can be virtually anything in this function, as it is called from the compiler.

This function is called when the drivers wants to cast a string to an object because of an implict or explicit cast. This function may also receive more arguments in the future.

These are useful if you want to start other Pike processes with the same options as this one was started with.

Returns 1 if we´re in async-mode, e.g. if the main method has returned a negative number.

0
1

The backend_thread() function is useful to determine if you are the backend thread - important when doing async/sync protocols. This method is only available if thread_create is present.

This function is called when all the driver is done with all setup of modules, efuns, tables etc. etc. and is ready to start executing _real_ programs. It receives the arguments not meant for the driver and an array containing the environment variables on the same form as a C program receives them.

This function is called whenever a compile error occurs. line is zero for errors that aren't associated with any specific line. err is not newline terminated.

This function is called whenever a compile warning occurs. line is zero for warnings that aren't associated with any specific line. err is not newline terminated.

This function is called when an exception is catched during compilation. Its message is also reported to compile_error if this function returns zero.

Called for every runtime warning. The first argument identifies where the warning comes from, the second identifies the specific message, and the rest depends on that. See code below for currently implemented warnings.

This function is called by cpp() when it wants to do character code conversion.

Converts a module path on the form "Foo.pmod/Bar.pmod" or "/path/to/pike/lib/modules/Foo.pmod/Bar.pmod" to a module identifier on the form "Foo.Bar".

If module_prefix or module_suffix are given, they are prepended and appended, respectively, to the returned string if it's a module file (i.e. ends with ".pmod" or ".so"). If object_suffix is given, it's appended to the returned string if it's an object file (i.e. ends with ".pike").

Describe the path to the module mod.

If mod is a program, attempt to describe the path to a clone of mod.

If an instance of mod is found, it will be returned by changing element 0 of ret_obj.

The a description of the path.

The returned description will end with a proper indexing method currently either "." or "->".

``
``

Version information about the current Pike version.

Version

SDL or Simple DirectMedia Layer is a cross-platform multimedia library designed to provide fast access to the graphics framebuffer, audio device, input and other devices. This module implements a wrapper for SDL and other relevant libraries like SDL_mixer. The interface is similar to the C one, but using generally accepted Pike syntax.

This means that classes are used when appropriate and that method names use all lowercase letters with words separated by _. For example SDL_SetVideoMode is named SDL.set_video_mode. Also note that unless otherwise noted, errors result in an error being thrown rather than returning -1 or 0, as commonly done in SDL methods.

Used in SDL to define a rectangular area. It is sometimes also used to specify only points or sizes (i.e only one of the position and dimension is used).

Position of the upper-left corner of the rectangle.

The width and height of the rectangle.

It is possible to cast a Rect object to an array or to a mapping. The array will have the values in the x, y, w, h order and the mapping will have the values associated with those names.

The Keysym class is used to report key presses and releases. It's available from the SDL.Event class for keyboard events.

The scancode field should generally be left alone - it is the hardware dependent scancode returned by the keyboard. The sym field is extremely useful. It is the SDL-defined value of the key. This field is very useful when you are checking for certain key presses.

mod stores the current state of the keyboard modifiers as explained in SDL.get_mod_state(). The unicode field is only used when UNICODE translation is enabled with SDL.enable_unicode(). If unicode is non-zero then this a the UNICODE character corresponding to the keypress. If the high 9 bits of the character are 0, then this maps to the equivalent ASCII character.

UNICODE translation does have a slight overhead so don't enable it unless its needed.

Hardware specific scancode

SDL virtual keysym

Current key modifiers

Translated character

This describes the format of the pixel data stored at the pixels field of a SDL.Surface. Every surface stores a PixelFormat in the format field.

The number of bits used to represent each pixel in a surface. Usually 8, 16, 24 or 32.

The number of bytes used to represent each pixel in a surface. Usually one to four.

Binary mask used to retrieve individual color values.

Precision loss of each color component.

Binary left shift of each color component in the pixel value.

Pixel value of transparent pixels.

Overall surface alpha value.

Convenience method returning the RGBA precision loss as an array.

Convenience method returning the RGBA masks as an array.

Convenience method returning the RGBA shifts as an array.

Maps the RGB color value to the specified pixel format and returns the pixel value as an integer.

If the format has a palette (8-bit) the index of the closest matching color in the palette will be returned.

If the pixel format has an alpha component it will be returned as all 1 bits (fully opaque).

The red, green and blue components specified as an integer between 0 and 255.

The color as represented by an Image.Color.Color object.

A pixel value best approximating the given RGB color value for a given pixel format.

map_rgba(), get_rgb(), get_rgba()

Image.Color.Color

Maps the RGBA color value to the specified pixel format and returns the pixel value as an integer.

If the format has a palette (8-bit) the index of the closest matching color in the palette will be returned.

If the pixel format has an alpha component it will be returned as all 1 bits (fully opaque).

The red, green and blue components specified as an integer between 0 and 255.

The color as represented by an Image.Color.Color object.

A pixel value best approximating the given RGB color value for a given pixel format.

map_rgb(), get_rgb(), get_rgba()

Image.Color.Color

Get RGB component values from a pixel stored in this pixel format.

A pixel retrieved from a surface with this pixel format or a color previously mapped with map_rgb() or map_rgba().

A Image.Color.Color object with the RGB components of the pixel.

map_rgb(), map_rgba(), get_rgba()

Image.Color.Color

Get RGB component values from a pixel stored in this pixel format.

A pixel retrieved from a surface with this pixel format or a color previously mapped with map_rgb() or map_rgba().

A mapping containing with the RGBA components of the pixel as described below.

- Image.Color.Color color

The RGB color value of the pixel.

- alpha

The alpha value of the pixel in the range 0-255.

map_rgb(), map_rgba(), get_rgb()

Image.Color.Color

This (read-only) class is returned by SDL.get_video_info(). It contains information on either the 'best' available mode (if called before SDL.set_video_mode()) or the current video mode.

Are hardware to hardware colorkey blits accelerated?

Are hardware to hardware alpha blits accelerated?

Are software to hardware blits accelerated?

Are software to hardware colorkey blits accelerated?

Are software to hardware alpha blits accelerated?

Are color fills accelerated?

Total amount of video memory in KB.

Pixel format of the video device.

SDL.PixelFormat

Surface's represent areas of "graphical" memory, memory that can be drawn to. The video framebuffer is returned as a SDL.Surface by SDL.set_video_mode() and SDL.get_video_surface().

The width and height of the surface in pixels.

This is the clipping rectangle as set by set_clip_rect().

SDL.Rect

The following are supported in the flags field.

Surface is stored in system memory

Surface is stored in video memory

Surface uses asynchronous blits if possible.

Allows any pixel-format (Display surface).

Surface has exclusive palette.

Surface is double buffered (Display surface).

Surface is full screen (Display Sur face).

Surface has an OpenGL context (Display Surface).

Surface supports OpenGL blitting (Display Surface).

Surface is resizable (Display Surface).

Surface blit uses hardware acceleration.

Surface use colorkey blitting.

Colorkey blitting is accelerated with RLE.

Surface blit uses alpha blending.

Surface uses preallocated memory.

The pixel format of this surface.

SDL.PixelFormat

Get the value of the specified pixel. The surface needs to be locked before this method can be used.

Pixel coordinate to get.

The value of the specified pixel.

set_pixel(), unlock(), lock()

Set the value of the specified pixel. The surface needs to be locked before this method can be used.

Pixel coordinate to modify.

Pixel value to set to the specified pixel.

A reference to the surface itself.

get_pixel(), unlock(), lock()

This methods locks the surface to allow direct access to the pixels using the get_pixel() and set_pixel() methods. Note that although all surfaces in SDL don't require locking, you still need to call this method to enable the set/get pixel methods. You should unlock the surface when you're doing modifying it.

Calling this method multiple times means that you need to call unlock an equal number of times for the surface to become unlocked.

1 for success or 0 if the surface couldn't be locked.

unlock(), set_pixel(), get_pixel()

Surfaces that were previously locked using lock() must be unlocked with unlock(). Surfaces should be unlocked as soon as possible.

lock()

This (re)initializes this surface using the specified parameters. Any previously allocated data will be freed. If depth is 8 bits an empty palette is allocated for the surface, otherwise a 'packed-pixel' SDL.PixelFormat is created using the [RGBA]mask's provided. width and height specifies the desired size of the image. The flags specifies the type of surface that should be created. It is an OR'd combination of the following possible values:

SDL will create the surface in system memory. This improves the performance of pixel level access, however you may not be able to take advantage of some types of hardware blitting.

SDL will attempt to create the surface in video memory. This will allow SDL to take advantage of Video->Video blits (which are often accelerated).

This flag turns on colourkeying for blits from this surface. If SDL.HWSURFACE is also specified and colourkeyed blits are hardware-accelerated, then SDL will attempt to place the surface in video memory. Use set_color_key() to set or clear this flag after surface creation.

This flag turns on alpha-blending for blits from this surface. If SDL.HWSURFACE is also specified and alpha blending blits are hardware-accelerated, then the surface will be placed in video memory if possible. Use set_alpha() to set or clear this flag after surface creation.

If an alpha-channel is specified (that is, if Amask is nonzero), then the SDL.SRCALPHA flag is automatically set. You may remove this flag by calling set_alpha() after surface creation.

A reference to itself.

If this method fails, the surface will become uninitialized.

set_image()

SDL.Surface

This (re)initializes this surface from the Image.Image in image. Any previously allocated data will be freed. If initialization is successful, this surface will use RGBA8888 format. For good blitting performance, it should be converted to the display format using display_format().

The source image.

Optional alpha channel. In Pike, the alpha channel can have different alpha values for red, green and blue. Since SDL doesn't support this, only the alpha value of the red color is used in the conversion. When this calling convention is used, the surface alpha value of image is ignored.

When present this specifies the type of surface that should be created. It is an OR'd combination of the following possible values:

SDL will create the surface in system memory. This improves the performance of pixel level access, however you may not be able to take advantage of some types of hardware blitting.

SDL will attempt to create the surface in video memory. This will allow SDL to take advantage of Video->Video blits (which are often accelerated).

This flag turns on colourkeying for blits from this surface. If SDL.HWSURFACE is also specified and colourkeyed blits are hardware-accelerated, then SDL will attempt to place the surface in video memory. Use set_color_key() to set or clear this flag after surface creation.

This flag turns on alpha-blending for blits from this surface. If SDL.HWSURFACE is also specified and alpha blending blits are hardware-accelerated, then the surface will be placed in video memory if possible. Note that if this surface has an alpha value specified, this flag is enabled automatically. Use set_alpha() to modify this flag at a later point.

If this method fails, the surface will become uninitialized.

A reference to itself.

init()

Image.Image
SDL.Surface
Image.Image
Image.Image
SDL.Surface

This function takes a surface and copies it to a new surface of the pixel format and colors of the video framebuffer, suitable for fast blitting onto the display surface. It calls convert_surface().

If you want to take advantage of hardware colorkey or alpha blit acceleration, you should set the colorkey and / or alpha value before calling this function.

If you want an alpha channel, see display_format_alpha().

The new surface. An error is thrown if the conversion fails.

SDL.Surface

This function takes a surface and copies it to a new surface of the pixel format and colors of the video framebuffer, suitable for fast blitting onto the display surface. It calls convert_surface().

If you want to take advantage of hardware colorkey or alpha blit acceleration, you should set the colorkey and / or alpha value before calling this function.

This function can be used to convert a colourkey to an alpha channel, if the SDL.SRCCOLORKEY flag is set on the surface. The generated surface will then be transparent (alpha=0) where the pixels match the colourkey, and opaque (alpha=255) elsewhere.

The new surface. An error is thrown if the conversion fails.

SDL.Surface

Document this function

SDL.Surface
SDL.Rect
SDL.Rect

Document this function

SDL.Rect

Document this function

Document this function

Document this function

Document this function

SDL.Rect

Document this function

SDL.PixelFormat

Document this function

Document this function

Document this function

Document this function

Document this function

Document this function

Document this function

Document this function

Document this function

Document this function

Document this function

Document this variable

Document this function

Document this variable

Document this function

CDTrack

Document this function

Document this function

Document this function

Document this function

Document this function

Document this function

Document this function

Document this function

Document this function

Document this function

Document this function

Document this function

Document this function

Document this function

Document this function

Document this function

Document this function

Document this function

Document this function

Document this function

Document this function

Document this function

Document this function

Keysym

Initializes SDL. This should be called before all other SDL functions.

The flags parameter specifies what part(s) of SDL to initialize. It can be one of many of the following ORed together.

Initializes the timer subsystem.

Initializes the audio subsystem.

Initializes the video subsystem.

Initializes the cdrom subsystem.

Initializes the joystick subsystem.

Initialize all of the above.

Prevents SDL from catching fatal signals.

Run event polling in a separate thread. Not always supported.

SDL.quit(), SDL.init_sub_system(), SDL.quit_sub_system()

Get the last internal SDL error.

The error string, or zero if there was no error.

After SDL has been initialized with init() you may initialize uninitialized subsystems with this method.

The same as what is used in SDL.init().

After SDL has been initialized with SDL.init() you may initialize uninitialized subsystems with this method.

a bitwise OR'd combination of the subsystems you wish to check (see SDL.init() for a list of subsystem flags).

SDL.init(), SDL.quit(), SDL.quit_sub_system()

This method allows you to see which SDL subsytems have been initialized.

a bitwise OR'd combination of the subsystems you wish to check (see SDL.init() for a list of subsystem flags).

a bitwised OR'd combination of the initialized subsystems

SDL.init(), SDL.init_sub_system()

Shuts down all SDL subsystems and frees the resources allocated to them. This should always be called before you exit.

You can use the atexit() method to ensure that this method is always called when Pike exits normally.

SDL.init(), SDL.init_sub_system(), SDL.quit_sub_system()

Enables/Disables UNICODE keyboard translation.

If you wish to translate a keysym to it's printable representation, you need to enable UNICODE translation using this function and then look in the unicode member of the SDL.Keysym class. This value will be zero for keysyms that do not have a printable representation. UNICODE translation is disabled by default as the conversion can cause a slight overhead.

A value of 1 enables Unicode translation, 0 disables it and -1 leaves it unchanged (useful for querying the current translation mode).

The previous translation mode (1 enabled, 0 disabled). If enable is -1, the return value is the current translation mode.

SDL.Keysym

Returns the current state of the modifier keys (CTRL, ALT, etc.).

The return value can be an OR'd combination of the following: SDL.KMOD_NONE, SDL.KMOD_LSHIFT, SDL.KMOD_RSHIFT, SDL.KMOD_LCTRL, SDL.KMOD_RCTRL, SDL.KMOD_LALT, SDL.KMOD_RALT, SDL.KMOD_LMETA, SDL.KMOD_RMETA, SDL.KMOD_NUM, SDL.KMOD_CAPS, and SDL.KMOD_MODE. For convenience the following are also defined: SDL.KMOD_CTRL, SDL.KMOD_SHIFT, SDL.KMOD_ALT and SDL.KMOD_META

SDL.get_key_state()

Gets a snapshot of the current keyboard state. The current state is return as a string. The string is indexed by the SDL.K_* symbols. A value of 1 means the key is pressed and a value of 0 means its not.

SDL.pump_events() to update the state array.

Document this function

On hardware that supports double-buffering, this function sets up a flip and returns. The hardware will wait for vertical retrace, and then swap video buffers before the next video surface blit or lock will return. On hardware that doesn't support double-buffering, this is equivalent to calling SDL.update_rect(screen, 0, 0, 0, 0)

The SDL.DOUBLEBUF flag must have been passed to SDL_SetVideoMode, when setting the video mode for this function to perform hardware flipping.

The screen object to flip. If missing, the default screen is used.

This function returns 1 if successful, or 0 if there was an error.

SDL.update_rect()

SDL.Surface

Makes sure the given area is updated on the given screen. The rectangle must be confined within the screen boundaries (no clipping is done).

If 'x', 'y', 'w' and 'h' are all 0, SDL_UpdateRect will update the entire screen.

This function should not be called while 'screen' is locked.

Top left corner of the rectangle to update.

Width and height of the rectangle to update.

The screen object to flip. If missing, the default screen is used.

SDL.flip()

SDL.Surface

Document this function

Document this function

Document this function

Document this function

Document this function

Document this function

Document this function

Document this function

Document this function

Document this function

SDL.Surface
SDL.Surface
SDL.Rect
SDL.Rect

Document this function

Document this function

Document this function

Document this function

Document this function

SDL.Surface

Document this function

Document this function

Document this function

Document this function

Document this function

Document this function

Document this function

Document this function

Document this function

This is a container that can be scrolled around, but it has no scrollbars. You can connect scrollbars to it using the adjustment objects. GTK.Viewport(GTK.Adjustment(),GTK.Adjustment())->set_usize(100,100) ../images/gtk_viewport.png

GTK.Viewport(GTK.Adjustment(),GTK.Adjustment())->set_usize(100,100)->set_shadow_type(GTK.SHADOW_ETCHED_IN) ../images/gtk_viewport_2.png

GTK.Viewport(GTK.Adjustment(),GTK.Adjustment())->set_usize(100,100)->add(GTK.Label("A label with a very long text on it, it will not fit"))->set_shadow_type(GTK.SHADOW_ETCHED_IN) ../images/gtk_viewport_3.png

lambda(){ object a1;object v = GTK.Viewport(a1=GTK.Adjustment(),GTK.Adjustment())->set_usize(100,100)->add(GTK.Label("A label with a very long text on it, it will not fit"))->set_shadow_type(GTK.SHADOW_ETCHED_IN);call_out(a1->set_value,0,100.0);return v;}() ../images/gtk_viewport_4.png

GTK.Bin

Create a new viewport. The adjustments are used to select what part of the viewport to view to the user. They are normally connected to a scrollbar or something similar.

GTK.Adjustment
GTK.Adjustment
GTK.Viewport

Return the current horizontal adjustment object

GTK.Adjustment

Return the current vertical adjustment object

GTK.Adjustment

Set a new horizontal adjustment object.

GTK.Adjustment
GTK.Viewport

Set the shadow style. One of SHADOW_ETCHED_IN, SHADOW_ETCHED_OUT, SHADOW_IN, SHADOW_NONE and SHADOW_OUT

GTK.Viewport

Set a new vertical adjustment object.

GTK.Adjustment
GTK.Viewport

An AccelGroup stores keybindings. A group is automatically created by W(MenuFactory)

NOIMG

GTK.Data

the widget is the one in which the signal specified by 'signal' recides.

The key is the character code (such as 'a' for the a key and '@' for the @ key), and modifiers is a bitmap of one or more bits, the bits are . Flags is one or more of ACCEL_LOCKED, ACCEL_SIGNAL_VISIBLE and ACCEL_VISIBLE

GTK.Widget
GTK.AccelGroup

Create a new accelerator group

GTK.AccelGroup
GTK.AccelGroup

Remove all bindings for the specified key/mask in the specified object.

GTK.Widget
GTK.AccelGroup

The GTK.Editable class is a base class for widgets for editing text, such as W(Entry) and W(Text). It cannot be instantiated by itself. The editable class contains functions for generically manipulating an editable widget, a large number of action signals used for key bindings, and several signals that an application can connect to to modify the behavior of a widget.

Signals: activate Indicates that the user has activated the widget in some fashion. Generally, this will be done with a keystroke. (The default binding for this action is Return for GTK.Entry and Control-Return for GTK.Text.

changed Called when the text in the edit area is changed

copy_clipboard An action signal. Causes the characters in the current selection to be copied to the clipboard.

cut_clipboard An action signal. Causes the characters in the current selection to be copied to the clipboard and then deleted from the widget.

delete_text This signal is emitted when text is deleted from the widget by the user. The default handler for this signal will normally be responsible for inserting the text, so by connecting to this signal and then stopping the signal with signal_emit_stop(), it is possible to modify the inserted text, or prevent it from being inserted entirely. The start_pos and end_pos parameters are interpreted as for delete_text()

insert_text This signal is emitted when text is inserted into the widget by the user. The default handler for this signal will normally be responsible for inserting the text, so by connecting to this signal and then stopping the signal with signal_emit_stop(), it is possible to modify the inserted text, or prevent it from being inserted entirely.

kill_char An action signal. Delete a single character.

kill_line An action signal. Delete a single line.

kill_word n action signal. Delete a single word.

move_cursor An action signal. Move the cursor position.

move_page An action signal. Move the cursor by pages.

move_to_column An action signal. Move the cursor to the given column.

move_to_row An action signal. Move the cursor to the given row.

move_word An action signal. Move the cursor by words.

paste_clipboard An action signal. Causes the contents of the clipboard to be pasted into the editable widget at the current cursor position.

set_editable Determines if the user can edit the text in the editable widget or not. This is meant to be overriden by child classes and should not generally be useful to applications.

GTK.Widget

Causes the characters in the current selection to be copied to the clipboard.

GTK.Editable

Causes the characters in the current selection to be copied to the clipboard and then deleted from the widget.

GTK.Editable

Deletes the current contents of the widgets selection and disclaims the selection.

GTK.Editable

Delete a sequence of characters. The characters that are deleted are those characters at positions from start_pos up to, but not including end_pos. If end_pos is negative, then the the characters deleted will be those characters from start_pos to the end of the text.

GTK.Editable

Retrieves a sequence of characters. The characters that are retrieved are those characters at positions from start_pos up to, but not including end_pos. If end_pos is negative, then the the characters retrieved will be those characters from start_pos to the end of the text.

Returns the cursor position

Insert 'num_chars' characters from the text at the position 'where'.

GTK.Editable

Causes the contents of the clipboard to be pasted into the given widget at the current cursor position.

GTK.Editable

Selects a region of text. The characters that are selected are those characters at positions from start_pos up to, but not including end_pos. If end_pos is negative, then the the characters selected will be those characters from start_pos to the end of the text. are

GTK.Editable

Determines if the user can edit the text in the editable widget or not.

GTK.Editable

Sets the cursor position.

GTK.Editable
GTK.Label
GTK.TipsQuery
GTK.Widget
GTK.Widget
GTK.Widget
GTK.TipsQuery
GTK.TipsQuery
GTK.TipsQuery
GTK.TipsQuery

The basic window. Nothing much to say about it. It can only contain one child widget. Show the main window last to avoid annoying flashes when the subwidet (and it's subwidgets) are added to it, this is done automatically by calling 'window->show_all' when you are done with your widget packing.

Signals: move_resize

set_focus

GTK.Bin

Activate the default widget

Activate the focus widget

This function adds an accelerator group to the window. The shortcuts in the table will work in the window, it's child, and all children of it's child that do not select keyboard input.

GTK.AccelGroup
GTK.Window

Add an embedded X-window

GTK.Window

Argument is one of WINDOW_DIALOG, WINDOW_POPUP and WINDOW_TOPLEVEL

GTK.Window

If true, the window can grow if nessesary

If true, the window can be shrunk by the user

If true, the window will shrink if possible

The default widget

GTK.Widget

The focus widget

GTK.Widget

If true, this is a modal dialog window

The title of the window

The parent window for this window if this is a transient window, 0 otherwise.

GTK.Window

The window type, one of WINDOW_DIALOG, WINDOW_POPUP and WINDOW_TOPLEVEL

The window manager class of this application.

The window manager name of this application.

Lower this window if the window manager allows that.

GTK.Window

Raise this window if the window manager allows that.

GTK.Window

Remove a previously installed table.

GTK.AccelGroup
GTK.Window

Remove the embeded X window

GTK.Window

Set the default widget to the specified widget. The specified widget must have the GTK.CanDefault flag set.

GTK.Widget
GTK.Window

The following differs from set_usize, in that set_usize() overrides the requisition, and thus sets a minimum size, while this only sets the size requested from the WM.

GTK.Window

Set the focus widget to the specified child. Please note that this is normaly handled automatically.

GTK.Widget
GTK.Window

Set the icon to the specified image (with mask) or the specified GDK.Window. It is up to the window manager to display the icon. Most window manager handles window and pixmap icons, but only a few can handle the mask argument. If you want a shaped icon, the only safe bet is a shaped window.

GDK.Pixmap
GDK.Bitmap
GDK.Window
GTK.Window

Set the icon name to the specified string.

GTK.Window

/ Is this a modal dialog?

GTK.Window

If allow shrink is true, the user can resize the window to a smaller size. If allow_grow is true, the window can resize itself, and the user can resize the window, to a bigger size. It auto shrink is true, the window will resize itself to a smaller size when it's subwidget is resized.

GTK.Window

one of WINDOW_DIALOG, WINDOW_POPUP, WINDOW_TOPLEVEL, WIN_POS_CENTER, WIN_POS_MOUSE and WIN_POS_NONE

GTK.Window

Set the window title. The default title is the value sent to setup_gtk, or if none is sent, Pike GTK.

GTK.Window

Mark this window as a transient window for the parent window. Most window managers renders transient windows differently (different borders, sometimes no resize widgets etc)

Useful for short lived dialogs.

GTK.Window
GTK.Window

Set the window manager application name and class.

GTK.Window

The Spin Button widget is generally used to allow the user to select a value from a range of numeric values. It consists of a text entry box with up and down arrow buttons attached to the side. Selecting one of the buttons causes the value to "spin" up and down the range of possible values. The entry box may also be edited directly to enter a specific value.

The Spin Button allows the value to have zero or a number of decimal places and to be incremented/decremented in configurable steps. The action of holding down one of the buttons optionally results in an acceleration of change in the value according to how long it is depressed.

The Spin Button uses an W(Adjustment) object to hold information about the range of values that the spin button can take.

The attributes of an W(Adjustment) are used by the Spin Button in the following way: <ul><li>value: initial value for the Spin Button</li> <li>lower: lower range value</li> <li>upper: upper range value</li> <li>step_increment: value to increment/decrement when pressing mouse button 1 on a button</li> <li>page_increment: value to increment/decrement when pressing mouse button 2 on a button</li> <li>page_size: unused</li> </ul>

The argument order for the W(Adjustment) constructor is: value, lower, upper, step_increment, page_increment, page_size

GTK.SpinButton( GTK.Adjustment(),0.1, 1 )->set_usize(60,20) ../images/gtk_spinbutton.png

GTK.Entry

Adjustment (with the lower/upper/increse values), climb_rate and digits

GTK.Adjustment
GTK.SpinButton

The climb_rate argument take a value between 0.0 and 1.0 and indicates the amount of acceleration that the Spin Button has. The digits argument specifies the number of decimal places to which the value will be displayed.

GTK.Adjustment
GTK.SpinButton

The amount of acceleration that the Spin Button has. 0.0 is no accelleration and 1.0 is highest accelleration.

The number of decimal places to which the value will be displayed.

If != 0 the user can not enter anything but numeric values.

If != 0 the Spin Button will round the value to the nearest step_increment.

The update policy. GTK_UPDATE_ALWAYS or GTK_UPDATE_IF_VALID.

The current value of a Spin Button can be retrieved as a float.

The current value of a Spin Button can be retrieved as a int.

If != 0 the Spin Button will wrap around between the upper and lower range values.

Set a new adjustment.

GTK.Adjustment
GTK.SpinButton

Set the number of digits to show to the user.

GTK.SpinButton

If true, it is a numeric value. This prevents a user from typing anything other than numeric values into the text box of a Spin Button

GTK.SpinButton

Type is one of SHADOW_ETCHED_IN, SHADOW_ETCHED_OUT, SHADOW_IN, SHADOW_NONE and SHADOW_OUT

GTK.SpinButton

Set the Spin Button to round the value to the nearest step_increment, which is set within the Adjustment object used with the Spin Button

GTK.SpinButton

The possible values of policy are either GTK.UpdateAlways or GTK.UpdateIfValid.

These policies affect the behavior of a Spin Button when parsing inserted text and syncing its value with the values of the Adjustment.

In the case of GTK.UpdateIfValid the Spin Button value only gets changed if the text input is a numeric value that is within the range specified by the Adjustment. Otherwise the text is reset to the current value.

In case of GTK.UpdateAlways errors are ignored while converting text into a numeric value.

GTK.SpinButton

Set the value.

GTK.SpinButton

If true, the spin button will wrap from the lowest to the highest value, and the highest to the lowest.

GTK.SpinButton

If you want to alter the value of a Spin Value relative to its current value, then this ffunction can be used.

The direction paramenter is one of SPIN_END, SPIN_HOME, SPIN_PAGE_BACKWARD, SPIN_PAGE_FORWARD, SPIN_STEP_BACKWARD, SPIN_STEP_FORWARD and SPIN_USER_DEFINED

GTK.SpinStepForward and GTK.SpinStepBackward change the value of the Spin Button by the amount specified by increment, unless increment is equal to 0, in which case the value is changed by the value of step_increment in theAdjustment.

GTK.SpinPageForward and GTK.SpinPageBackward simply alter the value of the Spin Button by increment.

GTK.SpinHome sets the value of the Spin Button to the bottom of the Adjustments range.

GTK.SpinEnd sets the value of the Spin Button to the top of the Adjustments range.

GTK.SpinUserDefined simply alters the value of the Spin Button by the specified amount.

GTK.SpinButton

Explicitly request that the Spin Button updates itself

GTK.SpinButton

A fixed container is a container that keeps it's children at fixed locations and give them fixed sizes, both given in pixels.

Example: GTK.Fixed()->put(GTK.Label("100,100"), 100, 100)->put(GTK.Label("0,0"), 0, 0)->set_usize(150,115) ../images/gtk_fixed.png

GTK.Container

Create a new fixed widget

GTK.Fixed

Move the widget to new_xpos,new_ypos from it's old location.

GTK.Widget
GTK.Fixed

Place the widget at xpos,ypos.

GTK.Widget
GTK.Fixed

A GTK.Menu is a W(MenuShell) that implements a drop down menu consisting of a list of W(MenuItem) objects which can be navigated and activated by the user to perform application functions.

A GTK.Menu is most commonly dropped down by activating a W(MenuItem) in a W(MenuBar) or popped up by activating a W(MenuItem) in another GTK.Menu.

A GTK.Menu can also be popped up by activating a W(OptionMenu). Other composite widgets such as the W(Notebook) can pop up a GTK.Menu as well.

Applications can display a GTK.Menu as a popup menu by calling the popup() function. The example below shows how an application can pop up a menu when the 3rd mouse button is pressed.

       GTK.Menu menu = create_menu();
       GTK.Window window = create_window();
       window->signal_connect( "button_press_event", lambda(GTK.Menu m,
                                                            GTK.Window w,
                                                            mapping e ) {
                 if( e->button == 3 )
                  menu->popup();
              }, menu );

GTK.MenuShell

Adds a new W(MenuItem) to the end of the menu's item list.

GTK.Widget
GTK.Menu

Attach the menu to a widget

GTK.Widget
GTK.Menu

Create a new GTK.Menu widget.

GTK.Menu

Detaches the menu from the widget to which it had been attached.

GTK.Menu

Returns the selected menu item from the menu. This is used by the W(OptionMenu).

GTK.Widget

Returns the W(Widget) that the menu is attached to.

GTK.Widget

return 1 if the menu is torn off.

Adds a new W(MenuItem) to the menu's item list at the position indicated by position.

GTK.Widget
GTK.Menu

Removes the menu from the screen.

GTK.Menu

The default button is 3.

GTK.Menu

Adds a new W(MenuItem) to the start of the menu's item list.

GTK.Widget
GTK.Menu

Moves a W(MenuItem) to a new position within the GTK.Menu.

GTK.Widget
GTK.Menu

Repositions the menu according to its position function.

GTK.Menu

Set the W(AccelGroup) which holds global accelerators for the menu.

GTK.AccelGroup
GTK.Menu

Selects the specified menu item within the menu. This is used by the W(OptionMenu).

GTK.Menu

Changes the tearoff state of the menu. A menu is normally displayed as drop down menu which persists as long as the menu is active. It can also be displayed as a tearoff menu which persists until it is closed or reattached.

GTK.Menu

Sets the title string for the menu. The title is displayed when the menu is shown as a tearoff menu.

GTK.Menu

The category of range widgets includes the ubiquitous scrollbar widget and the less common "scale" widget. Though these two types of widgets are generally used for different purposes, they are quite similar in function and implementation. All range widgets share a set of common graphic elements, each of which has its own X window and receives events. They all contain a "trough" and a "slider" (what is sometimes called a "thumbwheel" in other GUI environments). Dragging the slider with the pointer moves it back and forth within the trough, while clicking in the trough advances the slider towards the location of the click, either completely, or by a designated amount, depending on which mouse button is used.

As mentioned in the W(Adjustment) page, all range widgets are associated with an adjustment object, from which they calculate the length of the slider and its position within the trough. When the user manipulates the slider, the range widget will change the value of the adjustment.

All of the GTK range widgets react to mouse clicks in more or less the same way. Clicking button-1 in the trough will cause its adjustment's page_increment to be added or subtracted from its value, and the slider to be moved accordingly. Clicking mouse button-2 in the trough will jump the slider to the point at which the button was clicked. Clicking any button on a scrollbar's arrows will cause its adjustment's value to change step_increment at a time.

It may take a little while to get used to, but by default, scrollbars as well as scale widgets can take the keyboard focus in GTK. If you think your users will find this too confusing, you can always disable this by unsetting the GTK.CanFocus flag on the scrollbar, like this:

scrollbar->unset_flag( GTK.CanFocus );

The key bindings (which are, of course, only active when the widget has focus) are slightly different between horizontal and vertical range widgets, for obvious reasons. They are also not quite the same for scale widgets as they are for scrollbars, for somewhat less obvious reasons (possibly to avoid confusion between the keys for horizontal and vertical scrollbars in scrolled windows, where both operate on the same area).

GTK.Widget
GTK.Adjustment

set_adjustment() does absolutely nothing if you pass it the adjustment that range is already using, regardless of whether you changed any of its fields or not. If you pass it a new Adjustment, it will unreference the old one if it exists (possibly destroying it), connect the appropriate signals to the new one, and call the private function gtk_range_adjustment_changed(), which will (or at least, is supposed to...) recalculate the size and/or position of the slider and redraw if necessary.

GTK.Adjustment
GTK.Range

The "update policy" of a range widget defines at what points during user interaction it will change the value field of its Adjustment and emit the "value_changed" signal on this Adjustment. The update policies are:

This is the default. The "value_changed" signal is emitted continuously, i.e., whenever the slider is moved by even the tiniest amount.

The "value_changed" signal is only emitted once the slider has stopped moving and the user has released the mouse button.

The "value_changed" signal is emitted when the user releases the mouse button, or if the slider stops moving for a short period of time.

GTK.Range

Update the slider values.

GTK.Range

GTK.Curve() ../images/gtk_curve.png

GTK.DrawingArea
GTK.Curve
GTK.Curve

One of CURVE_TYPE_FREE, CURVE_TYPE_LINEAR and CURVE_TYPE_SPLINE;

GTK.Curve
GTK.Curve
GTK.Curve
GTK.Curve

This widget provides an analog dial widget, similar to, for example, a physical volume control on a stereo. Dial values can be changable or read-only for value reporting. GTK.Dial( GTK.Adjustment() ); ../images/gtk_dial.png

GTK.Dial( GTK.Adjustment(10.0) )->set_percentage(0.4); ../images/gtk_dial_2.png

GTK.Widget
GTK.Adjustment
GTK.Dial
GTK.Adjustment

Retrieves the current percentage held in the dial widget.

Retrieves the current value helt in the dial widget.

set_adjustment() does absolutely nothing if you pass it the adjustment that range is already using, regardless of whether you changed any of its fields or not. If you pass it a new Adjustment, it will unreference the old one if it exists (possibly destroying it), connect the appropriate signals to the new one, and call the private function gtk_range_adjustment_changed(), which will (or at least, is supposed to...) recalculate the size and/or position of the slider and redraw if necessary.

GTK.Adjustment
GTK.Dial

Sets the GTK.Dial's value to percent of dial->adjustment->upper. The upper value is set when the GtkAdjustment is created.

GTK.Dial

The "update policy" of a range widget defines at what points during user interaction it will change the value field of its Adjustment and emit the "value_changed" signal on this Adjustment. The update policies are:

This is the default. The "value_changed" signal is emitted continuously, i.e., whenever the slider is moved by even the tiniest amount.

The "value_changed" signal is only emitted once the slider has stopped moving and the user has released the mouse button.

The "value_changed" signal is emitted when the user releases the mouse button, or if the slider stops moving for a short period of time.

GTK.Dial

Sets the current value held in the GtkDial's adjustment object to value. Returns the new percentage of value to the adjustment's upper limit.

Specifies whether or not the user is to be able to edit the value represented by the dial widget. If view_only is TRUE, the dial will be set to view-only mode, and the user will not be able to edit it. If view_only is FALSE, the user will be able to change the valuerepresented.

GTK.Dial

Thee combo box is another fairly simple widget that is really just a collection of other widgets. From the user's point of view, the widget consists of a text entry box and a pull down menu from which the user can select one of a set of predefined entries. Alternatively, the user can type a different option directly into the text box.

The combo box has two principal parts that you as the programmer really care about: The W(entry) and the W(list).

GTK.Combo() ../images/gtk_combo.png

GTK.Hbox

Create a new combo box

GTK.Combo

This will disable the 'activate' signal for the entry widget in the combo box.

GTK.Combo

The entry widget

GTK.Entry

set_case_sensitive() toggles whether or not GTK searches for entries in a case sensitive manner. This is used when the Combo widget is asked to find a value from the list using the current entry in the text box. This completion can be performed in either a case sensitive or insensitive manner, depending upon the use of this function. The Combo widget can also simply complete the current entry if the user presses the key combination MOD-1 and "Tab". MOD-1 is often mapped to the "Alt" key, by the xmodmap utility. Note, however that some window managers also use this key combination, which will override its use within GTK.

GTK.Combo

The item is one of the ones in the list subwidget.

GTK.Item
GTK.Combo

Set the values in the popdown list.

GTK.Combo

set_use_arrows() lets the user change the value in the entry using the up/down arrow keys. This doesn't bring up the list, but rather replaces the current text in the entry with the next list entry (up or down, as your key choice indicates). It does this by searching in the list for the item corresponding to the current value in the entry and selecting the previous/next item accordingly. Usually in an entry the arrow keys are used to change focus (you can do that anyway using TAB). Note that when the current item is the last of the list and you press arrow-down it changes the focus (the same applies with the first item and arrow-up).

GTK.Combo

set_use_arrows_always() allows the use the the up/down arrow keys to cycle through the choices in the dropdown list, just as with set_use_arrows, but it wraps around the values in the list, completely disabling the use of the up and down arrow keys for changing focus.

GTK.Combo

If value_must_be_in_list is true, the user will not be able to enter any value that is not in the list. If ok_if_empty is true, empty values are possible as well as the values in the list.

GTK.Combo

Simply creates a vertical separator. No bells or whistles. GTK.Vseparator()->set_usize(3,50) ../images/gtk_vseparator.png

GTK.Separator

Used to create a new vseparator widget.

GTK.Vseparator

The paned window widgets are useful when you want to divide an area into two parts, with the relative size of the two parts controlled by the user. A groove is drawn between the two portions with a handle that the user can drag to change the ratio. This widgets makes a horizontal division

See W(Paned) for details.

GTK.Hpaned()->add1(GTK.Label("Left\nSide\nOf\nPane"))->add2(GTK.Label("Right\nSide\nOf\nPane"))->set_usize(100,100) ../images/gtk_hpaned.png

GTK.Paned
GTK.Hpaned

The frame widget is a Bin that surrounds its child with a decorative frame and an optional label. If present, the label is drawn in a gap in the top side of the frame. The position of the label can be controlled with set_label_align().

Used to visually group objects.

GTK.Frame("Title")->add(GTK.Label("Contents")) ../images/gtk_frame.png

GTK.Frame()->add(GTK.Label("Contents")) ../images/gtk_frame_2.png

GTK.Frame()->add(GTK.Label("Contents"))->set_shadow_type(GTK.SHADOW_IN) ../images/gtk_frame_3.png

GTK.Container

Create a new W(Frame) widget.

GTK.Frame

Set the text of the label.

GTK.Frame

Arguments are xalignment and yalignment. 0.0 is left or topmost, 1.0 is right or bottommost. The default value for a newly created Frame is 0.0.

GTK.Frame

Set the shadow type for the Frame widget. The type is one of SHADOW_ETCHED_IN, SHADOW_ETCHED_OUT, SHADOW_IN, SHADOW_NONE and SHADOW_OUT

GTK.Frame

Most packing is done by creating boxes. These are invisible widget containers that we can pack our widgets into which come in two forms, a horizontal box, and a vertical box. This is the horizontal one. When packing widgets into a horizontal box, the objects are inserted horizontally from left to right or right to left depending on the call used.

GTK.Hbox(0,0)->add(GTK.Button("Hello"))->add(GTK.Button("World"))->pack_end_defaults(GTK.Button("From right"))->pack_start_defaults(GTK.Button("From left")) ../images/gtk_hbox.png

GTK.Hbox(1,0)->add(GTK.Button("Hello"))->add(GTK.Button("World"))->pack_end_defaults(GTK.Button("From right"))->pack_start_defaults(GTK.Button("From left")) ../images/gtk_hbox_2.png

GTK.Hbox(1,40)->add(GTK.Button("Hello"))->add(GTK.Button("World"))->pack_end_defaults(GTK.Button("From right"))->pack_start_defaults(GTK.Button("From left")) ../images/gtk_hbox_3.png

GTK.Box

Create a new horizontal box widget. If all_same_size is true, all widgets will have exactly the same size. hpadding is added to the left and right of the children.

GTK.Hbox

Most packing is done by creating boxes. These are invisible widget containers that we can pack our widgets into which come in two forms, a horizontal box, and a vertical box. This is the vertical one. When packing widgets into a vertical box, the objects are inserted horizontally from top to bottom or bottom to top depending on the call used.

GTK.Vbox(0,0)->add(GTK.Button("Hello"))->add(GTK.Button("World"))->pack_end_defaults(GTK.Button("From right"))->pack_start_defaults(GTK.Button("From left")) ../images/gtk_vbox.png

GTK.Vbox(1,0)->add(GTK.Button("Hello"))->add(GTK.Button("World"))->pack_end_defaults(GTK.Button("From right"))->pack_start_defaults(GTK.Button("From left")) ../images/gtk_vbox_2.png

GTK.Vbox(1,40)->add(GTK.Button("Hello"))->add(GTK.Button("World"))->pack_end_defaults(GTK.Button("From right"))->pack_start_defaults(GTK.Button("From left")) ../images/gtk_vbox_3.png

GTK.Box

Create a new horizontal box widget. If all_same_size is true, all widgets will have exactly the same size. padding is added to the top and bottom of the children.

GTK.Vbox

A HbuttonBox is very similar to a Hbox. The major diffference is that the button box is made to pack buttons in, and has a few convenience function for normal button layouts.

GTK.HbuttonBox()->add(GTK.Button("Hello"))->add(GTK.Button("World"))->set_usize(400,30) ../images/gtk_hbuttonbox.png

GTK.HbuttonBox()->add(GTK.Button("Hello"))->add(GTK.Button("World"))->set_layout(GTK.BUTTONBOX_SPREAD)->set_usize(400,30) ../images/gtk_hbuttonbox_2.png

GTK.HbuttonBox()->add(GTK.Button("Hello"))->add(GTK.Button("World"))->set_layout(GTK.BUTTONBOX_EDGE)->set_usize(400,30) ../images/gtk_hbuttonbox_3.png

GTK.HbuttonBox()->add(GTK.Button("Hello"))->add(GTK.Button("World"))->set_layout(GTK.BUTTONBOX_START)->set_usize(400,30) ../images/gtk_hbuttonbox_4.png

GTK.HbuttonBox()->add(GTK.Button("Hello"))->add(GTK.Button("World"))->set_layout(GTK.BUTTONBOX_END)->set_usize(400,30) ../images/gtk_hbuttonbox_5.png

GTK.ButtonBox

Create a new horizontal button box

GTK.HbuttonBox

This class is deprecated.

Return the first child

GTK.CTreeNode

Return 1 if the node is expanded

Return 1 if the node is a leaf node

Return the level of this node (0 for root, 1 for a child of the root, etc)

Return the parent node of this node

GTK.CTreeNode

The drawing area is a window you can draw in. Please note that you must handle refresh and resize events on your own. Use W(pDrawingArea) for a drawingarea with automatic refresh/resize handling. GTK.DrawingArea()->set_usize(100,100) ../images/gtk_drawingarea.png

GTK.Widget

Either clears the rectangle defined by the arguments, of if no arguments are specified, the whole drawable.

GTK.DrawingArea

Copies the rectangle defined by xsource,ysource and width,height from the source drawable, and places the results at xdest,ydest in the drawable in which this function is called.

GDK.GC
GTK.Widget
GTK.DrawingArea
GTK.DrawingArea

Draws a single circular or elliptical arc. Each arc is specified by a rectangle and two angles. The center of the circle or ellipse is the center of the rectangle, and the major and minor axes are specified by the width and height. Positive angles indicate counterclockwise motion, and negative angles indicate clockwise motion. If the magnitude of angle2 is greater than 360 degrees, it is truncated to 360 degrees.

GDK.GC
GTK.DrawingArea

Draw a GDK(Bitmap) in this drawable. NOTE: This drawable must be a bitmap as well. This will be fixed in GTK 1.3

GDK.GC
GDK.Bitmap
GTK.DrawingArea

Draw the rectangle specified by xsrc,ysrc+width,height from the GDK(Image) at xdest,ydest in the destination drawable

GDK.GC
GDK.Image
GTK.DrawingArea

img_begin w = GTK.DrawingArea()->set_usize(100,100); delay: g = GDK.GC(w)->set_foreground( GDK.Color(255,0,0) ); delay: for(int x = 0; x<10; x++) w->draw_line(g,x*10,0,100-x*10,99); img_end

GDK.GC
GTK.DrawingArea

Draw the rectangle specified by xsrc,ysrc+width,height from the GDK(Pixmap) at xdest,ydest in the destination drawable

GDK.GC
GDK.Pixmap
GTK.DrawingArea

img_begin w = GTK.DrawingArea()->set_usize(10,10); delay: g = GDK.GC(w)->set_foreground( GDK.Color(255,0,0) ); delay: for(int x = 0; x<10; x++) w->draw_point(g, x, x); img_end

GDK.GC
GTK.DrawingArea

img_begin w = GTK.DrawingArea()->set_usize(100,100); delay: g = GDK.GC(w)->set_foreground( GDK.Color(255,0,0) ); delay: for(int x = 0; x<10; x++) w->draw_rectangle(g,0,x*10,0,100-x*10,99); img_end img_begin w = GTK.DrawingArea()->set_usize(100,100); delay: g = GDK.GC(w); delay: for(int x = 0; x<30; x++) { delay: g->set_foreground(GDK.Color(random(255),random(255),random(255)) ); delay: w->draw_rectangle(g,1,x*10,0,100-x*10,99); delay: } img_end

GDK.GC
GTK.DrawingArea

y is used as the baseline for the text. If forcewide is true, the string will be expanded to a wide string even if it is not already one. This is useful when writing text using either unicode or some other 16 bit font.

GDK.GC
GDK.Font
GTK.DrawingArea

This function is OBSOLETE

GTK.DrawingArea
GTK.Container
GTK.Adjustment
GTK.Adjustment
GTK.Layout
GTK.Layout
GTK.Adjustment
GTK.Adjustment
GTK.Widget
GTK.Layout
GTK.Widget
GTK.Layout
GTK.Adjustment
GTK.Layout
GTK.Layout
GTK.Adjustment
GTK.Layout
GTK.Layout

A simple progress bar. Useful when you are doing things that take a long time. Try to always have an 'abort' button whenever it makes sence. GTK.ProgressBar()->update(0.1) ../images/gtk_progressbar.png

GTK.ProgressBar()->set_show_text(1)->update(0.3) ../images/gtk_progressbar_2.png

GTK.ProgressBar()->update(0.6) ../images/gtk_progressbar_3.png

GTK.ProgressBar()->update(1.0) ../images/gtk_progressbar_4.png

GTK.Progress

Create a new progress bar. The default values are: Min 0.0, max 1.0, current 0.0

GTK.ProgressBar

The number of blocks that are set.

The current direction of the progress meter. 1 is forward and 0 is backwards. Usefull if you for some strange reason would like to know in what direction the activity indicator is swinging right now...

The position of the progress meter in pixels.

The step size of the activity indicator in pixels.

The progress bar style. GTK_PROGRESS_CONTINUOUS or GTK_PROGRESS_DISCRETE.

The total number of blocks.

The current orientation. GTK_PROGRESS_LEFT_TO_RIGHT, GTK_PROGRESS_RIGHT_TO_LEFT, GTK_PROGRESS_BOTTOM_TO_TOP or GTK_PROGRESS_TOP_TO_BOTTOM.

The number of activity blocks

GTK.ProgressBar

Include activity blocks (empty gaps in the progressbar, ala windows 98)

GTK.ProgressBar

One of GTK.ProgressContinuous or GTK.ProgressDiscrete

GTK.ProgressBar

The number of discrete blocks in the progress bar

GTK.ProgressBar

One of GTK.ProgressLeftToRight, GTK.ProgressRightToLeft, GTK.ProgressBottomToTop or GTK.ProgressTopToBottom

GTK.ProgressBar

0.0 is the minimum value, 1.0 is the maximum value.

GTK.ProgressBar

The GtkClock widget provides an easy way of providing a textual clock in your application. It supports realtime display, as well as count up and count down modes. The clock widget could conceivably be used in such applications as an application's status bar, or as the basis for a panel applet, etc.

Three modes of operation are supported. These are realtime - which displays the current time, count-up/increasing - which counts up from an initial value (like a stopwatch), and count-down/decreasing - which counts down from an initial value.

Note, however, that the accuracy of the gtkclock widget is limited to 1 second. GTK.Clock( GTK.ClockRealtime ); ../images/gtk_clock.png

GTK.Clock( GTK.ClockDecreasing )->set_seconds(10000)->start(); ../images/gtk_clock_2.png

GTK.Label

type is one of CLOCK_DECREASING, CLOCK_INCREASING and CLOCK_REALTIME;

GTK.Clock

Set the format of a GtkClock widget. The syntax of the format string is identical to that of the function strftime(3). Further information about time format strings can be found on this man page. The widget defaults to a format string of "%H:%M" in realtime mode, or "%H:%M:%S" in count-up or count-down modes.

GTK.Clock

Set the current time as displayed by the clock in count-up and count-down modes. This function has no effect in realtime mode, as the clock time is determined by the system clock in realtime mode.

GTK.Clock

Set the interval at which the GtkClock widget is updated. The seconds parameter is used to determine how often the time shown on the widget is updated. The default value is to update every second, but you may wish to increase this value. If you set the update interval to 0, the clock is never updated.

GTK.Clock

Start the clock counting in count-up or count-down modes. The clock will begin counting up or down from the time when this function is called, until gtk_clock_stop is called. This function has no effect in the realtime mode (you can't start and stop real time! :-).

GTK.Clock

Stop the clock counting in count-up or count-down modes. The clock ceases counting up or down, and the last time reached remains on the display. This function has no effect in the realtime mode (you can't start and stop real time! :-).

GTK.Clock

Toolbars are usually used to group some number of widgets in order to simplify customization of their look and layout. Typically a toolbar consists of buttons with icons, labels and tooltips, but any other widget can also be put inside a toolbar. Finally, items can be arranged horizontally or vertically and buttons can be displayed with icons, labels, or both.

Examples: lambda(){object t=GTK.Toolbar( GTK.ORIENTATION_HORIZONTAL, GTK.TOOLBAR_TEXT );t->append_item( "Button 1", "Tooltip 1", "", GTK.Frame(), lambda(){},0);t->append_space();t->append_item( "Button 2", "Tooltip 2", "", GTK.Frame(), lambda(){},0);t->append_item( "Button 3", "Tooltip 3", "", GTK.Frame(), lambda(){},0);t->append_space();t->append_item( "Button 4", "Tooltip 4", "", GTK.Frame(), lambda(){},0);t->append_item( "Button 5", "Tooltip 5", "", GTK.Frame(), lambda(){},0);return t;}() ../images/gtk_toolbar.png

lambda(){object t=GTK.Toolbar( GTK.ORIENTATION_VERTICAL, GTK.TOOLBAR_TEXT );t->append_item( "Button 1", "Tooltip 1", "", GTK.Frame(), lambda(){},0);t->append_space();t->append_item( "Button 2", "Tooltip 2", "", GTK.Frame(), lambda(){},0);t->append_item( "Button 3", "Tooltip 3", "", GTK.Frame(), lambda(){},0);t->append_space();t->append_item( "Button 4", "Tooltip 4", "", GTK.Frame(), lambda(){},0);t->append_item( "Button 5", "Tooltip 5", "", GTK.Frame(), lambda(){},0);return t;}() ../images/gtk_toolbar_2.png

lambda(){object i=GDK.Image()->set(Image.image(20,20)->test());object t=GTK.Toolbar( GTK.ORIENTATION_HORIZONTAL, GTK.TOOLBAR_BOTH );t->append_item( "Button 1", "Tooltip 1", "", GTK.Image(i), lambda(){},0);t->append_space();t->append_item( "Button 2", "Tooltip 2", "", GTK.Image(i), lambda(){},0);t->append_item( "Button 3", "Tooltip 3", "", GTK.Image(i), lambda(){},0);t->append_space();t->append_item( "Button 4", "Tooltip 4", "", GTK.Image(i), lambda(){},0);t->append_item( "Button 5", "Tooltip 5", "", GTK.Image(i), lambda(){},0);return t;}() ../images/gtk_toolbar_3.png

Signals: orientation_changed

style_changed

GTK.Container

Adds a new button to the start of the toolbar.

GTK.Widget
``
GTK.Toolbar

Adds a small space.

GTK.Toolbar

Append a custom widgets. Arguments are widget, tooltip, private

GTK.Widget
GTK.Toolbar

Orientation is one of ORIENTATION_HORIZONTAL and ORIENTATION_VERTICAL. Style is one of TOOLBAR_BOTH, TOOLBAR_ICONS and TOOLBAR_TEXT

GTK.Toolbar

Arguments as for append_item, but an extra position argument at the end. Adds a new button after the item at the specified position.

GTK.Widget
``
GTK.Toolbar

Inserts a small space at the specified postion.

GTK.Toolbar

Insert a custom widgets.

GTK.Widget
GTK.Toolbar

Arguments as for append_item Adds a new button to the end of the toolbar.

GTK.Widget
``
GTK.Toolbar

Adds a small space.

GTK.Toolbar

Prepend a custom widgets. Arguments are widget, tooltip, private

GTK.Widget
GTK.Toolbar
GTK.Toolbar

Set the orientation, one of ORIENTATION_HORIZONTAL and ORIENTATION_VERTICAL

GTK.Toolbar

Set the width (or height) of the space created by append_space.

GTK.Toolbar
GTK.Toolbar

Set the style, one of TOOLBAR_BOTH, TOOLBAR_ICONS and TOOLBAR_TEXT

GTK.Toolbar

If true, show the tooltips.

GTK.Toolbar

A OptionMenu is a widget that allows the user to choose from a list of valid choices. The OptionMenu displays the selected choice. When activated the OptionMenu displays a popup W(Menu) which allows the user to make a new choice.

GTK.OptionMenu()->set_menu(GTK.Menu()->add( GTK.Menu_item("Option 1") )); ../images/gtk_optionmenu.png

GTK.Button

Create a new option menu widget

GTK.OptionMenu

Returns the W(Menu) associated with the OptionMenu.

GTK.Menu

Remove the menu.

GTK.OptionMenu

Selects the menu item specified by index making it the newly selected value for the option menu.

GTK.OptionMenu

Provides the GtkMenu that is popped up to allow the user to choose a new value. You should provide a simple menu avoiding the use of tearoff menu items, submenus, and accelerators.

GTK.Menu
GTK.OptionMenu

The GtkCList widget is a multi-column list widget that is capable of handling literally thousands of rows of information. Each column can optionally have a title, which itself is optionally active, allowing us to bind a function to it's selection. GTK.Clist(2)->set_column_title(0,"Col 1")->set_column_title(1,"Col 2")->column_titles_show()->set_column_width(0,50)->set_usize(150,70) ../images/gtk_clist.png

Signals: abort_column_resize

click_column Called when a column is clicked

end_selection

extend_selection

resize_column Called when a column is resized

scroll_horizontal

scroll_vertical

select_all

select_row Called when a row is selected

start_selection

toggle_add_mode

toggle_focus_row

undo_selection

unselect_all

unselect_row Called when a row is deselected

GTK.Container

The return value of indicates the index of the row that was just added.

'columns' are the texts we want to put in the columns. The size of the array should equal the number of columns in the list.

remove all rows

GTK.Clist

Make a specific column title active

GTK.Clist

Make a specific column title passive

GTK.Clist

The column titles can be pressed

GTK.Clist

Hide the column titles

GTK.Clist

The column titles can't be pressed

GTK.Clist

Show the column titles.

GTK.Clist

Resize all columns according to their contents

Create a new empty clist, columns columns wide.

Not all columns have to be visible, some can be used to store data that is related to a certain cell in the list.

GTK.Clist

Find a row in the list that has the given user data. If no node is found, -1 is returned.

freeze all visual updates of the list, and then thaw the list after you have made a number of changes and the updates wil occure in a more efficent mannor than if you made them on a unfrozen list

GTK.Clist

Return the background color of a specified row

GDK.Color

return the W(Style) associated with a specific cell

GTK.Style

Return value is one of CELL_EMPTY, CELL_PIXMAP, CELL_PIXTEXT, CELL_TEXT and CELL_WIDGET

Returns the title of a specified column.

Return the widget for the specified column title

GTK.Widget

Return the number of columns in this clist

Return the button used to drag items (by default 1)

Return the flags. A bitwise or of CLIST_ADD_MODE, CLIST_AUTO_RESIZE_BLOCKED, CLIST_AUTO_SORT, CLIST_DRAW_DRAG_LINE, CLIST_DRAW_DRAG_RECT, CLIST_IN_DRAG, CLIST_REORDERABLE, CLIST_ROW_HEIGHT_SET, CLIST_SHOW_TITLES and CLIST_USE_DRAG_ICONS

The currently focused row

Return the foregroun color for the specified row

GDK.Color

Return the W(Adjustment) object used for horizontal scrolling

GTK.Adjustment

Return the pixmap for the specified cell

GTK.Clist

Return the pixmap and text for the specified cell as a mapping: ([ "spacing":spacing, "text":text, "pixmap":pixmap ])

Return the data associated with a row, or 0.

Return the height of the row

Return the W(style) object associated with the specified row

GTK.Style

Return the number of rows

Return 1 if the specified row can be selected by the user.

Return an array with all selected rows.

Return the row column corresponding to the x and y coordinates, the returned values are only valid if the x and y coordinates are relative to the clist window coordinates

Return the selection mode. One of SELECTION_BROWSE, SELECTION_EXTENDED, SELECTION_MULTIPLE and SELECTION_SINGLE

Return the curreent shadow type. One of SHADOW_ETCHED_IN, SHADOW_ETCHED_OUT, SHADOW_IN, SHADOW_NONE and SHADOW_OUT

The column that will be used to sort the rows

The sort method, one of SORT_ASCENDING and SORT_DESCENDING

Return the text associated with a specific cell.

GTK.Clist

Return the W(Adjustment) object used for vertical scrolling

GTK.Adjustment

Insert a row after a specified row. The return value of indicates the index of the row that was just added, please note that this is not nessasarily the same row as the specified one, if autosort is activated, the row will be inserted so that the list is sill sorted.

'columns' are the texts we want to put in the columns. The size of the array should equal the number of columns in the list.

Make the specified row and column visible, and place it relative to xpos and ypos in the area the Clist occupies. xpos and ypos are relative, 0.0 == top, 1.0 == bottom

GTK.Clist

Return the optimal width of the specified column

The return value of indicates the index of the row that was just added.

'columns' are the texts we want to put in the columns. The size of the array should equal the number of columns in the list.

Delete a specified row. If you want to remove all rows in a Clist, use 'clear()' instead of calling remove multiple times.

GTK.Clist

Move the specified row to just before the specified destination row.

GTK.Clist

Select all rows

GTK.Clist

Select the given row. The column is sent to the signal handler, but ignored for all other purposes.

GTK.Clist

If true, the clist will automatically be re-sorted when new rows are inserted. Please note that it will not be resorted if the text in cells are changed, use 'sort()' to force a reorder. The sort function is stable.

GTK.Clist

Set the background color of the specified row the the specified color

GDK.Color
GTK.Clist

Action is a bitwise or of BUTTONBOX_DEFAULT_STYLE, BUTTONBOX_EDGE, BUTTONBOX_END, BUTTONBOX_SPREAD, BUTTONBOX_START, BUTTON_DRAGS, BUTTON_EXPANDS, BUTTON_IGNORED and BUTTON_SELECTS Button is the mouse button (normally 1-3, 4 and 5 sometimes beeing scroll wheel up and scroll wheel down)

GTK.Clist

Set a W(Style) for a specific cell

GTK.Style
GTK.Clist

Automatically resize a column to the width of it's widest contents.

GTK.Clist

justification is one of JUSTIFY_CENTER, JUSTIFY_FILL, JUSTIFY_LEFT and JUSTIFY_RIGHT

GTK.Clist

if width 6lt; 0 , there is no restriction

GTK.Clist

Width in pixels

GTK.Clist

Make a column resizable, or remove it's the resizability.

GTK.Clist

Set the column title of a specified column. It is a good idea to set the titles before the column title buttons are shown.

GTK.Clist

Hide or show a column

GTK.Clist

Put a widget as a column title. The widget will be added to a W(Button).

GTK.Widget
GTK.Clist

Width in pixels

GTK.Clist

Set the compare function. The function will be called with a mapping as it's only argument, like this:

       ([
          "clist":the clist widget,
          "sort_column":the column to sort on,
          "row1_data":The user data pointer for the first row,
          "row2_data":The user data pointer for the second row,
          "row1_text":The text in the sort cell in the first row
          "row2_text":The text in the sort cell in the second row
       ])

The return value is one of: 1: Row 1 is more than row 2 0: The rows are equal -1: Row 1 is lesser than row 2 To remove the comparefunction, use 0 as the argument.
``
GTK.Clist

Set the foreground color of the specified row to the specified color

GDK.Color
GTK.Clist

Set the W(Adjustment) object used for horizontal scrolling

GTK.Adjustment
GTK.Clist

Set the pixmap of the specified cell. The mask is optional

GDK.Pixmap
GDK.Bitmap
GTK.Clist

Set the pixmap and text of the specified cell. The mask is optional The spacing is the number of pixels between the pixmap and the text.

GDK.Pixmap
GDK.Bitmap
GTK.Clist

If true, the user can drag around the rows in the list.

GTK.Clist

Set the user data associated with the specified row. This data can be used to find rows, and when a row is selected it can be easily retrieved using node_get_row_data.

You can only use objects as row data right now

GTK.Clist

in pixels

GTK.Clist
GTK.Style
GTK.Clist

If true, the row can be selected by the user, otherwise it cannot be selected, only focused.

GTK.Clist

One of SELECTION_BROWSE, SELECTION_EXTENDED, SELECTION_MULTIPLE and SELECTION_SINGLE

GTK.Clist

One of SHADOW_ETCHED_IN, SHADOW_ETCHED_OUT, SHADOW_IN, SHADOW_NONE and SHADOW_OUT

GTK.Clist

The contents of the specified cell will be drawn shifted (indented) the specifid number of pixels.

This can be useful to generate a tree-like layout when you do not want to make a W(Ctree)

GTK.Clist
GTK.Clist

Ascending or descending (One of SORT_ASCENDING and SORT_DESCENDING)

GTK.Clist

Set the text for the specified cell. Please note that even if auto sorting is enabled, the row will not be resorted. Use the 'sort()' function.

GTK.Clist

If true, hard coded drag icons will be used.

GTK.Clist

Set the W(Adjustment) object used for vertical scrolling

GTK.Adjustment
GTK.Clist

Set the column on which all sorting will be performed

GTK.Clist

freeze all visual updates of the list, and then thaw the list after you have made a number of changes and the updates wil occure in a more efficent mannor than if you made them on a unfrozen list

GTK.Clist

Undo the previous selection

GTK.Clist

Unselect all rows

GTK.Clist

Unselect the given row. The column is sent to the signal handler, but ignored for all other purposes.

GTK.Clist

This class is inherited by all 'item' type of widgets.

Signals: delselect

select

toggle

GTK.Bin

Emulate a 'deselect' event.

GTK.Item

Emulate a 'select' event.

GTK.Item

Emulate a 'toggle' event.

GTK.Item

The paned window widgets are useful when you want to divide an area into two parts, with the relative size of the two parts controlled by the user. A groove is drawn between the two portions with a handle that the user can drag to change the ratio. This widgets makes a vertical division

GTK.Vpaned()->add1(GTK.Label("Top Side Of Pane"))->add2(GTK.Label("Bottom"))->set_usize(100,100) ../images/gtk_vpaned.png

GTK.Paned
GTK.Vpaned

Radio buttons are similar to check buttons except they are grouped so that only one may be selected/depressed at a time. This is good for places in your application where you need to select from a short list of options. To connect the buttons, use another button in the desired group as the second argument to GTK.RadioButton().

GTK.Radio_button("Button"); ../images/gtk_radiobutton.png

GTK.CheckButton

Normal creation: object GTK.RadioButton(string title) - First button (with label) object GTK.RadioButton()->add(widget) - First button (with widget) object GTK.RadioButton(title, another_radio_button) - Second to n:th button (with title) object GTK.RadioButton(0,another_radio_button)->add(widget) - Second to n:th button (with widget)

GTK.RadioButton
GTK.RadioButton

the argument is another radio button to whose group this button should be added to. It is prefereable to use the second argument to the constructor instead, but if you for some reason want to move the button to another group, use this function.

GTK.RadioButton
GTK.RadioButton

GTK.FontSelection() ../images/gtk_fontselection.png

GTK.Notebook
GTK.FontSelection
GDK.Font

This sets the currently displayed font. It should be a valid X Logical Font Description font name (anything else will be ignored), e.g. "-adobe-courier-bold-o-normal--25-*-*-*-*-*-*-*"

GTK.FontSelection
GTK.FontSelection

A horizontal scrollbar. General documentation: See W(Scrollbar) GTK.Hscrollbar(GTK.Adjustment())->set_usize(300,15) ../images/gtk_hscrollbar.png

GTK.Scrollbar

Used to create a new vscale widget. The adjustment argument can either be an existing W(Adjustment), or 0, in which case one will be created for you. Specifying 0 might actually be useful in this case, if you wish to pass the newly automatically created adjustment to the constructor function of some other widget which will configure it for you, such as a text widget.

GTK.Adjustment
GTK.Hscrollbar

Exactly like W(RadioButton), but it is an menu item. GTK.RadioMenuItem("Menu item") ../images/gtk_radiomenuitem.png

GTK.MenuItem

object GTK.RadioMenuItem(string title) - First button (with label) object GTK.RadioMenuItem()->add(widget) - First button (with widget) object GTK.RadioMenuItem(title, another_radio_button) - Second to n:th button (with title) object GTK.RadioMenuItem(0,another_radio_button)->add(widget) - Second to n:th button (with widget)

GTK.RadioMenuItem
GTK.RadioMenuItem

the argument is another radio menu item to whose group this button should be added to. It is prefereable to use the second argument to the constructor instead, but if you for some reason want to move the button to another group, use this function.

GTK.RadioMenuItem
GTK.RadioMenuItem
GTK.Container

side is one of SIDE_BOTTOM, SIDE_LEFT, SIDE_RIGHT and SIDE_TOP, anchor is one of ANCHOR_CENTER, ANCHOR_E, ANCHOR_EAST, ANCHOR_N, ANCHOR_NE, ANCHOR_NORTH, ANCHOR_NORTH_EAST, ANCHOR_NORTH_WEST, ANCHOR_NW, ANCHOR_S, ANCHOR_SE, ANCHOR_SOUTH, ANCHOR_SOUTH_EAST, ANCHOR_SOUTH_WEST, ANCHOR_SW, ANCHOR_W and ANCHOR_WEST, options is a bitwise or of GTK.PackExpand, GTK.FillX and GTK.FillY

GTK.Widget
GTK.Packer

side is one of SIDE_BOTTOM, SIDE_LEFT, SIDE_RIGHT and SIDE_TOP, anchor is one of ANCHOR_CENTER, ANCHOR_E, ANCHOR_EAST, ANCHOR_N, ANCHOR_NE, ANCHOR_NORTH, ANCHOR_NORTH_EAST, ANCHOR_NORTH_WEST, ANCHOR_NW, ANCHOR_S, ANCHOR_SE, ANCHOR_SOUTH, ANCHOR_SOUTH_EAST, ANCHOR_SOUTH_WEST, ANCHOR_SW, ANCHOR_W and ANCHOR_WEST, options is a bitwise or of GTK.PackExpand, GTK.FillX and GTK.FillY

GTK.Widget
GTK.Packer
GTK.Packer
GTK.Widget
GTK.Packer

side is one of SIDE_BOTTOM, SIDE_LEFT, SIDE_RIGHT and SIDE_TOP, anchor is one of ANCHOR_CENTER, ANCHOR_E, ANCHOR_EAST, ANCHOR_N, ANCHOR_NE, ANCHOR_NORTH, ANCHOR_NORTH_EAST, ANCHOR_NORTH_WEST, ANCHOR_NW, ANCHOR_S, ANCHOR_SE, ANCHOR_SOUTH, ANCHOR_SOUTH_EAST, ANCHOR_SOUTH_WEST, ANCHOR_SW, ANCHOR_W and ANCHOR_WEST, options is a bitwise or of GTK.PackExpand, GTK.FillX and GTK.FillY

GTK.Widget
GTK.Packer
GTK.Packer
GTK.Packer
GTK.Packer
GTK.Packer

A W(Frame) widget that always maintain a specified ratio between width and height. width/height == ratio

GTK.Aspect_frame("Title",0.5,0.5,0.4,0)->add( GTK.Label("Wrong aspect"))->set_usize(200,200) ../images/gtk_aspectframe.png

GTK.Frame

Create a new frame. Arguments are label, xalign, yalign, ratio, obey_child xalign is floats between 0 and 1, 0.0 is upper (or leftmost), 1.0 is lower (or rightmost). If 'obey_child' is true, the frame will use the aspect ratio of it's (one and only) child widget instead of 'ratio'.

GTK.AspectFrame

Set the aspec values. Arguments are xalign, yalign, ratio, obey_child xalign is floats between 0 and 1, 0.0 is upper (or leftmost), 1.0 is lower (or rightmost). If 'obey_child' is true, the frame will use the aspect ratio of it's (one and only) child widget instead of 'ratio'.

GTK.AspectFrame

Glade is a free GUI builder for GTK+ and Gnome. It's normally used to create C-code, but can also produce code for other languages. Libglade is a utility library that builds the GUI from the Glade XML save files. This module uses libglade and allows you to easily make GUI designs to be used with your Pike applications. Since PiGTK doesn't support Gnome yet, you can only use the normal GTK widgets.

This function is used to get get the widget corresponding to name in the interface description. You would use this if you have to do anything to the widget after loading.

GTK.Widget

This function is used to get the widget corresponding to long_name in the interface description. You would use this if you have to do anything to the widget after loading. This function differs from GladeXML->get_widget, in that you have to give the long form of the widget name, with all its parent widget names, separated by periods.

GTK.Widget

Used to get the long name of a widget that was generated by a GladeXML object.

GTK.Widget

Used to get the name of a widget that was generated by a GladeXML object.

GTK.Widget

Creates a new GladeXML object (and the corresponding widgets) from the XML file filename. Optionally it will only build the interface from the widget node root. This feature is useful if you only want to build say a toolbar or menu from the XML file, but not the window it is embedded in. Note also that the XML parse tree is cached to speed up creating another GladeXML object for the same file. The third optional argument is used to specify a different translation domain from the default to be used.

GTK.GladeXML

Creates a new GladeXML object (and the corresponding widgets) from the string data. Optionally it will only build the interface from the widget node root. This feature is useful if you only want to build say a toolbar or menu from the XML document, but not the window it is embedded in. The third optional argument is used to specify a different translation domain from the default to be used.

GTK.GladeXML

Try to connect functions to all signals in the interface. The mapping should consist of handler name : function pairs. The data argument will be saved and sent as the first argument to all callback functions.

GTK.GladeXML

Try to connect functions to all signals in the interface. The mapping should consist of handler name : function pairs. This function differs from the signal_connect function in how it calls the callback function.

The old interface:

       void signal_handler( mixed data, GTK.Object object,
                            mixed ... signal_arguments )

The new interface:

       void signal_handler( mixed ... signal_arguments,
                            mixed data, GTK.Object object )

GTK.GladeXML

The Gtk.Table allow the programmer to arrange widgets in rows and columns, making it easy to align many widgets next to each other, horizontally and vertically.

GTK.Table(2,2,0)->attach_defaults( GTK.Label("0,0"), 0, 1, 0, 1)->attach_defaults( GTK.Label("0,1"), 0, 1, 1, 2)->attach_defaults( GTK.Label("1,0"), 1, 2, 0, 1)->attach_defaults( GTK.Label("1,1"), 1, 2, 1, 2)->set_col_spacings(10)->set_row_spacings(10) ../images/gtk_table.png

GTK.Table(2,2,0)->attach_defaults( GTK.Label("0,0-1,0"), 0, 2, 0, 1)->attach_defaults( GTK.Label("0,1"), 0, 1, 1, 2)->attach_defaults( GTK.Label("1,1"), 1, 2, 1, 2)->set_col_spacings(10)->set_row_spacings(10) ../images/gtk_table_2.png

GTK.Container

The left and right attach arguments specify where to place the widget, and how many boxes to use. If you want a button in the lower right table entry of our 2x2 table, and want it to fill that entry ONLY. left_attach would be = 1, right_attach = 2, top_attach = 1, bottom_attach = 2.

Now, if you wanted a widget to take up the whole top row of our 2x2 table, you'd use left_attach = 0, right_attach = 2, top_attach = 0, bottom_attach = 1.

The xoptions and yoptions are used to specify packing options and may be OR'ed together to allow multiple options.

These options are: <ul> <li> GTK.Fill - If the table box is larger than the widget, and GTK_FILL is specified, the widget will expand to use all the room available.</li> <li> GTK.Shrink - If the table widget was allocated less space then was requested (usually by the user resizing the window), then the widgets would normally just be pushed off the bottom of the window and disappear. If GTK_SHRINK is specified, the widgets will shrink with the table.</li> <li> GTK.Expand - This will cause the table cell to expand to use up any remaining space in the window.</li> </ul>

Padding is just like in boxes, creating a clear area around the widget specified in pixels

GTK.Widget
GTK.Table

As there are many options associated with attach(), this convenience function provides the programmer with a means to add children to a table with identical padding and expansion options.

xoptions, yoptions, xpadding and ypadding are all set the their default values. For the options that is GTK.Fill|GTK.Expand. For the padding it is 0.

GTK.Widget
GTK.Table

Used to create a new table widget. An initial size must be given by specifying how many rows and columns the table should have, although this can be changed later with resize().

There can never be more than 65535 colums nor more than 65535 rows.

setting homogeneousp to 1 forces the all tablecells to be exactly the same size.

GTK.Table

The spacing between all columns, in pixels.

If 1, all cells have exactly the same size

The number of columns. Between 1 and 65535.

The number of rows. Between 1 and 65535.

The spacing between all rows, in pixels.

If you need to change a table's size after it has been created, this function allows you to do so.

GTK.Table

alters the amount of space between a given table column and the adjacent columns.

GTK.Table

Sets the space between every column in the table equal to spacing.

GTK.Table

Set the homogeneous flag.

GTK.Table

alters the amount of space between a given table row and the adjacent rows.

GTK.Table

Sets the space between every row in the table equal to spacing.

GTK.Table

A generic separator. Basicaly a line, like &lt;hr&gt; in HTML.

GTK.Widget

Scrolled windows are used to create a scrollable area with another widget inside it. You may insert any type of widget into a scrolled window, and it will be accessible regardless of the size by using the scrollbars.

GTK.ScrolledWindow(GTK.Adjustment(),GTK.Adjustment())->add(GTK.Label("A small label"))->set_usize(100,80)->set_policy(GTK.POLICY_AUTOMATIC,GTK.POLICY_AUTOMATIC) ../images/gtk_scrolledwindow.png

GTK.ScrolledWindow(GTK.Adjustment(),GTK.Adjustment())->add(GTK.Label("A small label"))->set_usize(70,80)->set_policy(GTK.POLICY_AUTOMATIC,GTK.POLICY_AUTOMATIC) ../images/gtk_scrolledwindow_2.png

GTK.ScrolledWindow(GTK.Adjustment(),GTK.Adjustment())->add(GTK.Label("A small label"))->set_usize(80,80) ../images/gtk_scrolledwindow_3.png

GTK.ScrolledWindow(GTK.Adjustment(),GTK.Adjustment())->add(GTK.Label("A very huge label")->set_usize(700,700))->set_usize(80,80) ../images/gtk_scrolledwindow_4.png

GTK.Window

Add a widget to this container. This is equivalent to the C-GTK function gtk_scrolled_window_add_with_viewport or gtk_container_add, depeneding on whether or not the child supports the set_scroll_adjustments signal.

What this means in practice is that you do not have to care about this at all, it's all handled automatically.

GTK.Widget
GTK.ScrolledWindow

The two adjustments are most commonly set to 0.

GTK.Adjustment
GTK.Adjustment
GTK.ScrolledWindow

Return the horizontal adjustment used to scroll the window

GTK.Adjustment

The horizontal scrollbar

GTK.Hscrollbar

One of POLICY_ALWAYS, POLICY_AUTOMATIC and POLICY_NEVER

1 if the horizontal scrollbar is currently visible

Return the vertical adjustment used to scroll the window

GTK.Adjustment

The vertical scrollbar

GTK.Vscrollbar

One of POLICY_ALWAYS, POLICY_AUTOMATIC and POLICY_NEVER

1 if the vertical scrollbar is currently visible

The location of the window relative to the scrollbars. One of CORNER_BOTTOM_LEFT, CORNER_BOTTOM_RIGHT, CORNER_TOP_LEFT and CORNER_TOP_RIGHT

Set the horizontal adjustment object

GTK.Adjustment
GTK.ScrolledWindow

The location of the window relative to the scrollbars. One of CORNER_BOTTOM_LEFT, CORNER_BOTTOM_RIGHT, CORNER_TOP_LEFT and CORNER_TOP_RIGHT

GTK.ScrolledWindow

vertical and horiz policy. Both are one of POLICY_ALWAYS, POLICY_AUTOMATIC and POLICY_NEVER

GTK.ScrolledWindow

Set the vertical adjustment object

GTK.Adjustment
GTK.ScrolledWindow

a GTK.TearoffMenuItem is a special W(MenuItem) which is used to tear off and reattach its menu.

When its menu is shown normally, the GTK.TearoffMenuItem is drawn as a dotted line indicating that the menu can be torn off. Activating it causes its menu to be torn off and displayed in its own window as a tearoff menu.

When its menu is shown as a tearoff menu, the GTK.TearoffMenuItem is drawn as a dotted line which has a left pointing arrow graphic indicating that the tearoff menu can be reattached. Activating it will erase the tearoff menu window. GTK.TearoffMenuItem()->set_usize( 100,0 ) ../images/gtk_tearoffmenuitem.png

GTK.MenuItem

Create a new tear of menu item

GTK.TearoffMenuItem

Return 1 if the menu the menu item is connected to is currently torn off.

The GtkCTree widget is used for showing a hierarchical tree to the user, for example a directory tree.

The tree is internally represented as a set of GtkCTreeNode structures.

The interface has much in common with the GtkCList widget: rows (nodes) can be selected by the user etc.

Positions in the tree are often indicated by two arguments, a parent and a sibling, both GtkCTreeNode pointers. If the parent is NULL, the position is at the root of the tree and if the sibling is NULL, it will be the last child of parent, otherwise it will be inserted just before the sibling.

Signals: change_focus_row_expansion Changed when the focused row is either expanded or collapsed

tree_collapse Called when a node is collapsed

tree_expand Called when a node is expanded

tree_move Called when a node is moved (using DND, as an example)

tree_select_row Called when a node is selected.

tree_unselect_row Called when a node is unselected.

GTK.Clist

Collapse the node, hiding it's children. If no node is given, expand the toplevel of the tree

GTK.CTreeNode
GTK.Ctree

Collapse the node, showing it's children, it's childrens children, etc. If no node is given, collapse the whole tree

GTK.CTreeNode
GTK.Ctree

Collapse depth levels of the tree, starting with the specified node. If no node is given, start with the toplevel node.

GTK.CTreeNode
GTK.Ctree

tree_column is the column that has the tree graphics (lines and expander buttons).

GTK.Ctree

Expand the node, showing it's children. If no node is given, expand the toplevel of the tree

GTK.CTreeNode
GTK.Ctree

Expand the node, showing it's children, it's childrens children, etc. If no node is given, expand the whole tree

GTK.CTreeNode
GTK.Ctree

Expand depth levels of the tree, starting with the specified node. If no node is given, start with the toplevel node.

GTK.CTreeNode
GTK.Ctree

Returns true if the node is a child of the start node.

If you omit the starting node, the tree will be searched from the root.

GTK.CTreeNode
GTK.CTreeNode

Find a node in the tree starting with root, that has the given user data. If no node is found, 0 is returned.

CTreeNode
GTK.Ctree

Given a W(CTreeRow) (deprectated structure in PiGTK), return the W(CTreeNode) associated with the row.

GTK.CTreeRow
GTK.CTreeNode

The style of the expander buttons, one of CTREE_EXPANDER_CIRCULAR, CTREE_EXPANDER_NONE, CTREE_EXPANDER_SQUARE and CTREE_EXPANDER_TRIANGLE

The style of the lines, one of CTREE_LINES_DOTTED, CTREE_LINES_NONE, CTREE_LINES_SOLID and CTREE_LINES_TABBED

Will stubs be shows?

The column that is the tree column (the one with the expand/collapse icons)

The number of pixels to indent the tree levels.

The number of pixels between the tree and the columns

At least one of parent or sibling must be specified. If both are specified, sibling->parent() must be equal to parent.

If the parent and sibling is 0, the position is at the root of the tree, if the sibling is NULL, it will be the last child of parent, otherwise it will be inserted just before the sibling.

GTK.CTreeNode
GTK.CTreeNode
GTK.Ctree

Returns true if node is an ancestor of child

GTK.CTreeNode
GTK.CTreeNode

Returns true if the given coordinates lie on an expander button

Returns 1 if a certain node can be viewed (with or without scrolling of the tree). Returns 0 if the node is in a folded part of the tree.

GTK.CTreeNode

Returns the last child of the last child of the last child... of the given node.

GTK.CTreeNode
GTK.CTreeNode

Move a node. Coordinates work as for insert.

GTK.CTreeNode
GTK.CTreeNode
GTK.CTreeNode
GTK.Ctree

Return the style of a cell

GTK.CTreeNode
GTK.Style

Return the celltype of this node.

GTK.CTreeNode

Returns the pixmap and mask of this node in a mapping: ([ "pixmap":the_pixmap, "mask":the_bitmap ])

CTreeNode

Returns the pixmap, mask and text of this node in a mapping: ([ "pixmap":the_pixmap, "mask":the_bitmap, "text":the_text ])

GTK.CTreeNode

Return the data associated with a node, or 0.

GTK.CTreeNode

Return the style of a row

GTK.CTreeNode
GTK.Style

Return whether or not this node can be selcted by the user

GTK.CTreeNode

Returns the text of the specified node

GTK.CTreeNode

Return 1 if the node is currently visible

GTK.CTreeNode

Scroll the tree so a specified node (and column) is visible. If the node is folded, it's first visible parent will be shown.

GTK.CTreeNode
GTK.Ctree

Return the node that is currently visible on the specified row.

GTK.CTreeNode

Set the background of a row

GTK.CTreeNode
GDK.Color
GTK.Ctree

Set the style of a cell

GTK.CTreeNode
GTK.Style
GTK.Ctree

Set the foreground of a row

GTK.CTreeNode
GDK.Color
GTK.Ctree

Set the pixmap in a cell

GTK.CTreeNode
GDK.Pixmap
GDK.Bitmap
GTK.Ctree

Set the pixmap and text in a cell

GTK.CTreeNode
GDK.Pixmap
GDK.Bitmap
GTK.Ctree

Set the user data associated with the specified node. This data can be used to find nodes, and when a node is selected it can be easily retrieved using node_get_row_data.

You can only use objects as row data right now

GTK.CTreeNode
GTK.Ctree

Set the style of a row

GTK.CTreeNode
GTK.Style
GTK.Ctree

Whether this node can be selected by the user.

GTK.CTreeNode
GTK.Ctree

Shift the given cell the given amounts in pixels.

GTK.CTreeNode
GTK.Ctree

Set the text in a cell

GTK.CTreeNode
GTK.Ctree

Remove a node and it's subnodes from the tree. The nodes will be destroyed, so you cannot add them again.

GTK.CTreeNode
GTK.Ctree

Select a node.

GTK.CTreeNode
GTK.Ctree

Select a node and it's children.

GTK.CTreeNode
GTK.Ctree

Set the expander style, one of CTREE_EXPANDER_CIRCULAR, CTREE_EXPANDER_NONE, CTREE_EXPANDER_SQUARE and CTREE_EXPANDER_TRIANGLE

GTK.Ctree

Set the indentation level

GTK.Ctree

Set the line style, one of CTREE_LINES_DOTTED, CTREE_LINES_NONE, CTREE_LINES_SOLID and CTREE_LINES_TABBED

GTK.Ctree

text :The texts to be shown in each column. spacing : The extra space between the pixmap and the text. pixmap_closed : The pixmap to be used when the node is collapsed. Can be NULL. mask_closed : The mask for the above pixmap. Can be NULL. pixmap_opened : The pixmap to be used when the children are visible. Can be NULL. mask_opened : The mask for the above pixmap. Can be NULL. is_leaf : Whether this node is going to be a leaf. expanded : Whether this node should start out expanded or not.

GTK.CTreeNode
GDK.Pixmap
GDK.Bitmap
GDK.Pixmap
GDK.Bitmap
GTK.Ctree

If true, the 'stub' will be shown. The stub is the small line that goes horizontally from the expand or collapse button to the actual contents of the tree

GTK.Ctree

Set the spacing between the tree column and the other columns

GTK.Ctree

Sort the specified node.

GTK.CTreeNode
GTK.Ctree

Sort the specified node and it's children.

GTK.CTreeNode
GTK.Ctree

If the node is expanded, collapse it, and if it's collapsed, expand it.

GTK.CTreeNode
GTK.Ctree

Toggle the expansion of the whole subtree, starting with node.

GTK.CTreeNode
GTK.Ctree

Unselect a node.

GTK.CTreeNode
GTK.Ctree

Unselect a node and it's children.

GTK.CTreeNode
GTK.Ctree

Toggle buttons are derived from normal buttons and are very similar, except they will always be in one of two states, alternated by a click. They may be depressed, and when you click again, they will pop back up. Click again, and they will pop back down.

GTK.ToggleButton("Toggle button") ../images/gtk_togglebutton.png

GTK.ToggleButton("Toggle button")->set_active( 1 ) ../images/gtk_togglebutton_2.png

Signals: toggled

GTK.Button

If you supply a string, a label will be created and inserted in the button. Otherwise, use -&gt;add(widget) to create the contents of the button.

GTK.ToggleButton

returns 1 if the button is pressed, 0 otherwise.

If activep is true, the toggle button will be activated.

GTK.ToggleButton

If true, draw indicator

GTK.ToggleButton

emulate a 'toggle' of the button. This will emit a 'toggled' signal.

GTK.ToggleButton

GTK.Paned is the base class for widgets with two panes, arranged either horizontally (W(HPaned)) or vertically (W(VPaned)). Child widgets are added to the panes of the widget with pack1() and pack2(). The division beween the two children is set by default from the size requests of the children, but it can be adjusted by the user.

A paned widget draws a separator between the two child widgets and a small handle that the user can drag to adjust the division. It does not draw any relief around the children or around the separator. (The space in which the separator is called the gutter). Often, it is useful to put each child inside a W(Frame) with the shadow type set to GTK.ShadowIn so that the gutter appears as a ridge.

Each child has two options that can be set, resize and shrink. If resize is true, then when the GTK.Paned is resized, that child will expand or shrink along with the paned widget. If shrink is true, then when that child can be made smaller than it's requisition by the user. Setting shrink to 0 allows the application to set a minimum size. If resize is false for both children, then this is treated as if resize is true for both children.

The application can set the position of the slider as if it were set by the user, by calling set_position().

GTK.Container

Set the left or topmost item. This is equivalent to pack1(left_or_top,0,1)

GTK.Widget
GTK.Paned

Set the right or bottommost item This is equivalent to pack2(left_or_top,0,1)

GTK.Widget
GTK.Paned

The size of the handle, in pixels

The xpos of the handle, in pixels

The ypos of the handle, in pixels

Return 1 if the user is dragging the handle

The maximum handle position possible.

The minimum handle position possible.

Add a child to the top or left pane.

GTK.Widget
GTK.Paned

Add a child to the bottom or right pane.

GTK.Widget
GTK.Paned

Set the width of the gutter. (The area between the two panes).

GTK.Paned

The size of the handle in pixels

GTK.Paned

Set the position of the separator, as if set by the user. If position is negative, the remembered position is forgotten, and the division is recomputed from the the requisitions of the children.

GTK.Paned

A GTK.MenuShell is the abstract base class used to derive the W(Menu) and W(MenuBar) subclasses.

A GTK.MenuShell is a container of W(MenuItem) objects arranged in a list which can be navigated, selected, and activated by the user to perform application functions. A W(MenuItem) can have a submenu associated with it, allowing for nested hierarchical menus.

Signals: activate_current An action signal that activates the current menu item within the menu shell.

cancel An action signal which cancels the selection within the menu shell. Causes the selection_done signal to be emitted.

deactivate This signal is emitted when a menu shell is deactivated.

move_current An action signal which moves the current menu item in the direction specified by the third argument.

selection_done This signal is emitted when a selection has been completed within a menu shell.

GTK.Container

Activates the menu item within the menu shell.

GTK.Widget
GTK.MenuShell

Adds a new W(MenuItem) to the end of the menu shell's item list. Same as 'add'.

GTK.Widget
GTK.MenuShell

This function returns all children of the menushell as an array.

Deactivates the menu shell. Typically this results in the menu shell being erased from the screen.

GTK.MenuShell

1 if the menu shell is currently active.

Add a widget after the specified location

GTK.Widget
GTK.MenuShell

Add a menu item to the start of the widget (for a menu: top, for a bar: left)

GTK.Widget
GTK.MenuShell

Selects the menu item from the menu shell.

GTK.Widget
GTK.MenuShell

The Text widget allows multiple lines of text to be displayed and edited. It supports both multi-colored and multi-font text, allowing them to be mixed in any way we wish. It also has a wide set of key based text editing commands, which are compatible with Emacs.

The text widget supports full cut-and-paste facilities, including the use of double- and triple-click to select a word and a whole line, respectively.

Bugs:<ul> <li> You cannot add text to the widget before it is realized.</li> </ul>

GTK.Text(GTK.Adjustment(),GTK.Adjustment()) ../images/gtk_text.png

function_object(call_out(GTK.Text(GTK.Adjustment(),GTK.Adjustment())->set_text, 0, "Some text")[0]) ../images/gtk_text_2.png

function_object(call_out(GTK.Text(GTK.Adjustment(),GTK.Adjustment())->insert, 0, "Some text", 0, GDK.Color(255,255,0), GDK.Color(0,0,0))[0]) ../images/gtk_text_3.png

GTK.Editable

Delete n characters backwards from the cursor position

GTK.Text

Creates a new GTK.Text widget, initialized with the given Gtk.Adjustments. These pointers can be used to track the viewing position of the GTK.Text widget. Passing NULL to either or both of them will make the text widget create it's own. You can set these later with the function gtk_text_set_adjustment()

GTK.Adjustment
GTK.Adjustment
GTK.Text

Delete n characters forward from the cursor position

GTK.Text

Freezes the widget which disallows redrawing of the widget until it is thawed. This is useful if a large number of changes are going to made to the text within the widget, reducing the amount of flicker seen by the user.

GTK.Text

Returns the length of the all the text contained within the widget

Gets the current position of the cursor as the number of characters from the upper left corner of the GtkText widget.

Get the current contents of the text object.

syntax: object insert(string what); OR object insert(string what, GDK.Font font, GDK.Color fg, GDK.Color bg); OR object insert(string what, 0, GDK.Color fg, GDK.Color bg); OR object insert(string what, 0, GDK.Color fg); OR object insert(string what, 0, 0, GDK.Color bg);

Insert new text, optionally with colors.

GDK.Font
GDK.Color
GDK.Color
GTK.Text

Change the adjustments (as supplied to the constructor) to other adjustments.

GTK.Adjustment
GTK.Adjustment
GTK.Text

If true, the user can change the text in the widget.

GTK.Text

If true, the widget will automatically wrap the contents.

GTK.Text

Sets the cursor at the given point. In this case a point constitutes the number of characters from the extreme upper left corner of the widget.

GTK.Text

Set the text to the specified string.

GTK.Text

If true, the widget will automatically wrap the contents.

GTK.Text

unfreeze the widget.

GTK.Text

A class inherited by all objects used to store data (they are not widgets)

Signals: disconnect

GTK.Object

The color selection widget is, not surprisingly, a widget for interactive selection of colors. This composite widget lets the user select a color by manipulating RGB (Red, Green, Blue) and HSV (Hue, Saturation, Value) triples. This is done either by adjusting single values with sliders or entries, or by picking the desired color from a hue-saturation wheel/value bar. Optionally, the opacity of the color can also be set.

The color selection widget currently emits only one signal, "color_changed", which is emitted whenever the current color in the widget changes, either when the user changes it or if it's set explicitly through set_color().

GTK.ColorSelection() ../images/gtk_colorselection.png

GTK.Vbox

Create a new color selection.

GTK.ColorSelection

When you need to query the current color, typically when you've received a "color_changed" signal, you use this function. The return value is an array of floats, See the set_color() function for the description of this array.

You can set the current color explicitly by calling this function with an array of colors (floats). The length of the array depends on whether opacity is enabled or not. Position 0 contains the red component, 1 is green, 2 is blue and opacity is at position 3 (only if opacity is enabled, see set_opacity()) All values are between 0.0 and 1.0

GTK.ColorSelection

one of UPDATE_ALWAYS, UPDATE_CONTINUOUS, UPDATE_DELAYED, UPDATE_DISCONTINUOUS and UPDATE_IF_VALID.

The default policy is GTK.UpdateContinuous which means that the current color is updated continuously when the user drags the sliders or presses the mouse and drags in the hue-saturation wheel or value bar. If you experience performance problems, you may want to set the policy to GTK.UpdateDiscontinuous or GTK.UpdateDelayed.

GTK.ColorSelection

Some gtk widgets don't have associated X windows, so they just draw on their parents. Because of this, they cannot receive events and if they are incorrectly sized, they don't clip so you can get messy overwritting etc. If you require more from these widgets, the EventBox is for you.

At first glance, the EventBox widget might appear to be totally useless. It draws nothing on the screen and responds to no events. However, it does serve a function - it provides an X window for its child widget. This is important as many GTK widgets do not have an associated X window. Not having an X window saves memory and improves performance, but also has some drawbacks. A widget without an X window cannot receive events, and does not perform any clipping on it's contents. Although the name EventBox emphasizes the event-handling function, the widget can also be used for clipping.

The primary use for this widget is when you want to receive events for a widget without a window. Examples of such widgets are labels and images.

GTK.EventBox()->set_usize(100,100) ../images/gtk_eventbox.png

GTK.Bin

Create a new event box widget

GTK.EventBox

Basically a horizontal W(Menu). The menu image cannot be grabbed automatically, but this is how you would create a menu all in one line. This is not the recommended coding style. GTK.MenuBar()->add(GTK.Menu_item("Menu")->set_submenu(GTK.Menu()->add(GTK.Menu_item("Sub")))->select()->activate())->add(GTK.Menu_item("Bar")) ../images/gtk_menubar.png

GTK.MenuShell
GTK.Widget
GTK.MenuBar
GTK.MenuBar
GTK.Widget
GTK.MenuBar
GTK.Widget
GTK.MenuBar
GTK.MenuBar

Ruler widgets are used to indicate the location of the mouse pointer in a given window. A window can have a vertical ruler spanning across the width and a horizontal ruler spanning down the height. A small triangular indicator on the ruler shows the exact location of the pointer relative to the ruler.

GTK.Widget

draw the position

GTK.Ruler

draw the ticks

GTK.Ruler

The currently defined lower extent of the ruler.

The currently defined max_size of the ruler.

The currently defined initial position of the pointer indicator within the ruler.

The currently defined upper extent of the ruler.

Either GTK.Pixels, GTK.Centimers or GTK.Inches. The default measure is GTK.Pixels.

GTK.Ruler

The lower and upper arguments define the extent of the ruler, and max_size is the largest possible number that will be displayed. Position defines the initial position of the pointer indicator within the ruler.

GTK.Ruler

The GTK.HScale widget is used to allow the user to select a value using a horizontal slider. A GTK.Adjustment is used to set the initial value, the lower and upper bounds, and the step and page increments.

See W(Scale) for details

The position to show the current value, and the number of decimal places shown can be set using the parent W(Scale) class's functions.

GTK.Hscale(GTK.Adjustment())->set_usize(300,30) ../images/gtk_hscale.png

GTK.Scale

Used to create a new hscale widget. The adjustment argument can either be an existing W(Adjustment), or 0, in which case one will be created for you.

GTK.Adjustment
GTK.Hscale

The basic container class.

Signals: add Called when a new object is added to the container. (used internally)

focus Called when the container gets focus (used internally)

need_resize Called when the container needs resizing (used internally)

remove Called when a object is removed from the container (used internally)

set_focus_child

GTK.Widget

Add a subwidget to the container. Don't forget to call show() in the subwidget. Some (even most) containers can only contain one child. Calling this function might result in a resize of the container.

GTK.Widget
GTK.Container

Compatibility alias for set_border_width. Do not use this function in new code!

GTK.Container

This function returns all children of the container as an array.

Emulate a focus event. direction is one of DIR_DOWN, DIR_LEFT, DIR_RIGHT, DIR_TAB_BACKWARD, DIR_TAB_FORWARD and DIR_UP.

GTK.Container

Remove a child from the container. The argument is the child to remove. Calling this function might result in a resize of the container.

GTK.Widget
GTK.Container

Set the border width. The border width is the size of the padding around the container. Calling this function might result in a resize of the container.

GTK.Container

Emulate a set_focus_child signal. Focus on the specified child.

GTK.Widget
GTK.Container

Set the hadjustment used to focus children.

GTK.Adjustment
GTK.Container

Set the vadjustment used to focus children.

GTK.Adjustment
GTK.Container

One of RESIZE_IMMEDIATE, RESIZE_PARENT and RESIZE_QUEUE

GTK.Container

The basic widget, inherited (directly or indirectly) by all widgets. Thus, all functions and signals defined in this widget works on all widgets.

One of the most importat functions in this class is 'show', it lets GTK know that we are done setting the attributes of the widget, and it is ready to be displayed. You may also use hide to make it disappear again. The order in which you show the widgets is not important, but I suggest showing the toplevel window last so the whole window pops up at once rather than seeing the individual widgets come up on the screen as they're formed. The children of a widget (a window is a widget too) will not be displayed until the window itself is shown using the show() function.

Signals: add_accelerator Called when an accelarator (keyboard shortcut) is added to the widget

button_press_event Called when a mouse button is pressed

button_release_event Called when a mouse button is released

client_event An event sent by another client application

configure_event The size, position or stacking order of the widget has changed

debug_msg

delete_event Called when the user has requested that the widget should be closed

destroy_event Called when the widget is destroyed

drag_begin Called when the drag is initiated, on the sending side

drag_data_delete Called when the data can be safely deleted (there is no need to use this function in pigtk, it's all handled automatically)

drag_data_get Called on the sending side when the drop is initiated

drag_data_received Called on the receiving side when the drop is finished.

drag_drop Called on the receiving side when the drop is initiated

drag_end Called when the drag is finished, on the sending side

drag_leave Called when the mouse leaves the widget while the user is dragging something

drag_motion Called on the receiving side when the cursor is moved over the widget while dragging something

draw Called when the widget should draw itself.

draw_default Called when the widget should draw itself, and indicate that it's the default widget

draw_focus Called when the widget should draw itself, and a focus indicator around itself (or otherwise indicate that is has the keyboard focus)

enter_notify_event Called when the mouse enters the widget

event Called for all events

expose_event Called when the widget, or a part of the widget gets and expose event

focus_in_event The keyboard focus has entered the widget

focus_out_event The keyboard focus has left the widget

hide Called when the widget is hidden

key_press_event Called when a keyboard key is pressed

key_release_event Called when a keyboard key is released

leave_notify_event Called when the mouse leaves the widget

map Called when the window associated with the widget is mapped

map_event Called just before the 'map' signal

motion_notify_event Called when the mouse is moved inside the widget

no_expose_event

other_event

parent_set Called when the parent widget is changed

property_notify_event Called when a property of the GDK window associated with the widget is changed

proximity_in_event

proximity_out_event

realize Called when the widget is realized. Some methods cannot be used until the widget has been realized, if you get assertion errors related to 'w->window' or similar, this is probably the cause.

remove_accelerator Called when an accelerator (keyboard shortcut) is removed from the widget

selection_clear_event NYI

selection_notify_event NYI

selection_received NYI

selection_request_event NYI

show Called when the widget is shown

size_allocate Called when the widget get's the size it should be

size_request Called when the widget should calculate how big it want's to be

state_changed

style_set Called when the style is changed

unmap Called when the window associated with the widget is unmapped

unmap_event Called just before the 'unmap' signal

unrealize Called when the widget is unrealized.

visibility_notify_event The widget has been mapped, unmapped, hidden, or otherwise had it's visibility modified

GTK.Object

Activate the widget. This either activates the widget, if possible (as an example, buttons can be activated), or activates the default widget of it's parent (or it's parent, or it's parents parent etc.)

GTK.Widget

Add an accelerator (keyboard shortcut).

Flag is one of ACCEL_LOCKED, ACCEL_SIGNAL_VISIBLE and ACCEL_VISIBLE

The signal is the signal to invoke when the accelerator key is pressed.

The modifiers is a bitwise or of one or more of GDK.ShiftMask, GDK.LockMask, GDK.ControlMask, GDK_MOD1_MASK, GDK_MOD2_MASK, GDK_MOD3_MASK, GDK_MOD4_MASK and GDK_MOD5_MASK.

The group is the accelerator group in which the accelerator should be added.

The key is the unicode code for the key to bind.

GTK.AccelGroup
GTK.Widget

Events is one or more of: GDK.ExposureMask, GDK.PointerMotionMask, GDK.PointerMotion_HINTMask, GDK.ButtonMotionMask, GDK.Button1MotionMask, GDK.Button2MotionMask, GDK.Button3MotionMask, GDK.ButtonPressMask, GDK.ButtonReleaseMask, GDK.KeyPressMask, GDK.KeyReleaseMask, GDK.EnterNotifyMask, GDK.LeaveNotifyMask, GDK.FocusChangeMask, GDK.StructureMask, GDK.PropertyChangeMask, GDK.VisibilityNotifyMask, GDK.ProximityInMask, GDK.ProximityOutMask and GDK.AllEventsMask

GTK.Widget

Returns ([ "x":xoffset, "y":yoffset, "width":xsize, "height":ysize ])

Returns the class 'pathname' of this widget. Useful for rc-files and such.

Copies the rectangle defined by xsource,ysource and width,height from the source widget, and places the results at xdest,ydest in the widget in which this function is called. NOTE: The widget must be realized before this function can be used

GDK.GC
GTK.Widget
GTK.Widget

Register a drop site, and possibly add default behaviors. arguments: flags: Which types of default drag behavior to use (one of DEST_DEFAULT_ALL, DEST_DEFAULT_DROP, DEST_DEFAULT_HIGHLIGHT and DEST_DEFAULT_MOTION) targets: Table of targets that can be accepted ({ ({ content_type(string), flags(int(try 0)), id(int) }), ...}) The id will be received in the signal handlers. actions: one of GDK_ACTION_ASK, GDK_ACTION_COPY, GDK_ACTION_DEFAULT, GDK_ACTION_LINK, GDK_ACTION_MOVE and GDK_ACTION_PRIVATE results:

GTK.Widget

Removes the drop support from this widget (see drag_dest_set)

GTK.Widget

Get the data from a context and an integer timestamp (from an event), requesting it from the dropping client. This function should probably never be used directly.

Use the selection argument passed to the drag_data_received signal instead.

GDK.DragContext
GTK.Widget

Highlight the widget. Not normaly used directly.

GTK.Widget

Register a drop site, and possibly add default behaviors. arguments: buttons: Which mouse buttons can be used to start the drag targets: Table of targets that can be accepted ({ ({ content_type(string), flags(int(try 0)), id(int) }), ...}) The id will be received in the signal handlers. actions: one of GDK_ACTION_ASK, GDK_ACTION_COPY, GDK_ACTION_DEFAULT, GDK_ACTION_LINK, GDK_ACTION_MOVE and GDK_ACTION_PRIVATE results:

GTK.Widget

Set the icon that will be used (by default) for drags from this widget.

GDK.Pixmap
GDK.Bitmap
GTK.Widget

Remove the drag support from this widget. See drag_source_set.

GTK.Widget

Unhighlight the widget. Not normaly used directly.

GTK.Widget

Ensure that the widget has a style associated with it.

GTK.Widget

Like set name, but it is inherited by the children of this widget.

Return the current event mask (see set_events and add_events)

Returns one of GDK_EXTENSION_EVENTS_ALL, GDK_EXTENSION_EVENTS_CURSOR and GDK_EXTENSION_EVENTS_NONE

Return the GDK.Window associated with this widget, if any.

GDK.Window

Returns the name set by set_name or the class name

Returns the parent of this widget, if any, if there is no parent 0 is returned.

GTK.Widget

Return the style associated with this widget

GTK.Style

return the toplevel widget this widget is inside (or this widget if it is the toplevel widget)

GTK.Widget

Make this widget the default action for the parent widget

GTK.Widget

Grab the focus.

GTK.Widget

All possible flags are: GTK.AppPaintable, GTK.CanDefault, GTK.CanFocus, GTK.CompositeChild, GTK.HasDefault, GTK.HasFocus, GTK.HasGrab, GTK.Mapped, GTK.NoReparent, GTK.NoWindow, GTK.ParentSensitive, GTK.RcStyle, GTK.Realized, GTK.ReceivesDefault GTK.Sensitive, GTK.Toplevel and GTK.Visible.

Hide this widget

GTK.Widget

Hide this widget and all it's children

GTK.Widget

Do an intersection with the area and place the result in 'intersection'.

GDK.Rectangle
GDK.Rectangle

Returns true if the specified widget is an ancestor of this widget.

GTK.Widget

Make it impossible to add new accelerators, or remove old ones

GTK.Widget

Map the widget. Should normally not be called directly.

GTK.Widget

Returns the 'pathname' of this widget. Useful for rc-files and such.

Map the widget at the specified coordinates.

GTK.Widget

Force a clear (and subsequent redraw) of the widget

GTK.Widget

Force a clear (and subsequent redraw) of part of the widget

GTK.Widget

Force a redraw of the widget

GTK.Widget

Force a redraw of part of the widget

GTK.Widget

Force a allocation recalculation, followed by a redraw

GTK.Widget

Realize this widget, and it's children, if nessesary

GTK.Widget

Remove an accelerator (keyboard shortcut).

The modifiers is a bitwise or of one or more of GDK.ShiftMask, GDK.LockMask, GDK.ControlMask, GDK_MOD1_MASK, GDK_MOD2_MASK, GDK_MOD3_MASK, GDK_MOD4_MASK and GDK_MOD5_MASK.

The group is the accelerator group in which the accelerator should be added.

The key is the unicode code for the key to bind.

GTK.AccelGroup
GTK.Widget

Change the parent of the widget.

GTK.Widget
GTK.Widget

Reset all styles to their default value, recursively

GTK.Widget

Reset all styles to their default value

GTK.Widget

Supplying the selection is a bit more complicated than requesting it. You must register handlers that will be called when your selection is requested. For each selection/target pair you will handle, you make a call to this function.

selection, and target identify the requests this handler will manage. When a request for a selection is received, the "selection_get" signal will be called. info can be used as an enumerator to identify the specific target within the callback function.

Selection defaults to PRIMARY, and target defaults to STRING.

GDK.Atom
GDK.Atom
GTK.Widget

When prompted by the user, you claim ownership of the selection by calling this function.

If another application claims ownership of the selection, you will receive a "selection_clear_event".

The selection defaults to the PRIMARY selection, and the time to GDK.CurrentTime.

GDK.Atom
GTK.Widget

Retrieving the selection is an asynchronous process. To start the process, you call this function.

This converts the selection into the form specified by target. If at all possible, the time field should be the time from the event that triggered the selection. This helps make sure that events occur in the order that the user requested them. However, if it is not available (for instance, if the conversion was triggered by a "clicked" signal), then you can omit it altogether. This will cause it to be set to GDK.CurrentTime.

When the selection owner responds to the request, a "selection_received" signal is sent to your application. The handler for this signal receives a pointer to a GTK.SelectionData object.

The special target TARGETS generates a list of all valid targets.

Selection defaults to PRIMARY, and target defaults to STRING.

GDK.Atom
GDK.Atom

Make it possible to draw directly in the widget using the low-level drawing functions.

GTK.Widget

Set the background color or image. The argument is either a GDK.Pixmap or a GDK.Color object. NOTE: The widget must be realized before this function can be used

GDK.Color
GTK.Widget

xhot and yhot are the locations of the x and y hotspot relative to the upper left corner of the cursor image. Both the bitmaps and the colors must be specified.

GDK.Bitmap
GDK.Bitmap
GDK.Color
GDK.Color
GTK.Widget

Like set name, but it is inherited by the children of this widget.

GTK.Widget

Change the widget cursor. If no arguments are passed, restore the default cursor. Both fg and bg must be specified if either one is. <table border="0" cellpadding="3" cellspacing="0"> CURS(GDK.Arrow) CURS(GDK.BasedArrowDown) CURS(GDK.BasedArrowUp) CURS(GDK.Boat) CURS(GDK.Bogosity) CURS(GDK.BottomLeftCorner) CURS(GDK.BottomRightCorner) CURS(GDK.BottomSide) CURS(GDK.BottomTee) CURS(GDK.BoxSpiral) CURS(GDK.CenterPtr) CURS(GDK.Circle) CURS(GDK.Clock) CURS(GDK.CoffeeMug) CURS(GDK.Cross) CURS(GDK.CrossReverse) CURS(GDK.Crosshair) CURS(GDK.DiamondCross) CURS(GDK.Dot) CURS(GDK.Dotbox) CURS(GDK.DoubleArrow) CURS(GDK.DraftLarge) CURS(GDK.DraftSmall) CURS(GDK.DrapedBox) CURS(GDK.Exchange) CURS(GDK.Fleur) CURS(GDK.Gobbler) CURS(GDK.Gumby) CURS(GDK.Hand1) CURS(GDK.Hand2) CURS(GDK.Heart) CURS(GDK.Icon) CURS(GDK.IronCross) CURS(GDK.LeftPtr) CURS(GDK.LeftSide) CURS(GDK.LeftTee) CURS(GDK.Leftbutton) CURS(GDK.LlAngle) CURS(GDK.LrAngle) CURS(GDK.Man) CURS(GDK.Middlebutton) CURS(GDK.Mouse) CURS(GDK.Pencil) CURS(GDK.Pirate) CURS(GDK.Plus) CURS(GDK.QuestionArrow) CURS(GDK.RightPtr) CURS(GDK.RightSide) CURS(GDK.RightTee) CURS(GDK.Rightbutton) CURS(GDK.RtlLogo) CURS(GDK.Sailboat) CURS(GDK.SbDownArrow) CURS(GDK.SbHDoubleArrow) CURS(GDK.SbLeftArrow) CURS(GDK.SbRightArrow) CURS(GDK.SbUpArrow) CURS(GDK.SbVDoubleArrow) CURS(GDK.Shuttle) CURS(GDK.Sizing) CURS(GDK.Spider) CURS(GDK.Spraycan) CURS(GDK.Star) CURS(GDK.Target) CURS(GDK.Tcross) CURS(GDK.TopLeftArrow) CURS(GDK.TopLeftCorner) CURS(GDK.TopRightCorner) CURS(GDK.TopSide) CURS(GDK.TopTee) CURS(GDK.Trek) CURS(GDK.UlAngle) CURS(GDK.Umbrella) CURS(GDK.UrAngle) CURS(GDK.Watch) CURS(GDK.Xterm) </table>

GDK.Color
GDK.Color
GTK.Widget

Events is one or more of: GDK.ExposureMask, GDK.PointerMotionMask, GDK.PointerMotion_HINTMask, GDK.ButtonMotionMask, GDK.Button1MotionMask, GDK.Button2MotionMask, GDK.Button3MotionMask, GDK.ButtonPressMask, GDK.ButtonReleaseMask, GDK.KeyPressMask, GDK.KeyReleaseMask, GDK.EnterNotifyMask, GDK.LeaveNotifyMask, GDK.FocusChangeMask, GDK.StructureMask, GDK.PropertyChangeMask, GDK.VisibilityNotifyMask, GDK.ProximityInMask, GDK.ProximityOutMask and GDK.AllEventsMask

GTK.Widget

Events is one of GDK_EXTENSION_EVENTS_ALL, GDK_EXTENSION_EVENTS_CURSOR and GDK_EXTENSION_EVENTS_NONE

GTK.Widget

The flags that it makes sense to set are: GTK.CanFocus and GTK.CanDefault

GTK.Widget

Set the name of the widget. The name is used when the rc-file is parsed, you can also parse your own resources by calling GTK.parse_rc() with a resource string. Example: TODO

GTK.Widget

Set the style from the .rc files

GTK.Widget

Set the scrolling (panning) adjustment objects for this widget. Returns 1 if it is possible to do so, and 0 otherwise.

GTK.Adjustment
GTK.Adjustment

True (1) or false (0). If true, the widget can receive events, otherwise the user cannot interact with the widget. Most widgets are drawn 'greyed' or more dim when they are unsensitive.

GTK.Widget

One of STATE_ACTIVE, STATE_INSENSITIVE, STATE_NORMAL, STATE_PRELIGHT and STATE_SELECTED. This function should normaly not be used directly.

GTK.Widget

Set the style to be associated with this widget

GTK.Style
GTK.Widget

Set the absolute coordinates of the widget relative to it's parent.

GTK.Widget

Set the absolute size of the widget. It might resize itself anyway, but this size is used as is in most widgets. Beware of this function, it might produce unexpected results. 0 for any size means 'keep old size'. When setting sizes of wtoplevel windows, it is preferable to use set_default_size

GTK.Widget

Set the shape of the widget, or, rather, it's window, to that of the supplied bitmap. Notice how the window behind the example window can be seen because of the rather odd shape the example window has. GTK.Window( GTK.WINDOW_TOPLEVEL )->add(GTK.Label("A rather Oddly shaped\n" "Window\n" "Indeed\n" "Or what do you\nthink?\n" "This text\n" "should\n" "be long enough"))->shape_combine_mask( GDK.Bitmap(Image.image(100,100,255,255,255)->rotate(10,0,0,0) ), 20,20) ../images/gtk_widget_shape_combine_mask.png

NOTE: The widget must be realized before this function can be used

GDK.Bitmap
GTK.Widget

Show the widget. Most (almost all) widgets must be shown to be visible on the screen.

GTK.Widget

Show this widget and all it's children

GTK.Widget

Show this widget and do not return until it is visible.

GTK.Widget

Returns the width, in pixels, the string would have if it was written with the default font in the style object assosiated with the widget.

Make it possible to add new accelerators, and remove old ones, again. Use this after lock_accelerators()

GTK.Widget

Unmap the widget. Should normally not be called directly.

GTK.Widget

Remove this widget from it's parent

GTK.Widget

Unrealize this widget, and it's children, if nessesary

GTK.Widget

The flags that it makes sense to unset are: GTK.CanFocus and GTK.CanDefault

GTK.Widget

Returns the x position of the upper left corner relative to the widgets window in pixels. For widgets that have their own window this will most likely be 0.

Returns the width of the widget in pixels.

Returns the y position of the upper left corner relative to the widgets window in pixels. For widgets that have their own window this will most likely be 0.

Returns the height of the widget in pixels.

Tooltips are the messages that appear next to a widget when the mouse pointer is held over it for a short amount of time. They are especially helpful for adding more verbose descriptions of things such as buttons in a toolbar.

An individual tooltip belongs to a group of tooltips. A group is created with a call to GTK.Tooltips(). Every tooltip in the group can then be turned off with a call to disable() and enabled with enable().

The length of time the user must keep the mouse over a widget before the tip is shown, can be altered with set_delay(). This is set on a 'per group of tooltips' basis.

To assign a tip to a particular W(Widget), set_tip() is used.

The default appearance of all tooltips in a program is determined by the current gtk theme that the user has selected. To change the tooltip appearance manually, use set_colors(). Again, this is per group of tooltips.

GTK.Data

Creates an empty group of tooltips. This function initialises a GTK.Tooltips structure. Without at least one such structure, you can not add tips to your application.

GTK.Tooltips

Disable this tooltip collection

GTK.Tooltips

Enable this tooltip collection

GTK.Tooltips

Realize the tooltip window (as returned from get_gdkwindow())

GTK.Tooltips

Changes the foreground and background colors.

GDK.Color
GDK.Color
GTK.Tooltips

Set the delat (in seconds)

GTK.Tooltips

Adds a tooltip containing the message tip_text to the specified W(Widget).

GTK.Widget
GTK.Tooltips

This is one of the nodes (branch or leaf) of the CTree. They are the equivalent of row numbers in a normal CList.

Returns the first child node

CTreeNode

Returns the previous sibling (the next on the same level)

Returns the previous sibling (the next on the same level)

Returns the previous sibling (the next on the same level)

Returns the next sibling (the next on the same level)

CTreeNode

Returns the parent node

GTK.CTreeNode

Returns the previous sibling (the next on the same level)

CTreeNode

Returns the CTreeRow associated with this CTreeNode. DEPRECATED, all CTreeRow functions are also available directly in this object.

GTK.CTreeRow

Ruler widgets are used to indicate the location of the mouse pointer in a given window. A window can have a vertical ruler spanning across the width and a horizontal ruler spanning down the height. A small triangular indicator on the ruler shows the exact location of the pointer relative to the ruler.

GTK.Vruler()->set_metric(GTK.PIXELS)->set_range(0.0,100.0,50.0,100.0)->draw_ticks()->draw_pos()->set_usize(30,50) ../images/gtk_vruler.png

GTK.Vruler()->set_metric(GTK.CENTIMETERS)->set_range(0.0,100.0,50.0,100.0)->draw_ticks()->draw_pos()->set_usize(30,50) ../images/gtk_vruler_2.png

GTK.Vruler()->set_usize(30,50) ../images/gtk_vruler_3.png

GTK.Ruler

Used to create a new vruler widget.

GTK.Vruler

A calendar widget. GTK.Calendar(); ../images/gtk_calendar.png

GTK.Calendar()->select_day( 16 ); ../images/gtk_calendar_2.png

Signals: day_selected

day_selected_double_click

month_changed

next_month

next_year

prev_month

prev_year

GTK.Widget

Remove all day markers

GTK.Calendar

Create a new calendar widget

GTK.Calendar

Bitwise or of one or more of CALENDAR_NO_MONTH_CHANGE, CALENDAR_SHOW_DAY_NAMES, CALENDAR_SHOW_HEADING, CALENDAR_SHOW_WEEK_NUMBERS and CALENDAR_WEEK_START_MONDAY.

GTK.Calendar

Suspend all dynamic updating of the widget

GTK.Calendar

returns a mapping: ([ "year":year, "month":month, "day":day ])

Return an array of 6x7 days, representing the cells in the currently viewed calendar month.

Return an array of 6x7 days, representing the cells in the currently viewed calendar month. The value is the day of month.

The currently focused column

The currently focused row

The currently highlighted column

The currently highlighted row

Returns an array (with 31 elements) with 1es and 0es.

The current month

The number of days that are marked

The currently selected day

The current year

Mark a day

GTK.Calendar

Select a certain day of the currently selected month

GTK.Calendar

Select the month to be viewed.

Set the color to use to mark dates

GDK.Color
GTK.Calendar

Resume dynamic updating of the widget

GTK.Calendar

Unmark a day

GTK.Calendar

Check buttons inherent many properties and functions from the the toggle buttons, but look a little different. Rather than being buttons with text inside them, they are small squares with the text to the right of them. These are often used for toggling options on and off in applications. GTK.Check_button( "title" ) ../images/gtk_checkbutton.png

GTK.ToggleButton

The argument, if specified, is the label of the item. If no label is specified, use object->add() to add some other widget (such as an pixmap or image widget)

GTK.CheckButton

The GtkFontSelectionDialog widget is a dialog box for selecting a font.

To set the font which is initially selected, use set_font_name().

To get the selected font use get_font() or get_font_name().

To change the text which is shown in the preview area, use set_preview_text().

The base filter is not yet implemented in Pike GTK. Filters can be used to limit the fonts shown. There are 2 filters in the GtkFontSelectionDialog - a base filter and a user filter. The base filter can not be changed by the user, so this can be used when the user must choose from the restricted set of fonts (e.g. for a terminal-type application you may want to force the user to select a fixed-width font). The user filter can be changed or reset by the user, by using the 'Reset Filter' button or changing the options on the 'Filter' page of the dialog. GTK.FontSelectionDialog("Select a font") ../images/gtk_fontselectiondialog.png

GTK.Window

Create a new font selection dialog with the specified window title

GTK.FontSelectionDialog

The apply button

GTK.Button

The cancel button

GTK.Button

The W(FontSelection) widget

GTK.FontSelection

The ok button

GTK.Button

Menu items, to be added to menues.

GTK.Item

Emulate an activate signal

GTK.MenuItem

First argument is 'show_toggle_indicator', second is 'show_submenu_indicator'.

GTK.MenuItem

If a string is supplied, a W(Label) widget is created using that string and added to the item. Otherwise, you should add another widget to the list item with -&gt;add().

GTK.MenuItem

Emulate a deselect signal

GTK.MenuItem

The width of the accelerator string, in pixels

Is the widget right justified?

Should the submenu indicator be shown?

Should the toggle indicator be shown?

The direction the submenu will be shown in. One of DIR_DOWN, DIR_LEFT, DIR_RIGHT, DIR_TAB_BACKWARD, DIR_TAB_FORWARD and DIR_UP

The placement of the submenu.

The size of the toggle indicator

Remove the submenu for this menu button.

GTK.MenuItem

Make the menu item stick to the right edge of it's container.

GTK.MenuItem

Emulate a select signal

GTK.MenuItem

(sub menu placement) One of DIRECTION_LEFT and DIRECTION_RIGHT

GTK.MenuItem

Set the submenu for this menu button.

GTK.Widget
GTK.MenuItem

The basic GTK class. All other GTK classes inherit this class. The only user-callable functions are the signal related ones.

Signals: destroy Called when the object is destroyed

GTK.Object

Temporarily block a signal handler. No signals will be received while the hander is blocked. See signal connect for more info.

GTK.Object

Connect a signal to a pike function. The function will be called with the last argument to this function as it's first argument (defaults to 0), the second argument is always the widget, any other arguments are the ones supplied by GTK.

The return value of this function can be used to remove a signal with signal_disconnect, and block and unblock the signal will signal_block and signal_unblock.

``

Connect a signal to a pike function.

This function differs from the signal_connect function in how it calls the callback function.

The old interface:

       void signal_handler( mixed my_arg, GTK.Object object,
                            mixed ... signal_arguments )

The new interface:

       void signal_handler( mixed ... signal_arguments,
                            mixed my_arg, GTK.Object object )

The return value of this function can be used to remove a signal with signal_disconnect, and block and unblock the signal will signal_block and signal_unblock.

``

Remove a signal formerly added by signal_connect. The argument is the return value of signal_connect(). See signal connect for more info.

GTK.Object

Halt the emit of the current named signal. Useful in signal handlers when you want to override the behaviour of some default signal handler (key press events, as an example) See signal_connect.

GTK.Object

Unblock a formerly blocked signal handler. See signal_block and signal_connect for more info.

GTK.Object

A label for accelerators.

GTK.Label
GTK.AccelLabel
GTK.Widget
GTK.AccelLabel

More or less equivalent to a normal box, but you can set a few layout schemes that are not available for normal boxes. See the hbox and vbox documentation for examples.

GTK.Box

Return the default inter-child padding ([ "x":xpadding, "y":ypadding ])

Return the child size as ([ "x":xsize, "y":ysize ])

Returns the currently configured layout. One of BUTTONBOX_DEFAULT_STYLE, BUTTONBOX_EDGE, BUTTONBOX_END, BUTTONBOX_SPREAD and BUTTONBOX_START

Return the spacing that is added between the buttons

Set the padding for a specific child.

GTK.ButtonBox

Set the size of a specified child

GTK.ButtonBox

layout is one of BUTTONBOX_DEFAULT_STYLE, BUTTONBOX_EDGE, BUTTONBOX_END, BUTTONBOX_SPREAD and BUTTONBOX_START

GTK.ButtonBox

in pixels

GTK.ButtonBox

General documentation: See W(Scrollbar) GTK.Vscrollbar(GTK.Adjustment())->set_usize(15,60) ../images/gtk_vscrollbar.png

GTK.Scrollbar

Used to create a new vscrollbar widget. The adjustment argument can either be an existing W(Adjustment), or 0, in which case one will be created for you. Specifying 0 might actually be useful in this case, if you wish to pass the newly automatically created adjustment to the constructor function of some other widget which will configure it for you, such as a text widget.

GTK.Adjustment
GTK.Vscrollbar

A container that can only contain one child, and accepts events. draws a bevelbox around itself. GTK.Button("A button") ../images/gtk_button.png

GTK.Button("A button\nwith multiple lines\nof text") ../images/gtk_button_2.png

GTK.Button()->add(GTK.Image(GDK.Image(0)->set(Image.image(100,40)->test()))) ../images/gtk_button_3.png

Signals: clicked Called when the button is pressed, and then released

enter Called when the mouse enters the button

leave Called when the mouse leaves the button

pressed Called when the button is pressed

released Called when the button is released

GTK.Container

Emulate a 'clicked' event (press followed by release).

GTK.Button

If a string is supplied, a W(Label) is created and added to the button.

GTK.Button

Emulate a 'enter' event.

GTK.Button

The (one and only) child of this container.

GTK.Widget

One of RELIEF_HALF, RELIEF_NONE and RELIEF_NORMAL, set with set_relief()

Emulate a 'leave' event.

GTK.Button

Emulate a 'press' event.

GTK.Button

Emulate a 'release' event.

GTK.Button

One of RELIEF_HALF, RELIEF_NONE and RELIEF_NORMAL

GTK.Button

The contents of a handle box can be 'dragged' out of the box by the user. The contents will then be placed in a separate window. GTK.HandleBox()->add(GTK.Label("The contents")) ../images/gtk_handlebox.png

Signals: child_attached Called when a new child is added to the box

child_detached Called when a child is removed from the box

GTK.Bin

Create a new handle box widget.

GTK.HandleBox

Is the child detatched?

Is the floating window mapped?

The position of the handle. One of POS_BOTTOM, POS_LEFT, POS_RIGHT and POS_TOP

1 if the window is beeing dragged around right now.

True if the container should shrink when the child is detatched

The edge to snap to. One of POS_BOTTOM, POS_LEFT, POS_RIGHT and POS_TOP, or -1 for unset.

The position of the handle. One of POS_BOTTOM, POS_LEFT, POS_RIGHT and POS_TOP

GTK.HandleBox

True if the container should shrink when the child is detatched

One of SHADOW_ETCHED_IN, SHADOW_ETCHED_OUT, SHADOW_IN, SHADOW_NONE and SHADOW_OUT

GTK.HandleBox

The edge to snap to. One of POS_BOTTOM, POS_LEFT, POS_RIGHT and POS_TOP, or -1 for unset.

GTK.HandleBox
GTK.Widget

Sets the current value, the minimum value and the maximum value. The default min and max are 0.0 and 1.0 respectively.

GTK.Progress

The currently set activity mode.

Returns a float between 0.0 and 1.0

Return the current text (see set_format_string)

The format used to convert the value to a the text

Returns a float between 0.0 and 1.0

1 if the text will be shown

Formats 'value' and returns it as a text.

Return the current value

The text alignment, 0.0 is leftmost, 1.0 is rightmost

The text alignment, 0.0 is topmost, 1.0 is bottommost

As well as indicating the amount of progress that has occured, the progress bar may be set to just indicate that there is some activity. This can be useful in situations where progress cannot be measured against a value range. Mode is: 1: active 0: inactive

GTK.Progress

Sets the adjustment to use. See the adjustment documentation for more info

GTK.Adjustment
GTK.Progress

More or less like sprintf. %[field width][character] 0&lt;=width&gt;=2 Supported characters:

     %: Insert a %
     p or P: The percentage completed, with 'digits' number of decimals
     v or V: The actual value, with digits decimals.
     l or L: The lower value (from the adjustment)
     u or U: The higer value (from the adjustment)
     %: Insert a %

The default format is '%P%%'
GTK.Progress

Sets the value (between 0.0 and 1.0). Uses the min and max values.

GTK.Progress

If true, write a text in the progress bar.

GTK.Progress

The location for the text in the progress bar. xalign is between 0.0 (leftmost) and 1.0 (rightmost) yalign is between 0.0 (topmost) and 1.0 (bottommost)

Default is xalign == yalign == 0.5

GTK.Progress

Set the value.

GTK.Progress

An arrow pointing in one of four directions. The 'etched' shadow types does not work. GTK.Arrow(GTK.ARROW_UP, GTK.SHADOW_OUT) ../images/gtk_arrow.png

GTK.Arrow(GTK.ARROW_LEFT, GTK.SHADOW_IN) ../images/gtk_arrow_2.png

GTK.Arrow(GTK.ARROW_RIGHT, GTK.SHADOW_IN) ../images/gtk_arrow_3.png

GTK.Arrow(GTK.ARROW_DOWN, GTK.SHADOW_OUT) ../images/gtk_arrow_4.png

GTK.Misc

First argument is one of ARROW_DOWN, ARROW_LEFT, ARROW_RIGHT and ARROW_UP, second one of SHADOW_ETCHED_IN, SHADOW_ETCHED_OUT, SHADOW_IN, SHADOW_NONE and SHADOW_OUT.

GTK.Arrow

Return the arrow type. One of ARROW_DOWN, ARROW_LEFT, ARROW_RIGHT and ARROW_UP.

Return the shadow type. One of SHADOW_ETCHED_IN, SHADOW_ETCHED_OUT, SHADOW_IN, SHADOW_NONE and SHADOW_OUT.

First argument is one of ARROW_DOWN, ARROW_LEFT, ARROW_RIGHT and ARROW_UP, second one of SHADOW_ETCHED_IN, SHADOW_ETCHED_OUT, SHADOW_IN, SHADOW_NONE and SHADOW_OUT.

GTK.Arrow

GtkPixmapMenuItem works like a normal GTK menu item, but you can insert a arbitrary widget (most often a pixmap widget), which is displayed at the left side. The advantage is that indentation is handled the same way as GTK does (i.e if you create a menu with a gtk_check_menu_item, all normal menu items are automatically indented by GTK - so if you use a normal menu item to display pixmaps at the left side, the pixmaps will be indented, which is not what you want. This widget solves the problem).

GTK.MenuItem

Creates a new pixmap menu item.

GTK.PixmapMenuItem

Set the pixmap of the menu item.

GTK.Widget
GTK.PixmapMenuItem

The NoteBook Widget is a collection of 'pages' that overlap each other, each page contains different information. This widget has become more common lately in GUI programming, and it is a good way to show blocks similar information that warrant separation in their display.

GTK.Notebook( )->set_tab_pos( GTK.POS_LEFT )->append_page( GTK.Label("Page 1\nContents"), GTK.Label("Page 1"))->append_page( GTK.Label(""), GTK.Label("Page 2"))->append_page(GTK.Label("Page 3 contents\nare here!"), GTK.Label("Page 3")) ../images/gtk_notebook.png

GTK.Notebook( )->set_tab_pos( GTK.POS_TOP )->append_page( GTK.Label("Page 1\nContents"), GTK.Label("Page 1"))->append_page( GTK.Label(""), GTK.Label("Page 2"))->append_page(GTK.Label("Page 3 contents\nare here!"), GTK.Label("Page 3")) ../images/gtk_notebook_2.png

GTK.Notebook( )->set_tab_pos( GTK.POS_RIGHT )->append_page( GTK.Label("Page 1\nContents"), GTK.Label("Page 1"))->append_page( GTK.Label(""), GTK.Label("Page 2"))->append_page(GTK.Label("Page 3 contents\nare here!"), GTK.Label("Page 3"))->next_page()->next_page() ../images/gtk_notebook_3.png

Signals: switch_page Called when a different page is selected

GTK.Container

Add a new 'page' to the notebook. The first argument is the contents of the page, the second argument is the label.

GTK.Widget
GTK.Widget
GTK.Notebook

Add a new 'page' to the notebook. The first argument is the contents of the page, the second argument is the label, the third argument is a menu widget.

GTK.Widget
GTK.Widget
GTK.Menu
GTK.Notebook
GTK.Notebook

Returns the index of the currently selected page

GTK.Widget
GTK.Widget

Returns the page for the specified index

GTK.Widget
GTK.Widget
GTK.Widget

Insert a page at the specified location, arguments as for append_page, but an aditional integer specifies the location.

GTK.Widget
GTK.Widget
GTK.Notebook

Insert a page at the specified location, arguments as for append_page_menu, but an aditional integer specifies the location.

GTK.Widget
GTK.Widget
GTK.Menu
GTK.Notebook

Go to the next page

GTK.Notebook

Returns the index for the specified page

GTK.Widget

Disable the popup menu (set with insert_page_menu)

GTK.Notebook

Enable the popup menu (set with insert_page_menu)

GTK.Notebook

Add a page at the end of the list of pages. The first argument is the contents of the page, the second argument is the label.

GTK.Widget
GTK.Widget
GTK.Notebook

Add a new 'page' at the end of the list of pages. The first argument is the contents of the page, the second argument is the label, the third argument is a menu widget.

GTK.Widget
GTK.Widget
GTK.Menu
GTK.Notebook

Go to the previous page

GTK.Notebook

Returns ([ "expand":expandp, "fill":fillp, "pack_type":type ])

GTK.Widget

Remove a page.

GTK.Notebook

Move the specified page to the index new_index

GTK.Widget
GTK.Notebook

If true, all tabs will have the same size

GTK.Notebook
GTK.Widget
GTK.Widget
GTK.Notebook
GTK.Widget
GTK.Notebook

Go to the specified page

GTK.Notebook

If true, add scrollbars if nessesary.

GTK.Notebook

If true, show the borders around the contents and tabs.

GTK.Notebook

If supplied with a true value, the tabs will be shown. Otherwise they will not be shown. The user will not be able to select the pages without them, but you can add 'next' and 'previous' buttons to create a wizard-line interface.

GTK.Notebook

In pixels.

GTK.Notebook

In pixels.

GTK.Notebook
GTK.Widget
GTK.Widget
GTK.Notebook
GTK.Widget
GTK.Notebook
GTK.Widget
GTK.Notebook

One of POS_BOTTOM, POS_LEFT, POS_RIGHT and POS_TOP

GTK.Notebook

In pixels.

GTK.Notebook

Together with W(Socket), GTK.Plug provides the ability to embed widgets from one process into another process in a fashion that is transparent to the user. One process creates a W(Socket) widget and, passes the XID of that widgets window to the other process, which then creates a GTK.Plug window with that XID. Any widgets contained in the GTK.Plug then will appear inside the first applications window.

GTK.Window

Create a new plug, the socket_id is the window into which this plug will be plugged.

GTK.Plug

returns 1 if the socket the plug is connected to is in this application.

The W(Alignment) widget controls the alignment and size of its child widget. It has four settings: xscale, yscale, xalign, and yalign.

The scale settings are used to specify how much the child widget should expand to fill the space allocated to the W(Alignment). The values can range from 0 (meaning the child doesn't expand at all) to 1 (meaning the child expands to fill all of the available space).

The align settings are used to place the child widget within the available area. The values range from 0 (top or left) to 1 (bottom or right). Of course, if the scale settings are both set to 1, the alignment settings have no effect.

NOIMG

GTK.Bin

xalign : the horizontal alignment of the child widget, from 0 (left) to 1 (right). yalign : the vertical alignment of the child widget, from 0 (top) to 1 (bottom). xscale : the amount that the child widget expands horizontally to fill up unused space, from 0 to 1. A value of 0 indicates that the child widget should never expand. A value of 1 indicates that the child widget will expand to fill all of the space allocated for the GTK.Alignment. yscale : the amount that the child widget expands vertically to fill up unused space, from 0 to 1. The values are similar to xscale.

GTK.Alignment

the horizontal alignment of the child widget, from 0 (left) to 1 (right).

the amount that the child widget expands horizontally to fill up unused space, from 0 to 1. A value of 0 indicates that the child widget should never expand. A value of 1 indicates that the child widget will expand to fill all of the space allocated for the GTK.Alignment.

the vertical alignment of the child widget, from 0 (top) to 1 (bottom).

the amount that the child widget expands vertically to fill up unused space, from 0 to 1. The values are similar to xscale.

xalign : the horizontal alignment of the child widget, from 0 (left) to 1 (right). yalign : the vertical alignment of the child widget, from 0 (top) to 1 (bottom). xscale : the amount that the child widget expands horizontally to fill up unused space, from 0 to 1. A value of 0 indicates that the child widget should never expand. A value of 1 indicates that the child widget will expand to fill all of the space allocated for the GTK.Alignment. yscale : the amount that the child widget expands vertically to fill up unused space, from 0 to 1. The values are similar to xscale.

GTK.Alignment

This dialog is used to enable XInput devices. By default, no extension devices are enabled. We need a mechanism to allow users to enable and configure their extension devices. GTK provides the InputDialog widget to automate this process. The following procedure manages an InputDialog widget. It creates the dialog if it isn't present, and shows it otherwise.

     GTK.InputDialog inputd;
     void create_input_dialog ()
     {
       if (!inputd)
       {
         inputd = GTK.InputDialog();
         inputd-&gt;close_button()-&gt;signal_connect("clicked",inputd-&gt;hide, 0);
         inputd-&gt;save_button()-&gt;hide();
         inputd-&gt;show();
       }
       else
         inputd-&gt;show();
     }

GTK.InputDialog() ../images/gtk_inputdialog.png

Signals: disable_device his signal is emitted when the user changes the mode of a device from a GDK_MODE_SCREEN or GDK_MODE_WINDOW to GDK_MODE_ENABLED

enable_device This signal is emitted when the user changes the mode of a device from GDK_MODE_DISABLED to a GDK_MODE_SCREEN or GDK_MODE_WINDOW.

GTK.Dialog

Create a new input dialog window.

GTK.InputDialog

The 'close' button of the dialog.

GTK.Button

The 'save' button of the dialog.

GTK.Button

Statusbars are simple widgets used to display a text message. They keep a stack of the messages pushed onto them, so that popping the current message will re-display the previous text message.

In order to allow different parts of an application to use the same statusbar to display messages, the statusbar widget issues Context Identifiers which are used to identify different 'users'. The message on top of the stack is the one displayed, no matter what context it is in. Messages are stacked in last-in-first-out order, not context identifier order.

lambda() {object sb = GTK.Statusbar();int id = sb->get_context_id("test");sb->push(id,"A message");sb->push(id,"Another message");return sb;}() ../images/gtk_statusbar.png

lambda() {object sb = GTK.Statusbar();int id = sb->get_context_id("test");sb->push(id,"A message");sb->push(id,"Another message");sb->pop(id);return sb;}() ../images/gtk_statusbar_2.png

Signals: text_poped

text_pushed

GTK.Hbox

Create a new statusbar widget

GTK.Statusbar

Create a new context id (or get the id of an old one). The argument is any string. The return value can be used for -&gt;push() -&gt;pop() and -&gt;remove later on.

Remove the topmost message.

GTK.Statusbar

Push a message onto the statusbar. The return value is an id that can be passed to remove later on.

Remove the specified message (the message id is the second argument).

GTK.Statusbar

A dialog is a window with a few default widgets added. The 'vbox' is the main content area of the widget. The 'action_area' is allocated for buttons (ok, cancel etc)

GTK.Window

Create a new dialog widget.

GTK.Dialog

The action area, this is where the buttons (ok, cancel etc) go

GTK.HbuttonBox

The vertical box that should contain the contents of the dialog

GTK.Vbox

The GTK.Adjustment object represents a value which has an associated lower and upper bound, together with step and page increments, and a page size. It is used within several GTK+ widgets, including GtkSpinButton, GtkViewport, and GtkRange (which is a base class for GtkHScrollbar, GtkVScrollbar, GtkHScale, and GtkVScale).

The GtkAdjustment object does not update the value itself. Instead it is left up to the owner of the GtkAdjustment to control the value.

The owner of the GtkAdjustment typically calls the value_changed() and changed() functions after changing the value or its bounds. This results in the emission of the "value_changed" or "changed" signal respectively.

Signals: changed The adjustment changed in some way

value_changed The value changed

GTK.Data

Call this when you have modified anything except the value member of the adjustment.

GTK.Adjustment

Updates the GTK.Adjustment value to ensure that the range between lower and upper is in the current page (i.e. between value and value + page_size). If the range is larger than the page size, then only the start of it will be in the current page. A "value_changed" signal will be emitted if the value is changed.

GTK.Adjustment

The value argument is the initial value you want to give to the adjustment, usually corresponding to the topmost or leftmost position of an adjustable widget. The lower argument specifies the lowest value which the adjustment can hold. The step_increment argument specifies the "smaller" of the two increments by which the user can change the value, while the page_increment is the "larger" one. The page_size argument usually corresponds somehow to the visible area of a panning widget. The upper argument is used to represent the bottom most or right most coordinate in a panning widget's child. Therefore it is not always the largest number that value can take, since the page_size of such widgets is usually non-zero.

All values are optional, they default to 0.0. For most widgets the unit is pixels.

GTK.Adjustment

Get the lower limit

Get the page increment (page down or through click)

Get the page size (the actual size of a page)

Get the step increment (arrow click)

get the upper limit.

Get the value component.

Set the lower limit.

Set the page increment (page down or through click)

Set the page size (the actual size of a page)

Set the step increment (arrow click)

Set the upper limit.

Set the value component.

GTK.Adjustment

Together with W(Plug), GTK.Socket provides the ability to embed widgets from one process into another process in a fashion that is transparent to the user. One process creates a GTK.Socket widget and, passes the XID of that widget's window to the other process, which then creates a W(Plug) window with that XID. Any widgets contained in the W(Plug) then will appear inside the first applications window.

Note that if you pass the XID of the socket to another process that will create a plug in the socket, you must make sure that the socket widget is not destroyed until that plug is created. Violating this rule will cause unpredictable consequences, the most likely consequence being that the plug will appear as a separate toplevel window.

A socket can also be used to swallow arbitrary pre-existing top-level windows using steal(), though the integration when this is done will not be as close as between a W(Plug) and a GTK.Socket.

GTK.Container
GTK.Socket

return 1 if the widow contained in this socket comes from this process.

Returns true if this socket is occupied

Returns the window id, to be sent to the application providing the plug. You must realize this widget before calling this function.

Reparents a pre-existing toplevel window (not nessesarily a GTK window) into a socket.

GTK.Socket
GTK.DrawingArea
GTK.GLArea
GTK.GLArea
GTK.GLArea
GTK.GLArea
GTK.GLArea

Pixmaps are data structures that contain pictures. These pictures can be used in various places, but most visibly as icons on the X-Windows desktop, or as cursors. A bitmap is a 2-color pixmap.

To use pixmaps in GTK, you must first build a GDK.Pixmap object using GDK.Pixmap.

The pixels in a GTK.Pixmap cannot be manipulated by the application after creation, since under the X Window system the pixel data is stored on the X server and so is not available to the client application. If you want to create graphical images which can be manipulated by the application, look at W(Image).

GTK.Pixmap( GDK.Pixmap( Image.image(100,100)->test()) ) ../images/gtk_pixmap.png

GTK.Pixmap( GDK.Pixmap( Image.image(100,100)->test()), GDK.Bitmap(Image.image(100,100,255,255,255)->box(10,10,80,80, 0,0,0) )) ../images/gtk_pixmap_2.png

GTK.Misc

Create a new pixmap object, and sets the image and the mask.

GDK.Pixmap
GDK.Bitmap
GTK.Pixmap

Returns ([ "pixmap":pixmap, "mask":mask, "pixmap_insensitive":insensitive version of the pixmap ])

Sets the GDK.Pixmap image and the optinal GDK.Bitmap mask

GDK.Pixmap
GDK.Bitmap
GTK.Pixmap

Set to TRUE if an extra pixmap should be automatically created to use when the pixmap is insensitive.

GTK.Pixmap

Set the pixmap to use when the pixmap is insensitive.

GDK.Pixmap
GTK.Pixmap

Ruler widgets are used to indicate the location of the mouse pointer in a given window. A window can have a vertical ruler spanning across the width and a horizontal ruler spanning down the height. A small triangular indicator on the ruler shows the exact location of the pointer relative to the ruler.

GTK.Hruler()->set_metric(GTK.PIXELS)->set_range(0.0,100.0,50.0,100.0)->draw_ticks()->draw_pos()->set_usize(300,30) ../images/gtk_hruler.png

GTK.Hruler()->set_metric(GTK.CENTIMETERS)->set_range(0.0,100.0,50.0,100.0)->draw_ticks()->draw_pos()->set_usize(300,30) ../images/gtk_hruler_2.png

GTK.Hruler()->set_usize(300,30) ../images/gtk_hruler_3.png

GTK.Ruler

Used to create a new hruler widget.

GTK.Hruler

The GTK.Misc widget is an abstract widget which is not useful itself, but is used to derive subclasses which have alignment and padding attributes.

The horizontal and vertical padding attributes allows extra space to be added around the widget.

The horizontal and vertical alignment attributes enable the widget to be positioned within its allocated area. Note that if the widget is added to a container in such a way that it expands automatically to fill its allocated area, the alignment settings will not alter the widgets position.

GTK.Vbox(0,0)->add(GTK.Label("Label"))->set_usize(100,20) ../images/gtk_misc.png

GTK.Vbox(0,0)->add(GTK.Label("Label")->set_alignment(1.0,0.0))->set_usize(100,20) ../images/gtk_misc_2.png

GTK.Vbox(0,0)->add(GTK.Label("Label")->set_alignment(0.0,0.0))->set_usize(100,20) ../images/gtk_misc_3.png

GTK.Widget

The horizontal alignment, from 0 (left) to 1 (right).

The amount of space to add on the left and right of the widget, in pixels.

The vertical alignment, from 0 (top) to 1 (botton).

The amount of space to add on the top and bottom of the widget, in pixels.

Sets the alignment of the widget. 0.0 is left or topmost, 1.0 is right or bottommost.

GTK.Misc

Sets the amount of space to add around the widget. xpand and ypad are specified in pixels.

GTK.Misc

Use this widget when you want the user to input a single line of text. GTK.Entry()->set_text("Hello world")->set_editable(1) ../images/gtk_entry.png

GTK.Editable

Append the specified string at the end of the entry

GTK.Entry
GTK.Entry

Returns the contents of the entry widget.

Prepend the specified string to the start of the entry

GTK.Entry

text is truncated if needed

GTK.Entry

Set the text to the specified string. The old text is dropped.

GTK.Entry

0 indicates invisible text (password boxes, as an example)

GTK.Entry

GtkDatabox is designed to display large amounts of numerical data fast and easy. Thousands of data points (X and Y coordinate) may be displayed without any problems, zooming and scrolling as well as optional rulers are already included.

The widget may be used as display for oscilloscopes or other applications that need to display fast changes in their data.

GTK.Databox x=GTK.Databox(); x->data_add_x_y(3, ({ 1.0, 0.5, 0.0 }), ({1.0, -1.0, 0.0}),GDK.Color(Image.Color.red), GTK.DataboxLines,2); x->rescale(); x->set_usize(300,300); return x; ../images/gtk_databox.png

Signals: marked

selection_canceled

selection_changed

selection_started

selection_stopped

zoomed

GTK.Vbox

Create a new databox widget

GTK.Databox

Type is one of DATABOX_BARS, DATABOX_LINES, DATABOX_NOT_DISPLAYED and DATABOX_POINTS

GDK.Color

Type is one of DATABOX_BARS, DATABOX_LINES, DATABOX_NOT_DISPLAYED and DATABOX_POINTS

GDK.Color

Type is one of DATABOX_BARS, DATABOX_LINES, DATABOX_NOT_DISPLAYED and DATABOX_POINTS

GDK.Color
GTK.Databox
GTK.Databox
GTK.Databox
GTK.Databox
GTK.Databox
GTK.Databox
GTK.Databox
GDK.Color

Type is one of DATABOX_BARS, DATABOX_LINES, DATABOX_NOT_DISPLAYED and DATABOX_POINTS

GTK.Databox
GTK.Databox
GTK.Databox

The GTK.Scale widget is an abstract class, used only for deriving the subclasses GTK.Hscale and GTK.Vscale.

See W(Range) for generic range documentation

GTK.Range

non-zero if the scale's current value is displayed next to the slider.

The position in which the textual value is displayed, selected from POS_BOTTOM, POS_LEFT, POS_RIGHT and POS_TOP

An internal function used to get the maximum width needed to display the value string. Not normaly used by applications.

Sets the number of decimal places that are displayed in the value.

GTK.Scale

Specifies whether the current value is displayed as a string next to the slider.

GTK.Scale

Sets the position in which the current value is displayed. One of POS_BOTTOM, POS_LEFT, POS_RIGHT and POS_TOP

GTK.Scale

A check menu item is more or less identical to a check button, but it should be used in menus. GTK.CheckMenuItem("Hi there") ../images/gtk_checkmenuitem.png

GTK.CheckMenuItem("Hi there")->set_active(1) ../images/gtk_checkmenuitem_2.png

Signals: toggled Called when the state of the menu item is changed

GTK.MenuItem

The argument, if specified, is the label of the item. If no label is specified, use object->add() to add some other widget (such as an pixmap or image widget)

GTK.CheckMenuItem

State is either 1 or 0. If 1, the button will be 'pressed'.

GTK.CheckMenuItem

If true, the toggle indicator will be shown

GTK.CheckMenuItem

Emulate a toggled event

GTK.CheckMenuItem

A gamma curve widget.. Rather complex.

Lets the user edit a gamma curve (a one-to-one mapping usually used to adjust the intensity of an image to the physical characteristics of the output device). You can set the minimum and maximum values for input and output. You can set the initial vector as well. You are guaranteed that every input value will have a (not necessarily unique) output value specified.

GTK.GammaCurve()->set_usize(210,130) ../images/gtk_gammacurve.png

GTK.Vbox

Create a new gamma curve

GTK.GammaCurve

The actual curve

GTK.Curve

The current gamma value

Simply creates a horizontal separator. No bells or whistles. GTK.Hseparator()->set_usize(300,3) ../images/gtk_hseparator.png

GTK.Separator

Used to create a new hseparator widget.

GTK.Hseparator

A container that can only contain one child.

GTK.Container

Returns the (one and only) child of this container.

GTK.Widget

An invisible container, useful, eh? :)

GTK.Bin

Create a new invisible widget

GTK.Invisible

GtkFileSelection should be used to retrieve file or directory names from the user. It will create a new dialog window containing a directory list, and a file list corresponding to the current working directory. The filesystem can be navigated using the directory list, the drop-down history menu, or the TAB key can be used to navigate using filename completion common in text based editors such as emacs and jed.

The default filename can be set using set_filename() and the selected filename retrieved using get_filename().

Use complete() to display files that match a given pattern. This can be used for example, to show only *.txt files, or only files beginning with gtk*.

Simple file operations; create directory, delete file, and rename file, are available from buttons at the top of the dialog. These can be hidden using hide_fileop_buttons() and shown again using show_fileop_buttons().

GTK.FileSelection("File selector") ../images/gtk_fileselection.png

GTK.Window

Will attempt to match pattern to a valid filename in the current directory. If a match can be made, the matched filename will appear in the text entry field of the file selection dialog. If a partial match can be made, the "Files" list will contain those file names which have been partially matched.

GTK.FileSelection

Creates a new file selection dialog box. By default it will list the files in the current working directory. Operation buttons allowing the user to create a directory, delete files, and rename files will also be present by default.

GTK.FileSelection

The cancel button

GTK.Button

The list of directories

GTK.Clist

The list of files

GTK.Clist

Returns the currently entered filename as a string

The create directory button in the file operation button group

GTK.Button

The delete file button in the file operation button group

GTK.Button

The rename file button in the file operation button group

GTK.Button

The help button

GTK.Button

Used to create the drop-down directory histor

GTK.OptionMenu

The ok button

GTK.Button

Hides the file operation buttons that normally appear at the top of the dialog. Useful if you wish to create a custom file selector, based on GTK.FileSelection.

GTK.FileSelection

Sets a default path for the file requestor. If filename includes a directory path, then the requestor will open with that path as its current working directory.

GTK.FileSelection

Shows the file operation buttons, if they have previously been hidden. The rest of the widgets in the dialog will be resized accordingly.

GTK.FileSelection

A Vbutton_box is very similar to a Vbox. The major diffference is that the button box is made to pack buttons in, and has a few convenience function for normal button layouts.

GTK.VbuttonBox()->add(GTK.Button("Hello"))->add(GTK.Button("World"))->set_usize(100,300) ../images/gtk_vbuttonbox.png

GTK.VbuttonBox()->add(GTK.Button("Hello"))->add(GTK.Button("World"))->set_layout(GTK.BUTTONBOX_SPREAD)->set_usize(100,300) ../images/gtk_vbuttonbox_2.png

GTK.VbuttonBox()->add(GTK.Button("Hello"))->add(GTK.Button("World"))->set_layout(GTK.BUTTONBOX_EDGE)->set_usize(100,300) ../images/gtk_vbuttonbox_3.png

GTK.VbuttonBox()->add(GTK.Button("Hello"))->add(GTK.Button("World"))->set_layout(GTK.BUTTONBOX_START)->set_usize(100,300) ../images/gtk_vbuttonbox_4.png

GTK.VbuttonBox()->add(GTK.Button("Hello"))->add(GTK.Button("World"))->set_layout(GTK.BUTTONBOX_END)->set_usize(100,300) ../images/gtk_vbuttonbox_5.png

GTK.ButtonBox

Create a new vertical button box

GTK.VbuttonBox
GTKSupport

Special corba main loop for gnome panel applets

Exit from the applet_widget_gtk_main function on the next iteration.

Always returns false.

Flush GDK. Not normally needed, can be useful while doing calculations.

Initializes the application. This sets up all of the GNOME internals and prepares them (imlib, gdk/gtk, session-management, triggers, sound, user preferences). If corba init flags are specified, corba initialization is done as well as gnome initialization. corba_init_flags is 0 or more of GNORBA_INIT_SERVER_FUNC (1), GNORBA_INIT_DISABLE_COOKIES (2) and GNORBA_INIT_CORBA_PRIO_HIGH (4)

GTK.Widget
GTK.Widget

Low level GTK init function (used by setup_gtk). This function is more or less equivalent to the C-GTK+ function gtk_init. setup_gtk does some extra things (such as parsing ~/.pgtkrc).

Flush, but do not process events. Not normally needed.

Start GTK in blocking mode. Doing this disables asynchronous I/O in pike. You can return -1 from main in pike to run GTK (and the rest of pike) in asynchrounous mode.

Run one iteration in the mainloop. If block is true, wait for an event before returning.

Return the current recursion depth.

Exit from the gtk_main function on the next iteration.

Takes a string and reads it as a gtkrc file.

Returns the root window of the current display

GDK.Window

Initialize GTK, and all that comes with it. Also parses $HOME/.pgtkrc and $HOME/.gtkrc if they exists. The single argument, if supplied, is the argument array passed to the program. This is used to set default window titles etc. The second argument, if supplied, indicates that pike specific *rc files should not be parsed.

The most common usage is GTK.setup_gtk(argv);

Always returns true.

These are your standard, run-of-the-mill scrollbars. These should be used only for scrolling some other widget, such as a list, a text box, or a viewport (and it's generally easier to use the scrolled window widget in most cases). For other purposes, you should use scale widgets, as they are friendlier and more featureful.

GTK.Range

The GTK.VScale widget is used to allow the user to select a value using a vertical slider. A GtkAdjustment is used to set the initial value, the lower and upper bounds, and the step and page increments.

The position to show the current value, and the number of decimal places shown can be set using the parent W(Scale) class's functions.

GTK.Vscale(GTK.Adjustment())->set_usize(30,100) ../images/gtk_vscale.png

GTK.Scale

Used to create a new vscale widget. The adjustment argument can either be an existing W(Adjustment), or 0, in which case one will be created for you. Specifying 0 might actually be useful in this case, if you wish to pass the newly automatically created adjustment to the constructor function of some other widget which will configure it for you, such as a text widget.

GTK.Adjustment
GTK.Vscale

A box is a container that can contain more than one child. The basic 'Box' class cannot be instantiated, it is a virtual class that only defines some common 'Box' functions shared with all other Box widgets.

GTK.Container

Pack from the right (or bottom) of the box. Arguments are widget, expand, fill, paddingb widget, expand, fill, padding

GTK.Widget
GTK.Box

The argument is the widget to add.

GTK.Widget
GTK.Box

Pack from the left (or top) of the box. Argument are widget, expand, fill, padding pack(widget,1,1,0) is equivalent to 'add' or 'pack_start_defaults'

GTK.Widget
GTK.Box

The argument is the widget to add. This function is equivalent to 'add'

GTK.Widget
GTK.Box

Return a mapping: ([ "expand":expandp, "fill":fillp, "padding":paddingp, "type":type ])

GTK.Widget

Move widget to pos, pos is an integer, between 0 and sizeof(box->children())-1

GTK.Widget
GTK.Box

widget, expand, fill, padding, pack_type. If exand is true, the widget will be expanded when the box is resized. If 'fill' is true, the widget will be resized to fill up all available space. Padding is the amount of padding to use, and pack_type is one of PACK_END, PACK_EXPAND and PACK_START.

You can emulate pack_start and pack_end with add and set_child_packing.

GTK.Widget
GTK.Box

If true, all widgets in the box will get exactly the same amount of space

GTK.Box

This is the amount of spacing (in pixels) inserted beween all widgets

GTK.Box

The data associated with a selection.

Returns the selection in the data. The return value is always a string, but the width can vary (8, 16 or 32 bits per character).

Returns the selction format. The format is the number of bits per character.

Return the size of the selection data, in bytes.

The size of the data in characters (as returned by data()) is not necessarily the same.

The selection id, as a GDK(Atom).

GDK.Atom

Store new data into a GtkSelectionData object. Should _only_ by called from a selection handler callback.

GTK.SelectionData

The target, as a GDK(Atom).

GDK.Atom

The selection type, as a GDK(Atom).

GDK.Atom

A simple text label. GTK.Label("A simple text label") ../images/gtk_label.png

GTK.Label("Multi\nline text\nlabel here") ../images/gtk_label_2.png

GTK.Label("Multi\nline text\nlabel here")->set_justify(GTK.JUSTIFY_LEFT) ../images/gtk_label_3.png

GTK.Label("Multi\nline text\nlabel here")->set_justify(GTK.JUSTIFY_RIGHT) ../images/gtk_label_4.png

GTK.Misc

Creates a new label.

GTK.Label

Convenience function to set the text and pattern by parsing a string with embedded underscores, returns the appropriate key symbol for the accelerator.

DEPRECATED Compatibility function to set the text in the label. Use set_text. This function can dissapear in the future.

GTK.Label

one of JUSTIFY_CENTER, JUSTIFY_FILL, JUSTIFY_LEFT and JUSTIFY_RIGHT

GTK.Label

Should the label autolinewrap?

GTK.Label

A string with either spaces or underscores. It should be of the same length as the text.

When a character in the text has a matching _ in the pattern, the character in the label will be underlined.

GTK.Label

Set the text in the label

GTK.Label

An image is a image object stored in client, not X server, memory. A pixmap, on the other hand, is a image object stored in the X-server. See GDK.Image and GDK.Pixmap.

GTK.Image( GDK.Image(0)->set(Image.image(200,200)->test() ) ); ../images/gtk_image.png

GTK.Misc

You can skip the mask. The mask is used to mask the drawing of the image on it's background. It will not make the container transparent, though. Use shape_combine_mask on the container with the mask for that.

GDK.Image
GDK.Bitmap
GTK.Image

Returns ([ "image":GDK.Image img, "mask":GDK.Bitmap mask ])

Args: GDK.Image and GDK.Bitmap, respectively. You can skip the mask. The mask is used to mask the drawing of the image on it's background. It will not make the container transparent, though. Use shape_combine_mask on the container with the mask for that.

There is no need to call 'set' with the same GDK.Image again if you have modified the image. You must, however, use -&gt;queue_draw() to redraw the image. Otherwise the old contens will be shown until an refresh of the widget is done for any other reason.

GDK.Image
GDK.Bitmap
GTK.Image

Set the background of the specified window (or the subarea indicated by the rectangle) to the default background for the state specified by state_type.

If set_bgp is true, the background of the widget will be set, otherwise it will only be drawn into the window.

GDK.Window
GDK.Rectangle
GTK.Style

Attach a style to a window; this process allocates the colors and creates the GC's for the style - it specializes it to a particular visual and colormap. The process may involve the creation of a new style if the style has already been attached to a window with a different style and colormap.

GDK.Window
GTK.Style

Copy this style, and return the new style object

GTK.Style
GTK.Style

Undo a previous attach

GTK.Style
GDK.Color
GDK.GC
GDK.Font
GDK.Color
GDK.GC

The color selection dialog widget is, not surprisingly, a color selection widget in a dialog window. Use the subwidget functions below to access the different subwidgets directly.

GTK.ColorSelectionDialog("Select color") ../images/gtk_colorselectiondialog.png

Signals: color_changed Called when the color is changed

GTK.Window

Create a new color selection dialog with the specified title.

GTK.ColorSelectionDialog

Return the cancel button widget.

GTK.Button

Return the color selection widget

GTK.ColorSelection

Return the help button

GTK.Button

Return the ok button

GTK.Button

Not implemented OpenGL methods:

glAreTexturesResident glBitmap glBlendColorEXT glCallLists glColorPointer glDeleteTextures glDrawElements glEdgeFlagPointer glEdgeFlagv glEvalMesh glFeedbackBuffer glGenTextures glGetBooleanv glGetClipPlane glGetDoublev glGetFloatv glGetIntegerv glGetLight glGetMap glGetMaterial glGetPixelMap glGetPointerv glGetPolygonStipple glGetTexEnv glGetTexGen glGetTexImage glGetTexLevelParameter glGetTexParameter glIndexPointer glInterleavedArrays glMap1 glMap2 glMapGrid glNormalPointer glPixelMap glPixelStore glPixelTransfer glPolygonStipple glPrioritizeTextures glReadPixels glRect glSelectBuffer glTexCoordPointer glTexImage1D glTexSubImage1D glVertexPointer

The accumulation buffer is an extended-range color buffer. Images are not rendered into it. Rather, images rendered into one of the color buffers are added to the contents of the accumulation buffer after rendering. Effects such as antialiasing (of points, lines, and polygons), motion blur, and depth of field can be created by accumulating images generated with different transformation matrices.

Each pixel in the accumulation buffer consists of red, green, blue, and alpha values. The number of bits per component in the accumulation buffer depends on the implementation. You can examine this number by calling glGetIntegerv four times, with arguments GL_ACCUM_RED_BITS, GL_ACCUM_GREEN_BITS, GL_ACCUM_BLUE_BITS, and GL_ACCUM_ALPHA_BITS. Regardless of the number of bits per component, the range of values stored by each component is [-1, 1]. The accumulation buffer pixels are mapped one-to-one with frame buffer pixels.

glAccum operates on the accumulation buffer. The first argument, op, is a symbolic constant that selects an accumulation buffer operation. The second argument, value, is a floating-point value to be used in that operation. Five operations are specified: GL_ACCUM, GL_LOAD, GL_ADD, GL_MULT, and GL_RETURN.

All accumulation buffer operations are limited to the area of the current scissor box and applied identically to the red, green, blue, and alpha components of each pixel. If a glAccum operation results in a value outside the range [-1, 1], the contents of an accumulation buffer pixel component are undefined.

The operations are as follows:

GL_ACCUM Obtains R, G, B, and A values from the buffer currently selected for reading (see glReadBuffer). Each component value is divided by 2n1, where n is the number of bits allocated to each color component in the currently selected buffer. The result is a floating-point value in the range [0, 1], which is multiplied by value and added to the corresponding pixel component in the accumulation buffer, thereby updating the accumulation buffer. GL_LOAD Similar to GL_ACCUM, except that the current value in the accumulation buffer is not used in the calculation of the new value. That is, the R, G, B, and A values from the currently selected buffer are divided by 2n1, multiplied by value, and then stored in the corresponding accumulation buffer cell, overwriting the current value. GL_ADD Adds value to each R, G, B, and A in the accumulation buffer. GL_MULT Multiplies each R, G, B, and A in the accumulation buffer by value and returns the scaled component to its corresponding accumulation buffer location. GL_RETURN Transfers accumulation buffer values to the color buffer or buffers currently selected for writing. Each R, G, B, and A component is multiplied by value, then multiplied by 2n1, clamped to the range [0, 2n1 ], and stored in the corresponding display buffer cell. The only fragment operations that are applied to this transfer are pixel ownership, scissor, dithering, and color writemasks.

To clear the accumulation buffer, call glClearAccum with R, G, B, and A values to set it to, then call glClear with the accumulation buffer enabled.

Specifies the accumulation buffer operation. Symbolic constants GL_ACCUM, GL_LOAD, GL_ADD, GL_MULT, and GL_RETURN are accepted.

Specifies a floating-point value used in the accumulation buffer operation. op determines how value is used.

GL_INVALID_ENUM is generated if op is not an accepted value.

GL_INVALID_OPERATION is generated if there is no accumulation buffer.

GL_INVALID_OPERATION is generated if glAccum is executed between the execution of glBegin and the corresponding execution of glEnd.

The alpha test discards fragments depending on the outcome of a comparison between an incoming fragment's alpha value and a constant reference value. glAlphaFunc specifies the reference value and the comparison function. The comparison is performed only if alpha testing is enabled. By default, it is not enabled. (See glEnable and glDisable of GL_ALPHA_TEST.)

func and ref specify the conditions under which the pixel is drawn. The incoming alpha value is compared to ref using the function specified by func. If the value passes the comparison, the incoming fragment is drawn if it also passes subsequent stencil and depth buffer tests. If the value fails the comparison, no change is made to the frame buffer at that pixel location. The comparison functions are as follows:

GL_NEVER Never passes. GL_LESS Passes if the incoming alpha value is less than the reference value. GL_EQUAL Passes if the incoming alpha value is equal to the reference value. GL_LEQUAL Passes if the incoming alpha value is less than or equal to the reference value. GL_GREATER Passes if the incoming alpha value is greater than the reference value. GL_NOTEQUAL Passes if the incoming alpha value is not equal to the reference value. GL_GEQUAL Passes if the incoming alpha value is greater than or equal to the reference value. GL_ALWAYS Always passes (initial value).

glAlphaFunc operates on all pixel write operations, including those resulting from the scan conversion of points, lines, polygons, and bitmaps, and from pixel draw and copy operations. glAlphaFunc does not affect screen clear operations.

Specifies the alpha comparison function. Symbolic constants GL_NEVER, GL_LESS, GL_EQUAL, GL_LEQUAL, GL_GREATER, GL_NOTEQUAL, GL_GEQUAL, and GL_ALWAYS are accepted. The initial value is GL_ALWAYS.

Specifies the reference value that incoming alpha values are compared to. This value is clamped to the range 0 through 1, where 0 represents the lowest possible alpha value and 1 the highest possible value. The initial reference value is 0.

GL_INVALID_ENUM is generated if func is not an accepted value.

GL_INVALID_OPERATION is generated if glAlphaFunc is executed between the execution of glBegin and the corresponding execution of glEnd.

glArrayElement commands are used within glBegin/glEnd pairs to specify vertex and attribute data for point, line, and polygon primitives. If GL_VERTEX_ARRAY is enabled when glArrayElement is called, a single vertex is drawn, using vertex and attribute data taken from location i of the enabled arrays. If GL_VERTEX_ARRAY is not enabled, no drawing occurs but the attributes corresponding to the enabled arrays are modified.

Use glArrayElement to construct primitives by indexing vertex data, rather than by streaming through arrays of data in first-to-last order. Because each call specifies only a single vertex, it is possible to explicitly specify per-primitive attributes such as a single normal per individual triangle.

Changes made to array data between the execution of glBegin and the corresponding execution of glEnd may affect calls to glArrayElement that are made within the same glBegin/glEnd period in non-sequential ways. That is, a call to

glArrayElement that precedes a change to array data may access the changed data, and a call that follows a change to array data may access original data.

Specifies an index into the enabled vertex data arrays.

glBindTexture lets you create or use a named texture. Calling glBindTexture with

target set to GL_TEXTURE_1D or GL_TEXTURE_2D and texture set to the name of the newtexture binds the texture name to the target. When a texture is bound to a target, the previous binding for that target is automatically broken.

Texture names are unsigned integers. The value zero is reserved to represent the default texture for each texture target. Texture names and the corresponding texture contents are local to the shared display-list space (see glXCreateContext) of the current GL rendering context; two rendering contexts share texture names only if they also share display lists.

You may use glGenTextures to generate a set of new texture names.

When a texture is first bound, it assumes the dimensionality of its target: A texture first bound to GL_TEXTURE_1D becomes 1-dimensional and a texture first bound to GL_TEXTURE_2D becomes 2-dimensional. The state of a 1-dimensional texture immediately after it is first bound is equivalent to the state of the default GL_TEXTURE_1D at GL initialization, and similarly for 2-dimensional textures.

While a texture is bound, GL operations on the target to which it is bound affect the bound texture, and queries of the target to which it is bound return state from the bound texture. If texture mapping of the dimensionality of the target to which a texture is bound is active, the bound texture is used. In effect, the texture targets become aliases for the textures currently bound to them, and the texture name zero refers to the default textures that were bound to them at initialization.

A texture binding created with glBindTexture remains active until a different texture is bound to the same target, or until the bound texture is deleted with glDeleteTextures.

Once created, a named texture may be re-bound to the target of the matching dimensionality as often as needed. It is usually much faster to use glBindTexture to bind an existing named texture to one of the texture targets than it is to reload the texture image using glTexImage1D or glTexImage2D. For additional control over performance, use glPrioritizeTextures.

glBindTexture is included in display lists.

Specifies the target to which the texture is bound. Must be either GL_TEXTURE_1D or GL_TEXTURE_2D.

Specifies the name of a texture.

GL_INVALID_ENUM is generated if target is not one of the allowable values.

GL_INVALID_OPERATION is generated if texture has a dimensionality which doesn't match that of target.

GL_INVALID_OPERATION is generated if glBindTexture is executed between the execution of glBegin and the corresponding execution of glEnd.

In RGBA mode, pixels can be drawn using a function that blends the incoming (source) RGBA values with the RGBA values that are already in the frame buffer (the destination values). Blending is initially disabled. Use glEnable and glDisable with argument GL_BLEND to enable and disable blending.

glBlendFunc defines the operation of blending when it is enabled. sfactor specifies which of nine methods is used to scale the source color components. dfactor specifies which of eight methods is used to scale the destination color components. The eleven possible methods are described in the following table. Each method defines four scale factors, one each for red, green, blue, and alpha.

In the table and in subsequent equations, source and destination color components are referred to as (R sub s , G sub s , B sub s , A sub s ) and (R sub d , G sub d , B sub d , A sub d ). They are understood to have integer values between 0 and (k sub R , k sub G , k sub B , k sub A ), where

.RS .ce k sub c ~=~ 2 sup m sub c - 1 .RE

and (m sub R , m sub G , m sub B , m sub A ) is the number of red, green, blue, and alpha bitplanes.

Source and destination scale factors are referred to as (s sub R , s sub G , s sub B , s sub A ) and (d sub R , d sub G , d sub B , d sub A ). The scale factors described in the table, denoted (f sub R , f sub G , f sub B , f sub A ), represent either source or destination factors. All scale factors have range [0,1].

.TS center box ; ci | ci c | c . parameter (f sub R , ~~ f sub G , ~~ f sub B , ~~ f sub A ) = GL_ZERO (0, ~0, ~0, ~0 ) GL_ONE (1, ~1, ~1, ~1 ) GL_SRC_COLOR (R sub s / k sub R , ~G sub s / k sub G , ~B sub s / k sub B , ~A sub s / k sub A ) GL_ONE_MINUS_SRC_COLOR (1, ~1, ~1, ~1 ) ~-~ (R sub s / k sub R , ~G sub s / k sub G , ~B sub s / k sub B , ~A sub s / k sub A ) GL_DST_COLOR (R sub d / k sub R , ~G sub d / k sub G , ~B sub d / k sub B , ~A sub d / k sub A ) GL_ONE_MINUS_DST_COLOR (1, ~1, ~1, ~1 ) ~-~ (R sub d / k sub R , ~G sub d / k sub G , ~B sub d / k sub B , ~A sub d / k sub A ) GL_SRC_ALPHA (A sub s / k sub A , ~A sub s / k sub A , ~A sub s / k sub A , ~A sub s / k sub A ) GL_ONE_MINUS_SRC_ALPHA (1, ~1, ~1, ~1 ) ~-~ (A sub s / k sub A , ~A sub s / k sub A , ~A sub s / k sub A , ~A sub s / k sub A ) GL_DST_ALPHA (A sub d / k sub A , ~A sub d / k sub A , ~A sub d / k sub A , ~A sub d / k sub A ) GL_ONE_MINUS_DST_ALPHA (1, ~1, ~1, ~1 ) ~-~ (A sub d / k sub A , ~A sub d / k sub A , ~A sub d / k sub A , ~A sub d / k sub A ) GL_SRC_ALPHA_SATURATE (i, ~i, ~i, ~1 ) .TE .sp In the table,

.RS .nf

i ~=~ min (A sub s , ~k sub A - A sub d ) ~/~ k sub A .fi .RE

To determine the blended RGBA values of a pixel when drawing in RGBA mode, the system uses the following equations:

.RS .nf

R sub d ~=~ min ( k sub R , ~~ R sub s s sub R + R sub d d sub R ) G sub d ~=~ min ( k sub G , ~~ G sub s s sub G + G sub d d sub G ) B sub d ~=~ min ( k sub B , ~~ B sub s s sub B + B sub d d sub B ) A sub d ~=~ min ( k sub A , ~~ A sub s s sub A + A sub d d sub A ) .fi .RE

Despite the apparent precision of the above equations, blending arithmetic is not exactly specified, because blending operates with imprecise integer color values. However, a blend factor that should be equal to 1 is guaranteed not to modify its multiplicand, and a blend factor equal to 0 reduces its multiplicand to 0. For example, when sfactor is GL_SRC_ALPHA, dfactor is GL_ONE_MINUS_SRC_ALPHA, and A sub s is equal to k sub A, the equations reduce to simple replacement:

.RS .nf

R sub d ~=~ R sub s G sub d ~=~ G sub s B sub d ~=~ B sub s A sub d ~=~ A sub s .fi .RE

Specifies how the red, green, blue, and alpha source blending factors are computed. Nine symbolic constants are accepted: GL_ZERO, GL_ONE, GL_DST_COLOR, GL_ONE_MINUS_DST_COLOR, GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA, GL_DST_ALPHA, GL_ONE_MINUS_DST_ALPHA, and GL_SRC_ALPHA_SATURATE. The initial value is GL_ONE.

Specifies how the red, green, blue, and alpha destination blending factors are computed. Eight symbolic constants are accepted: GL_ZERO, GL_ONE, GL_SRC_COLOR, GL_ONE_MINUS_SRC_COLOR, GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA, GL_DST_ALPHA, and GL_ONE_MINUS_DST_ALPHA. The initial value is GL_ZERO.

GL_INVALID_ENUM is generated if either sfactor or dfactor is not an accepted value.

GL_INVALID_OPERATION is generated if glBlendFunc is executed between the execution of glBegin and the corresponding execution of glEnd.

glCallList causes the named display list to be executed. The commands saved in the display list are executed in order, just as if they were called without using a display list. If list has not been defined as a display list, glCallList is ignored.

glCallList can appear inside a display list. To avoid the possibility of infinite recursion resulting from display lists calling one another, a limit is placed on the nesting level of display lists during display-list execution. This limit is at least 64, and it depends on the implementation.

GL state is not saved and restored across a call to glCallList. Thus, changes made to GL state during the execution of a display list remain after execution of the display list is completed. Use glPushAttrib, glPopAttrib, glPushMatrix, and glPopMatrix to preserve GL state across glCallList calls.

Specifies the integer name of the display list to be executed.

glClear sets the bitplane area of the window to values previously selected by glClearColor, glClearIndex, glClearDepth, glClearStencil, and glClearAccum. Multiple color buffers can be cleared simultaneously by selecting more than one buffer at a time using glDrawBuffer.

The pixel ownership test, the scissor test, dithering, and the buffer writemasks affect the operation of glClear. The scissor box bounds the cleared region. Alpha function, blend function, logical operation, stenciling, texture mapping, and depth-buffering are ignored by glClear.

glClear takes a single argument that is the bitwise OR of several values indicating which buffer is to be cleared.

The values are as follows:

GL_COLOR_BUFFER_BIT Indicates the buffers currently enabled for color writing. GL_DEPTH_BUFFER_BIT Indicates the depth buffer. GL_ACCUM_BUFFER_BIT Indicates the accumulation buffer. GL_STENCIL_BUFFER_BIT Indicates the stencil buffer.

The value to which each buffer is cleared depends on the setting of the clear value for that buffer.

Bitwise OR of masks that indicate the buffers to be cleared. The four masks are GL_COLOR_BUFFER_BIT, GL_DEPTH_BUFFER_BIT, GL_ACCUM_BUFFER_BIT, and GL_STENCIL_BUFFER_BIT.

GL_INVALID_VALUE is generated if any bit other than the four defined bits is set in mask.

GL_INVALID_OPERATION is generated if glClear is executed between the execution of glBegin and the corresponding execution of glEnd.

glClearAccum specifies the red, green, blue, and alpha values used by glClear to clear the accumulation buffer.

Values specified by glClearAccum are clamped to the range [-1,1].

Specify the red, green, blue, and alpha values used when the accumulation buffer is cleared. The initial values are all 0.

GL_INVALID_OPERATION is generated if glClearAccum is executed between the execution of glBegin and the corresponding execution of glEnd.

glClearColor specifies the red, green, blue, and alpha values used by glClear to clear the color buffers. Values specified by glClearColor are clamped to the range [0,1].

Specify the red, green, blue, and alpha values used when the color buffers are cleared. The initial values are all 0.

GL_INVALID_OPERATION is generated if glClearColor is executed between the execution of glBegin and the corresponding execution of glEnd.

glClearDepth specifies the depth value used by glClear to clear the depth buffer. Values specified by glClearDepth are clamped to the range [0,1].

Specifies the depth value used when the depth buffer is cleared. The initial value is 1.

GL_INVALID_OPERATION is generated if glClearDepth is executed between the execution of glBegin and the corresponding execution of glEnd.

glClearIndex specifies the index used by glClear to clear the color index buffers. c is not clamped. Rather, c is converted to a fixed-point value with unspecified precision to the right of the binary point. The integer part of this value is then masked with 2 sup m -1, where m is the number of bits in a color index stored in the frame buffer.

Specifies the index used when the color index buffers are cleared. The initial value is 0.

GL_INVALID_OPERATION is generated if glClearIndex is executed between the execution of glBegin and the corresponding execution of glEnd.

glClearStencil specifies the index used by glClear to clear the stencil buffer. s is masked with 2 sup m - 1, where m is the number of bits in the stencil buffer.

Specifies the index used when the stencil buffer is cleared. The initial value is 0.

GL_INVALID_OPERATION is generated if glClearStencil is executed between the execution of glBegin and the corresponding execution of glEnd.

The GL stores both a current single-valued color index and a current four-valued RGBA color. If no alpha value has been give, 1.0 (full intensity) is implied.

Current color values are stored in floating-point format, with unspecified mantissa and exponent sizes. Unsigned integer color components, when specified, are linearly mapped to floating-point values such that the largest representable value maps to 1.0 (full intensity), and 0 maps to 0.0 (zero intensity). Signed integer color components, when specified, are linearly mapped to floating-point values such that the most positive representable value maps to 1.0, and the most negative representable value maps to -1.0. (Note that this mapping does not convert 0 precisely to 0.0.) Floating-point values are mapped directly.

Neither floating-point nor signed integer values are clamped to the range [0,1] before the current color is updated. However, color components are clamped to this range before they are interpolated or written into a color buffer.

Specify new red, green, and blue values for the current color.

Specifies a new alpha value for the current color.

glColorMask specifies whether the individual color components in the frame buffer can or cannot be written. If red is GL_FALSE, for example, no change is made to the red component of any pixel in any of the color buffers, regardless of the drawing operation attempted.

Changes to individual bits of components cannot be controlled. Rather, changes are either enabled or disabled for entire color components.

Specify whether red, green, blue, and alpha can or cannot be written into the frame buffer. The initial values are all GL_TRUE, indicating that the color components can be written.

GL_INVALID_OPERATION is generated if glColorMask is executed between the execution of glBegin and the corresponding execution of glEnd.

glColorMaterial specifies which material parameters track the current color. When GL_COLOR_MATERIAL is enabled, the material parameter or parameters specified by mode, of the material or materials specified by face, track the current color at all times.

To enable and disable GL_COLOR_MATERIAL, call glEnable and glDisable with argument GL_COLOR_MATERIAL. GL_COLOR_MATERIAL is initially disabled.

Specifies whether front, back, or both front and back material parameters should track the current color. Accepted values are GL_FRONT, GL_BACK, and GL_FRONT_AND_BACK. The initial value is GL_FRONT_AND_BACK.

Specifies which of several material parameters track the current color. Accepted values are GL_EMISSION, GL_AMBIENT, GL_DIFFUSE, GL_SPECULAR, and GL_AMBIENT_AND_DIFFUSE. The initial value is GL_AMBIENT_AND_DIFFUSE.

GL_INVALID_ENUM is generated if face or mode is not an accepted value.

GL_INVALID_OPERATION is generated if glColorMaterial is executed between the execution of glBegin and the corresponding execution of glEnd.

glCopyPixels copies a screen-aligned rectangle of pixels from the specified frame buffer location to a region relative to the current raster position. Its operation is well defined only if the entire pixel source region is within the exposed portion of the window. Results of copies from outside the window, or from regions of the window that are not exposed, are hardware dependent and undefined.

x and y specify the window coordinates of the lower left corner of the rectangular region to be copied. width and height specify the dimensions of the rectangular region to be copied. Both width and height must not be negative.

Several parameters control the processing of the pixel data while it is being copied. These parameters are set with three commands: glPixelTransfer, glPixelMap, and glPixelZoom. This reference page describes the effects on glCopyPixels of most, but not all, of the parameters specified by these three commands.

glCopyPixels copies values from each pixel with the lower left-hand corner at (x + i, y + j) for 0\(<=i<width and 0\(<=j<height. This pixel is said to be the ith pixel in the jth row. Pixels are copied in row order from the lowest to the highest row, left to right in each row.

type specifies whether color, depth, or stencil data is to be copied. The details of the transfer for each data type are as follows:

GL_COLOR Indices or RGBA colors are read from the buffer currently specified as the read source buffer (see glReadBuffer). If the GL is in color index mode, each index that is read from this buffer is converted to a fixed-point format with an unspecified number of bits to the right of the binary point. Each index is then shifted left by GL_INDEX_SHIFT bits, and added to GL_INDEX_OFFSET. If GL_INDEX_SHIFT is negative, the shift is to the right. In either case, zero bits fill otherwise unspecified bit locations in the result. If GL_MAP_COLOR is true, the index is replaced with the value that it references in lookup table GL_PIXEL_MAP_I_TO_I. Whether the lookup replacement of the index is done or not, the integer part of the index is then ANDed with 2 sup b -1, where b is the number of bits in a color index buffer. If the GL is in RGBA mode, the red, green, blue, and alpha components of each pixel that is read are converted to an internal floating-point format with unspecified precision. The conversion maps the largest representable component value to 1.0, and component value 0 to 0.0. The resulting floating-point color values are then multiplied by GL_c_SCALE and added to GL_c_BIAS, where c is RED, GREEN, BLUE, and ALPHA for the respective color components. The results are clamped to the range [0,1]. If GL_MAP_COLOR is true, each color component is scaled by the size of lookup table GL_PIXEL_MAP_c_TO_c, then replaced by the value that it references in that table. c is R, G, B, or A. The GL then converts the resulting indices or RGBA colors to fragments by attaching the current raster position z coordinate and texture coordinates to each pixel, then assigning window coordinates (x sub r + i , y sub r + j), where (x sub r , y sub r) is the current raster position, and the pixel was the ith pixel in the jth row. These pixel fragments are then treated just like the fragments generated by rasterizing points, lines, or polygons. Texture mapping, fog, and all the fragment operations are applied before the fragments are written to the frame buffer. GL_DEPTH Depth values are read from the depth buffer and converted directly to an internal floating-point format with unspecified precision. The resulting floating-point depth value is then multiplied by GL_DEPTH_SCALE and added to GL_DEPTH_BIAS. The result is clamped to the range [0,1]. The GL then converts the resulting depth components to fragments by attaching the current raster position color or color index and texture coordinates to each pixel, then assigning window coordinates (x sub r + i , y sub r + j), where (x sub r , y sub r) is the current raster position, and the pixel was the ith pixel in the jth row. These pixel fragments are then treated just like the fragments generated by rasterizing points, lines, or polygons. Texture mapping, fog, and all the fragment operations are applied before the fragments are written to the frame buffer. GL_STENCIL Stencil indices are read from the stencil buffer and converted to an internal fixed-point format with an unspecified number of bits to the right of the binary point. Each fixed-point index is then shifted left by GL_INDEX_SHIFT bits, and added to GL_INDEX_OFFSET. If GL_INDEX_SHIFT is negative, the shift is to the right. In either case, zero bits fill otherwise unspecified bit locations in the result. If GL_MAP_STENCIL is true, the index is replaced with the value that it references in lookup table GL_PIXEL_MAP_S_TO_S. Whether the lookup replacement of the index is done or not, the integer part of the index is then ANDed with 2 sup b -1, where b is the number of bits in the stencil buffer. The resulting stencil indices are then written to the stencil buffer such that the index read from the ith location of the jth row is written to location (x sub r + i , y sub r + j), where (x sub r , y sub r) is the current raster position. Only the pixel ownership test, the scissor test, and the stencil writemask affect these write operations.

The rasterization described thus far assumes pixel zoom factors of 1.0. If

glPixelZoom is used to change the x and y pixel zoom factors, pixels are converted to fragments as follows. If (x sub r, y sub r) is the current raster position, and a given pixel is in the ith location in the jth row of the source pixel rectangle, then fragments are generated for pixels whose centers are in the rectangle with corners at

.ce (x sub r + zoom sub x i, y sub r + zoom sub y j) .sp .5 .ce and .sp .5 .ce (x sub r + zoom sub x (i + 1), y sub r + zoom sub y ( j + 1 ))

where zoom sub x is the value of GL_ZOOM_X and zoom sub y is the value of GL_ZOOM_Y.

Specify the window coordinates of the lower left corner of the rectangular region of pixels to be copied.

Specify the dimensions of the rectangular region of pixels to be copied. Both must be nonnegative.

Specifies whether color values, depth values, or stencil values are to be copied. Symbolic constants GL_COLOR, GL_DEPTH, and GL_STENCIL are accepted.

GL_INVALID_ENUM is generated if type is not an accepted value.

GL_INVALID_VALUE is generated if either width or height is negative.

GL_INVALID_OPERATION is generated if type is GL_DEPTH and there is no depth buffer.

GL_INVALID_OPERATION is generated if type is GL_STENCIL and there is no stencil buffer.

GL_INVALID_OPERATION is generated if glCopyPixels is executed between the execution of glBegin and the corresponding execution of glEnd.

glCopyTexImage1D defines a one-dimensional texture image with pixels from the current GL_READ_BUFFER.

The screen-aligned pixel row with left corner at ("x", "y") and with a length of "width"~+~2~*~"border" defines the texture array at the mipmap level specified by level. internalFormat specifies the internal format of the texture array.

The pixels in the row are processed exactly as if glCopyPixels had been called, but the process stops just before final conversion. At this point all pixel component values are clamped to the range [0,\ 1] and then converted to the texture's internal format for storage in the texel array.

Pixel ordering is such that lower x screen coordinates correspond to lower texture coordinates.

If any of the pixels within the specified row of the current GL_READ_BUFFER are outside the window associated with the current rendering context, then the values obtained for those pixels are undefined.

Specifies the target texture. Must be GL_TEXTURE_1D.

Specifies the level-of-detail number. Level 0 is the base image level. Level n is the nth mipmap reduction image.

Specifies the internal format of the texture. Must be one of the following symbolic constants: GL_ALPHA, GL_ALPHA4, GL_ALPHA8, GL_ALPHA12, GL_ALPHA16, GL_LUMINANCE, GL_LUMINANCE4, GL_LUMINANCE8, GL_LUMINANCE12, GL_LUMINANCE16, GL_LUMINANCE_ALPHA, GL_LUMINANCE4_ALPHA4, GL_LUMINANCE6_ALPHA2, GL_LUMINANCE8_ALPHA8, GL_LUMINANCE12_ALPHA4, GL_LUMINANCE12_ALPHA12, GL_LUMINANCE16_ALPHA16, GL_INTENSITY, GL_INTENSITY4, GL_INTENSITY8, GL_INTENSITY12, GL_INTENSITY16, GL_RGB, GL_R3_G3_B2, GL_RGB4, GL_RGB5, GL_RGB8, GL_RGB10, GL_RGB12, GL_RGB16, GL_RGBA, GL_RGBA2, GL_RGBA4, GL_RGB5_A1, GL_RGBA8, GL_RGB10_A2, GL_RGBA12, or GL_RGBA16.

Specify the window coordinates of the left corner of the row of pixels to be copied.

Specifies the width of the texture image. Must be 0 or 2**n ~+~ 2*border for some integer n. The height of the texture image is 1.

Specifies the width of the border. Must be either 0 or 1.

GL_INVALID_ENUM is generated if target is not one of the allowable values.

GL_INVALID_VALUE is generated if level is less than 0. .P GL_INVALID_VALUE may be generated if level is greater than log sub 2 max, where max is the returned value of GL_MAX_TEXTURE_SIZE. .P GL_INVALID_VALUE is generated if internalFormat is not an allowable value.

GL_INVALID_VALUE is generated if width is less than 0 or greater than 2 + GL_MAX_TEXTURE_SIZE, or if it cannot be represented as 2 ** n ~+~ 2~*~("border") for some integer value of n.

GL_INVALID_VALUE is generated if border is not 0 or 1.

GL_INVALID_OPERATION is generated if glCopyTexImage1D is executed between the execution of glBegin and the corresponding execution of glEnd.

glCopyTexImage2D defines a two-dimensional texture image with pixels from the current GL_READ_BUFFER.

The screen-aligned pixel rectangle with lower left corner at (x, y) and with a width of width~+~2~*~border and a height of height~+~2~*~border defines the texture array at the mipmap level specified by level. internalFormat specifies the internal format of the texture array.

The pixels in the rectangle are processed exactly as if glCopyPixels had been called, but the process stops just before final conversion. At this point all pixel component values are clamped to the range [0,1] and then converted to the texture's internal format for storage in the texel array.

Pixel ordering is such that lower x and y screen coordinates correspond to lower s and t texture coordinates.

If any of the pixels within the specified rectangle of the current GL_READ_BUFFER are outside the window associated with the current rendering context, then the values obtained for those pixels are undefined.

Specifies the target texture. Must be GL_TEXTURE_2D.

Specifies the level-of-detail number. Level 0 is the base image level. Level n is the nth mipmap reduction image.

Specifies the internal format of the texture. Must be one of the following symbolic constants: GL_ALPHA, GL_ALPHA4, GL_ALPHA8, GL_ALPHA12, GL_ALPHA16, GL_LUMINANCE, GL_LUMINANCE4, GL_LUMINANCE8, GL_LUMINANCE12, GL_LUMINANCE16, GL_LUMINANCE_ALPHA, GL_LUMINANCE4_ALPHA4, GL_LUMINANCE6_ALPHA2, GL_LUMINANCE8_ALPHA8, GL_LUMINANCE12_ALPHA4, GL_LUMINANCE12_ALPHA12, GL_LUMINANCE16_ALPHA16, GL_INTENSITY, GL_INTENSITY4, GL_INTENSITY8, GL_INTENSITY12, GL_INTENSITY16, GL_RGB, GL_R3_G3_B2, GL_RGB4, GL_RGB5, GL_RGB8, GL_RGB10, GL_RGB12, GL_RGB16, GL_RGBA, GL_RGBA2, GL_RGBA4, GL_RGB5_A1, GL_RGBA8, GL_RGB10_A2, GL_RGBA12, or GL_RGBA16.

Specify the window coordinates of the lower left corner of the rectangular region of pixels to be copied.

Specifies the width of the texture image. Must be 0 or 2**n ~+~ 2*border for some integer n.

Specifies the height of the texture image. Must be 0 or 2**m ~+~ 2*border for some integer m.

Specifies the width of the border. Must be either 0 or 1.

GL_INVALID_ENUM is generated if target is not GL_TEXTURE_2D.

GL_INVALID_VALUE is generated if level is less than 0. .P GL_INVALID_VALUE may be generated if level is greater than log sub 2 max, where max is the returned value of GL_MAX_TEXTURE_SIZE.

GL_INVALID_VALUE is generated if width or height is less than 0, greater than 2~+~GL_MAX_TEXTURE_SIZE, or if width or height cannot be represented as 2**k ~+~ 2~*~border for some integer k.

GL_INVALID_VALUE is generated if border is not 0 or 1.

GL_INVALID_VALUE is generated if internalFormat is not one of the allowable values.

GL_INVALID_OPERATION is generated if glCopyTexImage2D is executed between the execution of glBegin and the corresponding execution of glEnd.

glCopyTexSubImage1D replaces a portion of a one-dimensional texture image with pixels from the current GL_READ_BUFFER (rather than from main memory, as is the case for glTexSubImage1D).

The screen-aligned pixel row with left corner at (x,\ y), and with length width replaces the portion of the texture array with x indices xoffset through "xoffset" ~+~ "width" ~-~ 1, inclusive. The destination in the texture array may not include any texels outside the texture array as it was originally specified.

The pixels in the row are processed exactly as if glCopyPixels had been called, but the process stops just before final conversion. At this point all pixel component values are clamped to the range [0,\ 1] and then converted to the texture's internal format for storage in the texel array.

It is not an error to specify a subtexture with zero width, but such a specification has no effect. If any of the pixels within the specified row of the current GL_READ_BUFFER are outside the read window associated with the current rendering context, then the values obtained for those pixels are undefined.

No change is made to the internalformat, width, or border parameters of the specified texture array or to texel values outside the specified subregion.

Specifies the target texture. Must be GL_TEXTURE_1D.

Specifies the level-of-detail number. Level 0 is the base image level. Level n is the nth mipmap reduction image.

Specifies the texel offset within the texture array.

Specify the window coordinates of the left corner of the row of pixels to be copied.

Specifies the width of the texture subimage.

GL_INVALID_ENUM is generated if target is not GL_TEXTURE_1D.

GL_INVALID_OPERATION is generated if the texture array has not been defined by a previous glTexImage1D or glCopyTexImage1D operation.

GL_INVALID_VALUE is generated if level is less than 0. .P GL_INVALID_VALUE may be generated if level>log sub 2 max, where max is the returned value of GL_MAX_TEXTURE_SIZE.

GL_INVALID_VALUE is generated if y ~<~ ~-b or if width ~<~ ~-b, where b is the border width of the texture array.

GL_INVALID_VALUE is generated if "xoffset" ~<~ ~-b, or ("xoffset"~+~"width") ~>~ (w-b), where w is the GL_TEXTURE_WIDTH, and b is the GL_TEXTURE_BORDER of the texture image being modified. Note that w includes twice the border width.

glCopyTexSubImage2D replaces a rectangular portion of a two-dimensional texture image with pixels from the current GL_READ_BUFFER (rather than from main memory, as is the case for glTexSubImage2D).

The screen-aligned pixel rectangle with lower left corner at (x,\ y) and with width width and height height replaces the portion of the texture array with x indices xoffset through xoffset~+~width~-~1, inclusive, and y indices yoffset through yoffset~+~height~-~1, inclusive, at the mipmap level specified by level.

The pixels in the rectangle are processed exactly as if glCopyPixels had been called, but the process stops just before final conversion. At this point, all pixel component values are clamped to the range [0,\ 1] and then converted to the texture's internal format for storage in the texel array.

The destination rectangle in the texture array may not include any texels outside the texture array as it was originally specified. It is not an error to specify a subtexture with zero width or height, but such a specification has no effect.

If any of the pixels within the specified rectangle of the current GL_READ_BUFFER are outside the read window associated with the current rendering context, then the values obtained for those pixels are undefined.

No change is made to the internalformat, width, height, or border parameters of the specified texture array or to texel values outside the specified subregion.

Specifies the target texture. Must be GL_TEXTURE_2D

Specifies the level-of-detail number. Level 0 is the base image level. Level n is the nth mipmap reduction image.

Specifies a texel offset in the x direction within the texture array.

Specifies a texel offset in the y direction within the texture array.

Specify the window coordinates of the lower left corner of the rectangular region of pixels to be copied.

Specifies the width of the texture subimage.

Specifies the height of the texture subimage.

GL_INVALID_ENUM is generated if target is not GL_TEXTURE_2D.

GL_INVALID_OPERATION is generated if the texture array has not been defined by a previous glTexImage2D or glCopyTexImage2D operation.

GL_INVALID_VALUE is generated if level is less than 0. .P GL_INVALID_VALUE may be generated if level is greater than log sub 2 max, where max is the returned value of GL_MAX_TEXTURE_SIZE.

GL_INVALID_VALUE is generated if x ~<~ ~-b or if y ~<~ ~-b, where b is the border width of the texture array.

GL_INVALID_VALUE is generated if "xoffset" ~<~ -b, (xoffset~+~width)~>~(w ~-~b), yoffset~<~ ~-b, or (yoffset~+~height)~>~(h ~-~b), where w is the GL_TEXTURE_WIDTH, h is the GL_TEXTURE_HEIGHT, and b is the GL_TEXTURE_BORDER of the texture image being modified. Note that w and h include twice the border width.

GL_INVALID_OPERATION is generated if glCopyTexSubImage2D is executed between the execution of glBegin and the corresponding execution of glEnd.

glDeleteLists causes a contiguous group of display lists to be deleted. list is the name of the first display list to be deleted, and range is the number of display lists to delete. All display lists \fId\fP with list \(<= \fId\fP \(<= list + range - 1 are deleted.

All storage locations allocated to the specified display lists are freed, and the names are available for reuse at a later time. Names within the range that do not have an associated display list are ignored. If range is 0, nothing happens.

Specifies the integer name of the first display list to delete.

Specifies the number of display lists to delete.

GL_INVALID_VALUE is generated if range is negative.

GL_INVALID_OPERATION is generated if glDeleteLists is executed between the execution of glBegin and the corresponding execution of glEnd.

glDepthMask specifies whether the depth buffer is enabled for writing. If flag is GL_FALSE, depth buffer writing is disabled. Otherwise, it is enabled. Initially, depth buffer writing is enabled.

Specifies whether the depth buffer is enabled for writing. If flag is GL_FALSE, depth buffer writing is disabled. Otherwise, it is enabled. Initially, depth buffer writing is enabled.

GL_INVALID_OPERATION is generated if glDepthMask is executed between the execution of glBegin and the corresponding execution of glEnd.

After clipping and division by w, depth coordinates range from -1 to 1, corresponding to the near and far clipping planes. glDepthRange specifies a linear mapping of the normalized depth coordinates in this range to window depth coordinates. Regardless of the actual depth buffer implementation, window coordinate depth values are treated as though they range from 0 through 1 (like color components). Thus, the values accepted by glDepthRange are both clamped to this range before they are accepted.

The setting of (0,1) maps the near plane to 0 and the far plane to 1. With this mapping, the depth buffer range is fully utilized.

Specifies the mapping of the near clipping plane to window coordinates. The initial value is 0.

Specifies the mapping of the far clipping plane to window coordinates. The initial value is 1.

GL_INVALID_OPERATION is generated if glDepthRange is executed between the execution of glBegin and the corresponding execution of glEnd.

glDrawArrays specifies multiple geometric primitives with very few subroutine calls. Instead of calling a GL procedure to pass each individual vertex, normal, texture coordinate, edge flag, or color, you can prespecify separate arrays of vertexes, normals, and colors and use them to construct a sequence of primitives with a single call to glDrawArrays.

When glDrawArrays is called, it uses count sequential elements from each enabled array to construct a sequence of geometric primitives, beginning with element first. mode specifies what kind of primitives are constructed, and how the array elements construct those primitives. If GL_VERTEX_ARRAY is not enabled, no geometric primitives are generated.

Vertex attributes that are modified by glDrawArrays have an unspecified value after glDrawArrays returns. For example, if GL_COLOR_ARRAY is enabled, the value of the current color is undefined after glDrawArrays executes. Attributes that aren't modified remain well defined.

Specifies what kind of primitives to render. Symbolic constants GL_POINTS, GL_LINE_STRIP, GL_LINE_LOOP, GL_LINES, GL_TRIANGLE_STRIP, GL_TRIANGLE_FAN, GL_TRIANGLES, GL_QUAD_STRIP, GL_QUADS, and GL_POLYGON are accepted.

Specifies the starting index in the enabled arrays.

Specifies the number of indices to be rendered.

GL_INVALID_ENUM is generated if mode is not an accepted value.

GL_INVALID_VALUE is generated if count is negative.

GL_INVALID_OPERATION is generated if glDrawArrays is executed between the execution of glBegin and the corresponding glEnd.

glDrawPixels reads pixel data from memory and writes it into the frame buffer relative to the current raster position. Use glRasterPos to set the current raster position; use glGet with argument GL_CURRENT_RASTER_POSITION to query the raster position.

Several parameters define the encoding of pixel data in memory and control the processing of the pixel data before it is placed in the frame buffer. These parameters are set with four commands: glPixelStore, glPixelTransfer, glPixelMap, and glPixelZoom. This reference page describes the effects on glDrawPixels of many, but not all, of the parameters specified by these four commands.

Data is read from pixels as a sequence of signed or unsigned bytes, signed or unsigned shorts, signed or unsigned integers, or single-precision floating-point values, depending on type. Each of these bytes, shorts, integers, or floating-point values is interpreted as one color or depth component, or one index, depending on format. Indices are always treated individually. Color components are treated as groups of one, two, three, or four values, again based on format. Both individual indices and groups of components are referred to as pixels. If type is GL_BITMAP, the data must be unsigned bytes, and format must be either GL_COLOR_INDEX or GL_STENCIL_INDEX. Each unsigned byte is treated as eight 1-bit pixels, with bit ordering determined by GL_UNPACK_LSB_FIRST (see glPixelStore).

widthtimesheight pixels are read from memory, starting at location pixels. By default, these pixels are taken from adjacent memory locations, except that after all width pixels are read, the read pointer is advanced to the next four-byte boundary. The four-byte row alignment is specified by glPixelStore with argument GL_UNPACK_ALIGNMENT, and it can be set to one, two, four, or eight bytes. Other pixel store parameters specify different read pointer advancements, both before the first pixel is read and after all width pixels are read. See the

glPixelStore reference page for details on these options.

The widthtimesheight pixels that are read from memory are each operated on in the same way, based on the values of several parameters specified by glPixelTransfer and glPixelMap. The details of these operations, as well as the target buffer into which the pixels are drawn, are specific to the format of the pixels, as specified by format. format can assume one of eleven symbolic values:

GL_COLOR_INDEX Each pixel is a single value, a color index. It is converted to fixed-point format, with an unspecified number of bits to the right of the binary point, regardless of the memory data type. Floating-point values convert to true fixed-point values. Signed and unsigned integer data is converted with all fraction bits set to 0. Bitmap data convert to either 0 or 1. Each fixed-point index is then shifted left by GL_INDEX_SHIFT bits and added to GL_INDEX_OFFSET. If GL_INDEX_SHIFT is negative, the shift is to the right. In either case, zero bits fill otherwise unspecified bit locations in the result. If the GL is in RGBA mode, the resulting index is converted to an RGBA pixel with the help of the GL_PIXEL_MAP_I_TO_R, GL_PIXEL_MAP_I_TO_G, GL_PIXEL_MAP_I_TO_B, and GL_PIXEL_MAP_I_TO_A tables. If the GL is in color index mode, and if GL_MAP_COLOR is true, the index is replaced with the value that it references in lookup table GL_PIXEL_MAP_I_TO_I. Whether the lookup replacement of the index is done or not, the integer part of the index is then ANDed with 2 sup b -1, where b is the number of bits in a color index buffer. The GL then converts the resulting indices or RGBA colors to fragments by attaching the current raster position z coordinate and texture coordinates to each pixel, then assigning x and y window coordinates to the nth fragment such that .sp .RS .ce x sub n ~=~ x sub r ~+~ n ~ roman mod ~ "width" .sp .ce y sub n ~=~ y sub r ~+~ \(lf ~ n / "width" ~ \(rf .ce 0 .sp .RE where (x sub r , y sub r) is the current raster position. These pixel fragments are then treated just like the fragments generated by rasterizing points, lines, or polygons. Texture mapping, fog, and all the fragment operations are applied before the fragments are written to the frame buffer. GL_STENCIL_INDEX Each pixel is a single value, a stencil index. It is converted to fixed-point format, with an unspecified number of bits to the right of the binary point, regardless of the memory data type. Floating-point values convert to true fixed-point values. Signed and unsigned integer data is converted with all fraction bits set to 0. Bitmap data convert to either 0 or 1. Each fixed-point index is then shifted left by GL_INDEX_SHIFT bits, and added to GL_INDEX_OFFSET. If GL_INDEX_SHIFT is negative, the shift is to the right. In either case, zero bits fill otherwise unspecified bit locations in the result. If GL_MAP_STENCIL is true, the index is replaced with the value that it references in lookup table GL_PIXEL_MAP_S_TO_S. Whether the lookup replacement of the index is done or not, the integer part of the index is then ANDed with 2 sup b -1, where b is the number of bits in the stencil buffer. The resulting stencil indices are then written to the stencil buffer such that the nth index is written to location

.RS .ce x sub n ~=~ x sub r ~+~ n ~ roman mod ~ "width" .sp .ce y sub n ~=~ y sub r ~+~ \(lf ~ n / "width" ~ \(rf .fi .sp .RE

where (x sub r , y sub r) is the current raster position. Only the pixel ownership test, the scissor test, and the stencil writemask affect these write operations.

GL_DEPTH_COMPONENT Each pixel is a single-depth component. Floating-point data is converted directly to an internal floating-point format with unspecified precision. Signed integer data is mapped linearly to the internal floating-point format such that the most positive representable integer value maps to 1.0, and the most negative representable value maps to -1.0. Unsigned integer data is mapped similarly: the largest integer value maps to 1.0, and 0 maps to 0.0. The resulting floating-point depth value is then multiplied by by GL_DEPTH_SCALE and added to GL_DEPTH_BIAS. The result is clamped to the range [0,1]. The GL then converts the resulting depth components to fragments by attaching the current raster position color or color index and texture coordinates to each pixel, then assigning x and y window coordinates to the nth fragment such that

.RS .ce x sub n ~=~ x sub r ~+~ n ~ roman mod ~ "width" .sp .ce y sub n ~=~ y sub r ~+~ \(lf ~ n / "width" ~ \(rf .ce 0 .sp .RE

where (x sub r , y sub r) is the current raster position. These pixel fragments are then treated just like the fragments generated by rasterizing points, lines, or polygons. Texture mapping, fog, and all the fragment operations are applied before the fragments are written to the frame buffer.

GL_RGBA Each pixel is a four-component group: for GL_RGBA, the red component is first, followed by green, followed by blue, followed by alpha. Floating-point values are converted directly to an internal floating-point format with unspecified precision. Signed integer values are mapped linearly to the internal floating-point format such that the most positive representable integer value maps to 1.0, and the most negative representable value maps to -1.0. (Note that this mapping does not convert 0 precisely to 0.0.) Unsigned integer data is mapped similarly: the largest integer value maps to 1.0, and 0 maps to 0.0. The resulting floating-point color values are then multiplied by GL_c_SCALE and added to GL_c_BIAS, where c is RED, GREEN, BLUE, and ALPHA for the respective color components. The results are clamped to the range [0,1]. If GL_MAP_COLOR is true, each color component is scaled by the size of lookup table GL_PIXEL_MAP_c_TO_c, then replaced by the value that it references in that table. c is R, G, B, or A respectively. The GL then converts the resulting RGBA colors to fragments by attaching the current raster position z coordinate and texture coordinates to each pixel, then assigning x and y window coordinates to the nth fragment such that

.RS .ce x sub n ~=~ x sub r ~+~ n ~ roman mod ~ "width" .sp .ce y sub n ~=~ y sub r ~+~ \(lf ~ n / "width" ~ \(rf .ce 0 .sp .RE

where (x sub r , y sub r) is the current raster position. These pixel fragments are then treated just like the fragments generated by rasterizing points, lines, or polygons. Texture mapping, fog, and all the fragment operations are applied before the fragments are written to the frame buffer.

GL_RED Each pixel is a single red component. This component is converted to the internal floating-point format in the same way the red component of an RGBA pixel is. It is then converted to an RGBA pixel with green and blue set to 0, and alpha set to 1. After this conversion, the pixel is treated as if it had been read as an RGBA pixel. GL_GREEN Each pixel is a single green component. This component is converted to the internal floating-point format in the same way the green component of an RGBA pixel is. It is then converted to an RGBA pixel with red and blue set to 0, and alpha set to 1. After this conversion, the pixel is treated as if it had been read as an RGBA pixel. GL_BLUE Each pixel is a single blue component. This component is converted to the internal floating-point format in the same way the blue component of an RGBA pixel is. It is then converted to an RGBA pixel with red and green set to 0, and alpha set to 1. After this conversion, the pixel is treated as if it had been read as an RGBA pixel. GL_ALPHA Each pixel is a single alpha component. This component is converted to the internal floating-point format in the same way the alpha component of an RGBA pixel is. It is then converted to an RGBA pixel with red, green, and blue set to 0. After this conversion, the pixel is treated as if it had been read as an RGBA pixel. GL_RGB Each pixel is a three-component group: red first, followed by green, followed by blue. Each component is converted to the internal floating-point format in the same way the red, green, and blue components of an RGBA pixel are. The color triple is converted to an RGBA pixel with alpha set to 1. After this conversion, the pixel is treated as if it had been read as an RGBA pixel. GL_LUMINANCE Each pixel is a single luminance component. This component is converted to the internal floating-point format in the same way the red component of an RGBA pixel is. It is then converted to an RGBA pixel with red, green, and blue set to the converted luminance value, and alpha set to 1. After this conversion, the pixel is treated as if it had been read as an RGBA pixel. GL_LUMINANCE_ALPHA Each pixel is a two-component group: luminance first, followed by alpha. The two components are converted to the internal floating-point format in the same way the red component of an RGBA pixel is. They are then converted to an RGBA pixel with red, green, and blue set to the converted luminance value, and alpha set to the converted alpha value. After this conversion, the pixel is treated as if it had been read as an RGBA pixel.

The following table summarizes the meaning of the valid constants for the type parameter: .sp 2 .TS center box ; ci | ci c | c . type corresponding type = GL_UNSIGNED_BYTE unsigned 8-bit integer GL_BYTE signed 8-bit integer GL_BITMAP single bits in unsigned 8-bit integers GL_UNSIGNED_SHORT unsigned 16-bit integer GL_SHORT signed 16-bit integer GL_UNSIGNED_INT unsigned 32-bit integer GL_INT 32-bit integer GL_FLOAT single-precision floating-point .TE .sp

The rasterization described so far assumes pixel zoom factors of 1. If

glPixelZoom is used to change the x and y pixel zoom factors, pixels are converted to fragments as follows. If (x sub r, y sub r) is the current raster position, and a given pixel is in the nth column and mth row of the pixel rectangle, then fragments are generated for pixels whose centers are in the rectangle with corners at .sp .RS .ce (x sub r + zoom sub x n, y sub r + zoom sub y m) .sp .ce (x sub r + zoom sub x (n + 1), y sub r + zoom sub y ( m + 1 )) .ce 0 .sp .RE

where zoom sub x is the value of GL_ZOOM_X and zoom sub y is the value of GL_ZOOM_Y.

Specify the dimensions of the pixel rectangle to be written into the frame buffer.

Specifies the format of the pixel data. Symbolic constants GL_COLOR_INDEX, GL_STENCIL_INDEX, GL_DEPTH_COMPONENT, GL_RGBA, GL_RED, GL_GREEN, GL_BLUE, GL_ALPHA, GL_RGB, GL_LUMINANCE, and GL_LUMINANCE_ALPHA are accepted.

Specifies the data type for pixels. Symbolic constants GL_UNSIGNED_BYTE, GL_BYTE, GL_BITMAP, GL_UNSIGNED_SHORT, GL_SHORT, GL_UNSIGNED_INT, GL_INT, and GL_FLOAT are accepted.

Specifies a pointer to the pixel data.

GL_INVALID_VALUE is generated if either width or height is negative.

GL_INVALID_ENUM is generated if format or type is not one of the accepted values.

GL_INVALID_OPERATION is generated if format is GL_RED, GL_GREEN, GL_BLUE, GL_ALPHA, GL_RGB, GL_RGBA, GL_LUMINANCE, or GL_LUMINANCE_ALPHA, and the GL is in color index mode.

GL_INVALID_ENUM is generated if type is GL_BITMAP and format is not either GL_COLOR_INDEX or GL_STENCIL_INDEX.

GL_INVALID_OPERATION is generated if format is GL_STENCIL_INDEX and there is no stencil buffer.

GL_INVALID_OPERATION is generated if glDrawPixels is executed between the execution of glBegin and the corresponding execution of glEnd.

Each vertex of a polygon, separate triangle, or separate quadrilateral specified between a glBegin/glEnd pair is marked as the start of either a boundary or nonboundary edge. If the current edge flag is true when the vertex is specified, the vertex is marked as the start of a boundary edge. Otherwise, the vertex is marked as the start of a nonboundary edge. glEdgeFlag sets the edge flag bit to GL_TRUE if flag is GL_TRUE, and to GL_FALSE otherwise.

The vertices of connected triangles and connected quadrilaterals are always marked as boundary, regardless of the value of the edge flag.

Boundary and nonboundary edge flags on vertices are significant only if GL_POLYGON_MODE is set to GL_POINT or GL_LINE. See glPolygonMode.

Specifies the current edge flag value, either GL_TRUE or GL_FALSE. The initial value is GL_TRUE.

Specifies a pointer to an array that contains a single boolean element, which replaces the current edge flag value.

glEvalCoord evaluates enabled one-dimensional maps at argument u or two-dimensional maps using two domain values, u and v. To define a map, call glMap1 and glMap2; to enable and disable it, call glEnable and glDisable.

When one of the glEvalCoord commands is issued, all currently enabled maps of the indicated dimension are evaluated. Then, for each enabled map, it is as if the corresponding GL command had been issued with the computed value. That is, if GL_MAP1_INDEX or GL_MAP2_INDEX is enabled, a glIndex command is simulated. If GL_MAP1_COLOR_4 or GL_MAP2_COLOR_4 is enabled, a glColor command is simulated. If GL_MAP1_NORMAL or GL_MAP2_NORMAL is enabled, a normal vector is produced, and if any of GL_MAP1_TEXTURE_COORD_1, GL_MAP1_TEXTURE_COORD_2, GL_MAP1_TEXTURE_COORD_3, GL_MAP1_TEXTURE_COORD_4, GL_MAP2_TEXTURE_COORD_1, GL_MAP2_TEXTURE_COORD_2, GL_MAP2_TEXTURE_COORD_3, or GL_MAP2_TEXTURE_COORD_4 is enabled, then an appropriate glTexCoord command is simulated.

For color, color index, normal, and texture coordinates the GL uses evaluated values instead of current values for those evaluations that are enabled, and current values otherwise, However, the evaluated values do not update the current values. Thus, if glVertex commands are interspersed with glEvalCoord commands, the color, normal, and texture coordinates associated with the glVertex commands are not affected by the values generated by the glEvalCoord commands, but only by the most recent glColor, glIndex, glNormal, and glTexCoord commands.

No commands are issued for maps that are not enabled. If more than one texture evaluation is enabled for a particular dimension (for example, GL_MAP2_TEXTURE_COORD_1 and GL_MAP2_TEXTURE_COORD_2), then only the evaluation of the map that produces the larger number of coordinates (in this case, GL_MAP2_TEXTURE_COORD_2) is carried out. GL_MAP1_VERTEX_4 overrides GL_MAP1_VERTEX_3, and GL_MAP2_VERTEX_4 overrides GL_MAP2_VERTEX_3, in the same manner. If neither a three- nor a four-component vertex map is enabled for the specified dimension, the glEvalCoord command is ignored.

If you have enabled automatic normal generation, by calling glEnable with argument GL_AUTO_NORMAL, glEvalCoord generates surface normals analytically, regardless of the contents or enabling of the GL_MAP2_NORMAL map. Let .sp .nf Pp Pp m = -- X -- Pu Pv .sp .fi

Then the generated normal n is

n = m over ~ over { || m || }

.sp

If automatic normal generation is disabled, the corresponding normal map GL_MAP2_NORMAL, if enabled, is used to produce a normal. If neither automatic normal generation nor a normal map is enabled, no normal is generated for glEvalCoord commands.

Specifies a value that is the domain coordinate u to the basis function defined in a previous glMap1 or glMap2 command.

Specifies a value that is the domain coordinate v to the basis function defined in a previous glMap2 command.

Specifies a pointer to an array containing either one or two domain coordinates. The first coordinate is u. The second coordinate is v.

glMapGrid and glEvalMesh are used in tandem to efficiently generate and evaluate a series of evenly spaced map domain values. glEvalPoint can be used to evaluate a single grid point in the same gridspace that is traversed by glEvalMesh. Calling glEvalPoint is equivalent to calling .nf

glEvalCoord1(i . DELTA u + u ); 1 where

DELTA u = (u - u ) / n 2 1

and n, u , and u 1 2

.fi are the arguments to the most recent glMapGrid1 command. The one absolute numeric requirement is that if i~=~n, then the value computed from .nf i . DELTA u + u is exactly u . 1 2

.fi

In the two-dimensional case, glEvalPoint, let .nf DELTA u = (u - u )/n 2 1

DELTA v = (v - v )/m 2 1

where n, u , u , m, v , and v 1 2 1 2

.fi are the arguments to the most recent glMapGrid2 command. Then the glEvalPoint command is equivalent to calling .nf

glEvalCoord2(i . DELTA u + u , j . DELTA v + v ); 1 1

.fi The only absolute numeric requirements are that if i~=~n, then the value computed from .nf

i . DELTA u + u is exactly u , 1 2 .fi and if j~=~m, then the value computed from .nf

j cdot DELTA v + v is exactly v . 1 2

Specifies the integer value for grid domain variable i.

Specifies the integer value for grid domain variable j (glEvalPoint only).

Fog is initially disabled. While enabled, fog affects rasterized geometry, bitmaps, and pixel blocks, but not buffer clear operations. To enable and disable fog, call glEnable and glDisable with argument GL_FOG.

glFog assigns the value or values in params to the fog parameter specified by pname. The following values are accepted for pname:

GL_FOG_MODE params is a single integer or floating-point value that specifies the equation to be used to compute the fog blend factor, f. Three symbolic constants are accepted: GL_LINEAR, GL_EXP, and GL_EXP2. The equations corresponding to these symbolic constants are defined below. The initial fog mode is GL_EXP. GL_FOG_DENSITY params is a single integer or floating-point value that specifies density, the fog density used in both exponential fog equations. Only nonnegative densities are accepted. The initial fog density is 1. GL_FOG_START params is a single integer or floating-point value that specifies start, the near distance used in the linear fog equation. The initial near distance is 0. GL_FOG_END params is a single integer or floating-point value that specifies end, the far distance used in the linear fog equation. The initial far distance is 1. GL_FOG_INDEX params is a single integer or floating-point value that specifies i sub f, the fog color index. The initial fog index is 0. GL_FOG_COLOR params contains four integer or floating-point values that specify C sub f, the fog color. Integer values are mapped linearly such that the most positive representable value maps to 1.0, and the most negative representable value maps to -1.0. Floating-point values are mapped directly. After conversion, all color components are clamped to the range [0,1]. The initial fog color is (0, 0, 0, 0).

Fog blends a fog color with each rasterized pixel fragment's posttexturing color using a blending factor f. Factor f is computed in one of three ways, depending on the fog mode. Let z be the distance in eye coordinates from the origin to the fragment being fogged. The equation for GL_LINEAR fog is .ce

.EQ f ~=~ {end ~-~ z} over {end ~-~ start} .EN

.RE

The equation for GL_EXP fog is .ce

.EQ f ~=~ e ** (-(density ~cdot~ z)) .EN

The equation for GL_EXP2 fog is .ce

.EQ f ~=~ e ** (-(density ~cdot~ z) ** 2) .EN

Regardless of the fog mode, f is clamped to the range [0,1] after it is computed. Then, if the GL is in RGBA color mode, the fragment's color C sub r is replaced by .sp .ce .EQ {C sub r} prime ~=~ f C sub r + (1 - f) C sub f .EN

In color index mode, the fragment's color index i sub r is replaced by .sp .ce .EQ {i sub r} prime ~=~ i sub r + (1 - f) i sub f .EN

Specifies a single-valued fog parameter. GL_FOG_MODE, GL_FOG_DENSITY, GL_FOG_START, GL_FOG_END, and GL_FOG_INDEX are accepted.

Specifies the value that pname will be set to.

Specifies a fog parameter. GL_FOG_MODE, GL_FOG_DENSITY, GL_FOG_START, GL_FOG_END, GL_FOG_INDEX, and GL_FOG_COLOR are accepted.

Specifies the value or values to be assigned to pname. GL_FOG_COLOR requires an array of four values. All other parameters accept an array containing only a single value.

GL_INVALID_ENUM is generated if pname is not an accepted value, or if pname is GL_FOG_MODE and params is not an accepted value.

GL_INVALID_VALUE is generated if pname is GL_FOG_DENSITY, and params is negative.

GL_INVALID_OPERATION is generated if glFog is executed between the execution of glBegin and the corresponding execution of glEnd.

glFrustum describes a perspective matrix that produces a perspective projection. The current matrix (see glMatrixMode) is multiplied by this matrix and the result replaces the current matrix, as if glMultMatrix were called with the following matrix as its argument:

.sp 5 .ce .EQ down 130 {left ( ~~ matrix { ccol { {{2 ~ "zNear"} over {"right" - "left"}} above 0 above 0 above 0 } ccol { 0 above {{2 ~ "zNear"} over {"top" - "bottom"}} ~ above 0 above 0 } ccol { A ~~~~ above B ~~~~ above C ~~~~ above -1 ~~~~} ccol { 0 above 0 above D above 0} } ~~~ right )} .EN .sp .ce .EQ down 130 {A ~=~ {"right" + "left"} over {"right" - "left"}} .EN .sp .ce .EQ down 130 {B ~=~ {"top" + "bottom"} over {"top" - "bottom"}} .EN .sp .ce .EQ down 130 {C ~=~ -{{"zFar" + "zNear"} over {"zFar" - "zNear"}}} .EN .sp .ce .EQ down 130 {D ~=~ -{{2 ~ "zFar" ~ "zNear"} over {"zFar" - "zNear"}}} .EN .sp

Typically, the matrix mode is GL_PROJECTION, and (left, bottom, -zNear) and (right, top, -zNear) specify the points on the near clipping plane that are mapped to the lower left and upper right corners of the window, assuming that the eye is located at (0, 0, 0). -zFar specifies the location of the far clipping plane. Both zNear and zFar must be positive.

Use glPushMatrix and glPopMatrix to save and restore the current matrix stack.

Specify the coordinates for the left and right vertical clipping planes.

Specify the coordinates for the bottom and top horizontal clipping planes.

Specify the distances to the near and far depth clipping planes. Both distances must be positive.

GL_INVALID_VALUE is generated if zNear or zFar is not positive.

GL_INVALID_OPERATION is generated if glFrustum is executed between the execution of glBegin and the corresponding execution of glEnd.

glGenLists has one argument, range. It returns an integer n such that range contiguous empty display lists, named n, n+1, ..., n+range -1, are created. If range is 0, if there is no group of range contiguous names available, or if any error is generated, no display lists are generated, and 0 is returned.

Specifies the number of contiguous empty display lists to be generated.

GL_INVALID_VALUE is generated if range is negative.

GL_INVALID_OPERATION is generated if glGenLists is executed between the execution of glBegin and the corresponding execution of glEnd.

glGetError returns the value of the error flag. Each detectable error is assigned a numeric code and symbolic name. When an error occurs, the error flag is set to the appropriate error code value. No other errors are recorded until glGetError is called, the error code is returned, and the flag is reset to GL_NO_ERROR. If a call to glGetError returns GL_NO_ERROR, there has been no detectable error since the last call to glGetError, or since the GL was initialized.

To allow for distributed implementations, there may be several error flags. If any single error flag has recorded an error, the value of that flag is returned and that flag is reset to GL_NO_ERROR when glGetError is called. If more than one flag has recorded an error, glGetError returns and clears an arbitrary error flag value. Thus, glGetError should always be called in a loop, until it returns GL_NO_ERROR, if all error flags are to be reset.

Initially, all error flags are set to GL_NO_ERROR.

The following errors are currently defined:

GL_NO_ERROR No error has been recorded. The value of this symbolic constant is guaranteed to be 0. GL_INVALID_ENUM An unacceptable value is specified for an enumerated argument. The offending command is ignored, and has no other side effect than to set the error flag. GL_INVALID_VALUE A numeric argument is out of range. The offending command is ignored, and has no other side effect than to set the error flag. GL_INVALID_OPERATION The specified operation is not allowed in the current state. The offending command is ignored, and has no other side effect than to set the error flag. GL_STACK_OVERFLOW This command would cause a stack overflow. The offending command is ignored, and has no other side effect than to set the error flag. GL_STACK_UNDERFLOW This command would cause a stack underflow. The offending command is ignored, and has no other side effect than to set the error flag. GL_OUT_OF_MEMORY There is not enough memory left to execute the command. The state of the GL is undefined, except for the state of the error flags, after this error is recorded.

When an error flag is set, results of a GL operation are undefined only if GL_OUT_OF_MEMORY has occurred. In all other cases, the command generating the error is ignored and has no effect on the GL state or frame buffer contents. If the generating command returns a value, it returns 0. If glGetError itself generates an error, it returns 0.

GL_INVALID_OPERATION is generated if glGetError is executed between the execution of glBegin and the corresponding execution of glEnd. In this case glGetError returns 0.

glGetString returns a pointer to a static string describing some aspect of the current GL connection. name can be one of the following:

GL_VENDOR Returns the company responsible for this GL implementation. This name does not change from release to release. GL_RENDERER Returns the name of the renderer. This name is typically specific to a particular configuration of a hardware platform. It does not change from release to release. GL_VERSION Returns a version or release number. GL_EXTENSIONS Returns a space-separated list of supported extensions to GL.

Because the GL does not include queries for the performance characteristics of an implementation, some applications are written to recognize known platforms and modify their GL usage based on known performance characteristics of these platforms. Strings GL_VENDOR and GL_RENDERER together uniquely specify a platform. They do not change from release to release and should be used by platform-recognition algorithms.

Some applications want to make use of features that are not part of the standard GL. These features may be implemented as extensions to the standard GL. The GL_EXTENSIONS string is a space-separated list of supported GL extensions. (Extension names never contain a space character.)

The GL_VERSION string begins with a version number. The version number uses one of these forms:

major_number.minor_number

major_number.minor_number.release_number

Vendor-specific information may follow the version number. Its format depends on the implementation, but a space always separates the version number and the vendor-specific information.

All strings are null-terminated.

Specifies a symbolic constant, one of GL_VENDOR, GL_RENDERER, GL_VERSION, or GL_EXTENSIONS.

GL_INVALID_ENUM is generated if name is not an accepted value.

GL_INVALID_OPERATION is generated if glGetString is executed between the execution of glBegin and the corresponding execution of glEnd.

Certain aspects of GL behavior, when there is room for interpretation, can be controlled with hints. A hint is specified with two arguments. target is a symbolic constant indicating the behavior to be controlled, and mode is another symbolic constant indicating the desired behavior. The initial value for each target is GL_DONT_CARE. mode can be one of the following:

GL_FASTEST The most efficient option should be chosen. GL_NICEST The most correct, or highest quality, option should be chosen. GL_DONT_CARE No preference.

Though the implementation aspects that can be hinted are well defined, the interpretation of the hints depends on the implementation. The hint aspects that can be specified with target, along with suggested semantics, are as follows:

GL_FOG_HINT Indicates the accuracy of fog calculation. If per-pixel fog calculation is not efficiently supported by the GL implementation, hinting GL_DONT_CARE or GL_FASTEST can result in per-vertex calculation of fog effects. GL_LINE_SMOOTH_HINT Indicates the sampling quality of antialiased lines. If a larger filter function is applied, hinting GL_NICEST can result in more pixel fragments being generated during rasterization, GL_PERSPECTIVE_CORRECTION_HINT Indicates the quality of color and texture coordinate interpolation. If perspective-corrected parameter interpolation is not efficiently supported by the GL implementation, hinting GL_DONT_CARE or GL_FASTEST can result in simple linear interpolation of colors and/or texture coordinates. GL_POINT_SMOOTH_HINT Indicates the sampling quality of antialiased points. If a larger filter function is applied, hinting GL_NICEST can result in more pixel fragments being generated during rasterization, GL_POLYGON_SMOOTH_HINT Indicates the sampling quality of antialiased polygons. Hinting GL_NICEST can result in more pixel fragments being generated during rasterization, if a larger filter function is applied.

Specifies a symbolic constant indicating the behavior to be controlled. GL_FOG_HINT, GL_LINE_SMOOTH_HINT, GL_PERSPECTIVE_CORRECTION_HINT, GL_POINT_SMOOTH_HINT, and GL_POLYGON_SMOOTH_HINT are accepted.

Specifies a symbolic constant indicating the desired behavior. GL_FASTEST, GL_NICEST, and GL_DONT_CARE are accepted.

GL_INVALID_ENUM is generated if either target or mode is not an accepted value.

GL_INVALID_OPERATION is generated if glHint is executed between the execution of glBegin and the corresponding execution of glEnd.

glIndex updates the current (single-valued) color index. It takes one argument, the new value for the current color index.

The current index is stored as a floating-point value. Integer values are converted directly to floating-point values, with no special mapping. The initial value is 1.

Index values outside the representable range of the color index buffer are not clamped. However, before an index is dithered (if enabled) and written to the frame buffer, it is converted to fixed-point format. Any bits in the integer portion of the resulting fixed-point value that do not correspond to bits in the frame buffer are masked out.

Specifies the new value for the current color index.

Specifies a pointer to a one-element array that contains the new value for the current color index.

glIndexMask controls the writing of individual bits in the color index buffers. The least significant n bits of mask, where n is the number of bits in a color index buffer, specify a mask. Where a 1 (one) appears in the mask, it's possible to write to the corresponding bit in the color index buffer (or buffers). Where a 0 (zero) appears, the corresponding bit is write-protected.

This mask is used only in color index mode, and it affects only the buffers currently selected for writing (see glDrawBuffer). Initially, all bits are enabled for writing.

Specifies a bit mask to enable and disable the writing of individual bits in the color index buffers. Initially, the mask is all 1's.

GL_INVALID_OPERATION is generated if glIndexMask is executed between the execution of glBegin and the corresponding execution of glEnd.

glIsEnabled returns GL_TRUE if cap is an enabled capability and returns GL_FALSE otherwise. Initially all capabilities except GL_DITHER are disabled; GL_DITHER is initially enabled.

The following capabilities are accepted for cap:

.TS lb lb l l l. Constant See _

GL_ALPHA_TEST glAlphaFunc GL_AUTO_NORMAL glEvalCoord GL_BLEND glBlendFunc, glLogicOp GL_CLIP_PLANE i glClipPlane GL_COLOR_ARRAY glColorPointer GL_COLOR_LOGIC_OP glLogicOp GL_COLOR_MATERIAL glColorMaterial GL_CULL_FACE glCullFace GL_DEPTH_TEST glDepthFunc, glDepthRange GL_DITHER glEnable GL_EDGE_FLAG_ARRAY glEdgeFlagPointer GL_FOG glFog GL_INDEX_ARRAY glIndexPointer GL_INDEX_LOGIC_OP glLogicOp GL_LIGHT i glLightModel, glLight GL_LIGHTING glMaterial, glLightModel, glLight GL_LINE_SMOOTH glLineWidth GL_LINE_STIPPLE glLineStipple GL_MAP1_COLOR_4 glMap1, glMap2 GL_MAP2_TEXTURE_COORD_2 glMap2 GL_MAP2_TEXTURE_COORD_3 glMap2 GL_MAP2_TEXTURE_COORD_4 glMap2 GL_MAP2_VERTEX_3 glMap2 GL_MAP2_VERTEX_4 glMap2 GL_NORMAL_ARRAY glNormalPointer GL_NORMALIZE glNormal GL_POINT_SMOOTH glPointSize GL_POLYGON_SMOOTH glPolygonMode GL_POLYGON_OFFSET_FILL glPolygonOffset GL_POLYGON_OFFSET_LINE glPolygonOffset GL_POLYGON_OFFSET_POINT glPolygonOffset GL_POLYGON_STIPPLE glPolygonStipple GL_SCISSOR_TEST glScissor GL_STENCIL_TEST glStencilFunc, glStencilOp GL_TEXTURE_1D glTexImage1D GL_TEXTURE_2D glTexImage2D GL_TEXTURE_COORD_ARRAY glTexCoordPointer GL_TEXTURE_GEN_Q glTexGen GL_TEXTURE_GEN_R glTexGen GL_TEXTURE_GEN_S glTexGen GL_TEXTURE_GEN_T glTexGen GL_VERTEX_ARRAY glVertexPointer .TE

Specifies a symbolic constant indicating a GL capability.

GL_INVALID_ENUM is generated if cap is not an accepted value.

GL_INVALID_OPERATION is generated if glIsEnabled is executed between the execution of glBegin and the corresponding execution of glEnd.

glIsList returns GL_TRUE if list is the name of a display list and returns GL_FALSE otherwise.

Specifies a potential display-list name.

GL_INVALID_OPERATION is generated if glIsList is executed between the execution of glBegin and the corresponding execution of glEnd.

glIsTexture returns GL_TRUE if texture is currently the name of a texture. If texture is zero, or is a non-zero value that is not currently the name of a texture, or if an error occurs, glIsTexture returns GL_FALSE.

Specifies a value that may be the name of a texture.

GL_INVALID_OPERATION is generated if glIsTexture is executed between the execution of glBegin and the corresponding execution of glEnd.

glLight sets the values of individual light source parameters. light names the light and is a symbolic name of the form GL_LIGHTi, where 0 \(<= i < GL_MAX_LIGHTS. pname specifies one of ten light source parameters, again by symbolic name. params is either a single value or a pointer to an array that contains the new values.

To enable and disable lighting calculation, call glEnable and glDisable with argument GL_LIGHTING. Lighting is initially disabled. When it is enabled, light sources that are enabled contribute to the lighting calculation. Light source i is enabled and disabled using glEnable and glDisable with argument GL_LIGHTi.

The ten light parameters are as follows:

GL_AMBIENT params contains four integer or floating-point values that specify the ambient RGBA intensity of the light. Integer values are mapped linearly such that the most positive representable value maps to 1.0, and the most negative representable value maps to -1.0. Floating-point values are mapped directly. Neither integer nor floating-point values are clamped. The initial ambient light intensity is (0, 0, 0, 1). GL_DIFFUSE params contains four integer or floating-point values that specify the diffuse RGBA intensity of the light. Integer values are mapped linearly such that the most positive representable value maps to 1.0, and the most negative representable value maps to -1.0. Floating-point values are mapped directly. Neither integer nor floating-point values are clamped. The initial value for GL_LIGHT0 is (1, 1, 1, 1); for other lights, the initial value is (0, 0, 0, 0). GL_SPECULAR params contains four integer or floating-point values that specify the specular RGBA intensity of the light. Integer values are mapped linearly such that the most positive representable value maps to 1.0, and the most negative representable value maps to -1.0. Floating-point values are mapped directly. Neither integer nor floating-point values are clamped. The initial value for GL_LIGHT0 is (1, 1, 1, 1); for other lights, the initial value is (0, 0, 0, 0). GL_POSITION params contains four integer or floating-point values that specify the position of the light in homogeneous object coordinates. Both integer and floating-point values are mapped directly. Neither integer nor floating-point values are clamped. The position is transformed by the modelview matrix when glLight is called (just as if it were a point), and it is stored in eye coordinates. If the w component of the position is 0, the light is treated as a directional source. Diffuse and specular lighting calculations take the light's direction, but not its actual position, into account, and attenuation is disabled. Otherwise, diffuse and specular lighting calculations are based on the actual location of the light in eye coordinates, and attenuation is enabled. The initial position is (0, 0, 1, 0); thus, the initial light source is directional, parallel to, and in the direction of the -z axis. GL_SPOT_DIRECTION params contains three integer or floating-point values that specify the direction of the light in homogeneous object coordinates. Both integer and floating-point values are mapped directly. Neither integer nor floating-point values are clamped. The spot direction is transformed by the inverse of the modelview matrix when glLight is called (just as if it were a normal), and it is stored in eye coordinates. It is significant only when GL_SPOT_CUTOFF is not 180, which it is initially. The initial direction is (0, 0, -1). GL_SPOT_EXPONENT params is a single integer or floating-point value that specifies the intensity distribution of the light. Integer and floating-point values are mapped directly. Only values in the range [0,128] are accepted. Effective light intensity is attenuated by the cosine of the angle between the direction of the light and the direction from the light to the vertex being lighted, raised to the power of the spot exponent. Thus, higher spot exponents result in a more focused light source, regardless of the spot cutoff angle (see GL_SPOT_CUTOFF, next paragraph). The initial spot exponent is 0, resulting in uniform light distribution. GL_SPOT_CUTOFF params is a single integer or floating-point value that specifies the maximum spread angle of a light source. Integer and floating-point values are mapped directly. Only values in the range [0,90] and the special value 180 are accepted. If the angle between the direction of the light and the direction from the light to the vertex being lighted is greater than the spot cutoff angle, the light is completely masked. Otherwise, its intensity is controlled by the spot exponent and the attenuation factors. The initial spot cutoff is 180, resulting in uniform light distribution. GL_CONSTANT_ATTENUATION GL_LINEAR_ATTENUATION GL_QUADRATIC_ATTENUATION params is a single integer or floating-point value that specifies one of the three light attenuation factors. Integer and floating-point values are mapped directly. Only nonnegative values are accepted. If the light is positional, rather than directional, its intensity is attenuated by the reciprocal of the sum of the constant factor, the linear factor times the distance between the light and the vertex being lighted, and the quadratic factor times the square of the same distance. The initial attenuation factors are (1, 0, 0), resulting in no attenuation.

Specifies a light. The number of lights depends on the implementation, but at least eight lights are supported. They are identified by symbolic names of the form GL_LIGHTi where 0 \(<= i < GL_MAX_LIGHTS.

Specifies a single-valued light source parameter for light. GL_SPOT_EXPONENT, GL_SPOT_CUTOFF, GL_CONSTANT_ATTENUATION, GL_LINEAR_ATTENUATION, and GL_QUADRATIC_ATTENUATION are accepted.

Specifies the value that parameter pname of light source light will be set to.

Specifies a light. The number of lights depends on the implementation, but at least eight lights are supported. They are identified by symbolic names of the form GL_LIGHTi where 0 \(<= i < GL_MAX_LIGHTS.

Specifies a light source parameter for light. GL_AMBIENT, GL_DIFFUSE, GL_SPECULAR, GL_POSITION, GL_SPOT_CUTOFF, GL_SPOT_DIRECTION, GL_SPOT_EXPONENT, GL_CONSTANT_ATTENUATION, GL_LINEAR_ATTENUATION, and GL_QUADRATIC_ATTENUATION are accepted.

Specifies a pointer to the value or values that parameter pname of light source light will be set to.

GL_INVALID_ENUM is generated if either light or pname is not an accepted value.

GL_INVALID_VALUE is generated if a spot exponent value is specified outside the range [0,128], or if spot cutoff is specified outside the range [0,90] (except for the special value 180), or if a negative attenuation factor is specified.

GL_INVALID_OPERATION is generated if glLight is executed between the execution of glBegin and the corresponding execution of glEnd.

glLightModel sets the lighting model parameter. pname names a parameter and params gives the new value. There are three lighting model parameters:

GL_LIGHT_MODEL_AMBIENT params contains four integer or floating-point values that specify the ambient RGBA intensity of the entire scene. Integer values are mapped linearly such that the most positive representable value maps to 1.0, and the most negative representable value maps to -1.0. Floating-point values are mapped directly. Neither integer nor floating-point values are clamped. The initial ambient scene intensity is (0.2, 0.2, 0.2, 1.0). GL_LIGHT_MODEL_LOCAL_VIEWER params is a single integer or floating-point value that specifies how specular reflection angles are computed. If params is 0 (or 0.0), specular reflection angles take the view direction to be parallel to and in the direction of the -z axis, regardless of the location of the vertex in eye coordinates. Otherwise, specular reflections are computed from the origin of the eye coordinate system. The initial value is 0. GL_LIGHT_MODEL_TWO_SIDE params is a single integer or floating-point value that specifies whether one- or two-sided lighting calculations are done for polygons. It has no effect on the lighting calculations for points, lines, or bitmaps. If params is 0 (or 0.0), one-sided lighting is specified, and only the front material parameters are used in the lighting equation. Otherwise, two-sided lighting is specified. In this case, vertices of back-facing polygons are lighted using the back material parameters, and have their normals reversed before the lighting equation is evaluated. Vertices of front-facing polygons are always lighted using the front material parameters, with no change to their normals. The initial value is 0.

In RGBA mode, the lighted color of a vertex is the sum of the material emission intensity, the product of the material ambient reflectance and the lighting model full-scene ambient intensity, and the contribution of each enabled light source. Each light source contributes the sum of three terms: ambient, diffuse, and specular. The ambient light source contribution is the product of the material ambient reflectance and the light's ambient intensity. The diffuse light source contribution is the product of the material diffuse reflectance, the light's diffuse intensity, and the dot product of the vertex's normal with the normalized vector from the vertex to the light source. The specular light source contribution is the product of the material specular reflectance, the light's specular intensity, and the dot product of the normalized vertex-to-eye and vertex-to-light vectors, raised to the power of the shininess of the material. All three light source contributions are attenuated equally based on the distance from the vertex to the light source and on light source direction, spread exponent, and spread cutoff angle. All dot products are replaced with 0 if they evaluate to a negative value.

The alpha component of the resulting lighted color is set to the alpha value of the material diffuse reflectance.

In color index mode, the value of the lighted index of a vertex ranges from the ambient to the specular values passed to glMaterial using GL_COLOR_INDEXES. Diffuse and specular coefficients, computed with a (.30, .59, .11) weighting of the lights' colors, the shininess of the material, and the same reflection and attenuation equations as in the RGBA case, determine how much above ambient the resulting index is.

Specifies a single-valued lighting model parameter. GL_LIGHT_MODEL_LOCAL_VIEWER and GL_LIGHT_MODEL_TWO_SIDE are accepted.

Specifies the value that param will be set to.

Specifies a lighting model parameter. GL_LIGHT_MODEL_AMBIENT, GL_LIGHT_MODEL_LOCAL_VIEWER, and GL_LIGHT_MODEL_TWO_SIDE are accepted.

Specifies a pointer to the value or values that params will be set to.

GL_INVALID_ENUM is generated if pname is not an accepted value.

GL_INVALID_OPERATION is generated if glLightModel is executed between the execution of glBegin and the corresponding execution of glEnd.

Line stippling masks out certain fragments produced by rasterization; those fragments will not be drawn. The masking is achieved by using three parameters: the 16-bit line stipple pattern pattern, the repeat count factor, and an integer stipple counter s.

Counter s is reset to 0 whenever glBegin is called, and before each line segment of a glBegin(GL_LINES)/glEnd sequence is generated. It is incremented after each fragment of a unit width aliased line segment is generated, or after each i fragments of an i width line segment are generated. The i fragments associated with count s are masked out if .sp .ce pattern bit (s ~/~ "factor") ~roman mod~ 16 .sp is 0, otherwise these fragments are sent to the frame buffer. Bit zero of pattern is the least significant bit.

Antialiased lines are treated as a sequence of 1 times width rectangles for purposes of stippling. Whether rectagle s is rasterized or not depends on the fragment rule described for aliased lines, counting rectangles rather than groups of fragments.

To enable and disable line stippling, call glEnable and glDisable with argument GL_LINE_STIPPLE. When enabled, the line stipple pattern is applied as described above. When disabled, it is as if the pattern were all 1's. Initially, line stippling is disabled.

Specifies a multiplier for each bit in the line stipple pattern. If factor is 3, for example, each bit in the pattern is used three times before the next bit in the pattern is used. factor is clamped to the range [1, 256] and defaults to 1.

Specifies a 16-bit integer whose bit pattern determines which fragments of a line will be drawn when the line is rasterized. Bit zero is used first; the default pattern is all 1's.

GL_INVALID_OPERATION is generated if glLineStipple is executed between the execution of glBegin and the corresponding execution of glEnd.

glLineWidth specifies the rasterized width of both aliased and antialiased lines. Using a line width other than 1 has different effects, depending on whether line antialiasing is enabled. To enable and disable line antialiasing, call glEnable and glDisable with argument GL_LINE_SMOOTH. Line antialiasing is initially disabled.

If line antialiasing is disabled, the actual width is determined by rounding the supplied width to the nearest integer. (If the rounding results in the value 0, it is as if the line width were 1.) If .nf | DELTA x | >= | DELTA y |, .fi i pixels are filled in each column that is rasterized, where i is the rounded value of width. Otherwise, i pixels are filled in each row that is rasterized.

If antialiasing is enabled, line rasterization produces a fragment for each pixel square that intersects the region lying within the rectangle having width equal to the current line width, length equal to the actual length of the line, and centered on the mathematical line segment. The coverage value for each fragment is the window coordinate area of the intersection of the rectangular region with the corresponding pixel square. This value is saved and used in the final rasterization step.

Not all widths can be supported when line antialiasing is enabled. If an unsupported width is requested, the nearest supported width is used. Only width 1 is guaranteed to be supported; others depend on the implementation. To query the range of supported widths and the size difference between supported widths within the range, call glGet with arguments GL_LINE_WIDTH_RANGE and GL_LINE_WIDTH_GRANULARITY.

Specifies the width of rasterized lines. The initial value is 1.

GL_INVALID_VALUE is generated if width is less than or equal to 0.

GL_INVALID_OPERATION is generated if glLineWidth is executed between the execution of glBegin and the corresponding execution of glEnd.

glCallLists specifies an array of offsets. Display-list names are generated by adding base to each offset. Names that reference valid display lists are executed; the others are ignored.

Specifies an integer offset that will be added to glCallLists offsets to generate display-list names. The initial value is 0.

GL_INVALID_OPERATION is generated if glListBase is executed between the execution of glBegin and the corresponding execution of glEnd.

glLoadMatrix replaces the current matrix with the one whose elements are specified by m. The current matrix is the projection matrix, modelview matrix, or texture matrix, depending on the current matrix mode (see glMatrixMode).

The current matrix, M, defines a transformation of coordinates. For instance, assume M refers to the modelview matrix. If v ~=~ (v[0], v[1], v[2], v[3]) is the set of object coordinates of a vertex, and m points to an array of 16 single- or double-precision floating-point values m[0], m[1],. . .,m[15], then the modelview transformation M(v) does the following:

.ce .EQ down 130 {M(v) ~ = ~ {{ left ( matrix { ccol { ~m[0] above m[1] above m[2] above m[3] ~} ccol { ~m[4] above m[5] above m[6] above m[7] ~} ccol { ~m[8] above m[9] above m[10] above m[11] ~} ccol { ~m[12]~ above m[13]~ above m[14]~ above m[15]~} } right ) } ~~ times ~~ {left ( matrix { ccol { ~v[0]~ above ~v[1]~ above ~v[2]~ above ~v[3]~ } } right )} }} .EN

.sp

Where 'times' denotes matrix multiplication.

Projection and texture transformations are similarly defined.

Specifies a pointer to 16 consecutive values, which are used as the elements of a 4 times 4 column-major matrix.

GL_INVALID_OPERATION is generated if glLoadMatrix is executed between the execution of glBegin and the corresponding execution of glEnd.

The name stack is used during selection mode to allow sets of rendering commands to be uniquely identified. It consists of an ordered set of unsigned integers. glLoadName causes name to replace the value on the top of the name stack, which is initially empty.

The name stack is always empty while the render mode is not GL_SELECT. Calls to glLoadName while the render mode is not GL_SELECT are ignored.

Specifies a name that will replace the top value on the name stack.

GL_INVALID_OPERATION is generated if glLoadName is called while the name stack is empty.

GL_INVALID_OPERATION is generated if glLoadName is executed between the execution of glBegin and the corresponding execution of glEnd.

glMaterial assigns values to material parameters. There are two matched sets of material parameters. One, the front-facing set, is used to shade points, lines, bitmaps, and all polygons (when two-sided lighting is disabled), or just front-facing polygons (when two-sided lighting is enabled). The other set, back-facing, is used to shade back-facing polygons only when two-sided lighting is enabled. Refer to the glLightModel reference page for details concerning one- and two-sided lighting calculations.

glMaterial takes three arguments. The first, face, specifies whether the GL_FRONT materials, the GL_BACK materials, or both GL_FRONT_AND_BACK materials will be modified. The second, pname, specifies which of several parameters in one or both sets will be modified. The third, params, specifies what value or values will be assigned to the specified parameter.

Material parameters are used in the lighting equation that is optionally applied to each vertex. The equation is discussed in the glLightModel reference page. The parameters that can be specified using glMaterial, and their interpretations by the lighting equation, are as follows:

GL_AMBIENT params contains four integer or floating-point values that specify the ambient RGBA reflectance of the material. Integer values are mapped linearly such that the most positive representable value maps to 1.0, and the most negative representable value maps to -1.0. Floating-point values are mapped directly. Neither integer nor floating-point values are clamped. The initial ambient reflectance for both front- and back-facing materials is (0.2, 0.2, 0.2, 1.0). GL_DIFFUSE params contains four integer or floating-point values that specify the diffuse RGBA reflectance of the material. Integer values are mapped linearly such that the most positive representable value maps to 1.0, and the most negative representable value maps to -1.0. Floating-point values are mapped directly. Neither integer nor floating-point values are clamped. The initial diffuse reflectance for both front- and back-facing materials is (0.8, 0.8, 0.8, 1.0). GL_SPECULAR params contains four integer or floating-point values that specify the specular RGBA reflectance of the material. Integer values are mapped linearly such that the most positive representable value maps to 1.0, and the most negative representable value maps to -1.0. Floating-point values are mapped directly. Neither integer nor floating-point values are clamped. The initial specular reflectance for both front- and back-facing materials is (0, 0, 0, 1). GL_EMISSION params contains four integer or floating-point values that specify the RGBA emitted light intensity of the material. Integer values are mapped linearly such that the most positive representable value maps to 1.0, and the most negative representable value maps to -1.0. Floating-point values are mapped directly. Neither integer nor floating-point values are clamped. The initial emission intensity for both front- and back-facing materials is (0, 0, 0, 1). GL_SHININESS params is a single integer or floating-point value that specifies the RGBA specular exponent of the material. Integer and floating-point values are mapped directly. Only values in the range [0,128] are accepted. The initial specular exponent for both front- and back-facing materials is 0. GL_AMBIENT_AND_DIFFUSE Equivalent to calling glMaterial twice with the same parameter values, once with GL_AMBIENT and once with GL_DIFFUSE. GL_COLOR_INDEXES params contains three integer or floating-point values specifying the color indices for ambient, diffuse, and specular lighting. These three values, and GL_SHININESS, are the only material values used by the color index mode lighting equation. Refer to the glLightModel reference page for a discussion of color index lighting.

Specifies which face or faces are being updated. Must be one of GL_FRONT, GL_BACK, or GL_FRONT_AND_BACK.

Specifies the single-valued material parameter of the face or faces that is being updated. Must be GL_SHININESS.

Specifies the value that parameter GL_SHININESS will be set to.

Specifies which face or faces are being updated. Must be one of GL_FRONT, GL_BACK, or GL_FRONT_AND_BACK.

Specifies the material parameter of the face or faces that is being updated. Must be one of GL_AMBIENT, GL_DIFFUSE, GL_SPECULAR, GL_EMISSION, GL_SHININESS, GL_AMBIENT_AND_DIFFUSE, or GL_COLOR_INDEXES.

Specifies a pointer to the value or values that pname will be set to.

GL_INVALID_ENUM is generated if either face or pname is not an accepted value.

GL_INVALID_VALUE is generated if a specular exponent outside the range [0,128] is specified.

glMultMatrix multiplies the current matrix with the one specified using m, and replaces the current matrix with the product.

The current matrix is determined by the current matrix mode (see glMatrixMode). It is either the projection matrix, modelview matrix, or the texture matrix.

Points to 16 consecutive values that are used as the elements of a 4 times 4 column-major matrix.

GL_INVALID_OPERATION is generated if glMultMatrix is executed between the execution of glBegin and the corresponding execution of glEnd.

Display lists are groups of GL commands that have been stored for subsequent execution. Display lists are created with glNewList. All subsequent commands are placed in the display list, in the order issued, until glEndList is called.

glNewList has two arguments. The first argument, list, is a positive integer that becomes the unique name for the display list. Names can be created and reserved with glGenLists and tested for uniqueness with glIsList. The second argument, mode, is a symbolic constant that can assume one of two values:

GL_COMPILE Commands are merely compiled. GL_COMPILE_AND_EXECUTE Commands are executed as they are compiled into the display list.

Certain commands are not compiled into the display list but are executed immediately, regardless of the display-list mode. These commands are glColorPointer, glDeleteLists, glDisableClientState, glEdgeFlagPointer, glEnableClientState, glFeedbackBuffer, glFinish, glFlush, glGenLists, glIndexPointer, glInterleavedArrays, glIsEnabled, glIsList, glNormalPointer, glPopClientAttrib, glPixelStore, glPushClientAttrib, glReadPixels, glRenderMode, glSelectBuffer, glTexCoordPointer, glVertexPointer, and all of the glGet commands.

Similarly, glTexImage2D and glTexImage1D are executed immediately and not compiled into the display list when their first argument is GL_PROXY_TEXTURE_2D or GL_PROXY_TEXTURE_1D, respectively.

When glEndList is encountered, the display-list definition is completed by associating the list with the unique name list (specified in the glNewList command). If a display list with name list already exists, it is replaced only when glEndList is called.

Specifies the display-list name.

Specifies the compilation mode, which can be GL_COMPILE or GL_COMPILE_AND_EXECUTE.

GL_INVALID_VALUE is generated if list is 0.

GL_INVALID_ENUM is generated if mode is not an accepted value.

GL_INVALID_OPERATION is generated if glEndList is called without a preceding glNewList, or if glNewList is called while a display list is being defined.

GL_INVALID_OPERATION is generated if glNewList or glEndList is executed between the execution of glBegin and the corresponding execution of glEnd.

GL_OUT_OF_MEMORY is generated if there is insufficient memory to compile the display list. If the GL version is 1.1 or greater, no change is made to the previous contents of the display list, if any, and no other change is made to the GL state. (It is as if no attempt had been made to create the new display list.)

The current normal is set to the given coordinates whenever glNormal is issued. Byte, short, or integer arguments are converted to floating-point format with a linear mapping that maps the most positive representable integer value to 1.0, and the most negative representable integer value to -1.0.

Normals specified with glNormal need not have unit length. If normalization is enabled, then normals specified with glNormal are normalized after transformation. To enable and disable normalization, call glEnable and glDisable with the argument GL_NORMALIZE. Normalization is initially disabled.

Specify the x, y, and z coordinates of the new current normal. The initial value of the current normal is the unit vector, (0, 0, 1).

Specifies a pointer to an array of three elements: the x, y, and z coordinates of the new current normal.

glOrtho describes a transformation that produces a parallel projection. The current matrix (see glMatrixMode) is multiplied by this matrix and the result replaces the current matrix, as if glMultMatrix were called with the following matrix as its argument: .sp .ce .EQ left ( matrix { ccol { {2 over {"right" - "left"}} above 0 above 0 above 0 } ccol { 0 above {2 over {"top" - "bottom"}} above 0 above 0 } ccol { 0 above 0 above {-2 over {"zFar" - "zNear"}} above 0 } ccol { {t sub x}~ above {t sub y}~ above {t sub z}~ above 1~ } } right ) .EN

where .ce .EQ t sub x ~=~ -{{"right" + "left"} over {"right" - "left"}} .EN

.ce .EQ t sub y ~=~ -{{"top" + "bottom"} over {"top" - "bottom"}} .EN

.ce .EQ t sub z ~=~ -{{"zFar" + "zNear"} over {"zFar" - "zNear"}} .EN

.RE

Typically, the matrix mode is GL_PROJECTION, and (left, bottom, -zNear) and (right, top, -zNear) specify the points on the near clipping plane that are mapped to the lower left and upper right corners of the window, respectively, assuming that the eye is located at (0, 0, 0). -zFar specifies the location of the far clipping plane. Both zNear and zFar can be either positive or negative.

Use glPushMatrix and glPopMatrix to save and restore the current matrix stack.

Specify the coordinates for the left and right vertical clipping planes.

Specify the coordinates for the bottom and top horizontal clipping planes.

Specify the distances to the nearer and farther depth clipping planes. These values are negative if the plane is to be behind the viewer.

GL_INVALID_OPERATION is generated if glOrtho is executed between the execution of glBegin and the corresponding execution of glEnd.

Feedback is a GL render mode. The mode is selected by calling glRenderMode with GL_FEEDBACK. When the GL is in feedback mode, no pixels are produced by rasterization. Instead, information about primitives that would have been rasterized is fed back to the application using the GL. See the glFeedbackBuffer reference page for a description of the feedback buffer and the values in it.

glPassThrough inserts a user-defined marker in the feedback buffer when it is executed in feedback mode. token is returned as if it were a primitive; it is indicated with its own unique identifying value: GL_PASS_THROUGH_TOKEN. The order of glPassThrough commands with respect to the specification of graphics primitives is maintained.

Specifies a marker value to be placed in the feedback buffer following a GL_PASS_THROUGH_TOKEN.

GL_INVALID_OPERATION is generated if glPassThrough is executed between the execution of glBegin and the corresponding execution of glEnd.

glPixelZoom specifies values for the x and y zoom factors. During the execution of glDrawPixels or glCopyPixels, if (xr , yr ) is the current raster position, and a given element is in the mth row and nth column of the pixel rectangle, then pixels whose centers are in the rectangle with corners at .sp .ce (xr ~+~ n cdot "xfactor", yr ~+~ m cdot "yfactor") .sp .ce (xr ~+~ (n+1) cdot "xfactor", yr ~+~ (m+1) cdot "yfactor") .sp are candidates for replacement. Any pixel whose center lies on the bottom or left edge of this rectangular region is also modified.

Pixel zoom factors are not limited to positive values. Negative zoom factors reflect the resulting image about the current raster position.

Specify the x and y zoom factors for pixel write operations.

GL_INVALID_OPERATION is generated if glPixelZoom is executed between the execution of glBegin and the corresponding execution of glEnd.

glPointSize specifies the rasterized diameter of both aliased and antialiased points. Using a point size other than 1 has different effects, depending on whether point antialiasing is enabled. To enable and disable point antialiasing, call glEnable and glDisable with argument GL_POINT_SMOOTH. Point antialiasing is initially disabled.

If point antialiasing is disabled, the actual size is determined by rounding the supplied size to the nearest integer. (If the rounding results in the value 0, it is as if the point size were 1.) If the rounded size is odd, then the center point ( x , y ) of the pixel fragment that represents the point is computed as .sp .ce ( \(lf ~ x sub w ~ \(rf ~+~ .5 , \(lf ~ y sub w ~ \(rf ~+~ .5 ) .sp where w subscripts indicate window coordinates. All pixels that lie within the square grid of the rounded size centered at ( x , y ) make up the fragment. If the size is even, the center point is .sp .ce ( \(lf ~ x sub w ~+~ .5 ~ \(rf, \(lf ~ y sub w ~+~ .5 ~ \(rf ) .sp and the rasterized fragment's centers are the half-integer window coordinates within the square of the rounded size centered at ( x , y ). All pixel fragments produced in rasterizing a nonantialiased point are assigned the same associated data, that of the vertex corresponding to the point.

If antialiasing is enabled, then point rasterization produces a fragment for each pixel square that intersects the region lying within the circle having diameter equal to the current point size and centered at the point's ( x sub w , y sub w ). The coverage value for each fragment is the window coordinate area of the intersection of the circular region with the corresponding pixel square. This value is saved and used in the final rasterization step. The data associated with each fragment is the data associated with the point being rasterized.

Not all sizes are supported when point antialiasing is enabled. If an unsupported size is requested, the nearest supported size is used. Only size 1 is guaranteed to be supported; others depend on the implementation. To query the range of supported sizes and the size difference between supported sizes within the range, call glGet with arguments GL_POINT_SIZE_RANGE and GL_POINT_SIZE_GRANULARITY.

Specifies the diameter of rasterized points. The initial value is 1.

GL_INVALID_VALUE is generated if size is less than or equal to 0.

GL_INVALID_OPERATION is generated if glPointSize is executed between the execution of glBegin and the corresponding execution of glEnd.

glPolygonMode controls the interpretation of polygons for rasterization. face describes which polygons mode applies to: front-facing polygons (GL_FRONT), back-facing polygons (GL_BACK), or both (GL_FRONT_AND_BACK). The polygon mode affects only the final rasterization of polygons. In particular, a polygon's vertices are lit and the polygon is clipped and possibly culled before these modes are applied.

Three modes are defined and can be specified in mode:

GL_POINT Polygon vertices that are marked as the start of a boundary edge are drawn as points. Point attributes such as GL_POINT_SIZE and GL_POINT_SMOOTH control the rasterization of the points. Polygon rasterization attributes other than GL_POLYGON_MODE have no effect. GL_LINE Boundary edges of the polygon are drawn as line segments. They are treated as connected line segments for line stippling; the line stipple counter and pattern are not reset between segments (see glLineStipple). Line attributes such as GL_LINE_WIDTH and GL_LINE_SMOOTH control the rasterization of the lines. Polygon rasterization attributes other than GL_POLYGON_MODE have no effect. GL_FILL The interior of the polygon is filled. Polygon attributes such as GL_POLYGON_STIPPLE and GL_POLYGON_SMOOTH control the rasterization of the polygon.

Specifies the polygons that mode applies to. Must be GL_FRONT for front-facing polygons, GL_BACK for back-facing polygons, or GL_FRONT_AND_BACK for front- and back-facing polygons.

Specifies how polygons will be rasterized. Accepted values are GL_POINT, GL_LINE, and GL_FILL. The initial value is GL_FILL for both front- and back-facing polygons.

GL_INVALID_ENUM is generated if either face or mode is not an accepted value.

GL_INVALID_OPERATION is generated if glPolygonMode is executed between the execution of glBegin and the corresponding execution of glEnd.

When GL_POLYGON_OFFSET is enabled, each fragment's depth value will be offset after it is interpolated from the depth values of the appropriate vertices. The value of the offset is "factor" ~*~ DZ ~~+~~ r ~*~ "units", where DZ~ is a measurement of the change in depth relative to the screen area of the polygon, and r is the smallest value that is guaranteed to produce a resolvable offset for a given implementation. The offset is added before the depth test is performed and before the value is written into the depth buffer.

glPolygonOffset is useful for rendering hidden-line images, for applying decals to surfaces, and for rendering solids with highlighted edges.

Specifies a scale factor that is used to create a variable depth offset for each polygon. The initial value is 0.

Is multiplied by an implementation-specific value to create a constant depth offset. The initial value is 0.

GL_INVALID_OPERATION is generated if glPolygonOffset is executed between the execution of glBegin and the corresponding execution of glEnd.

glPushAttrib takes one argument, a mask that indicates which groups of state variables to save on the attribute stack. Symbolic constants are used to set bits in the mask. mask is typically constructed by ORing several of these constants together. The special mask GL_ALL_ATTRIB_BITS can be used to save all stackable states.

The symbolic mask constants and their associated GL state are as follows (the second column lists which attributes are saved):

.TS ; l l . GL_ACCUM_BUFFER_BIT Accumulation buffer clear value

GL_COLOR_BUFFER_BIT GL_ALPHA_TEST enable bit Alpha test function and reference value GL_BLEND enable bit Blending source and destination functions Constant blend color Blending equation GL_DITHER enable bit GL_DRAW_BUFFER setting GL_COLOR_LOGIC_OP enable bit GL_INDEX_LOGIC_OP enable bit Logic op function Color mode and index mode clear values Color mode and index mode writemasks

GL_CURRENT_BIT Current RGBA color Current color index Current normal vector Current texture coordinates Current raster position GL_CURRENT_RASTER_POSITION_VALID flag RGBA color associated with current raster position Color index associated with current raster position Texture coordinates associated with current raster position GL_EDGE_FLAG flag

GL_DEPTH_BUFFER_BIT GL_DEPTH_TEST enable bit Depth buffer test function Depth buffer clear value GL_DEPTH_WRITEMASK enable bit

GL_ENABLE_BIT GL_ALPHA_TEST flag GL_AUTO_NORMAL flag GL_BLEND flag Enable bits for the user-definable clipping planes GL_COLOR_MATERIAL GL_CULL_FACE flag GL_DEPTH_TEST flag GL_DITHER flag GL_FOG flag GL_LIGHT i where 0\ <= i<GL_MAX_LIGHTS GL_LIGHTING flag GL_LINE_SMOOTH flag GL_LINE_STIPPLE flag GL_COLOR_LOGIC_OP flag GL_INDEX_LOGIC_OP flag GL_MAP1_x where x is a map type GL_MAP2_x where x is a map type GL_NORMALIZE flag GL_POINT_SMOOTH flag GL_POLYGON_OFFSET_LINE flag GL_POLYGON_OFFSET_FILL flag GL_POLYGON_OFFSET_POINT flag GL_POLYGON_SMOOTH flag GL_POLYGON_STIPPLE flag GL_SCISSOR_TEST flag GL_STENCIL_TEST flag GL_TEXTURE_1D flag GL_TEXTURE_2D flag Flags GL_TEXTURE_GEN_x where x is S, T, R, or Q

GL_EVAL_BIT GL_MAP1_x enable bits, where x is a map type GL_MAP2_x enable bits, where x is a map type 1D grid endpoints and divisions 2D grid endpoints and divisions GL_AUTO_NORMAL enable bit

GL_FOG_BIT GL_FOG enable bit Fog color Fog density Linear fog start Linear fog end Fog index GL_FOG_MODE value

GL_HINT_BIT GL_PERSPECTIVE_CORRECTION_HINT setting GL_POINT_SMOOTH_HINT setting GL_LINE_SMOOTH_HINT setting GL_POLYGON_SMOOTH_HINT setting GL_FOG_HINT setting

GL_LIGHTING_BIT GL_COLOR_MATERIAL enable bit GL_COLOR_MATERIAL_FACE value Color material parameters that are tracking the current color Ambient scene color GL_LIGHT_MODEL_LOCAL_VIEWER value GL_LIGHT_MODEL_TWO_SIDE setting GL_LIGHTING enable bit Enable bit for each light Ambient, diffuse, and specular intensity for each light Direction, position, exponent, and cutoff angle for each light Constant, linear, and quadratic attenuation factors for each light Ambient, diffuse, specular, and emissive color for each material Ambient, diffuse, and specular color indices for each material Specular exponent for each material GL_SHADE_MODEL setting

GL_LINE_BIT GL_LINE_SMOOTH flag GL_LINE_STIPPLE enable bit Line stipple pattern and repeat counter Line width

GL_LIST_BIT GL_LIST_BASE setting

GL_PIXEL_MODE_BIT GL_RED_BIAS and GL_RED_SCALE settings GL_GREEN_BIAS and GL_GREEN_SCALE values GL_BLUE_BIAS and GL_BLUE_SCALE GL_ALPHA_BIAS and GL_ALPHA_SCALE GL_DEPTH_BIAS and GL_DEPTH_SCALE GL_INDEX_OFFSET and GL_INDEX_SHIFT values GL_MAP_COLOR and GL_MAP_STENCIL flags GL_ZOOM_X and GL_ZOOM_Y factors GL_READ_BUFFER setting

GL_POINT_BIT GL_POINT_SMOOTH flag Point size

GL_POLYGON_BIT GL_CULL_FACE enable bit GL_CULL_FACE_MODE value GL_FRONT_FACE indicator GL_POLYGON_MODE setting GL_POLYGON_SMOOTH flag GL_POLYGON_STIPPLE enable bit GL_POLYGON_OFFSET_FILL flag GL_POLYGON_OFFSET_LINE flag GL_POLYGON_OFFSET_POINT flag GL_POLYGON_OFFSET_FACTOR GL_POLYGON_OFFSET_UNITS

GL_POLYGON_STIPPLE_BIT Polygon stipple image

GL_SCISSOR_BIT GL_SCISSOR_TEST flag Scissor box

GL_STENCIL_BUFFER_BIT GL_STENCIL_TEST enable bit Stencil function and reference value Stencil value mask Stencil fail, pass, and depth buffer pass actions Stencil buffer clear value Stencil buffer writemask

GL_TEXTURE_BIT Enable bits for the four texture coordinates Border color for each texture image Minification function for each texture image Magnification function for each texture image Texture coordinates and wrap mode for each texture image Color and mode for each texture environment Enable bits GL_TEXTURE_GEN_x, x is S, T, R, and Q GL_TEXTURE_GEN_MODE setting for S, T, R, and Q glTexGen plane equations for S, T, R, and Q Current texture bindings (for example, GL_TEXTURE_2D_BINDING)

GL_TRANSFORM_BIT Coefficients of the six clipping planes Enable bits for the user-definable clipping planes GL_MATRIX_MODE value GL_NORMALIZE flag

GL_VIEWPORT_BIT Depth range (near and far) Viewport origin and extent .TE

glPopAttrib restores the values of the state variables saved with the last

glPushAttrib command. Those not saved are left unchanged.

It is an error to push attributes onto a full stack, or to pop attributes off an empty stack. In either case, the error flag is set and no other change is made to GL state.

Initially, the attribute stack is empty.

Specifies a mask that indicates which attributes to save. Values for mask are listed below.

GL_STACK_OVERFLOW is generated if glPushAttrib is called while the attribute stack is full.

GL_STACK_UNDERFLOW is generated if glPopAttrib is called while the attribute stack is empty.

GL_INVALID_OPERATION is generated if glPushAttrib or glPopAttrib is executed between the execution of glBegin and the corresponding execution of glEnd.

glPushClientAttrib takes one argument, a mask that indicates which groups of client-state variables to save on the client attribute stack. Symbolic constants are used to set bits in the mask. mask is typically constructed by OR'ing several of these constants together. The special mask GL_CLIENT_ALL_ATTRIB_BITS can be used to save all stackable client state.

The symbolic mask constants and their associated GL client state are as follows (the second column lists which attributes are saved):

GL_CLIENT_PIXEL_STORE_BIT Pixel storage modes

GL_CLIENT_VERTEX_ARRAY_BIT Vertex arrays (and enables)

glPopClientAttrib restores the values of the client-state variables saved with the last glPushClientAttrib. Those not saved are left unchanged.

It is an error to push attributes onto a full client attribute stack, or to pop attributes off an empty stack. In either case, the error flag is set, and no other change is made to GL state.

Initially, the client attribute stack is empty.

Specifies a mask that indicates which attributes to save. Values for mask are listed below.

GL_STACK_OVERFLOW is generated if glPushClientAttrib is called while the attribute stack is full.

GL_STACK_UNDERFLOW is generated if glPopClientAttrib is called while the attribute stack is empty.

The name stack is used during selection mode to allow sets of rendering commands to be uniquely identified. It consists of an ordered set of unsigned integers and is initially empty.

glPushName causes name to be pushed onto the name stack. glPopName pops one name off the top of the stack.

The maximum name stack depth is implementation-dependent; call GL_MAX_NAME_STACK_DEPTH to find out the value for a particular implementation. It is an error to push a name onto a full stack, or to pop a name off an empty stack. It is also an error to manipulate the name stack between the execution of glBegin and the corresponding execution of glEnd. In any of these cases, the error flag is set and no other change is made to GL state.

The name stack is always empty while the render mode is not GL_SELECT. Calls to glPushName or glPopName while the render mode is not GL_SELECT are ignored.

Specifies a name that will be pushed onto the name stack.

GL_STACK_OVERFLOW is generated if glPushName is called while the name stack is full.

GL_STACK_UNDERFLOW is generated if glPopName is called while the name stack is empty.

GL_INVALID_OPERATION is generated if glPushName or glPopName is executed between a call to glBegin and the corresponding call to glEnd.

The GL maintains a 3D position in window coordinates. This position, called the raster position, is used to position pixel and bitmap write operations. It is maintained with subpixel accuracy. See glBitmap, glDrawPixels, and glCopyPixels.

The current raster position consists of three window coordinates (x, y, z), a clip coordinate value (w), an eye coordinate distance, a valid bit, and associated color data and texture coordinates. The w coordinate is a clip coordinate, because w is not projected to window coordinates. The variable z defaults to 0 and w defaults to 1.

The object coordinates presented by glRasterPos are treated just like those of a glVertex command: They are transformed by the current modelview and projection matrices and passed to the clipping stage. If the vertex is not culled, then it is projected and scaled to window coordinates, which become the new current raster position, and the GL_CURRENT_RASTER_POSITION_VALID flag is set. If the vertex .I is culled, then the valid bit is cleared and the current raster position and associated color and texture coordinates are undefined.

The current raster position also includes some associated color data and texture coordinates. If lighting is enabled, then GL_CURRENT_RASTER_COLOR (in RGBA mode) or GL_CURRENT_RASTER_INDEX (in color index mode) is set to the color produced by the lighting calculation (see glLight, glLightModel, and

glShadeModel). If lighting is disabled, current color (in RGBA mode, state variable GL_CURRENT_COLOR) or color index (in color index mode, state variable GL_CURRENT_INDEX) is used to update the current raster color.

Likewise, GL_CURRENT_RASTER_TEXTURE_COORDS is updated as a function of GL_CURRENT_TEXTURE_COORDS, based on the texture matrix and the texture generation functions (see glTexGen). Finally, the distance from the origin of the eye coordinate system to the vertex as transformed by only the modelview matrix replaces GL_CURRENT_RASTER_DISTANCE.

Initially, the current raster position is (0, 0, 0, 1), the current raster distance is 0, the valid bit is set, the associated RGBA color is (1, 1, 1, 1), the associated color index is 1, and the associated texture coordinates are (0, 0, 0, 1). In RGBA mode, GL_CURRENT_RASTER_INDEX is always 1; in color index mode, the current raster RGBA color always maintains its initial value.

Specify the x, y, z, and w object coordinates (if present) for the raster position.

Specifies a pointer to an array of two, three, or four elements, specifying x, y, z, and w coordinates, respectively.

GL_INVALID_OPERATION is generated if glRasterPos is executed between the execution of glBegin and the corresponding execution of glEnd.

glRotate produces a rotation of angle degrees around the vector ("x", "y", "z"). The current matrix (see glMatrixMode) is multiplied by a rotation matrix with the product replacing the current matrix, as if glMultMatrix were called with the following matrix as its argument:

.ce .EQ left ( ~ down 20 matrix { ccol { "x" "x" (1 - c)+ c above "y" "x" (1 - c)+ "z" s above "x" "z" (1 - c)-"y" s above ~0 } ccol {"x" "y" (1 - c)-"z" s above "y" "y" (1 - c)+ c above "y" "z" (1 - c)+ "x" s above ~0 } ccol { "x" "z" (1 - c)+ "y" s above "y" "z" (1 - c)- "x" s above "z" "z" (1 - c) + c above ~0 } ccol { ~0 above ~0 above ~0 above ~1} } ~~ right ) .EN

.sp Where c ~=~ cos("angle"), s ~=~ sine("angle"), and ||(~"x", "y", "z"~)|| ~=~ 1 (if not, the GL will normalize this vector). .sp .sp

If the matrix mode is either GL_MODELVIEW or GL_PROJECTION, all objects drawn after glRotate is called are rotated. Use glPushMatrix and glPopMatrix to save and restore the unrotated coordinate system.

Specifies the angle of rotation, in degrees.

Specify the x, y, and z coordinates of a vector, respectively.

GL_INVALID_OPERATION is generated if glRotate is executed between the execution of glBegin and the corresponding execution of glEnd.

glScale produces a nonuniform scaling along the x, y, and z axes. The three parameters indicate the desired scale factor along each of the three axes.

The current matrix (see glMatrixMode) is multiplied by this scale matrix, and the product replaces the current matrix as if glScale were called with the following matrix as its argument:

.ce .EQ left ( ~ down 20 matrix { ccol { ~"x" above ~0 above ~0 above ~0 } ccol { ~0 above ~"y" above ~0 above ~0 } ccol { ~0 above ~0 above ~"z" above ~0 } ccol { ~0 above ~0 above ~0 above ~1} } ~~ right ) .EN .sp If the matrix mode is either GL_MODELVIEW or GL_PROJECTION, all objects drawn after glScale is called are scaled.

Use glPushMatrix and glPopMatrix to save and restore the unscaled coordinate system.

Specify scale factors along the x, y, and z axes, respectively.

GL_INVALID_OPERATION is generated if glScale is executed between the execution of glBegin and the corresponding execution of glEnd.

glScissor defines a rectangle, called the scissor box, in window coordinates. The first two arguments, x and y, specify the lower left corner of the box. width and height specify the width and height of the box.

To enable and disable the scissor test, call glEnable and glDisable with argument GL_SCISSOR_TEST. The test is initially disabled. While the test is enabled, only pixels that lie within the scissor box can be modified by drawing commands. Window coordinates have integer values at the shared corners of frame buffer pixels. \f7glScissor(0,0,1,1)\fP allows modification of only the lower left pixel in the window, and \f7glScissor(0,0,0,0)\fP doesn't allow modification of any pixels in the window.

When the scissor test is disabled, it is as though the scissor box includes the entire window.

Specify the lower left corner of the scissor box. Initially (0, 0).

Specify the width and height of the scissor box. When a GL context is first attached to a window, width and height are set to the dimensions of that window.

GL_INVALID_VALUE is generated if either width or height is negative.

GL_INVALID_OPERATION is generated if glScissor is executed between the execution of glBegin and the corresponding execution of glEnd.

Stenciling, like depth-buffering, enables and disables drawing on a per-pixel basis. You draw into the stencil planes using GL drawing primitives, then render geometry and images, using the stencil planes to mask out portions of the screen. Stenciling is typically used in multipass rendering algorithms to achieve special effects, such as decals, outlining, and constructive solid geometry rendering.

The stencil test conditionally eliminates a pixel based on the outcome of a comparison between the reference value and the value in the stencil buffer. To enable and disable the test, call glEnable and glDisable with argument GL_STENCIL_TEST. To specify actions based on the outcome of the stencil test, call glStencilOp.

func is a symbolic constant that determines the stencil comparison function. It accepts one of eight values, shown in the following list. ref is an integer reference value that is used in the stencil comparison. It is clamped to the range [0,2 sup n - 1], where n is the number of bitplanes in the stencil buffer. mask is bitwise ANDed with both the reference value and the stored stencil value, with the ANDed values participating in the comparison. .P If stencil represents the value stored in the corresponding stencil buffer location, the following list shows the effect of each comparison function that can be specified by func. Only if the comparison succeeds is the pixel passed through to the next stage in the rasterization process (see glStencilOp). All tests treat stencil values as unsigned integers in the range [0,2 sup n - 1], where n is the number of bitplanes in the stencil buffer.

The following values are accepted by func:

GL_NEVER Always fails. GL_LESS Passes if ( ref & mask ) < ( stencil & mask ). GL_LEQUAL Passes if ( ref & mask ) \(<= ( stencil & mask ). GL_GREATER Passes if ( ref & mask ) > ( stencil & mask ). GL_GEQUAL Passes if ( ref & mask ) \(>= ( stencil & mask ). GL_EQUAL Passes if ( ref & mask ) = ( stencil & mask ). GL_NOTEQUAL Passes if ( ref & mask ) \(!= ( stencil & mask ). GL_ALWAYS Always passes.

Specifies the test function. Eight tokens are valid: GL_NEVER, GL_LESS, GL_LEQUAL, GL_GREATER, GL_GEQUAL, GL_EQUAL, GL_NOTEQUAL, and GL_ALWAYS. The initial value is GL_ALWAYS.

Specifies the reference value for the stencil test. ref is clamped to the range [0,2 sup n - 1], where n is the number of bitplanes in the stencil buffer. The initial value is 0.

Specifies a mask that is ANDed with both the reference value and the stored stencil value when the test is done. The initial value is all 1's.

GL_INVALID_ENUM is generated if func is not one of the eight accepted values.

GL_INVALID_OPERATION is generated if glStencilFunc is executed between the execution of glBegin and the corresponding execution of glEnd.

glStencilMask controls the writing of individual bits in the stencil planes. The least significant n bits of mask, where n is the number of bits in the stencil buffer, specify a mask. Where a 1 appears in the mask, it's possible to write to the corresponding bit in the stencil buffer. Where a 0 appears, the corresponding bit is write-protected. Initially, all bits are enabled for writing.

Specifies a bit mask to enable and disable writing of individual bits in the stencil planes. Initially, the mask is all 1's.

GL_INVALID_OPERATION is generated if glStencilMask is executed between the execution of glBegin and the corresponding execution of glEnd.

Stenciling, like depth-buffering, enables and disables drawing on a per-pixel basis. You draw into the stencil planes using GL drawing primitives, then render geometry and images, using the stencil planes to mask out portions of the screen. Stenciling is typically used in multipass rendering algorithms to achieve special effects, such as decals, outlining, and constructive solid geometry rendering.

The stencil test conditionally eliminates a pixel based on the outcome of a comparison between the value in the stencil buffer and a reference value. To enable and disable the test, call glEnable and glDisable with argument GL_STENCIL_TEST; to control it, call glStencilFunc.

glStencilOp takes three arguments that indicate what happens to the stored stencil value while stenciling is enabled. If the stencil test fails, no change is made to the pixel's color or depth buffers, and fail specifies what happens to the stencil buffer contents. The following six actions are possible.

GL_KEEP Keeps the current value. GL_ZERO Sets the stencil buffer value to 0. GL_REPLACE Sets the stencil buffer value to ref, as specified by glStencilFunc. GL_INCR Increments the current stencil buffer value. Clamps to the maximum representable unsigned value. GL_DECR Decrements the current stencil buffer value. Clamps to 0. GL_INVERT Bitwise inverts the current stencil buffer value.

Stencil buffer values are treated as unsigned integers. When incremented and decremented, values are clamped to 0 and 2 sup n - 1, where n is the value returned by querying GL_STENCIL_BITS.

The other two arguments to glStencilOp specify stencil buffer actions that depend on whether subsequent depth buffer tests succeed (zpass) or fail (zfail) (see

glDepthFunc). The actions are specified using the same six symbolic constants as fail. Note that zfail is ignored when there is no depth buffer, or when the depth buffer is not enabled. In these cases, fail and zpass specify stencil action when the stencil test fails and passes, respectively.

Specifies the action to take when the stencil test fails. Six symbolic constants are accepted: GL_KEEP, GL_ZERO, GL_REPLACE, GL_INCR, GL_DECR, and GL_INVERT. The initial value is GL_KEEP.

Specifies the stencil action when the stencil test passes, but the depth test fails. zfail accepts the same symbolic constants as fail. The initial value is GL_KEEP.

Specifies the stencil action when both the stencil test and the depth test pass, or when the stencil test passes and either there is no depth buffer or depth testing is not enabled. zpass accepts the same symbolic constants as fail. The initial value is GL_KEEP.

GL_INVALID_ENUM is generated if fail, zfail, or zpass is any value other than the six defined constant values.

GL_INVALID_OPERATION is generated if glStencilOp is executed between the execution of glBegin and the corresponding execution of glEnd.

glTexCoord specifies texture coordinates in one, two, three, or four dimensions. glTexCoord1 sets the current texture coordinates to (s, 0, 0, 1); a call to

glTexCoord2 sets them to (s, t, 0, 1). Similarly, glTexCoord3 specifies the texture coordinates as (s, t, r, 1), and glTexCoord4 defines all four components explicitly as (s, t, r, q).

The current texture coordinates are part of the data that is associated with each vertex and with the current raster position. Initially, the values for s, t, r, and q are (0, 0, 0, 1).

Specify s, t, r, and q texture coordinates. Not all parameters are present in all forms of the command.

Specifies a pointer to an array of one, two, three, or four elements, which in turn specify the s, t, r, and q texture coordinates.

A texture environment specifies how texture values are interpreted when a fragment is textured. target must be GL_TEXTURE_ENV. pname can be either GL_TEXTURE_ENV_MODE or GL_TEXTURE_ENV_COLOR.

If pname is GL_TEXTURE_ENV_MODE, then params is (or points to) the symbolic name of a texture function. Four texture functions may be specified: GL_MODULATE, GL_DECAL, GL_BLEND, and GL_REPLACE.

A texture function acts on the fragment to be textured using the texture image value that applies to the fragment (see glTexParameter) and produces an RGBA color for that fragment. The following table shows how the RGBA color is produced for each of the three texture functions that can be chosen. C is a triple of color values (RGB) and A is the associated alpha value. RGBA values extracted from a texture image are in the range [0,1]. The subscript f refers to the incoming fragment, the subscript t to the texture image, the subscript c to the texture environment color, and subscript v indicates a value produced by the texture function.

A texture image can have up to four components per texture element (see glTexImage1D, glTexImage2D, glCopyTexImage1D, and glCopyTexImage2D). In a one-component image, L sub t indicates that single component. A two-component image uses L sub t and A sub t. A three-component image has only a color value, C sub t. A four-component image has both a color value C sub t and an alpha value A sub t.

.ne .TS center box tab(:) ; ci || ci s s s ci || c c c c c || c | c | c | c. Base internal:Texture functions format:GL_MODULATE:GL_DECAL:GL_BLEND:GL_REPLACE = GL_ALPHA:C sub v = C sub f:undefined:C sub v = C sub f:C sub v = C sub f \^ :A sub v = A sub f A sub t:\^:A sub v = A sub f:A sub v = A sub t _ GL_LUMINANCE:C sub v = L sub t C sub f:undefined:C sub v = ( 1 - L sub t ) C sub f:C sub v = L sub t 1: : :+ L sub t C sub c: : : : : : A sub v = A sub f:\^: A sub v = A sub f:A sub v = A sub f _ GL_LUMINANCE:C sub v = L sub t C sub f:undefined:C sub v = ( 1 - L sub t ) C sub f :C sub v = L sub t \_ALPHA: : : + L sub t C sub c 2: : : : :A sub v = A sub t A sub f:\^:A sub v = A sub t A sub f:A sub v = A sub t _ GL_INTENSITY:C sub v = C sub f I sub t:undefined:C sub v = ( 1 - I sub t ) C sub f :C sub v = I sub t : : :+ I sub t C sub c : : : : \^ :A sub v = A sub f I sub t:\^:A sub v = ( 1 - I sub t ) A sub f :A sub v = I sub t : : :+ I sub t A sub c: _ GL_RGB:C sub v = C sub t C sub f:C sub v = C sub t:C sub v = (1 - C sub t) C sub f :C sub v = C sub t 3: : : + C sub t C sub c : : : : :A sub v = A sub f:A sub v = A sub f:A sub v = A sub f:A sub v = A sub f _ GL_RGBA:C sub v = C sub t C sub f:C sub v = ( 1 - A sub t ) C sub f :C sub v = (1 - C sub t) C sub f :C sub v = C sub t 4: :+ A sub t C sub t: + C sub t C sub c : : : : :A sub v = A sub t A sub f:A sub v = A sub f:A sub v = A sub t A sub f:A sub v = A sub t .TE .sp If pname is GL_TEXTURE_ENV_COLOR, params is a pointer to an array that holds an RGBA color consisting of four values. Integer color components are interpreted linearly such that the most positive integer maps to 1.0, and the most negative integer maps to -1.0. The values are clamped to the range [0,1] when they are specified. C sub c takes these four values.

GL_TEXTURE_ENV_MODE defaults to GL_MODULATE and GL_TEXTURE_ENV_COLOR defaults to (0, 0, 0, 0).

Specifies a texture environment. Must be GL_TEXTURE_ENV.

Specifies the symbolic name of a single-valued texture environment parameter. Must be GL_TEXTURE_ENV_MODE.

Specifies a single symbolic constant, one of GL_MODULATE, GL_DECAL, GL_BLEND, or GL_REPLACE.

Specifies a texture environment. Must be GL_TEXTURE_ENV.

Specifies the symbolic name of a texture environment parameter. Accepted values are GL_TEXTURE_ENV_MODE and GL_TEXTURE_ENV_COLOR.

Specifies a pointer to a parameter array that contains either a single symbolic constant or an RGBA color.

GL_INVALID_ENUM is generated when target or pname is not one of the accepted defined values, or when params should have a defined constant value (based on the value of pname) and does not.

GL_INVALID_OPERATION is generated if glTexEnv is executed between the execution of glBegin and the corresponding execution of glEnd.

glTexGen selects a texture-coordinate generation function or supplies coefficients for one of the functions. coord names one of the (s, t, r, q) texture coordinates; it must be one of the symbols GL_S, GL_T, GL_R, or GL_Q. pname must be one of three symbolic constants: GL_TEXTURE_GEN_MODE, GL_OBJECT_PLANE, or GL_EYE_PLANE. If pname is GL_TEXTURE_GEN_MODE, then params chooses a mode, one of GL_OBJECT_LINEAR, GL_EYE_LINEAR, or GL_SPHERE_MAP. If pname is either GL_OBJECT_PLANE or GL_EYE_PLANE, params contains coefficients for the corresponding texture generation function. .P If the texture generation function is GL_OBJECT_LINEAR, the function

.ce g = p sub 1 x sub o + p sub 2 y sub o + p sub 3 z sub o + p sub 4 w sub o

is used, where g is the value computed for the coordinate named in coord, p sub 1, p sub 2, p sub 3, and p sub 4 are the four values supplied in params, and x sub o, y sub o, z sub o, and w sub o are the object coordinates of the vertex. This function can be used, for example, to texture-map terrain using sea level as a reference plane (defined by p sub 1, p sub 2, p sub 3, and p sub 4). The altitude of a terrain vertex is computed by the GL_OBJECT_LINEAR coordinate generation function as its distance from sea level; that altitude can then be used to index the texture image to map white snow onto peaks and green grass onto foothills.

If the texture generation function is GL_EYE_LINEAR, the function

.ce g = {p sub 1} sup prime ~x sub e + {p sub 2} sup prime ~y sub e + {p sub 3} sup prime ~z sub e + {p sub 4} sup prime ~w sub e

is used, where

.ce $( {p sub 1} sup prime ~~{p sub 2} sup prime~~{p sub 3} sup prime~~ {{p sub 4}sup prime}) = ( p sub 1~~ p sub 2~~ p sub 3~~ p sub 4 ) ~M sup -1$

and x sub e, y sub e, z sub e, and w sub e are the eye coordinates of the vertex, p sub 1, p sub 2, p sub 3, and p sub 4 are the values supplied in params, and M is the modelview matrix when glTexGen is invoked. If M is poorly conditioned or singular, texture coordinates generated by the resulting function may be inaccurate or undefined.

Note that the values in params define a reference plane in eye coordinates. The modelview matrix that is applied to them may not be the same one in effect when the polygon vertices are transformed. This function establishes a field of texture coordinates that can produce dynamic contour lines on moving objects.

If pname is GL_SPHERE_MAP and coord is either GL_S or GL_T, s and t texture coordinates are generated as follows. Let u be the unit vector pointing from the origin to the polygon vertex (in eye coordinates). Let n sup prime be the current normal, after transformation to eye coordinates. Let

.ce f ~=~ ( f sub x~~f sub y~~f sub z ) sup T be the reflection vector such that

.ce f ~=~ u ~-~ 2 n sup prime n sup prime sup T u

Finally, let m ~=~ 2 sqrt { f sub x sup {~2} + f sub y sup {~2} + (f sub z + 1 ) sup 2}. Then the values assigned to the s and t texture coordinates are

.ce 1 s ~=~ f sub x over m ~+~ 1 over 2 .sp .ce 1 t ~=~ f sub y over m ~+~ 1 over 2

To enable or disable a texture-coordinate generation function, call glEnable or glDisable with one of the symbolic texture-coordinate names (GL_TEXTURE_GEN_S, GL_TEXTURE_GEN_T, GL_TEXTURE_GEN_R, or GL_TEXTURE_GEN_Q) as the argument. When enabled, the specified texture coordinate is computed according to the generating function associated with that coordinate. When disabled, subsequent vertices take the specified texture coordinate from the current set of texture coordinates. Initially, all texture generation functions are set to GL_EYE_LINEAR and are disabled. Both s plane equations are (1, 0, 0, 0), both t plane equations are (0, 1, 0, 0), and all r and q plane equations are (0, 0, 0, 0).

Specifies a texture coordinate. Must be one of GL_S, GL_T, GL_R, or GL_Q.

Specifies the symbolic name of the texture-coordinate generation function. Must be GL_TEXTURE_GEN_MODE.

Specifies a single-valued texture generation parameter, one of GL_OBJECT_LINEAR, GL_EYE_LINEAR, or GL_SPHERE_MAP.

Specifies a texture coordinate. Must be one of GL_S, GL_T, GL_R, or GL_Q.

Specifies the symbolic name of the texture-coordinate generation function or function parameters. Must be GL_TEXTURE_GEN_MODE, GL_OBJECT_PLANE, or GL_EYE_PLANE.

Specifies a pointer to an array of texture generation parameters. If pname is GL_TEXTURE_GEN_MODE, then the array must contain a single symbolic constant, one of GL_OBJECT_LINEAR, GL_EYE_LINEAR, or GL_SPHERE_MAP. Otherwise, params holds the coefficients for the texture-coordinate generation function specified by pname.

GL_INVALID_ENUM is generated when coord or pname is not an accepted defined value, or when pname is GL_TEXTURE_GEN_MODE and params is not an accepted defined value.

GL_INVALID_ENUM is generated when pname is GL_TEXTURE_GEN_MODE, params is GL_SPHERE_MAP, and coord is either GL_R or GL_Q.

GL_INVALID_OPERATION is generated if glTexGen is executed between the execution of glBegin and the corresponding execution of glEnd.

Texturing maps a portion of a specified texture image onto each graphical primitive for which texturing is enabled. To enable and disable two-dimensional texturing, call glEnable and glDisable with argument GL_TEXTURE_2D.

To define texture images, call glTexImage2D. The arguments describe the parameters of the texture image, such as height, width, width of the border, level-of-detail number (see glTexParameter), and number of color components provided. The last three arguments describe how the image is represented in memory; they are identical to the pixel formats used for glDrawPixels.

If target is GL_PROXY_TEXTURE_2D, no data is read from pixels, but all of the texture image state is recalculated, checked for consistency, and checked against the implementation's capabilities. If the implementation cannot handle a texture of the requested texture size, it sets all of the image state to 0, but does not generate an error (see glGetError). To query for an entire mipmap array, use an image array level greater than or equal to 1. .P If target is GL_TEXTURE_2D, data is read from pixels as a sequence of signed or unsigned bytes, shorts, or longs, or single-precision floating-point values, depending on type. These values are grouped into sets of one, two, three, or four values, depending on format, to form elements. If type is GL_BITMAP, the data is considered as a string of unsigned bytes (and format must be GL_COLOR_INDEX). Each data byte is treated as eight 1-bit elements, with bit ordering determined by GL_UNPACK_LSB_FIRST (see glPixelStore).

The first element corresponds to the lower left corner of the texture image. Subsequent elements progress left-to-right through the remaining texels in the lowest row of the texture image, and then in successively higher rows of the texture image. The final element corresponds to the upper right corner of the texture image.

format determines the composition of each element in pixels. It can assume one of nine symbolic values:

GL_COLOR_INDEX Each element is a single value, a color index. The GL converts it to fixed point (with an unspecified number of zero bits to the right of the binary point), shifted left or right depending on the value and sign of GL_INDEX_SHIFT, and added to GL_INDEX_OFFSET (see glPixelTransfer). The resulting index is converted to a set of color components using the GL_PIXEL_MAP_I_TO_R, GL_PIXEL_MAP_I_TO_G, GL_PIXEL_MAP_I_TO_B, and GL_PIXEL_MAP_I_TO_A tables, and clamped to the range [0,1]. GL_RED Each element is a single red component. The GL converts it to floating point and assembles it into an RGBA element by attaching 0 for green and blue, and 1 for alpha. Each component is then multiplied by the signed scale factor GL_c_SCALE, added to the signed bias GL_c_BIAS, and clamped to the range [0,1] (see glPixelTransfer). GL_GREEN Each element is a single green component. The GL converts it to floating point and assembles it into an RGBA element by attaching 0 for red and blue, and 1 for alpha. Each component is then multiplied by the signed scale factor GL_c_SCALE, added to the signed bias GL_c_BIAS, and clamped to the range [0,1] (see glPixelTransfer). GL_BLUE Each element is a single blue component. The GL converts it to floating point and assembles it into an RGBA element by attaching 0 for red and green, and 1 for alpha. Each component is then multiplied by the signed scale factor GL_c_SCALE, added to the signed bias GL_c_BIAS, and clamped to the range [0,1] (see glPixelTransfer). GL_ALPHA Each element is a single alpha component. The GL converts it to floating point and assembles it into an RGBA element by attaching 0 for red, green, and blue. Each component is then multiplied by the signed scale factor GL_c_SCALE, added to the signed bias GL_c_BIAS, and clamped to the range [0,1] (see glPixelTransfer). GL_RGB Each element is an RGB triple. The GL converts it to floating point and assembles it into an RGBA element by attaching 1 for alpha. Each component is then multiplied by the signed scale factor GL_c_SCALE, added to the signed bias GL_c_BIAS, and clamped to the range [0,1] (see glPixelTransfer). GL_RGBA Each element contains all four components. Each component is multiplied by the signed scale factor GL_c_SCALE, added to the signed bias GL_c_BIAS, and clamped to the range [0,1] (see glPixelTransfer). GL_LUMINANCE Each element is a single luminance value. The GL converts it to floating point, then assembles it into an RGBA element by replicating the luminance value three times for red, green, and blue and attaching 1 for alpha. Each component is then multiplied by the signed scale factor GL_c_SCALE, added to the signed bias GL_c_BIAS, and clamped to the range [0,1] (see glPixelTransfer). GL_LUMINANCE_ALPHA Each element is a luminance/alpha pair. The GL converts it to floating point, then assembles it into an RGBA element by replicating the luminance value three times for red, green, and blue. Each component is then multiplied by the signed scale factor GL_c_SCALE, added to the signed bias GL_c_BIAS, and clamped to the range [0,1] (see glPixelTransfer).

Refer to the glDrawPixels reference page for a description of the acceptable values for the type parameter.

If an application wants to store the texture at a certain resolution or in a certain format, it can request the resolution and format with internalformat. The GL will choose an internal representation that closely approximates that requested by internalformat, but it may not match exactly. (The representations specified by GL_LUMINANCE, GL_LUMINANCE_ALPHA, GL_RGB, and GL_RGBA must match exactly. The numeric values 1, 2, 3, and 4 may also be used to specify the above representations.)

Use the GL_PROXY_TEXTURE_2D target to try out a resolution and format. The implementation will update and recompute its best match for the requested storage resolution and format. To then query this state, call glGetTexLevelParameter. If the texture cannot be accommodated, texture state is set to 0.

A one-component texture image uses only the red component of the RGBA color extracted from pixels. A two-component image uses the R and A values. A three-component image uses the R, G, and B values. A four-component image uses all of the RGBA components.

Specifies the target texture. Must be GL_TEXTURE_2D or GL_PROXY_TEXTURE_2D.

Specifies the level-of-detail number. Level 0 is the base image level. Level n is the nth mipmap reduction image.

Specifies the number of color components in the texture. Must be 1, 2, 3, or 4, or one of the following symbolic constants: GL_ALPHA, GL_ALPHA4, GL_ALPHA8, GL_ALPHA12, GL_ALPHA16, GL_LUMINANCE, GL_LUMINANCE4, GL_LUMINANCE8, GL_LUMINANCE12, GL_LUMINANCE16, GL_LUMINANCE_ALPHA, GL_LUMINANCE4_ALPHA4, GL_LUMINANCE6_ALPHA2, GL_LUMINANCE8_ALPHA8, GL_LUMINANCE12_ALPHA4, GL_LUMINANCE12_ALPHA12, GL_LUMINANCE16_ALPHA16, GL_INTENSITY, GL_INTENSITY4, GL_INTENSITY8, GL_INTENSITY12, GL_INTENSITY16, GL_R3_G3_B2, GL_RGB, GL_RGB4, GL_RGB5, GL_RGB8, GL_RGB10, GL_RGB12, GL_RGB16, GL_RGBA, GL_RGBA2, GL_RGBA4, GL_RGB5_A1, GL_RGBA8, GL_RGB10_A2, GL_RGBA12, or GL_RGBA16.

Specifies the width of the texture image. Must be 2 sup n + 2 ( "border" ) for some integer n. All implementations support texture images that are at least 64 texels wide.

Specifies the height of the texture image. Must be 2 sup m + 2 ( "border" ) for some integer m. All implementations support texture images that are at least 64 texels high.

Specifies the width of the border. Must be either 0 or 1.

Specifies the format of the pixel data. The following symbolic values are accepted: GL_COLOR_INDEX, GL_RED, GL_GREEN, GL_BLUE, GL_ALPHA, GL_RGB, GL_RGBA, GL_LUMINANCE, and GL_LUMINANCE_ALPHA.

Specifies the data type of the pixel data. The following symbolic values are accepted: GL_UNSIGNED_BYTE, GL_BYTE, GL_BITMAP, GL_UNSIGNED_SHORT, GL_SHORT, GL_UNSIGNED_INT, GL_INT, and GL_FLOAT.

Specifies a pointer to the image data in memory.

GL_INVALID_ENUM is generated if target is not GL_TEXTURE_2D or GL_PROXY_TEXTURE_2D.

GL_INVALID_ENUM is generated if format is not an accepted format constant. Format constants other than GL_STENCIL_INDEX and GL_DEPTH_COMPONENT are accepted.

GL_INVALID_ENUM is generated if type is not a type constant.

GL_INVALID_ENUM is generated if type is GL_BITMAP and format is not GL_COLOR_INDEX.

GL_INVALID_VALUE is generated if level is less than 0. .P .P GL_INVALID_VALUE may be generated if level is greater than $log sub 2$max, where max is the returned value of GL_MAX_TEXTURE_SIZE.

GL_INVALID_VALUE is generated if internalformat is not 1, 2, 3, 4, or one of the accepted resolution and format symbolic constants.

GL_INVALID_VALUE is generated if width or height is less than 0 or greater than 2 + GL_MAX_TEXTURE_SIZE, or if either cannot be represented as 2 sup k + 2("border") for some integer value of k.

GL_INVALID_VALUE is generated if border is not 0 or 1.

GL_INVALID_OPERATION is generated if glTexImage2D is executed between the execution of glBegin and the corresponding execution of glEnd.

Texture mapping is a technique that applies an image onto an object's surface as if the image were a decal or cellophane shrink-wrap. The image is created in texture space, with an (s, t) coordinate system. A texture is a one- or two-dimensional image and a set of parameters that determine how samples are derived from the image.

glTexParameter assigns the value or values in params to the texture parameter specified as pname. target defines the target texture, either GL_TEXTURE_1D or GL_TEXTURE_2D. The following symbols are accepted in pname:

GL_TEXTURE_MIN_FILTER The texture minifying function is used whenever the pixel being textured maps to an area greater than one texture element. There are six defined minifying functions. Two of them use the nearest one or nearest four texture elements to compute the texture value. The other four use mipmaps. A mipmap is an ordered set of arrays representing the same image at progressively lower resolutions. If the texture has dimensions 2 sup n times 2 sup m, there are bold max ( n, m ) + 1 mipmaps. The first mipmap is the original texture, with dimensions 2 sup n times 2 sup m. Each subsequent mipmap has dimensions 2 sup { k - 1 } times 2 sup { l - 1 }, where 2 sup k times 2 sup l are the dimensions of the previous mipmap, until either k = 0 or l=0. At that point, subsequent mipmaps have dimension 1 times 2 sup { l - 1 } or 2 sup { k - 1} times 1 until the final mipmap, which has dimension 1 times 1. To define the mipmaps, call glTexImage1D, glTexImage2D, glCopyTexImage1D, or glCopyTexImage2D with the level argument indicating the order of the mipmaps. Level 0 is the original texture; level bold max ( n, m ) is the final 1 times 1 mipmap. params supplies a function for minifying the texture as one of the following: .RS 10 GL_NEAREST Returns the value of the texture element that is nearest (in Manhattan distance) to the center of the pixel being textured. GL_LINEAR Returns the weighted average of the four texture elements that are closest to the center of the pixel being textured. These can include border texture elements, depending on the values of GL_TEXTURE_WRAP_S and GL_TEXTURE_WRAP_T, and on the exact mapping. GL_NEAREST_MIPMAP_NEAREST Chooses the mipmap that most closely matches the size of the pixel being textured and uses the GL_NEAREST criterion (the texture element nearest to the center of the pixel) to produce a texture value. GL_LINEAR_MIPMAP_NEAREST Chooses the mipmap that most closely matches the size of the pixel being textured and uses the GL_LINEAR criterion (a weighted average of the four texture elements that are closest to the center of the pixel) to produce a texture value. GL_NEAREST_MIPMAP_LINEAR Chooses the two mipmaps that most closely match the size of the pixel being textured and uses the GL_NEAREST criterion (the texture element nearest to the center of the pixel) to produce a texture value from each mipmap. The final texture value is a weighted average of those two values. GL_LINEAR_MIPMAP_LINEAR Chooses the two mipmaps that most closely match the size of the pixel being textured and uses the GL_LINEAR criterion (a weighted average of the four texture elements that are closest to the center of the pixel) to produce a texture value from each mipmap. The final texture value is a weighted average of those two values. .RE As more texture elements are sampled in the minification process, fewer aliasing artifacts will be apparent. While the GL_NEAREST and GL_LINEAR minification functions can be faster than the other four, they sample only one or four texture elements to determine the texture value of the pixel being rendered and can produce moire patterns or ragged transitions. The initial value of GL_TEXTURE_MIN_FILTER is GL_NEAREST_MIPMAP_LINEAR. GL_TEXTURE_MAG_FILTER The texture magnification function is used when the pixel being textured maps to an area less than or equal to one texture element. It sets the texture magnification function to either GL_NEAREST or GL_LINEAR (see below). GL_NEAREST is generally faster than GL_LINEAR, but it can produce textured images with sharper edges because the transition between texture elements is not as smooth. The initial value of GL_TEXTURE_MAG_FILTER is GL_LINEAR. .RS 10 GL_NEAREST Returns the value of the texture element that is nearest (in Manhattan distance) to the center of the pixel being textured. GL_LINEAR Returns the weighted average of the four texture elements that are closest to the center of the pixel being textured. These can include border texture elements, depending on the values of GL_TEXTURE_WRAP_S and GL_TEXTURE_WRAP_T, and on the exact mapping.

.RE

GL_TEXTURE_WRAP_S Sets the wrap parameter for texture coordinate s to either GL_CLAMP or GL_REPEAT. GL_CLAMP causes s coordinates to be clamped to the range [0,1] and is useful for preventing wrapping artifacts when mapping a single image onto an object. GL_REPEAT causes the integer part of the s coordinate to be ignored; the GL uses only the fractional part, thereby creating a repeating pattern. Border texture elements are accessed only if wrapping is set to GL_CLAMP. Initially, GL_TEXTURE_WRAP_S is set to GL_REPEAT.

GL_TEXTURE_WRAP_T Sets the wrap parameter for texture coordinate t to either GL_CLAMP or GL_REPEAT. See the discussion under GL_TEXTURE_WRAP_S. Initially, GL_TEXTURE_WRAP_T is set to GL_REPEAT. GL_TEXTURE_BORDER_COLOR Sets a border color. params contains four values that comprise the RGBA color of the texture border. Integer color components are interpreted linearly such that the most positive integer maps to 1.0, and the most negative integer maps to -1.0. The values are clamped to the range [0,1] when they are specified. Initially, the border color is (0, 0, 0, 0). GL_TEXTURE_PRIORITY Specifies the texture residence priority of the currently bound texture. Permissible values are in the range [0,\ 1]. See glPrioritizeTextures and glBindTexture for more information.

Specifies the target texture, which must be either GL_TEXTURE_1D or GL_TEXTURE_2D.

Specifies the symbolic name of a single-valued texture parameter. pname can be one of the following: GL_TEXTURE_MIN_FILTER, GL_TEXTURE_MAG_FILTER, GL_TEXTURE_WRAP_S, GL_TEXTURE_WRAP_T, or GL_TEXTURE_PRIORITY.

Specifies the value of pname.

Specifies the target texture, which must be either GL_TEXTURE_1D or GL_TEXTURE_2D.

Specifies the symbolic name of a texture parameter. pname can be one of the following: GL_TEXTURE_MIN_FILTER, GL_TEXTURE_MAG_FILTER, GL_TEXTURE_WRAP_S, GL_TEXTURE_WRAP_T, GL_TEXTURE_BORDER_COLOR, or GL_TEXTURE_PRIORITY.

Specifies a pointer to an array where the value or values of pname are stored.

GL_INVALID_ENUM is generated if target or pname is not one of the accepted defined values.

GL_INVALID_ENUM is generated if params should have a defined constant value (based on the value of pname) and does not.

GL_INVALID_OPERATION is generated if glTexParameter is executed between the execution of glBegin and the corresponding execution of glEnd.

Texturing maps a portion of a specified texture image onto each graphical primitive for which texturing is enabled. To enable and disable two-dimensional texturing, call glEnable and glDisable with argument GL_TEXTURE_2D.

glTexSubImage2D redefines a contiguous subregion of an existing two-dimensional texture image. The texels referenced by pixels replace the portion of the existing texture array with x indices xoffset and "xoffset"~+~"width"~-~1, inclusive, and y indices yoffset and "yoffset"~+~"height"~-~1, inclusive. This region may not include any texels outside the range of the texture array as it was originally specified. It is not an error to specify a subtexture with zero width or height, but such a specification has no effect.

Specifies the target texture. Must be GL_TEXTURE_2D.

Specifies the level-of-detail number. Level 0 is the base image level. Level n is the nth mipmap reduction image.

Specifies a texel offset in the x direction within the texture array.

Specifies a texel offset in the y direction within the texture array.

Specifies the width of the texture subimage.

Specifies the height of the texture subimage.

Specifies the format of the pixel data. The following symbolic values are accepted: GL_COLOR_INDEX, GL_RED, GL_GREEN, GL_BLUE, GL_ALPHA, GL_RGB, GL_RGBA, GL_LUMINANCE, and GL_LUMINANCE_ALPHA.

Specifies the data type of the pixel data. The following symbolic values are accepted: GL_UNSIGNED_BYTE, GL_BYTE, GL_BITMAP, GL_UNSIGNED_SHORT, GL_SHORT, GL_UNSIGNED_INT, GL_INT, and GL_FLOAT.

Specifies a pointer to the image data in memory.

GL_INVALID_ENUM is generated if target is not GL_TEXTURE_2D.

GL_INVALID_OPERATION is generated if the texture array has not been defined by a previous glTexImage2D operation.

GL_INVALID_VALUE is generated if level is less than 0. .P P GL_INVALID_VALUE may be generated if level is greater than log sub 2max, where max is the returned value of GL_MAX_TEXTURE_SIZE.

GL_INVALID_VALUE is generated if "xoffset" ~<~ ~-b, ("xoffset"~+~"width") ~>~ (w~-~b), "yoffset" ~<~ ~-b, or ("yoffset" ~+~ "height") ~>~ (h~-~b). Where w is the GL_TEXTURE_WIDTH, h is the GL_TEXTURE_HEIGHT, and b is the border width of the texture image being modified. Note that w and h include twice the border width.

GL_INVALID_VALUE is generated if width or height is less than 0.

GL_INVALID_ENUM is generated if format is not an accepted format constant.

GL_INVALID_ENUM is generated if type is not a type constant.

GL_INVALID_ENUM is generated if type is GL_BITMAP and format is not GL_COLOR_INDEX.

GL_INVALID_OPERATION is generated if glTexSubImage2D is executed between the execution of glBegin and the corresponding execution of glEnd.

glTranslate produces a translation by ("x","y","z"). The current matrix (see

glMatrixMode) is multiplied by this translation matrix, with the product replacing the current matrix, as if glMultMatrix were called with the following matrix for its argument: .sp .ce .EQ left ( ~ down 20 matrix { ccol { 1~~ above 0~~ above 0~~ above 0~~ } ccol { 0~~ above 1~~ above 0~~ above 0~~ } ccol { 0~~ above 0~~ above 1~~ above 0~~ } ccol { "x"~ above "y"~ above "z"~ above 1} } ~~right ) .EN .sp .RE If the matrix mode is either GL_MODELVIEW or GL_PROJECTION, all objects drawn after a call to glTranslate are translated.

Use glPushMatrix and glPopMatrix to save and restore the untranslated coordinate system.

Specify the x, y, and z coordinates of a translation vector.

GL_INVALID_OPERATION is generated if glTranslate is executed between the execution of glBegin and the corresponding execution of glEnd.

glVertex commands are used within glBegin/glEnd pairs to specify point, line, and polygon vertices. The current color, normal, and texture coordinates are associated with the vertex when glVertex is called.

When only x and y are specified, z defaults to 0 and w defaults to 1. When x, y, and z are specified, w defaults to 1.

Specify x, y, z, and w coordinates of a vertex. Not all parameters are present in all forms of the command.

Specifies a pointer to an array of two, three, or four elements. The elements of a two-element array are x and y; of a three-element array, x, y, and z; and of a four-element array, x, y, z, and w.

glViewport specifies the affine transformation of x and y from normalized device coordinates to window coordinates. Let (x sub nd, y sub nd) be normalized device coordinates. Then the window coordinates (x sub w, y sub w) are computed as follows: .sp .ce .EQ x sub w ~=~ ( x sub nd + 1 ) left ( "width" over 2 right ) ~+~ "x" .EN .sp .ce .EQ y sub w ~=~ ( y sub nd + 1 ) left ( "height" over 2 right ) ~+~ "y" .EN .RE

Viewport width and height are silently clamped to a range that depends on the implementation. To query this range, call glGet with argument GL_MAX_VIEWPORT_DIMS.

Specify the lower left corner of the viewport rectangle, in pixels. The initial value is (0,0).

Specify the width and height of the viewport. When a GL context is first attached to a window, width and height are set to the dimensions of that window.

GL_INVALID_VALUE is generated if either width or height is negative.

GL_INVALID_OPERATION is generated if glViewport is executed between the execution of glBegin and the corresponding execution of glEnd.

glBegin and glEnd delimit the vertices that define a primitive or a group of like primitives. glBegin accepts a single argument that specifies in which of ten ways the vertices are interpreted. Taking n as an integer count starting at one, and N as the total number of vertices specified, the interpretations are as follows:

GL_POINTS Treats each vertex as a single point. Vertex n defines point n. N points are drawn. GL_LINES Treats each pair of vertices as an independent line segment. Vertices 2n-1 and 2n define line n. N/2 lines are drawn. GL_LINE_STRIP Draws a connected group of line segments from the first vertex to the last. Vertices n and n+1 define line n. N-1 lines are drawn. GL_LINE_LOOP Draws a connected group of line segments from the first vertex to the last, then back to the first. Vertices n and n+1 define line n. The last line, however, is defined by vertices N and 1. N lines are drawn. GL_TRIANGLES Treats each triplet of vertices as an independent triangle. Vertices 3n-2, 3n-1, and 3n define triangle n. N/3 triangles are drawn. GL_TRIANGLE_STRIP Draws a connected group of triangles. One triangle is defined for each vertex presented after the first two vertices. For odd n, vertices n, n+1, and n+2 define triangle n. For even n, vertices n+1, n, and n+2 define triangle n. N-2 triangles are drawn. GL_TRIANGLE_FAN Draws a connected group of triangles. One triangle is defined for each vertex presented after the first two vertices. Vertices 1, n+1, and n+2 define triangle n. N-2 triangles are drawn. GL_QUADS Treats each group of four vertices as an independent quadrilateral. Vertices 4n-3, 4n-2, 4n-1, and 4n define quadrilateral n. N/4 quadrilaterals are drawn. GL_QUAD_STRIP Draws a connected group of quadrilaterals. One quadrilateral is defined for each pair of vertices presented after the first pair. Vertices 2n-1, 2n, 2n+2, and 2n+1 define quadrilateral n. N/2-1 quadrilaterals are drawn. Note that the order in which vertices are used to construct a quadrilateral from strip data is different from that used with independent data. GL_POLYGON Draws a single, convex polygon. Vertices 1 through N define this polygon.

Only a subset of GL commands can be used between glBegin and glEnd. The commands are glVertex, glColor, glIndex, glNormal, glTexCoord, glEvalCoord, glEvalPoint, glArrayElement, glMaterial, and glEdgeFlag. Also, it is acceptable to use glCallList or glCallLists to execute display lists that include only the preceding commands. If any other GL command is executed between glBegin and glEnd, the error flag is set and the command is ignored.

Regardless of the value chosen for mode, there is no limit to the number of vertices that can be defined between glBegin and glEnd. Lines, triangles, quadrilaterals, and polygons that are incompletely specified are not drawn. Incomplete specification results when either too few vertices are provided to specify even a single primitive or when an incorrect multiple of vertices is specified. The incomplete primitive is ignored; the rest are drawn.

The minimum specification of vertices for each primitive is as follows: 1 for a point, 2 for a line, 3 for a triangle, 4 for a quadrilateral, and 3 for a polygon. Modes that require a certain multiple of vertices are GL_LINES (2), GL_TRIANGLES (3), GL_QUADS (4), and GL_QUAD_STRIP (2).

Specifies the primitive or primitives that will be created from vertices presented between glBegin and the subsequent glEnd. Ten symbolic constants are accepted: GL_POINTS, GL_LINES, GL_LINE_STRIP, GL_LINE_LOOP, GL_TRIANGLES, GL_TRIANGLE_STRIP, GL_TRIANGLE_FAN, GL_QUADS, GL_QUAD_STRIP, and GL_POLYGON.

GL_INVALID_ENUM is generated if mode is set to an unaccepted value.

GL_INVALID_OPERATION is generated if glBegin is executed between a glBegin and the corresponding execution of glEnd.

GL_INVALID_OPERATION is generated if glEnd is executed without being preceded by a glBegin.

GL_INVALID_OPERATION is generated if a command other than glVertex, glColor, glIndex, glNormal, glTexCoord, glEvalCoord, glEvalPoint, glArrayElement, glMaterial, glEdgeFlag, glCallList, or glCallLists is executed between the execution of glBegin and the corresponding execution glEnd.

Execution of glEnableClientState, glDisableClientState, glEdgeFlagPointer, glTexCoordPointer, glColorPointer, glIndexPointer, glNormalPointer,

glVertexPointer, glInterleavedArrays, or glPixelStore is not allowed after a call to glBegin and before the corresponding call to glEnd, but an error may or may not be generated.

Display lists are groups of GL commands that have been stored for subsequent execution. Display lists are created with glNewList. All subsequent commands are placed in the display list, in the order issued, until glEndList is called.

glNewList has two arguments. The first argument, list, is a positive integer that becomes the unique name for the display list. Names can be created and reserved with glGenLists and tested for uniqueness with glIsList. The second argument, mode, is a symbolic constant that can assume one of two values:

GL_COMPILE Commands are merely compiled. GL_COMPILE_AND_EXECUTE Commands are executed as they are compiled into the display list.

Certain commands are not compiled into the display list but are executed immediately, regardless of the display-list mode. These commands are glColorPointer, glDeleteLists, glDisableClientState, glEdgeFlagPointer, glEnableClientState, glFeedbackBuffer, glFinish, glFlush, glGenLists, glIndexPointer, glInterleavedArrays, glIsEnabled, glIsList, glNormalPointer, glPopClientAttrib, glPixelStore, glPushClientAttrib, glReadPixels, glRenderMode, glSelectBuffer, glTexCoordPointer, glVertexPointer, and all of the glGet commands.

Similarly, glTexImage2D and glTexImage1D are executed immediately and not compiled into the display list when their first argument is GL_PROXY_TEXTURE_2D or GL_PROXY_TEXTURE_1D, respectively.

When glEndList is encountered, the display-list definition is completed by associating the list with the unique name list (specified in the glNewList command). If a display list with name list already exists, it is replaced only when glEndList is called.

Specifies the display-list name.

Specifies the compilation mode, which can be GL_COMPILE or GL_COMPILE_AND_EXECUTE.

GL_INVALID_VALUE is generated if list is 0.

GL_INVALID_ENUM is generated if mode is not an accepted value.

GL_INVALID_OPERATION is generated if glEndList is called without a preceding glNewList, or if glNewList is called while a display list is being defined.

GL_INVALID_OPERATION is generated if glNewList or glEndList is executed between the execution of glBegin and the corresponding execution of glEnd.

GL_OUT_OF_MEMORY is generated if there is insufficient memory to compile the display list. If the GL version is 1.1 or greater, no change is made to the previous contents of the display list, if any, and no other change is made to the GL state. (It is as if no attempt had been made to create the new display list.)

glFinish does not return until the effects of all previously called GL commands are complete. Such effects include all changes to GL state, all changes to connection state, and all changes to the frame buffer contents.

GL_INVALID_OPERATION is generated if glFinish is executed between the execution of glBegin and the corresponding execution of glEnd.

Different GL implementations buffer commands in several different locations, including network buffers and the graphics accelerator itself. glFlush empties all of these buffers, causing all issued commands to be executed as quickly as they are accepted by the actual rendering engine. Though this execution may not be completed in any particular time period, it does complete in finite time.

Because any GL program might be executed over a network, or on an accelerator that buffers commands, all programs should call glFlush whenever they count on having all of their previously issued commands completed. For example, call glFlush before waiting for user input that depends on the generated image.

GL_INVALID_OPERATION is generated if glFlush is executed between the execution of glBegin and the corresponding execution of glEnd.

The name stack is used during selection mode to allow sets of rendering commands to be uniquely identified. It consists of an ordered set of unsigned integers. glInitNames causes the name stack to be initialized to its default empty state.

The name stack is always empty while the render mode is not GL_SELECT. Calls to glInitNames while the render mode is not GL_SELECT are ignored.

GL_INVALID_OPERATION is generated if glInitNames is executed between the execution of glBegin and the corresponding execution of glEnd.

glLoadIdentity replaces the current matrix with the identity matrix. It is semantically equivalent to calling glLoadMatrix with the identity matrix

.ce

.EQ left ( down 20 { ~ matrix { ccol { 1 above 0 above 0 above 0~ } ccol { 0 above 1 above 0 above 0~ } ccol { 0 above 0 above 1 above 0~ } ccol { 0 above 0 above 0 above 1 } } } ~~ right ) .EN

but in some cases it is more efficient.

GL_INVALID_OPERATION is generated if glLoadIdentity is executed between the execution of glBegin and the corresponding execution of glEnd.

glPushAttrib takes one argument, a mask that indicates which groups of state variables to save on the attribute stack. Symbolic constants are used to set bits in the mask. mask is typically constructed by ORing several of these constants together. The special mask GL_ALL_ATTRIB_BITS can be used to save all stackable states.

The symbolic mask constants and their associated GL state are as follows (the second column lists which attributes are saved):

.TS ; l l . GL_ACCUM_BUFFER_BIT Accumulation buffer clear value

GL_COLOR_BUFFER_BIT GL_ALPHA_TEST enable bit Alpha test function and reference value GL_BLEND enable bit Blending source and destination functions Constant blend color Blending equation GL_DITHER enable bit GL_DRAW_BUFFER setting GL_COLOR_LOGIC_OP enable bit GL_INDEX_LOGIC_OP enable bit Logic op function Color mode and index mode clear values Color mode and index mode writemasks

GL_CURRENT_BIT Current RGBA color Current color index Current normal vector Current texture coordinates Current raster position GL_CURRENT_RASTER_POSITION_VALID flag RGBA color associated with current raster position Color index associated with current raster position Texture coordinates associated with current raster position GL_EDGE_FLAG flag

GL_DEPTH_BUFFER_BIT GL_DEPTH_TEST enable bit Depth buffer test function Depth buffer clear value GL_DEPTH_WRITEMASK enable bit

GL_ENABLE_BIT GL_ALPHA_TEST flag GL_AUTO_NORMAL flag GL_BLEND flag Enable bits for the user-definable clipping planes GL_COLOR_MATERIAL GL_CULL_FACE flag GL_DEPTH_TEST flag GL_DITHER flag GL_FOG flag GL_LIGHT i where 0\ <= i<GL_MAX_LIGHTS GL_LIGHTING flag GL_LINE_SMOOTH flag GL_LINE_STIPPLE flag GL_COLOR_LOGIC_OP flag GL_INDEX_LOGIC_OP flag GL_MAP1_x where x is a map type GL_MAP2_x where x is a map type GL_NORMALIZE flag GL_POINT_SMOOTH flag GL_POLYGON_OFFSET_LINE flag GL_POLYGON_OFFSET_FILL flag GL_POLYGON_OFFSET_POINT flag GL_POLYGON_SMOOTH flag GL_POLYGON_STIPPLE flag GL_SCISSOR_TEST flag GL_STENCIL_TEST flag GL_TEXTURE_1D flag GL_TEXTURE_2D flag Flags GL_TEXTURE_GEN_x where x is S, T, R, or Q

GL_EVAL_BIT GL_MAP1_x enable bits, where x is a map type GL_MAP2_x enable bits, where x is a map type 1D grid endpoints and divisions 2D grid endpoints and divisions GL_AUTO_NORMAL enable bit

GL_FOG_BIT GL_FOG enable bit Fog color Fog density Linear fog start Linear fog end Fog index GL_FOG_MODE value

GL_HINT_BIT GL_PERSPECTIVE_CORRECTION_HINT setting GL_POINT_SMOOTH_HINT setting GL_LINE_SMOOTH_HINT setting GL_POLYGON_SMOOTH_HINT setting GL_FOG_HINT setting

GL_LIGHTING_BIT GL_COLOR_MATERIAL enable bit GL_COLOR_MATERIAL_FACE value Color material parameters that are tracking the current color Ambient scene color GL_LIGHT_MODEL_LOCAL_VIEWER value GL_LIGHT_MODEL_TWO_SIDE setting GL_LIGHTING enable bit Enable bit for each light Ambient, diffuse, and specular intensity for each light Direction, position, exponent, and cutoff angle for each light Constant, linear, and quadratic attenuation factors for each light Ambient, diffuse, specular, and emissive color for each material Ambient, diffuse, and specular color indices for each material Specular exponent for each material GL_SHADE_MODEL setting

GL_LINE_BIT GL_LINE_SMOOTH flag GL_LINE_STIPPLE enable bit Line stipple pattern and repeat counter Line width

GL_LIST_BIT GL_LIST_BASE setting

GL_PIXEL_MODE_BIT GL_RED_BIAS and GL_RED_SCALE settings GL_GREEN_BIAS and GL_GREEN_SCALE values GL_BLUE_BIAS and GL_BLUE_SCALE GL_ALPHA_BIAS and GL_ALPHA_SCALE GL_DEPTH_BIAS and GL_DEPTH_SCALE GL_INDEX_OFFSET and GL_INDEX_SHIFT values GL_MAP_COLOR and GL_MAP_STENCIL flags GL_ZOOM_X and GL_ZOOM_Y factors GL_READ_BUFFER setting

GL_POINT_BIT GL_POINT_SMOOTH flag Point size

GL_POLYGON_BIT GL_CULL_FACE enable bit GL_CULL_FACE_MODE value GL_FRONT_FACE indicator GL_POLYGON_MODE setting GL_POLYGON_SMOOTH flag GL_POLYGON_STIPPLE enable bit GL_POLYGON_OFFSET_FILL flag GL_POLYGON_OFFSET_LINE flag GL_POLYGON_OFFSET_POINT flag GL_POLYGON_OFFSET_FACTOR GL_POLYGON_OFFSET_UNITS

GL_POLYGON_STIPPLE_BIT Polygon stipple image

GL_SCISSOR_BIT GL_SCISSOR_TEST flag Scissor box

GL_STENCIL_BUFFER_BIT GL_STENCIL_TEST enable bit Stencil function and reference value Stencil value mask Stencil fail, pass, and depth buffer pass actions Stencil buffer clear value Stencil buffer writemask

GL_TEXTURE_BIT Enable bits for the four texture coordinates Border color for each texture image Minification function for each texture image Magnification function for each texture image Texture coordinates and wrap mode for each texture image Color and mode for each texture environment Enable bits GL_TEXTURE_GEN_x, x is S, T, R, and Q GL_TEXTURE_GEN_MODE setting for S, T, R, and Q glTexGen plane equations for S, T, R, and Q Current texture bindings (for example, GL_TEXTURE_2D_BINDING)

GL_TRANSFORM_BIT Coefficients of the six clipping planes Enable bits for the user-definable clipping planes GL_MATRIX_MODE value GL_NORMALIZE flag

GL_VIEWPORT_BIT Depth range (near and far) Viewport origin and extent .TE

glPopAttrib restores the values of the state variables saved with the last

glPushAttrib command. Those not saved are left unchanged.

It is an error to push attributes onto a full stack, or to pop attributes off an empty stack. In either case, the error flag is set and no other change is made to GL state.

Initially, the attribute stack is empty.

Specifies a mask that indicates which attributes to save. Values for mask are listed below.

GL_STACK_OVERFLOW is generated if glPushAttrib is called while the attribute stack is full.

GL_STACK_UNDERFLOW is generated if glPopAttrib is called while the attribute stack is empty.

GL_INVALID_OPERATION is generated if glPushAttrib or glPopAttrib is executed between the execution of glBegin and the corresponding execution of glEnd.

glPushClientAttrib takes one argument, a mask that indicates which groups of client-state variables to save on the client attribute stack. Symbolic constants are used to set bits in the mask. mask is typically constructed by OR'ing several of these constants together. The special mask GL_CLIENT_ALL_ATTRIB_BITS can be used to save all stackable client state.

The symbolic mask constants and their associated GL client state are as follows (the second column lists which attributes are saved):

GL_CLIENT_PIXEL_STORE_BIT Pixel storage modes

GL_CLIENT_VERTEX_ARRAY_BIT Vertex arrays (and enables)

glPopClientAttrib restores the values of the client-state variables saved with the last glPushClientAttrib. Those not saved are left unchanged.

It is an error to push attributes onto a full client attribute stack, or to pop attributes off an empty stack. In either case, the error flag is set, and no other change is made to GL state.

Initially, the client attribute stack is empty.

Specifies a mask that indicates which attributes to save. Values for mask are listed below.

GL_STACK_OVERFLOW is generated if glPushClientAttrib is called while the attribute stack is full.

GL_STACK_UNDERFLOW is generated if glPopClientAttrib is called while the attribute stack is empty.

There is a stack of matrices for each of the matrix modes. In GL_MODELVIEW mode, the stack depth is at least 32. In the other two modes, GL_PROJECTION and GL_TEXTURE, the depth is at least 2. The current matrix in any mode is the matrix on the top of the stack for that mode.

glPushMatrix pushes the current matrix stack down by one, duplicating the current matrix. That is, after a glPushMatrix call, the matrix on top of the stack is identical to the one below it.

glPopMatrix pops the current matrix stack, replacing the current matrix with the one below it on the stack.

Initially, each of the stacks contains one matrix, an identity matrix.

It is an error to push a full matrix stack, or to pop a matrix stack that contains only a single matrix. In either case, the error flag is set and no other change is made to GL state.

GL_STACK_OVERFLOW is generated if glPushMatrix is called while the current matrix stack is full.

GL_STACK_UNDERFLOW is generated if glPopMatrix is called while the current matrix stack contains only a single matrix.

GL_INVALID_OPERATION is generated if glPushMatrix or glPopMatrix is executed between the execution of glBegin and the corresponding execution of glEnd.

The name stack is used during selection mode to allow sets of rendering commands to be uniquely identified. It consists of an ordered set of unsigned integers and is initially empty.

glPushName causes name to be pushed onto the name stack. glPopName pops one name off the top of the stack.

The maximum name stack depth is implementation-dependent; call GL_MAX_NAME_STACK_DEPTH to find out the value for a particular implementation. It is an error to push a name onto a full stack, or to pop a name off an empty stack. It is also an error to manipulate the name stack between the execution of glBegin and the corresponding execution of glEnd. In any of these cases, the error flag is set and no other change is made to GL state.

The name stack is always empty while the render mode is not GL_SELECT. Calls to glPushName or glPopName while the render mode is not GL_SELECT are ignored.

Specifies a name that will be pushed onto the name stack.

GL_STACK_OVERFLOW is generated if glPushName is called while the name stack is full.

GL_STACK_UNDERFLOW is generated if glPopName is called while the name stack is empty.

GL_INVALID_OPERATION is generated if glPushName or glPopName is executed between a call to glBegin and the corresponding call to glEnd.

There is a stack of matrices for each of the matrix modes. In GL_MODELVIEW mode, the stack depth is at least 32. In the other two modes, GL_PROJECTION and GL_TEXTURE, the depth is at least 2. The current matrix in any mode is the matrix on the top of the stack for that mode.

glPushMatrix pushes the current matrix stack down by one, duplicating the current matrix. That is, after a glPushMatrix call, the matrix on top of the stack is identical to the one below it.

glPopMatrix pops the current matrix stack, replacing the current matrix with the one below it on the stack.

Initially, each of the stacks contains one matrix, an identity matrix.

It is an error to push a full matrix stack, or to pop a matrix stack that contains only a single matrix. In either case, the error flag is set and no other change is made to GL state.

GL_STACK_OVERFLOW is generated if glPushMatrix is called while the current matrix stack is full.

GL_STACK_UNDERFLOW is generated if glPopMatrix is called while the current matrix stack contains only a single matrix.

GL_INVALID_OPERATION is generated if glPushMatrix or glPopMatrix is executed between the execution of glBegin and the corresponding execution of glEnd.

glBegin and glEnd delimit the vertices that define a primitive or a group of like primitives. glBegin accepts a single argument that specifies in which of ten ways the vertices are interpreted. Taking n as an integer count starting at one, and N as the total number of vertices specified, the interpretations are as follows:

GL_POINTS Treats each vertex as a single point. Vertex n defines point n. N points are drawn. GL_LINES Treats each pair of vertices as an independent line segment. Vertices 2n-1 and 2n define line n. N/2 lines are drawn. GL_LINE_STRIP Draws a connected group of line segments from the first vertex to the last. Vertices n and n+1 define line n. N-1 lines are drawn. GL_LINE_LOOP Draws a connected group of line segments from the first vertex to the last, then back to the first. Vertices n and n+1 define line n. The last line, however, is defined by vertices N and 1. N lines are drawn. GL_TRIANGLES Treats each triplet of vertices as an independent triangle. Vertices 3n-2, 3n-1, and 3n define triangle n. N/3 triangles are drawn. GL_TRIANGLE_STRIP Draws a connected group of triangles. One triangle is defined for each vertex presented after the first two vertices. For odd n, vertices n, n+1, and n+2 define triangle n. For even n, vertices n+1, n, and n+2 define triangle n. N-2 triangles are drawn. GL_TRIANGLE_FAN Draws a connected group of triangles. One triangle is defined for each vertex presented after the first two vertices. Vertices 1, n+1, and n+2 define triangle n. N-2 triangles are drawn. GL_QUADS Treats each group of four vertices as an independent quadrilateral. Vertices 4n-3, 4n-2, 4n-1, and 4n define quadrilateral n. N/4 quadrilaterals are drawn. GL_QUAD_STRIP Draws a connected group of quadrilaterals. One quadrilateral is defined for each pair of vertices presented after the first pair. Vertices 2n-1, 2n, 2n+2, and 2n+1 define quadrilateral n. N/2-1 quadrilaterals are drawn. Note that the order in which vertices are used to construct a quadrilateral from strip data is different from that used with independent data. GL_POLYGON Draws a single, convex polygon. Vertices 1 through N define this polygon.

Only a subset of GL commands can be used between glBegin and glEnd. The commands are glVertex, glColor, glIndex, glNormal, glTexCoord, glEvalCoord, glEvalPoint, glArrayElement, glMaterial, and glEdgeFlag. Also, it is acceptable to use glCallList or glCallLists to execute display lists that include only the preceding commands. If any other GL command is executed between glBegin and glEnd, the error flag is set and the command is ignored.

Regardless of the value chosen for mode, there is no limit to the number of vertices that can be defined between glBegin and glEnd. Lines, triangles, quadrilaterals, and polygons that are incompletely specified are not drawn. Incomplete specification results when either too few vertices are provided to specify even a single primitive or when an incorrect multiple of vertices is specified. The incomplete primitive is ignored; the rest are drawn.

The minimum specification of vertices for each primitive is as follows: 1 for a point, 2 for a line, 3 for a triangle, 4 for a quadrilateral, and 3 for a polygon. Modes that require a certain multiple of vertices are GL_LINES (2), GL_TRIANGLES (3), GL_QUADS (4), and GL_QUAD_STRIP (2).

Specifies the primitive or primitives that will be created from vertices presented between glBegin and the subsequent glEnd. Ten symbolic constants are accepted: GL_POINTS, GL_LINES, GL_LINE_STRIP, GL_LINE_LOOP, GL_TRIANGLES, GL_TRIANGLE_STRIP, GL_TRIANGLE_FAN, GL_QUADS, GL_QUAD_STRIP, and GL_POLYGON.

GL_INVALID_ENUM is generated if mode is set to an unaccepted value.

GL_INVALID_OPERATION is generated if glBegin is executed between a glBegin and the corresponding execution of glEnd.

GL_INVALID_OPERATION is generated if glEnd is executed without being preceded by a glBegin.

GL_INVALID_OPERATION is generated if a command other than glVertex, glColor, glIndex, glNormal, glTexCoord, glEvalCoord, glEvalPoint, glArrayElement, glMaterial, glEdgeFlag, glCallList, or glCallLists is executed between the execution of glBegin and the corresponding execution glEnd.

Execution of glEnableClientState, glDisableClientState, glEdgeFlagPointer, glTexCoordPointer, glColorPointer, glIndexPointer, glNormalPointer,

glVertexPointer, glInterleavedArrays, or glPixelStore is not allowed after a call to glBegin and before the corresponding call to glEnd, but an error may or may not be generated.

glCullFace specifies whether front- or back-facing facets are culled (as specified by mode) when facet culling is enabled. Facet culling is initially disabled. To enable and disable facet culling, call the glEnable and glDisable commands with the argument GL_CULL_FACE. Facets include triangles, quadrilaterals, polygons, and rectangles.

glFrontFace specifies which of the clockwise and counterclockwise facets are front-facing and back-facing. See glFrontFace.

Specifies whether front- or back-facing facets are candidates for culling. Symbolic constants GL_FRONT, GL_BACK, and GL_FRONT_AND_BACK are accepted. The initial value is GL_BACK.

GL_INVALID_ENUM is generated if mode is not an accepted value.

GL_INVALID_OPERATION is generated if glCullFace is executed between the execution of glBegin and the corresponding execution of glEnd.

glDepthFunc specifies the function used to compare each incoming pixel depth value with the depth value present in the depth buffer. The comparison is performed only if depth testing is enabled. (See glEnable and glDisable of GL_DEPTH_TEST.)

func specifies the conditions under which the pixel will be drawn. The comparison functions are as follows:

GL_NEVER Never passes. GL_LESS Passes if the incoming depth value is less than the stored depth value. GL_EQUAL Passes if the incoming depth value is equal to the stored depth value. GL_LEQUAL Passes if the incoming depth value is less than or equal to the stored depth value. GL_GREATER Passes if the incoming depth value is greater than the stored depth value. GL_NOTEQUAL Passes if the incoming depth value is not equal to the stored depth value. GL_GEQUAL Passes if the incoming depth value is greater than or equal to the stored depth value. GL_ALWAYS Always passes.

The initial value of func is GL_LESS. Initially, depth testing is disabled. .NOTES Even if the depth buffer exists and the depth mask is non-zero, the depth buffer is not updated if the depth test is disabled.

Specifies the depth comparison function. Symbolic constants GL_NEVER, GL_LESS, GL_EQUAL, GL_LEQUAL, GL_GREATER, GL_NOTEQUAL, GL_GEQUAL, and GL_ALWAYS are accepted. The initial value is GL_LESS.

GL_INVALID_ENUM is generated if func is not an accepted value.

GL_INVALID_OPERATION is generated if glDepthFunc is executed between the execution of glBegin and the corresponding execution of glEnd.

glEnable and glDisable enable and disable various capabilities. Use glIsEnabled or glGet to determine the current setting of any capability. The initial value for each capability with the exception of GL_DITHER is GL_FALSE. The initial value for GL_DITHER is GL_TRUE.

Both glEnable and glDisable take a single argument, cap, which can assume one of the following values:

GL_ALPHA_TEST If enabled, do alpha testing. See glAlphaFunc. GL_AUTO_NORMAL If enabled, generate normal vectors when either GL_MAP2_VERTEX_3 or GL_MAP2_VERTEX_4 is used to generate vertices. See glMap2. GL_BLEND If enabled, blend the incoming RGBA color values with the values in the color buffers. See glBlendFunc. GL_CLIP_PLANE i If enabled, clip geometry against user-defined clipping plane i. See glClipPlane. GL_COLOR_LOGIC_OP If enabled, apply the currently selected logical operation to the incoming RGBA color and color buffer values. See glLogicOp. GL_COLOR_MATERIAL If enabled, have one or more material parameters track the current color. See glColorMaterial. GL_CULL_FACE If enabled, cull polygons based on their winding in window coordinates. See glCullFace. GL_DEPTH_TEST If enabled, do depth comparisons and update the depth buffer. Note that even if the depth buffer exists and the depth mask is non-zero, the depth buffer is not updated if the depth test is disabled. See glDepthFunc and glDepthRange. GL_DITHER If enabled, dither color components or indices before they are written to the color buffer. GL_FOG If enabled, blend a fog color into the posttexturing color. See glFog. GL_INDEX_LOGIC_OP If enabled, apply the currently selected logical operation to the incoming index and color buffer indices. See glLogicOp. GL_LIGHT i If enabled, include light i in the evaluation of the lighting equation. See glLightModel and glLight. GL_LIGHTING If enabled, use the current lighting parameters to compute the vertex color or index. Otherwise, simply associate the current color or index with each vertex. See glMaterial, glLightModel, and glLight. GL_LINE_SMOOTH If enabled, draw lines with correct filtering. Otherwise, draw aliased lines. See glLineWidth. GL_LINE_STIPPLE If enabled, use the current line stipple pattern when drawing lines. See glLineStipple. GL_MAP1_COLOR_4 If enabled, calls to glEvalCoord, glEvalMesh1, and glEvalPoint generate RGBA values. See glMap1. GL_MAP1_INDEX If enabled, calls to glEvalCoord, glEvalMesh1, and glEvalPoint generate color indices. See glMap1. GL_MAP1_NORMAL If enabled, calls to glEvalCoord, glEvalMesh1, and glEvalPoint generate normals. See glMap1. GL_MAP1_TEXTURE_COORD_1 If enabled, calls to glEvalCoord, glEvalMesh1, and glEvalPoint generate s texture coordinates. See glMap1. GL_MAP1_TEXTURE_COORD_2 If enabled, calls to glEvalCoord, glEvalMesh1, and glEvalPoint generate s and t texture coordinates. See glMap1. GL_MAP1_TEXTURE_COORD_3 If enabled, calls to glEvalCoord, glEvalMesh1, and glEvalPoint generate s, t, and r texture coordinates. See glMap1. GL_MAP1_TEXTURE_COORD_4 If enabled, calls to glEvalCoord, glEvalMesh1, and glEvalPoint generate s, t, r, and q texture coordinates. See glMap1. GL_MAP1_VERTEX_3 If enabled, calls to glEvalCoord, glEvalMesh1, and glEvalPoint generate x, y, and z vertex coordinates. See glMap1. GL_MAP1_VERTEX_4 If enabled, calls to glEvalCoord, glEvalMesh1, and glEvalPoint generate homogeneous x, y, z, and w vertex coordinates. See glMap1. GL_MAP2_COLOR_4 If enabled, calls to glEvalCoord, glEvalMesh2, and glEvalPoint generate RGBA values. See glMap2. GL_MAP2_INDEX If enabled, calls to glEvalCoord, glEvalMesh2, and glEvalPoint generate color indices. See glMap2. GL_MAP2_NORMAL If enabled, calls to glEvalCoord, glEvalMesh2, and glEvalPoint generate normals. See glMap2. GL_MAP2_TEXTURE_COORD_1 If enabled, calls to glEvalCoord, glEvalMesh2, and glEvalPoint generate s texture coordinates. See glMap2. GL_MAP2_TEXTURE_COORD_2 If enabled, calls to glEvalCoord, glEvalMesh2, and glEvalPoint generate s and t texture coordinates. See glMap2. GL_MAP2_TEXTURE_COORD_3 If enabled, calls to glEvalCoord, glEvalMesh2, and glEvalPoint generate s, t, and r texture coordinates. See glMap2. GL_MAP2_TEXTURE_COORD_4 If enabled, calls to glEvalCoord, glEvalMesh2, and glEvalPoint generate s, t, r, and q texture coordinates. See glMap2. GL_MAP2_VERTEX_3 If enabled, calls to glEvalCoord, glEvalMesh2, and glEvalPoint generate x, y, and z vertex coordinates. See glMap2. GL_MAP2_VERTEX_4 If enabled, calls to glEvalCoord, glEvalMesh2, and glEvalPoint generate homogeneous x, y, z, and w vertex coordinates. See glMap2. GL_NORMALIZE If enabled, normal vectors specified with glNormal are scaled to unit length after transformation. See glNormal. GL_POINT_SMOOTH If enabled, draw points with proper filtering. Otherwise, draw aliased points. See glPointSize. GL_POLYGON_OFFSET_FILL If enabled, and if the polygon is rendered in GL_FILL mode, an offset is added to depth values of a polygon's fragments before the depth comparison is performed. See glPolygonOffset. GL_POLYGON_OFFSET_LINE If enabled, and if the polygon is rendered in GL_LINE mode, an offset is added to depth values of a polygon's fragments before the depth comparison is performed. See glPolygonOffset. GL_POLYGON_OFFSET_POINT If enabled, an offset is added to depth values of a polygon's fragments before the depth comparison is performed, if the polygon is rendered in GL_POINT mode. See glPolygonOffset. GL_POLYGON_SMOOTH If enabled, draw polygons with proper filtering. Otherwise, draw aliased polygons. For correct anti-aliased polygons, an alpha buffer is needed and the polygons must be sorted front to back. GL_POLYGON_STIPPLE If enabled, use the current polygon stipple pattern when rendering polygons. See glPolygonStipple. GL_SCISSOR_TEST If enabled, discard fragments that are outside the scissor rectangle. See glScissor. GL_STENCIL_TEST If enabled, do stencil testing and update the stencil buffer. See glStencilFunc and glStencilOp. GL_TEXTURE_1D If enabled, one-dimensional texturing is performed (unless two-dimensional texturing is also enabled). See glTexImage1D. GL_TEXTURE_2D If enabled, two-dimensional texturing is performed. See glTexImage2D. GL_TEXTURE_GEN_Q If enabled, the q texture coordinate is computed using the texture generation function defined with glTexGen. Otherwise, the current q texture coordinate is used. See glTexGen. GL_TEXTURE_GEN_R If enabled, the r texture coordinate is computed using the texture generation function defined with glTexGen. Otherwise, the current r texture coordinate is used. See glTexGen. GL_TEXTURE_GEN_S If enabled, the s texture coordinate is computed using the texture generation function defined with glTexGen. Otherwise, the current s texture coordinate is used. See glTexGen. GL_TEXTURE_GEN_T If enabled, the t texture coordinate is computed using the texture generation function defined with glTexGen. Otherwise, the current t texture coordinate is used. See glTexGen.

Specifies a symbolic constant indicating a GL capability.

Specifies a symbolic constant indicating a GL capability.

GL_INVALID_ENUM is generated if cap is not one of the values listed previously.

GL_INVALID_OPERATION is generated if glEnable or glDisable is executed between the execution of glBegin and the corresponding execution of glEnd.

glEnableClientState and glDisableClientState enable or disable individual client-side capabilities. By default, all client-side capabilities are disabled. Both glEnableClientState and glDisableClientState take a single argument, cap, which can assume one of the following values:

GL_COLOR_ARRAY If enabled, the color array is enabled for writing and used during rendering when glDrawArrays or glDrawElement is called. See glColorPointer. GL_EDGE_FLAG_ARRAY If enabled, the edge flag array is enabled for writing and used during rendering when glDrawArrays or glDrawElements is called. See glEdgeFlagPointer. GL_INDEX_ARRAY If enabled, the index array is enabled for writing and used during rendering when glDrawArrays or glDrawElements is called. See glIndexPointer. GL_NORMAL_ARRAY If enabled, the normal array is enabled for writing and used during rendering when glDrawArrays or glDrawElements is called. See glNormalPointer. GL_TEXTURE_COORD_ARRAY If enabled, the texture coordinate array is enabled for writing and used for rendering when glDrawArrays or glDrawElements is called. See glTexCoordPointer. GL_VERTEX_ARRAY If enabled, the vertex array is enabled for writing and used during rendering when glDrawArrays or glDrawElements is called. See glVertexPointer.

Specifies the capability to enable. Symbolic constants GL_COLOR_ARRAY, GL_EDGE_FLAG_ARRAY, GL_INDEX_ARRAY, GL_NORMAL_ARRAY, GL_TEXTURE_COORD_ARRAY, and GL_VERTEX_ARRAY are accepted.

Specifies the capability to disable.

GL_INVALID_ENUM is generated if cap is not an accepted value.

glEnableClientState is not allowed between the execution of glBegin and the corresponding glEnd, but an error may or may not be generated. If no error is generated, the behavior is undefined.

When colors are written to the frame buffer, they are written into the color buffers specified by glDrawBuffer. The specifications are as follows:

GL_NONE No color buffers are written. GL_FRONT_LEFT Only the front left color buffer is written. GL_FRONT_RIGHT Only the front right color buffer is written. GL_BACK_LEFT Only the back left color buffer is written. GL_BACK_RIGHT Only the back right color buffer is written. GL_FRONT Only the front left and front right color buffers are written. If there is no front right color buffer, only the front left color buffer is written. GL_BACK Only the back left and back right color buffers are written. If there is no back right color buffer, only the back left color buffer is written. GL_LEFT Only the front left and back left color buffers are written. If there is no back left color buffer, only the front left color buffer is written. GL_RIGHT Only the front right and back right color buffers are written. If there is no back right color buffer, only the front right color buffer is written. GL_FRONT_AND_BACK All the front and back color buffers (front left, front right, back left, back right) are written. If there are no back color buffers, only the front left and front right color buffers are written. If there are no right color buffers, only the front left and back left color buffers are written. If there are no right or back color buffers, only the front left color buffer is written. GL_AUXi Only auxiliary color buffer i is written.

If more than one color buffer is selected for drawing, then blending or logical operations are computed and applied independently for each color buffer and can produce different results in each buffer.

Monoscopic contexts include only .I left buffers, and stereoscopic contexts include both .I left and .I right buffers. Likewise, single-buffered contexts include only .I front buffers, and double-buffered contexts include both .I front and .I back buffers. The context is selected at GL initialization.

Specifies up to four color buffers to be drawn into. Symbolic constants GL_NONE, GL_FRONT_LEFT, GL_FRONT_RIGHT, GL_BACK_LEFT, GL_BACK_RIGHT, GL_FRONT, GL_BACK, GL_LEFT, GL_RIGHT, GL_FRONT_AND_BACK, and GL_AUXi, where i is between 0 and ``GL_AUX_BUFFERS'' -1, are accepted (GL_AUX_BUFFERS is not the upper limit; use glGet to query the number of available aux buffers.) The initial value is GL_FRONT for single-buffered contexts, and GL_BACK for double-buffered contexts.

GL_INVALID_ENUM is generated if mode is not an accepted value.

GL_INVALID_OPERATION is generated if none of the buffers indicated by mode exists.

GL_INVALID_OPERATION is generated if glDrawBuffer is executed between the execution of glBegin and the corresponding execution of glEnd.

glEnable and glDisable enable and disable various capabilities. Use glIsEnabled or glGet to determine the current setting of any capability. The initial value for each capability with the exception of GL_DITHER is GL_FALSE. The initial value for GL_DITHER is GL_TRUE.

Both glEnable and glDisable take a single argument, cap, which can assume one of the following values:

GL_ALPHA_TEST If enabled, do alpha testing. See glAlphaFunc. GL_AUTO_NORMAL If enabled, generate normal vectors when either GL_MAP2_VERTEX_3 or GL_MAP2_VERTEX_4 is used to generate vertices. See glMap2. GL_BLEND If enabled, blend the incoming RGBA color values with the values in the color buffers. See glBlendFunc. GL_CLIP_PLANE i If enabled, clip geometry against user-defined clipping plane i. See glClipPlane. GL_COLOR_LOGIC_OP If enabled, apply the currently selected logical operation to the incoming RGBA color and color buffer values. See glLogicOp. GL_COLOR_MATERIAL If enabled, have one or more material parameters track the current color. See glColorMaterial. GL_CULL_FACE If enabled, cull polygons based on their winding in window coordinates. See glCullFace. GL_DEPTH_TEST If enabled, do depth comparisons and update the depth buffer. Note that even if the depth buffer exists and the depth mask is non-zero, the depth buffer is not updated if the depth test is disabled. See glDepthFunc and glDepthRange. GL_DITHER If enabled, dither color components or indices before they are written to the color buffer. GL_FOG If enabled, blend a fog color into the posttexturing color. See glFog. GL_INDEX_LOGIC_OP If enabled, apply the currently selected logical operation to the incoming index and color buffer indices. See glLogicOp. GL_LIGHT i If enabled, include light i in the evaluation of the lighting equation. See glLightModel and glLight. GL_LIGHTING If enabled, use the current lighting parameters to compute the vertex color or index. Otherwise, simply associate the current color or index with each vertex. See glMaterial, glLightModel, and glLight. GL_LINE_SMOOTH If enabled, draw lines with correct filtering. Otherwise, draw aliased lines. See glLineWidth. GL_LINE_STIPPLE If enabled, use the current line stipple pattern when drawing lines. See glLineStipple. GL_MAP1_COLOR_4 If enabled, calls to glEvalCoord, glEvalMesh1, and glEvalPoint generate RGBA values. See glMap1. GL_MAP1_INDEX If enabled, calls to glEvalCoord, glEvalMesh1, and glEvalPoint generate color indices. See glMap1. GL_MAP1_NORMAL If enabled, calls to glEvalCoord, glEvalMesh1, and glEvalPoint generate normals. See glMap1. GL_MAP1_TEXTURE_COORD_1 If enabled, calls to glEvalCoord, glEvalMesh1, and glEvalPoint generate s texture coordinates. See glMap1. GL_MAP1_TEXTURE_COORD_2 If enabled, calls to glEvalCoord, glEvalMesh1, and glEvalPoint generate s and t texture coordinates. See glMap1. GL_MAP1_TEXTURE_COORD_3 If enabled, calls to glEvalCoord, glEvalMesh1, and glEvalPoint generate s, t, and r texture coordinates. See glMap1. GL_MAP1_TEXTURE_COORD_4 If enabled, calls to glEvalCoord, glEvalMesh1, and glEvalPoint generate s, t, r, and q texture coordinates. See glMap1. GL_MAP1_VERTEX_3 If enabled, calls to glEvalCoord, glEvalMesh1, and glEvalPoint generate x, y, and z vertex coordinates. See glMap1. GL_MAP1_VERTEX_4 If enabled, calls to glEvalCoord, glEvalMesh1, and glEvalPoint generate homogeneous x, y, z, and w vertex coordinates. See glMap1. GL_MAP2_COLOR_4 If enabled, calls to glEvalCoord, glEvalMesh2, and glEvalPoint generate RGBA values. See glMap2. GL_MAP2_INDEX If enabled, calls to glEvalCoord, glEvalMesh2, and glEvalPoint generate color indices. See glMap2. GL_MAP2_NORMAL If enabled, calls to glEvalCoord, glEvalMesh2, and glEvalPoint generate normals. See glMap2. GL_MAP2_TEXTURE_COORD_1 If enabled, calls to glEvalCoord, glEvalMesh2, and glEvalPoint generate s texture coordinates. See glMap2. GL_MAP2_TEXTURE_COORD_2 If enabled, calls to glEvalCoord, glEvalMesh2, and glEvalPoint generate s and t texture coordinates. See glMap2. GL_MAP2_TEXTURE_COORD_3 If enabled, calls to glEvalCoord, glEvalMesh2, and glEvalPoint generate s, t, and r texture coordinates. See glMap2. GL_MAP2_TEXTURE_COORD_4 If enabled, calls to glEvalCoord, glEvalMesh2, and glEvalPoint generate s, t, r, and q texture coordinates. See glMap2. GL_MAP2_VERTEX_3 If enabled, calls to glEvalCoord, glEvalMesh2, and glEvalPoint generate x, y, and z vertex coordinates. See glMap2. GL_MAP2_VERTEX_4 If enabled, calls to glEvalCoord, glEvalMesh2, and glEvalPoint generate homogeneous x, y, z, and w vertex coordinates. See glMap2. GL_NORMALIZE If enabled, normal vectors specified with glNormal are scaled to unit length after transformation. See glNormal. GL_POINT_SMOOTH If enabled, draw points with proper filtering. Otherwise, draw aliased points. See glPointSize. GL_POLYGON_OFFSET_FILL If enabled, and if the polygon is rendered in GL_FILL mode, an offset is added to depth values of a polygon's fragments before the depth comparison is performed. See glPolygonOffset. GL_POLYGON_OFFSET_LINE If enabled, and if the polygon is rendered in GL_LINE mode, an offset is added to depth values of a polygon's fragments before the depth comparison is performed. See glPolygonOffset. GL_POLYGON_OFFSET_POINT If enabled, an offset is added to depth values of a polygon's fragments before the depth comparison is performed, if the polygon is rendered in GL_POINT mode. See glPolygonOffset. GL_POLYGON_SMOOTH If enabled, draw polygons with proper filtering. Otherwise, draw aliased polygons. For correct anti-aliased polygons, an alpha buffer is needed and the polygons must be sorted front to back. GL_POLYGON_STIPPLE If enabled, use the current polygon stipple pattern when rendering polygons. See glPolygonStipple. GL_SCISSOR_TEST If enabled, discard fragments that are outside the scissor rectangle. See glScissor. GL_STENCIL_TEST If enabled, do stencil testing and update the stencil buffer. See glStencilFunc and glStencilOp. GL_TEXTURE_1D If enabled, one-dimensional texturing is performed (unless two-dimensional texturing is also enabled). See glTexImage1D. GL_TEXTURE_2D If enabled, two-dimensional texturing is performed. See glTexImage2D. GL_TEXTURE_GEN_Q If enabled, the q texture coordinate is computed using the texture generation function defined with glTexGen. Otherwise, the current q texture coordinate is used. See glTexGen. GL_TEXTURE_GEN_R If enabled, the r texture coordinate is computed using the texture generation function defined with glTexGen. Otherwise, the current r texture coordinate is used. See glTexGen. GL_TEXTURE_GEN_S If enabled, the s texture coordinate is computed using the texture generation function defined with glTexGen. Otherwise, the current s texture coordinate is used. See glTexGen. GL_TEXTURE_GEN_T If enabled, the t texture coordinate is computed using the texture generation function defined with glTexGen. Otherwise, the current t texture coordinate is used. See glTexGen.

Specifies a symbolic constant indicating a GL capability.

Specifies a symbolic constant indicating a GL capability.

GL_INVALID_ENUM is generated if cap is not one of the values listed previously.

GL_INVALID_OPERATION is generated if glEnable or glDisable is executed between the execution of glBegin and the corresponding execution of glEnd.

glEnableClientState and glDisableClientState enable or disable individual client-side capabilities. By default, all client-side capabilities are disabled. Both glEnableClientState and glDisableClientState take a single argument, cap, which can assume one of the following values:

GL_COLOR_ARRAY If enabled, the color array is enabled for writing and used during rendering when glDrawArrays or glDrawElement is called. See glColorPointer. GL_EDGE_FLAG_ARRAY If enabled, the edge flag array is enabled for writing and used during rendering when glDrawArrays or glDrawElements is called. See glEdgeFlagPointer. GL_INDEX_ARRAY If enabled, the index array is enabled for writing and used during rendering when glDrawArrays or glDrawElements is called. See glIndexPointer. GL_NORMAL_ARRAY If enabled, the normal array is enabled for writing and used during rendering when glDrawArrays or glDrawElements is called. See glNormalPointer. GL_TEXTURE_COORD_ARRAY If enabled, the texture coordinate array is enabled for writing and used for rendering when glDrawArrays or glDrawElements is called. See glTexCoordPointer. GL_VERTEX_ARRAY If enabled, the vertex array is enabled for writing and used during rendering when glDrawArrays or glDrawElements is called. See glVertexPointer.

Specifies the capability to enable. Symbolic constants GL_COLOR_ARRAY, GL_EDGE_FLAG_ARRAY, GL_INDEX_ARRAY, GL_NORMAL_ARRAY, GL_TEXTURE_COORD_ARRAY, and GL_VERTEX_ARRAY are accepted.

Specifies the capability to disable.

GL_INVALID_ENUM is generated if cap is not an accepted value.

glEnableClientState is not allowed between the execution of glBegin and the corresponding glEnd, but an error may or may not be generated. If no error is generated, the behavior is undefined.

In a scene composed entirely of opaque closed surfaces, back-facing polygons are never visible. Eliminating these invisible polygons has the obvious benefit of speeding up the rendering of the image. To enable and disable elimination of back-facing polygons, call glEnable and glDisable with argument GL_CULL_FACE.

The projection of a polygon to window coordinates is said to have clockwise winding if an imaginary object following the path from its first vertex, its second vertex, and so on, to its last vertex, and finally back to its first vertex, moves in a clockwise direction about the interior of the polygon. The polygon's winding is said to be counterclockwise if the imaginary object following the same path moves in a counterclockwise direction about the interior of the polygon. glFrontFace specifies whether polygons with clockwise winding in window coordinates, or counterclockwise winding in window coordinates, are taken to be front-facing. Passing GL_CCW to mode selects counterclockwise polygons as front-facing; GL_CW selects clockwise polygons as front-facing. By default, counterclockwise polygons are taken to be front-facing.

Specifies the orientation of front-facing polygons. GL_CW and GL_CCW are accepted. The initial value is GL_CCW.

GL_INVALID_ENUM is generated if mode is not an accepted value.

GL_INVALID_OPERATION is generated if glFrontFace is executed between the execution of glBegin and the corresponding execution of glEnd.

glLogicOp specifies a logical operation that, when enabled, is applied between the incoming color index or RGBA color and the color index or RGBA color at the corresponding location in the frame buffer. To enable or disable the logical operation, call glEnable and glDisable using the symbolic constant GL_COLOR_LOGIC_OP for RGBA mode or GL_INDEX_LOGIC_OP for color index mode. The initial value is disabled for both operations.

.ne .TS center box ; ci | ci c | c . opcode resulting value = GL_CLEAR 0 GL_SET 1 GL_COPY s GL_COPY_INVERTED ~s GL_NOOP d GL_INVERT ~d GL_AND s & d GL_NAND ~(s & d) GL_OR s | d GL_NOR ~(s | d) GL_XOR s ^ d GL_EQUIV ~(s ^ d) GL_AND_REVERSE s & ~d GL_AND_INVERTED ~s & d GL_OR_REVERSE s | ~d GL_OR_INVERTED ~s | d .TE

opcode is a symbolic constant chosen from the list above. In the explanation of the logical operations, s represents the incoming color index and d represents the index in the frame buffer. Standard C-language operators are used. As these bitwise operators suggest, the logical operation is applied independently to each bit pair of the source and destination indices or colors.

Specifies a symbolic constant that selects a logical operation. The following symbols are accepted: GL_CLEAR, GL_SET, GL_COPY, GL_COPY_INVERTED, GL_NOOP, GL_INVERT, GL_AND, GL_NAND, GL_OR, GL_NOR, GL_XOR, GL_EQUIV, GL_AND_REVERSE, GL_AND_INVERTED, GL_OR_REVERSE, and GL_OR_INVERTED. The initial value is GL_COPY.

GL_INVALID_ENUM is generated if opcode is not an accepted value.

GL_INVALID_OPERATION is generated if glLogicOp is executed between the execution of glBegin and the corresponding execution of glEnd.

glMatrixMode sets the current matrix mode. mode can assume one of three values:

GL_MODELVIEW Applies subsequent matrix operations to the modelview matrix stack. GL_PROJECTION Applies subsequent matrix operations to the projection matrix stack. GL_TEXTURE Applies subsequent matrix operations to the texture matrix stack.

To find out which matrix stack is currently the target of all matrix operations, call glGet with argument GL_MATRIX_MODE. The initial value is GL_MODELVIEW.

Specifies which matrix stack is the target for subsequent matrix operations. Three values are accepted: GL_MODELVIEW, GL_PROJECTION, and GL_TEXTURE. The initial value is GL_MODELVIEW.

GL_INVALID_ENUM is generated if mode is not an accepted value.

GL_INVALID_OPERATION is generated if glMatrixMode is executed between the execution of glBegin and the corresponding execution of glEnd.

glReadBuffer specifies a color buffer as the source for subsequent glReadPixels, glCopyTexImage1D, glCopyTexImage2D, glCopyTexSubImage1D, glCopyTexSubImage2D, and glCopyPixels commands. mode accepts one of twelve or more predefined values. (GL_AUX0 through GL_AUX3 are always defined.) In a fully configured system, GL_FRONT, GL_LEFT, and GL_FRONT_LEFT all name the front left buffer, GL_FRONT_RIGHT and GL_RIGHT name the front right buffer, and GL_BACK_LEFT and GL_BACK name the back left buffer.

Nonstereo double-buffered configurations have only a front left and a back left buffer. Single-buffered configurations have a front left and a front right buffer if stereo, and only a front left buffer if nonstereo. It is an error to specify a nonexistent buffer to glReadBuffer.

mode is initially GL_FRONT in single-buffered configurations, and GL_BACK in double-buffered configurations.

Specifies a color buffer. Accepted values are GL_FRONT_LEFT, GL_FRONT_RIGHT, GL_BACK_LEFT, GL_BACK_RIGHT, GL_FRONT, GL_BACK, GL_LEFT, GL_RIGHT, and GL_AUXi, where i is between 0 and GL_AUX_BUFFERS -1.

GL_INVALID_ENUM is generated if mode is not one of the twelve (or more) accepted values.

GL_INVALID_OPERATION is generated if mode specifies a buffer that does not exist.

GL_INVALID_OPERATION is generated if glReadBuffer is executed between the execution of glBegin and the corresponding execution of glEnd.

glRenderMode sets the rasterization mode. It takes one argument, mode, which can assume one of three predefined values:

GL_RENDER Render mode. Primitives are rasterized, producing pixel fragments, which are written into the frame buffer. This is the normal mode and also the default mode. GL_SELECT Selection mode. No pixel fragments are produced, and no change to the frame buffer contents is made. Instead, a record of the names of primitives that would have been drawn if the render mode had been GL_RENDER is returned in a select buffer, which must be created (see glSelectBuffer) before selection mode is entered. GL_FEEDBACK Feedback mode. No pixel fragments are produced, and no change to the frame buffer contents is made. Instead, the coordinates and attributes of vertices that would have been drawn if the render mode had been GL_RENDER is returned in a feedback buffer, which must be created (see glFeedbackBuffer) before feedback mode is entered.

The return value of glRenderMode is determined by the render mode at the time glRenderMode is called, rather than by mode. The values returned for the three render modes are as follows:

GL_RENDER 0. GL_SELECT The number of hit records transferred to the select buffer. GL_FEEDBACK The number of values (not vertices) transferred to the feedback buffer.

See the glSelectBuffer and glFeedbackBuffer reference pages for more details concerning selection and feedback operation.

Specifies the rasterization mode. Three values are accepted: GL_RENDER, GL_SELECT, and GL_FEEDBACK. The initial value is GL_RENDER.

GL_INVALID_ENUM is generated if mode is not one of the three accepted values.

GL_INVALID_OPERATION is generated if glSelectBuffer is called while the render mode is GL_SELECT, or if glRenderMode is called with argument GL_SELECT before glSelectBuffer is called at least once.

GL_INVALID_OPERATION is generated if glFeedbackBuffer is called while the render mode is GL_FEEDBACK, or if glRenderMode is called with argument GL_FEEDBACK before glFeedbackBuffer is called at least once.

GL_INVALID_OPERATION is generated if glRenderMode is executed between the execution of glBegin and the corresponding execution of glEnd.

GL primitives can have either flat or smooth shading. Smooth shading, the default, causes the computed colors of vertices to be interpolated as the primitive is rasterized, typically assigning different colors to each resulting pixel fragment. Flat shading selects the computed color of just one vertex and assigns it to all the pixel fragments generated by rasterizing a single primitive. In either case, the computed color of a vertex is the result of lighting if lighting is enabled, or it is the current color at the time the vertex was specified if lighting is disabled.

Flat and smooth shading are indistinguishable for points. Starting when glBegin is issued and counting vertices and primitives from 1, the GL gives each flat-shaded line segment i the computed color of vertex i + 1, its second vertex. Counting similarly from 1, the GL gives each flat-shaded polygon the computed color of the vertex listed in the following table. This is the last vertex to specify the polygon in all cases except single polygons, where the first vertex specifies the flat-shaded color. .sp .TS center box; l | c . primitive type of polygon i vertex = Single polygon ( i == 1 ) 1 Triangle strip i + 2 Triangle fan i + 2 Independent triangle 3 i Quad strip 2 i + 2 Independent quad 4 i .TE .sp Flat and smooth shading are specified by glShadeModel with mode set to GL_FLAT and GL_SMOOTH, respectively.

Specifies a symbolic value representing a shading technique. Accepted values are GL_FLAT and GL_SMOOTH. The initial value is GL_SMOOTH.

GL_INVALID_ENUM is generated if mode is any value other than GL_FLAT or GL_SMOOTH.

GL_INVALID_OPERATION is generated if glShadeModel is executed between the execution of glBegin and the corresponding execution of glEnd.

Used in glFeedbackBuffer

Used in glCallLists

Used in glFeedbackBuffer

Used in glFeedbackBuffer

Used in glFeedbackBuffer

Used in glCallLists

Used in glFeedbackBuffer

Used in glCallLists

Used in glGetIntegerv, glPopAttrib, glGetBooleanv, glPushAttrib, glGetFloatv, glAccum, glGetDoublev and glClear

Used in glGetIntegerv, glGetBooleanv, glGetFloatv, glAccum and glGetDoublev

Used in glGetIntegerv, glGetBooleanv, glGetFloatv, glAccum and glGetDoublev

Used in glPopAttrib, glPushAttrib and glClear

Used in glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glGetIntegerv, glGetBooleanv, glGetFloatv, glAccum and glGetDoublev

Used in glGetIntegerv, glGetBooleanv, glGetFloatv, glAccum and glGetDoublev

Used in glAccum

Used in glPopAttrib and glPushAttrib

Used in glIsEnabled, glTexEnv, glGetIntegerv, glDrawPixels, glDisable, glCopyTexImage1D, glTexSubImage2D, glPopAttrib, glEnable, glPixelTransfer, glGetBooleanv, glGetTexImage, glPushAttrib, glGetFloatv, glGetDoublev, glAlphaFunc, glReadPixels, glCopyTexImage2D, glTexImage2D, glTexSubImage1D and glTexImage1D

Used in glCopyTexImage1D, glCopyTexImage2D, glTexImage2D and glTexImage1D

Used in glCopyTexImage1D, glCopyTexImage2D, glTexImage2D and glTexImage1D

Used in glCopyTexImage1D, glCopyTexImage2D, glTexImage2D and glTexImage1D

Used in glCopyTexImage1D, glCopyTexImage2D, glTexImage2D and glTexImage1D

Used in glGetIntegerv, glPopAttrib, glPixelTransfer, glGetBooleanv, glPushAttrib, glGetFloatv and glGetDoublev

Used in glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glGetIntegerv, glPopAttrib, glPixelTransfer, glGetBooleanv, glPushAttrib, glGetFloatv and glGetDoublev

Used in glIsEnabled, glGetIntegerv, glDisable, glPopAttrib, glEnable, glGetBooleanv, glPushAttrib, glGetFloatv, glGetDoublev and glAlphaFunc

Used in glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glGetIntegerv, glGetBooleanv, glGetFloatv, glGetDoublev, glAlphaFunc, glDepthFunc and glStencilFunc

Used in glGetIntegerv, glColorMaterial, glGetLight, glGetBooleanv, glGetFloatv, glMaterial, glGetDoublev, glLight and glGetMaterial

Used in glGetIntegerv, glColorMaterial, glGetBooleanv, glGetFloatv, glMaterial and glGetDoublev

Used in glLogicOp

Used in glLogicOp

Used in glLogicOp

Used in glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glIsEnabled, glGetIntegerv, glDisable, glPopAttrib, glEnable, glGetBooleanv, glPushAttrib, glGetFloatv, glGetDoublev and glEvalCoord

Used in glReadBuffer

Used in glReadBuffer

Used in glGetIntegerv, glGetBooleanv, glGetFloatv, glReadBuffer, glGetDoublev and glDrawBuffer

Used in glGetIntegerv, glColorMaterial, glCullFace, glPolygonMode, glGetBooleanv, glGetFloatv, glReadBuffer, glMaterial, glGetDoublev, glDrawBuffer and glGetMaterial

Used in glReadBuffer and glDrawBuffer

Used in glReadBuffer and glDrawBuffer

Used in glDrawPixels, glTexSubImage2D, glGetTexImage, glReadPixels, glTexImage2D, glFeedbackBuffer, glGetPolygonStipple, glBitmap, glTexSubImage1D, glTexImage1D and glPolygonStipple

Used in glFeedbackBuffer

Used in glIsEnabled, glTexEnv, glGetIntegerv, glBlendColorEXT, glBlendFunc, glDisable, glPopAttrib, glEnable, glGetBooleanv, glPushAttrib, glGetFloatv and glGetDoublev

Used in glGetIntegerv, glBlendColorEXT, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glGetIntegerv, glDrawPixels, glTexSubImage2D, glPopAttrib, glPixelTransfer, glGetBooleanv, glGetTexImage, glPushAttrib, glGetFloatv, glGetDoublev, glReadPixels, glTexImage2D, glTexSubImage1D and glTexImage1D

Used in glGetIntegerv, glPopAttrib, glPixelTransfer, glGetBooleanv, glPushAttrib, glGetFloatv and glGetDoublev

Used in glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glGetIntegerv, glPopAttrib, glPixelTransfer, glGetBooleanv, glPushAttrib, glGetFloatv and glGetDoublev

Used in glDrawPixels, glColorPointer, glTexSubImage2D, glNormalPointer, glGetTexImage, glCallLists, glReadPixels, glTexImage2D, glTexSubImage1D and glTexImage1D

Used in glInterleavedArrays

Used in glInterleavedArrays

Used in glInterleavedArrays

Used in glInterleavedArrays

Used in glGetIntegerv, glGetBooleanv, glGetFloatv, glGetDoublev and glFrontFace

Used in glTexParameter

Used in glLogicOp

Used in glPopClientAttrib and glPushClientAttrib

Used in glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glPopClientAttrib and glPushClientAttrib

Used in glPopClientAttrib and glPushClientAttrib

Used in glGetMap

Used in glIsEnabled, glGetIntegerv, glDrawElements, glDrawArrays, glColorMaterial, glDrawPixels, glDisable, glColorPointer, glTexSubImage2D, glPopAttrib, glEnable, glEnableClientState, glGetPointerv, glPixelTransfer, glLogicOp, glGetBooleanv, glGetTexImage, glPushAttrib, glGetFloatv, glMaterial, glGetDoublev, glReadPixels, glTexImage2D, glGetPolygonStipple, glBitmap, glCopyPixels, glLightModel, glDisableClientState, glTexSubImage1D, glTexImage1D, glGetMaterial, glClear and glPolygonStipple

Used in glIsEnabled, glGetIntegerv, glDrawElements, glDrawArrays, glColorPointer, glEnableClientState, glGetPointerv, glGetBooleanv, glGetFloatv, glGetDoublev and glDisableClientState

Used in glGetPointerv

Used in glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glPopAttrib, glPushAttrib and glClear

Used in glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glDrawPixels, glTexSubImage2D, glPixelTransfer, glGetTexImage, glMaterial, glReadPixels, glTexImage2D, glGetPolygonStipple, glBitmap, glLightModel, glTexSubImage1D, glTexImage1D, glGetMaterial and glPolygonStipple

Used in glMaterial, glLightModel and glGetMaterial

Used in glIsEnabled, glGetIntegerv, glDisable, glPopAttrib, glEnable, glLogicOp, glGetBooleanv, glPushAttrib, glGetFloatv and glGetDoublev

Used in glIsEnabled, glGetIntegerv, glColorMaterial, glDisable, glPopAttrib, glEnable, glGetBooleanv, glPushAttrib, glGetFloatv and glGetDoublev

Used in glGetIntegerv, glPopAttrib, glGetBooleanv, glPushAttrib, glGetFloatv and glGetDoublev

Used in glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glNewList and glEndList

Used in glNewList and glEndList

Used in glGetLight and glLight

Used in glGetIntegerv, glLogicOp, glGetBooleanv, glGetFloatv, glGetDoublev and glFeedbackBuffer

Used in glLogicOp

Used in glFeedbackBuffer

Used in glIsEnabled, glGetIntegerv, glCullFace, glDisable, glPopAttrib, glEnable, glGetBooleanv, glPushAttrib, glGetFloatv, glGetDoublev and glFrontFace

Used in glGetIntegerv, glPopAttrib, glGetBooleanv, glPushAttrib, glGetFloatv and glGetDoublev

Used in glPopAttrib and glPushAttrib

Used in glGetIntegerv, glGetBooleanv, glGetFloatv, glGetDoublev and glRasterPos

Used in glGetIntegerv, glGetBooleanv, glGetFloatv, glGetDoublev and glRasterPos

Used in glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glGetIntegerv, glGetBooleanv, glGetFloatv, glGetDoublev and glRasterPos

Used in glGetIntegerv, glGetBooleanv, glGetFloatv, glGetDoublev and glRasterPos

Used in glGetIntegerv, glGetBooleanv, glGetFloatv, glGetDoublev and glRasterPos

Used in glGetIntegerv, glDrawPixels, glPopAttrib, glGetBooleanv, glPushAttrib, glGetFloatv, glGetDoublev and glRasterPos

Used in glGetIntegerv, glPopAttrib, glGetBooleanv, glPushAttrib, glGetFloatv, glGetDoublev and glRasterPos

Used in glGetIntegerv, glGetBooleanv, glGetFloatv, glGetDoublev and glRasterPos

Used in glGetIntegerv, glGetBooleanv, glGetFloatv, glGetDoublev and glRasterPos

Used in glFrontFace

Used in glTexEnv

Used in glStencilOp

Used in glIsEnabled, glGetIntegerv, glDrawPixels, glDisable, glPopAttrib, glEnable, glPixelTransfer, glGetBooleanv, glGetTexImage, glPushAttrib, glGetFloatv, glGetDoublev, glReadPixels, glTexImage2D, glCopyPixels, glDepthFunc, glTexImage1D and glClear

Used in glGetIntegerv, glDrawPixels, glPopAttrib, glPixelTransfer, glGetBooleanv, glPushAttrib, glGetFloatv, glGetDoublev, glReadPixels and glCopyPixels

Used in glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glPopAttrib, glPushAttrib and glClear

Used in glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glDrawPixels, glGetTexImage, glReadPixels, glTexImage2D and glTexImage1D

Used in glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glGetIntegerv, glDrawPixels, glPopAttrib, glPixelTransfer, glGetBooleanv, glPushAttrib, glGetFloatv, glGetDoublev, glReadPixels and glCopyPixels

Used in glIsEnabled, glGetIntegerv, glDisable, glPopAttrib, glEnable, glGetBooleanv, glPushAttrib, glGetFloatv, glGetDoublev and glDepthFunc

Used in glGetIntegerv, glPopAttrib, glGetBooleanv, glPushAttrib, glGetFloatv and glGetDoublev

Used in glColorMaterial, glGetLight, glMaterial, glLight and glGetMaterial

Used in glIsEnabled, glGetIntegerv, glDisable, glPopAttrib, glEnable, glGetBooleanv, glPushAttrib, glGetFloatv and glGetDoublev

Used in glGetMap

Used in glGetIntegerv, glGetBooleanv, glGetFloatv, glGetDoublev and glHint

Used in glGetIntegerv, glVertexPointer, glColorPointer, glNormalPointer, glGetBooleanv, glGetFloatv, glGetDoublev, glTexCoordPointer and glIndexPointer

Used in glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glGetIntegerv, glPopAttrib, glGetBooleanv, glPushAttrib, glGetFloatv and glGetDoublev

Used in glFeedbackBuffer

Used in glBlendFunc

Used in glBlendFunc

Used in glIsEnabled, glGetIntegerv, glPopAttrib, glEnableClientState, glGetPointerv, glGetBooleanv, glPushAttrib, glGetFloatv, glEdgeFlagPointer, glGetDoublev and glDisableClientState

Used in glIsEnabled, glGetIntegerv, glEnableClientState, glGetPointerv, glGetBooleanv, glGetFloatv, glEdgeFlagPointer, glGetDoublev and glDisableClientState

Used in glGetPointerv

Used in glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glColorMaterial, glMaterial and glGetMaterial

Used in glPopAttrib and glPushAttrib

Used in glAlphaFunc, glDepthFunc and glStencilFunc

Used in glLogicOp

Used in glPopAttrib and glPushAttrib

Used in glFog, glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glFog

Used in glGetString

Used in glGetTexGen and glTexGen

Used in glGetTexGen and glTexGen

Used in glIsEnabled, glDepthMask, glIsList, glAreTexturesResident, glGetIntegerv, glIsTexture, glDisable, glEdgeFlag, glEnable, glColorMask, glGetBooleanv, glGetFloatv, glGetDoublev and glEdgeFlagv

Used in glHint

Used in glRenderMode, glPassThrough, glGetPointerv and glFeedbackBuffer

Used in glGetPointerv

Used in glGetIntegerv, glDisable, glEnable, glPolygonMode, glGetBooleanv, glGetFloatv, glGetDoublev and glEvalMesh

Used in glShadeModel

Used in glGetIntegerv, glDrawPixels, glVertexPointer, glColorPointer, glTexSubImage2D, glNormalPointer, glGetBooleanv, glGetTexImage, glGetFloatv, glGetDoublev, glCallLists, glReadPixels, glTexImage2D, glTexCoordPointer, glIndexPointer, glTexSubImage1D and glTexImage1D

Used in glIsEnabled, glFog, glGetIntegerv, glDisable, glPopAttrib, glEnable, glGetBooleanv, glPushAttrib, glGetFloatv, glGetDoublev and glHint

Used in glPopAttrib and glPushAttrib

Used in glFog, glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glFog, glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glFog, glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glGetIntegerv, glPopAttrib, glGetBooleanv, glPushAttrib, glGetFloatv, glGetDoublev and glHint

Used in glFog, glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glFog, glGetIntegerv, glPopAttrib, glGetBooleanv, glPushAttrib, glGetFloatv and glGetDoublev

Used in glFog, glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glGetIntegerv, glColorMaterial, glCullFace, glPopAttrib, glPolygonMode, glGetBooleanv, glPushAttrib, glGetFloatv, glReadBuffer, glMaterial, glGetDoublev, glDrawBuffer and glGetMaterial

Used in glGetIntegerv, glColorMaterial, glCullFace, glPolygonMode, glGetBooleanv, glGetFloatv, glMaterial, glGetDoublev and glDrawBuffer

Used in glGetIntegerv, glPopAttrib, glGetBooleanv, glPushAttrib, glGetFloatv and glGetDoublev

Used in glReadBuffer and glDrawBuffer

Used in glReadBuffer and glDrawBuffer

Used in glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glAlphaFunc, glDepthFunc and glStencilFunc

Used in glAlphaFunc, glDepthFunc and glStencilFunc

Used in glGetIntegerv, glDrawPixels, glTexSubImage2D, glPopAttrib, glPixelTransfer, glGetBooleanv, glGetTexImage, glPushAttrib, glGetFloatv, glGetDoublev, glReadPixels, glTexImage2D, glTexSubImage1D and glTexImage1D

Used in glGetIntegerv, glPopAttrib, glPixelTransfer, glGetBooleanv, glPushAttrib, glGetFloatv and glGetDoublev

Used in glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glGetIntegerv, glPopAttrib, glPixelTransfer, glGetBooleanv, glPushAttrib, glGetFloatv and glGetDoublev

Used in glPopAttrib and glPushAttrib

Used in glStencilOp

Used in glIsEnabled, glGetIntegerv, glEnableClientState, glGetPointerv, glGetBooleanv, glGetFloatv, glGetDoublev, glIndexPointer and glDisableClientState

Used in glGetPointerv

Used in glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glIsEnabled, glGetIntegerv, glDisable, glPopAttrib, glEnable, glLogicOp, glGetBooleanv, glPushAttrib, glGetFloatv and glGetDoublev

Used in glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glGetIntegerv, glDrawPixels, glPopAttrib, glPixelTransfer, glGetBooleanv, glPushAttrib, glGetFloatv, glGetDoublev, glReadPixels, glTexImage2D, glCopyPixels and glTexImage1D

Used in glGetIntegerv, glDrawPixels, glPopAttrib, glPixelTransfer, glGetBooleanv, glPushAttrib, glGetFloatv, glGetDoublev, glReadPixels, glTexImage2D, glCopyPixels and glTexImage1D

Used in glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glTexEnv, glDrawPixels, glVertexPointer, glColorPointer, glCopyTexImage1D, glTexSubImage2D, glNormalPointer, glGetTexImage, glCallLists, glReadPixels, glCopyTexImage2D, glTexImage2D, glTexCoordPointer, glIndexPointer, glTexSubImage1D and glTexImage1D

Used in glTexEnv, glCopyTexImage1D, glCopyTexImage2D, glTexImage2D and glTexImage1D

Used in glCopyTexImage1D, glCopyTexImage2D, glTexImage2D and glTexImage1D

Used in glCopyTexImage1D, glCopyTexImage2D, glTexImage2D and glTexImage1D

Used in glCopyTexImage1D, glCopyTexImage2D, glTexImage2D and glTexImage1D

Used in glCopyTexImage1D, glCopyTexImage2D, glTexImage2D and glTexImage1D

Used in glMatrixMode, glPixelStore, glIsEnabled, glGetTexLevelParameter, glFog, glTexEnv, glMap1, glRenderMode, glGetTexGen, glGetIntegerv, glEnd, glDrawElements, glDrawArrays, glCopyTexSubImage2D, glColorMaterial, glBindTexture, glGetClipPlane, glCullFace, glGetError, glClipPlane, glDrawPixels, glBlendFunc, glVertexPointer, glGetLight, glDisable, glMap2, glColorPointer, glCopyTexImage1D, glGetPixelMap, glTexSubImage2D, glNormalPointer, glEnable, glEnableClientState, glGetPointerv, glPixelTransfer, glPolygonMode, glGetTexParameter, glLogicOp, glGetBooleanv, glGetTexImage, glPixelMap, glGetFloatv, glGetMap, glAccum, glReadBuffer, glMaterial, glEdgeFlagPointer, glGetDoublev, glCallLists, glInterleavedArrays, glAlphaFunc, glShadeModel, glNewList, glReadPixels, glCopyTexImage2D, glTexImage2D, glGetTexEnv, glFeedbackBuffer, glEndList, glBegin, glLight, glStencilOp, glTexCoordPointer, glCopyPixels, glDepthFunc, glLightModel, glIndexPointer, glGetString, glTexParameter, glDisableClientState, glTexSubImage1D, glDrawBuffer, glHint, glTexImage1D, glStencilFunc, glGetMaterial, glCopyTexSubImage1D, glFrontFace, glEvalMesh and glTexGen

Used in glPolygonOffset, glPushMatrix, glMatrixMode, glLoadName, glPixelStore, glIsEnabled, glGetTexLevelParameter, glGenTextures, glFog, glTexEnv, glClearColor, glMap1, glPrioritizeTextures, glDepthMask, glPushName, glRenderMode, glMultMatrix, glIsList, glFrustum, glDepthRange, glAreTexturesResident, glDeleteTextures, glGetTexGen, glGetIntegerv, glEnd, glIsTexture, glDrawElements, glGenLists, glBlendColorEXT, glViewport, glDrawArrays, glCopyTexSubImage2D, glColorMaterial, glBindTexture, glGetClipPlane, glFinish, glCullFace, glGetError, glStencilMask, glClipPlane, glDrawPixels, glBlendFunc, glSelectBuffer, glGetLight, glInitNames, glPassThrough, glDisable, glMap2, glLineStipple, glCopyTexImage1D, glGetPixelMap, glTexSubImage2D, glPopAttrib, glEnable, glListBase, glColorMask, glPixelTransfer, glPolygonMode, glGetTexParameter, glPopName, glLogicOp, glIndexMask, glGetBooleanv, glGetTexImage, glPixelMap, glTranslate, glPushAttrib, glGetFloatv, glGetMap, glAccum, glReadBuffer, glGetDoublev, glClearDepth, glRasterPos, glAlphaFunc, glShadeModel, glNewList, glReadPixels, glCopyTexImage2D, glRect, glTexImage2D, glGetTexEnv, glClearIndex, glFeedbackBuffer, glRotate, glEndList, glBegin, glLight, glGetPolygonStipple, glStencilOp, glClearStencil, glBitmap, glScale, glCopyPixels, glFlush, glOrtho, glDepthFunc, glMapGrid, glLightModel, glGetString, glTexParameter, glScissor, glTexSubImage1D, glLoadIdentity, glPixelZoom, glDrawBuffer, glLineWidth, glHint, glTexImage1D, glStencilFunc, glGetMaterial, glClear, glCopyTexSubImage1D, glPopMatrix, glPointSize, glPolygonStipple, glFrontFace, glLoadMatrix, glEvalMesh, glTexGen, glClearAccum and glDeleteLists

Used in glPixelStore, glGetTexLevelParameter, glGenTextures, glFog, glMap1, glPrioritizeTextures, glFrustum, glAreTexturesResident, glDeleteTextures, glDrawElements, glGenLists, glViewport, glDrawArrays, glCopyTexSubImage2D, glGetError, glDrawPixels, glVertexPointer, glSelectBuffer, glMap2, glColorPointer, glCopyTexImage1D, glTexSubImage2D, glNormalPointer, glGetTexImage, glPixelMap, glMaterial, glCallLists, glInterleavedArrays, glNewList, glReadPixels, glCopyTexImage2D, glTexImage2D, glFeedbackBuffer, glEndList, glLight, glBitmap, glTexCoordPointer, glCopyPixels, glMapGrid, glIndexPointer, glScissor, glTexSubImage1D, glLineWidth, glTexImage1D, glClear, glCopyTexSubImage1D, glPointSize and glDeleteLists

Used in glLogicOp and glStencilOp

Used in glGetIntegerv, glGetBooleanv, glGetFloatv, glGetDoublev and glStencilOp

Used in glReadBuffer and glDrawBuffer

Used in glAlphaFunc, glDepthFunc and glStencilFunc

Used in glGetIntegerv, glGetBooleanv, glGetFloatv, glGetDoublev, glAlphaFunc, glDepthFunc and glStencilFunc

Used in glGetLight and glLight

Used in glIsEnabled, glGetIntegerv, glDisable, glPopAttrib, glEnable, glGetBooleanv, glPushAttrib, glGetFloatv, glGetDoublev and glLight

Used in glPopAttrib and glPushAttrib

Used in glGetIntegerv, glGetBooleanv, glGetFloatv, glGetDoublev and glLightModel

Used in glGetIntegerv, glPopAttrib, glGetBooleanv, glPushAttrib, glGetFloatv, glGetDoublev and glLightModel

Used in glGetIntegerv, glPopAttrib, glGetBooleanv, glPushAttrib, glGetFloatv, glGetDoublev and glLightModel

Used in glIsEnabled, glFog, glGetIntegerv, glEnd, glDrawElements, glDrawArrays, glGetLight, glDisable, glLineStipple, glEdgeFlag, glPopAttrib, glEnable, glPolygonMode, glGetTexParameter, glGetBooleanv, glPushAttrib, glGetFloatv, glGetDoublev, glFeedbackBuffer, glBegin, glLight, glTexParameter, glLineWidth, glHint, glEdgeFlagv and glEvalMesh

Used in glFog, glGetLight, glGetTexParameter, glLight and glTexParameter

Used in glGetLight and glLight

Used in glTexParameter

Used in glTexParameter

Used in glEnd, glDrawElements, glDrawArrays, glLineStipple, glBegin and glEvalMesh

Used in glPopAttrib and glPushAttrib

Used in glEnd, glDrawElements, glDrawArrays and glBegin

Used in glFeedbackBuffer

Used in glIsEnabled, glGetIntegerv, glDisable, glPopAttrib, glEnable, glPolygonMode, glGetBooleanv, glPushAttrib, glGetFloatv, glGetDoublev, glLineWidth and glHint

Used in glGetIntegerv, glPopAttrib, glGetBooleanv, glPushAttrib, glGetFloatv, glGetDoublev and glHint

Used in glIsEnabled, glGetIntegerv, glDisable, glLineStipple, glPopAttrib, glEnable, glGetBooleanv, glPushAttrib, glGetFloatv and glGetDoublev

Used in glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glEnd, glDrawElements, glDrawArrays, glBegin and glEvalMesh

Used in glFeedbackBuffer

Used in glGetIntegerv, glPolygonMode, glGetBooleanv, glGetFloatv, glGetDoublev and glLineWidth

Used in glGetIntegerv, glGetBooleanv, glGetFloatv, glGetDoublev and glLineWidth

Used in glGetIntegerv, glGetBooleanv, glGetFloatv, glGetDoublev and glLineWidth

Used in glGetIntegerv, glPopAttrib, glGetBooleanv, glPushAttrib, glGetFloatv and glGetDoublev

Used in glPopAttrib and glPushAttrib

Used in glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glAccum

Used in glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glTexEnv, glDrawPixels, glCopyTexImage1D, glTexSubImage2D, glGetTexImage, glReadPixels, glCopyTexImage2D, glTexImage2D, glTexSubImage1D and glTexImage1D

Used in glCopyTexImage1D, glCopyTexImage2D, glTexImage2D and glTexImage1D

Used in glCopyTexImage1D, glCopyTexImage2D, glTexImage2D and glTexImage1D

Used in glCopyTexImage1D, glCopyTexImage2D, glTexImage2D and glTexImage1D

Used in glCopyTexImage1D, glCopyTexImage2D, glTexImage2D and glTexImage1D

Used in glCopyTexImage1D, glCopyTexImage2D, glTexImage2D and glTexImage1D

Used in glCopyTexImage1D, glCopyTexImage2D, glTexImage2D and glTexImage1D

Used in glCopyTexImage1D, glCopyTexImage2D, glTexImage2D and glTexImage1D

Used in glCopyTexImage1D, glCopyTexImage2D, glTexImage2D and glTexImage1D

Used in glCopyTexImage1D, glCopyTexImage2D, glTexImage2D and glTexImage1D

Used in glCopyTexImage1D, glCopyTexImage2D, glTexImage2D and glTexImage1D

Used in glDrawPixels, glCopyTexImage1D, glTexSubImage2D, glGetTexImage, glReadPixels, glCopyTexImage2D, glTexImage2D, glTexSubImage1D and glTexImage1D

Used in glIsEnabled, glMap1, glGetIntegerv, glDisable, glEnable, glGetBooleanv, glGetFloatv, glGetMap, glGetDoublev and glEvalCoord

Used in glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glMap1, glGetIntegerv, glDisable, glEnable, glGetBooleanv, glGetFloatv, glGetMap, glGetDoublev and glEvalCoord

Used in glMap1, glGetIntegerv, glDisable, glEnable, glGetBooleanv, glGetFloatv, glGetMap, glGetDoublev and glEvalCoord

Used in glMap1, glGetIntegerv, glDisable, glEnable, glGetBooleanv, glGetFloatv, glGetMap, glGetDoublev and glEvalCoord

Used in glMap1, glGetIntegerv, glDisable, glEnable, glGetBooleanv, glGetFloatv, glGetMap, glGetDoublev and glEvalCoord

Used in glMap1, glGetIntegerv, glDisable, glEnable, glGetBooleanv, glGetFloatv, glGetMap, glGetDoublev and glEvalCoord

Used in glMap1, glGetIntegerv, glDisable, glEnable, glGetBooleanv, glGetFloatv, glGetMap, glGetDoublev and glEvalCoord

Used in glMap1, glGetIntegerv, glDisable, glEnable, glGetBooleanv, glGetFloatv, glGetMap, glGetDoublev and glEvalCoord

Used in glMap1, glGetIntegerv, glDisable, glEnable, glGetBooleanv, glGetFloatv, glGetMap, glGetDoublev and glEvalCoord

Used in glGetIntegerv, glDisable, glMap2, glEnable, glGetBooleanv, glGetFloatv, glGetMap, glGetDoublev and glEvalCoord

Used in glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glGetIntegerv, glDisable, glMap2, glEnable, glGetBooleanv, glGetFloatv, glGetMap, glGetDoublev and glEvalCoord

Used in glGetIntegerv, glDisable, glMap2, glEnable, glGetBooleanv, glGetFloatv, glGetMap, glGetDoublev and glEvalCoord

Used in glGetIntegerv, glDisable, glMap2, glEnable, glGetBooleanv, glGetFloatv, glGetMap, glGetDoublev and glEvalCoord

Used in glIsEnabled, glGetIntegerv, glDisable, glMap2, glEnable, glGetBooleanv, glGetFloatv, glGetMap, glGetDoublev and glEvalCoord

Used in glIsEnabled, glGetIntegerv, glDisable, glMap2, glEnable, glGetBooleanv, glGetFloatv, glGetMap, glGetDoublev and glEvalCoord

Used in glIsEnabled, glGetIntegerv, glDisable, glMap2, glEnable, glGetBooleanv, glGetFloatv, glGetMap, glGetDoublev and glEvalCoord

Used in glIsEnabled, glGetIntegerv, glDisable, glMap2, glEnable, glGetBooleanv, glGetFloatv, glGetMap, glGetDoublev and glEvalCoord

Used in glIsEnabled, glGetIntegerv, glDisable, glMap2, glEnable, glGetBooleanv, glGetFloatv, glGetMap, glGetDoublev and glEvalCoord

Used in glGetIntegerv, glDrawPixels, glPopAttrib, glPixelTransfer, glGetBooleanv, glPushAttrib, glGetFloatv, glGetDoublev, glReadPixels and glCopyPixels

Used in glGetIntegerv, glDrawPixels, glPopAttrib, glPixelTransfer, glGetBooleanv, glPushAttrib, glGetFloatv, glGetDoublev, glReadPixels and glCopyPixels

Used in glMatrixMode, glGetIntegerv, glPopAttrib, glGetBooleanv, glPushAttrib, glGetFloatv and glGetDoublev

Used in glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glGetIntegerv, glGetClipPlane, glClipPlane, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glMap1, glGetIntegerv, glMap2, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glGetIntegerv, glGetLight, glPopAttrib, glGetBooleanv, glPushAttrib, glGetFloatv, glGetDoublev and glLight

Used in glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glPushName, glGetIntegerv, glPopName, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glGetIntegerv, glGetBooleanv, glPixelMap, glGetFloatv and glGetDoublev

Used in glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glGetTexLevelParameter, glGetIntegerv, glCopyTexSubImage2D, glCopyTexImage1D, glTexSubImage2D, glGetBooleanv, glGetTexImage, glGetFloatv, glGetDoublev, glCopyTexImage2D, glTexImage2D, glTexSubImage1D, glTexImage1D and glCopyTexSubImage1D

Used in glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glGetIntegerv, glViewport, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glPushMatrix, glMatrixMode, glGetIntegerv, glGetBooleanv, glTranslate, glGetFloatv, glGetDoublev, glRotate, glScale and glPopMatrix

Used in glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glTexEnv and glGetTexEnv

Used in glAccum

Used in glInterleavedArrays

Used in glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glLogicOp

Used in glGetTexParameter and glTexParameter

Used in glGetTexParameter and glTexParameter

Used in glTexParameter

Used in glAlphaFunc, glDepthFunc and glStencilFunc

Used in glHint

Used in glDrawBuffer

Used in glLogicOp

Used in glIsEnabled, glGetIntegerv, glDisable, glNormalPointer, glPopAttrib, glEnable, glEnableClientState, glGetPointerv, glLogicOp, glGetBooleanv, glPushAttrib, glGetFloatv, glGetDoublev, glNormal and glDisableClientState

Used in glIsEnabled, glGetIntegerv, glDisable, glPopAttrib, glEnable, glGetBooleanv, glPushAttrib, glGetFloatv, glGetDoublev and glNormal

Used in glIsEnabled, glGetIntegerv, glNormalPointer, glEnableClientState, glGetPointerv, glGetBooleanv, glGetFloatv, glGetDoublev and glDisableClientState

Used in glGetPointerv

Used in glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glAlphaFunc, glDepthFunc and glStencilFunc

Used in glGetError

Used in glTexGen

Used in glGetTexGen and glTexGen

Used in glGetIntegerv, glBlendFunc, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glBlendFunc

Used in glBlendFunc

Used in glBlendFunc

Used in glBlendFunc

Used in glLogicOp and glGetMap

Used in glGetMap

Used in glLogicOp

Used in glLogicOp

Used in glGetError, glNewList and glEndList

Used in glPixelStore, glGetIntegerv, glGetBooleanv, glGetTexImage, glGetFloatv and glGetDoublev

Used in glPixelStore, glGetIntegerv, glGetBooleanv, glGetFloatv, glGetDoublev and glReadPixels

Used in glPixelStore, glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glPixelStore, glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glPixelStore, glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glPixelStore, glGetIntegerv, glGetBooleanv, glGetFloatv, glGetDoublev and glReadPixels

Used in glPassThrough and glFeedbackBuffer

Used in glGetIntegerv, glPopAttrib, glGetBooleanv, glPushAttrib, glGetFloatv, glGetDoublev and glHint

Used in glGetIntegerv, glGetPixelMap, glPixelTransfer, glGetBooleanv, glPixelMap, glGetFloatv and glGetDoublev

Used in glGetIntegerv, glPixelTransfer, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glGetIntegerv, glGetPixelMap, glPixelTransfer, glGetBooleanv, glPixelMap, glGetFloatv and glGetDoublev

Used in glGetIntegerv, glPixelTransfer, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glGetIntegerv, glGetPixelMap, glPixelTransfer, glGetBooleanv, glPixelMap, glGetFloatv and glGetDoublev

Used in glGetIntegerv, glPixelTransfer, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glGetIntegerv, glDrawPixels, glGetPixelMap, glPixelTransfer, glGetBooleanv, glPixelMap, glGetFloatv, glGetDoublev, glReadPixels, glTexImage2D and glTexImage1D

Used in glGetIntegerv, glPixelTransfer, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glGetIntegerv, glDrawPixels, glGetPixelMap, glPixelTransfer, glGetBooleanv, glPixelMap, glGetFloatv, glGetDoublev, glReadPixels, glTexImage2D and glTexImage1D

Used in glGetIntegerv, glPixelTransfer, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glGetIntegerv, glDrawPixels, glGetPixelMap, glPixelTransfer, glGetBooleanv, glPixelMap, glGetFloatv, glGetDoublev, glReadPixels, glTexImage2D and glTexImage1D

Used in glGetIntegerv, glPixelTransfer, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glGetIntegerv, glDrawPixels, glGetPixelMap, glPixelTransfer, glGetBooleanv, glPixelMap, glGetFloatv, glGetDoublev, glReadPixels and glCopyPixels

Used in glGetIntegerv, glPixelTransfer, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glGetIntegerv, glDrawPixels, glGetPixelMap, glPixelTransfer, glGetBooleanv, glPixelMap, glGetFloatv, glGetDoublev, glReadPixels, glTexImage2D and glTexImage1D

Used in glGetIntegerv, glPixelTransfer, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glGetIntegerv, glGetPixelMap, glPixelTransfer, glGetBooleanv, glPixelMap, glGetFloatv and glGetDoublev

Used in glGetIntegerv, glPixelTransfer, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glGetIntegerv, glDrawPixels, glGetPixelMap, glPixelTransfer, glGetBooleanv, glPixelMap, glGetFloatv, glGetDoublev, glReadPixels and glCopyPixels

Used in glGetIntegerv, glPixelTransfer, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glPopAttrib and glPushAttrib

Used in glIsEnabled, glGetIntegerv, glEnd, glDrawElements, glDrawArrays, glDisable, glEdgeFlag, glPopAttrib, glEnable, glPolygonMode, glGetBooleanv, glPushAttrib, glGetFloatv, glGetDoublev, glFeedbackBuffer, glBegin, glHint, glEdgeFlagv, glPointSize and glEvalMesh

Used in glEnd, glDrawElements, glDrawArrays, glBegin and glEvalMesh

Used in glPopAttrib and glPushAttrib

Used in glGetIntegerv, glPolygonMode, glGetBooleanv, glGetFloatv, glGetDoublev and glPointSize

Used in glGetIntegerv, glGetBooleanv, glGetFloatv, glGetDoublev and glPointSize

Used in glGetIntegerv, glGetBooleanv, glGetFloatv, glGetDoublev and glPointSize

Used in glIsEnabled, glGetIntegerv, glDisable, glPopAttrib, glEnable, glPolygonMode, glGetBooleanv, glPushAttrib, glGetFloatv, glGetDoublev, glHint and glPointSize

Used in glGetIntegerv, glPopAttrib, glGetBooleanv, glPushAttrib, glGetFloatv, glGetDoublev and glHint

Used in glFeedbackBuffer

Used in glPolygonOffset, glIsEnabled, glGetIntegerv, glEnd, glDrawElements, glDrawArrays, glDisable, glEdgeFlag, glPopAttrib, glEnable, glPolygonMode, glGetBooleanv, glPushAttrib, glGetFloatv, glGetDoublev, glRect, glFeedbackBuffer, glBegin, glHint, glEdgeFlagv and glPolygonStipple

Used in glPopAttrib and glPushAttrib

Used in glGetIntegerv, glEdgeFlag, glPopAttrib, glPolygonMode, glGetBooleanv, glPushAttrib, glGetFloatv, glGetDoublev and glEdgeFlagv

Used in glGetIntegerv, glPopAttrib, glGetBooleanv, glPushAttrib, glGetFloatv and glGetDoublev

Used in glIsEnabled, glGetIntegerv, glDisable, glPopAttrib, glEnable, glGetBooleanv, glPushAttrib, glGetFloatv and glGetDoublev

Used in glIsEnabled, glGetIntegerv, glDisable, glPopAttrib, glEnable, glGetBooleanv, glPushAttrib, glGetFloatv and glGetDoublev

Used in glIsEnabled, glGetIntegerv, glDisable, glPopAttrib, glEnable, glGetBooleanv, glPushAttrib, glGetFloatv and glGetDoublev

Used in glGetIntegerv, glPopAttrib, glGetBooleanv, glPushAttrib, glGetFloatv and glGetDoublev

Used in glIsEnabled, glGetIntegerv, glDisable, glPopAttrib, glEnable, glPolygonMode, glGetBooleanv, glPushAttrib, glGetFloatv, glGetDoublev and glHint

Used in glGetIntegerv, glPopAttrib, glGetBooleanv, glPushAttrib, glGetFloatv, glGetDoublev and glHint

Used in glIsEnabled, glGetIntegerv, glDisable, glPopAttrib, glEnable, glPolygonMode, glGetBooleanv, glPushAttrib, glGetFloatv, glGetDoublev and glPolygonStipple

Used in glPopAttrib and glPushAttrib

Used in glFeedbackBuffer

Used in glGetLight and glLight

Used in glPushMatrix, glMatrixMode, glFrustum, glGetIntegerv, glGetBooleanv, glTranslate, glGetFloatv, glGetDoublev, glRotate, glScale, glOrtho and glPopMatrix

Used in glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glGetTexLevelParameter, glGetIntegerv, glGetBooleanv, glGetFloatv, glGetDoublev, glNewList, glEndList and glTexImage1D

Used in glGetTexLevelParameter, glGetIntegerv, glGetBooleanv, glGetFloatv, glGetDoublev, glNewList, glTexImage2D and glEndList

Used in glGetTexGen, glEnd, glDrawElements, glDrawArrays, glGetLight, glBegin, glLight, glEvalMesh and glTexGen

Used in glGetLight and glLight

Used in glEnd, glDrawElements, glDrawArrays and glBegin

Used in glEnd, glDrawElements, glDrawArrays, glBegin and glEvalMesh

Used in glPixelStore, glTexEnv, glRenderMode, glGetTexGen, glGetIntegerv, glCopyTexSubImage2D, glDrawPixels, glCopyTexImage1D, glTexSubImage2D, glPopAttrib, glPixelTransfer, glGetTexParameter, glGetBooleanv, glGetTexImage, glPushAttrib, glGetFloatv, glAccum, glReadBuffer, glGetDoublev, glReadPixels, glCopyTexImage2D, glTexImage2D, glStencilOp, glGetString, glTexParameter, glTexSubImage1D, glDrawBuffer, glTexImage1D, glCopyTexSubImage1D and glTexGen

Used in glCopyTexImage1D, glCopyTexImage2D, glTexImage2D and glTexImage1D

Used in glGetIntegerv, glCopyTexSubImage2D, glCopyTexImage1D, glPopAttrib, glGetBooleanv, glPushAttrib, glGetFloatv, glGetDoublev, glCopyTexImage2D and glCopyTexSubImage1D

Used in glGetIntegerv, glDrawPixels, glTexSubImage2D, glPopAttrib, glPixelTransfer, glGetBooleanv, glGetTexImage, glPushAttrib, glGetFloatv, glGetDoublev, glReadPixels, glTexImage2D, glTexSubImage1D and glTexImage1D

Used in glGetIntegerv, glPopAttrib, glPixelTransfer, glGetBooleanv, glPushAttrib, glGetFloatv and glGetDoublev

Used in glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glGetIntegerv, glPopAttrib, glPixelTransfer, glGetBooleanv, glPushAttrib, glGetFloatv and glGetDoublev

Used in glRenderMode, glGetIntegerv, glGetBooleanv, glGetFloatv, glGetDoublev and glGetString

Used in glGetString

Used in glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glGetTexParameter and glTexParameter

Used in glTexEnv and glStencilOp

Used in glAccum

Used in glPixelStore, glTexEnv, glGetIntegerv, glDrawPixels, glCopyTexImage1D, glTexSubImage2D, glGetBooleanv, glGetTexImage, glGetFloatv, glGetDoublev, glReadPixels, glCopyTexImage2D, glTexImage2D, glTexSubImage1D and glTexImage1D

Used in glCopyTexImage1D, glCopyTexImage2D, glTexImage2D and glTexImage1D

Used in glCopyTexImage1D, glCopyTexImage2D, glTexImage2D and glTexImage1D

Used in glCopyTexImage1D, glCopyTexImage2D, glTexImage2D and glTexImage1D

Used in glCopyTexImage1D, glCopyTexImage2D, glTexImage2D and glTexImage1D

Used in glCopyTexImage1D, glCopyTexImage2D, glTexImage2D and glTexImage1D

Used in glCopyTexImage1D, glCopyTexImage2D, glTexImage2D and glTexImage1D

Used in glCopyTexImage1D, glCopyTexImage2D, glTexImage2D and glTexImage1D

Used in glCopyTexImage1D, glCopyTexImage2D, glTexImage2D and glTexImage1D

Used in glTexEnv, glGetIntegerv, glDrawPixels, glCopyTexImage1D, glTexSubImage2D, glGetBooleanv, glGetTexImage, glGetFloatv, glGetDoublev, glReadPixels, glCopyTexImage2D, glTexImage2D, glTexSubImage1D and glTexImage1D

Used in glCopyTexImage1D, glCopyTexImage2D, glTexImage2D and glTexImage1D

Used in glCopyTexImage1D, glCopyTexImage2D, glTexImage2D and glTexImage1D

Used in glCopyTexImage1D, glCopyTexImage2D, glTexImage2D and glTexImage1D

Used in glCopyTexImage1D, glCopyTexImage2D, glTexImage2D and glTexImage1D

Used in glCopyTexImage1D, glCopyTexImage2D, glTexImage2D and glTexImage1D

Used in glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glReadBuffer and glDrawBuffer

Used in glPushMatrix, glLoadName, glIsEnabled, glPushName, glRenderMode, glGetTexGen, glGetIntegerv, glColorMaterial, glGetError, glDrawPixels, glBlendFunc, glVertexPointer, glSelectBuffer, glGetLight, glInitNames, glDisable, glColorPointer, glTexSubImage2D, glNormalPointer, glPopAttrib, glEnable, glGetPointerv, glPopName, glLogicOp, glGetBooleanv, glGetTexImage, glPushAttrib, glGetFloatv, glMaterial, glGetDoublev, glCallLists, glShadeModel, glReadPixels, glTexImage2D, glLight, glPopClientAttrib, glStencilOp, glTexCoordPointer, glCopyPixels, glIndexPointer, glPushClientAttrib, glScissor, glTexSubImage1D, glTexImage1D, glStencilFunc, glGetMaterial, glClear, glPopMatrix and glTexGen

Used in glPopAttrib and glPushAttrib

Used in glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glIsEnabled, glGetIntegerv, glDisable, glPopAttrib, glEnable, glGetBooleanv, glPushAttrib, glGetFloatv, glGetDoublev and glScissor

Used in glLoadName, glPushName, glRenderMode, glSelectBuffer, glInitNames, glGetPointerv and glPopName

Used in glGetPointerv

Used in glLogicOp

Used in glGetIntegerv, glPopAttrib, glGetBooleanv, glPushAttrib, glGetFloatv and glGetDoublev

Used in glMaterial and glGetMaterial

Used in glDrawPixels, glVertexPointer, glColorPointer, glTexSubImage2D, glNormalPointer, glGetTexImage, glCallLists, glReadPixels, glTexImage2D, glTexCoordPointer, glIndexPointer, glTexSubImage1D and glTexImage1D

Used in glGetIntegerv, glGetBooleanv, glGetFloatv, glGetDoublev and glShadeModel

Used in glColorMaterial, glGetLight, glMaterial, glLight and glGetMaterial

Used in glTexGen

Used in glGetLight and glLight

Used in glGetLight and glLight

Used in glGetLight and glLight

Used in glBlendFunc

Used in glBlendFunc

Used in glBlendFunc

Used in glPushMatrix, glPushName, glGetError, glPopAttrib, glPopName, glPushAttrib, glPopClientAttrib, glPushClientAttrib and glPopMatrix

Used in glPushMatrix, glPushName, glGetError, glPopAttrib, glPopName, glPushAttrib, glPopClientAttrib, glPushClientAttrib and glPopMatrix

Used in glIsEnabled, glGetIntegerv, glDrawPixels, glDisable, glPopAttrib, glEnable, glGetBooleanv, glGetTexImage, glPushAttrib, glGetFloatv, glGetDoublev, glReadPixels, glTexImage2D, glStencilOp, glCopyPixels, glTexImage1D, glStencilFunc and glClear

Used in glGetIntegerv, glGetBooleanv, glGetFloatv, glGetDoublev and glStencilOp

Used in glPopAttrib, glPushAttrib and glClear

Used in glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glDrawPixels, glGetTexImage, glReadPixels, glTexImage2D and glTexImage1D

Used in glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glIsEnabled, glGetIntegerv, glDisable, glPopAttrib, glEnable, glGetBooleanv, glPushAttrib, glGetFloatv, glGetDoublev, glStencilOp and glStencilFunc

Used in glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glPushMatrix, glMatrixMode, glIsEnabled, glGetTexLevelParameter, glTexEnv, glIsList, glAreTexturesResident, glGetTexGen, glGetIntegerv, glEnd, glIsTexture, glDrawElements, glDrawArrays, glCopyTexSubImage2D, glBindTexture, glDisable, glCopyTexImage1D, glTexSubImage2D, glEdgeFlag, glPopAttrib, glEnable, glColorMask, glEnableClientState, glGetPointerv, glGetTexParameter, glGetBooleanv, glGetTexImage, glPushAttrib, glGetFloatv, glGetDoublev, glInterleavedArrays, glReadPixels, glCopyTexImage2D, glTexImage2D, glGetTexEnv, glBegin, glTexCoordPointer, glTexParameter, glDisableClientState, glTexSubImage1D, glEdgeFlagv, glTexImage1D, glCopyTexSubImage1D, glPopMatrix and glTexGen

Used in glInterleavedArrays

Used in glInterleavedArrays

Used in glInterleavedArrays

Used in glInterleavedArrays

Used in glInterleavedArrays

Used in glInterleavedArrays

Used in glInterleavedArrays

Used in glPushMatrix, glMatrixMode, glIsEnabled, glGetTexLevelParameter, glTexEnv, glAreTexturesResident, glGetTexGen, glGetIntegerv, glCopyTexSubImage2D, glBindTexture, glDisable, glCopyTexImage1D, glTexSubImage2D, glPopAttrib, glEnable, glEnableClientState, glGetPointerv, glGetTexParameter, glGetBooleanv, glGetTexImage, glPushAttrib, glGetFloatv, glGetDoublev, glCopyTexImage2D, glTexImage2D, glGetTexEnv, glTexCoordPointer, glTexParameter, glDisableClientState, glTexSubImage1D, glTexImage1D, glCopyTexSubImage1D, glPopMatrix and glTexGen

Used in glIsEnabled, glGetTexLevelParameter, glGetIntegerv, glBindTexture, glDisable, glCopyTexImage1D, glPopAttrib, glEnable, glGetTexParameter, glGetBooleanv, glGetTexImage, glPushAttrib, glGetFloatv, glGetDoublev, glTexParameter, glTexSubImage1D, glTexImage1D and glCopyTexSubImage1D

Used in glIsEnabled, glGetTexLevelParameter, glGetIntegerv, glCopyTexSubImage2D, glBindTexture, glDisable, glTexSubImage2D, glPopAttrib, glEnable, glGetTexParameter, glGetBooleanv, glGetTexImage, glPushAttrib, glGetFloatv, glGetDoublev, glCopyTexImage2D, glTexImage2D and glTexParameter

Used in glGetTexLevelParameter

Used in glPopAttrib and glPushAttrib

Used in glGetTexLevelParameter

Used in glGetTexLevelParameter, glCopyTexSubImage2D, glGetTexParameter, glTexParameter, glTexSubImage1D and glCopyTexSubImage1D

Used in glGetTexParameter and glTexParameter

Used in glIsEnabled, glGetIntegerv, glEnableClientState, glGetPointerv, glGetBooleanv, glGetFloatv, glGetDoublev, glTexCoordPointer and glDisableClientState

Used in glGetPointerv

Used in glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glTexEnv and glGetTexEnv

Used in glTexEnv and glGetTexEnv

Used in glTexEnv and glGetTexEnv

Used in glGetTexGen, glPopAttrib, glPushAttrib and glTexGen

Used in glIsEnabled, glGetIntegerv, glDisable, glEnable, glGetBooleanv, glGetFloatv, glGetDoublev and glTexGen

Used in glIsEnabled, glGetIntegerv, glDisable, glEnable, glGetBooleanv, glGetFloatv, glGetDoublev and glTexGen

Used in glIsEnabled, glGetIntegerv, glDisable, glEnable, glGetBooleanv, glGetFloatv, glGetDoublev and glTexGen

Used in glIsEnabled, glGetIntegerv, glDisable, glEnable, glGetBooleanv, glGetFloatv, glGetDoublev and glTexGen

Used in glGetTexLevelParameter

Used in glGetTexLevelParameter, glCopyTexSubImage2D and glTexSubImage2D

Used in glGetTexLevelParameter

Used in glGetTexLevelParameter

Used in glGetTexLevelParameter

Used in glGetTexParameter and glTexParameter

Used in glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glGetTexParameter and glTexParameter

Used in glGetTexParameter and glTexParameter

Used in glGetTexLevelParameter

Used in glAreTexturesResident and glGetTexParameter

Used in glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glGetTexLevelParameter, glCopyTexSubImage2D, glTexSubImage2D, glTexSubImage1D and glCopyTexSubImage1D

Used in glGetTexParameter and glTexParameter

Used in glGetTexParameter and glTexParameter

Used in glPopAttrib and glPushAttrib

Used in glEnd, glDrawElements, glDrawArrays and glBegin

Used in glEnd, glDrawElements, glDrawArrays and glBegin

Used in glEnd, glDrawElements, glDrawArrays and glBegin

Used in glIsEnabled, glIsList, glAreTexturesResident, glGetIntegerv, glIsTexture, glDisable, glEdgeFlag, glEnable, glColorMask, glGetTexParameter, glGetBooleanv, glGetFloatv, glGetDoublev, glReadPixels and glEdgeFlagv

Used in glPixelStore, glGetIntegerv, glDrawPixels, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glPixelStore, glGetIntegerv, glDrawPixels, glGetBooleanv, glGetFloatv, glGetDoublev, glTexImage2D, glTexImage1D and glPolygonStipple

Used in glPixelStore, glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glPixelStore, glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glPixelStore, glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glPixelStore, glGetIntegerv, glGetBooleanv, glGetFloatv, glGetDoublev and glPolygonStipple

Used in glDrawElements, glDrawPixels, glColorPointer, glTexSubImage2D, glGetTexImage, glCallLists, glReadPixels, glTexImage2D, glIndexPointer, glTexSubImage1D and glTexImage1D

Used in glDrawElements, glDrawPixels, glColorPointer, glTexSubImage2D, glGetTexImage, glCallLists, glReadPixels, glTexImage2D, glTexSubImage1D and glTexImage1D

Used in glDrawElements, glDrawPixels, glColorPointer, glTexSubImage2D, glGetTexImage, glCallLists, glReadPixels, glTexImage2D, glTexSubImage1D and glTexImage1D

Used in glInterleavedArrays

Used in glInterleavedArrays

Used in glGetString

Used in glGetString

Used in glIsEnabled, glArrayElement, glGetIntegerv, glDrawElements, glDrawArrays, glVertexPointer, glEnableClientState, glGetPointerv, glGetBooleanv, glGetFloatv, glGetDoublev and glDisableClientState

Used in glGetPointerv

Used in glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glGetIntegerv, glGetBooleanv, glGetFloatv and glGetDoublev

Used in glGetIntegerv, glPopAttrib, glGetBooleanv, glPushAttrib, glGetFloatv and glGetDoublev

Used in glPopAttrib and glPushAttrib

Used in glLogicOp

Used in glGetIntegerv, glBlendFunc, glGetBooleanv, glGetFloatv, glGetDoublev and glStencilOp

Used in glGetIntegerv, glDrawPixels, glPopAttrib, glGetBooleanv, glPushAttrib, glGetFloatv, glGetDoublev and glCopyPixels

Used in glGetIntegerv, glDrawPixels, glPopAttrib, glGetBooleanv, glPushAttrib, glGetFloatv, glGetDoublev and glCopyPixels

The Bz2 module contains functions to compress and uncompress strings using the same algorithm as the program bzip2. Compressing and decompressing can be done in streaming mode feeding the compress and decompress objects with arbitrarily large pieces of data. The Bz2 module consists of three classes; Bz2.Deflate,Bz2.Inflate. and Bz2.File Bz2.Deflate is used to compress data and Bz2.Inflate is used to uncompress data. (Think "inflatable boat") Bz2.File is used to handle Bzip2 files.

Note that this module is only available if libbzip2 was available when Pike was compiled.

Note that although the functions in Inflate and Deflate use the same algorithm as bzip2, they do not use the exact same format, so you can not directly zip files or unzip zip-files using those functions. That is why there exists a third class for files.

Bz2.Deflate is a builtin program written in C. It interfaces the packing routines in the bzlib library.

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

Bz2.Inflate()

If given, compression should be a number from 1 to 9 indicating the block size used when doing compression. The actual block size will be a 100000 times this number. Low numbers are considered 'fast', higher numbers are considered 'slow' but give better packing. The parameter is set to 9 if it is omitted.

This function can also be used to re-initialize a Bz2.Deflate object so it can be re-used.

1 9

This function feeds the data to the internal buffers of the Deflate object. All data is buffered until a read or a finish is done.

Bz2.Deflate->read() Bz2.Deflate->finish()

This function feeds the data to the internal buffers of the Deflate object. Then it compresses all buffered data and returns the compressed data as a string

Bz2.Deflate->feed() Bz2.Deflate->finish()

This method feeds the data to the internal buffers of the Deflate object. Then it compresses all buffered data adds a end of data marker ot it, returns the compressed data as a string, and reinitializes the deflate object.

Bz2.Deflate->feed() Bz2.Deflate->read()

This function performs bzip2 style compression on a string data and returns the packed data. Streaming can be done by calling this function several times and concatenating the returned data.

The optional argument flush_mode should be one of the following:

Bz2.BZ_RUN

Runs Bz2.Deflate->feed()

Bz2.BZ_FLUSH

Runs Bz2.Deflate->read()

Bz2.BZ_FINISH

Runs Bz2.Deflate->finish()

Bz2.Inflate->inflate()

0 2

Bz2.Inflate is a builtin program written in C. It interfaces the unpacking routines in the libz library.

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

Deflate

This function performs bzip2 style decompression. It can do decompression with arbitrarily large pieces of data. When fed with data, it decompresses as much as it can and buffers the rest.

while(..){ foo = compressed_data[i..i+9]; uncompressed_concatenated_data += inflate_object->inflate(foo); i = i+10; }

Bz2.Deflate->deflate()

Low-level implementation of read/write support for Bzip2 files

closes the file

0
1

Creates a Bz2.File object

Opens a file for reading.

The name of the file to be opened

0
1

Opens a file for writing.

The name of the file to be opened

0
1

Opens a file for I/O.

The name of the file to be opened

Mode for the file operations. Can be either "r" (read) or "w". Read is default.

0
1

Writes the data to the file.

the number of bytes written to the file.

Reads len (uncompressed) bytes from the file. If len is omitted the whole file is read. If read is unsuccessful, 0 is returned.

1 if EOF has been reached, 0 otherwise

0
1

This is an interface that all Throttlers must implement. It's not an actual class in this module.

This function is called when the Shuffle wants to send some data to a client.

When data can be sent, the callback function should be called with the amount of data that can be sent as the argument.

Shuffle
``

This function will be called by the Shuffle object to report that some data assigned to it by this throttler was unusued, and can be given to another Shuffle object instead.

Shuffle

This class contains the state for one ongoing data shuffling operation. To create a Shuffle instance, use the Shuffler()->shuffle method.

The Shuffler that owns this Shuffle object

Shuffler

The Throttler that is associated with this Shuffle object, if any.

Throttler

Calling this function overrides the Shuffler global throttler.

Throttler

Returns the amount of data that has been sent so far.

Returns the current state of the shuffler. This is one of the following: INITIAL, RUNNING, PAUSED, DONE, WRITE_ERROR, READ_ERROR and USER_ABORT

Sets the done callback. This function will be called when all sources have been processed, or if an error occurs.

`Shuffle`

Sets the extra argument sent to Throttler()->request() and Throttler()->give_back.

Start sending data from the sources.

Temporarily pause all data transmission

Stop all data transmission, and then call the done callback

Add a new source to the list of data sources. The data from the sources will be sent in order.

If start and length are not specified, the whole source will be sent, if start but not length is specified, the whole source, excluding the first start bytes will be sent.

Currently supported sources

An ordinary 8-bit wide pike string.

An initialized instance of the System.Memory class.

Stdio.File instance pointing to a normal file.

Stdio.File instance pointing to a stream of some kind (network socket, named pipe, stdin etc).

Stdio.File lookalike with read callback support (set_read_callback and set_close_callback).

A data shuffler. An instance of this class handles a list of Shuffle objects. Each Shuffle object can send data from one or more sources to a destination in the background.

Set the backend that will be used by all Shuffle objects created from this shuffler.

Pike.Backend

Set the throttler that will be used in all Shuffle objects created from this shuffler, unless overridden in the Shuffle objects.

Throttler

Pause all Shuffle objects associated with this Shuffler

Unpause all Shuffle objects associated with this Shuffler

Create a new Shuffle object.

Stdio.File
Shuffle

This is a glue against the librsvg-2.0 library, providing Scalable Vector Graphics (SVG) for Pike.

Data is the SVG data, the charset must be unicode.

If options is specified, it contains one or more of the following options

- xsize

If specified, gives the exact width in pixels the image will have. If only one of xsize or ysize is specified, the other is calculated.

- ysize

If specified, gives the exact height in pixels the image will have. If only one of xsize or ysize is specified, the other is calculated.

- scale

If specified, gives the scale the image will be drawn with. A scale of 2.0 will give an image that is twice as large.

The result is a mapping with the following members:

- type

Always image/svg

- xsize

The width of the image, in pixels

- ysize

The height of the image, in pixels

Data is the SVG data, the charset must be unicode.

If options is specified, it contains one or more of the following options

- xsize

If specified, gives the exact width in pixels the image will have. If only one of xsize or ysize is specified, the other is calculated.

- ysize

If specified, gives the exact height in pixels the image will have. If only one of xsize or ysize is specified, the other is calculated.

- scale

If specified, gives the scale the image will be drawn with. A scale of 2.0 will give an image that is twice as large.

The result is a mapping with the following members:

- type

Always image/svg

- xsize

The width of the image, in pixels

- ysize

The height of the image, in pixels

- Image.Image image

The image data

- Image.Image alpha

The alpha channel data

Data is the SVG data, the charset must be unicode.

If options is specified, it contains one or more of the following options

- xsize

If specified, gives the exact width in pixels the image will have. If only one of xsize or ysize is specified, the other is calculated.

- ysize

If specified, gives the exact height in pixels the image will have. If only one of xsize or ysize is specified, the other is calculated.

- scale

If specified, gives the scale the image will be drawn with. A scale of 2.0 will give an image that is twice as large.

The result is an array of Image.Layer objects. For now there is always at most one member in the array.

Image.Layer

Data is the SVG data, the charset must be unicode.

If options is specified, it contains one or more of the following options

- xsize

If specified, gives the exact width in pixels the image will have. If only one of xsize or ysize is specified, the other is calculated.

- ysize

If specified, gives the exact height in pixels the image will have. If only one of xsize or ysize is specified, the other is calculated.

- scale

If specified, gives the scale the image will be drawn with. A scale of 2.0 will give an image that is twice as large.

Returns the image member of the mapping returned by _decode

Image.Image

Pike glue for the FreeType2 library, http://www.freetype.org/

A FreeType font face. We recommend using the more generic font handling interfaces in Image.Fonts instead.

Image.Image
Face
- "family"

The font family, or the string "unknown"

- "style_name"

The name of the font style, or "unknown"

- "face_flags"
- "style_flags"

The sum of all face/style flags respectively.

The path of the font file to use

Decodes a TIFF image.

Throws upon error in data.

Decodes a TIFF image to a mapping with at least the members image and alpha.

- Image.Image "image"

The actual image.

- Image.Image "alpha"

Image alpha channel.

- "xres"
- "yres"

Resolution

- "unit"
"unitless"
"pixels/inch"
"pixels/cm"
- "xdpy"
- "ydpy"

Resolution

- "xposition"
- "yposition"
- "photometric"

Type of photometric. Can be "unknown".

- "extra_samples"

Array elements are either integers or any of

"unspecified"
"assoc-alpha"
"unassoc-alpha"
- "threshholding"
- "halftone_hints"

Array is always two elements.

- "artist"
- "datetime"
- "hostcomputer"
- "software"
- "name"
- "comment"
- "make"
- "model"
- "page_name"
- "page_number"

Array is always two elements.

- "colormap"

Array of array of RGB values.

- "whitepoint"

Array is always two elements.

- "primary_chromaticities"

Array is always six elements.

- "reference_black_white"

Array of array of two elements.

Throws upon error in data.

Encode an image object into a TIFF file. [encode] and _encode are identical.

The options argument may be a mapping containing zero or more encoding options. See _decode.

Image.TIFF.encode(img, ([ "compression":Image.TIFF.COMPRESSION_LZW, "name":"an image name", "comment":"an image comment", "alpha":An alpha channel, "dpy":Dots per inch (as a float), "xdpy":Horizontal dots per inch (as a float), "ydpy":Vertical dots per inch (as a float), ]));

This module adds TTF (Truetype font) capability to the Image module.

This module needs the libttf "Freetype" library

Makes a new TTF Face object.

The filename of the TTF font or the TTC font collection.

    advanced options:
        "face":int
            If opening a font collection,  '.TTC',
            this is used to get other fonts than the first.

0 if failed.

This represents instances of TTF Faces.

This flushes all cached information. Might be used to save memory - the face information is read back from disk upon need.

the object being called

Gives back the names or the complete name-list of this face.

The result from names() is a mapping, which has any or all of these indices:

    "copyright":   ("Copyright the Foo Corporation...bla bla")
    "family":      ("My Little Font")
    "style":       ("Bold")
    "full":        ("Foo: My Little Font: 1998")
    "expose":      ("My Little Font Bold")
    "version":     ("June 1, 1998; 1.00, ...")
    "postscript":  ("MyLittleFont-Bold")
    "trademark":   ("MyLittleFont is a registered...bla bla")

This is extracted from the information from _names(), and fit into pike-strings using unicode or iso-8859-1, if possible.

The result from _names() is a matrix, on this form:

         ({ ({ int platform, encoding, language, id, string name }),
            ({ int platform, encoding, language, id, string name }),
            ...
         })

the name as a mapping to string or the names as a matrix

To use the values from _names(), check the TrueType standard documentation.

This gives back a structure of the face's properties. Most of this stuff is information you can skip.

The most interesting item to look at may be ->num_Faces, which describes the number of faces in a .TTC font collection.

a mapping of a lot of properties

This instantiates the face for normal usage - to convert font data to images.

a Image.TTF.FaceInstance object.

This is the instance of a face, with geometrics, encodings and stuff.

creates a new Instance from a face.

This module uses libjpeg, a software from Independent JPEG Group.

Encodes an image object with JPEG compression. The image may also be a string containing a raw JPEG image. In the The options argument may be a mapping containing zero or more encoding options:

- 0 100 "quality"

Set quality of result. Default is 75.

- 0 1 "optimize"

Optimize Huffman table. Default is on (1) for images smaller than 50kpixels.

- 0 1 "progressive"

Make a progressive JPEG. Default is off (0).

- 0 1 "grayscale"

Make a grayscale JPEG instead of color (YCbCr).

- 1 100 "smooth"

Smooth input. Value is strength.

- "method"

DCT method to use. Any of IFAST, ISLOW, FLOAT, DEFAULT or FASTEST. DEFAULT and FASTEST is from the jpeg library, probably ISLOW and IFAST respectively.

- 0 2 "density_unit"

The unit used for x_density and y_density.

0

No unit

1

dpi

2

dpcm

- "x_density"
- "y_density"

Density of image.

- "comment"

Comment to be written in the JPEG file. Must not be a wide string.

- 0 1 "baseline"

Force baseline output. Useful for quality<25. Default is off for quality<25.

- "quant_tables"

Tune quantisation tables manually.

- "marker"

Application and comment markers; the integer should be one of Marker.COM, Marker.APP0, Marker.APP1, ..., Marker.APP15. The string is up to the application; most notable are Adobe and Photoshop markers.

- "transform"

Lossless image transformation. Has only effect when supplying a JPEG file as indata.

FLIP_H

Flip image horizontally

FLIP_V

Flip image vertically

ROT_90

Rotate image 90 degrees clockwise

ROT_180

Rotate image 180 degrees clockwise

ROT_270

Rotate image 270 degrees clockwise

TRANSPOSE

Transpose image

TRANSVERSE

Transverse image

Please read some about JPEG files. A quality setting of 100 does not mean the result is lossless.

Decodes a JPEG image. The simple decode function simply gives the image object, the other functions gives a mapping of information (see below).

The options argument may be a mapping containing zero or more decoding options:

- 0 1 "block_smoothing"

Do interblock smoothing. Default is on (1).

- 0 1 "fancy_upsampling"

Do fancy upsampling of chroma components. Default is on (1).

- "method"

DCT method to use. Any of IFAST, ISLOW, FLOAT, DEFAULT or FASTEST. DEFAULT and FASTEST is from the jpeg library, probably ISLOW and IFAST respective.

- 1 "scale_num"
- 1 "scale_denom"

Rescale the image when read from JPEG data. My (Mirar) version (6a) of jpeglib can only handle 1/1, 1/2, 1/4 and 1/8.

_decode and decode_header gives a mapping as result, with this content:

- "comment"

Comment marker of JPEG file, if present.

- "xsize"
- "ysize"

Size of image

- "xdpi"
- "ydpi"

Image dpi, if known.

- "type"

File type information as MIME type. Always "image/jpeg".

- "num_compontents"

Number of channels in JPEG image.

- "color_space"

Color space of JPEG image. Any of "GRAYSCALE", "RGB", "YUV", "CMYK", "YCCK" or "UNKNOWN".

- 0 2 "density_unit"

The unit used for x_density and y_density.

0

No unit

1

dpi

2

dpcm

- "x_density"
- "y_density"

Density of image.

- 0 1 "adobe_marker"

If the file has an Adobe marker.

- "quant_tables"

JPEG quant tables.

- 0 100 "quality"

JPEG quality guess.

Document this function

This submodule keep the GIF encode/decode capabilities of the Image module.

GIF is a common image storage format, usable for a limited color palette - a GIF image can only contain as most 256 colors - and animations.

Simple encoding: encode, encode_trans

Advanced stuff: render_block, header_block, end_block, netscape_loop_block

Very advanced stuff: _render_block, _gce_block

Image, Image.Image, Image.Colortable

Decodes GIF data and creates an image object.

the decoded image as an image object

This function may throw errors upon illegal GIF data. This function uses __decode, _decode, Image.Image->paste and Image.Image->paste_alpha internally.

encode

Decodes GIF data and creates an array of layers or the resulting layer.

The resulting layer may not have the same size as the gif image, but the resulting bounding box of all render chunks in the gif file. The offset should be correct, though.

encode, decode_map

Returns a mapping similar to other decoders _decode function.

        "image":the image
        "alpha":the alpha channel

        "xsize":int
        "ysize":int
            size of image
        "type":"image/gif"
            file type information as MIME type

The weird name of this function (not _decode as the other decoders) is because gif was the first decoder and was written before the API was finally defined. Sorry about that. /Mirar

Create a complete GIF file.

The latter (encode_trans) functions add transparency capabilities.

Example:

    img=Image.Image([...]);
    [...] // make your very-nice image
    write(Image.GIF.encode(img)); // write it as GIF on stdout

The image which to encode.

These arguments decides what colors the image should be encoded with. If a number is given, a colortable with be created with (at most) that amount of colors. Default is '256' (GIF maximum amount of colors).

Alpha channel image (defining what is transparent); black color indicates transparency. GIF has only transparent or nontransparent (no real alpha channel). You can always dither a transparency channel: Image.Colortable(my_alpha, ({({0,0,0}),({255,255,255})}))
->full()
->floyd_steinberg()
->map(my_alpha)

Use this (or the color closest to this) color as transparent pixels.

Encode transparent pixels (given by alpha channel image) to have this color. This option is for making GIFs for the decoders that doesn't support transparency.

Use this color no in the colortable as transparent color.

For advanced users:

    Image.GIF.encode_trans(img,colortable,alpha);

is equivalent of using

    Image.GIF.header_block(img->xsize(),img->ysize(),colortable)+
    Image.GIF.render_block(img,colortable,0,0,0,alpha)+
    Image.GIF.end_block();

and is actually implemented that way.

This function gives back a GIF end (trailer) block.

the end block as a string.

This is in the advanced sector of the GIF support; please read some about how GIFs are packed.

The result of this function is always ";" or "\x3b", but I recommend using this function anyway for code clearity.

header_block, end_block

This function gives back a GIF header block.

Giving a colortable to this function includes a global palette in the header block.

Size of drawing area. Usually same size as in the first (or only) render block(s).

This color in the palette is the background color. Background is visible if the following render block(s) doesn't fill the drawing area or are transparent. Most decoders doesn't use this value, though.

If set, write 'GIF87a' instead of 'GIF89a' (default 0 == 89a).

Aspect ratio of pixels, ranging from 4:1 to 1:4 in increments of 1/16th. Ignored by most decoders. If any of aspectx or aspecty is zero, aspectratio information is skipped.

Add this color as the transparent color. This is the color used as transparency color in case of alpha-channel given as image object. This increases (!) the number of colors by one.

the created header block as a string

This is in the advanced sector of the GIF support; please read some about how GIFs are packed.

This GIF encoder doesn't support different size of colors in global palette and color resolution.

header_block, end_block

Creates a application-specific extention block; this block makes netscape and compatible browsers loop the animation a certain amount of times.

Number of loops. Max and default is 65535.

This function gives a image block for placement in a GIF file, with or without transparency. The some options actually gives two blocks, the first with graphic control extensions for such things as delay or transparency.

Example:

    img1=Image.Image([...]);
    img2=Image.Image([...]);
    [...] // make your very-nice images
    nct=Image.Colortable([...]); // make a nice colortable
    write(Image.GIF.header_block(xsize,ysize,nct)); // write a GIF header
    write(Image.GIF.render_block(img1,nct,0,0,0,10)); // write a render block
    write(Image.GIF.render_block(img2,nct,0,0,0,10)); // write a render block
    [...]
    write(Image.GIF.end_block()); // write end block
    // voila! A GIF animation on stdout.

image_gif.c0.gifThe above animation is thus created:

    object nct=Image.colortable(lena,32,({({0,0,0})}));
    string s=GIF.header_block(lena->xsize(),lena->ysize(),nct);
    foreach ( ({lena->xsize(),
                (int)(lena->xsize()*0.75),
                (int)(lena->xsize()*0.5),
                (int)(lena->xsize()*0.25),
                (int)(1),
                (int)(lena->xsize()*0.25),
                (int)(lena->xsize()*0.5),
                (int)(lena->xsize()*0.75)}),int xsize)
    {
       object o=lena->scale(xsize,lena->ysize());
       object p=lena->clear(0,0,0);
       p->paste(o,(lena->xsize()-o->xsize())/2,0);
       s+=Image.GIF.render_block(p,nct,0,0,0,25);
    }
    s+=Image.GIF.netscape_loop_block(200);
    s+=Image.GIF.end_block();
    write(s);

The image.

Colortable with colors to use and to write as palette.

Position of this image.

If set, writes a local palette.

Alpha channel image; black is transparent.

Color of transparent pixels. Not all decoders understands transparency. This is ignored if localpalette isn't set.

View this image for this many centiseconds. Default is zero.

Index of the transparent color in the colortable. -1 indicates no transparency.

If set: wait the delay or until user input. If delay is zero, wait indefinitely for user input. May sound the bell upon decoding. Default is non-set.

Disposal method number;

0
  No disposal specified. The decoder is not required to take any action. (default)
1
  Do not dispose. The graphic is to be left in place.
2
  Restore to background color. The area used by the graphic must be restored to the background color.
3
  Restore to previous. The decoder is required to restore the area overwritten by the graphic with what was there prior to rendering the graphic.
4-7
  To be defined.

This is in the advanced sector of the GIF support; please read some about how GIFs are packed.

The user_input and disposal method are unsupported in most decoders.

encode, header_block, end_block

Decodes a GIF image structure down to chunks, and also decode the images in the render chunks.

    ({int xsize,int ysize,    // 0: size of image drawing area
      void|object colortable, // 2: opt. global colortable
      ({ int aspx, int aspy,  // 3 0: aspect ratio or 0, 0 if not set
         int background }),   //   2: index of background color

followed by any number these blocks in any order (gce chunks are decoded and incorporated in the render chunks):

      ({ GIF.RENDER,          //   0: block identifier
        int x, int y,         //   1: position of render
        object image,         //   3: render image
        void|object alpha,    //   4: 0 or render alpha channel
        object colortable,    //   5: colortable (may be same as global)

        int interlace,        //   6: interlace flag
        int trans_index,      //   7: 0 or transparent color index
        int delay,            //   8: 0 or delay in centiseconds
        int user_input,       //   9: user input flag
        int disposal})        //  10: disposal method number (0..7)

      ({ GIF.EXTENSION,       //   0: block identifier
         int extension,       //   1: extension number
         string data })       //   2: extension data

and possibly ended with one of these:

      ({ GIF.ERROR_PREMATURE_EOD })   // premature end-of-data

      ({ GIF.ERROR_TOO_MUCH_DATA,     // data following end marker
         string data })               // (rest of file)

      ({ GIF.ERROR_UNKNOWN_DATA,      // unknown data
         string data })               // (rest of file)

The decode method uses this data in a way similar to this program:

    import Image;

    object my_decode_gif(string data)
    {
       array a=GIF._decode(data);
       object img=image(a[0],a[1]);
       foreach (a[4..],array b)
          if (b[0]==GIF.RENDER)
             if (b[4]) img->paste_alpha(b[3],b[4],b[1],b[2]);
             else img->paste(b[3],b[1],b[2]);
       return img;
    }

GIF data (with header and all)

GIF data as from __decode

the above array

May throw errors if the GIF header is incomplete or illegal.

This is in the very advanced sector of the GIF support; please read about how GIF files works.

Encodes GIF data; reverses _decode.

data as returned from _encode

Some given values in the array are ignored. This function does not give the _exact_ data back!

This function gives back a Graphic Control Extension block. A GCE block has the scope of the following render block.

The following image has transparency, marked with this index.

View the following rendering for this many centiseconds (0..65535).

Wait the delay or until user input. If delay is zero, wait indefinitely for user input. May sound the bell upon decoding.

Disposal method number;

0
  No disposal specified. The decoder is not required to take any action.
1
  Do not dispose. The graphic is to be left in place.
2
  Restore to background color. The area used by the graphic must be restored to the background color.
3
  Restore to previous. The decoder is required to restore the area overwritten by the graphic with what was there prior to rendering the graphic.
4-7
  To be defined.

This is in the very advanced sector of the GIF support; please read about how GIF files works.

Most decoders just ignore some or all of these parameters.

_render_block, render_block

0

Advanced (!) method for writing renderblocks for placement in a GIF file. This method only applies LZW encoding on the indices and makes the correct headers.

Position of this image.

Size of the image. Length if the indices string must be xsize*ysize.

Bits per pixels in the indices. Valid range 1..8.

The image indices as an 8bit indices.

Colortable with colors to write as palette. If this argument is zero, no local colortable is written. Colortable string len must be 1<<bpp.

Interlace index data and set interlace bit. The given string should _not_ be pre-interlaced.

This is in the very advanced sector of the GIF support; please read about how GIF files works.

encode, _encode, header_block, end_block

Decodes a GIF image structure down to chunks and

    ({int xsize,int ysize,      // 0: size of image drawing area
      int numcol,               // 2: suggested number of colors
      void|string colortable,   // 3: opt. global colortable
      ({ int aspx, int aspy,    // 4,0: aspect ratio or 0, 0 if not set
         int background }),     //   1: index of background color

followed by any number these blocks in any order:

      ({ GIF.EXTENSION,         //   0: block identifier
         int extension,         //   1: extension number
         string data })         //   2: extension data

      ({ GIF.RENDER,            //   0: block identifier
         int x, int y,          //   1: position of render
         int xsize, int ysize,  //   3: size of render
         int interlace,         //   5: interlace flag
         void|string colortbl,  //   6: opt. local colortable
         int lzwsize,           //   7: lzw code size
         string lzwdata })      //   8: packed lzw data

and possibly ended with one of these:

      ({ GIF.ERROR_PREMATURE_EOD })   // premature end-of-data

      ({ GIF.ERROR_TOO_MUCH_DATA,     // data following end marker
         string data })               // (rest of file)

      ({ GIF.ERROR_UNKNOWN_DATA,      // unknown data
         string data })               // (rest of file)

the above array

May throw errors if the GIF header is incomplete or illegal.

This is in the very advanced sector of the GIF support; please read about how GIF files works.

This module uses libgmp.

Decodes an X-Face image.

The options argument may be a mapping containing zero options.

Decodes an X-Face image header.

        "xsize":int
        "ysize":int
            size of image
        "type":"image/x-xface"
            file type information

The options argument may be a mapping containing zero options.

There aint no such thing as a X-Face image header. This stuff tells the characteristics of an X-Face image.

Encodes an X-Face image.

The img argument must be an image of the dimensions 48 by 48 pixels. All non-black pixels will be considered white.

The options argument may be a mapping containing zero options.

Decodes images from the Atari image editor Neochrome.

Low level decoding of the NEO file contents in data.

- Image.Image "image"

The decoded bitmap

- Image.Image "images"

Coler cycled images.

- "filename"

The filename stored into the file.

- 0 15 "right_limit"
- 0 15 "left_limit"

The palette color range to be color cycled.

- 0 255 "speed"

The animation speed, expressed as the number of VBLs per animation frame.

- "direction"

Color cycling direction. Can be either "left" or "right".

- 0 255 "palette"

The palette to be used for color cycling.

Decodes the image data into an Image.Image object.

Image.Image

Decodes a XCF image to a single image object.

Throws upon error in data, you will loose quite a lot of information by doing this. See Image.XCF._decode and Image.XCF.__decode

Decodes a XCF image to an array of Image.Layer objects

The layer object have the following extra variables (to be queried using get_misc_value):

image_xres, image_yres, image_colormap, image_guides, image_parasites, name, parasites, visible, active

Takes the same argument mapping as _decode,

Decodes a XCF image to a mapping, with at least an 'image' and possibly an 'alpha' object. Data is either a XCF image, or a XCF.GimpImage object structure (as received from __decode)

     Supported options
     ([
        "background":({r,g,b})||Image.Color object
        "draw_all_layers":1,
             Draw invisible layers as well

        "draw_guides":1,
             Draw the guides

        "draw_selection":1,
              Mark the selection using an overlay

        "ignore_unknown_layer_modes":1
              Do not asume 'Normal' for unknown layer modes.

        "mark_layers":1,
             Draw an outline around all (drawn) layers

        "mark_layer_names":Image.Font object,
             Write the name of all layers using the font object,

        "mark_active_layer":1,
             Draw an outline around the active layer
      ])

Throws upon error in data. For more information, see Image.XCF.__decode

Decodes a XCF image to a Image.XCF.GimpImage object.

    Returned structure reference

       !class GimpImage
       {
         int width;
         int height;
         int compression;
         int type;
         int tattoo_state;
         float xres = 72.0;
         float yres = 72.0;
         int res_unit;
         Image.Colortable colormap;
         Image.Colortable meta_colormap;
         array(Layer) layers = ({});
         array(Channel) channels = ({});
         array(Guide) guides = ({});
         array(Parasite) parasites = ({});
         array(Path) paths = ({});

         Layer active_layer;
         Channel active_channel;
         Channel selection;
       }

       !class Layer
       {
         string name;
         int opacity;
         int type;
         int mode;
         int tattoo;
         mapping flags = ([]);
         int width, height;
         int xoffset, yoffset;
         array (Parasite) parasites;
         LayerMask mask;
         Hierarchy image;
       }

       !class Channel
       {
         string name;
         int width;
         int height;
         int opacity;
         int r, g, b;
         int tattoo;
         Hierarchy image_data;
         object parent;
         mapping flags = ([]);
         array (Parasite) parasites;
       }

       !class Hierarchy
       {
         Image.Image img;
         Image.Image alpha;
         int width;
         int height;
         int bpp;
       }

       !class Parasite
       {
         string name;
         int flags;
         string data;
       }

       !class Guide
       {
         int pos;
         int vertical;
       }

       !class Path
       {
         string name;
         int ptype;
         int tattoo;
         int closed;
         int state;
         int locked;
         array (PathPoint) points = ({});
       }

       !class PathPoint
       {
         int type;
         float x;
         float y;
       }

Decodes a XCF image to a mapping.

    Structure reference

        ([
          "width":int,
          "height":int,
          "type":int,
          "properties":({
            ([
              "type":int,
              "data":string,
            ]),
            ...
          }),
          "layers":({
            ([
              "name":string,
              "width":int,
              "height":int,
              "type":type,
              "properties":({
                ([
                  "type":int,
                  "data":string,
                ]),
                ...
              }),
              "mask":0 || ([
                "name":string,
                "width":int,
                "height":int,
                "properties":({
                  ([
                    "type":int,
                    "data":string,
                  ]),
                  ...
                }),
                "image_data":([
                  "bpp":int,
                  "width":int,
                  "height":int,
                  "tiles":({
                    string,
                    ...
                  }),
                ]),
              ]),
              "image_data":([
                "bpp":int,
                "width":int,
                "height":int,
                "tiles":({
                  string,
                  ...
                }),
              ]),
            ]),
            ...
          }),
          "channels":({
            "name":string,
            "width":int,
            "height":int,
            "properties":({
              ([
                "type":int,
                "data":string,
              ]),
              ...
            }),
            "image_data":([
              "bpp":int,
              "width":int,
              "height":int,
              "tiles":({
                string,
                ...
              }),
            ]),
          }),
        ])

Decodes a XBM image.

Throws upon error in data.

Encodes a XBM image.

The options argument may be a mapping containing zero or more encoding options.

    normal options:
        "name":"xbm_image_name"
            The name of the XBM. Defaults to 'image'

Decodes a XBM image to a mapping.

        Supported options:
       ([
          "fg":({fgcolor}),    // Foreground color. Default black
          "bg":({bgcolor}),    // Background color. Default white
          "invert":1,          // Invert the mask
        ])

Throws upon error in data.

Support for encoding and decoding the Portable Network Graphics format, PNG.

This module uses zlib.

Encodes a PNG chunk.

Please read about the PNG file format.

Splits a PNG file into chunks.

Result is an array of arrays, or 0 if data isn't a PNG file. Each element in the array is constructed as follows.

0

The type of the chunk, e.g. "IHDR" or "IDAT".

1

The actual chunk data.

0 1 2

Set to 1 if the checksum is ok and dontcheckcrc isn't set.

Please read about the PNG file format. Support for decoding cHRM, gAMA, sBIT, hIST, pHYs, tIME, tEXt and zTXt chunks are missing.

Decode a PNG image file.

- Image.Colortable "colortable"

A replacement color table to be used instead of the one in the PNG file, if any.

- Image.Image "image"

The decoded image.

- "bpp"

Number of bitplanes in the image. One of 1, 2, 4, 8 and 16.

- "type"

Image color type. Bit values are:

1

Palette used.

2

Color used.

4

Alpha channel used.

Valid values are 0, 2, 3, 4 and 6.

- "xsize"
- "ysize"

Image dimensions.

- "background"

The background color, if any. An array of size three with the RGB values.

- Image.Image "alpha"

The alpha channel, if any.

Throws an error if the image data is erroneous.

Please read about the PNG file format. This function ignores any checksum errors in the file. A PNG of higher color resolution than the Image module supports (8 bit) will lose that information in the conversion.

Encodes a PNG image.

- Image.Image "alpha"

Use this image as alpha channel (Note: PNG alpha channel is grey. The values are calculated by (r+2g+b)/4.)

- Image.Colortable "palette"

Use this as palette for pseudocolor encoding (Note: encoding with alpha channel and pseudocolor at the same time are not supported)

__decode

Please read some about PNG files.

Image.Image
Image.Image

Decodes only the PNG headers.

_decode

Decodes a PNG image. The options mapping is the as for _decode.

Throws upon error in data.

Image.Image
Image.Image

Decodes the alpha channel in a PNG file. The options mapping is the same as for _decode.

Throws upon error in data.

Image.Image

Handle encoding and decoding of PVR images.

PVR is the texture format of the NEC PowerVR system It is a rather simple, uncompressed, truecolor format.

decodes a PVR image

The decode_header and _decode has these elements:

       "image":object            - image object    \- not decode_header
       "alpha":object            - decoded alpha   /

       "type":"image/x-pvr"      - image type
       "xsize":int               - horisontal size in pixels
       "ysize":int               - vertical size in pixels
       "attr":int                - texture attributes
       "global_index":int        - global index (if present)

encode a PVR image

options is a mapping with optional values:

       "alpha":object            - alpha channel
       "global_index":int        - global index
       "vq":int(0..1)            - Vector Quantification compression

Handle decoding of TIM images.

TIM is the framebuffer format of the PSX game system. It is a simple, uncompressed, truecolor or CLUT format with a one bit alpha channel.

decodes a TIM image

The decode_header and _decode has these elements:

       "image":object            - image object    \- not decode_header
       "alpha":object            - decoded alpha   /

       "type":"image/x-tim"      - image type
       "xsize":int               - horisontal size in pixels
       "ysize":int               - vertical size in pixels
       "attr":int                - texture attributes

This submodule keep the ILBM encode/decode capabilities of the Image module.

Image, Image.Image, Image.Colortable

Decodes ILBM data and creates an image object.

the decoded image as an image object

This function may throw errors upon illegal ILBM data. This function uses __decode and _decode internally.

encode

Encodes an ILBM image.

The options argument may be a mapping containing zero or more encoding options:

    normal options:
        "alpha":image object
            Use this image as mask
            (Note: ILBM mask is boolean.
             The values are calculated by (r+2g+b)/4>=128.)

        "palette":colortable object
            Use this as palette for pseudocolor encoding

Decode an ILBM image file.

Result is a mapping,

    ([
       "image": object image,

       ... more ...
    ])

image is the stored image.

Decodes an ILBM image structure down to chunks and

    ({int xsize,int ysize,      // 0: size of image drawing area
      string bitmapheader,      // 2: BMHD chunk
      void|string colortable,   // 3: opt. colortable chunk (CMAP)
      void|string colortable,   // 4: opt. colormode chunk (CAMG)
      string body,              // 5: BODY chunk
      mapping more_chunks})     // 6: mapping with other chunks

the above array

May throw errors if the ILBM header is incomplete or illegal.

WAP bitmap format - WBMP.

Document this function.

Document this function.

- "format"

The MIME type and encoding for the image, e.g. "image/x-wap.wbmp; type=0".

- "xsize"
- "ysize"
- "fix_header_field"
- "ext_header_field"

Document this function.

This submodule handles encoding and decoding of the binary formats of X11.

Image, Image.Image, Image.Colortable

lazy support for pseudocolor ZPixmaps

currently, only byte-aligned pixmaps are supported

lazy support for truecolor ZPixmaps

currently, only byte-aligned masks are supported

the image object to encode

bits per pixel, how many bits each pixel should take

value bits per pixel; how many bits per pixel that really contains information

the number of even bits each line should be padded to

colortable to get indices for pseudocolor

translate table for colors. Length of this string should be 1<<vbpp (or 2<<vbpp if vbpp are greater than 8).

currently, only upto 16 bits pseudocolor are supported.

Pack an image into a truecolor string. You will get a string of packed red, green and blue bits; ie:

encode_truecolor(img, 12,32, 0, 3,5, 4,0, 3,8) will give (aligned to even 32 bits for each row):
0bbbrrr0 gggg0bbb rrr0gggg 0bbb...
<--pixel 1--><--pixel 2--> <--3-->
10987654 32101098 76543210 1098... <- bit position <-><-> <--> | | +--- 4,0: 4 bits green shifted 0 bits | +-------- 3,5: 3 bits red shifted 5 bits +----------- 3,8: 3 bits blue shifted 8 bits

The above call is equal to
encode_truecolor_masks(img, 12,32, 0, 224, 15, 768) and
encode_truecolor(img, 12,32, 0, 3,5,4,0,3,8, colortable(1<<3,1<<4,1<<3)).
The latter gives possibility to use dither algorithms, but is slightly slower.

the image object to encode

bits per pixel, how many bits each pixel should take

the number of even bits each line should be padded to

bits for each basecolor

leftshifts for each basecolor

masks for each basecolor (xbits and gbits are calculated from this), needs to be massive (no zeroes among the ones in the mask).

colortable object (for dithering, or whatever)

swap bytes for bpp==16,24,32, swaps bits in the bytes if bpp==1, for change of byte/bitorder between client and server.

Fills in img and alpha according to xpm data in bpc, colors and pixels.

Bytes per color. Number of bytes used to encode each color in pixels.

Array of color definitions.

A color definition is on the format "ee c #RRGGBB", where ee is a bpc long string used to encode the color, c is a literal "c", and RRGGBB is a hexadecimal RGB code.

Raw picture information.

0

Size information on the format (sprintf("%d %d %d %d", h, w, ncolors, bpn)).

1
ncolors

Same as colors.

ncolors_plus_one
ncolors_plus_h

Line information. Strings of length bpn*w with encoded pixels for each line.

Image.Image
Image.Image
0
0

This submodule keeps the BMP (Windows Bitmap) encode/decode capabilities of the Image module.

BMP is common in the Windows environment.

Simple encoding:
encode

Image, Image.Image, Image.Colortable

Decode a BMP.

decode gives an image object, _decode gives a mapping in the format

            "type":"image/x-MS-bmp",
            "image":image object,
            "colortable":colortable object (if applicable)

            "xsize":int,
            "ysize":int,
            "compression":int,
            "bpp":int,
            "windows":int,

the encoded image as a string

Doesn't support all BMP modes. At all.

encode

Make a BMP. It default to a 24 bpp BMP file, but if a colortable is given, it will be 8bpp with a palette entry.

option is a mapping that may contain:

    "colortable": Image.Colortable   - palette
    "bpp":        1|4|8|24           - force this many bits per pixel
    "rle":        0|1                - run-length encode (default is 0)

Source image.

Colortable object, shortcut for "colortable" in options.

the encoded image as a string

Doesn't support old BMP mode, only "windows" mode.

decode

Handle encoding and decoding of AVS-X images. AVS is rather trivial, and not really useful, but:

An AVS file is a raw (uncompressed) 24 bit image file with alpha. The alpha channel is 8 bit, and there is no separate alpha for r, g and b.

This method calls the other decoding methods and has some heuristics for what type of image this is.

Methods: decode, decode_alpha, _decode

Image

Tries heuristics to find the correct method of decoding the data, then calls that method.

The result of _decode() is a mapping that contains

            "type":image data type (ie, "image/jpeg" or similar)
            "image":the image object,
            "alpha":the alpha channel or 0 if N/A

Throws upon failure.

Decodes a Targa image.

Throws upon error in data.

Encodes a Targa image.

The options argument may be a mapping containing zero or more encoding options:

    normal options:
        "alpha":image object
            Use this image as alpha channel
            (Note: Targa alpha channel is grey.
             The values are calculated by (r+2g+b)/4.)

        "raw":1
            Do not RLE encode the image

Decodes a Targa image to a mapping. The mapping follows this format: ([ "image":img_object, "alpha":alpha_channel ])

Throws upon error in data.

This submodule keeps the XWD (X Windows Dump) decode capabilities of the Image module.

XWD is the output format for the xwd program.

Simple decoding:
decode

Advanced decoding:
_decode

Image, Image.Image, Image.PNM, Image.X

Simple decodes a XWD image file.

Decodes XWD data and returns the result.

Supported XWD visual classes and encoding formats are TrueColor / ZPixmap DirectColor / ZPixmap PseudoColor / ZPixmap

If someone sends me files of other formats, these formats may be implemented. :) /mirar+pike@mirar.org

the decoded image as an image object

This function may throw errors upon illegal or unknown XWD data.

decode

This submodule keep the RAS encode/decode capabilities of the Image module.

Image, Image.Image, Image.Colortable

Decodes RAS data and creates an image object.

the decoded image as an image object

This function may throw errors upon illegal RAS data.

encode

Encodes a RAS image.

The options argument may be a mapping containing zero or more encoding options:

    normal options:

        "palette":colortable object
            Use this as palette for pseudocolor encoding

Decodes a PCX image.

Throws upon error in data.

Encodes a PCX image. The _encode and the encode functions are identical

The options argument may be a mapping containing zero or more encoding options:

    normal options:
        "raw":1
            Do not RLE encode the image
        "dpy":int
        "xdpy":int
        "ydpy":int
            Image resolution (in pixels/inch, integer numbers)
        "xoffset":int
        "yoffset":int
            Image offset (not used by most programs, but gimp uses it)

Decodes a PCX image to a mapping.

Throws upon error in data.

This submodule keeps the PNM encode/decode capabilities of the Image module.

PNM is a common image storage format on unix systems, and is a very simple format.

This format doesn't use any color palette.

The format is divided into seven subformats;

    P1(PBM) - ascii bitmap (only two colors)
    P2(PGM) - ascii greymap (only grey levels)
    P3(PPM) - ascii truecolor
    P4(PBM) - binary bitmap
    P5(PGM) - binary greymap
    P6(PPM) - binary truecolor

Simple encoding:
encode,
encode_binary,
encode_ascii

Simple decoding:
decode

Advanced encoding:
encode_P1,
encode_P2,
encode_P3,
encode_P4,
encode_P5,
encode_P6

Image, Image.Image, Image.GIF

Decodes PNM (PBM/PGM/PPM) data and creates an image object.

the decoded image as an image object

This function may throw errors upon illegal PNM data.

encode

Make a complete PNM file from an image.

encode_binary() and encode_ascii() uses the most optimized encoding for this image (bitmap, grey or truecolor) - P4, P5 or P6 respective P1, P2 or P3.

encode_P1/encode_P4 assumes the image is black and white. Use Image.Image->threshold() or something like Image.Colortable( ({({0,0,0}),({255,255,255})}) )
->floyd_steinberg()
->map(my_image) to get a black and white image.

encode_P2/encode_P5 assumes the image is greyscale. Use Image.Image->grey() to get a greyscale image.

the encoded image as a string

encode() is equal to encode_binary(), but may change in a future release.

decode

Handle encoding and decoding of HRZ images. HRZ is rather trivial, and not really useful, but:

The HRZ file is always 256x240 with RGB values from 0 to 63. No compression, no header, just the raw RGB data. HRZ is (was?) used for amatuer radio slow-scan TV.

This is the same as apply_matrix, but it uses the maximum instead.

This function is not very fast.

the matrix; innermost is a value or an array with red, green, blue values for red, green, blue separation.

base level of result, default is zero

division factor, default is 1.0.

the new image object

experimental status; may not be exact the same output in later versions

This method creates a string that looks like the image. Example:

       //Stina is an image with a cat.
       array(object) Stina4=Stina->orient4();
       Stina4[1]*=215;
       Stina4[3]*=215;
       string foo=Stina->make_ascii(@Stina4,40,4,8);

some nice acsii-art.

experimental status; may not be exact the same output in later versions

          |      /    -    \
         hue=  0     64   128  192  (=red in an hsv image)

orient, orient4

This method creates an image that describes the match in every pixel in the image and the needle-Image.

       new pixel value =
         sum( my_abs(needle_pixel-haystack_pixel))

The new image only have the red rgb-part set.

Every pixel is divided with this value. Note that a proper value here depends on the size of the neadle.

The image to use for the matching.

This image should be the same size as the image itselves. A non-white-part of the haystack_cert-image modifies the output by lowering it.

The same, but for the needle-image.

This image should be the same size as the image itselves. If foo is less than the red value in haystack_avoid the corresponding matching-calculating is not calculated. The avoided parts are drawn in the color 0,100,0.

the new image object

experimental status; may not be exact the same output in later versions

phasev, phaseh

Draws images describing the phase of the current image. phaseh gives the horizontal phase and phasev the vertical phase.

phaseh gives an image where

           max  falling   min  rising
    value=  0     64      128   192

0 is set if there is no way to determine if it is rising or falling. This is done for the every red, green and blue part of the image.

Phase images can be used to create ugly effects or to find meta-information in the orginal image.

search.c0.png | search.c1.png | search.c2.png | search.c3.png | search.c4.png
original | phaseh() | phasev() | phasevh() | phasehv()

the new image object

experimental status; may not be exact the same output in later versions

0 should not be set as explained above.

Pastes a given image over the current image.

image to paste (may be empty, needs to be an image object)

where to paste the image; default is 0,0

the object called

paste_mask, paste_alpha, paste_alpha_color

Pastes a given image over the current image, with the specified alpha channel value.

An alpha channel value of 0 leaves nothing of the original image in the paste area, 255 is meaningless and makes the given image invisible.

image to paste

alpha channel value

where to paste the image; default is 0,0

the object called

paste_mask, paste, paste_alpha_color

Color
Color

Pastes a given color over the current image, using the given mask as opaque channel.

A pixel value of 255 makes the result become the color given, 0 doesn't change anything.

The masks red, green and blue values are used separately. If no color are given, the current is used.

mask image

what color to paint with; default is current

where to paste the image; default is 0,0

the object called

paste_mask, paste_alpha, paste_alpha_color

Pastes a given image over the current image, using the given mask as opaque channel.

A pixel value of 255 makes the result become a pixel from the given image, 0 doesn't change anything.

The masks red, green and blue values are used separately.

image to paste

mask image

where to paste the image; default is 0,0

the object called

paste, paste_alpha, paste_alpha_color

Draws images describing the orientation of the current image.

orient gives an HSV image (run a hsv_to_rgb pass on it to get a viewable image). corresponding to the angle of the orientation:

          |      /    -    \
         hue=  0     64   128  192  (=red in an hsv image)
             purple cyan green red

Red, green and blue channels are added and not compared separately.

If you first use orient4 you can give its output as input to this function.

The orient4 function gives back 4 image objects, corresponding to the amount of different directions, see above.

an image or an array of the four new image objects

experimental status; may not be exact the same output in later versions

Gives a new image with the old image's size, filled width a 'noise' pattern.

The random seed may be different with each instance of pike.

Example: ->noise( ({0,({255,0,0}), 0.3,({0,255,0}), 0.6,({0,0,255}), 0.8,({255,255,0})}), 0.2,0.0,0.0,1.0 );
pattern.c0.png

colorrange table

default value is 0.1

default value is 0,0

default value is 1

turbulence

greyint

Gives a randomized image;

pattern.c1.png | pattern.c2.png | pattern.c3.png | pattern.c4.png | pattern.c5.png | pattern.c6.png
original | ->random() | ->random(17) | greyed (same again) | color(red) (same again) | ...red channel

Use with ->grey() or ->color() for one-color-results.

a new image

test, noise

gives a new image with the old image's size, filled width a 'turbulence' pattern

The random seed may be different with each instance of pike.

Example:
->turbulence( ({0,({229,204,204}), 0.9,({229,20,20}), 0.9,Color.black}) );
pattern.c7.png

colorrange table

default value is 3

default value is 0.1

default value is 0,0

default value is 1

noise, Image.Color

The main object of the Image module, this object is used as drawing area, mask or result of operations.

basic:
clear, clone, create, xsize, ysize

plain drawing:
box, circle, getpixel, line, setcolor, setpixel, threshold, polyfill

operators:
`&, `*, `+, `-, `==, `>, `<, `|

pasting images:
paste, paste_alpha, paste_alpha_color, paste_mask

getting subimages, scaling, rotating:
autocrop, clone, copy, dct, mirrorx, rotate, rotate_ccw, rotate_cw, rotate_expand, scale, skewx, skewx_expand, skewy, skewy_expand

calculation by pixels:
apply_matrix, change_color, color, distancesq, grey, invert, modify_by_intensity, outline select_from, rgb_to_hsv, hsv_to_rgb,

average, max, min, sum, sumf, find_min, find_max

special pattern drawing:
noise, turbulence, test, tuned_box, gradients, random

Image, Image.Font, Image.Colortable, Image.X

Apply a lookup-table on all pixels in an image. If only one curve is passed, use the same curve for red, green and blue. If 'channel' is specified, the curve is only applied to the specified channel.

An array with 256 elements, each between 0 and 255. It is used as a look-up table, if the pixel value is 2 and curve[2] is 10, the new pixel value will be 10.

one of "red", "green", "blue", "value", "saturation" and "hue".

a new image object

gamma, `*, modify_by_intensity

Applies a pixel-transform matrix, or filter, to the image.

                           2   2
    pixel(x,y)= base+ k ( sum sum pixel(x+k-1,y+l-1)*matrix(k,l) )
                          k=0 l=0

1/k is sum of matrix, or sum of matrix multiplied with div. base is given by r,g,b and is normally black.

blur (ie a 2d gauss function):

    ({({1,2,1}),
      ({2,5,2}),
      ({1,2,1})})

image.c0.png

image.c1.png

| original

sharpen (k>8, preferably 12 or 16):

    ({({-1,-1,-1}),
      ({-1, k,-1}),
      ({-1,-1,-1})})

image.c2.png

edge detect:

    ({({1, 1,1}),
      ({1,-8,1}),
      ({1, 1,1})})

image.c3.png

horisontal edge detect (get the idea):

    ({({0, 0,0}),
      ({1,-2,1}),
      ({0, 0,0})})

image.c4.png

emboss (might prefer to begin with a grey image):

    ({({2, 1, 0}),
      ({1, 0,-1}),
      ({0,-1,-2})}), 128,128,128, 3

image.c5.png

image.c6.png

| greyed

This function is not very fast.

the matrix; innermost is a value or an array with red, green, blue values for red, green, blue separation.

base level of result, default is zero

division factor, default is 1.0.

the new image object

Color
Color

Removes "unneccesary" borders around the image, adds one of its own if wanted to, in selected directions.

"Unneccesary" is all pixels that are equal -- ie if all the same pixels to the left are the same color, that column of pixels are removed.

The find_autocrop() function simply returns x1,y1,x2,y2 for the kept area. (This can be used with copy later.)

which borders to scan and cut the image; a typical example is removing the top and bottom unneccesary pixels:

    img=img->autocrop(0, 0,0,1,1);

the new image object

copy

scales the image with a factor, without smoothing. This routine is faster than scale, but gives less correct results

image.c7.png | image.c8.png | image.c9.png
original | bitscale(0.75) | scale(0.75)

factor to use for both x and y

separate factors for x and y

the new image object

0
0

scales the image to a specified new size, if one of newxsize or newysize is 0, the image aspect ratio is preserved.

new image size in pixels

the new image object

resulting image will be 1x1 pixels, at least

A special case of apply_matrix that creates a blur effect. About four times faster than the generic apply_matrix. @[no_pass] is the number of times the blur matrix is applied.

image.c10.png | image.c11.png | image.c12.png
original | blur(1) | blur(5)

apply_matrix, grey_blur

Draws a filled rectangle on the image.

image.c13.png | image.c14.png | image.c15.png
original | ->box (40,10, 10,80, 0,255,0) | ->box (40,10, 10,80, 255,0,0,75)

box corners

color of the box

alpha value

the object called

Cast the image to another datatype. Currently supported are string ("rgbrgbrgb...") and array (double array of Image.Color objects).

Image.Color, Image.X

Changes one color (exakt match) to another. If non-exakt-match is preferred, check distancesq and paste_alpha_color.

destination color and next current color

source color, default is current color

a new (the destination) image object

Draws a circle on the image. The circle is not antialiased.

image.c16.png | image.c17.png
original | ->circle (50,50, 30,50, 0,255,255)

circle center

circle radius in pixels

color

alpha value

the object called

gives a new, cleared image with the same size of drawing area

image.c18.png | image.c19.png
original | ->clear (0,128,255)

color of the new image

new default alpha channel value

copy, clone

Copies to or initialize a new image object.

image.c20.png | image.c21.png | image.c22.png
original | clone | clone(50,50)

size of (new) image in pixels, called image is cropped to that size

current color of the new image, default is black. Will also be the background color if the cloned image is empty (no drawing area made).

new default alpha channel value

the new object

copy, create

Colorize an image.

The red, green and blue values of the pixels are multiplied with the given value(s). This works best on a grey image...

The result is divided by 255, giving correct pixel values.

If no arguments are given, the current color is used as factors.

image.c23.png | image.c24.png
original | ->color(128,128,255);

red, green, blue factors

factor

the new image object

grey, `*, modify_by_intensity

Copies this part of the image. The requested area can be smaller, giving a cropped image, or bigger - the new area will be filled with the given or current color.

image.c25.png | image.c26.png | image.c27.png
original | ->copy (5,5, XSIZE-6,YSIZE-6) | ->copy (-5,-5, XSIZE+4,YSIZE+4, 10,75,10)

The requested new area. Default is the old image size.

color of the new image

new default alpha channel value

a new image object

clone(void) and copy(void) does the same operation

clone, autocrop

Color
method

Initializes a new image object.

image.c28.png | image.c29.png
Image.Image (XSIZE,YSIZE) | Image.Image (XSIZE,YSIZE,255,128,0)

The image can also be calculated from some special methods, for convinience:

    channel modes; followed by a number of 1-char-per-pixel strings
    or image objects (where red channel will be used),
    or an integer value:
      "grey" : make a grey image (needs 1 source: grey)
      "rgb"  : make an rgb image (needs 3 sources: red, green and blue)
      "cmyk" : make a rgb image from cmyk (cyan, magenta, yellow, black)

    generate modes; all extra arguments is given to the
    generation function. These has the same name as the method:
      "test,"
      "gradients"
      "noise"
      "turbulence"
      "random"
      "randomgrey"
    specials cases:
      "tuned_box" (coordinates is automatic)

size of (new) image in pixels

background color (will also be current color), default color is black

default alpha channel value

SIGSEGVS can be caused if the size is too big, due to unchecked overflow - (xsize*ysize)&MAXINT is small enough to allocate.

copy, clone, Image.Image

Makes an grey-scale image, for alpha-channel use.

The given value (or current color) are used for coordinates in the color cube. Each resulting pixel is the distance from this point to the source pixel color, in the color cube, squared, rightshifted 8 steps:

    p = pixel color
    o = given color
    d = destination pixel
    d.red=d.blue=d.green=
        ((o.red-p.red)²+(o.green-p.green)²+(o.blue-p.blue)²)>>8

image.c30.png | image.c31.png | image.c32.png | image.c33.png
original | distance² to cyan | ...to purple | ...to yellow

red, green, blue coordinates

the new image object

select_from

Calculate pixels in image by gamma curve.

Intensity of new pixels are calculated by:
i' = i^g

For example, you are viewing your image on a screen with gamma 2.2. To correct your image to the correct gamma value, do something like:

my_display_image(my_image()->gamma(1/2.2);

gamma value

a new image object

grey, `*, color

position of the pixel

color of the requested pixel -- ({int red,int green,int blue})

image.c34.png | image.c35.png | image.c36.png | image.c37.png | image.c38.png | image.c39.png
original | 2 color gradient | 10 color gradient | 3 colors, grad=4.0 | 3 colors, grad=1.0 | 3 colors, grad=0.25

the new image

Makes a grey-scale image (with weighted values).

image.c40.png | image.c41.png | image.c42.png
original | ->grey(); | ->grey(0,0,255);

weight of color, default is r=87,g=127,b=41, which should be pretty accurate of what the eyes see...

the new image object

color, `*, modify_by_intensity

Works like blur, but only operates on the r color channel. A faster alternative to blur for grey scale images. @[no_pass] is the number of times the blur matrix is applied.

image.c43.png | image.c44.png | image.c45.png
original | grey_blur(1) | grey_blur(5)

blur

Converts RGB data to HSV data, or the other way around. When converting to HSV, the resulting data is stored like this: pixel.r = h; pixel.g = s; pixel.b = v;

When converting to RGB, the input data is asumed to be placed in the pixels as above.

image.c46.png | image.c47.png | image.c48.png
original | ->hsv_to_rgb(); | ->rgb_to_hsv();
image.c49.png | image.c50.png | image.c51.png
tuned box (below) | the rainbow (below) | same, but rgb_to_hsv()

HSV to RGB calculation:

    in = input pixel
    out = destination pixel
    h=-pos*c_angle*3.1415/(float)NUM_SQUARES;
    out.r=(in.b+in.g*cos(in.r));
    out.g=(in.b+in.g*cos(in.r + pi*2/3));
    out.b=(in.b+in.g*cos(in.r + pi*4/3));

RGB to HSV calculation: Hmm.

Example: Nice rainbow.

     object i = Image.Image(200,200);
     i = i->tuned_box(0,0, 200,200,
                      ({ ({ 255,255,128 }), ({ 0,255,128 }),
                         ({ 255,255,255 }), ({ 0,255,255 })}))
          ->hsv_to_rgb();

the new image object

Invert an image. Each pixel value gets to be 255-x, where x is the old value.

image.c52.png | image.c53.png | image.c54.png
original | ->invert(); | ->rgb_to_hsv()->invert()->hsv_to_rgb();

the new image object

Draws a line on the image. The line is not antialiased.

image.c55.png | image.c56.png
original | ->line (50,10, 10,50, 255,0,0)

line endpoints

color

alpha value

the object called

Compatibility functions. Do not use!

Replacement examples:

Old code:

    img=map_fs(img->select_colors(200));

New code:

    img=Image.Colortable(img,200)->floyd_steinberg()->map(img);

Old code:

    img=map_closest(img->select_colors(17)+({({255,255,255}),({0,0,0})}));

New code:

    img=Image.Colortable(img,19,({({255,255,255}),({0,0,0})}))->map(img);

Recolor an image from intensity values.

For each color an intensity is calculated, from r, g and b factors (see grey), this gives a value between 0 and max.

The color is then calculated from the values given, v1 representing the intensity value of 0, vn representing max, and colors between representing intensity values between, linear.

image.c57.png | image.c58.png
original | ->grey()->modify_by_intensity(1,0,0, 0,({255,0,0}),({0,255,0}));

red, green, blue intensity factors

destination color

the new image object

grey, `*, color

Makes an outline of this image, ie paints with the given color around the non-background pixels.

Default is to paint above, below, to the left and the right of these pixels.

You can also run your own outline mask.

The outline_mask function gives the calculated outline as an alpha channel image of white and black instead.

image.c59.png | image.c60.png | image.c61.png
original | masked through threshold | ...and outlined with red

mask matrix. Default is ({({0,1,0}),({1,1,1}),({0,1,0})}).

outline color. Default is current.

background color (what color to outline to); default is color of pixel 0,0.

division factor, default is 1.0.

the new image object

no antialias!

These functions read/write in the least significant bit of the image pixel values. The _rgb() functions read/write on each of the red, green and blue values, and the grey keeps the same lsb on all three.

The string is nullpadded or cut to fit.

the hidden message

the current object or the read string

Makes an grey-scale image, for alpha-channel use.

This is very close to a floodfill.

The image is scanned from the given pixel, filled with 255 if the color is the same, or 255 minus distance in the colorcube, squared, rightshifted 8 steps (see distancesq).

When the edge distance is reached, the scan is stopped. Default edge value is 30. This value is squared and compared with the square of the distance above.

image.c62.png | image.c63.png | image.c64.png | image.c65.png | image.c66.png | image.c67.png | image.c68.png
35, 35, 16 | 35, 35, 32 | 35, 35, 64 | 35, 35, 96 | 35, 35, 128 | 35, 35, 192 | 35, 35, 256

image.c69.png | image.c70.png
original | original * select_from(35,35,200)

originating pixel in the image

the new image object

distancesq

set the current color

new color

new alpha value

the object called

Image.Color

image.c71.png | image.c72.png
original | ->setpixel (10,10, 255,0,0)

position of the pixel

color

alpha value

the object called

Generates a test image, currently random gradients.

image.c73.png | image.c74.png | image.c75.png
original | ->test() | ...and again

the new image

May be subject to change or cease without prior warning.

gradients, tuned_box

Color

Makes a black-white image.

If any of red, green, blue parts of a pixel is larger then the given value, the pixel will become white, else black.

This method works fine with the grey method.

If no arguments are given, it will paint all non-black pixels white. (Ie, default is 0,0,0.)

image.c76.png | image.c77.png | image.c78.png
original | ->threshold(100); | ->threshold(0,100,0);

the new image object

The above statement "any ..." was changed from "all ..." in Pike 0.7 (9906). It also uses 0,0,0 as default input, instead of current color. This is more useful.

grey

Draws a filled rectangle with colors (and alpha values) tuned between the corners.

Tuning function is (1.0-x/xw)*(1.0-y/yw) where x and y is the distance to the corner and xw and yw are the sides of the rectangle.

image.c79.png | image.c80.png | image.c81.png | image.c82.png
original | tuned box | solid tuning (blue,red,green,yellow) | tuning transparency (as left + 255,128,128,0)

rectangle corners

colors of the corners:

    ({x1y1,x2y1,x1y2,x2y2})

each of these is an array of integeres:

    ({r,g,b}) or ({r,g,b,alpha})

Default alpha channel value is 0 (opaque).

the object called

the width of the image

the height of the image

mirrors an image:

matrix.c0.png | matrix.c1.png
original | ->mirrorx();

the new image object

mirrors an image:

matrix.c2.png | matrix.c3.png
original | ->mirrory();

Rotates an image a certain amount of degrees (360° is a complete rotation) counter-clockwise:

matrix.c4.png | matrix.c5.png | matrix.c6.png
original | ->rotate(15,255,0,0); | ->rotate_expand(15);

The "expand" variant of functions stretches the image border pixels rather then filling with the given or current color.

This rotate uses the skewx() and skewy() functions.

the number of degrees to rotate

color to fill with; default is current

the new image object

rotates an image counter-clockwise, 90 degrees.

matrix.c7.png | matrix.c8.png
original | ->rotate_ccw();

the new image object

rotates an image clockwise, 90 degrees.

matrix.c9.png | matrix.c10.png
original | ->rotate_cw();

the new image object

0.5

scales the image with a factor, 0.5 is an optimized case.

factor to use for both x and y

separate factors for x and y

the new image object

0
0

scales the image to a specified new size, if one of newxsize or newysize is 0, the image aspect ratio is preserved.

new image size in pixels

the new image object

resulting image will be 1x1 pixels, at least

Skews an image an amount of pixels or a factor; a skew-x is a transformation:

matrix.c11.png | matrix.c12.png | matrix.c13.png
original | ->skewx(15,255,0,0); | ->skewx_expand(15);

the number of pixels The "expand" variant of functions stretches the image border pixels rather then filling with the given or current color.

best described as: x=yfactor*this->ysize()

color to fill with; default is current

the new image object

Skews an image an amount of pixels or a factor; a skew-y is a transformation:

matrix.c14.png | matrix.c15.png | matrix.c16.png
original | ->skewy(15,255,0,0); | ->skewy_expand(15);

The "expand" variant of functions stretches the image border pixels rather then filling with the given or current color.

the number of pixels

best described as: t=xfactor*this->xsize()

color to fill with; default is current

the new image object

Scales the image to a new size.

Method for scaling is rather complex; the image is transformed via a cosine transform, and then resampled back.

This gives a quality-conserving upscale, but the algorithm used is n*n+n*m, where n and m is pixels in the original and new image.

Recommended wrapping algorithm is to scale overlapping parts of the image-to-be-scaled.

This functionality is actually added as an true experiment, but works...

new image size in pixels

the new image object

Do NOT use this function if you don't know what you're dealing with! Read some signal theory first...

It write's dots on stderr, to indicate some sort of progress. It doesn't use any fct (compare: fft) algorithms.

fills an area with the current color

curve(s), ({x1,y1,x2,y2,...,xn,yn}), automatically closed.

If any given curve is inside another, it will make a hole.

    Image.Image(100,100)->setcolor(255,0,0,128)->
      polyfill( ({ 20,20, 80,20, 80,80 }) );

polyfill.c0.png

the current object

Lines in the polygon may not be crossed without the crossing coordinate specified in both lines.

Inverted lines reported on Intel and Alpha processors.

setcolor

Gives back the average, minimum, maximum color value, and the sum of all pixel's color value.

sum() values can wrap! Most systems only have 31 bits available for positive integers. (Meaning, be careful with images that have more than 8425104 pixels.)

average() and sumf() may also wrap, but on a line basis. (Meaning, be careful with images that are wider than 8425104 pixels.) These functions may have a precision problem instead, during to limits in the 'double' C type and/or 'float' Pike type.

Gives back the position of the minimum or maximum pixel value, weighted to grey.

weight of color, default is r=87,g=127,b=41, same as the grey() method.

Color
Color

Divides pixel values and creates a new image from the result or the rest.

the other image to divide with; the images must have the same size.

if specified as color or value, it will act as a whole image of that color (or value).

the new image object

It isn't possible to do a modulo 256 either. (why?)

`-, `+, `|, `&amp;, `*, Image.Layer

makes a new image out of the minimum pixels values

the other image to compare with; the images must have the same size.

an array in format ({r,g,b}), this is equal to using an uniform-colored image.

equal to ({value,value,value}).

the new image object

`-, `+, `|, `*, Image.Layer

Compares an image with another image or a color.

Comparision is strict and on pixel-by-pixel basis. (Means if not all pixel r,g,b values are correct compared with the corresponding pixel values, 0 is returned.)

the other image to compare with; the images must have the same size.

an array in format ({r,g,b}), this is equal to using an uniform-colored image.

equal to ({value,value,value}).

true (1) or false (0).

`< or `> on empty ("no image") image objects or images with different size will result in an error. `== is always true on two empty image objects and always false if one and only one of the image objects is empty or the images differs in size.

a>=b and a<=b between objects is equal to !(a<b) and !(a>b), which may not be what you want (since both < and > can return false, comparing the same images).

`-, `+, `|, `*, `&amp;

Multiplies pixel values and creates a new image. This can be useful to lower the values of an image, making it greyer, for instance:

    image=image*128+64;

the other image to multiply with; the images must have the same size.

an array in format ({r,g,b}), this is equal to using an uniform-colored image.

equal to ({value,value,value}).

the new image object

`-, `+, `|, `&amp;, Image.Layer

adds two images; values are truncated at 255.

the image which to add.

an array in format ({r,g,b}), this is equal to using an uniform-colored image.

equal to ({value,value,value}).

the new image object

`-, `|, `&amp;, `*, Image.Layer

makes a new image out of the difference

the other image to compare with; the images must have the same size.

an array in format ({r,g,b}), this is equal to using an uniform-colored image.

equal to ({value,value,value}).

the new image object

`+, `|, `&amp;, `*, Image.Layer, min, max, `==

makes a new image out of the maximum pixels values

the other image to compare with; the images must have the same size.

an array in format ({r,g,b}), this is equal to using an uniform-colored image.

equal to ({value,value,value}).

the new image object

`-, `+, `&amp;, `*, Image.Layer

This module keeps names and easy handling for easy color support. It gives you an easy way to get colors from names.

A color is here an object, containing color information and methods for conversion, see below.

Image.Color can be called to make a color object. Image.Color() takes the following arguments:

        Image.Color(string name)          // "red"
        Image.Color(string prefix_string) // "lightblue"
        Image.Color(string hex_name)      // "#ff00ff"
        Image.Color(string cmyk_string)   // "%17,42,0,19.4"
        Image.Color(string hsv_string)    // "%@327,90,32"
        Image.Color(int red, int green, int blue)

The color names available can be listed by using indices on Image.Color. The colors are available by name directly as Image.Color.name, too:

        ...Image.Color.red...
        ...Image.Color.green...
        or, maybe
        import Image.Color;
        ...red...
        ...green...
        ...lightgreen...

Giving red, green and blue values is equal to calling Image.Color.rgb().

The prefix_string method is a form for getting modified colors, it understands all modifiers (light, dark, bright, dull and neon). Simply use "method"+"color"; (as in lightgreen, dullmagenta, lightdullorange).

The hex_name form is a simple #rrggbb form, as in HTML or X-program argument. A shorter form (#rgb) is also accepted. This is the inverse to the Image.Color.Color->hex() method.

The cmyk_string is a string form of giving cmyk (cyan, magenta, yellow, black) color. These values are floats representing percent.

The hsv_string is another hue, saturation, value representation, but in floats; hue is in degree range (0..360), and saturation and value is given in percent. This is not the same as returned or given to the hsv() methods!

This table lists all the different named colors available in Image.Color. The first column shows the actual color while the five following columns demonstrates the modifiers neon, light, dark, bright and dull. The color begind the name of the color is produced by calling neon()->dark()->dark()->dark() from the color object itself, i.e. Image.Color.mintcream->neon()->dark()->dark()->dark().

colors.c.0.png
colors.c.1.png
colors.c.2.png
colors.c.3.png
colors.c.4.png
colors.c.5.png
colors.c.6.png
colors.c.7.png
colors.c.8.png
colors.c.9.png
colors.c.10.png
colors.c.11.png
colors.c.12.png
colors.c.13.png
colors.c.14.png
colors.c.15.png
colors.c.16.png
colors.c.17.png
colors.c.18.png
colors.c.19.png
colors.c.20.png
colors.c.21.png
colors.c.22.png
colors.c.23.png
colors.c.24.png
colors.c.25.png
colors.c.26.png
colors.c.27.png
colors.c.28.png
colors.c.29.png
colors.c.30.png
colors.c.31.png
colors.c.32.png
colors.c.33.png
colors.c.34.png
colors.c.35.png
colors.c.36.png
colors.c.37.png
colors.c.38.png
colors.c.39.png
colors.c.40.png
colors.c.41.png
colors.c.42.png
colors.c.43.png
colors.c.44.png
colors.c.45.png
colors.c.46.png
colors.c.47.png
colors.c.48.png
colors.c.49.png
colors.c.50.png
colors.c.51.png
colors.c.52.png
colors.c.53.png
colors.c.54.png
colors.c.55.png
colors.c.56.png

Image.Color["something"] will never(!) generate an error, but a zero_type 0, if the color is unknown. This is enough to give the error "not present in module", if used as Image.Color.something, though.

If you are using colors from for instance a webpage, you might want to create the color from Image.Color.guess(), since that method is more tolerant for mistakes and errors.

Image.Color() is case- and space-sensitive. Use Image.Color.guess() to catch all variants.

and subtract with a space (lower_case(x)-" ") to make sure you get all variants.

Image.Color.Color, Image.Color.guess, Image, Image.Colortable

Creates a new color object from given red, green and blue, hue, saturation and value, or greylevel, in color value range. It could also be created from cmyk values in percent.

The html() method only understands the HTML color names, or the #rrggbb form. It is case insensitive.

the created object.

This is equivalent to Image.Color(lower_case(str)-" "), and tries the color with a prepending '#' if no corresponding color is found.

a color object or zero_type

(ie as indices(Image.Color) or values(Image.Color)) indices gives a list of all the known color names, values gives there corresponding objects.

Image.Color

This is the color object. It has six readable variables, r, g, b, for the red, green and blue values, and h, s, v, for the hue, saturation anv value values.

Returns the color as an integer. The first three parameters state how many bits to use for red, green and blue respectively. The last three state how many bits each colour should be shifted. For instance, Image.Color("#AABBCC")->bits(8, 8, 8, 16, 8, 0) returns the integer 11189196, that is, 0xAABBCC.

Color modification methods. These returns a new color.

method | effect | h | s | v | as
--- | --- | --- | --- | --- | ---
light | raise light level | ±0 | ±0 | +50 | colors.c57.png colors.c58.png colors.c59.png colors.c60.png
dark | lower light level | ±0 | ±0 | -50 | colors.c61.png colors.c62.png colors.c63.png colors.c64.png
bright | brighter color | ±0 | +50 | +50 | colors.c65.png colors.c66.png colors.c67.png colors.c68.png
dull | greyer color | ±0 | -50 | -50 | colors.c69.png colors.c70.png colors.c71.png colors.c72.png
neon | set to extreme | ±0 | max | max | colors.c73.png colors.c74.png

light and dark lower/highers saturation when value is min-/maximised respective.

the new color object

The opposites may not always take each other out. The color is maximised at white and black levels, so, for instance Image.Color.white->light()->dark() doesn't give the white color back, but the equal to Image.Color.white->dark(), since white can't get any lighter.

cast the object to an array, representing red, green and blue (equal to ->rgb()), or to a string, giving the name (equal to ->name()).

the name as string or rgb as array

rgb, name

This is methods of getting information from an Image.Color.Color object.

They give an array of red, green and blue (rgb) values (color value),
hue, saturation and value (hsv) values (range as color value),
cyan, magenta, yellow, black (cmyk) values (in percent)
or the greylevel value (range as color value).

The greylevel is calculated by weighting red, green and blue. Default weights are 87, 127 and 41, respective, and could be given by argument.

array(int) respective int

Image.Color.Color, grey

This is the main Image.Color.Color creation method, mostly for internal use.

Gives a new color, containing a grey color, which is calculated by the greylevel method.

a new Image.Color.Color object

greylevel

Information methods.

hex() simply gives a string on the #rrggbb format. If n is given, the number of significant digits is set to this number. (Ie, n=3 gives #rrrgggbbb.)

name() is a simplified method; if the color exists in the database, the name is returned, per default is the hex() method use.

html() gives the HTML name of the color, or the hex(2) if it isn't one of the 16 HTML colors.

a new Image.Color.Color object

rgb, hsv, Image.Color

Compares this object to another color, or color name. Example:

    object red=Image.Color.red;
    object other=Image.Color. ...;
    object black=Image.Color.black;

    if (red==other) ...
    if (red==({255,0,0})) ...
    if (black==0) ...
    if (red=="red") ...

1 or 0

The other datatype (not color object) must be to the right!

rgb, grey, name

Short technical documentation on a font file: This object adds the text-drawing and -creation capabilities of the Image module.

For simple usage, see write and load.

    	       struct file_head
    	       {
    		  unsigned INT32 cookie;   - 0x464f4e54
    		  unsigned INT32 version;  - 1
    		  unsigned INT32 chars;    - number of chars
    		  unsigned INT32 height;   - height of font
    		  unsigned INT32 baseline; - font baseline
    		  unsigned INT32 o[1];     - position of char_head's
    	       } *fh;
    	       struct char_head
    	       {
    		  unsigned INT32 width;    - width of this character
    		  unsigned INT32 spacing;  - spacing to next character
    		  unsigned char data[1];   - pixmap data (1byte/pixel)
    	       } *ch;

                version 2:

                	  On-disk syntax (everything in N.B.O), int is 4 bytes, a byte is 8 bits:

                pos
                	0   int cookie = 'FONT';     or 0x464f4e54
                	4   int version = 2;         1 was the old version without the last four chars
                	8   int numchars;            Always 256 in this version of the dump program
                12   int height;              in (whole) pixels
                16   int baseline;            in (whole) pixels
                20   char direction;          1==right to left, 0 is left to right
                21   char format;             Font format
                22   char colortablep;        Colortable format
                23   char kerningtablep;      Kerning table format

                24   int offsets[numchars];   pointers into the data, realative to &cookie.
                	    [colortable]
                	    [kerningtable]

                	  At each offset:

                0   int width;               in pixels
                4   int spacing;             in 1/1000:th of a pixels
                8   char data[];             Enough data to plot width * font->height pixels
                				    Please note that if width is 0, there is no data.

                Font formats:
                	id type
                	 0 Raw 8bit data
                	 1 RLE encoded data,  char length, char data,   70% more compact than raw data
                	 2 ZLib compressed data                         60% more compact than RLE

                Colortable types:
                	 0 No colortable		 (the data is an alpha channel)
                	 1 24bit RGB with alpha         (index->color, 256*4 bytes, rgba)
                	 2 8bit Greyscale with alpha    (index->color, 256*2 bytes)

                Kerningtable types:
                	 0 No kerning table
                	 1 numchars*numchars entries, each a signed char with the kerning value
                	 2 numchar entries, each with a list of kerning pairs, like this:
                	    int len
                	    len * (short char, short value)

Image, Image.Image

Loads a font file to this font object.

Returns zero upon failure and a font object upon success.

The path to the font file.

write

Image.Font

Loads a font file to this font object. Similar to load().

Writes some text; thus creating an image object that can be used as mask or as a complete picture. One or more text lines may be provided.

text_extents, load, Image.Image->paste_mask, Image.Image->paste_alpha_color

Image.Image

Returns the font height.

baseline, text_extents

Calculate extents of a text-image, that would be created by calling write with the same arguments. One or more lines of text may be provided.

width
height

write, height, baseline

Set spacing scale to write characters closer or more far away. This does not change scale of character, only the space between them.

Returns font baseline (pixels from top)

height, text_extents

Document this function.

Document this function.

Document this function.

This object keeps colortable information, mostly for image re-coloring (quantization).

The object has color reduction, quantisation, mapping and dithering capabilities.

Image, Image.Image, Image.Font, Image.GIF

Image.Image
Image.Image
Image.Image
Image.Image

create initiates a colortable object. Default is that no colors are in the colortable.

add takes the same argument(s) as create, thus adding colors to the colortable.

The colortable is mostly a list of colors, or more advanced, colors and weight.

The colortable could also be a colorcube, with or without additional scales. A colorcube is the by-far fastest way to find colors.

Example:

    ct=colortable(my_image,256); // the best 256 colors
    ct=colortable(my_image,256,({0,0,0})); // black and the best other 255

    ct=colortable(({({0,0,0}),({255,255,255})})); // black and white

    ct=colortable(6,7,6); // a colortable of 252 colors
    ct=colortable(7,7,5, ({0,0,0}),({255,255,255}),11);
            // a colorcube of 245 colors, and a greyscale of the rest -> 256

list of colors

source image

number of colors to get from the image

0 (zero) gives all colors in the image.

Default value is 256.

needed colors (to optimize selection of others to these given)

this will add to the total number of colors (see argument 'number')

size of sides in the colorcube, must (of course) be equal or larger than 2 - if smaller, the cube is ignored (no colors). This could be used to have only scales (like a greyscale) in the output.

This is to add the possibility of adding a scale of colors to the colorcube; for instance a grayscale using the arguments ({0,0,0}),({255,255,255}),17, adding a scale from black to white in 17 or more steps.

Colors already in the cube is used again to add the number of steps, if possible.

The total number of colors in the table is therefore r*b*g+step1+...+stepn.

max hash size is (probably, set by a #define) 32768 entries, giving maybe half that number of colors as maximum.

cast the colortable to an array or mapping, the array consists of Image.Color objects and are not in index order. The mapping consists of index:Image.Color pairs, where index is the index (int) of that color.

example: (mapping)Image.Colortable(img)

must be "string", "array" or "mapping".

Gives the eight corners in rgb colorspace as an array. The "black" and "white" corners are the first two.

Set the colortable to use the cubicles algorithm to lookup the closest color. This is a mostly very fast and very accurate way to find the correct color, and the default algorithm.

The colorspace is divided in small cubes, each cube containing the colors in that cube. Each cube then gets a list of the colors in the cube, and the closest from the corners and midpoints between corners.

When a color is needed, the algorithm first finds the correct cube and then compares with all the colors in the list for that cube.

example: colors=Image.Colortable(img)->cubicles();

algorithm time: between O[m] and O[m * n], where n is numbers of colors and m is number of pixels

The arguments can be heavy trimmed for the usage of your colortable; a large number (10×10×10 or bigger) of cubicles is recommended when you use the colortable repeatedly, since the calculation takes much more time than usage.

recommended values:

    image size  setup
    100×100     cubicles(4,5,4) (default)
    1000×1000   cubicles(12,12,12) (factor 2 faster than default)

In some cases, the full method is faster.

colortable.c0.png | colortable.c1.png | colortable.c2.png
original | default cubicles, 16 colors | accuracy=200

Size, ie how much the colorspace is divided. Note that the size of each cubicle is at least about 8b, and that it takes time to calculate them. The number of cubicles are r*g*b, and default is 4,5,4, ie 80 cubicles. This works good for 200±100 colors.

Accuracy when checking sides of cubicles. Default is 16. A value of 1 gives complete accuracy, ie cubicle() method gives exactly the same result as full(), but takes (in worst case) 16× the time to calculate.

the object being called

this method doesn't figure out the cubicles, this is done on the first use of the colortable.

Not applicable to colorcube types of colortable.

Set dithering method to floyd_steinberg.

The arguments to this method is for fine-tuning of the algorithm (for computer graphics wizards).

colortable.c3.png | colortable.c4.png | colortable.c5.png
original | floyd_steinberg to a 4×4×4 colorcube | floyd_steinberg to 16 chosen colors

Set algorithm direction of forward. -1 is backward, 1 is forward, 0 for toggle of direction each line (default).

Set error correction directions. Default is forward=7, downforward=1, down=5, downback=3.

Error keeping factor. Error will increase if more than 1.0 and decrease if less than 1.0. A value of 0.0 will cancel any dither effects. Default is 0.95.

the object being called

Set the colortable to use full scan to lookup the closest color.

example: colors=Image.Colortable(img)->full();

algorithm time: O[n*m], where n is numbers of colors and m is number of pixels

the object being called

Not applicable to colorcube types of colortable.

cubicles, map

cast the colortable to an image object

each pixel in the image object is an entry in the colortable

the resulting image object

Map colors in an image object to the colors in the colortable, and creates a new image with the closest colors.

| colortable.c6.png | colortable.c7.png | colortable.c8.png | colortable.c9.png | colortable.c10.png | no dither
| colortable.c11.png | colortable.c12.png | colortable.c13.png | colortable.c14.png | colortable.c15.png | floyd_steinberg dither
| colortable.c16.png | colortable.c17.png | colortable.c18.png | colortable.c19.png | colortable.c20.png | ordered dither
colortable.c21.png | colortable.c22.png | colortable.c23.png | colortable.c24.png | colortable.c25.png | colortable.c26.png | randomcube dither
original | 2 | 4 | 8 | 16 | 32 colors

a new image object

Flat (not cube) colortable and not 'full' method: this method does figure out the data needed for the lookup method, which may take time the first use of the colortable - the second use is quicker.

cubicles, full

Set no dithering (default).

the object being called

Set ordered dithering, which gives a position-dependent error added to the pixel values.

colortable.c27.png | colortable.c28.png | colortable.c29.png | colortable.c30.png
original | mapped to Image.Colortable(6,6,6)->
| ordered (42,42,42,2,2) | ordered() | ordered (42,42,42, 8,8, 0,0, 0,1, 1,0)
colortable.c31.png | colortable.c32.png | colortable.c33.png | colortable.c34.png

The maximum error. Default is 32, or colorcube steps (256/size).

Size of error matrix. Default is 8×8. Only values which factors to multiples of 2 and 3 are possible to choose (2,3,4,6,8,12,...).

Offset for the error matrix. x and y is for both red, green and blue values, the other is individual.

the object being called

randomcube, nodither, floyd_steinberg, create

Set random cube dithering. Color choosen is the closest one to color in picture plus (flat) random error; color±random(error).

The randomgrey method uses the same random error on red, green and blue and the randomcube method has three random errors.

colortable.c35.png | colortable.c36.png | colortable.c37.png
original | mapped to Image.Colortable(4,4,4)->
| randomcube() | randomgrey()
colortable.c38.png | colortable.c39.png | colortable.c40.png

The maximum error. Default is 32, or colorcube step.

the object being called

randomgrey method needs colorcube size to be the same on red, green and blue sides to work properly. It uses the red colorcube value as default.

ordered, nodither, floyd_steinberg, create

reduces the number of colors

All needed (see create) colors are kept.

reduce_fs creates and keeps the outmost corners of the color space, to improve floyd-steinberg dithering result. (It doesn't work very well, though.)

target number of colors

the new Colortable object

this algorithm assumes all colors are different to begin with (!)

reduce_fs keeps the "corners" as "needed colors".

corners

Set the colortable to use the "rigid" method of looking up colors.

This is a very simple way of finding the correct color. The algorithm initializes a cube with r x g x b colors, where every color is chosen by closest match to the corresponding coordinate.

This format is not recommended for exact match, but may be usable when it comes to quickly view pictures on-screen.

It has a high init-cost and low use-cost. The structure is initiated at first usage.

the object being called

Not applicable to colorcube types of colortable.

cubicles, map, full

Colortable tuning option, this sets the color space distance factors. This is used when comparing distances in the colorspace and comparing grey levels.

Default factors are 3, 4 and 1; blue is much darker than green. Compare with Image.Image->grey().

the object being called

This has no sanity check. Some functions may bug if the factors are to high - color reduction functions sums grey levels in the image, this could exceed maxint in the case of high factors. Negative values may also cause strange effects. *grin*

sums colortables

Colortable object with colors to add

the resulting new Colortable object

subtracts colortables

Colortable object with colors to subtract

the resulting new Colortable object

Image.Layer
Image.Layer
Image.Layer
Image.Layer

Combine layers.

a new layer object.

Image.Layer

layers

Image.Image
Image.Image
Image.Image
0
0

Set/change/get image and alpha channel for the layer. You could also cancel the channels giving 0 instead of an image object.

image and alpha channel must be of the same size, or canceled.

Set/get the general alpha value of this layer. This is a float value between 0 and 1, and is multiplied with the alpha channel.

0 1
0 1
0 1
0 1
0 1
0 1
0 1
0 1

This crops (of finds) a suitable crop, non-destructive crop. The layer alpha channel is checked, and edges that is transparent is removed.

(What really happens is that the image and alpha channel is checked, and edges equal the fill setup is cropped away.)

find_autocrop() returns an array of xoff,yoff,xsize,ysize, which can be fed to crop().

A tiled image will not be cropped at all.

left...bottom arguments can be used to tell what sides cropping are ok on.

crop, Image.Image->autocrop

Set/get layer mode. Mode is one of these:

The variables in the expression:
L
  The active layer
S
  The source layer (the sum of the layers below)
D
  The destintion layer (the result)
Xrgb
  Layer red (Xr), green (Xg) or blue channel (Xb)
Xhsv
  Layer hue (Xh), saturation (Xs) or value channel (Xv) (virtual channels)
Xhls
  Layer hue (Xh), lightness channel (Xl) or saturation (Xs) (virtual channels)
aX
  Layer alpha, channel in layer alpha

All channels are calculated separately, if nothing else is specified.

top layer
layers.c.0.jpeg |
bottom layer
layers.c.1.jpeg |
normal
layers.c.2.jpeg | D=L applied with alpha: D=(L*aL+S*(1-aL)*aS) / (aL+(1-aL)*aS), aD=(aL+(1-aL)*aS)
add
layers.c.3.jpeg | D=L+S applied with alpha, aD=aS
subtract
layers.c.4.jpeg | D=S-L applied with alpha, aD=aS
multiply
layers.c.5.jpeg | D=S*L applied with alpha, aD=aS
divide
layers.c.6.jpeg | D=S/L applied with alpha, aD=aS
negdivide
layers.c.7.jpeg | D=1.0-S/L applied with alpha, aD=aS
modulo
layers.c.8.jpeg | D=S%L applied with alpha, aD=aS
invsubtract
layers.c.9.jpeg | D=L-S applied with alpha, aD=aS
invdivide
layers.c.10.jpeg | D=L/S applied with alpha, aD=aS
invmodulo
layers.c.11.jpeg | D=L%S applied with alpha, aD=aS
imultiply
layers.c.12.jpeg | D=(1-L)*S applied with alpha, aD=aS
idivide
layers.c.13.jpeg | D=S/(1-L) applied with alpha, aD=aS
invidivide
layers.c.14.jpeg | D=L/(1-S) applied with alpha, aD=aS
difference
layers.c.15.jpeg | D=abs(L-S) applied with alpha, aD=aS
max
layers.c.16.jpeg | D=max(L,S) applied with alpha, aD=aS
min
layers.c.17.jpeg | D=min(L,S) applied with alpha, aD=aS
bitwise_and
layers.c.18.jpeg | D=L&amp;S applied with alpha, aD=aS
bitwise_or
layers.c.19.jpeg | D=L|S applied with alpha, aD=aS
bitwise_xor
layers.c.20.jpeg | D=L^S applied with alpha, aD=aS
replace
layers.c.21.jpeg | D=(L*aL+S*(1-aL)*aS) / (aL+(1-aL)*aS), aD=aS
red
layers.c.22.jpeg | Dr=(Lr*aLr+Sr*(1-aLr)*aSr) / (aLr+(1-aLr)*aSr), Dgb=Sgb, aD=aS
green
layers.c.23.jpeg | Dg=(Lg*aLg+Sg*(1-aLg)*aSg) / (aLg+(1-aLg)*aSg), Drb=Srb, aD=aS
blue
layers.c.24.jpeg | Db=(Lb*aLb+Sb*(1-aLb)*aSb) / (aLb+(1-aLb)*aSb), Drg=Srg, aD=aS
hardlight
layers.c.25.jpeg | Like photoshop hardlight layer mode, aD=aS
replace_hsv
layers.c.26.jpeg | Dhsv=Lhsv apply with alpha, aD=aS
hue
layers.c.27.jpeg | Dh=Lh apply with alpha, Dsv=Lsv, aD=aS
saturation
layers.c.28.jpeg | Ds=Ls apply with alpha, Dhv=Lhv, aD=aS
value
layers.c.29.jpeg | Dv=Lv apply with alpha, Dhs=Lhs, aD=aS
color
layers.c.30.jpeg | Dhs=Lhs apply with alpha, Dv=Lv, aD=aS
value_mul
layers.c.31.jpeg | Dv=Lv*Sv apply with alpha, Dhs=Lhs, aD=aS
darken
layers.c.32.jpeg | Dv=min(Lv,Sv) apply with alpha, Dhs=Lhs, aD=aS
lighten
layers.c.33.jpeg | Dv=max(Lv,Sv) apply with alpha, Dhs=Lhs, aD=aS
saturate
layers.c.34.jpeg | Ds=max(Ls,Ss) apply with alpha, Dhv=Lhv, aD=aS
desaturate
layers.c.35.jpeg | Ds=min(Ls,Ss) apply with alpha, Dhv=Lhv, aD=aS
hls_replace
layers.c.36.jpeg | Dhls=Lhls apply with alpha, aD=aS
hls_hue
layers.c.37.jpeg | Dh=Lh apply with alpha, Dsv=Lsv, aD=aS
hls_saturation
layers.c.38.jpeg | Ds=Ls apply with alpha, Dhv=Lhv, aD=aS
hls_lightness
layers.c.39.jpeg | Dl=Ll apply with alpha, Dhs=Lhs, aD=aS
hls_color
layers.c.40.jpeg | Dhs=Lhs apply with alpha, Dl=Ll, aD=aS
hls_lightness_mul
layers.c.41.jpeg | Dl=Ll*Sl apply with alpha, Dhs=Lhs, aD=aS
hls_darken
layers.c.42.jpeg | Dl=min(Ll,Sl) apply with alpha, Dhs=Lhs, aD=aS
hls_lighten
layers.c.43.jpeg | Dl=max(Ll,Sl) apply with alpha, Dhs=Lhs, aD=aS
hls_saturate
layers.c.44.jpeg | Ds=max(Ls,Ss) apply with alpha, Dhl=Lhl, aD=aS
hls_desaturate
layers.c.45.jpeg | Ds=min(Ls,Ss) apply with alpha, Dhl=Lhl, aD=aS
dissolve
layers.c.46.jpeg | i=random 0 or 1, D=i?L:S, aD=i+aS
behind
layers.c.47.jpeg | D=(S*aS+L*(1-aS)*aL) / (aS+(1-aS)*aL), aD=(aS+(1-aS)*aL); simply swap S and L
erase
layers.c.48.jpeg | D=S, aD=aS*(1-aL)
screen
layers.c.49.jpeg | 1-(1-S)*(1-L) applied with alpha, aD=aS
overlay
layers.c.50.jpeg | (1-(1-a)*(1-b)-a*b)*a+a*b applied with alpha, aD=aS
burn_alpha
layers.c.51.jpeg | aD=aL+aS applied with alpha, D=L+S; experimental, may change or be removed
equal
layers.c.52.jpeg | each channel D=max if L==S, 0 otherwise, apply with alpha
not_equal
layers.c.53.jpeg | each channel D=max if L!=S, 0 otherwise, apply with alpha
less
layers.c.54.jpeg | each channel D=max if L<S, 0 otherwise, apply with alpha
more
layers.c.55.jpeg | each channel D=max if L>S, 0 otherwise, apply with alpha
less_or_equal
layers.c.56.jpeg | each channel D=max if L<=S, 0 otherwise, apply with alpha
more_or_equal
layers.c.57.jpeg | each channel D=max if L>=S, 0 otherwise, apply with alpha
logic_equal
layers.c.58.jpeg | logic: D=white and opaque if L==S, black and transparent otherwise
logic_not_equal
layers.c.59.jpeg | logic: D=white and opaque if any L!=S, black and transparent otherwise
logic_strict_less
layers.c.60.jpeg | logic: D=white and opaque if all L<S, black and transparent otherwise
logic_strict_more
layers.c.61.jpeg | logic: D=white and opaque if all L>S, black and transparent otherwise
logic_strict_less_equal
layers.c.62.jpeg | logic: D=white and opaque if all L<=L, black and transparent otherwise
logic_strict_more_equal
layers.c.63.jpeg | logic: D=white and opaque if all L>=L, black and transparent otherwise

available_modes() simply gives an array containing the names of these modes.

image and alpha channel must be of the same size, or canceled.

([ "xsize":int, "ysize":int, "image":image, "alpha":image, "xoffset":int, "yoffset":int, "fill":image, "fill_alpha":image "tiled":int, "mode":string ])

Creates a copy of the called object.

the copy

The Layer construct either three arguments, the image object, alpha channel and mode, or a mapping with optional elements:

    "image":image,
            // default: black

    "alpha":alpha,
            // alpha channel object
            // default: full opaque

    "mode":string mode,
            // layer mode, see mode.
            // default: "normal"

    "alpha_value":float(0.0-1.0),
            // layer general alpha value
            // default is 1.0; this is multiplied
            // with the alpha channel.

    "xoffset":int,
    "yoffset":int,
            // offset of this layer

    "fill":Color,
    "fill_alpha":Color,
            // fill color, ie what color is used
            // "outside" the image. default: black
            // and black (full transparency).

    "tiled":int(0|1),
            // select tiling; if 1, the image
            // will be tiled. deafult: 0, off

The layer can also be created "empty", either giving a size and color - this will give a filled opaque square, or a color, which will set the "fill" values and fill the whole layer with an opaque color.

All values can be modified after object creation.

image and alpha channel must be of the same size.

Crops this layer at this offset and size. Offset is not relative the layer offset, so this can be used to crop a number of layers simuntaneously.

The fill values are used if the layer is enlarged.

a new layer object

The new layer object may have the same image object, if there was no cropping to be done.

Layer descriptions

Color
Color
Color

Set/query fill color and alpha, ie the color used "outside" the image. This is mostly useful if you want to "frame" a layer.

Set or query misc. attributes for the layer.

As an example, the XCF and PSD image decoders set the 'name' attribute to the name the layer had in the source file.

Set/query layer offset.

Set/query tiled flag. If set, the image and alpha channel will be tiled rather then framed by the fill values.

Query layer offset. This is the same as layer image/alpha image size.

Attempts to decode data as image data. The heuristics has some limited ability to decode macbinary files as well.

Attempts to decode data as image layer data. Additional arguments to the various formats decode_layers method can be passed through opt.

Image.Layer

Reads the file file and, if the file is compressed with gzip or bzip, attempts to decompress it by calling gzip and bzip2 in a Process.create_process call.

Loads in a file, which need not be an image file. If no argument is given the data will be taken from stdin. If a file object is given, it will be read to the end of the file. If a string is given the function will first attempt to load a file with that name, then try to download data with the string as URL. Zero will be returned upon failure.

Loads a file with load_file and decodes it with _decode.

Helper function to load an image layer from a file. If no filename is given, Stdio.stdin is used. The loaded file is decoded with _decode.

Image.Layer

Helper function to load all image layers from a file. If no filename is given, Stdio.stdin is used. The loaded file is decoded with decode_layers. Extra arguments to the image types layer decoder, e.g. for XCF files, can be given in the opts mapping.

Image.Layer

Helper function to load an image from a file. If no filename is given, Stdio.stdin is used. The loaded file is decoded with _decode.

Image.Image

Generates a filled circle of the dimensions xd x yd (or d x d). The Image is a white circle on black background; the layer function defaults to a white circle (the background is transparent).

Image.Image
Image.Image
Image.Layer
Image.Layer
Image.Color.Color
Image.Layer
Image.Color.Color
Image.Layer
Image.Layer
Image.Layer

Abstracted Font-handling support. Should be used instead of accessing the FreeType, TTF and Image.Font modules directly.

The abstract Font class. The file is a valid font-file, size is in pixels, but the size of the characters to be rendered, not the height of the finished image (the image is generally speaking bigger then the size of the characters).

The amount of 'boldness' that should be added to the font when text is rendered.

If true, make the font italic.

0 1

Returns ({ xsize, ysize }) of the image that will result if lines is sent as the argument to write.

Returns some information about the font. Always included: file: Filename specified when the font was opened size: Size specified when the font was opened family: Family name style: Bitwise or of the style flags, i.e. ITALIC and BOLD.

Render the text strings sent as line as an alpha-channel image.

Image.Image

The font is/should be italic

The font is/should be bold

Used in open_font() to specify that no fake bold or italic should be attempted.

Find a suitable font in the directories specified with set_font_dirs.

flags is a bitwise or of 0 or more of ITALIC, BOLD and NO_FAKE.

fontname is the human-readable name of the font.

If force is true, a font is always returned (defaulting to arial or the pike builtin font), even if no suitable font is found.

Font

Returns a list of all the fonts as a mapping.

Set the directories where fonts can be found.

Reads the dimensions of images of various image formats without decoding the actual image.

Reads the dimensions from a JPEG file and returns an array with width and height, or if the file isn't a valid image, 0.

Stdio.File

Reads the dimensions from a GIF file and returns an array with width and height, or if the file isn't a valid image, 0.

Stdio.File

Reads the dimensions from a PNG file and returns an array with width and height, or if the file isn't a valid image, 0.

Stdio.File

Reads the dimensions from a TIFF file and returns an array with width and height, or if the file isn't a valid image, 0.

Stdio.File

Read dimensions from a JPEG, GIF, PNG or TIFF file and return an array with width and height, or if the file isn't a valid image, 0. The argument file should be either a path to a file or a file object. The offset pointer will be assumed to be at the start of the file and will be modified by the function.

Stdio.File

Decodes a PSD image to a mapping, defined as follows.

- 1 24 "channels"

The number of channels in the image, including any alpha channels.

- 1 30000 "height"
- 1 30000 "width"

The image dimensions.

- 0 1 "compression"

1 if the image is compressed, 0 if not.

- 1 1 8 8 16 16 "depth"

The number of bits per channel.

- 0 4 7 9 "mode"

The color mode of the file.

0

Bitmap

1

Greyscale

2

Indexed

3

RGB

4

CMYK

7

Multichannel

8

Duotone

9

Lab

- "color_data"

Raw color data.

- "image_data"

Ram image data.

- "resources"

Additional image data. Se mappping below.

- "layers"

An array with the layers of the image. See mapping below.

The resources mapping. Unknown resources will be identified by their ID number (as an int).

- "caption"

Image caption.

- "url"

Image associated URL.

- "active_layer"

Which layer is active.

- "guides"

An array with all guides stored in the image file.

- "pos"

The position of the guide.

- 0 1 "vertical"

1 if the guide is vertical, 0 if it is horizontal.

- "resinof"

Resolution information

- "hres"
- "hres_unit"
- "width_unit"
- "vres"
- "vres_unit"
- "height_unit"

FIXME: Document these.

The layer mapping:

- "top"
- "left"
- "right"
- "bottom"

The rectangle containing the contents of the layer.

- "mask_top"
- "mask_left"
- "mask_right"
- "mask_bottom"
- "mask_flags"

FIXME: Document these

- 0 255 "opacity"

0=transparent, 255=opaque.

- "clipping"

0=base, 1=non-base.

- "flags"

bit 0=transparency protected bit 1=visible

- "mode"

Blend mode.

"norm"

Normal

"dark"

Darken

"lite"

Lighten

"hue "

Hue

"sat "

Saturation

"colr"

Color

"lum "

Luminosity

"mul "

Multiply

"scrn"

Screen

"diss"

Dissolve

"over"

Overlay

"hLit"

Hard light

"sLit"

Soft light

"diff"

Difference

- "extra_data"

Raw extra data.

- "name"

The name of the layer

- "channels"

The channels of the layer. Each array element is a mapping as follows

- "id"

The ID of the channel

-2

User supplied layer mask

-1

Transparency mask

0

Red

1

Green

2

Blue

- "data"

The image data

Decodes a PSD image to an array of Image.Layer objects

Takes the same aptions mapping as _decode, note especially "draw_all_layers":1, but implements "crop_to_bounds" which preserves the bounding box for the whole image (i.e. discards data that extend outside of the global bounds).

The layer object have the following extra variables (to be queried using Image.Layer()->get_misc_value):

"image_guides"

Returns array containing guide definitions.

"name"

Returns string containing the name of the layer.

"visible"

Is 1 of the layer is visible and 0 if it is hidden.

Image.Layer

Decodes a PSD image to a mapping, with at least an 'image' and possibly an 'alpha' object. Data is either a PSD image, or a mapping (as received from __decode)

- Image.Color "background"

Sets the background to the given color. Arrays should be in the format ({r,g,b}).

- 0 1 "draw_all_layers"

Draw invisible layers as well.

- 0 1 "draw_guides"

Draw the guides.

- 0 1 "draw_selection"

Mark the selection using an overlay.

- 0 1 "ignore_unknown_layer_modes"

Do not asume 'Normal' for unknown layer modes.

- 0 1 "mark_layers"

Draw an outline around all (drawn) layers.

- Image.Font "mark_layer_names"

Write the name of all layers using the font object,

- 0 1 "mark_active_layer"

Draw an outline around the active layer

- Image.Image "image"

The image object.

- Image.Image "alpha"

The alpha channel image object.

Throws upon error in data. For more information, see __decode

Decodes a PSD image to a single image object.

Throws upon error in data. To get access to more information like alpha channels and layer names, see _decode and __decode.

Image.Image

This module decodes the thumbnail raster images embedded in AutoCAD DWG files for AutoCAD version R13, R14 and R2000 (which equals to file version 12, 14 and 15). Implemented according to specifications from http://www.opendwg.org/.

Decodes the DWG data into a mapping.

- "version"

The version of the DWG file. One of 12, 14 and 15.

- "bmp"

An array with the raw BMP data.

- "wmf"

An array with the raw WMF data.

This functions throws an error when decoding somehow fails.

Works like __decode, but in addition it has the element "image" in the result mapping, containing the first successfully decoded bitmap image. to the result of decode(data).

If no preview was stored, or no preview could be decoded an error is thrown.

Returns the first successfully decoded bitmap image.

If no preview was stored, or no preview could be decoded an error is thrown.

Image.Image

Codec for the Adobe page description language PostScript. Uses Ghostscript for decoding or built-in support.

Decodes the postscript data into an image object using Ghostscript.

Optional decoding parameters.

- "dpi"

The resolution the image should be rendered in. Defaults to 100.

- "device"

The selected Ghostscript device. Defaults to "ppmraw".

- "binary"

Path to the Ghostscript binary to be used. If missing the environment paths will be searched for a file "gs" to be used instead.

- 0 1 "force_gs"

Forces use of Ghostscript for EPS files instead of Pikes native support.

- 0 1 "eps_crop"

Use -dEPSCrop option to Ghostscript to crop the BoundingBox for a EPS file.

- 0 1 "cie_color"

Use -dUseCIEColor option to Ghostscript for mapping color values through a CIE color space.

Calls decode and returns the image in the "image" index of the mapping. This method is present for API reasons.

Encodes the image object img as a postscript 3.0 file.

Optional extra encoding parameters.

- "dpi"

The resolution of the encoded image. Defaults to 100.

- 0 1 "eps"

If the resulting image should be an eps instead of ps. Defaults to 0, no.

Same as encode. Present for API reasons.

``

Represents information about a hash algorithm, such as name, digest size, and internal block size.

Returns a human readable name for the algorithm.

Returns the size of a hash digests.

Returns the internal block size of the hash algorithm.

Base class for hashing contexts.

Hashes more data.

HashState

Generates a digests, and resets the hashing contents.

If the length argument is provided, the digest is truncated to the given length.

The digest.

Internal mixin class, intended to be multiply inherited together with HashInfo.

State for MD5 hashing.

Internal mixin class, intended to be multiply inherited together with HashInfo.

State for MD4 hashing.

Internal mixin class, intended to be multiply inherited together with HashInfo.

State for MD2 hashing.

Internal mixin class, intended to be multiply inherited together with HashInfo.

State for SHA1 hashing.

Internal mixin class, intended to be multiply inherited together with HashInfo.

State for SHA256 hashing.

Low level crypto functions used by the Crypto module. Unless you are doing something very special, you would want to use the Crypto module instead.

Yarrow is a family of pseudo-randomness generators, designed for cryptographic use, by John Kelsey, Bruce Schneier and Niels Ferguson. Yarrow-160 is described in a paper at http://www.counterpane.com/yarrow.html, and it uses SHA1 and triple-DES, and has a 160-bit internal state. Nettle implements Yarrow-256, which is similar, but uses SHA256 and AES to get an internal state of 256 bits.

The number of entropy sources that will feed entropy to the random number generator is given as an argument to Yarrow during instantiation.

update

The random generator needs to be seeded before it can be used. The seed must be at least 32 characters long. The seed could be stored from a previous run by inserting the value returned from get_seed.

Returns the called object.

min_seed_size, get_seed, is_seeded

Yarrow

Returns the minimal number of characters that the seed needs to properly seed the random number generator.

seed

0

Returns part of the internal state so that it can be saved for later seeding.

seed

Returns 1 if the random generator is seeded and ready to generator output. 0 otherwise.

seed

0
1

By calling this function entropy is moved from the slow pool to the fast pool. Read more about Yarrow before using this.

Inject additional entropy into the random number generator.

create

0
1

The number of sources that must reach the threshold before a slow reseed will happen.

0

Returns a pseudo-random string of the requested length.

Does the crypt_md5 abrakadabra (MD5 + snakeoil). It is assumed that salt does not contain "$".

Represents information about a cipher algorithm, such as name, key size, and block size.

A human readable name for the algorithm.

The recommended key size for the cipher.

The block size of the cipher (1 for stream ciphers).

Base class for hashing contexts.

Initializes the object for encryption.

set_decrypt_key, crypt

CipherState

Initializes the object for decryption.

set_encrypt_key, crypt

CipherState

Generate a key by calling Crypto.Random.random_string and initialize this object for encryption with that key.

The generated key.

set_encrypt_key

Encrypts or decrypts data, using the current key.

For block ciphers, data must be an integral number of blocks.

The encrypted or decrypted data.

The actual key size for this cipher.

Internal mixin class, intended to be multiply inherited together with CipherInfo.

State for AES encyption

Internal mixin class, intended to be multiply inherited together with CipherInfo.

State for ARCFOUR encyption

Internal mixin class, intended to be multiply inherited together with CipherInfo.

State for Blowfish encyption

Internal mixin class, intended to be multiply inherited together with CipherInfo.

State for CAST128 encyption

Internal mixin class, intended to be multiply inherited together with CipherInfo.

Sets the last bit in every byte in key to reflect the parity. If a seven byte key is used, it will be expanded into eight bytes. If a key longer than eight characters is used, it will be truncated to eight characters.

State for DES encyption

Internal mixin class, intended to be multiply inherited together with CipherInfo.

Sets the last bit in every byte in key to reflect the parity. If a 21 byte key is used, it will be expanded into 24 bytes. If a key longer than 24 characters is used, it will be truncated to 24 characters.

State for DES3 encyption

Internal mixin class, intended to be multiply inherited together with CipherInfo.

State for Serpent encyption

Internal mixin class, intended to be multiply inherited together with CipherInfo.

State for Twofish encyption

Internal mixin class, intended to be multiply inherited together with CipherInfo.

State for IDEA encyption

Splits the input string into an array of words, on the boundaries between the different kinds of word characters as defined by is_wordchar. The result is an array of words, with the non-word characters between them thrown away.

A less wasteful equivalent of split_words(normalize(input)).

Normalize the given unicode string according to the specified method.

The methods are:

NFC, NFD, NFKC and NFKD.

The methods are described in detail in the UAX #15 document, which can currently be found at http://www.unicode.org/unicode/reports/tr15/tr15-21.html

A short description:

C and D specifies whether to decompose (D) complex characters to their parts, or compose (C) single characters to complex ones.

K specifies whether or not do a canonical or compatibility conversion. When K is present, compatibility transformations are performed as well as the canonical transformations.

In the following text, 'X' denotes the single character 'X', even if there is more than one character inside the quotation marks. The reson is that it's somewhat hard to describe unicode in iso-8859-1.

The Unicode Standard defines two equivalences between characters: canonical equivalence and compatibility equivalence. Canonical equivalence is a basic equivalency between characters or sequences of characters.

'Å' and 'A' '° (combining ring above)' are canonically equivalent.

For round-trip compatibility with existing standards, Unicode has encoded many entities that are really variants of existing nominal characters. The visual representations of these character are typically a subset of the possible visual representations of the nominal character. These are given compatibility decompositions in the standard. Because the characters are visually distinguished, replacing a character by a compatibility equivalent may lose formatting information unless supplemented by markup or styling.

Examples of compatibility equivalences:

Font variants (thin, italic, extra wide characters etc)

Circled and squared characters

super/subscript ('²' -> '2')

Fractions ('½' -> '1/2')

Other composed characters ('fi' -> 'f' 'i', 'kg' -> 'k' 'g')

Returns whether a unicode character c is a word, part of a word or not.

2

The character is an ideograph (a CJK single-word character)

1

The character is a letter, number or non-spacing mark, as defined by its unicode (general category) specification

0

Any other character (such as symbols, punctuation and separators)

This is an interface to the mSQL database server. This module may or may not be availible on your Pike, depending whether the appropriate include and library files (msql.h and libmsql.a respectively) could be found at compile-time. Note that you do not need to have a mSQL server running on your host to use this module: you can connect to the database over a TCP/IP socket

Please notice that unless you wish to specifically connect to a mSQL server, you'd better use the Sql.Sql program instead. Using Sql.Sql ensures that your Pike applications will run with any supported SQL server without changing a single line of code.

Also notice that some functions may be mSQL/2.0-specific, and thus missing on hosts running mSQL/1.0.*

The mSQL C API has some extermal dependencies. They take the form of certain environment variables which, if defined in the environment of the pike interpreter, influence the interface's behavior. Those are "MSQL_TCP_PORT" which forces the server to connect to a port other than the default, "MSQL_UNIX_PORT", same as above, only referring to the UNIX domain sockets. If you built your mSQL server with the default setttings, you shouldn't worry about these. The variable MINERVA_DEBUG can be used to debug the mSQL API (you shouldn't worry about this either). Refer to the mSQL documentation for further details.

Also note that THIS MODULE USES BLOCKING I/O to connect to the server. mSQL should be reasonably fast, but you might want to consider this particular aspect. It is thread-safe, and so it can be used in a multithread environment.

Although it seems that mSQL/2.0 has some support for server statistics, it's really VERY VERY primitive, so it won't be added for now.

Sql.Sql

This function shuts a SQL-server down.

This function forces a server to reload its ACLs.

This function is not part of the standard interface, so it is not availible through the Sql.Sql interface, but only through Sql.msql and Msql.msql programs.

create

With one argument, this function tries to connect to the specified (use hostname or IP address) database server. To connect to a server running on the local host via UNIX domain sockets use "localhost". To connect to the local host via TCP/IP sockets you have to use the IP address "127.0.0.1". With two arguments it also selects a database to use on the server. With no arguments it tries to connect to the server on localhost, using UNIX sockets.

You need to have a database selected before using the sql-object, otherwise you'll get exceptions when you try to query it. Also notice that this function can raise exceptions if the db server doesn't respond, if the database doesn't exist or is not accessible by you.

You don't need bothering about syncronizing the connection to the database: it is automatically closed (and the database is sync-ed) when the msql object is destroyed.

select_db

Returns an array containing the names of all databases availible on the system. Will throw an exception if there is no server connected. If an argument is specified, it will return only those databases whose name matches the given glob.

Returns an array containing the names of all the tables in the currently selected database. Will throw an exception if we aren't connected to a database. If an argument is specified, it will return only those tables whose name matches the given glob.

Before querying a database you have to select it. This can be accomplished in two ways: the first is calling the create function with two arguments, another is calling it with one or no argument and then calling select_db. You can also use this function to change the database you're querying, as long as it is on the same server you are connected to.

This function CAN raise exceptions in case something goes wrong (for example: unexistant database, insufficient permissions, whatever).

create, error

This is all you need to query the database. It takes as argument an SQL query string (i.e.: "SELECT foo,bar FROM baz WHERE name like '%kinkie%'" or "INSERT INTO baz VALUES ('kinkie','made','this')") and returns a data structure containing the returned values. The structure is an array (one entry for each returned row) of mappings which have the column name as index and the column contents as data. So to access a result from the first example you would have to do "results[0]->foo".

A query which returns no data results in an empty array (and NOT in a 0). Also notice that when there is a column name clash (that is: when you join two or more tables which have columns with the same name), the clashing columns are renamed to <tablename>+"."+<column name>. To access those you'll have to use the indexing operator '[] (i.e.: results[0]["foo.bar"]).

Errors (both from the interface and the SQL server) are reported via exceptions, and you definitely want to catch them. Error messages are not particularly verbose, since they account only for errors inside the driver. To get server-related error messages, you have to use the error function.

Note that if the query is NOT a of SELECT type, but UPDATE or MODIFY, the returned value is an empty array. This is not an error. Errors are reported only via exceptions.

error

This function returns a string describing the server we are talking to. It has the form "servername/serverversion" (like the HTTP protocol description) and is most useful in conjunction with the generic SQL-server module.

This function returns a string describing what host are we talking to, and how (TCP/IP or UNIX sockets).

This function returns the textual description of the last server-related error. Returns 0 if no error has occurred yet. It is not cleared upon reading (can be invoked multiple times, will return the same result until a new error occurs).

query

This function creates a new database with the given name (assuming we have enough permissions to do this).

drop_db

This function destroys a database and all the data it contains (assuming we have enough permissions to do so). USE WITH CAUTION!

create_db

Returns a mapping describing the fields of a table in the database. The returned value is a mapping, indexed on the column name, of mappings.The glob argument, if present, filters out the fields not matching the glob. These contain currently the fields:

- "type"

Describes the field's mSQL data type ("char","integer",...)

- "length"

It describes the field's length. It is only interesting for char() fields, in fact. Also notice that the strings returned by msql->query() have the correct length. This field only specifies the _maximum_ length a "char()" field can have.

- "table"

The table this field is in. Added only for interface compliancy.

- "flags"

It's a multiset containing textual descriptions of the server's flags associated with the current field. Currently it can be empty, or contain "unique" or "not null".

The version of this function in the Msql.msql() program is not sql-interface compliant (this is the main reason why using that program directly is deprecated). Use Sql.Sql instead.

query

This function returns how many rows in the database were affected by our last SQL query.

This function is availible only if you're using mSQL version 2 or later. (That means: if the includes and library of version 2 of mSQL were availible when the module was compiled).

This function is not part of the standard interface, so it is not availible through the Sql.Sql interface, but only through Sql.msql and Msql.msql programs

This function returns an array describing the index structure for the given table and index name, as defined by the non-standard SQL query 'create index' (see the mSQL documentation for further informations). More than one index can be created for a table. There's currently NO way to have a listing of the indexes defined for a table (blame it on the mSQL API).

This function is availible if you're using mSQL version 2 or later.

This function is not part of the standard interface, so it is not availible through the Sql.Sql interface, but only through Sql.msql and Msql.msql programs.

Should you need to report a bug to the author, please submit along with the report the driver version number, as returned by this call.

_SimpleRegexp
``

Regexp objects can be encoded and decoded.

encode_value, decode_value

This class implements the interface to a simple regexp engine with the following capabilities:

. Matches any character. [abc] Matches a, b or c. [a-z] Matches any character a to z inclusive. [^ac] Matches any character except a and c. (x) Matches x (x might be any regexp) If used with split, this also puts the string matching x into the result array. x* Matches zero or more occurances of 'x' (x may be any regexp). x+ Matches one or more occurances of 'x' (x may be any regexp). x|y Matches x or y. (x or y may be any regexp). xy Matches xy (x and y may be any regexp). ^ Matches beginning of string (but no characters). $ Matches end of string (but no characters). \< Matches the beginning of a word (but no characters). \> Matches the end of a word (but no characters).

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.

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 laters calls to e.g. match or split. Calling create() without an argument can be used to free up a little memory after the regexp has been used.

Returns 1 if str matches the regexp bound to the regexp object. Zero otherwise.

Returns an array containing strings in strs that match the regexp bound to the regexp object.

The current implementation doesn't support searching in strings containing the NUL character or any wide character.

split

Works as match, but returns an array of the strings that matched the subregexps. Subregexps are those contained in "( )" in the regexp. Subregexps that were not matched will contain zero. If the total regexp didn't match, zero is returned.

You can currently only have 39 subregexps.

The current implementation doesn't support searching in strings containing the NUL character or any wide character.

match

"___"

Convenience/compatibility method to get a SimpleRegexp object.

SimpleRegexp

Calls Regexp.PCRE.Plain.match in a temporary regexp object. Faster to type but slower to run...

0
1

Calls Regexp.PCRE.Plain.split in a temporary regexp object. Faster to type but slower to run...

Calls Regexp.PCRE.Plain.split2 in a temporary regexp object. Faster to type but slower to run...

Calls Regexp.PCRE.Plain.replace in a temporary regexp object. Faster to type but slower to run...

``

The option bits are:

OPTION.ANCHORED

Force pattern anchoring

OPTION.CASELESS

Do caseless matching

OPTION.DOLLAR_ENDONLY

$ not to match newline at end

OPTION.DOTALL

. matches anything including NL

OPTION.EXTENDED

Ignore whitespace and # comments

OPTION.EXTRA

PCRE extra features (not much use currently)

OPTION.MULTILINE

^ and $ match newlines within data

OPTION.NO_AUTO_CAPTURE

Disable numbered capturing parentheses (named ones available)

OPTION.UNGREEDY

Invert greediness of quantifiers

OPTION.UTF8

Run in UTF-8 mode

(from the pcreapi man-page) "When a pattern is going to be used several times, it is worth spending more time analyzing it in order to speed up the time taken for match- ing."

Returns additional information about a compiled pattern. Only available if PCRE was compiled with Fullinfo.

- "backrefmax"

Return the number of the highest back reference in the pattern. The fourth argument should point to an int variable. Zero is returned if there are no back references.

- "capturecount"

Return the number of capturing subpatterns in the pattern. The fourth argument should point to an int variable.

- "firstbyte"

Return information about the first byte of any matched string, for a non-anchored pattern. (This option used to be called PCRE_INFO_FIRSTCHAR; the old name is still recognized for backwards compatibility.)

If there is a fixed first byte, e.g. from a pattern such as (cat|cow|coyote), it is returned in the integer pointed to by where. Otherwise, if either

(a) the pattern was compiled with the PCRE_MULTILINE option, and every branch starts with "^", or

(b) every branch of the pattern starts with ".*" and PCRE_DOTALL is not set (if it were set, the pattern would be anchored),

-1 is returned, indicating that the pattern matches only at the start of a subject string or after any newline within the string. Otherwise -2 is returned. For anchored patterns, -2 is returned.

- "lastliteral"

Return the value of the rightmost literal byte that must exist in any matched string, other than at its start, if such a byte has been recorded. The fourth argument should point to an int variable. If there is no such byte, -1 is returned. For anchored patterns, a last literal byte is recorded only if it follows something of variable length. For example, for the pattern /^a\d+z\d+/ the returned value is "z", but for /^a\dz\d/ the returned value is -1.

- "namecount"
- "nameentrysize"
- "options"

Return a copy of the options with which the pattern was compiled. The fourth argument should point to an unsigned long int variable. These option bits are those specified in the call to pcre_compile(), modified by any top-level option settings within the pattern itself.

A pattern is automatically anchored by PCRE if all of its top-level alternatives begin with one of the following:

^unless PCRE_MULTILINE is set \A always \G always .*if PCRE_DOTALL is set and there are no back references to the subpattern in which .* appears

For such patterns, the PCRE_ANCHORED bit is set in the options returned.

- "size"

Return the size of the compiled pattern, that is, the value that was passed as the argument to pcre_malloc() when PCRE was getting memory in which to place the compiled data. The fourth argument should point to a size_t variable.

- "studysize"

Returns the size of the data block pointed to by the study_data field in a pcre_extra block. That is, it is the value that was passed to pcre_malloc() when PCRE was getting memory into which to place the data created by pcre_study(). The fourth argument should point to a size_t variable.

match a regexp; will return an array of 2*n integers where n is the number of hits; returns an int upon failure

Error codes:

ERROR.NOMATCH

The subject string did not match the pattern.

ERROR.NULL

Either code or subject was passed as NULL, or ovector was NULL and oversize was not zero.

ERROR.BADOPTION

An unrecognized bit was set in the options argument.

ERROR.BADMAGIC

PCRE stores a 4-byte "magic number" at the start of the compiled code, to catch the case when it is passed a junk pointer. This is the error it gives when the magic number isn't present.

ERROR.UNKNOWN_NODE

While running the pattern match, an unknown item was encountered in the compiled pattern. This error could be caused by a bug in PCRE or by overwriting of the compiled pattern.

ERROR.NOMEMORY

If a pattern contains back references, but the ovector that is passed to pcre_exec() is not big enough to remember the referenced substrings, PCRE gets a block of memory at the start of matching to use for this purpose. If the call via pcre_malloc() fails, this error is given. The memory is freed at the end of matching.

ERROR.NOSUBSTRING

This error is used by the pcre_copy_substring(), pcre_get_substring(), and pcre_get_substring_list() functions (see below). It is never returned by pcre_exec().

ERROR.MATCHLIMIT

The recursion and backtracking limit, as specified by the match_limit field in a pcre_extra structure (or defaulted) was reached. See the description above.

ERROR.CALLOUT

This error is never generated by pcre_exec() itself. It is provided for use by callout functions that want to yield a distinctive error code. See the pcrecallout documentation for details.

returns the number of a named subpattern

contains all option constants

(from the pcreapi manpage) If this bit is set, the pattern is forced to be "anchored", that is, it is constrained to match only at the first matching point in the string which is being searched (the "subject string"). This effect can also be achieved by appropriate constructs in the pattern itself, which is the only way to do it in Perl.

(from the pcreapi manpage) If this bit is set, letters in the pattern match both upper and lower case letters. It is equivalent to Perl's /i option, and it can be changed within a pattern by a (?i) option setting.

(from the pcreapi manpage) If this bit is set, a dollar metacharacter in the pattern matches only at the end of the subject string. Without this option, a dollar also matches immediately before the final character if it is a newline (but not before any other newlines). The PCRE_DOLLAR_ENDONLY option is ignored if PCRE_MULTILINE is set. There is no equivalent to this option in Perl, and no way to set it within a pattern.

(from the pcreapi manpage) If this bit is set, a dot metacharater in the pattern matches all characters, including newlines. Without it, newlines are excluded. This option is equivalent to Perl's /s option, and it can be changed within a pattern by a (?s) option setting. A negative class such as [^a] always matches a newline character, independent of the setting of this option.

(from the pcreapi manpage) If this bit is set, whitespace data characters in the pattern are totally ignored except when escaped or inside a character class. Whitespace does not include the VT character (code 11). In addition, characters between an unescaped # outside a character class and the next newline character, inclusive, are also ignored. This is equivalent to Perl's /x option, and it can be changed within a pattern by a (?x) option setting.

This option makes it possible to include comments inside complicated patterns. Note, however, that this applies only to data characters. Whitespace characters may never appear within special character sequences in a pattern, for example within the sequence (?( which introduces a conditional subpattern.

(from the pcreapi manpage) This option was invented in order to turn on additional functionality of PCRE that is incompatible with Perl, but it is currently of very little use. When set, any backslash in a pattern that is followed by a letter that has no special meaning causes an error, thus reserving these combinations for future expansion. By default, as in Perl, a backslash followed by a letter with no special meaning is treated as a literal. There are at present no other features controlled by this option. It can also be set by a (?X) option setting within a pattern.

(from the pcreapi manpage) By default, PCRE treats the subject string as consisting of a single "line" of characters (even if it actually contains several newlines). The "start of line" metacharacter (^) matches only at the start of the string, while the "end of line" metacharacter ($) matches only at the end of the string, or before a terminating newline (unless PCRE_DOL- LAR_ENDONLY is set). This is the same as Perl.

When PCRE_MULTILINE it is set, the "start of line" and "end of line" constructs match immediately following or immediately before any new- line in the subject string, respectively, as well as at the very start and end. This is equivalent to Perl's /m option, and it can be changed within a pattern by a (?m) option setting. If there are no "\n" charac- ters in a subject string, or no occurrences of ^ or $ in a pattern, setting PCRE_MULTILINE has no effect.

(from the pcreapi manpage) If this option is set, it disables the use of numbered capturing paren- theses in the pattern. Any opening parenthesis that is not followed by ? behaves as if it were followed by ?: but named parentheses can still be used for capturing (and they acquire numbers in the usual way). There is no equivalent of this option in Perl.

(from the pcreapi manpage) This option inverts the "greediness" of the quantifiers so that they are not greedy by default, but become greedy if followed by "?". It is not compatible with Perl. It can also be set by a (?U) option setting within the pattern.

(from the pcreapi manpage) This option causes PCRE to regard both the pattern and the subject as strings of UTF-8 characters instead of single-byte character strings. However, it is available only if PCRE has been built to include UTF-8 support. If not, the use of this option provokes an error. Details of how this option changes the behaviour of PCRE are given in the section on UTF-8 support in the main pcre page.

Documented in exec.

Convenience function that splits a subject string on the result from _pcre->exec()

equal to map(previous_result/2, lambda(array v) { return subject[v[0]..v[1]-1]; })

(from the pcreapi man-page) "The output is an integer that is set to one if UTF-8 support is available; otherwise it is set to zero." This constant is calculated when the module is initiated by using pcre_config(3).

(from the pcreapi man-page) "The output is an integer that is set to the value of the code that is used for the newline character. It is either linefeed (10) or carriage return (13), and should normally be the standard character for your operating system." This constant is calculated when the module is initiated by using pcre_config(3).

(from the pcreapi man-page) "The output is an integer that contains the number of bytes used for internal linkage in compiled regular expressions. The value is 2, 3, or 4. Larger values allow larger regular expressions to be compiled, at the expense of slower match- ing. The default value of 2 is sufficient for all but the most massive patterns, since it allows the compiled pattern to be up to 64K in size." This constant is calculated when the module is initiated by using pcre_config(3).

(from the pcreapi man-page) "The output is an integer that contains the threshold above which the POSIX interface uses malloc() for output vectors. Further details are given in the pcreposix documentation." This constant is calculated when the module is initiated by using pcre_config(3).

(from the pcreapi man-page) "The output is an integer that gives the default limit for the number of internal matching function calls in a pcre_exec() execution. Further details are given with pcre_exec() below." This constant is calculated when the module is initiated by using pcre_config(3).

The main regexp class. Will provide anything needed for matching regexps.

There are subclasses that adds wrappers for widestrings, and to optimize the regexp pattern.

_pcre

Matches a subject against the pattern, returns an array where the first element are the whole match, and the subsequent are the matching subpatterns. Returns 0 if there was no match.

example: > Regexp.PCRE.Plain("i\(.*\) is \(.*\)u")->split2("pike is fun"); Result: ({ "ike is fu", "ke", "f" })

0
0

Matches a subject against the pattern, compatible with the old split method: returns an array of the subpatterns, or if there are no subpattern but still a match, ({0}). Returns 0 if there was no match.

example: > Regexp.PCRE.Plain("i\(.*\) is \(.*\)u")->split("pike is fun"); (1) Result: ({ "ke", "f" }) > Regexp.PCRE.Plain("is fun")->split("pike is fun"); (4) Result: ({ 0 })

0
0

returns true (1) if a match is found, false otherwise

example: > Regexp.PCRE.Plain("is fun")->match("pike is fun"); Result: 1 > Regexp.PCRE.Plain("is fun")->match("pike isn't fun"); Result: 0

0
1

replace all occurances of a pattern in a subject; callbacks and replacements will be from the first occurance, not from the last as in Regexp.Builtin.replace.

example: > Regexp.PCRE("b[^-]*m")->replace("abam-boom-fooabadoom","gurka"); Result: "agurka-gurka-fooagurka" > Regexp.PCRE("b[^-]*m")->replace("abam-boom-fooabadoom", lambda(string s) { werror("%O\n",s); return "gurka"; }); "bam" "boom" "badoom" Result: "agurka-gurka-fooagurka"

``

replace one (first) occurance of a pattern in a subject

example: > Regexp.PCRE("b[^-]*m")->replace1("abam-boom-fooabadoom","gurka"); Result: "agurka-boom-fooabadoom"

``

Will give a callback for each match in a subject. Called arguments will be matching patterns and subpatterns in an array and as second argument the exec result array.

returns called object

example: > Regexp.PCRE("b(a*)([^-\1234]*)(\1234*)m") ->matchall("abam-boom-fooabado\1234m", lambda(mixed s) { werror("%O\n",s); return "gurka"; }); ({ /* 4 elements */ "bam", "a", "", "" }) ({ /* 4 elements */ "boom", "", "oo", "" }) ({ /* 4 elements */ "bado\1234m", "a", "do", "\1234" }) Result: Regexp.PCRE.StudiedWidestring("b(a*)([^-Ê\234]*)(Ê\234*)m")

``
this_program

Same as Plain, but will be studied to match faster; useful if you're doing many matches on the same pattern

Plain

Wrapper class around Plain, that will allow widestring patterns and subjects.

Widestring support and this class will not be implemented if the linked libpcre lacks UTF8 support.

Plain

The exec function is wrapped to give the correct indexes for the widestring.

Same as Widestring, but will be studied to match faster; useful if you're doing many matches on the same pattern

Widestring
"___"

Convenience function to create a suitable PCRE Regexp object; will create a StudiedWidestring from the arguments.

That means the result will be able to handle widestrings, and will produce fast matchings by studying the pattern, but the widestring wrapping will on the other hand add overhead.

If you need a faster regexp and doesn't use widestring, create a Regexp.PCRE.Studied instead.

Widestring support will not be used if the linked libpcre lacks UTF8 support. This can be tested with checking that the Regexp.PCRE.Widestring class exist.

GOOD
0 1

Decodes an http transport-encoded string.

Encodes the in data as an HTML safe string.

Represents an angle.

The actual keeper of the angle value.

The type of the angle value. Is either "deg", "rad", "gon" or "str".

If an angle object is created without arguments it will have the value 0 radians.

Returns a copy of the object.

Angle

Gets the value in the provided type.

Sets the angle value and type to the given value and type.

Angle

Normalizes the angle to be within one turn.

Returns the number of degrees, including minutes and seconds as decimals.

Returns the number of minute.

Returns the number of seconds.

Set degrees, minues and seconds. Returns the current angle object.

Angle
Angle
Angle

Returns degrees, minutes and seconds as a string, e.g. 47°6'36.00".

Sets the angle to the provided degree. Alters the type to degrees. Returns the current object.

Angle

Returns the number of gons.

Set the angle to the provided gons. Alters the type to gons. Returns the current angle object.

Angle

Returns the number of radians.

Set the angle to the provided radians. Alters the type to radians. Returns the current angle object.

Angle

Returns the number of strecks.

Set the angle to the provided strecks. Alters the type to streck. Returns the current angle object.

Angle

Turns the direction of the angle half a turn. Equal to add(180,"deg").

Turns the direction of the angle a quarter of a turn to the right. Equal to subtract(90,"deg").

Turns the direction of the angle a quarter of a turn to the left. Equal to add(90,"deg").

Returns the sinus for the angle.

Returns the cosinus for the angle.

Returns the tangen for the angle.

An angle can be casted to float, int and string.

Returns the sum of this angle and what it is added with. If added with an angle, a new angle object is returnes.

Angle
Angle

Adds the provided angle to the current angle. The result is normalized within 360 degrees.

Angle
Angle
Angle
Angle

Returns the difference between this angle and the provided value. If differenced with an angle, a new angle object is returned.

Angle
Angle

Subtracts the provided angle from the current angle. The result is normalized within 360 degrees.

Angle
Angle
Angle
Angle

Returns the product between this angle and the provided value. If differenced with an angle, a new angle object is returned.

Angle
Angle

Returns the fraction between this angle and the provided value. If differenced with an angle, a new angle object is returned.

Angle
Angle

Returns this result of this angle modulo the provided value. If differenced with an angle, a new angle object is returned.

Angle
Angle

Compares the unnormalized angle of two Angle objects.

Angle

Compares the unnormalized angle of two Angle objects.

Angle

Compares the unnormalized angle of two Angle objects.

Angle
"___"

This function converts between degrees, radians and gons. The from and to arguments may be any of the follwoing strings: "deg", "rad", "gon" and "str" for degrees, radians, gon and streck respectivly. The output is not guaranteed to be within the first turn, e.g. converting 10 radians yields almost 573 degrees as output.

Calculate binomial koefficient n choose k.

This is equvivalent to n!/(k!*(n-k)!).

The 10-logarithm of x.

Factorize the integer x. The returned list of factors will be sorted biggest to smallest factor.

This function is only available when Pike has been compiled with bignums.

Matrix representation with double precision floating point values.

Initializes the matrix as a 1D or 2D matrix, e.g. Math.Matrix( ({({1,2}),({3,4})}) ).

Initializes the matrix as to be a n*m matrix with init in every value. If no third argument is given, or the third argument is "identity", the matrix will be initialized with all zeroes except for the diagonal which will be 1.

When type is "identity" the matrix is initializes as a square identity matrix.

When type is "rotate" the matrix is initialized as a rotation matrix.

Matrix

It is possible to cast the matrix to an array and get back a double array of floats with the matrix values.

vect

Return all the elements of the matrix as an array of numbers

Returns the transpose of the matrix as a new object.

Matrix

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

Matrix

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

Matrix
Matrix
Matrix

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

Matrix
Matrix
Matrix
Matrix

Produces the sum of all the elements in the matrix.

Matrix

Produces the maximum or minimum value of all the elements in the matrix.

Matrix
Matrix

Matrix multiplication.

Matrix
Matrix
Matrix

Matrix cross-multiplication.

Matrix

Matrix dot product.

Convolve called matrix with the argument.

Matrix

Matrix representation with single precision floating point values.

Matrix

Matrix representation with 64 bit integer values.

Matrix

Matrix representation with 32 bit integer values.

Matrix

Matrix representation with 16 bit integer values.

Matrix

Returns the FFT of the input array. The input must be real and the output is complex. The output consists of an array. It's first element is the amplitudes and the second element is the phases.

The array of floats and/or ints to transform.

rIFFT(rFFT()) returns the input array scaled by n=sizeof(input array). This is due to the nature of the DFT algorithm.

rIFFT()

Returns the inverse FFT of the input array. The input must be complex and guaranteed to generate a real output.

The input is an array. It's first element is the amplitudes and the second element is the phases.

The output is an array of the real values for the iFFT.

The array of floats and/or ints to transform.

rIFFT(rFFT()) returns the input array scaled by n=sizeof(input array). This is due to the nature of the DFT algorithm.

rFFT()

Creates a new transform object. If n is specified, a plan is created for transformations of n-size arrays.

Size of the transform to be preformed. Note that the transform object will be initialized for this size, but if an array of different size is sent to the object, it will be reinitialized. This can be used to gain preformace if all transforms will be of a given size.

If exact is 1, a "better" plan for the transform will be created. This will take more time though. Use only if preformance is needed.

0 1

The constant pi (3.14159265358979323846).

The constant e (2.7182818284590452354).

Floating point infinity.

Floating point not-a-number (e.g. inf/inf).

``
``
``
``

The CommonLog module is used to parse the lines in a www server's logfile, which must be in "common log" format -- such as used by default for the access log by Roxen, Caudium, Apache et al.

Reads the log file and calls the callback function for every parsed line. For lines that fails to be parsed the callback is not called not is any error thrown. The number of bytes read are returned.

The callbacks first argument is an array with the different parts of the log entry.

remote_host
0 0 ident_user
0 0 auth_user
year
month
day
hours
minutes
seconds
timezone
0 0 method

One of "GET", "POST", "HEAD" etc.

0 0 path
protocol

E.g. "HTTP/1.0"

reply_code

One of 200, 404 etc.

bytes

The second callback argument is the current offset to the end of the current line.

The position in the file where the parser should begin.

``
Stdio.File

Implements Digital Video Broadcasting interface

Only Linux version is supported.

Main class.

Create a DVB object.

The number of card equipment.

The number specifies which device will be opened. Ie. /dev/ost/demux0, /dev/ost/demux1 ... for DVB v0.9.4 or /dev/dvb/demux0, /dev/dvb/demux1 ... for versions 2.0+

Return status of a DVB object's frondend device.

The resulting mapping contains the following fields:

- "power"

If 1 the frontend is powered up and is ready to be used.

- "signal"

If 1 the frontend detects a signal above a normal noise level

- "lock"

If 1 the frontend successfully locked to a DVB signal

- "carrier"

If 1 carrier dectected in signal

- "biterbi"

If 1 then lock at viterbi state

- "sync"

If 1 then TS sync byte detected

- "tuner_lock"

If 1 then tuner has a frequency lock

Return info of a frondend device.

The information heavily depends on driver. Many fields contain dumb values.

Tunes to apropriate transponder's parameters.

DiSeQc number of LNB.

Frequency divided by 1000.

Polarization. 0 or "v" for vertical type, 1 or "h" for horizontal one.

The service rate parameter.

0 3
0 1

Returns mapping with info of currently tuned program's pids.

tune()

Return mapping of all PMT.

sid:prognum

Parse PMT table.

analyze_pat()

Create a new stream reader object for PID.

PID of stream.

Callback function called whenever there is the data to read from stream. Only for nonblocking mode.

Type of payload data to read. By default, audio data is fetched.

Setting async callback doesn't set the object to nonblocking state.

DVB.Stream()->read()

``
DVB.Stream
``
DVB.Stream
DVB.Stream

Represents an elementary data stream (PES).

Purge a stream reader.

DVB.dvb()->stream(), read()

Read data from a stream. It reads up to read buffer size data.

Read buffer size is 4096 by default.

DVB.dvb()->stream(), close()

Closes an open stream.

read()

Object for controlling an audio subsystem on full featured cards.

Create a Audio object.

The number of card equipment.

Mute or unmute audio device.

Returns mapping of current audio device status.

Sets output level on DVB audio device.

This module allows access to an embedded Perl interpreter, if a libperl.so (or equivalent) was found during the installation of Pike.

An object of this class is a Perl interpreter.

Create a Perl interpreter object. There can only be one Perl interpreter object at the same time, unless Perl was compiled with the MULTIPLICITY option, and Pike managed to figure this out during installation. An error will be thrown if no Perl interpreter is available.

Parse a Perl script file and set up argument and environment for it. Returns zero on success, and non-zero if the parsing failed.

Arguments in the style of argv, i.e. with the name of the script first.

Environment mapping, mapping environment variable names to to their values.

Run a previously parsed Perl script file. Returns a status code.

Evalute a Perl expression in a scalar context, and return the result if it is a simple value type. Unsupported value types are rendered as 0.

Evalute a Perl expression in a list context, and return the result if it is a simple value type, or an array of simple value types. Unsupported value types are rendered as 0.

Call a Perl subroutine in a scalar context, and return the result if it is a simple value type. Unsupported value types are rendered as 0.

The name of the subroutine to call, as an 8-bit string.

Zero or more arguments to the function. Only simple value types are supported. Unsupported value types will cause an error to be thrown.

Call a Perl subroutine in a list context, and return the result if it is a simple value type, or an array of simple value types. Unsupported value types are rendered as 0.

The name of the subroutine to call, as an 8-bit string.

Zero or more arguments to the function. Only simple value types are supported. Unsupported value types will cause an error to be thrown.

Get the value of a Perl scalar variable. Returns the value, or a plain 0 if the value type was not supported.

Name of the scalar variable, as an 8-bit string.

Set the value of a Perl scalar variable.

Name of the scalar variable, as an 8-bit string.

The new value. Only simple value types are supported. Throws an error for unsupported value types.

Get the value of an entry in a Perl array variable. Returns the value, or a zero-type value if indexing outside the array, or a plain zero if the value type was not supported.

Name of the array variable, as an 8-bit string.

Array index. An error is thrown if the index is negative, non-integer or a bignum.

Set the value of an entry in a Perl array variable. Only simple value types are supported. Throws an error for unsupported value types.

Name of the array variable, as an 8-bit string.

Array index. An error is thrown if the index is negative, non-integer or a bignum.

New value. Only simple value types are supported. An error is thrown for unsupported value types.

Get the value of an entry in a Perl hash variable. Returns the value, or a zero-type value if the hash had no entry for the given key, or a plain 0 if the returned value type was not supported.

Name of the array variable, as an 8-bit string.

Hash key. Only simple value types are supported. An error is thrown for unsupported value types.

Set the value of an entry in a Perl hash variable.

Name of the hash variable, as an 8-bit string.

Hash key. Only simple value types are supported. An error is thrown for unsupported value types.

New value. Only simple value types are supported. An error is thrown for unsupported value types.

Get the size of the Perl array variable with the given name.

Name of the array variable, as an 8-bit string.

Get the contents of a Perl array variable as a Pike array. If the size of the array is larger than the specified array size limit, the returned Pike array will be truncated according to the limit.

Name of the array variable, as an 8-bit string.

array_size_limit()

Get the keys (indices) of a Perl hash variable as a Pike array. If the size of the resulting array is larger than the specified array size limit, an error will be thrown.

Name of the hash variable, as an 8-bit string.

array_size_limit()

Get (and optionally set) the array size limit for this interpreter instance. Without arguments, the current limit is returned. With an integer argument, the limit is set to that value, and the same value is returned.

The array size limit is mainly a way of ensuring that there isn't a sudden explosion in memory usage and data conversion time in this embedding interface. There is no particular limit other than available memory in Perl itself.

The default array size limit is 500 elements, but this may change in future releases of Pike.

The maximum array size limit is the highest number representable as a non-bignum integer (which is typically 2147483647 on a traditional 32-bit architecture).

The new array size limit.

This module enables access to the SANE (Scanner Access Now Easy) library from pike

This method returns an array where every element is a mapping, layed out as follows.

- "name"
- "title"
- "desc"
- "type"
"boolean"
"int"
"float"
"string"
"button"
"group"
- "unit"
"none"
"pixel"
"bit"
"mm"
"dpi"
"percent"
"microsend"
- "size"
- "cap"
"soft_select"
"hard_select"
"emulate"
"automatic"
"inactive"
"advanced"
- 0 0 "constraint"

Constraints can be of three different types; range, word list or string list. Constraint contains 0 if there are no constraints.

- "type"

Contains the value "range".

- "max"
- "min"
- "quant"
- "type"

Contains the value "list".

- "list"
- "type"

Contains the value "list".

- "list"

If no value is specified, the option is set to it's default value

- "format"
- "last_frame"
- "lines"
- "depth"
- "pixels_per_line"
- "bytes_per_line"
Image.Image
`Image.ImageScanner`
`Image.ImageScanner`

Returns an array with all available scanners.

Pike v0.7 release 120 running Hilfe v2.0 (Incremental Pike Frontend) > SANE.list_scanners(); Result: ({ ([ "model":"Astra 1220S ", "name":"umax:/dev/scg1f", "type":"flatbed scanner", "vendor":"UMAX " ]), ([ "model":"Astra 1220S ", "name":"net:lain.idonex.se:umax:/dev/scg1f", "type":"flatbed scanner", "vendor":"UMAX " ]) })

Resets the getpwent function to the first entry in the passwd source using the systemfunction setpwent(3).

Always 0 (zero)

get_all_users() getpwent() endpwent()

Closes the passwd source opened by getpwent function using the systemfunction endpwent(3).

Always 0 (zero)

get_all_users() getpwent() setpwent()

When first called, the getpwent function opens the passwd source and returns the first record using the systemfunction getpwent(3). For each following call, it returns the next record until EOF.

Call endpwent when done using getpwent.

An array with the information about the user

0

Users username (loginname)

1

User password (encrypted)

2

Users ID

3

Users primary group ID

4

Users real name an possibly some other info

5

Users home directory

6

Users shell

0 if EOF.

get_all_users() getpwnam() getpwent() setpwent() endpwent()

Rewinds the getgrent pointer to the first entry

get_all_groups() getgrent() endgrent()

Closes the /etc/groups file after using the getgrent function.

get_all_groups() getgrent() setgrent()

Get a group entry from /etc/groups file. getgrent interates thru the groups source and returns one entry per call using the systemfunction getgrent(3).

Always call endgrent when done using getgrent!

An array with the information about the group

0

Group name

1

Group password (encrypted)

2

ID of the group

3

Array with UIDs of group members

get_all_groups() getgrnam() getgrgid()

A popular demand is a class representing a raw piece of memory or a mmap'ed file. This is usually not the most effective way of solving a problem, but it might help in rare situations.

Using mmap can lead to segmentation faults in some cases. Beware, and read about mmap before you try anything. Don't blame Pike if you shoot your foot off.

Will call mmap() or allocate() depending on argument, either mmap'ing a file (in shared mode, writeable if possible) or allocating a chunk of memory.

Stdio.File

mmap a file. This will always try to mmap the file in PROT_READ|PROT_WRITE, readable and writable, but if it fails it will try once more in PROT_READ only.

Stdio.File
Stdio.File
Stdio.File
Stdio.File
0 255

Free the allocated or <tt>mmap</tt>ed memory.

returns the size of the memory (bytes). note: throws if not allocated

returns 1 if the memory is valid, 0 if not allocated

0
1

returns 1 if the memory is writeable, 0 if not

0
1

Cast to string or array.

Throws if not allocated.

Read a string from the memory. The 16 and 32 variants reads widestrings, 16 or 32 bits (2 or 4 bytes) wide, the i variants in intel byteorder, the normal in network byteorder, and the n variants in native byteorder.

len is the number of characters, wide or not. pos is the byte position (!).

0
0
0
0
0
0
0
0
0
0
0
0
0
0

Write a string to the memory (and to the file, if it's mmap()ed). The 16 and 32 variants writes widestrings, 16 or 32 bits (2 or 4 bytes) wide, the 'i' variants in intel byteorder, the other in network byteorder.

returns the number of bytes (not characters) written

0
0
0
0
0

Get a single value from the register.

One of the following:

HKEY_CLASSES_ROOT
HKEY_LOCAL_MACHINE
HKEY_CURRENT_USER
HKEY_USERS

Registry key.

Value name.

Returns the value stored at the specified location in the register if any. Throws errors on failure.

This function is only available on Win32 systems.

RegGetValues(), RegGetKeyNames()

Get a list of value key names from the register.

One of the following:

HKEY_CLASSES_ROOT
HKEY_LOCAL_MACHINE
HKEY_CURRENT_USER
HKEY_USERS

A registry key.

Returns an array of value keys stored at the specified location if any. Throws errors on failure.

> RegGetKeyNames(HKEY_CURRENT_USER, "Keyboard Layout"); (1) Result: ({ "IMEtoggle", "Preload", "Substitutes", "Toggle" })

This function is only available on Win32 systems.

RegGetValue(), RegGetValues()

Get multiple values from the register.

One of the following:

HKEY_CLASSES_ROOT
HKEY_LOCAL_MACHINE
HKEY_CURRENT_USER
HKEY_USERS

Registry key.

Returns a mapping with all the values stored at the specified location in the register if any. Throws errors on failure.

> RegGetValues(HKEY_CURRENT_USER, "Keyboard Layout\\Preload"); (5) Result: ([ "1":"0000041d" ])

This function is only available on Win32 systems.

RegGetValue(), RegGetKeyNames()

Logon a user.

User name of the user to login.

Domain to login on, or zero if local logon.

Password to login with.

One of the following values:

LOGON32_LOGON_BATCH
LOGON32_LOGON_INTERACTIVE
LOGON32_LOGON_SERVICE
LOGON32_LOGON_NETWORK

This is the default.

One of the following values:

LOGON32_PROVIDER_DEFAULT

This is the default.

Returns a login token object on success, and zero on failure.

This function is only available on some Win32 systems.

0 0

Get information about a network user.

User name of the user to get information about.

Server the user exists on.

Information level. One of:

0
1
2
3
10
11
20

Returns an array on success. Throws errors on failure.

Document the return value.

This function is only available on some Win32 systems.

NetUserEnum(), NetGroupEnum() NetLocalGroupEnum(), NetUserGetGroups(), NetUserGetLocalGroups(), NetGroupGetUsers(), NetLocalGroupGetMembers(), NetGetDCName(), NetGetAnyDCName()

0 0

Get information about network users.

Server the users exist on.

Information level. One of:

0
1
2
3
10
11
20

Returns an array on success. Throws errors on failure.

Document the return value.

This function is only available on some Win32 systems.

NetUserGetInfo(), NetGroupEnum() NetLocalGroupEnum(), NetUserGetGroups(), NetUserGetLocalGroups(), NetGroupGetUsers(), NetLocalGroupGetMembers(), NetGetDCName(), NetGetAnyDCName()

0 0

Get information about network groups.

Server the groups exist on.

Information level. One of:

0
1
2

Returns an array on success. Throws errors on failure.

Document the return value.

This function is only available on some Win32 systems.

NetUserGetInfo(), NetUserEnum(), NetLocalGroupEnum(), NetUserGetGroups(), NetUserGetLocalGroups(), NetGroupGetUsers(), NetLocalGroupGetMembers(), NetGetDCName(), NetGetAnyDCName()

0 0

Get information about local network groups.

Server the groups exist on.

Information level. One of:

0
1

Returns an array on success. Throws errors on failure.

Document the return value.

This function is only available on some Win32 systems.

NetUserGetInfo(), NetUserEnum(), NetGroupEnum(), NetUserGetGroups(), NetUserGetLocalGroups(), NetGroupGetUsers(), NetLocalGroupGetMembers(), NetGetDCName(), NetGetAnyDCName()

0 0

Get information about group membership for a network user.

Server the groups exist on.

User to retrieve groups for.

Information level. One of:

0
1

Returns an array on success. Throws errors on failure.

Document the return value.

This function is only available on some Win32 systems.

NetUserGetInfo(), NetUserEnum(), NetGroupEnum(), NetLocalGroupEnum(), NetUserGetLocalGroups(), NetGroupGetUsers(), NetLocalGroupGetMembers(), NetGetDCName(), NetGetAnyDCName()

0 0

Get information about group membership for a local network user.

Server the groups exist on.

User to retrieve groups for.

Information level. One of:

0

Zero, of one of the following:

LG_INCLUDE_INDIRECT

Returns an array on success. Throws errors on failure.

Document the return value.

This function is only available on some Win32 systems.

NetUserGetInfo(), NetUserEnum(), NetGroupEnum(), NetLocalGroupEnum(), NetUserGetGroups(), NetGroupGetUsers(), NetLocalGroupGetMembers(), NetGetDCName(), NetGetAnyDCName()

0 0

Get information about group membership for a network group.

Server the groups exist on.

Group to retrieve members for.

Information level. One of:

0
1

Returns an array on success. Throws errors on failure.

Document the return value.

This function is only available on some Win32 systems.

NetUserGetInfo(), NetUserEnum(), NetGroupEnum(), NetLocalGroupEnum(), NetUserGetGroups(), NetUserGetLocalGroups(), NetLocalGroupGetMembers(), NetGetDCName(), NetGetAnyDCName()

0 0

Get information about group membership for a network group.

Server the groups exist on.

Group to retrieve members for.

Information level. One of:

0
1
2
3

Returns an array on success. Throws errors on failure.

Document the return value.

This function is only available on some Win32 systems.

NetUserGetInfo(), NetUserEnum(), NetGroupEnum(), NetLocalGroupEnum(), NetUserGetGroups(), NetUserGetLocalGroups(), NetGroupGetUsers(), NetGetDCName(), NetGetAnyDCName()

0 0

Get name of the domain controller from a server.

Server the domain exists on.

Domain to get the domain controller for.

Returns the name of the domain controller on success. Throws errors on failure.

This function is only available on some Win32 systems.

NetUserGetInfo(), NetUserEnum(), NetGroupEnum(), NetLocalGroupEnum(), NetUserGetGroups(), NetUserGetLocalGroups(), NetGroupGetUsers(), NetLocalGroupGetMembers(), NetGetAnyDCName()

0 0

Get name of a domain controller from a server.

Server the domain exists on.

Domain to get a domain controller for.

Returns the name of a domain controller on success. Throws errors on failure.

This function is only available on some Win32 systems.

NetUserGetInfo(), NetUserEnum(), NetGroupEnum(), NetLocalGroupEnum(), NetUserGetGroups(), NetUserGetLocalGroups(), NetGroupGetUsers(), NetLocalGroupGetMembers(), NetGetDCName()

0 0

Get session information.

One of

0
1
2
10
502

This function is only available on some Win32 systems.

0 0
0 0
0 0

One of

0
1

This function is only available on some Win32 systems.

0 0

Normalize an NT filesystem path.

The following transformations are currently done:

Trailing slashes are removed.

Extraneous empty extensions are removed.

Short filenames are expanded to their corresponding long variants.

Forward slashes ('/') are converted to backward slashes ('\').

Current- and parent-directory paths are removed ("." and "..").

Relative paths are expanded to absolute paths.

Case-information is restored.

A normalized absolute path without trailing slashes.

Throws errors on failure, e.g. if the file or directory doesn't exist.

File fork information is currently not supported (invalid data).

combine_path(), combine_path_nt()

Get the file attributes for the specified file.

This function is only available on Win32 systems.

SetFileAttributes()

Set the file attributes for the specified file.

This function is only available on Win32 systems.

GetFileAttributes()

This function is only available on some Win32 systems.

0 0

This function is only available on some Win32 systems.

GetNamedSecurityInfo()

This function is only available on some Win32 systems.

SetNamedSecurityInfo()

Initializes the connection to syslogd.

The ident argument specifies an identifier to tag all logentries with.

A bitfield specifying the behaviour 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.

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
LOG_LOCAL1
LOG_LOCAL2
LOG_LOCAL3
LOG_LOCAL4
LOG_LOCAL5
LOG_LOCAL6
LOG_LOCAL7

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

Only available on systems with syslog(3).

LOG_NOWAIT should probably always be specified.

syslog, closelog

facility

Document this function.

Document this function.

This module embodies common operating system calls, making them available to the Pike programmer.

Create a hardlink named to from the file from.

This function is not available on all platforms.

symlink(), mv(), rm()

Create a symbolic link named to that points to from.

This function is not available on all platforms.

hardlink(), readlink(), mv(), rm()

Returns what the symbolic link path points to.

This function is not available on all platforms.

symlink()

Resolve all symbolic links of a pathname.

This function is not available on all platforms.

readlink(), symlink()

Set the current umask to mask.

If mask is not specified the current umask will not be changed.

Returns the old umask setting.

Sets the protection mode of the specified path.

Throws errors on failure.

Stdio.File->open(), errno()

Sets the owner and group of the specified path.

Throws errors on failure.

This function is not available on all platforms.

Set the last access time and last modification time for the path path to atime and mtime repectively.

Throws errors on failure.

This function is not available on all platforms.

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

Throws errors on failure.

This function is not available on all platforms.

setuid(), getuid(), setgid(), getgid(), seteuid(), geteuid(), setegid(), getegid(), getgroups(), setgroups()

Clear the supplemental group access list.

Throws errors on failure.

This function is not available on all platforms.

setgroups(), initgroups(), getgroups()

Set the supplemental group access list for this process.

Throws errors on failure.

This function is not available on all platforms.

initgroups(), cleargroups(), getgroups(), getgid(), getgid(), getegid(), setegid()

Get the current supplemental group access list for this process.

Throws errors on failure.

This function is not available on all platforms.

setgroups(), cleargroups(), initgroups(), getgid(), getgid(), getegid(), setegid()

Searches for matching entries in the netgroup database (usually /etc/netgroup). If any of the machine, user or domain arguments are zero or missing, those fields will match any value in the selected netgroup.

This function isn't available on all platforms.

0
1

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

Returns the current errno.

This function isn't available on all platforms.

getuid(), setgid(), getgid(), seteuid(), geteuid(), setegid(), getegid()

Sets the real group ID, effective group ID and saved group ID to gid. If gid is -1 the uid for "nobody" will be used.

Throws an error if no "nobody" user when gid is -1.

Returns the current errno.

This function is not available on all platforms.

getuid(), setuid(), getgid(), seteuid(), geteuid(), setegid(), getegid()

Set the effective user ID to euid. If euid is -1 the uid for "nobody" will be used.

Returns the current errno.

Throws an error if there is no "nobody" user when euid is -1.

This function isn't available on all platforms.

Set the effective group ID to egid. If egid is -1 the uid for "nobody" will be used.

Returns the current errno.

Throws an error if there is no "nobody" user when egid is -1.

This function isn't available on all platforms.

Get the process group id for the process pid. With no argguments or with 'pid' equal to zero, returns the process group ID of this process.

Not all platforms support getting the process group for other processes.

Not supported on all platforms.

getpid, getppid

Make this process a process group leader.

Not supported on all platforms.

Get the process session ID for the given process. If pid is not specified, the session ID for the current process will be returned.

This function is not available on all platforms.

Throws an error if the system call fails.

getpid, getpgrp, setsid

Set a new process session ID for the current process, and return it.

This function isn't available on all platforms.

Throws an error if the system call fails.

getpid, setpgrp, getsid

Get and/or set whether this process should be able to dump core.

Optional argument to set the core dumping state.

0

Disable core dumping for this process.

1

Enable core dumping for this process.

Returns 1 if this process currently is capable of dumping core, and 0 (zero) if not.

This function is currently only available on some versions of Linux.

0 1
0
1

Sets the real, effective and saved set-user-ID to ruid, euid and suid respectively.

Returns zero on success and errno on failure.

Sets the real, effective and saved group ID to rgid, egid and sgid respectively.

Returns zero on success and errno on failure.

Get the real user ID.

setuid, setgid, getgid, seteuid, geteuid, setegid, getegid

Get the real group ID.

setuid, getuid, setgid, seteuid, geteuid, getegid, setegid

Get the effective user ID.

setuid, getuid, setgid, getgid, seteuid, getegid, setegid

Get the effective group ID.

setuid, getuid, setgid, getgid, seteuid, geteuid, setegid

Returns the process ID of this process.

getppid, getpgrp

Returns the process ID of the parent process.

getpid, getpgrp

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

A nonzero value is returned if the call is successful. If there's an error then zero is returned and errno is set appropriately.

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.

Stdio.File

Get operating system information.

The resulting mapping contains the following fields:

- "sysname"

Operating system name.

- "nodename"

Hostname.

- "release"

Operating system release.

- "version"

Operating system version.

- "machine"

Hardware architecture.

- "architecture"

Basic instruction set architecture.

- "isalist"

List of upported instruction set architectures. Usually space-separated.

- "platform"

Specific model of hardware.

- "hw provider"

Manufacturer of the hardware.

- "hw serial"

Serial number of the hardware.

- "srpc domain"

Secure RPC domain.

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

Only the first five elements are always available.

Returns a string with the name of the host.

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

Returns an array with information about the specified IP address.

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

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

gethostbyname()

Returns an array with information about the specified host.

The returned array contains the following:

hostname

Name of the host.

ips

Array of IP numbers for the host.

aliases

Array of alternative names for the host.

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

gethostbyaddr()

Call the system sleep() function.

This is not to be confused with the global function predef::sleep() that does more elaborate things and can sleep with better precision (although dependant on a normal functioning system clock).

The system's sleep function often utilizes the alarm(2) call and might not be perfectly thread safe in combination with simultaneous sleep()'s or alarm()'s. It might also be interrupted by other signals.

If you don't need it to be independant of the system clock, use predef::sleep() instead.

May not be present; only exists if the function exists in the current system.

predef::sleep() usleep() nanosleep()

Call the system usleep() function.

This is not to be confused with the global function predef::sleep() that does more elaborate things and can sleep with better precision (although dependant on a normal functioning system clock).

The system's usleep function often utilizes the alarm(2) call and might not be perfectly thread safe in combination with simultaneous sleep()'s or alarm()'s. It might also be interrupted by other signals.

If you don't need it to be independant of the system clock, use predef::sleep() instead.

May not be present; only exists if the function exists in the current system.

predef::sleep() sleep() nanosleep()

Call the system nanosleep() function.

This is not to be confused with the global function predef::sleep() that does more elaborate things and can sleep with better precision (although dependant on a normal functioning system clock).

Returns the remaining time to sleep (as the system function does).

predef::sleep() sleep() usleep()

May not be present; only exists if the function exists in the current system.

Returns the current process limitation for the selected resource.

cpu

The CPU time limit in seconds.

fsize

The maximum size of files the process may create.

data

The maximum size of the process's data segment.

stack

The maximum size of process stack, in bytes.

core
rss

Specifies the limit of pages the process's resident set.

nproc

The maximum number of processes that can be created for the real user ID of the calling process.

nofile

The maximum number of file descriptors the process can open, +1.

memlock

The maximum number of bytes of virtual memory that may be locked into RAM.

as
vmem
0

The soft limit for the resource. -1 means no limit.

1

The hard limit for the resource. -1 means no limit.

This function nor all the resources are available on all systems.

getrlimits, setrlimit

Returns all process limits in a mapping.

getrlimit, setrlimit

Sets the soft and the hard process limit on a resource.

getrlimit, getrlimits

0
1

Identifier for a timer that decrements in real time.

setitimer, getitimer

Identifier for a timer that decrements only when the process is executing.

setitimer, getitimer

Identifier for a timer that decrements both when the process is executing and when the system is executing on behalf of the process.

setitimer, getitimer

Sets the timer to the supplied value. Returns the current timer interval.

One of ITIMER_REAL, ITIMER_VIRTUAL and ITIMER_PROF.

Shows the state of the selected timer.

0

The interval of the timer.

1

The value of the timer.

One of ITIMER_REAL, ITIMER_VIRTUAL and ITIMER_PROF.

Queries a NetInfo server for property values at the given path.

NetInfo domain. Use "." for the local domain.

NetInfo path for the property.

Name of the property to return.

An array holding all property values. If the path or property cannot be not found 0 is returned instead. If the NetInfo domain is not found or cannot be queried an exception is thrown.

system.get_netinfo_property(".", "/locations/resolver", "domain"); ({ "idonex.se" })

Only available on operating systems which have NetInfo libraries installed.

Executes the rdtsc (clock pulse counter) instruction and returns the result.

Calls gettimeofday(); the result is an array of seconds, microseconds, and possible tz_minuteswes, tz_dstttime as given by the gettimeofday(2) system call (read the man page).

time(), gethrtime()

This string constant tells whether or not the CPU time returned by gethrvtime is thread local or not. The value is "yes" if it is and "no" if it isn't. The value is also "no" if there is no thread support.

Return resource usage about the current process. An error is thrown if it isn't supported or if the system fails to return any information.

Returns a mapping describing the current resource usage:

- "utime"

Time in milliseconds spent in user code.

- "stime"

Time in milliseconds spent in system calls.

- "maxrss"

Maximum used resident size in kilobytes. [1]

- "ixrss"

Quote from GNU libc: An integral value expressed in kilobytes times ticks of execution, which indicates the amount of memory used by text that was shared with other processes. [1]

- "idrss"

Quote from GNU libc: An integral value expressed the same way, which is the amount of unshared memory used for data. [1]

- "isrss"

Quote from GNU libc: An integral value expressed the same way, which is the amount of unshared memory used for stack space. [1]

- "minflt"

Minor page faults, i.e. TLB misses which required no disk I/O.

- "majflt"

Major page faults, i.e. paging with disk I/O required.

- "nswap"

Number of times the process has been swapped out entirely.

- "inblock"

Number of block input operations.

- "oublock"

Number of block output operations.

- "msgsnd"

Number of IPC messsages sent.

- "msgrcv"

Number of IPC messsages received.

- "nsignals"

Number of signals received.

- "nvcsw"

Number of voluntary context switches (usually to wait for some service).

- "nivcsw"

Number of preemptions, i.e. context switches due to expired time slices, or when processes with higher priority were scheduled.

- "sysc"

Number of system calls. [2]

- "ioch"

Number of characters read and written. [2]

- "rtime"

Elapsed real time (ms). [2]

- "ttime"

Elapsed system trap (system call) time (ms). [2]

- "tftime"

Text page fault sleep time (ms). [2]

- "dftime"

Data page fault sleep time (ms). [2]

- "kftime"

Kernel page fault sleep time (ms). [2]

- "ltime"

User lock wait sleep time (ms). [2]

- "slptime"

Other sleep time (ms). [2]

- "wtime"

Wait CPU (latency) time (ms). [2]

- "stoptime"

Time spent in stopped (suspended) state. [2]

- "brksize"

Heap size. [3]

- "stksize"

Stack size. [3]

[1] Not if /proc rusage is used.

[2] Only from (Solaris?) /proc rusage.

[3] Only from /proc PRS usage.

On some systems, only utime will be filled in.

gethrvtime()

The current time as a structure containing a sec and a usec member.

The number of seconds and microseconds since the epoch and the last whole second, respectively. (See also predef::time())

Please note that these variables will continually update when they are requested, there is no need to create new Time() objects.

The number of microseconds since the epoch. Please note that pike has to have been compiled with bignum support for this variable to contain sensible values.

If fast is true, do not request a new time from the system, instead use the global current time variable.

This will only work in callbacks, but can save significant amounts of CPU.

Return the time in seconds since the last time get was called.

Return the time in seconds since the last time get was called. The first time this method is called the time since the object was created is returned instead.

Create a new timer object. The timer keeps track of relative time with sub-second precision.

If fast is specified, the timer will not do system calls to get the current time but instead use the one maintained by pike. This will result in faster but somewhat more inexact timekeeping. Also, if your program never utilizes the pike event loop the pike maintained current time never change.

Get the group entry for the group with the id gid using the systemfunction getgrid(3).

The id of the group

An array with the information about the group

0

Group name

1

Group password (encrypted)

2

ID of the group

3

Array with UIDs of group members

getgrent() getgrnam()

Get the group entry for the group with the name str using the systemfunction getgrnam(3).

The name of the group

An array with the information about the group

0

Group name

1

Group password (encrypted)

2

ID of the group

3

Array with UIDs of group members

getgrent() getgrgid()

Get the user entry for login str using the systemfunction getpwnam(3).

The login name of the user whos userrecord is requested.

An array with the information about the user

0

Users username (loginname)

1

User password (encrypted)

2

Users ID

3

Users primary group ID

4

Users real name an possibly some other info

5

Users home directory

6

Users shell

getpwuid() getpwent()

Get the user entry for UID uid using the systemfunction getpwuid(3).

The uid of the user whos userrecord is requested.

An array with the information about the user

0

Users username (loginname)

1

User password (encrypted)

2

Users ID

3

Users primary group ID

4

Users real name an possibly some other info

5

Users home directory

6

Users shell

getpwnam() getpwent()

Returns an array with all users in the system.

An array with arrays of userinfo as in getpwent.

getpwent() getpwnam() getpwuid()

Returns an array of arrays with all groups in the system groups source. Each element in the returned array has the same structure as in getgrent function.

The groups source is system dependant. Refer to your system manuals for information about how to set the source.

0

Array with info about the group

getgrent()

Gets all groups which a given user is a member of.

UID or loginname of the user

0

Information about all the users groups

get_all_groups() getgrgid() getgrnam() getpwuid() getpwnam()

Returns the sine value for f. f should be specified in radians.

asin(), cos(), tan()

Return the arcus sine value for f. The result will be in radians.

sin(), acos()

Return the cosine value for f. f should be specified in radians.

acos(), sin(), tan()

Return the arcus cosine value for f. The result will be in radians.

cos(), asin()

Returns the tangent value for f. f should be specified in radians.

atan(), sin(), cos()

Returns the arcus tangent value for f. The result will be in radians.

tan(), asin(), acos(), atan2()

Returns the arcus tangent value for f1/f2, and uses the signs of f1 and f2 to determine the quadrant. The result will be in radians.

tan(), asin(), acos(), atan()

Returns the hyperbolic sine value for f.

asinh(), cosh(), tanh()

Return the hyperbolic arcus sine value for f.

sinh(), acosh()

Return the hyperbolic cosine value for f.

acosh(), sinh(), tanh()

Return the hyperbolic arcus cosine value for f.

cosh(), asinh()

Returns the hyperbolic tangent value for f.

atanh(), sinh(), cosh()

Returns the hyperbolic arcus tangent value for f.

tanh(), asinh(), acosh()

Returns the square root of f, or in the integer case, the square root truncated to the closest lower integer. If the argument is an object, the lfun _sqrt in the object will be called.

pow(), log(), exp(), floor(), lfun::_sqrt

Return the natural logarithm of f. exp( log(x) ) == x for x > 0.

pow(), exp()

Return the natural exponential of f. log( exp( x ) ) == x as long as exp(x) doesn't overflow an int.

pow(), log()

Return n raised to the power of x. If both n and x are integers the result will be an integer. If n is an object its pow method will be called with x as argument.

exp(), log()

Return the closest integer value less or equal to f.

floor() does not return an int, merely an integer value stored in a float.

ceil(), round()

Return the closest integer value greater or equal to f.

ceil() does not return an int, merely an integer value stored in a float.

floor(), round()

Return the closest integer value to f.

round() does not return an int, merely an integer value stored in a float.

floor(), ceil()

Returns the smallest value among args. Compared objects must implement the lfun::`< method.

max()

0
0

Returns the largest value among args. Compared objects must implement the lfun::`< method.

min()

0
0

Return the absolute value for f. If f is an object it must implement lfun::`< and unary lfun::`-.

Check the sign of a value.

Returns -1 if value is less than zero, 1 if value is greater than zero and 0 (zero) otherwise.

abs()

PDF

note: Defaults to a4, portrait

PDF
PDF
PDF
PDF
PDF
PDF
PDF

Implements support of all codecs from a nice project Ffmpeg. You can find more info about it at http://ffmpeg.sf.net/.

Create decoder or encoder object.

Internal number of codec, eg. CODEC_ID_MP2.

If true, encoder object will be created, decoder object otherwise.

Returns mapping with info of used codec.

list_codecs()

Sets one codec parameter

The name of parameter. One of "sample_rate", "bit_rate", "channels".

Returns 1 on success, 0 otherwise (parameter not known).

get_codec_params()

Returns a mapping with the actual codec parameters.

set_codec_param()

Returns a mapping with the new decoded frame and lenght of data which was used for decoding.

Decode all data buffer and pass result to shuffler. Returns 1 on success, 0 otherwise.

Shuffler variant isn't implemented, yet.

Usable only in decoder.

create()

``

Gets all supported codecs.

Array of mapping with codec features.

Various audio and video codecs.

The list of supported codecs depends on Ffmpeg library.

Type of codec.

The Gz module contains functions to compress and uncompress strings using the same algorithm as the program gzip. Compressing can be done in streaming mode or all at once.

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 this module is only available if the gzip library was available when Pike was compiled.

Note that although these functions use the same algorithm as gzip, they do not use the exact same format, so you cannot directly unzip gzipped files with these routines. Support for this will be added in the future.

Gz_deflate is a builtin program written in C. It interfaces the packing routines in the libz library.

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

Gz.inflate()

If given, level 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.

If the argument is negative, no headers will be emitted. This is needed to produce ZIP-files, as an example. The negative value is then negated, and handled as a positive value.

strategy, if given, should be one of DEFAULT_STRATEGY, FILTERED or HUFFMAN_ONLY.

0 9

This function performs gzip style compression on a string data and returns the packed data. Streaming can be done by calling this function several times and concatenating the returned data.

The optional argument flush should be one of 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.

Gz.inflate->inflate()

Gz_deflate is a builtin program written in C. It interfaces the unpacking routines in the libz library.

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

deflate

The window_size value is passed down to inflateInit2 in zlib.

If the argument is negative, no header checks are done, and no verification of the data will be done either. This is needed for uncompressing ZIP-files, as an example. The negative value is then negated, and handled as a positive value.

Positive arguments set the maximum dictionary size to an exponent of 2, such that 8 (the minimum) will cause the window size to be 256, and 15 (the maximum, and default value) will cause it to be 32Kb. Setting this to anything except 15 is rather pointless in Pike.

It can be used to limit the amount of memory that is used to uncompress files, but 32Kb is not all that much in the great scheme of things.

To decompress files compressed with level 9 compression, a 32Kb window size is needed. level 1 compression only requires a 256 byte window.

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

// whole file write(Gz_inflate()->inflate(stdin->read(0x7fffffff));

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

Gz.deflate->deflate()

This function returns 0 if the end of stream marker has not yet been encountered, or a string (possibly empty) containg any extra data received following the end of stream marker if the marker has been encountered. If the extra data is not needed, the result of this function can be treated as a logical value.

This function calculates the standard ISO3309 Cyclic Redundancy Check.

Low-level implementation of read/write support for GZip files

Opens a file for I/O.

The filename or an open filedescriptor or Stream for the GZip file to use.

Mode for the fileoperations. Defaults to read only.

If the object already has been opened, it will first be closed.

Stdio.Stream

Opens a gzip file for reading.

Stdio.Stream

closes the file

1 if successful

Reads len (uncompressed) bytes from the file. If read is unsuccessful, 0 is returned.

Writes the data to the file.

the number of bytes written to the file.

Seeks within the file.

Position relative to the searchtype.

SEEK_SET = set current position in file to pos SEEK_CUR = new position is current+pos SEEK_END is not supported.

New position or negative number if seek failed.

the current position within the file.

1 if EOF has been reached.

0
1

Sets the encoding level and strategy

Level of the compression. 0 is the least compression, 9 is max. 8 is default.

Set strategy for encoding to one of the following: DEFAULT_STRATEGY FILTERED HUFFMAN_ONLY

Allows the user to open a Gzip archive and read and write it's contents in an uncompressed form, emulating the Stdio.File interface.

An important limitation on this class is that it may only be used for reading or writing, not both at the same time. Please also note that if you want to reopen a file for reading after a write, you must close the file before calling open or strange effects might be the result.

_file

Filename or filedescriptor of the gzip file to open, or an already open Stream.

mode for the file. Defaults to "rb".

open Stdio.File

Stdio.Stream

Filename or filedescriptor of the gzip file to open, or an already open Stream.

mode for the file. Defaults to "rb". May be one of the following:

read mode

write mode

append mode

For the wb and ab mode, additional parameters may be specified. Please se zlib manual for more info.

non-zero if successful.

Stdio.Stream

Reads data from the file. If no argument is given, the whole file is read.

"___"

Stat a file.

If the argument symlink is 1 symlinks will not be followed.

If the path specified by path doesn't exist 0 (zero) will be returned.

Otherwise an object describing the properties of path will be returned.

In Pike 7.0 and earlier this function returned an array with 7 elements. The old behaviour can be simulated with the following function:

array(int) file_stat(string path, void|int(0..1) symlink) { File.Stat st = predef::file_stat(path, symlink); if (!st) return 0; return (array(int))st; }

Stdio.Stat, Stdio.File->stat()

0 1
Stdio.Stat

Truncates the file file to the length specified in length.

Returns 1 if ok, 0 if failed.

Returns a mapping describing the properties of the filesystem containing the path specified by path.

If a filesystem cannot be determined 0 (zero) will be returned.

Otherwise a mapping(string:int) with the following fields will be returned:

- "blocksize"

Size in bytes of the filesystem blocks.

- "blocks"

Size of the entire filesystem in blocks.

- "bfree"

Number of free blocks in the filesystem.

- "bavail"

Number of available blocks in the filesystem. This is usually somewhat less than the "bfree" value, and can usually be adjusted with eg tunefs(1M).

- "files"

Total number of files (aka inodes) allowed by this filesystem.

- "ffree"

Number of free files in the filesystem.

- "favail"

Number of available files in the filesystem. This is usually the same as the "ffree" value, and can usually be adjusted with eg tunefs(1M).

- "fsname"

Name assigned to the filesystem. This item is not available on all systems.

- "fstype"

Type of filesystem (eg "nfs"). This item is not available on all systems.

Please note that not all members are present on all OSs.

file_stat()

Write to standard error.

Remove a file or directory.

Returns 0 (zero) on failure, 1 otherwise.

mkdir(), Stdio.recursive_rm()

Create a directory.

If mode is specified, it's will be used for the new directory after being &'ed with the current umask (on OS'es that support this).

Returns 0 (zero) on failure, 1 otherwise.

rm(), cd(), Stdio.mkdirhier()

Returns an array of all filenames in the directory dirname, or 0 (zero) if the directory does not exist.

mkdir(), cd()

Change the current directory for the whole Pike process.

Returns 1 for success, 0 (zero) otherwise.

getcwd()

Returns the current working directory.

cd()

This function transforms the Pike process into a process running the program specified in the argument file with the arguments 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(2), and in that case it returns 0 (zero).

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

This function is not available on all platforms.

Process.create_process(), fork(), Stdio.File->pipe()

Rename or move a file or directory.

If the destination already exists, it will be replaced. Replacement often only works if to is of the same type as from, i.e. a file can only be replaced by another file and so on. Also, a directory will commonly be replaced only if it's empty.

On some OSs this function can't move directories, only rename them.

Returns 0 (zero) on failure, 1 otherwise. Call errno() to get more error info on failure.

rm()

This function returns a description of an error code. The error code is usually obtained from eg Stdio.File->errno().

On some platforms the string returned can be somewhat nondescriptive.

This function returns the system error from the last file operation.

Note that you should normally use Stdio.File->errno() instead.

Stdio.File->errno(), strerror()

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 syncronizing 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".

The gdbm manual states that it is important that the database is closed properly. Unfortunately this will not be the case if Pike calls exit() or returns from main(). You should therefore make sure you call close or destruct your gdbm objects when exiting your program. This will probably be done automatically in the future.

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

Remove a key from the database. Returns 1 if successful, otherwise 0, e.g. when the item is not present or the database is read only.

0
1

Return the first key in the database, this can be any key in the database.

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

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

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.

gdbm[key] = data;

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.

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.

Closes the database.

GMP is a free library for arbitrary precision arithmetic, operating on signed integers, rational numbers, and floating point numbers. There is no practical limit to the precision except the ones implied by the available memory in the machine GMP runs on. http://www.swox.com/gmp/

This program is used by the internal auto-bignum conversion. It can be used to explicitly type integers that are too big to be INT_TYPE. Best is however to not use this program unless you really know what you are doing.

Gmp.mpz implements very large integers. In fact, the only limitation on these integers is the available memory. The mpz object implements all the normal integer operations.

Create and initialize a Gmp.mpz object.

Initial value. If no value is specified, the object will be initialized to zero.

Base the value is specified in. The default base is base 10. The base can be either a value in the range [2..36] (inclusive), in which case the numbers are taken from the ASCII range 0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ (case-insensitive), or the value 256, in which case value is taken to be the binary representation in network byte order.

Leading zeroes in value are not significant. In particular leading NUL characters are not preserved in base 256 mode.

2 36 256 256

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.

cast_to_string

2 36 256 256
0
1

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

It is possible to cast an mpz to a string, int or float.

cast_to_int, cast_to_float, cast_to_string

Gmp.mpz
Gmp.mpz
Gmp.mpz
Gmp.mpz
Gmp.mpz
Gmp.mpz
Gmp.mpz
Gmp.mpz
Gmp.mpz
Gmp.mpz
Gmp.mpz
Gmp.mpz

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

Gmp.mpz
Gmp.mpz
Gmp.mpz
Gmp.mpz
Gmp.mpz
Gmp.mpz
Gmp.mpz
Gmp.mpz
Gmp.mpz
Gmp.mpz
Gmp.mpz
Gmp.mpz
Gmp.mpz
Gmp.mpz
Gmp.mpz
Gmp.mpz
Gmp.mpz
Gmp.mpz
Gmp.mpz
Gmp.mpz
Gmp.mpz
Gmp.mpz
Gmp.mpz
Gmp.mpz
Gmp.mpz
Gmp.mpz
0
1
0
1
0
1
0
1
0
1
0
1

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

0
1
1
Gmp.mpz

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

Gmp.mpz
Gmp.mpz
Gmp.mpz
Gmp.mpz
Gmp.mpz
Gmp.mpz
Gmp.mpz
Gmp.mpz
Gmp.mpz
Gmp.mpz

This function returns ( mpz ** a ) % b.

Gmp.mpz
Gmp.mpz
Gmp.mpz
Gmp.mpz
Gmp.mpz
0
1

For values >= 0, returns the population count (the number of set bits). For negative values (who have an infinite number of leading ones in a binary representation), -1 is returned.

Gmp.mpz

Returns the factorial of x (x!).

Gmp.mpz

Rational number stored in canonical form. The canonical from means that the denominator and the numerator have no common factors, and that the denominator is positive. Zero has the unique representation 0/1. All functions canonicalize their result.

Gmp.mpz Gmp.mpq
0
1
Gmp.mpq
Gmp.mpq
Gmp.mpq
Gmp.mpq
Gmp.mpq
Gmp.mpq
Gmp.mpq
Gmp.mpq
Gmp.mpq
Gmp.mpq

a%b = a - floor(a/b)*b

Gmp.mpq
Gmp.mpq
Gmp.mpq

Defined as -1-x.

Gmp.mpq
0
1
0
1
0
1
0
1
0
1
0
1
-1
1
0
1

GMP floating point number.

The mantissa of each float has a user-selectable precision, limited only by available memory. Each variable has its own precision, and that can be increased or decreased at any time.

The exponent of each float is a fixed precision, one machine word on most systems. In the current implementation the exponent is a count of limbs, so for example on a 32-bit system this means a range of roughly 2^-68719476768 to 2^68719476736, or on a 64-bit system this will be greater.

Each variable keeps a size for the mantissa data actually in use. This means that if a float is exactly represented in only a few bits then only those bits will be used in a calculation, even if the selected precision is high.

All calculations are performed to the precision of the destination variable. Each function is defined to calculate with "infinite precision" followed by a truncation to the destination precision, but of course the work done is only what's needed to determine a result under that definition.

The precision selected for a variable is a minimum value, GMP may increase it a little to facilitate efficient calculation. Currently this means rounding up to a whole limb, and then sometimes having a further partial limb, depending on the high limb of the mantissa. But applications shouldn't be concerned by such details.

The mantissa in stored in binary, as might be imagined from the fact precisions are expressed in bits. One consequence of this is that decimal fractions like 0.1 cannot be represented exactly. The same is true of plain IEEE double floats. This makes both highly unsuitable for calculations involving money or other values that should be exact decimal fractions. (Suitably scaled integers, or perhaps rationals, are better choices.)

mpf functions and variables have no special notion of infinity or not-a-number, and applications must take care not to overflow the exponent or results will be unpredictable. This might change in a future release.

Note that the mpf functions are not intended as a smooth extension to IEEE P754 arithmetic. In particular results obtained on one computer often differ from the results on a computer with a different word size.

0
0
2 36

Returns the value of the object as a float.

The Gmp.mpf object will claim to be a "float".

Perhaps it should also return true for "object"?

0
1
Gmp.mpf
Gmp.mpf

Sets the precision of the current object to be at least prec bits. The precision is limited to 128Kb. The current object will be returned.

0
Gmp.mpf

Returns the current precision, in bits.

0
Gmp.mpf
Gmp.mpf
Gmp.mpf
Gmp.mpf
Gmp.mpf
Gmp.mpf
Gmp.mpf
Gmp.mpf
0
1
0
1
0
1
0
1
0
1
0
1
0
1

Objects of this class contain the result from Mysql queries.

Mysql.mysql, Mysql.mysql->big_query()

Make a new Mysql.mysql_result object.

Mysql.mysql->big_query(), Mysql.mysql->list_dbs(), Mysql.mysql->list_tables(), Mysql.mysql->list_processes(), Mysql.mysql

Mysql.mysql

Number of rows in the result.

num_fields()

Number of fields in the result.

num_rows()

Skip to specified field.

Places the field cursor at the specified position. This affects which field mysql_result->fetch_field() will return next.

Fields are numbered starting with 0.

This function is usually not enabled. To enable it SUPPORT_FIELD_SEEK must be defined when compiling the mysql-module.

fetch_field(), fetch_fields()

Sense end of result table.

Returns 1 when all rows have been read, and 0 (zero) otherwise.

fetch_row()

0
1

Return specification of the current field.

Returns a mapping with information about the current field, and advances the field cursor one step. Returns 0 (zero) if there are no more fields.

The mapping contains the same entries as those returned by Mysql.mysql->list_fields(), except that the entry "default" is missing.

This function is usually not enabled. To enable it SUPPORT_FIELD_SEEK must be defined when compiling the mysql-module.

fetch_fields(), field_seek(), Mysql.mysql->list_fields()

Get specification of all remaining fields.

Returns an array with one mapping for every remaining field in the result table.

The returned data is similar to the data returned by Mysql.mysql->list_fields(), except for that the entry "default" is missing.

Resets the field cursor to 0 (zero).

This function always exists even when fetch_field() and field_seek() don't.

fetch_field(), field_seek(), Mysql.mysql->list_fields()

Skip ahead rows rows.

Can only seek forward.

fetch_row()

Fetch the next row from the result.

Returns an array with the contents of the next row in the result. Advances the row cursor to the next now.

Returns 0 (zero) at the end of the table.

seek()

This module enables access to the Mysql database from within Pike. Use Sql.Sql for general database access.

Mysql is available from http://www.mysql.com.

Mysql.mysql, Mysql.mysql_result, Sql.Sql

Interface to the Mysql database.

This class enables access to the Mysql database from within Pike.

Mysql is available from http://www.mysql.com.

Mysql.mysql_result, Sql.Sql

Connect to a Mysql database.

To access the Mysql database, you must first connect to it. This is done with this function.

If you give no argument, or give "" as host it will connect with a UNIX-domain socket, which can be a big performance gain.

This optional mapping can contain zero or more of the following parameters:

- "init_command"

Command to execute on connect.

- "timeout"

Timeout in seconds.

- 0 1 "compress"

Enable compressed protocol.

- "mysql_config_file"

Change config file from "my.cnf".

- "mysql_group"

Specify additional group to read from config file.

- 0 1 "mysql_named_pipe"

Use named pipe to connect to server.

- 0 1 "mysql_local_infile"

Enable use of LOCAL INFILE (security).

- "mysql_charset_dir"

Change charset directory.

- "mysql_charset_name"

Set connection charset - see set_charset for details. The default is "latin1". As opposed to set_charset, this way of specifying the connection charset doesn't require MySQL 4.1.0.

- "unicode_decode_mode"

Enable unicode decode mode for the connection if nonzero. In this mode non-binary string results are automatically converted to (possibly wide) unicode strings. An error is thrown if the server doesn't support this. See set_unicode_decode_mode.

- "ssl_key"

Path to SSL-key for use in SSL-communication.

- "ssl_cert"

Path to SSL-cert for use in SSL-communication.

- "ssl_ca"

Path to SSL-CA for use in SSL-communication.

- "ssl_capath"

Path to SSL-CAPATH for use in SSL-communication.

- "ssl_cipher"

FIXME

- "connect_options"

Options used when connecting to the server. See mysql documentation for more information.

Some options may not be implemented. Unimplemented options are silently ignored.

To use SSL-connections, set the SSL-parameters correctly. They correspond to the parameters given to the mysql-client with the same name so make sure that the mysql-client works with SSL and set these parameters to the same values and everything should work. If SSL-options are loaded from a config-file, one may set the connect_options to include CLIENT_SSL.

If Pike has been built with an old MySQL client lib then it might not be possible to specify some charsets that the server supports with the "mysql_charset_name" option. In such cases it's possible that set_charset works better (provided the server is 4.1 or newer).

Returns the number of rows affected by the last query.

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

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

Returns 0 (zero) if there was no error.

Select database.

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

create(), create_db(), drop_db()

Create a new database

This function creates a new database named database in the Mysql-server.

select_db(), drop_db()

Drop a database

This function drops the database named database from the Mysql-server.

create_db(), select_db()

Shutdown the Mysql-server

This function shuts down a running Mysql-server.

reload()

Reload security tables

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

shutdown()

Some Mysql-server statistics

This function returns some server statistics.

server_info(), host_info(), protocol_info()

Get the version number of the Mysql-server.

statistics(), host_info(), protocol_info()

Get information about the Mysql-server connection

statistics(), server_info(), protocol_info()

Give the Mysql protocol version

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

statistics(), server_info(), host_info()

List databases

Returns a table containing the names of all databases in the Mysql-server. If the argument wild is specified, only those matching it will be returned.

list_tables(), list_fields(), list_processes(), Mysql.mysql_result

Mysql.mysql_result
Mysql.mysql_result

List tables in the current database

Returns a table containing the names of all tables in the current database. If the argument wild is given, only those matching it will be returned.

list_dbs(), list_fields(), list_processes(), Mysql.mysql_result

Mysql.mysql_result
Mysql.mysql_result

List all fields.

Returns an array of mappings with information about the fields in the table named table. If the argument wild is given, only those fields matching it will be returned

The mappings contain the following entries:

- "name"

The name of the field.

- "table"

The name of the table.

- "default"

The default value for the field.

- "type"

The SQL type of the field.

- "length"

The length of the field.

- "max_length"

The length of the longest element in this field.

- "flags"

Some flags.

- decimals

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.

Michael Widenius recomends use of the following query instead: show fields in 'table' like "wild".

list_dbs(), list_tables(), list_processes(), Mysql.mysql_result.fetch_field()

List all processes in the Mysql-server

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

list_dbs(), list_tables(), list_fields(), Mysql.mysql_result

Mysql.mysql_result

Inform if this version of Mysql.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.

The Mird module doubles as the Mird database class.

A Mird table has approximately the same characteristics as a Pike mapping. You store key:value pairs in it, you get values from keys, you delete keys.

For convinience, the Table object overloads `[](), `[]=(), _indices() and _values().

Creates a scanner over the called table; if key is given, continue at that key (as returned from Mird.Glue.Scanner.next_key()).

A scanner can be used to loop over all elements in a table.

Mird.Glue.Scanner
Mird.Glue.Scanner

Get and store key:value pairs, list the table.

All storage in the table will create a transaction, if we're not already in a transaction.

It is possible to cast the Table to a mapping or array; this will read all contents of the table, so beware if you have a big table.

"mapping"
"array"

A vTable is just like a Table, except that the values can be anything, not just strings. The data is encode_value()'ed before storage.

inherits Table

v0Table

This is just like a normal table, but all data is encode_value()ed, and gzipped, and unpacked if reading, for convinience. Only available when Pike supports Gz.

inherits Table

v0Table

A Transaction is the environment which in a change to the database can be made. Simplified, the database is not changed until the transaction is closed. More then one change to the database can be performed within one transaction.

If the same entries in the database were changed during the lifespan of the transaction, it cannot be closed but has to be cancelled.

Creates a Table, vTable or vzTable object for the specified table, which emulates a mapping and in which you can make changes to the database or do lookups.

Table
vTable
vzTable

Creates a new table in the database. A stringkey table is a mapping from string to string, and a hashkey table is mapping from int to string.

Table
Table

Removes a table and all items in it

Returns the names of the tables in the database.

Finishes a transaction. This throws exceptions if there were conflicts.

Cancels (rewinds) a transaction.

Caching transaction

Transaction

Opens the database using the given filename. Note that the file filename+".journal" will be created too.

Possible options:

- "flags"

Database flags, see below.

- "block_size"

Database block size; must be even 2^n. Database size is limited to 2^32 blocks, ie block_size*2^32 (8192*2^(32-5) is approximately 1Tb) (2048)

- "frag_bits"

This sets the number of fragments in a fragmented block, and address bits to locate them. The number of fragments in a fragmented block is equal to 2^frag_bits-1, by default 2^5-1=32-1=31.

This steals bits from the 32 bit address used to point out a chunk. (5)

- "hashtrie_bits"

This is the number of bits in each hash-trie hash; 4*2^n must be a lot less than block_size. (5)

- "cache_size"

This is the number of blocks cached from the database; this is used for both the read- and the write cache. Note that the memory usage is constant, approximately block_size*cache_size bytes. (32)

- "cache_search_length"

This is the closed hash maximum search length to find a block in the cache; note that this will result in linear time usage. (8)

- "max_free_frag_blocks"

This is how many blocks with free space that is kept in a list to be used when a transaction is running. The closest fit of usage of these blocks are where the data will be stored. (10)

- "file_mode"

This is the default mode the files are opened with; although affected by UMASK (0666)

- "journal_readback_n"

This is how many journal entries are read back at once at transaction finish, cancel or copy time. Bytes needed is approximately 24*this number (200)

"flags" is a string with any of these characters:

'r'

Readonly.

'R'

Readonly in a live system (one process writes, many reads).

'n'

Don't create if it doesn't exist.

'x'

Exclusive (always create).

's'

Call fsync(3) when finishing transactions.

'S'

Call sync(2) after fsync(3).

'j'

Complain if journal file is gone missing.

Gives back the table object for the specified table in the database.

Table

A vTable is just like a Table, except that the values can be anything, not just strings. The data is encode_value()'ed before storage.

A vzTable is just like a vTable, except that the values are both encoded and then packed using Gz. Only available if Pike supports Gz.

vTable
vzTable

Returns the name of the table with id id.

Create a new table in the database.

A transaction will be created when calling these on the Database level.

Table
Table

Creates a new transaction

Transaction

Gives a list of all tables in the database.

Syncs the database (syncs against disc and starts to reuse any space that is freed), sync_please() does this when the last living transaction is finished.

Starts a call_out loop that will call sync_please once every given interval. 0 or fewer seconds will shut down the loop. Default is 1 minute (60 seconds).

Syncs and closes the database

This closes the database, ie

cancels all ongoing transactions

syncs the database (flushes caches, and frees all unused blocks)

destroys the database object

Call this or destroy the database object when you want the database closed.

- "flags"

database flags, see below

- "block_size"

database block size; must be even 2^n database size is limited to 2^32 blocks, ie block_size*2^32 (8192*2^(32-5) is approximately 1Tb) (2048)

- "frag_bits"

this sets the number of frags in a fragmented block, and address bits to locate them. the number of frags in a fragmented block is equal to 2^frag_bits-1, per default 2^5-1=32-1=31

This steals bits from the 32 bit address used to point out a chunk. (5)

- "hashtrie_bits"

this is the number of bits in each hash-trie hash; 4*2^n must be a lot less then block_size (5)

- "cache_size"

this is the number of blocks cached from the database; this is used for both read- and write cache. Note that the memory usage is constant, approximately block_size*cache_size bytes. (32)

- "cache_search_length"

this is the closed hash maximum search length to find a block in the cache; note that this will result in linear time usage. (8)

- "max_free_frag_blocks"

this is how many blocks with free space that is kept in a list to be used when a transaction is running. The closest fit of usage of these blocks are where the data will be stored. (10)

- "file_mode"

this is the default mode the files are opened with; although affected by UMASK (0666)

- "journal_readback_n"

this is how many journal entries are read back at once at transaction finish, cancel or copy time bytes needed is approximately 24*this number (200)

    flags is a string with any of these characters:
    "r" - readonly
    "R" - readonly in a live system (one process writes, many reads)
    "n" - don't create if it doesn't exist
    "x" - exclusive (always create)
    "s" - call fsync when finishing transactions
    "S" - call sync(2) after fsync
    "j" - complain if journal file is gone missing

zero

the data value or zero_type if key wasn't found

This closes the database without flushing or syncing. This should never be used and exist only for testing purposes.

Syncs the database; this flushes all eventual caches and frees all unused blocks.

sync() can only be called when there is no ongoing transactions. sync_please() sets a marker that the database should be synced when the last transaction is finished or cancelled, which will eventually sync the database.

The usage could be in a call_out-loop,

       [...]
       call_out(sync_the_database,5*60);
       [...]
    void sync_the_database()
    {
       call_out(sync_please,5*60);
       my_mird->sync_please();
    }

the object being called

0 1

this syncs the database and verifies the database free list. It prints stuff on stderr. It exists only for debug purpose and has no other use.

the number of syscalls the database has done so far

A transaction object is enclosing a change in the database. It can either succeed in full or fail in full. If some other transaction has changed the same data as the current, the transaction closed last will fail (conflict).

cancels (rewinds) a transaction

closes a transaction; may cast exceptions if there are conflicts

Mird

Creates a new transaction within the given database.

zero

the data value or zero_type if key wasn't found

delets a table from the database

this can take some time, depending on how much data that is in that table

creates a table in the database

Tries to resolve a transaction; casts an exception if there is a conflict. May be called more then once.

the object being called

Objects of this class is used to read off all contents of a table in the database.

Mird
Transaction

Creates a new scanner object, tuned to the given table and database or transaction.

Gives back a possible argument to the constructor of Scanner; allows the possibility to continue to scan even if the Scanner object is lost.

zero

Reads some tupels from the table the scanner is directed against; the size of the resulting mapping is close to this number.

a mapping of the next (about) n tupels in the table, or zero if there is no more tupels in the table

a buffer directly depending on this size is allocated; it's not recommended doing a "read(0x7fffffff)".

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.

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. eg passwd.byname instead of just passwd.

If domain is not specified , the default domain will be used. (As returned by Yp.default_domain()).

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. This timeout is not configurable.

Yp.default_domain()

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.

For each entry in map, call the function specified by fun.

fun 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. eg passwd.byname instead of just passwd.

``

Returns the 'order' number for the map map.

This is usually the number of seconds since Jan 1 1970 (see 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. eg passwd.byname instead of just passwd.

Search for the key key in the Yp-map map.

If there is no key in the map, 0 (zero) will be returned, otherwise the string matching the key will be returned.

key must match exactly, no pattern matching of any kind is done.

Returns the default yp-domain.

Network Information Service aka YP map.

Create a new YP-map object.

map is the YP-map to bind to. This may be a nickname, such as passwd instead of just passwd.byname.

If domain is not specified, the default domain will be used.

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.

Search for the key key. If there is no key in the map, 0 (zero) will be returned, otherwise the string matching the key will be returned.

key must match exactly, no pattern matching of any kind is done.

Returns the whole map as a mapping.

Call a function for each entry in the map.

For each entry in the map, call the function fun.

The function will be called like void fun(string key, string value).

``

Return the server that provides this map.

Return the order number for this map.

Return the number of entries in this map.

Return the keys of the map.

Return the values of the map.

"___"

Contains the result of a Postgres-query.

Sql.postgres, Postgres.postgres, Sql.Sql, Sql.sql_result

You can't create istances of this object yourself. The only way to create it is via a big_query to a Postgres database.

Returns the number of rows in the result.

Returns the number of fields in the result.

Returns an array with an entry for each field, each entry is a mapping with the following fields:

- "name"

Name of the column

- "type"

The type ID of the field. This is the database's internal representation type ID.

- "length"

Can be an integer (the size of the contents in bytes) or the word "variable".

For char() fields, length is to be intended as the MAXIMUM length of the field. This is not part of the interface specifications in fact, but a driver-choice. In fact char() fields are for Postgres _FIXED_ length fields, and are space-padded. If CUT_TRAILING_SPACES is defined when the driver is compiled (default behavior) it will cut such spaces.

Moves the result cursor (ahead or backwards) the specified number of rows. Notice that when you fetch a row, the cursor is automatically moved forward one slot.

Returns an array with the contents of the next row in the result. Advances the row cursor to the next row. Returns 0 at end of table.

Since there's no generic way to know whether a type is numeric or not in Postgres, all results are returned as strings. You can typecast them in Pike to get the numeric value.

seek()

This is an interface to the Postgres (Postgres95, pgsql) database server. This module may or may not be availible on your Pike, depending whether the appropriate include and library files could be found at compile-time. Note that you do not need to have a Postgres server running on your host to use this module: you can connect to the database over a TCP/IP socket.

Please notice that unless you wish to specifically connect to a Postgres server, you'd better use the Sql.Sql, which is a server-independent sql-server-class. The interfaces to all existing sql-classes are consistent. Using Sql.Sql ensures that your Pike applications will run with any supported SQL server without changing a single line of code, at least for most common (and simple) operations.

The program Postgres.postgres provides the raw interface to the database. Many functions are not availible for this program. Therefore, its use is DEPRECATED. It is included in this documentation only for completeness' sake. Use Sql.postgres instead, or even better Sql.Sql

There is no testsuite for this module, since to test anything would require a working Postgres server. You can try to use the included scripts in the "pike/src/modules/Postgres/extras" directory but you'll probably have to patch them to reflect your site's settings.

Also note that this module uses blocking I/O I/O to connect to the server. Postgres is quite slow, and so you might want to consider this particular aspect. It is (at least should be) thread-safe, and so it can be used in a multithread environment.

The behavior of the Postgres C API also depends on certain environment variables defined in the environment of the pike interpreter.

"PGHOST"

Sets the name of the default host to connect to. It defaults to "localhost"

"PGOPTIONS"

Sets some extra flags for the frontend-backend connection. DO NOT SET unless you're sure of what you're doing.

"PGPORT"

Sets the default port to connect to, otherwise it will use compile-time defaults (that is: the time you compiled the postgres library, not the Pike driver).

"PGTTY"

Sets the file to be used for Postgres frontend debugging. Do not use, unless you're sure of what you're doing.

"PGDATABASE"

Sets the default database to connect to.

"PGREALM"

Sets the default realm for Kerberos authentication. I never used this, so I can't help you.

Refer to the Postgres documentation for further details.

Sql.Sql, Sql.postgres, Sql.postgres_result

Should you need to report a bug to the author, please submit along with the report the driver version number, as returned by this call.

With no arguments, this function initializes (reinitializes if a connection had been previously set up) a connection to the Postgres backend. Since Postgres requires a database to be selected, it will try to connect to the default database. The connection may fail however for a variety of reasons, in this case the most likely of all is because you don't have enough authority to connect to that database. So use of this particular syntax is discouraged.

The host argument allows you to connect to databases residing on different hosts. If it is 0 or "", it will try to connect to localhost.

The database argument specifies the database to connect to. If 0 or "", it will try to connect to the default database.

You need to have a database selected before using the sql-object, otherwise you'll get exceptions when you try to query it. Also notice that this function can raise exceptions if the db server doesn't respond, if the database doesn't exist or is not accessible by you.

You don't need bothering about syncronizing the connection to the database: it is automatically closed (and the database is sync-ed) when the object is destroyed.

Sql.postgres, Sql.Sql, select_db

This function allows you to connect to a database. Due to restrictions of the Postgres frontend-backend protocol, you always have to be connected to a database, so in fact this function just allows you to connect to a different database on the same server.

This function can raise exceptions if something goes wrong (backend process not running, not enough permissions..)

create

This is the only provided interface which allows you to query the database. If you wish to use the simpler "query" function, you need to use the Sql.Sql generic sql-object.

It returns a postgres_result object (which conforms to the Sql.sql_result standard interface for accessing data). I recommend using query() for simpler queries (because it is easier to handle, but stores all the result in memory), and big_query for queries you expect to return huge amounts of data (it's harder to handle, but fectches results on demand).

This function can raise exceptions.

The program Sql.postgres_result is exactly the same as Postgres.postgres_result.

Sql.Sql, Sql.sql_result

Sql.postgres_result

This function returns the textual description of the last server-related error. Returns 0 if no error has occurred yet. It is not cleared upon reading (can be invoked multiple times, will return the same result until a new error occurs).

big_query

This function resets the connection to the backend. Can be used for a variety of reasons, for example to detect the status of a connection.

This function is Postgres-specific, and thus it is not availible through the generic SQL-interface.

With Postgres you can associate events and notifications to tables. This function allows you to detect and handle such events.

With no arguments, resets and removes any callback you might have put previously, and any polling cycle.

With one argument, sets the notification callback (there can be only one for each sqlobject).

The callback function must return no value, and takes a string argument, which will be the name of the table on which the notification event has occured. In future versions, support for user-specified arguments will be added.

The Sql.postgres program adds support for automatic delivery of messages (see it for explanation on the inner workings of this feature).

This function is Postgres-specific, and thus it is not availible through the generic SQL-interface

Sql.postgres

``

This function returns a string describing what host are we talking to, and how (TCP/IP or UNIX sockets).

Escape a string to prevent SQL injection, using the current connection's character encoding settings.

"___"
jobject
jobject
jobject
jobject
jobject
jobject

Print formated output to string.

The format string is a string containing a description of how to output the data in args. This string should generally speaking have one %<modifiers><operator> format specifier (examples: %s, %0d, %-=20s) for each of the arguments.

The following modifiers are supported:

'0'

Zero pad numbers (implies right justification).

'!'

Toggle truncation.

' '

Pad positive integers with a space.

'+'

Pad positive integers with a plus sign.

'-'

Left adjust within field size (default is right).

'|'

Centered within field size.

'='

Column mode if strings are greater than field size.

'/'

Rough line break (break at exactly field size instead of between words).

'#'

Table mode, print a list of '\n' separated word (top-to-bottom order).

'$'

Inverse table mode (left-to-right order).

'n'

(Where n is a number or *) field size specifier.

'.n'

Precision specifier.

':n'

Field size precision specifier.

';n'

Column width specifier.

'*'

If n is a * then next argument is used for precision/field size.

"'"

Set a pad string. ' cannot be a part of the pad string (yet).

'~'

Get pad string from argument list.

'<'

Use same argument again.

'^'

Repeat this on every line produced.

'@'

Repeat this format for each element in the argument array.

'>'

Put the string at the bottom end of column instead of top.

'_'

Set width to the length of data.

'[n]'

Select argument number n. Use * to use the next argument as selector.

The following operators are supported:

'%'

Percent.

'b'

Signed binary integer.

'd'

Signed decimal integer.

'u'

Unsigned decimal integer.

'o'

Signed octal integer.

'x'

Lowercase signed hexadecimal integer.

'X'

Uppercase signed hexadecimal integer.

'c'

Character. If a fieldsize has been specified this will output the low-order bytes of the integer in network (big endian) byte order. To get little endian byte order, negate the field size.

'f'

Float. (Locale dependent formatting.)

'g'

Heuristically chosen representation of float. (Locale dependent formatting.)

'G'

Like %g, but uses uppercase E for exponent.

'e'

Exponential notation float. (Locale dependent output.)

'E'

Like %e, but uses uppercase E for exponent.

'F'

Binary IEEE representation of float (%4F gives single precision, %8F gives double precision.)

's'

String.

'O'

Any value, debug style. Do not rely on the exact formatting; how the result looks can vary depending on locale, phase of the moon or anything else the _sprintf method implementor wanted for debugging.

'n'

No operation (ignore the argument).

't'

Type of the argument.

'{'
'}'

Perform the enclosed format for every element of the argument array.

Most modifiers and operators are combinable in any fashion, but some combinations may render strange results.

If an argument is an object that implements lfun::_sprintf(), that callback will be called with the operator as the first argument, and the current modifiers as the second. The callback is expected to return a string.

Pike v7.4 release 13 running Hilfe v3.5 (Incremental Pike Frontend) > sprintf("The unicode character %c has character code %04X.", 'A', 'A'); (1) Result: "The unicode character A has character code 0041." > sprintf("#%@02X is the HTML code for purple.", Image.Color.purple->rgb()); (2) Result: "#A020F0 is the HTML code for purple." > int n=4711; > sprintf("%d = hexadecimal %x = octal %o = %b binary", n, n, n, n); (3) Result: "4711 = hexadecimal 1267 = octal 11147 = 1001001100111 binary"

sprintf style formatting is applied by many formatting functions, such write() and werror.

> write(#"Formatting examples: Left adjusted [%-10d] Centered [%|10d] Right adjusted [%10d] Zero padded [%010d] ", n, n, n, n); Formatting examples: Left adjusted [4711 ] Centered [ 4711 ] Right adjusted [ 4711] Zero padded [0000004711] (5) Result: 142 int screen_width=70; > write("%-=*s\n", screen_width, >> "This will wordwrap the specified string within the "+ >> "specified field size, this is useful say, if you let "+ >> "users specify their screen size, then the room "+ >> "descriptions will automagically word-wrap as appropriate.\n"+ >> "slosh-n's will of course force a new-line when needed.\n"); This will wordwrap the specified string within the specified field size, this is useful say, if you let users specify their screen size, then the room descriptions will automagically word-wrap as appropriate. slosh-n's will of course force a new-line when needed. (6) Result: 355 > write("%-=*s %-=*s\n", screen_width/2, >> "Two columns next to each other (any number of columns will "+ >> "of course work) independantly word-wrapped, can be useful.", >> screen_width/2-1, >> "The - is to specify justification, this is in addherence "+ >> "to std sprintf which defaults to right-justification, "+ >> "this version also supports centre and right justification."); Two columns next to each other (any The - is to specify justification, number of columns will of course this is in addherence to std work) independantly word-wrapped, sprintf which defaults to can be useful. right-justification, this version also supports centre and right justification. (7) Result: 426 > write("%-$*s\n", screen_width, >> "Given a\nlist of\nslosh-n\nseparated\n'words',\nthis option\n"+ >> "creates a\ntable out\nof them\nthe number of\ncolumns\n"+ >> "be forced\nby specifying a\npresision.\nThe most obvious\n"+ >> "use is for\nformatted\nls output."); Given a list of slosh-n separated 'words', this option creates a table out of them the number of columns be forced by specifying a presision. The most obvious use is for formatted ls output. (8) Result: 312 > write("%-#*s\n", screen_width, >> "Given a\nlist of\nslosh-n\nseparated\n'words',\nthis option\n"+ >> "creates a\ntable out\nof them\nthe number of\ncolumns\n"+ >> "be forced\nby specifying a\npresision.\nThe most obvious\n"+ >> "use is for\nformatted\nls output."); Given a creates a by specifying a list of table out presision. slosh-n of them The most obvious separated the number of use is for 'words', columns formatted this option be forced ls output. (9) Result: 312 > sample = ([ "align":"left", "valign":"middle" ]); (10) Result: ([ /* 2 elements */ "align":"left", "valign":"middle" ]) > write("<td%{ %s='%s'%}>\n", (array)sample); <td valign='middle' align='left'> (11) Result: 34 > write("Of course all the simple printf options "+ >> "are supported:\n %s: %d %x %o %c\n", >> "65 as decimal, hex, octal and a char", >> 65, 65, 65, 65); Of course all the simple printf options are supported: 65 as decimal, hex, octal and a char: 65 41 101 A (12) Result: 106 > write("%[0]d, %[0]x, %[0]X, %[0]o, %[0]c\n", 75); 75, 4b, 4B, 113, K (13) Result: 19 > write("%|*s\n",screen_width, "THE END"); THE END (14) Result: 71

lfun::_sprintf()

Construct a mapping.

Groups the arguments together two and two in key-index pairs and creates a mapping of those pairs. Generally, the mapping literal syntax is handier: ([ key1:val1, key2:val2, ... ])

sizeof(), mappingp(), mkmapping()

The purpose of sscanf is to match a string data against a format string and place the matching results into a list of variables. The list of lvalues are destructively modified (which is only possible because sscanf really is an opcode, rather than a pike function) with the values extracted from the data according to the format specification. Only the variables up to the last matching directive of the format string are touched.

The format string can contain strings separated by special matching directives like %d, %s %c and %f. Every such directive corresponds to one of the lvalues, in order they are listed. An lvalue is the name of a variable, a name of a local variable, an index in an array, mapping or object. It is because of these lvalues that sscanf can not be implemented as a normal function.

Whenever a percent character is found in the format string, a match is performed, according to which operator and modifiers follow it:

"%b"

Reads a binary integer ("0101" makes 5)

"%d"

Reads a decimal integer ("0101" makes 101).

"%o"

Reads an octal integer ("0101" makes 65).

"%x"

Reads a hexadecimal integer ("0101" makes 257).

"%D"

Reads an integer that is either octal (leading zero), hexadecimal (leading 0x) or decimal. ("0101" makes 65).

"%c"

Reads one character and returns it as an integer ("0101" makes 48, or '0', leaving "101" for later directives). Using the field width and endianness modifiers, you can decode integers of any size and endianness. For example "%-2c" decodes "0101" into 12592, leaving "01" fot later directives. The sign modifiers can be used to modify the signature of the data, making "%+1c" decode "ä" into -28.

"%f"

Reads a float ("0101" makes 101.0).

"%F"

Reads a float encoded according to the IEEE single precision binary format ("0101" makes 6.45e-10, approximately). Given a field width modifier of 8 (4 is the default), the data will be decoded according to the IEEE double precision binary format instead. (You will however still get a float, unless your pike was compiled with the configure argument --with-double-precision.)

"%s"

Reads a string. If followed by %d, %s will only read non-numerical characters. If followed by a %[], %s will only read characters not present in the set. If followed by normal text, %s will match all characters up to but not including the first occurrence of that text.

"%[set]"

Matches a string containing a given set of characters (those given inside the brackets). %[^set] means any character except those inside brackets. Ranges of characters can be defined by using a minus character between the first and the last character to be included in the range. Example: %[0-9H] means any number or 'H'. Note that sets that includes the character - must have it first in the brackets to avoid having a range defined. Sets including the character ']' must list this first (even before -) too, for natural reasons.

"%{format%}"

Repeatedly matches 'format' as many times as possible and assigns an array of arrays with the results to the lvalue.

"%O"

Match a Pike constant, such as string or integer (currently only integer, string and character constants are functional).

"%%"

Match a single percent character (hence this is how you quote the % character to just match, and not start an lvalue matcher directive).

Similar to sprintf, you may supply modifiers between the % character and the operator, to slightly change its behaviour from the default:

"*"

The operator will only match its argument, without assigning any variable.

number

You may define a field width by supplying a numeric modifier. This means that the format should match that number of characters in the input data; be it a number characters long string, integer or otherwise ("0101" using the format %2c would read an unsigned short 12337, leaving the final "01" for later operators, for instance).

"-"

Supplying a minus sign toggles the decoding to read the data encoded in little-endian byte order, rather than the default network (big-endian) byte order.

"+"

Interpret the data as a signed entity. In other words, "%+1c" will read "\xFF" as -1 instead of 255, as "%1c" would have.

Sscanf does not use backtracking. Sscanf simply looks at the format string up to the next % and tries to match that with the string. It then proceeds to look at the next part. If a part does not match, sscanf immediately returns how many % were matched. If this happens, the lvalues for % that were not matched will not be changed.

// a will be assigned "oo" and 1 will be returned sscanf("foo", "f%s", a);

// a will be 4711 and b will be "bar", 2 will be returned sscanf("4711bar", "%d%s", a, b);

// a will be 4711, 2 will be returned sscanf("bar4711foo", "%*s%d", a);

// a will become "test", 2 will be returned sscanf(" \t test", "%*[ \t]%s", a);

// Remove "the " from the beginning of a string // If 'str' does not begin with "the " it will not be changed sscanf(str, "the %s", str);

// It is also possible to declare a variable directly in the sscanf call; // another reason for sscanf not to be an ordinary function:

sscanf("abc def", "%s %s", string a, string b);

The number of directives matched in the format string. Note that a string directive (%s or %[]) counts as a match even when matching just the empty string (which either may do).

sprintf, array_sscanf

This function works just like sscanf(), but returns the matched results in an array instead of assigning them to lvalues. This is often useful for user-defined sscanf strings.

sscanf(), `/()

Called by various routines to format a readable description of an exception.

Something that was thrown. Usually an Error.Generic object, or an array with the following content:

msg

Error message.

backtrace_frame backtrace

Backtrace to the point where the exception occurred.

Returns a string describing the exeception.

Usually added by the initialization code the global name space with add_constant().

predef::describe_backtrace()

Unregister a program that was only partially compiled.

Called by compile() to clean up references to partially compiled programs.

Partially compiled program that should no longer be referenced.

Shouldn't this function be in the compilation handler?

The master object is used as a fallback codec by encode_value() and decode_value() if no codec was given.

It will also be used as a codec if decode_value() encounters old-style encode_value()'ed data.

Codec

The master object acts as fallback compilation handler for compile() and cpp().

CompilationHandler

Get compilation handler for simulation of Pike vmajor.minor.

This function is called by cpp() when it encounters #pike directives.

Major version.

Minor version.

Returns a compilation handler for Pike >= major.minor.

CompilationHandler

Convert raw from encoding charset to UNICODE.

This function is called by cpp() when it encounters #charset directives.

String to convert.

Name of encoding that raw uses.

raw decoded to UNICODE, or 0 (zero) if the decoding failed.

Locale.Charset

Called by the Pike runtime to cast strings to objects.

String to cast to object.

Filename of the file that attempts to perform the cast.

Returns the resulting object.

cast_to_program()

Called by the Pike runtime to cast strings to programs.

String to cast to object.

Filename of the file that attempts to perform the cast.

Returns the resulting program.

cast_to_object()

Called by the Pike runtime if an exception isn't caught.

Value that was throw()'n.

describe_backtrace()

Called by the Pike runtime to warn about data inconsistencies.

Runtime subsystem where the warning was generated. Currently the following subsystems may call this function:

"gc"

The garbage collector.

Warning message. Currently the following messages may be generated:

"bad_cycle"

A cycle where the destruction order isn't deterministic was detected by the garbage collector.

data will in this case contain an array of the elements in the cycle.

Optional data that further describes the warning specified by msg.

Class for exception objects for errors of unspecified type.

Cast operator.

The only supported type to cast to is "array", which generates and old-style error.

Index operator.

Simulates an array

msg

Error message.

backtrace

Backtrace as returned by backtrace() from where the error occurred.

The error message is always terminated with a newline.

backtrace()

0 1

Return a readable error report that includes the backtrace.

Return a readable message describing the error.

Return the backtrace where the error occurred.

predef::backtrace()

This is the interface for iterator objects. They implement an interface to a collection or stream of data items and a cursor that can be used to iterate over and examine individual items in the data set.

Iterators are typically created to access a data set in some specific object, array, mapping, multiset or string. An object can have several iterators that access different data sets in it, or the same in different ways. E.g. strings have both an iterator for access char-by-char (String.Iterator), and another for access over splitted substrings (String.SplitIterator). lfun::_get_iterator may be defined in an object to get an instance of the canonical iterator type for it. It's used by e.g. foreach to iterate over objects conveniently.

It's not an error to advance an iterator past the beginning or end of the data set; `!() will only return true then, and index and value will return UNDEFINED. An iterator in that state need not keep track of positions, so it's undefined what happens if it's "moved back" into the set of items.

Backward movement for iterators is optional. It's supported if and only if `-() is defined, but even then it's undefined how far back the iterator can move. Therefore iterators may support only a limited amount of backward movement, e.g. when they access a stream through a limited buffer. If such an iterator is moved back past the limit then it'll behave as if it's pointing entirely outside the data set (see above).

An iterator that doesn't support backward movement at all should throw an error if it's attempted.

predef::get_iterator, lfun::_get_iterator, Array.Iterator, Mapping.Iterator, Multiset.Iterator, String.Iterator, String.SplitIterator.

Initialize this iterator to access a data set in data. The type of data is specific to the iterator implementation. An iterator may also access some implicit data set, in which case data isn't specified at all.

The iterator initially points to the first item in the data set, if there is any.

The iterator need not support being reused, so this function is typically static.

Returns 0 (zero) when the iterator points to an item, 1 otherwise.

0
1

Returns a clone of this iterator which is advanced the specified number of steps. The amount may be negative to move backwards. If the iterator doesn't support backward movement it should throw an exception in that case.

Iterator

Advance this iterator the specified number of steps and return it. The amount may be negative to move backwards. If the iterator doesn't support backward movement it should throw an exception in that case.

foreach calls this function with a step value of 1.

foreach will call this function even when the the iterator has more than one reference. If you want to loop over a copy of the iterator, you can create a copy by adding 0 (zero) to it:

Iterator iterator; ... foreach(iterator+0; mixed index; mixed value) { ... }

Even though this function is an lfun, it is often beneficial to not declare it static, since code might want to advance the iterator by hand.

Iterator

This lfun should be defined if and only if the iterator supports backward movement to some degree. It should back up the specified number of steps. The amount may be negative to move forward.

Iterator

Returns the current index, or UNDEFINED if the iterator doesn't point to any item.

If there's no obvious index set then the index is the current position in the data set, counting from 0.

Returns the current value, or UNDEFINED if the iterator doesn't point to any item.

Returns the total number of items in the data set according to this iterator. If the size of the data set is unlimited or unknown then this function shouldn't be defined.

If this function is defined then it sets the iterator to point to a random item in the accessible set. The random distribution should be rectangular within that set, and the pseudorandom sequence provided by random should be used.

If this function is defined then it resets the iterator to point to the first item.

Returns zero if there are no items at all in the data set, one otherwise.

It's not enough to set the iterator to the earliest accessible item. If the iterator doesn't support backing up to the original start position then this function should not be implemented.

0
1

If this function is defined it should advance the iterator one step, just like `+=(1) would do.

Returns 1 if it succeeded in advancing, and 0 (zero) at end of iterator.

If this function is defined it should set the iterator at the specified index.

It should be possible to set the index at the end of the iterator.

An object of this class is returned by get_iterator() when called with a multiset.

get_iterator

predef::Iterator

Creates and returns a canonical iterator for data.

If data is an object with lfun::_get_iterator defined then it's called in it to create the iterator.

If data is an object that lacks lfun::_get_iterator then it's assumed to already be an iterator object, and is simply returned.

If data is an array, an Array.Iterator object will be returned.

If data is a mapping, a Mapping.Iterator object will be returned

If data is a multiset, a Multiset.Iterator object will be returned

If data is a string, a String.Iterator object will be returned

This function is used by foreach to get an iterator for an object.

Iterator, lfun::_get_iterator

Iterator

These are aliases for the corresponding functions in Pike.DefaultBackend.

Pike.Backend()->call_out(), Pike.Backend()->_do_call_outs(), Pike.Backend()->find_call_out(), Pike.Backend()->remove_call_out(), Pike.Backend()->call_out_info()

``
``
``
``

Returns the default module from which global symbols will be fetched.

Returns the default module, or 0 (zero).

If 0 (zero) is returned the compiler use the mapping returned by all_constants() as fallback.

get_predefines()

Called by compile() to report warnings.

File which triggered the warning.

Line which triggered the warning.

Warning message.

compile_error()

Called by compile() and cpp() when they encounter errors in the code they compile.

File where the error was detected.

Line where the error was detected.

Description of error.

compile_warning().

Called by compile() and cpp() if they trigger exceptions.

Called by cpp() to get the set of global symbols.

Returns a mapping from symbol name to symbol value. Returns zero on failure.

resolv(), get_default_module()

Called by compile() and cpp() to resolv module references.

Returns the resolved value, or UNDEFINED on failure.

get_predefines()

CompilationHandler

Called by compile() and cpp() to handle import directives specifying specific paths.

Returns the resolved value, or UNDEFINED on failure.

CompilationHandler

Called by cpp() to resolv #include and #string directives.

File that was requested for inclusion.

File where the directive was found.

Specifies reference method.

0

Directive was #include <header_file>.

1

Directive was #include "header_file".

Returns the filename to pass to read_include() if found, and 0 (zero) on failure.

read_include()

0 1

Called by cpp() to read included files.

Filename as returned by handle_include().

Returns a string with the content of the header file on success, and 0 (zero) on failure.

handle_include()

The undefined value; ie a zero for which zero_type() returns 1.

Builtin read only variable that evaluates to the current object.

this_program, this_object()

Builtin constant that evaluates to the current program.

this, this_object()

Program used internally by the compiler.

__placeholder_object

Object used internally by the compiler.

__null_program

Same as sprintf("%t",x);

sprintf()

Extract a column from a two-dimensional array.

This function is exactly equivalent to:

map(data, lambda(mixed x,mixed y) { return x[y]; }, index)

Except of course it is a lot shorter and faster. That is, it indices every index in the array data on the value of the argument index and returns an array with the results.

rows()

This function creates a multiset from an array.

aggregate_multiset()

This function changes the trace level for the subsystem identified by facility to level. If facility is zero or left out, it changes the global trace level which affects all subsystems.

Enabling tracing causes messages to be printed to stderr. A higher trace level includes the output from all lower levels. The lowest level is zero which disables all trace messages.

See the -t command-line option for more information.

If facility is specified then there is typically only one trace level for it, i.e. it's an on-or-off toggle. The global trace levels, when facility isn't specified, are:

1

Trace calls to Pike functions and garbage collector runs.

2

Trace calls to builtin functions.

3

Trace every interpreted opcode.

4

Also trace the opcode arguments.

Valid facilities are:

"gc"

Trace the start and end of each run of the garbage collector. The setting is never thread local.

Trace levels are normally thread local, so changes affect only the current thread. To change the level in all threads, pass a nonzero value in this argument.

The old trace level in the current thread is returned.

Convert the output from a previous call to time() into a readable string containing the current year, month, day and time.

Like localtime, this function might throw an error if the ctime(2) call failed on the system. It's platform dependent what time ranges that function can handle, e.g. Windows doesn't handle a negative timestamp.

time(), localtime(), mktime(), gmtime()

Make a mapping from two arrays.

Makes a mapping ind[x]:val[x], 0 <= x < sizeof(ind).

ind and val must have the same size.

This is the inverse operation of indices() and values().

indices(), values()

If map is an object that implements lfun::_m_delete(), that function will be called with index as its single argument.

Otherwise if map is a mapping the entry with index index will be removed from map destructively.

If the mapping does not have an entry with index index, nothing is done.

The value that was removed will be returned.

Note that m_delete() changes map destructively.

mappingp()

Returns the weak flag settings for m. It's a combination of Pike.WEAK_INDICES and Pike.WEAK_VALUES.

Return the name of the function f.

If f is a global function defined in the runtime 0 (zero) will be returned.

function_object()

``

Return the object the function f is in.

If f is a global function defined in the runtime 0 (zero) will be returned.

Zero will also be returned if f is a constant in the parent class. In that case function_program() can be used to get the parent program.

function_name(), function_program()

``

Return the program the function f is in.

If f is a global function defined in the runtime 0 (zero) will be returned.

function_name(), function_object()

``

If random is called with an object, lfun::random will be called in the object.

lfun::_random

This function returns a random number in the range 0 - max-1.

random_seed()

Returns a random element from x.

Returns a random index-value pair from the mapping.

FIXME: This documentation is not up to date!

Get a description of the current call stack.

The description is returned as an array with one entry for each call frame on the stack.

Each entry has this format:

file

A string with the filename if known, else zero.

line

An integer containing the linenumber if known, else zero.

`` fun

The function that was called at this level.

args

The arguments that the function was called with.

The current call frame will be last in the array.

Please note that the frame order may be reversed in a later version (than 7.1) of Pike to accommodate for deferred backtraces.

Note that the arguments reported in the backtrace are the current values of the variables, and not the ones that were at call-time. This can be used to hide sensitive information from backtraces (eg passwords).

catch(), throw()

Pike.BacktraceFrame

Report the version of Pike. Does the same as

sprintf("Pike v%d.%d release %d", __REAL_VERSION__, __REAL_MINOR__, __REAL_BUILD__);

__VERSION__, __MINOR__, __BUILD__, __REAL_VERSION__, __REAL_MINOR__, __REAL_BUILD__,

This function checks if the values a and b are equal.

For all types but arrays, multisets and mappings, this operation is the same as doing a == b. For arrays, mappings and multisets however, their contents are checked recursively, and if all their contents are the same and in the same place, they are considered equal.

copy_value()

Construct an array with the arguments as indices.

This function could be written in Pike as:

array aggregate(mixed ... elems) { return elems; }

Arrays are dynamically allocated there is no need to declare them like int a[10]=allocate(10); (and it isn't possible either) like in C, just array(int) a=allocate(10); will do.

sizeof(), arrayp(), allocate()

Return an integer derived from the string s. The same string will always hash to the same value, also between processes.

If max is given, the result will be >= 0 and < max, otherwise the result will be >= 0 and <= 0x7fffffff.

This function is provided for backward compatibility reasons.

This function is byte-order dependant for wide strings.

hash(), hash_7_0()

Return an integer derived from the string s. The same string always hashes to the same value, also between processes.

If max is given, the result will be >= 0 and < max, otherwise the result will be >= 0 and <= 0x7fffffff.

This function is provided for backward compatibility reasons.

This function is not NUL-safe, and is byte-order dependant.

hash(), hash_7_4()

Return an integer derived from the string s. The same string always hashes to the same value, also between processes, architectures, and Pike versions (see compatibility notes below, though).

If max is given, the result will be >= 0 and < max, otherwise the result will be >= 0 and <= 0x7fffffff.

The hash algorithm was changed in Pike 7.5. If you want a hash that is compatible with Pike 7.4 and earlier, use hash_7_4(). The difference only affects wide strings.

The hash algorithm was also changed in Pike 7.1. If you want a hash that is compatible with Pike 7.0 and earlier, use hash_7_0().

hash_7_0(), hash_7_4(), hash_value

Return a hash value for the argument. It's an integer in the native integer range.

The hash will be the same for the same value in the running process only (the memory address is typically used as the basis for the hash value).

If the value is an object with an lfun::__hash, that function is called and its result is returned.

This is the hashing method used by mappings.

hash

Copy a value recursively.

If the result value is changed destructively (only possible for multisets, arrays and mappings) the copied value will not be changed.

The resulting value will always be equal to the copied (as tested with the function equal()), but they may not the the same value (as tested with `==()).

equal()

Convert a string or character to lower case.

Returns a copy of the string s with all upper case characters converted to lower case, or the character c converted to lower case.

Assumes the string or character to be coded according to ISO-10646 (aka Unicode). If they are not, Locale.Charset.decoder can do the initial conversion for you.

Prior to Pike 7.5 this function only accepted strings.

upper_case(), Locale.Charset.decoder

Convert a string or character to upper case.

Returns a copy of the string s with all lower case characters converted to upper case, or the character c converted to upper case.

Assumes the string or character to be coded according to ISO-10646 (aka Unicode). If they are not, Locale.Charset.decoder can do the initial conversion for you.

Prior to Pike 7.5 this function only accepted strings.

lower_case(), Locale.Charset.decoder

Returns a string of random characters 0-255 with the length len.

This function sets the initial value for the random generator.

random()

Returns the number of arguments given when the previous function was called.

This is useful for functions that take a variable number of arguments.

call_function()

Search for needle in haystack. Return the position of needle in haystack or -1 if not found.

If the optional argument start is present search is started at this position.

When haystack is a string needle must be a string or an int, and the first occurrence of the string or int is returned.

When haystack is an array, needle is compared only to one value at a time in haystack.

When haystack is a mapping, search() tries to find the index connected to the data needle. That is, it tries to lookup the mapping backwards. If needle isn't present in the mapping, zero is returned, and zero_type() will return 1 for this zero.

When haystack is an object implementing lfun::_search(), the result of calling lfun::_search() with needle will be returned.

If haystack is an object that doesn't implement lfun::_search() it is assumed to be an Iterator, and implement Iterator()->index(), Iterator()->value(), and Iterator()->next(). search() will then start comparing elements with `==() until a match with needle is found. If needle is found haystack will be advanced to the element, and the iterator index will be returned. If needle is not found, haystack will be advanced to the end (and will thus evaluate to false), and a zero with zero_type 1 will be returned.

If start is supplied to an iterator object without an lfun::_search(), haystack will need to implement Iterator()->set_index().

indices(), values(), zero_type()

Returns 1 if the string s starts with prefix, returns 0 (zero) otherwise.

Returns 1 if the string s ends with suffix, returns 0 (zero) otherwise.

Search for index in haystack.

Returns 1 if index is in the index domain of haystack, or 0 (zero) if not found.

This function is equivalent to (but sometimes faster than):

search(indices(haystack), index) != -1

A negative index in strings and arrays as recognized by the index operators `[]() and `[]=() is not considered a proper index by has_index()

has_value(), indices(), search(), values(), zero_type()

Search for value in haystack.

Returns 1 if value is in the value domain of haystack, or 0 (zero) if not found.

This function is in all cases except when both arguments are strings equivalent to (but sometimes faster than):

search(values(haystack), value) != -1

If both arguments are strings, has_value() is equivalent to:

search(haystack, value) != -1

has_index(), indices(), search(), values(), zero_type()

Add a new predefined constant.

This function is often used to add builtin functions. All programs compiled after the add_constant() function has been called can access value by the name name.

If there is a constant called name already, it will be replaced by by the new definition. This will not affect already compiled programs.

Calling add_constant() without a value will remove that name from the list of constants. As with replacing, this will not affect already compiled programs.

all_constants()

Concatenate a relative path to an absolute path and remove any "//", "/.." or "/." to produce a straightforward absolute path as result.

combine_path_nt() concatenates according to NT-filesystem conventions, while combine_path_unix() concatenates according to UNIX-style. combine_path_amigaos() concatenates according to AmigaOS filesystem conventions.

combine_path() is equvivalent to combine_path_unix() on UNIX-like operating systems, and equivalent to combine_path_nt() on NT-like operating systems, and equivalent to combine_path_amigaos() on AmigaOS-like operating systems.

getcwd(), Stdio.append_path()

Return the type of zero.

There are many types of zeros out there, or at least there are two. One is returned by normal functions, and one returned by mapping lookups and find_call_out() when what you looked for wasn't there. The only way to separate these two kinds of zeros is zero_type().

When doing a find_call_out() or mapping lookup, zero_type() on this value will return 1 if there was no such thing present in the mapping, or if no such call_out could be found.

If the argument to zero_type() is a destructed object or a function in a destructed object, 2 will be returned.

In all other cases zero_type() will return 0 (zero).

find_call_out()

Converts a string into an UTF16 compliant byte-stream.

Throws an error if characters not legal in an UTF16 stream are encountered. Valid characters are in the range 0x00000 - 0x10ffff, except for characters 0xfffe and 0xffff.

Characters in range 0x010000 - 0x10ffff are encoded using surrogates.

Locale.Charset.decoder(), string_to_utf8(), unicode_to_string(), utf8_to_string()

Converts an UTF16 byte-stream into a string.

This function did not decode surrogates in Pike 7.2 and earlier.

Locale.Charset.decoder(), string_to_unicode(), string_to_utf8(), utf8_to_string()

Converts a string into an UTF8 compliant byte-stream.

Throws an error if characters not valid in an UTF8 stream are encountered. Valid characters are in the range 0x00000000 - 0x7fffffff.

If extended is 1, characters in the range 0x80000000-0xfffffffff will also be accepted, and encoded using a non-standard UTF8 extension.

Locale.Charset.encoder(), string_to_unicode(), unicode_to_string(), utf8_to_string()

Converts an UTF-8 byte-stream into a string.

Throws an error if the stream is not a legal UTF-8 byte-stream.

Accepts and decodes the extension used by string_to_utf8(), if extended is 1.

In conformance with RFC 3629 and Unicode 3.1 and later, non-shortest forms are not decoded. An error will be thrown instead.

Locale.Charset.encoder(), string_to_unicode(), string_to_utf8(), unicode_to_string()

Returns a mapping containing all global constants, indexed on the name of the constant, and with the value of the constant as value.

add_constant()

Allocate an array of size elements. If init is specified then each element is initialized by copying that value recursively.

sizeof(), aggregate(), arrayp()

Returns the object we are currently evaluating in.

level might be used to access the object of a surrounding class: The object at level 0 is the current object, the object at level 1 is the one belonging to the class that surrounds the class that the object comes from, and so on.

As opposed to a qualified this reference such as global::this, this function doesn't always access the objects belonging to the lexically surrounding classes. If the class containing the call has been inherited then the objects surrounding the inheriting class are accessed.

Throw value to a waiting catch.

If no catch is waiting the global error handling will send the value to master()->handle_error().

If you throw an array with where the first index contains an error message and the second index is a backtrace, (the output from backtrace()) then it will be treated exactly like a real error by overlying functions.

catch

Exit the whole Pike program with the given returncode.

Using exit() with any other value than 0 (zero) indicates that something went wrong during execution. See your system manuals for more information about return codes.

The arguments after the returncode will be used for a call to werror to output a message on stderr.

_exit()

This function does the same as exit, but doesn't bother to clean up the Pike interpreter before exiting. This means that no destructors will be called, caches will not be flushed, file locks might not be released, and databases might not be closed properly.

Use with extreme caution.

exit()

This function returns the number of seconds since 00:00:00 UTC, 1 Jan 1970.

The second syntax does not query the system for the current time. Instead the latest done by the pike process is returned again. That's slightly faster but can be wildly inaccurate. Pike queries the time internally when a thread has waited for something, typically in sleep or in a backend (see Pike.Backend).

The third syntax can be used to measure time more preciely than one second. It return how many seconds has passed since t. The precision of this function varies from system to system.

ctime(), localtime(), mktime(), gmtime(), System.gettimeofday, gethrtime

1 1
2

This function crypts and verifies a short string (only the first 8 characters are significant).

The first syntax crypts the string password into something that is hopefully hard to decrypt.

The second syntax is used to verify typed_password against crypted_password, and returns 1 if they match, and 0 (zero) otherwise.

0
1

Mark an object as destructed.

Calls o->destroy(), and then clears all variables in the object. If no argument is given, the current object is destructed.

All pointers and function pointers to this object will become zero. The destructed object will be freed from memory as soon as possible.

Return an array of all valid indices for the value x.

For strings and arrays this is simply an array of ascending numbers.

For mappings and multisets, the array may contain any value.

For objects which define lfun::_indices() that return value will be used.

For other objects an array with all non-static symbols will be returned.

values()

Return an array of all possible values from indexing the value x.

For strings an array of int with the ISO10646 codes of the characters in the string is returned.

For a multiset an array filled with ones (1) is returned.

For arrays a single-level copy of x is returned.

For mappings the array may contain any value.

For objects which define lfun::_values() that return value will be used.

For other objects an array with the values of all non-static symbols will be returned.

indices()

Returns the next object from the list of all objects.

All objects are stored in a linked list.

If no arguments have been given next_object() will return the first object from the list.

If o has been specified the object after o on the list will be returned.

This function is not recomended to use.

destruct()

Return the program from which o was instantiated. If the object was instantiated from a class using parent references the generating function will be returned.

If o is not an object or has been destructed 0 (zero) will be returned.

Reverses a string, array or int.

This function reverses a string, char by char, an array, value by value or an int, bit by bit and returns the result. It's not destructive on the input value.

Reversing strings can be particularly useful for parsing difficult syntaxes which require scanning backwards.

sscanf()

Generic replace function.

This function can do several kinds replacement operations, the different syntaxes do different things as follows:

If all the arguments are strings, a copy of s with every occurrence of from replaced with to will be returned. Special case: to will be inserted between every character in s if from is the empty string.

If the first argument is a string, and the others array(string), a string with every occurrance of from[i] in s replaced with to[i] will be returned. Instead of the arrays from and to a mapping equvivalent to mkmapping(from, to) can be used.

If the first argument is an array or mapping, the values of a which are `==() with from will be replaced with to destructively. a will then be returned.

Note that replace() on arrays and mappings is a destructive operation.

Compile a string to a program.

This function takes a piece of Pike code as a string and compiles it into a clonable program.

The optional argument handler is used to specify an alternative error handler. If it is not specified the current master object will be used.

The optional arguments major and minor are used to tell the compiler to attempt to be compatible with Pike major.minor.

Note that source must contain the complete source for a program. It is not possible to compile a single expression or statement.

Also note that compile() does not preprocess the program. To preprocess the program you can use compile_string() or call the preprocessor manually by calling cpp().

compile_string(), compile_file(), cpp(), master()

Set the value m to use weak or normal references in its indices and/or values (whatever is applicable). state is a bitfield built by using | between the following flags:

Pike.WEAK_INDICES

Use weak references for indices. Only applicable for multisets and mappings.

Pike.WEAK_VALUES

Use weak references for values. Only applicable for arrays and mappings.

Pike.WEAK

Shorthand for Pike.WEAK_INDICES|Pike.WEAK_VALUES.

If a flag is absent, the corresponding field will use normal references. state can also be 1 as a compatibility measure; it's treated like Pike.WEAK.

m will be returned.

Returns 1 if arg is an object, 0 (zero) otherwise.

mappingp(), programp(), arrayp(), stringp(), functionp(), multisetp(), floatp(), intp()

Returns 1 if arg is a function, 0 (zero) otherwise.

mappingp(), programp(), arrayp(), stringp(), objectp(), multisetp(), floatp(), intp()

Returns 1 if arg is a callable, 0 (zero) otherwise.

mappingp(), programp(), arrayp(), stringp(), objectp(), multisetp(), floatp(), intp()

This function makes the program stop for s seconds.

Only signal handlers can interrupt the sleep, and only when abort_on_signal is set. If more than one thread is running the signal must be sent to the sleeping thread. Other callbacks are not called during sleep.

If s is zero then this thread will yield to other threads but not sleep otherwise. Note that Pike yields internally at regular intervals so it's normally not necessary to do this.

signal(), delay()

This function makes the program stop for s seconds.

Only signal handlers can interrupt the sleep. Other callbacks are not called during delay. Beware that this function uses busy-waiting to achieve the highest possible accuracy.

signal(), sleep()

Force garbage collection.

This function checks all the memory for cyclic structures such as arrays containing themselves and frees them if appropriate. It also frees up destructed objects and things with only weak references.

Normally there is no need to call this function since Pike will call it by itself every now and then. (Pike will try to predict when 20% of all arrays/object/programs in memory is 'garbage' and call this routine then.)

The amount of garbage is returned. This is the number of arrays, mappings, multisets, objects and programs that had no nonweak external references during the garbage collection. It's normally the same as the number of freed things, but there might be some difference since destroy() functions are called during freeing, which can cause more things to be freed or allocated.

Pike.gc_parameters, Debug.gc_status

Returns 1 if arg is a program, 0 (zero) otherwise.

mappingp(), intp(), arrayp(), stringp(), objectp(), multisetp(), floatp(), functionp()

Returns 1 if arg is an int, 0 (zero) otherwise.

mappingp(), programp(), arrayp(), stringp(), objectp(), multisetp(), floatp(), functionp()

Returns 1 if arg is a mapping, 0 (zero) otherwise.

intp(), programp(), arrayp(), stringp(), objectp(), multisetp(), floatp(), functionp()

Returns 1 if arg is an array, 0 (zero) otherwise.

intp(), programp(), mappingp(), stringp(), objectp(), multisetp(), floatp(), functionp()

Returns 1 if arg is a multiset, 0 (zero) otherwise.

intp(), programp(), arrayp(), stringp(), objectp(), mappingp(), floatp(), functionp()

Returns 1 if arg is a string, 0 (zero) otherwise.

intp(), programp(), arrayp(), multisetp(), objectp(), mappingp(), floatp(), functionp()

Returns 1 if arg is a float, 0 (zero) otherwise.

intp(), programp(), arrayp(), multisetp(), objectp(), mappingp(), stringp(), functionp()

Sort arrays destructively.

This function sorts the array index destructively. That means that the array itself is changed and returned, no copy is created.

If extra arguments are given, they are supposed to be arrays of the same size as index. Each of these arrays will be modified in the same way as index. I.e. if index 3 is moved to position 0 in index index 3 will be moved to position 0 in all the other arrays as well.

The sort order is as follows:

Integers and floats are sorted in ascending order.

Strings are sorted primarily on the first characters that are different, and secondarily with shorter strings before longer. Different characters are sorted in ascending order on the character value. Thus the sort order is not locale dependent.

Arrays are sorted recursively on the first element. Empty arrays are sorted before nonempty ones.

Multisets are sorted recursively on the first index. Empty multisets are sorted before nonempty ones.

Objects are sorted in ascending order according to `<(), `>() and `==().

Other types aren't reordered.

Different types are sorted in this order: Arrays, mappings, multisets, objects, functions, programs, strings, types, integers and floats. Note however that objects can control their ordering wrt other types with `<, `> and `==, so this ordering of types only applies to objects without those functions.

The first argument is returned.

The sort is stable, i.e. elements that are compare-wise equal aren't reordered.

Array.sort_array, reverse()

Select a set of rows from an array.

This function is en optimized equivalent to:

map(index, lambda(mixed x) { return data[x]; })

That is, it indices data on every index in the array index and returns an array with the results.

column()

Convert seconds since 00:00:00 UTC, Jan 1, 1970 into components.

This function works like localtime() but the result is not adjusted for the local time zone.

localtime(), time(), ctime(), mktime()

Convert seconds since 00:00:00 UTC, 1 Jan 1970 into components.

This function returns a mapping with the following components:

- 0 60 "sec"

Seconds over the minute.

- 0 59 "min"

Minutes over the hour.

- 0 23 "hour"

Hour of the day.

- 1 31 "mday"

Day of the month.

- 0 11 "mon"

Month of the year.

- 0 "year"

Year since 1900.

- 0 6 "wday"

Day of week (0 = Sunday).

- 0 365 "yday"

Day of the year.

- 0 1 "isdst"

Is daylight savings time.

- "timezone"

Offset from UTC, including daylight savings time adjustment.

An error is thrown if the localtime(2) call failed on the system. It's platform dependent what time ranges that function can handle, e.g. Windows doesn't handle a negative timestamp.

Prior to Pike 7.5 the field "timezone" was sometimes not present, and was sometimes not adjusted for daylight savings time.

Calendar, gmtime(), time(), ctime(), mktime()

This function converts information about date and time into an integer which contains the number of seconds since 00:00:00 UTC, Jan 1, 1970.

You can either call this function with a mapping containing the following elements:

- 0 60 "sec"

Seconds over the minute.

- 0 59 "min"

Minutes over the hour.

- 0 23 "hour"

Hour of the day.

- 1 31 "mday"

Day of the month.

- 0 11 "mon"

Month of the year.

- 0 "year"

Year since 1900.

- 0 1 "isdst"

Is daylight savings time.

- "timezone"

The timezone offset from UTC in seconds. If left out, the time will be calculated in the local timezone.

Or you can just send them all on one line as the second syntax suggests.

On some operating systems (notably AIX), dates before 00:00:00 UTC, Jan 1, 1970 are not supported.

On most systems, the supported range of dates are Dec 13, 1901 20:45:52 UTC through Jan 19, 2038 03:14:07 UTC (inclusive).

time(), ctime(), localtime(), gmtime()

Match strings against globs.

In a glob string a question sign matches any character and an asterisk matches any string.

When the second argument is a string and str matches the glob glob 1 will be returned, 0 (zero) otherwise.

If the second array is an array and array containing the strings in arr that match glob will be returned.

sscanf(), Regexp

0
1

Find the next object/array/mapping/multiset/program or string.

All objects, arrays, mappings, multisets, programs and strings are stored in linked lists inside Pike. This function returns the next item on the corresponding list. It is mainly meant for debugging the Pike runtime, but can also be used to control memory usage.

next_object(), _prev()

Find the previous object/array/mapping/multiset or program.

All objects, arrays, mappings, multisets and programs are stored in linked lists inside Pike. This function returns the previous item on the corresponding list. It is mainly meant for debugging the Pike runtime, but can also be used to control memory usage.

Unlike _next() this function does not work on strings.

next_object(), _next()

Return the number of references o has.

It is mainly meant for debugging the Pike runtime, but can also be used to control memory usage.

Note that the number of references will always be at least one since the value is located on the stack when this function is executed.

_next(), _prev()

``

Return the runtime type of x.

typeof()

Replace the master object with o.

This will let you control many aspects of how Pike works, but beware that master.pike may be required to fill certain functions, so it is usually a good idea to have your master inherit the original master and only re-define certain functions.

FIXME: Tell how to inherit the master.

master()

Return the current master object.

replace_master()

Return the CPU time that has been consumed by this process or thread. -1 is returned if the system couldn't determine it. The time is normally returned in microseconds, but if the optional argument nsec is nonzero it's returned in nanoseconds.

The CPU time includes both user and system time, i.e. it's approximately the same thing you would get by adding together the "utime" and "stime" fields returned by System.getrusage (but perhaps with better accuracy). It's however system dependent whether or not it's the time consumed in all threads or in the current one only; System.CPU_TIME_IS_THREAD_LOCAL tells which.

The actual accuracy on many systems is significantly less than milliseconds or nanoseconds.

The garbage collector might run automatically at any time. The time it takes is not included in the figure returned by this function, so that normal measurements aren't randomly clobbered by it. Explicit calls to gc are still included, though.

The special function gauge is implemented with this function.

System.CPU_TIME_IS_THREAD_LOCAL, gauge(), System.getrusage(), gethrtime()

Return the real time since some arbitrary event in the past. The time is normally returned in microseconds, but if the optional argument nsec is nonzero it's returned in nanoseconds.

The actual accuracy on many systems is significantly less than milliseconds or nanoseconds.

time(), System.gettimeofday(), gethrvtime()

Get profiling information.

Returns an array with two elements.

num_clones

The first element is the number of times the program prog has been instantiated.

fun_prof_info

The second element is mapping from function name to an array with three elements.

num_calls

The first element is the number of times the function has been called.

total_time

The second element is the total time (in milliseconds) spent executing this function, and any functions called from it.

self_time

The third element is the time (in milliseconds) actually spent in this function so far.

This function is only available if the runtime was compiled with the option --with-profiling.

Find out if an object identifier is a variable.

This function returns 1 if var exists as a non-static variable in o, and returns 0 (zero) otherwise.

indices(), values()

0
1

Applies fun to the elements in arr and collects the results.

arr is treated as a set of elements, as follows:

fun is applied in order to each element. The results are collected, also in order, to a value of the same type as arr, which is returned.

fun is applied to the values, and each result is assigned to the same index in a new mapping, which is returned.

The program is treated as a mapping containing the identifiers that are indexable from it and their values.

If there is a lfun::cast method in the object, it's called to try to cast the object to an array, a mapping, or a multiset, in that order, which is then handled as described above.

fun is applied in different ways depending on its type:

fun is called for each element. It gets the current element as the first argument and extra as the rest. The result of the call is collected.

fun is used as a function like above, i.e. the lfun::`() method in it is called.

fun is indexed with each element. The result of that is collected.

Each element that is callable is called with extra as arguments. The result of the calls are collected. Elements that aren't callable gets zero as result.

Each element is indexed with the given string. If the result of that is zero then a zero is collected, otherwise it's called with extra as arguments and the result of that call is collected.

This is typically used when arr is a collection of objects, and fun is the name of some function in them.

The function is never destructive on arr.

filter(), enumerate(), foreach()

Filters the elements in arr through fun.

arr is treated as a set of elements to be filtered, as follows:

Each element is filtered with fun. The return value is of the same type as arr and it contains the elements that fun accepted. fun is applied in order to each element, and that order is retained between the kept elements.

If fun is an array, it should have the same length as arr. In this case, the elements in arr are kept where the corresponding positions in fun are nonzero. Otherwise fun is used as described below.

The values are filtered with fun, and the index/value pairs it accepts are kept in the returned mapping.

The program is treated as a mapping containing the identifiers that are indexable from it and their values.

If there is a lfun::cast method in the object, it's called to try to cast the object to an array, a mapping, or a multiset, in that order, which is then filtered as described above.

Unless something else is mentioned above, fun is used as filter like this:

fun is called for each element. It gets the current element as the first argument and extra as the rest. The element is kept if it returns true, otherwise it's filtered out.

The object is used as a function like above, i.e. the lfun::`() method in it is called.

fun is indexed with each element. The element is kept if the result is nonzero, otherwise it's filtered out.

Each element that is callable is called with extra as arguments. The element is kept if the result of the call is nonzero, otherwise it's filtered out. Elements that aren't callable are also filtered out.

Each element is indexed with the given string. If the result of that is zero then the element is filtered out, otherwise the result is called with extra as arguments. The element is kept if the return value is nonzero, otherwise it's filtered out.

This is typically used when arr is a collection of objects, and fun is the name of some predicate function in them.

The function is never destructive on arr.

map(), foreach()

Create an array with an enumeration, useful for initializing arrays or as first argument to map() or foreach().

The defaults are: step = 1, start = 0, operator = `+

# Advanced use

The resulting array is calculated like this:

array enumerate(int n, mixed step, mixed start, function operator) { array res = allocate(n); for (int i=0; i < n; i++) { res[i] = start; start = operator(start, step); } return res; }

map(), foreach()

``

This function first posts a notice to all threads that it is time to stop. It then waits until all threads actually *have* stopped, and then then returns a lock object. All other threads will be blocked from running until that object has been freed/destroyed.

It's mainly useful to do things that require a temporary uid/gid change, since on many OS the effective user and group applies to all threads.

You should make sure that the returned object is freed even if some kind of error is thrown. That means in practice that it should only have references (direct or indirect) from function local variables. Also, it shouldn't be referenced from cyclic memory structures, since those are only destructed by the periodic gc. (This advice applies to mutex locks in general, for that matter.)

_disable_threads

Trap signals.

This function allows you to trap a signal and have a function called when the process receives a signal. Although it IS possible to trap SIGBUS, SIGSEGV etc. I advice you not to. Pike should not receive any such signals and if it does it is because of bugs in the Pike interpreter. And all bugs should be reported, no matter how trifle.

The callback will receive the signal number as its only argument.

See the documentation for kill() for a list of signals.

If no second argument is given, the signal handler for that signal is restored to the default handler.

If the second argument is zero, the signal will be completely ignored.

kill(), signame(), signum()

``

Get a signal number given a descriptive string.

This function is the inverse of signame().

signame(), kill(), signal()

Returns a string describing the signal sig.

kill(), signum(), signal()

Fork the process in two.

Fork splits the process in two, and for the parent it returns a pid object for the child. Refer to your Unix manual for further details.

This function can cause endless bugs if used without proper care.

This function is disabled when using threads.

This function is not available on all platforms.

The most common use for fork is to start sub programs, which is better done with Process.create_process().

Process.create_process()

Send a signal to another process. Returns nonzero if it worked, zero otherwise. errno may be used in the latter case to find out what went wrong.

Some signals and their supposed purpose:

SIGHUP

Hang-up, sent to process when user logs out.

SIGINT

Interrupt, normally sent by ctrl-c.

SIGQUIT

Quit, sent by ctrl-\.

SIGILL

Illegal instruction.

SIGTRAP

Trap, mostly used by debuggers.

SIGABRT

Aborts process, can be caught, used by Pike whenever something goes seriously wrong.

SIGEMT

Emulation trap.

SIGFPE

Floating point error (such as division by zero).

SIGKILL

Really kill a process, cannot be caught.

SIGBUS

Bus error.

SIGSEGV

Segmentation fault, caused by accessing memory where you shouldn't. Should never happen to Pike.

SIGSYS

Bad system call. Should never happen to Pike.

SIGPIPE

Broken pipe.

SIGALRM

Signal used for timer interrupts.

SIGTERM

Termination signal.

SIGUSR1

Signal reserved for whatever you want to use it for. Note that some OSs reserve this signal for the thread library.

SIGUSR2

Signal reserved for whatever you want to use it for. Note that some OSs reserve this signal for the thread library.

SIGCHLD

Child process died. This signal is reserved for internal use by the Pike run-time.

SIGPWR

Power failure or restart.

SIGWINCH

Window change signal.

SIGURG

Urgent socket data.

SIGIO

Pollable event.

SIGSTOP

Stop (suspend) process.

SIGTSTP

Stop (suspend) process. Sent by ctrl-z.

SIGCONT

Continue suspended.

SIGTTIN

TTY input for background process.

SIGTTOU

TTY output for background process.

SIGVTALRM

Virtual timer expired.

SIGPROF

Profiling trap.

SIGXCPU

Out of CPU.

SIGXFSZ

File size limit exceeded.

SIGSTKFLT

Stack fault

Note that you have to use signame to translate the name of a signal to its number.

Note that the kill function is not available on platforms that do not support signals. Some platforms may also have signals not listed here.

signal(), signum(), signame(), fork()

Returns the process ID of this process.

System.getppid(), System.getpgrp()

Set an alarm clock for delivery of a signal.

alarm() arranges for a SIGALRM signal to be delivered to the process in seconds seconds.

If seconds is 0 (zero), no new alarm will be scheduled.

Any previous alarms will in any case be canceled.

Returns the number of seconds remaining until any previously scheduled alarm was due to be delivered, or zero if there was no previously scheduled alarm.

This function is only available on platforms that support signals.

ualarm(), signal(), call_out()

Set an alarm clock for delivery of a signal.

alarm() arranges for a SIGALRM signal to be delivered to the process in useconds microseconds.

If useconds is 0 (zero), no new alarm will be scheduled.

Any previous alarms will in any case be canceled.

Returns the number of microseconds remaining until any previously scheduled alarm was due to be delivered, or zero if there was no previously scheduled alarm.

This function is only available on platforms that support signals.

alarm(), signal(), call_out()

This function puts the callback in a queue of callbacks to call when pike exits.

Please note that atexit callbacks are not called if Pike exits abnormally.

exit(), _exit()

``

Load a binary module.

This function loads a module written in C or some other language into Pike. The module is initialized and any programs or constants defined will immediately be available.

When a module is loaded the C function pike_module_init() will be called to initialize it. When Pike exits pike_module_exit() will be called. These two functions must be available in the module.

The current working directory is normally not searched for dynamic modules. Please use "./name.so" instead of just "name.so" to load modules from the current directory.

Codec objects are used by encode_value() and decode_value() to encode and decode objects, functions and programs.

encode_value() and decode_value() will use the current master object as fallback codec object if no codec was specified.

Called by encode_value() to encode objects, functions and programs.

Returns something encodable on success, typically a string. The returned value will be passed to the corresponding objectof(), functionof() or programof() by decode_value().

Returns UNDEFINED on failure.

encode_value() has fallbacks for some classes of objects, functions and programs.

objectof(), functionof(), objectof()

``

Decode object encoded in data.

This function is called by decode_value() when it encounters encoded objects.

Encoding of some object as specified by nameof().

Minor version.

Returns the decoded object.

functionof(), programof()

Decode function encoded in data.

This function is called by decode_value() when it encounters encoded functions.

Encoding of some function as specified by nameof().

Minor version.

Returns the decoded function.

objectof(), programof()

Decode program encoded in data.

This function is called by decode_value() when it encounters encoded programs.

Encoding of some program as specified by nameof().

Minor version.

Returns the decoded program.

functionof(), objectof()

Called by decode_value() to register the program that is being decoded. Might get called repeatedly with several other programs that are being decoded recursively. The only safe assumption is that when the top level thing being decoded is a program, then the first call will be with the unfinished embryo that will later become that program.

Returns either zero or a placeholder object. A placeholder object must be a clone of __null_program. When the program is finished, the placeholder object will be converted to a clone of it. This is used for pike module objects.

Code a value into a string.

This function takes a value, and converts it to a string. This string can then be saved, sent to another Pike process, packed or used in any way you like. When you want your value back you simply send this string to decode_value() and it will return the value you encoded.

Almost any value can be coded, mappings, floats, arrays, circular structures etc.

To encode objects, programs and functions, a codec object must be provided.

When only simple types like int, floats, strings, mappings, multisets and arrays are encoded, the produced string is very portable between pike versions. It can at least be read by any later version.

The portability when objects, programs and functions are involved depends mostly on the codec. If the byte code is encoded, i.e. when Pike programs are actually dumped in full, then the string can probably only be read by the same pike version.

decode_value(), sprintf(), encode_value_canonic()

Code a value into a string on canonical form.

Takes a value and converts it to a string on canonical form, much like encode_value(). The canonical form means that if an identical value is encoded, it will produce exactly the same string again, even if it's done at a later time and/or in another Pike process. The produced string is compatible with decode_value().

Note that this function is more restrictive than encode_value() with respect to the types of values it can encode. It will throw an error if it can't encode to a canonical form.

encode_value(), decode_value()

Decode a value from the string coded_value.

This function takes a string created with encode_value() or encode_value_canonic() and converts it back to the value that was coded.

If codec is specified, it's used as the codec for the decode. If no codec is specified, the current master object will be used.

encode_value(), encode_value_canonic()

Codec
cpp::

Run a string through the preprocessor.

Preprocesses the string data with Pike's builtin ANSI-C look-alike preprocessor. If the current_file argument has not been specified, it will default to "-". charset defaults to "ISO-10646".

compile()

String index operator.

String assign index operator.

Inequality test.

Every expression with the != operator becomes a call to this function, i.e. a!=b is the same as predef::`!=(a,b).

This is the inverse of `==(); see that function for further details.

Returns 1 if the test is successful, 0 otherwise.

`==()

0
1

Equality test.

Every expression with the == operator becomes a call to this function, i.e. a==b is the same as predef::`==(a,b).

If more than two arguments are given, each argument is compared with the following one as described below, and the test is successful iff all comparisons are successful.

If the first argument is an object with an lfun::`==(), that function is called with the second as argument, and the test is successful iff its result is nonzero (according to `!).

Otherwise, if the second argument is an object with an lfun::`==(), that function is called with the first as argument, and the test is successful iff its result is nonzero (according to `!).

Otherwise, if the arguments are of different types, the test is unsuccessful. Function pointers to programs are automatically converted to program pointers if necessary, though.

Otherwise the test depends on the type of the arguments:

Successful iff the two integers are numerically equal.

Successful iff the two floats are numerically equal or if both are NaN.

Successful iff the two strings are identical, character for character. (Since all strings are kept unique, this is actually a test whether the arguments point to the same string, and it therefore run in constant time.)

``

Successful iff the two arguments point to the same instance.

Returns 1 if the test is successful, 0 otherwise.

Floats and integers are not automatically converted to test against each other, so e.g. 0==0.0 is false.

Programs are not automatically converted to types to be compared type-wise.

`!(), `!=()

0
1

Less than test.

Every expression with the < operator becomes a call to this function, i.e. a<b is the same as predef::`<(a,b).

If more than two arguments are given, each argument is compared with the following one as described below, and the test is successful iff all comparisons are successful. Thus a single call can be used to test if a whole list of values are in strictly increasing order.

If the first argument is an object with an lfun::`<(), that function is called with the second as argument, and the test is successful iff its result is nonzero (according to `!).

Otherwise, if the second argument is an object with an lfun::`==(), that function is called with the first as argument, and the test is successful iff its result is nonzero (according to `!).

Otherwise, if the arguments are of different types, the test is unsuccessful. Function pointers to programs are automatically converted to program pointers if necessary, though.

Otherwise the test depends on the type of the arguments:

Successful iff the two integers are numerically equal.

Successful iff the two floats are numerically equal or if both are NaN.

Successful iff the two strings are identical, character for character. (Since all strings are kept unique, this is actually a test whether the arguments point to the same string, and it therefore run in constant time.)

``

Successful iff the two arguments point to the same instance.

Returns 1 if the test is successful, 0 otherwise.

`<=(), `>(), `>=()

0
1

Less than or equal test.

Every expression with the <= operator becomes a call to this function, i.e. a<=b is the same as predef::`<=(a,b).

Returns 1 if the arguments are not strictly decreasing, and 0 (zero) otherwise.

This is the inverse of `>().

`<(), `>(), `>=()

0
1

Greater than test.

Every expression with the > operator becomes a call to this function, i.e. a>b is the same as predef::`>(a,b).

Returns 1 if the arguments are strictly decreasing, and 0 (zero) otherwise.

`<(), `<=(), `>=()

0
1

Greater than or equal test.

Every expression with the >= operator becomes a call to this function, i.e. a>=b is the same as predef::`>=(a,b).

Returns 1 if the arguments are not strictly increasing, and 0 (zero) otherwise.

This is the inverse of `<().

`<=(), `>(), `<()

0
1

Addition/concatenation.

Every expression with the + operator becomes a call to this function, i.e. a+b is the same as predef::`+(a,b). Longer + expressions are normally optimized to one call, so e.g. a+b+c becomes predef::`+(a,b,c).

If there's a single argument, that argument is returned.

If arg is an object with only one reference and an lfun::`+=(), that function is called with the rest of the arguments, and its result is returned.

Otherwise, if arg is an object with an lfun::`+(), that function is called with the rest of the arguments, and its result is returned.

Otherwise, if any of the other arguments is an object that has an lfun::``+(), the first such function is called with the arguments leading up to it, and `+() is then called recursively with the result and the rest of the arguments.

Otherwise, if arg is UNDEFINED and the other arguments are either arrays, mappings or multisets, the first argument is ignored and the remaining are added together as described below. This is useful primarily when appending to mapping values since m[x] += ({foo}) will work even if m[x] doesn't exist yet.

Otherwise the result depends on the argument types:

The result is the sum of all the arguments. It's a float if any argument is a float.

If any argument is a string, all will be converted to strings and concatenated in order to form the result.

The array arguments are concatened in order to form the result.

The result is like arg but extended with the entries from the other arguments. If the same index (according to hash_value and `==) occur in several arguments, the value from the last one is used.

The result is like arg but extended with the entries from the other arguments. Subsequences with orderwise equal indices (i.e. where `< returns false) are concatenated into the result in argument order.

The function is not destructive on the arguments - the result is always a new instance.

In Pike 7.0 and earlier the addition order was unspecified.

The treatment of UNDEFINED was new in Pike 7.0.

`-(), lfun::`+(), lfun::``+()

Negation/subtraction/set difference.

Every expression with the - operator becomes a call to this function, i.e. -a is the same as predef::`-(a) and a-b is the same as predef::`-(a,b). Longer - expressions are normally optimized to one call, so e.g. a-b-c becomes predef::`-(a,b,c).

If there's a single argument, that argument is returned negated. If arg1 is an object with an lfun::`-(), that function is called without arguments, and its result is returned.

If there are more than two arguments the result is: `-(`-(arg1, arg2), @extras).

Otherwise, if arg1 is an object with an lfun::`-(), that function is called with arg2 as argument, and its result is returned.

Otherwise, if arg2 is an object with an lfun::``-(), that function is called with arg1 as argument, and its result is returned.

Otherwise the result depends on the argument types:

The result is arg1 - arg2, and is a float if either arg1 or arg2 is a float.

The result is arg1 with all nonoverlapping occurrences of the substring arg2 removed. In cases with two overlapping occurrences, the leftmost is removed.

The result is like arg1 but without the elements/indices that match any in arg2 (according to `== and, in the case of mappings, hash_value).

The function is not destructive on the arguments - the result is always a new instance.

In Pike 7.0 and earlier the subtraction order was unspecified.

`+()

Bitwise and/intersection.

Every expression with the & operator becomes a call to this function, i.e. a&b is the same as predef::`&(a,b).

If there's a single argument, that argument is returned.

If there are more than two arguments the result is: `&(`&(arg1, arg2), @extras).

Otherwise, if arg1 is an object with an lfun::`&(), that function is called with arg2 as argument, and its result is returned.

Otherwise, if arg2 is an object with an lfun::``&(), that function is called with arg1 as argument, and its result is returned.

Otherwise the result depends on the argument types:

Bitwise and of arg1 and arg2.

The result is a string where each character is the bitwise and of the characters in the same position in arg1 and arg2. The arguments must be strings of the same length.

The result is like arg1 but only with the elements/indices that match any in arg2 (according to `== and, in the case of mappings, hash_value).

Type intersection of arg1 and arg2.

The function is not destructive on the arguments - the result is always a new instance.

`|(), lfun::`&(), lfun::``&()

Bitwise or/union.

Every expression with the | operator becomes a call to this function, i.e. a|b is the same as predef::`|(a,b).

If there's a single argument, that argument is returned.

If there are more than two arguments, the result is: `|(`|(arg1, arg2), @extras).

Otherwise, if arg1 is an object with an lfun::`|(), that function is called with arg2 as argument, and its result is returned.

Otherwise, if arg2 is an object with an lfun::``|(), that function is called with arg1 as argument, and its result is returned.

Otherwise the result depends on the argument types:

Bitwise or of arg1 and arg2.

The result is a string where each character is the bitwise or of the characters in the same position in arg1 and arg2. The arguments must be strings of the same length.

The result is an array with the elements in arg1 concatenated with those in arg2 that doesn't occur in arg1 (according to `==). The order between the elements that come from the same argument is kept.

Every element in arg1 is only matched once against an element in arg2, so if arg2 contains several elements that are equal to each other and are more than their counterparts in arg1, the rightmost remaining elements in arg2 are kept.

The result is like arg1 but extended with the entries from arg2. If the same index (according to hash_value and `==) occur in both, the value from arg2 is used.

The result is like arg1 but extended with the entries in arg2 that doesn't already occur in arg1 (according to `==). Subsequences with orderwise equal entries (i.e. where `< returns false) are handled just like the array case above.

Type union of arg1 and arg2.

The function is not destructive on the arguments - the result is always a new instance.

`&(), lfun::`|(), lfun::``|()

Exclusive or.

Every expression with the ^ operator becomes a call to this function, i.e. a^b is the same as predef::`^(a,b).

If there's a single argument, that argument is returned.

If there are more than two arguments, the result is: `^(`^(arg1, arg2), @extras).

Otherwise, if arg1 is an object with an lfun::`^(), that function is called with arg2 as argument, and its result is returned.

Otherwise, if arg2 is an object with an lfun::``^(), that function is called with arg1 as argument, and its result is returned.

Otherwise the result depends on the argument types:

Bitwise exclusive or of arg1 and arg2.

The result is a string where each character is the bitwise exclusive or of the characters in the same position in arg1 and arg2. The arguments must be strings of the same length.

The result is an array with the elements in arg1 that doesn't occur in arg2 concatenated with those in arg2 that doesn't occur in arg1 (according to `==). The order between the elements that come from the same argument is kept.

Every element is only matched once against an element in the other array, so if one contains several elements that are equal to each other and are more than their counterparts in the other array, the rightmost remaining elements are kept.

The result is like arg1 but with the entries from arg1 and arg2 whose indices are different between them (according to hash_value and `==).

The result is like arg1 but with the entries from arg1 and arg2 that are different between them (according to hash_value and `==). Subsequences with orderwise equal entries (i.e. where `< returns false) are handled just like the array case above.

The result is a type computed like this: (arg1&~arg2)|(~arg1&arg2).

The function is not destructive on the arguments - the result is always a new instance.

`&(), `|(), lfun::`^(), lfun::``^()

Left shift.

Every expression with the << operator becomes a call to this function, i.e. a<<b is the same as predef::`<<(a,b).

If arg1 is an object that implements lfun::`<<(), that function will be called with arg2 as the single argument.

If arg2 is an object that implements lfun::``<<(), that function will be called with arg1 as the single argument.

Otherwise arg1 will be shifted arg2 bits left.

`>>()

Right shift.

Every expression with the >> operator becomes a call to this function, i.e. a>>b is the same as predef::`>>(a,b).

If arg1 is an object that implements lfun::`>>(), that function will be called with arg2 as the single argument.

If arg2 is an object that implements lfun::``>>(), that function will be called with arg1 as the single argument.

Otherwise arg1 will be shifted arg2 bits right.

`<<()

Multiplication/repetition/implosion.

Every expression with the * operator becomes a call to this function, i.e. a*b is the same as predef::`*(a,b). Longer * expressions are normally optimized to one call, so e.g. a*b*c becomes predef::`*(a,b,c).

If there's a single argument, that argument will be returned.

If the first argument is an object that implements lfun::`*(), that function will be called with the rest of the arguments.

If there are more than two arguments, the result will be `*(`*(arg1, arg2), @extras).

If arg2 is an object that implements lfun::``*(), that function will be called with arg1 as the single argument.

Otherwise the result will be as follows:

The result will be arg1 concatenated arg2 times.

The result will be the elements of arg1 concatenated with arg2 interspersed.

The result will be arg1 concatenated arg2 times.

The result will be arg1 * arg2, and will be a float if either arg1 or arg2 is a float.

In Pike 7.0 and earlier the multiplication order was unspecified.

`+(), `-(), `/(), lfun::`*(), lfun::``*()

Division/split.

Every expression with the / operator becomes a call to this function, i.e. a/b is the same as predef::`/(a,b).

If there are more than two arguments, the result will be `/(`/(arg1, arg2), @extras).

If arg1 is an object that implements lfun::`/(), that function will be called with arg2 as the single argument.

If arg2 is an object that implements lfun::``/(), that function will be called with arg1 as the single argument.

Otherwise the result will be as follows:

The result will be and array of arg1 split in segments of length arg2. If arg2 is negative the splitting will start from the end of arg1.

The result will be an array of arg1 split at each occurrence of arg2. Note that the segments that matched against arg2 will not be in the result.

The result will be and array of arg1 split in segments of length arg2. If arg2 is negative the splitting will start from the end of arg1.

The result will be an array of arg1 split at each occurrence of arg2. Note that the elements that matched against arg2 will not be in the result.

The result will be arg1 / arg2. If both arguments are int, the result will be truncated to an int. Otherwise the result will be a float.

Unlike in some languages, the function f(x) = x/n (x and n integers) behaves in a well-defined way and is always rounded down. When you increase x, f(x) will increase with one for each n:th increment. For all x, (x + n) / n = x/n + 1; crossing zero is not special. This also means that / and % are compatible, so that a = b*(a/b) + a%b for all a and b.

`%

Modulo.

Every expression with the % operator becomes a call to this function, i.e. a%b is the same as predef::`%(a,b).

If arg1 is an object that implements lfun::`%() then that function will be called with arg2 as the single argument.

If arg2 is an object that implements lfun::``%() then that function will be called with arg2 as the single argument.

Otherwise the result will be as follows:

If arg2 is positive, the result will be the last `%(sizeof(arg1), arg2) elements of arg1. If arg2 is negative, the result will be the first `%(sizeof(arg1), -arg2) elements of arg1.

The result will be arg1 - arg2*floor(arg1/arg2). The result will be a float if either arg1 or arg2 is a float, and an int otherwise.

For numbers, this means that

a % b always has the same sign as b (typically b is positive; array size, rsa modulo, etc, and a varies a lot more than b).

The function f(x) = x % n behaves in a sane way; as x increases, f(x) cycles through the values 0,1, ..., n-1, 0, .... Nothing strange happens when you cross zero.

The % operator implements the binary "mod" operation, as defined by Donald Knuth (see the Art of Computer Programming, 1.2.4). It should be noted that Pike treats %-by-0 as an error rather than returning 0, though.

/ and % are compatible, so that a = b*(a/b) + a%b for all a and b.

`/

Logical not.

Every expression with the ! operator becomes a call to this function, i.e. !a is the same as predef::`!(a).

It's also used when necessary to test truth on objects, i.e. in a statement if (o) ... where o is an object, the test becomes the equivalent of !!o so that any lfun::`!() the object might have gets called.

If arg is an object that implements lfun::`!(), that function will be called.

If arg is 0 (zero), a destructed object, or a function in a destructed object, 1 will be returned.

Otherwise 0 (zero) will be returned.

No float is considered false, not even 0.0.

`==(), `!=(), lfun::`!()

``
0
1
0 0
1
1
0
0

Complement/inversion.

Every expression with the ~ operator becomes a call to this function, i.e. ~a is the same as predef::`~(a).

The result will be as follows:

If arg implements lfun::`~(), that function will be called.

The bitwise inverse of arg will be returned.

The result will be -1.0 - arg.

The type inverse of arg will be returned.

If arg only contains characters in the range 0 - 255 (8-bit), a string containing the corresponding 8-bit inverses will be returned.

`!(), lfun::`~()

Index/subrange.

Every non-lvalue expression with the [] operator becomes a call to this function, i.e. a[i] is the same as predef::`[](a,i) and a[i..j] is the same as predef::`[](a,i,j). If the lower limit i is left out, 0 is passed to the function. If the upper limit j is left out, Int.NATIVE_MAX is passed to the function, but that might be changed to an even larger number in the future.

If arg is an object that implements lfun::`[](), that function will be called with the rest of the arguments.

If there are 2 arguments the result will be as follows:

The non-static (ie public) symbol named index will be looked up in arg.

The bignum function named index will be looked up in arg.

If index is an int, index number index of arg will be returned. Otherwise an array of all elements in arg indexed with index will be returned.

If index exists in arg the corresponding value will be returned. Otherwise UNDEFINED will be returned.

If index exists in arg, 1 will be returned. Otherwise UNDEFINED will be returned.

The character (int) at index index in arg will be returned.

The non-static (ie public) constant symbol index will be looked up in arg.

Otherwise if there are 3 arguments the result will be as follows:

A string with the characters between start and end (inclusive) in arg will be returned.

An array with the elements between start and end (inclusive) in arg will be returned.

An indexing expression in an lvalue context, i.e. where the index is being assigned a new value, uses `[]= instead of this function.

`->(), lfun::`[](), `[]=

0
1

Arrow index.

Every non-lvalue expression with the -> operator becomes a call to this function. a->b is the same as predef::`^(a,"b") where "b" is the symbol b in string form.

This function behaves like `[], except that the index is passed literally as a string instead of being evaluated.

If arg is an object that implements lfun::`->(), that function will be called with index as the single argument.

Otherwise the result will be as follows:

The non-static (ie public) symbol named index will be looked up in arg.

The bignum function named index will be looked up in arg.

An array of all elements in arg arrow indexed with index will be returned.

If index exists in arg the corresponding value will be returned. Otherwise UNDEFINED will be returned.

If index exists in arg, 1 will be returned. Otherwise UNDEFINED will be returned.

The non-static (ie public) constant symbol index will be looked up in arg.

In an expression a->b, the symbol b can be any token that matches the identifier syntax - keywords are disregarded in that context.

An arrow indexing expression in an lvalue context, i.e. where the index is being assigned a new value, uses `->= instead of this function.

`[](), lfun::`->(), ::`->(), `->=

0
1

Index assignment.

Every lvalue expression with the [] operator becomes a call to this function, i.e. a[b]=c is the same as predef::`[]=(a,b,c).

If arg is an object that implements lfun::`[]=(), that function will be called with index and val as the arguments.

The non-static (ie public) variable named index will be looked up in arg, and assigned val.

Index index in arg will be assigned val.

If val is 0 (zero), one occurrance of index in arg will be removed. Otherwise index will be added to arg if it is not already there.

val will be returned.

An indexing expression in a non-lvalue context, i.e. where the index is being queried instead of assigned, uses `[] instead of this function.

`->=(), lfun::`[]=(), `[]

0 1
0
1

Arrow index assignment.

Every lvalue expression with the -> operator becomes a call to this function, i.e. a->b=c is the same as predef::`->=(a,"b",c) where "b" is the symbol b in string form.

This function behaves like `[]=, except that the index is passed literally as a string instead of being evaluated.

If arg is an object that implements lfun::`->=(), that function will be called with index and val as the arguments.

The non-static (ie public) variable named index will be looked up in arg, and assigned val.

Index index in arg will be assigned val.

If val is 0 (zero), one occurrance of index in arg will be removed. Otherwise index will be added to arg if it is not already there.

val will be returned.

In an expression a->b=c, the symbol b can be any token that matches the identifier syntax - keywords are disregarded in that context.

An arrow indexing expression in a non-lvalue context, i.e. where the index is being queried instead of assigned, uses `-> instead of this function.

`[]=(), lfun::`->=(), `->

0 1
0
1

Size query.

The result will be as follows:

The number of characters in arg will be returned.

The number of elements in arg will be returned.

The number of key-value pairs in arg will be returned.

If arg implements lfun::_sizeof(), that function will be called. Otherwise the number of non-static (ie public) symbols in arg will be returned.

lfun::_sizeof()

Call a function.

Calls the function fun with the arguments specified by args.

lfun::`()()

``
``

Throws an error. A more readable version of the code throw( ({ sprintf(f, @args), backtrace() }) ).

Check if a path p is fully qualified (ie not relative).

Returns 1 if the path is absolute, 0 otherwise.

Split a path p into its components.

This function divides a path into its components. This might seem like it could be done by dividing the string on <tt>"/"</tt>, but that will not work on some operating systems. To turn the components back into a path again, use combine_path().

Returns all but the last segment of a path. Some example inputs and outputs:

Expression Value dirname("/a/b")"/a" dirname("/a/")"/a" dirname("/a")"/" dirname("/")"/" dirname("")""

basename(), explode_path()

Returns the last segment of a path.

dirname(), explode_path()

Compile the Pike code in the string source into a program. If filename is not specified, it will default to "-".

Functionally equal to compile(cpp(source, filename)).

compile(), cpp(), compile_file()

When called with no arguments, a mapping with all current environment variables will be returned. Destructive opreations on the mapping will not affect the internal environment representation.

If the varname argument has been given, the value of the environment variable with the name varname will be returned. If no such environment variable exists, 0 (zero) will be returned.

On NT the environment variable name is case insensitive.

Compile the Pike code contained in the file filename into a program.

This function will compile the file filename to a Pike program that can later be instantiated. It is the same as doing compile_string(Stdio.read_file(filename), filename).

compile(), compile_string(), cpp()

Sets the environment variable varname to value.

On NT the environment variable name is case insensitive.

getenv()

Replaces "\" with "/" if runing on MS Windows. It is adviced to use System.normalize_path instead.

Alias for sizeof.

sizeof

Writes a string on stdout. Works just like Stdio.File.write on Stdio.stdout.

Return a readable message that describes where the backtrace trace was made (by backtrace).

It may also be an error object or array (typically caught by a catch), in which case the error message also is included in the description.

backtrace(), describe_error(), catch(), throw()

Return the error message from an error object or array (typically caught by a catch). The type of the error is checked, hence err is declared as mixed and not object|array.

If an error message couldn't be obtained, a fallback message describing the failure is returned. No errors due to incorrectness in err are thrown.

describe_backtrace(), get_backtrace

Return the backtrace array from an error object or array (typically caught by a catch), or zero if there is none. Errors are thrown on if there are problems retrieving the backtrace.

describe_backtrace(), describe_error()

This class does not exist in the Locale module in Pike 7.6.

ASCIIDec
Locale.Charset
Encoder

Protocol constants

SSL.Constants

Encryption and MAC algorithms used in SSL.

SSL.Cipher
"constants"

Interface similar to Stdio.File.

"cipher"
SSL.connection

This module is obsolete. All code should use ASN1.Types instead.

Standards.PKCS.Signature

In Pike 7.6 the hash is required to be a Crypto.Hash object.

The life length of the Fd instance has changed. In newer versions it's always the same as for the File instance. That can theoretically cause incompatibilities in code that uses File.dup and File.assign, which are deprecated and very rarely used.

Stdio.File
Sql.Sql
Sql.Sql
ADT.Heap

This method has been renamed to pop in Pike 7.6.

pop
Protocol
Protocols.SMTP.Protocol
Client
Protocols.SMTP.Client
Crypto.Substitution
Crypto.Substitution
Crypto.Koremutake
Crypto.Koremutake
Crypto.Arcfour
Nettle.ARCFOUR_State
Crypto.DES
Nettle.DES_State
Crypto.Buffer
Nettle.Proxy

Assorted stronger or weaker randomnumber generators. These devices try to collect entropy from the environment. They differ in behaviour when they run low on entropy, /dev/random will block if it can't provide enough random bits, while /dev/urandom will degenerate into a reasonably strong pseudo random generator

Crypto.Random

Virtual class for randomness source object.

Returns a string of length len with (pseudo) random values.

0

A pseudo random generator based on the arcfour crypto.

Nettle.ARCFOUR_State

Initialize and seed the arcfour random generator.

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

Executes several programs (last -256, arp -a, netstat -anv, netstat -mv, netstat -sv, uptime, ps -fel, ps aux, vmstat -s, vmstat -M, iostat, iostat -cdDItx) to generate some entropy from their output. On Microsoft Windows the Windows cryptographic routines are called to generate random data.

Returns a reasonably random random-source.

RandomSource

Returns a really random random-source.

RandomSource
Crypto.DSA
Crypto.AES
Nettle.AES_State
Crypto.CBC
Nettle.CBC
Crypto.CAST
Nettle.CAST128_State
Crypto.SHA1
Nettle.SHA1_State

Use Crypto.CBC(Crypto.DES) instead.

Nettle.CBC
Crypto.AES
Nettle.AES_State

From Pike 7.5 pw and salt are binary strings, so the result is different if any of these includes "\0".

The return type is also changed from string to int|string. If the second argument is a hash, pw will be hashed with the salt from the hash and compared with the hash.

String.string2hex
String.hex2string

des_parity is removed. Instead there is Crypto.DES->fix_parity, but it always outputs a key sized string.

Crypto.RSA
Crypto.RSA
Crypto.DES3
Nettle.DES3_State

Use Crypto.CBC(Crypto.IDEA) instead.

Nettle.CBC

Inversion crypto module.

Returns the string "INVERT".

Returns the block size for the invert crypto (currently 8).

8
8

Returns the minimum key length for the invert crypto.

Since this crypto doesn't use a key, this will be 0.

0
0

Set the encryption key (currently a no op).

Set the decryption key (currently a no op).

De/encrypt the string data with the invert crypto (ie invert the string).

Use Crypto.CBC(Crypto.DES3) instead.

Nettle.CBC
Crypto.MD4
Nettle.MD4_State
Crypto.IDEA
Nettle.IDEA_State
Crypto.MD2
Nettle.MD2_State
Crypto.HMAC
Crypto.HMAC
Crypto.MD5
Nettle.MD5_State

Pike 7.4 compatibility.

The symbols in this namespace will appear in programs that use #pike 7.4 or lower.

predef::

Return resource usage. An error is thrown if it isn't supported or if the system fails to return any information.

Returns an array of ints describing how much resources the interpreter process has used so far. This array will have at least 29 elements, of which those values not available on this system will be zero.

The elements are as follows:

user_time

Time in milliseconds spent in user code.

system_time

Time in milliseconds spent in system calls.

maxrss

Maximum used resident size in kilobytes.

ixrss

Quote from GNU libc: An integral value expressed in kilobytes times ticks of execution, which indicates the amount of memory used by text that was shared with other processes.

idrss

Quote from GNU libc: An integral value expressed the same way, which is the amount of unshared memory used for data.

isrss

Quote from GNU libc: An integral value expressed the same way, which is the amount of unshared memory used for stack space.

minor_page_faults

Minor page faults, i.e. TLB misses which required no disk I/O.

major_page_faults

Major page faults, i.e. paging with disk I/O required.

swaps

Number of times the process has been swapped out entirely.

block_input_op

Number of block input operations.

block_output_op

Number of block output operations.

messages_sent

Number of IPC messsages sent.

messages_received

Number of IPC messsages received.

signals_received

Number of signals received.

voluntary_context_switches

Number of voluntary context switches (usually to wait for some service).

involuntary_context_switches

Number of preemptions, i.e. context switches due to expired time slices, or when processes with higher priority were scheduled.

sysc

Number of system calls.

ioch

Number of characters read and written.

rtime

Elapsed real time (ms).

ttime

Elapsed system trap (system call) time (ms).

tftime

Text page fault sleep time (ms).

dftime

Data page fault sleep time (ms).

kftime

Kernel page fault sleep time (ms).

ltime

User lock wait sleep time (ms).

slptime

Other sleep time (ms).

wtime

Wait CPU (latency) time (ms).

stoptime

Time spent in stopped (suspended) state.

brksize

Heap size.

stksize

Stack size.

The values will not be further explained here; read your system manual for more information.

All values may not be present on all systems.

System.getrusage

time(), System.getrusage()

Thread

The Mutex destruct behaviour in Pike 7.4 and below is different from 7.6 in that destructing a mutex destroys the key that is locking it.

Array

This diff3 implementation is obsoleted by Array.diff3.

diff3
Array

Much simplified type compared to later versions of map.

``

Pike 0.6 compatibility.

The symbols in this namespace will appear in programs that use #pike 0.6 or lower.

7.0::

7.0::

More lax types than in later versions.

time unit: TNGDate

Implements ST:TNG stardates. Can be used as create argument to Day.

Calendar._TimeUnit

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

This module exists only for backward compatibility with Pike 7.0.

Base class for units of time.

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.

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.

next() and prev() give 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.

time units: <ref>Year</ref>, <ref>Month</ref>, <ref>Week</ref>, <ref>Day</ref>

A Calendar._TimeUnit.

Lesser units: <ref>Month</ref>, <ref>Week</ref>, <ref>Day</ref> Greater units: none

_TimeUnit

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)

Replacement for localtime().

Replacement for ctime().

Replacement for ctime.

Pike 7.0 compatibility.

The symbols in this namespace will appear in programs that use #pike 7.0 or lower.

7.2::

7.2::

Stat a file (Pike 7.0 compatibility).

Returns an array with the following content:

mode

Access mode.

size

Size in bytes, or filetype indicator.

atime

Last access time.

mtime

Last modification time.

ctime

Last change time.

uid

User id.

gid

Group id.

See predef::file_stat() for a full description of the array.

predef::file_stat()

Get the runtime type of a value (Pike 7.0 compatibility).

Returns the type of x as a string.

predef::_typeof()

Delete an entry x from a mapping m (Pike 7.0 compatibility).

Returns m.

predef::m_delete()

Calculate a hash of a string (Pike 7.0 compatibility).

This function is now available as predef::hash_7_0().

predef::hash_7_0(), predef::hash()

Callback functions used to overload various builtin functions.

The functions can be grouped into a few sets:

Object initialization and destruction.

__INIT(), create(), destroy()

Unary operator overloading.

`~(), `!(), _values(), cast(), _sizeof(), _indices(), __hash()

Binary asymmetric operator overloading.

`+(), ``+(), `-(), ``-(), `&(), ``&(), `|(), ``|(), `^(), ``^(), `<<(), ``<<(), `>>(), ``>>(), `*(), ``*(), `/(), ``/(), `%(), ``%()

Binary symmetric operator overloading.

The optimizer will make assumptions about the relations between these functions.

`==(), _equal(), `<(), `>()

Other binary operator overloading.

`[](), `[]=(), `->(), `->=(), `+=(), `()()

Overloading of other builtin functions.

_is_type(), _sprintf(), _m_delete(), _get_iterator(), _search()

Although these functions are called from outside the object they exist in, they will still be used even if they are declared static. It is in fact recommended to declare them static, since that will hinder them being used for other purposes.

::

Called by sqrt when the square root of an object is requested.

_sqrt is not a real lfun, so it must not be defined as static.

predef::sqrt()

Called by random. Typical uses is when the object implements a ADT, then a call to this lfun should return a random member of the ADT or range implied by the ADT.

predef::random()

Inherit and variable initialization.

This function is generated automatically by the compiler. It's called just before lfun::create() when an object is instantiated.

It first calls any __INIT functions in inherited classes (regardless of modifiers on the inherits). It then executes all the variable initialization expressions in this class, in the order they occur.

This function can not be overloaded or blocked from executing.

lfun::create()

Object creation callback.

This function is called right after lfun::__INIT().

args are the arguments passed when the program was called.

In Pike 7.2 and later this function can be created implicitly by the compiler using the new syntax:

class Foo(int foo) { int bar; }

In the above case an implicit lfun::create() is created, and it's equvivalent to:

class Foo { int foo; int bar; static void create(int foo) { local::foo = foo; } }

lfun::__INIT(), lfun::destroy()

Object destruction callback.

This function is called by predef::destruct() right before it zeroes all the object variables and destroys the object.

Note that it's also called on implicit destruct, i.e. when there are no more references to the object, or when the garbage collector decides to destruct it.

Regarding destruction order during garbage collection:

If an object is destructed by the garbage collector, it's part of a reference cycle with other things but with no external references. If there are other objects with destroy functions in the same cycle, it becomes a problem which to call first.

E.g. if this object has a variable with another object which (directly or indirectly) points back to this one, you might find that the other object already has been destructed and the variable thus contains zero.

The garbage collector tries to minimize such problems by defining an order as far as possible:

If an object A contains an lfun::destroy and an object B does not, then A is destructed before B.

If A references B single way, then A is destructed before B.

If A and B are in a cycle, and there is a reference somewhere from B to A that is weaker than any reference from A to B, then A is destructed before B.

Weak references (e.g. set with predef::set_weak_flag()) are considered weaker than normal references, and both are considered weaker than strong references.

Strong references are those from objects to the objects of their lexically surrounding classes. There can never be a cycle consisting only of strong references. (This means the gc never destructs a parent object before all children have been destructed.)

An example with well defined destruct order due to strong references:

class Super { class Sub { static void destroy() { if (!Super::this) error ("My parent has been destructed!\n"); } } Sub sub = Sub(); static void destroy() { if (!sub) werror ("sub already destructed.\n"); } }

The garbage collector ensures that these objects are destructed in an order so that werror in Super is called and not error in Sub.

When the garbage collector calls lfun::destroy, all accessible non-objects and objects without destroy functions are still intact. They are not freed if the destroy function adds external references to them. However, all objects with lfun::destroy in the cycle are already scheduled for destruction and are thus be destroyed even if external references are added to them.

The garbage collector had completely random destruct order in versions prior to 7.2.

lfun::create(), predef::destruct()

Left side addition/concatenation callback.

This is used by predef::`+. It's called with any arguments that follow this object in the argument list of the call to predef::`+. The returned value should be a new instance that represents the addition/concatenation between this object and the arguments in the order they are given.

It's assumed that this function is side-effect free.

lfun::``+(), lfun::`+=(), predef::`+()

Destructive addition/concatenation callback.

This is used by predef::`+. It's called with any arguments that follow this object in the argument list of the call to predef::`+. It should update this object to represent the addition/concatenation between it and the arguments in the order they are given. It should always return this object.

This function should only be implemented if lfun::`+() also is. It should only work as a more optimized alternative to that one, for the case when it's safe to change the object destructively and use it directly as the result.

This function is not an lfun for the += operator. It's only whether or not it's safe to do a destructive change that decides if this function or lfun::`+() is called; both the + operator and the += operator can call either one.

lfun::`+(), predef::`+()

this_program

Right side addition/concatenation callback.

This is used by predef::`+. It's called with any arguments that precede this object in the argument list of the call to predef::`+. The returned value should be a new instance that represents the addition/concatenation between the arguments in the order they are given and this object.

It's assumed that this function is side-effect free.

lfun::`+(), predef::`+()

Negation and left side subtraction/set difference callback.

This is used by predef::`-. When called without an argument the result should be a new instance that represents the negation of this object, otherwise the result should be a new instance that represents the difference between this object and arg.

It's assumed that this function is side-effect free.

lfun::``-(), predef::`-()

Right side subtraction/set difference callback.

This is used by predef::`-. The result should be a new instance that represents the difference between arg and this object.

It's assumed that this function is side-effect free.

lfun::`-(), predef::`-()

Left side bitwise and/intersection callback.

It's assumed that this function is side-effect free.

lfun::``&(), predef::`&()

Right side bitwise and/intersection callback.

It's assumed that this function is side-effect free.

lfun::`&(), predef::`&()

Left side bitwise or/union callback.

It's assumed that this function is side-effect free.

lfun::``|(), predef::`|()

Right side bitwise or/union callback.

It's assumed that this function is side-effect free.

lfun::`|(), predef::`|()

Left side exclusive or callback.

It's assumed that this function is side-effect free.

lfun::``^(), predef::`^()

Right side exclusive or callback.

It's assumed that this function is side-effect free.

lfun::`^(), predef::`^()

Left side left shift callback.

It's assumed that this function is side-effect free.

lfun::``<<(), predef::`<<()

Right side left shift callback.

It's assumed that this function is side-effect free.

lfun::`<<(), predef::`<<()

Left side right shift callback.

It's assumed that this function is side-effect free.

lfun::``>>(), predef::`>>()

Right side right shift callback.

It's assumed that this function is side-effect free.

lfun::`>>(), predef::`>>()

Left side multiplication/repetition/implosion callback.

It's assumed that this function is side-effect free.

lfun::``*(), predef::`*()

Right side multiplication/repetition/implosion callback.

It's assumed that this function is side-effect free.

lfun::`*(), predef::`*()

Left side division/split callback.

It's assumed that this function is side-effect free.

lfun::``/(), predef::`/()

Right side division/split callback.

It's assumed that this function is side-effect free.

lfun::`/(), predef::`/()

Left side modulo callback.

It's assumed that this function is side-effect free.

lfun::``%(), predef::`%()

Right side modulo callback.

It's assumed that this function is side-effect free.

lfun::`%(), predef::`%()

Logical not callback.

Returns non-zero if the object should be evaluated as false, and 0 (zero) otherwise.

It's assumed that this function is side-effect free.

predef::`!()

Complement/inversion callback.

It's assumed that this function is side-effect free.

predef::`~()

Equality test callback.

If this is implemented it might be necessary to implement lfun::__hash too. Otherwise mappings might hold several objects as indices which are duplicates according to this function. Various other functions that use hashing also might not work correctly, e.g. predef::Array.uniq.

It's assumed that this function is side-effect free.

predef::`==(), lfun::__hash

0
1

Less than test callback.

It's assumed that this function is side-effect free.

predef::`<()

0
1

Greater than test callback.

It's assumed that this function is side-effect free.

predef::`>()

0
1

Hashing callback.

This function gets called by various mapping operations when the object is used as index in a mapping. It should return an integer that corresponds to the object in such a way that all values which lfun::`== considers equal to the object gets the same hash value.

The function predef::hash does not return hash values that are compatible with this one.

It's assumed that this function is side-effect free.

lfun::`==

Value cast callback.

Type to cast to.

Expected to return the object value-casted (converted) to the type described by requested_type.

The argument is currently a string with the name of the type, but might in the future be a value of the type type.

Currently casting between object types is a noop.

If the returned value is not deemed to be of the requested type a runtime error may be thrown.

It's assumed that this function is side-effect free.

Index/subrange callback.

It's assumed that this function is side-effect free.

predef::`[]()

Index assignment callback.

predef::`[]=(), lfun::`->=()

Arrow index callback.

It's assumed that this function is side-effect free.

predef::`->()

Arrow index assignment callback.

predef::`->=(), lfun::`[]=()

Size query callback.

Called by predef::sizeof() to determine the number of elements in an object. If this function is not present, the number of public symbols in the object will be returned.

Expected to return the number of valid indices in the object.

It's assumed that this function is side-effect free.

predef::sizeof()

List indices callback.

Expected to return an array with the valid indices in the object.

It's assumed that this function is side-effect free.

predef::indices(), lfun::_values()

List values callback.

Expected to return an array with the values corresponding to the indices returned by lfun::_indices().

It's assumed that this function is side-effect free.

predef::values(), lfun::_indices()

Apply callback.

predef::`()

Type comparison callback.

Called by the cast operator to determine if an object simulates a basic type.

One of:

"array"
"float"
"function"
"int"
"mapping"
"multiset"
"object"
"program"
"string"
"type"
"void"
"zero"

The following five shouldn't occurr, but are here for completeness:

"lvalue"
"mapping_data"
"object storage"
"pike_frame"
"unknown"

Expected to return 1 if the object is to be regarded as a simulation of the type specified by basic_type.

The argument is currently a string with the name of the type, but might in the future be a value of the type type.

It's assumed that this function is side-effect free.

0
1

Sprintf callback.

This method is called by predef::sprintf() to print objects. If it is not present, printing of the object will not be supported for any conversion-type except for the %O-conversion-type, which will output "object".

One of:

'b'

Signed binary integer.

'd'

Signed decimal integer.

'u'

Unsigned decimal integer.

'o'

Signed octal integer.

'x'

Lowercase signed hexadecimal integer.

'X'

Uppercase signed hexadecimal integer.

'c'

Character. If a fieldsize has been specified this will output the low-order bytes of the integer in network byte order.

'f'

Float.

'g'

Heuristically chosen representation of float.

'G'

Like %g, but uses uppercase E for exponent.

'e'

Exponential notation float.

'E'

Like %e, but uses uppercase E for exponent.

's'

String.

'O'

Any value (debug style).

't'

Type of the argument.

Conversion parameters. The following parameters may be supplied:

- "precision"

Precision.

- "width"

Field width.

- 1 1 "flag_left"

Indicates that the output should be left-aligned.

- "indent"

Indentation level in %O-mode.

Is expected to return a string describing the object formatted according to conversion_type.

_sprintf() is currently not called for the following conversion-types:

'F'

Binary IEEE representation of float (%4F gives single precision, %8F gives double precision.)

This function might be called at odd times, e.g. before lfun::create has been called or when an error has occurred. The reason is typically that it gets called when a backtrace is being formatted to report an error. It should therefore be very robust and not make any assumptions about its own internal state, at least not when conversion_type is 'O'.

It's assumed that this function is side-effect free.

predef::sprintf()

Recursive equality callback.

It's assumed that this function is side-effect free.

predef::equal(), lfun::`==()

Delete index callback.

predef::m_delete()

Iterator creation callback.

The returned predef::Iterator instance works as a cursor that references a specific item contained (in some arbitrary sense) in this one.

It's assumed that this function is side-effect free.

predef::Iterator, predef::get_iterator, predef::foreach()

predef::Iterator

Search callback.

predef::search()

This define contains the current Pike version as a float. If another Pike version is emulated, this define is updated accordingly.

__REAL_VERSION__

This define always contains the version of the current Pike, represented as a float.

__VERSION__

This define contains the major part of the current Pike version, represented as an integer. If another Pike version is emulated, this define is updated accordingly.

__REAL_MAJOR__

This define always contains the major part of the version of the current Pike, represented as an integer.

__MAJOR__

This define contains the minor part of the current Pike version, represented as an integer. If another Pike version is emulated, this define is updated accordingly.

__REAL_MINOR__

This define always contains the minor part of the version of the current Pike, represented as an integer.

__MINOR__

This constant contains the build number of the current Pike version, represented as an integer. If another Pike version is emulated, this constant remains unaltered.

__REAL_MINOR__

This define always contains the minor part of the version of the current Pike, represented as an integer.

__BUILD__

This define contains the current line number, represented as an integer, in the source file.

This define contains the file path and name of the source file.

This define contains the current date at the time of compilation, e.g. "Jul 28 2001".

This define contains the current time at the time of compilation, e.g. "12:20:51".

This define is always true.

This define is defined when automatic bignum conversion is enabled. When enabled all integers will automatically be converted to bignums when they get bigger than what can be represented by an integer, hampering performance slightly instead of crashing the program.

This define is defined when the Pike is running on a Microsoft Windows OS, not just Microsoft Windows NT, as the name implies.

This define is defined when the Pike is running on Amiga OS.

Symbols implicitly inherited from the virtual base class.

These symbols exist mainly to simplify implementation of the corresponding lfuns.

lfun::

Builtin arrow operator.

This function indexes the current object with the string index. This is useful when the arrow operator has been overloaded.

::`->=()

Builtin arrow set operator.

This function indexes the current object with the string index, and sets it to value. This is useful when the arrow set operator has been overloaded.

::`->()

Builtin function to list the identifiers of an object. This is useful when lfun::_indices has been overloaded.

::_values, ::`->

Builtin function to list the values of the identifiers of an object. This is useful when lfun::_values has been overloaded.

::_indices, ::`->