Namespace 9.0::

Description

Pike 9.0 compatibility.

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

Inherit: inherit 9.1:: :

Namespace cpp::

Description

Pike has a builtin C-style preprocessor. It works similar to the ANSI-C preprocessor but has a few extra features. These and the default set of preprocessor macros are described here.

The preprocessor is usually accessed via MasterObject->compile_file() or MasterObject->compile_string(), but may be accessed directly by calling cpp().

See also

compile(), cpp(), CompilerEnvironment.CPP

Constant __STDC_ISO_10646__

constant__STDC_ISO_10646__

Description

This macro expands to the year and date (6 digits) of the Unicode standard that the Pike runtime supports.

Note that this differs slightly from the corresponding macro in the C23 standard in that it does NOT have an ending 'L'.

See also

__UNICODE_VERSION__

Constant __UNICODE_VERSION__: constant__UNICODE_VERSION__
Description: This macro expands to a decimal representation of the version of the Unicode standard that the Pike runtime supports. It is formated with the sprintf-format %d%02d%02d with the values major, minor and revision in order. Version 12.1 thus results in the value 120100.
See also: __STDC_ISO_10646__

Directive #embed

#embed

Description

Include a file as a list of items.

By default the items are int(8bit).

See also

#include, #string

Method __has_embed: bool__has_embed(mixedidentifiers)
Description: This macro checks whether the set of identifiers is a valid argument to #embed or not.
Returns: __has_embed returns 1 if the set of identifiers given as argument is valid as an argument to #embed and 0 otherwise. Note that the set of identifiers may contain preprocessor parameters.
Note: Not available prior to Pike 9.0.
See also: #if, #ifdef, constant(), defined(), #embed, __has_include()

Method __has_include: bool__has_include(mixedidentifiers)
Description: This macro checks whether the set of identifiers is a valid argument to #include or not.
Returns: __has_include returns 1 if the symbol given as argument is valid as an argument to #include and 0 otherwise.
Note: Not available prior to Pike 9.0.
See also: #if, #ifdef, constant(), defined(), #include, #string, __has_embed()

Method parse_param_if_empty: protectedstringparse_param_if_empty(stringsym, stringarg)
Description: Parse the argument to if_empty() and/or __if_empty__().
See also: #embed, C23 6.10.3.5

Method parse_param_limit: protectedint(0..)parse_param_limit(stringsym, stringarg)
Description: Parse the argument to limit() and/or __limit__().
See also: #embed, C23 6.10.3.2

Method parse_param_pike_charset

protectedtypeparse_param_pike_charset(stringsym, stringarg)

Description

Parse the argument for the #embed parameters pike::charset() and/or __pike__::__charset__().

This #embed parameter is used to specify the character encoding for the embedded file. If this is not specified, the default encoding (ie iso-8859-1) will be used.

Some commonly used charsets here are:

UCS-2
16-bit quantities in big-endian byte order.
UCS-2le
16-bit quantities in little-endian byte order.
UCS-4
32-bit quantities in big-endian byte order.
UCS-4be
32-bit quantities in little-endian byte order.
UTF-8
Text in UTF-8.
UTF-16
Text in UTF-16.
UTF-16le
Text in UTF-16le.

See also

#embed

Method parse_param_prefix: protectedstringparse_param_prefix(stringsym, stringarg)
Description: Parse the argument to prefix() and/or __prefix__().
See also: #embed, C23 6.10.3.4

Method parse_param_suffix: protectedstringparse_param_suffix(stringsym, stringarg)
Description: Parse the argument to suffix() and/or __suffix__().
See also: #embed, C23 6.10.3.3

Namespace predef::

Description: This is the default namespace and contains lots of global symbols.

Typedef utf8_string

typedef __attribute__("utf8_string", string(8bit)) utf8_string

Description

String containing UTF-8 encoded data.

This is similar to a string(8bit), but allows the compiler to keep track of whether strings are UTF-8 or not.

See also

string_to_utf8(), utf8_to_string()

Typedef zero: typedefint(0)zero
Description: Zero datatype.

Constant UNDEFINED: constantUNDEFINED
Description: The undefined value; ie a zero for which zero_type() returns 1.

Constant __null_program: constant__null_program
Description: Program used internally by the compiler to create objects that are later modified into instances of the compiled program by the compiler.
See also: __placeholder_object

Constant __placeholder_object: constant__placeholder_object
Description: Object used internally by the compiler.
See also: __null_program

Constant sprintf_args: constantsprintf_args
Description: Type constant used for typing extra arguments that are sent to sprintf().
See also: strict_sprintf_format, sprintf_format, sprintf()

Constant sprintf_format: constantsprintf_format
Description: Type constant used for typing arguments that are optionally sent to sprintf() depending on the presence of extra arguments.
See also: strict_sprintf_format, sprintf_args, sprintf()

Constant sprintf_result: constantsprintf_result
Description: Type constant used for typing the return value from sprintf().
See also: strict_sprintf_format, sprintf_format, sprintf()

Constant strict_sprintf_format: constantstrict_sprintf_format
Description: Type constant used for typing arguments that are always sent to sprintf() regardless of the presence of extra arguments.
See also: sprintf_format, sprintf_args, sprintf()

Constant this: constantthis
Description: Builtin read only variable that evaluates to the current object.
See also: this_program, this_object()

Constant this_function: constantthis_function
Description: Builtin constant that evaluates to the current function.
See also: continue::this_function, this, this_object()

Constant this_program: constantthis_program
Description: Builtin constant that evaluates to the current program.
See also: this, this_object()

Method ProxyFactory

programProxyFactory(programp)

Description

Create a class that acts as a proxy for the specified program.

Parameter p

Program to generate a proxy for.

The generated class will have the same symbols (public and private) with the same types as in p, where accesses to these will proxy the access to the same symbol in the proxied (aka wrapped) object. With the following exceptions:

: Initialize the object to act as a proxy for obj.
: Special case for c == 'O', where it will return sprintf("%O(%O)", this_program, obj), and otherwise proxy the call.
: These lfuns will not be present as the act of them being proxied would likely confuse the proxied object.

Note

The same proxy class will be returned if this function is called with the same program multiple times.

Method _Static_assert

void_Static_assert(intconstant_expression, stringconstant_message)

Description

Perform a compile-time assertion check.

If constant_expression is false, a compiler error message containing constant_message will be generated.

Note

Note that the function call compiles to the null statement, and thus does not affect the run-time.

See also

cpp::static_assert

Method __automap__

array__automap__(function(:void) fun, mixed ... args)

Description

Automap execution function.

Parameter fun

Function to call for each of the mapped arguments.

Parameter args

Arguments for fun. Either

`Builtin.automap_marker`	Wrapper for an array to loop over. All of the arrays will be looped over in parallel.
`mixed`	All other arguments will be held constant during the automap, and sent as is to `fun`.

Note

This function is used by the compiler to implement the automap syntax, and should in normal circumstances never be used directly.

It may however show up during module dumping and in backtraces.

Note

It is an error not to have any Builtin.automap_markers in args.

See also

Builtin.automap_marker, map()

Method __cast: mixed__cast(mixedval, string|typetype_name)
Description: Cast val to the type indicated by type_name.
See also: lfun::cast()

Method __empty_program: program__empty_program(int|voidline, string|voidfile)
Parameter line: Optional line number of file where the program to be compiled definition starts.
Parameter file: Optional file name where the program to be compiled is defined.
Returns: Returns a virgin (ie empty) program suitable as the target argument to PikeCompiler().
See also: __null_program, PikeCompiler, compile_string()

Method __handle_sprintf_format

type__handle_sprintf_format(stringattr, string|zerofmt, typearg_type, type|zerocont_type, mappingstate)

Description

Type attribute handler for "sprintf_format".

Parameter attr

Attribute to handle, either "sprintf_format" or "strict_sprintf_format".

Parameter fmt

Sprintf-style formatting string to generate type information from.

Parameter arg_type

Declared type of the fmt argument (typically string).

Parameter cont_type

Continuation function type after the fmt argument. This is scanned for the type attribute "sprintf_args" to determine where the remaining arguments to sprintf() will come from.

Parameter state

State mapping.

This function is typically called from PikeCompiler()->apply_attribute_constant() and is used to perform stricter compile-time argument checking of sprintf()-style functions.

It currently implements two operating modes depending on the value of attr:

`"strict_sprintf_format"`	The formatting string `fmt` is known to always be passed to `sprintf()`.
`"sprintf_format"`	The formatting string `fmt` is passed to `sprintf()` only if there are `"sprintf_args"`.

Returns

Returns cont_type with "sprintf_args" replaced by the arguments required by the fmt formatting string, and "sprintf_result" replaced by the resulting string type.

See also

PikeCompiler()->apply_attribute_constant(), sprintf()

Method __parse_pike_type: string(8bit)__parse_pike_type(string(8bit)t)

Method _gdb_breakpoint: void_gdb_breakpoint()
Description: This function only exists so that it is possible to set a gdb breakpoint on the function pike_gdb_breakpoint.

Method abs: floatabs(floatf)
intabs(intf)
objectabs(objectf)
Description: Return the absolute value for f. If f is an object it must implement lfun::`< and unary lfun::`-.

Method acos: floatacos(int|floatf)
Description: Return the arcus cosine value for f. The result will be in radians.
See also: cos(), asin()

Method acosh: floatacosh(int|floatf)
Description: Return the hyperbolic arcus cosine value for f.
See also: cosh(), asinh()

Method add_constant

voidadd_constant(stringname, mixedvalue)
voidadd_constant(stringname)

Description

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.

See also

all_constants()

Method add_include_path

voidadd_include_path(stringtmp)

Description

Add a directory to search for include files.

This is the same as the command line option -I.

Note

Note that the added directory will only be searched when using < > to quote the included file.

See also

remove_include_path()

Method add_module_path

voidadd_module_path(stringpath, string|voidsubpath)

Description

Add a directory to search for modules.

This is the same as the command line option -M.

See also

remove_module_path()

Parameter path

a string containing a path to search for Pike modules. May be a directory, or a path to a ZIP archive. If a ZIP archive path is provided, modules will be loaded from a directory, "modules" within the ZIP archive (see the subpath argument).

Parameter subpath

if path is a ZIP archive, this argument will determine the path within the archive to be searched.

Method add_program_path

voidadd_program_path(stringtmp)

Description

Add a directory to search for programs.

This is the same as the command line option -P.

See also

remove_program_path()

Method aggregate

arrayaggregate(mixed ... elements)

Description

Construct an array with the arguments as indices.

This function could be written in Pike as:

array aggregate(mixed ... elems){return elems;}

Note

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.

See also

sizeof(), arrayp(), allocate()

Method aggregate_mapping

mappingaggregate_mapping(mixed ... elems)

Description

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

See also

sizeof(), mappingp(), mkmapping()

Method aggregate_multiset: multisetaggregate_multiset(mixed ... elems)
Description: Construct a multiset with the arguments as indices. The multiset will not contain any values. This method is most useful when constructing multisets with map or similar; generally, the multiset literal syntax is handier: (<elem1, elem2, ...>) With it, it's also possible to construct a multiset with values: (<index1: value1, index2: value2, ...>)
See also: sizeof(), multisetp(), mkmultiset()

Method all_constants: mapping(string:mixed) all_constants()
Description: Returns a mapping containing all global constants, indexed on the name of the constant, and with the value of the constant as value.
See also: add_constant()

Method allocate: arrayallocate(intsize)
arrayallocate(intsize, mixedinit)
Description: Allocate an array of size elements. If init is specified then each element is initialized by copying that value recursively.
See also: sizeof(), aggregate(), arrayp()

Method array_sscanf: arrayarray_sscanf(stringdata, stringformat)
Description: 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.
See also: sscanf(), `/()

Method asin: floatasin(int|floatf)
Description: Return the arcus sine value for f. The result will be in radians.
See also: sin(), acos()

Method asinh: floatasinh(int|floatf)
Description: Return the hyperbolic arcus sine value for f.
See also: sinh(), acosh()

Method atan: floatatan(int|floatf)
Description: Returns the arcus tangent value for f. The result will be in radians.
See also: tan(), asin(), acos(), atan2()

Method atan2: floatatan2(floatf1, floatf2)
Description: 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.
See also: tan(), asin(), acos(), atan()

Method atanh: floatatanh(int|floatf)
Description: Returns the hyperbolic arcus tangent value for f.
See also: tanh(), asinh(), acosh()

Method atomic_get_set

mixedatomic_get_set(mapping|objectmap, mixedkey, mixedval)
mixedatomic_get_set(arrayarr, intindex, mixedval)

Description

Replace atomically the value for a key in a mapping or array.

Parameter map

Parameter arr

Mapping or array to alter.

Parameter key

Parameter index

Key or index to change the value for.

Parameter val

Value to change to. If value is UNDEFINED and map is a mapping this function function behaves exactly as m_delete(map, key).

Returns

Returns the previous value for key. If map is a mapping and there was no previous value UNDEFINED is returned.

If map is an object lfun::_m_replace() will be called in it.

See also

m_delete()

Method await

mixedawait(Concurrent.Futurefuture)

Description

Stop execution of the current restartable function for now. Resume when the future completes.

Returns

Evaluates to the result of the future if it succeeds.

Throws

Throws an error if the future failed.

Calling this special form is similar to the expression:

(future->on_await(continue::this_function), yield())

Note

Use of this from a non-restartable functions causes a compilation warning and falls back to calling future->get(). This will thus then perform a wait blocking the current thread.

Note

No checks that the future has actually completed are performed. It is assumed that nothing else will call the restartable function during the wait.

See also

Concurrent.Future()->get(), yield(), continue::this_function, Restartable functions

Method basetype: stringbasetype(mixedx)
Description: Same as sprintf("%t",x);
See also: sprintf()

Method ceil: floatceil(int|floatf)
Description: Return the closest integer value greater or equal to f.
Note: ceil() does not return an int, merely an integer value stored in a float.
See also: floor(), round()

Method clone_to: objectclone_to(objectplaceholder, programp, mixed ... p_args)
Description: Coerce a placeholder object into a clone of a program.
Parameter placeholder: Clone of __null_program to alter.
Parameter p: Program to coerce the object to be a clone of.
Parameter p_args: Arguments to pass to lfun::create() in p.
Returns: Returns placeholder after successful coercion.
Note: placeholder may also already be a clone of [p], in which case this operation is a no-op.
See also: __null_program

Method column

arraycolumn(arraydata, mixedindex)

Description

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.

See also

rows()

Method compile

Description

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

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

See also

compile_string(), compile_file(), cpp(), master(), CompilationHandler, DefaultCompilerEnvironment

Method compile_file

programcompile_file(stringfilename, CompilationHandler|voidhandler, void|programp, void|objecto)

Description

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

See also

compile(), compile_string(), cpp()

Method compile_string

Description

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

See also

compile(), cpp(), compile_file()

Method copy_value

mixedcopy_value(mixedvalue)

Description

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 `==()).

See also

equal()

Method cos: floatcos(int|floatf)
Description: Return the cosine value for f. f should be specified in radians.
See also: acos(), sin(), tan()

Method cosh: floatcosh(int|floatf)
Description: Return the hyperbolic cosine value for f.
See also: acosh(), sinh(), tanh()

Method cpp

Description

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

If the second argument is a mapping, no other arguments may follow. Instead, they have to be given as members of the mapping (if wanted). The following members are recognized:

`"current_file" : string`	Name of the current file. It is used for generating #line directives and for locating include files.
`"charset" : bool\|string`	Charset to use when processing `data`.
`"handler" : object`	Compilation handler.
`"compat_major" : int`	Sets the major pike version used for compat handling.
`"compat_minor" : int`	Sets the minor pike version used for compat handling.
`"picky_cpp" : int`	Generate more warnings.
`"keep_comments" : int`	This option keeps `cpp()` from removing comments. Useful in combination with the prefix feature below.
`"prefix" : string`	If a prefix is given, only prefixed directives will be processed. For example, if the prefix is `"foo"`, then `#foo_ifdef COND` and `foo___LINE__` would be processed, `#ifdef COND` and `__LINE__` would not.
`"predefines" : mapping(string:mixed)`	Mapping of predefined macros in addition to those returned by `CPP()->get_predefines()`.

See also

compile()

Method ctime

stringctime(inttimestamp)

Description

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.

See also

strftime(), time(), localtime(), gmtime(), mktime()

Method decode_value

mixeddecode_value(string(8bit)coded_value, void|Codec|int(-1)codec)

Description

Decode a value from the string coded_value.

Parameter coded_value

Value to decode.

Parameter codec

Codec to use when encoding objects and programs.

Parameter trace

String.Buffer to contain a readable dump of the value.

Parameter debug

Debug level. Only available when the runtime has been compiled --with-rtl-debug.

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 none is specified, then one is instantiated through master()->Decoder(). As a compatibility fallback, the master itself is used if it has no Decoder class. If codec is the special value -1, then decoding of types, functions, programs and objects is disabled.

Note

Decoding a coded_value that you have not generated yourself is a security risk that can lead to execution of arbitrary code, unless codec is specified as -1.

See also

encode_value(), encode_value_canonic()

Method delay

voiddelay(int|floats)

Description

This function makes the thread 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.

See also

signal(), sleep()

Method describe_backtrace

stringdescribe_backtrace(mixedtrace, void|intlinewidth)

Description

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.

Pass linewidth -1 to disable wrapping of the output.

See also

backtrace(), describe_error(), catch(), throw()

Method describe_error

stringdescribe_error(mixederr)

Description

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.

See also

describe_backtrace(), get_backtrace

Method destruct

booldestruct(void|objecto)

Description

Mark an object as destructed.

Calls o->_destruct(), 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.

Returns

Returns 1 if o has an lfun::_destruct() that returned 1 and inhibited destruction.

Method encode_value

string(8bit)encode_value(mixedvalue, Codec|voidcodec)
string(8bit)encode_value(mixedvalue, Codec|voidcodec, String.Buffertrace)
string(8bit)encode_value(mixedvalue, Codec|voidcodec, int(0..)debug)

Description

Code a value into a string.

Parameter value

Value to encode.

Parameter codec

Codec to use when encoding objects and programs.

Parameter trace

String.Buffer to contain a readable dump of the value.

Parameter debug

Debug level. Only available when the runtime has been compiled --with-rtl-debug.

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.

If codec is specified, it's used as the codec for the encode. If none is specified, then one is instantiated through master()->Encoder(). As a compatibility fallback, the master itself is used if it has no Encoder class.

If codec->nameof(o) returns UNDEFINED for an object, val = o->encode_object(o) will be called. The returned value will be passed to o->decode_object(o, val) when the object is decoded.

Note

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.

See also

decode_value(), sprintf(), encode_value_canonic()

Method encode_value_canonic

string(8bit)encode_value_canonic(mixedvalue, object|voidcodec)
string(8bit)encode_value_canonic(mixedvalue, object|voidcodec, String.buffertrace)
string(8bit)encode_value_canonic(mixedvalue, object|voidcodec, int(0..)debug)

Description

Code a value into a string on canonical form.

Parameter value

Value to encode.

Parameter codec

Codec to use when encoding objects and programs.

Parameter trace

String.Buffer to contain a readable dump of the value.

Parameter debug

Debug level. Only available when the runtime has been compiled --with-rtl-debug.

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

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.

See also

encode_value(), decode_value()

Method enumerate

array(int) enumerate(intn)
arrayenumerate(intn, void|mixedstep, void|mixedstart, void|function(:void) operator)

Description

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;}

See also

map(), foreach()

Method equal

intequal(mixeda, mixedb)

Description

This function checks if the values a and b are equivalent.

Returns

If either of the values is an object the (normalized) result of calling lfun::_equal() will be returned.

Returns 1 if both values are false (zero, destructed objects, prototype functions, etc).

Returns 0 (zero) if the values have different types.

Otherwise depending on the type of the values:

int

Returns the same as a == b.

array

The contents of a and b are checked recursively, and if all their contents are equal and in the same place, they are considered equal.

Note that for objects this case is only reached if neither a nor b implements lfun::_equal().

type

Returns (a <= b) && (b <= a).

See also

copy_value(), `==()

Method error: voiderror(sprintf_formatf, sprintf_args ... args)
Description: Throws an error. A more readable version of the code throw( ({ sprintf(f, @args), backtrace() }) ).

Method exp: floatexp(float|intf)
Description: Return the natural exponential of f. log( exp( x ) ) == x as long as exp(x) doesn't overflow an int.
See also: pow(), log()

Method filter

mixedfilter(mixedarr, void|mixedfun, mixed ... extra)

Description

Filters the elements in arr through fun.

Parameter arr

arr is treated as a set of elements to be filtered, as follows:

`array`	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.
`mapping`	The values are filtered with `fun`, and the index/value pairs it accepts are kept in the returned mapping.
`program`	The program is treated as a mapping containing the identifiers that are indexable from it and their values.
`object`	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.

Parameter fun

Unless something else is mentioned above, fun is used as filter like this:

`array`	When both `arr` and `fun` are arrays, they should have the same lengths. In this case, the elements in `arr` are kept where the corresponding positions in `fun` are nonzero.
`function(mixed ... :mixed)`	`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 `fun` returns true, otherwise it's filtered out.
`object`	The object is used as a `function` like above, i.e. the lfun::`() method in it is called.
`multiset`	`fun` is indexed with each element. The element is kept if the result is nonzero, otherwise it's filtered out.
`zero\|void`	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.
`string`	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.

Note

The function is never destructive on arr.

See also

map(), foreach()

Method floor: floatfloor(int|floatf)
Description: Return the closest integer value less or equal to f.
Note: floor() does not return an int, merely an integer value stored in a float.
See also: ceil(), round()

Method get_active_compilation_handler: CompilationHandlerget_active_compilation_handler()
Description: Returns the currently active compilation compatibility handler, or 0 (zero) if none is active.
Note: This function should only be used during a call of compile().
See also: get_active_error_handler(), compile(), master()->get_compilation_handler(), CompilationHandler

Method get_active_compiler: CompilerEnvironment.PikeCompiler|zeroget_active_compiler()
Description: Returns the most recent of the currently active pike compilers, or UNDEFINED if none is active.
Note: This function should only be used during a call of compile().
See also: get_active_error_handler(), compile(), master()->get_compilation_handler(), CompilationHandler

Method get_active_error_handler: CompilationHandlerget_active_error_handler()
Description: Returns the currently active compilation error handler (second argument to compile()), or 0 (zero) if none is active.
Note: This function should only be used during a call of compile().
See also: get_active_compilation_handler(), compile(), CompilationHandler

Method get_all_groups

array(array(int|string|array(string))) get_all_groups()

Description

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.

Note

The groups source is system dependant. Refer to your system manuals for information about how to set the source.

Returns

Array
`array(int\|string\|array(string)) 0..`	Array with info about the group

See also

getgrent()

Method get_all_users: array(array(int|string)) get_all_users()
Description: Returns an array with all users in the system.
Returns: An array with arrays of userinfo as in getpwent.
See also: getpwent()getpwnam()getpwuid()

Method get_backtrace: arrayget_backtrace(object|arrayerr)
Description: 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.
See also: describe_backtrace(), describe_error()

Method get_groups_for_user

array(int) get_groups_for_user(int|stringuser)

Description

Gets all groups which a given user is a member of.

Parameter user

UID or loginname of the user

Returns

Array
`array0..`	Information about all the users groups

See also

get_all_groups()getgrgid()getgrnam()getpwuid()getpwnam()

Method get_iterator

Description

Creates and returns a canonical iterator for data.

Returns

data can have any of the following types:

`object`	If `data` is an object with `lfun::_get_iterator` defined then that function will be called with the arguments `args` to create the iterator. If `data` is an object that lacks `lfun::_get_iterator` then it is assumed to already be an iterator object. In this case `args` will be ignored (note this behavior may be changed). The iterator object is then checked whether it has `lfun::_iterator_next()` in which case it will simply be returned. Otherwise an attempt to wrap it in a `CompatIterator` will be performed.
`array`	If `data` is an array, an `Array.Iterator` object will be returned.
`function(:void)`	If `data` is a function, a `Function.Iterator` object will be returned.
`mapping`	If `data` is a mapping, a `Mapping.Iterator` object will be returned
`multiset`	If `data` is a multiset, a `Multiset.Iterator` object will be returned
`string`	If `data` is a string, a `String.Iterator` object will be returned

Note

This function is used by foreach to get an iterator for an object.

See also

Iterator, lfun::_get_iterator

Method getenv

mapping(string:string) getenv(void|intforce_update)

Description

Queries the environment variables.

Parameter force_update

A cached copy of the real environment is kept to make this function quicker. If the optional flag force_update is nonzero then the real environment is queried and the cache is updated from it. That can be necessary if the environment changes through other means than putenv, typically from a C-level library.

Returns

Returns the whole environment as a mapping. Destructive operations on the mapping will not affect the internal environment representation.

Variable names and values cannot be wide strings nor contain '\0' characters. Variable names also cannot contain '=' characters.

Note

On NT the environment variable name is case insensitive.

See also

putenv()

Method getenv

stringgetenv(stringvarname, void|intforce_update)

Description

Query the value of a specific environment variable.

Parameter varname

Environment variable to query.

Parameter force_update

Returns

Returns the value of the environment variable varname if it exists, and 0 (zero) otherwise.

Variable names and values cannot be wide strings nor contain '\0' characters. Variable names also cannot contain '=' characters.

Note

On NT the environment variable name is case insensitive.

See also

putenv()

Method getgrgid

array(int|string|array(string)) getgrgid(intgid)

Description

Get the group entry for the group with the id gid using the systemfunction getgrid(3).

Parameter gid

The id of the group

Returns

An array with the information about the group

Array
`string0`	Group name
`string1`	Group password (encrypted)
`int2`	ID of the group
`array3..`	Array with UIDs of group members

See also

getgrent()getgrnam()

Method getgrnam

array(int|string|array(string)) getgrnam(stringstr)

Description

Get the group entry for the group with the name str using the systemfunction getgrnam(3).

Parameter str

The name of the group

Returns

An array with the information about the group

Array
`string0`	Group name
`string1`	Group password (encrypted)
`int2`	ID of the group
`array3..`	Array with UIDs of group members

See also

getgrent()getgrgid()

Method gethrdtime: intgethrdtime(void|intnsec)
Description: Return the high resolution real time spent with threads disabled since the Pike interpreter was started. The time is normally returned in microseconds, but if the optional argument nsec is nonzero it's returned in nanoseconds.
Note: The actual accuracy on many systems is significantly less than microseconds or nanoseconds. See System.REAL_TIME_RESOLUTION.
See also: _disable_threads(), gethrtime()

Method gethrtime

intgethrtime(void|intnsec)

Description

Return the high resolution 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.

It's system dependent whether or not this time is monotonic, i.e. if it's unaffected by adjustments of the calendaric clock in the system. System.REAL_TIME_IS_MONOTONIC tells what it is. Pike tries to use monotonic time for this function if it's available.

Note

The actual accuracy on many systems is significantly less than microseconds or nanoseconds. See System.REAL_TIME_RESOLUTION.

See also

System.REAL_TIME_IS_MONOTONIC, System.REAL_TIME_RESOLUTION, time(), System.gettimeofday(), gethrvtime(), Pike.implicit_gc_real_time

Method gethrvtime

intgethrvtime(void|intnsec)

Description

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. If both types are available then thread local time is preferred.

Note

The actual accuracy on many systems is significantly less than microseconds or nanoseconds. See System.CPU_TIME_RESOLUTION.

Note

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.

Note

The special function gauge is implemented with this function.

See also

System.CPU_TIME_IS_THREAD_LOCAL, System.CPU_TIME_RESOLUTION, gauge(), System.getrusage(), gethrtime()

Method getpid: intgetpid()
Description: Returns the process ID of this process.
See also: System.getppid(), System.getpgrp()

Method getpwnam

array(int|string) getpwnam(stringstr)

Description

Get the user entry for login str using the systemfunction getpwnam(3).

Parameter str

The login name of the user whos userrecord is requested.

Returns

An array with the information about the user

Array
`string0`	Users username (loginname)
`string1`	User password (encrypted)
`int2`	Users ID
`int3`	Users primary group ID
`string4`	Users real name an possibly some other info
`string5`	Users home directory
`string6`	Users shell

See also

getpwuid()getpwent()

Method getpwuid

array(int|string) getpwuid(intuid)

Description

Get the user entry for UID uid using the systemfunction getpwuid(3).

Parameter uid

The uid of the user whos userrecord is requested.

Returns

An array with the information about the user

Array
`string0`	Users username (loginname)
`string1`	User password (encrypted)
`int2`	Users ID
`int3`	Users primary group ID
`string4`	Users real name an possibly some other info
`string5`	Users home directory
`string6`	Users shell

See also

getpwnam()getpwent()

Method getxattr: stringgetxattr(stringfile, stringattr, void|boolsymlink)
Description: Return the value of a specified attribute, or 0 if it does not exist.

Method glob

boolglob(stringglob, stringstr)
zero|stringglob(array(string) glob, stringstr)
array(string) glob(stringglob, array(string) str)
array(string) glob(array(string) glob, array(string) str)

Description

Match strings against a glob pattern.

Parameter glob

string

The glob pattern.

Some characters have special meanings.

When a character range is not started the following characters have special meanings:

`'?'`	A question sign (`'?'`) matches any character.
`'*'`	An asterisk (`'*'`) matches a string of arbitrary length.
`'\\'`	A back-slash (`'\\'`) escapes the following character so that it is matched verbatim.
`'['`	A left-bracket (`'['`) starts a character range.

If a character range is started the following characters have special meanings:

`'\\'`	Escape (as above).
`']'`	A right-bracket (`']'`) ends a character range.
`'^'`	The characters `'^'` and `'!'` invert the character range if they are the first character in the range and otherwise match themselves.
`'!'`
`'-'`	The character `'-'` separates the first and last characters in a character sequence.

All other characters only match themselves.

array(string)

An array of glob patterns (as above).

The function returns the matching glob if any of the given patterns match. Otherwise 0. If the second argument (str) is an array it will behave as if the first argument is a string (see below).

Parameter str

`string`	`1` is returned if the string `str` matches `glob`, `0` (zero) otherwise.
`array(string)`	All strings in the array `str` are matched against `glob`, and those that match are returned in an array (in the same order).

Note

In Pike 8.0 and earlier only '?' and '*' had special meanings. The old implementation is available as 8.0::glob().

Note

In Pike 8.0 and earlier 1 was also returned when matching an array of globs against a single string.

See also

8.0::glob(), sscanf(), Regexp

Method gmtime

mapping(string:int) gmtime(inttimestamp)

Description

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.

Note

Timestamps prior to 1970-01-01T00:00:00 (ie negative timestamps) were not supported on NT and AIX prior to Pike 9.0.

See also

localtime(), time(), ctime(), mktime(), strptime()

Method has_index

inthas_index(stringhaystack, intindex)
inthas_index(arrayhaystack, intindex)
inthas_index(mapping|multiset|object|programhaystack, mixedindex)

Description

Search for index in haystack.

Returns

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

Note

A negative index in strings and arrays as recognized by the index operators `[]() and `[]=() is not considered a proper index by has_index()

See also

has_value(), has_prefix(), has_suffix(), indices(), search(), values(), zero_type()

Method has_prefix

inthas_prefix(string|objects, stringprefix)

Description

Returns 1 if the string s starts with prefix, returns 0 (zero) otherwise.

When s is an object, it needs to implement lfun::_sizeof() and lfun::`[].

See also

has_suffix(), has_value(), search()

Method has_suffix: inthas_suffix(strings, stringsuffix)
Description: Returns 1 if the string s ends with suffix, returns 0 (zero) otherwise.
See also: has_prefix(), has_value(), search()

Method has_value

inthas_value(stringhaystack, stringvalue)
inthas_value(stringhaystack, intvalue)
inthas_value(array|mapping|object|programhaystack, mixedvalue)

Description

Search for value in haystack.

Returns

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

See also

has_index(), indices(), search(), has_prefix(), has_suffix(), values(), zero_type()

Method hash

inthash(strings)
inthash(strings, intmax)

Description

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.

Note

The hash algorithm was changed in Pike 8.1. If you want a hash that is compatible with Pike 8.0 and earlier, use hash_8_0().

The hash algorithm was also 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 with regards to hash_8_0() 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().

Note

This hash function differs from the one provided by hash_value(), in that hash_value() returns a process specific value.

See also

hash_7_0(), hash_7_4(), hash_8_0(), hash_value

Method hash_7_0

inthash_7_0(strings)
inthash_7_0(strings, intmax)

Description

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.

Note

This function is provided for backward compatibility with code written for Pike up and including version 7.0.

This function is not NUL-safe, and is byte-order dependant.

See also

hash(), hash_7_4

Method hash_7_4

inthash_7_4(strings)
inthash_7_4(strings, intmax)

Description

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.

Note

This function is provided for backward compatibility with code written for Pike up and including version 7.4.

This function is byte-order dependant for wide strings.

See also

hash_7_6(), hash_7_0

Method hash_8_0

inthash_8_0(strings)
inthash_8_0(strings, intmax)

Description

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.

Deprecated

Use hash_value() for in-process hashing (eg, for implementing lfun::_hash()) or one of the cryptographic hash functions.

Note

This function is really bad at hashing strings. Similar string often return similar hash values.

It is especially bad for url:s, paths and similarly formatted strings.

Note

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

Note

This hash function differs from the one provided by hash_value(), in that hash_value() returns a process specific value.

See also

hash(), hash_7_0(), hash_7_4(), hash_value

Method hash_value

inthash_value(mixedvalue)

Description

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

Note

This is the hashing method used by mappings.

See also

lfun::__hash()

Method is_absolute_path: intis_absolute_path(stringp)
Description: Check if a path p is fully qualified (ie not relative).
Returns: Returns 1 if the path is absolute, 0 otherwise.

Method iterator_index: mixediterator_index(Iteratoriter)
Description: Get the current index for iter.
See also: iterator_value(), lfun::_iterator_index(), get_iterator()

Method iterator_next: mixediterator_next(Iteratoriter)
Description: Advance iter one step.
Returns: Returns UNDEFINED if the iterator failed to advance, and otherwise the value returned from lfun::_iterator_next().
Note: Zero values returned by lfun::_iterator_next() are converted to UNDEFINED when lfun::_iterator_value() is implemented.
See also: iterator_prev(), lfun::_iterator_next(), get_iterator()

Method iterator_prev: mixediterator_prev(Iteratoriter)
Description: Advance iter one step backward (if supported).
See also: iterator_next(), lfun::_iterator_prev(), get_iterator()

Method iterator_value: mixediterator_value(Iteratoriter)
Description: Get the current value for iter.
See also: iterator_index(), lfun::_iterator_value(), get_iterator()

Method kill

boolkill(intpid, intsignal)

Description

Send a signal to another process.

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

Returns

`1`	Success.
`0`	Failure. `errno()` is set to EINVAL, EPERM or ESRCH.

Note

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.

See also

signal(), signum(), signame(), fork()

Method limit: int|float|objectlimit(int|float|objectminval, int|float|objectx, int|float|objectmaxval)
Description: Limits the value x so that it's between minval and maxval. If x is an object, it must implement the lfun::`< method.
See also: max() and min()

Method listxattr: array(string) listxattr(stringfile, void|boolsymlink)
Description: Return an array of all extended attributes set on the file

Method load_module

programload_module(stringmodule_name)

Description

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.

Note

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.

Method localtime

mapping(string:int) localtime(inttimestamp)

Description

Convert seconds since 00:00:00 UTC, 1 Jan 1970 into components.

Returns

This function returns a mapping with the following components:

`"sec" : int(0..60)`	Seconds over the minute.
`"min" : int(0..59)`	Minutes over the hour.
`"hour" : int(0..23)`	Hour of the day.
`"mday" : int(1..31)`	Day of the month.
`"mon" : int(0..11)`	Month of the year.
`"year" : int(0..)`	Year since 1900.
`"wday" : int(0..6)`	Day of week (0 = Sunday).
`"yday" : int(0..365)`	Day of the year.
`"isdst" : bool`	Is daylight-saving time active.
`"timezone" : int`	Offset from UTC, including daylight-saving 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.

Note

Prior to Pike 7.5 the field "timezone" was sometimes not present, and was sometimes not adjusted for daylight-saving time.

Note

Timestamps prior to 1970-01-01T00:00:00 (ie negative timestamps) were not supported on NT and AIX prior to Pike 9.0. Note also that dst-handling may be incorrect for such timestamps.

See also

Calendar, gmtime(), time(), ctime(), mktime(), strptime()

Method log: floatlog(int|floatf)
Description: Return the natural logarithm of f. exp( log(x) ) == x for x > 0.
See also: pow(), exp()

Method lower_case: stringlower_case(strings)
intlower_case(intc)
Description: Convert a string or character to lower case.
Returns: Returns a copy of the string s with all upper case characters converted to lower case, or the character c converted to lower case.
Note: Assumes the string or character to be coded according to ISO-10646 (aka Unicode). If they are not, Charset.decoder can do the initial conversion for you.
Note: Prior to Pike 7.5 this function only accepted strings.
See also: upper_case(), Charset.decoder

Method m_add: voidm_add(multiset|objectl, mixedval)
Description: Add a member to a multiset.
See also: m_delete()

Method m_clear

voidm_clear(mapping|multiset|objectmap)

Description

Clear the contents of a mapping or multiset.

This function clears the content of the mapping or multiset map so that it becomes empty. This is an atomic operation.

If map is an object lfun::_m_clear() will be called in it.

See also

m_delete()

Method m_delete

mixedm_delete(object|mapping|multisetmap, mixedindex, mixed|voidexpected)

Description

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 or multiset the entry with index index will be removed from map destructively.

If the mapping or multiset does not have an entry with index index, nothing is done.

If expected has been specified, the entry will only be removed if its value matches (with `==()).

Returns

The value that was removed will be returned, and UNDEFINED otherwise.

Note

Note that m_delete() changes map destructively.

Note

The third argument (expected) was added in Pike 9.0, and can be used for atomic test and unset.

See also

mappingp()

Method map

mixedmap(mixedarr, void|mixedfun, mixed ... extra)

Description

Applies fun to the elements in arr and collects the results.

Parameter arr

arr is treated as a set of elements, as follows:

`array`	`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.
`mapping`	`fun` is applied to the values, and each result is assigned to the same index in a new mapping, which is returned.
`program`	The program is treated as a mapping containing the identifiers that are indexable from it and their values.
`object`	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.

Parameter fun

fun is applied in different ways depending on its type:

`function(mixed ... :mixed)`	`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.
`object`	`fun` is used as a function like above, i.e. the lfun::`() method in it is called.
`array`	Each element of the `fun` array will be called for each element of `arr`.
`multiset`	`fun` is indexed with each element. The result of that is collected.
`zero\|void`	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.
`string`	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.

Note

The function is never destructive on arr.

See also

filter(), enumerate(), foreach()

Method master: objectmaster()
Description: Return the current master object.
Note: May return UNDEFINED if no master has been loaded yet.
See also: replace_master()

Method max: int|float|objectmax(int|float|object, int|float|object ... args)
stringmax(string, string ... args)
int(0)max()
Description: Returns the largest value among args. Compared objects must implement the lfun::`< method.
See also: min() and limit()

Method min: int|float|objectmin(int|float|object, int|float|object ... args)
stringmin(string, string ... args)
int(0)min()
Description: Returns the smallest value among args. Compared objects must implement the lfun::`< method.
See also: max() and limit()

Method mkmapping

mappingmkmapping(arrayind, arrayval)

Description

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

See also

indices(), values()

Method mkmultiset: multisetmkmultiset(arraya)
Description: This function creates a multiset from an array.
See also: aggregate_multiset()

Method mktime

intmktime(mapping(string:int) tm)
intmktime(intsec, intmin, inthour, intmday, intmon, intyear, int|voidisdst, int|voidtz)

Description

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:

`"sec" : int(0..60)`	Seconds over the minute.
`"min" : int(0..59)`	Minutes over the hour.
`"hour" : int(0..23)`	Hour of the day.
`"mday" : int(1..31)`	Day of the month.
`"mon" : int(0..11)`	Month of the year.
`"year" : int(0..)`	Year since 1900.
`"isdst" : int(-1..1)`	Is daylight-saving time active. If omitted or set to `-1`, it means that the information is not available.
`"timezone" : int`	The timezone offset from UTC in seconds. If omitted, the time will be calculated in the local timezone.

Or you can just send them all on one line as the second syntax suggests.

Note

For proper UTC calculations ensure that isdst = 0andtimezone = 0; omitting either one of these parameters will mess up the UTC calculation.

Note

On some operating systems (notably AIX and Win32), dates before 00:00:00 UTC, Jan 1, 1970 were not supported prior to Pike 9.0.

On most 32-bit systems, the supported range of dates is from Dec 13, 1901 20:45:52 UTC through to Jan 19, 2038 03:14:07 UTC (inclusive).

On most 64-bit systems, the supported range of dates is expressed in 56 bits and is thus practically unlimited (at least up to 1141 milion years in the past and into the future).

See also

time(), ctime(), localtime(), gmtime(), strftime()

Method normalize_path: stringnormalize_path(stringpath)
Description: Replaces "\" with "/" if runing on MS Windows. It is adviced to use System.normalize_path instead.

Method object_variablep: boolobject_variablep(objecto, stringvar)
Description: Find out if an object identifier is a variable.
Returns: This function returns 1 if var exists as a non-protected variable in o, and returns 0 (zero) otherwise.
See also: indices(), values()

Method objectp: intobjectp(mixedarg)
Description: Returns 1 if arg is an object, 0 (zero) otherwise.
See also: mappingp(), programp(), arrayp(), stringp(), functionp(), multisetp(), floatp(), intp()

Method pow: int|floatpow(float|intn, float|intx)
mixedpow(objectn, float|int|objectx)
Description: 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.
See also: exp(), log()

Method putenv

voidputenv(stringvarname, void|stringvalue)

Description

Sets the environment variable varname to value.

If value is omitted or zero, the environment variable varname is removed.

varname and value cannot be wide strings nor contain '\0' characters. varname also cannot contain '=' characters.

Note

On NT the environment variable name is case insensitive.

See also

getenv()

Method random: arrayrandom(mappingm)
floatrandom(floatmax)
intrandom(intmax)
mixedrandom(objecto)
mixedrandom(array|multisetx)
Description: Get a random value generated by the default RandomSystem.
See also: RandomSystem()->random(), random_string()

Method random_seed: voidrandom_seed(intseed)
Description: This function sets the initial value for the random generator.
See also: random()
Deprecated: Random.Deterministic

Method random_string: stringrandom_string(intlen)
Description: Get a string of random characters 0..255 with the length len from the default RandomSystem.
See also: RandomSystem()->random_string(), random()

Method remove_include_path

voidremove_include_path(stringtmp)

Description

Remove a directory to search for include files.

This function performs the reverse operation of add_include_path().

See also

add_include_path()

Method remove_module_path

voidremove_module_path(stringtmp)

Description

Remove a directory to search for modules.

This function performs the reverse operation of add_module_path().

See also

add_module_path()

Method remove_program_path

voidremove_program_path(stringtmp)

Description

Remove a directory to search for programs.

This function performs the reverse operation of add_program_path().

See also

add_program_path()

Method removexattr: voidremovexattr(stringfile, stringattr, void|boolsymlink)
Description: Remove the specified extended attribute.

Method replace

arrayreplace(arraya, mixedfrom, mixedto)
mappingreplace(mappinga, mixedfrom, mixedto)

Description

Generic replace function (arrays and mappings).

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

Note that replace() on arrays and mappings is a destructive operation.

Method replace

stringreplace(strings, stringfrom, stringto)
stringreplace(strings, array(string) from, array(string) to)
stringreplace(strings, array(string) from, stringto)
stringreplace(strings, mapping(string:string) replacements)

Description

Generic replace function (strings).

Parameter s

Source string to perform the replacements on.

Parameter from

Sub-string or strings to match verbatim.

Parameter to

String or strings that from in s should be replaced with.

Parameter replacements

Instead of the arrays from and to a mapping equivalent to mkmapping(from, to) can be used.

Replaces all occurrances of from in s with the corresponding to.

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.

Method replace_master

voidreplace_master(objecto)

Description

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.

See also

master()

Method reverse

Description

Reverses a string, array or int.

Parameter s

String to reverse.

Parameter a

Array to reverse.

Parameter i

Integer to reverse.

Parameter o

Object to reverse.

Parameter start

Optional start index of the range to reverse. Default: 0 (zero).

Parameter end

Optional end index of the range to reverse. Default for strings: sizeof(s)-1. Default for arrays: sizeof(a)-1. Default for integers: Pike.get_runtime_info()->int_size - 1.

Parameter options

Optional arguments that are to be passed to lfun::_reverse().

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. For objects it simply calls lfun::_reverse() in the object, and returns the result.

Reversing strings can be particularly useful for parsing difficult syntaxes which require scanning backwards.

See also

sscanf()

Method round: floatround(int|floatf)
Description: Return the closest integer value to f.
Note: round() does not return an int, merely an integer value stored in a float.
See also: floor(), ceil()

Method rows

arrayrows(mixeddata, arrayindex)

Description

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.

See also

column()

Method search

Description

Search for needle in haystack.

Parameter haystack

Item to search in. This can be one of:

`string`	When `haystack` is a string `needle` must be a string or an int, and the first occurrence of the string or int is returned.
`array`	When `haystack` is an array, `needle` is compared only to one value at a time in `haystack`.
`mapping`	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.
`object`	When `haystack` is an object implementing `lfun::_search()`, the result of calling `lfun::_search()` with `needle`, `start` and any `extra_args` 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.

Parameter start

If the optional argument start is present search is started at this position. This has no effect on mappings.

Parameter end

If the optional argument end is present, the search will terminate at this position (exclusive) if not found earlier.

Returns

Returns the position of needle in haystack if found.

If not found the returned value depends on the type of haystack:

`string\|array`	`-1`.
`mapping\|Iterator`	`UNDEFINED`.
`object`	The value returned by `lfun::_search()`.

Note

If start is supplied to an iterator object without an lfun::_search(), haystack will need to implement Iterator()->set_index().

Note

For mappings and object UNDEFINED will be returned when not found. In all other cases -1 will be returned when not found.

See also

indices(), values(), zero_type(), has_value(), has_prefix(), has_suffix()

Method set_priority: intset_priority(stringlevel, int(0..)|voidpid)

Method set_weak_flag

array|mapping|multisetset_weak_flag(array|mapping|multisetm, intstate)

Description

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.

Returns

m will be returned.

Method setxattr

voidsetxattr(stringfile, stringattr, stringvalue, intflags, void|boolsymlink)

Description

Set the attribute attr to the value value.

The flags parameter can be used to refine the semantics of the operation.

Stdio.XATTR_CREATE specifies a pure create, which fails if the named attribute exists already.

Stdio.XATTR_REPLACE specifies a pure replace operation, which fails if the named attribute does not already exist.

By default (no flags), the extended attribute will be created if need be, or will simply replace the value if the attribute exists.

Returns

1 if successful, 0 otherwise, setting errno.

Method sgn: intsgn(mixedvalue)
intsgn(mixedvalue, mixedzero)
Description: Check the sign of a value.
Returns: Returns -1 if value is less than zero, 1 if value is greater than zero and 0 (zero) otherwise.
See also: abs()

Method signal

function(int|void:void) signal(intsig, function(int|void:void) callback)
function(int|void:void) signal(intsig)

Description

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

Returns

Returns the previous signal function, or 0 if none had been registered.

See also

kill(), signame(), signum()

Method signame: stringsigname(intsig)
Description: Returns a string describing the signal sig.
See also: kill(), signum(), signal()

Method signum

intsignum(stringsig)

Description

Get a signal number given a descriptive string.

This function is the inverse of signame().

See also

signame(), kill(), signal()

Method sin: floatsin(int|floatf)
Description: Returns the sine value for f. f should be specified in radians.
See also: asin(), cos(), tan()

Method sinh: floatsinh(int|floatf)
Description: Returns the hyperbolic sine value for f.
See also: asinh(), cosh(), tanh()

Method sizeof

int(0..)sizeof(stringarg)
int(0..)sizeof(arrayarg)
int(0..)sizeof(mappingarg)
int(0..)sizeof(multisetarg)
int(0..)sizeof(objectarg)

Description

Size query.

Returns

The result will be as follows:

arg can have any of the following types:

`string`	The number of characters in `arg` will be returned.
`array\|multiset`	The number of elements in `arg` will be returned.
`mapping`	The number of key-value pairs in `arg` will be returned.
`object`	If `arg` implements `lfun::_sizeof()`, that function will be called. Otherwise the number of non-protected (ie public) symbols in `arg` will be returned.

See also

lfun::_sizeof()

Method sleep

voidsleep(int|floats, void|intabort_on_signal)

Description

This function makes the thread 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.

See also

signal(), delay()

Method sort

arraysort(array(mixed) index, array(mixed) ... data)

Description

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.

Returns

The first argument is returned.

Note

The sort is stable, i.e. elements that are compare-wise equal aren't reordered.

See also

Array.sort_array, reverse()

Method sprintf

stringsprintf(strict_sprintf_formatformat, sprintf_args ... args)

Description

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 width. Breaks between words (possibly skipping or adding spaces). Can not be used together with '/'.

'/'

Column mode with rough line break (break at exactly field width instead of between words). Can not be used together with '='.

'#'

Table mode, print a list of '\n' separated words (top-to-bottom order).

'$'

Inverse table mode (left-to-right order).

'n'

(Where n is a number or *) field width specifier.

':n'

'.n'

Precision specifier.

';n'

Column width specifier.

'*'

If n is a * then next argument is used for precision/field size. The argument may either be an integer, or a modifier mapping as received by lfun::_sprintf():

`"precision" : int\|void`	Precision (aka `'.n'` where n is a number).
`"width" : int(0..)\|void`	Field width (aka `'n'` or `':n'` where n is a number).
`"flag_left" : bool\|void`	Indicates that the output should be left-aligned (aka `'-'`).
`"indent" : int(0..)\|void`	Base indentation level in number of spaces in `%O`-mode.

"'"

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 arguments are numbered starting from 0 (zero) for the first argument after the format. Note that this only affects where the current operand is fetched.

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 or 8-bit string.
`'X'`	Uppercase signed hexadecimal integer or 8-bit string.
`'c'`	Character (integer). 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) in network (big endian) byte order. To get little endian byte order, negate the field size.
`'s'`	String.
`'q'`	Quoted string. Escapes all control and non-8-bit characters, as well as the quote characters `'\\'` and `'\"'`.
`'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 `lfun::_sprintf()` method implementor wanted for debugging.
`'p'`	Hexadecimal representation of the memory address of the object. Integers and floats have no address, and are printed as themselves.
`'H'`	Binary Hollerith string. Equivalent to `sprintf("%c%s", strlen(str), str)`. Arguments (such as width etc) adjust the length-part of the format. Requires 8-bit strings.
`'n'`	No argument. Same as `"%s"` with an empty string as argument. Note: Does take an argument array (but ignores its content) if the modifier `'@'` is active.
`'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.

Note

sprintf-style formatting is applied by many formatting functions, such write() and werror(). It is also possible to get sprintf-style compile-time argument checking by using the type-attributes sprintf_format or strict_sprintf_format in combination with sprintf_args.

Note

Most formats are available in all versions of Pike; the exceptions are:

Format	Version	Availability constant	Notes
`'*'`	Pike 7.8.238	`String.__HAVE_SPRINTF_STAR_MAPPING__`	Support for specifying modifiers via a mapping.
`'b'`	Pike 0.7.62
`'c'`	Pike 0.7.3		Support for wide characters.
`'c'`	Pike 0.7.64		Support for little endian output.
`'E'`	Pike 0.6.38
`'F'`	Pike 0.6.38
`'F'`	Pike 7.8.242	`String.__HAVE_SPRINTF_NEGATIVE_F__`	Support for litte endian byte order.
`'G'`	Pike 0.6.38
`'H'`	Pike 7.7.31
`'p'`	Pike 7.5.4		Implemented but disabled (`#if 0`-block).
`'p'`	Pike 8.1.14		Enabled.
`'q'`	Pike 7.7.28
`'x'`	Pike 8.1.5		Support for hex-formatting strings.
`'X'`	Pike 8.1.5		Support for hex-formatting strings.
`'[n]'`	Pike 7.1.5

Example

Pike v7.8 release 263 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"> 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#%|*s\n", screen_width,"THE END",
>>      (["width":screen_width ]),"ALTERNATIVE END");
#                               THE END
#                           ALTERNATIVE END
(14) Result: 144

See also

lfun::_sprintf(), strict_sprintf_format, sprintf_format, sprintf_args, String.__HAVE_SPRINTF_STAR_MAPPING__, String.__HAVE_SPRINTF_NEGATIVE_F__.

Method sqrt: floatsqrt(floatf)
int(0..)sqrt(int(0..)i)
mixedsqrt(objecto)
Description: 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.
See also: pow(), log(), exp(), floor(), lfun::_sqrt

Method sscanf

intsscanf(stringdata, stringformat, mixed ... lvalues)

Description

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 a special form, 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 may contain strings separated by special matching directives like %d, %s%c and %f. Every such directive corresponds to one of the lvalues, in the order they are listed. An lvalue is the name of a variable, a name of a local variable, an index into 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"` for later directives. The sign modifiers can be used to modify the signature of the data, making `"%+1c"` decode `"ä"` into `-28`.
`"%n"`	Returns the current character offset in `data`. Note that any characters matching fields scanned with the `"!"`-modifier are removed from the count (see below).
`"%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.
`"%H"`	Reads a Hollerith-encoded string, i.e. first reads the length of the string and then that number of characters. The size and byte order of the length descriptor can be modified in the same way as `%c`. As an example `"%2H"` first reads `"%2c"` and then the resulting number of characters.
`"%[set]"`	Matches a string containing a given set of characters (those given inside the 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 (not possible in complemented sets, see below) or last in the brackets to avoid having a range defined. Sets including the character ']' must list this first too. If both '-' and ']' should be included then put ']' first and '-' last. It is not possible to make a range that ends with ']'; make the range end with '\' instead and put ']' at the beginning of the set. Likewise it is generally not possible to have a range start with '-'; make the range start with '.' instead and put '-' at the end of the set. If the first character after the [ bracket is '^' (%[^set]), and this character does not begin a range, it means that the set is complemented, which is to say that any character except those inside brackets is matched. To include '-' in a complemented set, it must be put last, not first. To include '^' in a non-complemented set, it can be put anywhere but first, or be specified as a range ("^-^").
`"%{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.
`"!"`	Ignore the matched characters with respect to any following `"%n"`.

Note

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.

Example

// 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);

Returns

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

See also

sprintf, array_sscanf

Method strftime

string(1..255)strftime(string(1..255)format, mapping(string:int) tm)

Description

Convert the structure to a string.

%a: The abbreviated weekday name according to the current locale
%A: The full weekday name according to the current locale.
%b: The abbreviated month name according to the current locale.
%B: The full month name according to the current locale.
%c: The preferred date and time representation for the current locale.
%C: The century number (year/100) as a 2-digit integer.
%d: The day of the month as a decimal number (range 01 to 31).
%D: Equivalent to %m/%d/%y. (for Americans only. Americans should note that in other countries %d/%m/%y is rather common. This means that in international context this format is ambiguous and should not be used.)
%e: Like %d, the day of the month as a decimal number, but a leading zero is replaced by a space.
%E: Modifier: use alternative format, see below.
%F: Equivalent to %Y-%m-%d (the ISO 8601 date format). (C99)
%G: The ISO 8601 week-based year (see NOTES) with century as a decimal number. The 4-digit year corresponding to the ISO week number (see %V). This has the same format and value as %Y, except that if the ISO week number belongs to the previous or next year, that year is used instead.
%g: Like %G, but without century, that is, with a 2-digit year (00-99). (TZ)
%h: Equivalent to %b.
%H: The hour as a decimal number using a 24-hour clock (range 00 to 23).
%I: The hour as a decimal number using a 12-hour clock (range 01 to 12).
%j: The day of the year as a decimal number (range 001 to 366).
%m: The month as a decimal number (range 01 to 12).
%M: The minute as a decimal number (range 00 to 59).
%n: A newline character. (SU)
%O: Modifier: use alternative format, see below. (SU)
%p: Either "AM" or "PM" according to the given time value, or the corresponding strings for the current locale. Noon is treated as "PM" and midnight as "AM".
%P: Like %p but in lowercase: "am" or "pm" or a corresponding string for the current locale.
%r: The time in a.m. or p.m. notation. In the POSIX locale this is equivalent to %I:%M:%S %p.
%R: The time in 24-hour notation (%H:%M). (SU) For a version including the seconds, see %T below.
%s: The number of seconds since the Epoch, 1970-01-01 00:00:00 +0000 (UTC). (TZ)
%S: The second as a decimal number (range 00 to 60). (The range is up to 60 to allow for occasional leap seconds.)
%t: A tab character. (SU)
%T: The time in 24-hour notation (%H:%M:%S). (SU)
%u: The day of the week as a decimal, range 1 to 7, Monday being 1. See also %w. (SU)
%U: The week number of the current year as a decimal number, range 00 to 53, starting with the first Sunday as the first day of week 01. See also %V and %W.
%V: The ISO 8601 week number of the current year as a decimal number, range 01 to 53, where week 1 is the first week that has at least 4 days in the new year. See also %U and %W.
%w: The day of the week as a decimal, range 0 to 6, Sunday being 0. See also %u.

See also

ctime(), mktime(), strptime(), Gettext.setlocale

Method string_filter_non_unicode: string(1..)string_filter_non_unicode(strings)
Description: Replace the most obviously non-unicode characters from s with the unicode replacement character.
Note: This will replace characters outside the ranges 0x00000000-0x0000d7ff and 0x0000e000-0x0010ffff with 0xffea (the replacement character).
See also: Charset.encoder(), string_to_unicode(), unicode_to_string(), utf8_to_string(), string_to_utf8()

Method string_to_unicode

string(8bit)string_to_unicode(strings, int(0..2)|voidbyteorder)

Description

Converts a string into an UTF16 compliant byte-stream.

Parameter s

String to convert to UTF16.

Parameter byteorder

Byte-order for the output. One of:

`0`	Network (aka big-endian) byte-order (default).
`1`	Little-endian byte-order.
`2`	Native byte-order.

Note

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.

See also

Charset.decoder(), string_to_utf8(), unicode_to_string(), utf8_to_string()

Method string_to_utf8

utf8_stringstring_to_utf8(strings)
utf8_stringstring_to_utf8(strings, intextended)

Description

Convert a string into a UTF-8 compliant byte-stream.

Parameter s

String to encode into UTF-8.

Parameter extended

Bitmask with extension options.

`1`	Accept and encode the characters outside the valid ranges using the same algorithm. Such encoded characters are however not UTF-8 compliant.
`2`	Encode characters outside the BMP with UTF-8 encoded UTF-16 (ie split them into surrogate pairs and encode).

Note

Throws an error if characters not valid in an UTF-8 stream are encountered. Valid characters are in the ranges 0x00000000-0x0000d7ff and 0x0000e000-0x0010ffff.

See also

Charset.encoder(), string_to_unicode(), unicode_to_string(), utf8_to_string()

Method stringp: intstringp(mixedarg)
Description: Returns 1 if arg is a string, 0 (zero) otherwise.
See also: intp(), programp(), arrayp(), multisetp(), objectp(), mappingp(), floatp(), functionp()

Method strptime

mapping(string:int) strptime(string(1..255)data, string(1..255)format)

Description

Parse the given data using the format in format as a date.

%%: The % character.
%a or %A: The weekday name according to the C locale, in abbreviated form or the full name.
%b or %B or %h: The month name according to the C locale, in abbreviated form or the full name.
%c: The date and time representation for the C locale.
%C: The century number (0-99).
%d or %e: The day of month (1-31).
%D: Equivalent to %m/%d/%y.
%H: The hour (0-23).
%I: The hour on a 12-hour clock (1-12).
%j: The day number in the year (1-366).
%m: The month number (1-12).
%M: The minute (0-59).
%n: Arbitrary whitespace.
%p: The C locale's equivalent of AM or PM.
%R: Equivalent to %H:%M.
%S: The second (0-60; 60 may occur for leap seconds; earlier also 61 was allowed).
%t: Arbitrary whitespace.
%T: Equivalent to %H:%M:%S.
%U: The week number with Sunday the first day of the week (0-53).
%w: The weekday number (0-6) with Sunday = 0.
%W: The week number with Monday the first day of the week (0-53).
%x: The date, using the C locale's date format.
%X: The time, using the C locale's time format.
%y: The year within century (0-99). When a century is not otherwise specified, values in the range 69-99 refer to years in the twentieth century (1969-1999); values in the range 00-68 refer to years in the twenty-first century (2000-2068).
%Y: The year, including century (for example, 1991).

See also

localtime(), gmtime(), strftime()

Method tan: floattan(int|floatf)
Description: Returns the tangent value for f. f should be specified in radians.
See also: atan(), sin(), cos()

Method tanh: floattanh(int|floatf)
Description: Returns the hyperbolic tangent value for f.
See also: atanh(), sinh(), cosh()

Method this_object: objectthis_object(void|intlevel)
Description: Returns the object we are currently evaluating in.
Parameter level: level may 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.
Note: 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.

Method thread_local

Thread.Localthread_local()

Returns

Returns Thread.Local().

This is primarily intended as a convenience function and detection symbol for use by the master before the module system has been fully initiated.

See also

Thread.Local

Method throw

mixed|voidthrow(mixedvalue)

Description

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.

See also

catch

Method time

inttime()
inttime(int(1)one)
floattime(int(2..)t)

Description

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 last time value used by the pike process is returned again. It avoids a system call, and thus is 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 precisely than one second. It returns how many seconds have passed since t. The precision of this function varies from system to system.

See also

ctime(), localtime(), mktime(), gmtime(), System.gettimeofday(), gethrtime()

Method ualarm

intualarm(intuseconds)

Description

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

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.

Note

This function is only available on platforms that support signals.

See also

alarm(), signal(), call_out()

Method unicode_to_string

stringunicode_to_string(string(8bit)s, int(0..2)|voidbyteorder)

Description

Converts an UTF16 byte-stream into a string.

Parameter s

String to convert to UTF16.

Parameter byteorder

Default input byte-order. One of:

`0`	Network (aka big-endian) byte-order (default).
`1`	Little-endian byte-order.
`2`	Native byte-order.

Note that this argument is disregarded if s starts with a BOM.

See also

Charset.decoder(), string_to_unicode(), string_to_utf8(), utf8_to_string()

Method upper_case: stringupper_case(strings)
intupper_case(intc)
Description: Convert a string or character to upper case.
Returns: Returns a copy of the string s with all lower case characters converted to upper case, or the character c converted to upper case.
Note: Assumes the string or character to be coded according to ISO-10646 (aka Unicode). If they are not, Charset.decoder can do the initial conversion for you.
Note: Prior to Pike 7.5 this function only accepted strings.
See also: lower_case(), Charset.decoder

Method utf8_to_string

stringutf8_to_string(utf8_strings)
stringutf8_to_string(utf8_strings, intextended)

Description

Converts an UTF-8 byte-stream into a string.

Parameter s

String of UTF-8 encoded data to decode.

Parameter extended

Bitmask with extension options.

`1`	Accept and decode the extension used by `string_to_utf8()`.
`2`	Accept and decode UTF-8 encoded UTF-16 (ie accept and decode valid surrogates).

Note

Throws an error if the stream is not a legal UTF-8 byte-stream.

Note

In conformance with RFC 3629 and Unicode 3.1 and later, non-shortest forms are not decoded. An error is thrown instead.

See also

Charset.encoder(), string_to_unicode(), string_to_utf8(), unicode_to_string(), validate_utf8()

Method validate_utf8

boolvalidate_utf8(utf8_strings)
boolvalidate_utf8(utf8_strings, intextended)

Description

Checks whether a string is a valid UTF-8 byte-stream.

Parameter s

String of UTF-8 encoded data to validate.

Parameter extended

Bitmask with extension options.

`1`	Accept the extension used by `string_to_utf8()`, including lone UTF-16 surrogates.
`2`	Accept UTF-8 encoded UTF-16 (ie accept valid surrogate-pairs).

Returns

Returns 0 (zero) if the stream is not a legal UTF-8 byte-stream, and 1 if it is.

Note

In conformance with RFC 3629 and Unicode 3.1 and later, non-shortest forms are considered invalid.

See also

Charset.encoder(), string_to_unicode(), string_to_utf8(), unicode_to_string(), utf8_to_string()

Method werror: intwerror(stringfmt, mixed ... args)
Description: Writes a string on stderr. Works just like Stdio.File.write on Stdio.stderr.

Method write: intwrite(stringfmt, mixed ... args)
Description: Writes a string on stdout. Works just like Stdio.File.write on Stdio.stdout.

Method yield

mixedyield(mixed|voidval)

Description

Stop execution of the current restartable function for now, and return the value val.

Parameter val

Value to be returned from the restartable function.

May be omitted in functions returning void (including asynchronous functions). For asynchronous functions this means that Concurrent.Promise()->success() in the implicit Concurrent.Promise will not be called.

Returns

Evaluates to the first argument passed to the restartable function on restart, or if it has already been called, the value passed at that time.

Calling this special form is similar to the statement:

continue return val;

This syntax is however an expression and can thus be used to pass a value back.

Note

Use of this function is only valid in restartable functions.

Throws

The second argument to a restartable function may be a function that throws a value. That value will appear to have been thrown via yield().

See also

await(), Restartable functions

Enum bool

Description: Boolean datatype.

Constant false
Constant true: constantfalse
constanttrue

Class Codec

Description: An Encoder and a Decoder lumped into a single instance which can be used for both encoding and decoding.

Inherit Decoder: inherit Decoder : Decoder

Inherit Encoder: inherit Encoder : Encoder

Class CompilationHandler

Description

Objects used by the compiler to handle references to global symbols, modules, external files, etc.

There can be up to three compilation handlers active at the same time during a compilation. They are in order of precedence:

The error handler
This is the object passed to compile() as the second argument (if any). This object is returned by get_active_error_handler() during a compilation.
The compatibility handler
This is the object returned by master()->get_compilation_handler() (if any), which the compiler calls when it sees #pike-directives, or expressions using the version scope (eg 7.4::rusage). This object is returned by get_active_compilation_handler() during a compilation.
The master object.
This is returned by master() at any time.

Any of the objects may implement a subset of the CompilationHandler functions, and the first object that implements a function will be used. The error handler object can thus be used to block certain functionality (eg to restrict the number of available functions).

See also

master()->get_compilation_handler(), get_active_error_handler(), get_active_compilation_handler(), compile()

Method compile_error: voidcompile_error(stringfilename, intline, stringmsg)
Description: Called by compile() and cpp() when they encounter errors in the code they compile.
Parameter filename: File where the error was detected.
Parameter line: Line where the error was detected.
Parameter msg: Description of error.
See also: compile_warning().

Method compile_exception: voidcompile_exception(mixedexception)
Description: Called by compile() and cpp() if they trigger exceptions.

Method compile_warning: voidcompile_warning(stringfilename, intline, stringmsg)
Description: Called by compile() to report warnings.
Parameter filename: File which triggered the warning.
Parameter line: Line which triggered the warning.
Parameter msg: Warning message.
See also: compile_error()

Method get_default_module

mapping(string:mixed)|objectget_default_module()

Description

Returns the default module from which global symbols will be fetched.

Returns

Returns the default module, or 0 (zero).

If 0 (zero) is returned the compiler use the mapping returned by all_constants() as fallback.

See also

get_predefines()

Method get_predefines: mapping(string:mixed) get_predefines()
Description: Called by cpp() to get the set of global symbols.
Returns: Returns a mapping from symbol name to symbol value. Returns zero on failure.
See also: resolv(), get_default_module()

Method handle_import: mapping(string:mixed)|object|program|zerohandle_import(stringpath, stringfilename, CompilationHandlerhandler)
Description: Called by compile() and cpp() to handle import directives specifying specific paths.
Returns: Returns the resolved value, or UNDEFINED on failure.
See also: resolv()

Method handle_include

stringhandle_include(stringheader_file, stringcurrent_file, boolis_local_ref)

Description

Called by cpp() to resolv #include and #string directives.

Parameter header_file

File that was requested for inclusion.

Parameter current_file

File where the directive was found.

Parameter is_local_ref

Specifies reference method.

`0`	Directive was `#include <header_file>`.
`1`	Directive was `#include "header_file"`.

Returns

Returns the filename to pass to read_include() if found, and 0 (zero) on failure.

See also

read_include()

Method read_include: stringread_include(stringfilename)
Description: Called by cpp() to read included files.
Parameter filename: Filename as returned by handle_include().
Returns: Returns a string with the content of the header file on success, and 0 (zero) on failure.
See also: handle_include()

Method resolv: mixedresolv(stringsymbol, stringfilename, CompilationHandlerhandler)
Description: Called by compile() and cpp() to resolv module references.
Returns: Returns the resolved value, or UNDEFINED on failure.
See also: get_predefines()

Class CompilerEnvironment

Description

predef::CompilerEnvironment that supports handlers.

The compiler environment.

By inheriting this class and overloading the functions, it is possible to make a custom Pike compiler.

Note

Prior to Pike 7.8 this sort of customization has to be done either via custom master objects, or via CompilationHandlers.

See also

CompilationHandler, MasterObject, master(), replace_master()

Inherit OrigCompilerEnvironment: inherit predef::CompilerEnvironment : OrigCompilerEnvironment

Inherit Reporter: inherit Reporter : Reporter
Description: Implements the Reporter API.
See also: Reporter()->report(), Reporter()->SeverityLevel

Method compile

Description

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

This function essentially performs

program compile(mixed ... args){return PikeCompiler(@args)->compile();}

Note

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

See also

compile_string(), compile_file(), cpp(), master(), CompilationHandler

Method compile_exception: intcompile_exception(mixederr)

Method decode_charset: stringdecode_charset(stringdata, stringcharset)
Description: The default implementation calls the corresponding function in master() with the same arguments and returns its result.

Method format_exception: string|zeroformat_exception(mixederr)

Method get_compilation_handler

objectget_compilation_handler(intmajor, intminor)

Description

Get compatibility handler for Pike major.minor.

The default implementation calls the corresponding function in the master object.

Note

This function is typically called by PikeCompiler()->get_compilation_handler().

See also

MasterObject()->get_compilation_handler().

Method get_default_module

mapping(string:mixed)|objectget_default_module()

Description

Get the default module for the current compatibility level (ie typically the value returned by predef::all_constants()).

The default implementation calls the corresponding function in the master object.

Returns

`mapping(string:mixed)\|object`	Constant table to use.
`int(0)`	Use the builtin constant table.

Note

This function is typically called by Pike_compiler()->get_default_module().

See also

MasterObject()->get_default_module().

Method get_predefines

mapping(string:string|function(:void)|object) get_predefines()

Description

Returns a mapping containing the set of predefined macros. These are typically the macros defined via the -D option when starting Pike.

After _take_over_initial_predefines() has been called, it instead calls master()->get_predefines() and returns its result.

See also

cpp(), CompilationHandler->get_predefines(), _take_over_initial_predefines()

Method handle_import

programhandle_import(stringmodule, stringcurrent_file, object|voidhandler)

Description

Look up an import module.

The default implementation calls the corresponding function in the master object.

See also

MasterObject()->handle_import().

Method handle_include: stringhandle_include(stringheader_file, stringcurrent_file, boolis_local_ref)
Description: The default implementation calls the corresponding function in master() with the same arguments and returns its result.

Method handle_inherit

programhandle_inherit(stringinh, stringcurrent_file, object|voidhandler)

Description

Look up an inherit inh.

The default implementation calls the corresponding function in the master object.

See also

MasterObject()->handle_inherit().

Method read_include: stringread_include(stringfilename)
Description: The default implementation calls the corresponding function in master() with the same arguments and returns its result.

Method resolv

mixedresolv(stringidentifier, stringfilename, object|voidhandler, object|voidcompat_handler)

Description

Look up identifier in the current context.

The default implementation calls the corresponding function in the handlers (if any), falling back to the master object.

Returns

Returns the value of the identifier if found, and UNDEFINED if not.

Enum CompilerEnvironment.CppDefArgFlags

Description: These flags affect the behavior of macro argument expansion, and are used in the define()->parts array.

Constant CPP_DEF_ARG_MASK: constantint CompilerEnvironment.CPP_DEF_ARG_MASK
Description: Mask for converting a define()->parts entry into an argument number.

Constant CPP_DEF_ARG_NEED_COMMA: constantint CompilerEnvironment.CPP_DEF_ARG_NEED_COMMA
Description: Insert a comma before the argument if it is not the empty varargs argument.

Constant CPP_DEF_ARG_NOPOSTSPACE: constantint CompilerEnvironment.CPP_DEF_ARG_NOPOSTSPACE
Description: Inhibit insertion of whitespace after the argument expansion.

Constant CPP_DEF_ARG_NOPRESPACE: constantint CompilerEnvironment.CPP_DEF_ARG_NOPRESPACE
Description: Inhibit insertion of whitespace before the argument expansion.

Constant CPP_DEF_ARG_STRINGIFY: constantint CompilerEnvironment.CPP_DEF_ARG_STRINGIFY
Description: Convert the argument to a quoted string (including initial and ending '"').

Enum CompilerEnvironment.CppFlags

Description: Flags for CPP()->low_cpp() and directives.

Constant CPP_DO_IF: constantint CompilerEnvironment.CPP_DO_IF
Description: Enable cpp::defined() et al.

Constant CPP_END_AT_NEWLINE: constantint CompilerEnvironment.CPP_END_AT_NEWLINE
Description: Halt at end of line.

Constant CPP_EXPECT_ELSE: constantint CompilerEnvironment.CPP_EXPECT_ELSE
Description: Expect #else/#elif/#elseif.

Constant CPP_EXPECT_ENDIF: constantint CompilerEnvironment.CPP_EXPECT_ENDIF
Description: Expect #endif.

Constant CPP_NO_DIRECTIVES: constantint CompilerEnvironment.CPP_NO_DIRECTIVES
Description: Disable parsing of #-directives.

Constant CPP_NO_EXPAND: constantint CompilerEnvironment.CPP_NO_EXPAND
Description: Reserved.

Constant CPP_NO_OUTPUT: constantint CompilerEnvironment.CPP_NO_OUTPUT
Description: Inside false section of #if/#else.

Constant CPP_REALLY_NO_OUTPUT: constantint CompilerEnvironment.CPP_REALLY_NO_OUTPUT
Description: Entire preprocessor is in false section.

Enum CompilerEnvironment.CppMacroFlags

Description: Flags for define().

Constant CPP_MACRO_DISABLED: constantint CompilerEnvironment.CPP_MACRO_DISABLED
Description: Flag indicating that the macro is temorarily disabled. Don't expand. This flag is used during preprocessing of the result from expansion of the macro.

Constant CPP_MACRO_IN_USE: constantint CompilerEnvironment.CPP_MACRO_IN_USE
Description: In use. This flag is used during preprocessing of arguments to the macro.

Constant CPP_MACRO_KEEP_NL: constantint CompilerEnvironment.CPP_MACRO_KEEP_NL
Description: Keep newlines.

Constant CPP_MACRO_USER_FLAGS: constantint CompilerEnvironment.CPP_MACRO_USER_FLAGS
Description: Mask for valid user flags (ie CPP_MACRO_VARARGS or CPP_MACRO_KEEP_NL).

Constant CPP_MACRO_VARARGS: constantint CompilerEnvironment.CPP_MACRO_VARARGS
Description: Macro is a function-style macro that accepts more arguments than define()->num_args.

Class CompilerEnvironment.CPP

Description

The state for an instance of the preprocessor.

The default set of supported directives and macros, etc is documented in the cpp:: scope.

Custom directives may be added by inheriting this class and adding non-private functions string directive_XXX(CppFlags flags, string rest_of_line), or by adding the same to the directives mapping.

See also

predef::cpp(), cpp(), cpp::

Inherit this_program: inherit ::this_program : this_program

Variable handler
Variable compat_handler: CompilationHandler CompilerEnvironment.CPP.handler
CompilationHandler CompilerEnvironment.CPP.compat_handler

Variable directives: mapping(string:function(int(16bit), string:string|zero))|zero CompilerEnvironment.CPP.directives
Description: Mapping containing the set of active dynamic custom preprocessor directives.
Note: This mapping is only consulted if a corresponding directive_XXX symbol is not present (or is private) in this.

Method apply_handler: protectedmixedapply_handler(stringfun, mixed ... args)

Method change_cpp_compatibility

voidchange_cpp_compatibility(intmajor, intminor)

Description

Change the pike compatibility level for this preprocessor to the specified version of Pike.

Parameter major

Major version of Pike to attempt to be compatible with. Specifying a major version of -1 is a short hand for specifying __REAL_MAJOR__ and __REAL_MINOR__.

Parameter minor

Minor version of Pike to attempt to be compatible with.

This function is called by the preprocessor to set the compatibility level.

The default implementation performs some normalization, and then sets compat_major and compat_minor to their respective values (which in turn affects symbols such as __MAJOR__ and __MINOR__).

Method clear_macros

voidclear_macros()

Description

Clear the set of macros.

It is recomended to call this function when the CPP object is no longer to be used.

See also

define_macro()

Method compile_exception: intcompile_exception(mixederr)

Method cpp: stringcpp(stringdata, CppFlags|voidflags)
Description: Preprocess a string.
Returns: Returns the preprocessed result.
See also: low_cpp(), high_cpp()

Method cpp_error

voidcpp_error(sprintf_formatmsg, sprintf_args ... arguments)

Description

Convenience function for reporting a cpp error at the current position.

This function calls report() with the same arguments, but prefixed with suitable defaults.

See also

report()

Method create

Description

Initialize the preprocessor.

Parameter options

If the first argument is a mapping, no other arguments may follow. Instead, they have to be given as members of the mapping (if wanted). The following members are then recognized:

`"current_file" : string`	Name of the current file. It is used for generating #line directives and for locating include files.
`"charset" : int\|string`	Charset to use when processing `data`.
`"handler" : CompilationHandler`	Compilation handler.
`"compat_major" : int`	Sets the major pike version used for compat handling.
`"compat_minor" : int`	Sets the minor pike version used for compat handling.
`"picky_cpp" : int`	Generate more warnings.
`"keep_comments" : int`	This option keeps `cpp()` from removing comments. Useful in combination with the prefix feature below.
`"prefix" : string`	If a prefix is given, only prefixed directives will be processed. For example, if the prefix is `"foo"`, then `#foo_ifdef COND` and `foo___LINE__` would be processed, `#ifdef COND` and `__LINE__` would not.

Parameter current_file

If the current_file argument has not been specified, it will default to "-".

Parameter charset

Turn on automatic character set detection if 1, otherwise specifies the character set used by the input. Defaults to "ISO-10646".

See also

compile()

Method create

Description

Initialize the preprocessor.

Parameter options

If the first argument is a mapping, no other arguments may follow. Instead, they have to be given as members of the mapping (if wanted). The following members are then recognized:

`"current_file" : string`	Name of the current file. It is used for generating #line directives and for locating include files.
`"charset" : bool\|string`	Charset to use when processing `data`.
`"handler" : object`	Compilation handler.
`"compat_major" : int`	Sets the major pike version used for compat handling.
`"compat_minor" : int`	Sets the minor pike version used for compat handling.
`"picky_cpp" : int`	Generate more warnings.
`"keep_comments" : int`	This option keeps `cpp()` from removing comments. Useful in combination with the prefix feature below.
`"prefix" : string`	If a prefix is given, only prefixed directives will be processed. For example, if the prefix is `"foo"`, then `#foo_ifdef COND` and `foo___LINE__` would be processed, `#ifdef COND` and `__LINE__` would not.
`"predefines" : mapping(string:mixed)`	Mapping of predefined macros in addition to those returned by `CPP()->get_predefines()`.

Parameter current_file

If the current_file argument has not been specified, it will default to "-".

Parameter charset

Turn on automatic character set detection if 1, otherwise specifies the character set used by the input. Defaults to "ISO-10646".

See also

compile()

Method decode_charset: stringdecode_charset(stringdata, stringcharset)
Description: The default implementation is a proxy for the same function in the lexical parent class.

Method define_ansi_macros: voiddefine_ansi_macros()
Description: Adds some cpp macros defined by the ANSI-C standards, such as __FILE__, __LINE__, etc.
See also: define_macro(), define_pike_macros()

Method define_macro

Description

Define a cpp macro.

Parameter name

Name of macro to define. Ending the name with "()" changes the defaults for numargs and flags to 0 and 3 respectively.

Parameter value

Macro definition. Defaults to "1".

Parameter numargs

Number of required arguments to a function-style macro. -1 indicates not function-style. Defaults to -1.

Parameter flags

Bit-wise or of flags affecting the macro behavior:

`CPP_MACRO_VARARGS`	Function style macro with a variable number of arguments. Invalid if `numargs` is `-1`.
`CPP_MACRO_KEEP_NL`	Keep newlines emitted by the macro.

Defaults to 0.

See also

define_multiple_macros()

Method define_multiple_macros: voiddefine_multiple_macros(mapping(string:string|function(:void)|object|array(string|CppDefArgFlags))|voidpredefs)
Description: Define multiple macros in one operation.
Parameter predefs: Macros to define.
Note: The values predefs mapping may get updated by the function in order to improve performance of a second call.
See also: define_macro(), CompilationHandler()->get_predefines(), _take_over_initial_predefines()

Method define_pike_macros: voiddefine_pike_macros()
Description: Adds some pike-specific cpp macros, such as __DIR__, __VERSION__, __PIKE__, etc.
See also: define_macro(), define_ansi_macros()

Method defines: mapping(string:define) defines()
Description: Mapping containing the set of active macros.

Method drain: stringdrain()
Description: Return the preprocessor output so far, and empties the buffer.
Returns: Returns the content of the output buffer.
See also: low_cpp(), high_cpp()

Method format_exception

stringformat_exception(mixederr)

Description

Format an exception caught by cpp as a suitable cpp error message.

Parameter err

Caught value.

Returns

Returns one of:

`zero`	Generate a cpp error using the default format (ie call `master()->describe_error()`, and replace any newlines with spaces).
`string`	Cpp error message to `report()`. The empty string supresses the cpp error.

The default implementation just returns 0.

Method get_compilation_handler: objectget_compilation_handler(intmajor, intminor)

Method get_predefines

mapping(string:string|function(:void)|object|array(string|CppDefArgFlags)) get_predefines()

Description

Get the predefined macros for this preprocessor.

This function is called by init_pike_cpp() to retrieve the set of macros to define at initialization.

The default implementation returns the internal set of predefined macros unless _take_over_initial_predefines() has been called, in which case it instead calls the corresponding function in the master.

Note

This function does NOT return the set of currently defined macros.

See also

init_pike_cpp(), define_multiple_macros(), _take_over_initial_predefines(), defines

Method handle_import: mapping|object|programhandle_import(stringmodule)
Description: The default implementation is a proxy for the same function in the lexical parent class.

Method handle_include: stringhandle_include(stringheader_file, stringcurrent_file, boolis_local_ref)
Description: The default implementation is a proxy for the same function in the lexical parent class.

Method high_cpp: string|zerohigh_cpp(stringdata)
Description: Preprocess a string.
Returns: Returns the preprocessed result, unless there was a dependency failure in which case 0 (zero) is returned. If the function has failed, the result so far may be retrieved with drain().
Note: Clears the set of defined macros on completion.
Throws: Throws error on preprocessor failure.
See also: low_cpp(), cpp(), drain()

Method init_pike_cpp

voidinit_pike_cpp()

Description

Convenience function for initializing the preprocessor to Pike defaults.

The default implementation is essentially (disregarding error handling):

{string save_file = current_file;int save_line = current_line;
      current_file ="<built-in>";
      current_line = 0;
      define_ansi_macros();
      define_pike_macros();
      current_file ="<command-line>";
      define_multiple_macros(get_predefines());
      current_file = save_current_file;
      current_line = save_line;}

Method low_cpp

voidlow_cpp(stringdata, CppFlagsflags)

Description

Preprocess a string fragment.

The preocessed result is appended to the current output buffer.

Note

This is probably not the function you want.

See also

cpp(), high_cpp(), drain()

Method read_include: stringread_include(stringfilename)
Description: The default implementation is a proxy for the same function in the lexical parent class.

Method report

voidreport(SeverityLevelseverity, stringfilename, int(0..)linenumber, stringsubsystem, sprintf_formatmessage, sprintf_args ... extra_args)

Description

Report a diagnostic from the preprocessor.

Parameter severity

The severity of the diagnostic.

Parameter filename

Parameter linenumber

Location which triggered the diagnostic. linenumber0 (zero) indicates that it is not applicable (typically originating from command line arguments or similar).

Parameter subsystem

Typically "cpp".

Parameter message

String with the diagnostic message, with optional sprintf()-style formatting (if any extra_args).

Parameter extra_args

Extra arguments to sprintf().

The default implementation does the following:

If there's a handler which implements Reporter()->report(), call it with the same arguments.
Otherwise if there's a handler which implements compile_warning() or compile_error() that matches severity, call it with suitable arguments.
Otherwise if there's a compat handler, use it in the same manner as the handler.
Otherwise fall back to calling ::report() with the same arguments.

Note

In Pike 8.0 and earlier MasterObject()->report() was not called.

See also

Reporter()->report()

Method report

voidreport(SeverityLevelseverity, stringfilename, int(0..)linenumber, stringsubsystem, stringmessage, mixed ... extra_args)

Description

Report a diagnostic from the preprocessor.

Parameter severity

The severity of the diagnostic.

Parameter filename

Parameter linenumber

Location which triggered the diagnostic. linenumber0 (zero) indicates that it is not applicable (typically originating from command line arguments or similar).

Parameter subsystem

Always "cpp".

Parameter message

String with the diagnostic message, with optional sprintf()-style formatting (if any extra_args).

Parameter extra_args

Extra arguments to sprintf().

The default implementation just calls CompilerEnviroment::report() in the parent with the same arguments.

See also

Reporter()->report(), cpp_error()

Method resolv

mixedresolv(stringsym)

Description

Attempt to resolve a symbol.

The default implementation calls CompilerEnvironment()->resolv() in the parent object, with the remaining arguments taken from the current CPP context.

Returns

Returns the value of sym if found, and UNDEFINED if not.

Class CompilerEnvironment.PikeCompiler

Description

The Pike compiler.

An object of this class compiles a single string of Pike code.

Inherit this_program: inherit ::this_program : this_program

Variable handler
Variable compat_handler: CompilationHandler CompilerEnvironment.PikeCompiler.handler
CompilationHandler CompilerEnvironment.PikeCompiler.compat_handler

Variable current_file: string CompilerEnvironment.PikeCompiler.current_file
Description: The name of the file currently being compiled (during an active compilation).

Variable current_line: int CompilerEnvironment.PikeCompiler.current_line
Description: The current line number (during an active compilation).

Method apply_attribute_constant

typeapply_attribute_constant(stringattr, mixedvalue, typearg_type, voidcont_type, mappingstate)

Description

Handle constant arguments to attributed function argument types.

Parameter attr

Attribute that arg_type had.

Parameter value

Constant value sent as parameter.

Parameter arg_type

Declared type of the function argument.

Parameter cont_type

Continuation function type after the current argument.

Parameter state

Mapping intended to hold state during checking of multiple arguments.

This function is called when a function is called with the constant value value and it has been successfully matched against arg_type, and arg_type had the type attribute attr.

This function is typically used to perform specialized argument checking and to allow for a strengthening of the function type based on value.

The default implementation handles the following attributes:

: This marks the arguments to sprintf().
: These mark arguments that will be sent as the first argument to sprintf().
: This marks the return value for sprintf().
: These mark arguments that will be sent as the second argument to sscanf().
: This is the input for sscanf().

Returns

Returns a continuation type if it succeeded in strengthening the type.

Returns UNDEFINED otherwise (this is not an error indication).

See also

pop_type_attribute(), push_type_attribute()

Method apply_handler: protectedmixedapply_handler(stringfun, mixed ... args)

Method apply_type_attribute

boolapply_type_attribute(stringattribute, typea, mapping|voidstate)

Description

Type attribute handler.

Parameter attribute

Attribute that a had.

Parameter a

Continuation of the function being called or UNDEFINED indicating that there are no further arguments.

Parameter state

Mapping intended to hold state during checking of multiple arguments.

Called during type checking when there has been successfull partial evaluation of a function type that had the type attribute attribute before the evaluation.

The default implementation implements the attributes:

Returns

Returns 1 if the type check should be allowed (ie __attribute__(attribute, a)(b)) is valid, and 0 (zero) otherwise.

See also

pop_type_attribute(), push_type_attribute()

Method change_compiler_compatibility: voidchange_compiler_compatibility(intmajor, intminor)
Description: Change compiler to attempt to be compatible with Pike major.minor.

Method compile

programcompile()

Description

Compile the current source into a program.

This function compiles the current Pike source code into a clonable program.

See also

compile_string(), compile_file(), cpp(), master(), CompilationHandler, create()

Method create

Description

Create a PikeCompiler object for a source string.

This function takes a piece of Pike code as a string and initializes a compiler object accordingly.

Parameter source

Source code to compile.

Parameter handler

The optional argument handler is used to specify an alternative error handler. If it is not specified the current master object at compile time will be used.

Parameter major

Parameter minor

The optional arguments major and minor are used to tell the compiler to attempt to be compatible with Pike major.minor.

Parameter target

__empty_program() program to fill in. The virgin program returned by __empty_program() will be modified and returned by compile() on success.

Parameter placeholder

__null_program() placeholder object to fill in. The object will be modified into an instance of the resulting program on successfull compile. Note that lfun::create() in the program will be called without any arguments.

Note

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 no preprocessing is performed. To preprocess the program you can use compile_string() or call the preprocessor manually by calling cpp().

Note

Note that all references to target and placeholder should removed if compile() failes. On failure the placeholder object will be destructed.

See also

compile_string(), compile_file(), cpp(), master(), CompilationHandler

Method eval_type_attribute: typeeval_type_attribute(stringattribute, typet, mappingstate)

Method get_compilation_handler: objectget_compilation_handler(intmajor, intminor)
Description: Get compatibility handler for Pike major.minor.
Note: This function is called by change_compiler_compatibility().

Method get_default_module

mapping(string:mixed)|objectget_default_module()

Description

Get the default module for the current compatibility level (ie typically the value returned by predef::all_constants()).

The default implementation calls the corresponding function in the current handler, the current compatibility handler or in the parent CompilerEnvironment in that order.

Returns

`mapping(string:mixed)\|object`	Constant table to use.
`int(0)`	Use the builtin constant table.

Note

This function is called by change_compiler_compatibility().

Method handle_import: programhandle_import(stringmodule)
Description: Look up an import module.

Method handle_inherit: programhandle_inherit(stringinh)
Description: Look up an inherit inh in the current program.

Method index_type_attribute

boolindex_type_attribute(stringattribute, typea, typei)

Description

Type attribute handler.

Called during type checking when a value of the type a is indexed with a value of type i and a had the type attribute attribute before the comparison.

The default implementation implements the "deprecated" and "experimental" attributes.

Returns

Returns 1 if the type check should be allowed (ie __attribute__(attribute, a)[i]), and 0 (zero) otherwise.

See also

pop_type_attribute(), push_type_attribute()

Method pop_type_attribute

bool|typepop_type_attribute(stringattribute, typea, typeb, mapping|voidstate)

Description

Type attribute handler.

Called during type checking when a <= b and a had the type attribute attribute before the comparison.

The default implementation implements the "deprecated" and "experimental" attributes.

Returns

Returns one of:

`type`	An alternative type for `a` against which `b` will be matched again.
`int(1)`	Allow the check (ie `__attribute__(attribute, a) <= b`).
`int(0)`	Do not allow the check.

See also

push_type_attribute(), index_type_attribute()

Method push_type_attribute

bool|typepush_type_attribute(stringattribute, typea, typeb, mapping|voidstate)

Description

Type attribute handler.

Called during type checking when a <= b and b had the type attribute attribute before the comparison.

The default implementation implements the following attributes:

`"deprecated"`	Warns about use of deprecated functions and values.
`"experimental"`	Warns about use of experimental functions and values.
`"sprintf_args"`	Used for type checking of `sprintf()` arguments. They are passed along to `__handle_sprintf_format()`.
`"sprintf_char"`
`"sprintf_lfun"`
`"sprintf_string"`
`"utf8"`	Warns about passing non-UTF-8 string values to places that expect UTF-8 encoded strings.

Returns

Returns one of:

`type`	An alternative type for `b` against which `a` will be matched again.
`int(1)`	Allow the check (ie `a <= __attribute__(attribute, b)`).
`int(0)`	Do not allow the check.

See also

pop_type_attribute(), index_type_attribute(), utf8_string

Method report

voidreport(SeverityLevelseverity, stringfilename, intlinenumber, stringsubsystem, stringmessage, mixed ... extra_args)

Description

Report a diagnostic from the compiler.

The default implementation attempts to call the first corresponding function in the active handlers in priority order:

Call handler->report().
Call handler->compile_warning() or handler->compile_error() depending on severity.
Call compat->report().
Call compat->compile_warning() or compat->compile_error() depending on severity.
Fallback: Call CompilerEnvironment()->report() in the parent object.

The arguments will be as follows:

report()

The report() function will be called with the same arguments as this function.

compile_warning()/compile_error()

Depending on the severity either compile_warning() or compile_error() will be called.

They will be called with the filename, linenumber and formatted message as arguments.

Note that these will not be called for the NOTICE severity, and that compile_error() will be used for both ERROR and FATAL.

Note

In Pike 7.8 and earlier the report() function was not called in the handlers.

See also

CompilerEnvironment()->report()

Method resolv

mixedresolv(stringidentifier)

Description

Resolve the symbol identifier.

The default implementation calls CompilerEnvironment()->resolv() in the parent object, with the remaining arguments taken from the current PikeCompiler context.

Returns

Returns the value of sym if found, and UNDEFINED if not.

Method suppress_deprecation_warnings: int(0..2)suppress_deprecation_warnings()
Description: Allows to query whether (during an active compilation) deprecation and experimental warnings are supposed to be suppressed.
Returns: 2 if deprecation and experimental warnings should be suppressed, 1 if experimental warnings should be suppressed, 0 otherwise.

Class CompilerEnvironment.PikeCompiler.CompilerState

Description: Keeps the state of a single program/class during compilation.
Note: Not in use yet!

Class CompilerEnvironment.define

Variable flags: CppMacroFlags CompilerEnvironment.define.flags
Note: Read only

Variable name: string CompilerEnvironment.define.name
Description: Macro name.

Variable num_args: int(-1..) CompilerEnvironment.define.num_args
Note: Read only

Variable parts: array(string|CppDefArgFlags|function(mixed ... :string))|zero CompilerEnvironment.define.parts
Description: Macro expansion rule.

Method `(): string res = CompilerEnvironment.define()()
Description: Apply the macro with the specified arguments.
Parameter arguments: Array of arguments to the macro. Zero if no parenthesis.
Parameter context: CPP context we are evaluating in.
Returns: Returns the expansion of the macro on success, and 0 (zero) on failure (typically due to invalid arguments).

Method create: CompilerEnvironment.defineCompilerEnvironment.define(stringname, intnum_args, array(string|CppDefArgFlags|function(mixed|void ... :string)) parts)

Class CompilerEnvironment.lock

Description

This class acts as a lock against other threads accessing the compiler.

The lock is released when the object is destructed.

Class Decoder

Description: Codec used by decode_value() to decode objects, functions and programs which have been encoded by Encoder.nameof in the corresponding Encoder object.

Method __register_new_program: object__register_new_program(programp)
Description: Called 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: 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.

Method functionof

function(:void) functionof(stringdata)

Description

Decode function encoded in data.

This function is called by decode_value() when it encounters encoded functions.

Parameter data

Encoding of some function as returned by Encoder.nameof().

Returns

Returns the decoded function.

See also

objectof(), programof()

Method objectof

objectobjectof(stringdata)

Description

Decode object encoded in data.

This function is called by decode_value() when it encounters encoded objects.

Parameter data

Encoding of some object as returned by Encoder.nameof().

Returns

Returns the decoded object.

See also

functionof(), programof()

Method programof

programprogramof(stringdata)

Description

Decode program encoded in data.

This function is called by decode_value() when it encounters encoded programs.

Parameter data

Encoding of some program as returned by Encoder.nameof().

Returns

Returns the decoded program.

See also

functionof(), objectof()

Class Encoder

Description: Codec used by encode_value() to encode objects, functions and programs. Its purpose is to look up some kind of identifier for them, so they can be mapped back to the corresponding instance by decode_value(), rather than creating a new copy.

Method nameof

mixednameof(object|function(:void)|programx)

Description

Called by encode_value() to encode objects, functions and programs.

Returns

Returns something encodable on success, typically a string. The returned value will be passed to the corresponding objectof(), functionof() or programof() by decode_value().

If it returns UNDEFINED then encode_value starts to encode the thing recursively, so that decode_value later will rebuild a copy.

Note

encode_value() has fallbacks for some classes of objects, functions and programs.

See also

Decoder.objectof(), Decoder.functionof(), Decoder.objectof()

Class Iterator

Description

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; _iterator_index and _iterator_value will just return UNDEFINED then. 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 currently not supported.

See also

predef::get_iterator, lfun::_get_iterator, Array.Iterator, Mapping.Iterator, Multiset.Iterator, String.Iterator, String.SplitIterator, 8.0::Iterator.

Method _iterator_index

optionalprotectedmixed_iterator_index()

Description

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

See also

_iterator_value(), lfun::_iterator_index(), iterator_index()

Method _iterator_next: protectedmixed_iterator_next()
Description: This function advances the iterator one step.
Note: This is the only function that is required in the Pike 9.0 and later iterator API. Presence of this function indicates that the iterator implements the Pike 9.0 API.
Returns: Returns UNDEFINED if there are no more values in the set of elements. If [_iterator_value()] is implemented, 0 (zero) may also be returned if there are no more values. Any other value may be returned if it succeeded in advancing to a new element. The returned value is used as the result for _iterator_index() and _iterator_value() if they are not implemented.
See also: _iterator_prev(), lfun::_iterator_next(), iterator_next(), _iterator_index(), _iterator_value()

Method _iterator_prev: optionalprotectedmixed_iterator_prev()
Description: This function advances the iterator one step backwards.
Returns: Returns UNDEFINED if there are no more values in the set of elements. It may return any other value if it succeeded in advancing to the previous element. The returned value may be used as the result for _iterator_index() and _iterator_value() if they are not implemented.
See also: _iterator_next(), lfun::_iterator_prev(), iterator_prev(), _iterator_index(), _iterator_value()

Method _iterator_value: optionalprotectedmixed_iterator_value()
Description: Returns the current value, or UNDEFINED if the iterator doesn't point to any item.
See also: _iterator_index(), lfun::_iterator_value(), iterator_value()

Method _random: voidrandom(Iteratorarg)
Description: If this function is defined then it sets the iterator to point to before 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.
See also: random()

Method _sizeof: intsizeof(Iteratorarg)
Description: 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.

Method `+

Iterator res = Iterator() + steps

Description

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.

See also

_iterator_next, `-

Method `-: Iterator res = Iterator() - steps
Description: Returns a clone of this iterator which is backed up the specified number of steps. The amount may be negative to move forward.
See also: _iterator_next, `+,

Method create

IteratorIterator(void|mixeddata)

Description

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 before the first item in the data set, if there is any.

The iterator does not need to support being reused, so this function is typically declared protected.

Note

In the iterator API in Pike 8.0 and earlier the iterators initially pointed to the first element.

See also

CompatIterator

Method first: optionalboolfirst()
Description: If this function is defined then it resets the iterator to point to before the first item.
Returns: Returns zero if there are no items at all in the data set, one otherwise.
Note: 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.

Method set_index: optionalvoidset_index(zeroindex)
Description: If this function is defined it should set the iterator at the specified index.
Note: It should be possible to set the index at the end of the iterator.

Class Iterator.CompatIterator

Description: Wrapper for iterators implementing the Pike 8.0 and earlier iterator API (8.0::Iterator). Used transparently by predef::get_iterator() to provide an iterator suitable for foreach().
Note: This class provides only those functions that are required by the iterator API. It does not proxy any other functions.
See also: get_iterator(), 8.0::Iterator

Inherit Iterator: inherit Iterator : Iterator

Method create: Iterator.CompatIteratorIterator.CompatIterator(Iteratorold_style_iterator)

Class MasterObject

Description: Master control program for Pike.
See also: predef::master(), predef::replace_master()

Inherit Codec: inherit Codec : Codec

Inherit CompatResolver: inherit CompatResolver : CompatResolver

Inherit CompilationHandler: inherit CompilationHandler : CompilationHandler
Description: The master object acts as fallback compilation handler for compile() and cpp().

Inherit Pike_9_0_master

protected inherit Pike_9_0_master : Pike_9_0_master

Description

Namespaces for compat masters.

This inherit is used to provide compatibility namespaces for get_compat_master().

See also

get_compat_master()

Inherit __master: inherit Builtin.__master : __master

Constant bt_max_string_len: constantint MasterObject.bt_max_string_len
Description: 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.

Constant out_of_date_warning: constantint MasterObject.out_of_date_warning
Description: Should Pike complain about out of date compiled files. 1 means yes and 0 means no. Controlled by the OUT_OF_DATE_WARNING define.

Variable Decoder: program MasterObject.Decoder
Description: This program in the master is cloned and used as codec by decode_value if it wasn't given any codec. An instance is only created on-demand the first time decode_value encounters something for which it needs a codec, i.e. the result of a call to Pike.Encoder.nameof.
See also: Decoder, Pike.Decoder

Variable Encoder: program MasterObject.Encoder
Description: This program in the master is cloned and used as codec by encode_value if it wasn't given any codec. An instance is only created on-demand the first time encode_value encounters something for which it needs a codec, i.e. an object, program, or function.
See also: Encoder, Pike.Encoder

Variable _pike_file_name
Variable _master_file_name: string MasterObject._pike_file_name
string MasterObject._master_file_name
Description: These are useful if you want to start other Pike processes with the same options as this one was started with.

Variable cflags: string MasterObject.cflags
Description: Flags suitable for use when compiling Pike C modules

Variable compat_major

int MasterObject.compat_major

Description

Major pike version to emulate.

This is typically set via the option "-V".

See also

compat_minor

Variable compat_minor

int MasterObject.compat_minor

Description

Minor pike version to emulate.

This is typically set via the option "-V".

See also

compat_major

Variable currentversion: Version MasterObject.currentversion
Description: Version information about the current Pike version.

Variable doc_prefix: string MasterObject.doc_prefix
Description: Prefix for autodoc files.

Variable programs
Variable documentation
Variable source_cache

mapping(string:program|NoValue) MasterObject.programs
mapping(program:object) MasterObject.documentation
mapping(program:string) MasterObject.source_cache

Description

Mapping containing the cache of currently compiled files.

This mapping currently has the following structure:

filename : program

The filename path separator is / on both NT and UNIX.

Note

Special cases: The current master program is available under the name "/master", and the program containing the main function under "/main".

Variable include_prefix: string MasterObject.include_prefix
Description: Prefix for Pike-related C header files.

Variable is_pike_master: int MasterObject.is_pike_master
Description: This integer variable should exist in any object that aspires to be the master. It gets set to 1 when the master is installed, and is therefore set in any object that is or has been the master. That makes the Encoder class encode references to the master and all ex-masters as references to the current master object.

Variable ldflags: string MasterObject.ldflags
Description: Flags suitable for use when linking Pike C modules

Variable no_precompile: int MasterObject.no_precompile
Description: Turn off loading of precompiled modules.

Variable show_if_constant_errors

int MasterObject.show_if_constant_errors

Description

Show compilation warnings from compilation of cpp()#if constant() expressions.

This is typically set via the option "--picky-cpp".

Variable want_warnings: int MasterObject.want_warnings
Description: If not zero compilation warnings will be written out on stderr.

Method _main: void_main(array(string(8bit)) orig_argv)
Description: 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.

Method add_filesystem_handler

Filesystem.Base|zeroadd_filesystem_handler(stringmountpoint, Filesystem.Base|zerofilesystem)

Description

Mount a filesystem handler to be used by the resolver. On its own does nothing, but may be used with add_module_path() and friends to enable modules to be loaded from Filesystem objects.

Parameter mountpoint

The location in the filesystem to mount the handler

Parameter filesystem

A filesystem object that will handle requests for the given mountpoint.

Example

master()->add_filesystem_handler("/foo/bar.zip",Filesystem.Zip("/foo/bar.zip"));
    master()->add_module_path("/foo/bar.zip/lib");

See also

find_handler_for_path()

Method asyncp: boolasyncp()
Description: Returns 1 if we're in async-mode, e.g. if the main method has returned a negative number.

Method backend_thread: objectbackend_thread()
Description: 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.

Method cast_to_object: objectcast_to_object(stringoname, stringcurrent_file, CompilationHandler|voidcurrent_handler)
Description: 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.

Method cast_to_object: objectcast_to_object(stringstr, string|voidcurrent_file)
Description: Called by the Pike runtime to cast strings to objects.
Parameter str: String to cast to object.
Parameter current_file: Filename of the file that attempts to perform the cast.
Returns: Returns the resulting object.
See also: cast_to_program()

Method cast_to_program: programcast_to_program(stringpname, stringcurrent_file, CompilationHandler|voidhandler)
Description: 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.

Method cast_to_program: programcast_to_program(stringstr, string|voidcurrent_file)
Description: Called by the Pike runtime to cast strings to programs.
Parameter str: String to cast to object.
Parameter current_file: Filename of the file that attempts to perform the cast.
Returns: Returns the resulting program.
See also: cast_to_object()

Method compile_error: voidcompile_error(stringfile, intline, stringerr)
Description: 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.
See also: compile_warning(), compile_exception(), get_inhibit_compile_errors(), set_inhibit_compile_errors(),

Method compile_exception: intcompile_exception(array|objecttrace)
Description: This function is called when an exception is caught during compilation. Its message is also reported to compile_error if this function returns zero.
See also: compile_error(), compile_warning(), get_inhibit_compile_errors(), set_inhibit_compile_errors(),

Method compile_warning: voidcompile_warning(stringfile, intline, stringerr)
Description: 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.
See also: compile_error(), compile_exception(), get_inhibit_compile_errors(), set_inhibit_compile_errors(),

Method decode_charset: stringdecode_charset(stringdata, stringcharset)
Description: This function is called by cpp() when it wants to do character code conversion.

Method decode_charset

stringdecode_charset(stringraw, stringcharset)

Description

Convert raw from encoding charset to UNICODE.

This function is called by cpp() when it encounters #charset directives.

Parameter raw

String to convert.

Parameter charset

Name of encoding that raw uses.

Returns

raw decoded to UNICODE, or 0 (zero) if the decoding failed.

See also

Charset

Method describe_backtrace

stringdescribe_backtrace(mixedexception)

Description

Called by various routines to format a readable description of an exception.

Parameter exception

Something that was thrown. Usually an Error.Generic object, or an array with the following content:

Array
`stringmsg`	Error message.
`array(backtrace_frame\|array(mixed)) backtrace`	Backtrace to the point where the exception occurred.

Returns

Returns a string describing the exeception.

Note

Usually added by the initialization code the global name space with add_constant().

See also

predef::describe_backtrace()

Method describe_function: string|zerodescribe_function(function(:void) f)
Description: Function called by describe_backtrace() to describe functions in the backtrace.

Method describe_module: stringdescribe_module(object|programmod, array(object)|voidret_obj)
Description: Describe the path to the module mod.
Parameter mod: If mod is a program, attempt to describe the path to a clone of mod.
Parameter ret_obj: If an instance of mod is found, it will be returned by changing element 0 of ret_obj.
Returns: The a description of the path.
Note: The returned description will end with a proper indexing method currently either "." or "->".

Method describe_object: string|zerodescribe_object(objecto)
Description: Function called by sprintf("%O") for objects that don't have an lfun::_sprintf(), or have one that returns UNDEFINED.

Method describe_program: string|zerodescribe_program(program|function(:void) p)
Description: Function called by sprintf("%O") for programs.

Method enable_source_cache: voidenable_source_cache()
Description: Enable caching of sources from compile_string()

Method fc_reverse_lookup: stringfc_reverse_lookup(objectobj)
Description: Returns the path for obj in fc, if it got any.

Method find_handler_for_path: string|zerofind_handler_for_path(stringfile)
Description: Return the mountpoint for the filesystem handler handling the file (if any).
See also: add_filesystem_handler()

Method get_compat_master

objectget_compat_master(intmajor, intminor)

Description

Return a master object compatible with the specified version of Pike.

This function is used to implement the various compatibility versions of master().

See also

get_compilation_handler(), master()

Method get_compilation_handler

CompilationHandlerget_compilation_handler(intmajor, intminor)

Description

Get compilation handler for simulation of Pike vmajor.minor.

This function is called by cpp() when it encounters #pike directives.

Parameter major

Major version.

Parameter minor

Minor version.

Returns

Returns a compilation handler for Pike >= major.minor.

Method get_inhibit_compile_errors

bool|CompilationHandler|function(string, int, string:void) get_inhibit_compile_errors()

Description

Get the current compile error, warning and exception behaviour.

See set_inhibit_compile_errors() for details.

See also

set_inhibit_compile_errors()

Method get_precompiled_mtime: intget_precompiled_mtime(stringid)
Description: Given an identifier returned by query_precompiled_names, returns the mtime of the precompiled entry. Returns -1 if there is no entry.

Method handle_attribute

optionalboolhandle_attribute(mixedvalue, stringattribute)

Description

This function is called in runtime check_types mode (-rt), when encountering a soft cast to an attributed type.

Parameter value

Value that is about to receive the attribute.

Parameter attribute

Type attribute to validate.

Returns

Returns one of:

`1`	If the attribute is valid for the value.
`0`	If the attribute is not valid for the value.
`UNDEFINED`	If the attribute is unsupported.

The default master implements validation of the "utf8" attribute.

Method handle_error: voidhandle_error(mixedexception)
Description: Called by the Pike runtime if an exception isn't caught.
Parameter exception: Value that was throw()'n.
See also: describe_backtrace()

Method handle_error: voidhandle_error(array|objecttrace)
Description: This function is called when an error occurs that is not caught with catch().

Method handle_inherit: programhandle_inherit(stringpname, stringcurrent_file, CompilationHandler|voidhandler)
Description: 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.

Method master_read_file

string|zeromaster_read_file(stringfile)

Description

Read a file from the master filesystem.

The master filesystem defaults to the system filesystem, but additional mountpoints may be added via add_filesystem_handler().

All file I/O performed by the MasterObject is performed via this function and its related functions.

See also

add_filesystem_handler(), find_handler_for_path(), master_get_dir(), master_file_stat()

Method module_defined: array(string) module_defined(object|programmod)
Description: Find the files in which mod is defined, as they may be hidden away in joinnodes and dirnodes
Parameter mod: The module we are looking for.
Returns: An array of strings with filenames. (one for each file in a joinnode, or just one otherwise)

Method objects_reverse_lookup: programobjects_reverse_lookup(objectobj)
Description: Returns the program for obj, if known to the master.

Method program_path_to_name

stringprogram_path_to_name(stringpath, string|voidmodule_prefix, string|voidmodule_suffix, string|voidobject_suffix)

Description

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

Method programs_reverse_lookup: stringprograms_reverse_lookup(programprog)
Description: Returns the path for prog in programs, if it got any.

Method query_precompiled_names: array(string) query_precompiled_names(stringfname)
Description: Returns identifiers (e.g. file names) of potentially precompiled files in priority order.

Method read_precompiled: stringread_precompiled(stringid)
Description: Given an identifier returned by query_precompiled_names, returns the precompiled entry. Can assume the entry exists.

Method runtime_warning

voidruntime_warning(stringsubsystem, stringmsg, mixed|voiddata)

Description

Called by the Pike runtime to warn about data inconsistencies.

Parameter subsystem

Runtime subsystem where the warning was generated. Currently the following subsystems may call this function:

`"gc"`	The garbage collector.
`"runtime"`	The runtime itself.

Parameter msg

Warning message.

Parameter data

Optional data that further describes the warning specified by msg.

Currently the following subsystems and messages are defined:

`subsystem`	`message`	`data`
`"gc"`	`"bad_cycle"`	`arraycycle`
A cycle where the destruction order isn't deterministic was detected by the garbage collector. `cycle` is an array of the elements in the cycle.
`"runtime"`	`"unsupported_compat"`	`Versionrequested_version`
Compatibility with a version older than the oldest supported version was requested. `requested_version` is the requested version.

Method runtime_warning: voidruntime_warning(stringwhere, stringwhat, mixed ... args)
Description: 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.

Method set_inhibit_compile_errors

voidset_inhibit_compile_errors(bool|CompilationHandler|function(string, int, string:void) behaviour)

Description

Set the compile error, warning and exception behaviour.

Parameter behaviour

The desired behaviour. One of:

`int(0)`	Output compilation errors and warnings to `stderr`. This is the default behaviour.
`int(1)`	Inhibit output of compilator diagnostics.
`function(string, int, string:void)`	Function to call for compilation errors. Compilation warnings and exceptions are inhibited. The function will be called with the same arguments as those passed to `compile_error()`.
`CompilationHandler`	Compilation handler to use for diagnostics.

Note

Note that the behaviour is thread local, and is not copied to new threads when they are created.

See also

get_inhibit_compile_errors()

Method show_doc: objectshow_doc(program|object|function(:void) obj)
Description: Show documentation for the item obj
Parameter obj: The object for which the documentation should be shown
Returns: an AutoDoc object

Method thread_quanta_exceeded

voidthread_quanta_exceeded(Thread.Threadthread, intns)

Description

Function called when a thread has exceeded the thread quanta.

Parameter thread

Thread that exceeded the thread quanta.

Parameter ns

Number of nanoseconds that the thread executed before allowing other threads to run.

The default master prints a diagnostic and the thread backtrace to Stdio.stderr.

Note

This function runs in a signal handler context, and should thus avoid handling of mutexes, etc.

See also

get_thread_quanta(), set_thread_quanta()

Method unregister

voidunregister(programp)

Description

Unregister a program that was only partially compiled.

Called by compile() to clean up references to partially compiled programs.

Parameter p

Partially compiled program that should no longer be referenced.

FIXME

Shouldn't this function be in the compilation handler?

Method zap_all_caches: voidzap_all_caches()
Description: Called by the runtime in clean up on exit mode in order to get a reasonable destruction order.

Class MasterObject.Codec

Description: Encoder and Decoder rolled into one. This is for mainly compatibility; there's typically no use combining encoding and decoding into the same object.

Inherit Decoder: inherit Decoder : Decoder

Inherit Encoder: inherit Encoder : Encoder

Method create: MasterObject.CodecMasterObject.Codec(void|mixedencoded)
Description: The optional argument is the thing to encode; it's passed on to Encoder.

Class MasterObject.CompatResolver

Description: Resolver of symbols not located in the program being compiled.

Variable fallback_resolver

CompatResolver MasterObject.CompatResolver.fallback_resolver

Description

If we fail to resolv, try the fallback.

Typical configuration:

0.6->7.0->7.2-> ... ->master

Variable handler_root_modules: mapping(CompilationHandler:joinnode) MasterObject.CompatResolver.handler_root_modules
Description: Lookup from handler module to corresponding root_module.

Variable pike_include_path: array(string) MasterObject.CompatResolver.pike_include_path
Description: The complete include search path

Variable pike_module_path: array(string) MasterObject.CompatResolver.pike_module_path
Description: The complete module search path

Variable pike_program_path: array(string) MasterObject.CompatResolver.pike_program_path
Description: The complete program search path

Variable root_module: joinnode MasterObject.CompatResolver.root_module
Description: Join node of the root modules for this resolver.

Variable system_module_path: array(string) MasterObject.CompatResolver.system_module_path
Description: The pike system module path, not including any set by the user.

Method add_include_path

voidadd_include_path(stringtmp)

Description

Add a directory to search for include files.

This is the same as the command line option -I.

Note

Note that the added directory will only be searched when using < > to quote the included file.

See also

remove_include_path()

Method add_module_path

voidadd_module_path(stringpath, string|voidsubpath)

Description

Add a directory to search for modules.

This is the same as the command line option -M.

See also

remove_module_path()

Parameter path

Parameter subpath

if path is a ZIP archive, this argument will determine the path within the archive to be searched.

Method add_predefine: voidadd_predefine(stringname, mixedvalue)
Description: Add a define (without arguments) which will be implicitly defined in cpp calls.

Method add_program_path

voidadd_program_path(stringtmp)

Description

Add a directory to search for programs.

This is the same as the command line option -P.

See also

remove_program_path()

Method create

MasterObject.CompatResolverMasterObject.CompatResolver(mixedversion, CompatResolver|voidfallback_resolver)

Description

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.

Method get_default_module

mappingget_default_module()

Description

Return the default module for the CompatResolver.

This is the mapping that corresponds to the predef:: name space for the compatibility level, and is the value returned by all_constants() for the same.

Method get_predefines: mappingget_predefines()
Description: Returns a mapping with the current predefines.

Method handle_include: string|zerohandle_include(stringf, stringcurrent_file, intlocal_include)
Description: 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.
Returns: Returns a path suitable for read_include() if the file was found and 0 if it was not found.
See also: read_include()

Method instantiate_static_modules: protectedmapping(string:mixed) instantiate_static_modules(object|mappingstatic_modules)
Description: Instantiate static modules in the same way that dynamic modules are instantiated.

Method read_include: stringread_include(stringf)
Description: Read the file specified by handle_include().
See also: handle_include()

Method remove_include_path

voidremove_include_path(stringtmp)

Description

Remove a directory to search for include files.

This function performs the reverse operation of add_include_path().

See also

add_include_path()

Method remove_module_path

voidremove_module_path(stringtmp)

Description

Remove a directory to search for modules.

This function performs the reverse operation of add_module_path().

See also

add_module_path()

Method remove_predefine: voidremove_predefine(stringname)
Description: Remove a define from the set that are implicitly defined in cpp calls.

Method remove_program_path

voidremove_program_path(stringtmp)

Description

Remove a directory to search for programs.

This function performs the reverse operation of add_program_path().

See also

add_program_path()

Method resolv: mixedresolv(stringidentifier, string|voidcurrent_file, CompilationHandler|voidcurrent_handler, CompilationHandler|voidcurrent_compat_handler)
Description: Resolve the identifier expression.
Returns: Returns the value of the identifier if it exists, and UNDEFINED otherwise.

Method resolv_base: mixedresolv_base(stringidentifier, string|voidcurrent_file, CompilationHandler|voidcurrent_handler, CompilationHandler|voidcurrent_compat_handler)
Description: Look up identifier in the root module.

Method resolv_or_error: mixedresolv_or_error(stringidentifier, string|voidcurrent_file, void|CompilationHandlercurrent_handler)
Description: Same as resolv, but throws an error instead of returning UNDEFINED if the resolv failed.

Class MasterObject.Decoder

Description

Codec for use with decode_value. This is the decoder corresponding to Encoder. See that one for more details.

Parameter fname

Name of file being decoded.

Parameter placeholder

Make a singleton object of the program being decoded. One of:

`void\|zero`	Do not make an object.
`object`	Object to alter into the singleton. MUST be a clone of `__null_program()`.
`__deprecated__(int(1))`	Old API: Generate a singleton object.

Parameter handler

Handler object to use.

Variable fname
Variable placeholder
Variable handler: void|string MasterObject.Decoder.fname
void|__deprecated__(int)|object MasterObject.Decoder.placeholder
void|CompilationHandler MasterObject.Decoder.handler

Method __create__: protectedlocalvoid__create__(void|stringfname, void|__deprecated__(int)|objectplaceholder, void|CompilationHandlerhandler)

Method create: MasterObject.DecoderMasterObject.Decoder(void|stringfname, void|__deprecated__(int)|objectplaceholder, void|CompilationHandlerhandler)

Method decode_object

array(mixed)|zerodecode_object(objecto, mixeddata)

Description

Restore the state of an encoded object.

Parameter o

Object to modify.

Parameter data

State information from Encoder()->encode_object().

The default implementation calls o->_decode(data) if the object has an _decode(), otherwise if data is an array, returns it to indicate that lfun::create() should be called.

Note

This function is called beforelfun::create() in the object has been called, but after lfun::__INIT() has been called.

Returns

Returns an array to indicate to the caller that lfun::create() should be called with the elements of the array as arguments.

Returns 0 (zero) to inhibit calling of lfun::create().

See also

Encoder()->encode_object()

Class MasterObject.Describer

Description: Class used by describe_backtrace() to describe values in backtraces.

Inherit DestructImmediate: inherit _static_modules.Builtin.DestructImmediate : DestructImmediate

Class MasterObject.Encoder

Description

Codec for use with encode_value. It understands all the standard references to builtin functions, pike modules, and the main program script.

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.

Method create: MasterObject.EncoderMasterObject.Encoder(void|mixedencoded)
Description: 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.

Method nameof: string|arraynameof(mixedwhat, void|array(object) module_object)
Description: 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.

Class MasterObject.Pike_7_8_master

Description

Pike 7.8 master compatibility interface.

Most of the interface is implemented via mixin, or overloading by more recent masters.

This interface is used for compatibility with Pike 7.8.

Deprecated

Replaced by predef::MasterObject.

See also

get_compat_master(), master(), predef::MasterObject

Class MasterObject.Pike_8_0_master

Description

Pike 8.0 master compatibility interface.

Most of the interface is implemented via mixin, or overloading by more recent masters.

This interface is used for compatibility with Pike 8.0.

Deprecated

Replaced by predef::MasterObject.

See also

get_compat_master(), master(), predef::MasterObject

Inherit Pike_7_8_master: inherit Pike_7_8_master : Pike_7_8_master

Class MasterObject.Pike_9_0_master

Description

Pike 9.0 master compatibility interface.

Most of the interface is implemented via mixin, or overloading by more recent masters.

This interface is used for compatibility with Pike 9.0.

Deprecated

Replaced by predef::MasterObject.

See also

get_compat_master(), master(), predef::MasterObject

Inherit Pike_8_0_master: inherit Pike_8_0_master : Pike_8_0_master

Class MasterObject.Version

Description: Contains version information about a Pike version.

Variable major
Variable minor: int MasterObject.Version.major
int MasterObject.Version.minor
Description: The major and minor parts of the version.

Method `<
Method `>
Method `==
Method __hash: int res = MasterObject.Version() < v
int res = MasterObject.Version() > v
int res = MasterObject.Version() == v
inthash_value(MasterObject.Versionarg)
Description: Methods define so that version objects can be compared and ordered.

Method cast: (int)MasterObject.Version() (float)MasterObject.Version() (string)MasterObject.Version() (array)MasterObject.Version() (mapping)MasterObject.Version() (multiset)MasterObject.Version()
Description: The version object can be casted into a string.

Method create: MasterObject.VersionMasterObject.Version(intmajor, intminor)
Description: Set the version in the object.

Class MasterObject.dirnode

Description: Module node representing a single directory.
See also: joinnode

Variable dirname
Variable compilation_handler
Variable name: string MasterObject.dirnode.dirname
CompilationHandler|void MasterObject.dirnode.compilation_handler
string|void MasterObject.dirnode.name

Method __create__: protectedlocalvoid__create__(stringdirname, CompilationHandler|voidcompilation_handler, string|voidname)

Class MasterObject.joinnode

Description: Module node holding possibly multiple directories, and optionally falling back to another level.
See also: dirnode

Variable joined_modules
Variable compilation_handler
Variable fallback_module
Variable name: array(object|mapping) MasterObject.joinnode.joined_modules
CompilationHandler|void MasterObject.joinnode.compilation_handler
joinnode|mapping(mixed:int(0))|void MasterObject.joinnode.fallback_module
string|void MasterObject.joinnode.name

Method __create__: protectedlocalvoid__create__(array(object|mapping) joined_modules, CompilationHandler|voidcompilation_handler, joinnode|mapping(mixed:int(0))|voidfallback_module, string|voidname)

Class RandomInterface

Method random

arrayrandom(mappingm)

Description

Returns a random index-value pair from the mapping.

Array
`mixed0`	The index of the mapping entry.
`mixed1`	The value f the mapping entry.

Throws

Throws an exception if the mapping is empty.

Method random: floatrandom(floatmax)
Description: This function returns a random number in the range 0 .. max-ɛ.
See also: Random

Method random: intrandom(intmax)
Description: This function returns a random number in the range 0 .. max-1.
See also: Random

Method random: mixedrandom(objecto)
Description: If random is called with an object, lfun::_random will be called in the object.
Throws: Throws an exception if the object doesn't have a _random method.
See also: lfun::_random()

Method random: mixedrandom(array|multisetx)
Description: Returns a random element from x.
Throws: Throws an exception if the array or multiset is empty.

Method random_string

string(8bit)random_string(int(0..))

Description

Prototype for the randomness generating function.

Override this symbol to implement a usable class.

Class RandomSystem

Inherit RandomInterface: inherit RandomInterface : RandomInterface

Method random_string

string(8bit)random_string(int(0..)len)

Description

Return a string of random data from the system randomness pool.

On POSIX platforms this reads random data from /dev/urandom on other platforms it may use other methods.

Throws

May throw errors on unexpected state.

Class Reporter

Description: API for reporting parse errors and similar.

Method report

voidreport(SeverityLevelseverity, stringfilename, int(0..)linenumber, stringsubsystem, stringmessage, mixed ... extra_args)

Description

Report a diagnostic from the compiler.

Parameter severity

The severity of the diagnostic.

Parameter filename

Parameter linenumber

Location which triggered the diagnostic. linenumber0 (zero) indicates that it is not applicable (typically originating from command line arguments or similar).

Parameter subsystem

Compiler subsystem that generated the diagnostic.

Parameter message

sprintf()-style formatting string with the diagnostic message.

Parameter extra_args

Extra arguments to sprintf().

The default implementation does the following:

If there's a MasterObject()->report(), call it with the same arguments as ourselves.
Otherwise depending on severity:
NOTICE
Ignored.
WARNING
Calls MasterObject()->compile_warning().
ERROR
Calls MasterObject()->compile_error().
FATAL

If there's no master object yet, the diagnostic is UTF8-encoded and output to Stdio.stderr.

Note

In Pike 7.8 and earlier MasterObject()->report() was not called.

In Pike 8.0 the fallback output was not UTF8-encoded.

See also

PikeCompiler()->report()

Enum Reporter.SeverityLevel

Description: Message severity level. { NOTICE, WARNING, ERROR, FATAL }
See also: report()

Constant NOTICE
Constant WARNING
Constant ERROR
Constant FATAL: constant Reporter.NOTICE
constant Reporter.WARNING
constant Reporter.ERROR
constant Reporter.FATAL

Class __dirnode

Inherit dirnode: inherit MasterObject.dirnode : dirnode

Class __joinnode

Inherit joinnode: inherit MasterObject.joinnode : joinnode

Class mklibpike

Method parse: mapping(string:array(array(Parser.C.Token))) parse(array(Parser.C.Token) tokens)
Description: Returns a mapping from symbol to a tuple of return type and parameters.

Class mklibpike.C_Include_Handler

Variable search_path: array(string) mklibpike.C_Include_Handler.search_path

Method __create__: protectedlocalvoid__create__(array(string) search_path)

Method create: mklibpike.C_Include_Handlermklibpike.C_Include_Handler(array(string) search_path)

Class string_assignment

Method `[]: int res = string_assignment()[ i ]
Description: String index operator.

Method `[]=: string_assignment()[ i ] = j
Description: String assign index operator.

Module Arg

Description

Argument parsing module

This module supports two rather different methods of argument parsing. The first is suitable quick argument parsing without much in the way of checking:

int main(int c,array(string) argv ){mapping arguments =Arg.parse(argv);array files = arguments[Arg.REST];if( arguments->help ) print_help();
  ...
}

The Arg.parse method will return a mapping from argument name to the argument value, if any.

Non-option arguments will be placed in the index Arg.REST

The second way to use this module is to inherit the Options class and add supported arguments.

class MyArguments {inheritArg.Options;string help_pre ="Usage: somecommand";
   Opt verbose = NoOpt("-v")|NoOpt("--verbose");string verbose_help ="Turn on verbose output";
   Opt help = MaybeOpt("--help");
   Opt output = HasOpt("--output")|HasOpt("-o");string output_help ="Determine where output goes to";string help_post ="Command aborted";};

Then, in main:

MyArguments args = MyArguments(argv);

See the documentation for OptLibrary for details about the various Opt classes.

Constant APP: constant Arg.APP
Description: Constant used to represent the name of the application from the command line. Can be used when indexing an Options object.

Constant PATH: constant Arg.PATH
Description: Constant used to represent the full path of the application from the command line. Can be used when indexing an Options object.

Constant REST: constant Arg.REST
Description: Constant used to represent command line arguments not identified as options. Can be used both in the response mapping from parse and when indexing an Options object.

Method parse

mapping(string:string|int(1..)) parse(array(string) argv)

Description

Convenience function for simple argument parsing.

Handles the most common cases.

The return value is a mapping from option name to the option value.

The special index Arg.REST will be set to the remaining arguments after all options have been parsed.

The following argument syntaxes are supported:

--foo         ->  "foo":1
--foo=bar     ->  "foo":"bar"-bar          ->  "b":1,"a":1,"r":1
-bar=foo      ->  "b":1,"a":1,"r":"foo"(?)
--foo --bar   ->  "foo":1,"bar":1
--foo - --bar ->  "foo":1
--foo x --bar ->  "foo":1 (?)-foo          ->  "f":1,"o":2
-x -x -x      ->  "x":3

Example

void main(int n,array argv){mapping opts =Arg.parse(argv);
  argv = opts[Arg.REST];if( opts->help )/*... */}

Class Arg.LowOptions

Inherit OptLibrary: protected inherit OptLibrary : OptLibrary

Variable application: protectedstring Arg.LowOptions.application

Variable argv: protectedarray(string) Arg.LowOptions.argv

Variable opts: protectedmapping(string:Opt) Arg.LowOptions.opts

Variable values: protectedmapping(string:int(1)|string) Arg.LowOptions.values

Method cast: (int)Arg.LowOptions() (float)Arg.LowOptions() (string)Arg.LowOptions() (array)Arg.LowOptions() (mapping)Arg.LowOptions() (multiset)Arg.LowOptions()

Method create: Arg.LowOptionsArg.LowOptions(array(string) _argv, void|mapping(string:string) env)

Method unhandled_argument: protectedboolunhandled_argument(array(string) argv, mapping(string:string) env)

Class Arg.OptLibrary

Description: This class contains a library of parser for different type of options.

Class Arg.OptLibrary.Default

Description

Default value for a setting.

Example

Opt output = HasOpt("-o")|Default("a.out");

Inherit Opt: inherit Opt : Opt

Class Arg.OptLibrary.Env

Description

Environment fallback for an option. Can of course be used as only Opt source.

Example

Opt debug = NoOpt("--debug")|Env("MY_DEBUG");

Inherit Opt: inherit Opt : Opt

Class Arg.OptLibrary.HasOpt

Description

Parses an option that has a parameter. --foo=bar, -x bar and -x=bar will set the variable to bar.

Example

Opt user = HasOpt("--user")|HasOpt("-u");

Inherit NoOpt: inherit NoOpt : NoOpt

Class Arg.OptLibrary.Int

Description

Wrapper class that converts the option argument to an integer.

Example

Opt foo = Int(HasOpt("--foo")|Default(4711));

Inherit Opt: inherit Opt : Opt

Variable opt: Opt Arg.OptLibrary.Int.opt

Method __create__: protectedlocalvoid__create__(Optopt)

Method create: Arg.OptLibrary.IntArg.OptLibrary.Int(Optopt)

Class Arg.OptLibrary.MaybeOpt

Description

Parses an option that may have a parameter. --foo, -x and x in a sequence like -axb will set the variable to 1. --foo=bar, -x bar and -x=bar will set the variable to bar.

Example

Opt debug = MaybeOpt("--debug");

Inherit NoOpt: inherit NoOpt : NoOpt

Class Arg.OptLibrary.Multiple

Description

Wrapper class that allows multiple instances of an option.

Example

Opt filter = Multiple(HasOpt("--filter"));

Inherit Opt: inherit Opt : Opt

Variable opt: Opt Arg.OptLibrary.Multiple.opt

Method __create__: protectedlocalvoid__create__(Optopt)

Method create: Arg.OptLibrary.MultipleArg.OptLibrary.Multiple(Optopt)

Class Arg.OptLibrary.NoOpt

Description

Parses an option without parameter, such as --help, -x or "x" from -axb.

Example

Opt verbose = NoOpt("-v")|NoOpt("--verbose");

Inherit Opt: inherit Opt : Opt

Class Arg.OptLibrary.Opt

Description: Base class for parsing an argument. Inherit this class to create custom made option types.

Method __sprintf: protectedstring__sprintf()
Description: This function will be called by _sprintf, which handles formatting of chaining between objects.

Method get_opts: array(string) get_opts()
Description: Should return a list of options that are parsed. To properly chain argument parsers, return your_opts + ::get_opts().

Method get_value: mixedget_value(array(string) argv, mapping(string:string) env, mixedprevious)
Description: The overloading method should calculate the value of the option and return it. Methods processing argv should only look at argv[0] and if it matches, set it to 0. Returning UNDEFINED means the option was not set (or matched). To properly chain arguments parsers, return ::get_value(argv, env, previous) instead of UNDEFINED, unless you want to explicitly stop the chain and not set this option.

Class Arg.Options

Description: The option parser class that contains all the argument objects.

Inherit LowOptions: inherit LowOptions : LowOptions

Variable help
Variable help_help: Opt Arg.Options.help
protectedstring Arg.Options.help_help
Description: Options that trigger help output.

Method unhandled_argument: protectedboolunhandled_argument(array(string) argv, mapping(string:string) env)

Class Arg.SimpleOptions

Description: Options parser with a unhandled_argument implementation that parses most common argument formats.

Inherit LowOptions: inherit LowOptions : LowOptions

Method unhandled_argument: boolunhandled_argument(array(string) argv, mapping(string:string) env)
Description: Handles arguments as described in Arg.parse

Module Audio

Module Audio.Codec

Class Audio.Codec.decoder

Description: Decoder object.
Note: It needs _Ffmpeg.ffmpeg module for real work.

Method create: Audio.Codec.decoderAudio.Codec.decoder(string|voidcodecname, object|void_codec)
Description: Creates decoder object
Parameter codecnum: Some of supported codec, like _Ffmpeg.CODEC_ID_*
Parameter _codec: The low level object will be used for decoder. By default _Ffmpeg.ffmpeg object will be used.
Note: Until additional library is implemented the second parameter _codec hasn't effect.
See also: _Ffmpeg.ffmpeg, _Ffmpeg.CODEC_ID_MP2

Method decode: mapping|intdecode(int|voidpartial)
Description: Decodes audio data
Parameter partial: Only one frame will be decoded per call.
Returns: If successfull a mapping with decoded data and byte number of used input data is returned, 0 otherwise.

Method from_file

this_program|zerofrom_file(Audio.Format.ANYfile)

Description

Set codec type from file

It uses Audio.Format.ANY's method get_map() to determine which codec should be used.

Parameter file

The object Audio.Format.ANY.

Method get_status: mappingget_status()
Description: Returns decoder status

Module Audio.Format

Description: Audio data format handling
Note: API remains marked "unstable".

Class Audio.Format.ANY

Method check_format: intcheck_format()
Description: Check if data are correctly formated.

Method get_data: stringget_data()
Description: Returns data only.
Note: The operation is destructive. Ie. current data cursor is moved over.
See also: get_frame, get_sample

Method get_frame: stringget_frame()
Description: Returns frame for current position and moves cursor forward.
Note: The operation is destructive. Ie. current data cursor is moved over.
See also: get_data, get_sample

Method get_map: mappingget_map()

Method get_sample: mappingget_sample()
Description: Returns sample for current position and moves cursor forward.
Note: The operation is destructive. Ie. current data cursor is moved over.
See also: get_frame, get_data

Method read_file: this_programread_file(stringfilename, int|voidnocheck)
Description: Reads data from file
See also: read_streamed

Method read_streamed

this_programread_streamed(stringfilename, int|voidnocheck)

Description

Reads data from stream

Ie. for packetized data source the beggining of data is searched.

See also

read_file

Method read_string: this_programread_string(stringdata, int|voidnocheck)
Description: Reads data from string

Class Audio.Format.MP3

Description: A MP3 file parser with ID3 tag support.

Inherit ANY: inherit .module.ANY : ANY

Method get_frame

mapping|intget_frame()

Description

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

Module COM

Method CreateObject: CObjCreateObject(stringprog_id)

Method GetConstants: mappingGetConstants(stringtypelib)
mappingGetConstants(CObjcobj)

Method GetObject: objectGetObject(string|voidfilename, string|voidprog_id)

Method GetTypeInfo: mixedGetTypeInfo(CObjcobj)

Method _sprintf: protectedstring_sprintf(intc, mappingopts)

Module Cache

Description

Common Caching implementation

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.

To create a new cache, do Cache.cache( Cache.Storage.Base storage_type, Cache.Policy.Base expiration_policy )

The cache store instances of Cache.Data.

Class Cache.Data

Description: Base stored object for the cache system.

Variable atime: int Cache.Data.atime
Description: last-access time.

Variable cost: float Cache.Data.cost
Description: relative preciousness scale

Variable ctime: int Cache.Data.ctime
Description: creation-time

Variable etime: int Cache.Data.etime
Description: expiry-time (if supplied). 0 otherwise

Method create: Cache.DataCache.Data(void|mixedvalue, void|intexpire_time, void|floatpreciousness)
Description: expire_time is relative and in seconds.

Method data: mixeddata()
Description: A method in order to allow for lazy computation

Method recursive_low_size: intrecursive_low_size(mixedwhatfor)
Description: Attempts a wild guess of an object's size. It's left here as a common utility. Some classes won't even need it.

Method size: intsize()
Description: A method in order to allow for lazy computation. Used by some Policy Managers

Class Cache.cache

Description: 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.

Method alookup: voidalookup(stringkey, function(string, mixed, mixed ... :void) callback, int|floattimeout, mixed ... args)
Description: 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.

Method async_cleanup_cache: voidasync_cleanup_cache()

Method create: Cache.cacheCache.cache(Cache.Storage.Basestorage_mgr, Cache.Policy.Basepolicy_mgr, void|intcleanup_cycle_delay)
Description: Creates a new cache object. Required are a storage manager, and an expiration policy object.

Method delete: voiddelete(stringkey, void|boolhard)
Description: Forcibly removes some key. If the 'hard' parameter is supplied and true, deleted objects will also have their lfun::_destruct method called upon removal by some backends (i.e. memory)

Method lookup: mixedlookup(stringkey)
Description: Looks in the cache for an element with the given key and, if available, returns it. Returns 0 if the element is not available

Method start_cleanup_cycle: voidstart_cleanup_cycle()

Method store

voidstore(stringkey, mixedvalue, void|intmax_life, void|floatpreciousness, void|multiset(string) dependants)

Description

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.

Method threaded_cleanup_cycle: voidthreaded_cleanup_cycle()

Module Cache.Policy

Class Cache.Policy.Base

Description: Base class for cache expiration policies.

Method expire

voidexpire(Cache.Storage.Basestorage)

Description

Expire callback.

This function is called to expire parts of storage.

Note

All Storage.Policy classes must MUST implement this method.

Class Cache.Policy.Multiple

Description: A multiple-policies expiration policy manager.
Thanks: Thanks to Francesco Chemolli <kinkie@roxen.com> for the contribution.

Inherit Base: inherit Cache.Policy.Base : Base

Method create: Cache.Policy.MultipleCache.Policy.Multiple(Cache.Policy.Base ... policies)

Method expire: voidexpire(Cache.Storage.Basestorage)
Description: This expire function calls the expire functions in all of the sub-policies in turn.

Class Cache.Policy.Null

Description

Null policy-manager for the generic Caching system

This is a policy manager that doesn't actually expire anything. It is useful in multilevel and/or network-based caches.

Thanks

Thanks to Francesco Chemolli <kinkie@roxen.com> for the contribution.

Inherit Base: inherit Cache.Policy.Base : Base

Method expire: voidexpire(Cache.Storage.Basestorage)
Description: This is an expire function that does nothing.

Class Cache.Policy.Sized

Description: An LRU, size-constrained expiration policy manager.
Thanks: Thanks to Francesco Chemolli <kinkie@roxen.com> for the contribution.

Inherit Base: inherit Cache.Policy.Base : Base

Method create: Cache.Policy.SizedCache.Policy.Sized(intmax, void|intmin)

Method expire: voidexpire(Cache.Storage.Basestorage)

Class Cache.Policy.Timed

Description: An access-time-based expiration policy manager.

Inherit Base: inherit Cache.Policy.Base : Base

Module Cache.Storage

Class Cache.Storage.Base

Description

Base class for cache storage managers.

All Cache.Storage managers must provide these methods.

Method aget

voidaget(stringkey, function(string, int(0)|Cache.Data, mixed ... :void) callback, mixed ... extra_callback_args)

Description

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.

Method delete

mixeddelete(stringkey, void|boolhard)

Description

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

Returns the deleted entry.

Method first
Method next

int(0)|stringfirst()
int(0)|stringnext()

Description

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.

Method get: int(0)|Cache.Dataget(stringkey, void|boolnotouch)
Description: Fetch some data from the cache synchronously.
Note: Be careful, as with some storage managers it might block the calling thread for some time.

Method set

voidset(stringkey, mixedvalue, void|intmax_life, void|floatpreciousness, void|multiset(string) dependants)

Description

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.

Class Cache.Storage.Gdbm

Description

A GBM-based storage manager.

This storage manager provides the means to save data to memory. In this manager I'll add reference documentation as comments to interfaces. It will be organized later in a more comprehensive format

Settings will be added later.

Thanks

Thanks to Francesco Chemolli <kinkie@roxen.com> for the contribution.

Inherit Base: inherit Cache.Storage.Base : Base

Method create: Cache.Storage.GdbmCache.Storage.Gdbm(stringpath)
Description: A GDBM storage-manager must be hooked to a GDBM Database.

Class Cache.Storage.Gdbm.Data

Inherit Data: inherit Cache.Data : Data

Class Cache.Storage.Memory

Description

A RAM-based storage manager.

This storage manager provides the means to save data to memory. In this manager I'll add reference documentation as comments to interfaces. It will be organized later in a more comprehensive format

Settings will be added later.

Thanks

Thanks to Francesco Chemolli <kinkie@roxen.com> for the contribution.

Inherit Base: inherit Cache.Storage.Base : Base

Method get: int(0)|Cache.Dataget(stringkey, void|intnotouch)
Description: Fetches some data from the cache. If notouch is set, don't touch the data from the cache (meant to be used by the storage manager only)

Class Cache.Storage.Memory.Data

Inherit Data: inherit Cache.Data : Data

Class Cache.Storage.MySQL

Description

An SQL-based storage manager

This storage manager provides the means to save data to an SQL-based backend.

For now it's mysql only, dialectization will be added at a later time. Serialization should be taken care of by the low-level SQL drivers.

Note

An administrator is supposed to create the database and give the user enough privileges to write to it. It will be care of this driver to create the database tables itself.

Thanks

Thanks to Francesco Chemolli <kinkie@roxen.com> for the contribution.

Inherit Base: inherit Cache.Storage.Base : Base

Method create: Cache.Storage.MySQLCache.Storage.MySQL(stringsql_url)

Class Cache.Storage.MySQL.Data

Description: Database manipulation is done externally. This class only returns values, with some lazy decoding.

Inherit Data: inherit Cache.Data : Data

Class Cache.Storage.Yabu

Description

A Yabu-based storage manager.

Settings will be added later.

Thanks

Thanks to Francesco Chemolli <kinkie@roxen.com> for the contribution.

Inherit Base: inherit Cache.Storage.Base : Base

Method create: Cache.Storage.YabuCache.Storage.Yabu(stringpath)

Class Cache.Storage.Yabu.Data

Inherit Data: inherit Cache.Data : Data

Module Cairo

Constant ANTIALIAS_BEST: constantint Cairo.ANTIALIAS_BEST
Description: Hint that the backend should render at the highest quality, sacrificing speed if necessary

Constant ANTIALIAS_DEFAULT: constantint Cairo.ANTIALIAS_DEFAULT
Description: Use the default antialiasing for the subsystem and target device

Constant ANTIALIAS_FAST: constantint Cairo.ANTIALIAS_FAST
Description: Hint that the backend should perform some antialiasing but prefer speed over quality

Constant ANTIALIAS_GOOD: constantint Cairo.ANTIALIAS_GOOD
Description: The backend should balance quality against performance

Constant ANTIALIAS_GRAY: constantint Cairo.ANTIALIAS_GRAY
Description: Perform single-color antialiasing (using shades of gray for black text on a white background, for example)

Constant ANTIALIAS_NONE: constantint Cairo.ANTIALIAS_NONE
Description: Use a bilevel alpha mask

Constant ANTIALIAS_SUBPIXEL: constantint Cairo.ANTIALIAS_SUBPIXEL
Description: Perform antialiasing by taking advantage of the order of subpixel elements on devices such as LCD panels

Constant CAIRO_VERSION
Constant CAIRO_VERSION_MAJOR
Constant CAIRO_VERSION_MINOR
Constant CAIRO_VERSION_MICRO
Constant CAIRO_VERSION_STRING: constantint Cairo.CAIRO_VERSION
constantint Cairo.CAIRO_VERSION_MAJOR
constantint Cairo.CAIRO_VERSION_MINOR
constantint Cairo.CAIRO_VERSION_MICRO
constantstring Cairo.CAIRO_VERSION_STRING
Description: Compile-time version

Constant COLOR_MODE_COLOR: constantint Cairo.COLOR_MODE_COLOR
Description: Enable rendering color glyphs. If the font contains a color presentation for a glyph, and when supported by the font backend, the glyph will be rendered in color.

Constant COLOR_MODE_DEFAULT: constantint Cairo.COLOR_MODE_DEFAULT
Description: Use the default color mode for font backend and target device

Constant COLOR_MODE_NO_COLOR: constantint Cairo.COLOR_MODE_NO_COLOR
Description: Disable rendering color glyphs. Glyphs are always rendered as outline glyphs.

Constant COLOR_PALETTE_DEFAULT: constantint Cairo.COLOR_PALETTE_DEFAULT
Description: The default color palette index.

Constant CONTENT_ALPHA: constantint Cairo.CONTENT_ALPHA
Description: The surface will hold alpha content only.

Constant CONTENT_COLOR: constantint Cairo.CONTENT_COLOR
Description: The surface will hold color content only.

Constant CONTENT_COLOR_ALPHA: constantint Cairo.CONTENT_COLOR_ALPHA
Description: The surface will hold color and alpha content.

Constant DITHER_BEST: constantint Cairo.DITHER_BEST
Description: Best algorithm available in the backend

Constant DITHER_DEFAULT: constantint Cairo.DITHER_DEFAULT
Description: Default choice at cairo compile time. Currently DITHER_NONE.

Constant DITHER_FAST: constantint Cairo.DITHER_FAST
Description: Fastest dithering algorithm supported by the backend

Constant DITHER_GOOD: constantint Cairo.DITHER_GOOD
Description: An algorithm with smoother dithering than DITHER_FAST

Constant DITHER_NONE: constantint Cairo.DITHER_NONE
Description: No dithering.

Constant EXTEND_NONE: constantint Cairo.EXTEND_NONE
Description: pixels outside of the source pattern are fully transparent

Constant EXTEND_PAD: constantint Cairo.EXTEND_PAD
Description: pixels outside of the pattern copy the closest pixel from the source

Constant EXTEND_REFLECT: constantint Cairo.EXTEND_REFLECT
Description: the pattern is tiled by reflecting at the edges

Constant EXTEND_REPEAT: constantint Cairo.EXTEND_REPEAT
Description: the pattern is tiled by repeating

Constant FILL_RULE_EVEN_ODD: constantint Cairo.FILL_RULE_EVEN_ODD
Description: Counts the total number of intersections, without regard to the orientation of the contour. If the total number of intersections is odd, the point will be filled.

Constant FILL_RULE_WINDING: constantint Cairo.FILL_RULE_WINDING
Description: If the path crosses the ray from left-to-right, counts +1. If the path crosses the ray from right to left, counts -1. (Left and right are determined from the perspective of looking along the ray from the starting point.) If the total count is non-zero, the point will be filled.

Constant FILTER_BEST: constantint Cairo.FILTER_BEST
Description: The highest-quality available, performance may not be suitable for interactive use.

Constant FILTER_BILINEAR: constantint Cairo.FILTER_BILINEAR
Description: Linear interpolation in two dimensions

Constant FILTER_FAST: constantint Cairo.FILTER_FAST
Description: A high-performance filter, with quality similar to FILTER_NEAREST

Constant FILTER_GAUSSIAN: constantint Cairo.FILTER_GAUSSIAN
Description: This filter value is currently unimplemented, and should not be used in current code.

Constant FILTER_GOOD: constantint Cairo.FILTER_GOOD
Description: A reasonable-performance filter, with quality similar to FILTER_BILINEAR

Constant FILTER_NEAREST: constantint Cairo.FILTER_NEAREST
Description: Nearest-neighbor filtering

Constant FONT_SLANT_ITALIC: constantint Cairo.FONT_SLANT_ITALIC
Description: Italic font style

Constant FONT_SLANT_NORMAL: constantint Cairo.FONT_SLANT_NORMAL
Description: Upright font style

Constant FONT_SLANT_OBLIQUE: constantint Cairo.FONT_SLANT_OBLIQUE
Description: Oblique font style

Constant FONT_WEIGHT_BOLD: constantint Cairo.FONT_WEIGHT_BOLD
Description: Bold font weight

Constant FONT_WEIGHT_NORMAL: constantint Cairo.FONT_WEIGHT_NORMAL
Description: Normal font weight

Constant FORMAT_A1: constantint Cairo.FORMAT_A1
Description: each pixel is a 1-bit quantity holding an alpha value. Pixels are packed together into 32-bit quantities. The ordering of the bits matches the endianness of the platform. On a big-endian machine, the first pixel is in the uppermost bit, on a little-endian machine the first pixel is in the least-significant bit.

Constant FORMAT_A8: constantint Cairo.FORMAT_A8
Description: each pixel is a 8-bit quantity holding an alpha value.

Constant FORMAT_ARGB32: constantint Cairo.FORMAT_ARGB32
Description: each pixel is a 32-bit quantity, with alpha in the upper 8 bits, then red, then green, then blue. The 32-bit quantities are stored native-endian. Pre-multiplied alpha is used. (That is, 50% transparent red is 0x80800000, not 0x80ff0000.)

Constant FORMAT_INVALID: constantint Cairo.FORMAT_INVALID
Description: no such format exists or is supported.

Constant FORMAT_RGB16_565: constantint Cairo.FORMAT_RGB16_565
Description: each pixel is a 16-bit quantity with red in the upper 5 bits, then green in the middle 6 bits, and blue in the lower 5 bits.

Constant FORMAT_RGB24: constantint Cairo.FORMAT_RGB24
Description: each pixel is a 32-bit quantity, with the upper 8 bits unused. Red, Green, and Blue are stored in the remaining 24 bits in that order.

Constant FORMAT_RGB30: constantint Cairo.FORMAT_RGB30
Description: like RGB24 but with 10bpc.

Constant FORMAT_RGB96F: constantint Cairo.FORMAT_RGB96F
Description: 3 floats, R, G, B.

Constant FORMAT_RGBA128F: constantint Cairo.FORMAT_RGBA128F
Description: 4 floats, R, G, B, A.

Constant HINT_METRICS_DEFAULT: constantint Cairo.HINT_METRICS_DEFAULT
Description: Hint metrics in the default manner for the font backend and target device

Constant HINT_METRICS_OFF: constantint Cairo.HINT_METRICS_OFF
Description: Do not hint font metrics

Constant HINT_METRICS_ON: constantint Cairo.HINT_METRICS_ON
Description: Hint font metrics

Constant HINT_STYLE_DEFAULT: constantint Cairo.HINT_STYLE_DEFAULT
Description: Use the default hint style for font backend and target device

Constant HINT_STYLE_FULL: constantint Cairo.HINT_STYLE_FULL
Description: Hint outlines to maximize contrast

Constant HINT_STYLE_MEDIUM: constantint Cairo.HINT_STYLE_MEDIUM
Description: Hint outlines with medium strength giving a compromise between fidelity to the original shapes and contrast

Constant HINT_STYLE_NONE: constantint Cairo.HINT_STYLE_NONE
Description: Do not hint outlines

Constant HINT_STYLE_SLIGHT: constantint Cairo.HINT_STYLE_SLIGHT
Description: Hint outlines slightly to improve contrast while retaining good fidelity to the original shapes

Constant LINE_CAP_BUTT: constantint Cairo.LINE_CAP_BUTT
Description: start(stop) the line exactly at the start(end) point

Constant LINE_CAP_ROUND: constantint Cairo.LINE_CAP_ROUND
Description: use a round ending, the center of the circle is the end point

Constant LINE_CAP_SQUARE: constantint Cairo.LINE_CAP_SQUARE
Description: use squared ending, the center of the square is the end point

Constant LINE_JOIN_BEVEL: constantint Cairo.LINE_JOIN_BEVEL
Description: use a cut-off join, the join is cut off at half the line width from the joint point

Constant LINE_JOIN_MITER: constantint Cairo.LINE_JOIN_MITER
Description: use a sharp (angled) corner, see Context->set_miter_limit()

Constant LINE_JOIN_ROUND: constantint Cairo.LINE_JOIN_ROUND
Description: use a rounded join, the center of the circle is the joint point

Constant MIME_TYPE_CCITT_FAX: constantstring Cairo.MIME_TYPE_CCITT_FAX
Description: Group 3 or Group 4 CCITT facsimile encoding (International Telecommunication Union, Recommendations T.4 and T.6.)

Constant MIME_TYPE_CCITT_FAX_PARAMS: constantstring Cairo.MIME_TYPE_CCITT_FAX_PARAMS
Description: Decode parameters for Group 3 or Group 4 CCITT facsimile encoding. See CCITT Fax Images.

Constant MIME_TYPE_EPS: constantstring Cairo.MIME_TYPE_EPS
Description: Encapsulated PostScript file. Encapsulated PostScript File Format Specification

Constant MIME_TYPE_EPS_PARAMS: constantstring Cairo.MIME_TYPE_EPS_PARAMS
Description: Embedding parameters Encapsulated PostScript data. See Embedding EPS files.

Constant MIME_TYPE_JBIG2: constantstring Cairo.MIME_TYPE_JBIG2
Description: Joint Bi-level Image Experts Group image coding standard (ISO/IEC 11544).

Constant MIME_TYPE_JBIG2_GLOBAL: constantstring Cairo.MIME_TYPE_JBIG2_GLOBAL
Description: Joint Bi-level Image Experts Group image coding standard (ISO/IEC 11544) global segment.

Constant MIME_TYPE_JBIG2_GLOBAL_ID: constantstring Cairo.MIME_TYPE_JBIG2_GLOBAL_ID
Description: An unique identifier shared by a JBIG2 global segment and all JBIG2 images that depend on the global segment.

Constant MIME_TYPE_JP2: constantstring Cairo.MIME_TYPE_JP2
Description: The Joint Photographic Experts Group (JPEG) 2000 image coding standard (ISO/IEC 15444-1).

Constant MIME_TYPE_JPEG: constantstring Cairo.MIME_TYPE_JPEG
Description: The Joint Photographic Experts Group (JPEG) image coding standard (ISO/IEC 10918-1).

Constant MIME_TYPE_PNG: constantstring Cairo.MIME_TYPE_PNG
Description: The Portable Network Graphics image file format (ISO/IEC 15948).

Constant MIME_TYPE_UNIQUE_ID: constantstring Cairo.MIME_TYPE_UNIQUE_ID
Description: Unique identifier for a surface (cairo specific MIME type). All surfaces with the same unique identifier will only be embedded once.

Constant MIME_TYPE_URI: constantstring Cairo.MIME_TYPE_URI
Description: URI for an image file (unofficial MIME type).

Constant OPERATOR_ADD: constantint Cairo.OPERATOR_ADD
Description: source and destination layers are accumulated

Constant OPERATOR_ATOP: constantint Cairo.OPERATOR_ATOP
Description: draw source on top of destination content and only there

Constant OPERATOR_CLEAR: constantint Cairo.OPERATOR_CLEAR
Description: clear destination layer (bounded)

Constant OPERATOR_COLOR_BURN: constantint Cairo.OPERATOR_COLOR_BURN
Description: darkens the destination color to reflect the source color.

Constant OPERATOR_COLOR_DODGE: constantint Cairo.OPERATOR_COLOR_DODGE
Description: brightens the destination color to reflect the source color.

Constant OPERATOR_DARKEN: constantint Cairo.OPERATOR_DARKEN
Description: replaces the destination with the source if it is darker, otherwise keeps the source.

Constant OPERATOR_DEST: constantint Cairo.OPERATOR_DEST
Description: ignore the source

Constant OPERATOR_DEST_ATOP: constantint Cairo.OPERATOR_DEST_ATOP
Description: leave destination on top of source content and only there (unbounded)

Constant OPERATOR_DEST_IN: constantint Cairo.OPERATOR_DEST_IN
Description: leave destination only where there was source content (unbounded)

Constant OPERATOR_DEST_OUT: constantint Cairo.OPERATOR_DEST_OUT
Description: leave destination only where there was no source content

Constant OPERATOR_DEST_OVER: constantint Cairo.OPERATOR_DEST_OVER
Description: draw destination on top of source

Constant OPERATOR_DIFFERENCE: constantint Cairo.OPERATOR_DIFFERENCE
Description: Takes the difference of the source and destination color.

Constant OPERATOR_EXCLUSION: constantint Cairo.OPERATOR_EXCLUSION
Description: Produces an effect similar to difference, but with lower contrast.

Constant OPERATOR_HARD_LIGHT: constantint Cairo.OPERATOR_HARD_LIGHT
Description: Multiplies or screens, dependent on source color.

Constant OPERATOR_HSL_COLOR: constantint Cairo.OPERATOR_HSL_COLOR
Description: Creates a color with the hue and saturation of the source and the luminosity of the target. This preserves the gray levels of the target and is useful for coloring monochrome images or tinting color images.

Constant OPERATOR_HSL_HUE: constantint Cairo.OPERATOR_HSL_HUE
Description: Creates a color with the hue of the source and the saturation and luminosity of the target.

Constant OPERATOR_HSL_LUMINOSITY: constantint Cairo.OPERATOR_HSL_LUMINOSITY
Description: Creates a color with the luminosity of the source and the hue and saturation of the target. This produces an inverse effect to OPERATOR_HSL_COLOR.

Constant OPERATOR_HSL_SATURATION: constantint Cairo.OPERATOR_HSL_SATURATION
Description: Creates a color with the saturation of the source and the hue and luminosity of the target. Painting with this mode onto a gray area produces no change.

Constant OPERATOR_IN: constantint Cairo.OPERATOR_IN
Description: draw source where there was destination content (unbounded)

Constant OPERATOR_LIGHTEN: constantint Cairo.OPERATOR_LIGHTEN
Description: replaces the destination with the source if it is lighter, otherwise keeps the source.

Constant OPERATOR_MULTIPLY: constantint Cairo.OPERATOR_MULTIPLY
Description: source and destination layers are multiplied. This causes the result to be at least as dark as the darker inputs.

Constant OPERATOR_OUT: constantint Cairo.OPERATOR_OUT
Description: draw source where there was no destination content (unbounded)

Constant OPERATOR_OVER: constantint Cairo.OPERATOR_OVER
Description: draw source layer on top of destination layer (bounded)

Constant OPERATOR_OVERLAY: constantint Cairo.OPERATOR_OVERLAY
Description: multiplies or screens, depending on the lightness of the destination color.

Constant OPERATOR_SATURATE: constantint Cairo.OPERATOR_SATURATE
Description: like over, but assuming source and dest are disjoint geometries

Constant OPERATOR_SCREEN: constantint Cairo.OPERATOR_SCREEN
Description: source and destination are complemented and multiplied. This causes the result to be at least as light as the lighter inputs.

Constant OPERATOR_SOFT_LIGHT: constantint Cairo.OPERATOR_SOFT_LIGHT
Description: Darkens or lightens, dependent on source color.

Constant OPERATOR_SOURCE: constantint Cairo.OPERATOR_SOURCE
Description: replace destination layer (bounded)

Constant OPERATOR_XOR: constantint Cairo.OPERATOR_XOR
Description: source and destination are shown where there is only one of them

Constant PATH_CLOSE_PATH: constantint Cairo.PATH_CLOSE_PATH
Description: A close-path operation

Constant PATH_CURVE_TO: constantint Cairo.PATH_CURVE_TO
Description: A curve-to operation

Constant PATH_LINE_TO: constantint Cairo.PATH_LINE_TO
Description: A line-to operation

Constant PATH_MOVE_TO: constantint Cairo.PATH_MOVE_TO
Description: A move-to operation

Constant PDF_METADATA_AUTHOR: constantint Cairo.PDF_METADATA_AUTHOR
Description: The document author

Constant PDF_METADATA_CREATE_DATE: constantint Cairo.PDF_METADATA_CREATE_DATE
Description: The document creation date

Constant PDF_METADATA_CREATOR: constantint Cairo.PDF_METADATA_CREATOR
Description: The document creator

Constant PDF_METADATA_KEYWORDS: constantint Cairo.PDF_METADATA_KEYWORDS
Description: The document keywords

Constant PDF_METADATA_MOD_DATE: constantint Cairo.PDF_METADATA_MOD_DATE
Description: The document modification date

Constant PDF_METADATA_SUBJECT: constantint Cairo.PDF_METADATA_SUBJECT
Description: The document subject

Constant PDF_METADATA_TITLE: constantint Cairo.PDF_METADATA_TITLE
Description: The document title

Constant PDF_OUTLINE_FLAG_BOLD: constantint Cairo.PDF_OUTLINE_FLAG_BOLD
Description: The outline item is displayed by the viewer in bold text

Constant PDF_OUTLINE_FLAG_ITALIC: constantint Cairo.PDF_OUTLINE_FLAG_ITALIC
Description: The outline item is displayed by the viewer in italic text

Constant PDF_OUTLINE_FLAG_OPEN: constantint Cairo.PDF_OUTLINE_FLAG_OPEN
Description: The outline item defaults to open in the PDF viewer

Constant PDF_OUTLINE_ROOT: constantint Cairo.PDF_OUTLINE_ROOT
Description: The root outline item in PDFSurface->add_outline().

Constant PDF_VERSION_1_4: constantint Cairo.PDF_VERSION_1_4
Description: The version 1.4 of the PDF specification.

Constant PDF_VERSION_1_5: constantint Cairo.PDF_VERSION_1_5
Description: The version 1.5 of the PDF specification.

Constant PDF_VERSION_1_6: constantint Cairo.PDF_VERSION_1_6
Description: The version 1.6 of the PDF specification.

Constant PDF_VERSION_1_7: constantint Cairo.PDF_VERSION_1_7
Description: The version 1.7 of the PDF specification.

Constant PS_LEVEL_2: constantint Cairo.PS_LEVEL_2
Description: The language level 2 of the PostScript specification.

Constant PS_LEVEL_3: constantint Cairo.PS_LEVEL_3
Description: The language level 3 of the PostScript specification.

Constant SCRIPT_MODE_ASCII: constantint Cairo.SCRIPT_MODE_ASCII
Description: the output will be in readable text (default).

Constant SCRIPT_MODE_BINARY: constantint Cairo.SCRIPT_MODE_BINARY
Description: the output will use byte codes.

Constant STATUS_CLIP_NOT_REPRESENTABLE: constantint Cairo.STATUS_CLIP_NOT_REPRESENTABLE
Description: clip region not representable in desired format

Constant STATUS_DEVICE_ERROR: constantint Cairo.STATUS_DEVICE_ERROR
Description: an operation to the device caused an unspecified error

Constant STATUS_DEVICE_FINISHED: constantint Cairo.STATUS_DEVICE_FINISHED
Description: target device has been finished

Constant STATUS_DEVICE_TYPE_MISMATCH: constantint Cairo.STATUS_DEVICE_TYPE_MISMATCH
Description: the device type is not appropriate for the operation

Constant STATUS_DWRITE_ERROR: constantint Cairo.STATUS_DWRITE_ERROR
Description: error occurred in the Windows Direct Write API

Constant STATUS_FILE_NOT_FOUND: constantint Cairo.STATUS_FILE_NOT_FOUND
Description: file not found

Constant STATUS_FONT_TYPE_MISMATCH: constantint Cairo.STATUS_FONT_TYPE_MISMATCH
Description: the font type is not appropriate for the operation

Constant STATUS_FREETYPE_ERROR: constantint Cairo.STATUS_FREETYPE_ERROR
Description: error occurred in libfreetype

Constant STATUS_INVALID_CLUSTERS: constantint Cairo.STATUS_INVALID_CLUSTERS
Description: input clusters do not represent the accompanying text and glyph array

Constant STATUS_INVALID_CONTENT: constantint Cairo.STATUS_INVALID_CONTENT
Description: invalid value for an input content

Constant STATUS_INVALID_DASH: constantint Cairo.STATUS_INVALID_DASH
Description: invalid value for a dash setting

Constant STATUS_INVALID_DSC_COMMENT: constantint Cairo.STATUS_INVALID_DSC_COMMENT
Description: invalid value for a DSC comment

Constant STATUS_INVALID_FORMAT: constantint Cairo.STATUS_INVALID_FORMAT
Description: invalid value for an input format

Constant STATUS_INVALID_INDEX: constantint Cairo.STATUS_INVALID_INDEX
Description: invalid index passed to getter

Constant STATUS_INVALID_MATRIX: constantint Cairo.STATUS_INVALID_MATRIX
Description: invalid matrix (not invertible)

Constant STATUS_INVALID_MESH_CONSTRUCTION: constantint Cairo.STATUS_INVALID_MESH_CONSTRUCTION
Description: a mesh pattern construction operation was used outside of a MeshPattern->begin_patch()/MeshPattern->end_patch() pair

Constant STATUS_INVALID_PATH_DATA: constantint Cairo.STATUS_INVALID_PATH_DATA
Description: input path data not valid

Constant STATUS_INVALID_POP_GROUP: constantint Cairo.STATUS_INVALID_POP_GROUP
Description: no saved group to pop, i.e. Context->pop_group() without matching Context->push_group()

Constant STATUS_INVALID_RESTORE: constantint Cairo.STATUS_INVALID_RESTORE
Description: Context->restore() called without matching Context->save()

Constant STATUS_INVALID_SIZE: constantint Cairo.STATUS_INVALID_SIZE
Description: invalid value (typically too big) for the size of the input (surface, pattern, etc.)

Constant STATUS_INVALID_SLANT: constantint Cairo.STATUS_INVALID_SLANT
Description: invalid value for an input slant

Constant STATUS_INVALID_STATUS: constantint Cairo.STATUS_INVALID_STATUS
Description: invalid value for an input status

Constant STATUS_INVALID_STRIDE: constantint Cairo.STATUS_INVALID_STRIDE
Description: invalid value for stride

Constant STATUS_INVALID_STRING: constantint Cairo.STATUS_INVALID_STRING
Description: input string not valid UTF-8

Constant STATUS_INVALID_VISUAL: constantint Cairo.STATUS_INVALID_VISUAL
Description: invalid value for an input visual

Constant STATUS_INVALID_WEIGHT: constantint Cairo.STATUS_INVALID_WEIGHT
Description: invalid value for an input weight

Constant STATUS_JBIG2_GLOBAL_MISSING: constantint Cairo.STATUS_JBIG2_GLOBAL_MISSING
Description: MIME_TYPE_JBIG2_GLOBAL_ID has been used on at least one image but no image provided MIME_TYPE_JBIG2_GLOBAL

Constant STATUS_LAST_STATUS: constantint Cairo.STATUS_LAST_STATUS
Description: this is a special value indicating the number of status values defined in this enumeration. When using this value, note that the version of cairo at run-time may have additional status values defined than the value of this symbol at compile-time.

Constant STATUS_NEGATIVE_COUNT: constantint Cairo.STATUS_NEGATIVE_COUNT
Description: negative number used where it is not allowed

Constant STATUS_NO_CURRENT_POINT: constantint Cairo.STATUS_NO_CURRENT_POINT
Description: no current point defined

Constant STATUS_NO_MEMORY: constantint Cairo.STATUS_NO_MEMORY
Description: out of memory

Constant STATUS_NULL_POINTER: constantint Cairo.STATUS_NULL_POINTER
Description: NULL pointer

Constant STATUS_PATTERN_TYPE_MISMATCH: constantint Cairo.STATUS_PATTERN_TYPE_MISMATCH
Description: the pattern type is not appropriate for the operation

Constant STATUS_PNG_ERROR: constantint Cairo.STATUS_PNG_ERROR
Description: error occurred in libpng while reading from or writing to a PNG file

Constant STATUS_READ_ERROR: constantint Cairo.STATUS_READ_ERROR
Description: error while reading from input stream

Constant STATUS_SUCCESS: constantint Cairo.STATUS_SUCCESS
Description: no error has occurred

Constant STATUS_SURFACE_FINISHED: constantint Cairo.STATUS_SURFACE_FINISHED
Description: target surface has been finished

Constant STATUS_SURFACE_TYPE_MISMATCH: constantint Cairo.STATUS_SURFACE_TYPE_MISMATCH
Description: the surface type is not appropriate for the operation

Constant STATUS_SVG_FONT_ERROR: constantint Cairo.STATUS_SVG_FONT_ERROR
Description: error occurred in OpenType-SVG font rendering

Constant STATUS_TAG_ERROR: constantint Cairo.STATUS_TAG_ERROR
Description: invalid tag name, attributes, or nesting

Constant STATUS_TEMP_FILE_ERROR: constantint Cairo.STATUS_TEMP_FILE_ERROR
Description: error creating or writing to a temporary file

Constant STATUS_USER_FONT_ERROR: constantint Cairo.STATUS_USER_FONT_ERROR
Description: error occurred in a user-font callback function

Constant STATUS_USER_FONT_IMMUTABLE: constantint Cairo.STATUS_USER_FONT_IMMUTABLE
Description: the user-font is immutable

Constant STATUS_USER_FONT_NOT_IMPLEMENTED: constantint Cairo.STATUS_USER_FONT_NOT_IMPLEMENTED
Description: user-font method not implemented

Constant STATUS_WIN32_GDI_ERROR: constantint Cairo.STATUS_WIN32_GDI_ERROR
Description: error occurred in the Windows Graphics Device Interface

Constant STATUS_WRITE_ERROR: constantint Cairo.STATUS_WRITE_ERROR
Description: error while writing to output stream

Constant SUBPIXEL_ORDER_BGR: constantint Cairo.SUBPIXEL_ORDER_BGR
Description: Subpixel elements are arranged horizontally with blue at the left

Constant SUBPIXEL_ORDER_DEFAULT: constantint Cairo.SUBPIXEL_ORDER_DEFAULT
Description: Use the default subpixel order for for the target device

Constant SUBPIXEL_ORDER_RGB: constantint Cairo.SUBPIXEL_ORDER_RGB
Description: Subpixel elements are arranged horizontally with red at the left

Constant SUBPIXEL_ORDER_VBGR: constantint Cairo.SUBPIXEL_ORDER_VBGR
Description: Subpixel elements are arranged vertically with blue at the top

Constant SUBPIXEL_ORDER_VRGB: constantint Cairo.SUBPIXEL_ORDER_VRGB
Description: Subpixel elements are arranged vertically with red at the top

Constant SVG_UNIT_CM: constantint Cairo.SVG_UNIT_CM
Description: Centimeters (1cm = 96px/2.54).

Constant SVG_UNIT_EM: constantint Cairo.SVG_UNIT_EM
Description: The size of the element's font.

Constant SVG_UNIT_EX: constantint Cairo.SVG_UNIT_EX
Description: The x-height of the element’s font.

Constant SVG_UNIT_IN: constantint Cairo.SVG_UNIT_IN
Description: Inches (1in = 2.54cm = 96px).

Constant SVG_UNIT_MM: constantint Cairo.SVG_UNIT_MM
Description: Millimeters (1mm = 1/10th of 1cm).

Constant SVG_UNIT_PC: constantint Cairo.SVG_UNIT_PC
Description: Picas (1pc = 1/6th of 1in).

Constant SVG_UNIT_PERCENT: constantint Cairo.SVG_UNIT_PERCENT
Description: Percent, a value that is some fraction of another reference value.

Constant SVG_UNIT_PT: constantint Cairo.SVG_UNIT_PT
Description: Points (1pt = 1/72th of 1in).

Constant SVG_UNIT_PX: constantint Cairo.SVG_UNIT_PX
Description: Pixels (1px = 1/96th of 1in).

Constant SVG_UNIT_USER: constantint Cairo.SVG_UNIT_USER
Description: User unit, a value in the current coordinate system. If used in the root element for the initial coordinate systems it corresponds to pixels.

Constant SVG_VERSION_1_1: constantint Cairo.SVG_VERSION_1_1
Description: The version 1.1 of the SVG specification.

Constant SVG_VERSION_1_2: constantint Cairo.SVG_VERSION_1_2
Description: The version 1.2 of the SVG specification.

Constant TAG_CONTENT: constantstring Cairo.TAG_CONTENT
Description: Create a content tag.

Constant TAG_CONTENT_REF: constantstring Cairo.TAG_CONTENT_REF
Description: Create a content reference tag.

Constant TAG_DEST: constantstring Cairo.TAG_DEST
Description: Create a destination for a hyperlink.

Constant TAG_LINK: constantstring Cairo.TAG_LINK
Description: Create hyperlink.

Constant TEXT_CLUSTER_FLAG_BACKWARD: constantint Cairo.TEXT_CLUSTER_FLAG_BACKWARD
Description: The clusters in the cluster array map to glyphs in the glyph array from end to start.

Method cairo_version: intcairo_version()
Description: Returns the version of the cairo library encoded in a single integer
See also: cairo_version_string()

Method cairo_version_string: stringcairo_version_string()
Description: Returns the version of the cairo library as a human-readable string
See also: cairo_version()

Method stride_for_width: intstride_for_width(intformat, intwidth)
Description: This function provides a stride value that will respect all alignment requirements of the accelerated image-rendering code within cairo.
Parameter format: A cairo format
Parameter width: The desired width of an image surface to be created.
Returns: the appropriate stride to use given the desired format and width, or -1 if either the format is invalid or the width too large.

Class Cairo.Context

Description: The cairo drawing context

Method append_path: voidappend_path(Pathpath)
Description: Append the path onto the current path. The path may be either the return value from one of copy_path() or copy_path_flat() or it may be constructed manually.
Parameter path: path to be appended

Method arc

voidarc(float|intxc, float|intyc, float|intradius, floatangle1, floatangle2)

Description

Adds a circular arc of the given radius to the current path. The arc is centered at (xc, yc), begins at angle1 and proceeds in the direction of increasing angles to end at angle2. If angle2 is less than angle1 it will be progressively increased by 2*M_PI until it is greater than angle1.

If there is a current point, an initial line segment will be added to the path to connect the current point to the beginning of the arc. If this initial line is undesired, it can be avoided by calling new_sub_path() before calling arc().

Angles are measured in radians. An angle of 0.0 is in the direction of the positive X axis (in user space). An angle of M_PI/2.0 radians (90 degrees) is in the direction of the positive Y axis (in user space). Angles increase in the direction from the positive X axis toward the positive Y axis. So with the default transformation matrix, angles increase in a clockwise direction.

This function gives the arc in the direction of increasing angles; see arc_negative() to get the arc in the direction of decreasing angles.

Parameter xc

X position of the center of the arc

Parameter yc

Y position of the center of the arc

Parameter radius

the radius of the arc

Parameter angle1

the start angle, in radians

Parameter angle2

the end angle, in radians

Method arc_negative

voidarc_negative(float|intxc, float|intyc, float|intradius, floatangle1, floatangle2)

Description

Adds a circular arc of the given radius to the current path. The arc is centered at (xc, yc), begins at angle1 and proceeds in the direction of decreasing angles to end at angle2. If angle2 is greater than angle1 it will be progressively decreased by 2*M_PI until it is less than angle1.

See arc() for more details. This function differs only in the direction of the arc between the two angles.

Parameter xc

X position of the center of the arc

Parameter yc

Y position of the center of the arc

Parameter radius

the radius of the arc

Parameter angle1

the start angle, in radians

Parameter angle2

the end angle, in radians

Method clip

voidclip()

Description

Establishes a new clip region by intersecting the current clip region with the current path as it would be filled by fill() and according to the current fill rule (see set_fill_rule()).

After clip(), the current path will be cleared from the cairo context.

The current clip region affects all drawing operations by effectively masking out any changes to the surface that are outside the current clip region.

Calling clip() can only make the clip region smaller, never larger. But the current clip is part of the graphics state, so a temporary restriction of the clip region can be achieved by calling clip() within a save()/restore() pair. The only other means of increasing the size of the clip region is reset_clip().

Method clip_extents: array(float) clip_extents()
Description: Computes a bounding box in user coordinates covering the area inside the current clip.
Returns: an array with coordinates for the left, top, right, and bottom, respectively, of the resulting extents

Method clip_preserve

voidclip_preserve()

Description

Establishes a new clip region by intersecting the current clip region with the current path as it would be filled by fill() and according to the current fill rule (see set_fill_rule()).

Unlike clip(), clip_preserve() preserves the path within the cairo context.

The current clip region affects all drawing operations by effectively masking out any changes to the surface that are outside the current clip region.

Calling clip_preserve() can only make the clip region smaller, never larger. But the current clip is part of the graphics state, so a temporary restriction of the clip region can be achieved by calling clip_preserve() within a save()/restore() pair. The only other means of increasing the size of the clip region is reset_clip().

Method close_path

voidclose_path()

Description

Adds a line segment to the path from the current point to the beginning of the current sub-path, (the most recent point passed to move_to()), and closes this sub-path. After this call the current point will be at the joined endpoint of the sub-path.

The behavior of close_path() is distinct from simply calling line_to() with the equivalent coordinate in the case of stroking. When a closed sub-path is stroked, there are no caps on the ends of the sub-path. Instead, there is a line join connecting the final and initial segments of the sub-path.

If there is no current point before the call to close_path(), this function will have no effect.

Method copy_clip_rectangle_list: array(Rectangle) copy_clip_rectangle_list()
Description: Gets the current clip region as a list of rectangles in user coordinates.
Returns: the current clip region as an array of rectangles in user coordinates.

Method copy_page

voidcopy_page()

Description

Emits the current page for backends that support multiple pages, but doesn't clear it, so, the contents of the current page will be retained for the next page too. Use show_page() if you want to get an empty page after the emission.

This is a convenience function that simply calls Surface->copy_page() on the context's target.

Method copy_path: Pathcopy_path()
Description: Creates a copy of the current path and returns it to the user as a Path.
Returns: the copy of the current path.

Method copy_path_flat

Pathcopy_path_flat()

Description

Gets a flattened copy of the current path and returns it to the user as a Path.

This function is like copy_path() except that any curves in the path will be approximated with piecewise-linear approximations, (accurate to within the current tolerance value).

Returns

the copy of the current path.

Method create: Cairo.ContextCairo.Context(Surfacetarget)
Description: Creates a new context with all graphics state parameters set to default values and with target as a target surface.
Parameter target: target surface for the context

Method curve_to

Description

Adds a cubic Bézier spline to the path from the current point to position (x3, y3) in user-space coordinates, using (x1, y1) and (x2, y2) as the control points. After this call the current point will be (x3, y3).

If there is no current point before the call to curve_to() this function will behave as if preceded by a call to move_to(x1, y1).

Parameter x1

the X coordinate of the first control point

Parameter y1

the Y coordinate of the first control point

Parameter x2

the X coordinate of the second control point

Parameter y2

the Y coordinate of the second control point

Parameter x3

the X coordinate of the end of the curve

Parameter y3

the Y coordinate of the end of the curve

Method device_to_user

array(float) device_to_user(float|intx, float|inty)

Description

Transform a coordinate from device space to user space by multiplying the given point by the inverse of the current transformation matrix (CTM).

Parameter x

X value of coordinate

Parameter y

Y value of coordinate

Returns

The transformed point

Array
`float0`	X position of the new point
`float1`	Y position of the new point

Method device_to_user_distance

array(float) device_to_user_distance(float|intdx, float|intdy)

Description

Transform a distance vector from device space to user space. This function is similar to device_to_user() except that the translation components of the inverse CTM will be ignored when transforming (dx, dy).

Parameter dx

X component of a distance vector (in/out parameter)

Parameter dy

Y component of a distance vector (in/out parameter)

Returns

The transformed distance vector

Array
`float0`	X component of the new distance vector
`float1`	Y component of the new distance vector

Method fill: voidfill()
Description: A drawing operator that fills the current path according to the current fill rule, (each sub-path is implicitly closed before being filled). After fill(), the current path will be cleared from the cairo context.
See also: set_fill_rule() and fill_preserve().

Method fill_extents

array(float) fill_extents()

Description

Computes a bounding box in user coordinates covering the area that would be affected, (the "inked" area), by a fill() operation given the current path and fill parameters. If the current path is empty, returns an empty rectangle ({0, 0, 0, 0}). Surface dimensions and clipping are not taken into account.

Contrast with path_extents(), which is similar, but returns non-zero extents for some paths with no inked area, (such as a simple line segment).

Note that fill_extents() must necessarily do more work to compute the precise inked areas in light of the fill rule, so path_extents() may be more desirable for sake of performance if the non-inked path extents are desired.

Returns

an array with coordinates for the left, top, right, and bottom, respectively, of the resulting extents

See also

fill(), set_fill_rule() and fill_preserve().

Method fill_preserve: voidfill_preserve()
Description: A drawing operator that fills the current path according to the current fill rule, (each sub-path is implicitly closed before being filled). Unlike fill(), fill_preserve() preserves the path within the cairo context.
See also: set_fill_rule() and fill().

Method font_extents

array(float) font_extents()

Description

Gets the font extents for the currently selected font.

Returns

an array which stores the retrieved extents:

Array
`float0`	ascent: the distance that the font extends above the baseline. Note that this is not always exactly equal to the maximum of the extents of all the glyphs in the font, but rather is picked to express the font designer's intent as to how the font should align with elements above it.
`float1`	descent: the distance that the font extends below the baseline. This value is positive for typical fonts that include portions below the baseline. Note that this is not always exactly equal to the maximum of the extents of all the glyphs in the font, but rather is picked to express the font designer's intent as to how the font should align with elements below it.
`float2`	height: the recommended vertical distance between baselines when setting consecutive lines of text with the font. This is greater than ascent + descent by a quantity known as the line spacing or external leading. When space is at a premium, most fonts can be set with only a distance of ascent + descent between lines.
`float3`	max_x_advance: the maximum distance in the X direction that the origin is advanced for any glyph in the font.
`float4`	max_y_advance: the maximum distance in the Y direction that the origin is advanced for any glyph in the font. This will be zero for normal fonts used for horizontal writing. (The scripts of East Asia are sometimes written vertically.)

Method get_antialias: intget_antialias()
Description: Gets the current shape antialiasing mode, as set by set_antialias().
Returns: the current shape antialiasing mode.

Method get_current_point

array(float) get_current_point()

Description

Gets the current point of the current path, which is conceptually the final point reached by the path so far.

The current point is returned in the user-space coordinate system. If there is no defined current point or if the context is in an error status, both returned coordinates will be 0.0. It is possible to check this in advance with has_current_point().

Returns

an array with the current x and y coordinates

Method get_dash: array(array(float)|float) get_dash()
Description: Gets the current dash array.
Returns: an array with two elements, the first is the dash array, and the second is the current dash offset

Method get_dash_count: intget_dash_count()
Description: This function returns the length of the dash array (0 if dashing is not currently in effect).
Returns: the length of the dash array, or 0 if no dash array set.
See also: set_dash() and get_dash().

Method get_fill_rule: intget_fill_rule()
Description: Gets the current fill rule, as set by set_fill_rule().
Returns: the current fill rule.

Method get_font_face: FontFaceget_font_face()
Description: Gets the current font face for a Context.
Returns: the current font face

Method get_font_matrix: Matrixget_font_matrix()
Description: Returns the current font matrix. See set_font_matrix().
Returns: the matrix

Method get_font_options: voidget_font_options(FontOptionsoptions)
Description: Retrieves font rendering options set via set_font_options(). Note that the returned options do not include any options derived from the underlying surface; they are literally the options passed to set_font_options().
Parameter options: a FontOptions object into which to store the retrieved options. All existing values are overwritten

Method get_group_target: Surfaceget_group_target()
Description: Gets the current destination surface for the context. This is either the original target surface or the target surface for the current group as started by the most recent call to push_group() or push_group_with_content().
Returns: the target surface.

Method get_hairline: boolget_hairline()
Description: Returns whether or not hairline mode is set, as set by set_hairline().
Returns: whether hairline mode is set.

Method get_line_cap: intget_line_cap()
Description: Gets the current line cap style, as set by set_line_cap().
Returns: the current line cap style.

Method get_line_join: intget_line_join()
Description: Gets the current line join style, as set by set_line_join().
Returns: the current line join style.

Method get_line_width: floatget_line_width()
Description: This function returns the current line width value exactly as set by set_line_width(). Note that the value is unchanged even if the CTM has changed between the calls to set_line_width() and get_line_width().
Returns: the current line width.

Method get_matrix: Matrixget_matrix()
Description: Returns the current transformation matrix (CTM).
Returns: the matrix

Method get_miter_limit: floatget_miter_limit()
Description: Gets the current miter limit, as set by set_miter_limit().
Returns: the current miter limit.

Method get_operator: intget_operator()
Description: Gets the current compositing operator for a cairo context.
Returns: the current compositing operator.

Method get_scaled_font: ScaledFontget_scaled_font()
Description: Gets the current scaled font for a Context.
Returns: the current scaled font.

Method get_source: Patternget_source()
Description: Gets the current source pattern.
Returns: the current source pattern.

Method get_target: Surfaceget_target()
Description: Gets the target surface for the cairo context
Returns: the target surface.

Method get_tolerance: floatget_tolerance()
Description: Gets the current tolerance value, as set by set_tolerance().
Returns: the current tolerance value.

Method glyph_extents

TextExtentsglyph_extents(array(Glyph|array(int|float)) glyphs)

Description

Gets the extents for an array of glyphs. The extents describe a user-space rectangle that encloses the "inked" portion of the glyphs, (as they would be drawn by show_glyphs(). Additionally, the x_advance and y_advance values indicate the amount by which the current point would be advanced by show_glyphs().

Note that whitespace glyphs do not contribute to the size of the rectangle (TextExtents->width and TextExtents->height).

Parameter glyphs

an array of glyph IDs with X and Y offsets, with each glyph being represented either as a Glyph object or as an array having the following format:

Array
`int0`	glyph index in the font. The exact interpretation of the glyph index depends on the font technology being used.
`float\|int1`	the offset in the X direction between the origin used for drawing the string and the origin of this glyph
`float\|int2`	the offset in the Y direction between the origin used for drawing the string and the origin of this glyph

Returns

a TextExtents object which stores the results.

Method glyph_path

voidglyph_path(array(Glyph|array(int|float)) glyphs)

Description

Adds closed paths for the glyphs to the current path. The generated path if filled, achieves an effect similar to that of show_glyphs().

Parameter glyphs

array of glyphs to show, with each glyph being represented either as a Glyph object or as an array of the following format:

Array
`int0`	glyph index in the font. The exact interpretation of the glyph index depends on the font technology being used.
`float\|int1`	the offset in the X direction between the origin used for drawing the string and the origin of this glyph
`float\|int2`	the offset in the Y direction between the origin used for drawing the string and the origin of this glyph

Method has_current_point: boolhas_current_point()
Description: Returns whether a current point is defined on the current path.
See also: get_current_point() for details on the current point.
Returns: whether a current point is defined.

Method identity_matrix: voididentity_matrix()
Description: Resets the current transformation matrix (CTM) by setting it equal to the identity matrix. That is, the user-space and device-space axes will be aligned and one user-space unit will transform to one device-space unit.

Method in_clip: boolin_clip(float|intx, float|inty)
Description: Tests whether the given point is inside the area that would be visible through the current clip, i.e. the area that would be filled by a paint() operation.
See also: clip(), and clip_preserve().
Parameter x: X coordinate of the point to test
Parameter y: Y coordinate of the point to test
Returns: A non-zero value if the point is inside, or zero if outside.

Method in_fill: boolin_fill(float|intx, float|inty)
Description: Tests whether the given point is inside the area that would be affected by a fill() operation given the current path and filling parameters. Surface dimensions and clipping are not taken into account.
Parameter x: X coordinate of the point to test
Parameter y: Y coordinate of the point to test
Returns: A non-zero value if the point is inside, or zero if outside.
See also: fill(), set_fill_rule() and fill_preserve().

Method in_stroke: boolin_stroke(float|intx, float|inty)
Description: Tests whether the given point is inside the area that would be affected by a stroke() operation given the current path and stroking parameters. Surface dimensions and clipping are not taken into account.
Parameter x: X coordinate of the point to test
Parameter y: Y coordinate of the point to test
Returns: A non-zero value if the point is inside, or zero if outside.
See also: stroke(), set_line_width(), set_line_join(), set_line_cap(), set_dash(), and stroke_preserve().

Method line_to

voidline_to(float|intx, float|inty)

Description

Adds a line to the path from the current point to position (x, y) in user-space coordinates. After this call the current point will be (x, y).

If there is no current point before the call to line_to() this function will behave as move_to(x, y).

Parameter x

the X coordinate of the end of the new line

Parameter y

the Y coordinate of the end of the new line

Method mask: voidmask(Patternpattern)
Description: A drawing operator that paints the current source using the alpha channel of pattern as a mask. (Opaque areas of pattern are painted with the source, transparent areas are not painted.)
Parameter pattern: a Pattern

Method mask_surface: voidmask_surface(Surfacesurface, float|intsurface_x, float|intsurface_y)
Description: A drawing operator that paints the current source using the alpha channel of surface as a mask. (Opaque areas of surface are painted with the source, transparent areas are not painted.)
Parameter surface: a Surface
Parameter surface_x: X coordinate at which to place the origin of surface
Parameter surface_y: Y coordinate at which to place the origin of surface

Method move_to: voidmove_to(float|intx, float|inty)
Description: Begin a new sub-path. After this call the current point will be (x, y).
Parameter x: the X coordinate of the new position
Parameter y: the Y coordinate of the new position

Method new_path: voidnew_path()
Description: Clears the current path. After this call there will be no path and no current point.

Method new_sub_path

voidnew_sub_path()

Description

Begin a new sub-path. Note that the existing path is not affected. After this call there will be no current point.

In many cases, this call is not needed since new sub-paths are frequently started with move_to().

A call to new_sub_path() is particularly useful when beginning a new sub-path with one of the arc() calls. This makes things easier as it is no longer necessary to manually compute the arc's initial coordinates for a call to move_to().

Method paint: voidpaint()
Description: A drawing operator that paints the current source everywhere within the current clip region.

Method paint_with_alpha: voidpaint_with_alpha(floatalpha)
Description: A drawing operator that paints the current source everywhere within the current clip region using a mask of constant alpha value alpha . The effect is similar to paint(), but the drawing is faded out using the alpha value.
Parameter alpha: alpha value, between 0 (transparent) and 1 (opaque)

Method path_extents

array(float) path_extents()

Description

Computes a bounding box in user-space coordinates covering the points on the current path. If the current path is empty, returns an empty rectangle ({0, 0, 0, 0}). Stroke parameters, fill rule, surface dimensions and clipping are not taken into account.

Contrast with fill_extents() and stroke_extents() which return the extents of only the area that would be "inked" by the corresponding drawing operations.

Returns

an array with coordinates for the left, top, right, and bottom, respectively, of the resulting extents

Method pop_group

Patternpop_group()

Description

Terminates the redirection begun by a call to push_group() or push_group_with_content() and returns a new pattern containing the results of all drawing operations performed to the group.

The pop_group() function calls restore(), (balancing a call to save() by the push_group function), so that any changes to the graphics state will not be visible outside the group.

Returns

a newly created (surface) pattern containing the results of all drawing operations performed to the group.

Method pop_group_to_source

voidpop_group_to_source()

Description

Terminates the redirection begun by a call to push_group() or push_group_with_content() and installs the resulting pattern as the source pattern in the given cairo context.

The pop_group() function calls restore(), (balancing a call to save() by the push_group function), so that any changes to the graphics state will not be visible outside the group.

Method push_group

voidpush_group()

Description

Temporarily redirects drawing to an intermediate surface known as a group. The redirection lasts until the group is completed by a call to pop_group() or pop_group_to_source(). These calls provide the result of any drawing to the group as a pattern, (either as an explicit object, or set as the source pattern).

This group functionality can be convenient for performing intermediate compositing. One common use of a group is to render objects as opaque within the group, (so that they occlude each other), and then blend the result with translucence onto the destination.

Groups can be nested arbitrarily deep by making balanced calls to push_group()/pop_group(). Each call pushes/pops the new target group onto/from a stack.

The push_group() function calls save() so that any changes to the graphics state will not be visible outside the group, (the pop_group functions call restore()).

By default the intermediate group will have a content type of CONTENT_COLOR_ALPHA. Other content types can be chosen for the group by using push_group_with_content() instead.

Method push_group_with_content

voidpush_group_with_content(intcontent)

Description

The group will have a content type of content. The ability to control this content type is the only distinction between this function and push_group() which you should see for a more detailed description of group rendering.

Parameter content

the type of group that will be created

Method rectangle: voidrectangle(float|intx, float|inty, float|intwidth, float|intheight)
Description: Adds a closed sub-path rectangle of the given size to the current path at position (x, y) in user-space coordinates.
Parameter x: the X coordinate of the top left corner of the rectangle
Parameter y: the Y coordinate to the top left corner of the rectangle
Parameter width: the width of the rectangle
Parameter height: the height of the rectangle

Method rel_curve_to

Description

Relative-coordinate version of curve_to(). All offsets are relative to the current point. Adds a cubic Bézier spline to the path from the current point to a point offset from the current point by (dx3, dy3), using points offset by (dx1, dy1) and (dx2, dy2) as the control points. After this call the current point will be offset by (dx3, dy3).

Given a current point of (x, y), rel_curve_to(dx1, dy1, dx2, dy2, dx3, dy3) is logically equivalent to curve_to(x+dx1, y+dy1, x+dx2, y+dy2, x+dx3, y+dy3).

It is an error to call this function with no current point.

Parameter dx1

the X offset to the first control point

Parameter dy1

the Y offset to the first control point

Parameter dx2

the X offset to the second control point

Parameter dy2

the Y offset to the second control point

Parameter dx3

the X offset to the end of the curve

Parameter dy3

the Y offset to the end of the curve

Method rel_line_to

voidrel_line_to(float|intdx, float|intdy)

Description

Relative-coordinate version of line_to(). Adds a line to the path from the current point to a point that is offset from the current point by (dx, dy) in user space. After this call the current point will be offset by (dx, dy).

Given a current point of (x, y), rel_line_to(dx, dy) is logically equivalent to line_to(x + dx , y + dy).

It is an error to call this function with no current point.

Parameter dx

the X offset to the end of the new line

Parameter dy

the Y offset to the end of the new line

Method rel_move_to

voidrel_move_to(float|intdx, float|intdy)

Description

Begin a new sub-path. After this call the current point will offset by (x, y).

Given a current point of (x, y), rel_move_to(dx , dy) is logically equivalent to move_to(x + dx , y + dy).

It is an error to call this function with no current point.

Parameter dx

the X offset

Parameter dy

the Y offset

Method reset_clip

voidreset_clip()

Description

Reset the current clip region to its original, unrestricted state. That is, set the clip region to an infinitely large shape containing the target surface. Equivalently, if infinity is too hard to grasp, one can imagine the clip region being reset to the exact bounds of the target surface.

Note that code meant to be reusable should not call reset_clip() as it will cause results unexpected by higher-level code which calls clip(). Consider using save() and restore() around clip() as a more robust means of temporarily restricting the clip region.

Method restore: voidrestore()
Description: Restores to the state saved by a preceding call to save() and removes that state from the stack of saved states.

Method rotate: voidrotate(floatangle)
Description: Modifies the current transformation matrix (CTM) by rotating the user-space axes by angle radians. The rotation of the axes takes places after any existing transformation of user space. The rotation direction for positive angles is from the positive X axis toward the positive Y axis.
Parameter angle: angle (in radians) by which the user-space axes will be rotated

Method save: voidsave()
Description: Makes a copy of the current state and saves it on an internal stack of saved states. When restore() is called, the context will be restored to the saved state. Multiple calls to save() and restore() can be nested; each call to restore() restores the state from the matching paired save().

Method scale: voidscale(float|intsx, float|intsy)
Description: Modifies the current transformation matrix (CTM) by scaling the X and Y user-space axes by sx and sy respectively. The scaling of the axes takes place after any existing transformation of user space.
Parameter sx: scale factor for the X dimension
Parameter sy: scale factor for the Y dimension

Method select_font_face

voidselect_font_face(stringfamily, intslant, intweight)

Note

The select_font_face() function call is part of what the cairo designers call the "toy" text API. It is convenient for short demos and simple programs, but it is not expected to be adequate for serious text-using applications.

Selects a family and style of font from a simplified description as a family name, slant and weight. Cairo provides no operation to list available family names on the system (this is a "toy", remember), but the standard CSS2 generic family names, ("serif", "sans-serif", "cursive", "fantasy", "monospace"), are likely to work as expected.

If family starts with the string "@cairo:", or if no native font backends are compiled in, cairo will use an internal font family. The internal font family recognizes many modifiers in the family string, most notably, it recognizes the string "monospace". That is, the family name "@cairo:monospace" will use the monospace version of the internal font family.

For "real" font selection, see the font-backend-specific font_face_create functions for the font backend you are using. The resulting font face could then be used with scaled_font_create() and set_scaled_font().

If text is drawn without a call to select_font_face(), (nor set_font_face() nor set_scaled_font()), the default family is platform-specific, but is essentially "sans-serif". Default slant is FONT_SLANT_NORMAL, and default weight is FONT_WEIGHT_NORMAL.

This function is equivalent to a call to toy_font_face_create() followed by set_font_face().

Parameter family

a font family name

Parameter slant

the slant for the font

Parameter weight

the weight for the font

Method set_antialias

voidset_antialias(intantialias)

Description

Set the antialiasing mode of the rasterizer used for drawing shapes. This value is a hint, and a particular backend may or may not support a particular value. At the current time, no backend supports ANTIALIAS_SUBPIXEL when drawing shapes.

Note that this option does not affect text rendering, instead see FontOptions->set_antialias().

Parameter antialias

the new antialiasing mode

Method set_dash

voidset_dash(array(float|int) dashes, float|intoffset)

Description

Sets the dash pattern to be used by stroke(). A dash pattern is specified by dashes, an array of positive values. Each value provides the length of alternate "on" and "off" portions of the stroke. The offset specifies an offset into the pattern at which the stroke begins.

Each "on" segment will have caps applied as if the segment were a separate sub-path. In particular, it is valid to use an "on" length of 0.0 with LINE_CAP_ROUND or LINE_CAP_SQUARE in order to distributed dots or squares along a path.

Note

The length values are in user-space units as evaluated at the time of stroking. This is not necessarily the same as the user space at the time of set_dash().

If dashes is empty dashing is disabled.

If dashes contains a single value a symmetric pattern is assumed with alternating on and off portions of the size specified by the value.

Parameter dashes

an array specifying alternate lengths of on and off stroke portions

Parameter offset

an offset into the dash pattern at which the stroke should start

Method set_fill_rule

voidset_fill_rule(intfill_rule)

Description

Set the current fill rule within the cairo context. The fill rule is used to determine which regions are inside or outside a complex (potentially self-intersecting) path. The current fill rule affects both fill() and clip().

The default fill rule is FILL_RULE_WINDING.

Parameter fill_rule

a fill rule

Method set_font_face: voidset_font_face(FontFace|zerofont_face)
Description: Replaces the current FontFace object in the Context with font_face.
Parameter font_face: a FontFace, or 0 to restore to the default font

Method set_font_matrix: voidset_font_matrix(Matrixmatrix)
Description: Sets the current font matrix to matrix. The font matrix gives a transformation from the design space of the font (in this space, the em-square is 1 unit by 1 unit) to user space. Normally, a simple scale is used (see set_font_size()), but a more complex font matrix can be used to shear the font or stretch it unequally along the two axes
Parameter matrix: a Matrix describing a transform to be applied to the current font.

Method set_font_options: voidset_font_options(FontOptionsoptions)
Description: Sets a set of custom font rendering options for the Context. Rendering options are derived by merging these options with the options derived from underlying surface; if the value in options has a default value (like ANTIALIAS_DEFAULT), then the value from the surface is used.
Parameter options: font options to use

Method set_font_size

voidset_font_size(float|intsize)

Description

Sets the current font matrix to a scale by a factor of size, replacing any font matrix previously set with set_font_size() or set_font_matrix(). This results in a font size of size user space units. (More precisely, this matrix will result in the font's em-square being a size by size square in user space.)

If text is drawn without a call to set_font_size(), (nor set_font_matrix() nor set_scaled_font()), the default font size is 10.0.

Parameter size

the new font size, in user space units

Method set_hairline

voidset_hairline(boolset_hairline)

Description

Sets lines within the cairo context to be hairlines. Hairlines are logically zero-width lines that are drawn at the thinnest renderable width possible in the current context.

On surfaces with native hairline support, the native hairline functionality will be used. Surfaces that support hairlines include:

pdf/ps: Encoded as 0-width line. win32_printing: Rendered with PS_COSMETIC pen. svg: Encoded as 1px non-scaling-stroke. script: Encoded with set-hairline function.

Cairo will always render hairlines at 1 device unit wide, even if an anisotropic scaling was applied to the stroke width. In the wild, handling of this situation is not well-defined. Some PDF, PS, and SVG renderers match Cairo's output, but some very popular implementations (Acrobat, Chrome, rsvg) will scale the hairline unevenly. As such, best practice is to reset any anisotropic scaling before calling stroke().

Parameter set_hairline

whether or not to set hairline mode

Method set_line_cap

voidset_line_cap(intline_cap)

Description

Sets the current line cap style within the cairo context.

As with the other stroke parameters, the current line cap style is examined by stroke(), and stroke_extents(), but does not have any effect during path construction.

The default line cap style is LINE_CAP_BUTT.

Parameter line_cap

a line cap style

Method set_line_join

voidset_line_join(intline_join)

Description

Sets the current line join style within the cairo context.

As with the other stroke parameters, the current line join style is examined by stroke(), and stroke_extents(), but does not have any effect during path construction.

The default line join style is LINE_JOIN_MITER.

Parameter line_join

a line join style

Method set_line_width

voidset_line_width(float|intwidth)

Description

Sets the current line width. The line width value specifies the diameter of a pen that is circular in user space.

As with the other stroke parameters, the current line width is examined by stroke(), and stroke_extents(), but does not have any effect during path construction.

The default line width value is 2.0.

Parameter width

a line width

Method set_matrix: voidset_matrix(Matrixmatrix)
Description: Modifies the current transformation matrix (CTM) by setting it equal to matrix.
Parameter matrix: a transformation matrix from user space to device space

Method set_miter_limit

voidset_miter_limit(float|intlimit)

Description

Sets the current miter limit within the cairo context.

If the current line join style is set to LINE_JOIN_MITER (see set_line_join()), the miter limit is used to determine whether the lines should be joined with a bevel instead of a miter. Cairo divides the length of the miter by the line width. If the result is greater than the miter limit, the style is converted to a bevel.

As with the other stroke parameters, the current line miter limit is examined by stroke(), and stroke_extents(), but does not have any effect during path construction.

The default miter limit value is 10.0, which will convert joins with interior angles less than 11 degrees to bevels instead of miters. For reference, a miter limit of 2.0 makes the miter cutoff at 60 degrees, and a miter limit of 1.414 makes the cutoff at 90 degrees.

A miter limit for a desired angle can be computed as: miter limit = 1/sin(angle/2)

Parameter limit

miter limit to set

Method set_operator

voidset_operator(intop)

Description

Sets the compositing operator to be used for all drawing operations.

The default operator is OPERATOR_OVER.

Parameter op

a compositing operator

Method set_scaled_font: voidset_scaled_font(ScaledFontscaled_font)
Description: Replaces the current font face, font matrix, and font options in the Context with those of the ScaledFont. Except for some translation, the current CTM of the Context should be the same as that of the ScaledFont, which can be accessed using ScaledFont->get_ctm().
Parameter scaled_font: a ScaledFont

Method set_source

voidset_source(Patternsource)

Description

Sets the source pattern to source. This pattern will then be used for any subsequent drawing operation until a new source pattern is set.

Note

The pattern's transformation matrix will be locked to the user space in effect at the time of set_source(). This means that further modifications of the current transformation matrix will not affect the source pattern. See Pattern->set_matrix().

The default source pattern is a solid pattern that is opaque black, (that is, it is equivalent to set_source_rgb(0.0, 0.0, 0.0)).

Parameter source

a Pattern to be used as the source for subsequent drawing operations.

Method set_source_rgb

voidset_source_rgb(floatred, floatgreen, floatblue)

Description

Sets the source pattern to an opaque color. This opaque color will then be used for any subsequent drawing operation until a new source pattern is set.

The color components are floating point numbers in the range 0 to 1. If the values passed in are outside that range, they will be clamped.

The default source pattern is opaque black, (that is, it is equivalent to set_source_rgb(0.0, 0.0, 0.0)).

Parameter red

red component of color

Parameter green

green component of color

Parameter blue

blue component of color

Method set_source_rgba

voidset_source_rgba(floatred, floatgreen, floatblue, floatalpha)

Description

Sets the source pattern to a translucent color. This color will then be used for any subsequent drawing operation until a new source pattern is set.

The color and alpha components are floating point numbers in the range 0 to 1. If the values passed in are outside that range, they will be clamped.

Note that the color and alpha values are not premultiplied.

The default source pattern is opaque black, (that is, it is equivalent to set_source_rgba(0.0, 0.0, 0.0, 1.0)).

Parameter red

red component of color

Parameter green

green component of color

Parameter blue

blue component of color

Parameter alpha

alpha component of color

Method set_source_surface

voidset_source_surface(Surfacesurface, float|intx, float|inty)

Description

This is a convenience function for creating a pattern from surface and setting it as the source with set_source().

The x and y parameters give the user-space coordinate at which the surface origin should appear. (The surface origin is its upper-left corner before any transformation has been applied.) The x and y parameters are negated and then set as translation values in the pattern matrix.

Other than the initial translation pattern matrix, as described above, all other pattern attributes, (such as its extend mode), are set to the default values as in Pattern->create(). The resulting pattern can be queried with get_source() so that these attributes can be modified if desired, (eg. to create a repeating pattern with Pattern->set_extend()).

Parameter surface

a surface to be used to set the source pattern

Parameter x

User-space X coordinate for surface origin

Parameter y

User-space Y coordinate for surface origin

Method set_tolerance: voidset_tolerance(float|inttolerance)
Description: Sets the tolerance used when converting paths into trapezoids. Curved segments of the path will be subdivided until the maximum deviation between the original path and the polygonal approximation is less than tolerance. The default value is 0.1. A larger value will give better performance, a smaller value, better appearance. (Reducing the value from the default value of 0.1 is unlikely to improve appearance significantly.) The accuracy of paths within Cairo is limited by the precision of its internal arithmetic, and the prescribed tolerance is restricted to the smallest representable internal value.
Parameter tolerance: the tolerance, in device units (typically pixels)

Method show_glyphs

voidshow_glyphs(array(Glyph|array(int|float)) glyphs)

Description

A drawing operator that generates the shape from an array of glyphs, rendered according to the current font face, font size (font matrix), and font options.

Parameter glyphs

array of glyphs to show, with each glyph being represented either as a Glypg object or as an array of the following format:

Array
`int0`	glyph index in the font. The exact interpretation of the glyph index depends on the font technology being used.
`float\|int1`	the offset in the X direction between the origin used for drawing the string and the origin of this glyph
`float\|int2`	the offset in the Y direction between the origin used for drawing the string and the origin of this glyph

Method show_page

voidshow_page()

Description

Emits and clears the current page for backends that support multiple pages. Use copy_page() if you don't want to clear the page.

This is a convenience function that simply calls Surface->show_page() on the context's target.

Method show_text

voidshow_text(string|zerotext)

Description

A drawing operator that generates the shape from a string of characters, rendered according to the current font_face, font_size (font_matrix), and font_options.

This function first computes a set of glyphs for the string of text. The first glyph is placed so that its origin is at the current point. The origin of each subsequent glyph is offset from that of the previous glyph by the advance values of the previous glyph.

After this call the current point is moved to the origin of where the next glyph would be placed in this same progression. That is, the current point will be at the origin of the final glyph offset by its advance values. This allows for easy display of a single logical string with multiple calls to show_text().

Note

The show_text() function call is part of what the cairo designers call the "toy" text API. It is convenient for short demos and simple programs, but it is not expected to be adequate for serious text-using applications. See show_glyphs() for the "real" text display API in cairo.

Parameter text

a string of text, or 0

Method show_text_glyphs

voidshow_text_glyphs(stringtext, array(Glyph|array(int|float)) glyphs, array(TextCluster) clusters, intcluster_flags)

Description

This operation has rendering effects similar to show_glyphs() but, if the target surface supports it, uses the provided text and cluster mapping to embed the text for the glyphs shown in the output. If the target does not support the extended attributes, this function acts like the basic show_glyphs() as if it had been passed glyphs.

The mapping between text and glyphs is provided by an array of clusters. Each cluster covers a number of text bytes and glyphs, and neighboring clusters cover neighboring areas of text and glyphs. The clusters should collectively cover text and glyphs in entirety.

The first cluster always covers bytes from the beginning of text. If cluster_flags do not have the flag TEXT_CLUSTER_FLAG_BACKWARD set, the first cluster also covers the beginning of glyphs, otherwise it covers the end of the glyphs array and following clusters move backward.

See TextCluster for constraints on valid clusters.

Parameter text

a string of text

Parameter glyphs

array of glyphs to show

Parameter clusters

array of cluster mapping information

Parameter cluster_flags

cluster mapping flags

Method stroke: voidstroke()
Description: A drawing operator that strokes the current path according to the current line width, line join, line cap, and dash settings. After stroke(), the current path will be cleared from the context.
See also: set_line_width(), set_line_join(), set_line_cap(), set_dash(), and stroke_preserve().

Method stroke_extents

array(float) stroke_extents()

Description

Computes a bounding box in user coordinates covering the area that would be affected, (the "inked" area), by a stroke() operation given the current path and stroke parameters. If the current path is empty, returns an empty rectangle ({0, 0, 0, 0}). Surface dimensions and clipping are not taken into account.

Note that if the line width is set to exactly zero, then stroke_extents() will return an empty rectangle. Contrast with path_extents() which can be used to compute the non-empty bounds as the line width approaches zero.

Note that stroke_extents() must necessarily do more work to compute the precise inked areas in light of the stroke parameters, so path_extents() may be more desirable for sake of performance if non-inked path extents are desired.

Returns

an array with coordinates for the left, top, right, and bottom, respectively, of the resulting extents

See also

stroke(), set_line_width(), set_line_join(), set_line_cap(), set_dash(), and stroke_preserve().

Method stroke_preserve: voidstroke_preserve()
Description: A drawing operator that strokes the current path according to the current line width, line join, line cap, and dash settings. Unlike stroke(), stroke_preserve() preserves the path within the cairo context.
See also: set_line_width(), set_line_join(), set_line_cap(), set_dash(), and stroke_preserve().

Method tag_begin

voidtag_begin(stringtag_name, string|voidattributes)

Description

Marks the beginning of the tag_name structure. Call ddtag_end() with the same tag_name to mark the end of the structure.

The attributes string is of the form "key1=value2 key2=value2 ...". Values may be boolean (true/false or 1/0), integer, float, string, or an array.

String values are enclosed in single quotes ('). Single quotes and backslashes inside the string should be escaped with a backslash.

Boolean values may be set to true by only specifying the key. eg the attribute string "key" is the equivalent to "key=true".

Arrays are enclosed in '[]'. eg "rect=[1.2 4.3 2.0 3.0]".

If no attributes are required, attributes can be an empty string or omitted.

See also

tag_end()

Parameter tag_name

tag name

Parameter attributes

tag attributes

Method tag_end: voidtag_end(stringtag_name)
Description: Marks the end of the tag_name structure.
See also: tag_begin().
Parameter tag_name: tag name

Method text_extents

TextExtentstext_extents(string|zerotext)

Description

Gets the extents for a string of text. The extents describe a user-space rectangle that encloses the "inked" portion of the text, (as it would be drawn by show_text()). Additionally, the x_advance and y_advance values indicate the amount by which the current point would be advanced by show_text().

Note that whitespace characters do not directly contribute to the size of the rectangle (TextExtents->width and TextExtents->height). They do contribute indirectly by changing the position of non-whitespace characters. In particular, trailing whitespace characters are likely to not affect the size of the rectangle, though they will affect the x_advance and y_advance values.

Parameter text

a string of text, or 0

Returns

a TextExtents object which stores the results.

Method text_path

voidtext_path(string|zerotext)

Description

Adds closed paths for text to the current path. The generated path if filled, achieves an effect similar to that of show_text().

Text conversion and positioning is done similar to show_text().

Like show_text(), After this call the current point is moved to the origin of where the next glyph would be placed in this same progression. That is, the current point will be at the origin of the final glyph offset by its advance values. This allows for chaining multiple calls to to text_path() without having to set current point in between.

Parameter text

a string of text, or 0

Method transform: voidtransform(Matrixmatrix)
Description: Modifies the current transformation matrix (CTM) by applying matrix as an additional transformation. The new transformation of user space takes place after any existing transformation.
Parameter matrix: a transformation to be applied to the user-space axes

Method translate: voidtranslate(float|inttx, float|intty)
Description: Modifies the current transformation matrix (CTM) by translating the user-space origin by (tx, ty). This offset is interpreted as a user-space coordinate according to the CTM in place before the new call to translate(). In other words, the translation of the user-space origin takes place after any existing transformation.
Parameter tx: amount to translate in the X direction
Parameter ty: amount to translate in the Y direction

Method user_to_device

array(float) user_to_device(float|intx, float|inty)

Description

Transform a coordinate from user space to device space by multiplying the given point by the current transformation matrix (CTM).

Parameter x

X value of coordinate

Parameter y

Y value of coordinate

Returns

The transformed point

Array
`float0`	X position of the new point
`float1`	Y position of the new point

Method user_to_device_distance

array(float) user_to_device_distance(float|intdx, float|intdy)

Description

Transform a distance vector from user space to device space. This function is similar to user_to_device() except that the translation components of the CTM will be ignored when transforming (dx, dy).

Parameter dx

X component of a distance vector

Parameter dy

Y component of a distance vector

Returns

The transformed distance vector

Array
`float0`	X component of the new distance vector
`float1`	Y component of the new distance vector

Class Cairo.Device

Description: interface to underlying rendering system

Method `==: bool res = Cairo.Device() == x
Returns: Returns 1 if x is the same Device, and 0 (zero) otherwise.

Method acquire

voidacquire()

Description

Acquires the device for the current thread. This function will block until no other thread has acquired the device.

From now on your thread owns the device and no other thread will be able to acquire it until a matching call to release(). It is allowed to recursively acquire the device multiple times from the same thread.

You must never acquire two different devices at the same time unless this is explicitly allowed. Otherwise the possibility of deadlocks exist. As various Cairo functions can acquire devices when called, these functions may also cause deadlocks when you call them with an acquired device. So you must not have a device acquired when calling them. These functions are marked in the documentation.

After a successful call to acquire(), a matching call to release() is required.

Method finish

voidfinish()

Description

This function finishes the device and drops all references to external resources. All surfaces, fonts and other objects created for this device will be finished, too. Further operations on the device will not affect the device but will instead trigger a STATUS_DEVICE_FINISHED error.

When the reference count of a Device drops to zero, cairo will call finish() if it hasn't been called already, before freeing the resources associated with the device.

This function may acquire devices.

Method flush

voidflush()

Description

Finish any pending operations for the device and also restore any temporary modifications cairo has made to the device's state. This function must be called before switching from using the device with Cairo to operating on it directly with native APIs. If the device doesn't support direct access, then this function does nothing.

This function may acquire devices.

Method observer_elapsed: floatobserver_elapsed()
Description: Returns the total elapsed time of the observation.
Returns: the elapsed time, in nanoseconds.

Method observer_fill_elapsed: floatobserver_fill_elapsed()
Description: Returns the elapsed time of the fill operations.
Returns: the elapsed time, in nanoseconds.

Method observer_glyphs_elapsed: floatobserver_glyphs_elapsed()
Description: Returns the elapsed time of the glyph operations.
Returns: the elapsed time, in nanoseconds.

Method observer_mask_elapsed: floatobserver_mask_elapsed()
Description: Returns the elapsed time of the mask operations.
Returns: the elapsed time, in nanoseconds

Method observer_paint_elapsed: floatobserver_paint_elapsed()
Description: Returns the elapsed time of the paint operations.
Returns: the elapsed time, in nanoseconds.

Method observer_print: voidobserver_print(Stdio.OutputStreamMixinstream)
Description: Prints the device log to the given output stream
Parameter stream: the output stream

Method observer_stroke_elapsed: floatobserver_stroke_elapsed()
Description: Returns the elapsed time of the stroke operations.
Returns: the elapsed time, in nanoseconds.

Method release: voidrelease()
Description: Releases a device previously acquired using acquire(). See that function for details.

Class Cairo.Error

Description: Error object used for Cairo errors.

Inherit Generic: inherit Error.Generic : Generic

Constant is_cairo_error
Constant error_type: constantint Cairo.Error.is_cairo_error
constantstring Cairo.Error.error_type
Description: Object recognition constants.

Variable status: int Cairo.Error.status
Description: The numeric status code (STATUS_xxx)

Class Cairo.FontFace

Description: FontFace represents a particular font at a particular weight, slant, and other characteristic but no size, transformation, or size.

Method `==: bool res = Cairo.FontFace() == x
Returns: Returns 1 if x is the same FontFace, and 0 (zero) otherwise.

Class Cairo.FontOptions

Description: The font options specify how fonts should be rendered. Most of the time the font options implied by a surface are just right and do not need any changes, but for pixel-based targets tweaking font options may result in superior output on a particular display.

Method `==: bool res = Cairo.FontOptions() == x
Returns: Returns 1 if all fields of the two font options objects match and 0 (zero) otherwise. Note that this function will return 0 if either object is in error.

Method create: Cairo.FontOptionsCairo.FontOptions(FontOptions|voidoriginal)
Description: Allocates a new font options object with all options initialized either to default values, or to values taken from original.
Parameter original: If specified, a set of font options to copy

Method get_antialias: intget_antialias()
Description: Gets the antialiasing mode for the font options object.
Returns: the antialiasing mode

Method get_color_mode: intget_color_mode()
Description: Gets the color mode for the font options object.
Returns: the color mode for the font options object

Method get_color_palette: int(0..)get_color_palette()
Description: Gets the current OpenType color font palette for the font options object.
Returns: the palette index

Method get_custom_palette_color

array(float) get_custom_palette_color(int(0..)index)

Description

Gets the custom palette color for the color index for the font options object.

Parameter index

the index of the color to get

Returns

An array with the components of the color

Array
`float0`	red component of color
`float1`	green component of color
`float2`	blue component of color
`float3`	alpha component of color

Method get_hint_metrics: intget_hint_metrics()
Description: Gets the metrics hinting mode for the font options object.
Returns: the metrics hinting mode for the font options object

Method get_hint_style: intget_hint_style()
Description: Gets the hint style for font outlines for the font options object.
Returns: the hint style for the font options object

Method get_subpixel_order: intget_subpixel_order()
Description: Gets the subpixel order for the font options object.
Returns: the subpixel order for the font options object

Method get_variations: string(7bit)|zeroget_variations()
Description: Gets the OpenType font variations for the font options object. See set_variations() for details about the string format.
Returns: the font variations for the font options object.

Method merge: voidmerge(FontOptionsother)
Description: Merges non-default options from other into options, replacing existing values. This operation can be thought of as somewhat similar to compositing other onto options with the operation of OPERATOR_OVER.
Parameter other: another FontOptions

Method set_antialias: voidset_antialias(intantialias)
Description: Sets the antialiasing mode for the font options object. This specifies the type of antialiasing to do when rendering text.
Parameter antialias: the new antialiasing mode

Method set_color_mode: voidset_color_mode(intcolor_mode)
Description: Sets the color mode for the font options object. This controls whether color fonts are to be rendered in color or as outlines.
Parameter color_mode: the new color mode

Method set_color_palette

voidset_color_palette(int(0..)palette_index)

Description

Sets the OpenType font color palette for the font options object. OpenType color fonts with a CPAL table may contain multiple palettes. The default color palette index is COLOR_PALETTE_DEFAULT.

If palette_index is invalid, the default palette is used.

Individual colors within the palette may be overriden with set_custom_palette_color().

Parameter palette_index

the palette index in the CPAL table

Method set_custom_palette_color

voidset_custom_palette_color(int(0..)index, floatred, floatgreen, floatblue, floatalpha)

Description

Sets a custom palette color for the font options object. This overrides the palette color at the specified color index. This override is independent of the selected palette index and will remain in place even if set_color_palette() is called to change the palette index.

It is only possible to override color indexes already in the font palette.

Parameter index

the index of the color to set

Parameter red

red component of color

Parameter green

green component of color

Parameter blue

blue component of color

Parameter alpha

alpha component of color

Method set_hint_metrics: voidset_hint_metrics(inthint_metrics)
Description: Sets the metrics hinting mode for the font options object. This controls whether metrics are quantized to integer values in device units.
Parameter hint_metrics: the new metrics hinting mode

Method set_hint_style: voidset_hint_style(inthint_style)
Description: Sets the hint style for font outlines for the font options object. This controls whether to fit font outlines to the pixel grid, and if so, whether to optimize for fidelity or contrast.
Parameter hint_style: the new hint style

Method set_subpixel_order: voidset_subpixel_order(intsubpixel_order)
Description: Sets the subpixel order for the font options object. The subpixel order specifies the order of color elements within each pixel on the display device when rendering with an antialiasing mode of ANTIALIAS_SUBPIXEL.
Parameter subpixel_order: the new subpixel order

Method set_variations

voidset_variations(string(7bit)|zerovariations)

Description

Sets the OpenType font variations for the font options object. Font variations are specified as a string with a format that is similar to the CSS font-variation-settings. The string contains a comma-separated list of axis assignments, which each assignment consists of a 4-character axis name and a value, separated by whitespace and optional equals sign.

Example

wght=200,wdth=140.5
wght 200 , wdth 140.5

Parameter variations

the new font variations, or 0

Class Cairo.Glyph

Description

Holds information about a single glyph when drawing or measuring text. A font is (in simple terms) a collection of shapes used to draw text. A glyph is one of these shapes. There can be multiple glyphs for a single character (alternates to be used in different contexts, for example), or a glyph can be a ligature of multiple characters. Cairo doesn't expose any way of converting input text into glyphs, so in order to use the Cairo interfaces that take arrays of glyphs, you must directly access the appropriate underlying font system.

Note that the offsets given by x and y are not cumulative. When drawing or measuring text, each glyph is individually positioned with respect to the overall origin

Variable index: int(0..) Cairo.Glyph.index
Description: glyph index in the font. The exact interpretation of the glyph index depends on the font technology being used.

Variable x: float Cairo.Glyph.x
Description: the offset in the X direction between the origin used for drawing or measuring the string and the origin of this glyph.

Variable y: float Cairo.Glyph.y
Description: the offset in the Y direction between the origin used for drawing or measuring the string and the origin of this glyph.

Method _sprintf: stringsprintf(stringformat, ... Cairo.Glypharg ... )

Method create: Cairo.GlyphCairo.Glyph(int(0..)index, float|int|voidx, float|int|voidy)
Parameter index: glyph index in the font. The exact interpretation of the glyph index depends on the font technology being used.
Parameter x: the offset in the X direction between the origin used for drawing or measuring the string and the origin of this glyph.
Parameter y: the offset in the Y direction between the origin used for drawing or measuring the string and the origin of this glyph.

Class Cairo.Gradient

Description: A gradient.

Inherit Pattern: inherit Pattern : Pattern

Method add_color_stop_rgb

voidadd_color_stop_rgb(floatoffset, floatred, floatgreen, floatblue)

Description

Adds an opaque color stop to a gradient pattern. The offset specifies the location along the gradient's control vector. For example, a linear gradient's control vector is from (x0,y0) to (x1,y1) while a radial gradient's control vector is from any point on the start circle to the corresponding point on the end circle.

The color is specified in the same way as in Context->set_source_rgb().

If two (or more) stops are specified with identical offset values, they will be sorted according to the order in which the stops are added, (stops added earlier will compare less than stops added later). This can be useful for reliably making sharp color transitions instead of the typical blend.

Parameter offset

an offset in the range [0.0 .. 1.0]

Parameter red

red component of color

Parameter green

green component of color

Parameter blue

blue component of color

Method add_color_stop_rgba

voidadd_color_stop_rgba(floatoffset, floatred, floatgreen, floatblue, floatalpha)

Description

Adds a translucent color stop to a gradient pattern. The offset specifies the location along the gradient's control vector. For example, a linear gradient's control vector is from (x0,y0) to (x1,y1) while a radial gradient's control vector is from any point on the start circle to the corresponding point on the end circle.

The color is specified in the same way as in Context->set_source_rgba().

Parameter offset

an offset in the range [0.0 .. 1.0]

Parameter red

red component of color

Parameter green

green component of color

Parameter blue

blue component of color

Parameter alpha

alpha component of color

Method get_color_stop_count: intget_color_stop_count()
Description: Gets the number of color stops specified in the gradient pattern.
Returns: the number of color stops

Method get_color_stop_rgba

array(float) get_color_stop_rgba(intindex)

Description

Gets the color and offset information at the given index for a gradient pattern. Values of index range from 0 to n-1 where n is the number returned by get_color_stop_count().

Note that the color and alpha values are not premultiplied.

Parameter index

index of the stop to return data for

Returns

Array
`float0`	the offset of the stop
`float1`	red component of color
`float2`	green component of color
`float3`	blue component of color
`float4`	alpha component of color

Class Cairo.ImageSurface

Description: Rendering to memory buffers

Inherit Surface: inherit Surface : Surface

Method create: Cairo.ImageSurfaceCairo.ImageSurface(intformat, intwidth, intheight)
Description: Creates an image surface of the specified format and dimensions. Initially the surface contents are set to 0. (Specifically, within each pixel, each color or alpha channel belonging to format will be 0. The contents of bits within a pixel, but not belonging to the given format are undefined.)
Parameter format: format of pixels in the surface to create
Parameter width: width of the surface, in pixels
Parameter height: height of the surface, in pixels

Method create: Cairo.ImageSurfaceCairo.ImageSurface(Image.Image|Image.Layer|string|Stdio.InputStreamimage_or_png)
Description: Creates a new image surface and initializes the contents to the given Image.Image or Image.Layer or PNG file.
Parameter image_or_png: Either an Image.Image or Image.Layer to copy pixel data from, or the filename of a PNG file to load, or a Stdio.InputStream to read PNG data from.

Method get_format: intget_format()
Description: Get the format of the surface.
Returns: the format of the surface

Method get_height: intget_height()
Description: Get the height of the image surface in pixels.
Returns: the height of the surface in pixels.

Method get_stride: intget_stride()
Description: Get the stride of the image surface in bytes
Returns: the stride of the image surface in bytes (or 0 if surface is not an image surface). The stride is the distance in bytes from the beginning of one row of the image data to the beginning of the next row.

Method get_width: intget_width()
Description: Get the width of the image surface in pixels.
Returns: the width of the surface in pixels.

Method write_to_png: voidwrite_to_png(string|Stdio.OutputStreamMixinpng_file)
Description: Writes the contents of this ImageSurface as a PNG image.
Parameter png_file: the name of a file to write to, or a Stdio.OutputStreamMixin to write the PNG data to

Class Cairo.LinearGradient

Description: A linear gradient.

Inherit Gradient: inherit Gradient : Gradient

Method create: Cairo.LinearGradientCairo.LinearGradient(float|intx0, float|inty0, float|intx1, float|inty1)
Description: Create a new LinearGradient along the line defined by (x0, y0) and (x1, y1). Before using the gradient pattern, a number of color stops should be defined using add_color_stop_rgb() or add_color_stop_rgba().
Note: The coordinates here are in pattern space. For a new pattern, pattern space is identical to user space, but the relationship between the spaces can be changed with set_matrix().
Parameter x0: x coordinate of the start point
Parameter y0: y coordinate of the start point
Parameter x1: x coordinate of the end point
Parameter y1: y coordinate of the end point

Method get_linear_points

array(float) get_linear_points()

Description

Gets the gradient endpoints for a linear gradient.

Returns

Array
`float0`	the x coordinate of the first point
`float1`	the y coordinate of the first point
`float2`	the x coordinate of the second point
`float3`	the y coordinate of the second point

Class Cairo.Matrix

Description: Holds an affine transformation, such as a scale, rotation, shear, or a combination of those.

Variable x0: float Cairo.Matrix.x0
Description: X translation component of the affine transformation

Variable xx: float Cairo.Matrix.xx
Description: xx component of the affine transformation

Variable xy: float Cairo.Matrix.xy
Description: xy component of the affine transformation

Variable y0: float Cairo.Matrix.y0
Description: Y translation component of the affine transformation

Variable yx: float Cairo.Matrix.yx
Description: yx component of the affine transformation

Variable yy: float Cairo.Matrix.yy
Description: yy component of the affine transformation

Method _sprintf: stringsprintf(stringformat, ... Cairo.Matrixarg ... )

Method `*: Matrix res = Cairo.Matrix() * other
Description: Multiplies the affine transformations in this and other. The effect of the resulting transformation is to first apply the transformation in this to the coordinates and then apply the transformation in other to the coordinates.
Parameter other: a Matrix

Method create: Cairo.MatrixCairo.Matrix(float|int|voidxx, float|int|voidyx, float|int|voidxy, float|int|voidyy, float|int|voidx0, float|int|voidy0)
Parameter xx: xx component of the affine transformation
Parameter yx: yx component of the affine transformation
Parameter xy: xy component of the affine transformation
Parameter yy: yy component of the affine transformation
Parameter x0: X translation component of the affine transformation
Parameter y0: Y translation component of the affine transformation

Method invert: voidinvert()
Description: Changes matrix to be the inverse of its original value. Not all transformation matrices have inverses; if the matrix collapses points together (it is degenerate), then it has no inverse and this function will fail.

Method rotate: voidrotate(floatradians)
Description: Applies rotation by radians to the transformation. The effect of the new transformation is to first rotate the coordinates by radians, then apply the original transformation to the coordinates.
Parameter radians: angle of rotation, in radians. The direction of rotation is defined such that positive angles rotate in the direction from the positive X axis toward the positive Y axis. With the default axis orientation of cairo, positive angles rotate in a clockwise direction.

Method scale: voidscale(float|intsx, float|intsy)
Description: Applies scaling by sx, sy to the transformation. The effect of the new transformation is to first scale the coordinates by sx and sy, then apply the original transformation to the coordinates.
Parameter sx: scale factor in the X direction
Parameter sy: scale factor in the Y direction

Method transform_distance

array(float) transform_distance(float|intdx, float|intdy)

Description

Transforms the distance vector (dx, dy). This is similar to transform_point() except that the translation components of the transformation are ignored. The calculation of the returned vector is as follows:

dx_new = xx * dx + xy * dy;
dy_new = yx * dx + yy * dy;

Parameter dx

X component of a distance vector

Parameter dy

Y component of a distance vector

Returns

The transformed distance vector

Array
`float0`	X component of the new distance vector
`float1`	Y component of the new distance vector

Method transform_point

array(float) transform_point(float|intx, float|inty)

Description

Transforms the point (x, y). The transformation is given by:

x_new = xx * x + xy * y + x0;
y_new = yx * x + yy * y + y0;

Parameter x

X position

Parameter y

Y position

Returns

The transformed point

Array
`float0`	X position of the new point
`float1`	Y position of the new point

Method translate: voidtranslate(float|inttx, float|intty)
Description: Applies a translation by tx, ty to the transformation. The effect of the new transformation is to first translate the coordinates by tx and ty, then apply the original transformation to the coordinates.
Parameter tx: amount to translate in the X direction
Parameter ty: amount to translate in the Y direction

Class Cairo.MeshPattern

Description

Mesh patterns are tensor-product patch meshes (type 7 shadings in PDF). Mesh patterns may also be used to create other types of shadings that are special cases of tensor-product patch meshes such as Coons patch meshes (type 6 shading in PDF) and Gouraud-shaded triangle meshes (type 4 and 5 shadings in PDF).

Mesh patterns consist of one or more tensor-product patches, which should be defined before using the mesh pattern. Using a mesh pattern with a partially defined patch as source or mask will put the context in an error status with a status of STATUS_INVALID_MESH_CONSTRUCTION.

A tensor-product patch is defined by 4 Bézier curves (side 0, 1, 2, 3) and by 4 additional control points (P0, P1, P2, P3) that provide further control over the patch and complete the definition of the tensor-product patch. The corner C0 is the first point of the patch.

Degenerate sides are permitted so straight lines may be used. A zero length line on one side may be used to create 3 sided patches.


          C1     Side 1       C2
           +---------------+
           |               |
           |  P1       P2  |
           |               |
    Side 0 |               | Side 2
           |               |
           |               |
           |  P0       P3  |
           |               |
           +---------------+
         C0     Side 3        C3

Each patch is constructed by first calling begin_patch(), then move_to() to specify the first point in the patch (C0). Then the sides are specified with calls to curve_to() and line_to().

The four additional control points (P0, P1, P2, P3) in a patch can be specified with set_control_point().

At each corner of the patch (C0, C1, C2, C3) a color may be specified with set_corner_color_rgb() or set_corner_color_rgba(). Any corner whose color is not explicitly specified defaults to transparent black.

A Coons patch is a special case of the tensor-product patch where the control points are implicitly defined by the sides of the patch. The default value for any control point not specified is the implicit value for a Coons patch, i.e. if no control points are specified the patch is a Coons patch.

A triangle is a special case of the tensor-product patch where the control points are implicitly defined by the sides of the patch, all the sides are lines and one of them has length 0, i.e. if the patch is specified using just 3 lines, it is a triangle. If the corners connected by the 0-length side have the same color, the patch is a Gouraud-shaded triangle.

Calling end_patch() completes the current patch. If less than 4 sides have been defined, the first missing side is defined as a line from the current point to the first point of the patch (C0) and the other sides are degenerate lines from C0 to C0. The corners between the added sides will all be coincident with C0 of the patch and their color will be set to be the same as the color of C0.

Additional patches may be added with additional calls to begin_patch()/end_patch().

Inherit Pattern: inherit Pattern : Pattern

Method begin_patch

voidbegin_patch()

Description

Begin a patch in a mesh pattern.

After calling this function, the patch shape should be defined with move_to(), line_to() and curve_to().

After defining the patch, end_patch() must be called before using pattern as a source or mask.

Note

If pattern already has a current patch, it will be put into an error status with a status of STATUS_INVALID_MESH_CONSTRUCTION.

Method create: Cairo.MeshPatternCairo.MeshPattern()
Description: Create a new mesh pattern.

Method curve_to

Description

Adds a cubic Bézier spline to the current patch from the current point to position (x3, y3) in pattern-space coordinates, using (x1, y1) and (x2, y2) as the control points.

If the current patch has no current point before the call to curve_to(), this function will behave as if preceded by a call to move_to(x1, y1).

After this call the current point will be (x3, y3).

Note

If pattern has no current patch or the current patch already has 4 sides, pattern will be put into an error status with a status of STATUS_INVALID_MESH_CONSTRUCTION.

Parameter x1

the X coordinate of the first control point

Parameter y1

the Y coordinate of the first control point

Parameter x2

the X coordinate of the second control point

Parameter y2

the Y coordinate of the second control point

Parameter x3

the X coordinate of the end of the curve

Parameter y3

the Y coordinate of the end of the curve

Method end_patch

voidend_patch()

Description

Indicates the end of the current patch in a mesh pattern.

If the current patch has less than 4 sides, it is closed with a straight line from the current point to the first point of the patch as if line_to() was used.

Note

If pattern has no current patch or the current patch has no current point, pattern will be put into an error status with a status of STATUS_INVALID_MESH_CONSTRUCTION.

Method get_control_point

array(float) get_control_point(int(0..)patch_num, int(2bit)point_num)

Description

Gets the control point point_num of patch patch_num for a mesh pattern.

patch_num can range from 0 to n-1 where n is the number returned by get_patch_count().

Valid values for point_num are from 0 to 3 and identify the control points as explained in MeshPattern.

Parameter patch_num

the patch number to return data for

Parameter point_num

the control point number to return data for

Returns

the coordinates of the control point

Array
`float0`	the x coordinate of the control point
`float1`	the y coordinate of the control point

Method get_corner_color_rgba

array(float) get_corner_color_rgba(int(0..)patch_num, int(2bit)corner_num)

Description

Gets the color information in corner corner_num of patch patch_num for a mesh pattern.

patch_num can range from 0 to n-1 where n is the number returned by get_patch_count().

Valid values for corner_num are from 0 to 3 and identify the corners as explained in MeshPattern.

Note that the color and alpha values are not premultiplied.

Parameter patch_num

the patch number to return data for

Parameter corner_num

the corner number to return data for

Returns

the color information of the corner

Array
`float0`	red component of color
`float1`	green component of color
`float2`	blue component of color
`float3`	alpha component of color

Method get_patch_count

int(0..)get_patch_count()

Description

Gets the number of patches specified in this mesh pattern.

The number only includes patches which have been finished by calling end_patch(). For example it will be 0 during the definition of the first patch.

Returns

the number patches

Method get_path

Pathget_path(int(0..)patch_num)

Description

Gets path defining the patch patch_num for a mesh pattern.

patch_num can range from 0 to n-1 where n is the number returned by get_patch_count().

Parameter patch_num

the patch number to return data for

Returns

the path defining the patch

Method line_to

voidline_to(float|intx, float|inty)

Description

Adds a line to the current patch from the current point to position (x, y) in pattern-space coordinates.

If there is no current point before the call to line_to() this function will behave as move_to(x, y).

After this call the current point will be (x, y).

Note

If pattern has no current patch or the current patch already has 4 sides, pattern will be put into an error status with a status of STATUS_INVALID_MESH_CONSTRUCTION.

Parameter x

the X coordinate of the end of the new line

Parameter y

the Y coordinate of the end of the new line

Method move_to

voidmove_to(float|intx, float|inty)

Description

Define the first point of the current patch in a mesh pattern.

After this call the current point will be (x, y).

Note

If pattern has no current patch or the current patch already has at least one side, pattern will be put into an error status with a status of STATUS_INVALID_MESH_CONSTRUCTION.

Parameter x

the X coordinate of the new position

Parameter y

the Y coordinate of the new position

Method set_control_point

voidset_control_point(int(2bit)point_num, float|intx, float|inty)

Description

Set an internal control point of the current patch.

Valid values for point_num are from 0 to 3 and identify the control points as explained in MeshPattern.

Note

If point_num is not valid, pattern will be put into an error status with a status of STATUS_INVALID_INDEX. If pattern has no current patch, pattern will be put into an error status with a status of STATUS_INVALID_MESH_CONSTRUCTION.

Parameter point_num

the control point to set the position for

Parameter x

the X coordinate of the control point

Parameter y

the Y coordinate of the control point

Method set_corner_color_rgb

voidset_corner_color_rgb(int(2bit)corner_num, floatred, floatgreen, floatblue)

Description

Sets the color of a corner of the current patch in a mesh pattern.

The color is specified in the same way as in Context->set_source_rgb().

Valid values for corner_num are from 0 to 3 and identify the corners as explained in MeshPattern.

Note

If corner_num is not valid, pattern will be put into an error status with a status of STATUS_INVALID_INDEX. If pattern has no current patch, pattern will be put into an error status with a status of STATUS_INVALID_MESH_CONSTRUCTION.

Parameter corner_num

the corner to set the color for

Parameter red

red component of color

Parameter green

green component of color

Parameter blue

blue component of color

Method set_corner_color_rgba

voidset_corner_color_rgba(int(2bit)corner_num, floatred, floatgreen, floatblue, floatalpha)

Description

Sets the color of a corner of the current patch in a mesh pattern.

The color is specified in the same way as in Context->set_source_rgba().

Valid values for corner_num are from 0 to 3 and identify the corners as explained in MeshPattern.

Note

Parameter corner_num

the corner to set the color for

Parameter red

red component of color

Parameter green

green component of color

Parameter blue

blue component of color

Parameter alpha

alpha component of color

Class Cairo.PDFSurface

Description: Rendering PDF documents

Inherit Surface: inherit Surface : Surface

Method add_outline: intadd_outline(intparent_id, stringname, stringlink_attribs, intflags)
Description: Add an item to the document outline hierarchy with the given name that links to the location specified by link_attribs. Link attributes have the same keys and values as the Link Tag, excluding the "rect" attribute. The item will be a child of the item with id parent_id. Use PDF_OUTLINE_ROOT as the parent id of top level items.
Parameter parent_id: the id of the parent item or PDF_OUTLINE_ROOT if this is a top level item.
Parameter name: the name of the outline
Parameter link_attribs: the link attributes specifying where this outline links to
Parameter flags: outline item flags

Method create: Cairo.PDFSurfaceCairo.PDFSurface(string|Stdio.OutputStreamMixin|zeropdf_file, float|intwidth_in_points, float|intheight_in_points)
Description: Creates a PDF surface of the specified size in points to be written to pdf_file.
Parameter pdf_file: a filename for the PDF output (must be writable), or a Stdio.OutputStreamMixin to write the output to. 0 may be used to specify no output. This will generate a PDF surface that may be queried and used as a source, without generating a temporary file.
Parameter width_in_points: width of the surface, in points (1 point == 1/72.0 inch)
Parameter height_in_points: height of the surface, in points (1 point == 1/72.0 inch)

Method get_versions: array(int) get_versions()
Description: Used to retrieve the list of supported versions. See restrict_to_version().
Returns: supported version list

Method restrict_to_version

voidrestrict_to_version(intversion)

Description

Restricts the generated PDF file to version.

This function should only be called before any drawing operations have been performed on the given surface. The simplest way to do this is to call this function immediately after creating the surface.

Parameter version

PDF version

Method set_custom_metadata

voidset_custom_metadata(stringname, string|zerovalue)

Description

Set custom document metadata. name may be any string except for the following names reserved by PDF: "Title", "Author", "Subject", "Keywords", "Creator", "Producer", "CreationDate", "ModDate", "Trapped".

If value is 0 or an empty string, the name metadata will not be set.

Example

pdf_surface->set_custom_metadata("ISBN","978-0123456789");

Parameter name

The name of the custom metadata item to set.

Parameter value

The value of the metadata.

Method set_metadata

voidset_metadata(intmetadata, stringvalue)

Description

Set document metadata. The PDF_METADATA_CREATE_DATE and PDF_METADATA_MOD_DATE values must be in ISO-8601 format: YYYY-MM-DDThh:mm:ss. An optional timezone of the form "[+/-]hh:mm" or "Z" for UTC time can be appended. All other metadata values can be any string.

Example

pdf_surface->set_metadata(Cairo.PDF_METADATA_TITLE,"My Document");
pdf_surface->set_metadata(Cairo.PDF_METADATA_CREATE_DATE,"2015-12-31T23:59+02:00");

Parameter metadata

The metadata item to set.

Parameter value

metadata value

Method set_page_label: voidset_page_label(stringlabel)
Description: Set page label for the current page.
Parameter label: The page label.

Method set_size

voidset_size(float|intwidth_in_points, float|intheight_in_points)

Description

Changes the size of a PDF surface for the current (and subsequent) pages.

This function should only be called before any drawing operations have been performed on the current page. The simplest way to do this is to call this function immediately after creating the surface or immediately after completing a page with either Context->show_page() or Context->copy_page().

Parameter width_in_points

new surface width, in points (1 point == 1/72.0 inch)

Parameter height_in_points

new surface height, in points (1 point == 1/72.0 inch)

Method set_thumbnail_size: voidset_thumbnail_size(intwidth, intheight)
Description: Set the thumbnail image size for the current and all subsequent pages. Setting a width or height of 0 disables thumbnails for the current and subsequent pages.
Parameter width: Thumbnail width.
Parameter height: Thumbnail height

Method version_to_string: stringversion_to_string(intversion)
Description: Get the string representation of the given version id. This function will return UNDEFINED if version isn't valid. See get_versions() for a way to get the list of valid version ids.
Returns: the string associated to given version.

Class Cairo.PSSurface

Description: Rendering PostScript documents

Inherit Surface: inherit Surface : Surface

Method create: Cairo.PSSurfaceCairo.PSSurface(string|Stdio.OutputStreamMixin|zerops_file, float|intwidth_in_points, float|intheight_in_points)
Description: Creates a PostScript surface of the specified size in points to be written to ps_file.
Parameter ps_file: a filename for the PS output (must be writable), or a Stdio.OutputStreamMixin to write the output to. 0 may be used to specify no output. This will generate a PS surface that may be queried and used as a source, without generating a temporary file.
Parameter width_in_points: width of the surface, in points (1 point == 1/72.0 inch)
Parameter height_in_points: height of the surface, in points (1 point == 1/72.0 inch)

Method dsc_begin_page_setup

voiddsc_begin_page_setup()

Description

This function indicates that subsequent calls to dsc_comment() should direct comments to the PageSetup section of the PostScript output.

This function call is only needed for the first page of a surface. It should be called after any call to dsc_begin_setup() and before any drawing is performed to the surface.

See dsc_comment() for more details.

Method dsc_begin_setup

voiddsc_begin_setup()

Description

This function indicates that subsequent calls to dsc_comment() should direct comments to the Setup section of the PostScript output.

This function should be called at most once per surface, and must be called before any call to dsc_begin_page_setup() and before any drawing is performed to the surface.

See dsc_comment() for more details.

Method dsc_comment

voiddsc_comment(stringcomment)

Description

Emit a comment into the PostScript output for the given surface.

The comment is expected to conform to the PostScript Language Document Structuring Conventions (DSC). Please see that manual for details on the available comments and their meanings. In particular, the %%IncludeFeature comment allows a device-independent means of controlling printer device features. So the PostScript Printer Description Files Specification will also be a useful reference.

The comment string must begin with a percent character (%) and the total length of the string (including any initial percent characters) must not exceed 255 characters. Violating either of these conditions will place surface into an error state. But beyond these two conditions, this function will not enforce conformance of the comment with any particular specification.

The comment string must not contain any newline characters.

The DSC specifies different sections in which particular comments can appear. This function provides for comments to be emitted within three sections: the header, the Setup section, and the PageSetup section. Comments appearing in the first two sections apply to the entire document while comments in the BeginPageSetup section apply only to a single page.

For comments to appear in the header section, this function should be called after the surface is created, but before a call to dsc_begin_setup().

For comments to appear in the Setup section, this function should be called after a call to dsc_begin_setup() but before a call to dsc_begin_page_setup().

For comments to appear in the PageSetup section, this function should be called after a call to dsc_begin_page_setup().

Note that it is only necessary to call dsc_begin_page_setup() for the first page of any surface. After a call to Context->show_page() or Context->copy_page() comments are unambiguously directed to the PageSetup section of the current page. But it doesn't hurt to call this function at the beginning of every page as that consistency may make the calling code simpler.

As a final note, cairo automatically generates several comments on its own. As such, applications must not manually generate any of the following comments:

Header section: %!PS-Adobe-3.0, %%Creator, %%CreationDate, %%Pages, %%BoundingBox, %%DocumentData, %%LanguageLevel, %%EndComments.

Setup section: %%BeginSetup, %%EndSetup

PageSetup section: %%BeginPageSetup, %%PageBoundingBox, %%EndPageSetup.

Other sections: %%BeginProlog, %%EndProlog, %%Page, %%Trailer, %%EOF

Here is an example sequence showing how this function might be used:

Example

Cairo.Surface surface = Cairo.PSSurface(filename, width, height);
...
surface->dsc_comment("%%Title: My excellent document");
surface->dsc_comment("%%Copyright: Copyright (C) 2006 Cairo Lover")
...
surface->dsc_begin_setup();
surface->dsc_comment("%%IncludeFeature: *MediaColor White");
...
surface->dsc_begin_page_setup();
surface->dsc_comment("%%IncludeFeature: *PageSize A3");
surface->dsc_comment("%%IncludeFeature: *InputSlot LargeCapacity");
surface->dsc_comment("%%IncludeFeature: *MediaType Glossy");
surface->dsc_comment("%%IncludeFeature: *MediaColor Blue");
... draw to first page here ..
cr->show_page();
...
surface->dsc_comment("%%IncludeFeature: *PageSize A5");
...

Parameter comment

a comment string to be emitted into the PostScript output

Method get_eps: boolget_eps()
Description: Check whether the PostScript surface will output Encapsulated PostScript.
Returns: 1 if the surface will output Encapsulated PostScript.

Method get_levels: array(int) get_levels()
Description: Used to retrieve the list of supported levels. See restrict_to_level().
Returns: supported level list

Method level_to_string: stringlevel_to_string(intlevel)
Description: Get the string representation of the given level id. This function will return UNDEFINED if level id isn't valid. See get_levels() for a way to get the list of valid level ids.
Parameter level: a level id
Returns: the string associated to given level.

Method restrict_to_level

voidrestrict_to_level(intlevel)

Description

Restricts the generated PostSript file to level.

Parameter level

PostScript level

Method set_eps

voidset_eps(booleps)

Description

If eps is 1, the PostScript surface will output Encapsulated PostScript.

This function should only be called before any drawing operations have been performed on the current page. The simplest way to do this is to call this function immediately after creating the surface. An Encapsulated PostScript file should never contain more than one page.

Parameter eps

1 to output EPS format PostScript

Method set_size

voidset_size(float|intwidth_in_points, float|intheight_in_points)

Description

Changes the size of a PostScript surface for the current (and subsequent) pages.

Parameter width_in_points

new surface width, in points (1 point == 1/72.0 inch)

Parameter height_in_points

new surface height, in points (1 point == 1/72.0 inch)

Class Cairo.Path

Description: Paths are the most basic drawing tools and are primarily used to implicitly generate simple masks

Method _get_iterator: Cairo.Patha; foreach( a; index; value ) orPathIterator_get_iterator(void|intind)
Description: Create and initiate a new PathIterator that could be used to iterate over this path.
Returns: An iterator.

Method _sprintf: stringsprintf(stringformat, ... Cairo.Patharg ... )

Class Cairo.Path.PathIterator

Description: This is the iterator for the Path.

Method _iterator_index

int_iterator_index()

Description

Returns the current index, or UNDEFINED if the iterator doesn't point to any item.

The index is the current position in the data set, counting from 0 (zero).

Method _iterator_next: bool_iterator_next()
Description: Advance the iterator one step.
Returns: Returns 1 if it succeeded in advancing, and 0 (zero) if it has reached the end of the iterator.
See also: _iterator_index(), _iterator_value()

Method _iterator_value: mixed_iterator_value()
Description: Returns the current value, or UNDEFINED if the iterator doesn't point to any item.

Method create: Cairo.Path.PathIteratorCairo.Path.PathIterator(Pathpath)
Description: Creates a new iterator for the Path path.

Class Cairo.Pattern

Description: The paint with which cairo draws. The primary use of patterns is as the source for all cairo drawing operations, although they can also be used as masks, that is, as the brush too.

Method `==: bool res = Cairo.Pattern() == x
Returns: Returns 1 if x is the same Pattern, and 0 (zero) otherwise.

Method get_dither: intget_dither()
Description: Gets the current dithering mode, as set by set_dither().
Returns: the current dithering mode.

Method get_extend: intget_extend()
Description: Gets the current extend mode for a pattern.
Returns: the current extend strategy used for drawing the pattern.

Method get_filter: intget_filter()
Description: Gets the current filter for a pattern.
Returns: the current filter used for resizing the pattern.

Method get_matrix: Matrixget_matrix()
Description: Stores the pattern's transformation matrix into a Matrix.
Returns: the matrix

Method set_dither: voidset_dither(intdither)
Description: Set the dithering mode of the rasterizer used for drawing shapes. This value is a hint, and a particular backend may or may not support a particular value. At the current time, only pixman is supported.
Parameter dither: the new dithering mode

Method set_extend

voidset_extend(intextend)

Description

Sets the mode to be used for drawing outside the area of a pattern.

The default extend mode is EXTEND_NONE for surface patterns and EXTEND_PAD for gradient patterns.

Parameter extend

how the area outside of the pattern will be drawn

Method set_filter

voidset_filter(intfilter)

Description

Sets the filter to be used for resizing when using this pattern.

Note that you might want to control filtering even when you do not have an explicit Pattern object, (for example when using Context->set_source_surface()). In these cases, it is convenient to use Context->get_source() to get access to the pattern that cairo creates implicitly. For example:

cr->set_source_surface(image, x, y);
cr->get_source()->set_filter(Cairo.FILTER_NEAREST);

Parameter filter

the filter to use for resizing the pattern

Method set_matrix

voidset_matrix(Matrixmatrix)

Description

Sets the pattern's transformation matrix to matrix. This matrix is a transformation from user space to pattern space.

When a pattern is first created it always has the identity matrix for its transformation matrix, which means that pattern space is initially identical to user space.

Important: Please note that the direction of this transformation matrix is from user space to pattern space. This means that if you imagine the flow from a pattern to user space (and on to device space), then coordinates in that flow will be transformed by the inverse of the pattern matrix.

Also, please note the discussion of the user-space locking semantics of Context->set_source().

Parameter matrix

a matrix

Class Cairo.RadialGradient

Description: A radial gradient.

Inherit Gradient: inherit Gradient : Gradient

Method create: Cairo.RadialGradientCairo.RadialGradient(float|intcx0, float|intcy0, float|intradius0, float|intcx1, float|intcy1, float|intradius1)
Description: Creates a new RadialGradient between the two circles defined by (cx0, cy0, radius0) and (cx1, cy1, radius1). Before using the gradient pattern, a number of color stops should be defined using add_color_stop_rgb() or add_color_stop_rgba().
Note: The coordinates here are in pattern space. For a new pattern, pattern space is identical to user space, but the relationship between the spaces can be changed with set_matrix().
Parameter cx0: x coordinate for the center of the start circle
Parameter cy0: y coordinate for the center of the start circle
Parameter radius0: radius of the start circle
Parameter cx1: x coordinate for the center of the end circle
Parameter cy1: y coordinate for the center of the end circle
Parameter radius1: radius of the end circle

Method get_radial_circles

array(float) get_radial_circles()

Description

Gets the gradient endpoint circles for a radial gradient, each specified as a center coordinate and a radius.

Returns

Array
`float0`	the x coordinate of the center of the first circle
`float1`	the y coordinate of the center of the first circle
`float2`	the radius of the first circle
`float3`	the x coordinate of the center of the second circle
`float4`	the y coordinate of the center of the second circle
`float5`	the radius of the second circle

Class Cairo.RecordingSurface

Description: Records all drawing operations

Inherit Surface: inherit Surface : Surface

Method create

Cairo.RecordingSurfaceCairo.RecordingSurface(intcontent, Rectangle|voidextents)

Description

Creates a recording-surface which can be used to record all drawing operations at the highest level (that is, the level of Context->paint, Context->mask, Context->stroke, Context->fill and Context->show_text_glyphs). The recording surface can then be "replayed" against any target surface by using it as a source to drawing operations.

The recording phase of the recording surface is careful to snapshot all necessary objects (paths, patterns, etc.), in order to achieve accurate replay.

Parameter content

the content of the recording surface

Parameter extents

the extents to record in pixels, can be omitted to record unbounded operations.

Method get_extents: Rectangleget_extents()
Description: Get the extents of the RecordingSurface.
Returns: A Rectangle if the surface is bounded, otherwise UNDEFINED

Method ink_extents

array(float) ink_extents()

Description

Measures the extents of the operations stored within the RecordingSurface. This is useful to compute the required size of an ImageSurface (or equivalent) into which to replay the full sequence of drawing operations.

Returns

An array with the following elements:

Array
`float0`	the x-coordinate of the top-left of the ink bounding box
`float1`	the y-coordinate of the top-left of the ink bounding box
`float2`	the width of the ink bounding box
`float3`	the height of the ink bounding box

Class Cairo.Rectangle

Description: A data structure for holding a rectangle.

Variable height: float Cairo.Rectangle.height
Description: height of the rectangle

Variable width: float Cairo.Rectangle.width
Description: width of the rectangle

Variable x: float Cairo.Rectangle.x
Description: X coordinate of the left side of the rectangle

Variable y: float Cairo.Rectangle.y
Description: Y coordinate of the top side of the rectangle

Method _sprintf: stringsprintf(stringformat, ... Cairo.Rectanglearg ... )

Method create: Cairo.RectangleCairo.Rectangle(float|intx, float|inty, float|intwidth, float|intheight)
Parameter x: X coordinate of the left side of the rectangle
Parameter y: Y coordinate of the top side of the rectangle
Parameter width: width of the rectangle
Parameter height: height of the rectangle

Class Cairo.RectangleInt

Description: A data structure for holding a rectangle with integer coordinates.

Variable height: int Cairo.RectangleInt.height
Description: height of the rectangle

Variable width: int Cairo.RectangleInt.width
Description: width of the rectangle

Variable x: int Cairo.RectangleInt.x
Description: X coordinate of the left side of the rectangle

Variable y: int Cairo.RectangleInt.y
Description: Y coordinate of the top side of the rectangle

Method _sprintf: stringsprintf(stringformat, ... Cairo.RectangleIntarg ... )

Method create: Cairo.RectangleIntCairo.RectangleInt(intx, inty, intwidth, intheight)
Parameter x: X coordinate of the left side of the rectangle
Parameter y: Y coordinate of the top side of the rectangle
Parameter width: width of the rectangle
Parameter height: height of the rectangle

Class Cairo.SVGSurface

Description: Rendering SVG documents

Inherit Surface: inherit Surface : Surface

Method create: Cairo.SVGSurfaceCairo.SVGSurface(string|Stdio.OutputStreamMixin|zerosvg_file, float|intwidth_in_points, float|intheight_in_points)
Description: Creates a SVG surface of the specified size in points to be written to svg_file.
Parameter svg_file: a filename for the SVG output (must be writable), or a Stdio.OutputStreamMixin to write the output to. 0 may be used to specify no output. This will generate a SVG surface that may be queried and used as a source, without generating a temporary file.
Parameter width_in_points: width of the surface, in points (1 point == 1/72.0 inch)
Parameter height_in_points: height of the surface, in points (1 point == 1/72.0 inch)

Method get_document_unit: intget_document_unit()
Description: Get the unit of the SVG surface.
Returns: the SVG unit of the SVG surface.

Method get_versions: array(int) get_versions()
Description: Used to retrieve the list of supported versions. See restrict_to_version().
Returns: supported version list

Method restrict_to_version

voidrestrict_to_version(intversion)

Description

Restricts the generated SVG file to version. See get_versions() for a list of available version values that can be used here.

Parameter version

SVG version

Method set_document_unit

voidset_document_unit(intunit)

Description

Use the specified unit for the width and height of the generated SVG file.

This function can be called at any time before generating the SVG file.

However to minimize the risk of ambiguities it's recommended to call it before any drawing operations have been performed on the given surface, to make it clearer what the unit used in the drawing operations is.

The simplest way to do this is to call this function immediately after creating the SVG surface.

Note

If this function is never called, the default unit for SVG documents generated by cairo will be user unit.

Parameter unit

SVG unit

Method version_to_string: stringversion_to_string(intversion)
Description: Get the string representation of the given version id. This function will return UNDEFINED if version isn't valid. See get_versions() for a way to get the list of valid version ids.
Parameter version: a version id
Returns: the string associated to given version.

Class Cairo.ScaledFont

Description: ScaledFont represents a realization of a font face at a particular size and transformation and a certain set of font options

Method `==: bool res = Cairo.ScaledFont() == x
Returns: Returns 1 if x is the same ScaledFont, and 0 (zero) otherwise.

Method create: Cairo.ScaledFontCairo.ScaledFont(FontFacefont_face, Matrixfont_matrix, Matrixctm, FontOptionsoptions)
Description: Creates a ScaledFont object from a font face and matrices that describe the size of the font and the environment in which it will be used.
Parameter font_face: a FontFace
Parameter font_matrix: font space to user space transformation matrix for the font. In the simplest case of a N point font, this matrix is just a scale by N, but it can also be used to shear the font or stretch it unequally along the two axes. See Context->set_font_matrix().
Parameter ctm: user to device transformation matrix with which the font will be used.
Parameter options: options to use when getting metrics for the font and rendering with it.

Method extents

array(float) extents()

Description

Gets the metrics for a ScaledFont. Values are given in the current user-space coordinate system.

Because font metrics are in user-space coordinates, they are mostly, but not entirely, independent of the current transformation matrix. If you call Context->scale(2.0, 2.0), text will be drawn twice as big, but the reported text extents will not be doubled. They will change slightly due to hinting (so you can't assume that metrics are independent of the transformation matrix), but otherwise will remain unchanged.

Returns

an array which stores the retrieved extents:

Array
`float0`	ascent: the distance that the font extends above the baseline. Note that this is not always exactly equal to the maximum of the extents of all the glyphs in the font, but rather is picked to express the font designer's intent as to how the font should align with elements above it.
`float1`	descent: the distance that the font extends below the baseline. This value is positive for typical fonts that include portions below the baseline. Note that this is not always exactly equal to the maximum of the extents of all the glyphs in the font, but rather is picked to express the font designer's intent as to how the font should align with elements below it.
`float2`	height: the recommended vertical distance between baselines when setting consecutive lines of text with the font. This is greater than ascent + descent by a quantity known as the line spacing or external leading. When space is at a premium, most fonts can be set with only a distance of ascent + descent between lines.
`float3`	max_x_advance: the maximum distance in the X direction that the origin is advanced for any glyph in the font.
`float4`	max_y_advance: the maximum distance in the Y direction that the origin is advanced for any glyph in the font. This will be zero for normal fonts used for horizontal writing. (The scripts of East Asia are sometimes written vertically.)

Method get_ctm: Matrixget_ctm()
Description: Stores the CTM with which this ScaledFont was created into a Matrix. Note that the translation offsets (x0, y0) of the CTM are ignored by ScaledFont->create(). So, the matrix this function returns always has 0,0 as x0,y0.
Returns: the matrix

Method get_font_face: FontFaceget_font_face()
Description: Gets the font face that this scaled font uses. This might be the font face passed to create(), but this does not hold true for all possible cases.
Returns: The FontFace with which scaled_font was created.

Method get_font_matrix: Matrixget_font_matrix()
Description: Stores the font matrix with which this ScaledFont was created into a Matrix.
Returns: the matrix

Method get_font_options: voidget_font_options(FontOptionsoptions)
Description: Stores the font options with which this ScaledFont was created into options.
Parameter options: return value for the font options

Method get_scale_matrix: Matrixget_scale_matrix()
Description: Stores the scale matrix of this ScaledFont into a Matrix. The scale matrix is product of the font matrix and the ctm associated with the scaled font, and hence is the matrix mapping from font space to device space.
Returns: the matrix

Method glyph_extents

TextExtentsglyph_extents(array(Glyph|array(int|float)) glyphs)

Description

Gets the extents for an array of glyphs. The extents describe a user-space rectangle that encloses the "inked" portion of the glyphs, (as they would be drawn by Context->show_glyphs() if the cairo graphics state were set to the same font_face, font_matrix, ctm, and font_options as this ScaledFont). Additionally, the x_advance and y_advance values indicate the amount by which the current point would be advanced by Context->show_glyphs().

Note that whitespace glyphs do not contribute to the size of the rectangle (TextExtents->width and TextExtents->height).

Parameter glyphs

an array of glyph IDs with X and Y offsets, with each glyph being represented either as a Glyph object or as an array having the following format:

Array
`int0`	glyph index in the font. The exact interpretation of the glyph index depends on the font technology being used.
`float\|int1`	the offset in the X direction between the origin used for drawing the string and the origin of this glyph
`float\|int2`	the offset in the Y direction between the origin used for drawing the string and the origin of this glyph

Returns

a TextExtents object which stores the retrieved extents.

Method text_extents

TextExtentstext_extents(stringtext)

Description

Gets the extents for a string of text. The extents describe a user-space rectangle that encloses the "inked" portion of the text drawn at the origin (0,0) (as it would be drawn by Context->show_text() if the cairo graphics state were set to the same font_face, font_matrix, ctm, and font_options as this ScaledFont). Additionally, the x_advance and y_advance values indicate the amount by which the current point would be advanced by Context->show_text().

Parameter text

a string of text

Returns

a TextExtents object which stores the retrieved extents.

Method text_to_glyphs

array(array(Glyph)|array(TextCluster)|int) text_to_glyphs(float|intx, float|inty, stringtext)

Description

Converts text to an array of glyphs, optionally with cluster mapping, that can be used to render later using ScaledFont.

For details of how clusters, and cluster_flags map UTF-8 text to the output glyphs see Context->show_text_glyphs().

The output values can be readily passed to Context->show_text_glyphs(), Context->show_glyphs(), or related functions, assuming that the exact same ScaledFont is used for the operation.

Parameter x

X position to place first glyph

Parameter y

Y position to place first glyph

Parameter text

a string of text

Returns

An array with three elements

Array
`array(Glyph) 0`	array of glyphs
`array(TextCluster) 1`	array of cluster mapping information
`int2`	cluster flags corresponding to the output clusters

Class Cairo.ScriptDevice

Description: Rendering to replayable scripts

Inherit Device: inherit Device : Device

Method create: Cairo.ScriptDeviceCairo.ScriptDevice(string|Stdio.OutputStreamMixinscript_file)
Description: Creates a output device for emitting the script, used when creating the individual surfaces.
Parameter script_file: the name (path) of the file, or a Stdio.OutputStreamMixin, to write the script to

Method from_recording_surface: voidfrom_recording_surface(RecordingSurfacerecording_surface)
Description: Converts the record operations in recording_surface into a script.
Parameter recording_surface: the recording surface to replay

Method get_mode: intget_mode()
Description: Queries the script for its current output mode.
Returns: the current output mode of the script

Method set_mode: voidset_mode(intmode)
Description: Change the output mode of the script
Parameter mode: the new mode

Method write_comment: voidwrite_comment(string(8bit)comment)
Description: Emit a string verbatim into the script.
Parameter comment: the string to emit

Class Cairo.ScriptSurface

Description: Rendering to replayable scripts

Inherit Surface: inherit Surface : Surface

Method create: Cairo.ScriptSurfaceCairo.ScriptSurface(ScriptDevicescript, intcontent, float|intwidth, float|intheight)
Description: Create a new surface that will emit its rendering through script
Parameter script: the script (output device)
Parameter content: the content of the surface
Parameter width: width in pixels
Parameter height: height in pixels

Method create: Cairo.ScriptSurfaceCairo.ScriptSurface(ScriptDevicescript, Surfacetarget)
Description: Create a pxoy surface that will render to target and record the operations to device.
Parameter script: the script (output device)
Parameter target: a target surface to wrap

Class Cairo.SolidPattern

Description: A solid (uniform) color. It may be opaque or translucent.

Inherit Pattern: inherit Pattern : Pattern

Method create: Cairo.SolidPatternCairo.SolidPattern(floatred, floatgreen, floatblue, float|voidalpha)
Description: Creates a new Pattern corresponding to an opaque or translucent color. The color components are floating point numbers in the range 0 to 1. If the values passed in are outside that range, they will be clamped.
Parameter red: red component of the color
Parameter green: green component of the color
Parameter blue: blue component of the color
Parameter alpha: alpha component of the color. If omitted the pattern will be opaque.

Method get_rgba

array(float) get_rgba()

Description

Gets the solid color for a solid color pattern.

Note that the color and alpha values are not premultiplied.

Returns

An array with the components of the color

Array
`float0`	red component of color
`float1`	green component of color
`float2`	blue component of color
`float3`	alpha component of color

Class Cairo.Surface

Description: Base class for surfaces

Method `==: bool res = Cairo.Surface() == x
Returns: Returns 1 if x is the same Surface, and 0 (zero) otherwise.

Method copy_page

voidcopy_page()

Description

Emits the current page for backends that support multiple pages, but doesn't clear it, so that the contents of the current page will be retained for the next page. Use show_page() if you want to get an empty page after the emission.

There is a convenience function for this in Context, namely Context->copy_page().

Method create_for_rectangle

Surfacecreate_for_rectangle(float|intx, float|inty, float|intwidth, float|intheight)

Description

Create a new surface that is a rectangle within the target surface. All operations drawn to this surface are then clipped and translated onto the target surface. Nothing drawn via this sub-surface outside of its bounds is drawn onto the target surface, making this a useful method for passing constrained child surfaces to library routines that draw directly onto the parent surface, i.e. with no further backend allocations, double buffering or copies.

The semantics of subsurfaces have not been finalized yet unless the rectangle is in full device units, is contained within the extents of the target surface, and the target or subsurface's device transforms are not changed.

Parameter x

the x-origin of the sub-surface from the top-left of the target surface (in device-space units)

Parameter y

the y-origin of the sub-surface from the top-left of the target surface (in device-space units)

Parameter width

width of the sub-surface (in device-space units)

Parameter height

height of the sub-surface (in device-space units)

Returns

a newly allocated surface.

Method create_similar

Surfacecreate_similar(intcontent, intwidth, intheight)

Description

Create a new surface that is as compatible as possible with this surface. For example the new surface will have the same device scale, fallback resolution and font options as this. Generally, the new surface will also use the same backend, unless that is not possible for some reason.

Initially the surface contents are all 0 (transparent if contents have transparency, black otherwise.)

Use create_similar_image() if you need an image surface which can be painted quickly to the target surface.

Parameter content

the content for the new surface

Parameter width

width of the new surface, (in device-space units)

Parameter height

height of the new surface (in device-space units)

Returns

a newly allocated surface.

Method create_similar_image

Surfacecreate_similar_image(intformat, intwidth, intheight)

Description

Create a new image surface that is as compatible as possible for uploading to and the use in conjunction with this surface. However, this surface can still be used like any normal image surface. Unlike create_similar() the new image surface won't inherit the device scale from this.

Initially the surface contents are all 0 (transparent if contents have transparency, black otherwise.)

Use create_similar() if you don't need an image surface.

Parameter format

the format for the new surface

Parameter width

width of the new surface, (in pixels)

Parameter height

height of the new surface (in pixels)

Returns

a newly allocated image surface.

Method finish

voidfinish()

Description

This function finishes the surface and drops all references to external resources. For example, for the Xlib backend it means that cairo will no longer access the drawable, which can be freed. After calling finish() the only valid operations on a surface are checking status, getting and setting user, referencing and destroying, and flushing and finishing it. Further drawing to the surface will not affect the surface but will instead trigger a STATUS_SURFACE_FINISHED error.

When the reference count of the Surface decreases to zero, cairo will call finish() if it hasn't been called already, before freeing the resources associated with the surface.

Method flush: voidflush()
Description: Do any pending drawing for the surface and also restore any temporary modifications cairo has made to the surface's state. This function must be called before switching from drawing on the surface with cairo to drawing on it directly with native APIs, or accessing its memory outside of Cairo. If the surface doesn't support direct access, then this function does nothing.

Method get_content: intget_content()
Description: This function returns the content type of surface which indicates whether the surface contains color and/or alpha information.
Returns: The content type of surface .

Method get_device: Deviceget_device()
Description: This function returns the device for a surface. See Device.
Returns: The device for this surface or UNDEFINED if the surface does not have an associated device.

Method get_device_offset

array(float) get_device_offset()

Description

This function returns the previous device offset set by set_device_offset().

Returns

The device offset

Array
`float0`	the offset in the X direction, in device units
`float1`	the offset in the Y direction, in device units

Method get_device_scale

array(float) get_device_scale()

Description

This function returns the previous device scale set by set_device_scale().

Returns

The device scale

Array
`float0`	the scale in the X direction, in device units
`float1`	the scale in the Y direction, in device units

Method get_fallback_resolution

array(float) get_fallback_resolution()

Description

This function returns the previous fallback resolution set by set_fallback_resolution(), or default fallback resolution if never set.

Returns

The fallback resolution

Array
`float0`	horizontal pixels per inch
`float1`	vertical pixels per inch

Method get_font_options: voidget_font_options(FontOptionsoptions)
Description: Retrieves the default font rendering options for the surface. This allows display surfaces to report the correct subpixel order for rendering on them, print surfaces to disable hinting of metrics and so forth. The result can then be used with ScaledFont->create().
Parameter options: a FontOptions object into which to store the retrieved options. All existing values are overwritten

Method get_mime_data: string(8bit)|zeroget_mime_data(string(7bit)mime_type)
Description: Return mime data previously attached to surface using the specified mime type. If no data has been attached with the given mime type, UNDEFINED is returned.
Parameter mime_type: the mime type of the image data
Returns: the image data attached to the surface

Method has_show_text_glyphs: boolhas_show_text_glyphs()
Description: Returns whether the surface supports sophisticated Context->show_text_glyphs() operations. That is, whether it actually uses the provided text and cluster data to a Context->show_text_glyphs() call.
Note: Even if this function returns 0, a Context->show_text_glyphs() operation targeted at this surface will still succeed. It just will act like a Context->show_glyphs() operation. Users can use this function to avoid computing UTF-8 text and cluster mapping if the target surface does not use it.
Returns: 1 if surface supports Context->show_text_glyphs(), 0 otherwise

Method map_to_image: Surfacemap_to_image(RectangleInt|voidextents)
Description: Returns an image surface that is the most efficient mechanism for modifying the backing store of the target surface. The region retrieved may be limited to the extents, or the whole surface if no extents are given.
Note: The use of the original surface as a target or source whilst it is mapped is undefined. The result of mapping the surface multiple times is undefined. Destroying or calling finish() on the resulting image surface results in undefined behavior. Changing the device transform of the image surface or of surface before the image surface is unmapped results in undefined behavior.
Parameter extents: limit the extraction to an rectangular region
Returns: a newly allocated image surface. The caller must use unmap_image() to destroy this image surface.

Method mark_dirty: voidmark_dirty()
Description: Tells cairo that drawing has been done to surface using means other than cairo, and that cairo should reread any cached areas. Note that you must call flush() before doing such drawing.

Method mark_dirty_rectangle

voidmark_dirty_rectangle(intx, inty, intwidth, intheight)

Description

Like mark_dirty(), but drawing has been done only to the specified rectangle, so that cairo can retain cached contents for other parts of the surface.

Any cached clip set on the surface will be reset by this function, to make sure that future cairo calls have the clip set that they expect.

Parameter x

X coordinate of dirty rectangle

Parameter y

Y coordinate of dirty rectangle

Parameter width

width of dirty rectangle

Parameter height

height of dirty rectangle

Method set_device_offset

voidset_device_offset(float|intx_offset, float|inty_offset)

Description

Sets an offset that is added to the device coordinates determined by the CTM when drawing to surface. One use case for this function is when we want to create a Surface that redirects drawing for a portion of an onscreen surface to an offscreen surface in a way that is completely invisible to the user of the cairo API. Setting a transformation via Context->translate() isn't sufficient to do this, since functions like Context->device_to_user() will expose the hidden offset.

Note that the offset affects drawing to the surface as well as using the surface in a source pattern.

Parameter x_offset

the offset in the X direction, in device units

Parameter y_offset

the offset in the Y direction, in device units

Method set_device_scale

voidset_device_scale(float|intx_scale, float|inty_scale)

Description

Sets a scale that is multiplied to the device coordinates determined by the CTM when drawing to this surface. One common use for this is to render to very high resolution display devices at a scale factor, so that code that assumes 1 pixel will be a certain size will still work. Setting a transformation via Context->scale() isn't sufficient to do this, since functions like Context->device_to_user() will expose the hidden scale.

Note that the scale affects drawing to the surface as well as using the surface in a source pattern.

Parameter x_scale

a scale factor in the X direction

Parameter y_scale

a scale factor in the Y direction

Method set_fallback_resolution

voidset_fallback_resolution(float|intx_pixels_per_inch, float|inty_pixels_per_inch)

Description

Set the horizontal and vertical resolution for image fallbacks.

When certain operations aren't supported natively by a backend, cairo will fallback by rendering operations to an image and then overlaying that image onto the output. For backends that are natively vector-oriented, this function can be used to set the resolution used for these image fallbacks, (larger values will result in more detailed images, but also larger file sizes).

Some examples of natively vector-oriented backends are the ps, pdf, and svg backends.

For backends that are natively raster-oriented, image fallbacks are still possible, but they are always performed at the native device resolution. So this function has no effect on those backends.

Note

The fallback resolution only takes effect at the time of completing a page (with Context->show_page() or Context->copy_page()) so there is currently no way to have more than one fallback resolution in effect on a single page.

The default fallback resolution is 300 pixels per inch in both dimensions.

Parameter x_pixels_per_inch

horizontal setting for pixels per inch

Parameter y_pixels_per_inch

vertical setting for pixels per inch

Method set_mime_data

voidset_mime_data(string(7bit)mime_type, string(8bit)|zerodata)

Description

Attach an image in the format mime_type to surface. To remove the data from a surface, call this function with same mime type and 0 for data.

The attached image (or filename) data can later be used by backends which support it (currently: PDF, PS, SVG and Win32 Printing surfaces) to emit this data instead of making a snapshot of the surface. This approach tends to be faster and requires less memory and disk space.

The recognized MIME types are the following: MIME_TYPE_JPEG, MIME_TYPE_PNG, MIME_TYPE_JP2, MIME_TYPE_URI, MIME_TYPE_UNIQUE_ID, MIME_TYPE_JBIG2, MIME_TYPE_JBIG2_GLOBAL, MIME_TYPE_JBIG2_GLOBAL_ID, MIME_TYPE_CCITT_FAX, MIME_TYPE_CCITT_FAX_PARAMS.

See corresponding backend surface docs for details about which MIME types it can handle. Caution: the associated MIME data will be discarded if you draw on the surface afterwards. Use this function with care.

Even if a backend supports a MIME type, that does not mean cairo will always be able to use the attached MIME data. For example, if the backend does not natively support the compositing operation used to apply the MIME data to the backend. In that case, the MIME data will be ignored. Therefore, to apply an image in all cases, it is best to create an image surface which contains the decoded image data and then attach the MIME data to that. This ensures the image will always be used while still allowing the MIME data to be used whenever possible.

Parameter mime_type

the MIME type of the image data

Parameter data

the image data to attach to the surface

Method show_page

voidshow_page()

Description

Emits and clears the current page for backends that support multiple pages. Use copy_page() if you don't want to clear the page.

There is a convenience function for this in Context, namely Context->show_page().

Method supports_mime_type: boolsupports_mime_type(string(7bit)mime_type)
Description: Return whether surface supports mime_type.
Parameter mime_type: the mime type
Returns: 1 if surface supports mime_type, 0 otherwise

Method unmap_image

voidunmap_image(Surfaceimage)

Description

Unmaps the image surface as returned from map_to_image().

The content of the image will be uploaded to the target surface. Afterwards, the image is destroyed.

Using an image surface which wasn't returned by map_to_image() results in undefined behavior.

Parameter image

the currently mapped image

Class Cairo.SurfacePattern

Description: A pattern based on a surface (an image).

Inherit Pattern: inherit Pattern : Pattern

Method create: Cairo.SurfacePatternCairo.SurfacePattern(Surfacetarget)
Description: Create a new Pattern for the given surface.
Parameter surface: the surface

Method get_surface: Surfaceget_surface()
Description: Gets the surface of a SurfacePattern.
Returns: surface of pattern

Class Cairo.TeeSurface

Description: Redirect input to multiple surfaces

Inherit Surface: inherit Surface : Surface

Method add: voidadd(array(Surface) target)
Description: Adds a new target surface to the list of replicas of a tee surface.
Parameter target: the surface to add

Method create

Cairo.TeeSurfaceCairo.TeeSurface(Surfaceprimary)

Description

Creates a new "tee" surface.

The primary surface is used when querying surface options, like font options and extents.

Operations performed on the tee surface will be replayed on any surface added to it.

Parameter primary

the primary Surface

Method index

Surfaceindex(int(0..)index)

Description

Retrieves the replica surface at the given index.

The primary surface used to create the cairo_tee_surface_t is always set at the zero index.

Parameter index

the index of the replica to retrieve

Returns

the surface at the given index

Method remove: voidremove(Surfacetarget)
Description: Removes the given surface from the list of replicas of a tee surface.
Parameter target: the surface to remove

Class Cairo.TextCluster

Description

Holds information about a single text cluster. A text cluster is a minimal mapping of some glyphs corresponding to some UTF-8 text.

For a cluster to be valid, both num_bytes and num_glyphs should be non-negative, and at least one should be non-zero. Note that clusters with zero glyphs are not as well supported as normal clusters. For example, PDF rendering applications typically ignore those clusters when PDF text is being selected.

See Context->show_text_glyphs() for how clusters are used in advanced text operations.

Variable num_bytes: int Cairo.TextCluster.num_bytes
Description: the number of bytes of UTF-8 text covered by cluster

Variable num_glyphs: int Cairo.TextCluster.num_glyphs
Description: the number of glyphs covered by cluster

Method _sprintf: stringsprintf(stringformat, ... Cairo.TextClusterarg ... )

Method create: Cairo.TextClusterCairo.TextCluster(intnum_bytes, intnum_glyphs)
Parameter num_bytes: the number of bytes of UTF-8 text covered by cluster
Parameter num_glyphs: the number of glyphs covered by cluster

Class Cairo.TextExtents

Description: Stores the extents of a single glyph or a string of glyphs in user-space coordinates. Because text extents are in user-space coordinates, they are mostly, but not entirely, independent of the current transformation matrix. If you call Context->scale(2.0, 2.0), text will be drawn twice as big, but the reported text extents will not be doubled. They will change slightly due to hinting (so you can't assume that metrics are independent of the transformation matrix), but otherwise will remain unchanged.

Variable height: float Cairo.TextExtents.height
Description: height of the glyphs as drawn

Variable width: float Cairo.TextExtents.width
Description: width of the glyphs as drawn

Variable x_advance: float Cairo.TextExtents.x_advance
Description: distance to advance in the X direction after drawing these glyphs

Variable x_bearing: float Cairo.TextExtents.x_bearing
Description: the horizontal distance from the origin to the leftmost part of the glyphs as drawn. Positive if the glyphs lie entirely to the right of the origin.

Variable y_advance: float Cairo.TextExtents.y_advance
Description: distance to advance in the Y direction after drawing these glyphs. Will typically be zero except for vertical text layout as found in East-Asian languages.

Variable y_bearing: float Cairo.TextExtents.y_bearing
Description: the vertical distance from the origin to the topmost part of the glyphs as drawn. Positive only if the glyphs lie completely below the origin; will usually be negative.

Class Cairo.ToyFontFace

Description: Font faces used in implementation of the Context "toy" font API.

Inherit FontFace: inherit FontFace : FontFace

Method create

Cairo.ToyFontFaceCairo.ToyFontFace(stringfamily, intslant, intweight)

Description

Creates a font face from a triplet of family, slant, and weight.

If family is the zero-length string "", the platform-specific default family is assumed. The default family then can be queried using get_family().

The Context->select_font_face() function uses this to create font faces. See that function for limitations and other details of toy font faces.

Parameter family

a font family name

Parameter slant

the slant for the font

Parameter weight

the weight for the font

Method get_family: stringget_family()
Description: Gets the family name of a toy font.
Returns: The family name.

Method get_slant: intget_slant()
Description: Gets the slant a toy font.
Returns: The slant value

Method get_weight: intget_weight()
Description: Gets the weight a toy font.
Returns: The weight value

Class Cairo.XCBSurface

Description: X Window System rendering using the XCB library

Inherit Surface: inherit Surface : Surface

Method set_size

voidset_size(intwidth, intheight)

Description

Informs cairo of the new size of the XCB drawable underlying the surface. For a surface created for a window (rather than a pixmap), this function must be called each time the size of the window changes. (For a subwindow, you are normally resizing the window yourself, but for a toplevel window, it is necessary to listen for ConfigureNotify events.)

A pixmap can never change size, so it is never necessary to call this function on a surface created for a pixmap.

If flush() wasn't called, some pending operations might be discarded.

Parameter width

the new width of the surface

Parameter height

the new height of the surface

Class Cairo.XlibSurface

Description: X Window System rendering using XLib

Inherit Surface: inherit Surface : Surface

Method get_depth: intget_depth()
Description: Get the number of bits used to represent each pixel value.
Returns: the depth of the surface in bits.

Method get_height: intget_height()
Description: Get the height of the X Drawable underlying the surface in pixels.
Returns: the height of the surface in pixels.

Method get_width: intget_width()
Description: Get the width of the X Drawable underlying the surface in pixels.
Returns: the width of the surface in pixels.

Module CommonLog

Description: 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.

Method read

intread(function(array(int|string), int:void) callback, Stdio.File|stringlogfile, void|intoffset)

Description

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.

Parameter callback

The callbacks first argument is an array with the different parts of the log entry.

Array
`stringremote_host`
`int(0)\|stringident_user`
`int(0)\|stringauth_user`
`intyear`
`intmonth`
`intday`
`inthours`
`intminutes`
`intseconds`
`inttimezone`
`int(0)\|stringmethod`	One of "GET", "POST", "HEAD" etc.
`int(0)\|stringpath`
`stringprotocol`	E.g. "HTTP/1.0"
`intreply_code`	One of 200, 404 etc.
`intbytes`

The second callback argument is the current offset to the end of the current line.

Parameter logfile

The logfile to parse. Either an open Stdio.File object, or a string with the path to the logfile.

Parameter offset

The absolute position in the file where the parser should begin. Note that the offset defaults to 0 (zero), NOT the current offset of logfile.

Module DVB

Description: Implements Digital Video Broadcasting interface
Note: Only Linux version is supported.

Class DVB.Audio

Description: Object for controlling an audio subsystem on full featured cards.

Method create: DVB.AudioDVB.Audio(intcard_number)
DVB.AudioDVB.Audio()
Description: Create a Audio object.
Parameter card_number: The number of card equipment.

Method mixer: intmixer(intleft, intright)
intmixer(intboth)
Description: Sets output level on DVB audio device.
See also: mute()

Method mute: intmute(intmute)
intmute()
Description: Mute or unmute audio device.
See also: mixer()

Method status: mappingstatus()
Description: Returns mapping of current audio device status.

Class DVB.Stream

Description: Represents an elementary data stream (PES).

Method _destruct: int_destruct()
Description: Purge a stream reader.
See also: DVB.dvb()->stream(), read()

Method close: voidclose()
Description: Closes an open stream.
See also: read()

Method read: string|intread()
Description: Read data from a stream. It reads up to read buffer size data.
Note: Read buffer size is 4096 by default.
See also: DVB.dvb()->stream(), close()

Method set_buffer: intset_buffer(intlen)
Description: Sets stream's internal buffer.
Note: The size is 4096 by default.
See also: read()

Class DVB.dvb

Description: Main class.

Method analyze_pat

mappinganalyze_pat()

Description

Return mapping of all PMT.

sid:prognum

Method analyze_pmt: array(mapping)|intanalyze_pmt(intsid, intprognum)
Description: Parse PMT table.
See also: analyze_pat()

Method create: DVB.dvbDVB.dvb(intcard_number)
Description: Create a DVB object.
Parameter card_number: The number of card equipment.
Note: 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+

Method fe_info: mappingfe_info()
Description: Return info of a frondend device.
Note: The information heavily depends on driver. Many fields contain dumb values.

Method fe_status

mapping|intfe_status()

Description

Return status of a DVB object's frondend device.

Returns

The resulting mapping contains the following fields:

`"power" : string`	If 1 the frontend is powered up and is ready to be used.
`"signal" : string`	If 1 the frontend detects a signal above a normal noise level
`"lock" : string`	If 1 the frontend successfully locked to a DVB signal
`"carrier" : string`	If 1 carrier dectected in signal
`"biterbi" : string`	If 1 then lock at viterbi state
`"sync" : string`	If 1 then TS sync byte detected
`"tuner_lock" : string`	If 1 then tuner has a frequency lock

Method get_pids: mapping|intget_pids()
Description: Returns mapping with info of currently tuned program's pids.
See also: tune()

Method stream: DVB.Streamstream(intpid, int|function(:void) rcb, intptype)
DVB.Streamstream(intpid, int|function(:void) rcb)
DVB.Streamstream(intpid)
Description: Create a new stream reader object for PID.
Parameter pid: PID of stream.
Parameter rcb: Callback function called whenever there is the data to read from stream. Only for nonblocking mode.
Parameter ptype: Type of payload data to read. By default, audio data is fetched.
Note: Setting async callback doesn't set the object to nonblocking state.
See also: DVB.Stream()->read()

Method tune: inttune(int(2bit)lnb, intfreq, bool|stringpol, intsr)
Description: Tunes to apropriate transponder's parameters.
Parameter lnb: DiSeQc number of LNB.
Parameter freq: Frequency divided by 1000.
Parameter pol: Polarization. 0 or "v" for vertical type, 1 or "h" for horizontal one.
Parameter sr: The service rate parameter.

Module Debug

Inherit _Debug: inherit _Debug : _Debug

Variable globals: mapping Debug.globals
Description: Can be custom filled from within your program in order to have global references to explore live datastructures using Inspect; comes preinitialised with the empty mapping, ready for use.

Method add_to_perf_map: voidadd_to_perf_map(programp)
Description: Updates the perf map file with new program p.
See also: generate_perf_map()
Note: Expects generate_perf_map() to have been called before.

Method assembler_debug: int(0..)assembler_debug(int(0..)level)
Description: Set the assembler debug level.
Returns: The old assembler debug level will be returned.
Note: This function is only available if the Pike runtime has been compiled with RTL debug.

Method compiler_trace: int(0..)compiler_trace(int(0..)level)
Description: Set the compiler trace level.
Returns: The old compiler trace level will be returned.
Note: This function is only available if the Pike runtime has been compiled with RTL debug.

Method count_objects: mapping(string:int) count_objects()
Description: Returns the number of objects of every kind in memory.

Method debug: int(0..)debug(int(0..)level)
Description: Set the run-time debug level.
Returns: The old debug level will be returned.
Note: This function is only available if the Pike runtime has been compiled with RTL debug.

Method describe: mixeddescribe(mixedx)
Description: Prints out a description of the thing x to standard error. The description contains various internal info associated with x.
Note: This function only exists if the Pike runtime has been compiled with RTL debug.

Method describe_encoded_value: intdescribe_encoded_value(stringdata)
Description: Describe the contents of an encode_value() string.
Returns: Returns the number of encoding errors that were detected (if any).

Method describe_program

array(array(int|string|type)) describe_program(programp)

Description

Debug function for showing the symbol table of a program.

Returns

Returns an array of arrays with the following information for each symbol in p:

Array
`intmodifiers`	Bitfield with the modifiers for the symbol.
`stringsymbol_name`	Name of the symbol.
`typevalue_type`	Value type for the symbol.
`intsymbol_type`	Type of symbol.
`intsymbol_offset`	Offset into the code or data area for the symbol.
`intinherit_offset`	Offset in the inherit table to the inherit containing the symbol.
`intinherit_level`	Depth in the inherit tree for the inherit containing the symbol.

Note

The API for this function is not fixed, and has changed since Pike 7.6. In particular it would make sense to return an array of objects instead, and more information about the symbols might be added.

Method disassemble: voiddisassemble(function(:void) fun)
Description: Disassemble a Pike function to Stdio.stderr.
Note: This function is only available if the Pike runtime has been compiled with debug enabled.

Method dmalloc_set_name: voiddmalloc_set_name()
Note: Only available when compiled with dmalloc.

Method dmalloc_set_name: voiddmalloc_set_name(stringfilename, int(1..)linenumber)
Note: Only available when compiled with dmalloc.

Method dump_backlog: voiddump_backlog()
Description: 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.
Note: This function only exists if the Pike runtime has been compiled with RTL debug.

Method dump_dmalloc_locations: voiddump_dmalloc_locations(string|array|mapping|multiset|function(:void)|object|program|typeo)
Note: Only available when compiled with dmalloc.

Method dump_program_tables: voiddump_program_tables(programp, int(0..)|voidindent)
Description: Dumps the internal tables for the program p on stderr.
Parameter p: Program to dump.
Parameter indent: Number of spaces to indent the output.

Method find_all_clones

array(object) find_all_clones(programp, bool|voidinclude_subclasses)

Description

Return an array with all objects that are clones of p.

Parameter p

Program that the objects should be a clone of.

Parameter include_subclasses

If true, include also objects that are clones of programs that have inherited p. Note that this adds significant overhead.

This function is only intended to be used for debug purposes.

See also

map_all_objects()

Method gc_set_watch: voidgc_set_watch(array|multiset|mapping|object|function(:void)|program|stringx)
Description: 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.
Note: This function only exists if the Pike runtime has been compiled with RTL debug.

Method gc_status

mapping(string:int|float) gc_status()

Description

Get statistics from the garbage collector.

Returns

A mapping with the following content will be returned:

`"num_objects" : int`	Number of arrays, mappings, multisets, objects and programs.
`"num_allocs" : int`	Number of memory allocations since the last gc run.
`"alloc_threshold" : int`	Threshold for "num_allocs" when another automatic gc run is scheduled.
`"projected_garbage" : float`	Estimation of the current amount of garbage.
`"objects_alloced" : int`	Decaying average over the number of allocated objects between gc runs.
`"objects_freed" : int`	Decaying average over the number of freed objects in each gc run.
`"last_garbage_ratio" : float`	Garbage ratio in the last gc run.
`"non_gc_time" : int`	Decaying average over the interval between gc runs, measured in real time nanoseconds.
`"gc_time" : int`	Decaying average over the length of the gc runs, measured in real time nanoseconds.
`"last_garbage_strategy" : string`	The garbage accumulation goal that the gc aimed for when setting "alloc_threshold" in the last run. The value is either "garbage_ratio_low", "garbage_ratio_high" or "garbage_max_interval". The first two correspond to the gc parameters with the same names in `Pike.gc_parameters`, and the last is the minimum gc time limit specified through the "min_gc_time_ratio" parameter to `Pike.gc_parameters`.
`"last_gc" : int`	Time when the garbage-collector last ran.
`"total_gc_cpu_time" : int`	The total amount of CPU time that has been consumed in implicit GC runs, in nanoseconds. 0 on systems where Pike lacks support for CPU time measurement.
`"total_gc_real_time" : int`	The total amount of real time that has been spent in implicit GC runs, in nanoseconds.

See also

gc(), Pike.gc_parameters(), Pike.implicit_gc_real_time

Method generate_perf_map: voidgenerate_perf_map()
Description: Generates a perf map file of all Pike code and writes it to /tmp/perf-<pid>.map. This is useful only if pike has been compiled with machine code support. It allows the linux perf tool to determine the correct name of Pike functions that were compiled to machine code by pike.

Method get_program_layout: mapping(string:int) get_program_layout(programp)
Description: Returns a mapping which describes the layout of compiled machine code in the program p. The indices of the returned mapping are function names, the values the starting address of the compiled function. The total size of the program code is stored with index 0.

Method hexdump: voidhexdump(string(8bit)raw)
Description: Write a hexadecimal dump of the contents of raw to Stdio.stderr.

Method list_open_fds: voidlist_open_fds()
Note: Only available when compiled with dmalloc.

Method locate_references: mixedlocate_references(string|array|mapping|multiset|function(:void)|object|program|typeo)
Description: 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.
Note: This function only exists if the Pike runtime has been compiled with RTL debug.

Method map_all_objects

int(0..)map_all_objects(function(object:void) cb)

Description

Call cb for all objects that currently exist. The callback will not be called with destructed objects as it's argument.

Objects might be missed if cb creates new objects or destroys old ones.

This function is only intended to be used for debug purposes.

Returns

The total number of objects

See also

next_object(), find_all_clones()

Method map_all_programs

int(0..)map_all_programs(function(program:void) cb)

Description

Call cb for all programs that currently exist.

Programs might be missed if cb creates new programs.

This function is only intended to be used for debug purposes.

Returns

The total number of programs

See also

map_all_objects()

Method map_all_strings

int(0..)map_all_strings(function(string:void) cb)

Description

Call cb for all strings that currently exist.

strings might be missed if cb creates new strings or destroys old ones.

This function is only intended to be used for debug purposes.

Returns

The total number of strings

See also

next_object()

Method memory_usage

mapping(string:int) memory_usage()

Description

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.

The entries in the mapping are typically paired, with one named "num_" + SYMBOL + "s" containing a count, and the other named SYMBOL + "_bytes" containing a best effort approximation of the size in bytes.

Note

Exactly what fields this function returns is version dependant.

See also

_verify_internals()

Method next

mixednext(mixedx)

Description

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.

See also

next_object(), prev()

Method next_object

objectnext_object(objecto)
objectnext_object()

Description

Returns the next object from the list of all objects.

All objects are stored in a linked list.

Returns

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.

Note

This function is not recomended to use.

See also

destruct()

Method optimizer_debug: int(0..)optimizer_debug(int(0..)level)
Description: Set the optimizer debug level.
Returns: The old optimizer debug level will be returned.
Note: This function is only available if the Pike runtime has been compiled with RTL debug.

Method pp_memory_usage: stringpp_memory_usage()
Description: Returns a pretty printed version of the output from memory_usage.

Method pp_object_usage: stringpp_object_usage()
Description: Returns a pretty printed version of the output from count_objects (with added estimated RAM usage)

Method prev

mixedprev(mixedx)

Description

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.

Note

Unlike next() this function does not work on strings.

See also

next_object(), next()

Method refs

Description

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

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.

See also

next(), prev()

Method remove_from_perf_map: voidremove_from_perf_map(programp)
Description: Removed p from the perf map file.

Method reset_dmalloc: voidreset_dmalloc()
Note: Only available when compiled with dmalloc.

Method size_object

intsize_object(objecto)

Description

Return the aproximate size of the object, in bytes. This might not work very well for native objects

The function tries to estimate the memory usage of variables belonging to the object.

It will not, however, include the size of objects assigned to variables in the object.

If the object has a lfun::_size_object() it will be called without arguments, and the return value will be added to the final size. It is primarily intended to be used by C-objects that allocate memory that is not normally visible to pike.

See also

lfun::_size_object(), sizeof()

Method verify_internals

voidverify_internals()

Description

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.

Note

This function does a more thorough check if the Pike runtime has been compiled with RTL debug.

Enum Debug.DecoderFP

Constant FP_SNAN
Constant FP_QNAN
Constant FP_NINF
Constant FP_PINF
Constant FP_ZERO
Constant FP_PZERO
Constant FP_NZERO: constant Debug.FP_SNAN
constant Debug.FP_QNAN
constant Debug.FP_NINF
constant Debug.FP_PINF
constant Debug.FP_ZERO
constant Debug.FP_PZERO
constant Debug.FP_NZERO

Enum Debug.DecoderTags

Constant TAG_DELAYED
Constant TAG_AGAIN: constant Debug.TAG_DELAYED
constant Debug.TAG_AGAIN

Constant TAG_ARRAY
Constant TAG_MAPPING
Constant TAG_MULTISET
Constant TAG_OBJECT
Constant TAG_FUNCTION
Constant TAG_PROGRAM
Constant TAG_STRING
Constant TAG_FLOAT
Constant TAG_INT
Constant TAG_TYPE: constant Debug.TAG_ARRAY
constant Debug.TAG_MAPPING
constant Debug.TAG_MULTISET
constant Debug.TAG_OBJECT
constant Debug.TAG_FUNCTION
constant Debug.TAG_PROGRAM
constant Debug.TAG_STRING
constant Debug.TAG_FLOAT
constant Debug.TAG_INT
constant Debug.TAG_TYPE

Constant TAG_NEG
Constant TAG_SMALL: constant Debug.TAG_NEG
constant Debug.TAG_SMALL

Enum Debug.EntryTypes

Constant ID_ENTRY_TYPE_CONSTANT
Constant ID_ENTRY_EFUN_CONSTANT
Constant ID_ENTRY_RAW
Constant ID_ENTRY_EOT
Constant ID_ENTRY_VARIABLE
Constant ID_ENTRY_FUNCTION
Constant ID_ENTRY_CONSTANT
Constant ID_ENTRY_INHERIT
Constant ID_ENTRY_ALIAS: constant Debug.ID_ENTRY_TYPE_CONSTANT
constant Debug.ID_ENTRY_EFUN_CONSTANT
constant Debug.ID_ENTRY_RAW
constant Debug.ID_ENTRY_EOT
constant Debug.ID_ENTRY_VARIABLE
constant Debug.ID_ENTRY_FUNCTION
constant Debug.ID_ENTRY_CONSTANT
constant Debug.ID_ENTRY_INHERIT
constant Debug.ID_ENTRY_ALIAS

Enum Debug.PikeTypes

Constant T_ATTRIBUTE
Constant T_NSTRING
Constant T_NAME
Constant T_SCOPE
Constant T_ASSIGN
Constant T_UNKNOWN
Constant T_MIXED
Constant T_NOT
Constant T_AND
Constant T_OR: constant Debug.T_ATTRIBUTE
constant Debug.T_NSTRING
constant Debug.T_NAME
constant Debug.T_SCOPE
constant Debug.T_ASSIGN
constant Debug.T_UNKNOWN
constant Debug.T_MIXED
constant Debug.T_NOT
constant Debug.T_AND
constant Debug.T_OR

Constant T_ARRAY
Constant T_MAPPING
Constant T_MULTISET
Constant T_OBJECT
Constant T_FUNCTION
Constant T_PROGRAM
Constant T_STRING
Constant T_TYPE
Constant T_VOID
Constant T_MANY: constant Debug.T_ARRAY
constant Debug.T_MAPPING
constant Debug.T_MULTISET
constant Debug.T_OBJECT
constant Debug.T_FUNCTION
constant Debug.T_PROGRAM
constant Debug.T_STRING
constant Debug.T_TYPE
constant Debug.T_VOID
constant Debug.T_MANY

Constant T_INT
Constant T_FLOAT: constant Debug.T_INT
constant Debug.T_FLOAT

Constant T_ZERO: constant Debug.T_ZERO

Class Debug.Decoder

Variable input: Stdio.Buffer Debug.Decoder.input

Method __create__: protectedlocalvoid__create__(Stdio.Bufferinput)

Method create: Debug.DecoderDebug.Decoder(Stdio.Bufferinput)

Class Debug.Inspect

Description

Allows for interactive debugging and live data structure inspection in both single- and multi-threaded programs. Creates an independent background thread that every pollinterval will show a list of running threads. Optionally, a triggersignal can be specified which allows the dump to be triggered by a signal.

Example: In the program you'd like to inspect, insert the following one-liner:

Debug.Inspect("/tmp/test.pike");

Then start the program and keep it running. Next you create a /tmp/test.pike with the following content:

void create(){
 werror("Only once per modification of test.pike\n");}int main(){
 werror("This will run every iteration\n");
 werror("By returning 1 here, we disable the stacktrace dumps\n");return 0;}void _destruct(){
 werror("_destruct() runs just as often as create()\n");}

Whenever you edit /tmp/test.pike, it will automatically reload the file.

Variable _callback: string|function(void:void) Debug.Inspect._callback
Description: Either the callback function which is invoked on each iteration, or the name of a file which contains a class which is (re)compiled automatically and called on each iteration.
See also: create

Variable _loopthread: Thread.Thread Debug.Inspect._loopthread
Description: The inspect-thread. It will not appear in the displayed thread-list.

Variable pollinterval: int Debug.Inspect.pollinterval
Description: The polling interval in seconds, defaults to 4.

Variable triggersignal: int Debug.Inspect.triggersignal
Description: If assigned to, it will allow the diagnostics inspection to be triggered by this signal.

Method create: Debug.InspectDebug.Inspect(string|function(void:void)|voidcb)
Description: Starts up the background thread.
Parameter cb: Specifies either the callback function which is invoked on each iteration, or the name of a file which contains a class which is (re)compiled automatically with an optional main() method, which will be called on each iteration. If the main() method returns 0, new stacktraces will be dumped every iteration; if it returns 1, stacktrace dumping will be suppressed.
Note: The compilation and the running of the callback is guarded by a catch(), so that failures (to compile) in that section will not interfere with the running program.
Note: If the list of running threads did not change, displaying the list again will be suppressed.
See also: triggersignal, pollinterval, _loopthread, _callback, Debug.globals

Method inspect: voidinspect()
Description: The internal function which does all the work each pollinterval. Run it directly to force a thread-dump.

Class Debug.Rapidlog

Description: Allows for rapid collection of logdata, which is then fed to the real werror() at idle moments. This allows for logging to occur with minimal timing interference.

Method werror: voidwerror(stringformat, mixed ... args)
Description: Overloads the predef::werror() function to allow floods of logentries while introducing minimal latency. Logs are buffered, and periodically flushed from another thread. If the arrival rate of logs is excessive, it simply skips part of the logs to keep up.
Note: When parts are skipped, records are skipped in whole and will never be split up.
See also: werror_options()

Method werror_options: voidwerror_options(intoptions, void|intpollinterval, void|intdrainrate, void|intmaxbufentries)
Parameter options: Defaults to 0, reserved for future enhancements.
Parameter pollinterval: Pollinterval in seconds for the log-flush thread; defaults to 1. Logs will only be flushed out, if during the last pollinterval no new logs have been added.
Parameter drainrate: Maximum number of lines per second that will be dumped to stderr. Defaults to 10.
Parameter maxbufentries: Maximum number of buffered logrecords which have not been flushed to stderr yet. If this number is exceeded, the oldest maxbufentries/2 entries will be skipped; a notice to that effect is logged to stderr.
See also: werror()

Class Debug.Subject

Description

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.

Example

> object s = Debug.Subject();
 create()
 > random(s);
 _random()
 (1) Result: 0
 > abs(s);
 `<(0)
 _sprintf(79, ([ ]))
 (2) Result: Debug.Subject
 > abs(class { inherit Debug.Subject; int `<(mixed ... args) { return 1; } }());
 create()
 `-()
 _destruct()
 (3) Result: 0
 > pow(s,2);
 `[]("pow")
 Attempt to call the NULL-value
 Unknown program: 0(2)

Class Debug.Tracer

Description: A class that when instatiated will turn on trace, and when it's destroyed will turn it off again.

Method create: Debug.TracerDebug.Tracer(intlevel)
Description: Sets the level of debug trace to level.

Class Debug.Wrapper

Description

This wrapper can be placed around another object to get printouts about what is happening to it. Only a few LFUNs are currently supported.

Example

> 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

Method _indices: arrayindices(Debug.Wrapperarg)

Method _sizeof: intsizeof(Debug.Wrapperarg)

Method _sprintf: stringsprintf(stringformat, ... Debug.Wrapperarg ... )

Method _values: arrayvalues(Debug.Wrapperarg)

Method `!: bool res = !Debug.Wrapper()

Method `->: mixed res = Debug.Wrapper()->X

Method `[]: mixed res = Debug.Wrapper()[ x ]

Method create: Debug.WrapperDebug.Wrapper(objectx)

Module Debug.Profiling

Method display

Description

Show profiling information in a more-or-less readable manner. This only works if pike has been compiled with profiling support.

The function will print to stderr using werror.

This is mainly here for use from the Debug.Watchdog class, if you want to do your own formatting or output to some other channel use get_prof_info instead.

Method get_prof_info

Description

Collect profiling data.

This will return the CPU usage, by function, since the last time the function was called.

The returned array contains the following entries per entry:

Array
`stringname`	The name of the function.
`intnumber_of_calls`	The number of calls.
`floattotal_self_time`	Total self CPU time in milliseconds.
`floattotal_cpu_time`	Total self CPU time in milliseconds, including children.
`floatavg_self_time`	Average self CPU time in microseconds.
`floatavg_cpu_time`	Average self CPU time in microseconds, including children.
`floatself_time_pct`	The self CPU time as percentage of total time.
`floatcpu_time_pct`	The self CPU time, including children, as percentage of total time.
`stringfunction_line`	Function's definition source location.

Module DefaultCompilerEnvironment

Description: The CompilerEnvironment object that is used for loading C-modules and by predef::compile().
Note: predef::compile() is essentially an alias for the CompilerEnvironment()->compile() in this object.
See also: CompilerEnvironment, predef::compile()

Inherit CompilerEnvironment: inherit CompilerEnvironment : CompilerEnvironment

Module Error

Method mkerror: objectmkerror(mixederror)
Description: Returns an Error object for any argument it receives. If the argument already is an Error object or is empty, it does nothing.

Class Error.Generic

Description: Class for exception objects for errors of unspecified type.

Variable error_backtrace

array(backtrace_frame|array(mixed)) Error.Generic.error_backtrace

Description

The backtrace as returned by backtrace where the error occurred.

Code that catches and rethrows errors should ensure that this remains the same in the rethrown error.

Variable error_message

string Error.Generic.error_message

Description

The error message. It always ends with a newline ('\n') character and it might be more than one line.

Code that catches and rethrows errors may extend this with more error information.

Method _is_type: bool res = is_type(Error.Generic())
Description: Claims that the error object is an array, for compatibility with old style error handling code.

Method _sprintf: stringsprintf(stringformat, ... Error.Genericarg ... )

Method `[]

array|string res = Error.Generic()[ index ]

Description

Index operator.

Simulates an array

Array
`stringmsg`	Error message as returned by `message`.
`arraybacktrace`	Backtrace as returned by `backtrace`.

Note

The error message is always terminated with a newline.

See also

backtrace()

Method backtrace: arraybacktrace()
Description: Return the backtrace where the error occurred. Normally simply returns error_backtrace.
See also: predef::backtrace()

Method cast: (array)Error.Generic()
Description: Cast operator.
Note: The only supported type to cast to is "array", which generates an old-style error ({message(), backtrace()}).

Method create: Error.GenericError.Generic(stringmessage, void|array(backtrace_frame|array(mixed)) backtrace)

Method describe: stringdescribe()
Description: Return a readable error report that includes the backtrace.

Method message

stringmessage()

Description

Return a readable message describing the error. Normally simply returns error_message.

If you override this function then you should ensure that error_message is included in the returned message, since there might be code that catches your error objects, extends error_message with more info, and rethrows the error.

Module Filesystem

Method `(): protectedfunction(:void) `()(void|stringpath)
Description: FIXME: Document this function

Method get_filesystem: programget_filesystem(stringwhat)
Description: FIXME: Document this function

Method parse_mode: intparse_mode(intold, int|stringmode)
Description: FIXME: Document this function

Class Filesystem.Base

Description: Baseclass that can be extended to create new filesystems. Is used by the Tar and System filesystem classes.

Method apply: intapply()
Description: FIXME: Document this function

Method cd: Basecd(string|voiddirectory)
Description: Change directory within the filesystem. Returns a new filesystem object with the given directory as cwd.

Method chmod: voidchmod(stringfilename, int|stringmode)
Description: Change mode of a file or directory.

Method chown: voidchown(stringfilename, int|objectowner, int|objectgroup)
Description: Change ownership of the file or directory

Method chroot: Basechroot(void|stringdirectory)
Description: Change the root of the filesystem.

Method cwd: stringcwd()
Description: Returns the current working directory within the filesystem.

Method find: arrayfind(void|function(Stat:int) mask, mixed ... extra)
Description: FIXME: Document this function

Method get_dir: array(string) get_dir(void|stringdirectory, void|string|arrayglob)
Description: Returns an array of all files and directories within a given directory.
Parameter directory: Directory where the search should be made within the filesystem. CWD is assumed if none (or 0) is given.
Parameter glob: Return only files and dirs matching the glob (if given).
See also: [get_stats]

Method get_stats: array(Stat) get_stats(void|stringdirectory, void|string|arrayglob)
Description: Returns stat-objects for the files and directories matching the given glob within the given directory.
See also: [get_dir]

Method mkdir: intmkdir(stringdirectory, void|int|stringmode)
Description: Create a new directory

Method open: Stdio.Fileopen(stringfilename, stringmode)
Description: Open a file within the filesystem
Returns: A Stdio.File object.

Method rm: intrm(stringfilename)
Description: Remove a file from the filesystem.

Method stat: Statstat(stringfile, int|voidlstat)
Description: Return a stat-object for a file or a directory within the filesystem.

Class Filesystem.Stat

Description: Describes the stat of a file

Variable isblk

bool Filesystem.Stat.isblk

Description

fifo: Is the file a FIFO?
chr: Is the file a character device?
dir: Is the file (?) a directory?
blk: Is the file a block device?
reg: Is the file a regular file?
lnk: Is the file a link to some other file or directory?
sock: Is the file a socket?
door: FIXME: Document this function.

Returns

1 if the file is of a specific type 0 if the file is not.

See also

[set_type]

Note

Read only

Variable ischr

bool Filesystem.Stat.ischr

Description

fifo: Is the file a FIFO?
chr: Is the file a character device?
dir: Is the file (?) a directory?
blk: Is the file a block device?
reg: Is the file a regular file?
lnk: Is the file a link to some other file or directory?
sock: Is the file a socket?
door: FIXME: Document this function.

Returns

1 if the file is of a specific type 0 if the file is not.

See also

[set_type]

Note

Read only

Variable isdir

bool Filesystem.Stat.isdir

Description

fifo: Is the file a FIFO?
chr: Is the file a character device?
dir: Is the file (?) a directory?
blk: Is the file a block device?
reg: Is the file a regular file?
lnk: Is the file a link to some other file or directory?
sock: Is the file a socket?
door: FIXME: Document this function.

Returns

1 if the file is of a specific type 0 if the file is not.

See also

[set_type]

Note

Read only

Variable isdoor

bool Filesystem.Stat.isdoor

Description

fifo: Is the file a FIFO?
chr: Is the file a character device?
dir: Is the file (?) a directory?
blk: Is the file a block device?
reg: Is the file a regular file?
lnk: Is the file a link to some other file or directory?
sock: Is the file a socket?
door: FIXME: Document this function.

Returns

1 if the file is of a specific type 0 if the file is not.

See also

[set_type]

Note

Read only

Variable isfifo

bool Filesystem.Stat.isfifo

Description

fifo: Is the file a FIFO?
chr: Is the file a character device?
dir: Is the file (?) a directory?
blk: Is the file a block device?
reg: Is the file a regular file?
lnk: Is the file a link to some other file or directory?
sock: Is the file a socket?
door: FIXME: Document this function.

Returns

1 if the file is of a specific type 0 if the file is not.

See also

[set_type]

Note

Read only

Variable islnk

bool Filesystem.Stat.islnk

Description

fifo: Is the file a FIFO?
chr: Is the file a character device?
dir: Is the file (?) a directory?
blk: Is the file a block device?
reg: Is the file a regular file?
lnk: Is the file a link to some other file or directory?
sock: Is the file a socket?
door: FIXME: Document this function.

Returns

1 if the file is of a specific type 0 if the file is not.

See also

[set_type]

Note

Read only

Variable isreg

bool Filesystem.Stat.isreg

Description

fifo: Is the file a FIFO?
chr: Is the file a character device?
dir: Is the file (?) a directory?
blk: Is the file a block device?
reg: Is the file a regular file?
lnk: Is the file a link to some other file or directory?
sock: Is the file a socket?
door: FIXME: Document this function.

Returns

1 if the file is of a specific type 0 if the file is not.

See also

[set_type]

Note

Read only

Variable issock

bool Filesystem.Stat.issock

Description

fifo: Is the file a FIFO?
chr: Is the file a character device?
dir: Is the file (?) a directory?
blk: Is the file a block device?
reg: Is the file a regular file?
lnk: Is the file a link to some other file or directory?
sock: Is the file a socket?
door: FIXME: Document this function.

Returns

1 if the file is of a specific type 0 if the file is not.

See also

[set_type]

Note

Read only

Method attach_statarray: voidattach_statarray(array(int) a)
Description: Fills the stat-object with data from a Stdio.File.stat() call.

Method cd: object|zerocd()
Description: Change to the stated directory.
Returns: the directory if the stated object was a directory, 0 otherwise.

Method nice_date: stringnice_date()
Description: Returns the date of the stated object as cleartext.

Method open: Stdio.Fileopen(stringmode)
Description: Open the stated file within the filesystem
Returns: a [Stdio.File] object
See also: [Stdio.File]

Method set_type

voidset_type(stringx)

Description

Set a type for the stat-object.

Note

This call doesnot change the filetype in the underlaying filesystem.

Parameter x

Type to set. Type is one of the following:

fifo
chr
dir
blk
reg
lnk
sock
door

See also

[isfifo], [ischr], [isdir], [isblk], [isreg], [islnk], [issock], [isdoor]

Class Filesystem.System

Description: Implements an abstraction of the normal filesystem.

Inherit Base: inherit Filesystem.Base : Base

Method create: Filesystem.SystemFilesystem.System(void|stringdirectory, void|stringroot, void|intfast, void|Filesystem.Baseparent)
Description: Instanciate a new object representing the filesystem.
Parameter directory: The directory (in the real filesystem) that should become the root of the filesystemobject.
Parameter root: Internal
Parameter fast: Internal
Parameter parent: Internal

Class Filesystem.Traversion

Description

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:

Example

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
   }

Method create: Filesystem.TraversionFilesystem.Traversion(stringpath, void|boolsymlink, void|boolignore_errors, void|function(array:array) sort_fun)
Parameter path: The root path from which to traverse.
Parameter symlink: Don't traverse symlink directories.
Parameter ignore_errors: Ignore directories that can not be accessed.
Parameter sort_fun: Sort function to be applied to directory entries before traversing. Can also be a filter function.

Method progress: floatprogress(void|floatshare)
Description: 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.

Method stat: Stdio.Stat|zerostat()
Description: Returns the stat for the current index-value-pair.

Module Filesystem.Monitor

Class Filesystem.Monitor.basic

Description

Basic filesystem monitor.

This module is intended to be used for incremental scanning of a filesystem.

Supports FSEvents on MacOS X and Inotify on Linux to provide low overhead monitoring; other systems use a less efficient polling approach.

See also

Filesystem.Monitor.symlinks, System.FSEvents, System.Inotify

Constant default_file_interval_factor

protected constantint Filesystem.Monitor.basic.default_file_interval_factor

Description

The default factor to multiply default_max_dir_check_interval with to get the maximum number of seconds between checks of files.

The value can be changed by calling create().

The value can be overridden for individual files or directories by calling monitor().

Overload this constant to change the default.

Constant default_max_dir_check_interval

protected constantint Filesystem.Monitor.basic.default_max_dir_check_interval

Description

The default maximum number of seconds between checks of directories in seconds.

This value is multiplied with default_file_interval_factor to get the corresponding default maximum number of seconds for files.

The value can be changed by calling create().

The value can be overridden for individual files or directories by calling monitor().

Overload this constant to change the default.

Constant default_stable_time: protected constantint Filesystem.Monitor.basic.default_stable_time
Description: The default minimum number of seconds without changes for a change to be regarded as stable (see stable_data_change().

Variable backend

protectedPike.Backend Filesystem.Monitor.basic.backend

Description

Backend to use.

If 0 (zero) - use the default backend.

Variable co_id: protectedmixed Filesystem.Monitor.basic.co_id
Description: Call-out identifier for backend_check() if in nonblocking mode.
See also: set_nonblocking(), set_blocking()

Variable monitor_mutex: protectedThread.Mutex Filesystem.Monitor.basic.monitor_mutex
Description: Mutex controlling access to monitor_queue.

Variable monitor_queue

protectedADT.Heap(< Monitor >) Filesystem.Monitor.basic.monitor_queue

Description

Heap containing active Monitors that need polling.

The heap is sorted on Monitor()->next_poll.

Variable monitors

protectedmapping(string:Monitor) Filesystem.Monitor.basic.monitors

Description

Mapping from monitored path to corresponding Monitor.

The paths are normalized to canonic_path(path),

Note

All filesystems are handled as if case-sensitive. This should not be a problem for case-insensitive filesystems as long as case is maintained.

Method adjust_monitor: protectedvoidadjust_monitor(Monitorm)
Description: Update the position in the monitor_queue for the monitor m to account for an updated next_poll value.

Method attr_changed

voidattr_changed(stringpath, Stdio.Statst)

Description

File attribute changed callback.

Parameter path

Path of the file or directory which has changed attributes.

Parameter st

Status information for path as obtained by file_stat(path, 1).

This function is called when a change has been detected for an attribute for a monitored file or directory.

Called by check() and check_monitor().

Note

If there is a data_changed() callback, it may supersede this callback if the file content also has changed.

Overload this to do something useful.

Method backend_check

protectedvoidbackend_check()

Description

Backend check callback function.

This function is intended to be called from a backend, and performs a check() followed by rescheduling itself via a call to set_nonblocking().

See also

check(), set_nonblocking()

Method canonic_path: protectedstringcanonic_path(stringpath)
Description: Canonicalize a path.
Parameter path: Path to canonicalize.
Returns: The default implementation returns combine_path(path, "."), i.e. no trailing slashes.

Method check

intcheck(int|voidmax_wait, int|voidmax_cnt, mapping(string:int)|voidret_stats)

Description

Check for changes.

Parameter max_wait

Maximum time in seconds to wait for changes. -1 for infinite wait.

Parameter max_cnt

Maximum number of paths to check in this call. 0 (zero) for unlimited.

Parameter ret_stats

Optional mapping that will be filled with statistics (see below).

A suitable subset of the monitored files will be checked for changes.

Returns

The function returns when either a change has been detected or when max_wait has expired. The returned value indicates the number of seconds until the next call of check().

If ret_stats has been provided, it will be filled with the following entries:

`"num_monitors" : int`	The total number of active monitors when the scan completed.
`"scanned_monitors" : int`	The number of monitors that were scanned for updates during the call.
`"updated_monitors" : int`	The number of monitors that were updated during the call.
`"idle_time" : int`	The number of seconds that the call slept.

Note

Any callbacks will be called from the same thread as the one calling check().

See also

check_all(), monitor()

Method check_all

voidcheck_all(mapping(string:int)|voidret_stats)

Description

Check all monitors for changes.

Parameter ret_stats

Optional mapping that will be filled with statistics (see below).

All monitored paths will be checked for changes.

Note

You typically don't want to call this function, but instead check().

Note

Any callbacks will be called from the same thread as the one calling check().

See also

check(), monitor()

Method check_monitor

protectedboolcheck_monitor(Monitorm, MonitorFlags|voidflags)

Description

Check a single Monitor for changes.

Parameter m

Monitor to check.

Parameter flags

`0`	Don't recurse.
`1`	Check all monitors for the entire subtree rooted in `m`.

This function is called by check() for the Monitors it considers need checking. If it detects any changes an appropriate callback will be called.

Returns

Returns 1 if a change was detected and 0 (zero) otherwise.

Note

Any callbacks will be called from the same thread as the one calling check_monitor().

Note

The return value can not be trusted to return 1 for all detected changes in recursive mode.

See also

check(), data_changed(), attr_changed(), file_created(), file_deleted(), stable_data_change()

Method clear: voidclear()
Description: Clear the set of monitored files and directories.
Note: Due to circular datastructures, it's recomended to call this function prior to discarding the object.

Method create: Filesystem.Monitor.basicFilesystem.Monitor.basic(int|voidmax_dir_check_interval, int|voidfile_interval_factor, int|voidstable_time)
Description: Create a new monitor.
Parameter max_dir_check_interval: Override of default_max_dir_check_interval.
Parameter file_interval_factor: Override of default_file_interval_factor.
Parameter stable_time: Override of default_stable_time.

Method data_changed

voiddata_changed(stringpath)

Description

File content changed callback.

Parameter path

Path of the file which has had content changed.

This function is called when a change has been detected for a monitored file.

Called by check() and check_monitor().

Overload this to do something useful.

Method file_created

voidfile_created(stringpath, Stdio.Statst)

Description

File creation callback.

Parameter path

Path of the new file or directory.

Parameter st

Status information for path as obtained by file_stat(path, 1).

This function is called when either a monitored path has started existing, or when a new file or directory has been added to a monitored directory.

Called by check() and check_monitor().

Overload this to do something useful.

Note

This callback has similar semantics to file_exists(), but is called at run time.

See also

file_exists(), file_deleted(), stable_data_change()

Method file_deleted

voidfile_deleted(stringpath)

Description

File deletion callback.

Parameter path

Path of the new file or directory that has been deleted.

This function is called when either a monitored path has stopped to exist, or when a file or directory has been deleted from a monitored directory.

Called by check() and check_monitor().

Overload this to do something useful.

See also

file_created(), file_exists(), stable_data_change()

Method file_exists

voidfile_exists(stringpath, Stdio.Statst)

Description

File existance callback.

Parameter path

Path of the file or directory.

Parameter st

Status information for path as obtained by file_stat(path, 1).

This function is called during initialization for all monitored paths, and subpaths for monitored directories. It represents the initial state for the monitor.

Note

For directories, file_exists() will be called for the subpaths before the call for the directory itself. This can be used to detect when the initialization for a directory is finished.

Called by check() and check_monitor() the first time a monitored path is checked (and only if it exists).

Overload this to do something useful.

Note

This callback has similar semantics to file_created(), but is called at initialization time.

See also

file_created(), file_deleted(), stable_data_change()

Method inotify_event: protectedvoidinotify_event(intwd, intevent, intcookie, string(8bit)path)
Description: Event callback for Inotify.

Method is_monitored: boolis_monitored(stringpath)
Description: Check whether a path is monitored or not.
Parameter path: Path to check.
Returns: Returns 1 if there is a monitor on path, and 0 (zero) otherwise.
See also: monitor(), release()

Method low_eventstream_callback: protectedvoidlow_eventstream_callback(stringpath, intflags, intevent_id)
Description: This function is called when the FSEvents EventStream detects a change in one of the monitored directories.

Method monitor

Description

Parameter path

Path to monitor.

Parameter flags

`0`	Don't recurse.
`1`	Monitor the entire subtree, and any directories or files that may appear later.
`3`	Monitor the entire subtree, and any directories or files that may appear later. Remove the monitor automatically when `path` is deleted.

Parameter max_dir_check_interval

Override of default_max_dir_check_interval for this path or subtree.

Parameter file_interval_factor

Override of default_file_interval_factor for this path or subtree.

Parameter stable_time

Override of default_stable_time for this path or subtree.

See also

release()

Method monitor_factory

protectedDefaultMonitormonitor_factory(stringpath, MonitorFlags|voidflags, int(0..)|voidmax_dir_check_interval, int(0..)|voidfile_interval_factor, int(0..)|voidstable_time)

Description

Create a new Monitor for a path.

This function is called by monitor() to create a new Monitor object.

The default implementation just calls DefaultMonitor with the same arguments.

See also

monitor(), DefaultMonitor

Method release

voidrelease(stringpath, MonitorFlags|voidflags)

Description

Release a path from monitoring.

Parameter path

Path to stop monitoring.

Parameter flags

`0`	Don't recurse.
`1`	Release the entire subtree.
`3`	Release the entire subtree, but only those paths that were added automatically by a recursive monitor.

See also

monitor()

Method release_monitor: protectedvoidrelease_monitor(Monitorm)
Description: Release a single Monitor from monitoring.
See also: release()

Method report

protectedvoidreport(SeverityLevellevel, string(7bit)fun, sprintf_formatformat, sprintf_args ... args)

Description

Event tracing callback.

Parameter level

Severity level of the event.

Parameter fun

Name of the function that called report().

Parameter format

sprintf() formatting string describing the event.

Parameter args

Optional extra arguments for the format string.

This function is called in various places to provide granular tracing of the monitor state.

The default implementation calls werror() with format and args if level is ERROR or higher, or if FILESYSTEM_MONITOR_DEBUG has been defined.

Method reschedule_backend_check

protectedvoidreschedule_backend_check(int|voidsuggested_t)

Description

Reschedule beckend check.

Parameter suggested_t

Suggested time in seconds until next call of check().

check() and thus all the callbacks will be called from the backend thread.

Method set_backend: voidset_backend(Pike.Backend|voidbackend)
Description: Change backend.
Parameter backend: Backend to use. 0 (zero) for the default backend.

Method set_blocking: voidset_blocking()
Description: Turn off nonblocking mode.
See also: set_nonblocking()

Method set_file_interval_factor: voidset_file_interval_factor(intfile_interval_factor)
Description: Set the file_interval_factor.

Method set_max_dir_check_interval: voidset_max_dir_check_interval(intmax_dir_check_interval)
Description: Set the max_dir_check_interval.

Method set_nonblocking

voidset_nonblocking(int|voidsuggested_t)

Description

Turn on nonblocking mode.

Parameter suggested_t

Suggested time in seconds until next call of check().

check() and thus all the callbacks will be called from the backend thread.

Note

If nonblocking mode is already active, this function will be a noop.

See also

set_blocking(), check().

Method set_stable_time: voidset_stable_time(intstable_time)
Description: Set the stable_time.

Method stable_data_change

voidstable_data_change(stringpath, Stdio.Statst)

Description

Stable change callback.

Parameter path

Path of the file or directory that has stopped changing.

Parameter st

Status information for path as obtained by file_stat(path, 1).

This function is called when previous changes to path are considered "stable".

"Stable" in this case means that there have been no detected changes for at lease stable_time seconds.

Called by check() and check_monitor().

Overload this to do something useful.

Note

This callback being called does not mean that the contents or inode has changed, just that they don't seem to change any more. In particular it is called for paths found during initialization after stable_time seconds have passed.

See also

file_created(), file_exists(), file_deleted()

Enum Filesystem.Monitor.basic.MonitorFlags

Description: Flags for Monitors.

Constant MF_RECURSE
Constant MF_AUTO
Constant MF_INITED
Constant MF_HARD: constant Filesystem.Monitor.basic.MF_RECURSE
constant Filesystem.Monitor.basic.MF_AUTO
constant Filesystem.Monitor.basic.MF_INITED
constant Filesystem.Monitor.basic.MF_HARD

Class Filesystem.Monitor.basic.DefaultMonitor

Description

This symbol evaluates to the Monitor class used by the default implementation of monitor_factory().

It is currently one of the values Monitor, EventStreamMonitor or InotifyMonitor.

See also

monitor_factory()

Inherit Monitor: inherit Monitor : Monitor

Class Filesystem.Monitor.basic.EventStreamMonitor

Description: FSEvents EventStream-accelerated Monitor.

Inherit Monitor: inherit Monitor : Monitor

Class Filesystem.Monitor.basic.InotifyMonitor

Description: Inotify-accelerated Monitor.

Inherit Monitor: inherit Monitor : Monitor

Class Filesystem.Monitor.basic.Monitor

Description: Monitoring information for a single filesystem path.
See also: monitor()

Inherit Element: inherit ADT.Heap.Element(< Monitor >) : Element

Variable path
Variable flags
Variable max_dir_check_interval
Variable file_interval_factor
Variable stable_time: string Filesystem.Monitor.basic.Monitor.path
MonitorFlags Filesystem.Monitor.basic.Monitor.flags
int Filesystem.Monitor.basic.Monitor.max_dir_check_interval
int Filesystem.Monitor.basic.Monitor.file_interval_factor
int Filesystem.Monitor.basic.Monitor.stable_time

Method __create__: protectedlocalvoid__create__(stringpath, MonitorFlagsflags, intmax_dir_check_interval, intfile_interval_factor, intstable_time)

Method attr_changed

protectedvoidattr_changed(stringpath, Stdio.Statst)

Description

File attribute or content changed callback.

Parameter st

Status information for path as obtained by file_stat(path, 1).

This function is called when a change has been detected for an attribute for a monitored file or directory.

Called by check() and check_monitor().

The default implementation calls global::attr_changed() or global::data_changed() depending on the state.

Note

If there is a data_changed() callback, it may supersede this callback if the file content also has changed.

Method bump

voidbump(MonitorFlags|voidflags, int|voidseconds)

Description

Bump the monitor to an earlier scan time.

Parameter flags

`0`	Don't recurse.
`1`	Check all monitors for the entire subtree.

Parameter seconds

Number of seconds from now to run next scan. Defaults to half of the remaining interval.

Method call_callback: protectedvoidcall_callback(function(string, Stdio.Stat|void:void) cb, stringpath, Stdio.Stat|voidst)
Description: Call a notification callback.
Parameter cb: Callback to call or UNDEFINED for no operation.
Parameter path: Path to notify on.
Parameter st: Stat for the path.

Method check

boolcheck(MonitorFlags|voidflags)

Description

Check for changes.

Parameter flags

`0`	Don't recurse.
`1`	Check all monitors for the entire subtree rooted in `m`.

This function is called by check() for the Monitors it considers need checking. If it detects any changes an appropriate callback will be called.

Returns

Returns 1 if a change was detected and 0 (zero) otherwise.

Note

Any callbacks will be called from the same thread as the one calling check_monitor().

Note

The return value can not be trusted to return 1 for all detected changes in recursive mode.

See also

check(), data_changed(), attr_changed(), file_created(), file_deleted(), stable_data_change()

Method check_for_release: voidcheck_for_release(intmask, intflags)
Description: Check if this monitor should be removed automatically.

Method file_created

protectedvoidfile_created(stringpath, Stdio.Statst)

Description

File creation callback.

Parameter st

Status information for path as obtained by file_stat(path, 1).

This function is called when either a monitored path has started existing, or when a new file or directory has been added to a monitored directory.

Called by check() and check_monitor().

The default implementation registers the path, and calls global::file_deleted().

Note

This callback has similar semantics to file_exists(), but is called at run time.

See also

file_exists(), file_deleted(), stable_data_change()

Method file_deleted

protectedvoidfile_deleted(stringpath, Stdio.Stat|voidold_st)

Description

File deletion callback.

Parameter path

Path of the new file or directory that has been deleted.

Parameter old_st

Stat for the file prior to deletion (if known). Note that this argument is not passed along to top level function.

This function is called when either a monitored path has stopped to exist, or when a file or directory has been deleted from a monitored directory.

Called by check() and check_monitor().

The default implementation unregisters the path, and calls global::file_deleted().

See also

file_created(), file_exists(), stable_data_change()

Method file_exists

protectedvoidfile_exists(stringpath, Stdio.Statst)

Description

File existance callback.

Parameter st

Status information for path as obtained by file_stat(path, 1).

This function is called during initialization for all monitored paths, and subpaths for monitored directories. It represents the initial state for the monitor.

Note

For directories, file_created() will be called for the subpaths before the call for the directory itself. This can be used to detect when the initialization for a directory is finished.

Called by check() and check_monitor() the first time a monitored path is checked (and only if it exists).

The default implementation registers the path, and calls global::file_exists().

Note

This callback has similar semantics to file_created(), but is called at initialization time.

See also

file_created(), file_deleted(), stable_data_change()

Method monitor: protectedvoidmonitor(stringpath, intflags, intmax_dir_interval, intfile_interval_factor, intstable_time)
Description: Called to create a sub monitor.

Method parent: this_programparent()
Description: Returns the parent monitor, or UNDEFINED if no such monitor exists.

Method register_path: protectedvoidregister_path(int|voidinitial)
Description: Register the Monitor with the monitoring system.
Parameter initial: Indicates that the Monitor is newly created.

Method report

protectedvoidreport(SeverityLevellevel, string(7bit)fun, sprintf_formatformat, sprintf_args ... args)

Description

Event tracing callback.

Parameter level

Severity level of the event.

Parameter fun

Name of the function that called report().

Parameter format

sprintf() formatting string describing the event.

Parameter args

Optional extra arguments for the format string.

This function is called in various places to provide granular tracing of the monitor state.

The default implementation just calls global::report() with the same arguments.

Method stable_data_change

protectedvoidstable_data_change(stringpath, Stdio.Statst)

Description

Stable change callback.

Parameter st

Status information for path as obtained by file_stat(path, 1).

This function is called when previous changes to path are considered "stable".

"Stable" in this case means that there have been no detected changes for at lease stable_time seconds.

Called by check() and check_monitor().

The default implementation calls global::stable_data_change().

Note

See also

file_created(), file_exists(), file_deleted()

Method status_change: protectedboolstatus_change(Stdio.Statold_st, Stdio.Statst, intorig_flags, intflags)
Description: Called when the status has changed for an existing file.

Method submonitor_released: voidsubmonitor_released(this_programsubmon)
Description: To be called when a (direct) submonitor is released.

Method unregister_path: protectedvoidunregister_path(int|voiddying)
Description: Unregister the Monitor from the monitoring system.
Parameter dying: Indicates that the Monitor is being destructed. It is the destruction cause value offset by one.

Method update

protectedvoidupdate(Stdio.Statst)

Description

Calculate and set a suitable time for the next poll of this monitor.

Parameter st

New stat for the monitor.

This function is called by check() to schedule the next check.

Class Filesystem.Monitor.debug

Description

Debugging filesystem monitor.

This module behaves as symlinks, but has default implementations of all callbacks that call report(), as well as an implementation of [report()] that logs everything to Stdio.stderr.

See also

Filesystem.Monitor.basic, Filesystem.Monitor.symlinks

Inherit "symlinks.pike": inherit "symlinks.pike" : "symlinks.pike"

Method get_monitors: mapping(string:Monitor) get_monitors()
Description: Return the set of active monitors.

Class Filesystem.Monitor.symlinks

Description

Filesystem monitor with support for symbolic links.

This module extends Filesystem.Monitor.basic with support for symbolic links.

Note

For operating systems where symbolic links aren't supported, this module will behave exactly like Filesystem.Monitor.basic.

See also

Filesystem.Monitor.basic

Inherit basic: inherit Filesystem.Monitor.basic : basic

Variable available_ids: protectedint Filesystem.Monitor.symlinks.available_ids
Description: Bitmask of all unallocated symlink ids.

Variable symlink_ids: protectedmapping(string:int) Filesystem.Monitor.symlinks.symlink_ids
Description: Mapping from symlink name to symlink id.

Variable symlink_targets: protectedmapping(string:string) Filesystem.Monitor.symlinks.symlink_targets
Description: Mapping from symlink name to symlink target.

Method allocate_symlink: protectedintallocate_symlink(stringsym)
Description: Allocates a symlink id for the link sym.

Method attr_changed

voidattr_changed(stringpath, Stdio.Statst)

Description

File attribute changed callback.

Parameter path

Path of the file or directory which has changed attributes.

Parameter st

Status information for path as obtained by file_stat(path).

This function is called when a change has been detected for an attribute for a monitored file or directory.

Called by check() and check_monitor().

Note

If there is a data_changed() callback, it may supersede this callback if the file content also has changed.

Note

It differs from the Filesystem.Monitor.basic version in that symbolic links have the st of their targets.

Overload this to do something useful.

Method file_created

voidfile_created(stringpath, Stdio.Statst)

Description

File creation callback.

Parameter path

Path of the new file or directory.

Parameter st

Status information for path as obtained by file_stat(path).

This function is called when either a monitored path has started existing, or when a new file or directory has been added to a monitored directory.

Note

It differs from the Filesystem.Monitor.basic version in that symbolic links have the st of their targets.

Called by check() and check_monitor().

Overload this to do something useful.

Method file_exists

voidfile_exists(stringpath, Stdio.Statst)

Description

File existance callback.

Parameter path

Path of the file or directory.

Parameter st

Status information for path as obtained by file_stat(path).

This function is called during initialization for all monitored paths, and subpaths for monitored directories. It represents the initial state for the monitor.

Note

For directories, file_created() will be called for the subpaths before the call for the directory itself. This can be used to detect when the initialization for a directory is finished.

Note

It differs from the Filesystem.Monitor.basic version in that symbolic links have the st of their targets.

Called by check() and check_monitor() the first time a monitored path is checked (and only if it exists).

Overload this to do something useful.

Method stable_data_change

voidstable_data_change(stringpath, Stdio.Statst)

Description

Stable change callback.

Parameter path

Path of the file or directory that has stopped changing.

Parameter st

Status information for path as obtained by file_stat(path).

This function is called when previous changes to path are considered "stable".

"Stable" in this case means that there have been no detected changes for at lease stable_time seconds.

Note

It differs from the Filesystem.Monitor.basic version in that symbolic links have the st of their targets.

Called by check() and check_monitor().

Overload this to do something useful.

Class Filesystem.Monitor.symlinks.DefaultMonitor

Description

Monitoring information for a single filesystem path.

With support for expansion of symbolic links.

See also

monitor()

Inherit DefaultMonitor: inherit basic::DefaultMonitor : DefaultMonitor
Description: Based on Filesystem.Monitor.basic.DefaultMonitor.

Variable symlinks: int Filesystem.Monitor.symlinks.DefaultMonitor.symlinks
Description: Mask of symlink ids that can reach this monitor.

Method attr_changed

protectedvoidattr_changed(stringpath, Stdio.Statst)

Description

File attribute or content changed callback.

Parameter st

Status information for path as obtained by file_stat(path, 1).

This function is called when a change has been detected for an attribute for a monitored file or directory.

Called by check() and check_monitor().

Note

If there is a data_changed() callback, it may supersede this callback if the file content also has changed.

Method call_callback: protectedvoidcall_callback(function(string, __unknown__ ... :void) cb, stringpath, Stdio.Stat|voidst)
Description: Call a notification callback and handle symlink expansion.
Parameter cb: Callback to call or UNDEFINED for no operation.
Parameter extras: Extra arguments after the path argument to cb.

Method check_for_release: voidcheck_for_release(intmask, intflags)
Description: Check if this monitor should be removed automatically.

Method check_symlink: protectedvoidcheck_symlink(stringpath, Stdio.Stat|zerost, int|voidinhibit_notify)
Description: Check whether a symlink has changed.

Method file_created

protectedvoidfile_created(stringpath, Stdio.Statst)

Description

File creation callback.

Parameter st

Status information for path as obtained by file_stat(path, 1).

This function is called when either a monitored path has started existing, or when a new file or directory has been added to a monitored directory.

Called by check() and check_monitor().

Method file_deleted

protectedvoidfile_deleted(stringpath, Stdio.Statold_st)

Description

File deletion callback.

Parameter path

Path of the new file or directory that has been deleted.

This function is called when either a monitored path has stopped to exist, or when a file or directory has been deleted from a monitored directory.

Called by check() and check_monitor().

Method file_exists

protectedvoidfile_exists(stringpath, Stdio.Statst)

Description

File existance callback.

Parameter st

Status information for path as obtained by file_stat(path, 1).

This function is called during initialization for all monitored paths, and subpaths for monitored directories. It represents the initial state for the monitor.

Note

For directories, file_created() will be called for the subpaths before the call for the directory itself. This can be used to detect when the initialization for a directory is finished.

Called by check() and check_monitor() the first time a monitored path is checked (and only if it exists).

Method low_call_callback: voidlow_call_callback(function(string, __unknown__ ... :void) cb, mapping(string:int) state, mapping(string:string) symlink_targets, stringpath, Stdio.Stat|voidst, string|voidsymlink)
Description: Call a notification callback and handle symlink expansion.
Parameter cb: Callback to call or UNDEFINED for no operation.
Parameter state: State mapping to avoid multiple notification and infinite loops. Call with an empty mapping.
Parameter symlinks: Symlinks that have not been expanded yet.
Parameter path: Path to notify on.
Parameter extras: Extra arguments to cb.
Parameter symlink: Symbolic link that must have been followed for the callback to be called.

Method monitor: protectedvoidmonitor(stringpath, intflags, intmax_dir_interval, intfile_interval_factor, intstable_time)
Description: Called to create a sub monitor.

Method stable_data_change

protectedvoidstable_data_change(stringpath, Stdio.Statst)

Description

Stable change callback.

Parameter st

Status information for path as obtained by file_stat(path, 1).

This function is called when previous changes to path are considered "stable".

"Stable" in this case means that there have been no detected changes for at lease stable_time seconds.

Called by check() and check_monitor().

Method status_change: protectedboolstatus_change(Stdio.Statold_st, Stdio.Statst, intorig_flags, intflags)
Description: Called when the status has changed for an existing file.

Method zap_symlink: protectedvoidzap_symlink(stringpath)
Description: Called when the symlink path is no more.

Module Filesystem.Tar

Description

Filesystem which can be used to mount a Tar file.

Two kinds of extended tar file records are supported:

`"ustar\0\60\60"`	POSIX ustar (Version 0?).
`"ustar \0"`	GNU tar (POSIX draft)

Note

For a quick start, you probably want to use `()().

See also

`()()

Constant EXTRACT_CHOWN: constantint Filesystem.Tar.EXTRACT_CHOWN
Description: Set owning user and group from the tar records.

Constant EXTRACT_ERR_ON_UNKNOWN: constantint Filesystem.Tar.EXTRACT_ERR_ON_UNKNOWN
Description: Throw an error if an entry of an unsupported type is encountered. This is ignored otherwise.

Constant EXTRACT_SKIP_EXT_MODE: constantint Filesystem.Tar.EXTRACT_SKIP_EXT_MODE
Description: Don't set set-user-ID, set-group-ID, or sticky bits from the tar records.

Constant EXTRACT_SKIP_MODE: constantint Filesystem.Tar.EXTRACT_SKIP_MODE
Description: Don't set any permission bits from the tar records.

Constant EXTRACT_SKIP_MTIME: constantint Filesystem.Tar.EXTRACT_SKIP_MTIME
Description: Don't set mtime from the tar records.

Class Filesystem.Tar._Tar

Description: Low-level Tar Filesystem.

Method extract

voidextract(stringsrc_dir, stringdest_dir, void|string|function(string, Filesystem.Stat:int|string) filter, void|intflags)

Description

Extracts files from the tar file in sequential order.

Parameter src_dir

The root directory in the tar file system to extract.

Parameter dest_dir

The root directory in the real file system that will receive the contents of src_dir. It is assumed to exist and be writable.

Parameter filter

A filter for the entries under src_dir to extract. If it's a string then it's taken as a glob pattern which is matched against the path below src_dir. That path always begins with a /. For directory entries it ends with a / too, otherwise not.

If it's a function then it's called for every entry under src_dir, and those where it returns nonzero are extracted. The function receives the path part below src_dir as the first argument, which is the same as in the glob case above, and the stat struct as the second. If the function returns a string, it's taken as the path below dest_dir where this entry should be extracted (any missing directories are created automatically).

If filter is zero, then everything below src_dir is extracted.

Parameter flags

Bitfield of flags to control the extraction:

`Filesystem.Tar.EXTRACT_SKIP_MODE`	Don't set any permission bits from the tar records.
`Filesystem.Tar.EXTRACT_SKIP_EXT_MODE`	Don't set set-user-ID, set-group-ID, or sticky bits from the tar records.
`Filesystem.Tar.EXTRACT_SKIP_MTIME`	Don't set mtime from the tar records.
`Filesystem.Tar.EXTRACT_CHOWN`	Set owning user and group from the tar records.
`Filesystem.Tar.EXTRACT_ERR_ON_UNKNOWN`	Throw an error if an entry of an unsupported type is encountered. This is ignored otherwise.

Files and directories are supported on all platforms, and symlinks are supported whereever symlink exists. Other record types are currently not supported.

Throws

I/O errors are thrown.

Class Filesystem.Tar._TarFS

Inherit System: inherit Filesystem.System : System

Method chmod: voidchmod(stringfilename, int|stringmode)
FIXME: Not implemented yet.

Method chown: voidchown(stringfilename, int|objectowner, int|objectgroup)
FIXME: Not implemented yet.

Method create: Filesystem.Tar._TarFSFilesystem.Tar._TarFS(_Tar_tar, string_wd, string_root, Filesystem.Base_parent)

Method rm: intrm(stringfilename)
FIXME: Not implemented yet.

Class Filesystem.Tar.`()

Inherit _TarFS: inherit _TarFS : _TarFS

Method create: Filesystem.Tar.`()Filesystem.Tar.`()(stringfilename, void|Filesystem.Baseparent, void|objectfile)
Parameter filename: The tar file to mount.
Parameter parent: The parent filesystem. If none is given, the normal system filesystem is assumed. This allows mounting a TAR-file within a tarfile.
Parameter file: If specified, this should be an open file descriptor. This object could e.g. be a Stdio.File, Gz.File or Bz2.File object.

Module Filesystem.Zip

Method create: void Filesystem.Zipcreate(stringfilename, void|Filesystem.Baseparent, void|objectfile)
Description: Filesystem which can be used to mount a ZIP file.
Parameter filename: The tar file to mount.
Parameter parent: The parent filesystem. If non is given, the normal system filesystem is assumed. This allows mounting a ZIP-file within a zipfile.
Parameter file: If specified, this should be an open file descriptor. This object could e.g. be a Stdio.File or similar object.

Class Filesystem.Zip.Decrypt

Description: traditional Zip encryption is CRC32 based, and rather insecure. support here exists to ease transition and to work with legacy files.

Method decrypt: stringdecrypt(stringx)
Description: decrypt a string
Parameter x: encrypted string to decrypt

Class Filesystem.Zip._Zip

Description

A class for reading and writing ZIP files.

Note that this class does not support the full ZIP format specification, but does support the most common features.

Storing, Deflating and Bzip2 (if the Bz2 module is available) are supported storage methods.

This class is able to extract data from traditional ZIP password encrypted archives.

Notably, advanced PKware encryption (beyond reading traditional password protected archives) and multi-part archives are not currently supported.

Method add_dir: voidadd_dir(stringpath, intrecurse, string|voidarchiveroot)
Description: adds a directory to an archive

Method add_file: voidadd_file(stringfilename, string|Stdio.File|zerodata, int|object|voidstamp, int|voidno_compress)
Description: add a file to an archive.

Method create: Filesystem.Zip._ZipFilesystem.Zip._Zip(object|voidfd, string|voidfilename, object|voidparent)

Method date_dos2unix: intdate_dos2unix(inttime, intdate)
Description: Convert MS-DOS time/date pair to a linear UNIX date.

Method date_unix2dos: arraydate_unix2dos(intunix_date)
Description: Convert linear UNIX date to a MS-DOS time/date pair.
Returns: an array containing ({time, date})

Method generate: stringgenerate()
Description: generate the zip archive

Method is_zip64: intis_zip64()
Description: is this archive using zip64 extensions?

Method set_compression_value: voidset_compression_value(int(0..9)v)
Description: sets the compression value (0 to 9)

Method set_password: voidset_password(stringpw)
Description: sets the password to be used for files encrypted using traditional PKZip encryption.

Method set_zip64: voidset_zip64(intflag)
Description: enable zip64 extensions (large files) for this archive
Note: This setting may be used to force zip64 for files that do not otherwise require its use. If a file whose properties requires the use of zip65 is added to an archive, zip64 extensions will be enabled automatically.

Method unzip: voidunzip(stringtodir)

Class Filesystem.Zip._ZipFS

Inherit System: inherit Filesystem.System : System

Method set_password: voidset_password(stringpw)

Module Fuse

Description

Fuse - Filesystem in USErspace

FUSE (Filesystem in USErspace) provides a simple interface for userspace programs to export a virtual filesystem to the Linux kernel. FUSE also aims to provide a secure method for non privileged users to create and mount their own filesystem implementations.

See http://sourceforge.net/projects/fuse/ for more information

This module maps the Fuse library more or less directly to pike.

In order to create a filesystem, create a subclass of the Operations class, clone it and pass it to the run method.

You do not need to implemnent all functions, but at least getattr, readdir and read are needed to make a useable filesystem.

A tip: ERRNO constants are available in the System module, and if one is missing /usr/include/asm[-generic]/errno.h can be included in pike programs on Linux.

Inherit "___Fuse": inherit "___Fuse" : "___Fuse"

Constant FUSE_MAJOR_VERSION
Constant FUSE_MINOR_VERSION: constant Fuse.FUSE_MAJOR_VERSION
constant Fuse.FUSE_MINOR_VERSION
Description: The version of FUSE

Method run

voidrun(Operationshandler, array(string) args)

Description

Start fuse. Args is as in argv in main(). This function will not return.

The first argument (argv[0], program name) is used as the filesystem name. The first non-flag argument after argv[0] is used as the mountpoint. Otherwise these arguments are supported:

     -d                  enable debug output (implies -f)
     -f                  foreground operation
     -s                  disable multithreaded operation
     -r                  mount read only (equivalent to '-o ro')
     -o opt,[opt...]     mount options
     -h                  print help

Mount options:

     rootmode=M             permissions of the '/' directory in the filesystem (octal)
     user_id=N              user of '/' (numeric)
     group_id=N             group of '/' (numeric)
     default_permissions    enable permission checking

  By default FUSE doesn't check file access permissions, the
  filesystem is free to implement it's access policy or leave it to
  the underlying file access mechanism (e.g. in case of network
  filesystems).  This option enables permission checking,
  restricting access based on file mode.  It is usually useful
  together with the 'allow_other' mount option.

     allow_other            allow access to other users

 This option overrides the security measure restricting file access
 to the user mounting the filesystem.  This option is by default
 only allowed to root, but this restriction can be removed with a
 (userspace) configuration option (in fuse.ini).

     large_read             issue large read requests (2.4 only)
     max_read=N             set maximum size of read requests (default 128K)
     hard_remove            immediate removal (don't hide files)
     debug                  enable debug output
     fsname=NAME            set filesystem name in mtab (overrides argv[0])

Class Fuse.Operations

Description

This is the interface you have to implement to write a FUSE filesystem If something goes wrong in your callback, always return errno. Unless the function returns a specific value (Stat, string or similar), return 0 if all is well.

You do not have to implement all functions. Unimplemented functions have a default implementation that returns -ENOIMPL.

Constant DT_BLK: final constantint Fuse.Operations.DT_BLK
Description: Block special directory entry

Constant DT_CHR: final constantint Fuse.Operations.DT_CHR
Description: Character special directory entry

Constant DT_DIR: final constantint Fuse.Operations.DT_DIR
Description: Directory directory entry

Constant DT_FIFO: final constantint Fuse.Operations.DT_FIFO
Description: FIFO directory entry

Constant DT_LNK: final constantint Fuse.Operations.DT_LNK
Description: Symlink directory entry

Constant DT_REG: final constantint Fuse.Operations.DT_REG
Description: Normal file directory entry

Constant DT_SOCK: final constantint Fuse.Operations.DT_SOCK
Description: Socket directory entry

Constant DT_UNKNOWN: final constantint Fuse.Operations.DT_UNKNOWN
Description: Unkown directory entry type

Constant F_GETLK
Constant F_SETLK
Constant F_SETLKW
Constant F_RDLCK
Constant F_WRLCK
Constant F_UNLCK: final constant Fuse.Operations.F_GETLK
final constant Fuse.Operations.F_SETLK
final constant Fuse.Operations.F_SETLKW
final constant Fuse.Operations.F_RDLCK
final constant Fuse.Operations.F_WRLCK
final constant Fuse.Operations.F_UNLCK
Description: lock() mode operations.

Constant O_ACCMODE: final constantint Fuse.Operations.O_ACCMODE
Description: Mask for read/write/rdwr

Constant O_APPEND: final constantint Fuse.Operations.O_APPEND
Description: Open for append

Constant O_RDONLY: final constantint Fuse.Operations.O_RDONLY
Description: Open read only

Constant O_RDWR: final constantint Fuse.Operations.O_RDWR
Description: Open read/write only

Constant O_WRONLY: final constantint Fuse.Operations.O_WRONLY
Description: Open write only

Method access: intaccess(stringpath, intmode)
Description: Return if the user is allowed to access the path. If the 'default_permissions' mount option is given, this method is not called.

Method chmod: intchmod(stringpath, intmode)
Description: Change the permission of a file or directory
Returns: errno or 0

Method chown: intchown(stringpath, intuid, intgid)
Description: Change the owner of a file or directory
Returns: errno or 0

Method creat: intcreat(stringpath, intmode, intflag)
Description: Create and open or just open the given path

Method flush: intflush(stringpath, intflags)
Description: Write unwritten data.

Method fsync: intfsync(stringpath, intdatasync)
Description: Flush data and user-data to disk. Not required. If the datasync parameter is non-zero, then only the user data should be flushed, not the meta data.

Method getattr: Stdio.Stat|int(1..)getattr(stringpath)
Description: Stat a file.
Note: This function is required.
Returns: A Stdio.Stat object or an errno.

Method getxattr: stringgetxattr(stringpath, stringname)
Description: Get the extended attribute name on path

Method link: intlink(stringsource, stringdestination)
Description: Create a hard link from source to destination.
Returns: errno or 0

Method listxattr: array(string)|intlistxattr(stringpath)
Description: Return a list of all available extended attributes on path

Method lock

mapping(string:int)|intlock(stringpath, intmode, mapping(string:int) how)

Description

Lock, unlock or test for the existence of record locks (POSIX file locking). The owner of the lock is identified by how->owner

If you only need local file-locking on the computer the filesystem is mounted on you do not need to implement this interface. This is only needed for network filesystems that want locking to work over the network.

The operation mode depends on the mode argument.

F_SETLK

Acquire a lock (when how->type is F_RDLCK or F_WRLCK) or release a lock (when how->type is F_UNLCK) on the bytes specified by the how->whence, how->start, and how->len fields of lock. If a conflicting lock is held by another process, you should return EACCES or EAGAIN.

F_SETLKW

Identical to SETLK, but if a lock is held on the file, wait for it to be released before returning. You are allowed to return EINTR, to signal that the waiting has been interrupted and must be restarted.

F_GETLK

Identical to SETLK, but do not actually aquire the lock if it can be aquired. If one or more incompatible locks would prevent this lock being placed, then fcntl() returns details about one of these locks in the type, whence, start, and len fields of how and set pid to be the PID of the process holding that lock. Then return the mapping.

Method mkdir: intmkdir(stringpath, intmode)
Description: Create a directory.
Returns: errno or 0

Method mknod: intmknod(stringpath, intmode, intrdev)
Description: Create a node (file, device special, or named pipe). See man 2 mknod
Returns: errno or 0

Method open: intopen(stringpath, intmode)
Description: Open path. mode is as for the system call open. (mode & O_ACCMODE) is one of O_RDONLY, O_WRONLY and O_RDWR. The mode can also contain other flags, most notably O_APPEND.
Note: You do not really have to implement this function. It's useful to start prefetch and to cache open files, and check that the user has permission to read/write the file.
Returns: errno or 0

Method read: string|int(1..)read(stringpath, intlen, intoffset)
Description: Read data from a file. You have to return at most len bytes, wunless an error occurs, or there is less than len bytes of data still left to read.
Returns: errno or the data

Method readdir

intreaddir(stringpath, function(string:void) callback)

Description

Get directory contents.

Call the callback once per file in the directory with the filename as the argument.

Note

This function is required.

Returns

errno or 0

Method readlink: string|int(1..)readlink(stringpath)
Description: Read a symlink.
Returns: The symlink contents or errno

Method release: intrelease(stringpath)
Description: The inverse of open.
Note: The file might very well be openend multiple times. Keep reference counts.

Method removexattr: intremovexattr(stringpath, stringname)
Description: Remove the extended attribute name from path

Method rename: intrename(stringsource, stringdestination)
Description: Rename source to destination.
Returns: errno or 0

Method rmdir: intrmdir(stringpath)
Description: Remove a directory
Returns: errno or 0

Method setxattr: intsetxattr(stringpath, stringname, stringvalue, intflags)
Description: Set the extended attrbiute name on path to value

Method statfs: mapping(string:int) statfs(stringpath)
Description: Stat a filesystem. Mapping as from filesystem_stat
Note: required for 'df' support, without this function there is an error each time 'df' is run.

Method symlink: intsymlink(stringsource, stringdestination)
Description: Create a symlink from source to destination.
Returns: errno or 0

Method truncate: inttruncate(stringpath, intnew_length)
Description: Shrink or enlarge a file
Returns: errno or 0

Method unlink: intunlink(stringpath)
Description: Remove a file
Returns: errno or 0

Method utime

intutime(stringpath, intatime, intmtime)

Description

Set access and modification time. The arguments are the number of seconds since jan 1 1970 00:00.

This function is deprecated, utimens is the recommended method.

Returns

errno or 0

Method utimens: intutimens(stringpath, intatime, intmtime)
Description: Set access and modification time, with nanosecond resolution. The arguments are the number of nanoseconds since jan 1 1970 00:00.
Returns: errno or 0

Method write: intwrite(stringpath, stringdata, intoffset)
Description: Write data to the file. Should write all data.
Returns: errno or amount written (bytes)

Module G

Description: The base object classes used by GTK2 et al.
See also: G.Object, GTK2, https://docs.gtk.org/gobject/

Class G.InitiallyUnowned

Description: Abstract class - do not instantiate

Inherit Object: inherit G.Object : Object

Class G.Object

Description

The base object. All GDK and GTK classes inherit from this. The Pango classes also inherit from this class.

Signals: notify

Method _destruct: protectedG.Object_destruct()
Description: Destroy this object. This is the normal way to (eg) close a window - simply call destruct(obj) and it will be destroyed.

Method accel_groups_activate: G.Objectaccel_groups_activate(intaccel_key, intaccel_mods)
Description: Finds the first accelerator in an GTK.AccelGroup attached to this object that matches accel_key and accel_mods, and activates that accelerator.

Method get_data: objectget_data(stringname)
Description: Gets a named field from the object.

Method get_docs: stringget_docs()
Description: Get documentation on object

Method get_property: mixedget_property(stringproperty)
Description: Get a property.

Method is_floating: intis_floating()
Description: Checks whether this object has a floating reference.

Method new_signal: intnew_signal(stringname, arraytypes, stringreturn_type)
Description: Create a new signal.

Method notify: G.Objectnotify(stringproperty)
Description: Emits a "notify" signal for the named property on the object.

Method set_data

objectset_data(stringname, mixedarg)

Description

Each object carries around a table of associations from strings to pointers. This function lets you set an association.

If the object already had an association with that name, the old association will be destroyed.

Method set_property: G.Objectset_property(stringproperty, mixedvalue)
Description: Set a property on a G.Object (and any derived types) to value.

Method signal_block: G.Objectsignal_block(intsignal_id)
Description: Temporarily block a signal handler. No signals will be received while the handler is blocked. See signal_connect() for more info.

Method signal_connect

intsignal_connect(stringsignal, function(:void) callback, mixed|voidcallback_arg, string|voiddetail, int|voidconnect_before)

Description

Connect a signal to a pike function. The function will be called with the last argument to this function as its last argument (defaults to 0); the first argument is always the widget, and any other arguments are the ones supplied by GTK. If connect_before is nonzero, the callback will be called prior to the normal handling of the signal (and can return true to suppress that handling), otherwise it will be called after.

The return value of this function can be used to remove a signal with signal_disconnect(), and block and unblock the signal with signal_block() and signal_unblock().

Method signal_disconnect: G.Objectsignal_disconnect(intsignal_id)
Description: Remove a signal formerly added by signal_connect. The argument is the return value of signal_connect(). See signal_connect() for more info.

Method signal_emit: G.Objectsignal_emit(stringsignal_name, string|voiddetail)
Description: Send the current named signal.

Method signal_stop: G.Objectsignal_stop(stringsignal_name)
Description: Stop the emission of a signal.

Method signal_unblock: G.Objectsignal_unblock(intsignal_id)
Description: Unblock a formerly blocked signal handler. See signal_block() and signal_connect() for more info.

Module GI

Method get_default_repository: Repositoryget_default_repository()

Class GI.BaseInfo

Method get_container: BaseInfoget_container()

Method get_name: stringget_name()

Method get_namespace: stringget_namespace()

Class GI.ConstantInfo

Method get: mixedget()

Class GI.EnumInfo

Method get_values: array(ValueInfo) get_values()

Class GI.FieldInfo

Method get_field: mixedget_field(GBoxedbox)

Method set_field: voidset_field(GBoxedbox, mixedvalue)

Class GI.FunctionInfo

Method invoke: mixedinvoke(mixed ... args)

Class GI.GBoxed

Method create: GI.GBoxedGI.GBoxed(StructInfoinfo, mapping(string:mixed)|voidprops)

Class GI.GObject

Method connect: intconnect(stringsignal_spec, function(:void) callback, mixed ... extra_args)

Method connect_after: intconnect_after(stringsignal_spec, function(:void) callback, mixed ... extra_args)

Method create: GI.GObjectGI.GObject(ObjectInfoinfo, mapping(string:mixed)|voidprops)

Class GI.InterfaceInfo

Method get_methods: array(FunctionInfo) get_methods()

Class GI.ObjectInfo

Method get_interfaces: array(InterfaceInfo) get_interfaces()

Method get_methods: array(FunctionInfo) get_methods()

Method get_parent: ObjectInfoget_parent()

Class GI.Repository

Method enumerate_versions: array(string) enumerate_versions(strignamespace)

Method find_by_name: BaseInfofind_by_name(stringnamespace, stringname)

Method get_infos: array(BaseInfo) get_infos(stringnamespace)

Method require: voidrequire(stringnamespace, string|voidversion, bool|voidlazy)

Class GI.StructInfo

Method get_fields: array(FieldInfo) get_fields()

Method get_methods: array(FunctionInfo) get_methods()

Class GI.ValueInfo

Method get_value: intget_value()

Module Geography

Class Geography.Position

Description

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.

Constant ellipsoids: constant Geography.Position.ellipsoids
Description: 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.

Variable alt: float Geography.Position.alt
Description: Altitud of the position, in meters. Positive numbers is up. Zero is the shell of the current ellipsoid.

Variable equatorial_radius: float Geography.Position.equatorial_radius
Description: The equatorial radius is how many meters the earth radius is at the equator (east-west direction).

Variable lat: float Geography.Position.lat
Description: Latitude (N--S) of the position, in degrees. Positive number is north, negative number is south.

Variable long: float Geography.Position.long
Description: Longitude (W--E) of the position, in degrees. Positive number is east, negative number is west.

Variable polar_radius: float Geography.Position.polar_radius
Description: The polar radius is how many meters the earth radius is at the poles (north-south direction).

Method ECEF: array(float) ECEF()
Description: Returns the current position as Earth Centered Earth Fixed Cartesian Coordinates.
Returns: ({ X, Y, Z })

Method GEOREF: stringGEOREF()
Description: Gives the full GEOREF position for the current position, e.g. "LDJA0511".

Method RT38: array(float) RT38()

Method UTM: stringUTM(intprecision)
Description: 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.

Method UTM_offset: array(float) UTM_offset()
Description: Returns the offset within the present UTM cell. The result will be returned in an array of floats, containing easting and northing.

Method UTM_zone_designator: stringUTM_zone_designator()
Description: Returns the UTM letter designator for the current latitude. Returns "Z" if latitude is outside the UTM limits of 84N to 80S.

Method UTM_zone_number: intUTM_zone_number()
Description: Returns the UTM zone number for the current longitude, with correction for the Svalbard deviations.

Method __hash: inthash_value(Geography.Positionarg)

Method _sprintf: stringsprintf(stringformat, ... Geography.Positionarg ... )

Method `<: int res = Geography.Position() < pos

Method `==: int res = Geography.Position() == pos

Method `>: int res = Geography.Position() > pos

Method approx_height: floatapprox_height()
Description: 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.

Method create: Geography.PositionGeography.Position(int|floatlat, int|floatlong, void|int|floatalt)
Geography.PositionGeography.Position(stringlat, stringlong)
Geography.PositionGeography.Position(stringposition)
Geography.PositionGeography.Position()
Description: 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.

Method eccentricity_squared: floateccentricity_squared()
Description: Returns the first eccentricity squared for the selected earth approximation ellipsoid.

Method euclidian_distance: floateuclidian_distance(this_programp)
Description: Calculate the euclidian distance between two Geography.Position. Result is in meter. This uses the ECEF function.

Method flattening: floatflattening()
Description: Returns the flattening factor for the selected earth approximation ellipsoid.

Method latitude
Method longitude

stringlatitude(void|intn)
stringlongitude(void|intn)

Description

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"

Method set_ellipsoid

boolset_ellipsoid(stringname)
boolset_ellipsoid(floatequatorial_radius, floatpolar_radius)

Description

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"

Note

The longitude and lattitude are not converted to the new ellipsoid.

Method set_from_RT38: voidset_from_RT38(int|float|stringx_n, int|float|stringy_e)
Description: Sets the longitude and lattitude from the given RT38 coordinates.

Method set_from_UTM: voidset_from_UTM(intzone_number, stringzone_designator, floatUTME, floatUTMN)
Description: Sets the longitude and lattitude from the given UTM coordinates.

Method standard_grid: stringstandard_grid()
Description: Returns the standard map grid system for the current position. Can either be "UPS" or "UTM".

Class Geography.PositionRT38

Description: Create a Position object from a RT38 coordinate

Inherit Position: inherit .Position : Position

Module Geography.Countries

Variable countries: array(Country) Geography.Countries.countries
Description: All known countries.

Method `[]
Method `->

mixed`[](stringwhat)
mixed`->(stringwhat)

Description

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"

Method continents

mapping(string:array(Country)) continents()

Description

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"

Note

Some countries are considered to be on more than one continent.

Method from_domain

Countryfrom_domain(stringdomain)

Description

Look up a country from a domain name. Returns zero if the domain doesn't map to a country. Note that there are some valid domains that don't:

INT: International
MIL: US Military
NET: Network
ORG: Non-Profit Organization
ARPA: Old style Arpanet
NATO: 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>

Method from_domain: Countryfrom_domain(stringname)
Description: Look up a country from its name or aka. The search is case-insensitive but regards whitespace and interpunctation.

Class Geography.Countries.Country

Description: Country

Variable name
Variable aka: string Geography.Countries.Country.name
array(string) Geography.Countries.Country.aka
Description: Country name and also-known-as, if any

Variable fips10: string|zero Geography.Countries.Country.fips10
Description: FIPS 10-character code; "Federal Information Processing Standards 10-4" etc, previously used by some goverments in the US.
Note: This character code is slightly different from iso2, and should only be used for compatibility with old code.
Deprecated: Replaced by iso2.; FIPS 10-4 was withdrawn by NIST 2008-09-02.

Variable former: int Geography.Countries.Country.former
Description: Flag that is set if this country doesn't exist anymore. (eg USSR.)

Variable iso2: string|zero Geography.Countries.Country.iso2
Description: ISO-3166-1 2-character code aka domain name.
Note: May be zero in some obscure cases where the ISO-3166-1 grouping differs from the FIPS-10 grouping.

Method cast: (string)Geography.Countries.Country()
Description: It is possible to cast a country to a string, which will be the same as performing country->name;.

Method continent: stringcontinent()
Description: Returns the continent of the country.
Note: 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.

Module Geography.GeoIP

Method parse_77: voidparse_77(stringline, objecttree)
Description: Parsing function for geoip databases in the format used my http://software77.net/.

Method parse_maxmind: voidparse_maxmind(stringline, objecttree)
Description: Parsing function for geoip databases in the format used my http://www.maxmind.com/.

Class Geography.GeoIP.IP

Description: Base class for GeoIP lookups. Use Geography.GeoIP.IPv4.

Method from_ip: mixedfrom_ip(stringip)
Description: Returns the geographical location of the given ip address ip. When this object has been created using one of the standard parsing functions the locations are instances of Geography.Countries.Country.

Class Geography.GeoIP.IPv4

Description: Class for GeoIP lookups of ipv4 addresses. Uses ADT.CritBit.IPv4Tree objects internally to map IPv4 addresses to a geographical region.

Inherit IP: inherit IP : IP

Method create

Geography.GeoIP.IPv4Geography.GeoIP.IPv4(stringfile_name, function(string, ADT.CritBit.IPv4Tree:void) fun)
Geography.GeoIP.IPv4Geography.GeoIP.IPv4(ADT.CritBit.IPv4Treetree)

Description

Objects of this class can either be created from a file file_name with an optional parsing function fun. When fun is omitted, it defaults to Geography.GeoIP.parse_maxmind. fun will be called for each line in file_name and the critbit tree to add the entry to.

Alternatively, an instance of ADT.CritBit.IPv4Tree can be passed. tree is expected to map the first address of each range to its geographical location.

Module Getopt

Description

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.

Constant HAS_ARG: constantint Getopt.HAS_ARG
Description: Used with find_all_options() to indicate that an option requires an argument.
See also: find_all_options()

Constant MAY_HAVE_ARG: constantint Getopt.MAY_HAVE_ARG
Description: Used with find_all_options() to indicate that an option takes an optional argument.
See also: find_all_options()

Constant NO_ARG: constantint Getopt.NO_ARG
Description: Used with find_all_options() to indicate that an option does not take an argument.
See also: find_all_options()

Method find_all_options

Description

This function does the job of several calls to find_option(). The main advantage of this is that it allows it to handle the POSIX_ME_HARDER environment variable better. When 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.

Parameter argv

The should be the array of strings that was sent as the second argument to your main() function.

Parameter options

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

Array
`stringname`	Name is a tag used to identify the option in the output.
`inttype`	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.
`string\|array(string) 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`.
`void\|string\|array(string) 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.
`void\|mixeddefault`	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.

Parameter posix_me_harder

Don't scan for arguments after the first non-option.

Parameter throw_errors

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.

Returns

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:

Array
`stringname`	Option identifier name from the input.
`mixedvalue`	Value given. If no value was specified, and no default has been specified, the value will be 1.

Note

find_all_options() modifies argv.

Index 0 (zero) of argv is not scanned for options, since it is reserved for the program name.

See also

Getopt.get_args(), Getopt.find_option()

Method find_option

Description

This is a generic function to parse command line options of the type -f, --foo or --foo=bar.

Parameter argv

The first argument should be the array of strings that was sent as the second argument to your main() function.

Parameter shortform

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.

Parameter longform

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.

Parameter envvars

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.

Parameter def

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.

The value may be one of:

int(0)|zero

The option does not require a value.

int(1)|string

The option requires a value, and def will be returned if the option is not present. If the option is present, but does not have an argument find_option() will fail.

Note that a set option will always return a string, so setting def to 1 can be used to detect whether the option is present or not.

Parameter throw_errors

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

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.

Throws

If an option that requires an argument lacks an argument and throw_errors is set an error will be thrown.

Note

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.

See also

Getopt.get_args()

Method get_args

array(string) get_args(array(string|zero) argv, void|int(-1..1)posix_me_harder, void|intthrow_errors)

Description

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.

Returns

On success a new argv array without the parsed options is returned.

See also

Getopt.find_option(), Getopt.find_all_options()

Module Git

Description: This is a module for interacting with the Git distributed version control system.

Constant MODE_DIR: constantint Git.MODE_DIR
Description: A subdirectory.

Constant MODE_EXE: constantint Git.MODE_EXE
Description: A normal, but executable file.

Constant MODE_FILE: constantint Git.MODE_FILE
Description: A normal (non-executable) file.

Constant MODE_GITLINK: constantint Git.MODE_GITLINK
Description: A gitlink (aka submodule reference).

Constant MODE_SYMLINK: constantint Git.MODE_SYMLINK
Description: A symbolic link.

Constant NULL_SHA1: constantstring Git.NULL_SHA1
Description: The NULL SHA1.

Variable git_binary

string Git.git_binary

Description

The git binary to use.

Defaults to "git", but may be overridden to select a different binary.

Method git: stringgit(string|zerogit_dir, stringcommand, string ... args)
Description: Run a git command, and get the output.
Parameter git_dir: Directory containing the Git repository. May be UNDEFINED to specify the Git repository for the current directory.
Parameter command: Git subcommand to execute.
Parameter args: Arguemnts for command.
Returns: Returns the output on stdout from running the command on success, and throws an error on failure.
See also: try_git(), low_git()

Method hash_blob: stringhash_blob(stringdata)
Description: Hash algorithm for blobs that is compatible with git.

Method low_git: Process.Processlow_git(mapping(string:mixed) options, string|zerogit_dir, stringcommand, string ... args)
Description: Start a git process.
Parameter options: Options for Process.Process().
Parameter git_dir: Directory containing the Git repository. May be UNDEFINED to specify the Git repository for the current directory.
Parameter command: Git subcommand to execute.
Parameter args: Arguemnts for command.
Returns: Returns the corresponding Process.Process object.
See also: git(), try_git()

Method try_git: string|zerotry_git(stringgit_dir, stringcommand, string ... args)
Description: Attempt to run a git command and get its output.
Parameter git_dir: Directory containing the Git repository. May be UNDEFINED to specify the Git repository for the current directory.
Parameter command: Git subcommand to execute.
Parameter args: Arguemnts for command.
Returns: Returns the output on stdout from running the command on success, and 0 (zero) on failure.
Note: This is a convenience function, and there is no way to get the specific cause for failures other than rerunning the command with e.g. git().
See also: git(), low_git()

Class Git.Export

Description: Framework for creating a command-stream suitable for git-fast-import.

Method blob: voidblob(stringblob, string|voidmarker)
Description: Upload data.
Parameter blob: Data to upload.
Parameter marker: Optional export marker for referring to the data.

Method cat_blob: voidcat_blob(stringdataref)
Description: Output a blob on the cat-blob-fd.
Parameter dataref: Reference to the blob to output.

Method checkpoint: voidcheckpoint()
Description: Flush state to disk.

Method command: voidcommand(sprintf_formatcmd, sprintf_args ... args)
Description: Send a raw command.

Method commit

voidcommit(stringref, string|voidcommit_marker, string|voidauthor_info, stringcommitter_info, stringmessage, string|void ... parents)

Description

Create a new commit on a branch.

Parameter ref

Reference to add the commit to. Typically "refs/heads/" followed by a branchname, or "refs/notes/commits".

Parameter commit_marker

Optional export marker for referring to the new commit.

Parameter author_info

Optional author information. Defaults to committer_info.

Parameter committer_info

Name, email and timestamp for the committer. See format_author() for details.

Parameter message

Commit message.

Parameter parents

The ordered set of parents for the commit. Defaults to the current HEAD for ref, if it exists, and to the empty set otherwise.

The set of files for the commit defaults to the set for the first of the parents, and can be modified with filemodify, filedelete, filecopy, filerename, filedeleteall and notemodify.

Method create

Git.ExportGit.Export()
Git.ExportGit.Export(Stdio.Filefd)
Git.ExportGit.Export(stringgit_dir)

Description

Create a new fast-import command-stream.

Parameter fd

File to write the command-stream to.

Parameter git_dir

Git directory to modify. If the directory doesn't exist, it will be created empty. A git-fast-import session will be started for the directory to receive the command-stream.

If neither fd nor git_dir has been specified, the command stream will be output to Stdio.stdout.

Parameter verbosity

The amount of verbosity on Stdio.stderr for various commands.

Method done: intdone()
Description: End the command-stream and wait for completion.

Method export: voidexport(stringfile_name, string|voidgit_name)
Description: Convenience funtion for exporting a filesystem file or directory (recursively) to git.
Parameter file_name: Name of the file on disc.
Parameter git_name: Name of the file in git. Defaults to file_name.

Method feature

voidfeature(stringfeature, string|voidarg)

Description

Require that the backend for the stream supports a certian feature.

Parameter feature

Feature to require support for. Typically one of:

`"date-format"`	Same as the corresponding command-line option.
`"export-marks"`
`"relative-marks"`
`"no-relative-marks"`
`"force"`
`"import-marks"`
`"import-marks-if-exists"`
`"cat-blob"`	Require the `cat_blob` and `ls` commands to be supported.
`"ls"`	Require the `cat_blob` and `ls` commands to be supported.
`"notes"`	Require that the backend supports the `notemodify` subcommand.
`"done"`	Require the stream to terminate with a `done` command.

Method filecopy: voidfilecopy(stringfrom, stringto)
Description: Copy a file or directory.

Method filedelete: voidfiledelete(stringpath)
Description: Delete a file.

Method filedeleteall

voidfiledeleteall()

Description

Delete all files.

Used to start a commit from a clean slate.

Method filemodify

voidfilemodify(intmode, stringpath, string|voiddataref)

Description

Create or modify a file.

Parameter mode

Mode for the file. See the MODE_* constants.

Parameter path

Path to the file relative to the repository root.

Parameter dataref

Reference to the data for the file. One of:

`string`	A mark reference set by a prior `blob` command or a full 40-byte SHA-1 of an existing Git blob.
`zero`	Left out, `UNDEFINED` or `"inline"` in which case the `filemodify` command must be followed by a `data` command.

Method filerename: voidfilerename(stringfrom, stringto)
Description: Rename a file or directory.

Method ls: voidls(stringpath, string|voiddataref)
Description: Output a file to the cat-blob-fd.
Parameter path: Path to the file to output.
Parameter dataref: Marker, tag, commit or tree for the root. Defaults to the commit in progress.

Method notemodify

voidnotemodify(stringcommit, string|voiddataref)

Description

Annotate a commit.

Parameter commit

Commit to annotate.

Parameter dataref

Reference to the data for the annotation. One of:

`string`	A mark reference set by a prior `blob` command or a full 40-byte SHA-1 of an existing Git blob.
`zero`	Left out, `UNDEFINED` or `"inline"` in which case the `notemodify` command must be followed by a `data` command.

Note that this command is typically only used when a commit on a ref under "refs/notes/" is active.

Method option: voidoption(stringoption)
Description: Set backend options.

Method progress: voidprogress(stringmessage)
Description: Output a progress message.
Parameter message: Message to output.
Note: Note that each line of the message will be prefixed with "progress ".

Method reset

voidreset(stringref, string|voidcommittish)

Description

Move a reference.

Parameter ref

Reference to move.

Parameter committish

Commit to reference.

This command can also be used to make light-weight tags.

See also

tag

Method tag: voidtag(stringname, stringcommittish, stringtagger_info, stringmessage)
Description: Create an annotated tag referring to a specific commit.
Parameter name: Tag name. Note that it is automatically prefixed with "refs/tags/".
Parameter committish: Commit to tag.
Parameter tagger_info: Name, email and timestamp for the tagger. See format_author() for details.
Parameter message: Message for the tag.
See also: reset

Module Gmp

Description: 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/

Constant version: constant Gmp.version
Description: The version of the current GMP library, e.g. "6.1.0".

Method fac: Gmp.mpzfac(intx)
Description: Returns the factorial of x (x!).

Class Gmp.bignum

Description

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.

Due to the auto-bignum conversion, all integers can be treated as Gmp.mpz objects insofar as that they can be indexed with the functions in the Gmp.mpz class. For instance, to calculate the greatest common divisor between 51 and 85, you can do 51->gcd(85). In other words, all the functions in Gmp.mpz are also available here.

Class Gmp.mpf

Description

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.

Note

This class will use mpfr if available, in which case the precision will be exact and IEEE rules will be followed.

Variable catalan: mpf Gmp.mpf.catalan

Variable euler: mpf Gmp.mpf.euler

Variable ln2: mpf Gmp.mpf.ln2

Variable pi: mpf Gmp.mpf.pi

Method __hash: inthash_value(Gmp.mpfarg)

Method _is_type: bool res = is_type(Gmp.mpf())
Description: The Gmp.mpf object will claim to be a "float".
FIXME: Perhaps it should also return true for "object"?

Method _sprintf: stringsprintf(stringformat, ... Gmp.mpfarg ... )

Method `!: bool res = !Gmp.mpf()

Method `*: Gmp.mpf res = Gmp.mpf() * a

Method `+: Gmp.mpf res = Gmp.mpf() + a

Method `+=: Gmp.mpf() += a

Method `-: Gmp.mpf res = Gmp.mpf() - a

Method `/: Gmp.mpf res = Gmp.mpf() / a

Method `<: bool res = Gmp.mpf() < q

Method `==: bool res = Gmp.mpf() == q

Method `>: bool res = Gmp.mpf() > q

Method ``*: Gmp.mpf res = a * Gmp.mpf()

Method ``+: Gmp.mpf res = a + Gmp.mpf()

Method ``-: Gmp.mpf res = sv - Gmp.mpf()

Method ``/: Gmp.mpf res = sv / Gmp.mpf()

Method `~: Gmp.mpf res = ~Gmp.mpf()

Method cast: (string)Gmp.mpf() (int)Gmp.mpf() (float)Gmp.mpf()

Method ceil: mpfceil()

Method create: Gmp.mpfGmp.mpf(void|int|string|float|objectx, void|int(0..)precision)
Gmp.mpfGmp.mpf(stringx, int(0..)precision, int(2..36)base)

Method exp: mpfexp()

Method exp10: mpfexp10()

Method exp2: mpfexp2()

Method floor: mpffloor()

Method frac: mpffrac()

Method get_float: floatget_float()
Description: Returns the value of the object as a float.

Method get_int: int|objectget_int()

Method get_precision: int(0..)get_precision()
Description: Returns the current precision, in bits.

Method get_string: stringget_string()

Method log: mpflog()

Method log10: mpflog10()

Method log2: mpflog2()

Method pow: mpf res = pow([Gmp.mpf]a, b) ormpfpow(int|float|Gmp.mpz|Gmp.mpfexp)

Method rint: mpfrint()

Method round: mpfround()

Method set_precision: Gmp.mpfset_precision(int(0..)prec)
Description: 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.

Method sgn: intsgn()

Method sqr: mpfsqr()

Method sqrt: mpf res = sqrt([Gmp.mpf]a) ormpfsqrt()

Method trunc: mpftrunc()

Class Gmp.mpq

Description: 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.

Method __hash: inthash_value(Gmp.mpqarg)

Method _is_type: bool res = is_type(Gmp.mpq())

Method _sprintf: stringsprintf(stringformat, ... Gmp.mpqarg ... )

Method `!: bool res = !Gmp.mpq()

Method `%: Gmp.mpq res = Gmp.mpq() % a
Description: a%b = a - floor(a/b)*b

Method `*: Gmp.mpq res = Gmp.mpq() * a

Method `+: Gmp.mpq res = Gmp.mpq() + a

Method `+=: Gmp.mpq() += a

Method `-: Gmp.mpq res = Gmp.mpq() - a

Method `/: Gmp.mpq res = Gmp.mpq() / a

Method `<: bool res = Gmp.mpq() < q

Method `==: bool res = Gmp.mpq() == q

Method `>: bool res = Gmp.mpq() > q

Method ``%: Gmp.mpq res = a % Gmp.mpq()

Method ``*: Gmp.mpq res = a * Gmp.mpq()

Method ``+: Gmp.mpq res = a + Gmp.mpq()

Method ``-: Gmp.mpq res = sv - Gmp.mpq()

Method ``/: Gmp.mpq res = sv / Gmp.mpq()

Method `~: Gmp.mpq res = ~Gmp.mpq()
Description: Defined as -1-x.

Method cast: (int)Gmp.mpq() (string)Gmp.mpq() (float)Gmp.mpq()
Description: Casting to a string returns the number in the decimal fraction format, where both decimal point and quotient is included only if required. I.e. it is the same as calling get_string with 1 as argument.

Method create: Gmp.mpqGmp.mpq(void|string|int|float|Gmp.mpz|Gmp.mpqx)
Gmp.mpqGmp.mpq(int|Gmp.mpznumerator, int|Gmp.mpzdenominator)
Gmp.mpqGmp.mpq(stringx, intbase)

Method den: intden()
Description: Returns the denominator. It is always positive.

Method get_float: floatget_float()

Method get_int: intget_int()

Method get_string

stringget_string(void|intdecimal_fraction)

Description

If decimal_fraction is zero or left out, the number is returned as a string on the form "numerator/denominator", where both parts are decimal integers. The numerator may be negative, but the denominator is always positive.

If decimal_fraction is set, then the number is returned as a (possibly negative) decimal fraction, i.e. a decimal number with a decimal point somewhere inside. There is always at least one digit before and after the decimal point.

If the number can be accurately described that way, i.e. without an infinite number of decimals, then no denominator is included. Otherwise the remaining denominator is added to the decimal fraction after a "/". For example, 4711/100 is returned as "47.11", 4711/200 as "23.555", and 4711/300 as "47.11/3".

If decimal_fraction is 1 then the decimal fraction contains a '.' only if there are decimals in it. If it is 2 or higher then the decimal fraction always contains a '.' with at least one digit before and after it.

Note

In any case, there are no unnecessary padding zeroes at the beginning or end of any decimal number.

Method invert: Gmp.mpqinvert()

Method num: intnum()
Description: Returns the numerator.

Method sgn: int(-1..1)sgn()

Class Gmp.mpz

Description

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.

Note that the auto-bignum feature also makes these operations available "in" normal integers. For instance, to calculate the greatest common divisor between 51 and 85, you can do 51->gcd(85).

Method __hash: inthash_value(Gmp.mpzarg)
Description: Calculate a hash of the value.
Note: Prior to Pike 7.8.359 this function returned the low 32-bits as an unsigned integer. This could in some common cases lead to very unbalanced mappings.
See also: hash_value()

Method _decode: Gmp.mpzdecode_value(string(8bit)data)

Method _encode: string(8bit)encode_value(Gmp.mpzdata)

Method _random: Gmp.mpzrandom(Gmp.mpzarg)

Method _sprintf: stringsprintf(stringformat, ... Gmp.mpzarg ... )

Method `!: bool res = !Gmp.mpz()

Method `%: Gmp.mpz res = Gmp.mpz() % x

Method `&: Gmp.mpz res = Gmp.mpz() & x

Method `*: Gmp.mpz res = Gmp.mpz() * x

Method `+: Gmp.mpz res = Gmp.mpz() + x

Method `-: Gmp.mpz res = Gmp.mpz() - x

Method `/: Gmp.mpz res = Gmp.mpz() / x

Method `<: bool res = Gmp.mpz() < with

Method `<<: Gmp.mpz res = Gmp.mpz() << x

Method `==: bool res = Gmp.mpz() == with

Method `>: bool res = Gmp.mpz() > with

Method `>>: Gmp.mpz res = Gmp.mpz() >> x

Method `^: Gmp.mpz res = Gmp.mpz() ^ x

Method ``%: Gmp.mpz res = x % Gmp.mpz()

Method ``*: Gmp.mpz res = x * Gmp.mpz()

Method ``**: Gmp.mpz|Gmp.mpq res = x ** Gmp.mpz()
Description: Return x raised to the value of this object. The case when zero is raised to zero yields one. When this object has a negative value and x is not a float, a Gmp.mpq object will be returned.
See also: pow

Method ``+: Gmp.mpz res = x + Gmp.mpz()

Method ``-: Gmp.mpz res = x - Gmp.mpz()

Method ``/: Gmp.mpz res = x / Gmp.mpz()

Method ``<<: Gmp.mpz res = x << Gmp.mpz()

Method ``>>: Gmp.mpz res = x >> Gmp.mpz()

Method `|: Gmp.mpz res = Gmp.mpz() | x

Method `~: Gmp.mpz res = ~Gmp.mpz()

Method bin

Gmp.mpzbin(intk)

Description

Return the binomial coefficient n over k, where n is the value of this mpz object. Negative values of n are supported using the identity

(-n)->bin(k) == (-1)->pow(k)*(n+k-1)->bin(k)

(See Knuth volume 1, section 1.2.6 part G.)

Throws

The k value can't be arbitrarily large. An error is thrown if it's too large.

Method cast: (string)Gmp.mpz() (int)Gmp.mpz() (float)Gmp.mpz()
Description: Cast this mpz object to another type. Allowed types are string, int and float.

Method create

Description

Create and initialize a Gmp.mpz object.

Parameter value

Initial value. If no value is specified, the object will be initialized to zero.

Parameter base

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), in the range [37..62] (inclusive), in which case the ASCII range will be case sensitive, or either of the values 256 or -256, in which case value is taken to be the unsigned binary representation in network byte order or reversed byte order respectively.

Values in base [2..62] can be prefixed with "+" or "-". If no base is given, values prefixed with "0b" or "0B" will be interpreted as binary. Values prefixed with "0x" or "0X" will be interpreted as hexadecimal. Values prefixed with "0" will be interpreted as octal.

Note

Leading zeroes in value are not significant when a base is explicitly given. In particular leading NUL characters are not preserved in the base 256 modes.

Before GMP 5.0 only bases 2-36 and 256 were supported.

Method digits: stringdigits(void|int(2..62)|int(256)|int(-256)base)
Description: Convert this mpz object to a string. If a base is given the number will be represented in that base. Valid bases are 2-62 and 256 and -256. The default base is 10.
Note: The bases 37 to 62 are not available when compiled with GMP earlier than version 5.
See also: cast

Method encode_json: stringencode_json()

Method fac: Gmp.mpzfac()
Description: Return the factorial of this mpz object.
Throws: Since factorials grow very quickly, only small integers are supported. An error is thrown if the value in this mpz object is too large.

Method gcd: Gmp.mpzgcd(object|int|float|string ... args)
Description: Return the greatest common divisor between this mpz object and all the arguments.

Method gcdext

array(Gmp.mpz) gcdext(int|float|Gmp.mpzx)

Description

Compute the greatest common divisor between this mpz object and x. An array ({g,s,t}) is returned where g is the greatest common divisor, and s and t are the coefficients that satisfies

this * s + x * t = g

See also

gcdext2, gcd

Method gcdext2

array(Gmp.mpz) gcdext2(int|float|Gmp.mpzx)

Description

Compute the greatest common divisor between this mpz object and x. An array ({g,s}) is returned where g is the greatest common divisor, and s is a coefficient that satisfies

this * s + x * t = g

where t is some integer value.

See also

gcdext, gcd

Method hamdist: inthamdist(intx)
Description: Calculates the hamming distance between this number and x.

Method invert: Gmp.mpzinvert(int|float|Gmp.mpzx)
Description: Return the inverse of this mpz value modulo x. The returned value satisfies 0 <= result < x.
Throws: An error is thrown if no inverse exists.

Method next_prime

Gmp.mpznext_prime()

Description

Returns the next higher prime for positive numbers and the next lower for negative.

The prime number testing is using Donald Knuth's probabilistic primality test. The chance for a false positive is pow(0.25,25).

Method popcount: intpopcount()
Description: 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.

Method pow: Gmp.mpz res = pow([Gmp.mpz]a, b) orGmp.mpzpow(int|float|Gmp.mpzx)
Description: Return this mpz object raised to x. The case when zero is raised to zero yields one.
See also: powm

Method powm: Gmp.mpzpowm(int|string|float|Gmp.mpzexp, int|string|float|Gmp.mpzmod)
Description: Return ( this->pow(exp) ) % mod.
See also: pow

Method probably_prime_p: int(0..2)probably_prime_p(void|intcount)
Description: Return 2 if this mpz object is a prime, 1 if it probably is a prime, and 0 if it definitely is not a prime. Testing values below 1000000 will only return 2 or 0.
Parameter count: The prime number testing is using Donald Knuth's probabilistic primality test. The chance for a false positive is pow(0.25,count). Default value is 25 and resonable values are between 15 and 50.

Method sgn: intsgn()
Description: Return the sign of the integer, i.e. 1 for positive numbers and -1 for negative numbers.

Method size: int(0..)size(void|intbase)
Description: Return how long this mpz would be represented in the specified base. The default base is 2.

Method small_factor: intsmall_factor(void|int(1..)limit)

Method sqrt: Gmp.mpz res = sqrt([Gmp.mpz]a) orGmp.mpzsqrt()
Description: Return the the truncated integer part of the square root of this mpz object.

Method sqrtrem: array(Gmp.mpz) sqrtrem()

Module Gnome2

Class Gnome2.App

Description

Toplevel GNOME applications would normally use one Gnome2.App widget as their toplevel window. You can create as many Gnome2.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 Gnome2.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(). Properties: string app-id

Inherit Window: inherit GTK2.Window : Window

Method add_docked

Gnome2.Appadd_docked(GTK2.Widgetwidget, stringname, intbehavior, intplacement, intband_num, intband_position, int|voidoffset)

Description

Create a new Gnome2.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 Gnome2.DockTop, Gnome2.DockRight, Gnome2.DockBottom, Gnome2.DockLeft and Gnome2.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.

Method add_toolbar

Gnome2.Appadd_toolbar(GTK2.Toolbartoolbar, stringname, intbehavior, intplacement, intband_num, intband_position, int|voidoffset)

Description

Create a new Gnome2.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 Gnome2.DockTop, Gnome2.DockRight, Gnome2.DockBottom, Gnome2.DockLeft and Gnome2.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.

Method create: Gnome2.AppGnome2.App(voidappname, voidtitle)
Description: 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.

Method enable_layout_config: Gnome2.Appenable_layout_config(intenable)
Description: Specify whether the the dock's layout configuration should be automatically saved via gnome-config whenever it changes, or not.

Method set_contents: Gnome2.Appset_contents(GTK2.Widgetcontents)
Description: Sets the status bar of the application window.

Method set_menus: Gnome2.Appset_menus(GTK2.MenuBarmenu_bar)
Description: Sets the menu bar of the application window.

Method set_statusbar: Gnome2.Appset_statusbar(GTK2.Widgetstatusbar)
Description: Sets the status bar of the application window.

Method set_statusbar_custom: Gnome2.Appset_statusbar_custom(GTK2.Widgetcontainer, GTK2.Widgetstatusbar)
Description: Sets the status bar of the application window, but use container as its container.

Method set_toolbar: Gnome2.Appset_toolbar(GTK2.Toolbartoolbar)
Description: Sets the main toolbar of the application window.

Class Gnome2.Appbar

Description

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 GTK2.Gnome2Appbar( 1, 1, GTK2.GNOME_PREFERENCES_USER )->set_progress_percentage( 0.4 );

Properties: int has-progress int has-status int interactivity

Signals: clear_prompt Emitted when the prompt is cleared. mixed user_data

user_response Emitted when the user hits enter after a prompt. mixed user_data

Inherit Hbox: inherit GTK2.Hbox : Hbox

Method clear_prompt: Gnome2.Appbarclear_prompt()
Description: Remove any prompt.

Method clear_stack: Gnome2.Appbarclear_stack()
Description: Remove all status messages from appbar, and display default status message (if present).

Method create

Gnome2.AppbarGnome2.Appbar(voidhas_progress, voidhas_status, voidinteractivity)

Description

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 Gnome2.PREFERENCES_NEVER, it is never interactive. If it is set to Gnome2.PREFERENCES_USER we respect user preferences from ui-properties. If it's Gnome2.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 Gnome2.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.

Method get_progress: GTK2.ProgressBarget_progress()
Description: Returns GTK2.ProgressBar widget pointer, so that the progress bar may be manipulated further.

Method get_response: stringget_response()
Description: Get the response to the prompt, if any.

Method get_status: GTK2.Widgetget_status()
Description: Retrieves the statusbar widget.

Method pop: Gnome2.Appbarpop()
Description: Remove current status message, and display previous status message, if any. It is OK to call this with an empty stack.

Method push: Gnome2.Appbarpush(stringwhat)
Description: Push a new status message onto the status bar stack, and display it.

Method refresh: Gnome2.Appbarrefresh()
Description: Reflect the current state of stack/default. Useful to force a set_status to disappear.

Method set_default: Gnome2.Appbarset_default(stringdefault_status)
Description: What to show when showing nothing else; defaults to "".

Method set_progress_percentage: Gnome2.Appbarset_progress_percentage(floatpercentage)
Description: Sets progress bar to the given percentage.

Method set_prompt: Gnome2.Appbarset_prompt(stringprompt, intmodal)
Description: Put a prompt in the appbar and wait for a response. When the user responds or cancels, a "user-response" signal is emitted.

Method set_status: Gnome2.Appbarset_status(stringstatus)
Description: Sets the status label without changing widget state; next set or push will destroy this permanently.

Class Gnome2.Canvas

Description

Gnome2.Canvas is an engine for structured graphics that offers a rich imaging model, high performance rendering, and a powerful, high level API. It offers a choice of two rendering back-ends, one based on Xlib for extremely fast display, and another based on Libart, a sophisticated, antialiased, alpha-compositing engine. This widget can be used for flexible display of graphics and for creating interactive user interface elements.

A Gnome2.Canvas widget contains one or more Gnome2.CanvasItem objects. Items consist of graphing elements like lines, ellipses, polygons, images, text, and curves. These items are organized using Gnome2.CanvasGroup objects, which are themselves derived from Gnome2.CanvasItem. Since a group is an item it can be contained within other groups, forming a tree of canvas items. Certain operations, like translating and scaling, can be performed on all items in a group. See http://developer.gnome.org/doc/API/2.0/libgnomecanvas/GnomeCanvas.html for more information. Properties: int aa

Signals: draw_background

render_background

Inherit Layout: inherit GTK2.Layout : Layout

Method c2w: arrayc2w(intcx, intcy)
Description: Converts canvas pixel coordinates to world coordinates.

Method create: Gnome2.CanvasGnome2.Canvas(voidanti_alias)
Description: Create a new Gnome2.Canvas widget. Set anti_alias to true to create a canvas in antialias mode.

Method get_center_scroll_region: intget_center_scroll_region()
Description: Returns whether the canvas is set to center the scrolling region in the window if the former is smaller than the canvas' allocation.

Method get_color: GDK2.Colorget_color(string|voidspec)
Description: Allocates a color based on the specified X color specification. An omitted or empty string is considered transparent.

Method get_color_pixel: intget_color_pixel(intrgba)
Description: Allocates a color from the RGBA value passed into this function. The alpha opacity value is discarded, since normal X colors do not support it.

Method get_dither: intget_dither()
Description: Returns the type of dithering used to render an antialiased canvas.

Method get_item_at: Gnome2.CanvasItemget_item_at(floatx, floaty)
Description: Looks for the item that is under the specified position, which must be specified in world coordinates.

Method get_scroll_offsets: arrayget_scroll_offsets()
Description: Queries the scrolling offsets of a canvas. The values are returned in canvas pixel units.

Method get_scroll_region: mappingget_scroll_region()
Description: Queries the scrolling region of a canvas.

Method root: Gnome2.CanvasGrouproot()
Description: Queries the root group.

Method scroll_to: Gnome2.Canvasscroll_to(intcx, intcy)
Description: Makes a canvas scroll to the specified offsets, given in canvas pixel units. The canvas will adjust the view so that it is not outside the scrolling region. This function is typically not used, as it is better to hook scrollbars to the canvas layout's scrolling adjustments.

Method set_center_scroll_region: Gnome2.Canvasset_center_scroll_region(intsetting)
Description: When the scrolling region of the canvas is smaller than the canvas window, e.g. the allocation of the canvas, it can be either centered on the window or simply made to be on the upper-left corner on the window.

Method set_dither: Gnome2.Canvasset_dither(intdither)
Description: Controls the dithered rendering for antialiased canvases. The value of dither should be GDK2.RgbDitherNone, GDK2.RgbDitherNormal, or GDK2.RgbDitherMax. The default canvas setting is GDK2.RgbDitherNormal.

Method set_pixels_per_unit

Gnome2.Canvasset_pixels_per_unit(floatn)

Description

Sets the zooming factor of a canvas by specifying the number of pixels that correspond to one canvas unit.

The anchor point for zooming, i.e. the point that stays fixed and all others zoom inwards or outwards from it, depends on whether the canvas is set to center the scrolling region or not. You can contorl this using the set_center_scroll_region() function. If the canvas is set to center the scroll region, then the center of the canvas window is used as the anchor point for zooming. Otherwise, the upper-left corner of the canvas window is used as the anchor point.

Method set_scroll_region: Gnome2.Canvasset_scroll_region(floatx1, floaty1, floatx2, floaty2)
Description: Sets the scrolling region of a canvas to the specified rectangle. The canvas will then be able to scroll only within this region. The view of the canvas is adjusted as appropriate to display as much of the new region as possible.

Method w2c: arrayw2c(floatwx, floatwy)
Description: Converts world coordinates into canvas pixel coordinates.

Method w2c_affine: arrayw2c_affine()
Description: Gets the affine transform that converts from world coordinates to canvas pixel coordinates.

Method w2c_d: arrayw2c_d(floatwx, floatwy)
Description: Converts world coordinates into canvas pixel coordinates. This version returns coordinates in floating point coordinates, for greater precision.

Method window_to_world: arraywindow_to_world(floatwinx, floatwiny)
Description: Converts window-relative coordinates into world coordinates. You can use this when you need to convert mouse coordinates into world coordinates, for example.

Method world_to_window: arrayworld_to_window(floatworldx, floatworldy)
Description: Converts world coordinates into window-relative coordinates.

Class Gnome2.CanvasBpath

Inherit CanvasShape: inherit Gnome2.CanvasShape : CanvasShape

Class Gnome2.CanvasClipgroup

Description: Properties: string path int wind

Inherit CanvasGroup: inherit Gnome2.CanvasGroup : CanvasGroup

Class Gnome2.CanvasEllipse

Inherit CanvasRE: inherit Gnome2.CanvasRE : CanvasRE

Class Gnome2.CanvasGroup

Inherit CanvasItem: inherit Gnome2.CanvasItem : CanvasItem

Class Gnome2.CanvasItem

Description

This is the base class for all canvas items. Canvas items are the drawing elements of a Gnome2.Canvas. Example items include lines, ellipses, polygons, images, text, curves, and even arbitary GTK+ widgets.

Properties: Gnome2.CanvasItem parent

Signals: event

Inherit Object: inherit GTK2.Object : Object

Class Gnome2.CanvasLine

Description: Properties: float arrow-shape-a float arrow-shape-b float arrow-shape-c int cap-style string fill-color GDK2.Color fill-color-gdk int fill-color-rgba GDK2.Drawable fill-stipple int first-arrowhead int join-style int last-arrowhead int line-style Gnome2.CanvasPoints points int smooth int spline-steps int width-pixels float width-units

Inherit CanvasItem: inherit Gnome2.CanvasItem : CanvasItem

Class Gnome2.CanvasPixbuf

Description: Properties: int anchor float height int height-in-pixels int height-set GDK2.Pixbuf pixbuf float width int width-in-pixels int width-set float x int x-in-pixels float y int y-in-pixels

Inherit CanvasItem: inherit Gnome2.CanvasItem : CanvasItem

Class Gnome2.CanvasRE

Description: Properties: float x1 float x2 float y1 float y2

Inherit CanvasShape: inherit Gnome2.CanvasShape : CanvasShape

Class Gnome2.CanvasRect

Inherit CanvasRE: inherit Gnome2.CanvasRE : CanvasRE

Class Gnome2.CanvasRichText

Description

Properties: int anchor int cursor-blink int cursor-visible int direction int editable int grow-height float height int indent int justification int left-margin int pixels-above-lines int pixels-below-lines int pixels-inside-wrap int right-margin string text int visible float width int wrap-mode float x float y

Signals: tag_changed

Inherit CanvasItem: inherit Gnome2.CanvasItem : CanvasItem

Method get_buffer: GTK2.TextBufferget_buffer()
Description: Get the text buffer.

Method set_buffer: Gnome2.CanvasRichTextset_buffer(GTK2.TextBufferbuffer)
Description: Set the text buffer.

Class Gnome2.CanvasShape

Description: Properties: int cap-style string dash string fill-color GDK2.Color fill-color-gdk int fill-color-rgba GDK2.Drawable fill-stipple int join-style float miterlimit string outline-color GDK2.Color outline-color-gdk int outline-color-rgba GDK2.Drawable outline-stipple int width-pixels float width-units int wind

Inherit CanvasItem: inherit Gnome2.CanvasItem : CanvasItem

Class Gnome2.CanvasText

Description: Properties: int anchor Pango.AttrList attributes int clip float clip-height float clip-width string family int family-set string fill-color GDK2.Color fill-color-gdk int fill-color-rgba GDK2.Drawable fill-stipple string font Pango.FontDescription font-dest int justification string markup int rise int rise-set float scale int scale-set int size float size-points int size-set Pango.Stretch stretch int stretch-set int strikethrough int strikethrough-set Pango.Style style int style-set string text float text-height float text-width Pango.Underline underline int underline-set Pango.Variant variant int variant-set int weight float x float x-offset float y float y-offset

Inherit CanvasItem: inherit Gnome2.CanvasItem : CanvasItem

Class Gnome2.CanvasWidget

Description: Properties: int anchor float height int size-pixels GTK2.Widget widget float width float x float y

Inherit CanvasItem: inherit Gnome2.CanvasItem : CanvasItem

Class Gnome2.Client

Description

Signals: connect Called once the client has been connected to the signal manager. int arg1, mixed user_data

die Called when the session manager wants the client to shut down. mixed user_data

disconnect Called when the client is disconnected from the session manager. mixed user_data

save_complete Called when the session manager has finished checkpointing all of the clients. Clients are then free to change their state. mixed user_data

save_yourself Called when either a "SaveYourself" or a "SaveYourselfPhase2" call is made by the session manager. int arg1: the phase of the "SaveYourself" command ('1' or '2'). int arg2: the data which should be saved (local, global, or both). int arg3: true if the session manager is shutting down. int arg4: how the client is allowed to interact with the user while saving. int arg5: true if this is to be a "fast" shutdown. mixed user_data

shutdown_cancelled Called if the session manager had sent a "SaveYourself" to all clients in preparation for shutting down and the shutdown was then cancelled. A client can then continue running and change its state. mixed user_data

Inherit Object: inherit GTK2.Object : Object

Method create: Gnome2.ClientGnome2.Client()
Description: Gets the master session management client.

Method disconnect: Gnome2.Clientdisconnect()
Description: Disconnect the client from the session manager.

Method flush: Gnome2.Clientflush()
Description: This will force the underlying connection to the session manager to be flushed. This is useful if you have some pending changes that you want to make sure get committed.

Method get_config_prefix: stringget_config_prefix()
Description: Get the config prefix. This config prefix provides a suitable place to store any details about the state of the client which can not be described using the app's command line arguments (as set in the restart command).

Method get_desktop_id: stringget_desktop_id()
Description: Get the client ID of the desktop's current instance, i.e. if you consider the desktop as a whole as a session managed app, this returns its session ID using a gnome extension to session management. May return empty for apps not running under a recent version of gnome-session; apps should handle that case.

Method get_flags: intget_flags()
Description: Determine the client's status with the session manager.

Method get_global_config_prefix

stringget_global_config_prefix()

Description

Get the config prefix that will be returned by get_config_prefix() for clients which have NOT been restarted or cloned (i.e. for clients started by the user without '--sm-' options). This config prefix may be used to write the user's preferred config for these "new"clients".

You could also use this prefix as a place to store and retrieve config details that you wish to apply to ALL instances of the app. However, this practice limits the users freedom to configure each instance in a different way so it should be used with caution.

Method get_id: stringget_id()
Description: Returns the session management ID.

Method get_previous_id: stringget_previous_id()
Description: Get the session management ID from the previous session.

Method request_phase_2: Gnome2.Clientrequest_phase_2()
Description: Request the session manager to emit the "save-yourself" signal for a second time after all the clients in the session have ceased interacting with the user and entered an idle state. This might be useful if your app managers other apps and requires that they are in an idle state before saving its final data.

Method request_save

Gnome2.Clientrequest_save(intsave_style, intshutdown, intinteract_style, intfast, intglobal)

Description

Request the session manager to save the session in some way. The arguments correspond with the arguments passed to the "save-yourself" signal handler.

The save_style (GNOME_SAVE_BOTH, GNOME_SAVE_GLOBAL and GNOME_SAVE_LOCAL) indicates whether the save should affect data accessible to other users (GTK2.GNOME_SAVE_GLOBAL) or only the state visible to the current user (GTK2.GNOME_SAVE_LOCAL), or both. Setting shutdown to true will initiate a logout. The interact_style (GNOME_INTERACT_ANY, GNOME_INTERACT_ERRORS and GNOME_INTERACT_NONE) specifies which kinds of interaction will be available. Setting fast to true will limit the save to setting the session manager properties plus any essential data. Setting the value of global to true will request that all the other apps in the session do a save as well. A global save is mandatory when doing a shutdown.

Method save_any_dialog: Gnome2.Clientsave_any_dialog(GTK2.Dialogdialog)
Description: May be called during a "save-yourself" handler to request that a (modal) dialog is presented to the user. The session manager decides when the dialog is shown, but it will not be shown it unless the session manager is sending an interaction style of GTK2.GNOME_INTERACT_ANY. "Cancel" and "Log out" buttons will be added during a shutdown.

Method save_error_dialog: Gnome2.Clientsave_error_dialog(GTK2.Dialogdialog)
Description: May be called during a "save-yourself" handler when an error has occurred during the save.

Method set_clone_command: Gnome2.Clientset_clone_command(arrayargv)
Description: Set a command the session manager can use to create a new instance of the application. Not implemented yet.

Method set_current_directory: Gnome2.Clientset_current_directory(stringdir)
Description: Set the directory to be in when running shutdown, discard, restart, etc. commands.

Method set_discard_command: Gnome2.Clientset_discard_command(arrayargv)
Description: Provides a command to run when a client is removed from the session. It might delete session-specific config files, for example. Executing the discard command on the local host should delete the information saved as part of the session save that was in progress when the discard command was set. For example: string prefix=client->get_config_prefix(); array argv=({ "rm","-r" }); argv+=({ Gnome2.Config->get_real_path(prefix) }); client->set_discard_command(argv); Not implemented yet.

Method set_environment: Gnome2.Clientset_environment(stringname, stringvalue)
Description: Set an environment variable to be placed in the client's environment prior to running restart, shutdown, discard, etc. commands.

Method set_global_config_prefix: Gnome2.Clientset_global_config_prefix(stringprefix)
Description: Set the value used for the global config prefix. The global config prefix defaults to a name based on the name of the executable. This function allows you to set it to a different value. It should be called BEFORE retrieving the config prefix for the first time. Later calls will be ignored.

Method set_priority: Gnome2.Clientset_priority(intpriority)
Description: The gnome-session manager restarts clients in order of their priorities in a similar way to the start up ordering in SysV. This function allows the app to suggest a position in this ordering. The value should be between 0 and 99. A default value of 50 is assigned to apps that do not provide a value. The user may assign a different priority.

Method set_resign_command

Gnome2.Clientset_resign_command(arrayargv)

Description

Some clients can be "undone", removing their effects and deleting any saved state. For example, xmodmap could register a resign command to undo the keymap changes it saved.

Used by clients that use the GTK2.GNOME_RESTART_ANYWAY restart style to undo their effects (these clients usually perform initialization functions and leave effects behind after they die). The resign command combines the effects of a shutdown command and a discard command. It is executed when the user decides that the client should cease to be restarted. Not implemented yet.

Method set_restart_command: Gnome2.Clientset_restart_command(arrayargv)
Description: When clients crash or the user logs out and back in, they are restarted. This command should perform the restart. Executing the restart command on the local host should reproduce the state of the client at the time of the session save as closely as possible. Saving config info under the get_config_prefix() is generally useful. Not implemented yet.

Method set_restart_style: Gnome2.Clientset_restart_style(intstyle)
Description: Tells the session manager how the client should be restarted in future sessions. One of GNOME_RESTART_ANYWAY, GNOME_RESTART_IF_RUNNING, GNOME_RESTART_IMMEDIATELY and GNOME_RESTART_NEVER

Method set_shutdown_command

Gnome2.Clientset_shutdown_command(arrayargv)

Description

GTK2.GNOME_RESTART_ANYWAY clients can set this command to run when the user logs out but the client is no longer running.

Used by clients that use the GTK2.GNOME_RESTART_ANYWAY restart style to undo their effects (these clients usually perform initialization functions and leave effects behind after they die). The shutdown command simply undoes the effects of the client. It is executed during a normal logout. Not implemented yet.

Class Gnome2.DateEdit

Description

The GnomeDateEdit widget provides a way to enter dates and times with a helper calendar to let the user select the date. GTK2.Gnome2DateEdit(time(),1,1);

GTK2.Gnome2DateEdit(time(),0,1);

Properties: int dateedit-flags int initial-time int lower-hour int time int upper-hour

Signals: date_changed

time_changed

Inherit Hbox: inherit GTK2.Hbox : Hbox

Method create: Gnome2.DateEditGnome2.DateEdit(voidthe_time, voidshow_time, voiduse_24_format)
Description: Creates a new GnomeDateEdit widget which can be used to provide an easy to use way for entering dates and times.

Method get_flags: intget_flags()
Description: Get the flags.

Method get_initial_time: int64get_initial_time()
Description: Queries the initial time that was set using set_time() or during creation.

Method get_time: int64get_time()
Description: Return the time entered in the widget.

Method set_flags: Gnome2.DateEditset_flags(intflags)
Description: Bitwise or of GNOME_DATE_EDIT_24_HR, GNOME_DATE_EDIT_SHOW_TIME and GNOME_DATE_EDIT_WEEK_STARTS_ON_MONDAY.

Method set_popup_range: Gnome2.DateEditset_popup_range(intlow_hour, intup_hour)
Description: Sets the range of times that will be provide by the time popup selectors.

Method set_time: Gnome2.DateEditset_time(int64the_time)
Description: Changes the displayed date and time in the GnomeDateEdit widget to be the one represented by the_time.

Class Gnome2.Druid

Description

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 Gnome2.Druid widget, and the set of W(Gnome2.DruidPage) widgets. The Gnome2.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(GTK2.Window) in almost all cases. The W(Gnome2.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.

Properties: int show-finish int show-help

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.

help

Inherit Container: inherit GTK2.Container : Container

Method append_page: Gnome2.Druidappend_page(Gnome2.DruidPagepage)
Description: This will append a GnomeDruidPage into the internal list of pages that the druid has.

Method create: Gnome2.DruidGnome2.Druid()
Description: Create a new druid

Method insert_page: Gnome2.Druidinsert_page(Gnome2.DruidPageback_page, Gnome2.DruidPagepage)
Description: 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.

Method prepend_page: Gnome2.Druidprepend_page(Gnome2.DruidPagepage)
Description: This will prepend a GnomeDruidPage into the internal list of pages that the druid has.

Method set_buttons_sensitive: Gnome2.Druidset_buttons_sensitive(intback_sensitive, intnext_sensitive, intcancel_sensitive, inthelp_sensitive)
Description: 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.

Method set_page: Gnome2.Druidset_page(Gnome2.DruidPagepage)
Description: This will make page the currently showing page in the druid. page must already be in the druid.

Method set_show_finish: Gnome2.Druidset_show_finish(intshow_finish)
Description: 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".

Method set_show_help: Gnome2.Druidset_show_help(intshow_help)
Description: Sets the "Help" button on the druid to be visible in the lower left corner of the widget, if show_help is true.

Class Gnome2.DruidPage

Description

This widget is a virtual widget to define the interface to a druid page. It's descendants are placed in a W(Gnome2.Druid) widget.

Signals: back

cancel

finish

next

prepare

Inherit Bin: inherit GTK2.Bin : Bin

Method back: intback()
Description: This will emit the "back" signal for that particular page.

Method cancel: intcancel()
Description: This will emit the "cancel" signal for that particular page.

Method create: Gnome2.DruidPageGnome2.DruidPage()
Description: Creates a new Gnome2.DruidPage.

Method finish: Gnome2.DruidPagefinish()
Description: This emits the "finish" signal for the page.

Method next: intnext()
Description: This will emit the "next" signal for that particular page. It is called by gnome-druid exclusviely. It is expected that non-linear Druid's will override this signal and return true if it handles changing pages.

Method prepare: Gnome2.DruidPageprepare()
Description: This emits the "prepare" signal for the page. It is called by gnome-druid exclusively. This function is called immediately prior to a druid page being show so that it can "prepare" for display.

Class Gnome2.DruidPageEdge

Inherit DruidPage: inherit Gnome2.DruidPage : DruidPage

Method create: Gnome2.DruidPageEdgeGnome2.DruidPageEdge(voidposition, voidanti_alias)
Description: Create a new Gnome2.DruidPageEdge, with optional anti-aliasing.

Method set_bg_color: Gnome2.DruidPageEdgeset_bg_color(GDK2.Colorcolor)
Description: This will set the background color.

Method set_logo: Gnome2.DruidPageEdgeset_logo(GDK2.Pixbuflogo)
Description: Sets a GDK2.Pixbuf as the logo in the top right corner. If omitted, then no logo will be displayed.

Method set_logo_bg_color: Gnome2.DruidPageEdgeset_logo_bg_color(GDK2.Colorcolor)
Description: Sets the color behind the druid page's logo.

Method set_text: Gnome2.DruidPageEdgeset_text(sprintf_formattext, sprintf_args ... fmt)
Description: Sets the contents of the text portion.

Method set_text_color: Gnome2.DruidPageEdgeset_text_color(GDK2.Colorcolor)
Description: Sets the color of the text in the body of the page.

Method set_textbox_color: Gnome2.DruidPageEdgeset_textbox_color(GDK2.Colorcolor)
Description: Sets the color of the background in the main text area of the page.

Method set_title: Gnome2.DruidPageEdgeset_title(stringtitle)
Description: Sets the contents of the page's title text.

Method set_title_color: Gnome2.DruidPageEdgeset_title_color(GDK2.Colorcolor)
Description: Sets the color of the title text.

Method set_top_watermark: Gnome2.DruidPageEdgeset_top_watermark(GDK2.Pixbufwatermark)
Description: Sets a GDK2.Pixbuf as the watermark on top of the top strip on the druid. If watermark is omitted, it is reset to the normal color.

Method set_watermark: Gnome2.DruidPageEdgeset_watermark(GDK2.Pixbufwatermark)
Description: Sets a GDK2.Pixbuf as the watermark on the left strip on the druid. If watermark is omitted, it is reset to the normal color.

Class Gnome2.DruidPageStandard

Description: Properties: string background GDK2.Color background-gdk int background-set string contents-background GDK2.Color contents-background-gdk int contents-background-set GDK2.Pixbuf logo string logo-background GDK2.Color logo-background-gdk int logo-background-set string title string title-foreground GDK2.Color title-foreground-gdk int title-foreground-set GDK2.Pixbuf top-watermark

Inherit DruidPage: inherit Gnome2.DruidPage : DruidPage

Method append_item

Gnome2.DruidPageStandardappend_item(stringquestion, GTK2.Widgetitem, stringadditional_info)

Description

Convenience function to add a GTK2.Widget to the vbox. This function creates a new contents section that has the question text followed by the item widget and then the additional_info text, all stacked vertically from top to bottom.

The item widget could be something like a set of radio checkbuttons requesting a choice from the user.

Method create: Gnome2.DruidPageStandardGnome2.DruidPageStandard(voidtitle, voidlogo, voidtop_watermark)
Description: Construct a new Gnome2.DruidPageStandard.

Method set_background: Gnome2.DruidPageStandardset_background(GDK2.Colorcolor)
Description: Sets the background color of the top section.

Method set_contents_background: Gnome2.DruidPageStandardset_contents_background(GDK2.Colorcolor)
Description: Sets the color of the main contents section's background.

Method set_logo: Gnome2.DruidPageStandardset_logo(GDK2.Pixbuflogo)
Description: Sets a GDK2.Pixbuf as the logo in the top right corner. If omitted, then no logo will be displayed.

Method set_logo_background: Gnome2.DruidPageStandardset_logo_background(GDK2.Colorcolor)
Description: Sets the background color of the logo.

Method set_title: Gnome2.DruidPageStandardset_title(stringtitle)
Description: Sets the title.

Method set_title_foreground: Gnome2.DruidPageStandardset_title_foreground(GDK2.Colorcolor)
Description: Sets the title text to the specified color.

Method set_top_watermark: Gnome2.DruidPageStandardset_top_watermark(GDK2.Pixbufwatermark)
Description: Sets a GDK2.Pixbuf as the watermark on top of the top strip on the druid. If watermark is omitted, it is reset to the normal color.

Class Gnome2.Href

Description

This widget is a GtkButton button that contains a URL. When clicked it invokes the configured browser for the URL you provided.

GTK2.Gnome2Href( "http://www.gnome.org", "GNOME Web Site" )

GTK2.Gnome2Href( "http://www.gnome.org" )

Properties: string text string url

Style properties: GDK.Color link-color

Inherit Button: inherit GTK2.Button : Button

Method create: Gnome2.HrefGnome2.Href(voidurl, voidlabel)
Description: 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.

Method get_text: stringget_text()
Description: Returns the contents of the label widget used to display the link text.

Method get_url: stringget_url()
Description: Return the url

Method set_text: Gnome2.Hrefset_text(sprintf_formattext, sprintf_args ... fmt)
Description: Sets the internal label widget text (used to display a URL's link text) to the given value.

Method set_url: Gnome2.Hrefset_url(stringurl)
Description: Sets the internal URL

Class Gnome2.IconEntry

Description

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. Properties: string browse-dialog-title string filename string history-id GTK2.Dialog pick-dialog string pixmap-subdir

Signals: browse

changed

Inherit Vbox: inherit GTK2.Vbox : Vbox

Method create: Gnome2.IconEntryGnome2.IconEntry(voidhistory_id, voidtitle)
Description: Creates a new icon entry widget

Method get_filename: stringget_filename()
Description: 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.

Method pick_dialog: GTK2.Widgetpick_dialog()
Description: If a pick dialog exists, returns it. This is if you need to do something with all dialogs. You would use the browse signal with connect_after to get the pick dialog when it is displayed.

Method set_browse_dialog_title: Gnome2.IconEntryset_browse_dialog_title(stringtitle)
Description: Set the title of the browse dialog.

Method set_filename: intset_filename(stringfilename)
Description: Sets the icon of Gnome2.IconEntry to be the one pointed to by filename.

Method set_history_id: Gnome2.IconEntryset_history_id(stringhistory_id)
Description: Set the history_id of the entry in the browse dialog and reload the history.

Method set_pixmap_subdir: Gnome2.IconEntryset_pixmap_subdir(stringsubdir)
Description: Sets the subdirectory below gnome's default pixmap directory to use as the default path for the file entry.

Class Gnome2.IconSelection

Description: An icon listing/chooser display.

Inherit Vbox: inherit GTK2.Vbox : Vbox

Method add_defaults: Gnome2.IconSelectionadd_defaults()
Description: Adds the default pixmap directory into the selection widget.

Method add_directory: Gnome2.IconSelectionadd_directory(stringdir)
Description: Adds the icons from the directory dir to the selection widget.

Method clear: Gnome2.IconSelectionclear(int|voidnot_shown)
Description: 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.

Method create: Gnome2.IconSelectionGnome2.IconSelection()
Description: Creates a new icon selection widget, it uses a W(GnomeIconList) for the listing of icons

Method get_box: GTK2.Widgetget_box()
Description: Gets the W(Vbox) widget.

Method get_icon: stringget_icon(intfull_path)
Description: 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.

Method select_icon: Gnome2.IconSelectionselect_icon(stringfilename)
Description: Selects the icon filename. This icon must have already been added and shown

Method show_icons: Gnome2.IconSelectionshow_icons()
Description: 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.

Method stop_loading: Gnome2.IconSelectionstop_loading()
Description: Stop the loading of images when we are in the loop in show_icons.

Module Graphics

Module Graphics.Graph

Inherit create_pie: protected inherit .create_pie : create_pie

Method pie
Method bars
Method sumbars
Method line
Method norm
Method graph: Image.Imagepie(mapping(string:mixed) diagram_data)
Image.Imagebars(mapping(string:mixed) diagram_data)
Image.Imagesumbars(mapping(string:mixed) diagram_data)
Image.Imageline(mapping(string:mixed) diagram_data)
Image.Imagenorm(mapping(string:mixed) diagram_data)
Image.Imagegraph(mapping(string:mixed) diagram_data)
Description: Generate a graph of the specified type. See check_mapping for an explanation of diagram_data.

Method check_mapping

mapping(string:mixed) check_mapping(mapping(string:mixed) diagram_data, stringtype)

Description

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.

Parameter diagram_data

`"drawtype" : mixed`	Default: "linear" Will be set to "2D" for pie below Only "linear" works for now.
`"tone" : mixed`	Default: 0 If present a Pie-chart will be toned.
`"3Ddepth" : mixed`	Default: 10 How much 3D-depth a graph will have in pixels Default is 10.
`"data" : array(array(float))`	Default: ({({1.0}), ({2.0}), ({4.0})}) Will be set to something else with graph An array of arrays. Each array describing a data-set. The graph-function however should be fed with an array of arrays with X,Y-pairs. Example: ({({1.0, 2.0, 3.0}),({1.2, 2.2, 3.8})}) draws stuff in yellow with the values (1.0, 2.0, 3.0), and (1.2, 2.2, 3.8) in blue.
`"labels" : array(string)`	Default: 0 Should have four elements ({xquantity, yquantity, xunit, yunit}). The strings will be written on the axes.
`"xnames" : array(string)`	Default: 0 An array(string) with the text that will be written under the X-axis. This should be the same size as sizeof(data).
`"ynames" : array(string)`	Default: 0 An array(string) with the text that will be written to the left of the Y-axis.
`"fontsize" : mixed`	Default: 10 The size of the text. Default is 10.
`"graphlinewidth" : mixed`	Default: 1.0 Width of the lines that draws data in Graph and line. Default is 1.0
`"labelsize" : mixed`	Default: same as fontsize The size of the text for labels.
`"legendfontsize" : mixed`	Default: same as fontsize The size of the text for the legend.
`"legend_texts" : mixed`	Default: 0 The texts that will be written the legend.
`"values_for_xnames" : array(float)`	Default: 0 An array(float) that describes where the ynames should be placed. The numbers are like the data-numbers. Default is equally distributed.
`"values_for_ynames" : array(float)`	Default: 0 An array(float) that describes where the ynames should be placed. The numbers are like the data-numbers. Default is equally distributed.
`"xsize" : int`	Default: 100 X-size of the graph in pixels.
`"ysize" : int`	Default: 100 Y-size of the graph in pixels.
`"image" : mixed`	Default: 0 An image that the graph will be drawn on.
`"legendcolor" : mixed`	Default: 0 The color of the text in the legend. Default is?
`"legendimage" : mixed`	Default: 0 I have no idea.
`"bgcolor" : mixed`	Default: 0 The bakground-color. If the the background is a image this color is used for antialias the texts.
`"gbimage" : mixed`	Default: 0 Some sort of image...
`"axcolor" : mixed`	Default: ({0,0,0}) The color of the axis.
`"datacolors" : mixed`	Default: 0 An array of colors for the datasets.
`"backdatacolors" : mixed`	Default: 0 An array of color that do something...
`"textcolor" : mixed`	Default: ({0,0,0}) Color of the text. Default is black.
`"labelcolor" : mixed`	Default: 0 Color of the labeltexts.
`"orient" : string`	Default: "hor" Can be "hor" or "vert". Orientation of the graph.
`"linewidth" : mixed`	Default: 0 Width of lines (the axis and their like).
`"backlinewidth" : mixed`	Default: 0 Width of the outline-lines. Default is 0.
`"vertgrid" : mixed`	Default: 0 If the vertical grid should be present.
`"horgrid" : mixed`	Default: 0 If the horizontal grid should be present.
`"gridwidth" : mixed`	Default: 0 Width of the grid. Default is linewidth/4.
`"rotate" : mixed`	Default: 0 How much a the Pie in a Pie-shart should be rotated in degrees.
`"center" : mixed`	Default: 0 Makes the first Pie-slice be centered.
`"bw" : mixed`	Default: 0 Draws the graph black and white.
`"eng" : mixed`	Default: 0 Writes the numbers in eng format.
`"neng" : mixed`	Default: 0 Writes the numbers in engformat except for 0.1 < x < 1.0
`"xmin" : mixed`	Default: 0 Where the X-axis should start. This will be overrided by datavalues.
`"ymin" : mixed`	Default: 0 Where the Y-axis should start. This will be overridden by datavalues.
`"name" : mixed`	Default: 0 A string with the name of the graph that will be written at top of the graph.
`"namecolor" : mixed`	Default: 0 The color of the name.
`"font" : mixed`	Default: Image.Font() The font that will be used.
`"gridcolor" : mixed`	Default: ({0,0,0} The color of the grid. Default is black.

Class Graphics.Graph.create_bars

Description: Graph sub-module for drawing bars.

Inherit create_graph: inherit .create_graph : create_graph

Class Graphics.Graph.create_graph

Description

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.

Inherit polyline: inherit .polyline : polyline

Class Graphics.Graph.create_pie

Description: Graph sub-module for drawing pie-charts.

Inherit create_bars: inherit .create_bars : create_bars

Class Graphics.Graph.polyline

Description: Graph sub-module providing draw functions.

Module HTTPAccept

Description

High performance webserver optimized for somewhat static content.

HTTPAccept is a less capable WWW-server than the Protocols.HTTP.Server server, but for some applications it can be preferable. It is significantly more optimized, for most uses, and can handle a very high number of requests per second on even low end machines.

Class HTTPAccept.LogEntry

Variable from: string HTTPAccept.LogEntry.from

Variable method: string HTTPAccept.LogEntry.method

Variable protocol: string HTTPAccept.LogEntry.protocol

Variable raw: string HTTPAccept.LogEntry.raw

Variable received_bytes: int HTTPAccept.LogEntry.received_bytes

Variable reply: int HTTPAccept.LogEntry.reply

Variable sent_bytes: int HTTPAccept.LogEntry.sent_bytes

Variable time: int HTTPAccept.LogEntry.time

Variable url: string HTTPAccept.LogEntry.url

Class HTTPAccept.Loop

Method cache_status

mapping(string:int) cache_status()

Description

Returns information about the cache.

`hits : int`	The number of hits since start
`misses : int`	The number of misses since start
`stale : int`	The number of misses that were stale hits, and not used
`size : int`	The total current size
`entries : int`	The number of entries in the cache
`max_size : int`	The maximum size of the cache
`sent_bytes : int`	The number of bytes sent since the last call to cache_status
`received_bytes : int`	The number of bytes received since the last call to cache_status
`num_requests : int`	The number of requests received since the last call to cache_status

Method create

HTTPAccept.LoopHTTPAccept.Loop(Stdio.Portport, RequestProgramprogram, function(RequestProgram:void) request_handler, intcache_size, boolkeep_log, inttimeout)

Description

Create a new HTTPAccept.

This will start a new thread that will listen for requests on the port, parse them and pass on requests, instanced from the program class (which has to inherit RequestProgram to the request_handler callback function.

cache_size is the maximum size of the cache, in bytes. keep_log indicates if a log of all requests should be kept. timeout if non-zero indicates a maximum time the server will wait for requests.

Method log_as_array: array(LogEntry) log_as_array()
Description: Return the current log as an array of LogEntry objects.

Method log_as_commonlog_to_file

intlog_as_commonlog_to_file(Stdio.Streamfd)

Description

Write the current log to the specified file in a somewhat common commonlog format.

Will return the number of bytes written.

Method log_size: intlog_size()
Description: Returns the number of entries waiting to be logged.

Method logp: boollogp()
Description: Returns true if logging is enabled

Class HTTPAccept.RequestProgram

Variable client: string HTTPAccept.RequestProgram.client
Description: The user agent

Variable data: string HTTPAccept.RequestProgram.data
Description: Any payload that arrived with the request

Variable headers: mapping(string:array(string)) HTTPAccept.RequestProgram.headers
Description: All received headers

Variable method: string HTTPAccept.RequestProgram.method
Description: The method (GET, PUT etc)

Variable my_fd: Stdio.NonblockingStream HTTPAccept.RequestProgram.my_fd
Description: The filedescriptor for this request.

Variable not_query: string HTTPAccept.RequestProgram.not_query
Description: The part of the URL before the first '?'.

Variable pragma: multiset(string) HTTPAccept.RequestProgram.pragma
Description: Tokenized pragma headers

Variable prot: string HTTPAccept.RequestProgram.prot
Description: The protocol part of the request. As an example "HTTP/1.1"

Variable query: string HTTPAccept.RequestProgram.query
Description: The part of the URL after the first '?'

Variable raw: string HTTPAccept.RequestProgram.raw
Description: The full request

Variable raw_url: string HTTPAccept.RequestProgram.raw_url
Description: The raw URL received, the part after the method and before the protocol.

Variable referer: string HTTPAccept.RequestProgram.referer
Description: The referer header

Variable remoteaddr: string HTTPAccept.RequestProgram.remoteaddr
Description: The remote address

Variable rest_query: string HTTPAccept.RequestProgram.rest_query
Description: The part of the URL after the first '?' that does not seem to be query variables.

Variable since: string HTTPAccept.RequestProgram.since
Description: The get-if-not-modified, if set.

Variable time: int HTTPAccept.RequestProgram.time
Description: The time_t when the request arrived to the server

Variable variables: mapping(string:string) HTTPAccept.RequestProgram.variables
Description: Parsed query variables

Method output: voidoutput(stringdata)
Description: Send data directly to the remote side.

Method reply: voidreply(stringdata)
voidreply(stringheaders, Stdio.Filefd, intlen)
voidreply(int(0)ignore, Stdio.Filefd, intlen)
Description: Send a reply to the remote side. In the first case the data will be sent. In the second case the headers will be sent, then len bytes from fd. In the last case len bytes from fd will be sent.

Method reply_with_cache: voidreply_with_cache(stringdata, int(1..)stay_time)
Description: Send data as the reply, and keep it as a cache entry to requests to this URL for stay_time seconds.

Module Java

Inherit "___Java": inherit "___Java" : "___Java"

Variable pkg

object Java.pkg

Description

Singleton 'package' object.

Usage: object cls = Java.pkg.java.lang.String;

or: object cls = Java.pkg["java/lang/String"];

cls is a jclass object; call it to create a jobject, which will have all the methods of the Java class.

Example: Java.pkg.FooClass()->getResult();

Method JArray: jobjectJArray(arraya)

Method JBoolean: jobjectJBoolean(inti)

Method JFloat: jobjectJFloat(floatf)

Method JHashMap: jobjectJHashMap(mappingm)

Method JInteger: jobjectJInteger(inti)

Method JString: jobjectJString(strings)

Class Java.jclass

Description

Interface to one Java class. Can be called to construct a jobject.

Obtained normally via Java.pkg.`[] and not created directly.

Class Java.jobject

Description

An instantiated Java object. Has methods for all the Java object's methods. Can be cast to string.

NOTE: Use indices(x) to get a list of the available methods.

Constructed from a jclass object.

Module Kerberos

Class Kerberos.Context

Method authenticate: boolauthenticate(stringuser, stringpassword)

Module Languages

Module Languages.PLIS

Description: PLIS, Permuted Lisp. A Lisp language somewhat similar to scheme.

Method default_environment

Environmentdefault_environment()

Description

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

Method init_functions: voidinit_functions(Environmentenvironment)
Description: Adds the functions +, *, -, =, <, >, concat, read-string, eval, apply, global-environment, var, cdr, null?, setcar!, setcdr!, cons and list to the environment.

Method init_specials: voidinit_specials(Environmentenvironment)
Description: Adds the special functions quote, set!, setq, while, define, defmacro, lambda, if, and, or, begin and catch to the environment.

Method main

voidmain()

Description

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

Class Languages.PLIS.Binding

Variable value: object Languages.PLIS.Binding.value

Method __create__: protectedlocalvoid__create__(objectvalue)

Method create: Languages.PLIS.BindingLanguages.PLIS.Binding(objectvalue)

Class Languages.PLIS.Builtin

Inherit LObject: inherit LObject : LObject

Variable apply: function(:void) Languages.PLIS.Builtin.apply

Method __create__: protectedlocalvoid__create__(function(:void) apply)

Method create: Languages.PLIS.BuiltinLanguages.PLIS.Builtin(function(:void) apply)

Class Languages.PLIS.Lambda

Inherit LObject: inherit LObject : LObject

Variable formals
Variable list: object Languages.PLIS.Lambda.formals
object Languages.PLIS.Lambda.list

Method __create__: protectedlocalvoid__create__(objectformals, objectlist)

Method create: Languages.PLIS.LambdaLanguages.PLIS.Lambda(objectformals, objectlist)

Class Languages.PLIS.Number

Inherit SelfEvaluating: inherit SelfEvaluating : SelfEvaluating

Variable value: int|float|object Languages.PLIS.Number.value

Method __create__: protectedlocalvoid__create__(int|float|objectvalue)

Method create: Languages.PLIS.NumberLanguages.PLIS.Number(int|float|objectvalue)

Class Languages.PLIS.Parser

Variable buffer: string Languages.PLIS.Parser.buffer

Method __create__: protectedlocalvoid__create__(stringbuffer)

Method create: Languages.PLIS.ParserLanguages.PLIS.Parser(stringbuffer)

Class Languages.PLIS.SelfEvaluating

Inherit LObject: inherit LObject : LObject

Variable name: string Languages.PLIS.SelfEvaluating.name

Method __create__: protectedlocalvoid__create__(stringname)

Method create: Languages.PLIS.SelfEvaluatingLanguages.PLIS.SelfEvaluating(stringname)

Class Languages.PLIS.String

Inherit SelfEvaluating: inherit SelfEvaluating : SelfEvaluating

Variable value: string Languages.PLIS.String.value

Method __create__: protectedlocalvoid__create__(stringvalue)

Method create: Languages.PLIS.StringLanguages.PLIS.String(stringvalue)

Module Local

Description

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.

Example

If the user has installed the pike module Mine.pmod in the directory $HOME/pike_modules. it can be accessed as Local.Mine.

See also

Local.add_path(), Local.remove_path()

Inherit __joinnode: inherit __joinnode : __joinnode

Method add_path: booladd_path(stringpath)
Description: This function prepends path to the Local module searchpath.
Parameter path: The path to the directory to be added.
Returns: Returns 1 on success, otherwise 0.

Method remove_path: voidremove_path(stringpath)
Description: This function removes path from the Local module searchpath. If path is not in the search path, this is a noop.
Parameter path: The path to be removed.

Module Locale

Description

The functions and classes in the top level of the Locale module implements a dynamic localization system, suitable for programs that need 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.

Example

// 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;}

Note

In order to update your code to actually use the locale strings you need to run the locale extractor.

This is available as pike -x extract_locale

Syntax: pike -x extract_locale [arguments] infile(s)
   Arguments: --project=name  default: first found in infile
              --config=file   default: [project].xml
              --out=file      default: [project]_eng.xml
              --nocopy        update infile instead of infile.new
              --notime        don't include dump time in xml files
              --wipe          remove unused ids from xml
              --sync          synchronize all locale projects
              --encoding=enc  default: ISO-8859-1
              --verbose       more informative text in xml

Method cache_status: mapping(string:int) cache_status()
Description: Retrieve some statistics about the currently loaded LocaleObjects.

Method call: function(:void)|zerocall(stringproject, stringlang, stringname, void|function(:void)|stringfb)
Description: Returns a localized function If function not found, tries fallback function fb, or fallback language fb instead

Method clean_cache: voidclean_cache()
Description: Remove old LocaleObjects from the cache.
See also: flush_cache()

Method flush_cache: voidflush_cache()
Description: Remove all entries in the LocaleObject cache.

Method get_object: LocaleObject|zeroget_object(stringproject, stringlang)
Returns: Returns the corresponding LocaleObject if it exists and 0 (zero) if it does not.
See also: get_objects()

Method get_objects: mapping(string:object)|zeroget_objects(stringlang)
Description: Reads in and returns a mapping with all the registred projects' LocaleObjects in the language 'lang'

Method list_languages: array(string) list_languages(stringproject)
Description: Returns a list of all registered languages for a specific project.

Method register_project: voidregister_project(stringname, stringpath, void|stringpath_base)
Description: 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.

Method set_default_project_path: voidset_default_project_path(stringpath)
Description: 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.

Method translate: stringtranslate(stringproject, stringlang, string|intid, stringfallback)
Description: Returns a translation for the given id, or the fallback string

Class Locale.DeferredLocale

Description: This class simulates a multi-language "string". The actual language to use is determined as late as possible.

Variable project
Variable get_lang
Variable key
Variable fallback: protectedstring Locale.DeferredLocale.project
protectedfunction(:string) Locale.DeferredLocale.get_lang
protectedstring|int Locale.DeferredLocale.key
protectedstring Locale.DeferredLocale.fallback

Method __create__: protectedlocalvoid__create__(stringproject, function(:string) get_lang, string|intkey, stringfallback)

Method create: Locale.DeferredLocaleLocale.DeferredLocale(stringproject, function(:string) get_lang, string|intkey, stringfallback)

Method get_identifier: arrayget_identifier()
Description: Return the data nessesary to recreate this "string".

Class Locale.LanguageListObject

Variable languages: array(string) Locale.LanguageListObject.languages

Method __create__: protectedlocalvoid__create__(array(string) languages)

Method create: Locale.LanguageListObjectLocale.LanguageListObject(array(string) languages)

Class Locale.LocaleObject

Description: Class for objects representing a Locale.

Method _sprintf: stringsprintf(stringformat, ... Locale.LocaleObjectarg ... )

Method `(): mixed res = Locale.LocaleObject()()
Description: Calls the function f with the arguments args if it exists and is a function. Otherwise returns the value (ie constant function) for f and UNDEFINED if it does not exist.

Method create: Locale.LocaleObjectLocale.LocaleObject(mapping(string|int:string) _bindings, mapping(string:function(:void))|void_functions, mapping(string|int:string)|void_origs)

Method estimate_size: intestimate_size()
Returns: Returns an estimate of the number of bytes that the object uses.

Method is_function: function(:void) is_function(stringf)
Returns: Returns the function for the function name f if it exists and is a function and 0 (zero) otherwise.

Method translate: stringtranslate(string|intkey, string|voidfallback)
Description: Returns the translation for the key key

Module Locale.Charset

Description: This is the old location for the predef::Charset module.
Deprecated: Replaced by predef::Charset.

Inherit Charset: inherit predef::Charset : Charset

Module Locale.Gettext

Description: This module enables access to localization functions from within Pike.
Note: The message conversion functions in this module do not handle Unicode strings. They only provide thin wrappers to gettext(3) etc, which means strings are assumed to be encoded according to the LC_* and LANG variables. See the docs for gettext(3) for details.

Constant LC_ALL

constant Locale.Gettext.LC_ALL

Description

Locale category for all of the locale.

Only supported as an argument to setlocale().

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

Constant LC_CTYPE: constant Locale.Gettext.LC_CTYPE
Description: Locale category for the character classification and conversion routines.

Constant LC_MESSAGES: constant Locale.Gettext.LC_MESSAGES
FIXME: Document this constant.

Constant LC_MONETARY: constant Locale.Gettext.LC_MONETARY
Description: Locale category for localeconv().

Constant LC_NUMERIC: constant Locale.Gettext.LC_NUMERIC
Description: Locale category for the decimal character.

Constant LC_TIME: constant Locale.Gettext.LC_TIME
Description: Locale category for strftime() (currently not accessible from Pike).

Method bindtextdomain

stringbindtextdomain(string|voiddomainname, string|voiddirname)

Description

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.

Returns

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.

See also

textdomain, gettext, setlocale, localeconv

Method dcgettext

stringdcgettext(stringdomain, stringmsg, intcategory)

Description

Return a translated version of msg within the context of the specified domain and current locale for the specified category. Calling dcgettext with category Locale.Gettext.LC_MESSAGES gives the same result as dgettext.

If there is no translation available, msg is returned.

Deprecated

Replaced by gettext.

Obsoleted by gettext() in Pike 7.3.

See also

bindtextdomain, textdomain, gettext, setlocale, localeconv

Method dgettext: stringdgettext(stringdomain, stringmsg)
Description: 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.
Deprecated: Replaced by gettext.; Obsoleted by gettext() in Pike 7.3.
See also: bindtextdomain, textdomain, gettext, setlocale, localeconv

Method gettext

stringgettext(stringmsg)
stringgettext(stringmsg, stringdomain)
stringgettext(stringmsg, stringdomain, intcategory)

Parameter msg

Message to be translated.

Parameter domain

Domain from within the message should be translated. Defaults to the current domain.

Parameter category

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.

See also

bindtextdomain, textdomain, setlocale, localeconv

Method localeconv

mappinglocaleconv()

Description

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

"decimal_point" : string

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

"thousands_sep" : string

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

"int_curr_symbol" : string

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" : string

The local currency symbol applicable to the current locale.

"mon_decimal_point" : string

The decimal point used to format monetary quantities.

"mon_thousands_sep" : string

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

"positive_sign" : string

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

"negative_sign" : string

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

"int_frac_digits" : int

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

"frac_digits" : int

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

"p_cs_precedes" : bool

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

"p_sep_by_space" : bool

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.

"n_cs_precedes" : bool

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

"n_sep_by_space" : bool

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.

"p_sign_posn" : int(0..4)

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" : int

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

See also

bindtextdomain, textdomain, gettext, dgettext, dcgettext, setlocale

Method setlocale

intsetlocale(intcategory, stringlocale)

Description

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

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

The argument category determines which functions are influenced by the new locale are LC_ALL, LC_COLLATE, LC_CTYPE, LC_MONETARY, LC_NUMERIC and LC_TIME.

Returns

Returns 1 if the locale setting successed, 0 for failure

See also

bindtextdomain, textdomain, gettext, dgettext, dcgettext, localeconv

Method textdomain

stringtextdomain(void|stringdomain)

Description

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. It must be non-empty.

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

Returns

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.

See also

bindtextdomain, gettext, setlocale, localeconv

Module Locale.Language

Class Locale.Language.abstract

Description: Abstract language locale class, inherited by all the language locale classes.

Constant days: constant Locale.Language.abstract.days
Description: Array(string) with the days of the week, beginning with Sunday.

Constant english_name: constantstring Locale.Language.abstract.english_name
Description: The name of the language in english.

Constant iso_639_1: optional constantint Locale.Language.abstract.iso_639_1
Description: String with the language code in ISO-639-1 (two character code). Note that all languages does not have a ISO-639-1 code.

Constant iso_639_2: constantint Locale.Language.abstract.iso_639_2
Description: String with the language code in ISO-639-2/T (three character code).

Constant iso_639_2B: constantint Locale.Language.abstract.iso_639_2B
Description: 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).

Constant languages: constant Locale.Language.abstract.languages
Description: Mapping(string:string) that maps an ISO-639-2/T id code to the name of that language.

Constant months: constant Locale.Language.abstract.months
Description: Array(string) with the months of the year, beginning with January.

Constant name: constantstring Locale.Language.abstract.name
Description: The name of the langauge. E.g. "svenska" for Swedish.

Method date

stringdate(inttimestamp, string|voidmode)

Description

Returns the date for posix time timestamp as a textual string.

Parameter mode

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"

Example

> Locale.Language.eng()->date(time());
 Result: "today, 06:36"

Method day: stringday(int(1..7)num)
Description: Returns the name of weekday number num.

Method month: stringmonth(int(1..12)num)
Description: Returns the name of month number num.

Method number: stringnumber(inti)
Description: Returns the number i as a string.

Method ordered: stringordered(inti)
Description: Returns the ordered number i as a string.

Method short_day: stringshort_day(int(1..7)num)
Description: Returns an abbreviated weekday name from the weekday number num.

Method short_month: stringshort_month(int(1..12)num)
Description: Returns an abbreviated month name from the month number num.

Module Locale.Language.cat

Description: Catalan language locale.

Inherit "abstract": inherit "abstract" : "abstract"

Module Locale.Language.ces

Description: Czech language locale by Jan Petrous 16.10.1997, based on Slovenian language module by Iztok Umek.

Inherit "abstract": inherit "abstract" : "abstract"

Module Locale.Language.deu

Description: German language locale by Tvns Böker.

Inherit "abstract": inherit "abstract" : "abstract"

Module Locale.Language.eng

Description: English language locale.

Inherit "abstract": inherit "abstract" : "abstract"

Module Locale.Language.fin

Description: Finnish language locale created by Janne Edelman, Turku Unix Users Group ry, Turku, Finland

Inherit "abstract": inherit "abstract" : "abstract"

Module Locale.Language.fra

Description: French language locale by Patrick Kremer.

Inherit "abstract": inherit "abstract" : "abstract"

Module Locale.Language.hrv

Description: Croatian language locale by Klara Makovac 1997/07/02

Inherit "abstract": inherit "abstract" : "abstract"

Module Locale.Language.hun

Description: Hungarian language locale by Zsolt Varga.

Inherit "abstract": inherit "abstract" : "abstract"

Module Locale.Language.ita

Description: Italian language locale by Francesco Chemolli

Inherit "abstract": inherit "abstract" : "abstract"

Module Locale.Language.jpn

Description: Japanese language locale.

Inherit "abstract": inherit "abstract" : "abstract"

Module Locale.Language.mri

Description: Maaori (New Zealand) language locale by Jason Rumney

Inherit "abstract": inherit "abstract" : "abstract"

Module Locale.Language.nld

Description: Dutch language locale by Stephen R. van den Berg

Inherit "abstract": inherit "abstract" : "abstract"

Module Locale.Language.nor

Description: Norwegian language locale

Inherit "abstract": inherit "abstract" : "abstract"

Module Locale.Language.pol

Description: Polish language locale by Piotr Klaban <makler@man.torun.pl>.

Inherit "abstract": inherit "abstract" : "abstract"

Module Locale.Language.por

Description: Portuguese language locale

Inherit "abstract": inherit "abstract" : "abstract"

Module Locale.Language.rus

Description: Russian language locale

Inherit "abstract": inherit "abstract" : "abstract"

Module Locale.Language.slv

Description: Slovenian language locale by Iztok Umek 7. 8. 1997

Inherit "abstract": inherit "abstract" : "abstract"

Module Locale.Language.spa

Description: Spanish language locale

Inherit "abstract": inherit "abstract" : "abstract"

Module Locale.Language.srp

Description: Serbian language locale by Goran Opacic 1996/12/11

Inherit "abstract": inherit "abstract" : "abstract"

Module Locale.Language.swe

Description: Swedish language locale

Inherit "abstract": inherit "abstract" : "abstract"

Module MIME

Description

RFC 1521, 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 RFC 0822, MIME declares that a message should consist of two entities, the headers and the body. In addition, the following properties are given to these two entities:

Headers

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.

Body

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.

Inherit ___MIME: inherit ___MIME : ___MIME

Constant TOKENIZE_KEEP_ESCAPES: constant MIME.TOKENIZE_KEEP_ESCAPES
Description: Don't unquote backslash-sequences in quoted strings during tokenizing. This is used for bug-compatibility with Microsoft...
See also: tokenize(), tokenize_labled()

Method decode

string|StringRangedecode(string|StringRangedata, void|stringencoding)

Description

Extract raw data from an encoded string suitable for transport between systems.

The encoding can be any of

"7bit"

"8bit"

"base64"

"binary"

"quoted-printable"

"x-uue"

"x-uuencode"

The encoding string is not case sensitive.

See also

MIME.encode()

Method decode_base32: stringdecode_base32(stringencoded_data)
Description: This function decodes data encoded using the base32 transfer encoding.
See also: MIME.encode_base32(), MIME.decode()

Method decode_base32hex: stringdecode_base32hex(stringencoded_data)
Description: Decode strings according to RFC 4648 base32hex encoding.
See also: MIME.decode_base32

Method decode_base64: stringdecode_base64(stringencoded_data)
Description: This function decodes data encoded using the base64 transfer encoding.
See also: MIME.encode_base64(), MIME.decode()

Method decode_base64url: stringdecode_base64url(stringencoded_data)
Description: Decode strings according to RFC 4648 base64url encoding.
See also: MIME.decode_base64

Method decode_crypt64

string(8bit)decode_crypt64(string(7bit)encoded_data)

Description

This function decodes data encoded using the crypt64 encoding.

This is an ad hoc encoding similar to base64 that several password hashing algorithms use for entries in the password database.

Note

This is NOT a MIME-compliant encoding, and MUST NOT be used as such.

See also

MIME.encode_crypt64()

Method decode_headerfield_params: array(ADT.OrderedMapping(< string, string >)) decode_headerfield_params(strings)
Description: Decodes the given string as a key-value parameter cascade according to e.g. RFC 7239 section 4.
Note: This function will decode all conforming inputs, but it will also be forgiving when presented with non-conforming inputs.
See also: encode_headerfield_params

Method decode_qp: stringdecode_qp(stringencoded_data)
Description: This function decodes data encoded using the quoted-printable (a.k.a. quoted-unreadable) transfer encoding.
See also: MIME.encode_qp(), MIME.decode()

Method decode_uue: stringdecode_uue(stringencoded_data)
Description: This function decodes data encoded using the x-uue transfer encoding. It can also be used to decode generic UUEncoded files.
See also: MIME.encode_uue(), MIME.decode()

Method decode_word: array(string) decode_word(stringword)
Description: Extracts the textual content and character set from an encoded word as specified by RFC 1522/RFC 2047. 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: Note that this function can only be applied to individual encoded words.
See also: MIME.encode_word()

Method decode_words_text: array(array(string)) decode_words_text(stringtxt)
Description: 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().
See also: MIME.decode_words_tokenizedMIME.decode_words_text_remapped

Method decode_words_text_remapped: stringdecode_words_text_remapped(stringtxt)
Description: 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 RFC 1522 escapes, and with all characters in UNICODE encoding.
See also: MIME.decode_words_tokenized_remapped

Method decode_words_tokenized: array(array(string)|int) decode_words_tokenized(stringphrase, int|voidflags)
Description: 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.
See also: MIME.decode_words_tokenized_labledMIME.decode_words_tokenized_remappedMIME.decode_words_text

Method decode_words_tokenized_labled

array(array(string|int|array(array(string)))) decode_words_tokenized_labled(stringphrase, int|voidflags)

Description

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

See also

MIME.decode_words_tokenized_labled_remapped

Method decode_words_tokenized_labled_remapped: array(array(string|int)) decode_words_tokenized_labled_remapped(stringphrase, int|voidflags)
Description: 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 RFC 1522 escapes, and with all characters in UNICODE encoding.

Method decode_words_tokenized_remapped: array(string|int) decode_words_tokenized_remapped(stringphrase, int|voidflags)
Description: 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 RFC 1522 escapes, and with all characters in UNICODE encoding.
See also: MIME.decode_words_tokenized_labled_remappedMIME.decode_words_text_remapped

Method encode

stringencode(stringdata, void|stringencoding, void|stringfilename, void|intno_linebreaks)

Description

Encode raw data into something suitable for transport to other systems.

The encoding can be any of

"7bit"

"8bit"

"base64"

"binary"

"quoted-printable"

"x-uue"

"x-uuencode"

The encoding string is not case sensitive. For the x-uue encoding, an optional filename string may be supplied.

If a nonzero value is passed as no_linebreaks, the result string will not contain any linebreaks (base64 and quoted-printable only).

See also

MIME.decode()

Method encode_base32

stringencode_base32(stringdata, void|intno_linebreaks, void|intno_pad)

Description

Encode strings according to RFC 4648 base32 encoding.

If a nonzero value is passed as no_linebreaks, the result string will not contain any linebreaks.

See also

MIME.decode_base32(), MIME.encode()

Method encode_base32hex

stringencode_base32hex(stringdata, void|intno_linebreaks, void|intno_pad)

Description

Encode strings according to RFC 4648 base32hex encoding.

If a nonzero value is passed as no_linebreaks, the result string will not contain any linebreaks.

See also

MIME.encode_base32hex

Method encode_base64

stringencode_base64(stringdata, void|intno_linebreaks, void|intno_pad)

Description

This function encodes data using the base64 transfer encoding.

If a nonzero value is passed as no_linebreaks, the result string will not contain any linebreaks.

See also

MIME.decode_base64(), MIME.encode()

Method encode_base64url: stringencode_base64url(stringdata, void|intno_linebreaks, void|intno_pad)
Description: Encode strings according to RFC 4648 base64url encoding. No padding is performed and no_linebreaks defaults to true.
See also: MIME.encode_base64

Method encode_crypt64

stringencode_crypt64(string(8bit)data)

Description

This function encodes data using the crypt64 encoding.

This is an ad hoc encoding similar to base64 that several password hashing algorithms use for entries in the password database.

Note

This is NOT a MIME-compliant encoding, and MUST NOT be used as such.

See also

MIME.decode_crypt64()

Method encode_headerfield_params: stringencode_headerfield_params(array(mapping(string:string)|ADT.OrderedMapping(< string, string >)) params)
Description: Encodes the given key-value parameters as a string according to e.g. RFC 7239 section 4.
See also: decode_headerfield_params

Method encode_qp

stringencode_qp(stringdata, void|intno_linebreaks)

Description

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

If a nonzero value is passed as no_linebreaks, the result string will not contain any linebreaks.

Note

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

See also

MIME.decode_qp(), MIME.encode()

Method encode_uue

string(7bit)encode_uue(string(8bit)encoded_data, void|string(7bit)filename)

Description

This function encodes data using the x-uue transfer encoding.

The optional argument filename specifies an advisory filename to include in the encoded data, for extraction purposes.

This function can also be used to produce generic UUEncoded files.

See also

MIME.decode_uue(), MIME.encode()

Method encode_word

stringencode_word(string|array(string|zero) word, string|zeroencoding)

Description

Create an encoded word as specified in RFC 1522 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.

See also

MIME.decode_word()

Method encode_words_quoted: stringencode_words_quoted(array(array(string)|int) phrase, stringencoding)
Description: 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().
Parameter encoding: Either "base64" or "quoted-printable" (or either "b" or "q" for short).
See also: MIME.encode_words_quoted_remapped()MIME.encode_words_quoted_labled()

Method encode_words_quoted_labled: stringencode_words_quoted_labled(array(array(string|int|array(string|array(string)))) phrase, stringencoding)
Description: 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.
Parameter encoding: Either "base64" or "quoted-printable" (or either "b" or "q" for short).
See also: MIME.encode_words_quoted()MIME.encode_words_quoted_labled_remapped()

Method encode_words_quoted_labled_remapped: stringencode_words_quoted_labled_remapped(array(array(string|int)) phrase, stringencoding, string|function(string:string) charset, string|voidreplacement, function(string:string)|voidrepcb)
Description: The inverse of decode_words_tokenized_labled_remapped(), this function accepts an array equivalent to the argument of quote_labled(), but also performs on demand word encoding in the same way as encode_words_text_remapped().

Method encode_words_quoted_remapped: stringencode_words_quoted_remapped(array(string|int) phrase, stringencoding, string|function(string:string) charset, string|voidreplacement, function(string:string)|voidrepcb)
Description: The inverse of decode_words_tokenized_remapped(), this functions accepts an array equivalent to the argument of quote(), but also performs on demand word encoding in the same way as encode_words_text_remapped().
See also: MIME.encode_words_text_remapped()MIME.encode_words_quoted_labled_remapped()

Method encode_words_text: stringencode_words_text(array(string|array(string)) phrase, stringencoding)
Description: 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.
Parameter encoding: Either "base64" or "quoted-printable" (or either "b" or "q" for short).
See also: MIME.encode_words_text_remapped

Method encode_words_text_remapped: stringencode_words_text_remapped(stringtext, stringencoding, string|function(string:string) charset, string|voidreplacement, function(string:string)|voidrepcb)
Description: This is the reverse of MIME.decode_words_text_remapped(). A single UNICODE string is provided, which is separated into fragments and transcoded to selected character sets by this function as needed.
Parameter encoding: Either "base64" or "quoted-printable" (or either "b" or "q" for short).
Parameter charset: Either the name of a character set to use, or a function returning a character set to use given a text fragment as input.
Parameter replacement: The replacement argument to use when calling Charset.encoder
Parameter repcb: The repcb argument to use when calling Charset.encoder
See also: MIME.encode_words_tokenized_remapped

Method ext_to_media_type: stringext_to_media_type(stringextension)
Description: 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.

Method generate_boundary

stringgenerate_boundary()

Description

This function will create a string that can be used as a separator string for multipart messages. If a boundary prefix has been set using MIME.set_boundary_prefix(), the generated string will be prefixed with the boundary prefix.

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.

See also

MIME.set_boundary_prefix()

Method get_boundary_prefix: string(8bit)get_boundary_prefix()
Description: Returns the boundary_prefix set via set_boundary_prefix().
See also: MIME.set_boundary_prefix(), MIME.Message.setboundary()

Method guess_subtype

string|zeroguess_subtype(stringtype)

Description

Provide a reasonable default for the subtype field.

Some pre-RFC 1521 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"`

Method parse_headers

array(mapping(string:string)|string) parse_headers(stringmessage)
array(mapping(string:array(string))|string) parse_headers(stringmessage, int(1)use_multiple)

Description

This is a low level function that will separate the headers from the body of an encoded message. It will also translate the headers into a mapping. It will however not try to analyze the meaning of any particular header. This 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 occur multiple times will have their contents NUL separated, unless use_multiple has been specified, in which case the contents will be arrays.

Note

Some headers (eg Subject) may include RFC 1522/RFC 2047 encoded words. To decode these, see decode_words_text and decode_words_tokenized and their friends.

Method quote

stringquote(array(string|int) lexical_elements)

Description

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.

Note

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

See also

MIME.tokenize()

Method quote_labled: stringquote_labled(array(array(string|int)) tokens)
Description: This function performs the reverse operation of tokenize_labled().
See also: MIME.quote(), MIME.tokenize_labled()

Method reconstruct_partial

int|objectreconstruct_partial(array(object) collection)

Description

This function will attempt to reassemble a fragmented message from its parts.

The array collection should contain MIME.Message objects forming a complete set of parts for a single fragmented message. The order of the messages in 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

Note that the returned message may in turn be a part of another, larger, fragmented message.

See also

MIME.Message->is_partial()

Method set_boundary_prefix: voidset_boundary_prefix(string(8bit)boundary_prefix)
Description: Set a message boundary prefix. The MIME.generate_boundary() will use this prefix when creating a boundary string.
Throws: An error is thrown if boundary_prefix doesn't adhere to RFC 1521.
See also: MIME.generate_boundary(), MIME.get_boundary_prefix()
Parameter boundary_prefix: This must adhere to RFC 1521 and can not be longer than 56 characters.

Method tokenize

array(string|int) tokenize(stringheader, int|voidflags)

Description

A structured header field, as specified by RFC 0822, is constructed from a sequence of lexical elements.

Parameter header

The header value to parse.

Parameter flags

An optional set of flags. Currently only one flag is defined:

TOKENIZE_KEEP_ESCAPES

Keep backslash-escapes in quoted-strings.

The lexical elements parsed 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.

Note

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

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

See also

MIME.quote(), tokenize_labled(), decode_words_tokenized_remapped().

Method tokenize_labled

array(array(string|int)) tokenize_labled(stringheader, int|voidflags)

Description

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.

Parameter header

The header value to parse.

Parameter flags

An optional set of flags. Currently only one flag is defined:

TOKENIZE_KEEP_ESCAPES

Keep backslash-escapes in quoted-strings.

The following labels exist:

`"encoded-word"`	Word encoded according to =?...
`"special"`	Special character.
`"word"`	Word.
`"domain-literal"`	Domain literal.
`"comment"`	Comment.

See also

MIME.quote(), tokenize(), decode_words_tokenized_labled_remapped()

Class MIME.Message

Description: This class is used to hold a decoded MIME message.

Variable body_parts: array(object) MIME.Message.body_parts
Description: If the message is of type multipart, this is an array containing one Message object for each part of the message. If the message is not a multipart, this field is 0 (zero).
See also: type, boundary

Variable boundary: string MIME.Message.boundary
Description: For multipart messages, this Content-Type parameter gives a delimiter string for separating the individual messages. As multiparts are handled internally by the module, you should not need to access this field.
See also: setboundary()

Variable charset

string MIME.Message.charset

Description

One of the possible parameters of the Content-Type header is the charset attribute. It determines the character encoding used in bodies of type text.

If there is no Content-Type header, the value of this field is "us-ascii".

See also

type

Variable data

string MIME.Message.data

Description

This variable contains the raw data of the message body entity.

The type and subtype attributes indicate how this data should be interpreted.

Note

In Pike 7.6 and earlier you had to use getdata() and setdata() to access this value.

See also

getdata(), setdata()

Variable disp_params: mapping(string:string) MIME.Message.disp_params
Description: A mapping containing all the additional parameters to the Content-Disposition header.
See also: setdisp_param(), get_filename()

Variable disposition

string MIME.Message.disposition

Description

The first part of the Content-Disposition header, hinting on how this part of a multipart message should be presented in an interactive application.

If there is no Content-Disposition header, this field is 0.

Variable headers

mapping(string:string) MIME.Message.headers

Description

This mapping contains all the headers of the message.

The key is the header name (in lower case) and the value is the header value.

Although the mapping contains all headers, some particular headers get special treatment by the module and should not be accessed through this mapping. These fields are currently:

"content-type"

"content-disposition"

"content-length"

"content-transfer-encoding"

The contents of these fields can be accessed and/or modified through a set of variables and methods available for this purpose.

See also

type, subtype, charset, boundary, transfer_encoding, params, disposition, disp_params, setencoding(), setparam(), setdisp_param(), setcharset(), setboundary()

Note

Some headers (eg Subject) may include RFC 1522/RFC 2047 encoded words. To decode these, see decode_words_text and decode_words_tokenized and their friends.

Variable params

mapping(string:string) MIME.Message.params

Description

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

Some of these parameters have fields of their own, which should be accessed instead of this mapping wherever applicable.

See also

charset, boundary, setparam()

Variable subtype

string MIME.Message.subtype

Description

The Content-Type header contains a type, a subtype, and optionally some parameters. This field contains the subtype attribute extracted from the header.

If there is no Content-Type header, the value of this field is "plain".

See also

type, params

Variable transfer_encoding

string MIME.Message.transfer_encoding

Description

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.

See also

setencoding()

Variable type

string MIME.Message.type

Description

The Content-Type header contains a type, a subtype, and optionally some parameters. This field contains the type attribute extracted from the header.

If there is no Content-Type header, the value of this field is "text".

See also

subtype, params

Method cast

(string)MIME.Message()

Description

Casting the message object to a string will yield a byte stream suitable for transmitting the message over protocols such as ESMTP and NNTP.

The body will be encoded using the current transfer encoding, and subparts of a multipart will be collected recursively. If the message is a multipart and no boundary string has been set, one will be generated using generate_boundary().

See also

create()

Method create

MIME.MessageMIME.Message()
MIME.MessageMIME.Message(stringmessage)
MIME.MessageMIME.Message(stringmessage, mapping(string:string|array(string)) headers, array(object)|voidparts)
MIME.MessageMIME.Message(stringmessage, mapping(string:string|array(string)) headers, array(object)|voidparts, boolguess)

Description

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.

See also

cast()

Method get_filename

stringget_filename()

Description

This method tries to find a suitable filename should you want to save the body data to disk.

It will examine the filename attribute of the Content-Disposition header, and failing that the name attribute of the Content-Type header. If neither attribute is set, the method returns 0.

Note

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

Method getdata

stringgetdata()

Description

This method returns the raw data of the message body entity.

The type and subtype attributes indicate how this data should be interpreted.

See also

setdata(), getencoded(), data

Method getencoded

stringgetencoded()

Description

This method returns the data of the message body entity, encoded using the current transfer encoding.

You should never have to call this function.

See also

getdata()

Method is_partial

array(string|int)|zerois_partial()

Description

If this message is a part of a fragmented message (i.e. has a Content-Type of message/partial), an array with three elements is returned.

The first element is an identifier string. This string should be used to group this message with the other fragments of the message (which will have the same id string).

The second element is the sequence number of this fragment. The first part will have number 1, the next number 2 etc.

The third element of the array is either the total number of fragments that the original message has been split into, or 0 of this information is not available.

If this method is called in a message that is not a part of a fragmented message, it will return 0.

See also

MIME.reconstruct_partial()

Method parse_param: protectedvoidparse_param(mapping(string:string) params, array(string|int) entry, stringheader, int|voidguess, array(string|int)|voidentry2)
Description: Parse a Content-Type or Content-Disposition parameter.
Parameter params: Mapping to add parameters to.
Parameter entry: Array of tokens containing a parameter declaration.
Parameter header: Name of the header from which entry originated. This is only used to report errors.
Parameter guess: Make a best-effort attempt to parse broken entries.
Parameter entry2: Same as entry, but tokenized with MIME.TOKENIZE_KEEP_ESCAPES.
See also: create()

Method setboundary

voidsetboundary(stringboundary)

Description

Sets the boundary parameter of the Content-Type header.

This is equivalent of calling setparam("boundary", boundary).

See also

setparam()

Method setcharset

voidsetcharset(stringcharset)

Description

Sets the charset parameter of the Content-Type header.

This is equivalent of calling setparam("charset", charset).

See also

setparam()

Method setdata

voidsetdata(stringdata)

Description

Replaces the body entity of the data with a new piece of raw data.

The new data should comply to the format indicated by the type and subtype attributes.

Note

Do not use this method unless you know what you are doing.

See also

getdata(), setencoded, data

Method setdisp_param

voidsetdisp_param(stringparam, stringvalue)

Description

Set or modify the named parameter of the Content-Disposition header.

A common parameters is e.g. filename.

Note

It is not allowed to modify the Content-Disposition header directly, please use this function instead.

See also

setparam(), get_filename()

Method setencoding

voidsetencoding(stringencoding)

Description

Select a new transfer encoding for this message.

The Content-Transfer-Encoding header will be modified accordingly, and subsequent calls to getencoded will produce data encoded using the new encoding.

See MIME.encode() for a list of valid encodings.

See also

getencoded(), MIME.encode()

Method setparam

voidsetparam(stringparam, stringvalue)

Description

Set or modify the named parameter of the Content-Type header.

Common parameters include charset for text messages, and boundary for multipart messages.

Note

It is not allowed to modify the Content-Type header directly, please use this function instead.

See also

setcharset(), setboundary(), setdisp_param()

Class MIME.StringRange

Description

Class representing a substring of a larger string.

This class is used to reduce the number of string copies during parsing of MIME.Messages.

Module MIME.ext_to_media_type

Module MPI

Method Finalize: voidFinalize()
Description: Cleans up the MPI stack. Will be called automatically upon termination of the Pike program, but can be called explicitly when it is required that some of the parallel processes continue running and some terminate.
See also: Init(), MPI_Finalize(3)

Method Init

voidInit()

Description

Initializes MPI. MPI in Pike will auto-initialize once the first MPI-operation is called. You can call this function to initialize the parallel MPI at a specific time, since initialization is a collective operation and will block the process until all member processes of the parallel program are present.

Example

int main() {
	MPI.Init();
	write("I am process %d of %d.\n", MPI.world->rank,
	      MPI.world->size);
	MPI.Finalize();
	return 0;
}

See also

Finalize(), MPI_Init(3)

Method Op_create

OpOp_create(function(object, object:void) ufun, intcommute)

Description

Creates a user-defined MPI operation.

Parameter ufun

The function that implements the MPI.Op to be created.

Parameter commute

Set to 1 if the operation commutes.

Example

void my_add_fun(object invec, object outvec) {
	for (int i = 0; i < sizeof(outvec); i++) {
	outvec[i] += invec[i];
}
int main() {
	MPI.Op myadd;
	MPI.IntArray ia = MPI.IntArray(10), results;
	MPI.Init();
	myadd = MPI.Op_create(my_add_fun, 1);
	for (int i = 0; i < sizeof(ia); i++)
		ia[i] = random(1000);
	if (!MPI.world->rank) results = MPI.IntArray(sizeof(ia));
	MPI.world->Reduce(ia, results, 0);
	if (!MPI.world->rank)
		for (int i; i < sizeof(results); i++)
			write("%02d: %d\n", i, results[i]);
	MPI.Finalize();
	return 0;
}

Note

User-defined MPI operations may not call any MPI operations themselves.

See also

MPI.Comm->Reduce(), MPI_Op_create(3)

Class MPI.Comm

Description: A communicator object holds a group of processes both relate messages between those processes as well as perform collective operations, in which all member processes of the communicator are involved.

Method Recv

Description

Receives a message from source with matching tag into buf, storing the sender's rank and the tag used into the optionally given MPI.Status.

Note

The type of the buffer of the receiver site has to match the type of the buffer of the sender. Exception: If a string is sent, it has to be received into a MPI.Pointer.

Example

int main() {
	MPI.IntArray ia = MPI.IntArray(5);
 MPI.Init();
	write("This is rank %d, %d processes total.\n", MPI.world->rank,
	      MPI.world->size);
	if (MPI.world->rank) {
		for (int i = 0; i < sizeof(ia); i++) {
			ia[i] = MPI.world->rank + i;
		}
		MPI.world->Send(ia, 0); // send to rank 0
	} else {
		for (int i = 0; i < MPI.world->size; i++) {
			MPI.world->Recv(ia, i);
			write("Rank %d sent %O to rank 0.\n", i, (array)ia);
		}
	}
	MPI.Finalize();
	return 0;
}

See also

MPI.Comm->Send(), MPI.Comm->Bcast(), MPI.ANY_SOURCE, MPI.ANY_TAG, MPI_Send(3).

Method Send: voidSend(stringbuf, intdest, int|voidtag)
voidSend(MPI.IntArraybuf, intdest, int|voidtag)
voidSend(MPI.FloatArraybuf, intdest, int|voidtag)
voidSend(MPI.SingleArraybuf, intdest, int|voidtag)
voidSend(MPI.Sentinelbuf, intdest, int|voidtag)
Description: Sends the buffer buf to the process with rankdest, marked with tag.
See also: MPI.Comm()->Recv(), MPI.Comm()->Bcast(), MPI_Send(3).

Class MPI.FloatArray

Description: This class implements an array of double precision floats.
Note: Values will be converted to and from the Pike float type, which may introduce rounding errors if the types don't match in your installation.

Method _sizeof: intsizeof(MPI.FloatArrayarg)
Returns: The number of entries in this MPI_FloatArray .

Method _values

array(float) values(MPI.FloatArrayarg)

Returns

A Pike array copy of this array.

Example

array pike_array = values(typed_array);

Method `[]: float res = MPI.FloatArray()[ idx ]
Description: Gives the idxths element of the MPI_FloatArray .

Method `[]=: MPI.FloatArray()[ idx ] = val
Description: Sets the idxths element of the MPI_FloatArray to val.

Method assign: voidassign(MPI_FloatArrayother)
Description: Assigns the first sizeof(other) entries from other to the respective entries in the current array.
Throws: If sizeof(other) > sizeof(this)

Method cast

(int)MPI.FloatArray() (float)MPI.FloatArray() (string)MPI.FloatArray() (array)MPI.FloatArray() (mapping)MPI.FloatArray() (multiset)MPI.FloatArray()

Description

Supports casting (by copy) this MPI_FloatArray to a Pike array.

Example

array pike_array = (array)typed_array;

Method clear: voidclear()
Description: Sets all elements of the MPI_FloatArray to 0.

Method create: MPI.FloatArrayMPI.FloatArray(int(0..)size)

Class MPI.IntArray

Description: This class implements an array of 32 bit integers.

Method _sizeof: intsizeof(MPI.IntArrayarg)
Returns: The number of entries in this MPI_IntArray .

Method _values

array(int) values(MPI.IntArrayarg)

Returns

A Pike array copy of this array.

Example

array pike_array = values(typed_array);

Method `[]: int res = MPI.IntArray()[ idx ]
Description: Gives the idxths element of the MPI_IntArray .

Method `[]=: MPI.IntArray()[ idx ] = val
Description: Sets the idxths element of the MPI_IntArray to val.

Method assign: voidassign(MPI_IntArrayother)
Description: Assigns the first sizeof(other) entries from other to the respective entries in the current array.
Throws: If sizeof(other) > sizeof(this)

Method cast

(int)MPI.IntArray() (float)MPI.IntArray() (string)MPI.IntArray() (array)MPI.IntArray() (mapping)MPI.IntArray() (multiset)MPI.IntArray()

Description

Supports casting (by copy) this MPI_IntArray to a Pike array.

Example

array pike_array = (array)typed_array;

Method clear: voidclear()
Description: Sets all elements of the MPI_IntArray to 0.

Method create: MPI.IntArrayMPI.IntArray(int(0..)size)

Class MPI.Op

Description

Objects of this class represent MPI operations used in collective operations like MPI.Comm()->reduce(). You can use operations predefined by MPI or create your own.

Other than that, Ops are not that useful from Pike.

See also

MPI constants, MPI.Op_create(), MPI.Comm->Reduce().

Class MPI.Pointer

Description

A pointer like class. Because MPI.Comm->Recv() et al do not return "results" but take references/pointers to the target storage, you need to pass a Pointer to MPI.Comm()->recv() in order to receive the string.

Example

int main() {
	string s;
	MPI.Pointer p = MPI.Pointer();
	MPI.Init();
	if (MPI.world->rank())
		MPI.world->Send(ctime(time(1)), 0);
	else
		for (int i = 1; i < MPI.world->size; i++) {
			MPI.world->Recv(p, i);
			write("Rank %03d says now is %s.\n", p());
		}
	MPI.Finalize();
	return 0;
}

Method `(): mixed res = MPI.Pointer()()
mixed res = MPI.Pointer()()
Description: If called with 0 arguments, returns the pointee. If called with argument m, now points to m.

Method create: MPI.PointerMPI.Pointer()
MPI.PointerMPI.Pointer(mixedm)
Description: If m is given, point to m, else point to UNDEFINED.

Class MPI.Sentinel

Description

A Sentinel is a kind of handle that can be given out by objects if they want to allow MPI to send from/receive into the memory areas pointed to by the Sentinel.

Other than that, Sentinels are not that useful from Pike.

See also

Math.FMatrix()->get_sentinel(), Math.FMatrix

Class MPI.SingleArray

Description: This class implements an array of single precision floats.
Note: Values will be converted to and from the Pike float type, which may introduce rounding errors if the types don't match in your installation.

Method _sizeof: intsizeof(MPI.SingleArrayarg)
Returns: The number of entries in this MPI_SingleArray .

Method _values

array(float) values(MPI.SingleArrayarg)

Returns

A Pike array copy of this array.

Example

array pike_array = values(typed_array);

Method `[]: float res = MPI.SingleArray()[ idx ]
Description: Gives the idxths element of the MPI_SingleArray .

Method `[]=: MPI.SingleArray()[ idx ] = val
Description: Sets the idxths element of the MPI_SingleArray to val.

Method assign: voidassign(MPI_SingleArrayother)
Description: Assigns the first sizeof(other) entries from other to the respective entries in the current array.
Throws: If sizeof(other) > sizeof(this)

Method cast

(int)MPI.SingleArray() (float)MPI.SingleArray() (string)MPI.SingleArray() (array)MPI.SingleArray() (mapping)MPI.SingleArray() (multiset)MPI.SingleArray()

Description

Supports casting (by copy) this MPI_SingleArray to a Pike array.

Example

array pike_array = (array)typed_array;

Method clear: voidclear()
Description: Sets all elements of the MPI_SingleArray to 0.

Method create: MPI.SingleArrayMPI.SingleArray(int(0..)size)

Class MPI.Status

Description

Objects of this class can be passed as the last argument to the receive operation of MPI.Comm communicators. After the operation has finished, they will contain information about the sender the message was received from and the tag used for communication.

Therefore, Status objects are particularly helpful in combination with MPI.ANY_SOURCE and MPI.ANY_TAG.

See also

MPI.Comm()->Recv()

Variable SOURCE

int MPI.Status.SOURCE

Description

Contains the source that the message was received from.

Example

int main() {
	if (MPI.world->rank) {
		sleep(random(MPI.world->size)/10.0);
		MPI.world->Send(gethostname(), MPI.world->rank), 0);
	} else {
		MPI.Status status;
		MPI.Pointer p;
		for (int i = 0; i < MPI.world->size; i++) {
			MPI.world->Recv(p, MPI.ANY_SOURCE, 0, status);
			write("Rank %d has hostname %s.\n", status->SOURCE, p());
		}
	}
	return 0;
}

See also

MPI.Comm()->Recv()

Variable TAG: int MPI.Status.TAG
Description: Contains the tag that was used in the MPI.Comm()->Recv operation.
See also: MPI.Comm()->Recv()

Module Math

Inherit "___Math": inherit "___Math" : "___Math"

Constant e: constant Math.e
Description: The constant e (2.7182818284590452354).

Constant inf: constant Math.inf
Description: Floating point infinity.

Constant nan: constant Math.nan
Description: Floating point not-a-number (e.g. inf/inf).
See also: Float.isnan()

Constant pi: constant Math.pi
Description: The constant pi (3.14159265358979323846).

Method choose

int(0..)choose(int(0..)n, int(0..)k)

Description

Calculate the binomial coefficient n choose k.

This is equal to n!/(k!*(n-k)!).

Method convert_angle: int|floatconvert_angle(int|floatangle, stringfrom, stringto)
Description: 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.

Method factor: array(int(-1..)) factor(intx)
Description: Factorize the integer x. The returned list of factors will be sorted biggest to smallest factor.
Note: In Pike versions prior to v8.0, only primes <= 8161 were considered.

Method log10: floatlog10(int|floatx)
Description: The 10-logarithm of x.

Method log2: floatlog2(int|floatx)
Description: The 2-logarithm of x.

Method logn: floatlogn(int|floatn, int|floatx)
Description: The n-logarithm of x.

Class Math.Angle

Description: Represents an angle.

Variable angle: int|float Math.Angle.angle
Description: The actual keeper of the angle value.

Variable type: string Math.Angle.type
Description: The type of the angle value. Is either "deg", "rad", "gon" or "str".

Method __hash: inthash_value(Math.Anglearg)

Method `%: float|int|Angle res = Math.Angle() % _angle
Description: Returns this result of this angle modulo the provided value. If differenced with an angle, a new angle object is returned.

Method `*: float|int|Angle res = Math.Angle() * _angle
Description: Returns the product between this angle and the provided value. If differenced with an angle, a new angle object is returned.

Method `+: float|int|Angle res = Math.Angle() + _angle
Description: Returns the sum of this angle and what it is added with. If added with an angle, a new angle object is returnes.

Method `-: float|int|Angle res = Math.Angle() - _angle
Description: Returns the difference between this angle and the provided value. If differenced with an angle, a new angle object is returned.

Method `/: float|int|Angle res = Math.Angle() / _angle
Description: Returns the fraction between this angle and the provided value. If differenced with an angle, a new angle object is returned.

Method `<: int res = Math.Angle() < _angle
Description: Compares the unnormalized angle of two Angle objects.

Method `==: int res = Math.Angle() == _angle
Description: Compares the unnormalized angle of two Angle objects.

Method `>: int res = Math.Angle() > _angle
Description: Compares the unnormalized angle of two Angle objects.

Method about_face: voidabout_face()
Description: Turns the direction of the angle half a turn. Equal to add(180,"deg").

Method add: Angleadd(float|intangle)
Angleadd(float|intangle, stringtype)
Angleadd(Angleangle)
Description: Adds the provided angle to the current angle. The result is normalized within 360 degrees.

Method cast: (float)Math.Angle() (int)Math.Angle() (string)Math.Angle()
Description: An angle can be casted to float, int and string.

Method clone_me: Angleclone_me()
Description: Returns a copy of the object.

Method cos: floatcos()
Description: Returns the cosinus for the angle.

Method create: Math.AngleMath.Angle()
Math.AngleMath.Angle(int|floatradians)
Math.AngleMath.Angle(int|floatangle, stringtype)
Description: If an angle object is created without arguments it will have the value 0 radians.

Method degree: int|floatdegree()
Description: Returns the number of degrees, including minutes and seconds as decimals.

Method format_dms: stringformat_dms()
Description: Returns degrees, minutes and seconds as a string, e.g. 47°6'36.00".

Method get: int|floatget(stringtype)
Description: Gets the value in the provided type.

Method gon: int|floatgon()
Description: Returns the number of gons.

Method left_face: voidleft_face()
Description: Turns the direction of the angle a quarter of a turn to the left. Equal to add(90,"deg").

Method minute: intminute()
Description: Returns the number of minute.

Method normalize: voidnormalize()
Description: Normalizes the angle to be within one turn.

Method rad: floatrad()
Description: Returns the number of radians.

Method right_face: voidright_face()
Description: Turns the direction of the angle a quarter of a turn to the right. Equal to subtract(90,"deg").

Method second: floatsecond()
Description: Returns the number of seconds.

Method set: Angleset(stringtype, int|float_angle)
Description: Sets the angle value and type to the given value and type.

Method set_degree: Angleset_degree(int|floatdegree)
Description: Sets the angle to the provided degree. Alters the type to degrees. Returns the current object.

Method set_dms: Angleset_dms(intdegrees)
Angleset_dms(intdegrees, intminutes)
Angleset_dms(intdegrees, intminutes, floatseconds)
Description: Set degrees, minues and seconds. Returns the current angle object.

Method set_gon: Angleset_gon(int|floatgon)
Description: Set the angle to the provided gons. Alters the type to gons. Returns the current angle object.

Method set_rad: Angleset_rad(int|floatrad)
Description: Set the angle to the provided radians. Alters the type to radians. Returns the current angle object.

Method set_streck: Angleset_streck(int|floatstr)
Description: Set the angle to the provided strecks. Alters the type to streck. Returns the current angle object.

Method sin: floatsin()
Description: Returns the sinus for the angle.

Method streck: float|intstreck()
Description: Returns the number of strecks.

Method subtract: Anglesubtract(float|intangle)
Anglesubtract(float|intangle, stringtype)
Anglesubtract(Angleangle)
Description: Subtracts the provided angle from the current angle. The result is normalized within 360 degrees.

Method tan: floattan()
Description: Returns the tangen for the angle.

Class Math.FMatrix

Description: Matrix representation with single precision floating point values.

Inherit Matrix: inherit Matrix : Matrix

Class Math.IMatrix

Description: Matrix representation with 32 bit integer values.

Inherit Matrix: inherit Matrix : Matrix

Class Math.LMatrix

Description: Matrix representation with 64 bit integer values.

Inherit Matrix: inherit Matrix : Matrix

Class Math.Matrix

Description: Matrix representation with double precision floating point values.

Method `*
Method ``*
Method mult: Matrix res = Math.Matrix() * with
Matrix res = with * Math.Matrix()
Matrixmult(objectwith)
Description: Matrix multiplication.

Method `+
Method ``+
Method add: Matrix res = Math.Matrix() + with
Matrix res = with + Math.Matrix()
Matrixadd(objectwith)
Description: Add this matrix to another matrix. A new matrix is returned. The matrices must have the same size.

Method `-
Method ``-
Method sub: Matrix res = Math.Matrix() - x
Matrix res = Math.Matrix() - with
Matrix res = with - Math.Matrix()
Matrixsub(objectwith)
Description: Subtracts this matrix from another. A new matrix is returned. -m is equal to -1*m.

Method cast: (array(array(float)))Math.Matrix()
(array(array(float)))Math.Matrix()
Description: It is possible to cast the matrix to an array and get back a double array of floats with the matrix values.
See also: vect

Method convolve: Matrixconvolve(objectwith)
Description: Convolve called matrix with the argument.

Method create: Math.MatrixMath.Matrix(array(array(int|float)) matrix_2d)
Math.MatrixMath.Matrix(array(int|float) matrix_1d)
Description: Initializes the matrix as a 1D or 2D matrix, e.g. Math.Matrix( ({({1,2}),({3,4})}) ).

Method create: Math.MatrixMath.Matrix(intn, intm)
Math.MatrixMath.Matrix(intn, intm, stringtype)
Math.MatrixMath.Matrix(intn, intm, float|intinit)
Description: 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.

Method create: Math.MatrixMath.Matrix(stringtype, intsize)
Description: When type is "identity" the matrix is initializes as a square identity matrix.

Method create: Math.MatrixMath.Matrix(stringtype, intsize, floatrads, Matrixaxis)
Math.MatrixMath.Matrix(stringtype, intsize, floatrads, floatx, floaty, floatz)
Description: When type is "rotate" the matrix is initialized as a rotation matrix.

Method cross: Matrixcross(objectwith)
Description: Matrix cross-multiplication.

Method dot_product: floatdot_product(objectwith)
Description: Matrix dot product.

Method max
Method min: Matrixmax()
Matrixmin()
Description: Produces the maximum or minimum value of all the elements in the matrix.

Method norm
Method norm2
Method normv

floatnorm()
floatnorm2()
Matrixnormv()

Description

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

This equals |A| or sqrt( A₀² + A₁² + ... + A_n² ).

It is only usable with 1xn or nx1 matrices.

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

Method sum: Matrixsum()
Description: Produces the sum of all the elements in the matrix.

Method transpose: Matrixtranspose()
Description: Returns the transpose of the matrix as a new object.

Method vect: arrayvect()
Description: Return all the elements of the matrix as an array of numbers

Method xsize: intxsize()
Description: Returns the width of the matrix.

Method ysize: intysize()
Description: Returns the height of the matrix.

Class Math.SMatrix

Description: Matrix representation with 16 bit integer values.

Inherit Matrix: inherit Matrix : Matrix

Module Math.Transforms

Class Math.Transforms.FFT

Method create: Math.Transforms.FFTMath.Transforms.FFT(void|intn, void|boolexact)
Description: Creates a new transform object. If n is specified, a plan is created for transformations of n-size arrays.
Parameter n: 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.
Parameter exact: 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.

Method rFFT: array(array(float)) rFFT(array(int|float) real_input)
Description: 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.
Parameter real_input: The array of floats and/or ints to transform.
Note: rIFFT(rFFT()) returns the input array scaled by n=sizeof(input array). This is due to the nature of the DFT algorithm.
See also: rIFFT()

Method rIFFT

array(float) rIFFT(array(array(float)) input)

Description

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.

Parameter real_input

The array of floats and/or ints to transform.

Note

rIFFT(rFFT()) returns the input array scaled by n=sizeof(input array). This is due to the nature of the DFT algorithm.

See also

rFFT()

Module NetUtils

Description: Various networking-related utility functions.

Constant locality: constant NetUtils.locality
Description: Mapping from NetworkType to an integer between 0 and 10 that describes how local that type of network is.

Variable ANY

string|zero NetUtils.ANY

Description

Returns either 0 or "::" depending on whether or not this computer has IPv6 support.

The intent is to use this when binding addresses, like port->bind(portno,callback,NetUtils.ANY) to get ipv6 support if present.

The reason for the existence of this function is that using "::" on a computer that does not actually have any ipv6 addresses (and thus no support for ipv6), at least on linux, causes the bind call to fail entirely.

Note

Read only

Method broadcast_addresses: mapping(string:array(string)) broadcast_addresses()
Description: Returns a mapping from interface name to the broadcast addresses on that interface.

Method cidr_to_netmask

array(int)|zerocidr_to_netmask(string|zerocidr)

Description

Converts a string with an IP address and mask (in CIDR notation) into a binary IP address and bitmask.

Parameter cidr

The CIDR-notation input string.

Returns

An array containing:

Array
`intip`	The binary representation of the IP address.
`intmask`	The bitmask.

Returns 0 if the string could not be parsed.

Method clear_cache: voidclear_cache()
Description: Clear any caches. This might be needed if the network setup on the system changes.

Method connectable_network_types

array(NetworkType) connectable_network_types()

Description

Returns network types in priority order according to RFC 3484.

This function assumes a network category (ipv4 or ipv6) is available if the local host has a configured address (excluding localhost) of that network type.

This function will always list the v6 and non-v6 addresses separately.

Method get_network_type

NetworkTypeget_network_type(int|stringipstr, bool|voidseparate_6)

Description

Determine the network type of a given ip address.

Parameter ipstr

IP address in string or numerical form

Parameter separate_6

Adds a 'v6' to the category for ipv6 addresses (ie, "global" and "globalv6")

Returns

Returns one of:

`"localhost"`	The local computer.
`"local"`	The local network.
`"linklocal"`	An unrouted local network (IPv6).
`"private"`	A private network, such as 10.0.0.0/8 or fc00::/7 that is not also a local network.
`"multicast"`	A multicast address.
`"teredo"`	An address in the teredo or 6to4 IPv6 tunneling systems, respectively.
`"6to4"`
`"global"`	A globally routable address that does not match any other category.

Method has_ipv4: boolhas_ipv4()
Description: Returns true if the local host has a public IPv4 address

Method has_ipv6: boolhas_ipv6()
Description: Returns true if the local host has a public IPv6 address

Method host_to_cidr: stringhost_to_cidr(int|stringip)
Description: Return the CIDR notation for the single host defined by x.
Parameter ip: The host ip in either string or raw form
Returns: either ip/128 or ip/32 depending on the IPV6-ness of the host IP.

Method ip_and_port_of

array(string)|zeroip_and_port_of(RemoteAddressObject|string|int(0)inc, bool|voidlocal_address)

Description

Similar to ip_of. Returns 2-element array containing IP address and port number. Second element will be 0 if no port number can be retrieved.

This function can return 0 if inc is a RemoteAddressObject and query_address throws an error or does not return a string.

Method ip_in_block

boolip_in_block(intnet, intmask, int|stringip)

Description

Checks whether an IP address is in a block.

The net and mask parameters should be as returned from cidr_to_netmask.

Throws an error if the IP address could not be parsed.

Parameter net

The network component of the block.

Parameter mask

The bitmask of the block.

Parameter ip

The IP address to check, in either string or binary representation.

Returns

true if the IP is in the given block, false otherwise.

Method ip_less_global: boolip_less_global(int|stringwhich, int|stringtowhat, bool|voidprefer_v4)
Description: Returns true if which is less globally accessible than towhat.

Method ip_of

stringip_of(RemoteAddressObject|string|int(0)inc, bool|voidlocal_address, string|voiddef)

Description

If the argument is an object with a query_address method, return the IP# part of the string returned by calling that function with local_address as the argument.

This means that for Stdio.File objects the remote address is returned by default, but if local_address is true the local address is returned.

If the argument is a string instead, the part of the string before the first space is returned.

If the argument is 0 the default def value is returned, UNDEFINED unless specified.

If def is supplied, it is used both when query_address() fails or something that is not a file descriptor object or a string is passed as the argument to this function.

Method ip_to_string

string|zeroip_to_string(intip, bool|voidv6_only)

Description

Converts a binary representation of an IP address into the IPv4 or IPv6 string representation.

The reverse of string_to_ip.

Parameter ip

The binary representation of the address.

Parameter v6_only

Always return IPV6 addresses. IPV4 addresses will be formatted as ::FFFF:<ipv4>

Returns

The string representation of the address, or 0 if the IP was invalid.

Method is_ipv6: boolis_ipv6(int|stringip)
Description: Returns true if the IP ip is a IPV6 IP.

Method is_local_host: boolis_local_host(RemoteAddressObject|string|inthost, bool|voidonly_localhost)
Description: Returns true if host points to the local host.
Parameter host: The host to check
Parameter only_localhost: Only check if it is ipv6 or ipv4 localhost, not if it is one of the public IP# of this host.
Returns: true if the given host is the local host, false otherwise

Method is_local_network: stringis_local_network(RemoteAddressObject|int|stringhost)
Description: Returns non-zero if host is on one of the local networks, and if so which interface it is on.

Method local_host: stringlocal_host()
Description: Returns either ::1 or 127.0.0.1 depending on the availability of IPV6.

Method local_interfaces: mapping(string:array(string)) local_interfaces()
Description: Return a mapping from interface to address/netmask (only returns non link-local addresses for ipv6)

Method local_ips: multiset(string) local_ips(bool|voidinclude_localhost)
Description: Return an array with locally configured IP-numbers, excluding the ones configured on the loopback inteface, unless include_localhost is specified.

Method local_ips_raw: multiset(int) local_ips_raw(bool|voidinclude_localhost)
Description: Much like local_ips, but returns the IP:s parsed to the integer raw format.

Method local_networks: IpRangeLookuplocal_networks()
Description: Returns an IpRangeLookup that can be used to find the interface for an IP address.

Method netmask_to_cidr: intnetmask_to_cidr(stringmask)
Description: Returns the CIDR of a given netmask. Only returns the correct value for netmasks with all-zeroes at the end (eg, 255.255.255.128 works, while 255.255.255.3 will give the wrong return value)
See also: http://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing#CIDR_notation

Method normalize_address

string|zeronormalize_address(stringa)

Description

Normalize the IP specified in a. This normalizes IPv6 addresses and converts ::FFFF:<ipv4> and ::<ipv4> to "normal" IPV4 addresses.

Will return 0 if a is not a valid address.

Method port_of

stringport_of(RemoteAddressObject|string|int(0)inc, bool|voidlocal_address, string|voiddef)

Description

Similar to ip_of but instead of IP returns port number.

If the argument is an object with a query_address method, return the port# part of the string returned by calling that function with local_address as the argument.

This means that for Stdio.File objects the remote address is returned by default, but if local_address is true the local address is returned.

If the argument is a string instead, the part of the string after the first space is returned.

If the argument is 0 the default def value is returned, UNDEFINED unless specified.

If def is supplied, it is used both when query_address() fails or something that is not a file descriptor object or a string is passed as the argument to this function.

Method sort_addresses

array(string) sort_addresses(array(string) addresses, array(NetworkType)|voidexclude_types, bool|voidseparate_v6)

Description

Given a list of addresses, sort them according to connectable priority order (RFC 3484).

If exclude_types is specified, addresses that match any of the network types (({"local", "localhost"}) for the local network as an example) in the given array will be exluded from the result.

If separate_v6 is true, exclude_types separates v6 from v4. That is, you can disable "localhost" without also disabling "localhostv6".

The addresses inside each group will be returned in random order.

Method special_networks: IpRangeLookupspecial_networks()
Description: Return an IpRangeLookup instance useful for finding out the address category of a ip. Basically like get_network_type without the "local" category.

Method string_to_ip: intstring_to_ip(stringips)
Description: Converts a string representation of an IPv4 address into the binary representation.
Parameter ips: The string representation of the address. For convenience this function accepts the notation returned from fd->query_adddress() ("ip port")
Returns: The binary representation of the address, or -1 if the string could not be parsed.

Method valid_domain_name: boolvalid_domain_name(stringhostname)
Description: Perform a basic sanity check on hostname based on total and subdomain label length. Does not test for invalid chars.
Parameter hostname: Domain name string to test.
Returns: True if hostname looks like a valid domain name

Enum NetUtils.Method

Constant Unsupported
Constant NT
Constant GenericIFConfig
Constant LinuxIFConfig
Constant LinuxIP: constant NetUtils.Unsupported
constant NetUtils.NT
constant NetUtils.GenericIFConfig
constant NetUtils.LinuxIFConfig
constant NetUtils.LinuxIP

Enum NetUtils.NetworkType

Description: A list of all known network type/classes

Constant LOCALHOST
Constant LOCAL
Constant MULTICAST
Constant GLOBAL
Constant PRIVATE: constant NetUtils.LOCALHOST
constant NetUtils.LOCAL
constant NetUtils.MULTICAST
constant NetUtils.GLOBAL
constant NetUtils.PRIVATE
Description: V4 and in non-v6-separate mode also used for V6

Constant LOCALHOSTV6
Constant LOCALV6
Constant PRIVATEV6
Constant MULTICASTV6
Constant GLOBALV6: constant NetUtils.LOCALHOSTV6
constant NetUtils.LOCALV6
constant NetUtils.PRIVATEV6
constant NetUtils.MULTICASTV6
constant NetUtils.GLOBALV6
Description: V6 only versions

Constant LINKLOCAL: constant NetUtils.LINKLOCAL

Constant TEREDO
Constant V6TO4: constant NetUtils.TEREDO
constant NetUtils.V6TO4
Description: Tunneling reserved addresses

Class NetUtils.IpRangeLookup

Description: Class used for checking an IP against a list of IP ranges and looking up some associated information.

Method create

NetUtils.IpRangeLookupNetUtils.IpRangeLookup(mapping(mixed:array(string)) ranges)

Description

Creates a new IpRangeLookup object and initialises the IP range table. Errors will be thrown if ranges contains invalid data.

Parameter ranges

A mapping from information data to arrays of IP ranges.

Each range can be a single addresses ("192.168.1.1"), a range of addresses ("192.168.1.1-192.168.1.5") or be written in CIDR notation ("192.168.1.0/24").

Method get_ranges: mapping(string:array(Range)) get_ranges()
Description: Return a copy of the internal range to info mapping.

Method lookup: mixedlookup(int|stringipstr)
Description: Looks up an IP address and returns the associated information, if any.
Parameter ipstr: The IP address in string or binary form.
Returns: The information associated with the most-specific IP range matching ipstr.

Method lookup_range: Rangelookup_range(int|stringipstr)
Description: Looks up an IP address and returns the associated Range, if any.
Parameter ipstr: The IP address in string or binary form.
Returns: The matching net-range

Class NetUtils.IpRangeLookup.Range

Description: Represents a single range in a IpRangeLoopup.

Inherit NetMask: inherit NetMask : NetMask

Variable info: mixed NetUtils.IpRangeLookup.Range.info

Class NetUtils.NetMask

Description: Persistent representation of a network + mask.

Variable mask: int NetUtils.NetMask.mask
Description: The network mask

Variable net: int NetUtils.NetMask.net
Description: The network number

Method cast: (int)NetUtils.NetMask() (float)NetUtils.NetMask() (string)NetUtils.NetMask() (array)NetUtils.NetMask() (mapping)NetUtils.NetMask() (multiset)NetUtils.NetMask()
Description: Convert to either a string (back to CIDR notation) or an array (net,mask)

Method create: NetUtils.NetMaskNetUtils.NetMask(stringcidr)
Description: Construct a new NetMask object from the given CIDR.
Parameter cidr: An IP and mask in CIDR notation.

Method ip_in: boolip_in(int|stringip)
Description: Match an IP number against the mask.
Returns: true if the ip is in the network, false otherwise.
Parameter ip: The IP address to check, in either string or binary representation.

Class NetUtils.RemoteAddressObject

Description

Interface for objects that can be sent to ip_of and friends.

This matches at least Stdio.File and Stdio.Port, Stdio.UDP and some other classes.

Module Object

Constant DESTRUCT_EXPLICIT
Constant DESTRUCT_NO_REFS
Constant DESTRUCT_GC
Constant DESTRUCT_CLEANUP: constant Object.DESTRUCT_EXPLICIT
constant Object.DESTRUCT_NO_REFS
constant Object.DESTRUCT_GC
constant Object.DESTRUCT_CLEANUP
Description: Flags passed to lfun::_destruct.
Note: Object.DESTRUCT_EXPLICIT is 0 and Object.DESTRUCT_CLEANUP is 1 for compatibility.

Method secure: objectsecure(objectstr)
Description: Marks the object as secure, which will clear the memory area before freeing the object.
See also: String.secure()

Module PDF

Constant a0_width
Constant a0_height
Constant a1_width
Constant a1_height
Constant a2_width
Constant a2_height
Constant a3_width
Constant a3_height
Constant a4_width
Constant a4_height
Constant a5_width
Constant a5_height
Constant a6_width
Constant a6_height
Constant b5_width
Constant b5_height
Constant letter_width
Constant letter_height
Constant legal_width
Constant legal_height
Constant ledger_width
Constant ledger_height
Constant p11x17_width
Constant p11x17_height: constant PDF.a0_width
constant PDF.a0_height
constant PDF.a1_width
constant PDF.a1_height
constant PDF.a2_width
constant PDF.a2_height
constant PDF.a3_width
constant PDF.a3_height
constant PDF.a4_width
constant PDF.a4_height
constant PDF.a5_width
constant PDF.a5_height
constant PDF.a6_width
constant PDF.a6_height
constant PDF.b5_width
constant PDF.b5_height
constant PDF.letter_width
constant PDF.letter_height
constant PDF.legal_width
constant PDF.legal_height
constant PDF.ledger_width
constant PDF.ledger_height
constant PDF.p11x17_width
constant PDF.p11x17_height

Class PDF.PDFgen

Description: Interface to the pdflib pdf generator. For more information see http://www.pdflib.com

Method add_bookmark: intadd_bookmark(stringtext, intparent, intopen)

Method add_launchlink: objectadd_launchlink(floatllx, floatlly, floaturx, floatury, stringfilename)

Method add_locallink: objectadd_locallink(floatllx, floatlly, floaturx, floatury, intpage, stringdest)

Method add_pdflink: objectadd_pdflink(floatllx, floatlly, floaturx, floatury, stringfilename, intpage, stringdest)

Method add_weblink: objectadd_weblink(floatllx, floatlly, floaturx, floatury, stringurl)

Method arc: objectarc(floatx, floaty, floatr, floatstart, floatend)

Method attach_file: objectattach_file(floatllx, floatlly, floaturx, floatury, stringfilename, stringdescription, stringauthor, stringmimetype, stringicon)

Method begin_page: PDFbegin_page()
PDFbegin_page(floatwidth, floatheight)
Description: note: Defaults to a4, portrait

Method circle: objectcircle(floatx, floaty, floatr)

Method close: PDFclose()

Method close_image: objectclose_image(intimage)

Method concat: objectconcat(floata, floatb, floatc, floatd, floate, floatf)

Method continue_text: PDFcontinue_text(strings)

Method create: PDF.PDFgenPDF.PDFgen()

Method curveto: objectcurveto(floatx1, floaty1, floatx2, floaty2, floatx3, floaty3)

Method end_page: PDFend_page()

Method findfont: intfindfont(stringfontname)
intfindfont(stringfontname, void|stringencoding, void|intembed)

Method get_parameter: stringget_parameter(stringkey)
stringget_parameter(stringkey, floatmodifier)

Method get_value: floatget_value(stringkey)
floatget_value(stringkey, floatmodifier)

Method lineto: objectlineto(floatx, floaty)

Method moveto: objectmoveto(floatx, floaty)

Method open_CCITT: intopen_CCITT(stringfilename, intwidth, intheight, intBitReverse, intK, intBlackIs1)

Method open_file: intopen_file(stringfilename)

Method open_image: intopen_image(stringtype, stringsource, stringdata, intwidth, intheight, intcomponents, intbpc, stringparams)

Method open_image_file: intopen_image_file(stringtype, stringfilename)
intopen_image_file(stringtype, stringfilename, void|stringstringparam, void|intintparam)

Method place_image: objectplace_image(intimage, floatx, floaty, floatscale)

Method rect: objectrect(floatx, floaty, floatwidth, floatheight)

Method rotate: objectrotate(floatphi)

Method scale: objectscale(floatsx, floatsy)

Method set_border_color: objectset_border_color(floatred, floatgreen, floatblue)

Method set_border_dash: objectset_border_dash(floatb, floatw)

Method set_border_style: objectset_border_style(stringstyle, floatwidth)

Method set_info: floatset_info(stringkey, stringinfo)

Method set_parameter: floatset_parameter(stringkey, stringparameter)

Method set_text_pos: objectset_text_pos(floatx, floaty)

Method set_value: floatset_value(stringkey, floatvalue)

Method setdash: objectsetdash(floatb, floatw)

Method setflat: objectsetflat(floatflatness)

Method setfont: PDFsetfont(intn, floatsize)

Method setgray: objectsetgray(floatgray)

Method setgray_fill: objectsetgray_fill(floatgray)

Method setgray_stroke: objectsetgray_stroke(floatgray)

Method setlinecap: objectsetlinecap(intlinecap)

Method setlinejoin: objectsetlinejoin(intlinejoin)

Method setlinewidth: objectsetlinewidth(floatwidth)

Method setmiterlimit: objectsetmiterlimit(floatmiter)

Method setrgbcolor: objectsetrgbcolor(floatred, floatgreen, floatblue)

Method setrgbcolor_fill: objectsetrgbcolor_fill(floatred, floatgreen, floatblue)

Method setrgbcolor_stroke: objectsetrgbcolor_stroke(floatred, floatgreen, floatblue)

Method show: PDFshow(strings)

Method show_boxed: intshow_boxed(stringtext, floatx, floaty, floatwidth, floatheight, stringmode)
intshow_boxed(stringtext, floatx, floaty, floatwidth, floatheight, stringmode, stringfeature)

Method showxy: PDFshowxy(strings, floatx, floaty)

Method skew: objectskew(floatalpha, floatbeta)

Method stringwidth: floatstringwidth(stringtext, intfont, floatsize)

Method translate: objecttranslate(floattx, floatty)

Module Pango

Class Pango.AttrList

Description: A PangoAttrList.

Method copy: Pango.AttrListcopy()
Description: Copy the list.

Method create: Pango.AttrListPango.AttrList()
Description: Create a new empty attribute list.

Class Pango.Context

Description: PangoContext.

Inherit Object: inherit G.Object : Object

Class Pango.FontDescription

Description: Pango Font Description.

Method better_match: intbetter_match(Pango.FontDescriptionnew, Pango.FontDescriptionold)
Description: Determines if the style attributes of new are a closer match than old, or if old is omitted, determines if new is a match at all. Approximate matching is done for weight and style; other attributes must match exactly.

Method copy: Pango.FontDescriptioncopy()
Description: Copy a font description.

Method create: Pango.FontDescriptionPango.FontDescription(voiddesc)
Description: Create a new font description. If desc is present, creates a new font description from a string representation in the form "[FAMILY-LIST] [STYLE-OPTIONS] [SIZE]", where FAMILY-LIST is a comma separated list of families optionally terminated by a comma, STYLE-OPTIONS is a whitespace separated list of words where each word describes one of style, variant, weight, or stretch, and size is a decimal number (size in points). Any one of the options may be absent. If FAMILY-LIST is absent, then the family name will be blank. If STYLE-OPTIONS is missing, then all style options will be set to the default values. If SIZE is missing, the size in the resulting font description will be set to 0.

Method equal: intequal(Pango.FontDescriptiondesc)
Description: Compares two font descriptions for equality.

Method get_family: stringget_family()
Description: Gets the family name.

Method get_size: intget_size()
Description: Gets the size.

Method get_stretch: intget_stretch()
Description: Get the stretch.

Method get_style: intget_style()
Description: Gets the style.

Method get_variant: intget_variant()
Description: Gets the variant.

Method get_weight: intget_weight()
Description: Gets the weight.

Method merge: Pango.FontDescriptionmerge(Pango.FontDescriptiondesc, intreplace)
Description: Merges the fields that are set int desc to the fields in this description. If replace is false, only fields in this description that are not already set are affected. If true, then fields that are already set will be replaced as well.

Method set_family: Pango.FontDescriptionset_family(stringfamily)
Description: Sets the family name. The family name represents a family of related fonts styles, and will resolve to a particular PangoFontFamily.

Method set_size: Pango.FontDescriptionset_size(intsize)
Description: Sets the size in fractional points. This is the size of the font in points, scaled by PANGO_SCALE. (That is, a size value of 10*PANGO_SCALE) is a 10 point font. The conversion factor between points and device units depends on system configuration and the output device. For screen display, a logical DPI of 96 is common, in which case a 10 point font corresponds to a 1o*(96.72) = 13.3 pixel font. Use set_absolute_size() if you need a particular size in device units.

Method set_stretch: Pango.FontDescriptionset_stretch(intstretch)
Description: Sets the stretch. This specifies how narrow or wide the font should be. One of PANGO_STRETCH_CONDENSED, PANGO_STRETCH_EXPANDED, PANGO_STRETCH_EXTRA_CONDENSED, PANGO_STRETCH_EXTRA_EXPANDED, PANGO_STRETCH_NORMAL, PANGO_STRETCH_SEMI_CONDENSED, PANGO_STRETCH_SEMI_EXPANDED, PANGO_STRETCH_ULTRA_CONDENSED and PANGO_STRETCH_ULTRA_EXPANDED.

Method set_style: Pango.FontDescriptionset_style(intstyle)
Description: Sets the style. This describes whether the font is slanted and the manner in which is is slanted. One of PANGO_STYLE_ITALIC, PANGO_STYLE_NORMAL and PANGO_STYLE_OBLIQUE. Most fonts will either have an italic style or an oblique style, but not both, and font matching in Pango will match italic specifications with oblique fonts and vice-versa if an exact match is not found.

Method set_variant: Pango.FontDescriptionset_variant(intvariant)
Description: Sets the variant. One of PANGO_VARIANT_NORMAL and PANGO_VARIANT_SMALL_CAPS.

Method set_weight: Pango.FontDescriptionset_weight(intweight)
Description: Sets the weight. The weight specifies how bold or light the font should be. In addition to the values of PANGO_WEIGHT_BOLD, PANGO_WEIGHT_HEAVY, PANGO_WEIGHT_LIGHT, PANGO_WEIGHT_NORMAL, PANGO_WEIGHT_ULTRABOLD and PANGO_WEIGHT_ULTRALIGHT, other intermediate numeric values are possible.

Method to_filename: stringto_filename()
Description: Creates a filename representation. The filename is identical to the result from calling to_string(), but with underscores instead of characters that are untypical in filenames, and in lower case only.

Method to_string: stringto_string()
Description: Creates a string representation. The family list in the string description will only have a terminating comm if the last word of the list is a valid style option.

Class Pango.Layout

Description: Pango Layout.

Inherit Object: inherit G.Object : Object

Method context_changed: Pango.Layoutcontext_changed()
Description: Forces recomputation of any state in the layout that might depend on the layout's context. This function should be called if you make changes to the context subsequent to creating the layout.

Method copy: Pango.Layoutcopy(Pango.Layoutsrc)
Description: Does a copy of the src.

Method create: Pango.LayoutPango.Layout(voidcontext)
Description: Create a new layout with attributes initialized to default values for a particular Pango.Context

Method get_alignment: intget_alignment()
Description: Gets the alignment.

Method get_auto_dir: intget_auto_dir()
Description: Gets whether to calculate the bidirectional base direction for the layout according to the contents of the layout.

Method get_context: Pango.Contextget_context()
Description: Returns the Pango.Context.

Method get_cursor_pos: arrayget_cursor_pos(intindex)
Description: Given an index within a layout, determines the positions of the strong and weak cursors if the insertion point is at that index. The position of each cursor is stored as a zero-width rectangle. The strong cursor is the location where characters of the directionality equal to the base direction of the layout are inserted. The weak cursor location is the location where characters of the directionality opposite to the base direction of the layout are inserted. Returns: array of mappings, each mapping is the same as index_to_pos().

Method get_indent: intget_indent()
Description: Gets the paragraph indent in pango units. A negative value indicates a hanging indent.

Method get_justify: intget_justify()
Description: Gets whether or not each complete line should be stretched to fill the entire width of the layout.

Method get_line: Pango.LayoutLineget_line(intline)
Description: Retrieves a specific line.

Method get_line_count: intget_line_count()
Description: Retrieves the count of lines.

Method get_single_paragraph_mode: intget_single_paragraph_mode()
Description: Gets the value set by set_single_paragraph_mode().

Method get_size: mappingget_size()
Description: Determines the logical width and height in Pango units.

Method get_spacing: intget_spacing()
Description: Gets the amount of spacing between the lines.

Method get_tabs: Pango.TabArrayget_tabs()
Description: Gets the current W(TabArray) used by this layout. If no W(TabArray) has been set, then the default tabs are in use and 0 is returned. Default tabs are every 8 spaces.

Method get_text: stringget_text()
Description: Gets the text.

Method get_width: intget_width()
Description: Gets the line wrap width.

Method get_wrap: intget_wrap()
Description: Gets the wrap mode for the layout.

Method index_to_pos

mappingindex_to_pos(intindex)

Description

Converts from an index to the onscreen position corresponding to the grapheme at that index, which is represented as a rectangle. Note that x is always the leading edge of the grapheme and x+width the trailing edge of the grapheme. If the direction of the grapheme is right-to-left, then width will be negative.

Returns: ([ "x": x coordinate, "y": y coordinate, "width": width of the rectangle, "height": height of the rectangle ])

Method move_cursor_visually

mappingmove_cursor_visually(intstrong, intold_index, intold_trailing, intdir)

Description

Computes a new cursor position from an old position and a count of positions to move visually. If count is positive, then the new strong cursor position will be one position to the right of the old cursor position. If count is negative, then the new strong cursor position will be one position to the left of the old cursor position.

In the presence of bidirectional text, the correspondence between logical and visual order will depend on the direction of the current run, and there may be jumps when the cursor is moved off the end of a run.

Motion here is in cursor positions, not in characters, so a single call to move_cursor_visually() may move the cursor over multiple characters when multiple characters combine to form a single grapheme.

Method set_alignment: Pango.Layoutset_alignment(intalignment)
Description: Sets the alignment for the layout (how partial lines are positioned within the horizontal space available.) One of PANGO_ALIGN_CENTER, PANGO_ALIGN_LEFT and PANGO_ALIGN_RIGHT.

Method set_auto_dir

Pango.Layoutset_auto_dir(intauto_dir)

Description

Sets whether to calculate the bidirectional base direction for the layout according to the contents of the layout; when this flag is on (the default), then paragraphs that begin with strong right-to-left characters (Arabic and Hebrew principally), will have right-left-layout, paragraphs with letters from other scripts will have left-to-right layout. Paragraphs with only neutral characters get their direction from the surrounding paragraphs.

When false, the choice between left-to-right and right-to-left layout is done by according to the base direction of the Pango.Context.

Method set_font_description: Pango.Layoutset_font_description(Pango.FontDescriptiondesc)
Description: Sets the default font description for the layout. If no font description is set on the layout, the font descriptions from the layout's context is used.

Method set_indent: Pango.Layoutset_indent(intindent)
Description: Sets the width in pango units to indent each paragraph. A negative value of indent will produce a hanging indent. That is, the first line will have the full width, and subsequent lines will be indented by the absolute value of indent.

Method set_justify: Pango.Layoutset_justify(intjustify)
Description: Sets whether or not each complete line should be stretched to fill the entire width of the layout. This stretching is typically done by adding whitespace, but for some scripts (such as Arabic), the justification is done by extending the characters.

Method set_markup: Pango.Layoutset_markup(stringmarkup, intlength)
Description: Same as set_markup_with_accel(), but the markup text isn't scanned for accelerators.

Method set_markup_with_accel

Pango.Layoutset_markup_with_accel(stringmarkup, intlength, int|voidaccel_marker)

Description

Sets the layout text and attribute from marked-up text. Replaces the current text and attribute list.

If accel_marker is nonzero, the given character will mark the character following it as an accelerator. For example, the accel marker might be an ampersand or underscore. All characters marked as an acclerator will receive a GTK2.PANGO_UNDERLINE_LOW attribute, and the first character so marked will be returned. Two accel_marker characters following each other produce a single literal accel_marker character.

Method set_single_paragraph_mode: Pango.Layoutset_single_paragraph_mode(intsetting)
Description: If setting is true, do not treat newlines and similar characters as paragraph separators; instead, keep all text in a single paragraph, and display a glyph for paragraph separator characters. Used when you want to allow editing of newlines on a single text line.

Method set_spacing: Pango.Layoutset_spacing(intspacing)
Description: Sets the amount of spacing between the lines.

Method set_tabs: Pango.Layoutset_tabs(Pango.TabArraytabs)
Description: Sets the tabs to use, overriding the default tabs (by default, tabs are every 8 spaces). If tabs is omitted, the default tabs are reinstated.

Method set_text: Pango.Layoutset_text(sprintf_formattext, sprintf_args ... fmt)
Description: Sets the text of the layout.

Method set_width: Pango.Layoutset_width(intwidth)
Description: Sets the width to which the lines should be wrapped.

Method set_wrap: Pango.Layoutset_wrap(intwrap)
Description: Sets the wrap mode; the wrap mode only has an effect if a width is set on the layout with set_width(). To turn off wrapping, set the width to -1. One of PANGO_WRAP_CHAR, PANGO_WRAP_WORD and PANGO_WRAP_WORD_CHAR.

Method xy_to_index

mappingxy_to_index(intx, inty)

Description

Converts from x and y position within a layout to the byte index to the character at that logical position. If the y position is not inside the layout, the closest position is chosen (the position will be clamped inside the layout). If the X position is not within the layout, then the start or the end of the line is chosen as describe for x_to_index(). If either the x or y positions were not inside the layout, then returns 0.

Returns: ([ "index": byte index, "trailing": where in grapheme user clicked ]).

Class Pango.LayoutIter

Description: PangoLayoutIter.

Method at_last_line: intat_last_line()
Description: Determines whether this iter is on the last line of the layout.

Method get_baseline: intget_baseline()
Description: Gets the y position of the current line's baseline, in layout coordinates (origin at top left of the entire layout).

Method get_char_extents: mappingget_char_extents()
Description: Gets the extents of the current character, in layout coordinates (origin is the top left of the entire layout).

Method get_cluster_extents: arrayget_cluster_extents()
Description: Gets the extents of the current cluster, in layout coordinates.

Method get_index: intget_index()
Description: Gets the current byte index. Note that iterating forward by char moves in visual order, not logical order, so indexes may not be sequential. Also, the index may be equal to the length of the text in the layout.

Method get_layout_extents: arrayget_layout_extents()
Description: Obtains the extents of the layout.

Method get_line: Pango.LayoutLineget_line()
Description: Gets the current line.

Method get_line_extents: arrayget_line_extents()
Description: Obtains the extents of the current line.

Method get_line_yrange: arrayget_line_yrange()
Description: Divides the vertical space being iterated over between the lines in the layout, and returns the space belonging to the current line. A line's range includes the line's logical extents, plus half of the spacing above and below the line, if Pango.Layout->set_spacing() has been called to set layout spacing. The y positions are in layout coordinates.

Method get_run_extents: arrayget_run_extents()
Description: Gets the extents of the current run in layout coordinates.

Method next_char: intnext_char()
Description: Moves forward to the next character in visual order. If it was already at the end of the layout, returns false.

Method next_cluster: intnext_cluster()
Description: Moves forward to the next cluster in visual order. If it was already at the end of the layout, returns false.

Method next_line: intnext_line()
Description: Moves forward to the start of the next line. If it is already on the last line, returns false.

Method next_run: intnext_run()
Description: Moves forward to the next run in visual order. If it was already at the end of the layout, returns false.

Class Pango.LayoutLine

Description: PangoLayoutLine.

Method get_extents: arrayget_extents()
Description: Computes the logical and ink extents of a layout line.

Method get_pixel_extents: arrayget_pixel_extents()
Description: Computes the logical and ink extents of a layout line, in device units.

Method index_to_x: intindex_to_x(intindex, inttrailing)
Description: Converts an index within a line to an x position.

Method x_to_index: mappingx_to_index(intx_pos)
Description: Converts from x offset to the byte index of the corresponding character within the text of the layout. If x_pos is outside the line, index and trailing will point to the very first or very last position in the line. This determination is based on the resolved direction of the paragraph; for example, if the resolved direction is right-to-left, then an X position to the right of the line (after it) results in 0 being stored in index and trailing. An X position to the left of the line results in index pointing to the (logical) last grapheme in the line and trailing set to the number of characters in that grapheme. The reverse is true for a left-to-right line.

Class Pango.TabArray

Description: A set of tab stops for laying out text that includes tab characters.

Inherit Object: inherit G.Object : Object

Method copy: Pango.TabArraycopy()
Description: Returns a copy.

Method create: Pango.TabArrayPango.TabArray(voidinitial_size, voidposition_in_pixels)
Description: Creates an array of initial_size tab stops. Tab stops are specified in pixel units if positions_in_pixels is true, otherwise in Pango units. All stops are initially at position 0.

Method get_positions_in_pixels: intget_positions_in_pixels()
Description: Returns true if the tab positions are in pixels, false if they are in Pango units.

Method get_size: intget_size()
Description: Gets the number of tab stops.

Method get_tab: mappingget_tab(inttab_index)
Description: Gets the alignment and position of a tab stop.

Method get_tabs: arrayget_tabs()
Description: Gets alignments and locations of all tab stops.

Method resize: Pango.TabArrayresize(intnew_size)
Description: Resizes the array. You must subsequently initialize any tabs that were added as a result of growing the array.

Method set_tab: Pango.TabArrayset_tab(inttab_index, intalignment, intlocation)
Description: Sets the alignment and location of a tab stop. Alignment must always be PANGO_TAB_LEFT.

Module Pike

Constant INDEX_FROM_BEG
Constant INDEX_FROM_END
Constant OPEN_BOUND

local constant Pike.INDEX_FROM_BEG
local constant Pike.INDEX_FROM_END
local constant Pike.OPEN_BOUND

Description

Used with predef::`[..] and lfun::`[..] to specify how the corresponding index maps to an upper or lower range bound:

INDEX_FROM_BEG: The index is relative to the beginning of the string or array (or any other sequence implemented through an object). Sequences typically start at zero.
INDEX_FROM_END: The index is relative to the end of the sequence. In strings and arrays, the last element is at zero, the one before that at one, etc.
OPEN_BOUND: The range is open in the corresponding direction. The index is irrelevant in this case.

Constant WEAK_INDICES
Constant WEAK_VALUES
Constant WEAK: local constant Pike.WEAK_INDICES
local constant Pike.WEAK_VALUES
local constant Pike.WEAK
Description: Flags for use together with set_weak_flag and get_weak_flag. See set_weak_flag for details.

Constant __HAVE_CPP_PREFIX_SUPPORT__: local constant Pike.__HAVE_CPP_PREFIX_SUPPORT__
Description: This constant exists and has the value 1 if cpp supports the prefix feature.
See also: cpp()

Method count_memory

intcount_memory(int|mapping(string:int) options, mixed ... things)

Description

In brief, if you call Pike.count_memory(0,x) you get back the number of bytes x occupies in memory.

The detailed story is a bit longer:

This function calculates the number of bytes that all things occupy. Or put another way, it calculates the number of bytes that would be freed if all those things would lose their references at the same time, i.e. not only the memory in the things themselves, but also in all the things that are directly and indirectly referenced from those things and not from anywhere else.

The memory counted is only that which is directly occupied by the things in question, including any overallocation for mappings, multisets and arrays. Other memory overhead that they give rise to is not counted. This means that if you would count the memory occupied by all the pike accessible things you would get a figure significantly lower than what the OS gives for the pike process.

Also, if you were to actually free the things, you should not expect the size of the pike process to drop the amount of bytes returned by this function. That since Pike often retains the memory to be reused later.

However, what you should expect is that if you actually free the things and then later allocates some more things for which this function returns the same size, there should be essentially no increase in the size of the pike process (some increase might occur due to internal fragmentation and memory pooling, but it should be small in general and over time).

The search for things only referenced from things can handle limited cyclic structures. That is done by doing a "lookahead", i.e. searching through referenced things that apparently have other outside references. You can control how long this lookahead should be through options (see below). If the lookahead is too short to cover the cycles in a structure then a too low value is returned. If the lookahead is made gradually longer then the returned value will eventually become accurate and not increase anymore. If the lookahead is too long then unnecessary time might be spent searching through things that really have external references.

Objects that are known to be part of cyclic structures are encouraged to have an integer constant or variable pike_cycle_depth that specifies the lookahead needed to discover those cycles. When Pike.count_memory visits such objects, it uses that as the lookahead when going through the references emanating from them. Thus, assuming objects adhere to this convention, you should rarely have to specify a lookahead higher than zero to this function.

Note that pike_cycle_depth can also be set to zero to effectively stop the lookahead from continuing through the object. That can be useful to put in objects you know have global references, to speed up the traversal.

Parameter options

If this is an integer, it specifies the maximum lookahead distance. -1 counts only the memory of the given things, without following any references. 0 extends the count to all their referenced things as long as there are no cycles (except if pike_cycle_depth is found in objects - see above). 1 makes it cover cycles of length 1 (e.g. a thing points to itself), 2 handles cycles of length 2 (e.g. where two things point at each other), and so on.

However, the lookahead is by default blocked by programs, i.e. it never follows references emanating from programs. That since programs seldom are part of dynamic data structures, and they also typically contain numerous references to global data which would add a lot of work to the lookahead search.

To control the search in more detail, options can be a mapping instead:

`lookahead : int`	The maximum lookahead distance, as described above. Defaults to 0 if missing.
`block_arrays : int`	When any of these are given with a nonzero value, the corresponding type is blocked when lookahead references are followed. They are unblocked if the flag is given with a zero value. Only programs are blocked by default. These blocks are only active during the lookahead, so blocked things are still recursed and memory counted if they are given as arguments or only got internal references.
`block_mappings : int`
`block_multisets : int`
`block_objects : int`
`block_programs : int`
`block_strings : int`	If positive then strings are always excluded (except any given directly in `things`), if negative they are always included. Otherwise they are counted if they have no other refs, but note that since strings are shared they might get refs from other unrelated parts of the program.
`block_pike_cycle_depth : int`	Do not heed `pike_cycle_depth` values found in objects. This is implicit if the lookahead is negative.
`return_count : int`	Return the number of things that memory was counted for, instead of the byte count. (This is the same number `internal` contains if `collect_stats` is set.)
`collect_internals : int`	If this is nonzero then its value is replaced with an array that contains the things that memory was counted for.
`collect_externals : int`	If set then the value is replaced with an array containing the things that were visited but turned out to have external references (within the limited lookahead).
`collect_direct_externals : int`	If set then the value is replaced with an array containing the things found during the lookahead that (appears to) have direct external references. This list is a subset of the `collect_externals` list. It is useful if you get unexpected global references to your data structure which you want to track down.
`collect_stats : int`	If this is nonzero then the mapping is extended with more elements containing statistics from the search; see below.

When the collect_stats flag is set, the mapping is extended with these elements:

`internal : int`	Number of things that were marked internal and hence memory counted. It includes the things given as arguments.
`cyclic : int`	Number of things that were marked internal only after resolving cycles.
`external : int`	Number of things that were visited through the lookahead but were found to be external.
`visits : int`	Number of times things were visited in total. This figure includes visits to various internal things that aren't visible from the pike level, so it might be larger than what is apparently motivated by the numbers above.
`revisits : int`	Number of times the same things were revisited. This can occur in the lookahead when a thing is encountered through a shorter path than the one it first got visited through. It also occurs in resolved cycles. Like `visits`, this count can include things that aren't visible from pike.
`rounds : int`	Number of search rounds. This is usually 1 or 2. More rounds are necessary only when blocked types turn out to be (acyclic) internal, so that they need to be counted and recursed anyway.
`work_queue_alloc : int`	The number of elements that were allocated to store the work queue which is used to keep track of the things to visit during the lookahead. This is usually bigger than the maximum number of things the queue actually held.
`size : int`	The memory occupied by the internal things. This is the same as the normal return value, but it's put here too for convenience.

Parameter things

One or more things to count memory size for. Only things passed by reference are allowed, except for functions which are forbidden because a meaningful size calculation can't be done for them.

Integers are allowed because they are bignum objects when they become sufficiently large. However, passing an integer that is small enough to fit into the native integer type will return zero.

Returns

Returns the number of bytes occupied by the counted things. If the return_count option is set then the number of things are returned instead.

Note

The result of Pike.count_memory(0,a,b) might be larger than the sum of Pike.count_memory(0,a) and Pike.count_memory(0,b) since a and b together might reference things that aren't referenced from anywhere else.

Note

It's possible that a string that is referenced still isn't counted, because strings are always shared in Pike and the same string may be in use in some unrelated part of the program.

Method gc_parameters

mapping(string:float) gc_parameters(void|mapping(string:mixed) params)

Description

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" : int

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" : float

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

"time_ratio" : float

When more than this fraction of the time is spent in the gc, aim for garbage_ratio_high instead of garbage_ratio_low.

"garbage_ratio_high" : float

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

"min_gc_time_ratio" : float

This puts an upper limit on the gc interval, in addition to the factors above. It is specified as the minimum amount of time spent doing gc, as a factor of the total time. The reason for this limit is that the current amount of garbage can only be measured in a gc run, and if the gc starts to run very seldom due to very little garbage, it might get too slow to react to an increase in garbage generation. Set to 0.0 to turn this limit off.

"average_slowness" : float

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.

"pre_cb" : function(:void)

This function is called when the gc starts.

"post_cb" : function(:void)

This function is called when the mark and sweep pass of the gc is done.

"destruct_cb" : function(object, int, int:void)

This function is called once for each object that is part of a cycle just before the gc will destruct it. The arguments are:

The object to be destructed.

The reason for it being destructed. One of:

`Object.DESTRUCT_CLEANUP`	Destructed during exit.
`Object.DESTRUCT_GC`	Destructed during normal implicit or explicit `gc()`.

The number of references it had.

"done_cb" : function(int:void)

This function is called when the gc is done and about to exit. The argument is the same value as will be returned by gc().

See also

gc, Debug.gc_status

Method get_first_arg_type

type|zeroget_first_arg_type(typefun_type)

Description

Check if a function of the type fun_type may be called with an argument, and return the type of that argument.

Returns

Returns the expected type of the first argument to the function.

Returns 0 (zero) if a function of the type fun_type may not be called with any argument, or if it is not callable.

Method get_return_type

type|zeroget_return_type(typefun_type)
type|zeroget_return_type(typefun_type, mappingstate)

Description

Check what a function of the type fun_type will return if called with no further arguments.

Parameter state

State mapping. This mapping may be used by attribute handlers to store state between different arguments. Note that attribute handlers may alter the contents of the mapping.

Returns

Returns the type of the returned value on success

Returns 0 (zero) on failure.

Method get_runtime_info

mapping(string:int|string) get_runtime_info()

Description

Get information about the Pike runtime.

Returns

Returns a mapping with the following content:

`"bytecode_method" : string`	A string describing the bytecode method used by the Pike interpreter.
`"abi" : int`	The number of bits in the ABI. Usually `32` or `64`.
`"native_byteorder" : int`	The byte order used by the native cpu. Usually `1234` (aka little endian) or `4321` (aka bigendian).
`"int_size" : int`	The number of bits in the native integer type. Usually `32` or `64`.
`"time_size" : int`	The number of bits in the native `time_t` type. This is typically the same value as `"int_size"`.
`"float_size" : int`	The number of bits in the native floating point type. Usually `32` or `64`.
`"auto_bignum" : int(1)`	Integers larger than the native size are now always automatically converted into bignums.
`"rtl_debug" : int(1)`	The runtime has been compiled --with-rtldebug.
`"debug_malloc" : int(1)`	The runtime has been compiled --with-debug-malloc.
`"running_on_valgrind" : int(0..)`	The number of nested valgrinds the runtime is running under.

Method get_type_attributes: array(string) get_type_attributes(typet)
Description: Get the attribute markers for a type.
Returns: Returns an array with the attributes for the type t.
See also: get_return_type(), get_first_arg_type()

Method identify_cycle

array(mixed) identify_cycle(mixedx)

Description

Identify reference cycles in Pike datastructures.

This function is typically used to identify why certain datastructures need the gc to run to be freed.

Parameter x

Value that is believed to be involved in a reference cycle.

Returns

`zero`	Returns `UNDEFINED` if `x` is not member of a reference cycle.
`array(mixed)`	Otherwise returns an array identifying a cycle with `x` as the first element, and where the elements refer to each other in order, and the last element refers to the first.

Method implicit_gc_real_time: intimplicit_gc_real_time(void|intnsec)
Description: Returns the total amount of real time that has been spent in implicit GC runs. The time is normally returned in microseconds, but if the optional argument nsec is nonzero it's returned in nanoseconds.
See also: Debug.gc_status

Method low_check_call

type|zerolow_check_call(typefun_type, typearg_type)
type|zerolow_check_call(typefun_type, typearg_type, intflags)
type|zerolow_check_call(typefun_type, typearg_type, intflags, mappingstate)
type|zerolow_check_call(typefun_type, typearg_type, intflags, mappingstate, mixedval)

Description

Check whether a function of type fun_type may be called with a first argument of type arg_type.

Parameter flags

The following flags are currently defined:

`1`	Strict types. Fail if not all possible values in `arg_type` are valid as the first argument to `fun_type`.
`2`	Last argument. `arg_type` is the last argument to `fun_type`.
`3`	Both strict types and last argument as above.

Parameter state

State mapping. This mapping may be used by attribute handlers to store state between different arguments. Note that attribute handlers may alter the contents of the mapping.

Parameter val

Value of the argument if known.

Returns

Returns a continuation type on success.

Returns 0 (zero) on failure.

Method signal_contextp

boolsignal_contextp()

Description

Returns whether the current thread is running in a signal handler context.

A signal handler context implies that ordinary program flow for the current thread has been interrupted (note that other threads will continue to execute concurrently), and will resume when the handler returns. Note that code that is executing in a signal context may still be interrupted.

Some origins for entering a signal handler context are:

A caught signal triggering a signal handler to be called.
An object implementing lfun::_destruct() running out of references or being destructed by the gc().
An uncaught runtime error (causing MasterObject()->handle_error() to be called).

In a signal handler context some operations are not supported eg locking of Thread.Mutex or waiting on Thread.Condition.

Intended use is to be able to throw errors early in APIs that are not signal context safe, or to be able to detect this and upgrade the call to a normal context (eg via call_out()).

See also

lfun::_destruct(), call_out(), gc(), MasterObject()->handle_error()

Method soft_cast: type|zerosoft_cast(typeto, typefrom)
Description: Return the resulting type from a soft cast of from to to.
Returns: Returns UNDEFINED if the cast is invalid.
Note: The return value for the invalid case may in the future change to __unknown__.

Method switch_lookup: intswitch_lookup(array|mappingswitch_table, mixedval)
Description: Lookup a switch-case.
Parameter switch_table: Lookup table as generated by the compiler.
Parameter val: Value to lookup.
Returns: Returns the entry number (ie >= 0) if val was found in switch_table, and the binary inverse of the next entry number (ie < 0) if it was not found.

Class Pike.Annotation

Description: This class describes the API that the compiler expects for the annotation syntax.
Note: Classes implementing this API typically need to be marked constant.
See also: Annotations

Method end_pass: optionalvoidend_pass(intpass, programprog, CompilerEnvironment.PikeCompilercompiler)
Description: Callback called by the compiler when it is finishing a compilation pass.
Parameter pass: Compilation pass.
Parameter prog: Program being compiled.
Parameter compiler: CompilerEnvironment.PikeCompiler state for the compiler.

Class Pike.BacktraceFrame

Method _is_type: bool res = is_type(Pike.BacktraceFrame())
Description: This object claims to be an array for backward compatibility.

Method _sizeof: int(3..)sizeof(Pike.BacktraceFramearg)

Method _sprintf: stringsprintf(stringformat, ... Pike.BacktraceFramearg ... )

Method `[]: mixed res = Pike.BacktraceFrame()[ index ]
Description: The BacktraceFrame object can be indexed as an array.

Method `[]=: Pike.BacktraceFrame()[ index ] = value

Class Pike.DestructImmediate

Description: An empty class that can be inherited to get the PROGRAM_DESTRUCT_IMMEDIATE flag set.
See also: InhibitDestruct

Class Pike.FakeObject

Description

Used as a place holder in eg backtraces for objects that are unsuitable to have references to in backtraces.

Examples of such objects are instances of Thread.MutexKey, and Nettle.Cipher.State.

See also

backtrace()

Class Pike.InhibitDestruct

Description

This is a class that implements a way to temporarily inhibit destruction by explicit calls of destruct().

This is mostly useful as a mix-in for modules implemented in C or similar.

All symbols in the class are either protected or private in order to affect users minimally.

See also

DestructImmediate

Method _destruct: bool_destruct(int|voidreason)
Description: Returns 1 when inhibit_destruct() has been called more times than permit_destruct().
See also: inhibit_destruct(), permit_destruct(), destruct(), lfun::_destruct()

Method inhibit_destruct: voidinhibit_destruct()
Description: Inhibit explicit destruction of this object.
See also: permit_destruct(), _destruct(), destruct(), lfun::_destruct()

Method permit_destruct: voidpermit_destruct()
Description: Allow explicit destruction of this object again.
See also: inhibit_destruct(), _destruct(), destruct(), lfun::_destruct()

Class Pike.LiveBacktraceFrame

Description

A BacktraceFrame which retains access to the running code.

This means that unless the corresponding thread running the code is halted (or similar), the values in the fields contained in this object may change at any time.

On the other hand it allows for inspection and altering of the local variables (if any) belonging to the frame. Typical use of this would be for debugging.

See also

BacktraceFrame

Method _is_type: bool res = is_type(Pike.LiveBacktraceFrame())
Description: This object claims to be an array for backward compatibility.

Method _sizeof: int(3..)sizeof(Pike.LiveBacktraceFramearg)

Method `[]: mixed res = Pike.LiveBacktraceFrame()[ index ]
Description: The BacktraceFrame object can be indexed as an array.

Class Pike.MasterCodec

Description: This is a bare-bones codec that is used when loading a dumped master.
See also: Codec

Method decode_object: objectdecode_object(objectobj, mixeddata)
Description: Calls obj->_decode(data).

Method functionof: mixedfunctionof(mixedsymbol)
Description: Look up a function in all_constants().

Method objectof: mixedobjectof(mixedsymbol)
Description: Look up an object in all_constants().

Method programof: mixedprogramof(mixedsymbol)
Description: Look up a program in all_constants().

Class Pike.PollBackend

Description: Backend implemented with poll(2) (SVr4, POSIX).
See also: Backend

Inherit __Backend: inherit __Backend : __Backend

Method `()

float|int(0) res = Pike.PollBackend()()

Description

Perform one pass through the backend.

Calls any outstanding call-outs and non-blocking I/O callbacks that are registred in this backend object.

Parameter sleep_time

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

Returns

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.

See also

Pike.DefaultBackend, main()

Class Pike.PollDeviceBackend

Description: Backend implemented with /dev/poll (Solaris and OSF/1), epoll(2) (Linux) or kqueue(2) (MacOS X, FreeBSD, OpenBSD, etc).
See also: Backend

Inherit __Backend: inherit __Backend : __Backend

Method `()

float|int(0) res = Pike.PollDeviceBackend()()

Description

Perform one pass through the backend.

Calls any outstanding call-outs and non-blocking I/O callbacks that are registred in this backend object.

Parameter sleep_time

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

Returns

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.

See also

Pike.DefaultBackend, main()

Method enable_core_foundation: intenable_core_foundation(boolenable)
Description: On systems with CoreFoundation (OSX, iOS, etc), use CoreFoundation to poll for events. This enables system level technologies that rely on CoreFoundation Runloops to function properly.
Parameter enable: enable or disable this functionality
Returns: the previous value of this setting.

Method enable_external_runloop

intenable_external_runloop(boolenable)

Description

On systems with CoreFoundation (OSX, iOS, etc), delegate running of the Pike Backend to the main runloop of the process (such as a Cocoa application's NSRunLoop).

Enabling the external runloop allows Pike callouts and callback-based I/O to function normally while greatly reducing cpu utilization compared to running the external runloop manually.

Parameter enable

enable or disable this functionality

Returns

the previous value of this setting.

Method query_core_foundation_enabled: intquery_core_foundation_enabled()
Description: On systems with CoreFoundation (OSX, iOS, etc), indicate whether CoreFoundation is being used by this backend to poll for events.
Returns: the current state of CoreFoundation polling: 1=enabled, 0=disabled

Method set_signal_event_callback: optionalvoidset_signal_event_callback(intsignum, function(:void) cb)
Description: Request cb to be called from the backend when the signal signum is received.
Note: This function is a noop except for the kqueue case.
Note: Caveat emptor: Unlikely to work.
See also: signal()

Class Pike.SelectBackend

Description: Backend based on the classic select(2) system call from BSD.

Inherit __Backend: inherit __Backend : __Backend

Method `()

float|int(0) res = Pike.SelectBackend()()

Description

Perform one pass through the backend.

Calls any outstanding call-outs and non-blocking I/O callbacks that are registred in this backend object.

Parameter sleep_time

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

Returns

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.

See also

Pike.DefaultBackend, main()

Class Pike.SmallBackend

Annotations

@@Pike.Annotations.Implements(Pike.__Backend)

Description

This is the most suitable backend implementation if you only want to monitor a small number of Stdio.File objects.

Inherit __Backend: inherit Pike.__Backend : __Backend

Class Pike.Watchdog

Description

A Watchdog that ensures that the process is not hung for an extended period of time. The definition of 'hung' is: Has not used the default backend.

An important and useful side-effect of this class is that the process will start to respond to kill -QUIT by printing a lot of debug information to stderr, including memory usage, and if pike is compiled with profiling, the CPU used since the last time kill -QUIT was called.

Method add_debug: voidadd_debug(function(void:void) f)
Description: The function f will be called if the watchdog triggers, before the normal watchdog output is written.

Method add_probe: voidadd_probe(function(void:bool) f)
Description: Add additional functions to be called each time the watchdog is checked. If any of the probes return false, the watchdog will trigger.

Method alarm_alarm_alarm: voidalarm_alarm_alarm()
Description: Explicitly trigger the watchdog, if enough CPU time has been used. This is not normally called manually.

Method create

Pike.WatchdogPike.Watchdog(intt)

Description

Create a new watchdog, with the intended delay.

Even though the actual watchdog functionality is currently not available on systems without sigalarm, such as Windows, the functionality can still be triggered by adding probe functions

See also

add_probe() and set_delay()

Method ping: voidping()
Description: Tell the watchdog that all is well, and the CPU is not really blocked. Can be used during long calculations that block the normal backend, note that this basically bypasses the main functionality of the watchdog, that is, detecting blocked backend threads.

Method print_debug: voidprint_debug()
Description: Output thread stacktraces, memory and profiling (if available) debug information to stderr.

Method really_trigger_watchdog_promise: voidreally_trigger_watchdog_promise()
Description: Really trigger the watchdog, killing the current process. This is not normally called manually.

Method set_delay

voidset_delay(intt)

Description

Set the watchdog interval to t seconds.

The change will not take effect until the previous probe has been triggered.

Class Pike.__Backend

Description

Base class for the various backend implementations.

Implements callback registration functions and defines the main backend APIs.

Variable before_callback
Variable after_callback

function(Backend:void) Pike.__Backend.before_callback
function(Backend:void) Pike.__Backend.after_callback

Description

If set, these are called just before and after the backend waits for an event.

If an error is thrown from these callbacks then it is reported using master()->handle_error() - it doesn't interrupt the operation of the backend.

Method _do_call_outs

int_do_call_outs()

Description

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.

Returns

Zero if no call outs were called, nonzero otherwise.

See also

call_out(), find_call_out(), remove_call_out()

Method _m_clear: void_m_clear()
Description: Clear all active registrations with this backend (ie unlink all file event callbacks and pending call_outs).
Note: Files are still registered with the backend (albeit the backend does no longer hold any references to them).

Method `()

float|int(0) res = Pike.__Backend()()

Description

Perform one pass through the backend.

Calls any outstanding call-outs and non-blocking I/O callbacks that are registred in this backend object.

Parameter sleep_time

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

Returns

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.

Note

If multiple threads concurrently call this function, then:

One of the threads will be the controlling thread.
All callbacks will be called from the controlling thread.
All threads will be woken up when the controlling thread is done. This may be prematurely if the controlling thread had a shorter timeout.

Note

The backend may also be woken up prematurely if the set of events to monitor is changed.

Note

Multiple concurrent calls was not supported prior to Pike 8.0.

See also

Pike.DefaultBackend, main()

Method add_file

voidadd_file(Stdio.File|Stdio.FILEf)

Description

Parameter f

File to register.

Registers f to be handled by this backend. This simply does f->set_backend(backend) where backend is this object.

See also

Pike.DefaultBackend, main()

Method call_out

arraycall_out(function(:void) f, float|intdelay, mixed ... args)

Description

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

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

See also

remove_call_out(), find_call_out(), call_out_info(), CallOut

Method call_out_info

array(array) call_out_info()

Description

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:

Array
`inttime_left`	Time remaining in seconds until the call_out is to be performed.
`int(0)zero`	Used to be the object that scheduled the call_out.
`function(:void) fun`	Function to be called.
`mixed ... args`	Arguments to the function.

See also

call_out(), find_call_out(), remove_call_out()

Method create: Pike.__BackendPike.__Backend()

Method executing_thread

Thread.Threadexecuting_thread()
intexecuting_thread()

Description

Return the thread currently executing in the backend. I.e. the thread that has called `() and hasn'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.

Method find_call_out

intfind_call_out(function(:void) f)
intfind_call_out(arrayid)

Description

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

Returns

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.

See also

call_out(), remove_call_out(), call_out_info()

Method get_stats

mapping(string:int) get_stats()

Description

Get some statistics about the backend.

Returns

Returns a mapping with the follwoing content:

`"num_call_outs" : int`	The number of active call-outs.
`"call_out_bytes" : int`	The amount of memory used by the call-outs.

Method id: intid()
Description: Return an integer that uniquely identifies this backend. For the default backend that integer is 0.

Method remove_call_out

intremove_call_out(function(:void) f)
intremove_call_out(arrayid)

Description

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

Returns

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.

See also

call_out_info(), call_out(), find_call_out()

Class Pike.__Backend.CallOut

Description: Represents a single call_out in the call_out list.
See also: call_out()

Variable args: protectedarray Pike.__Backend.CallOut.args
Description: The array containing the function and arguments.

Method create

Pike.__Backend.CallOutPike.__Backend.CallOut(int|floatseconds, mixedfun, mixed ... args)

Description

Start a new call out.

This is the low-level implementation of call_out().

call_out() is essentially implemented as:

array call_out(mixed fun,int|float seconds,mixed ... args){return CallOut(seconds, fun, @args)->args;}

See also

call_out()

Module Pike.Annotations

Description: This module contains the set of annotations that the compiler and runtime care about.

Constant AutoCodec: constant Pike.Annotations.AutoCodec
Description: This Annotation causes the compiler to automatically add an implementation of _encode() that returns an array with suitable arguments to lfun::create.
Note: This annotation is only useful for classes that use the implicit create()-syntax, or have a create() that doesn't need any arguments.

Constant Inherited: constant Pike.Annotations.Inherited
Description: This Annotation informs the compiler that any Annotation marked with it is to be inherited. The default is that annotations on classes are not inherited.

Constant Override: constant Pike.Annotations.Override
Description: This Annotation informs the compiler that any symbol marked with it is expected to also have been inherited.

Class Pike.Annotations.AutoCodecClass

Description: This is the class that implements the AutoCodec annotation.

Inherit Annotation: inherit Annotation : Annotation

Class Pike.Annotations.Implements

Description: This annotation causes the compiler to validate that the annotated class implements the specified API.

Inherit Annotation: inherit Pike.Annotation : Annotation

Class Pike.Annotations.InheritedClass

Description: This is the class for the Inherited annotation.

Inherit Annotation: inherit Pike.Annotation : Annotation

Class Pike.Annotations.OverrideClass

Description: This is the class for the Override annotation.

Inherit Annotation: inherit Pike.Annotation : Annotation

Module Pike.DefaultBackend

Description

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.

See also

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

Module Pike.Lazy

Description

This module provides lazy resolving of functions.

Example

The expression Pike.Lazy.Standards.JSON.decode will evaluate to Standards.JSON.decode, but the resolution (and associated compilation) of Standards.JSON will be delayed until the first time that the expression is evaluated.

Note

Note that this destroys type information and delays resolver errors.

Typical use is to break circular compilation dependencies between modules.

Class Pike.Lazy.LazyValue

Variable path: string Pike.Lazy.LazyValue.path

Method __create__: protectedlocalvoid__create__(stringpath)

Method create: Pike.Lazy.LazyValuePike.Lazy.LazyValue(stringpath)

Module Pipe

Description

Single socket output.

Regular file output and (multiple, adding) socket output with no mmap input.

Multiple socket output without regular file output illegal.

Note

It is preferable to use the Shuffler API, it is significantly more flexible.

Class Pipe.pipe

Description: Concatenation pipe.

Method bytes_sent: intbytes_sent()
Description: Return the number of bytes sent.

Method finish: voidfinish()
Description: Terminate and reinitialize the pipe.

Method input: voidinput(objectobj)
Description: Add an input file to this pipe.

Method output: voidoutput(objectobj, int|voidstart_pos)
Description: Add an output file object.

Method set_done_callback: voidset_done_callback(void|function(mixed:mixed) done_cb, void|mixedid)
Description: Set the callback function to be called when all the outputs have been sent.

Method set_output_closed_callback: voidset_output_closed_callback(void|function(mixed, object:mixed) close_cb, void|mixedid)
Description: Set the callback function to be called when one of the outputs has been closed from the other side.

Method start: voidstart()
Description: Start sending the input(s) to the output(s).

Method version: stringversion()
Description: Return the version of the module.

Method write: voidwrite(stringbytes)
Description: Add an input string to this pipe.

Module Process

Method daemon

voiddaemon(intnochdir, intnoclose, void|mapping(string:string|Stdio.File) modifiers)

Description

A function to run current program in the background.

Parameter nochdir

If 0 the process will continue to run in / or the directory dictadet by modifiers.

Parameter noclose

If this is not 0 the process will keep current file descriptors open.

Parameter modifiers

Optional extra arguments. The parameters passed in this mapping will override the arguments nochdir and noclose.

`"cwd" : string`	Change current working directory to this directory.
`"stdin" : string\|Stdio.File`	If this is a string this will be interpreted as a filename pointing out a file to be used as stdandard input to the process. If this is a Stdio.File object the process will use this as standard input.
`"stdout" : string\|Stdio.File`	If this is a string this will be interpreted as a filename pointing out a file to be used as stdandard output to the process. If this is a Stdio.File object the process will use this as standard output.
`"stderr" : string\|Stdio.File`	If this is a string this will be interpreted as a filename pointing out a file to be used as stdandard error to the process. If this is a Stdio.File object the process will use this as standard error.

See also

System.daemon

Note

This function only works on UNIX-like operating systems.

Example

/* close all fd:s and cd to '/' */
   Process.daemon(0, 0);
   /* Do not change working directory. Write stdout to a file called
      access.log and stderr to error.log. */
   Process.daemon(1, 0, ([ "stdout": "access.log", "stderr": "error.log" ]) );

Method exec: intexec(stringfile, string ... foo)

Method get_forkd_default: boolget_forkd_default()
Description: Get the default value for the "forkd" modifier to Process.
Note: The default default value is 0 (zero).
See also: set_forkd_default(), Process()->create()

Method popen: stringpopen(stringcommand)
Description: Executes command as a shell statement ("/bin/sh -c command" for Unix, "cmd /c command" for Windows), waits until it has finished and returns the result as a string.
See also: system, spawn
Deprecated: Replaced by Process.Process.

Method popen

Stdio.FILEpopen(stringcommand, stringmode)

Description

Open a "process" for reading or writing. The command is executed as a shell statement ("/bin/sh -c command" for Unix, "cmd /c command" for Windows). The parameter mode should be one of the following letters:

`"r"`	Open for reading. Data written by the process to stdout is available for read.
`"w"`	Open for writing. Data written to the file is available to the process on stdin.

See also

system, spawn

Deprecated

Replaced by Process.Process.

Method run

mappingrun(string|array(string) cmd, mapping|voidmodifiers)

Description

Easy and lazy way of using Process.Process that runs a process and returns a mapping with the output and exit code without having to make sure you read nonblocking yourself.

Parameter args

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.

Parameter modifiers

It takes all the modifiers Process.Process accepts, with the exception of stdout and stderr. Each must be either absent, or a function accepting a string; if present, the functions will be called whenever output is made on the corresponding stream, otherwise the data will be collected and returned in the result mapping.

If modifiers->stdin is set to a string it will automatically be converted to a pipe that is fed to stdin of the started process.

See also

Process.Processcreate_process

Returns

`"stdout" : string`	Everything the process wrote on stdout, unless a stdout function was provided.
`"stderr" : string`	Everything the process wrote on stderr, similarly.
`"exitcode" : int`	The process' exitcode.

Note

As the entire output of stderr and stdout is stored in the returned mapping it could potentially grow until memory runs out. It is therefore advisable to set up rlimits if the output has a potential to be very large, or else provide functions to handle partial data.

Example

Process.run( ({ "ls", "-l" }) );
   Process.run( ({ "ls", "-l" }), ([ "cwd":"/etc" ]) );
   Process.run( "ls -l" );
   Process.run( "awk -F: '{print $2}'", ([ "stdin":"foo:2\nbar:17\n" ]) );
   Process.run( ({ "echo Output will be immediately written to stdout" }),
                ([ "stdout": lambda(string s) { write(s); },
                   "stderr": lambda(string e) { werror(e); } ]) );

Method search_path

stringsearch_path(stringcommand)

Description

Search for the path to an executable.

Parameter command

Executable to search for.

Searches for command in the directories listed in the environment variable $PATH.

Returns

Returns the path to command if found, and 0 (zero) on failure.

Note

This function is NOT thread safe if the environment variable $PATH is being changed concurrently.

Note

In Pike 7.8.752 and earlier the environment variable $PATH was only read once.

Method set_forkd_default: voidset_forkd_default(boolmode)
Description: Set the default value for the "forkd" modifier to Process.
Note: The default default value is 0 (zero).
See also: get_forkd_default(), Process()->create()

Method sh_quote: stringsh_quote(strings)

Method spawn: __deprecated__Processspawn(stringcommand, void|Stdio.Streamstdin, void|Stdio.Streamstdout, void|Stdio.Streamstderr)
Description: Spawns a process that executes command as a command shell statement ("/bin/sh -c command" for Unix, "cmd /c command" for Windows).
Parameter stdin
Parameter stdout
Parameter stderr: Stream objects to use as standard input, standard output and standard error, respectively, for the created process. The corresponding streams for this process are used for those that are left out.
Returns: Returns a Process.Process object for the created process.
See also: system, popen
Deprecated: Replaced by Process.Process.

Method spawn_pike

Processspawn_pike(array(string) argv, void|mapping(string:mixed) options, array(string)|voidlauncher)

Description

Spawn a new pike process similar to the current.

Parameter argv

Arguments for the new process.

Parameter options

Process creation options. See Process.Process for details. May also specify "add_predefines", "add_program_path", or "add_include_path" in order to include these components in command path (module path is included by default.)

Parameter launcher

Optional launcher prefix command used to spawn the pike binary.

When used this is typically something like ({ "/usr/bin/valgrind" }).

Defaults to the empty array.

See also

Process.Process

Method split_quoted_string

array(string) split_quoted_string(strings, bool|voidnt_mode)

Description

Splits the given string into a list of arguments, according to common (i.e. /bin/sh-based) command line quoting rules:

Sequences of whitespace, i.e. space, tab, \n or \r, are treated as argument separators by default.
Single or double quotes (' or ") can be used around an argument to avoid whitespace splitting inside it. If such quoted strings are used next to each other then they get concatenated to one argument; e.g. a"b"'c' becomes a single argument abc.
Backslash (\) can be used in front of one of the space or quote characters mentioned above to treat them literally. E.g. x\ y is a single argument with a space in the middle, and x\"y is a single argument with a double quote in the middle.
A backslash can also be used to quote itself; i.e. \\ becomes \.
Backslashes in front of other characters are removed by default. However, if the optional nt_mode flag is set then they are retained as-is, to work better with Windows style paths.
Backslashes are treated literally inside quoted strings, with the exception that \" is treated as a literal " inside a "-quoted string. It's therefore possible to include a literal " in a "-quoted string, as opposed to '-quoted strings which cannot contain a '.

Method system: __deprecated__intsystem(stringcommand, void|Stdio.Streamstdin, void|Stdio.Streamstdout, void|Stdio.Streamstderr)
Description: Executes command as a shell statement ("/bin/sh -c command" for Unix, "cmd /c command" for Windows), waits until it has finished and returns its return value.
Parameter stdin
Parameter stdout
Parameter stderr: Stream objects to use as standard input, standard output and standard error, respectively, for the created process. The corresponding streams for this process are used for those that are left out.
Returns: Returns the exit code for the subprocess on normal completion. Returns the negation of the last signal code if it terminated due to a signal.
Note: In Pike 8.0 and earlier this function returned the result straight from Process.Process()->wait().
Deprecated: Replaced by Process.Process.
See also: spawn, popen

Class Process.ForkdDecoder

Description: Decoder for data received by Tools.Standalone.forkd.
See also: ForkdEncoder

Variable fds: array(Stdio.Fd) Process.ForkdDecoder.fds

Method __create__: protectedlocalvoid__create__(array(Stdio.Fd) fds)

Method create: Process.ForkdDecoderProcess.ForkdDecoder(array(Stdio.Fd) fds)

Class Process.ForkdEncoder

Description: Encoder for data to be sent to Tools.Standalone.forkd.
See also: ForkdDecoder

Variable remote_fd: Stdio.File Process.ForkdEncoder.remote_fd

Method __create__: protectedlocalvoid__create__(Stdio.Fileremote_fd)

Method create: Process.ForkdEncoderProcess.ForkdEncoder(Stdio.Fileremote_fd)

Class Process.Process

Description

Slightly polished version of create_process.

In addition to the features supported by create_process, it also supports:

Callbacks on timeout and process termination.
Using Tools.Standalone.forkd via RPC to spawn the new process.

See also

create_process, Tools.Standalone.forkd

Inherit create_process: inherit create_process : create_process
Description: Based on create_process.

Method create

Process.ProcessProcess.Process(string|array(string) command_args, mapping(string:mixed)|voidmodifiers)

Parameter command_args

Parameter modifiers

In addition to the modifiers that create_process accepts, this object also accepts

`"read_callback" : function(Process:void)`	This callback is called when there is data to be read from the process.
`"timeout_callback" : function(Process:void)`	This callback is called if the process times out.
`"timeout" : int`	The time it takes for the process to time out. Default is 15 seconds.
`"forkd" : bool`	Use `Tools.Standalone.forkd` to actually spawn the process.

Note

The default value for the "forkd" modifier may be set via set_forkd_default().

See also

create_process, create_process()->create(), split_quoted_string(), Tools.Standalone.forkd, set_forkd_default(), get_forkd_default()

Class Process.Spawn

Method create: Process.SpawnProcess.Spawn(stringcmd, void|array(string) args, void|mapping(string:string) env, string|voidcwd, void|array(Stdio.File|void) ownpipes, void|array(Stdio.File|void) fds_to_close)

Method kill: intkill(intsignal)

Method wait: intwait()

Class Process.TraceProcess

Description

Class that enables tracing of processes.

The new process will be started in stopped state. Use cont() to let it start executing.

Note

This class currently only exists on systems that implement ptrace().

Inherit create_process: inherit create_process : create_process

Method cont: voidcont(int|voidsignal)
Description: Allow a traced process to continue.
Parameter signal: Deliver this signal to the process.
Note: This function may only be called for stopped processes.
See also: wait()

Method exit: voidexit()
Description: Cause the traced process to exit.
Note: This function may only be called for stopped processes.
See also: cont(), wait()

Method wait

intwait()

Description

Waits for the process to stop.

Returns

`(0..)`	The exit code of the process.
`-1`	The process was killed by a signal.
`-2`	The process has stopped.

See also

create_process::wait()

Class Process.TraceProcess.Registers

Description: Interface to the current register contents of a stopped process.
See also: TraceProcess

Method `[]: int res = Process.TraceProcess.Registers()[ regno ]
Description: Get the contents of register regno.

Class Process.create_process

Description: 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.
See also: Process

Constant limit_value

constant Process.create_process.limit_value

Description

Each limit_value may be either of:

integer: sets current limit, max is left as it is.
mapping: ([ "hard":int, "soft":int ]) Both values are optional, hard <= soft.
array: ({ hard, soft }), both can be set to the string "unlimited". A value of -1 means 'keep the old value'.
string: The string "unlimited" sets both the hard and soft limit to unlimited

Method _sprintf: stringsprintf(stringformat, ... Process.create_processarg ... )

Method create

Process.create_processProcess.create_process(array(string) command_args, void|mappingmodifiers)

Parameter command_args

The command name and its command-line arguments. You do not have to worry about quoting them; pike does this for you.

Parameter modifiers

This optional mapping can can contain zero or more of the following parameters:

"callback" : function(Process.Process:void)

Function called when the created process changes state.

Note that this function is called in a signal handler context, which means that it may be called by any thread at any time after the child process has changed state, and is thus not only called by the main thread when the main backend is idle. Indeed, you can specify a callback even if your program does not use a backend.

"cwd" : string|Stdio.Fd

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.

Note also that the path is relative to the "chroot" if used.

Note that support for the Stdio.Fd variant is not present prior to Pike 9.0, and is only present on some OSes.

"chroot" : string|Stdio.Fd

Chroot to this directory before executing the command.

Note that the current directory will be changed to "/" in the chroot environment, unless "cwd" above has been set.

Note that support for the Stdio.Fd variant is not present prior to Pike 9.0, and is only present on some OSes.

"stdin" : Stdio.File

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.

"stdout" : Stdio.File

"stderr" : Stdio.File

"env" : mapping(string:string)

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" : int|string

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" : int|string

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

"setsid" : bool|Stdio.File

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" : array(int|string)

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.

"noinitgroups" : bool

This parameter overrides a behaviour of the "uid" parameter. If this parameter is used, the gid and groups of the new process will be inherited from the current process rather than changed to the approperiate values for that uid.

"priority" : string

This sets the priority of the new process, see set_priority for more info.

"nice" : int

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.

"keep_signals" : bool

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.

"fds" : array(Stdio.File|int(0))

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.

"rlimit" : mapping(string:limit_value)

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)

`"core" : limit_value`	maximum core file size in bytes
`"cpu" : limit_value`	maximum amount of cpu time used by the process in seconds
`"data" : limit_value`	maximum heap (brk, malloc) size in bytes
`"fsize" : limit_value`	maximum size of files created by the process in bytes
`"map_mem" : limit_value`	maximum size of the process's mapped address space (mmap() and heap size) in bytes
`"mem" : limit_value`	maximum size of the process's total amount of available memory (mmap, heap and stack size) in bytes
`"nofile" : limit_value`	maximum number of file descriptors the process may create
`"stack" : limit_value`	maximum stack size in bytes

"conpty" : Stdio.File

Bind the process to the console associated with this pty slave. NT only.

Example

Process.create_process(({ "/usr/bin/env" }),
                        (["env" : getenv() + (["TERM":"vt100"]) ]));

Example

//! 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 });
 }

Note

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.

Note

On NT the only supported modifiers are: "cwd", "conpty", "stdin", "stdout", "stderr" and "env". All other modifiers are silently ignored.

Note

Support for "callback" was added in Pike 7.7.

Note

Chroot changing directory to "/" was added in Pike 7.9.

Method kill

boolkill(intsignal)

Description

Send a signal to the process.

Returns

`1`	Success.
`0`	Failure. `errno()` is set to EINVAL, EPERM or ESRCH.

Note

This function is only available on platforms that support signals.

See also

predef::kill()

Method last_signal: int(0..)last_signal()
Description: Returns the last signal that was sent to the process.

Method pid: intpid()
Description: Returns the process identifier of the process.

Method set_priority

intset_priority(stringpriority)

Description

Sets the priority of the process. priority is one of the strings

"realtime"
"highest"
"higher"
"high"
"normal"
"low"
"lowest"

Method status

int(-1..2)status()

Description

Returns the status of the process:

`-1`	Unknown
`0`	Running
`1`	Stopped
`2`	Exited

Method wait

intwait()

Description

Waits for the process to end.

Returns

`(0..)`	The exit code of the process.
`-1`	The process was killed by a signal.
`-2`	The process is stopped.

See also

TraceProcess()->wait()

Module Random

Class Random.AES128_CTR_DRBG

Description

Implements NIST SP800-90Ar1 pseudo random number generator CTR_DRBG using AES-128.

https://csrc.nist.gov/publications/detail/sp/800-90a/rev-1/final

Inherit AES128_CTR_DRBG: inherit Nettle.AES128_CTR_DRBG : AES128_CTR_DRBG

Inherit RandomInterface: inherit Builtin.RandomInterface : RandomInterface

Method create: Random.AES128_CTR_DRBGRandom.AES128_CTR_DRBG(string(8bit)entropy, void|string(8bit)personalization)
Description: Instantiate a random generator without derivation function, with the given initial entropy and personalization.

Method entropy_underflow: protectedvoidentropy_underflow()
Description: This method is called when a reseed is forced. By default new entropy is gethered from Random.System. Overload to change the default behaviour.

Class Random.Deterministic

Description

This class implements a detministic random generator by combining a Fortuna random generator with the Random.Interface. The generator is not reseeded after the initial seed.

In case of a process fork the random generators in both processes will continue to generate identical results.

Inherit Fortuna: inherit Nettle.Fortuna : Fortuna

Inherit RandomInterface: inherit Builtin.RandomInterface : RandomInterface

Method create: Random.DeterministicRandom.Deterministic(string(8bit)|intseed)
Description: Initialize the random generator with seed. The internal state is 256 bits, but all seed sizes are allowed.

Class Random.Fast

Description

This class implements a fast and secure random generator. The generator is a Fortuna PRNG that is fed additional entropy from the system RNG (or hardware RNG, if available) for every generated megabyte of data.

If a hardware RNG is present it will be used instead of Fortuna for random strings shorter than 48 bytes.

In case of a process fork it is possible that the random generators will produce identical results for up to one megabyte of generated data.

Inherit Fortuna: inherit Nettle.Fortuna : Fortuna

Inherit RandomInterface: inherit Builtin.RandomInterface : RandomInterface

Class Random.Hardware

Description

This class implements a random generator based on the hardware generator available on some system. Currently only supports Intel RDRAND CPU extension.

In case of a process fork the generators in the two processes will generate independent random values.

Inherit RandomInterface: inherit Builtin.RandomInterface : RandomInterface

Class Random.Interface

Description

This class implements the Pike predef::random API on top of a byte stream random source. This source should be implemented in the random_string method and will be called by random(int) for random input. random(int) is in turned called by all the other variants of random and applied to their use cases.

While it is possible to overload the random variants, care must be taken to not introduce any bias. The default implementation gathers enough bits to completely reach the limit value, and discards them if the result overshoots the limit.

Inherit RandomInterface: inherit Builtin.RandomInterface : RandomInterface

Method random: int(0..)random(int(0..)max)
floatrandom(floatmax)
mixedrandom(array|multisetx)
arrayrandom(mappingm)
mixedrandom(objecto)
Description: Implementation of predef::random.

Method random_string: string(8bit)random_string(intlength)
Description: Prototype for the random source stream function. Must return exactly length bytes of random data.

Class Random.System

Description

This is the default implementation of the random functions. This is the Random.Interface combined with a system random source. On Windows this is the default crypto service while on Unix systems it is /dev/urandom.

In case of a process fork the generators in the two processes will generate independent random values.

Inherit RandomSystem: inherit Builtin.RandomSystem : RandomSystem

Module Regexp

Inherit "___Regexp": inherit "___Regexp" : "___Regexp"

Method `(): protectedSimpleRegexp`()(void|stringregexp)
Description: Convenience/compatibility method to get a SimpleRegexp object.

Method match: boolmatch(stringregexp, stringdata)
Description: Calls Regexp.PCRE.Plain.match in a temporary regexp object. Faster to type but slower to run...

Method replace: stringreplace(stringregexp, stringdata, string|function(string:string) transform)
Description: Calls Regexp.PCRE.Plain.replace in a temporary regexp object. Faster to type but slower to run...

Method split: arraysplit(stringregexp, stringdata)
Description: Calls Regexp.PCRE.Plain.split in a temporary regexp object. Faster to type but slower to run...

Method split2: arraysplit2(stringregexp, stringdata)
Description: Calls Regexp.PCRE.Plain.split2 in a temporary regexp object. Faster to type but slower to run...

Class Regexp.SimpleRegexp

Description

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.

Inherit _SimpleRegexp: inherit _SimpleRegexp : _SimpleRegexp

Method _encode
Method _decode: string(8bit)encode_value(Regexp.SimpleRegexpdata)
Regexp.SimpleRegexpdecode_value(string(8bit)data)
Description: Regexp objects can be encoded and decoded.
See also: encode_value, decode_value

Method create: Regexp.SimpleRegexpRegexp.SimpleRegexp(stringre)
Description: When create is called, the current regexp bound to this object is cleared. If a string is sent to create(), this string will be compiled to an internal representation of the regexp and bound to this object for 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.

Method match: intmatch(stringstr)
Description: Returns 1 if str matches the regexp bound to the regexp object. Zero otherwise.

Method match: array(string) match(array(string) strs)
Description: Returns an array containing strings in strs that match the regexp bound to the regexp object.
Bugs: The current implementation doesn't support searching in strings containing the NUL character or any wide character.
See also: split

Method replace: stringreplace(stringin, string|function(string:string) transform)

Method split: array(string) split(strings)
Description: 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.
Bugs: You can currently only have 39 subregexps.
Bugs: The current implementation doesn't support searching in strings containing the NUL character or any wide character.
See also: match

Module Regexp.PCRE

Inherit "____Regexp_PCRE": inherit "____Regexp_PCRE" : "____Regexp_PCRE"

Constant buildconfig_LINK_SIZE: constant Regexp.PCRE.buildconfig_LINK_SIZE
Description: (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).

Constant buildconfig_MATCH_LIMIT: constant Regexp.PCRE.buildconfig_MATCH_LIMIT
Description: (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).

Constant buildconfig_NEWLINE: constant Regexp.PCRE.buildconfig_NEWLINE
Description: (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).

Constant buildconfig_POSIX_MALLOC_THRESHOLD: constant Regexp.PCRE.buildconfig_POSIX_MALLOC_THRESHOLD
Description: (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).

Constant buildconfig_UTF8: constant Regexp.PCRE.buildconfig_UTF8
Description: (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).

Method `()

StudiedWidestring`()(stringpattern, void|intoptions, void|objecttable)

Description

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.

Method split_subject

array(string) split_subject(stringsubject, array(int) previous_result)

Description

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]; })

Class Regexp.PCRE.Plain

Description

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.

Inherit _pcre: inherit _pcre : _pcre

Method match

boolmatch(stringsubject, void|intstartoffset)

Description

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

Method matchall

this_programmatchall(stringsubject, function(array(string)|void, array(int)|void:mixed|void) callback)

Description

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

Method replace

stringreplace(stringsubject, string|function(:void) with, mixed ... args)

Description

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.

if with is a function, the first argument will be the total match string, and the subsequent arguments will contain any submatches

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"

example:

>Regexp.PCRE("([a-z0-9_\\.-]+)@([\\da-z\\.-]+)\\.([a-z\\.]{2,6})")
  ->replace("foo@bar.org",lambda(string whole,string user,string loc,string domain){return user +" from "+ loc +" dot "+ domain;});(4) Result:"foo from bar dot org"

Method replace1

stringreplace1(stringsubject, string|function(string:string) with)

Description

replace one (first) occurance of a pattern in a subject

example:

>Regexp.PCRE("b[^-]*m")->replace1("abam-boom-fooabadoom","gurka");
Result:"agurka-boom-fooabadoom"

Method replace_positional

stringreplace_positional(stringsubject, stringsubst)

Description

replaces matches in a string, with support for backreferences (matched groups)

Parameter subject

the string to be tested against the regular expression

Parameter subst

string to be inserted in place of each match. backreferences can be inserted into the string to be substituted using the syntax %[n]s where n is the nth matching string group, and 0 (zero) is the full match.

example:

>Regexp.PCRE.Plain("my name is ([a-zA-Z]+)")
      ->replace_positional("allow me to introduce myself: my name is john","%[0]s is my name");(1) Result:"allow me to introduce myself: john is my name"

Method split

array(string)|int(0)split(stringsubject, void|intstartoffset)

Description

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

Method split2

array(string)|int(0)split2(stringsubject, void|intstartoffset)

Description

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"})

Class Regexp.PCRE.Studied

Description: Same as Plain, but will be studied to match faster; useful if you're doing many matches on the same pattern

Inherit Plain: inherit Plain : Plain

Class Regexp.PCRE.StudiedWidestring

Description: Same as Widestring, but will be studied to match faster; useful if you're doing many matches on the same pattern

Inherit Widestring: inherit Widestring : Widestring

Class Regexp.PCRE.Widestring

Description

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.

Inherit Plain: inherit Plain : Plain

Method exec: array(int)|intexec(stringsubject, void|intstartoffset)
Description: The exec function is wrapped to give the correct indexes for the widestring.

Class Regexp.PCRE._pcre

Method _sprintf: stringsprintf(stringformat, ... Regexp.PCRE._pcrearg ... )

Method create

Regexp.PCRE._pcreRegexp.PCRE._pcre(stringpattern, void|intoptions, void|objecttable)

Description

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

Method exec

int|arrayexec(stringsubject, void|intstartoffset)

Description

Matches the regexp against subject, starting at startoffset if it is given.

If the match is successful, the return value is an array that holds the offsets of all matches:

Elements 0 and 1 have the start and end offsets, respectively, of the match for the whole regexp. The start offset is inclusive while the end is exclusive, i.e. the matching string is subject[res[0]..res[1]-1].

Elements 2 and 3 have the offsets of the first capturing submatch (if any) in the same way, elements 4 and 5 are for the second capturing submatch, etc. If a submatch didn't match anything, the corresponding elements are set to -1. If a submatch has matched successfully several times, the offsets of the last match are returned.

The returned array is always of length 2*n + 1, where n is the total number of capturing submatches in the regexp.

If there is an error, an integer error code is returned:

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

Method get_stringnumber: intget_stringnumber(stringstringname)
Description: returns the number of a named subpattern

Method info

mappinginfo()

Description

Returns additional information about a compiled pattern. Only available if PCRE was compiled with Fullinfo.

Returns

"backrefmax" : int

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" : int

Return the number of capturing subpatterns in the pattern. The fourth argument should point to an int variable.

"firstbyte" : int

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" : int

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" : int

"nameentrysize" : int

"options" : int

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" : int

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" : int

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.

Method study: objectstudy()
Description: (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."

Module Regexp.PCRE.ERROR

Constant NOMATCH
Constant NULL
Constant BADOPTION
Constant BADMAGIC
Constant UNKNOWN_NODE
Constant NOMEMORY
Constant NOSUBSTRING
Constant MATCHLIMIT
Constant CALLOUT: constant Regexp.PCRE.ERROR.NOMATCH
constant Regexp.PCRE.ERROR.NULL
constant Regexp.PCRE.ERROR.BADOPTION
constant Regexp.PCRE.ERROR.BADMAGIC
constant Regexp.PCRE.ERROR.UNKNOWN_NODE
constant Regexp.PCRE.ERROR.NOMEMORY
constant Regexp.PCRE.ERROR.NOSUBSTRING
constant Regexp.PCRE.ERROR.MATCHLIMIT
constant Regexp.PCRE.ERROR.CALLOUT
Description: Documented in exec.

Module Regexp.PCRE.OPTION

Description: contains all option constants

Constant ANCHORED: constant Regexp.PCRE.OPTION.ANCHORED
Description: (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.

Constant CASELESS: constant Regexp.PCRE.OPTION.CASELESS
Description: (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.

Constant DOLLAR_ENDONLY: constant Regexp.PCRE.OPTION.DOLLAR_ENDONLY
Description: (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.

Constant DOTALL: constant Regexp.PCRE.OPTION.DOTALL
Description: (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.

Constant EXTENDED

constant Regexp.PCRE.OPTION.EXTENDED

Description

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

Constant EXTRA: constant Regexp.PCRE.OPTION.EXTRA
Description: (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.

Constant MULTILINE

constant Regexp.PCRE.OPTION.MULTILINE

Description

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

Constant NO_AUTO_CAPTURE: constant Regexp.PCRE.OPTION.NO_AUTO_CAPTURE
Description: (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.

Constant UNGREEDY: constant Regexp.PCRE.OPTION.UNGREEDY
Description: (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.

Constant UTF8: constant Regexp.PCRE.OPTION.UTF8
Description: (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.

Module Remote

Description: Remote RPC system.

Class Remote.Call

Description: Wrapper for a remote function.

Method `()

mixed res = Remote.Call()()

Description

Call the wrapped function.

Parameter args

Arguments to pass to the wrapped function.

This function can operate in two modes depending on whether asynchronous mode has been activated or not. If it has it is equivalent to a call of async() and if not of sync() with the same arguments.

See also

async(), sync(), is_async(), set_async()

Method async: voidasync(mixed ... args)
Description: Call the wrapped remote function asynchronously.
Parameter args: Arguments to send to the remote function.
See also: sync(), `()()

Method create: Remote.CallRemote.Call(string|zeroobjectid, stringname, objectconnection, objectcontext, intasync)

Method exists: intexists()
Description: Check whether the wrapped function actually exists at the other end.

Method is_async: intis_async()
Returns: Whether asynchronous mode is active or not.
See also: set_async()

Method set_async: voidset_async(inta)
Description: Change to/from asynchronous mode.
See also: is_async()

Method sync: mixedsync(mixed ... args)
Description: Call the wrapped remote function synchronously.
Parameter args: Arguments to send to the remote function.
Returns: Returns (the possibly wrapped) result from the remote function.
See also: async(), `()()

Class Remote.Client

Description: Remote RPC Client.

Variable con: Remote.Connection Remote.Client.con
Description: Connection to the Remote.Server.

Method close: voidclose()
Description: Close the connection.

Method closed: intclosed()
Description: Check if the connection is closed.

Method create: Remote.ClientRemote.Client(stringhost, intport, void|intnice, void|inttimeout, void|intmax_call_threads)
Description: Connect to a Remote.Server.
Parameter host
Parameter port: Hostname and port for the Remote.Server.
Parameter nice: If set, inhibits throwing of errors from call_sync().
Parameter timeout: Connection timeout in seconds.
Parameter max_call_threads: Maximum number of concurrent threads.

Method get: objectget(stringname)
Description: Get a named object from the remote server.

Method provide: voidprovide(stringname, mixedthing)
Description: Provide a named thing to the Remote.Server.
Parameter name: Name to provide thing under.
Parameter thing: Thing to provide.

Method set_close_callback: voidset_close_callback(function(:void) f)
Description: Set the callback to call when the connection is closed.

Class Remote.Connection

Method add_close_callback: voidadd_close_callback(function(:void) f, mixed ... args)
Description: Add a function that is called when the connection is closed.

Method call_async: voidcall_async(arraydata)
Description: Make a call but don't wait for the result

Method call_sync: mixedcall_sync(arraydata)
Description: Make a call and wait for the result

Method close: voidclose()
Description: Closes the connection nicely, after waiting in outstanding calls in both directions.

Method connect: intconnect(stringhost, intport, void|inttimeout)
Description: This function is called by clients to connect to a server.

Method create: Remote.ConnectionRemote.Connection(void|intnice, void|intmax_call_threads)
Parameter nice: If set, no errors will be thrown.

Method error_message: string|zeroerror_message()
Description: Returns an error message for the last error, in case connect returns zero. Returns zero if the last connect call was successful.

Method get_named_object: objectget_named_object(stringname)
Description: Get a named object provided by the server.

Method remove_close_callback: voidremove_close_callback(arrayf)
Description: Remove a function that is called when the connection is closed.

Method start_server: voidstart_server(objectc, objectcx)
Description: 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.

Class Remote.Context

Description

Remote context tracker.

This class keeps track of what local things correspond to what remote things, and the reverse.

Method add: voidadd(objecto, stringid)

Method create: Remote.ContextRemote.Context(stringb, object|voidcn)

Method decode: mixeddecode(arraya)

Method decode_call: function(:void)|objectdecode_call(arraydata)

Method decode_existp: intdecode_existp(arraydata)

Method describe: stringdescribe(arraydata)

Method encode: arrayencode(mixedval)

Method encode_call: arrayencode_call(object|stringo, string|function(:void) f, arrayargs, inttype)

Method function_for: objectfunction_for(stringid)

Method id_for: stringid_for(mixedthing)

Method object_for: object|zeroobject_for(stringid)

Method set_server_context: voidset_server_context(objectctx, objectcn)

Class Remote.Obj

Description: Wrapper for a remote object.

Method `->: mixed res = Remote.Obj()->X

Method `[]: mixed res = Remote.Obj()[ f ]

Method create: Remote.ObjRemote.Obj(stringid, objectconnection, objectcontext)

Method exists: intexists()

Method get_function: mixedget_function(stringf)

Class Remote.Server

Description: Remote RPC server.

Variable connections: array(Connection) Remote.Server.connections
Description: Open connections.

Variable port: Stdio.Port Remote.Server.port
Description: Port for the Remote.Server.

Variable sctx: Minicontext Remote.Server.sctx
Description: Server context.

Method close: voidclose()
Description: Shut down the Remote.Server for new connections.

Method close_all: voidclose_all()
Description: Shut down the Remote.Server and terminate all current clients.

Method closed: intclosed()
Description: Check if the Remote.Server is closed.

Method create: Remote.ServerRemote.Server(stringhost, intport, void|intmax_call_threads)
Description: Create a Remote.Server.
Parameter host
Parameter port: Hostname and port for the Remote.Server.
Parameter max_call_threads: Maximum number of concurrent threads.

Method provide: voidprovide(stringname, mixedthing)
Description: Provide a named thing to the Remote.Client(s).
Parameter name: Name to provide thing under.
Parameter thing: Thing to provide.

Class Remote.Server.Minicontext

Description: The server Context class.

Module SANE

Description: This module enables access to the SANE (Scanner Access Now Easy) library from pike

Constant FrameGray
Constant FrameRGB
Constant FrameRed
Constant FrameGreen
Constant FrameBlue: constant SANE.FrameGray
constant SANE.FrameRGB
constant SANE.FrameRed
constant SANE.FrameGreen
constant SANE.FrameBlue

Method list_scanners

array(mapping) list_scanners()

Description

Returns an array with all available scanners.

Example

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    "
            ])
        })

Class SANE.Scanner

Method cancel_scan: voidcancel_scan()

Method create: SANE.ScannerSANE.Scanner(stringname)

Method get_option: mixedget_option(stringname)

Method get_parameters

mapping(string:int) get_parameters()

Returns

"format" : int

"last_frame" : int

"lines" : int

"depth" : int

"pixels_per_line" : int

"bytes_per_line" : int

Method list_options

array(mapping) list_options()

Description

This method returns an array where every element is a mapping, layed out as follows.

"name" : string

"title" : string

"desc" : string

"type" : string

"boolean"

"int"

"float"

"string"

"button"

"group"

"unit" : string

"none"

"pixel"

"bit"

"mm"

"dpi"

"percent"

"microsend"

"size" : int

"cap" : multiset

"soft_select"

"hard_select"

"emulate"

"automatic"

"inactive"

"advanced"

"constraint" : int(0)|mapping

Constraints can be of three different types; range, word list or string list. Constraint contains 0 if there are no constraints.

`"type" : string`	Contains the value "range".
`"max" : int`
`"min" : int`
`"quant" : int`

`"type" : string`	Contains the value "list".
`"list" : array(float\|int)`

`"type" : string`	Contains the value "list".
`"list" : array(string)`

Method nonblocking_row_scan: voidnonblocking_row_scan(function(Image.Image, int, Scanner, int:void) callback)

Method row_scan: voidrow_scan(function(Image.Image, int, Scanner:void) callback)

Method set_option: voidset_option(stringname, mixednew_value)
voidset_option(stringname)
Description: If no value is specified, the option is set to it's default value

Method simple_scan: Image.Imagesimple_scan()

Module SDL

Description

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.

Method blit_surface

intblit_surface(SDL.Surfacesrc, SDL.Surfacedst, SDL.Rect|voidsrcrect, SDL.Rect|voiddstrect)

Description

Peforms a fast blit from the source surface to the destination surface.

The final blit rectangle is stored in dstrect. This may differ from srcrect if there was clipping.

This function should not be called on a locked surface.

Parameter src

The surface to be copied.

Parameter dst

The destination surface. This will usually be your main screen, initialized with a call to SDL.set_video_mode().

Parameter srcrect

The rectangular section of src to copy. If the whole surface is to be copied, you can set this to 0.

Parameter dstrect

Where the source surface should be copied to on the destination surface. Only the x and y fields of the SDL.Rect object are used. To copy src to the top-left corner of dst, i.e. at coordinates <0,0>, you can set this to 0.

Returns

If successful, 0, otherwise -1.

See also

SDL.Surface()->blit()

Method cd_name: string|voidcd_name(intdrive)
Description: Returns a human-readable and system-dependent name for the given drive.
Parameter drive: The CD drive index.
Returns: A human-readable and system-dependent name for the given drive, or 0 if no name is available.
See also: SDL.cd_num_drives()

Method cd_num_drives: intcd_num_drives()
Returns: The number of CD-ROM drives on the system.
See also: SDL.cd_name()

Method enable_unicode

intenable_unicode(intenable)

Description

Enables/Disables UNICODE keyboard translation.

If you wish to translate a keysym to its 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.

Parameter enable

A value of 1 enables Unicode translation, 0 disables it and -1 leaves it unchanged (useful for querying the current translation mode).

Returns

The previous translation mode (1 enabled, 0 disabled). If enable is -1, the return value is the current translation mode.

See also

SDL.Keysym

Method flip

intflip(SDL.Surface|voidscreen)

Description

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.set_video_mode() when setting the video mode for this function to perform hardware flipping.

Parameter screen

The screen object to flip. If missing, the default screen is used.

Returns

This function returns 1 if successful, or 0 if there was an error.

See also

SDL.update_rect()

Method get_caption: array(string) get_caption()
Returns: A 2-element array holding the window title and icon name.
See also: SDL.set_caption()

Method get_error: string|zeroget_error()
Description: Get the last internal SDL error.
Returns: The error string, or zero if there was no error.

Method get_key_state

stringget_key_state()

Description

Gets a snapshot of the current keyboard state.

Returns

The current state is returned 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 it's not.

Note

Call SDL.pump_events() to update the state array.

See also

SDL.get_mod_state(), SDL.pump_events()

Example

// Test if the 'Escape' key is pressed.SDL.pump_events();string ks =SDL.get_key_state();if( ks[SDL.K_ESCAPE]){// handle key press...

Method get_mod_state

intget_mod_state()

Description

Returns the current state of the modifier keys (CTRL, ALT, etc.).

Returns

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

See also

SDL.get_key_state(), SDL.pump_events()

Method get_video_info: objectget_video_info()
Returns: Returns an SDL.VideoInfo object, which holds information about the video hardware, or 0 if the video device has not yet been initialized (with a call to SDL.init()).

Method get_video_surface

objectget_video_surface()

Description

Returns the current display surface.

If SDL is doing format conversion on the display surface, this method returns the publicly visible surface, not the real video surface.

Returns

The current display surface, or 0 if there is no display surface.

See also

SDL.set_video_mode()

Method gl_get_attribute

intgl_get_attribute(intattribute)

Description

Returns the value of the given SDL/OpenGL attribute. You might want to call this after SDL.set_video_mode() to check that attributes have been set as you expected.

Parameter attribute

The SDL/OpenGL attribute to query.

Returns

The value of the given attribute.

Example

// Has double-buffering been set?int db =SDL.gl_get_attribute(SDL.GL_DOUBLEBUFFER );if( db ){// yes...

Method gl_set_attribute

voidgl_set_attribute(intattribute, intvalue)

Description

Sets an SDL/OpenGL attribute to the given value.

This won't take effect until after a call to SDL.set_video_mode().

Parameter attribute

The attribute to set. This will be one of SDL.GL_RED_SIZE, SDL.GL_GREEN_SIZE, SDL.GL_BLUE_SIZE, SDL.GL_DEPTH_SIZE or SDL.GL_DOUBLEBUFFER.

Parameter value

The value to set for this attribute.

See also

SDL.gl_get_attribute()

Method gl_swap_buffers: voidgl_swap_buffers()
Description: Swaps the OpenGL buffers on a double-buffered screen.
See also: SDL.gl_set_attribute(), SDL.gl_get_attribute(), SDL.set_video_mode()

Method grab_input

intgrab_input(intmode)

Description

Sets or queries the current 'grab' mode.

Grabbing input means asking that all mouse activity be confined to this application window and that nearly all keyboard events are passed directly to the application, bypassing the window manager.

Parameter mode

One of the following constants:

SDL.GRAB_ON

SDL.GRAB_OFF

SDL.GRAB_QUERY

Returns

The current grab mode, either SDL.GRAB_ON or SDL.GRAB_OFF.

Method iconify_window

inticonify_window()

Description

Attempts to iconify (i.e. minimize) the application window.

If the call is successful, the application will receive an SDL.APPACTIVE loss event.

Returns

Non-zero if successful, otherwise 0.

Method init

voidinit(intflags)

Description

Initializes SDL. This should be called before all other SDL functions.

Parameter flags

The flags parameter specifies what part(s) of SDL to initialize. It can be one of many of the following ORed together.

SDL.INIT_TIMER: Initializes the timer subsystem.
SDL.INIT_AUDIO: Initializes the audio subsystem.
SDL.INIT_VIDEO: Initializes the video subsystem.
SDL.INIT_CDROM: Initializes the cdrom subsystem.
SDL.INIT_JOYSTICK: Initializes the joystick subsystem.
SDL.INIT_EVERYTHING: Initialize all of the above.
SDL.INIT_NOPARACHUTE: Prevents SDL from catching fatal signals.
SDL.INIT_EVENTTHREAD: Run event polling in a separate thread. Not always supported.

See also

SDL.quit(), SDL.init_sub_system(), SDL.quit_sub_system()

Method init_sub_system: voidinit_sub_system(intflags)
Description: After SDL has been initialized with SDL.init() you may initialize uninitialized subsystems with this method.
Parameter flags: The same as what is used in SDL.init().
See also: SDL.init(), SDL.quit(), SDL.quit_sub_system()

Method joystick_event_state

intjoystick_event_state(intstate)

Description

Enables, disables or queries the state of joystick event processing.

Parameter state

One of the following constants:

SDL.ENABLE

Enables joystick event processing.

SDL.IGNORE

Disables joystick event processing.

SDL.QUERY

Queries the current state and returns it.

Returns

The current state of joystick event processing. If state was SDL.ENABLE or SDL.IGNORE, then processing will now be enabled or disabled, respectively.

Method joystick_name: stringjoystick_name(intdevice_index)
Description: Returns the implementation-dependent name of the nth joystick device available to the system.
Parameter device_index: The nth joystick device.
Returns: The implementation-dependent name of the given joystick device.
See also: SDL.Joystick->name()

Method joystick_opened: intjoystick_opened(intdevice_index)
Description: Determines whether the given joystick device has already been opened.
Parameter device_index: The nth joystick device.
Returns: 1 if this device has already been opened, otherwise 0.

Method joystick_update: voidjoystick_update()
Description: Updates the state of all open joysticks attached to the system.

Method num_joysticks: intnum_joysticks()
Returns: The number of joysticks available to the system.
See also: SDL.Joystick

Method open_audio

voidopen_audio(intfrequency, intformat, intchannels, intbufsize)

Description

Initializes the audio API.

Throws an exception if audio can't be initialized.

Parameter frequency

Output sampling frequency, measured in samples per second (Hz). A value of 44100 provides CD-quality playback. A less CPU-intensive value for games is 22050.

Parameter format

Output sample format. One of the following constants:

SDL.AUDIO_U8: Unsigned 8-bit samples.
SDL.AUDIO_S8: Signed 8-bit samples.
SDL.AUDIO_U16LSB: Unsigned 16-bit samples in little-endian byte order.
SDL.AUDIO_S16LSB: Signed 16-bit samples in little-endian byte order.
SDL.AUDIO_U16MSB: Unsigned 16-bit samples in big-endian byte order.
SDL.AUDIO_S16MSB: Signed 16-bit samples in big-endian byte order.
SDL.AUDIO_U16: Same as SDL.AUDIO_U16LSB.
SDL.AUDIO_S16: Same as SDL.AUDIO_S16LSB.
SDL.AUDIO_U16SYS: Unsigned 16-bit samples in system byte order.
SDL.AUDIO_S16SYS: Signed 16-bit samples in system byte order. If in doubt, try this one first.

Parameter channels

Number of sound channels in output: 1 for mono, 2 for stereo.

Parameter bufsize

How many bytes to use per output sample. 1024 is a typical value for games. If just playing music you might set this to 4096 or higher.

Method pump_events

voidpump_events()

Description

Pumps the event loop, gathering events from the input devices.

Normally you won't need to call this method, as it's called implicitly by SDL.Event->poll().

See also

get_key_state(), get_mod_state()

Method quit: voidquit()
Description: Shuts down all SDL subsystems and frees the resources allocated to them. This should always be called before you exit.
Note: You can use the atexit() method to ensure that this method is always called when Pike exits normally.
See also: SDL.init(), SDL.init_sub_system(), SDL.quit_sub_system()

Method quit_sub_system: voidquit_sub_system(intflags)
Description: After an SDL subsystem has been initialized with SDL.init() or SDL.init_sub_system(), it may be shut down with this method.
Parameter flags: A bitwise OR'd combination of the subsystems you wish to shut down (see SDL.init() for a list of subsystem flags).
See also: SDL.init(), SDL.init_sub_system(), SDL.quit()

Method set_caption: voidset_caption(stringtitle, stringicon)
Description: Sets the window's title and icon name. Icon name refers to the text that appears next to the application's icon in its minimized window.
Parameter title: The window's title.
Parameter icon: The minimized window's icon name.
See also: SDL.get_caption()

Method set_gamma: intset_gamma(floatred, floatgreen, floatblue)
FIXME: Document this function

Method set_video_mode: objectset_video_mode(intwidth, intheight, intbpp, intflags)
Description: Sets up a video mode with the specified width, height and bits per pixel.
Parameter width: The desired width. Setting this to <= 0 results in an SDL error.
Parameter height: The desired height. Setting this to <= 0 results in an SDL error.
Parameter bpp: The bits per pixel. This should be either 0, 8, 16, 24 or 32. If you set this to 0, the bits-per-pixel value of the current display will be used.
Parameter flags: An OR'd combination of the desired SDL.Surface flags.
Returns: The framebuffer surface. An error is thrown if the video mode can't be set.
See also: SDL.Surface, SDL.video_mode_ok()

Method show_cursor

intshow_cursor(intshow)

Description

Sets the state of the mouse cursor on the SDL screen (visible or hidden), or queries its current state.

By default, the cursor is visible.

Parameter show

One of these constants:

SDL.ENABLE: Show the cursor.
SDL.DISABLE: Hide the cursor.
SDL.QUERY: Determine the current state of the cursor.

Returns

The current state of the mouse cursor, either SDL.ENABLE or SDL.DISABLE.

Method toggle_fullscreen: inttoggle_fullscreen(void|SDL.Surfacescreen)
Description: Toggles the application between windowed and fullscreen mode, if supported. X11 is the only target currently supported.
Parameter screen: The framebuffer surface, as returned by SDL.set_video_mode().
Returns: Returns 1 on success or 0 on failure.

Method update_rect

voidupdate_rect(intx, inty, intw, inth, SDL.Surface|voidscreen)

Description

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.update_rect() will update the entire screen.

This function should not be called while screen is locked.

Parameter x

Parameter y

Top left corner of the rectangle to update.

Parameter w

Parameter h

Width and height of the rectangle to update.

Parameter screen

The screen object to flip. If missing, the default screen is used.

See also

SDL.flip()

Method video_driver_name: stringvideo_driver_name()
Description: Obtains the name of the video driver. This is a simple one-word identifier such as 'x11' or 'windib'.
Returns: The name of the video driver, or 0 if video has not yet been initialized (with a call to SDL.init()).

Method video_mode_ok: intvideo_mode_ok(intwidth, intheight, intbpp, intflags)
Description: Checks to see if a particular video mode is supported.
Returns: Returns 0 if the requested mode isn't supported under any bit depth, or the bits-per-pixel of the closest available mode with the given width, height and SDL.Surface flags.
See also: SDL.Surface, SDL.set_video_mode(), SDL.get_video_info()

Method warp_mouse: voidwarp_mouse(intxpos, intypos)
Description: Sets the position of the mouse cursor to the given coordinates. This generates an SDL.MOUSEMOTION event.
Parameter xpos: Requested position of the mouse cursor along the x-axis.
Parameter ypos: Requested position of the mouse cursor along the y-axis.

Method was_init: intwas_init(intflags)
Description: This method allows you to see which SDL subsytems have been initialized.
Parameter flags: A bitwise OR'd combination of the subsystems you wish to check (see SDL.init() for a list of subsystem flags).
Returns: A bitwised OR'd combination of the initialized subsystems
See also: SDL.init(), SDL.init_sub_system()

Class SDL.CD

Variable current_frame: int SDL.CD.current_frame
FIXME: Document this variable

Variable current_track: int SDL.CD.current_track
FIXME: Document this variable

Variable id: int SDL.CD.id
FIXME: Document this variable

Variable numtracks: int SDL.CD.numtracks
FIXME: Document this variable

Method create: SDL.CDSDL.CD(intdrive)
FIXME: Document this function

Method eject: inteject()
FIXME: Document this function

Method pause: intpause()
FIXME: Document this function

Method play: intplay(intstart, intlength)
FIXME: Document this function

Method play_tracks: intplay_tracks(intstart_track, intstart_frame, intntracks, intnframes)
FIXME: Document this function

Method resume: intresume()
FIXME: Document this function

Method status: intstatus()
FIXME: Document this function

Method stop: intstop()
FIXME: Document this function

Method track: CDTracktrack(inttrack)
FIXME: Document this function

Class SDL.CDTrack

Variable id
Variable length
Variable offset
Variable type: int SDL.CDTrack.id
int SDL.CDTrack.length
int SDL.CDTrack.offset
int SDL.CDTrack.type
FIXME: Document this variable

Class SDL.Event

Variable axis
Variable ball
Variable button
Variable code
Variable gain
Variable h
Variable hat
Variable keysym
Variable state
Variable type
Variable value
Variable w
Variable which
Variable x
Variable xrel
Variable y
Variable yrel: int SDL.Event.axis
int SDL.Event.ball
int SDL.Event.button
int SDL.Event.code
int SDL.Event.gain
int SDL.Event.h
int SDL.Event.hat
Keysym SDL.Event.keysym
int SDL.Event.state
int SDL.Event.type
int SDL.Event.value
int SDL.Event.w
int SDL.Event.which
int SDL.Event.x
int SDL.Event.xrel
int SDL.Event.y
int SDL.Event.yrel

Method get: intget()
Description: Removes the next event (if any) from the queue and stores it in this SDL.Event object.
Returns: 1 if there was an event to 'get', otherwise 0.

Method poll: intpoll()
Description: Polls for currently pending events.
Returns: 1 if there are currently pending events, otherwise 0.

Method wait: intwait()
Description: Waits indefinitely for the next available event, which is then removed from the queue and stored in this SDL.Event object.
Returns: Returns 1 on success, or 0 if there was an error while waiting for the next event.

Class SDL.Joystick

Description

Represents a joystick, gamepad or other similar input device attached to the system.

You must call SDL.init() with the SDL.INIT_JOYSTICK flag to enable joystick support.

All index numbers count from 0.

All SDL.Joystick methods throw an exception if they are called on an uninitialized object.

Method create: SDL.JoystickSDL.Joystick(intdevice_index)
Description: Opens the given joystick device for use.
Parameter device_index: The nth joystick device available to the system.
See also: SDL.num_joysticks()

Method get_axis

floatget_axis(intaxis)

Description

Returns the current position of the given axis.

The returned value is a float between -1.0 and 1.0.

Parameter axis

The axis index.

Returns

The current position of the given axis.

See also

num_axes()

Method get_ball

array(int) get_ball(intball)

Description

Returns the axis change of the given trackball.

This is its relative motion along both axes since the last call to get_ball(). It is returned as a 2-element array holding the values of dx and dy (- the motion deltas).

Returns

The axis change of the given trackball.

See also

num_balls()

Method get_button

intget_button(intbutton)

Description

Returns the current state of the given button.

This is 1 if the button is pressed, otherwise 0.

Parameter button

The button index.

Returns

The current state of the given button.

See also

num_buttons()

Method get_hat

intget_hat(inthat)

Description

Returns the current state of the given hat.

This is represented as an OR'd combination of one or more of the following constants:

SDL.HAT_CENTERED

SDL.HAT_UP

SDL.HAT_RIGHT

SDL.HAT_DOWN

SDL.HAT_LEFT

SDL.HAT_RIGHTUP

SDL.HAT_RIGHTDOWN

SDL.HAT_LEFTUP

SDL.HAT_LEFTDOWN

Parameter hat

The hat index.

Returns

The current state of the given hat.

See also

num_hats()

Method index: intindex()
Returns: The index of this joystick.

Method name: stringname()
Returns: The implementation-dependent name of this joystick.
See also: SDL.joystick_name()

Method num_axes: intnum_axes()
Returns: The number of axes available for this joystick.

Method num_balls: intnum_balls()
Returns: The number of trackballs available for this joystick.

Method num_buttons: intnum_buttons()
Returns: The number of buttons available for this joystick.

Method num_hats: intnum_hats()
Returns: The number of hats available for this joystick.

Class SDL.Keysym

Description: The Keysym class is used to report key presses and releases. It's available from the SDL.Event class for keyboard events.

Variable mod

int SDL.Keysym.mod

Description

Current key modifiers

mod stores the current state of the keyboard modifiers as explained in SDL.get_mod_state().

Variable scancode

int SDL.Keysym.scancode

Description

Hardware specific scancode

The scancode field should generally be left alone - it is the hardware dependent scancode returned by the keyboard.

Variable sym

int SDL.Keysym.sym

Description

SDL virtual keysym

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.

Variable unicode

int SDL.Keysym.unicode

Description

Translated character

The unicode field is only used when UNICODE translation has beed enabled with SDL.enable_unicode(). If unicode is non-zero then this the UNICODE character corresponding to the keypress.

Note

UNICODE translation does have a slight overhead so don't enable it unless its needed.

Class SDL.Music

Description

Use an SDL.Music object to load in a music file or sample and then play it back using an internal player.

You must call SDL.init() with the SDL.INIT_AUDIO flag for audio support to be available. You must also first set up some audio parameters with a call to SDL.open_audio().

See also

SDL.open_audio()

Method create

SDL.MusicSDL.Music(stringfname)

Description

Loads in the given music file and initializes the object ready for playback.

Supported formats are OGG, MP3, MOD, MID and WAV.

An exception is thrown if the file fails to load.

Parameter fname

The name of the music file to be loaded.

Method fade_in

objectfade_in(intms, int|voidloops)

Description

Fades the music in over the given number of milliseconds. Playback is repeated loops number of times.

The fade-in will only happen on the first play, not on subsequent loops. Likewise, calling this method on an object that is already playing has the same effect as rewind(): playback will start over at the beginning but without fading in.

Parameter ms

Music fades in over this number of milliseconds.

Parameter loops

How many times the music should be repeated (looped). Passing a value of 0 here means the music plays once over - i.e. no repeats. A value of -1 loops the music indefinitely. This is the default if you don't specify a value.

Returns

The SDL.Music object.

See also

fade_out(), fading()

Method fade_out

objectfade_out(intms)

Description

Fades the music out over the given number of milliseconds.

After ms milliseconds have passed, the music will be stopped; i.e. playing() will return 0.

Parameter ms

The number of milliseconds it will take to fade out the music, starting from now.

Returns

The SDL.Music object.

Method fading

intfading()

Description

Determines the current state of fading for this SDL.Music object.

Returns

One of the following constants:

SDL.MIX_NO_FADING

SDL.MIX_FADING_IN

SDL.MIX_FADING_OUT

See also

fade_in(), fade_out()

Method halt: objecthalt()
Description: Stops music playback immediately, including any fader effects.
Returns: The SDL.Music object.

Method pause

objectpause()

Description

Pauses the music playback.

It is safe to call this method when the music is already paused.

Returns

The SDL.Music object.

See also

resume(), paused()

Method paused: intpaused()
Description: Determines if the music is already paused.
Returns: 1 if the music is paused, otherwise 0.

Method play: objectplay(int|voidloops)
Description: Starts playback. Repeats loops number of times.
Parameter loops: The number of times the music should be looped (i.e. repeated). If loops is -1 or omitted, the music will repeat indefinitely.
Returns: The SDL.Music object.

Method playing

intplaying()

Description

Determines if the music is already playing.

This method will return 1 even if the music has been paused.

Returns

1 if the music is playing, otherwise 0.

Method resume

objectresume()

Description

Resume music playback after a call to pause().

It is safe to call this method when the music isn't paused.

Returns

The SDL.Music object.

See also

pause(), paused()

Method rewind

objectrewind()

Description

Rewinds the music to the start and resumes playback.

If the music was paused at the time of this call, you will still need to call resume() to restart playback.

This function works only for MOD, OGG, MP3 and Native MIDI streams.

Returns

The SDL.Music object.

Method set_volume: floatset_volume(floatvol)
Description: Sets the volume for music playback.
Parameter vol: The volume to set. This is a float value from 0.0 (silent) to 1.0 (full volume). Values above and below these limits will be clamped.
Returns: The previous volume setting.

Method volume: floatvolume()
Returns: The current volume setting. This is a float value from 0.0 (silent) to 1.0 (full volume).

Class SDL.PixelFormat

Description: 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.

Variable rloss
Variable gloss
Variable bloss
Variable aloss: int SDL.PixelFormat.rloss
int SDL.PixelFormat.gloss
int SDL.PixelFormat.bloss
int SDL.PixelFormat.aloss
Description: Precision loss of each color component.

Variable alpha: int SDL.PixelFormat.alpha
Description: Overall surface alpha value.

Variable rmask
Variable gmask
Variable bmask
Variable amask: int SDL.PixelFormat.rmask
int SDL.PixelFormat.gmask
int SDL.PixelFormat.bmask
int SDL.PixelFormat.amask
Description: Binary mask used to retrieve individual color values.

Variable rshift
Variable gshift
Variable bshift
Variable ashift: int SDL.PixelFormat.rshift
int SDL.PixelFormat.gshift
int SDL.PixelFormat.bshift
int SDL.PixelFormat.ashift
Description: Binary left shift of each color component in the pixel value.

Variable bits_per_pixel: int SDL.PixelFormat.bits_per_pixel
Description: The number of bits used to represent each pixel in a surface. Usually 8, 16, 24 or 32.

Variable bytes_per_pixel: int SDL.PixelFormat.bytes_per_pixel
Description: The number of bytes used to represent each pixel in a surface. Usually one to four.

Variable colorkey: int SDL.PixelFormat.colorkey
Description: Pixel value of transparent pixels.

Method get_rgb: Image.Color.Colorget_rgb(intpixel)
Description: Get RGB component values from a pixel stored in this pixel format.
Parameter pixel: A pixel retrieved from a surface with this pixel format or a color previously mapped with map_rgb() or map_rgba().
Returns: A Image.Color.Color object with the RGB components of the pixel.
See also: map_rgb(), map_rgba(), get_rgba()

Method get_rgba

mapping(string:Image.Color.Color|int) get_rgba(intpixel)

Description

Get RGB component values from a pixel stored in this pixel format.

Parameter pixel

A pixel retrieved from a surface with this pixel format or a color previously mapped with map_rgb() or map_rgba().

Returns

A mapping containing the RGBA components of the pixel:

`"color" : Image.Color.Color`	The RGB color value of the pixel.
`"alpha" : int`	The alpha value of the pixel in the range 0-255.

See also

map_rgb(), map_rgba(), get_rgb()

Method losses: array(int) losses()
Description: Convenience method returning the RGBA precision loss as an array.

Method map_rgb

intmap_rgb(intr, intg, intb)
intmap_rgb(Image.Color.Colorcolor)

Description

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

Parameter r

Parameter g

Parameter b

The red, green and blue components specified as an integer between 0 and 255.

Parameter color

The color as represented by an Image.Color.Color object.

Returns

A pixel value best approximating the given RGB color value for a given pixel format.

See also

map_rgba(), get_rgb(), get_rgba()

Method map_rgba

intmap_rgba(intr, intg, intb, inta)
intmap_rgba(Image.Color.Colorcolor, inta)

Description

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

Parameter r

Parameter g

Parameter b

Parameter a

The red, green and blue components specified as an integer between 0 and 255.

Parameter color

The color as represented by an Image.Color.Color object.

Returns

A pixel value best approximating the given RGB color value for a given pixel format.

See also

map_rgb(), get_rgb(), get_rgba()

Method masks: array(int) masks()
Description: Convenience method returning the RGBA masks as an array.

Method shifts: array(int) shifts()
Description: Convenience method returning the RGBA shifts as an array.

Class SDL.Rect

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

Variable w Variable h: int(16bit) SDL.Rect.w
int(16bit) SDL.Rect.h
Description: The width and height of the rectangle. Internally these are 16 bit unsigned integers. A runtime error will be generated when integer values are used that are too big.

Variable x Variable y: int(-32768..32767) SDL.Rect.x
int(-32768..32767) SDL.Rect.y
Description: Position of the upper-left corner of the rectangle. Internally these are 16 bit signed integers. A runtime error will be generated when integer values are used that are too big.

Method cast: (array)SDL.Rect() (mapping)SDL.Rect()
Description: It is possible to cast a Rect object to an array or to a mapping. The array will have the values in the order x, y, w, h and the mapping will have the values associated with the corresponding names.

Method create: SDL.RectSDL.Rect()
SDL.RectSDL.Rect(int(-32768..32767)x, int(-32768..32767)y)
SDL.RectSDL.Rect(int(-32768..32767)x, int(-32768..32767)y, int(16bit)w, int(16bit)h)
Description: Create a new Rect.
Parameter x
Parameter y: Optional initial values for Rect()->x and Rect()->y.
Parameter w
Parameter h: Optional initial values for Rect()->w and Rect()->h.

Class SDL.Surface

Description: 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().

Variable clip_rect: SDL.Rect SDL.Surface.clip_rect
Description: This is the clipping rectangle as set by set_clip_rect().

Variable flags

int SDL.Surface.flags

Description

The following are supported in the flags field.

SDL.SWSURFACE: Surface is stored in system memory
SDL.HWSURFACE: Surface is stored in video memory
SDL.ASYNCBLIT: Surface uses asynchronous blits if possible.
SDL.ANYFORMAT: Allows any pixel-format (Display surface).
SDL.HWPALETTE: Surface has exclusive palette.
SDL.DOUBLEBUF: Surface is double buffered (Display surface).
SDL.FULLSCREEN: Surface is full screen (Display Sur face).
SDL.OPENGL: Surface has an OpenGL context (Display Surface).
SDL.OPENGLBLIT: Surface supports OpenGL blitting (Display Surface).
SDL.RESIZABLE: Surface is resizable (Display Surface).
SDL.HWACCEL: Surface blit uses hardware acceleration.
SDL.SRCCOLORKEY: Surface use colorkey blitting.
SDL.RLEACCEL: Colorkey blitting is accelerated with RLE.
SDL.SRCALPHA: Surface blit uses alpha blending.
SDL.PREALLOC: Surface uses preallocated memory.

Variable format: SDL.PixelFormat SDL.Surface.format
Description: The pixel format of this surface.

Variable w Variable h: int SDL.Surface.w
int SDL.Surface.h
Description: The width and height of the surface in pixels.

Method blit: objectblit(SDL.Surfacedst, SDL.Rect|voidsrcrect, SDL.Rect|voiddstrect)
Description: Perform a blit from this surface to the dst surface.
Parameter dst: Destination Surface for the blit.
Parameter srcrect: Optional source Rect. If UNDEFINED the entire source Surface will be copied.
Parameter dstrect: Optional destination Rect. Only the position fields x and y values are used. If UNDEFINED the blit will be performed to position 0, 0.

Method convert_surface: objectconvert_surface(SDL.PixelFormatfmt, intflags)
FIXME: Document this function

Method display_format

SDL.Surfacedisplay_format()

Description

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

Returns

The new surface. An error is thrown if the conversion fails.

Method display_format_alpha

SDL.Surfacedisplay_format_alpha()

Description

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.

Returns

The new surface. An error is thrown if the conversion fails.

Method fill: objectfill(intcolor)
Description: Fill the entire surface with a solid color.
See also: fill_rect()

Method fill_rect: objectfill_rect(intcolor, SDL.Rectdstrect)
Description: Fill a rectangle with a solid color.
See also: fill()

Method get_pixel: intget_pixel(intx, inty)
Description: Get the value of the specified pixel. The surface needs to be locked before this method can be used.
Parameter x
Parameter y: Pixel coordinate to get.
Returns: The value of the specified pixel.
See also: set_pixel(), unlock(), lock()

Method init

SDL.Surfaceinit(intflags, intwidth, intheight, intdepth, intRmask, intGmask, intBmask, intAmask)

Description

This (re)initializes this surface using the specified parameters.

Any previously allocated data will be freed.

Parameter depth

Parameter Rmask

Parameter Gmask

Parameter Bmask

Parameter Amask

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.

Parameter width

Parameter height

width and height specify the desired size of the image.

Parameter flags

flags specifies the type of surface that should be created. It is an OR'd combination of the following possible values:

SDL.SWSURFACE: 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.HWSURFACE: 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).
SDL.SRCCOLORKEY: 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.
SDL.SRCALPHA: 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.

Note

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.

Returns

A reference to itself.

Note

If this method fails, the surface will become uninitialized.

See also

set_image()

Method lock: intlock()
Description: This methods locks the surface to allow direct access to the pixels using the get_pixel() and set_pixel() methods.
Note: 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.
Note: Calling this method multiple times means that you need to call unlock an equal number of times for the surface to become unlocked.
Returns: 1 for success or 0 if the surface couldn't be locked.
See also: unlock(), set_pixel(), get_pixel()

Method set_alpha: objectset_alpha(intflag, intalpha)
FIXME: Document this function

Method set_clip_rect: objectset_clip_rect(SDL.Rectrect)
FIXME: Document this function

Method set_color_key: objectset_color_key(intflag, intkey)
Description: Set or clear the color key (aka transparent pixel) for a the surface. Also control whether RLE-accelleration is enabled or not.
Parameter flag
FIXME: Document this function

Method set_image

SDL.Surfaceset_image(Image.Imageimage, int|voidflags)
SDL.Surfaceset_image(Image.Imageimage, Image.Imagealpha, int|voidflags)

Description

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

Parameter image

The source image.

Parameter alpha

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.

Parameter flags

When present this specifies the type of surface that should be created. It is an OR'd combination of the following possible values:

SDL.SWSURFACE: 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.HWSURFACE: 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).
SDL.SRCCOLORKEY: 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.
SDL.SRCALPHA: 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.

Note

If this method fails, the surface will become uninitialized.

Returns

A reference to itself.

See also

init()

Method set_pixel: intset_pixel(intx, inty, intpixel)
Description: Set the value of the specified pixel. The surface needs to be locked before this method can be used.
Parameter x
Parameter y: Pixel coordinate to modify.
Parameter pixel: Pixel value to set to the specified pixel.
Returns: A reference to the surface itself.
See also: get_pixel(), unlock(), lock()

Method unlock

voidunlock()

Description

Surfaces that were previously locked using lock() must be unlocked with unlock().

Surfaces should be unlocked as soon as possible.

See also

lock()

Class SDL.VideoInfo

Description: 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.

Variable blit_fill: int SDL.VideoInfo.blit_fill
Description: Are color fills accelerated?

Variable blit_hw: int SDL.VideoInfo.blit_hw
Description: Are hardware to hardware blits accelerated?

Variable blit_hw_a: int SDL.VideoInfo.blit_hw_a
Description: Are hardware to hardware alpha blits accelerated?

Variable blit_hw_cc: int SDL.VideoInfo.blit_hw_cc
Description: Are hardware to hardware colorkey blits accelerated?

Variable blit_sw: int SDL.VideoInfo.blit_sw
Description: Are software to hardware blits accelerated?

Variable blit_sw_a: int SDL.VideoInfo.blit_sw_a
Description: Are software to hardware alpha blits accelerated?

Variable blit_sw_cc: int SDL.VideoInfo.blit_sw_cc
Description: Are software to hardware colorkey blits accelerated?

Variable format: SDL.PixelFormat SDL.VideoInfo.format
Description: Pixel format of the video device.

Variable hw_available: int SDL.VideoInfo.hw_available
Description: Is it possible to create hardware surfaces?

Variable video_mem: int SDL.VideoInfo.video_mem
Description: Total amount of video memory in KB.

Variable wm_available: int SDL.VideoInfo.wm_available
Description: Is there a window manager available

Module Search

Method do_query_and

ResultSetdo_query_and(array(string) words, array(int) field_coefficients, array(int) proximity_coefficients, intcutoff, function(string, int, int:string) blobfeeder)

Parameter words

Arrays of word ids. Note that the order is significant for the ranking.

Parameter field_coefficients

An array of ranking coefficients for the different fields. In the range of [0x0000-0xffff]. The array (always) has 65 elements:

Array
`int0`	body
`int1..64`	Special field 0..63.

Parameter proximity_coefficients

An array of ranking coefficients for the different proximity categories. Always has 8 elements, in the range of [0x0000-0xffff].

Array
`int0`	spread: 0 (Perfect hit)
`int1`	spread: 1-5
`int2`	spread: 6-10
`int3`	spread: 11-20
`int4`	spread: 21-40
`int5`	spread: 41-80
`int6`	spread: 81-160
`int7`	spread: 161-

Parameter blobfeeder

This function returns a Pike string containing the word hits for a certain word. Call repeatedly until it returns 0.

Method do_query_or

ResultSetdo_query_or(array(string) words, array(int) field_coefficients, array(int) proximity_coefficients, intcutoff, function(string, int, int:string) blobfeeder)

Parameter words

Arrays of word ids. Note that the order is significant for the ranking.

Parameter field_coefficients

An array of ranking coefficients for the different fields. In the range of [0x0000-0xffff]. The array (always) has 65 elements:

Array
`int0`	body
`int1..64`	Special field 0..63.

Parameter proximity_coefficients

An array of ranking coefficients for the different proximity categories. Always has 8 elements, in the range of [0x0000-0xffff].

Array
`int0`	spread: 0 (Perfect hit)
`int1`	spread: 1-5
`int2`	spread: 6-10
`int3`	spread: 11-20
`int4`	spread: 21-40
`int5`	spread: 41-80
`int6`	spread: 81-160
`int7`	spread: 161-

Parameter blobfeeder

This function returns a Pike string containing the word hits for a certain word. Call repeatedly until it returns 0.

Method do_query_phrase

ResultSetdo_query_phrase(array(string) words, array(int) field_coefficients, function(string, int, int:string) blobfeeder)

Parameter words

Arrays of word ids. Note that the order is significant for the ranking.

Parameter field_coefficients

An array of ranking coefficients for the different fields. In the range of [0x0000-0xffff]. The array (always) has 65 elements:

Array
`int0`	body
`int1..64`	Special field 0..63.

Parameter blobfeeder

This function returns a Pike string containing the word hits for a certain word. Call repeatedly until it returns 0.

Method get_filter: Search.Filer.Baseget_filter(stringmime_type)
Description: Returns the appropriate filter object for the given mime type. This will be one of the objects in Search.Filter.

Method get_filter_fields: array(string) get_filter_fields()
Description: Returns an array of field types supported by the available set of media plugins.

Method get_filter_mime_types: mapping(string:Search.Filter.Base) get_filter_mime_types()
Description: Returns a mapping from mime-type to filter objects. The filter objects are from Search.Filter.

Class Search.Blob

Method add: voidadd(intdocid, intfield, intoffset)

Method create: Search.BlobSearch.Blob(void|stringinitial)

Method data: stringdata()

Method memsize: intmemsize()

Method merge: voidmerge(stringdata)

Method remove: voidremove(intdoc_id)

Method remove_list: voidremove_list(array(int) docs)

Class Search.Blobs

Method add_words: voidadd_words(intdocid, array(string) words, intfield_id)
Description: Add all the words in the 'words' array to the blobs

Method memsize: intmemsize()
Description: Returns the in-memory size of the blobs

Method read: arrayread()
Description: returns ({ string word_id, string blob }) or ({0,0}) As a side-effect, this function frees the blob and the word_id, so you can only read the blobs struct once. Also, once you have called read, add_words will no longer work as expected.

Method read_all_sorted: array(array(string)) read_all_sorted()
Description: Returns ({({ string word1_id, string blob1 }),...}), sorted by word_id in octet order.
Note: This function also frees the blobs and the word_ids, so you can only read the blobs struct once. Also, once you have called read or read_all_sorted, add_words will no longer work as expected.

Class Search.LinkFarm

Method add: voidadd(int, array, int, int)

Method memsize: intmemsize()
Description: Returns the in-memory size of the linkfarm

Method read: arrayread()
Description: returns ({ int word_id, Blob b }) or 0

Class Search.MergeFile

Method create: Search.MergeFileSearch.MergeFile(Stdio.File_fd)

Method merge_mergefiles: voidmerge_mergefiles(Search.MergeFilea, Search.MergeFileb)

Method write_blobs: voidwrite_blobs(_WhiteFish.Blobsblobs)

Class Search.RankingProfile

Variable cutoff: int Search.RankingProfile.cutoff

Variable field_ranking: array(int) Search.RankingProfile.field_ranking

Variable proximity_ranking: array(int) Search.RankingProfile.proximity_ranking

Method copy: this_programcopy()
Description: Returns a copy of this object.

Method create: Search.RankingProfileSearch.RankingProfile(void|intcutoff, void|array(int) proximity_ranking)
Search.RankingProfileSearch.RankingProfile(intcutoff, array(int) proximity_ranking, Search.Database.Basedb, array(int)|mapping(string:int) field_ranking)
Parameter cutoff: Defaults to 8
Parameter proximity_ranking: Defaults to ({ 8, 7, 6, 5, 4, 3, 2, 1, })
Parameter field_ranking: Defaults to ({ 17, 0, 147 }) + allocate(62).
Parameter db: Only needed if field_ranking is provided as a mapping.

Class Search.ResultSet

Description

A resultset is basically an array of hits from the search.

Note: inheriting this class is _not_ supported (for performance reasons)

Method _sizeof
Method size: intsizeof(Search.ResultSetarg)
intsize()
Description: Return the size of this resultset, in entries.

Method intersect
Method `&: ResultSetintersect(ResultSeta)
ResultSet res = Search.ResultSet() & a
Description: Return a new resultset with all entries that are present in _both_ sets. Only the document_id is checked, the resulting ranking is the sum of the rankings if the two sets.

Method `| Method `+ Method or: ResultSet res = Search.ResultSet() | a
ResultSet res = Search.ResultSet() + a
ResultSetor(ResultSeta)
Description: Add the given resultsets together, to generate a resultset with both sets included. The rankings will be added if a document exists in both resultsets.

Method sub
Method `-

ResultSetsub(ResultSeta)
ResultSet res = Search.ResultSet() - a

Description

Return a new resultset with all entries in a removed from the current ResultSet.

Only the document_id is checked, the ranking is irrelevalt.

Method add_ranking: ResultSetadd_ranking(ResultSeta)
Description: Return a new resultset. All entries are the same as in this set, but if an entry exists in a, the ranking from a is added to the ranking of the entry

Method cast: (array)Search.ResultSet()
Description: Only works when type == "array". Returns the resultset data as a array.

Method dup: ResultSetdup()
Description: Return a new resultset with the same contents as this one.

Method memsize: intmemsize()
Description: Return the size of this resultset, in bytes.

Method overhead

intoverhead()

Description

Return the size of the memory overhead, in bytes.

You can minimize the overhead by calling dup(), which will create a new resultset with the exact size needed.

Method slice: array(array(int)) slice(intfirst, intnelems)
Description: Return nelems entries from the result-set, starting with first. If 'first' is outside the resultset, or nelems is 0, 0 is returned.

Method sort: voidsort()
Description: Sort this ResultSet according to ranking.

Method sort: voidsort()
Description: Sort this ResultSet according to ranking.

Method sort_docid: voidsort_docid()
Description: Sort this ResultSet according to document id.

Method test

ResultSettest(intnelems, intstart, intincr)

Description

Fills the resulttest with nelems entries, the document IDs are strictly raising, starting with start, ending with start+nelems*incr.

Used for debug and testing.

Module Search.Database

Class Search.Database.Base

Description: Base class for Search database storage abstraction implementations.

Method allocate_field_id: intallocate_field_id(stringfield)
Description: Allocate a field id.
Parameter field: The (possibly wide string) field name wanted.
Returns: An allocated numeric id, or -1 if the allocation failed.

Method create: Search.Database.BaseSearch.Database.Base(stringdb_url)
Description: Initialize the database object.
Parameter path: The URL that identifies the underlying database storage

Method get_blob: stringget_blob(stringword, intnum, void|mapping(string:mapping(int:string)) blobcache)
Description: Retrieves a blob from the database.
Parameter word: The wanted word. Possibly in wide-string format. (Not UTF-8 encoded.)
Parameter num
Parameter blobcache
Returns: The blob requested, or 0 if there's no more blobs.

Method get_database_size: intget_database_size()
Description: Returns the size, in bytes, of the search database.

Method get_document_id: intget_document_id(stringuri, void|stringlanguage, void|intdo_not_create)
Description: Retrieve and possibly creates the document id corresponding to the given URI and language code.
Parameter uri: The URI to be retrieved or created.
Parameter language: A two letter ISO-639-1 language code, or 0 if the document is language neutral.
Parameter do_not_create: If non-zero, do not create the document.
Returns: The non-zero numeric identifier if the document identified by uri and language_code exists, or 0 otherwise.

Method get_field_id: intget_field_id(stringfield, void|intdo_not_create)
Description: Retrieve and possibly creates the numeric id of a field
Parameter field: The (possibly wide string) field name wanted.
Parameter do_not_create: If non-zero, do not allocate a field id for this field
Returns: An allocated numeric id, or -1 if it did not exist, or allocation failed.

Method get_language_stats: mapping(string|int:int) get_language_stats()
Description: Retrieve statistics about the number of documents in different languages.
Returns: A mapping with the the language code in the index part, and the corresponding number of documents as values.

Method get_lastmodified: intget_lastmodified(Standards.URI|string|array(Standards.URI|string) uri, void|stringlanguage)
Description: Get last modification time for uri, language.
Returns: Returns modification time in seconds since 1970-01-01T00:00:00 UTC) if known, and 0 (zero) otherwise.

Method get_metadata: mapping(string:string) get_metadata(int|Standards.URI|stringuri, void|stringlanguage, void|array(string) wanted_fields)
Description: Retrieve a metadata collection for a document.
Parameter uri: The URI of the resource being indexed.
Parameter language: A two letter ISO-639-1 language code, or 0 if the document is language neutral.
Parameter wanted_fields: An array containing the wanted metadata field names, or 0.
Returns: The metadata fields in wanted_fields or all existing fields if wanted_fields is 0.

Method get_most_common_words: array(array) get_most_common_words(void|intcount)
Description: Returns a list of the count most common words in the database. count defaults to 10.

Method get_num_deleted_documents: intget_num_deleted_documents()
Description: Returns the number of deleted documents in the database.

Method get_num_words: intget_num_words()
Description: Returns the number of distinct words in the database.

Method get_uri_and_language

mappingget_uri_and_language(int|array(int) doc_id)

Description

Retrieve the URI and language code associated with doc_id.

Returns

`"uri" : string`	The URI of the document.
`"language" : void\|string`	The ISO-639-1 language code of the document, or 0 if not set.

Method get_uri_id: intget_uri_id(stringuri, void|intdo_not_create)
Description: Retrieve and possibly creates the URI id corresponding to the given URI.
Parameter uri: The URI to be retrieved or created.
Parameter do_not_create: If non-zero, do not create the URI.
Returns: The non-zero numeric identifier if uri exists, or 0 otherwise.

Method insert_words: voidinsert_words(Standards.URI|stringuri, void|stringlanguage, stringfield, array(string) words)
Description: Index words into the database. The data may be buffered until the next sync call.
Parameter uri: The URI of the resource being indexed.
Parameter language: A two letter ISO-639-1 language code, or 0 if the document is language neutral.
Parameter field: The field name for the words being indexed.
Parameter words: The words being indexed. Possibly in wide-string format. (Not UTF8 encoded.)

Method list_fields: mapping(string:int) list_fields()
Description: Lists all fields in the search database.
Returns: A mapping with the fields in the index part, and the corresponding numeric field id as values.

Method list_url_by_prefix: voidlist_url_by_prefix(stringurl_prefix, function(string:void) cb)
Description: Calls cb for all uri:s that match uri_prefix.

Method remove_document: voidremove_document(string|Standards.URIuri, void|stringlanguage)
Description: Remove a document from the database.
Parameter uri: The URI of the resource being indexed.
Parameter language: A two letter ISO-639-1 language code. If zero, delete all existing language forks with the URI of uri.

Method remove_document_prefix: voidremove_document_prefix(string|Standards.URIuri)
Description: Removes all documents that matches the provided uri prefix.
Parameter uri: The URI prefix of the documents to delete.

Method remove_field: voidremove_field(stringfield)
Description: Remove a field from the database. Also removes all stored metadata with this field, but not all indexed words using this field id.
Parameter field: The (possibly wide string) field name to be removed.

Method remove_metadata: voidremove_metadata(Standards.URI|stringuri, void|stringlanguage)
Description: Remove all metadata for a document
Parameter uri: The URI of the resource whose metadata should be removed.
Parameter language: A two letter ISO-639-1 language code, or 0 if the document is language neutral.

Method remove_uri: voidremove_uri(string|Standards.URIuri)
Description: Remove URI from the database.
Parameter uri: The URI of the resource being removed.

Method remove_uri_prefix: voidremove_uri_prefix(string|Standards.URIuri)
Description: Remove URI prefix from the database.
Parameter uri: The URI prefix of the resource being removed.

Method safe_remove_field: voidsafe_remove_field(stringfield)
Description: Remove a field from the database if it isn't used by the filters. Also removes all stored metadata with this field, but not all indexed words using this field id.
Parameter field: The (possibly wide string) field name to be removed.

Method set_lastmodified: voidset_lastmodified(Standards.URI|stringuri, void|stringlanguage, intwhen)
Description: Set last modification time for uri, language to mtime (seconds since 1970-01-01T00:00:00 UTC).

Method set_metadata: voidset_metadata(Standards.URI|stringuri, void|stringlanguage, mapping(string:string) metadata)
Description: Set a metadata collection for a document.
Parameter uri: The URI of the resource being indexed.
Parameter language: A two letter ISO-639-1 language code, or 0 if the document is language neutral.
Parameter metadata: A collection of metadata strings to be set for a document. The strings may be wide. The "body" metadata may be cut off at 64K.

Method set_sync_callback: voidset_sync_callback(function(:void) f)
Description: Sets a function to be called when sync has been completed.

Method sync: voidsync()
Description: Writes the data stored in temporary buffers to permanent storage. Calls the function set by set_sync_callback] when done.

Module Search.Filter

Class Search.Filter.Base

Constant contenttypes: constantarray(string) Search.Filter.Base.contenttypes
Description: The MIME content types this object can filter.

Constant fields

optional constantarray(string) Search.Filter.Base.fields

Description

The different fields this object can extract from the media. The list can contain any of the following values.

"body"

"title"

"keywords"

"description"

"robots"

"headline"

"modified"

"author"

"summary"

Method filter: .Outputfilter(Standards.URIuri, string|Stdio.Filedata, stringcontent_type, mixed ... more)

Class Search.Filter.Output

Description: This object is returned from Search.Filter plugins.

Variable document_size: int Search.Filter.Output.document_size
Description: The size of the document.

Variable fields: mapping(string:string) Search.Filter.Output.fields
Description: Data extracted from input, grouped by type. Standard fields are "body", "title", "description", "keywords" and "mtime".
Note: Note that all field values (even "mtime") are strings.

Variable links: array(Standards.URI|string) Search.Filter.Output.links
Description: All links collected from the document.

Variable uri_anchors: mapping(string:string) Search.Filter.Output.uri_anchors
Description: Maps un-normalized URLs to raw text, e.g. ([ "http://pike.lysator.liu.se": "Pike language" ]) .

Method fix_relative_links: voidfix_relative_links(Standards.URIbase_uri)
Description: Modifies relative links in links to be relative to base_uri.

Module Search.Grammar

Method getDefaultFields: multiset(string) getDefaultFields()

Method optimize: ParseNode|zerooptimize(ParseNodenode, string|voidparentOp)

Method remove_stop_words: voidremove_stop_words(ParseNodenode, array(string) stop_words)

Class Search.Grammar.AbstractParser

Method create

Search.Grammar.AbstractParserSearch.Grammar.AbstractParser(void|mapping(string:mixed) options)

Parameter options

`"implicit" : string`	Either of the strings: "and", "or". If not supplied, default to "or".
`"fields" : multiset(string)`	The words that should be recognized as fields. If not supplied, it should default to `Search.Grammar.getDefaultFields()`

Class Search.Grammar.AndNode

Description: And node.

Inherit ParseNode: inherit ParseNode : ParseNode

Class Search.Grammar.DateNode

Description: Date node.

Inherit ParseNode: inherit ParseNode : ParseNode

Class Search.Grammar.DefaultParser

Inherit AbstractParser: protected inherit .AbstractParser : AbstractParser

Inherit Lexer: protected inherit .Lexer : Lexer

Variable options: mapping(string:mixed) Search.Grammar.DefaultParser.options

Method create: Search.Grammar.DefaultParserSearch.Grammar.DefaultParser(mapping(string:mixed)|voidopt)

Method parse: ParseNodeparse(stringq)

Class Search.Grammar.OrNode

Description: Or node.

Inherit ParseNode: inherit ParseNode : ParseNode

Class Search.Grammar.ParseNode

Description: Abstract parse tree node.

Class Search.Grammar.TextNode

Description: Text node.

Inherit ParseNode: inherit ParseNode : ParseNode

Module Search.Grammar.Lexer

Method tokenize: string|array(array(Token|string)) tokenize(stringquery)
Description: Tokenizes a query into tokens for later use by a parser.
Parameter query: The query to tokenize.
Returns: An array containing the tokens: ({ ({ TOKEN_WORD, "foo" }), ... }) Or, in case of an error, a string with the error message.

Enum Search.Grammar.Lexer.Token

Constant TOKEN_AND
Constant TOKEN_OR: constant Search.Grammar.Lexer.TOKEN_AND
constant Search.Grammar.Lexer.TOKEN_OR

Constant TOKEN_PLUS
Constant TOKEN_MINUS
Constant TOKEN_COLON: constant Search.Grammar.Lexer.TOKEN_PLUS
constant Search.Grammar.Lexer.TOKEN_MINUS
constant Search.Grammar.Lexer.TOKEN_COLON

Constant TOKEN_END: constant Search.Grammar.Lexer.TOKEN_END

Constant TOKEN_EQUAL
Constant TOKEN_LESSEQUAL
Constant TOKEN_GREATEREQUAL
Constant TOKEN_NOTEQUAL
Constant TOKEN_LESS
Constant TOKEN_GREATER: constant Search.Grammar.Lexer.TOKEN_EQUAL
constant Search.Grammar.Lexer.TOKEN_LESSEQUAL
constant Search.Grammar.Lexer.TOKEN_GREATEREQUAL
constant Search.Grammar.Lexer.TOKEN_NOTEQUAL
constant Search.Grammar.Lexer.TOKEN_LESS
constant Search.Grammar.Lexer.TOKEN_GREATER

Constant TOKEN_LPAREN
Constant TOKEN_RPAREN: constant Search.Grammar.Lexer.TOKEN_LPAREN
constant Search.Grammar.Lexer.TOKEN_RPAREN

Constant TOKEN_TEXT: constant Search.Grammar.Lexer.TOKEN_TEXT

Constant TOKEN_UNKNOWN: constant Search.Grammar.Lexer.TOKEN_UNKNOWN

Module Search.Indexer

Method extension_to_type: stringextension_to_type(stringextension)

Method filename_to_type: stringfilename_to_type(stringfilename)

Method filter_and_index: Search.Filter.Output|zerofilter_and_index(Search.Database.Basedb, string|Standards.URIuri, void|stringlanguage, string|Stdio.Filedata, stringcontent_type, void|mappingheaders, void|stringdefault_charset)

Method index_document: voidindex_document(Search.Database.Basedb, string|Standards.URIuri, void|stringlanguage, mappingfields)

Method remove_document: voidremove_document(Search.Database.Basedb, string|Standards.URIuri, void|stringlanguage)

Module Search.Query

Method execute

array(Search.ResultSet|array(string)) execute(Search.Database.Basedb, Search.Grammar.AbstractParserparser, stringquery, Search.RankingProfileranking, void|array(string) stop_words, search_order|voidorder)

Parameter query

The query string entered by user.

Parameter db

The search database.

Parameter defaultRanking

Used when searching in the field "any:".

Returns

An array with three elements:

Array
`Search.ResultSet0`	The ResultSet containing the hits.
`array(string) 1`	All wanted words in the query. (I.e. not the words that were preceded by minus.)
`array(mapping) 2`	All wanted globs in the query. (I.e. not the globs that were preceded by minus.)

Enum Search.Query.search_order

Constant RELEVANCE
Constant DATE_ASC
Constant DATE_DESC
Constant NONE
Constant PUBL_DATE_ASC
Constant PUBL_DATE_DESC: constant Search.Query.RELEVANCE
constant Search.Query.DATE_ASC
constant Search.Query.DATE_DESC
constant Search.Query.NONE
constant Search.Query.PUBL_DATE_ASC
constant Search.Query.PUBL_DATE_DESC

Module Search.Queue

Class Search.Queue.Base

Description: Virtual base class for the Search crawler state.

Inherit Queue: inherit Web.Crawler.Queue : Queue

Method add_uri: voidadd_uri(Standards.URIuri, intrecurse, stringtemplate, void|intforce)
Description: Add an URI to be crawled.

Method clear: voidclear()
Description: Clear and empty the entire queue.

Method clear_cache: voidclear_cache()
Description: Clear any RAM caches.

Method clear_md5: voidclear_md5(int ... stages)
Description: Clear the content MD5 for all URIs at the specified stages.

Method clear_stage: voidclear_stage(int ... stages)
Description: Reset all URIs at the specified stage to stage 0 (zero).

Method get: int|Standards.URIget()

Method get_extra

mappingget_extra(Standards.URIuri)

Returns

Returns a mapping with the current state for the URI.

"md5" : string

"recurse" : string|int

"stage" : string|int

"template" : string

FIXME

Currently this function always returns a mapping(string:string), but this may change to the above in the future.

Method get_uris: array(Standards.URI) get_uris(void|intstage)
Returns: Returns all URIs if no stage is specified, otherwise returns the URIs at the specified stage.
FIXME: State 0 (zero) is a special case, and returns all URIs. This may change in the future.

Method num_with_stage: intnum_with_stage(int ... stage)
Returns: Returns the number of URIs at the specified stage(s).

Method put

voidput(string|array(string)|Standards.URI|array(Standards.URI) uri)

Description

Add one or multiple URIs to the queue.

All the URIs will be added with recursion enabled and an empty template.

Method remove_stage: voidremove_stage(intstage)
Description: Remove all URIs at the specified stage.

Method remove_uri: voidremove_uri(string|Standards.URIuri)
Description: Remove an URI from the queue.

Method remove_uri_prefix: voidremove_uri_prefix(string|Standards.URIuri)
Description: Remove all URIs with the specified prefix from the queue.

Method set_md5: voidset_md5(Standards.URIuri, stringmd5)
Description: Set the content MD5 for an URI.

Method set_recurse: voidset_recurse(Standards.URIuri, intrecurse)
Description: Set the recurse mode for an URI.

Method set_stage: voidset_stage(Standards.URIuri, intstage)
Description: Set the stage for a single URI.

Enum Search.Queue.Base.Stage

Description: The queue stage levels.

Constant STAGE_WAITING
Constant STAGE_FETCHING
Constant STAGE_FETCHED
Constant STAGE_FILTERED
Constant STAGE_INDEXED
Constant STAGE_COMPLETED
Constant STAGE_ERROR: constant Search.Queue.Base.STAGE_WAITING
constant Search.Queue.Base.STAGE_FETCHING
constant Search.Queue.Base.STAGE_FETCHED
constant Search.Queue.Base.STAGE_FILTERED
constant Search.Queue.Base.STAGE_INDEXED
constant Search.Queue.Base.STAGE_COMPLETED
constant Search.Queue.Base.STAGE_ERROR

Class Search.Queue.MySQL

Description: Search crawler state stored in a Mysql database.

Inherit Base: inherit .Base : Base

Method create

Search.Queue.MySQLSearch.Queue.MySQL(Web.Crawler.Stats_stats, Web.Crawler.Policy_policy, string_url, string_table, void|Web.Crawler.RuleSet_allow, void|Web.Crawler.RuleSet_deny)

Parameter _url

Sql.Sql URL for the database to store the queue.

Parameter _table

Sql.Sql table name to store the queue in.

If the table doesn't exist it will be created.

Method get_schemes: array(string) get_schemes()
Returns: Returns an array with all URI schemes currently used in the queue.

Method get_stage: intget_stage(Standards.URIuri)
Returns: Returns the current stage for the specified URI.
See also: set_stage()

Method reset_stage: voidreset_stage(string|voiduri_prefix)
Description: Reset the stage to 0 (zero) for all URIs with the specified uri_prefix. If no uri_prefix is specified reset the stage for all URIs.

Module Search.Utils

Method flush_profile: voidflush_profile(intp)
Description: Flushes the profile p from all ProfileCache objects obtained with get_profile_cache.

Method get_profile_cache: ProfileCacheget_profile_cache(stringdb_name)
Description: Returns a ProfileCache for the profiles stored in the database db_name.

Method get_profile_storage: mappingget_profile_storage(stringdb_name)
Description: Returns a profile storage mapping, which will be shared between all callers with the same db_name given.

Method get_scheduler: Schedulerget_scheduler(stringdb_name)
Description: Returns a scheduler for the given profile database.

Method normalize: stringnormalize(stringin)
Description: Normalize the input string. Performs unicode NFKD normalization and then lowercases the whole string

Method tokenize: array(string) tokenize(stringin)
Description: Tokenize the input string (Note: You should first call normalize on it)

Method tokenize_and_normalize: array(string) tokenize_and_normalize(stringwhat)
Description: This can be optimized quite significantly when compared to tokenize( normalize( x ) ) in the future, currently it's not all that much faster, but still faster.

Class Search.Utils.Logger

Method add_program_name: intadd_program_name(intcode, stringname)

Method create: Search.Utils.LoggerSearch.Utils.Logger(Sql.Sqldb_object, intprofile, intstderr_logging)
Search.Utils.LoggerSearch.Utils.Logger(stringdb_url, intprofile, intstderr_logging)

Method get_log: array(array(string|int)) get_log(intprofile, array(string) types, intfrom, intto)

Method log_error: voidlog_error(intcode, void|stringextra, void|intlog_profile)

Method log_event: voidlog_event(intcode, stringtype, void|stringextra, void|intlog_profile)

Method log_notice: voidlog_notice(intcode, void|stringextra, void|intlog_profile)

Method log_warning: voidlog_warning(intcode, void|stringextra, void|intlog_profile)

Class Search.Utils.ProfileCache

Variable db_name: string Search.Utils.ProfileCache.db_name

Method __create__: protectedlocalvoid__create__(stringdb_name)

Method create: Search.Utils.ProfileCacheSearch.Utils.ProfileCache(stringdb_name)

Method flush_cache: voidflush_cache()
Description: Empty the whole cache.

Method flush_profile: voidflush_profile(intp)
Description: Flushes profile entry p from the profile cache.

Method get_db_profile_number: intget_db_profile_number(stringname)
Description: Returns the profile number for the given database profile.

Method get_profile_entry: ProfileEntryget_profile_entry(stringdb_name, void|stringquery_name)
Description: Returns a ProfileEntry object with the states needed for commiting searches in the database profile db_name with the rules from query profile query_name.

Method get_query_profile_number: intget_query_profile_number(stringname)
Description: Returns the profile number for the given query profile.

Method get_value_mapping: mappingget_value_mapping(intprofile)
Description: Returns the value mapping for the given profile.

Method list_db_profiles: array(string) list_db_profiles()
Description: Returns a list of available database profiles.

Method list_query_profiles: array(string) list_query_profiles()
Description: Returns a list of available query profiles.

Method up_to_datep

int(-1..1)up_to_datep(intprofile_id)

Description

Checks if the profile profile_id has been changed, and clears related caches if so.

Returns

`-1`	The profile is deleted.
`0`	The profile is not up to date.
`1`	The profile is up to date.

Class Search.Utils.ProfileEntry

Description: A result entry from the ProfileCache.

Method check_timeout: boolcheck_timeout()
Description: Checks if it is time to check if the profile values are to old.

Method create: Search.Utils.ProfileEntrySearch.Utils.ProfileEntry(intdatabase_profile_id, intquery_profile_id, ProfileCachecache)
Parameter cache: The parent cache object.

Method get_database: Search.Database.MySQLget_database()
Description: Returns a cached search database for the current database profile.

Method get_database_value: mixedget_database_value(stringindex)
Description: Returns the database profile value index.

Method get_query_value: mixedget_query_value(stringindex)
Description: Returns the query profile value index.

Method get_ranking: Search.RankingProfileget_ranking()
Description: Returns a cached ranking profile for the current database and query profile.

Method get_stop_words: array(string) get_stop_words()
Description: Returns a cached array of stop words for the current query profile.

Class Search.Utils.Scheduler

Method new_entry: voidnew_entry(intlatency, array(int) profiles)
Description: Call this method to indicate that a new entry has been added to the queue. The scheduler will delay indexing with at most latency minutes.

Module Serializer

Description

Serialization interface.

This module contains APIs to simplify serialization and deserialization of objects.

See also

serialize(), deserialize()

Method deserialize: voiddeserialize(objecto, function(function(mixed:void), string, type:void) deserializer)
Description: Call lfun::_deserialize() in o.
See also: serialize(), lfun::_deserialize(), Serializable()->_deserialize()

Method serialize: voidserialize(objecto, function(mixed, string, type:void) serializer)
Description: Call lfun::_serialize() in o.
See also: deserialize(), lfun::_serialize(), Serializable()->_serialize()

Class Serializer.Encodeable

Description

Simple base for an object that can be serialized by encode_value. Also supports decoding.

Uses Serializable as it's base.

Simply inherit this class in the classes you want to have encoded and decoded.

Note that it's not automatically recursive, objects assigned to variables in this object have to be Encodeable on their own for encode to work.

When decoding only variables that existed at the time the object was encoded are assigned, that is, if the class now has more variables they new variables will be set to 0.

Inherit Serializable: inherit Serializable : Serializable

Method _decode

Serializer.Encodeabledecode_value(string(8bit)data)

Description

Callback for decoding the object. Sets variables in the object from the values in the mapping.

Called automatically by decode_value, not normally called manually.

Method _encode

string(8bit)encode_value(Serializer.Encodeabledata)

Description

Callback for encoding the object. Returns a mapping from variable name to value.

Called automatically by encode_value, not normally called manually.

Class Serializer.Serializable

Description

The base class for serializable objects.

Inherit this class in classes that need to be serializable.

See also

Serializer.serialize(), Serializer.deserialize()

Method _deserialize

protectedvoid_deserialize(objecto, function(function(mixed:void), string, type:void) deserializer)

Description

Dispatch function for deserialization.

Parameter o

Object to serialize. Always a context of the current object.

Parameter deserializer

Function to typically be called once for every variable in the inheriting class.

This function calls _deserialize_variable() once for every variable in the inheriting class, which in turn will call deserializer with the arguments:

Argument 1: The setter for the variable.
Argument 2: The name of the variable.
Argument 3: The declared type of the variable.

Note

The symbols will be listed in the order they were defined in the class.

Note

This function is typically called via Serializer.deserialize().

See also

Serializer.deserialize(), _deserialize_variable(), _serialize(), Builtin.Setter

Method _deserialize_variable

protectedvoid_deserialize_variable(function(function(mixed:void), string, type:void) deserializer, function(mixed:void) setter, stringsymbol, typesymbol_type)

Description

Default deserialization function for variables.

Parameter deserializer

Function to be called in turn.

Parameter setter

Function that sets the value of the variable.

Parameter symbol

Variable name.

Parameter symbol_type

Type of the variable.

This function is typically called from _deserialize(), and does something like:

if(object_typep(symbol_type)){program p = program_from_type(symbol_type);if(p && !needs_parent(p) && is_deserializable(p)){object value = p();
        setter(value);Serializer.deserialize(value, deserializer);return;}}
    deserializer(setter, symbol, symbol_type);

Note

The above takes care of the most common cases, but

Does not support anonymous object types.
Does not support objects needing a parent.
Does not support non-serializable objects.
Selects one of the object types in case of a complex symbol_type. The selected type is NOT deterministic in case there are multiple choices that satisfy the above.
Is likely to throw errors if p() requires arguments.

These issues can all be solved by overloading this function.

See also

_deserialize(), _serialize_variable(), Builtin.Setter

Method _serialize

protectedvoid_serialize(objecto, function(mixed, string, type:void) serializer)

Description

Dispatch function for serialization.

Parameter o

Object to serialize. Always a context of the current object.

Parameter serializer

Function to typically be called once for every variable in the inheriting class.

This function calls _serialize_variable() once for every variable in the inheriting class, which in turn will call serializer with the arguments:

Argument 1: The value of the variable.
Argument 2: The name of the variable.
Argument 3: The declared type of the variable.

Note

The symbols will be listed in the order they were defined in the class.

Note

This function is typically called via Serializer.serialize().

See also

Serializer.serialize(), _serialize_variable(), _deserialize()

Method _serialize_variable

protectedvoid_serialize_variable(function(mixed, string, type:void) serializer, mixedvalue, stringsymbol, typesymbol_type)

Description

Default serialization function for variables.

Parameter serializer

Function to be called in turn.

Parameter value

Value of the variable.

Parameter symbol

Variable name.

Parameter symbol_type

Type of the variable.

This function is typically called from _serialize(), and just does

serializer(value, symbol, symbol_type);

It is provided for overloading for eg filtering or validation purposes.

See also

_serialize(), _deserialize_variable()

Module Shuffler

Description

Module implementing sending to and from nonblocking streams and other sources.

Most useful when implementing sending of data from strings, files and other sources to a network connection. The module also supports generic bandwidth throttling.

Multiple Shuffler object can be created, each optionally with their own backend.

This makes it easier to use more than one CPU for pure data transmission, just have multiple backends each in their own thread, with their own shuffle object.

Constant INITIAL
Constant RUNNING
Constant PAUSED
Constant DONE
Constant WRITE_ERROR
Constant READ_ERROR
Constant USER_ABORT: constant Shuffler.INITIAL
constant Shuffler.RUNNING
constant Shuffler.PAUSED
constant Shuffler.DONE
constant Shuffler.WRITE_ERROR
constant Shuffler.READ_ERROR
constant Shuffler.USER_ABORT
Description: The state of an individual Shuffle object.

Class Shuffler.Shuffle

Description: This class contains the state for one ongoing data shuffling operation. To create a Shuffle instance, use the Shuffler()->shuffle method.

Variable shuffler: Shuffler Shuffler.Shuffle.shuffler
Description: The Shuffler that owns this Shuffle object

Variable throttler: Throttler Shuffler.Shuffle.throttler
Description: The Throttler that is associated with this Shuffle object, if any.

Method add_source

voidadd_source(mixedsource, int|voidstart, int|voidlength)
voidadd_source(mixedsource, function(Shuffle, int:array(string)|zero) wrap_cb)
voidadd_source(arraysource)
voidadd_source(arraysource, function(Shuffle, int:array(string)|zero) wrap_cb)

Description

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

int: An ordinary 8-bit wide byte.
string: An ordinary 8-bit wide pike string.
System.Memory: An initialized instance of the System.Memory class.
Stdio.Buffer: A Stdio.Buffer object which will be called once with read_buffer() to acquire the data.
Stdio.File: Stdio.File instance pointing to a normal file.
Stdio.Stream: Stdio.File instance pointing to a stream of some kind (network socket, named pipe, stdin etc). Blocking or nonblocking.
Stdio.NonblockingStream|Stdio.Stream: An object implementing the callback based reading (set_read_callback and set_close_callback).
array: An array of any of the supported sources. Note that neither start nor length can be specified then.

Method create: Shuffler.ShuffleShuffler.Shuffle(objectfd, objectshuffler, mixedthrottler, mixedbackend, void|intstart, void|intlength)
Description: This object is normally not created directly, instead use Shuffler()->shuffle

Method pause: voidpause()
Description: Temporarily pause all data transmission

Method sent_data: intsent_data()
Description: Returns the amount of data that has been sent so far.

Method set_done_callback: voidset_done_callback(function(Shuffle, int:void) cb)
Description: Sets the done callback. This function will be called when all sources have been processed, or if an error occurs.

Method set_request_arg: voidset_request_arg(mixedarg)
Description: Sets the extra argument sent to Throttler()->request() and Throttler()->give_back.

Method set_throttler: voidset_throttler(Throttlert)
Description: Calling this function overrides the Shuffler global throttler.

Method start: voidstart(void|intautopause, void|intfreerun)
Description: Start sending data from the sources.
Parameter autopause: If true, automatically pause the shuffler when all sources have been consumed. Everytime this happens, the done_callback will ben called.
Parameter freerun: If true, do not attempt to coalesce output by using bulkmode.

Method state: intstate()
Description: Returns the current state of the shuffler. This is one of the following: INITIAL, RUNNING, PAUSED, DONE, WRITE_ERROR, READ_ERROR and USER_ABORT

Method stop: voidstop()
Description: Stop all data transmission, and then call the done callback

Class Shuffler.Shuffler

Description: 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.

Method pause: voidpause()
Description: Pause all Shuffle objects associated with this Shuffler

Method set_backend: voidset_backend(Pike.Backendb)
Description: Set the backend that will be used by all Shuffle objects created from this shuffler.

Method set_throttler: voidset_throttler(Throttlert)
Description: Set the throttler that will be used in all Shuffle objects created from this shuffler, unless overridden in the Shuffle objects.

Method shuffle

Shuffleshuffle(Stdio.NonblockingStreamdestination, int|voidstart, int|voidlength)

Description

Create a new Shuffle object.

The destination has to support nonblocking I/O through set_nonblocking_keep_callbacks and set_write_callback member functions.

Note

For destinations that connect directly to a kernel-filedescriptor please note that the filedescriptor will be dup()ed for the duration of the shuffle. This means that if the original destination object is kept, we temporarily use two filedescriptors for it.

Method start: voidstart()
Description: Unpause all Shuffle objects associated with this Shuffler

Class Shuffler.Throttler

Note: This is an interface that all Throttlers must implement. It's not an actual class in this module.

Method give_back: voidgive_back(Shuffleshuffle, intamount)
Description: This function will be called by the Shuffle object to report that some data assigned to it by this throttler was unused, and can be given to another Shuffle object instead.

Method request

voidrequest(Shuffleshuffle, intamount, function(int:void) callback)

Description

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.

Module Standards

Class Standards.URI

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

Variable authority: string|zero Standards.URI.authority
Description: Authority component of URI (formerly called net_loc, from RFC 2396 known as authority)

Variable base_uri: this_program|zero Standards.URI.base_uri
Description: The base URI object, if present

Variable fragment: string|zero Standards.URI.fragment
Description: The fragment part of URI. May be 0 if not present.

Variable host
Variable user
Variable password: string|zero Standards.URI.host
string|zero Standards.URI.user
string|zero Standards.URI.password
Description: Certain classes of URI (e.g. URL) may have these defined

Variable path: string Standards.URI.path
Description: Path component of URI. May be empty, but not undefined.

Variable port: int Standards.URI.port
Description: If no port number is present in URI, but the scheme used has a default port number, this number is put here.

Variable query: string|zero Standards.URI.query
Description: Query component of URI. May be 0 if not present.

Variable scheme: string|zero Standards.URI.scheme
Description: Scheme component of URI

Method `->=
Method `[]=: Standards.URI()->X = value
Standards.URI()[ property ] = value
Description: Assign a new value to a property of URI
Parameter property: When any of the following properties are used, properties that depend on them are recalculated: user, password, host, port, authority, base_uri.
Parameter value: The value to assign to property

Method `==: int res = Standards.URI() == something
Description: Compare this URI to something, in a canonical way.
Parameter something: Compare the URI to this

Method add_query_variable: voidadd_query_variable(stringname, stringvalue)
Description: Adds the provided query variable to the already existing ones. Will overwrite an existing variable with the same name.

Method add_query_variables: voidadd_query_variables(mapping(string:string) vars)
Description: Appends the provided set of query variables with the already existing ones. Will overwrite all existing variables with the same names.

Method cast: (string)Standards.URI() (mapping)Standards.URI()
Description: 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.

Method create: Standards.URIStandards.URI(URIuri)
Standards.URIStandards.URI(URIuri, URIbase_uri)
Standards.URIStandards.URI(URIuri, stringbase_uri)
Standards.URIStandards.URI(stringuri)
Standards.URIStandards.URI(stringuri, URIbase_uri)
Standards.URIStandards.URI(stringuri, stringbase_uri)
Parameter base_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.
Parameter uri: When uri is another URI object, the created URI will inherit all properties of the supplied uri except, of course, for its base_uri.
Throws: An exception is thrown if the uri is a relative URI or only a fragment, and missing a base_uri.

Method get_http_path_query: stringget_http_path_query()
Description: Return the path and query part of the URI, coded according to RFC 1738.

Method get_http_query: string|zeroget_http_query()
Description: Return the query part, coded according to RFC 1738, or zero.

Method get_path_query: stringget_path_query()
Description: Returns path and query part of the URI if present.

Method get_query_variables: mapping(string:string) get_query_variables()
Description: Returns the query variables as a mapping(string:string).

Method reparse_uri: voidreparse_uri()
voidreparse_uri(URIbase_uri)
voidreparse_uri(stringbase_uri)
Description: 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.
Parameter base_uri: Set the new base URI to this.
Throws: An exception is thrown if the uri is a relative URI or only a fragment, and missing a base_uri.

Method set_query_variables: voidset_query_variables(mapping(string:string) vars)
Description: Sets the query variables from the provided mapping.

Module Standards.ASN1

Method decode_der_oid: stringdecode_der_oid(stringder_oid)
Description: Convenience function to convert a DER/BER encoded oid (object identifier) to the human readable dotted-decimal form.
See also: encode_der_oid

Method encode_der_oid: stringencode_der_oid(stringdotted_decimal)
Description: Convenience function to convert an oid (object identifier) on dotted-decimal form (e.g. "1.3.6.1.4.1.1466.115.121.1.38") to its DER (and hence also BER) encoded form.
See also: decode_der_oid

Module Standards.ASN1.Decode

Description: Decodes a DER object.

Method der_decode: .Types.Objectder_decode(Stdio.Bufferdata, mapping(int:program) types, void|boolsecure)
Parameter data: An instance of Stdio.Buffer containing the DER encoded data.
Parameter types: 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.
Parameter secure: Will fail if the encoded ASN.1 isn't in its canonical encoding.
Returns: 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.
FIXME: Handling of implicit and explicit ASN.1 tagging, as well as other context dependence, is next to non_existant.

Method secure_der_decode: .Types.Object|zerosecure_der_decode(string(8bit)data, mapping(int:program)|voidtypes)
Description: Works just like simple_der_decode, except it will return 0 on errors, including if there is leading or trailing data in the provided ASN.1 data.
See also: simple_der_decode

Method simple_der_decode: .Types.Objectsimple_der_decode(string(8bit)data, mapping(int:program)|voidtypes)
Description: decode a DER encoded object using universal data types
Parameter data: a DER encoded object
Parameter types: An optional set of application-specific types. Should map 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. This set is used to extend universal_types.
Returns: an object from Standards.ASN1.Types or either Standards.ASN1.Decode.Primitive or Standards.ASN1.Decode.Constructed if the type is unknown.

Class Standards.ASN1.Decode.Constructed

Description: Constructed type

Inherit Compound: inherit .Types.Compound : Compound

Variable cls
Variable tag
Variable raw
Variable elements: int Standards.ASN1.Decode.Constructed.cls
int Standards.ASN1.Decode.Constructed.tag
string(8bit) Standards.ASN1.Decode.Constructed.raw
array(.Types.Object) Standards.ASN1.Decode.Constructed.elements

Method __create__: protectedlocalvoid__create__(intcls, inttag, string(8bit)raw, array(.Types.Object) elements)

Method create: Standards.ASN1.Decode.ConstructedStandards.ASN1.Decode.Constructed(intcls, inttag, string(8bit)raw, array(.Types.Object) elements)

Method get_der_content: string(8bit)get_der_content()
Description: Get raw encoded contents of object

Class Standards.ASN1.Decode.Primitive

Description: Primitive unconstructed ASN1 data type.

Inherit Object: inherit Types.Object : Object

Variable cls
Variable tag
Variable raw: int Standards.ASN1.Decode.Primitive.cls
int Standards.ASN1.Decode.Primitive.tag
string(8bit) Standards.ASN1.Decode.Primitive.raw

Method __create__: protectedlocalvoid__create__(intcls, inttag, string(8bit)raw)

Method create: Standards.ASN1.Decode.PrimitiveStandards.ASN1.Decode.Primitive(intcls, inttag, string(8bit)raw)

Method get_der_content: string(8bit)get_der_content()
Description: Get raw encoded contents of object

Module Standards.ASN1.Types

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

Variable TaggedType0
Variable TaggedType1
Variable TaggedType2
Variable TaggedType3

MetaExplicit Standards.ASN1.Types.TaggedType0
MetaExplicit Standards.ASN1.Types.TaggedType1
MetaExplicit Standards.ASN1.Types.TaggedType2
MetaExplicit Standards.ASN1.Types.TaggedType3

Description

Some common explicit tags for convenience.

These are typically used to indicate which of several optional fields are present.

Example

Eg RFC 5915 section 3:
ECPrivateKey ::= SEQUENCE {
      version        INTEGER { ecPrivkeyVer1(1)}(ecPrivkeyVer1),
      privateKey     OCTET STRING,
      parameters [0] ECParameters {{ NamedCurve }} OPTIONAL,
      publicKey  [1] BIT STRING OPTIONAL
    }
The presence of the fields parameters and publicKey above
   are indicated with TaggedType0 and TaggedType1 respectively.

Method asn1_IA5_valid: boolasn1_IA5_valid(strings)

Method asn1_bmp_valid: boolasn1_bmp_valid(strings)

Method asn1_broken_teletex_valid: boolasn1_broken_teletex_valid(strings)

Method asn1_printable_valid: boolasn1_printable_valid(strings)
Description: Checks if a Pike string can be encoded as a PrintableString.

Method asn1_universal_valid: int(0)asn1_universal_valid(strings)

Method asn1_utf8_valid: int(1)asn1_utf8_valid(strings)
Description: Checks if a Pike string can be encoded with UTF8. That is always the case...

Method extract_cls: int(2bit)extract_cls(int(0..)i)
Description: Extract ASN1 type class from a combined tag.
See also: make_combined_tag

Method extract_tag: int(0..)extract_tag(int(0..)i)
Description: Extract ASN1 type tag from a combined tag.
See also: make_combined_tag

Method make_combined_tag: int(0..)make_combined_tag(int(2bit)cls, int(0..)tag)
Description: Combines tag and class to a single integer, for internal uses.
Parameter cls: ASN1 type class.
Parameter tag: ASN1 type tag.
Returns: The combined tag.
See also: extract_tag, extract_cls

Class Standards.ASN1.Types.BMPString

Annotations

@Pike.Annotations.Implements(Object)

Description

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.

Inherit OctetString: inherit OctetString : OctetString

Class Standards.ASN1.Types.BitString

Annotations

@Pike.Annotations.Implements(Object)

Description

Bit string object

Inherit Object: inherit Object : Object

Variable value: string(8bit) Standards.ASN1.Types.BitString.value
Description: value of object

Method set_from_ascii: this_programset_from_ascii(string(8bit)s)
Description: Set the bitstring value as a string with "1" and "0".

Method set_length: this_programset_length(intlen)
Description: Sets the length of the bit string to len number of bits. Will only work correctly on strings longer than len bits.

Class Standards.ASN1.Types.Boolean

Annotations

@Pike.Annotations.Implements(Object)

Description

boolean object

Inherit Object: inherit Object : Object

Variable value: int Standards.ASN1.Types.Boolean.value
Description: value of object

Class Standards.ASN1.Types.BrokenTeletexString

Annotations

@Pike.Annotations.Implements(Object)

Description

(broken) TeletexString object

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

Inherit String: inherit String : String

Class Standards.ASN1.Types.Compound

Annotations

@Pike.Annotations.Implements(Object)

Description

Compound object primitive

Inherit Object: inherit Object : Object

Constant constructed: constantint Standards.ASN1.Types.Compound.constructed

Variable elements: array(Object) Standards.ASN1.Types.Compound.elements
Description: Contents of compound object.

Class Standards.ASN1.Types.Enumerated

Annotations

@Pike.Annotations.Implements(Object)

Description

Enumerated object

Inherit Integer: inherit Integer : Integer

Class Standards.ASN1.Types.GeneralizedTime

Annotations

@Pike.Annotations.Implements(UTC)

Inherit UTC: inherit UTC : UTC

Method get_posix: intget_posix()

Method set_posix: variantthis_programset_posix(Calendar.ISO_UTC.Secondsecond)

Class Standards.ASN1.Types.IA5String

Annotations

@Pike.Annotations.Implements(Object)

Description

IA5 String object

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

Inherit String: inherit String : String

Class Standards.ASN1.Types.Identifier

Annotations

@Pike.Annotations.Implements(Object)

Description

Object identifier object

Inherit Object: inherit Object : Object

Variable id: array(int) Standards.ASN1.Types.Identifier.id
Description: value of object

Method append: this_programappend(int ... args)
Description: Returns a new Identifier object with args appended to the ID path.

Class Standards.ASN1.Types.Integer

Annotations

@Pike.Annotations.Implements(Object)

Description

Integer object All integers are represented as bignums, for simplicity

Inherit Object: inherit Object : Object

Variable value: Gmp.mpz Standards.ASN1.Types.Integer.value
Description: value of object

Class Standards.ASN1.Types.MetaExplicit

Description

Meta-instances handle a particular explicit tag and set of types. Once cloned this object works as a factory for Compound objects with the cls and tag that the meta object was initialized with.

Example

MetaExplicit m = MetaExplicit(1,2);
   Compound c = m(Integer(3));

Method create: Standards.ASN1.Types.MetaExplicitStandards.ASN1.Types.MetaExplicit(int(2bit)cls, int(0..)tag, mapping(int:program)|voidtypes)

Class Standards.ASN1.Types.MetaExplicit.`()

Annotations

@Pike.Annotations.Implements(Object)

Inherit Compound: inherit Compound : Compound

Class Standards.ASN1.Types.Null

Annotations

@Pike.Annotations.Implements(Object)

Description

Null object

Inherit Object: inherit Object : Object

Class Standards.ASN1.Types.Object

Description: Generic, abstract base class for ASN1 data types.

Constant constructed: constantint Standards.ASN1.Types.Object.constructed
Description: Flag indicating whether this type is a constructed (aka Compound) type or not.

Constant type_name: constantstring Standards.ASN1.Types.Object.type_name
Description: ASN1 type name.

Variable cls: int(2bit) Standards.ASN1.Types.Object.cls
Description: ASN1 type class.

Variable tag: int(0..) Standards.ASN1.Types.Object.tag
Description: ASN1 type tag.

Method get_cls: int(2bit)get_cls()
Description: Get the class of this object.
Returns: The class of this object.

Method get_combined_tag: int(0..)get_combined_tag()
Description: Get the combined tag (tag + class) for this object.
Returns: the combined tag header

Method get_der: string(8bit)get_der()
Description: Get the DER encoded version of this object.
Returns: DER encoded representation of this object.

Method get_tag: int(0..)get_tag()
Description: Get the tag for this object.
Returns: The tag for this object.

Class Standards.ASN1.Types.OctetString

Annotations

@Pike.Annotations.Implements(Object)

Description

Octet string object

Inherit String: inherit String : String

Class Standards.ASN1.Types.PrintableString

Annotations

@Pike.Annotations.Implements(Object)

Description

PrintableString object

Inherit String: inherit String : String

Class Standards.ASN1.Types.Real

Annotations

@Pike.Annotations.Implements(Object)

Inherit Object: inherit Object : Object

Class Standards.ASN1.Types.Sequence

Annotations

@Pike.Annotations.Implements(Object)

Description

Sequence object

Inherit Compound: inherit Compound : Compound

Class Standards.ASN1.Types.Set

Annotations

@Pike.Annotations.Implements(Object)

Description

Set object

Inherit Compound: inherit Compound : Compound

Class Standards.ASN1.Types.String

Annotations

@Pike.Annotations.Implements(Object)

Description

string object primitive

Inherit Object: inherit Object : Object

Variable value: string Standards.ASN1.Types.String.value
Description: value of object

Class Standards.ASN1.Types.UTC

Annotations

@Pike.Annotations.Implements(Object)

Description

UTCTime

RFC 2459 section 4.1.2.5.1

Inherit String: inherit String : String

Method get_posix: intget_posix()

Method set_posix: variantthis_programset_posix(Calendar.ISO_UTC.Secondsecond)

Class Standards.ASN1.Types.UTF8String

Annotations

@Pike.Annotations.Implements(Object)

Description

UTF8 string object

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

Variable width encoding, see RFC 2279.

Inherit String: inherit String : String

Class Standards.ASN1.Types.UniversalString

Annotations

@Pike.Annotations.Implements(Object)

Description

Universal String object

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

FIXME

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

Inherit OctetString: inherit OctetString : OctetString

Class Standards.ASN1.Types.VisibleString

Annotations

@Pike.Annotations.Implements(Object)

Inherit String: inherit String : String

Module Standards.BSON

Description: Tools for handling the BSON structured data format. See http://www.bsonspec.org/.

Inherit _BSON: inherit Standards._BSON : _BSON

Variable MaxKey: object Standards.BSON.MaxKey

Variable MinKey: object Standards.BSON.MinKey

Method decode: mixeddecode(stringbson)
Description: Decode a BSON formatted document string into a native Pike data structure.

Method decode_array: arraydecode_array(stringbsonarray)
Description: Decode a BSON formatted string containing multiple data structures

Method encode: stringencode(array|mappingm, int|voidquery_mode)
Description: Encode a data structure as a BSON document.
Parameter query_mode: if set to true, encoding will allow "$" and "." in key names, which would normally be disallowed.

Class Standards.BSON.Binary

Method create: Standards.BSON.BinaryStandards.BSON.Binary(stringdata, int|voidsubtype)

Class Standards.BSON.Javascript

Method create: Standards.BSON.JavascriptStandards.BSON.Javascript(string_data, void|mapping_scope)

Class Standards.BSON.ObjectId

Method create: Standards.BSON.ObjectIdStandards.BSON.ObjectId(string|void_id)

Class Standards.BSON.Regex

Method create: Standards.BSON.RegexStandards.BSON.Regex(stringregex, void|stringoptions)

Class Standards.BSON.Symbol

Method create: Standards.BSON.SymbolStandards.BSON.Symbol(string_data)

Class Standards.BSON.Timestamp

Method create: Standards.BSON.TimestampStandards.BSON.Timestamp()

Module Standards.EXIF

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

Method get_properties: mapping(string:mixed) get_properties(Stdio.BlockFilefile, void|mappingtags)
Description: Parses and returns all EXIF properties.
Parameter file: A JFIF file positioned at the start.
Parameter tags: An optional list of tags to process. If given, all unknown tags will be ignored.
Returns: A mapping with all found EXIF properties.

Module Standards.FIPS10_4

Description

This module implements the FIPS10-4 standard for short-form codes of "Countries, Dependencies, Areas of Special Sovereignty, and Their Principal Administrative Divisions."

This is a list of two-letter country codes used by the US government until 2008-10-02, when GENC, based on ISO 3166 replaced it as the prefered standard. The subdivisions are named using the main region name followed by two digits.

This list is similar to, but not entirely compatible with, ISO-3166 alpha-2.

Method division_code_to_line

array(string) division_code_to_line(stringcode)

Description

Convert a division code to the information about the division. As an example division_code_to_line("sw16") would return

({"SW","SW16","Ostergotlands Lan","province/lan"})

Returns

Array

stringregion

stringdivision

stringname

stringtype

Method division_code_to_name: stringdivision_code_to_name(stringcode)
Description: Similar to division_code_to_line(), but only returns the name

Method division_guess_to_codes

array(string) division_guess_to_codes(stringcode)

Description

Return an array of possible division codes given a division name.

Returns

Array

array(string) regions

Array

stringregion

stringdivision

stringname

stringtype

Method division_guess_to_lines

array(array(string)) division_guess_to_lines(stringname)

Description

Return an array of possible divisions given a division name.

Returns

Array

array(string) regions

Array

stringregion

stringdivision

stringname

stringtype

Method division_name_to_line
Method division_name_to_code

array(string) division_name_to_line(stringname)
stringdivision_name_to_code(stringcode)

Description

Lookup a division by name.

These aren't really all that useful, since there might very well be multiple divisions with the same name.

division_guess_to_lines() and division_guess_to_codes() are more useful.

Method region_code_to_name: stringregion_code_to_name(stringcode)
Description: Convert a region (country etc) code to the name of the region. As an example, region_code_to_name("se") would return "SEYCHELLES".

Method region_name_to_code: stringregion_name_to_code(stringcode)
Description: The reverse of region_code_to_name(), region_name_to_code("Sweden") would return "SW".

Method region_to_division_codes: array(string) region_to_division_codes(stringregion)
Description: Given a region (country etc) return all divisions codes in that region

Method region_to_divisions

array(array(string)) region_to_divisions(stringregion)

Description

Given a region (country etc) return all divisions in that region

Returns

Array

array(string) regions

Array

stringregion

stringdivision

stringname

stringtype

Module Standards.ID3

Description: ID3 decoder/encoder. Supports versions 1.0, 1.1, 2.2-2.4. For more info see http://www.id3.org
Note: Note that this implementation is far from complete and that interface changes might be necessary during the implementation of the full standard.

Method decode_string: stringdecode_string(stringin, inttype)
Description: Decodes the string in from the type, according to ID3v2.4.0-structure section 4, into a wide string.
See also: encode_string

Method encode_string: array(string|int) encode_string(stringin)
Description: 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.
See also: decode_string, encode_strings

Method encode_strings: array(string|int) encode_strings(array(string) in)
Description: 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.
See also: decode_string, encode_string

Method int_to_synchsafe: array(int) int_to_synchsafe(intin, void|intno_bytes)
Description: Encodes a integer to a synchsafe integer according to ID3v2.4.0-structure section 6.2.
See also: synchsafe_to_int

Method resynchronise: stringresynchronise(stringin)
Description: Reverses the effects of unsyncronisation done according to ID3v2.4.0-structure section 6.1.
See also: unsynchronise

Method synchsafe_to_int: intsynchsafe_to_int(array(int) bytes)
Description: Decodes a synchsafe integer, generated according to ID3v2.4.0-structure section 6.2.
See also: int_to_synchsafe

Method unsynchronise: stringunsynchronise(stringin)
Description: Unsynchronises the string according to ID3v2.4.0-structure section 6.1.
See also: resynchronise

Class Standards.ID3.Buffer

Description: A wrapper around a Stdio.File object that provides a read limit capability.

Variable buffer: Stdio.File Standards.ID3.Buffer.buffer

Method __create__: protectedlocalvoid__create__(Stdio.Filebuffer)

Method bytes_left: intbytes_left()
Description: The number of bytes left before reaching the limit set by set_limit.

Method create: Standards.ID3.BufferStandards.ID3.Buffer(Stdio.Filebuffer)

Method peek: stringpeek()
Description: Preview the next byte. Technically it is read from the encapsulated buffer and put locally to avoid seeking.

Method read: stringread(intbytes)
Description: 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.

Method set_limit: voidset_limit(intbytes)
Description: Set an artificial EOF bytes bytes further into the buffer.

Class Standards.ID3.ExtendedHeader

Method create: Standards.ID3.ExtendedHeaderStandards.ID3.ExtendedHeader(void|Bufferbuffer)

Method decode: voiddecode(Bufferbuffer)

Method encode: stringencode()

Class Standards.ID3.Frame

Description: Manages the common frame information.

Method create: Standards.ID3.FrameStandards.ID3.Frame(string|Bufferin, TagHeaderthd)

Class Standards.ID3.FrameData

Description: Abstract class for frame data.

Method changed: boolchanged()
Description: Is the content altered?

Method create: Standards.ID3.FrameDataStandards.ID3.FrameData(void|stringdata)

Class Standards.ID3.Tag

Description: 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.
Note: Version 1 tag is searched only if version 2 isn't found.
See also: Tagv2, Tagv1

Constant version: constant Standards.ID3.Tag.version
Description: The version of the encapsulated tag in the form "%d.%d.%d".

Method _indices: arrayindices(Standards.ID3.Tagarg)
Description: Indices will return the indices of the tag object.

Method _values: arrayvalues(Standards.ID3.Tagarg)
Description: Values will return the values of the tag object.

Method `[]
Method `->: mixed res = Standards.ID3.Tag()[ index ]
mixed res = Standards.ID3.Tag()->X
Description: The index operators are overloaded to index the encapsulated Tagv1 or Tagv2 object.

Method create: Standards.ID3.TagStandards.ID3.Tag(Stdio.Filefd)
Description: The file object fd is searched for version 2 tags, and if not found, version 1 tags.
Throws: If no tag was found in the file an error is thrown.

Method friendly_values

mapping(string:string) friendly_values()

Description

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" : string`	Takes its value from TPE1 or TP1 frames.
`"album" : string`	Takes its value from TALB or TAL frames.
`"title" : string`	Takes its value from TIT2 or TT2 frames.
`"genre" : string`	Takes its value from TCON or TCM frames.
`"year" : string`	Takes its value from TYER or TYE frames.
`"track" : string`	Takes its value from TRCK or TRK frames. The string may be either in the `"%d"` form or in the `"%d/%d"` form.

Class Standards.ID3.TagHeader

Description: Represents an ID3v2 header.

Method create: Standards.ID3.TagHeaderStandards.ID3.TagHeader(void|Bufferbuffer)

Method decode: voiddecode(Bufferbuffer)
Description: Decode a tag header from buffer and store its data in this object.

Method encode: stringencode()
Description: Encode the data in this tag and return as a string.

Method set_flag_unsynchronisation: boolset_flag_unsynchronisation(array(Frame) frames)
Description: Should the unsynchronisation flag be set or not?

Class Standards.ID3.Tagv1

Description: 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.

Class Standards.ID3.Tagv2

Description: ID3 version 2 (2.2, 2.3, 2.4) Tags

Method create: Standards.ID3.Tagv2Standards.ID3.Tagv2(void|Buffer|Stdio.Filebuffer, void|bool_best_effort)

Module Standards.IDNA

Description: This module implements various algorithms specified by the Internationalizing Domain Names in Applications (IDNA) memo by the Internet Engineering Task Force (IETF), see RFC 3490.

Variable Punycode: object Standards.IDNA.Punycode
Description: Punycode transcoder, see RFC 3492. Punycode is used by to_ascii as an "ASCII Compatible Encoding" when needed.

Method nameprep: stringnameprep(strings, bool|voidallow_unassigned)
Description: Prepare a Unicode string for ACE transcoding. Used by to_ascii. Nameprep is a profile of Stringprep, which is described in RFC 3454.
Parameter s: The string to prep.
Parameter allow_unassigned: Set this flag the the string to transform is a "query string", and not a "stored string". See RFC 3454.

Method to_ascii: string(7bit)to_ascii(strings, bool|voidallow_unassigned, bool|voiduse_std3_ascii_rules)
Description: 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.
Parameter s: The sequence of Unicode code points to transform.
Parameter allow_unassigned: Set this flag if the the string to transform is a "query string", and not a "stored string". See RFC 3454.
Parameter use_std3_ascii_rules: Set this flag to enforce the restrictions on ASCII characters in host names imposed by STD3.

Method to_unicode: stringto_unicode(strings)
Description: 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.
Parameter s: The sequence of Unicode code points to transform.

Method zone_to_ascii: string(7bit)zone_to_ascii(strings, bool|voidallow_unassigned, bool|voiduse_std3_ascii_rules)
Description: Takes a sequence of labels separated by '.' and applies to_ascii on each.

Method zone_to_unicode: stringzone_to_unicode(strings)
Description: Takes a sequence of labels separated by '.' and applies to_unicode on each.

Module Standards.IIM

Description

IPTC Information Interchange Model data (aka "IPTC header") extraction.

http://www.iptc.org/IIM/

Method get_information

mapping(string(7bit):array(string)) get_information(Stdio.InputStreamfd)

Description

Get IPTC information from an open file.

Supported embedding formats are:

PhotoShop Document (aka PSD).
Postscript and Embedded Postscript.
Joint Picture Experts Group (aka JPEG).

Returns

Returns a mapping containing any found IPTC IIM data.

Module Standards.ISO639_2

Method convert_b_to_t: string|zeroconvert_b_to_t(stringcode)
Description: Converts an ISO 639-2/B code to an ISO 639-2/T code.

Method convert_t_to_b: string|zeroconvert_t_to_b(stringcode)
Description: Converts an ISO 639-2/T code to an ISO 639-2/B code.

Method get_language: stringget_language(stringcode)
Description: 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.

Method get_language_b: stringget_language_b(stringcode)
Description: Look up the language name given an ISO 639-2/B code in lower case. Returns zero typed zero on failure.

Method get_language_t: stringget_language_t(stringcode)
Description: Look up the language name given an ISO 639-2/T code in lower case. Returns zero typed zero on failure.

Method list_639_1: mapping(string:string) list_639_1()
Description: Return a mapping from ISO 639-1 code to ISO 639-2/T code.

Method list_languages: mapping(string:string) list_languages()
Description: Return a mapping from ISO 639-2/T + ISO 639-2/B codes to language names.

Method list_languages_b: mapping(string:string) list_languages_b()
Description: Return a mapping from ISO 639-2/B codes to language names.

Method list_languages_t: mapping(string:string) list_languages_t()
Description: Return a mapping from ISO 639-2/T codes to language names.

Method map_639_1: stringmap_639_1(stringcode)
Description: Look up the ISO 639-2/T code given an ISO 639-1 code in lower case.

Method map_to_639_1: stringmap_to_639_1(stringcode)
Description: Look up the ISO 639-1 code given an ISO 639-2/T code in lower case.

Module Standards.JSON

Description: Tools for handling the JSON structured data format. See http://www.json.org/ and RFC 4627.

Constant ASCII_ONLY
Constant HUMAN_READABLE
Constant PIKE_CANONICAL
Constant CANONICAL

constant Standards.JSON.ASCII_ONLY
constant Standards.JSON.HUMAN_READABLE
constant Standards.JSON.PIKE_CANONICAL
constant Standards.JSON.CANONICAL

Description

Bit field flags for use with encode:

Standards.JSON.ASCII_ONLY

Use \uxxxx escapes for all non-ascii characters and DEL (U+007f). The default is to escape only the characters that must be escaped. The flag value is 1.

Characters above U+FFFF are encoded using escaped surrogate pairs, as per RFC 4627.

Standards.JSON.HUMAN_READABLE

Pretty print with indentation to make the result easier on human eyes. The default is to use no extra whitespace at all. The flag value is 2.

Standards.JSON.PIKE_CANONICAL

Make the output canonical, so that the same value always generates the same char-by-char equal string. In practice this means that mapping elements are sorted on their indices. Note that the other flags take precedence, so e.g. the canonical form with HUMAN_READABLE is not the same as the canonical form without it. The flag value is 4.

This canonical form is stable for the encode function, providing floats aren't used (their formatting is currently affected by float size and libc formatting code). In the future there may be a standardized canonical form which quite likely will be different from this one. In that case a separate flag has to be added so this one doesn't change - hence the name PIKE_CANONICAL. See also CANONICAL below.

Standards.JSON.CANONICAL

Make the output canonical as per RFC 8785, so that the same value always generates the same char-by-char equal string. The flag value is 8.

Note that RFC 8785-compliant output will only be generated if this is the only flag that has been set and no indentation has been requested, and Pike.get_runtime_info()->float_size == 64. In other cases a best effort attempt to comply with RFC 8785 will be performed, but deviations may occur.

Constant NO_OBJECTS

constant Standards.JSON.NO_OBJECTS

Description

Bit field flags for use with decode:

Standards.JSON.NO_OBJECTS: Do not decode "true", "false" and "null" into Val.true, Val.false and Val.null, but instead 1, 0 and UNDEFINED.

Variable true
Variable false
Variable null: Val.True Standards.JSON.true
Val.False Standards.JSON.false
Val.Null Standards.JSON.null
Description: Compat aliases for the corresponding Val objects. These are used to represent the three JSON literals true, false and null.
Deprecated: Replaced by Val.true, Val.false and Val.null.

Method decode: array|mapping|string|float|int|objectdecode(strings, void|intflags)
Description: Decodes a JSON string.
Parameter flags: The flag NO_OBJECTS can be used to output 1, 0 and UNDEFINED instead of Val.true, Val.false and Val.null.
Throws: Throws an exception in case the data contained in s is not valid JSON.

Method decode_utf8: array|mapping|string|float|int|objectdecode_utf8(strings)
Description: Decodes an utf8 encoded JSON string. Should give the same result as Standards.JSON.decode(utf8_to_string(s)).
Throws: Throws an exception in case the data contained in s is not valid JSON.

Method encode: stringencode(int|float|string|array|mapping|objectval, void|intflags, void|function(:void)|object|program|stringcallback)
Description: Encodes a value to a JSON string.
Parameter val: The value to encode. It can contain integers, floats (except the special numbers NaN and infinity), strings, arrays, mappings with string indices, and the special object values null, true and false defined in this module (or really any object that implements an encode_json callback or is handled by the supplied callback argument).
Parameter flags: Flag bit field to control formatting. See ASCII_ONLY, HUMAN_READABLE and PIKE_CANONICAL for further details.
Parameter callback: A function that will be called for types that can not be encoded otherwise. It will be called with the value to be encoded as the first argument, and optionally with flags and indent arguments. If a string is supplied, it will be used to replace the value verbatim. The callback must return a string or throw an error.
Note: 8-bit and wider characters in input strings are neither escaped nor utf-8 encoded by default. string_to_utf8 can be used safely on the returned string to get a valid transport encoded JSON string. See escape_string for further details on string escaping.
See also: escape_string

Method escape_string

stringescape_string(stringstr, void|intflags)

Description

Escapes string data for use in a JSON string.

8-bit and wider characters in input strings are neither escaped nor utf-8 encoded by default. string_to_utf8 can be used safely on the returned string to get a valid transport encoded JSON string.

The characters U+2028 (LINE SEPARATOR) and U+2029 (PARAGRAPH SEPARATOR) are exceptions - they are encoded with \u escapes for compatibility. The reason is that those characters are not allowed in Javascript strings, so JSON parsers built in Javascript may have trouble with them otherwise.

Parameter val

The string to escape.

Parameter flags

Flag bit field to control formatting. ASCII_ONLY is the only flag that has any effect for this function.

Note

The difference between using this function and encode on a string is that encode returns quotations marks around the result.

See also

encode

Method validate: intvalidate(strings)
Description: Checks if a string is valid JSON.
Returns: In case the string contains valid JSON -1 is returned. It is then guaranteed to be parsed without errors by decode(). In case the string is not valid JSON, the error position is returned.

Method validate_utf8: intvalidate_utf8(strings)
Description: Checks if a string is valid utf8 encoded JSON.
Returns: In case the string contains valid JSON -1 is returned. It is then guaranteed to be parsed without errors by decode(). In case the string is not valid JSON, the integer position inside the string where the error occurs is returned.

Class Standards.JSON.DecodeError

Description: Error thrown when JSON decode fails.

Inherit Generic: inherit Error.Generic : Generic

Variable err_pos: int Standards.JSON.DecodeError.err_pos
Description: The failing position in err_str.

Variable err_str: string Standards.JSON.DecodeError.err_str
Description: The string that failed to be decoded.

Class Standards.JSON.Validator

Description

An instance of this class can be used to validate a JSON object against a JSON schema.

Example

string schema_s = "{\n" +
       "  \"name\": \"SomeExample\",\n" +
       "  \"type\": \"object\",\n" +
       "  \"properties\": {\n" +
       "      \"name\": { \"type\": \"string\" },\n" +
       "      \"id\": {\n" +
       "          \"type\": \"integer\",\n" +
       "          \"minimum\": 0\n" +
       "      }\n" +
       "  }\n" +
       "}";
   string example_s = "{\n" +
       "  \"name\": \"An Example\",\n" +
       "  \"id\": 17\n" +
       "}";
   mixed schema = Standards.JSON.decode(schema_s);
   mixed example = Standards.JSON.decode(example_s);
   if (string error = Standards.JSON.Validator(schema).validate(example))
      werror("Error: JSON string %O did not validate: %s\n", example_s, error);
   else
      write("JSON ok\n");

Note

This class validates only a subset of the JSON schema specification. Currently dependencies and references are not handled and regular expressions (for pattern properties) are limited to those that can be handled by Regexp.SimpleRegexp.

For more information of JSON schema look at http://json-schema.org/documentation.html "The home of JSON Schema".

Method create: Standards.JSON.ValidatorStandards.JSON.Validator(mixed_schema)
Description: Create a JSON validator for some JSON schema.
Parameter _schema: The JSON schema to use in validate(). This must be a valid JSON object.
Throws: Throws an error if the schema is invalid.

Method has_schema_array: privateboolhas_schema_array(mapping(string:mixed) schema, stringproperty)
Description: Test if the schema has the specified property and the value of the property is an array.
Throws: Throws an error if the value of the property is no array.
Returns: 1 if the schema has the specified property.

Method has_schema_array_mapping: privateboolhas_schema_array_mapping(mapping(string:mixed) schema, stringproperty)
Description: Test if the schema has the specified property and the value of the property is an array(mapping).
Throws: Throws an error if the value of the property is no array(mapping).
Returns: 1 if the schema has the specified property.

Method has_schema_array_string: privateboolhas_schema_array_string(mapping(string:mixed) schema, stringproperty)
Description: Test if the schema has the specified property and the value of the property is an array(string).
Throws: Throws an error if the value of the property is no array(string).
Returns: 1 if the schema has the specified property.

Method has_schema_boolean: privateboolhas_schema_boolean(mapping(string:mixed) schema, stringproperty)
Description: Test if the schema has the specified property and the value of the property is a boolean (with values Standards.JSON.true or Standards.JSON.false).
Throws: Throws an error if the value of the property is no boolean.
Returns: 1 if the schema has the specified property.

Method has_schema_integer: privateboolhas_schema_integer(mapping(string:mixed) schema, stringproperty)
Description: Test if the schema has the specified property and the value of the property is an integer.
Throws: Throws an error if the value of the property is no integer.
Returns: 1 if the schema has the specified property.

Method has_schema_mapping: privateboolhas_schema_mapping(mapping(string:mixed) schema, stringproperty)
Description: Test if the schema has the specified property and the value of the property is a mapping.
Throws: Throws an error if the value of the property is no mapping.
Returns: 1 if the schema has the specified property.

Method has_schema_mapping_mapping: privateboolhas_schema_mapping_mapping(mapping(string:mixed) schema, stringproperty)
Description: Test if the schema has the specified property and the value of the property is a mapping(string:mapping).
Throws: Throws an error if the value of the property is no mapping(string:mapping).
Returns: 1 if the schema has the specified property.

Method has_schema_number: privateboolhas_schema_number(mapping(string:mixed) schema, stringproperty)
Description: Test if the schema has the specified property and the value of the property is a number (integer or float).
Throws: Throws an error if the value of the property is no number.
Returns: 1 if the schema has the specified property.

Method has_schema_string: privateboolhas_schema_string(mapping(string:mixed) schema, stringproperty)
Description: Test if the schema has the specified property and the value of the property is a string.
Throws: Throws an error if the value of the property is no string.
Returns: 1 if the schema has the specified property.

Method is_JSON_boolean: privateboolis_JSON_boolean(mixedvalue)
Returns: 1 if the specified value is either Standards.JSON.true or Standards.JSON.false.

Method validate: string|zerovalidate(mixedjson)
Description: This function validates a JSON object against the JSON schema that was specified in the Validator's constructor. If the JSON object is not valid, a string with an error-message is returned. If the JSON object is valid, 0 is returned.
Parameter json: The JSON object to validate.
Returns: 0, if the json object is valid, and an error-message if it is not valid.

Method validate_array

privatestring|zerovalidate_array(stringkey, mixedvalue, mapping(string:mixed) schema)

Description

Verify that the specified value is an array according to the specified schema. The following properties of schema are verified:

minItems: If schema has the property "minItems", then the array must have at least the specified number of items.
maxItems: If schema has the property "maxItems", then the array must not have more than the specified number of items.
items: If schema has the property "items", which is an array of schema objects, then each element in the value array must be valid according the corresponding schema in the "items" array.

Method validate_integer

privatestring|zerovalidate_integer(stringkey, mixedvalue, mapping(string:mixed) schema)

Description

Verify that the specified value is an integer according to the specified schema. This is the similar to validate_number(), but the value must be an int and not a float. The following properties of schema are verified:

minimum: If the schema has the property "minimum", then the value must be greater than or equal to the specified minimum.
exclusiveMinimum: If the schema has the properties "minimum" and "exclusiveMinimum" is Standards.JSON.true, then the value must be greater than the specified minimum.
maximum: If the schema has the property "maximum", then the value must be lower than or equal to the specified maximum.
exclusiveMaximum: If the schema has the properties "maximum" and "exclusiveMaximum" is Standards.JSON.true, then the value must be lower than the specified minimum.
multipleOf: If schema has the property "multipleOf", then the value must be an integer multiple of the specified multpleOf.

Method validate_item_type

privatestring|zerovalidate_item_type(stringkey, mixedvalue, mappingschema)

Description

Verify that the specified value has the correct type that is defined by schema->type. schema->type can be any of

"boolean",
"integer",
"number",
"string",
"array",
"object",
"null",

or an array of these.

Method validate_number

privatestring|zerovalidate_number(stringkey, mixedvalue, mapping(string:mixed) schema)

Description

Verify that the specified value is a number (integer or float) according to the specified schema. The following properties of schema are verified:

minimum: If the schema has the property "minimum", then the value must be greater than or equal to the specified minimum.
exclusiveMinimum: If the schema has the properties "minimum" and "exclusiveMinimum" is Standards.JSON.true, then the value must be greater than the specified minimum.
maximum: If the schema has the property "maximum", then the value must be lower than or equal to the specified maximum.
exclusiveMaximum: If the schema has the properties "maximum" and "exclusiveMaximum" is Standards.JSON.true, then the value must be lower than the specified minimum.
multipleOf: If schema has the property "multipleOf", then the value must be an integer multiple of the specified multpleOf.

Method validate_object

privatestring|zerovalidate_object(stringkey, mixedvalue, mapping(string:mixed) schema)

Description

Verify that the specified value is an object according to the specified schema. The following properties of schema are verified:

minProperties

If schema has the property "minProperties", then the object must have at least the specified number of properties.

maxProperties

If schema has the property "maxProperties", then the object must not have more than the specified number of items.

required

If schema has the property "required", which is an array of strings, then the object must have all properties that are listed in the specified array.

properties

If schema has the property "properties", which is a mapping of property-name to a schema, then each property of the object that has a corresponding schema in "properties" must be valid according to that schema.

patternProperties

If schema has the property "properties", which is a mapping of property-name-pattern to a schema, then each property of the object must be valid according to all schema objects for which the pattern matches the property-name.

additionalProperties

If schema has the property "additionalProperties", it can be either a boolean value, or a schema.

If it is a boolean with value Standards.JSON.false, then all properties of the object must be validated either by a schema from "properties" or "patternProperties".
If it is a boolean with value Standards.JSON.true, then the object is allowed to have additional properties without validation.
If it is a schema, then any propery of the object that is not validated by a schema from "properties" or "patternProperties" must be validated by the specified schema.

Note

TODO: We use Regexp.SimpleRegexp to handle schema->patternProperties, but that covers only some part of the possible regular expressions.

Method validate_properties

privatestring|zerovalidate_properties(stringkey, mixedvalue, mappingschema)

Description

Verify that the specified value matches the specified schema. The following properties of schema are verified:

type: If the schema has a property "type", then the value must match the specified type (see validate_item_type()).
allOf: If the schema has a property "allOf", which is an array of schema objects, then the value must match each schema specified in that array (via another call to validate_properties()).
anyOf: If the schema has a property "anyOf", which is an array of schema objects, then the value must match at least one schema specified in that array (via another call to validate_properties()).
oneOf: If the schema has a property "oneOf", which is an array of schema objects, then the value must match exactly one schema specified in that array (via another call to validate_properties()).
not: If the schema has a property "not", then the value must not match the schema specified by that property (via another call to validate_properties()).
enum: If the schema has a property "enum", then the value must be equal to any of the values specified in the enum array.

Note

If the schema is empty (i.e., it has none of the above specified properties, then the value is valid).

Method validate_string

privatestring|zerovalidate_string(stringkey, mixedvalue, mapping(string:mixed) schema)

Description

Verify that the specified value is a string according to the specified schema. The following properties of schema are verified:

minLength: If schema has the property "minLength", then the value must not be shorter than the specified length.
maxLength: If schema has the property "maxLength", then the value must not be longer than the specified length.
pattern: If schema has the property "pattern", then the value must match the specified pattern.

Note

TODO: We use Regexp.SimpleRegexp to handle schema->pattern, but that covers only some part of the possible regular expressions.

Module Standards.JSON5

Description: Tools for handling the JSON5 structured data format. See http://www.json5.org/ and RFC 4627.

Constant ASCII_ONLY
Constant HUMAN_READABLE
Constant PIKE_CANONICAL
Constant UNQUOTED_IDENTIFIERS
Constant SINGLE_QUOTED_STRINGS

constant Standards.JSON5.ASCII_ONLY
constant Standards.JSON5.HUMAN_READABLE
constant Standards.JSON5.PIKE_CANONICAL
constant Standards.JSON5.UNQUOTED_IDENTIFIERS
constant Standards.JSON5.SINGLE_QUOTED_STRINGS

Description

Bit field flags for use with encode:

Standards.JSON5.ASCII_ONLY

Use \uxxxx escapes for all non-ascii characters and DEL (U+007f). The default is to escape only the characters that must be escaped. The flag value is 1.

Characters above U+FFFF are encoded using escaped surrogate pairs, as per RFC 4627.

Standards.JSON5.HUMAN_READABLE

Pretty print with indentation to make the result easier on human eyes. The default is to use no extra whitespace at all. The flag value is 2.

Standards.JSON5.PIKE_CANONICAL

Standards.JSON5.UNQUOTED_IDENTIFIERS

When producing mapping keys, permit keys which are identifiers to be expressed without surrounding quotation marks.

Standards.JSON5.SINGLE_QUOTED_STRINGS

Use single quotation marks rather than double quotation marks when encoding string values.

Variable true
Variable false
Variable null: Val.True Standards.JSON5.true
Val.False Standards.JSON5.false
Val.Null Standards.JSON5.null
Description: Compat aliases for the corresponding Val objects. These are used to represent the three JSON5 literals true, false and null.
Deprecated: Replaced by Val.true, Val.false and Val.null.

Method decode: array|mapping|string|float|int|objectdecode(strings)
Description: Decodes a JSON5 string.
Throws: Throws an exception in case the data contained in s is not valid JSON5.

Method decode_utf8: array|mapping|string|float|int|objectdecode_utf8(strings)
Description: Decodes an utf8 encoded JSON5 string. Should give the same result as Standards.JSON5.decode(utf8_to_string(s)).
Throws: Throws an exception in case the data contained in s is not valid JSON5.

Method encode: stringencode(int|float|string|array|mapping|objectval, void|intflags, void|function(:void)|object|program|stringcallback)
Description: Encodes a value to a JSON5 string.
Parameter val: The value to encode. It can contain integers, floats (except the special numbers NaN and infinity), strings, arrays, mappings with string indices, and the special object values null, true and false defined in this module (or really any object that implements an encode_json5 callback or is handled by the supplied callback argument).
Parameter flags: Flag bit field to control formatting. See ASCII_ONLY, HUMAN_READABLE and PIKE_CANONICAL for further details.
Parameter callback: A function that will be called for types that can not be encoded otherwise. It will be called with the value to be encoded as the first argument, and optionally with flags and indent arguments. If a string is supplied, it will be used to replace the value verbatim. The callback must return a string or throw an error.
Note: 8-bit and wider characters in input strings are neither escaped nor utf-8 encoded by default. string_to_utf8 can be used safely on the returned string to get a valid transport encoded JSON5 string. See escape_string for further details on string escaping.
See also: escape_string

Method escape_string

stringescape_string(stringstr, void|intflags)

Description

Escapes string data for use in a JSON5 string.

8-bit and wider characters in input strings are neither escaped nor utf-8 encoded by default. string_to_utf8 can be used safely on the returned string to get a valid transport encoded JSON5 string.

The characters U+2028 (LINE SEPARATOR) and U+2029 (PARAGRAPH SEPARATOR) are exceptions - they are encoded with \u escapes for compatibility. The reason is that those characters are not allowed in Javascript strings, so JSON5 parsers built in Javascript may have trouble with them otherwise.

Parameter val

The string to escape.

Parameter flags

Flag bit field to control formatting. ASCII_ONLY is the only flag that has any effect for this function.

Note

The difference between using this function and encode on a string is that encode returns quotations marks around the result.

See also

encode

Method validate: intvalidate(strings)
Description: Checks if a string is valid JSON5.
Returns: In case the string contains valid JSON5 -1 is returned. It is then guaranteed to be parsed without errors by decode(). In case the string is not valid JSON5, the error position is returned.

Method validate_utf8: intvalidate_utf8(strings)
Description: Checks if a string is valid utf8 encoded JSON5.
Returns: In case the string contains valid JSON5 -1 is returned. It is then guaranteed to be parsed without errors by decode(). In case the string is not valid JSON5, the integer position inside the string where the error occurs is returned.

Class Standards.JSON5.DecodeError

Description: Error thrown when JSON5 decode fails.

Inherit Generic: inherit Error.Generic : Generic

Variable err_pos: int Standards.JSON5.DecodeError.err_pos
Description: The failing position in err_str.

Variable err_str: string Standards.JSON5.DecodeError.err_str
Description: The string that failed to be decoded.

Class Standards.JSON5.Validator

Description

An instance of this class can be used to validate a JSON5 object against a JSON5 schema.

Example

string schema_s = "{\n" +
       "  \"name\": \"SomeExample\",\n" +
       "  \"type\": \"object\",\n" +
       "  \"properties\": {\n" +
       "      \"name\": { \"type\": \"string\" },\n" +
       "      \"id\": {\n" +
       "          \"type\": \"integer\",\n" +
       "          \"minimum\": 0\n" +
       "      }\n" +
       "  }\n" +
       "}";
   string example_s = "{\n" +
       "  \"name\": \"An Example\",\n" +
       "  \"id\": 17\n" +
       "}";
   mixed schema = Standards.JSON5.decode(schema_s);
   mixed example = Standards.JSON5.decode(example_s);
   if (string error = Standards.JSON5.Validator(schema).validate(example))
      werror("Error: JSON5 string %O did not validate: %s\n", example_s, error);
   else
      write("JSON5 ok\n");

Note

This class validates only a subset of the JSON5 schema specification. Currently dependencies and references are not handled and regular expressions (for pattern properties) are limited to those that can be handled by Regexp.SimpleRegexp.

For more information of JSON5 schema look at http://json5-schema.org/documentation.html "The home of JSON5 Schema".

Method create: Standards.JSON5.ValidatorStandards.JSON5.Validator(mixed_schema)
Description: Create a JSON5 validator for some JSON5 schema.
Parameter _schema: The JSON5 schema to use in validate(). This must be a valid JSON5 object.
Throws: Throws an error if the schema is invalid.

Method has_schema_array: privateboolhas_schema_array(mapping(string:mixed) schema, stringproperty)
Description: Test if the schema has the specified property and the value of the property is an array.
Throws: Throws an error if the value of the property is no array.
Returns: 1 if the schema has the specified property.

Method has_schema_array_mapping: privateboolhas_schema_array_mapping(mapping(string:mixed) schema, stringproperty)
Description: Test if the schema has the specified property and the value of the property is an array(mapping).
Throws: Throws an error if the value of the property is no array(mapping).
Returns: 1 if the schema has the specified property.

Method has_schema_array_string: privateboolhas_schema_array_string(mapping(string:mixed) schema, stringproperty)
Description: Test if the schema has the specified property and the value of the property is an array(string).
Throws: Throws an error if the value of the property is no array(string).
Returns: 1 if the schema has the specified property.

Method has_schema_boolean: privateboolhas_schema_boolean(mapping(string:mixed) schema, stringproperty)
Description: Test if the schema has the specified property and the value of the property is a boolean (with values Standards.JSON5.true or Standards.JSON5.false).
Throws: Throws an error if the value of the property is no boolean.
Returns: 1 if the schema has the specified property.

Method has_schema_integer: privateboolhas_schema_integer(mapping(string:mixed) schema, stringproperty)
Description: Test if the schema has the specified property and the value of the property is an integer.
Throws: Throws an error if the value of the property is no integer.
Returns: 1 if the schema has the specified property.

Method has_schema_mapping: privateboolhas_schema_mapping(mapping(string:mixed) schema, stringproperty)
Description: Test if the schema has the specified property and the value of the property is a mapping.
Throws: Throws an error if the value of the property is no mapping.
Returns: 1 if the schema has the specified property.

Method has_schema_mapping_mapping: privateboolhas_schema_mapping_mapping(mapping(string:mixed) schema, stringproperty)
Description: Test if the schema has the specified property and the value of the property is a mapping(string:mapping).
Throws: Throws an error if the value of the property is no mapping(string:mapping).
Returns: 1 if the schema has the specified property.

Method has_schema_number: privateboolhas_schema_number(mapping(string:mixed) schema, stringproperty)
Description: Test if the schema has the specified property and the value of the property is a number (integer or float).
Throws: Throws an error if the value of the property is no number.
Returns: 1 if the schema has the specified property.

Method has_schema_string: privateboolhas_schema_string(mapping(string:mixed) schema, stringproperty)
Description: Test if the schema has the specified property and the value of the property is a string.
Throws: Throws an error if the value of the property is no string.
Returns: 1 if the schema has the specified property.

Method is_JSON5_boolean: privateboolis_JSON5_boolean(mixedvalue)
Returns: 1 if the specified value is either Standards.JSON5.true or Standards.JSON5.false.

Method validate: string|zerovalidate(mixedjson5)
Description: This function validates a JSON5 object against the JSON5 schema that was specified in the Validator's constructor. If the JSON5 object is not valid, a string with an error-message is returned. If the JSON5 object is valid, 0 is returned.
Parameter json5: The JSON5 object to validate.
Returns: 0, if the json5 object is valid, and an error-message if it is not valid.

Method validate_array

privatestring|zerovalidate_array(stringkey, mixedvalue, mapping(string:mixed) schema)

Description

Verify that the specified value is an array according to the specified schema. The following properties of schema are verified:

minItems: If schema has the property "minItems", then the array must have at least the specified number of items.
maxItems: If schema has the property "maxItems", then the array must not have more than the specified number of items.
items: If schema has the property "items", which is an array of schema objects, then each element in the value array must be valid according the corresponding schema in the "items" array.

Method validate_integer

privatestring|zerovalidate_integer(stringkey, mixedvalue, mapping(string:mixed) schema)

Description

minimum: If the schema has the property "minimum", then the value must be greater than or equal to the specified minimum.
exclusiveMinimum: If the schema has the properties "minimum" and "exclusiveMinimum" is Standards.JSON5.true, then the value must be greater than the specified minimum.
maximum: If the schema has the property "maximum", then the value must be lower than or equal to the specified maximum.
exclusiveMaximum: If the schema has the properties "maximum" and "exclusiveMaximum" is Standards.JSON5.true, then the value must be lower than the specified minimum.
multipleOf: If schema has the property "multipleOf", then the value must be an integer multiple of the specified multpleOf.

Method validate_item_type

privatestring|zerovalidate_item_type(stringkey, mixedvalue, mappingschema)

Description

Verify that the specified value has the correct type that is defined by schema->type. schema->type can be any of

"boolean",
"integer",
"number",
"string",
"array",
"object",
"null",

or an array of these.

Method validate_number

privatestring|zerovalidate_number(stringkey, mixedvalue, mapping(string:mixed) schema)

Description

Verify that the specified value is a number (integer or float) according to the specified schema. The following properties of schema are verified:

minimum: If the schema has the property "minimum", then the value must be greater than or equal to the specified minimum.
exclusiveMinimum: If the schema has the properties "minimum" and "exclusiveMinimum" is Standards.JSON5.true, then the value must be greater than the specified minimum.
maximum: If the schema has the property "maximum", then the value must be lower than or equal to the specified maximum.
exclusiveMaximum: If the schema has the properties "maximum" and "exclusiveMaximum" is Standards.JSON5.true, then the value must be lower than the specified minimum.
multipleOf: If schema has the property "multipleOf", then the value must be an integer multiple of the specified multpleOf.

Method validate_object

privatestring|zerovalidate_object(stringkey, mixedvalue, mapping(string:mixed) schema)

Description

Verify that the specified value is an object according to the specified schema. The following properties of schema are verified:

minProperties

If schema has the property "minProperties", then the object must have at least the specified number of properties.

maxProperties

If schema has the property "maxProperties", then the object must not have more than the specified number of items.

required

If schema has the property "required", which is an array of strings, then the object must have all properties that are listed in the specified array.

properties

patternProperties

additionalProperties

If schema has the property "additionalProperties", it can be either a boolean value, or a schema.

If it is a boolean with value Standards.JSON5.false, then all properties of the object must be validated either by a schema from "properties" or "patternProperties".
If it is a boolean with value Standards.JSON5.true, then the object is allowed to have additional properties without validation.
If it is a schema, then any propery of the object that is not validated by a schema from "properties" or "patternProperties" must be validated by the specified schema.

Note

TODO: We use Regexp.SimpleRegexp to handle schema->patternProperties, but that covers only some part of the possible regular expressions.

Method validate_properties

privatestring|zerovalidate_properties(stringkey, mixedvalue, mappingschema)

Description

Verify that the specified value matches the specified schema. The following properties of schema are verified:

type: If the schema has a property "type", then the value must match the specified type (see validate_item_type()).
allOf: If the schema has a property "allOf", which is an array of schema objects, then the value must match each schema specified in that array (via another call to validate_properties()).
anyOf: If the schema has a property "anyOf", which is an array of schema objects, then the value must match at least one schema specified in that array (via another call to validate_properties()).
oneOf: If the schema has a property "oneOf", which is an array of schema objects, then the value must match exactly one schema specified in that array (via another call to validate_properties()).
not: If the schema has a property "not", then the value must not match the schema specified by that property (via another call to validate_properties()).
enum: If the schema has a property "enum", then the value must be equal to any of the values specified in the enum array.

Note

If the schema is empty (i.e., it has none of the above specified properties, then the value is valid).

Method validate_string

privatestring|zerovalidate_string(stringkey, mixedvalue, mapping(string:mixed) schema)

Description

Verify that the specified value is a string according to the specified schema. The following properties of schema are verified:

minLength: If schema has the property "minLength", then the value must not be shorter than the specified length.
maxLength: If schema has the property "maxLength", then the value must not be longer than the specified length.
pattern: If schema has the property "pattern", then the value must match the specified pattern.

Note

TODO: We use Regexp.SimpleRegexp to handle schema->pattern, but that covers only some part of the possible regular expressions.

Module Standards.MsgPack

Description

Tools for handling the MsgPack data format. MsgPack is a binary serialization format with applications similar to JSON. However, MsgPack is more versatile and is able to serialize arbitrary objects using an extension format. The following table shows how some special Pike data types are encoded in the MsgPack format. All basic types, namely int, string, float, array and mapping are mapped onto their natural MsgPack counterparts. Note that the encoder does not use all integer and floating point lengths and in particular integers are never encoded as unsigned.

binary
Stdio.Buffer
nil
Val.null
true
Val.true
false
Val.false

All other types can be encoded and decoded using extension handlers.

Typedef decode_handler: typedeffunction(int(-127..128), Stdio.Buffer:mixed) Standards.MsgPack.decode_handler
Description: Function prototype for decode extension handlers. The first argument is the extension type identifier. The second argument is a Stdio.Buffer containing the payload.
See also: decode, decode_from

Typedef encode_handler: typedeffunction(Stdio.Buffer, mixed:void) Standards.MsgPack.encode_handler
Description: Function prototype for encode extension handlers. The first argument is the Stdio.Buffer, the second the value to encode. Use add_extension_header to generate the correct extension header.
See also: decode, decode_from

Method add_extension_header: voidadd_extension_header(Stdio.Bufferb, int(-128..127)type, int(0..)len)
Description: Adds an extension header to b for given type and payload length.

Method decode: mixeddecode(string(8bit)data, void|decode_handler|objecthandler)
Description: Decode one MsgPack encoded value from data.

Method decode_from: mixeddecode_from(Stdio.Bufferbuffer, void|decode_handler|objecthandler)
Description: Decode one MsgPack encoded value from the buffer.

Method default_handler: voiddefault_handler(Stdio.Bufferb, function(:void)|object|programv)
Description: Default encoding handler. Encodes Val.null, Val.true and Val.false.

Method encode: string(8bit)encode(mixedv, void|encode_handler|objecthandler)
Description: Encode v into a string.

Method encode_to: voidencode_to(Stdio.Bufferbuf, mixedv, void|encode_handler|objecthandler)
Description: Encode v into buf. If handler is not specified, it defaults to default_handler.

Class Standards.MsgPack.DecodeError

Description: Error thrown when MsgPack decoding fails.

Inherit Generic: inherit Error.Generic : Generic

Variable buffer: Stdio.Buffer Standards.MsgPack.DecodeError.buffer
Description: The data which failed to be decoded.

Variable err_pos: int Standards.MsgPack.DecodeError.err_pos
Description: The failing position in buffer.

Module Standards.PEM

Description: Support for parsing PEM-style messages, defined in RFC 1421. Encapsulation defined in RFC 0934.

Method build: stringbuild(stringtag, stringdata, void|mapping(string:string) headers, void|stringchecksum)
Description: Creates a PEM message, wrapped to 64 character lines.
Parameter tag: The encapsulation boundary string.
Parameter data: The data to be encapsulated.
Parameter headers: Optional mapping containing encapsulated headers as name value pairs.
Parameter checksum: Optional checksum string, added as per RFC 4880.

Method decrypt_body: string(8bit)decrypt_body(string(8bit)dek_info, string(8bit)body, string(8bit)password)
Description: Decrypt a PEM body.
Parameter dek_info: "dek-info" header from the Message.
Parameter body: Encypted PEM body.
Parameter password: Decryption password.
Returns: Returns the decrypted body text.

Method decrypt_fragment: string(8bit)|zerodecrypt_fragment(Messagem, string(8bit)pwd)
Description: Decrypt a PEM Message.
Parameter body: Fragment with encypted PEM body.
Parameter password: Decryption password.
Returns: Returns the decrypted body text.

Method derive_key

string(8bit)derive_key(string(8bit)password, string(8bit)salt, intbytes)

Description

Key derivation function used in PEM.

FIXME

Derived from OpenSSL. Is there any proper specification?

It seems to be related to PBKDF1 from RFC 2898.

Method simple_decode: string(8bit)|zerosimple_decode(string(8bit)pem)
Description: Convenience function that decodes a PEM message containing only one part, and returns it as a string. Returns 0 for indata containing no or multiple parts.

Class Standards.PEM.Message

Description: Represents a PEM-style message.

Variable body: string(8bit)|zero Standards.PEM.Message.body
Description: The decode message body.

Variable headers: mapping(string(8bit):string(8bit))|zero Standards.PEM.Message.headers
Description: Encapsulated headers. If headers occur multiple times, they will be concatenated separated by delimiting NUL characters.

Variable post

string|zero Standards.PEM.Message.post

Description

Post-encapsulation boundary string.

Usually the same value as pre.

Variable pre

string|zero Standards.PEM.Message.pre

Description

Pre-encapsulation boundary string.

Typically a string like "CERTIFICATE" or "PRIVATE KEY".

Variable trailer: string(8bit)|zero Standards.PEM.Message.trailer
Description: Message trailer, like RFC 4880 checksum.

Class Standards.PEM.Messages

Description: The Messages class acts as an envelope for a PEM message file or stream.

Variable fragments: array(string(8bit)|Message) Standards.PEM.Messages.fragments
Description: The fragments array contains the different message fragments, as Message objects for decoded messages and strings for non-messages or incomplete messages.

Variable parts: mapping(string(8bit):array(Message)) Standards.PEM.Messages.parts
Description: This is a mapping from encapsulation boundary string to Message objects. All message objects and surrounding text will be listed, in order, in fragments.

Method create: Standards.PEM.MessagesStandards.PEM.Messages(string(8bit)data)
Description: A Messages object is created with the file or stream data.

Method get_certificate: stringget_certificate()
Description: Convenience wrapper for get_certificates that returns the first available certificate, or 0.

Method get_certificates: array(string) get_certificates()
Description: Returns an array of all the bodies of "CERTIFICATE" and "X509 CERTIFICATE" fragments.

Method get_encrypted_private_key: string|zeroget_encrypted_private_key(string(8bit)pwd)
Description: Returns the first key, decoded by the pwd password.

Method get_fragment_bodies: array(string) get_fragment_bodies(multisetlabels)
Description: Returns an array of the string bodies of all fragments with any of the given labels in the boundy preamble.

Method get_fragments: array(Message) get_fragments(multisetlabels)
Description: Returns an array of all fragments with any of the given labels in the boundy preamble.

Method get_private_key: stringget_private_key()
Description: Convenience wrapper for get_private_key that returns the first available key, or 0.

Method get_private_keys: array(string) get_private_keys()
Description: Returns an array of all the bodies of "RSA PRIVATE KEY", "DSA PRIVATE KEY", "EC PRIVATE KEY" and "ANY PRIVATE KEY" fragments.

Module Standards.PKCS

Description

Public-Key Cryptography Standards (PKCS).

This is the Pike API for dealing with a set of standards initially published by RSA Security Inc, and later by IETF and others in various RFCs.

See also

Standards.ASN1, Crypto, RFC 2314, RFC 2459, RFC 2986, RFC 3279, RFC 3280, RFC 4055, RFC 4985, RFC 5208, RFC 5280, RFC 5480, RFC 5639, RFC 5915, RFC 5958, RFC 7292, RFC 7468

Method parse_private_key: Crypto.Sign.Stateparse_private_key(Sequenceseq)
Description: Parse a PKCS#8 PrivateKeyInfo (cf RFC 5208 section 5).
See also: parse_public_key(), RSA.parse_private_key(), DSA.parse_private_key()

Method parse_public_key: Crypto.Sign.Stateparse_public_key(Sequenceseq)
Description: Parse a PKCS#10 SubjectPublicKeyInfo (cf RFC 5280 section 4.1 and RFC 7468 section 13).
See also: parse_private_key(), RSA.parse_public_key(), DSA.parse_public_key()

Module Standards.PKCS.CSR

Description: Handling of Certificate Signing Requests (PKCS-10, RFC 2314, RFC 2986)

Method build_csr: Sequencebuild_csr(Crypto.Signsign, Sequencename, mapping(string:array(Object)) attributes, Crypto.Hash|voidhash)
Description: Build a Certificate Signing Request.
Parameter sign: Signature algorithm for the certificate. Both private and public keys must be set.
Parameter name: The distinguished name for the certificate.
Parameter attributes: Attributes from PKCS #9 to add to the certificate.
Parameter hash: Hash algoritm to use for the CSR signature. Defaults to Crypto.SHA256.
Note: Prior to Pike 8.0 this function only supported signing with Crypto.RSA and the default (and only) hash was Crypto.MD5.

Method sign_cri: Sequencesign_cri(CRIcri, Crypto.Signsign, Crypto.Hashhash)
Description: Sign a CRI to generate a Certificate Signing Request.
Parameter cri: CertificationRequestInfo to sign.
Parameter sign: Signature to use. Must have a private key set that matches the public key in the keyinfo in cri.
Parameter hash: Hash algorithm to use for the signature.

Class Standards.PKCS.CSR.CRI

Description

CertificationRequestInfo

This is the data that is signed by sign_cri().

Inherit Sequence: inherit Sequence : Sequence

Variable attributes: void Standards.PKCS.CSR.CRI.attributes
Description: Subject attributes.

Variable keyinfo: void Standards.PKCS.CSR.CRI.keyinfo
Description: Public key information.

Variable subject: void Standards.PKCS.CSR.CRI.subject
Description: Certificate subject.

Variable version: void Standards.PKCS.CSR.CRI.version

Class Standards.PKCS.CSR.CRIAttributes

Inherit Attributes: inherit .Certificate.Attributes : Attributes

Module Standards.PKCS.Certificate

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

Method build_distinguished_name

variantSequencebuild_distinguished_name(arrayargs)

Description

Creates an ASN.1 Sequence with the distinguished name of the list of pairs given in args. Supported identifiers are

commonName
surname
countryName
localityName
stateOrProvinceName
organizationName
organizationUnitName
title
name
givenName
initials
generationQualifier
dnQualifier
emailAddress

Parameter args

Either a mapping that lists from id string to string or ASN.1 object, or an array with mappings, each containing one pair. No type validation is performed.

Method decode_distinguished_name: array(mapping(string(7bit):string)) decode_distinguished_name(Sequencedn)
Description: Perform the reverse operation of build_distinguished_name().
See also: build_distinguished_name()

Method get_dn_string: stringget_dn_string(Sequencednsequence)
Description: Converts an RDN (relative distinguished name) Seqeunce object to a human readable string in X500 format.
Returns: A string containing the certificate issuer Distinguished Name (DN) in human readable X500 format.
Note: We don't currently handle attributes with multiple values, not all attribute types are understood.

Module Standards.PKCS.DSA

Description: DSA operations as defined in RFC 2459.

Method algorithm_identifier: Sequencealgorithm_identifier(Crypto.DSA|voiddsa)
Description: Returns the AlgorithmIdentifier as defined in RFC 5280 section 4.1.1.2. Optionally the DSA parameters are included, if a DSA object is given as argument.

Method build_private_key: Sequencebuild_private_key(Crypto.DSAdsa)
Description: Creates a PrivateKeyInfo ASN.1 sequence for the given rsa object. See RFC 5208 section 5.

Method build_public_key: Sequencebuild_public_key(Crypto.DSAdsa)
Description: Creates a SubjectPublicKeyInfo ASN.1 sequence for the given dsa object. See RFC 5280 section 4.1.2.7.

Method parse_private_key: Crypto.DSAparse_private_key(Sequenceseq)

Method parse_private_key: variantCrypto.DSAparse_private_key(stringkey)

Method parse_public_key: Crypto.DSA|zeroparse_public_key(stringkey, Gmp.mpzp, Gmp.mpzq, Gmp.mpzg)
Description: Decodes a DER-encoded DSAPublicKey structure.
Parameter key: DSAPublicKey provided in ASN.1 DER-encoded format
Parameter p: Public parameter p, usually transmitted in the algoritm identifier.
Parameter q: Public parameter q, usually transmitted in the algoritm identifier.
Parameter g: Public parameter g, usually transmitted in the algoritm identifier.
Returns: Crypto.DSA object

Method private_key: stringprivate_key(Crypto.DSAdsa)

Method public_key: stringpublic_key(Crypto.DSAdsa)
Description: Generates the DSAPublicKey value, as specified in RFC 2459.

Method signature_algorithm_id: Sequence|zerosignature_algorithm_id(Crypto.Hashhash)
Description: Returns the PKCS-1 algorithm identifier for DSA and the provided hash algorithm. One of SHA1, SHA224 or SHA256.

Module Standards.PKCS.ECDSA

Description: ECDSA operations.

Variable curve_lookup: protectedmapping(string:Crypto.ECC.Curve) Standards.PKCS.ECDSA.curve_lookup
Description: Lookup from ASN.1 DER encoded ECC named curve identifier to the corresponding Crypto.ECC.Curve.

Method parse_ec_parameters: Crypto.ECC.Curve|zeroparse_ec_parameters(stringec_parameters)
Description: Get the ECC curve corresponding to an ASN.1 DER encoded named curve identifier.
Returns: Returns UNDEFINED if the curve is unsupported.

Method parse_private_key

Crypto.ECC.SECP_521R1.ECDSA|zeroparse_private_key(Sequencea, Crypto.ECC.Curve|voidc)

Description

Get an initialized ECDSA object from an ECC curve and an ASN.1 ec private key sequence.

As specified in RFC 5915 section 3.

Method parse_private_key

variantCrypto.ECC.SECP_521R1.ECDSA|zeroparse_private_key(string(8bit)ec_private_key, Crypto.ECC.Curve|voidc)

Description

Get an initialized ECDSA object from an ECC curve and an ASN.1 DER encoded ec private key.

As specified in RFC 5915 section 3.

Method parse_public_key

Crypto.ECC.SECP_521R1.ECDSAparse_public_key(string(8bit)key, Crypto.ECC.Curvec)

Description

Get an initialized ECDSA object from an ECC curve and an ec public key.

See RFC 5280 section 4.1.2.7 and RFC 5480 section 2.2.

Method private_key: string(8bit)private_key(Crypto.ECC.SECP_521R1.ECDSAecdsa)
Description: Create a DER-coded ECPrivateKey structure
Parameter ecdsa: Crypto.ECC.Curve()->ECDSA object.
Returns: ASN.1 coded ECPrivateKey structure as specified in RFC 5915 section 3.

Method public_key: string(8bit)public_key(Crypto.ECC.SECP_521R1.ECDSAecdsa)
Description: Create a DER-coded ECPublicKey structure
Parameter ecdsa: Crypto.ECC.Curve()->ECDSA object.
Returns: ASN.1 coded ECPublicKey structure as specified in RFC 5480 section 2.

Module Standards.PKCS.Identifiers

Description: Various ASN.1 identifiers used by PKCS.
See also: RFC 2459, RFC 3279, RFC 3280, RFC 3447, RFC 4055, RFC 4985, RFC 5480, RFC 5639, RFC 8410

Module Standards.PKCS.PFX

Description: PKCS #12: Personal Information Exchange Syntax v1.1, RFC 7292.

Module Standards.PKCS.RSA

Description: RSA operations and types as described in PKCS-1.

Method algorithm_identifier: Sequencealgorithm_identifier()
Description: Returns the AlgorithmIdentifier as defined in RFC 5280 section 4.1.1.2.

Method build_private_key: Sequencebuild_private_key(Crypto.RSArsa)
Description: Creates a PrivateKeyInfo ASN.1 sequence for the given rsa object. See RFC 5208 section 5.

Method build_public_key: Sequencebuild_public_key(Crypto.RSArsa)
Description: Creates a SubjectPublicKeyInfo ASN.1 sequence for the given rsa object. See RFC 5280 section 4.1.2.7.

Method oaep_algorithm_id: Sequenceoaep_algorithm_id(Crypto.Hashhash, string(8bit)|voidlabel)
Description: Returns the PKCS-1 algorithm identifier for RSAES-OAEP and the provided hash algorithm and label.
See also: RFC 3447 appendix A.2.1

Method parse_private_key: Crypto.RSA.Stateparse_private_key(Sequenceseq)
Description: Decode a RSAPrivateKey structure
Parameter key: RSAPrivateKey provided in ASN.1 format
Returns: Crypto.RSA object

Method parse_private_key: variantCrypto.RSA.Stateparse_private_key(stringkey)
Description: Decode a DER-coded RSAPrivateKey structure
Parameter key: RSAPrivateKey provided in ASN.1 DER-encoded format
Returns: Crypto.RSA object

Method parse_public_key: Crypto.RSA.Stateparse_public_key(stringkey)
Description: Decode a DER-coded RSAPublicKey structure
Parameter key: RSAPublicKey provided in ASN.1 DER-encoded format
Returns: Crypto.RSA object

Method private_key: stringprivate_key(Crypto.RSArsa)
Description: Create a DER-coded RSAPrivateKey structure
Parameter rsa: Crypto.RSA object
Returns: ASN1 coded RSAPrivateKey structure

Method pss_signature_algorithm_id: Sequencepss_signature_algorithm_id(Crypto.Hashhash, int(0..)|voidsaltlen)
Description: Returns the PKCS-1 algorithm identifier for RSASSA-PSS and the provided hash algorithm and saltlen.
See also: RFC 3447 appendix A.2.3

Method public_key: stringpublic_key(Crypto.RSArsa)
Description: Create a DER-coded RSAPublicKey structure
Parameter rsa: Crypto.RSA object
Returns: ASN1 coded RSAPublicKey structure

Method signature_algorithm_id: Sequence|zerosignature_algorithm_id(Crypto.Hashhash)
Description: Returns the PKCS-1 algorithm identifier for RSA and the provided hash algorithm. One of MD2, MD5, SHA1, SHA256, SHA384 or SHA512.

Module Standards.PKCS.Signature

Method build_digestinfo: stringbuild_digestinfo(stringmsg, Crypto.Hashhash)
Description: Construct a PKCS-1 digestinfo.
Parameter msg: message to digest
Parameter hash: crypto hash object such as Crypto.SHA1 or Crypto.MD5
See also: Crypto.RSA()->sign

Method sign: Signedsign(Sequencetbs, Crypto.Signsign, Crypto.Hashhash)
Description: Generic PKCS signing.
Parameter tbs: Standards.ASN1 structure to be signed.
Parameter sign: Signature to use. Must have a private key set.
Parameter hash: Hash algorithm to use for the signature. Must be valid for the signature algorithm.
Returns: Returns a Standards.ASN1.Types.Sequence with the signature.

Class Standards.PKCS.Signature.Signed

Description: This is an ASN.1 structure from PKCS #10 v1.7 and others, which represents a signed block of data.
See also: sign(), Standards.X509.sign_tbs().

Inherit Sequence: inherit Sequence : Sequence

Variable algorithm

Sequence Standards.PKCS.Signature.Signed.algorithm

Description

Getting

Signing algorithm that was used to sign with.

Setting

Signing algorithm that was used to sign with.

Variable signature

BitString Standards.PKCS.Signature.Signed.signature

Description

Getting

The signature.

Setting

The signature.

Variable tbs

Object Standards.PKCS.Signature.Signed.tbs

Description

Getting

ASN.1 structure that has been signed.

Setting

ASN.1 structure that has been signed.

Method sign

this_programsign(Crypto.Signsign, Crypto.Hashhash)

Description

Sign tbs with the provided sign and hash.

Sets algorithm and signature.

Returns

Returns the Signed object.

Module Standards.TLD

Constant cc: constant Standards.TLD.cc
Description: A mapping between country TLDs and the name of the country.

Variable generic: multiset Standards.TLD.generic
Description: A multiset containing the generic TLDs, such as "com" and "info".

Module Standards.UUID

Description

Support for Universal Unique Identifiers (UUID) and Globally Unique Identifiers (GUID).

See also

: A Universally Unique IDentifier (UUID) URN Namespace.
ITU-T X.667: Generation and registration of Universally Unique Identifiers (UUIDs) and their use as ASN.1 object identifier components.

Constant NameSpace_DNS: constantstring Standards.UUID.NameSpace_DNS
Description: Name space UUID for DNS.

Constant NameSpace_OID: constantstring Standards.UUID.NameSpace_OID
Description: Name space UUID for OID.

Constant NameSpace_URL: constantstring Standards.UUID.NameSpace_URL
Description: Name space UUID for URL.

Constant NameSpace_X500: constantstring Standards.UUID.NameSpace_X500
Description: Name space UUID for X500.

Constant Nil_UUID: constantstring Standards.UUID.Nil_UUID
Description: The Nil UUID.

Method format_uuid: stringformat_uuid(stringuuid)
Description: Returns the string representation of the binary UUID uuid.

Method get_clock_state: array(int) get_clock_state()
Description: Returns the internal clock state. Can be used for persistent storage when an application is terminated.
See also: set_clock_state

Method make_dns: UUIDmake_dns(stringname)
Description: Creates a DNS UUID with the given DNS name.

Method make_dns: UUIDmake_dns(stringname)
Description: Creates a DNS UUID with the given DNS name.

Method make_null: UUIDmake_null()
Description: Creates a null UUID object.

Method make_oid: UUIDmake_oid(stringname)
Description: Creates an OID UUID with the given OID.

Method make_oid: UUIDmake_oid(stringname)
Description: Creates an OID UUID with the given OID.

Method make_url: UUIDmake_url(stringname)
Description: Creates a URL UUID with the given URL.

Method make_url: UUIDmake_url(stringname)
Description: Creates a URL UUID with the given URL.

Method make_version1: UUIDmake_version1(intnode)
Description: Creates a new version 1 UUID.
Parameter node: Either the 48 bit IEEE 802 (aka MAC) address of the system or -1.

Method make_version3: UUIDmake_version3(stringname, string|UUIDnamespace)
Description: Creates a version 3 UUID with a name string and a binary representation of a name space UUID.

Method make_version4: UUIDmake_version4()
Description: Creates a version 4 (random) UUID.

Method make_version5: UUIDmake_version5(stringname, string|UUIDnamespace)
Description: Creates a version 5 UUID with a name string and a binary representation of a name space UUID.

Method make_x500: UUIDmake_x500(stringname)
Description: Creates an X500 UUID with the gived X500 address.

Method make_x500: UUIDmake_x500(stringname)
Description: Creates an X500 UUID with the gived X500 address.

Method parse_uuid: stringparse_uuid(stringuuid)
Description: Returns the binary representation of the UUID uuid.

Method set_clock_state: voidset_clock_state(intlast_time, intseq)
Description: Sets the internal clock state.
See also: get_clock_state

Class Standards.UUID.UUID

Description: Represents an UUID

Variable clk_seq: int Standards.UUID.UUID.clk_seq
Description: The clock sequence. Should be 13 to 15 bits depending on UUID version.

Variable node: int Standards.UUID.UUID.node
Description: The UUID node. Should be 48 bit.

Variable timestamp: int Standards.UUID.UUID.timestamp
Description: 60 bit value representing the time stamp.

Variable var: int Standards.UUID.UUID.var
Description: The variant of the UUID.

Variable version: int Standards.UUID.UUID.version
Description: The version of the UUID.

Method create: Standards.UUID.UUIDStandards.UUID.UUID(void|stringin)
Description: Optionally created with a string or binary representation of a UUID.

Method encode: stringencode()
Description: Encodes a binary representation of the UUID.

Method posix_time: intposix_time()
Description: Returns the posix time of the UUID.

Method str: stringstr()
Description: Creates a string representation of the UUID.

Method str_variant: stringstr_variant()
Description: Returns a string representation of the variant, e.g. "IETF draft variant".

Method str_version: stringstr_version()
Description: Returns a string representation of the version, e.g. "Name-based (MD5)".

Method time_hi_and_version: inttime_hi_and_version()
Description: Returns the time_hi_and_version field.

Method time_low: inttime_low()
Description: Returns the time_low field.

Method time_mid: inttime_mid()
Description: Returns the time_mid field.

Method urn: stringurn()
Description: Creates a URN representation of the UUID.

Method validate: voidvalidate()
Description: Validates the current UUID.

Module Standards.X509

Description: Functions to generate and validate RFC 2459 style X.509 v3 certificates.

Method decode_certificate: TBSCertificate|zerodecode_certificate(string|.PKCS.Signature.Signedcert)
Description: Decodes a certificate and verifies that it is structually sound. Returns a TBSCertificate object if ok, otherwise 0.

Method get_algorithms: mapping(Identifier:Crypto.Hash) get_algorithms()
Description: Returns the mapping of signature algorithm to hash algorithm supported by Verifier and thus verify_ca_certificate(), verify_certificate(), and verify_certificate_chain().

Method get_letsencrypt_cert

arrayget_letsencrypt_cert(stringhost)

Description

Read and decode certificate chain for the given host from the letsencrypt directory (/etc/letsencrypt/live/{host}/). Note that the process has to have read privileges for the directory.

The resulting array can be used directly as input to the SSL.Context()->add_cert() method.

Returns

Array
`Crypto.Sign.State0`	A signing object using the private key.
`array(string) 1`	An array of DER encoded certificates representing the certificate chain.

Method load_authorities: mapping(string:array(Verifier)) load_authorities(string|array(string)|voidroot_cert_dirs, bool|voidcache)
Description: Convenience function for loading known root certificates.
Parameter root_cert_dirs: Directory/directories containing the PEM-encoded root certificates to load. Defaults to a rather long list of directories, including "/etc/ssl/certs", "/etc/pki/tls/certs" and "/System/Library/OpenSSL/certs", which seem to be the most common locations.
Parameter cache: A flag to control if the answer should be given from an internal cache or always scan the directories. If a cache is used, it will refresh when any certificate expires (which typically is measured in years) or when asked for in unchached mode.
Returns: Returns a mapping from DER-encoded issuer to Verifiers compatible with eg verify_certificate()
Note: If a certificate directory contains a file named "ca-certificates.crt", "ca-bundle.crt" or "ca-bundle.trust.crt", it is assumed to contain a concatenation of all the certificates in the directory.
See also: verify_certificate(), verify_certificate_chain()

Method make_extension: Sequencemake_extension(Identifierid, Objectext, void|intcritical)
Description: Creates a certificate extension with the id as identifier and ext as the extension payload. If the critical flag is set the extension will be marked as critical.

Method make_selfsigned_certificate: stringmake_selfsigned_certificate(Crypto.Sign.Statec, intttl, mapping|arrayname, mapping(Identifier:Sequence)|voidextensions, Crypto.Hash|voidh, int|voidserial)
Description: Creates a selfsigned certificate, i.e. where issuer and subject are the same entity. This entity is derived from the list of pairs in name, which is encoded into an distinguished_name by Standards.PKCS.Certificate.build_distinguished_name.
Parameter c: The public key cipher used for the certificate, Crypto.RSA, Crypto.DSA or Crypto.ECC.Curve.ECDSA. The object should be initialized with both public and private keys.
Parameter ttl: The validity of the certificate, in seconds, starting from creation date.
Parameter name: List of properties to create distinguished name from.
Parameter extensions: Mapping with extensions as ASN.1 structures, as produced by make_extension. The extensions subjectKeyIdentifier, keyUsage (flagged critical) and basicConstraints (flagged critical) will automatically be added if not present.
Parameter h: The hash function to use for the certificate. Must be one of the standardized PKCS hashes to be used with the given Crypto. By default Crypto.SHA256 is selected for both RSA and DSA.
Parameter serial: Serial number of the certificate. Defaults to generating a UUID version1 value with random node. Some browsers will refuse different certificates from the same signer with the same serial number.
See also: sign_key(), sign_tbs()

Method make_tbs: TBSCertificatemake_tbs(Sequenceissuer, Sequencealgorithm, Sequencesubject, Sequencekeyinfo, Integerserial, Sequencevalidity, array|int(0)|voidextensions)
Description: Creates the ASN.1 TBSCertificate sequence (see RFC 2459 section 4.1) to be signed (TBS) by the CA. version is explicitly set to v3, and extensions is optionally added to the sequence. issuerUniqueID and subjectUniqueID are not supported.

Method make_tbs: variantTBSCertificatemake_tbs(Sequenceissuer, Sequencealgorithm, Sequencesubject, Sequencekeyinfo, Integerserial, intttl, array|int(0)|voidextensions)
Description: Creates the ASN.1 TBSCertificate sequence (see RFC 2459 section 4.1) to be signed (TBS) by the CA. version is explicitly set to v3, validity is calculated based on time and ttl, and extensions is optionally added to the sequence. issuerUniqueID and subjectUniqueID are not supported.
Note: Prior to Pike 8.0 this function returned a plain Sequence object.

Method parse_private_key: Crypto.Sign.Stateparse_private_key(Sequenceseq)
Description: DWIM-parse the ASN.1-sequence for a private key.

Method parse_private_key: variantCrypto.Sign.Stateparse_private_key(string(8bit)private_key)
Description: DWIM-parse the DER-sequence for a private key.

Method sign_key: stringsign_key(Sequenceissuer, Crypto.Sign.Statec, Crypto.Sign.Stateca, Crypto.Hashh, Sequencesubject, intserial, intttl, array|mapping|voidextensions)
Description: Low-level function for creating a signed certificate.
Parameter issuer: Distinguished name for the issuer. See Standards.PKCS.Certificate.build_distinguished_name.
Parameter c: RSA, DSA or ECDSA parameters for the subject. Only the public key needs to be set. See Crypto.RSA, Crypto.DSA and Crypto.ECC.Curve.ECDSA.
Parameter ca: RSA, DSA or ECDSA parameters for the issuer. Only the private key needs to be set. See Crypto.RSA, Crypto.DSA and Crypto.ECC.Curve.ECDSA.
Parameter h: The hash function to use for the certificate. Must be one of the standardized PKCS hashes to be used with the given Crypto.
Parameter subject: Distinguished name for the subject. See Standards.PKCS.Certificate.build_distinguished_name.
Parameter public_key: DER-encoded RSAPublicKey structure. See Standards.PKCS.RSA.public_key().
Parameter serial: Serial number for this key and subject.
Parameter ttl: Validity time in seconds for this signature to be valid.
Parameter extensions: Set of extensions.
Returns: Returns a DER-encoded certificate.
See also: make_selfsigned_certificate(), make_tbs(), sign_tbs()

Method sign_tbs: Sequencesign_tbs(TBSCertificatetbs, Crypto.Sign.Statesign, Crypto.Hashhash)
Description: Sign the provided TBSCertificate.
Parameter tbs: A TBSCertificate as returned by decode_certificate() or make_tbs().
Parameter sign: RSA, DSA or ECDSA parameters for the issuer. See Crypto.RSA, Crypto.DSA and Crypto.ECC.Curve.ECDSA. Must be initialized with the private key.
Parameter hash: The hash function to use for the certificate. Must be one of the standardized PKCS hashes to be used with the given Crypto.
See also: decode_certificate(), make_tbs()

Method verify_ca_certificate: TBSCertificate|zeroverify_ca_certificate(string|TBSCertificatetbs)
Description: Verifies that all extensions mandated for certificate signing certificates are present and valid.

Method verify_certificate

TBSCertificate|zeroverify_certificate(strings, mapping(string:Verifier|array(Verifier)) authorities, mapping(Standards.ASN1.Types.Identifier:Crypto.Hash)|voidoptions)

Description

Decodes a certificate, checks the signature. Returns the TBSCertificate structure, or 0 if decoding or verification fails. The valid time range for the certificate is not checked.

Parameter authorities

A mapping from (DER-encoded) names to a verifiers.

Parameter options

"verifier_algorithms" : mapping(Standards.ASN1.Types.Identifier:Crypto.Hash)

A mapping of verifier algorithm identifier to hash algorithm implementation.

Note

This function allows self-signed certificates, and it doesn't check that names or extensions make sense.

Method verify_certificate_chain

Description

Decodes a certificate chain, ordered from leaf to root, and checks the signatures. Verifies that the chain can be decoded correctly, is unbroken, and that all certificates are in effect (time-wise.) and allowed to sign its child certificate.

No verifications are done on the leaf certificate to determine what it can and can not be used for.

Returns a mapping with the following contents, depending on the verification of the certificate chain:

`"error_code" : int`	Error describing type of verification failures, if verification failed. May be one of the following, OR:ed together: `CERT_TOO_NEW`, `CERT_TOO_OLD`, `CERT_ROOT_UNTRUSTED`, `CERT_BAD_SIGNATURE`, `CERT_INVALID`, `CERT_CHAIN_BROKEN`, `CERT_UNAUTHORIZED_CA` or `CERT_EXCEEDED_PATH_LENGTH`.
`"error_cert" : int`	Index number of the certificate that caused the verification failure.
`"self_signed" : bool`	Non-zero if the certificate is self-signed.
`"verified" : bool`	Non-zero if the certificate is verified.
`"authority" : Standards.ASN1.Sequence`	The authority RDN that verified the chain.
`"cn" : Standards.ASN1.Sequence`	The common name RDN of the leaf certificate.
`"certificates" : array(TBSCertificate)`	An array with the decoded certificates, ordered from root to leaf.

Parameter cert_chain

An array of certificates, with the relative-root last. Each certificate should be a DER-encoded certificate, or decoded as a Standards.PKCS.Signature.Signed object.

Parameter authorities

A mapping from (DER-encoded) names to verifiers.

Parameter require_trust

Require that the certificate be traced to an authority, even if it is self signed.

Parameter strict

By default this function only requires that the certificates are in order, it ignores extra certificates we didn't need to verify the leaf certificate.

If you specify strict, this will change, each certificate has to be signed by the next in the chain.

Some https-servers send extraneous intermediate certificates that aren't used to validate the leaf certificate. So strict mode will be incompatible with such srevers.

Parameter options

`"verifier_algorithms" : mapping(Standards.ASN1.Types.Identifier:Crypto.Hash)`	A mapping of verifier algorithm identifier to hash algorithm implementation.
`"strict" : int`	See `strict` above.

See also

get_algorithms()

See Standards.PKCS.Certificate.get_dn_string for converting the RDN to an X500 style string.

Enum Standards.X509.CertFailure

Constant CERT_BAD_SIGNATURE: constant Standards.X509.CERT_BAD_SIGNATURE

Constant CERT_CHAIN_BROKEN: constant Standards.X509.CERT_CHAIN_BROKEN

Constant CERT_EXCEEDED_PATH_LENGTH: constant Standards.X509.CERT_EXCEEDED_PATH_LENGTH
Description: The certificate chain is longer than allowed by a certificate in the chain.

Constant CERT_INVALID: constant Standards.X509.CERT_INVALID

Constant CERT_ROOT_UNTRUSTED: constant Standards.X509.CERT_ROOT_UNTRUSTED

Constant CERT_TOO_NEW: constant Standards.X509.CERT_TOO_NEW

Constant CERT_TOO_OLD: constant Standards.X509.CERT_TOO_OLD

Constant CERT_UNAUTHORIZED_CA: constant Standards.X509.CERT_UNAUTHORIZED_CA
Description: A CA certificate is not allowed by basic constraints to sign another certificate.

Constant CERT_UNAUTHORIZED_SIGNING: constant Standards.X509.CERT_UNAUTHORIZED_SIGNING
Description: The certificate is not allowed by its key usage to sign data.

Enum Standards.X509.keyUsage

Constant KU_digitalSignature
Constant KU_nonRepudiation
Constant KU_keyEncipherment
Constant KU_dataEncipherment
Constant KU_keyAgreement
Constant KU_keyCertSign
Constant KU_cRLSign
Constant KU_encipherOnly
Constant KU_decipherOnly
Constant KU_last_keyUsage: constant Standards.X509.KU_digitalSignature
constant Standards.X509.KU_nonRepudiation
constant Standards.X509.KU_keyEncipherment
constant Standards.X509.KU_dataEncipherment
constant Standards.X509.KU_keyAgreement
constant Standards.X509.KU_keyCertSign
constant Standards.X509.KU_cRLSign
constant Standards.X509.KU_encipherOnly
constant Standards.X509.KU_decipherOnly
constant Standards.X509.KU_last_keyUsage

Class Standards.X509.IssuerId

Description

Unique identifier for the certificate issuer.

X.509v2 (deprecated).

Inherit BitString: inherit BitString : BitString

Class Standards.X509.SubjectId

Description

Unique identifier for the certificate subject.

X.509v2 (deprecated).

Inherit BitString: inherit BitString : BitString

Class Standards.X509.TBSCertificate

Description: Represents a TBSCertificate.
Note: Was not compatible with Standards.ASN1.Types.Sequence prior to Pike 8.0.

Inherit Sequence: inherit Sequence : Sequence

Variable algorithm: void Standards.X509.TBSCertificate.algorithm
Description: Algorithm Identifier.

Variable critical: multiset Standards.X509.TBSCertificate.critical
Note: optional
Note: Read only

Variable der: void Standards.X509.TBSCertificate.der

Variable ext_authorityKeyIdentifier: bool Standards.X509.TBSCertificate.ext_authorityKeyIdentifier
Description: Set if the certificate contains a valid authorityKeyIdentifier extension. RFC 3280 section 4.2.1.1.

Variable ext_authorityKeyIdentifier_authorityCertSerialNumber: Gmp.mpz Standards.X509.TBSCertificate.ext_authorityKeyIdentifier_authorityCertSerialNumber
Description: Set to the CertificateSerialNumber, if set in the extension.

Variable ext_authorityKeyIdentifier_keyIdentifier: string Standards.X509.TBSCertificate.ext_authorityKeyIdentifier_keyIdentifier
Description: Set to the KeyIdentifier, if set in the extension.

Variable ext_basicConstraints: bool Standards.X509.TBSCertificate.ext_basicConstraints
Description: Set if the certificate contains a valid basicConstraints extension. RFC 3280 section 4.2.1.10.

Variable ext_basicConstraints_cA: bool Standards.X509.TBSCertificate.ext_basicConstraints_cA
Description: If set, the certificate may be used as a CA certificate, i.e. sign other certificates.

Variable ext_basicConstraints_pathLenConstraint: int Standards.X509.TBSCertificate.ext_basicConstraints_pathLenConstraint
Description: The maximum number of certificates that may follow this certificate in a certificate chain. 0 in case no limit is imposed. Note that this variable is off by one compared to the RFC 3280 definition, which only counts intermediate certificates (i.e. 0 intermediates means this variable would be 1, as in one following certificate).

Variable ext_extKeyUsage: array(Identifier) Standards.X509.TBSCertificate.ext_extKeyUsage
Description: Set to the list of extended key usages from anyExtendedKeyUsage, if the certificate contains the extKeyUsage extensions. These Identifier objects are typically found in .PKCS.Identifiers.reverse_kp_ids. RFC 3280 section 4.2.1.13.

Variable ext_keyUsage: keyUsage Standards.X509.TBSCertificate.ext_keyUsage
Description: Set to the value of the KeyUsage if the certificate contains the keyUsage extension. RFC 3280 section 4.2.1.3.

Variable ext_subjectKeyIdentifier: string Standards.X509.TBSCertificate.ext_subjectKeyIdentifier
Description: Set to the value of the SubjectKeyIdentifier if the certificate contains the subjectKeyIdentifier extension. RFC 3280 section 4.2.1.2.

Variable extensions: mapping(Identifier:Object) Standards.X509.TBSCertificate.extensions
Note: optional
Note: Read only

Variable hash: Crypto.Hash Standards.X509.TBSCertificate.hash
Description: Algorithm hash if known and supported. Otherwise UNDEFINED.
Note: Read only

Variable internal_critical: protectedmultiset Standards.X509.TBSCertificate.internal_critical
Note: optional

Variable internal_extensions: protectedmapping(Identifier:Object) Standards.X509.TBSCertificate.internal_extensions
Note: optional

Variable issuer: void Standards.X509.TBSCertificate.issuer
Description: Certificate issuer.

Variable issuer_id: void Standards.X509.TBSCertificate.issuer_id
Note: optional

Variable keyinfo: void Standards.X509.TBSCertificate.keyinfo

Variable not_after: void Standards.X509.TBSCertificate.not_after

Variable not_before: void Standards.X509.TBSCertificate.not_before

Variable public_key: void Standards.X509.TBSCertificate.public_key

Variable raw_extensions: void Standards.X509.TBSCertificate.raw_extensions
Description: The raw ASN.1 objects from which extensions and critical have been generated.
Note: optional

Variable serial: void Standards.X509.TBSCertificate.serial

Variable subject: void Standards.X509.TBSCertificate.subject

Variable subject_id: void Standards.X509.TBSCertificate.subject_id
Note: optional

Variable validity: void Standards.X509.TBSCertificate.validity

Variable version: void Standards.X509.TBSCertificate.version

Method dn_str: stringdn_str(Sequencedn)
Description: Try to extract a readable name from dn. This is one of commonName, organizationName or organizationUnitName. The first that is found is returned. Suitable for subjects and issuer sequences.

Method init: this_programinit(array|Objectasn1)
Description: Populates the object from a certificate decoded into an ASN.1 Object. Returns the object on success, otherwise 0. You probably want to call decode_certificate or even verify_certificate.

Method issuer_str: stringissuer_str()
Description: Return the issuer of the certificate as a human readable string. Mainly useful for debug.

Method low_set: protectedvoidlow_set(intindex, Sequence|Integerval)
Parameter index: Index in a v1 certificate.
Parameter val: New value for index.

Method subject_str: stringsubject_str()
Description: Attempt to create a presentable string from the subject DER.

Class Standards.X509.Verifier

Method verify: boolverify(Sequencealgorithm, string(8bit)msg, string(8bit)signature, mapping(Identifier:Crypto.Hash)|voidverifier_algorithms)
Description: Verifies the signature of the certificate msg using the indicated hash algorithm, choosing from verifier_algorithms.
See also: get_algorithms()

Module Standards.XML

Module Standards.XML.Wix

Description: Helper module for generating Windows Installer XML structures.
See also: Parser.XML.Tree.SimpleNode

Method get_module_xml: WixNodeget_module_xml(Directorydir, stringid, stringversion, string|voidmanufacturer, string|voiddescription, string|voidguid, string|voidcomments, string|voidinstaller_version)
Note: Modifies dir if it contains files at the root level.

Module Standards._BSON

Method decode: mappingdecode(Stdio.Bufferdocument)

Method decode: mappingdecode(string(8bit)document)

Module Sybase

Class Sybase.sybase

Inherit Connection: inherit __builtin.Sql.Connection : Connection

Module System

Description: This module embodies common operating system calls, making them available to the Pike programmer.

Inherit _system: inherit _system : _system

Constant CPU_TIME_IMPLEMENTATION: constantstring System.CPU_TIME_IMPLEMENTATION
Description: This string constant identifies the internal interface used to get the CPU time. It is an implementation detail - see rusage.c for possible values and their meanings.
See also: gethrvtime, gauge

Constant CPU_TIME_IS_THREAD_LOCAL: constantstring System.CPU_TIME_IS_THREAD_LOCAL
Description: This string constant tells whether or not the CPU time, returned by e.g. 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.
See also: gethrvtime, gauge

Constant CPU_TIME_RESOLUTION: constantint System.CPU_TIME_RESOLUTION
Description: The resolution of the CPU time, returned by e.g. gethrvtime, in nanoseconds. It is -1 if the resolution isn't known.
See also: gethrvtime, gauge

Constant HKEY_CLASSES_ROOT
Constant HKEY_LOCAL_MACHINE
Constant HKEY_CURRENT_USER
Constant HKEY_USERS: constantint System.HKEY_CLASSES_ROOT
constantint System.HKEY_LOCAL_MACHINE
constantint System.HKEY_CURRENT_USER
constantint System.HKEY_USERS
Description: Root handles in the Windows registry.
Note: These constants are only available on Win32 systems.
See also: RegGetValue(), RegGetValues(), RegGetKeyNames()

Constant ITIMER_PROF: constant System.ITIMER_PROF
Description: Identifier for a timer that decrements both when the process is executing and when the system is executing on behalf of the process.
See also: setitimer, getitimer

Constant ITIMER_REAL: constant System.ITIMER_REAL
Description: Identifier for a timer that decrements in real time.
See also: setitimer, getitimer

Constant ITIMER_VIRTUAL: constant System.ITIMER_VIRTUAL
Description: Identifier for a timer that decrements only when the process is executing.
See also: setitimer, getitimer

Constant REAL_TIME_IMPLEMENTATION: constantstring System.REAL_TIME_IMPLEMENTATION
Description: This string constant identifies the internal interface used to get the high resolution real time. It is an implementation detail - see rusage.c for possible values and their meanings.
See also: gethrtime

Constant REAL_TIME_IS_MONOTONIC

constantstring System.REAL_TIME_IS_MONOTONIC

Description

This string constant tells whether or not the high resolution real time returned by gethrtime, is monotonic or not. The value is "yes" if it is and "no" if it isn't.

Monotonic time is not affected by clock adjustments that might happen to keep the calendaric clock in synch. It's therefore more suited to measure time intervals in programs.

See also

gethrtime

Constant REAL_TIME_RESOLUTION: constantint System.REAL_TIME_RESOLUTION
Description: The resolution of the real time returned by gethrtime, in nanoseconds. It is -1 if the resolution isn't known.
See also: gethrtime

Method AllocConsole: intAllocConsole()
Description: Allocates a new console for the calling process.
Note: Only available on certain Windows systems.
Returns: 0 on success, non-zero otherwise.

Method AttachConsole: intAttachConsole(intpid)
Description: Attaches calling process to a specific console.
Parameter pid
Note: Only available on certain Windows systems.
Returns: 0 on success, non-zero otherwise.

Method FreeConsole: intFreeConsole()
Description: Detaches the calling process from its console.
Note: Before calling this function, Stdio.stderr, Stdio.stdout and Stdio.stdin must be closed.
Note: Only available on certain Windows systems.
Returns: 0 on success, non-zero otherwise.

Method GetComputerName: stringGetComputerName()
Description: Retrieves the NetBIOS name of the local computer.
Note: This function is Windows specific, and is not available on all systems.

Method GetFileAttributes: intGetFileAttributes(string(8bit)filename)
Description: Get the file attributes for the specified file.
Note: This function is only available on Win32 systems.
See also: SetFileAttributes()

Method GetNamedSecurityInfo: mapping(string:mixed) GetNamedSecurityInfo(stringname, int|voidtype, int|voidflags)
Note: This function is only available on some Win32 systems.
See also: SetNamedSecurityInfo()

Method GetUserName: stringGetUserName()
Description: Retrieves the name of the user associated with the current thread.
Note: This function is Windows specific, and is not available on all systems.

Method LogonUser

UserTokenLogonUser(stringusername, string|zerodomain, string|zeropassword, int|voidlogon_type, int|voidlogon_provider)

Description

Logon a user.

Parameter username

User name of the user to login.

Parameter domain

Domain to login on, or zero if local logon.

Parameter password

Password to login with (if required).

Parameter logon_type

One of the following values:

`LOGON32_LOGON_BATCH`
`LOGON32_LOGON_INTERACTIVE`
`LOGON32_LOGON_SERVICE`
`LOGON32_LOGON_NETWORK`	This is the default.

Parameter logon_provider

One of the following values:

LOGON32_PROVIDER_DEFAULT

This is the default.

Returns

Returns a login UserToken object on success, and zero on failure.

Note

This function is only available on some Win32 systems.

Method LookupAccountName

array(mixed) LookupAccountName(string|int(0)sys, stringaccount)

Returns

Returns 0 (zero) if the account was not found, and an array containing the following on success:

Array
`SID0`	`SID` object representing the `account`.
`string1`	Domain name.
`int2`	Account type.

Note

This function is only available on some Win32 systems.

Method NetGetAnyDCName: stringNetGetAnyDCName(string|int(0)server, stringdomain)
Description: Get name of a domain controller from a server.
Parameter server: Server the domain exists on.
Parameter domain: Domain to get a domain controller for.
Returns: Returns the name of a domain controller on success. Throws errors on failure.
Note: This function is only available on some Win32 systems.
See also: NetUserGetInfo(), NetUserEnum(), NetGroupEnum(), NetLocalGroupEnum(), NetUserGetGroups(), NetUserGetLocalGroups(), NetGroupGetUsers(), NetLocalGroupGetMembers(), NetGetDCName()

Method NetGetDCName: stringNetGetDCName(string|int(0)server, stringdomain)
Description: Get name of the domain controller from a server.
Parameter server: Server the domain exists on.
Parameter domain: Domain to get the domain controller for.
Returns: Returns the name of the domain controller on success. Throws errors on failure.
Note: This function is only available on some Win32 systems.
See also: NetUserGetInfo(), NetUserEnum(), NetGroupEnum(), NetLocalGroupEnum(), NetUserGetGroups(), NetUserGetLocalGroups(), NetGroupGetUsers(), NetLocalGroupGetMembers(), NetGetAnyDCName()

Method NetGroupEnum

Description

Get information about network groups.

Parameter server

Server the groups exist on.

Parameter level

Information level. One of:

0

1

2

Returns

Returns an array on success. Throws errors on failure.

FIXME

Document the return value.

Note

This function is only available on some Win32 systems.

See also

NetUserGetInfo(), NetUserEnum(), NetLocalGroupEnum(), NetUserGetGroups(), NetUserGetLocalGroups(), NetGroupGetUsers(), NetLocalGroupGetMembers(), NetGetDCName(), NetGetAnyDCName()

Method NetGroupGetUsers

array(string|array(int|string)) NetGroupGetUsers(string|int(0)server, stringgroup, int|voidlevel)

Description

Get information about group membership for a network group.

Parameter server

Server the groups exist on.

Parameter group

Group to retrieve members for.

Parameter level

Information level. One of:

0

1

Returns

Returns an array on success. Throws errors on failure.

FIXME

Document the return value.

Note

This function is only available on some Win32 systems.

See also

NetUserGetInfo(), NetUserEnum(), NetGroupEnum(), NetLocalGroupEnum(), NetUserGetGroups(), NetUserGetLocalGroups(), NetLocalGroupGetMembers(), NetGetDCName(), NetGetAnyDCName()

Method NetLocalGroupEnum

array(array(string|int)) NetLocalGroupEnum(string|int(0)|voidserver, int|voidlevel)

Description

Get information about local network groups.

Parameter server

Server the groups exist on.

Parameter level

Information level. One of:

0

1

Returns

Returns an array on success. Throws errors on failure.

FIXME

Document the return value.

Note

This function is only available on some Win32 systems.

See also

NetUserGetInfo(), NetUserEnum(), NetGroupEnum(), NetUserGetGroups(), NetUserGetLocalGroups(), NetGroupGetUsers(), NetLocalGroupGetMembers(), NetGetDCName(), NetGetAnyDCName()

Method NetLocalGroupGetMembers

array(string|array(int|string)) NetLocalGroupGetMembers(string|int(0)server, stringgroup, int|voidlevel)

Description

Get information about group membership for a network group.

Parameter server

Server the groups exist on.

Parameter group

Group to retrieve members for.

Parameter level

Information level. One of:

0

1

2

3

Returns

Returns an array on success. Throws errors on failure.

FIXME

Document the return value.

Note

This function is only available on some Win32 systems.

See also

NetUserGetInfo(), NetUserEnum(), NetGroupEnum(), NetLocalGroupEnum(), NetUserGetGroups(), NetUserGetLocalGroups(), NetGroupGetUsers(), NetGetDCName(), NetGetAnyDCName()

Method NetSessionEnum

array(int|string) NetSessionEnum(string|int(0)server, string|int(0)client, string|int(0)user, intlevel)

Description

Get session information.

Parameter level

One of

0

1

2

10

502

Note

This function is only available on some Win32 systems.

Method NetUserEnum

Description

Get information about network users.

Parameter server

Server the users exist on.

Parameter level

Information level. One of:

0

1

2

3

10

11

20

Returns

Returns an array on success. Throws errors on failure.

FIXME

Document the return value.

Note

This function is only available on some Win32 systems.

See also

NetUserGetInfo(), NetGroupEnum()NetLocalGroupEnum(), NetUserGetGroups(), NetUserGetLocalGroups(), NetGroupGetUsers(), NetLocalGroupGetMembers(), NetGetDCName(), NetGetAnyDCName()

Method NetUserGetGroups

array(array(string|int)) NetUserGetGroups(string|int(0)server, stringuser, int|voidlevel)

Description

Get information about group membership for a network user.

Parameter server

Server the groups exist on.

Parameter user

User to retrieve groups for.

Parameter level

Information level. One of:

0

1

Returns

Returns an array on success. Throws errors on failure.

FIXME

Document the return value.

Note

This function is only available on some Win32 systems.

See also

NetUserGetInfo(), NetUserEnum(), NetGroupEnum(), NetLocalGroupEnum(), NetUserGetLocalGroups(), NetGroupGetUsers(), NetLocalGroupGetMembers(), NetGetDCName(), NetGetAnyDCName()

Method NetUserGetInfo

string|array(string|int) NetUserGetInfo(stringusername, string|int(0)server, int|voidlevel)

Description

Get information about a network user.

Parameter username

User name of the user to get information about.

Parameter server

Server the user exists on.

Parameter level

Information level. One of:

0

1

2

3

10

11

20

Returns

Returns an array on success. Throws errors on failure.

FIXME

Document the return value.

Note

This function is only available on some Win32 systems.

See also

NetUserEnum(), NetGroupEnum()NetLocalGroupEnum(), NetUserGetGroups(), NetUserGetLocalGroups(), NetGroupGetUsers(), NetLocalGroupGetMembers(), NetGetDCName(), NetGetAnyDCName()

Method NetUserGetLocalGroups

array(string) NetUserGetLocalGroups(string|int(0)server, stringuser, int|voidlevel, int|voidflags)

Description

Get information about group membership for a local network user.

Parameter server

Server the groups exist on.

Parameter user

User to retrieve groups for.

Parameter level

Information level. One of:

0

Parameter flags

Zero, of one of the following:

LG_INCLUDE_INDIRECT

Returns

Returns an array on success. Throws errors on failure.

FIXME

Document the return value.

Note

This function is only available on some Win32 systems.

See also

NetUserGetInfo(), NetUserEnum(), NetGroupEnum(), NetLocalGroupEnum(), NetUserGetGroups(), NetGroupGetUsers(), NetLocalGroupGetMembers(), NetGetDCName(), NetGetAnyDCName()

Method NetWkstaUserEnum

array(mixed) NetWkstaUserEnum(string|int(0)server, intlevel)

Parameter level

One of

0

1

Note

This function is only available on some Win32 systems.

Method SetFileAttributes: intSetFileAttributes(string(8bit)filename)
Description: Set the file attributes for the specified file.
Note: This function is only available on Win32 systems.
See also: GetFileAttributes()

Method SetNamedSecurityInfo: intSetNamedSecurityInfo(stringname, mapping(string:mixed) options)
Note: This function is only available on some Win32 systems.
See also: GetNamedSecurityInfo()

Method chmod: voidchmod(stringpath, intmode)
Description: Sets the protection mode of the specified path.
Note: Throws errors on failure.
See also: Stdio.File->open(), errno()

Method chown

voidchown(stringpath, intuid, intgid, void|intsymlink)

Description

Sets the owner and group of the specified path.

If symlink is set and path refers to a symlink, then the owner and group for the symlink are set. Symlinks are dereferenced otherwise.

Note

Throws errors on failure.

This function is not available on all platforms. On some platforms the symlink flag isn't supported. In that case, the function does nothing if path is a symlink.

Method chroot

intchroot(stringnewroot)
intchroot(Stdio.Filenewroot)

Description

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

Returns

A nonzero value is returned if the call is successful. If there's an error then zero is returned and errno is set appropriately.

Note

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

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

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

Note

On success the current working directory will be changed to the new "/". This behavior was added in Pike 7.9.

Note

This function could be interrupted by signals prior to Pike 7.9.

Method cleargroups

voidcleargroups()

Description

Clear the supplemental group access list.

Note

Throws errors on failure.

This function is not available on all platforms.

See also

setgroups(), initgroups(), getgroups()

Method clonefile: voidclonefile(stringfrom, stringto)
Description: Copy a file from with copy-on-write semantics to the destination named to.
Note: This function is currently only available on macOS and Linux, and then only when from and to reference a common file system with copy-on-write support (e.g. an APFS volume).
See also: hardlink(), symlink()

Method closelog: voidcloselog()
FIXME: Document this function.

Method daemon: intdaemon(intnochdir, intnoclose)
Description: Low level system daemon() function, see also Process.daemon()

Method drop_privs: voiddrop_privs(stringuser, void|stringgroup, void|intexception)
Description: Drops the process privileges to the provided user and optionally group. If no group is provided the default group for the user is used.
Parameter exception: If true, an error exception will be thrown if

Method dumpable

booldumpable(bool|voidval)

Description

Get and/or set whether this process should be able to dump core.

Parameter val

Optional argument to set the core dumping state.

`0`	Disable core dumping for this process.
`1`	Enable core dumping for this process.

Returns

Returns 1 if this process currently is capable of dumping core, and 0 (zero) if not.

Note

This function is currently only available on some versions of Linux.

Method endgrent: intendgrent()
Description: Closes the /etc/groups file after using the getgrent function.
See also: get_all_groups()getgrent()setgrent()

Method endpwent: intendpwent()
Description: Closes the passwd source opened by getpwent function using the systemfunction endpwent(3).
Returns: Always 0 (zero)
See also: get_all_users()getpwent()setpwent()

Method get_home: string|zeroget_home()
Description: Get the full path for the current user's home directory
Returns: the full path to the current user's home directory, or zero if the appropriate environment variables have not been set.
Note: This method uses the standard environment variables for various systems to determine the home directory.

Method get_netinfo_property

array(string) get_netinfo_property(stringdomain, stringpath, stringproperty)

Description

Queries a NetInfo server for property values at the given path.

Parameter domain

NetInfo domain. Use "." for the local domain.

Parameter path

NetInfo path for the property.

Parameter property

Name of the property to return.

Returns

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.

Example

system.get_netinfo_property(".", "/locations/resolver", "domain");
   ({
      "idonex.se"
   })

Note

Only available on operating systems which have NetInfo libraries installed.

Method get_user: string|zeroget_user()
Description: Get the username of the user that started the process.
Returns: the username of the user "associated" with the current process, or zero if a method to find this information does not exist on the current system.
Note: On NT systems, this returns the user the current thread is running as, while on Unix-like systems this function returns the user that started the process (rather than the effective user)..

Method getegid: intgetegid()
Description: Get the effective group ID.
See also: setuid, getuid, setgid, getgid, seteuid, geteuid, setegid

Method geteuid: intgeteuid()
Description: Get the effective user ID.
See also: setuid, getuid, setgid, getgid, seteuid, getegid, setegid

Method getgid: intgetgid()
Description: Get the real group ID.
See also: setuid, getuid, setgid, seteuid, geteuid, getegid, setegid

Method getgrent

array(int|string|array(string)) getgrent()

Description

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!

Returns

An array with the information about the group

Array
`string0`	Group name
`string1`	Group password (encrypted)
`int2`	ID of the group
`array3..`	Array with UIDs of group members

See also

get_all_groups()getgrnam()getgrgid()

Method getgroups

array(int) getgroups()

Description

Get the current supplemental group access list for this process.

Note

Throws errors on failure.

This function is not available on all platforms.

See also

setgroups(), cleargroups(), initgroups(), getgid(), getgid(), getegid(), setegid()

Method gethostbyaddr: array(string|array(string)) gethostbyaddr(stringaddr)
Description: Returns an array with information about the specified IP address.
Returns: The returned array contains the same information as that returned by gethostbyname().
Note: This function only exists on systems that have the gethostbyaddr(2) or similar system call.
See also: gethostbyname()

Method gethostbyname

array(string|array(string)) gethostbyname(stringhostname)

Description

Returns an array with information about the specified host.

Returns

The returned array contains the following:

Array
`stringhostname`	Name of the host.
`array(string) ips`	Array of IP numbers for the host.
`array(string) aliases`	Array of alternative names for the host.

Note

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

See also

gethostbyaddr()

Method gethostname: stringgethostname()
Description: Returns a string with the name of the host.
Note: This function only exists on systems that have the gethostname(2) or uname(2) system calls.

Method getitimer

array(float) getitimer(inttimer)

Description

Shows the state of the selected timer.

Returns

Array
`float0`	The interval of the timer.
`float1`	The value of the timer.

Parameter timer

One of ITIMER_REAL, ITIMER_VIRTUAL and ITIMER_PROF.

Method getloadavg

array(float) getloadavg()

Description

Get system load averages.

Returns

Array
`float0`	Load average over the last minute.
`float1`	Load average over the last 5 minutes.
`float2`	Load average over the last 15 minutes.

Method getpgrp

intgetpgrp(int|voidpid)

Description

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.

Note

Not all platforms support getting the process group for other processes.

Not supported on all platforms.

See also

getpid, getppid

Method getpid: intgetpid()
Description: Returns the process ID of this process.
See also: getppid, getpgrp

Method getppid: intgetppid()
Description: Returns the process ID of the parent process.
See also: getpid, getpgrp

Method getpwent

array(int|string) getpwent()

Description

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.

Returns

An array with the information about the user

Array
`string0`	Users username (loginname)
`string1`	User password (encrypted)
`int2`	Users ID
`int3`	Users primary group ID
`string4`	Users real name an possibly some other info
`string5`	Users home directory
`string6`	Users shell

0 if EOF.

See also

get_all_users()getpwnam()getpwent()setpwent()endpwent()

Method getrlimit

array(int) getrlimit(stringresource)

Description

Returns the current process limitation for the selected resource.

Parameter 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`

Returns

Array
`int0`	The soft limit for the resource. `-1` means no limit.
`int1`	The hard limit for the resource. `-1` means no limit.

Note

This function nor all the resources are available on all systems.

See also

getrlimits, setrlimit

Method getrlimits: mapping(string:array(int)) getrlimits()
Description: Returns all process limits in a mapping.
See also: getrlimit, setrlimit

Method getrusage

mapping(string:int) getrusage()

Description

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

Returns a mapping describing the current resource usage:

`"utime" : int`	Time in milliseconds spent in user code.
`"stime" : int`	Time in milliseconds spent in system calls.
`"maxrss" : int`	Maximum used resident size in kilobytes. [1]
`"ixrss" : int`	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" : int`	Quote from GNU libc: An integral value expressed the same way, which is the amount of unshared memory used for data. [1]
`"isrss" : int`	Quote from GNU libc: An integral value expressed the same way, which is the amount of unshared memory used for stack space. [1]
`"minflt" : int`	Minor page faults, i.e. TLB misses which required no disk I/O.
`"majflt" : int`	Major page faults, i.e. paging with disk I/O required.
`"nswap" : int`	Number of times the process has been swapped out entirely.
`"inblock" : int`	Number of block input operations.
`"oublock" : int`	Number of block output operations.
`"msgsnd" : int`	Number of IPC messsages sent.
`"msgrcv" : int`	Number of IPC messsages received.
`"nsignals" : int`	Number of signals received.
`"nvcsw" : int`	Number of voluntary context switches (usually to wait for some service).
`"nivcsw" : int`	Number of preemptions, i.e. context switches due to expired time slices, or when processes with higher priority were scheduled.
`"sysc" : int`	Number of system calls. [2]
`"ioch" : int`	Number of characters read and written. [2]
`"rtime" : int`	Elapsed real time (ms). [2]
`"ttime" : int`	Elapsed system trap (system call) time (ms). [2]
`"tftime" : int`	Text page fault sleep time (ms). [2]
`"dftime" : int`	Data page fault sleep time (ms). [2]
`"kftime" : int`	Kernel page fault sleep time (ms). [2]
`"ltime" : int`	User lock wait sleep time (ms). [2]
`"slptime" : int`	Other sleep time (ms). [2]
`"wtime" : int`	Wait CPU (latency) time (ms). [2]
`"stoptime" : int`	Time spent in stopped (suspended) state. [2]
`"brksize" : int`	Heap size. [3]
`"stksize" : int`	Stack size. [3]

Note

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

See also

gethrvtime()

Method getsid: intgetsid(int|voidpid)
Description: Get the process session ID for the given process. If pid is not specified, the session ID for the current process will be returned.
Note: This function is not available on all platforms.
Throws: Throws an error if the system call fails.
See also: getpid, getpgrp, setsid

Method gettimeofday: array(int) gettimeofday()
Description: 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).
See also: time(), gethrtime()

Method getuid: intgetuid()
Description: Get the real user ID.
See also: setuid, setgid, getgid, seteuid, geteuid, setegid, getegid

Method hardlink: voidhardlink(stringfrom, stringto)
Description: Create a hardlink named to from the file from.
Note: This function is not available on all platforms.
See also: symlink(), clonefile(), mv(), rm()

Method hw_random: string(8bit)hw_random(int(0..)length)
Description: Read a specified number of bytes from the hardware random generator, if available. This function will not exist if hardware random is not available. Currently only supports Intel RDRAND CPU instruction.

Method initgroups

voidinitgroups(stringname, intbase_gid)

Description

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

Note

Throws errors on failure.

This function is not available on all platforms.

See also

setuid(), getuid(), setgid(), getgid(), seteuid(), geteuid(), setegid(), getegid(), getgroups(), setgroups()

Method innetgr: boolinnetgr(stringnetgroup, string|voidmachine, string|voiduser, string|voiddomain)
Description: 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.
Note: This function isn't available on all platforms.

Method nanosleep

floatnanosleep(int|floatseconds)

Description

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

See also

predef::sleep()sleep()usleep()

Note

May not be present; only exists if the function exists in the current system.

Method normalize_path

utf8_stringnormalize_path(utf8_stringpath)

Description

Normalize an existing MacOS X file system path.

The following transformations are currently done:

Relative paths are expanded to absolute paths.
Initial components "/private" and "/var/automount" (or both) are removed if the result indicates the same directory node.
Trailing slashes ('/') are removed.
Current- and parent-directory path components ("." and "..") are followed, similar to combine_path.
Case-information in directory and file names is restored.
File fork information is stripped (ie all stuff after the first non-directory in the path is stripped).

Returns

A normalized absolute path without trailing slashes.

May throw errors on failure, e.g. if the file or directory doesn't exist or if the path is not valid UTF-8.

See also

combine_path()

Method normalize_path

utf8_stringnormalize_path(string(8bit)path)

Description

Normalize an existing Windows file system path.

The following transformations are currently done:

If the path is not valid UTF-8, it will be converted into UTF-8.
Forward slashes ('/') are converted to backward slashes ('\').
Trailing slashes are removed, except a single slash after a drive letter (e.g. "C:\" is returned instead of "C:").
Extraneous empty extensions are removed.
Short filenames are expanded to their corresponding long variants.
Relative paths are expanded to absolute paths.
Current- and parent-directory path components ("." and "..") are followed, similar to combine_path.
Case-information in directory and file names is restored.
Drive letters are returned in uppercase.
The host and share parts of UNC paths are returned in lowercase.

Returns

A normalized absolute path without trailing slashes.

Throws errors on failure, e.g. if the file or directory doesn't exist.

Note

File fork information is currently not supported (invalid data).

Note

In Pike 7.6 and earlier, this function didn't preserve a single slash after drive letters, and it didn't convert the host and share parts of an UNC path to lowercase.

See also

combine_path(), combine_path_nt()

Method openlog

voidopenlog(stringident, intoptions, intfacility)

Description

Initializes the connection to syslogd.

Parameter ident.

The ident argument specifies an identifier to tag all logentries with.

Parameter options

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.

Parameter facility

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

`LOG_AUTH`	Authorization subsystem
`LOG_AUTHPRIV`
`LOG_CRON`	Crontab subsystem
`LOG_DAEMON`	System daemons
`LOG_KERN`	Kernel subsystem (NOT USABLE)
`LOG_LOCAL`	For local use
`LOG_LOCAL1`
`LOG_LOCAL2`
`LOG_LOCAL3`
`LOG_LOCAL4`
`LOG_LOCAL5`
`LOG_LOCAL6`
`LOG_LOCAL7`
`LOG_LPR`	Line printer spooling system
`LOG_MAIL`	Mail subsystem
`LOG_NEWS`	Network news subsystem
`LOG_SYSLOG`
`LOG_USER`
`LOG_UUCP`	UUCP subsystem

Note

Only available on systems with syslog(3).

Bugs

LOG_NOWAIT should probably always be specified.

See also

syslog, closelog

Method rdtsc: intrdtsc()
Description: Executes the rdtsc (clock pulse counter) instruction and returns the result.

Method readlink: stringreadlink(stringpath)
Description: Returns what the symbolic link path points to.
Note: This function is not available on all platforms.
See also: symlink()

Method resolvepath

string(8bit)resolvepath(string(8bit)path)

Description

Resolve all symbolic links of a pathname.

This function resolves all symbolic links, extra ``/'' characters and references to /./ and /../ in pathname, and returns the resulting absolute path, or 0 (zero) if an error occurs.

Note

This function is not available on all platforms.

See also

readlink(), symlink()

Method setegid: intsetegid(integid)
Description: Set the effective group ID to egid. If egid is -1 the uid for "nobody" will be used.
Returns: Returns the current errno.
Throws: Throws an error if there is no "nobody" user when egid is -1.
Note: This function isn't available on all platforms.

Method seteuid: intseteuid(inteuid)
Description: Set the effective user ID to euid. If euid is -1 the uid for "nobody" will be used.
Returns: Returns the current errno.
Throws: Throws an error if there is no "nobody" user when euid is -1.
Note: This function isn't available on all platforms.

Method setgid: intsetgid(intgid)
Description: 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: Throws an error if no "nobody" user when gid is -1.
Returns: Returns the current errno.
Note: This function is not available on all platforms.
See also: getuid(), setuid(), getgid(), seteuid(), geteuid(), setegid(), getegid()

Method setgrent: intsetgrent()
Description: Rewinds the getgrent pointer to the first entry
See also: get_all_groups()getgrent()endgrent()

Method setgroups

voidsetgroups(array(int) gids)

Description

Set the supplemental group access list for this process.

Note

Throws errors on failure.

This function is not available on all platforms.

See also

initgroups(), cleargroups(), getgroups(), getgid(), getgid(), getegid(), setegid()

Method setitimer: floatsetitimer(inttimer, int|floatvalue)
Description: Sets the timer to the supplied value. Returns the current timer interval.
Parameter timer: One of ITIMER_REAL, ITIMER_VIRTUAL and ITIMER_PROF.

Method setpgrp: intsetpgrp()
Description: Make this process a process group leader.
Note: Not supported on all platforms.

Method setproctitle: voidsetproctitle(stringtitle, mixed ... extra)
Description: Sets the processes title.

Method setpwent: intsetpwent()
Description: Resets the getpwent function to the first entry in the passwd source using the systemfunction setpwent(3).
Returns: Always 0 (zero)
See also: get_all_users()getpwent()endpwent()

Method setresgid: intsetresgid(intrgid, integid, intsgid)
Description: Sets the real, effective and saved group ID to rgid, egid and sgid respectively.
Returns: Returns zero on success and errno on failure.

Method setresuid: intsetresuid(intruid, inteuid, intsuid)
Description: Sets the real, effective and saved set-user-ID to ruid, euid and suid respectively.
Returns: Returns zero on success and errno on failure.

Method setrlimit: boolsetrlimit(stringresource, intsoft, inthard)
Description: Sets the soft and the hard process limit on a resource.
See also: getrlimit, getrlimits

Method setsid: intsetsid()
Description: Set a new process session ID for the current process, and return it.
Note: This function isn't available on all platforms.
Throws: Throws an error if the system call fails.
See also: getpid, setpgrp, getsid

Method setuid: intsetuid(intuid)
Description: Sets the real user ID, effective user ID and saved user ID to uid.
Returns: Returns the current errno.
Note: This function isn't available on all platforms.
See also: getuid(), setgid(), getgid(), seteuid(), geteuid(), setegid(), getegid()

Method sleep

intsleep(intseconds)

Description

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

Note

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.

See also

predef::sleep()usleep()nanosleep()

Method symlink: voidsymlink(stringfrom, stringto)
Description: Create a symbolic link named to that points to from.
Note: This function is not available on all platforms.
See also: hardlink(), readlink(), clonefile(), mv(), rm()

Method sync: voidsync()
Description: Flush operating system disk buffers to permanent storage.
Note: On some operating systems this may require administrative privileges.

Method syslog

voidsyslog(intpriority, stringmsg)

Description

Writes the message msg to the log with the priorities in priority.

Parameter priority

Priority is a bit vector with the wanted priorities or:ed together.

`0`	LOG_EMERG, system is unusable.
`1`	LOG_ALERT, action must be taken immediately.
`2`	LOG_CRIT, critical conditions.
`3`	LOG_ERR, error conditions.
`4`	LOG_WARNING, warnind conditions.
`5`	LOG_NOTICE, normal, but significant, condition.
`6`	LOG_INFO, informational message.
`7`	LOG_DEBUG, debug-level message.

Method umask

intumask(void|intmask)

Description

Set the current umask to mask.

If mask is not specified the current umask will not be changed.

Returns

Returns the old umask setting.

Method uname

mapping(string:string) uname()

Description

Get operating system information.

Returns

The resulting mapping contains the following fields:

`"sysname" : string`	Operating system name.
`"nodename" : string`	Hostname.
`"release" : string`	Operating system release.
`"version" : string`	Operating system version.
`"machine" : string`	Hardware architecture.
`"architecture" : string`	Basic instruction set architecture.
`"isalist" : string`	List of upported instruction set architectures. Usually space-separated.
`"platform" : string`	Specific model of hardware.
`"hw provider" : string`	Manufacturer of the hardware.
`"hw serial" : string`	Serial number of the hardware.
`"srpc domain" : string`	Secure RPC domain.

Note

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

Only the first five elements are always available.

Method usleep

voidusleep(intusec)

Description

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

Note

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.

See also

predef::sleep()sleep()nanosleep()

Method utime

voidutime(stringpath, intatime, intmtime, void|intsymlink)

Description

Set the last access time and last modification time for the path path to atime and mtime repectively. They are specified as unix timestamps with 1 second resolution.

If symlink is set and path refers to a symlink, then the timestamps for the symlink are set. Symlinks are dereferenced otherwise.

Note

Throws errors on failure.

This function is not available on all platforms. On some platforms the symlink flag isn't supported. In that case, the function does nothing if path is a symlink.

See also

System.set_file_atime, System.set_file_mtime

Class System.Memory

Description

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.

Method _sizeof: intsizeof(System.Memoryarg)
Description: returns the size of the memory (bytes). note: throws if not allocated

Method `[..]: string(8bit) res = System.Memory()[start..end]
Description: The range operator on the object gives a string containing the bytes in the range.

Method `[]: int(8bit) res = System.Memory()[ pos ]
Description: Indexing the object returns the value of the byte at that position.

Method `[]=: System.Memory()[ pos ] = char
Description: Set the value of the byte at the specified position.

Method allocate: voidallocate(intbytes)
voidallocate(intbytes, int(8bit)fill)

Method cast: (string)System.Memory() (array)System.Memory()
Description: Cast to string or array.
Note: Throws if not allocated.

Method create: System.MemorySystem.Memory()
System.MemorySystem.Memory(string|Stdio.Filefilename_to_mmap)
System.MemorySystem.Memory(intshmkey, intshmsize, intshmflg)
System.MemorySystem.Memory(intbytes_to_allocate)
Description: 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.

Method free: voidfree()
Description: Free the allocated or <tt>mmap</tt>ed memory.

Method mmap
Method mmap_private: intmmap(string|Stdio.Filefile)
intmmap(string|Stdio.Filefile, intoffset, intsize)
intmmap_private(string|Stdio.Filefile)
intmmap_private(string|Stdio.Filefile, intoffset, intsize)
Description: 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.

Method pread
Method pread16
Method pread32
Method pread16i
Method pread32i
Method pread16n
Method pread32n

string(8bit)pread(int(0..)pos, int(0..)len)
string(16bit)pread16(int(0..)pos, int(0..)len)
stringpread32(int(0..)pos, int(0..)len)
string(16bit)pread16i(int(0..)pos, int(0..)len)
stringpread32i(int(0..)pos, int(0..)len)
string(16bit)pread16n(int(0..)pos, int(0..)len)
stringpread32n(int(0..)pos, int(0..)len)

Description

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

Method pwrite
Method pwrite16
Method pwrite32
Method pwrite16i
Method pwrite32i

intpwrite(int(0..)pos, stringdata)
intpwrite16(int(0..)pos, stringdata)
intpwrite32(int(0..)pos, stringdata)
intpwrite16i(int(0..)pos, stringdata)
intpwrite32i(int(0..)pos, stringdata)

Description

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

Method valid: boolvalid()
Description: returns 1 if the memory is valid, 0 if not allocated

Method writeable: boolwriteable()
Description: returns 1 if the memory is writeable, 0 if not

Class System.SID

Description

Security Identifier.

Objects of this class are returned by LookupAccountName().

See also

LookupAccountName()

Method `==: bool res = System.SID() == x

Method account

array(string|int) account(string|voidsys)

Returns

Returns an array with the following content:

Array
`string0`	Account name.
`string1`	Domain name.
`int(0..)2`	Account type.

Returns an array with three zeroes on failure.

Note

This function is only available on some Win32 systems.

Class System.SecurityContext

Method create: System.SecurityContextSystem.SecurityContext(stringpkgName)

Method gen_context: array(string|int) gen_context(string)

Method get_last_context: array(string|int) get_last_context()

Method get_last_error: intget_last_error()

Method get_username: stringget_username()

Method is_done: intis_done()

Method type: stringtype()

Class System.TM

Description: A wrapper for the system struct tm time keeping structure. This can be used as a (very) lightweight alternative to Calendar.

Variable gmtoff: int System.TM.gmtoff
Description: The offset from GMT for the time in this tm-struct

Variable sec
Variable min
Variable hour
Variable mday
Variable mon
Variable year

int(0..60) System.TM.sec
int(0..59) System.TM.min
int(0..59) System.TM.hour
int(1..31) System.TM.mday
int(0..11) System.TM.mon
int System.TM.year

Description

The various fields in the structure. Note that setting these might cause other fields to be recalculated, as an example, adding 1000 to the hour field would advance the 'mday', 'mon' and possibly 'year' fields.

When read the fields are always normalized.

Unlike the system struct tm the 'year' field is not year-1900, instead it is the actual year.

Variable isdst: int System.TM.isdst
Description: True if daylight-saving is in effect. If this field is -1 (the default) it (and the timezone info) will be updated automatically using the timezone rules.

Variable wday: int System.TM.wday
Description: The day of the week, sunday is 0, saturday is 6. This is calculated from the other fields and can not be changed directly.

Variable yday: int System.TM.yday
Description: The day of the year, from 0 (the first day) to 365 This is calculated from the other fields and can not be changed directly.

Variable zone: string|zero System.TM.zone
Description: The timezone of this structure

Method asctime: stringasctime()
Description: Return a string representing the time. Mostly useful for debug purposes.
Note: In versions of Pike prior to Pike 8.0.1866 the exact format was very locale (see Gettext.setlocale) and OS dependent.

Method cast

(int)System.TM() (string)System.TM()

Description

Casted to an integer unix_time will be returned.

Casting to a string will call asctime.

Method create: System.TMSystem.TM()
Description: Construct a new TM, all fields will be set to 0.

Method create: System.TMSystem.TM(int|Gmp.mpzt)
Description: Create a new TM initialized from a unix time_t. The timezone will always be UTC when using this function.

Method create: System.TMSystem.TM(intyear, int(0..11)mon, int(1..31)mday, int(0..24)hour, int(0..59)min, int(0..59)sec, string|voidtimezone)
Description: Construct a new time using the given values. Slightly faster than setting them individually.

Method gmtime: boolgmtime(inttime)
Description: Initialize the struct tm to the UTC time for the specified unix time_t.

Method gmtime: boolgmtime(Gmp.mpztime)
Description: Initialize the struct tm to the UTC time for the specified unix time_t.

Method localtime: boollocaltime(inttime)
Description: Initialize the struct tm to the local time for the specified unix time_t.

Method strftime

string(1..255)strftime(string(1..255)format)

Description

Format the timestamp into a string.

See predef::strftime() for details.

See also

strptime(), predef::strftime(), predef::strptime(), Gettext.setlocale()

Method strptime: boolstrptime(string(1..255)format, string(1..255)data)
Note: The order of format and data are reversed compared to predef::strptime().
See also: strftime(), predef::strftime(), predef::strptime()

Method unix_time: intunix_time()
Description: Return the unix time corresponding to this time_t. If no time can be parsed from the structure -1 is returned.

Class System.Time

Description: The current time as a structure containing a sec and a usec member.

Variable sec
Variable usec: int System.Time.sec
int System.Time.usec
Description: The number of seconds and microseconds since the epoch and the last whole second, respectively. (See also predef::time())
Note: Please note that these variables will continually update when they are requested, there is no need to create new Time() objects.

Variable usec_full: int System.Time.usec_full
Description: The number of microseconds since the epoch. Please note that pike needs to have been compiled with bignum support for this variable to contain sensible values.

Method create

System.TimeSystem.Time(intfast)

Description

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.

Class System.Timer

Method create

System.TimerSystem.Timer(int|voidfast)

Description

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 more or less inexact timekeeping. The pike maintained time is only updated when a Pike.Backend object stops waiting and starts executing code.

Method get: floatget()
Description: 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.

Method peek: floatpeek()
Description: Return the time in seconds since the last time get was called.

Module System.FSEvents

Inherit _FSEvents

inherit System._FSEvents : _FSEvents

Description

The System.FSEvents module provides an interface to FSEvents. FSEvents is an API in Mac OS X which allows an application to register for notifications of changes to a given directory tree without forcing the application to continously poll the directory tree.

This module is designed for use in asynchronous, or backend mode. That is, rather than polling for changes, a function you specify will be called when events of interest occur.

Note

This module requires the presence and use of a CFRunLoop based Backend object, otherwise this module will not receive events from the OS. CFRunLoop based backends are avilable on Mac OS X 10.5 and higher.

See also

Pike.PollDeviceBackend.enable_core_foundation

Constant kFSEventStreamCreateFlagFileEvents: constant System.FSEvents.kFSEventStreamCreateFlagFileEvents
Description: Available in MacOS X 10.7 and newer.

Constant kFSEventStreamCreateFlagIgnoreSelf: constant System.FSEvents.kFSEventStreamCreateFlagIgnoreSelf
Description: Available in MacOS X 10.6 and newer.

Constant kFSEventStreamCreateFlagNoDefer: constant System.FSEvents.kFSEventStreamCreateFlagNoDefer

Constant kFSEventStreamCreateFlagNone: constant System.FSEvents.kFSEventStreamCreateFlagNone

Constant kFSEventStreamCreateFlagWatchRoot: constant System.FSEvents.kFSEventStreamCreateFlagWatchRoot

Constant kFSEventStreamEventFlagChangeOwner: constant System.FSEvents.kFSEventStreamEventFlagChangeOwner
Description: Available in MacOS X 10.7 and newer.

Constant kFSEventStreamEventFlagEventIdsWrapped: constant System.FSEvents.kFSEventStreamEventFlagEventIdsWrapped

Constant kFSEventStreamEventFlagFinderInfoMod: constant System.FSEvents.kFSEventStreamEventFlagFinderInfoMod
Description: Available in MacOS X 10.7 and newer.

Constant kFSEventStreamEventFlagHistoryDone: constant System.FSEvents.kFSEventStreamEventFlagHistoryDone

Constant kFSEventStreamEventFlagInodeMetaMod: constant System.FSEvents.kFSEventStreamEventFlagInodeMetaMod
Description: Available in MacOS X 10.7 and newer.

Constant kFSEventStreamEventFlagIsDir: constant System.FSEvents.kFSEventStreamEventFlagIsDir
Description: Available in MacOS X 10.7 and newer.

Constant kFSEventStreamEventFlagIsFile: constant System.FSEvents.kFSEventStreamEventFlagIsFile
Description: Available in MacOS X 10.7 and newer.

Constant kFSEventStreamEventFlagIsSymlink: constant System.FSEvents.kFSEventStreamEventFlagIsSymlink
Description: Available in MacOS X 10.7 and newer.

Constant kFSEventStreamEventFlagItemCreated: constant System.FSEvents.kFSEventStreamEventFlagItemCreated
Description: Available in MacOS X 10.7 and newer.

Constant kFSEventStreamEventFlagItemModified: constant System.FSEvents.kFSEventStreamEventFlagItemModified
Description: Available in MacOS X 10.7 and newer.

Constant kFSEventStreamEventFlagItemRemoved: constant System.FSEvents.kFSEventStreamEventFlagItemRemoved
Description: Available in MacOS X 10.7 and newer.

Constant kFSEventStreamEventFlagKernelDropped: constant System.FSEvents.kFSEventStreamEventFlagKernelDropped

Constant kFSEventStreamEventFlagMount: constant System.FSEvents.kFSEventStreamEventFlagMount

Constant kFSEventStreamEventFlagMustScanSubDirs: constant System.FSEvents.kFSEventStreamEventFlagMustScanSubDirs

Constant kFSEventStreamEventFlagNone: constant System.FSEvents.kFSEventStreamEventFlagNone

Constant kFSEventStreamEventFlagRenamed: constant System.FSEvents.kFSEventStreamEventFlagRenamed
Description: Available in MacOS X 10.7 and newer.

Constant kFSEventStreamEventFlagRootChanged: constant System.FSEvents.kFSEventStreamEventFlagRootChanged

Constant kFSEventStreamEventFlagUnmount: constant System.FSEvents.kFSEventStreamEventFlagUnmount

Constant kFSEventStreamEventFlagUserDropped: constant System.FSEvents.kFSEventStreamEventFlagUserDropped

Constant kFSEventStreamEventFlagXattrMod: constant System.FSEvents.kFSEventStreamEventFlagXattrMod
Description: Available in MacOS X 10.7 and newer.

Constant kFSEventStreamEventIdSinceNow: constant System.FSEvents.kFSEventStreamEventIdSinceNow

Method describe_event_flag: stringdescribe_event_flag(intmask)
Description: describe the event flags associated with an event.
Returns: a string describing the flags set.

Class System.FSEvents.BlockingEventStream

Description: A variation of EventStream that provides a blocking interface.
Note: A quirk of the underlying IO subsystem in CoreFoundation is that there is exactly one runloop per thread. Because FSEvents uses CoreFoundation, this means that there's no meaningful way to specify which backend should process these events. Therefore, always make sure that the thread you create the EventStream object is the same one you read events from, otherwise read_event will run not run the EventLoop that this EventStream is registered with, resulting in events never being delivered.

Inherit EventStream: inherit .EventStream : EventStream

Method create: System.FSEvents.BlockingEventStreamSystem.FSEvents.BlockingEventStream(array(string) paths, floatlatency, int|voidsince_when, int|voidflags)

Method read_event: mixedread_event(void|floattimeout)
Description: wait for an event to be received, and return it.
Parameter timeout: an optional limit to the amount of time we're willing to wait

Class System.FSEvents.EventStream

Method add_path: voidadd_path(stringpath)
Description: Add a path to the monitor list.
Parameter path
Note: this can only be called when the monitor is stopped.

Method create

System.FSEvents.EventStreamSystem.FSEvents.EventStream(array(string) paths, floatlatency, int|voidsince_when, int|voidflags)

Description

Creates a new Public.System.FSEvents.EventStream object

Parameter paths

An array with each element containing a path to a directory, signifying the root of a filesystem hierarchy to be watched for modifications.

Additional paths may be added later using add_path(), though only if the stream is stopped.

Parameter latency

The number of seconds the service should wait after hearing about an event from the kernel before passing it along to the client via its callback. Specifying a larger value may result in more effective temporal coalescing, resulting in fewer callbacks and greater overall efficiency.

Parameter since_when

The service will supply events that have happened after the given event ID. To ask for events "since now" pass the constant kFSEventStreamEventIdSinceNow. Do not pass zero for this value unless you want to receive events for the requested directories "since the beginning of time".

Parameter flags

Flags that modify the behavior of the stream being created. See Apple's FSEvents documentation for details of the various flags available.

Method flush_async

voidflush_async()

Description

Requests that the FS Events service to flush out any events that have occurred but have not yet been delivered, due to the latency parameter that was supplied when the stream was created.

This flushing occurs asynchronously -- events most likely will not have been delivered by the time this call returns.

Note

Only call this function after the stream has been started, via start().

Method flush_sync

voidflush_sync()

Description

Requests that the FS Events service to flush out any events that have occurred but have not yet been delivered, due to the latency parameter that was supplied when the stream was created.

Flushing synchronously when using this method; clients will have received all the callbacks by the time this call returns to them.

Note

Only call this function after the stream has been started, via start().

Method is_started: intis_started()
Description: Has start() been called?

Method set_callback

voidset_callback(function(:void) callback)

Description

Sets the function that will be called when a file notification event is received.

The method signature for the callback is:

void event_callback(string path, int flags, int event_id)

Method start

voidstart()

Description

Requests that new events be delivered to this EventStream.

If a value was supplied for the since_when parameter then "historical" events will be sent via your callback first, then a HistoryDone event, then "contemporary" events will be sent on an ongoing basis.

Method stop: voidstop()
Description: Stops watching for new events.

Module System.Inotify

Description: This module implements an API to linux inotify. It is available on all kernels from version 2.6.13 onwards. Inotify offers fast and scalable file notifications.

Constant IN_ACCESS
Constant IN_ATTRIB
Constant IN_CLOSE
Constant IN_CLOSE_WRITE
Constant IN_CLOSE_NOWRITE
Constant IN_CREATE
Constant IN_DELETE
Constant IN_DELETE_SELF
Constant IN_MODIFY
Constant IN_MOVE_SELF
Constant IN_MOVED_FROM
Constant IN_MOVED_TO
Constant IN_OPEN
Constant IN_MOVE
Constant IN_DONT_FOLLOW
Constant IN_MASK_ADD
Constant IN_ONESHOT
Constant IN_ONLYDIR
Constant IN_IGNORED
Constant IN_ISDIR
Constant IN_Q_OVERFLOW
Constant IN_UNMOUNT: constant System.Inotify.IN_ACCESS
constant System.Inotify.IN_ATTRIB
constant System.Inotify.IN_CLOSE
constant System.Inotify.IN_CLOSE_WRITE
constant System.Inotify.IN_CLOSE_NOWRITE
constant System.Inotify.IN_CREATE
constant System.Inotify.IN_DELETE
constant System.Inotify.IN_DELETE_SELF
constant System.Inotify.IN_MODIFY
constant System.Inotify.IN_MOVE_SELF
constant System.Inotify.IN_MOVED_FROM
constant System.Inotify.IN_MOVED_TO
constant System.Inotify.IN_OPEN
constant System.Inotify.IN_MOVE
constant System.Inotify.IN_CLOSE
constant System.Inotify.IN_DONT_FOLLOW
constant System.Inotify.IN_MASK_ADD
constant System.Inotify.IN_ONESHOT
constant System.Inotify.IN_ONLYDIR
constant System.Inotify.IN_IGNORED
constant System.Inotify.IN_ISDIR
constant System.Inotify.IN_Q_OVERFLOW
constant System.Inotify.IN_UNMOUNT
Description: Please have a look at the inotify(7) manpage for information about these constants.
Note: Some constants may not be available when the module has been compiled on a machine with linux kernel before 2.6.15. See the manpage for more details.

Constant IN_ALL_EVENTS: constant System.Inotify.IN_ALL_EVENTS
Description: This is a derived constant that is not part of the standard inotify API. It is the union of all other constants.

Method describe_mask: stringdescribe_mask(intmask)
Description: Turn an event mask into a human readable representation. This is used for debugging purpose.

Method parse_event

array(string|int) parse_event(stringdata)

Description

Parses one inotify_event struct from data.

Returns

Returns an array consisting of

Array
`int0`	The watch descriptor returned by `_Instance()->add_watch()` when the watch for this file was added.
`int1`	An integer that describes the event that occured. See the inotify manpage for a list of possible events and their numerical identifiers.
`int2`	An integer cookie that can be used to group together different events that were triggered by moving a file from one location to another.
`string3`	The name of the file. This will only be present if the event happened to a file in a directory that was watched, e.g. with `System.Inotify.IN_CREATE`. Otherwise this will be 0.
`int4`	The length of the data that has been parsed. If the `data` string contains more than one inotify event, this parse function needs to be called again with the remainder as an argument.

Class System.Inotify.Instance

Description: More convenient interface to inotify(7). Automatically reads events from the inotify file descriptor and parses them.
Note: Objects of this class will be destructed when they go out of external references. As such they behave differently from other classes which use callbacks, e.g. Stdio.File.
Note: The number of inotify instances is limited by ulimits.

Inherit _Instance: inherit _Instance : _Instance

Method add_watch: intadd_watch(stringfilename, intmask, function(int, int, string, mixed ... :void) callback, mixed ... extra)
Description: Add a watch for a certain file and a set of events specified by mask. The function callback will be called when such an event occurs. The arguments to the callback will be the events mask, the cookie, the filename and extra.
Returns: Returns a watch descriptor which can be used to remove the watch.
Note: When adding a second watch for the same file the old one will be removed unless System.Inotify.IN_MASK_ADD is contained in mask.
Note: The mask of an event may be a subset of the mask given when adding the watch.
Note: In case the watch is added for a regular file, the filename will be passed to the callback. In case the watch is added for a directory, the name of the file to which the event happened inside the directory will be concatenated.

Class System.Inotify._Instance

Description: Simple wrapper class that gives direct access to the inotify(7) interface. On create an inotify instance is initiated by calling inotify_init(2). Every object of this class has its own inotify file descriptor. Use this class only if you want direct access to the file descriptor to read from it manually. For a more user friendly interface use System.Inotify.Instance.
See also: System.Inotify.Instance

Variable event_callback: privatefunction(int, int, int, string:void) System.Inotify._Instance.event_callback
Description: Callback function that is called when an event is triggered.
See also: set_event_callback(), query_event_callback()

Method add_watch

intadd_watch(stringpath, intmask)

Description

Add a watch for a certain file or directory and specific events.

Adding more than one watch for a path will overwrite the previous watch unless System.Inotify.IN_MASK_ADD is contained in the mask.

Parameter path

Path of the file or directory.

Parameter mask

Integer mask specifying the event type. This can be a combination of different event types using bitwise OR. See the inotify manpage for possible values and their description. The values defined by the inotify header file are exported by System.Inotify as constants using the same names (e.g. System.Inotify.IN_CREATE).

Returns

Returns a watch descriptor on success, and -1 on filesystem-related failures, in which case errno() will indicate the cause. These typically indicate time of check, time of use race conditions. For other failures errors are thrown.

Note

Subdirectories are not watched. If you want to watch subdirectories as well, you need to add watches for them individually.

Note

At creation of a watch for a directory, simulated IN_CREATE-events with cookie 0x7fffffff will be added for the initial contents of the directory. This is to reduce the risk of losing state changes due to races. Note that is is not known whether these paths are in flux or not. Note also that there may be multiple notifications for content that is created at the moment the watch is created.

Note

In old versions of Pike errors were thrown for all failures.

See also

rm_watch(), parse_event()

Method get_event_callback: function(int, int, int, string:void) get_event_callback()
Description: Get the current event_callback.
See also: set_event_callback(), event_callback, poll()

Method poll

voidpoll()

Description

Check for any pending events.

Any pending events will be read and parsed, and event_callback will be called once for each event. The arguments to the event_callback will be:

Array
`int1`	The watch descriptor that was triggered.
`int2`	The event that was triggerend (one of `IN_*`).
`int3`	An integer cookie used to identify grouped events.
`string4`	The name of the path segment (if any).

Note

This function is called by the backend when there are events pending.

See also

set_event_callback()

Method query_fd: intquery_fd()
Returns: Returns the file descriptor associated with this inotify instance.

Method rm_watch: intrm_watch(intwd)
Description: Remove a watch.
Parameter wd: The watch descriptor that was returned by add_watch().

Method set_backend: voidset_backend(Pike.Backendbackend)
Description: Set the backend used for callbacks.
See also: set_event_callback(), set_nonblocking(), poll()

Method set_blocking

voidset_blocking()

Description

Disable backend callback mode.

The configured backend will stop calling poll(), so poll() will need to be called by hand.

See also

set_blocking(), poll()

Method set_event_callback: voidset_event_callback(function(int, int, int, string:void) cb)
Description: Set the event_callback.
See also: get_event_callback(), event_callback, poll()

Method set_nonblocking

voidset_nonblocking()

Description

Enable backend callback mode.

The configured backend will call poll() automatically as soon as there are events pending.

See also

set_blocking(), poll()

Module System.Wnotify

Description: An interface to Windows filesystem change information.

Constant FILE_NOTIFY_CHANGE_ATTRIBUTES: constant System.Wnotify.FILE_NOTIFY_CHANGE_ATTRIBUTES

Constant FILE_NOTIFY_CHANGE_DIR_NAME: constant System.Wnotify.FILE_NOTIFY_CHANGE_DIR_NAME

Constant FILE_NOTIFY_CHANGE_FILE_NAME: constant System.Wnotify.FILE_NOTIFY_CHANGE_FILE_NAME

Constant FILE_NOTIFY_CHANGE_LAST_WRITE: constant System.Wnotify.FILE_NOTIFY_CHANGE_LAST_WRITE

Constant FILE_NOTIFY_CHANGE_SECURITY: constant System.Wnotify.FILE_NOTIFY_CHANGE_SECURITY

Constant FILE_NOTIFY_CHANGE_SIZE: constant System.Wnotify.FILE_NOTIFY_CHANGE_SIZE

Class System.Wnotify.EventPoller

Method add_handle: voidadd_handle(NotificationHandlehandle)

Method poll: NotificationHandle|intpoll(void|floattimeout)

Class System.Wnotify.NotificationHandle

Method create: System.Wnotify.NotificationHandleSystem.Wnotify.NotificationHandle(stringpath, intwatch_subtree, intfilter)

Method get_error: intget_error()

Module Tools

Class Tools.PV

Description: Display a image on the screen. Requires GTK.

Inherit Window: inherit GTK.Window : Window

Typedef PVImage: typedefStandards.URI|string|Image.Image|Image.Layer|array(Image.Layer) Tools.PV.PVImage
Description: 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.

Method get_as_image: Image.Imageget_as_image(PVImagei)
Description: Return the current image as a Image object, with the alpha combining done.

Method save: voidsave(stringfilename, string|voidformat)
Description: 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.

Method scale: voidscale(floatfactor)
Description: Scale the image before display with the specified factor.

Method set_alpha_colors: voidset_alpha_colors(Image.Color.Colorc1, Image.Color.Color|voidc2)
Description: Set the colors used for the alpha combination. c2 is only used for the Squares alpha mode.
See also: set_alpha_mode()

Method set_alpha_mode: voidset_alpha_mode(AlphaModem)
Description: Set the alpha combining mode. m is one of Squares, Solid, None and AlphaOnly.

Method set_image: voidset_image(PVImagei)
Description: Change the image.

Enum Tools.PV.AlphaMode

Description

The alpha combination modes.

Use set_alpha_mode() to change the mode.

Constant AlphaOnly: constant Tools.PV.AlphaOnly
Description: Only show the alpha channel (if any).

Constant None: constant Tools.PV.None
Description: Ignore alpha.

Constant Solid: constant Tools.PV.Solid
Description: Solid color.

Constant Squares: constant Tools.PV.Squares
Description: Checkerboard pattern (default).

Module Tools.AutoDoc

Enum Tools.AutoDoc.Flags

Description: Flags affecting autodoc extractor behaviour.
See also: ProcessXML.extractXML(), MirarDocParser, Tools.Standalone.extract_autodoc()

Constant FLAG_COMPAT: constant Tools.AutoDoc.FLAG_COMPAT
Description: Attempt to be compatible with old Pike.

Constant FLAG_DEBUG: constant Tools.AutoDoc.FLAG_DEBUG
Description: Full verbosity.

Constant FLAG_KEEP_GOING: constant Tools.AutoDoc.FLAG_KEEP_GOING
Description: Attempt to keep going after errors.

Constant FLAG_NORMAL: constant Tools.AutoDoc.FLAG_NORMAL
Description: Normal verbosity.

Constant FLAG_NO_DYNAMIC: constant Tools.AutoDoc.FLAG_NO_DYNAMIC
Description: Reduce the amount of dynamic information in the generated files (line numbers, extractor version, extraction time, etc).

Constant FLAG_QUIET: constant Tools.AutoDoc.FLAG_QUIET
Description: Keep quiet about non-fatal errors.

Constant FLAG_VERBOSE: constant Tools.AutoDoc.FLAG_VERBOSE
Description: Extra verbosity.

Constant FLAG_VERB_MASK: constant Tools.AutoDoc.FLAG_VERB_MASK
Description: Verbosity mask.

Class Tools.AutoDoc.AutoDocError

Description: Base class for errors generated by the autodoc extraction system.

Variable message: string Tools.AutoDoc.AutoDocError.message
Description: Error message.

Variable part: string Tools.AutoDoc.AutoDocError.part
Description: Which part of the autodoc system.

Variable position: SourcePosition Tools.AutoDoc.AutoDocError.position

Method __create__: protectedlocalvoid__create__(SourcePositionposition, stringpart, stringmessage)

Method create: Tools.AutoDoc.AutoDocErrorTools.AutoDoc.AutoDocError(SourcePositionposition, stringpart, stringmessage)

Class Tools.AutoDoc.BMMLParser

Inherit is_example: inherit Regexp.SimpleRegexp : is_example

Inherit lastident: protected inherit Regexp.SimpleRegexp : lastident

Inherit megamagic: protected inherit Regexp.SimpleRegexp : megamagic

Method magic: stringmagic(strings, intquote)
Description: Convert a block of tab-indented text to a set of paragraphs.

Class Tools.AutoDoc.PikeParser

Description: A very special purpose Pike parser that can parse some selected elements of the Pike language...

Inherit PikeObjects: protected inherit .PikeObjects : PikeObjects

Constant EOF: constantstring Tools.AutoDoc.PikeParser.EOF
Description: The end of file marker.

Constant WITH_NL: constantint Tools.AutoDoc.PikeParser.WITH_NL
Description: Newline indicator flag value.

Variable currentPosition: SourcePosition Tools.AutoDoc.PikeParser.currentPosition
Description: The current position in the source.

Method create: Tools.AutoDoc.PikeParserTools.AutoDoc.PikeParser(string|voids, string|SourcePosition|void_filename, int|voidline, .Flags|voidflags)

Method eat: stringeat(multiset(string)|stringtoken)
Description: Consume one token, error if not (one of) the expected in token.

Method eatIdentifier: stringeatIdentifier(void|intallowScopePrefix)
Description: Expect an identifier.
Note: Also ::ident, scope::ident.
Note: This function also converts old-style getters and setters into new-style.

Method eatLiteral: stringeatLiteral()
Description: Expect a literal constant.
See also: parseLiteral()

Method getReadDocComments: intgetReadDocComments()
Returns: Returns the number of documentation comments that have been returned by readToken().

Method literalType: Type|zeroliteralType(stringliteral)
Description: Returns the type of a literal. Currently only recognizes the top level type. Currently does not thoroughly check that the literal is syntactically valid.

Method lookAhead: stringlookAhead(intoffset, int|voidwith_newlines)
Description: Peek offset tokens ahead, skipping newlines, unless with_newlines is set.
See also: peekToken()

Method parseAnnotation: Annotation|zeroparseAnnotation()
Description: Parse a single annotation from the token stream.

Method parseAnnotations: array(Annotation) parseAnnotations()
Description: Parse a set of annotations from the token stream.

Method parseArgList

arrayparseArgList(int|voidallowLiterals)

Description

Parse the list of arguments in a function declaration.

Parameter allowLiterals

If allowLiterals != 0 then you can write a literal or Pike idents as an argument, like:

void convert("jpeg",Image image,float quality)

For a literal arg, the argname[] string contains the literal and the corresponding argtypes element is 0

Note

Expects that the arglist is followed by a ")".

Method parseArray: ArrayTypeparseArray()
Description: Parse an array type.

Method parseDecl: PikeObject|array(PikeObject)|AnnotationparseDecl(mapping|voidargs)
Description: Parse the next Pike declaration from the token stream.
Note: parseDecl() reads ONLY THE HEAD, NOT the ";" or "{" .. "}" !!!

Method parseFunction: FunctionTypeparseFunction()
Description: Parse a function type.

Method parseIdents: string|voidparseIdents()
Description: Parse a '.'-separated identitifer string.
Note: Also parses stuff preceded by "scope::" or "::"

Method parseInt: IntTypeparseInt()
Description: Parse an integer type.

Method parseLiteral: string|zeroparseLiteral()
Description: Parse the next literal constant (if any) from the token stream.

Method parseMapping: MappingTypeparseMapping()
Description: Parse a mapping type.

Method parseModifiers: array(string) parseModifiers()
Description: Parse a set of modifiers from the token stream.

Method parseMultiset: MultisetTypeparseMultiset()
Description: Parse a multiset type.

Method parseOrType: TypeparseOrType()
Description: Parse a union type.

Method parseString: StringTypeparseString()
Description: Parse a string type.

Method peekToken: stringpeekToken(int|voidwith_newlines)
Description: Peek at the next token in the stream without advancing.
Parameter with_newlines: If set will return "\n" tokens, these will otherwise silently be skipped.
Returns: Returns the next token.
See also: readToken(), lookAhead()

Method readToken: stringreadToken(int|voidwith_newlines)
Description: Read the next token from the stream and advance.
Parameter with_newlines: If set will return "\n" tokens, these will otherwise silently be skipped.
Returns: Returns the next token.
See also: peekToken()

Method setTokens: voidsetTokens(array(string) t, array(int) p)

Method skip: voidskip(multiset(string)|stringtokens)
Description: Skip the next token if it is a member of the tokens set.
Note: The newline token ("\n") is not skipped implicitly by this function.
See also: readToken(), peekToken(), eat(), skipUntil()

Method skipBlock: array(string) skipBlock()
Description: Skip passed a matched pair of parenthesis, brackets or braces.

Method skipNewlines: voidskipNewlines()
Description: Skip past any newlines.

Method skipUntil: array(string) skipUntil(multiset(string)|stringtokens)
Description: Skip tokens until one of tokens is the next to read.
Note: The newline token ("\n") is not skipped implicitly by this function.
See also: skip()

Method tokenize: array(array(string)|array(int)) tokenize(strings, intline)
Description: Tokenize a string of Pike code.

Class Tools.AutoDoc.SourcePosition

Description: Class used to keep track of where in the source a piece of documentation originated.

Variable filename: string Tools.AutoDoc.SourcePosition.filename

Variable firstline
Variable lastline: int Tools.AutoDoc.SourcePosition.firstline
int Tools.AutoDoc.SourcePosition.lastline
Description: Range of lines.

Method copy: SourcePositioncopy()
Returns: Returns a copy of the current object.

Method create: Tools.AutoDoc.SourcePositionTools.AutoDoc.SourcePosition(stringfilename, intfirstline, int|voidlastline)

Method xml: stringxml(Flags|voidflags)
Returns: Returns a string with an XML-fragment describing the source position.

Module Tools.AutoDoc.DocParser

Inherit PikeObjects: inherit .PikeObjects : PikeObjects

Constant EOF: constant Tools.AutoDoc.DocParser.EOF
Description: End of file marker.

Variable keywordtype: mapping(string:DocTokenType) Tools.AutoDoc.DocParser.keywordtype
Description: The DocTokenTypes for the documentation @-keywords.

Method splitDocBlock: array(array(Token)) splitDocBlock(stringblock, SourcePositionposition)
Description: Split a block of documentation text into segments of Tokens split on METAKEYWORDs.
Returns: Each of the arrays in the returned array can be fed to Parse::create()

Enum Tools.AutoDoc.DocParser.DocTokenType

Description: Enum of documentation token types.

Constant BRACEKEYWORD: constant Tools.AutoDoc.DocParser.BRACEKEYWORD
Description: eg @i{@}

Constant CONTAINERKEYWORD: constant Tools.AutoDoc.DocParser.CONTAINERKEYWORD
Description: eg @mapping

Constant DELIMITERKEYWORD: constant Tools.AutoDoc.DocParser.DELIMITERKEYWORD
Description: eg @param

Constant ENDKEYWORD: constant Tools.AutoDoc.DocParser.ENDKEYWORD
Description: eg @endmapping

Constant ENDTOKEN: constant Tools.AutoDoc.DocParser.ENDTOKEN
Description: End of documentation marker.

Constant ERRORKEYWORD: constant Tools.AutoDoc.DocParser.ERRORKEYWORD
Description: eg @invalid

Constant METAKEYWORD: constant Tools.AutoDoc.DocParser.METAKEYWORD
Description: eg @decl

Constant SINGLEKEYWORD: constant Tools.AutoDoc.DocParser.SINGLEKEYWORD
Description: None existant.

Constant TEXTTOKEN: constant Tools.AutoDoc.DocParser.TEXTTOKEN
Description: Documentation text.

Class Tools.AutoDoc.DocParser.DocParserClass

Description: Internal class for parsing documentation markup.

Variable argHandlers

mapping(string:function(string, string:string)|function(string, string:mapping(string:string))) Tools.AutoDoc.DocParser.DocParserClass.argHandlers

Description

Contains functions that handle keywords with non-standard arg list syntax. The function for each keyword can return a mapping or a string:

`mapping(string:string)`	If a `mapping(string:string)` is returned, it is interpreted as the attributes to put in the tag.
`string`	If a string is returned, it is an XML fragment that gets inserted inside the tag.

Variable currentPosition: SourcePosition Tools.AutoDoc.DocParser.DocParserClass.currentPosition

Method getDoc: stringgetDoc(stringcontext)
Returns: Returns the documentation corresponding to the context as an XML string.
Note: getMetaData() must be called before this function.

Method getMetaData: MetaDatagetMetaData()
Returns: Returns the MetaData for the documentation string.

Class Tools.AutoDoc.DocParser.MetaData

Description: Metadata about a Documentation object.

Variable belongs
Variable appears: string Tools.AutoDoc.DocParser.MetaData.belongs
string Tools.AutoDoc.DocParser.MetaData.appears
Description: Relocation information.

Variable decls: array(PikeObject) Tools.AutoDoc.DocParser.MetaData.decls
Description: Set of declarations.

Variable inherits: array(PikeObject) Tools.AutoDoc.DocParser.MetaData.inherits
Description: Set of inherits.

Variable name: string Tools.AutoDoc.DocParser.MetaData.name
Description: If type is one of "class", "module", "endmodule", or "endclass".

Variable type: string Tools.AutoDoc.DocParser.MetaData.type
Description: Type of documented entity.

Class Tools.AutoDoc.DocParser.Parse

Description

Documentation markup parser.

This is a class, because you need to examine the meta lines before you can determine which context to parse the actual doc lines in.

Inherit DocParserClass: inherit DocParserClass : DocParserClass

Method create: Tools.AutoDoc.DocParser.ParseTools.AutoDoc.DocParser.Parse(string|array(Token) s, SourcePosition|voidsp, .Flags|voidflags)
Description: Parse a documentation string s.

Method doc: string|zerodoc(stringcontext)
Returns: Returns the documentation corresponding to the context as an XML string.
Note: metadata() must be called before this function.

Method metadata: MetaDatametadata()
Returns: Returns the MetaData for the documentation string.

Class Tools.AutoDoc.DocParser.Token

Variable type
Variable keyword
Variable arg
Variable text
Variable position: int Tools.AutoDoc.DocParser.Token.type
string|zero Tools.AutoDoc.DocParser.Token.keyword
string|zero Tools.AutoDoc.DocParser.Token.arg
string|zero Tools.AutoDoc.DocParser.Token.text
SourcePosition|zero Tools.AutoDoc.DocParser.Token.position

Method __create__: protectedlocalvoid__create__(inttype, string|zerokeyword, string|zeroarg, string|zerotext, SourcePosition|zeroposition)

Method create: Tools.AutoDoc.DocParser.TokenTools.AutoDoc.DocParser.Token(inttype, string|zerokeyword, string|zeroarg, string|zerotext, SourcePosition|zeroposition)

Module Tools.AutoDoc.PikeExtractor

Inherit DocParser: protected inherit .DocParser : DocParser

Method extractClass: voidextractClass(AutoDocroot, Moduleparent, strings, void|stringfilename, void|stringclassName, void|.Flagsflags)
Description: Extract documentation for a Pike class (aka program).
See also: extractNamespace(), extractModule()

Method extractModule: voidextractModule(AutoDocroot, Moduleparent, strings, void|stringfilename, void|stringmoduleName, void|.Flagsflags)
Description: Extract documentation for a Pike module.
See also: extractNamespace(), extractClass()

Method extractNamespace: voidextractNamespace(AutoDocroot, strings, void|stringfilename, void|stringnamespaceName, void|.Flagsflags)
Description: Extract documentation for a Pike namespace.
See also: extractModule(), extractClass()

Module Tools.AutoDoc.PikeObjects

Description: This module contains classes to represent Pike objects such as classes, modules, methods, variables ... The classes can produce XML representations of themselves.

Inherit "module.pmod": protected inherit "module.pmod" : "module.pmod"

Inherit Tree: protected inherit Parser.XML.Tree : Tree

Variable EmptyDoc: protectedDocumentation Tools.AutoDoc.PikeObjects.EmptyDoc
Description: The empty Documentation.

Class Tools.AutoDoc.PikeObjects.Annotation

Description: Class representing an annotation.

Class Tools.AutoDoc.PikeObjects.ArrayType

Description: The class for representing array types.
See also: Type

Inherit Type: inherit Type : Type

Variable length: Type Tools.AutoDoc.PikeObjects.ArrayType.length
Description: The length of the array.

Variable valuetype: Type Tools.AutoDoc.PikeObjects.ArrayType.valuetype
Description: The Type of the array elements.

Method create: Tools.AutoDoc.PikeObjects.ArrayTypeTools.AutoDoc.PikeObjects.ArrayType()

Class Tools.AutoDoc.PikeObjects.AttributeType

Description: The class for representing attributed types.
See also: Type

Inherit Type: inherit Type : Type

Variable attribute: string Tools.AutoDoc.PikeObjects.AttributeType.attribute
Description: The name of the attribute.

Variable prefix

int Tools.AutoDoc.PikeObjects.AttributeType.prefix

Description

Flag indicating:

`0`	The attribute is on the type.
`1`	The attribute is a prefix and acts as a modifier. This is only used for functions.

Variable subtype: Type Tools.AutoDoc.PikeObjects.AttributeType.subtype
Description: The type that is attributed.

Method create: Tools.AutoDoc.PikeObjects.AttributeTypeTools.AutoDoc.PikeObjects.AttributeType()

Class Tools.AutoDoc.PikeObjects.AutoDoc

Description: The top-level container. This container should only contain namespaces, and they in turn contain modules etc.

Inherit _Class_or_Module: inherit _Class_or_Module : _Class_or_Module

Constant objtype: constantstring Tools.AutoDoc.PikeObjects.AutoDoc.objtype

Class Tools.AutoDoc.PikeObjects.Class

Description: Represents a class.

Inherit _Class_or_Module: inherit _Class_or_Module : _Class_or_Module

Constant objtype: constantstring Tools.AutoDoc.PikeObjects.Class.objtype

Class Tools.AutoDoc.PikeObjects.Constant

Description: Represents a named constant.

Inherit PikeObject: inherit PikeObject : PikeObject

Constant objtype: constantstring Tools.AutoDoc.PikeObjects.Constant.objtype

Variable type: Type Tools.AutoDoc.PikeObjects.Constant.type
Description: The type of the constant, if known.

Variable typedefType: Type Tools.AutoDoc.PikeObjects.Constant.typedefType
Description: Typedef Type if it is a typedef.

Class Tools.AutoDoc.PikeObjects.CppDirective

Description: Representation of an inherit.

Inherit PikeObject: inherit PikeObject : PikeObject

Constant objtype: constantstring Tools.AutoDoc.PikeObjects.CppDirective.objtype

Class Tools.AutoDoc.PikeObjects.DocGroup

Description: A class associating a piece of Documentation with a set of PikeObjects.

Variable appears
Variable belongs: string Tools.AutoDoc.PikeObjects.DocGroup.appears
string Tools.AutoDoc.PikeObjects.DocGroup.belongs
Description: Relocation information.

Variable documentation: Documentation Tools.AutoDoc.PikeObjects.DocGroup.documentation
Description: The Documentation for the objects.

Variable objects: array(PikeObject) Tools.AutoDoc.PikeObjects.DocGroup.objects
Description: The set of PikeObjects that are documented.

Method create: Tools.AutoDoc.PikeObjects.DocGroupTools.AutoDoc.PikeObjects.DocGroup(array(PikeObject) objs, Documentation|voiddoc)

Method xml: stringxml(.Flags|voidflags)
Returns: Returns a string with an XML representation of the documentation.

Class Tools.AutoDoc.PikeObjects.Documentation

Description: The base class for documentation strings.
See also: DocGroup

Variable text
Variable xml
Variable position: string|void Tools.AutoDoc.PikeObjects.Documentation.text
string|void Tools.AutoDoc.PikeObjects.Documentation.xml
SourcePosition|void Tools.AutoDoc.PikeObjects.Documentation.position

Method __create__: protectedlocalvoid__create__(string|voidtext, string|voidxml, SourcePosition|voidposition)

Method create: Tools.AutoDoc.PikeObjects.DocumentationTools.AutoDoc.PikeObjects.Documentation(string|voidtext, string|voidxml, SourcePosition|voidposition)

Class Tools.AutoDoc.PikeObjects.Enum

Description: The enum container.

Inherit PikeObject: inherit PikeObject : PikeObject

Constant objtype: constantstring Tools.AutoDoc.PikeObjects.Enum.objtype

Variable children: array(DocGroup) Tools.AutoDoc.PikeObjects.Enum.children
Description: The set of children.

Variable documentation: Documentation Tools.AutoDoc.PikeObjects.Enum.documentation
Description: Mimic the class { ... } behaviour.

Method addChild: voidaddChild(DocGroupc)
Description: Adds c to the set of children.

Method addGroup: voidaddGroup(DocGroupc)
Description: Adds c to the set of children.

Method containsDoc: intcontainsDoc()
Returns: Returns 1 if there is any documentation at all for this entity.

Class Tools.AutoDoc.PikeObjects.EnumConstant

Description

The values inside enum Foo { ... }

These are currently handled identically to normal constants.

Inherit Constant: inherit Constant : Constant

Class Tools.AutoDoc.PikeObjects.FloatType

Description: The class for representing the float type.
See also: Type

Inherit Type: inherit Type : Type

Method create: Tools.AutoDoc.PikeObjects.FloatTypeTools.AutoDoc.PikeObjects.FloatType()

Class Tools.AutoDoc.PikeObjects.FunctionType

Description: The class for representing function types.
See also: Type

Inherit Type: inherit Type : Type

Variable argtypes: array(Type) Tools.AutoDoc.PikeObjects.FunctionType.argtypes
Description: An array with types for the arguments to the function.

Variable returntype: Type Tools.AutoDoc.PikeObjects.FunctionType.returntype
Description: The type for the return value of the function.

Method create: Tools.AutoDoc.PikeObjects.FunctionTypeTools.AutoDoc.PikeObjects.FunctionType()

Class Tools.AutoDoc.PikeObjects.Generic

Description: Represents a generic.

Inherit Typedef: inherit Typedef : Typedef

Constant objtype: constantstring Tools.AutoDoc.PikeObjects.Generic.objtype

Variable default_type: Type Tools.AutoDoc.PikeObjects.Generic.default_type
Description: Default Type.

Variable generic_argument_number: int Tools.AutoDoc.PikeObjects.Generic.generic_argument_number

Class Tools.AutoDoc.PikeObjects.Import

Description: Representation of an import.

Inherit Inherit: inherit Inherit : Inherit

Constant objtype: constantstring Tools.AutoDoc.PikeObjects.Import.objtype

Class Tools.AutoDoc.PikeObjects.Inherit

Description: Representation of an inherit.

Inherit PikeObject: inherit PikeObject : PikeObject

Constant objtype: constantstring Tools.AutoDoc.PikeObjects.Inherit.objtype

Variable bindings: array(Type) Tools.AutoDoc.PikeObjects.Inherit.bindings
Description: Bindings (if any).

Variable classname: string Tools.AutoDoc.PikeObjects.Inherit.classname
Description: Name of the class that is inherited.

Class Tools.AutoDoc.PikeObjects.IntType

Description: The class for representing integer types.
See also: Type

Inherit Type: inherit Type : Type

Variable min
Variable max: string Tools.AutoDoc.PikeObjects.IntType.min
string Tools.AutoDoc.PikeObjects.IntType.max
Description: The minimum and maximum range limits for the integer type.

Method create: Tools.AutoDoc.PikeObjects.IntTypeTools.AutoDoc.PikeObjects.IntType()

Class Tools.AutoDoc.PikeObjects.MappingType

Description: The class for representing mapping types.
See also: Type

Inherit Type: inherit Type : Type

Variable indextype
Variable valuetype: Type Tools.AutoDoc.PikeObjects.MappingType.indextype
Type Tools.AutoDoc.PikeObjects.MappingType.valuetype
Description: The types for the indices and values of the mapping.

Method create: Tools.AutoDoc.PikeObjects.MappingTypeTools.AutoDoc.PikeObjects.MappingType()

Class Tools.AutoDoc.PikeObjects.Method

Description: Represents a function.

Inherit PikeObject: inherit PikeObject : PikeObject

Constant objtype: constantstring Tools.AutoDoc.PikeObjects.Method.objtype

Variable argnames: array(string) Tools.AutoDoc.PikeObjects.Method.argnames
Description: The names of the arguments.

Variable argtypes: array(Type) Tools.AutoDoc.PikeObjects.Method.argtypes
Description: The types for the arguments.

Variable returntype: Type Tools.AutoDoc.PikeObjects.Method.returntype
Description: The return type for the function.

Class Tools.AutoDoc.PikeObjects.MixedType

Description: The class for representing the mixed type.
See also: Type

Inherit Type: inherit Type : Type

Method create: Tools.AutoDoc.PikeObjects.MixedTypeTools.AutoDoc.PikeObjects.MixedType()

Class Tools.AutoDoc.PikeObjects.Modifier

Description

A modifier range, e.g.:

finalprotected{
  ...
  <<declarations>>
  ...
}

Inherit _Class_or_Module: inherit _Class_or_Module : _Class_or_Module

Constant objtype: constantstring Tools.AutoDoc.PikeObjects.Modifier.objtype

Class Tools.AutoDoc.PikeObjects.Module

Description: Represents a module.

Inherit _Class_or_Module: inherit _Class_or_Module : _Class_or_Module

Constant objtype: constantstring Tools.AutoDoc.PikeObjects.Module.objtype

Class Tools.AutoDoc.PikeObjects.MultisetType

Description: The class for representing multiset types.
See also: Type

Inherit Type: inherit Type : Type

Variable indextype: Type Tools.AutoDoc.PikeObjects.MultisetType.indextype
Description: The type for the indices of the multiset.

Method create: Tools.AutoDoc.PikeObjects.MultisetTypeTools.AutoDoc.PikeObjects.MultisetType()

Class Tools.AutoDoc.PikeObjects.NameSpace

Description: Represents a name space, eg: predef:: or lfun::.

Inherit _Class_or_Module: inherit _Class_or_Module : _Class_or_Module

Constant objtype: constantstring Tools.AutoDoc.PikeObjects.NameSpace.objtype

Class Tools.AutoDoc.PikeObjects.ObjectType

Description: The class for representing object types.
See also: Type

Inherit Type: inherit Type : Type

Variable classname: string Tools.AutoDoc.PikeObjects.ObjectType.classname
Description: The name of the class for the object.

Method create: Tools.AutoDoc.PikeObjects.ObjectTypeTools.AutoDoc.PikeObjects.ObjectType()

Class Tools.AutoDoc.PikeObjects.OrType

Description: The class for representing union types.
See also: Type

Inherit Type: inherit Type : Type

Variable types: array(Type) Tools.AutoDoc.PikeObjects.OrType.types
Description: An array with the types that are member of the union.

Method create: Tools.AutoDoc.PikeObjects.OrTypeTools.AutoDoc.PikeObjects.OrType()

Class Tools.AutoDoc.PikeObjects.PikeObject

Description

Base class for representing a documentable Pike lexical entity.

This class is inherited by classes for representing classes, functions, variables, etc.

See also

Inherit, Import, Class, Module, NameSpace, AutoDoc, Modifier, Method, Constant, Typedef, EnumConstant, Enum, Variable

Constant objtype: constantstring Tools.AutoDoc.PikeObjects.PikeObject.objtype
Description: The object type identifier.

Variable appears
Variable belongs: string Tools.AutoDoc.PikeObjects.PikeObject.appears
string Tools.AutoDoc.PikeObjects.PikeObject.belongs
Description: Relocation information.

Variable modifiers: array(string) Tools.AutoDoc.PikeObjects.PikeObject.modifiers
Description: The set of modifiers affecting this entity.

Variable name: string Tools.AutoDoc.PikeObjects.PikeObject.name
Description: The name of the entity.

Variable position: SourcePosition Tools.AutoDoc.PikeObjects.PikeObject.position
Description: The source position where the entity was found.

Variable squeezedInDoc: Documentation Tools.AutoDoc.PikeObjects.PikeObject.squeezedInDoc

Method print: stringprint()
Returns: Returns a string with a Pike syntax representation of the entity.

Method xml: stringxml(.Flags|voidflags)
Returns: Returns a string with an XML representation of the entity.

Class Tools.AutoDoc.PikeObjects.ProgramType

Description: The class for representing program (aka class) types.
See also: Type

Inherit Type: inherit Type : Type

Variable classname: string Tools.AutoDoc.PikeObjects.ProgramType.classname
Description: The name of the class (if any).

Method create: Tools.AutoDoc.PikeObjects.ProgramTypeTools.AutoDoc.PikeObjects.ProgramType()

Class Tools.AutoDoc.PikeObjects.StringType

Description: The class for representing string types.
See also: Type

Inherit Type: inherit Type : Type

Variable max: string Tools.AutoDoc.PikeObjects.StringType.max
Description: The maximum value for characters in the string.

Variable min: string Tools.AutoDoc.PikeObjects.StringType.min
Description: The minimum value for characters in the string.

Method create: Tools.AutoDoc.PikeObjects.StringTypeTools.AutoDoc.PikeObjects.StringType()

Class Tools.AutoDoc.PikeObjects.Type

Description: The base class for representing types.

Variable name: string Tools.AutoDoc.PikeObjects.Type.name

Method __create__: protectedlocalvoid__create__(stringname)

Method create: Tools.AutoDoc.PikeObjects.TypeTools.AutoDoc.PikeObjects.Type(stringname)

Method print: stringprint()
Returns: Returns a string with a Pike-syntax representation of the type.

Method xml: stringxml(.Flags|voidflags)
Returns: Returns a string with an XML representation of the type.

Class Tools.AutoDoc.PikeObjects.TypeType

Description: The class for representing type types.
See also: Type

Inherit Type: inherit Type : Type

Variable subtype: Type Tools.AutoDoc.PikeObjects.TypeType.subtype
Description: The subtype of the type.

Method create: Tools.AutoDoc.PikeObjects.TypeTypeTools.AutoDoc.PikeObjects.TypeType()

Class Tools.AutoDoc.PikeObjects.Typedef

Description: Represents a typedef.

Inherit PikeObject: inherit PikeObject : PikeObject

Constant objtype: constantstring Tools.AutoDoc.PikeObjects.Typedef.objtype

Variable type: Type Tools.AutoDoc.PikeObjects.Typedef.type
Description: Typedef Type.

Class Tools.AutoDoc.PikeObjects.UnknownType

Description: The class for representing the unknown type.
See also: Type

Inherit Type: inherit Type : Type

Method create: Tools.AutoDoc.PikeObjects.UnknownTypeTools.AutoDoc.PikeObjects.UnknownType()

Class Tools.AutoDoc.PikeObjects.VarargsType

Description: The class for representing varargs types.
See also: Type

Inherit Type: inherit Type : Type

Variable type: Type Tools.AutoDoc.PikeObjects.VarargsType.type
Description: The type that is varargs.

Method create: Tools.AutoDoc.PikeObjects.VarargsTypeTools.AutoDoc.PikeObjects.VarargsType(Typet)

Class Tools.AutoDoc.PikeObjects.Variable

Annotations

@Pike.Annotations.Implements(PikeObject)

Description

Represents a variable.

Inherit PikeObject: inherit PikeObject : PikeObject

Constant objtype: constantstring Tools.AutoDoc.PikeObjects.Variable.objtype

Variable type: Type Tools.AutoDoc.PikeObjects.Variable.type
Description: Type of the variable.

Class Tools.AutoDoc.PikeObjects.VoidType

Description: The class for representing the void type.
See also: Type

Inherit Type: inherit Type : Type

Method create: Tools.AutoDoc.PikeObjects.VoidTypeTools.AutoDoc.PikeObjects.VoidType()

Class Tools.AutoDoc.PikeObjects.ZeroType

Description: The class for representing the zero type.
See also: Type

Inherit Type: inherit Type : Type

Method create: Tools.AutoDoc.PikeObjects.ZeroTypeTools.AutoDoc.PikeObjects.ZeroType()

Class Tools.AutoDoc.PikeObjects._Class_or_Module

Description: Base class for representing classes, modules and namespaces.
See also: Class, Module, NameSpace, AutoDoc, Modifier

Inherit PikeObject: inherit PikeObject : PikeObject

Variable children: array(_Class_or_Module) Tools.AutoDoc.PikeObjects._Class_or_Module.children
Description: Entities that are children to this entity.

Variable docGroups: array(DocGroup) Tools.AutoDoc.PikeObjects._Class_or_Module.docGroups
Description: Documented entities that are children to this entity.

Variable documentation: Documentation Tools.AutoDoc.PikeObjects._Class_or_Module.documentation
Note: The documentation appears as a child of the <class> or <module>

Variable generics: array(array(string|PikeObject)) Tools.AutoDoc.PikeObjects._Class_or_Module.generics
Description: Array of symbol followed by type and default type triples.

Variable inherits: array(Inherit|Import) Tools.AutoDoc.PikeObjects._Class_or_Module.inherits
Description: Inherits and Imports that affect the symbol lookup for the entity.

Method addChild: voidaddChild(_Class_or_Modulec)
Description: Adds c to the set of children.

Method addGroup: voidaddGroup(DocGroupd)
Description: Adds d to the set of docGroups.

Method addInherit: voidaddInherit(PikeObjectp)
Description: Adds p to the set of inherits.

Method containsDoc: intcontainsDoc()
Returns: Returns 1 if there is any documentation at all for this entity.

Method findChild: PikeObject|zerofindChild(stringname)
Returns: Returns the first child with the name name if any.

Method findObject: DocGroup|zerofindObject(stringname)
Returns: Returns the first DocGroup that documents an entity with the name name if any.

Module Tools.AutoDoc.ProcessXML

Inherit "module.pmod": protected inherit "module.pmod" : "module.pmod"

Inherit Tree: protected inherit Parser.XML.Tree : Tree

Method extractXML

Description

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.

Parameter filename

The file to extract from.

Parameter pikeMode

Non-zero if it is a Pike file. If the file contains style doc comments, C-mode is used despite pikeMode != 0.

Parameter type

"class", "module" or "namespace".

Parameter name

The name of the class/module/namespace.

Parameter parentModules

The ancestors of the class/module/namespace.

Parameter flags

Flags adjusting the extractor behaviour. Defaults to FLAG_NORMAL.

Example

// To extract doc for Foo.Bar.Ippa:
   string xml = extractXML("lib/modules/Foo.pmod/Bar.pmod/Ippa.pike", 1,
     "class", "Ippa", ({ "Foo", "Bar" }));

Method handleAppears: voidhandleAppears(SimpleNoderoot, .Flags|voidflags)
Description: Take care of all the @appears and @belongs directives everywhere, and rearranges the nodes in the tree accordingly
Parameter root: The root (<autodoc>) node of the documentation tree.

Method mergeTrees

voidmergeTrees(SimpleNodedest, SimpleNodesource)

Description

Puts all children of source into the tree dest, in their correct place module-hierarchically.

Used to merge the results of extractions of different Pike and C files.

Some minor effort is expended to normalize the result to some sort of canonical order.

Parameter source

Parameter dest

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.

Note

Both source and dest are modified destructively.

Note

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.

Method moveImages: stringmoveImages(stringdocXMLFile, stringimageSourceDir, stringimageDestDir, int|voidquiet)
Description: Copy all images to canonical files in a flat directory.
Parameter docXMLFile: 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.
Parameter imageSourceDir: 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.
Parameter imageDestDir: The directory where the images should be copied.
Parameter quiet: Quiet operation.
Returns: The XML file contents (with decorated <image>-tags)

Method postProcess

voidpostProcess(SimpleNoderoot, string|voidlogfile, .Flags|voidflags)

Description

Perform the last steps on a completed documentation tree.

Parameter root

Root <autodoc> node of the completed documentation tree.

Calls handleAppears(), cleanUndocumented() and resolveRefs() in turn.

See also

handleAppears(), cleanUndocumented(), resolveRefs()

Class Tools.AutoDoc.ProcessXML.DummyNScope

Variable name: string Tools.AutoDoc.ProcessXML.DummyNScope.name

Method __create__: protectedlocalvoid__create__(stringname)

Method create: Tools.AutoDoc.ProcessXML.DummyNScopeTools.AutoDoc.ProcessXML.DummyNScope(stringname)

Class Tools.AutoDoc.ProcessXML.NScope

Description: A symbol lookup scope.

Method addImplicitInherits: voidaddImplicitInherits(string|voidfallback_namespace)
Description: This function improves the symbol resolution by adding implicit inherits for modules in compatibility namespaces.

Class Tools.AutoDoc.ProcessXML.ReOrganizeTask

Variable n
Variable parent: SimpleNode Tools.AutoDoc.ProcessXML.ReOrganizeTask.n
SimpleNode Tools.AutoDoc.ProcessXML.ReOrganizeTask.parent

Method __create__: protectedlocalvoid__create__(SimpleNoden, SimpleNodeparent)

Method create: Tools.AutoDoc.ProcessXML.ReOrganizeTaskTools.AutoDoc.ProcessXML.ReOrganizeTask(SimpleNoden, SimpleNodeparent)

Class Tools.AutoDoc.ProcessXML.Scope

Variable type
Variable name: string|void Tools.AutoDoc.ProcessXML.Scope.type
string|void Tools.AutoDoc.ProcessXML.Scope.name

Method __create__: protectedlocalvoid__create__(string|voidtype, string|voidname)

Method create: Tools.AutoDoc.ProcessXML.ScopeTools.AutoDoc.ProcessXML.Scope(string|voidtype, string|voidname)

Module Tools.Hilfe

Method format_hr_time: stringformat_hr_time(inti)
Description: Helper function that formats a time span in nanoseconds to something more human readable (ns, ms or s).

Class Tools.Hilfe.Command

Description: Abstract class for Hilfe commands.

Method doc: stringdoc(stringwhat, stringwith)
Description: A more elaborate documentation of the command. This should be less than 68 characters per line.

Method exec: voidexec(Evaluatore, stringline, array(string) words, array(string) tokens)
Description: The actual command callback. Messages to the user should be written out by using the safe_write method in the Evaluator object.

Method help: stringhelp(string|zerowhat)
Description: Returns a one line description of the command. This help should be shorter than 54 characters.

Class Tools.Hilfe.CommandReset

Description: Variable reset command. Put ___Hilfe->commands->reset = Tools.Hilfe.CommandReset(); in your .hilferc to have this command defined when you open Hilfe.

Inherit Command: inherit Command : Command

Class Tools.Hilfe.CommandSet

Inherit Command: inherit Command : Command

Class Tools.Hilfe.CommandSet.Intwriter

Variable type
Variable fallback: string Tools.Hilfe.CommandSet.Intwriter.type
function(:void) Tools.Hilfe.CommandSet.Intwriter.fallback

Method __create__: protectedlocalvoid__create__(stringtype, function(:void) fallback)

Method create: Tools.Hilfe.CommandSet.IntwriterTools.Hilfe.CommandSet.Intwriter(stringtype, function(:void) fallback)

Class Tools.Hilfe.CommandSet.Reswriter

Variable format: string Tools.Hilfe.CommandSet.Reswriter.format

Method __create__: protectedlocalvoid__create__(stringformat)

Method create: Tools.Hilfe.CommandSet.ReswriterTools.Hilfe.CommandSet.Reswriter(stringformat)

Class Tools.Hilfe.Evaluator

Description: This class implements the actual Hilfe interpreter. It is accessible as ___Hilfe from Hilfe expressions.

Variable assembler_debug_level: int Tools.Hilfe.Evaluator.assembler_debug_level
Description: The current assembler debug level. Only available if Pike is compiled with RTL debug.

Variable commands: mapping(string:Command) Tools.Hilfe.Evaluator.commands
Description: 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.

Variable compiler_trace_level: int Tools.Hilfe.Evaluator.compiler_trace_level
Description: The current compiler trace level. Only available if Pike is compiled with RTL debug.

Variable constants: mapping(string:mixed) Tools.Hilfe.Evaluator.constants
Description: The locally defined constants (name:value).

Variable debug_level: int Tools.Hilfe.Evaluator.debug_level
Description: The current debug level. Only available if Pike is compiled with RTL debug.

Variable functions: mapping(string:function(:void)) Tools.Hilfe.Evaluator.functions
Description: The locally defined functions (name:value).

Variable history: HilfeHistory Tools.Hilfe.Evaluator.history
Description: The current result history.

Variable imports: array(string) Tools.Hilfe.Evaluator.imports
Description: The current imports.

Variable inherits: array(string) Tools.Hilfe.Evaluator.inherits
Description: The current inherits.

Variable last_compile_time: int(0..) Tools.Hilfe.Evaluator.last_compile_time
Description: The last compile time;

Variable last_compiled_expr: string Tools.Hilfe.Evaluator.last_compiled_expr
Description: The last created wrapper in which an expression was evaluated.

Variable last_else: bool Tools.Hilfe.Evaluator.last_else
Description: Should an else expression be carried out?

Variable last_eval_time: int(0..) Tools.Hilfe.Evaluator.last_eval_time
Description: The last evaluation time;

Variable programs: mapping(string:program) Tools.Hilfe.Evaluator.programs
Description: The locally defined programs (name:value).

Variable reswrite: function(:void) Tools.Hilfe.Evaluator.reswrite
Description: 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 evaluation time (int). If the evaluated expression didn't return anything (e.g. a for loop) then 0 will be given as the result string.

Variable state: ParserState Tools.Hilfe.Evaluator.state
Description: Keeps the state, e.g. multiline input in process etc.

Variable strict_types: bool Tools.Hilfe.Evaluator.strict_types
Description: Strict types?

Variable trace_level: int Tools.Hilfe.Evaluator.trace_level
Description: The current trace level.

Variable types: mapping(string:string) Tools.Hilfe.Evaluator.types
Description: The types of the locally defined variables (name:type).

Variable variables: mapping(string:mixed) Tools.Hilfe.Evaluator.variables
Description: The locally defined variables (name:value).

Variable warnings: bool Tools.Hilfe.Evaluator.warnings
Description: Show warnings?

Variable write: array|object|function(string:int(0..)) Tools.Hilfe.Evaluator.write
Description: The function to use when writing to the user.

Method add_buffer: voidadd_buffer(strings)
Description: 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.

Method add_input_hook: voidadd_input_hook(function(:void)|objectnew)
Description: Adds a function to the input hook, making all user data be fed into the function.
See also: remove_input_hook

Method add_input_line: voidadd_input_line(strings)
Description: Input a line of text into Hilfe. It checks if s is ".", in which case it calls state->flush(). Otherwise just calls add_buffer.

Method add_writer: voidadd_writer(object|function(string:int(0..)) new)
Description: Adds another output function.

Method evaluate: voidevaluate(stringa, boolshow_result)
Description: 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.

Method hilfe_compile: object|zerohilfe_compile(stringf, void|stringnew_var)
Description: 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.

Method parse_expression: string|zeroparse_expression(Expressionexpr)
Description: Parses a Pike expression. Returns 0 if everything went well, or a string with an error message otherwise.

Method print_version: voidprint_version()
Description: Displays the current version of Hilfe.

Method remove_input_hook: voidremove_input_hook(function(:void)|objectold)
Description: Removes a function from the input hook.
See also: add_input_hook

Method remove_writer: voidremove_writer(object|function(:void) old)
Description: Removes an output function.

Method reset_evaluator: voidreset_evaluator()
Description: 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.

Method safe_write: intsafe_write(array(string)|stringin, mixed ... args)
Description: An output method that shouldn't crash.

Method std_reswrite: voidstd_reswrite(function(:void) w, stringsres, intnum, mixedres)
Description: The standard reswrite function.

Class Tools.Hilfe.Evaluator.HilfeCompileHandler

Variable stack_level: int Tools.Hilfe.Evaluator.HilfeCompileHandler.stack_level

Method __create__: protectedlocalvoid__create__(intstack_level)

Class Tools.Hilfe.Expression

Description: Represents a Pike expression

Method _sizeof: intsizeof(Tools.Hilfe.Expressionarg)
Description: The number of non-whitespace tokens in the expression.

Method `[]: string|zero res = Tools.Hilfe.Expression()[ f ]
Description: Returns a token or a token range without whitespaces.

Method `[]=: Tools.Hilfe.Expression()[ f ] = v
Description: Replaces a token with a new token.

Method cast: (int)Tools.Hilfe.Expression() (float)Tools.Hilfe.Expression() (string)Tools.Hilfe.Expression() (array)Tools.Hilfe.Expression() (mapping)Tools.Hilfe.Expression() (multiset)Tools.Hilfe.Expression()
Description: An Expression object can be cast to an array or a string. In both forms all tokens, including white spaces will be returned.

Method check_modifiers: string|zerocheck_modifiers()
Description: See if there are any forbidden modifiers used in the expression, e.g. "private int x;" is not valid inside Hilfe.
Returns: Returns an error message as a string if the expression contains a forbidden modifier, otherwise 0.

Method code: stringcode()
Description: Returns the expression verbatim.

Method create: Tools.Hilfe.ExpressionTools.Hilfe.Expression(array(string) t)
Parameter t: An array of Pike tokens.

Method depth: intdepth(intf)
Description: Return the parenthesis depth at the given position.

Method endoftype: int(-1..)endoftype(int(-1..)position)
Description: Returns at which position the type declaration that begins at position position ends. A return value of -1 means that the token or tokens from position can not be a type declaration.

Method find_matching: int(-1..)find_matching(stringtoken, int(0..)|voidpos)
Description: Returns the position of the matching parenthesis of the given kind, starting from the given position. The position should be the position after the opening parenthesis, or later. Assuming balanced code. Returns -1 on failure.

Method in_sscanf: boolin_sscanf(intf)
Description: Returns 1 if the current position is within a sscanf expression.

Method is_block: boolis_block(intpos)
Description: Is there a block starting at pos?

Class Tools.Hilfe.GenericAsyncHilfe

Inherit Evaluator: inherit Evaluator : Evaluator

Variable infile
Variable outfile: Stdio.File Tools.Hilfe.GenericAsyncHilfe.infile
Stdio.File Tools.Hilfe.GenericAsyncHilfe.outfile

Method __create__: protectedlocalvoid__create__(Stdio.Fileinfile, Stdio.Fileoutfile)

Class Tools.Hilfe.GenericHilfe

Inherit Evaluator: inherit Evaluator : Evaluator

Method create: Tools.Hilfe.GenericHilfeTools.Hilfe.GenericHilfe(Stdio.FILEin, Stdio.Fileout)

Class Tools.Hilfe.HilfeHistory

Description: 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.

Inherit History: inherit ADT.History(< mixed >) : History

Class Tools.Hilfe.ParserState

Description: 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 output in the other. The parser object is accessible as ___Hilfe->state from Hilfe expressions.

Variable evaluator: Evaluator Tools.Hilfe.ParserState.evaluator

Method __create__: protectedlocalvoid__create__(Evaluatorevaluator)

Method create: Tools.Hilfe.ParserStateTools.Hilfe.ParserState(Evaluatorevaluator)

Method datap: intdatap()
Description: Returns true if there is any waiting expression that can be fetched with read.

Method feed: voidfeed(array(string) tokens)
Description: Feed more tokens into the state.

Method finishedp: boolfinishedp()
Description: Are we in the middle of an expression. Used e.g. for changing the Hilfe prompt when entering multiline expressions.

Method flush: voidflush()
Description: Clear the current state.

Method push_string: array(string)|zeropush_string(stringline)
Description: Sends the input line to Parser.Pike for tokenization, but keeps a state between each call to handle multiline /**/ comments and multiline #"" strings.

Method read: array(Expression) read()
Description: Read out completed expressions. Returns an array where every element is an expression represented as an array of tokens.

Method show_error: voidshow_error(function(array(string)|string, mixed ... :int) w)
Description: Prints out any error that might have occurred while push_string was executed. The error will be printed with the print function w.

Method status: stringstatus()
Description: Returns the current parser state. Used by "dump state".

Class Tools.Hilfe.StdinHilfe

Description: 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.

Inherit Evaluator: inherit Evaluator : Evaluator

Variable readline: Stdio.Readline Tools.Hilfe.StdinHilfe.readline
Description: The readline object,

Method create: Tools.Hilfe.StdinHilfeTools.Hilfe.StdinHilfe(void|array(string) init)
Description: Any hilfe statements given in the init array will be executed once .hilferc has been executed.

Method save_history: voidsave_history()
Description: Saves the user input history, if possible, when called.

Class Tools.Hilfe.SubSysLogger

Class Tools.Hilfe.SubSysLogger.Logger

Variable e
Variable logfile: Evaluator Tools.Hilfe.SubSysLogger.Logger.e
Stdio.File Tools.Hilfe.SubSysLogger.Logger.logfile

Method __create__: protectedlocalvoid__create__(Evaluatore, Stdio.Filelogfile)

Module Tools.Install

Description: Common routines which are useful for various install scripts based on Pike.

Method features: array(string) features()
Description: Return an array of enabled features.
Note: Used by the master when given the option --features.
See also: Tools.Standalone.features

Method make_absolute_path: stringmake_absolute_path(stringpath, string|voidcwd)

Class Tools.Install.ProgressBar

Description: A class keeping some methods and state to conveniently render ASCII progress bars to stdout.

Method create: Tools.Install.ProgressBarTools.Install.ProgressBar(stringname, intcur, intmax, float|voidphase_base, float|voidphase_size)
Parameter name: The name (printed in the first 13 columns of the row)
Parameter cur: How much progress has been made so far
Parameter max: The amount of progress signifying 100% done. Must be greater than zero.

Method set_current: voidset_current(int_cur)
Description: Change the amount of progress without updating on stdout.

Method set_name: voidset_name(string_name)
Description: Change the name of the progress bar without updating on stdout.

Method set_phase: voidset_phase(float_phase_base, float_phase_size)

Method update: intupdate(intincrement)
Description: Write the current look of the progressbar to stdout.
Parameter increment: the number of increments closer to completion since last call
Returns: the length (in characters) of the line with the progressbar

Class Tools.Install.Readline

Inherit Readline: inherit Stdio.Readline : Readline

Method absolute_path: stringabsolute_path(stringpath)

Method edit: stringedit(mixed ... args)

Method edit_directory: stringedit_directory(mixed ... args)

Method edit_filename: stringedit_filename(mixed ... args)

Method set_cwd: voidset_cwd(string_cwd)

Method trap_signal: voidtrap_signal(intn)

Module Tools.Legal

Module Tools.Legal.Copyright

Description: Contains functions and information to store and present copyright information about Pike and it's components.

Method add: voidadd(stringwhat, array(string) holders)
Description: Adds a copyright message for the copyright holders for the component what.
Throws: An error is thrown if the copyrighted component what is already in the list of copyrights.

Method get_all: mapping(string:array(string)) get_all()
Description: Returns a mapping containing all the stored copyrights. The mapping maps component name to an array of copyright holders.

Method get_latest_pike: stringget_latest_pike()
Description: Return the latest copyright holder of Pike.

Method get_text: stringget_text()
Description: Returns the copyrights as a string, suitable for saving as a file.

Module Tools.Legal.License

Method get_text: stringget_text()
Description: Returns all the licenses as a string, suitable for saving as a file.

Module Tools.Legal.License.GPL

Description: GNU General Public License 2

Method get_name: stringget_name()
Description: Returns the name of the license.

Method get_text: stringget_text()
Description: Returns the text of the license.

Method get_xml: stringget_xml()
Description: Returns an XML <pre>-fragment with the text of the license.

Module Tools.Legal.License.LGPL

Description: GNU Lesser General Public License 2.1

Inherit GPL: inherit .GPL : GPL

Module Tools.Legal.License.MPL

Description: Mozilla Public License 1.1

Method get_name: stringget_name()
Description: Returns the name of the license.

Method get_text: stringget_text()
Description: Returns the text of the license.

Method get_xml: stringget_xml()
Description: Returns an XML <pre>-fragment with the text of the license.

Module Tools.Markdown

Description: This is a small stub entrypoint to Parser.Markdown - it is exactly equivalent to calling Parser.Markdown.parse().

Module Tools.MasterHelp

Description: This module contains usage strings for the master()->_main().

Constant environment_help: constant Tools.MasterHelp.environment_help
Description: The set of environment variables that the default master looks at.

Constant kladdkaka_help: constant Tools.MasterHelp.kladdkaka_help
Description: Useful recipe for when all else fails.

Constant opt_summary: constant Tools.MasterHelp.opt_summary
Description: Summary of the options for the Pike interpreter binary, and the default master.

Constant options_help: constant Tools.MasterHelp.options_help
Description: Complete set of options for the Pike interpreter binary, and the default master.

Method do_help: stringdo_help(string|intwhat)
Description: Select a suitable help message.

Module Tools.Monger

Class Tools.Monger.MongerDeveloper

Method add_new_version: intadd_new_version(stringmodule_name, stringversion, stringchanges, stringlicense)

Method delete_dependency: intdelete_dependency(stringmodule_name, stringversion, stringdependency, stringmin_version, stringmax_version)

Method get_dependencies: arrayget_dependencies(stringmodule_name, stringversion)

Method set_auth: voidset_auth(string_username, string_password)
Description: set the username and password for accessing the remote repository.

Method set_default_directory: voidset_default_directory()
Description: sets the default directory for working and storing configurations ($HOME/.monger)

Method set_default_repository: voidset_default_repository()
Description: sets the default repository location (modules.gotpike.org)

Method set_dependency: intset_dependency(stringmodule_name, stringversion, stringdependency, stringmin_version, stringmax_version, boolrequired)

Method set_directory: voidset_directory(string_directory)
Description: sets the monger directory to use for working and storing configurations.

Method set_module_source: intset_module_source(stringmodule_name, stringversion, stringfilename)

Method set_repository

voidset_repository(string_repository)

Description

specify an alternate repository location.

this should be a URL specifying the XMLRPC endpoint for the repository.

Method set_version_active: intset_version_active(stringmodule_name, stringversion, intactive)

Method update_version: intupdate_version(stringmodule_name, stringversion, string|voidchanges, string|voidlicense)

Method user_change_email: intuser_change_email(string|void_username, string_newemail)

Method user_change_password: intuser_change_password(string|void_username, string_newpassword)

Class Tools.Monger.MongerDeveloper.xmlrpc_handler

Class Tools.Monger.MongerDeveloper.xmlrpc_handler._caller

Variable n: string Tools.Monger.MongerDeveloper.xmlrpc_handler._caller.n

Method __create__: protectedlocalvoid__create__(stringn)

Method create: Tools.Monger.MongerDeveloper.xmlrpc_handler._callerTools.Monger.MongerDeveloper.xmlrpc_handler._caller(stringn)

Module Tools.Shoot

Method format_big_number: stringformat_big_number(inti)
Description: Format an integer with SI-suffixes.

Method run

mapping(string:int|float|string) run(Testtest, intmaximum_seconds, __deprecated__(float)|voidoverhead)

Description

Run a single benchmark test.

Parameter test

Benchmark to run.

Parameter maximum_seconds

Number of seconds to run the test before terminating it.

Parameter overhead

Ignored, obsolete.

Returns

Returns a mapping with the following fields on success:

`"time" : float`	Actual number of seconds that the test ran.
`"loops" : int`	Number of times that the test ran.
`"n" : int`	Number of sub tests that were run.
`"readable" : string`	Description of the test result.
`"n_over_time" : int`	Number of sub tests per second.

On benchmark failure a mapping with the single entry "readable" set to "FAIL" is returned.

See also

run_sub(), tests()

Method run_sub

voidrun_sub(Testtest, intmaximum_seconds, __deprecated__(float)|voidoverhead)

Description

Run a single benchmark test in the current process and return the result as JSON on stdout.

Parameter test

Benchmark to run.

Parameter maximum_seconds

Number of seconds to run the test before terminating it.

Parameter overhead

Ignored, obsolete.

Returns

Writes a JSON-encoded mapping with the following fields on success:

`"time" : float`	Actual number of seconds that the test ran.
`"loops" : int`	Number of times that the test ran.
`"n" : int`	Number of sub tests that were run.
`"readable" : string`	Description of the test result.
`"n_over_time" : int`	Number of sub tests per second.

On benchmark failure a JSON-encoded mapping with the single entry "readable" set to "FAIL" is written to stdout.

Note

This is the funcction that is called in a sub-process by run().

See also

run(), tests()

Method tests: mapping(string:Test) tests()
Description: Return a mapping with all known and enabled benchmark tests.
Returns: Returns a mapping indexed on the display names of the benchmark tests.

Class Tools.Shoot.Test

Constant name: constantstring Tools.Shoot.Test.name
Description: The name of the test.

Method perform

intperform(mixed|voidcontext)

Description

perform() is the function called in the tests, when it returns the test is complete.

The function returns the number of whatever the test did.

Method prepare: optionalmixedprepare()
Description: If this function exists, it computes the context to pass to the perform() function. The time consumed by this function will not count towards the test.

Module Tools.Standalone

Class Tools.Standalone.autodoc_to_html

Description: AutoDoc XML to HTML converter.
See also: tree_split

Variable lay: mapping Tools.Standalone.autodoc_to_html.lay
Description: Layout template headers and trailers.

Method image_prefix: stringimage_prefix()
Description: Path to where in the destination filesystem the images are.

Method parse_text: stringparse_text(Noden, void|String.Bufferret, array(string)|voidsection_path)
Description: Typically called with a <group/> node or a sub-node that is a container.

Class Tools.Standalone.autodoc_to_split_html

Inherit autodoc_to_html: inherit .autodoc_to_html : autodoc_to_html

Class Tools.Standalone.autodoc_to_split_html.Node

Method lookup: Node|zerolookup(stringreference)
Description: Perform a lexical lookup rooted in the current node.

Method low_lookup: Node|zerolow_lookup(stringsym)
Description: Lookup a single symbol in the current node.

Class Tools.Standalone.forkd

Description

Fork Daemon

This is a light-weight daemon that can be used via Process.Process to spawn new processes (by specifying the "forkd" modifier).

The typical use is when the main program is large and/or when it has lots of open file descriptors. This can cause considerable overhead in process creation.

See also

Process.RemoteProcess, Process.create_process

Class Tools.Standalone.forkd.FdStream

Description

This is the main control Stdio.Fd and is always on fd number 3.

To spawn a new process, a new Stdio.PROP_SEND_FD capable Stdio.Fd is sent over this fd, and a single byte of data is sent as payload.

The sent fd will become a ForkFd inside a ForkStream.

Inherit File: inherit Stdio.File : File

Class Tools.Standalone.forkd.ForkStream

Description

This class maps 1 to 1 to Process.RemoteProcess, and implements the daemon side of the RPC protocol.

It contains an array (fds) with the file descriptors that have been received so far from the remote.

Inherit File: inherit Stdio.File : File

Variable fds: array(Stdio.Fd) Tools.Standalone.forkd.ForkStream.fds
Description: The remote file descriptors received so far in order.

Class Tools.Standalone.git_export_autodoc

Description

Tool for converting the Pike git repository to a corresponding git repository containing the extracted autodoc.xml and documentation.

It supports incremental operation, so that it can be used to keep track with the source.

Typical use: pike -x git_export_autodoc -v --git-dir=Autodoc.git

Variable autodoc_hash: mapping(string:string) Tools.Standalone.git_export_autodoc.autodoc_hash
Description: Mapping from doc commit sha1 or export reference to sha1 for the autodoc.xml blob.

Variable doc_refs: mapping(string:string) Tools.Standalone.git_export_autodoc.doc_refs
Description: Mapping from doc reference to doc commit sha1 or export reference.

Variable doc_to_parents: mapping(string:array(string)) Tools.Standalone.git_export_autodoc.doc_to_parents
Description: Mapping from doc commit sha1 or export reference to array of same for its direct parents.

Variable doc_to_src: mapping(string:array(string)) Tools.Standalone.git_export_autodoc.doc_to_src
Description: Mapping from doc commit sha1 or export reference to the corresponding list of source commit sha1s.

Variable refdoc_hash: mapping(string:string) Tools.Standalone.git_export_autodoc.refdoc_hash
Description: Mapping from source commit to refdoc sha1.

Variable rev_refs: mapping(string:multiset(string)) Tools.Standalone.git_export_autodoc.rev_refs
Description: Lookup from source commit sha1 to the corresponding references (if any).

Variable src_refs: mapping(string:string) Tools.Standalone.git_export_autodoc.src_refs
Description: Mapping from source reference to source commit sha1.

Variable src_to_doc: mapping(string:string) Tools.Standalone.git_export_autodoc.src_to_doc
Description: Mapping from source commit sha1 to doc commit sha1 or export reference.

Method get_version: stringget_version()
Description: Attempt to get the version for the Pike source tree.

Class Tools.Standalone.pike_to_html

Description

Convert Pike code to HTML with syntax highlighting

pike -x pike_to_html /path/to/file.pike > file.html

Method convert

stringconvert(stringcode)

Description

Turn code into HTML.

The following css classes will be used:

Delimiters: delim
Reserved words: lang
Data types: type
Constants: const
Modifiers: mods
Root namespaces: ns
Strings: string
Comments: comment
Macros: macro

Parameter code

Class Tools.Standalone.pmar_install

Description

a prototype installer for prepackaged modules

note: portions of this code are highly inefficient (wrt tar filehandling). we assume that this will be used infrequently enough that this is not going to be a problem.

a package file is a tar file that contains the following structure:

ROOTDIR/ METADATA.TXT a file containing metadata about the package format: KEY=value, where values include: PLATFORM, in the form of os/processor (either can be "any") MODULE, the name of the module, in Module.Submodule format. VERSION, the version of this module. MODULE/ any files that need to be installed in the module directory MODREF/ ??? documentation suitable for inclusion in the modref INCLUDE/ ??? any pike language include files to be installed SCRIPTS/ standalone (no bundled dependencies) scripts used to perform custom actions they receive the installer object (this) and the System.Filesystem object of the package archive as arguments to the constructor. The method "run()" should perform the actual action. The run() method should return true or false to indicate success or failure. preinstall.pike postinstall.pike

Class Tools.Standalone.precompile

Description: Convert .cmod-files to .c files.

Class Tools.Standalone.precompile.ArgCheckFunction

Variable tokens: array Tools.Standalone.precompile.ArgCheckFunction.tokens

Method __create__: protectedlocalvoid__create__(arraytokens)

Method create: Tools.Standalone.precompile.ArgCheckFunctionTools.Standalone.precompile.ArgCheckFunction(arraytokens)

Class Tools.Standalone.process_files

Description

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.

Inherit process_files: inherit Toole.Standalone.process_files : process_files

Variable default_flag_docs: string Tools.Standalone.process_files.default_flag_docs
Description: Flag docs to append to your usage description. Explains default options.

Variable description: string Tools.Standalone.process_files.description
Description: 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.

Variable overwrite: bool Tools.Standalone.process_files.overwrite
Description: 0 to make backups, 1 to overwrite (default)

Variable recursive: bool Tools.Standalone.process_files.recursive
Description: 1 to recurse into directories, 0 not to (default)

Variable usage: string Tools.Standalone.process_files.usage
Description: 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.

Variable verbosity: int(0..) Tools.Standalone.process_files.verbosity
Description: 0 in quiet mode, 1 by default, above = more output

Variable version

string Tools.Standalone.process_files.version

Description

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

Example

string version =
    sprintf("%d.%d.%d",(int)__REAL_VERSION__,__REAL_MINOR__,__REAL_BUILD__);

Variable want_args: int Tools.Standalone.process_files.want_args
Description: The number of (mandatory) command-line options your hack needs and which your process callback wants (beside the input file). By default 0.

Method main: int(0..)main(intargc, array(string) argv)
Description: Base implementation of main program, handling basic flags and returning an exit status matching the number of failures during operation.
FIXME: 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.

Method process: stringprocess(stringinput, string ... args)
Description: 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.

Method process_file: boolprocess_file(stringpath, string ... args)
Description: 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.
See also: process_path

Method process_path: int(0..)process_path(stringpath, string ... args)
Description: 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.
See also: process_file

Module Tools.Testsuite

Method log_msg

voidlog_msg(stringmsg, mixed ... args)

Description

Logs a testsuite message to stderr. The message is shown regardless of the verbosity level. If the previous message was logged without a trailing newline then a newline is inserted first.

The message should normally have a trailing newline - no extra newline is added to it. Use log_status to log a message intended to be overwritten.

Method log_msg_cont: voidlog_msg_cont(stringmsg, mixed ... args)
Description: Similar to log_msg, but doesn't insert a newline first if the previous message didn't end with one. Does however insert a newline if the previous message was logged "in place" by log_status.

Method log_status

voidlog_status(stringmsg, mixed ... args)

Description

Logs a testsuite status message to stdout. This is suitable for nonimportant progress messages.

If the verbosity is 0 then nothing is logged, but the message is saved and will be logged if the next call is to log_msg.
If the verbosity is 1, the message is "in place" on the current line without a trailing line feed, so that the next log_status message will replace this one.
If the verbosity is 2 or greater, the message is logged with a trailing line feed.

The message should be short and not contain newlines, to work when the verbosity is 1, but if it ends with a newline then it's logged normally. It can be an empty string to just clear the last "in place" logged message - it won't be logged otherwise.

See also

log_twiddler

Method log_twiddler: voidlog_twiddler()
Description: Logs a rotating bar for showing progress. Only output at the end of an "in place" message written by log_status on verbosity level 1.

Method report_result: voidreport_result(intsucceeded, intfailed, void|intskipped)
Description: Use this to report the number of successful, failed, and skipped tests in a script started using run_script. Can be called multiple times - the counts are accumulated.

Method run_script: array(int) run_script(string|array(string) pike_script)
Description: Runs an external pike script from a testsuite. Use Tools.Testsuite.report_result in the script to report how many tests succeeded, failed, and were skipped. Those numbers are returned in the array from this function.

Class Tools.Testsuite.CompatPlugin

Annotations

@Pike.Annotations.Implements(Plugin)

Description

A source code plugin for running code in different Pike compat modes. Instantiated with the pike compat version to run in, e.g. "7.8".

Inherit Plugin: inherit Plugin : Plugin

Variable pike_compat: string Tools.Testsuite.CompatPlugin.pike_compat

Method __create__: protectedlocalvoid__create__(stringpike_compat)

Method create: Tools.Testsuite.CompatPluginTools.Testsuite.CompatPlugin(stringpike_compat)

Method preprocess: stringpreprocess(stringsource)
Description: Modifies the source code to add "#pike" and the version at the top of the code, followed by "#pragma no_deprecation_warnings".

Method process_name: stringprocess_name(stringname)
Description: Modifies the name by adding the version and "compat" after the test name, e.g. "testsuite:1: Test 1 (7.8 compat)".

Class Tools.Testsuite.M4Testsuite

Description: Represents a "testsuite" file, after m4 processing.

Inherit Testsuite: inherit Testsuite : Testsuite

Class Tools.Testsuite.M4Testsuite.M4Test

Description: Represents a test case from a "testsuite" file, after m4 processing.

Inherit Test: inherit Test : Test

Method create: Tools.Testsuite.M4Testsuite.M4TestTools.Testsuite.M4Testsuite.M4Test(stringdata)
Parameter data: The data from a testsuite file, after start/stop markers have been stripped and the file splitted on "...." tokens. From this the conditions, file, line, number, type and source will be parsed.

Class Tools.Testsuite.Plugin

Description: Interface for source code plugins, added to a Test by calling add_plugin.

Method active: boolactive(Testt)
Description: Returns 1 if the plugin is active (i.e. should be called by the test), otherwise 0. Defaults to 1.

Method preprocess: stringpreprocess(stringsource)
Description: Called by the test to modify the source code. By default just returns the unmodified source.

Method process_name: stringprocess_name(stringname)
Description: Allows for modifications of the name of the test. By default just returns the name unmodified.

Class Tools.Testsuite.Test

Description: Rerpesents a test in a testsuite.

Variable conditions: array(string) Tools.Testsuite.Test.conditions
Description: The list of conditions that has to be met for this test to not be skipped. Each condition should be an expression.

Variable file: string Tools.Testsuite.Test.file
Description: The file the testsuite (source) resides in.

Variable inhibit_errors: bool|object Tools.Testsuite.Test.inhibit_errors
Description: This value will be sent to MasterObject.set_inhibit_errors before compilation by compile().

Variable line: int(1..) Tools.Testsuite.Test.line
Description: The line number offset to this test in the file.

Variable number: int(1..) Tools.Testsuite.Test.number
Description: The test number in this file.

Variable source: string Tools.Testsuite.Test.source
Description: The source code that is to be compiled and evaluated.

Variable type

string Tools.Testsuite.Test.type

Description

The type of the test. Any of

"COMPILE"

Compiles the source and make verifies there are no warnings or errors.

"COMPILE_ERROR"

Compiles the source and expects to get a compilation error.

"COMPILE_WARNING"

Compiles the source and expects to get a compilation warning.

"EVAL_ERROR"

Evaluates the method a of the source source and expects an evaluation error.

"FALSE"

Verifies that the response from method a of the source is false.

"TRUE"

Verifies that the response from method a of the source is true.

"PUSH_WARNING"

Evaluate the method a and take the resulting string and push it to the set of ignored warnings. The same warning can be pushed multiple times, but must be popped multiple times.

"POP_WARNING"

Evaluate the method a and take the resulting string and pop the warning from the set of ignored warnings. When popped the same number of times as it has been pushed, the warning is no longer ignored.

"PUSH_EXPECTED_COMPILE_ERROR"

Evaluate the method a and take the resulting string and push it to the set of expected compilation errors. The same error can be pushed multiple times, but must also be popped the same number of times.

"POP_EXPECTED_COMPILE_ERROR"

Evaluate the method a and take the resulting string and pop the expected compilation error from the set of expected compilation errors. When popped a testsuite failure is logged if the compilation error was not triggered since it was pushed.

"RUN"

Compiles and evaluates method a of the source, but ignores the result.

"RUNCT"

Compiles and evaluates method a od source, and expects an array(int) of two or three elements back.

Array
`int0`	The number of successful tests performed.
`int1`	The number of failed tests,
`int2`	Optionally the number of skipped tests.

"EQ"

Compares the result of the method a and b with ==.

"EQUAL"

Compares the result of the method a and b with equal.

Method add_plugin: voidadd_plugin(Pluginp)
Description: Add a Plugin object to the test, allowing the source code to be modified.

Method compile: programcompile(stringsrc)
Description: Compile the source code src in the context of the file this test belongs. Note that no changes in error mode is done and compilation errors are not caught.

Method compile: variantprogramcompile()
Description: Set the error mode according to inhibi_errors, applies any source code plugins by calling prepare_source and finally compiles the result. Any resulting compilation errors will be stored in compilation_error. The error mode will be set to 0 after compiltion is done.

Method create: Tools.Testsuite.TestTools.Testsuite.Test(stringfile, intline, intnumber, stringtype, stringsource, void|array(string) cond)

Method name: stringname()
Description: The name of this test, in the form of filename:line:" Test "number. The result is then processed by any code plugins.

Method prepare_source: stringprepare_source()
Description: Applies all the plugins on the source code contained in this test and returns the result.

Class Tools.Testsuite.Test.AdjustLine

Method __create__: protectedlocalvoid__create__()

Method create: Tools.Testsuite.Test.AdjustLineTools.Testsuite.Test.AdjustLine()

Module Tools.sed

Description

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

Method `(): protectedstring|array`()(string|array(string) commands, string|array(string) data, void|intsuppress)

Module Unicode

Constant version: constant Unicode.version
Description: Contains the version of the current Unicode database as a string, e.g. "5.0.0".

Method is_rtlchar: intis_rtlchar(intc)
Description: Returns 1 if the character is a RTL character or indicator, otherwise 0.

Method is_rtlstring: intis_rtlstring(strings)
Description: Returns 1 if the string contains RTL characters or RTL indicators, otherwise 0.

Method is_whitespace: boolis_whitespace(intc)
Description: Returns 1 if the character is a white space character, otherwise 0.

Method is_wordchar

intis_wordchar(intc)

Description

Returns whether a unicode character c is a word, part of a word or not.

Returns

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

Method normalize

stringnormalize(stringdata, stringmethod)

Description

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

Method split_words: array(string) split_words(stringinput)
Description: 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.

Method split_words_and_normalize: array(string) split_words_and_normalize(stringinput)
Description: A less wasteful equivalent of split_words(normalize(input, "NFKD")).

Module VCDiff

Description

Pike glue for the open-vcdiff differential compression library. http://code.google.com/p/open-vcdiff/

Encoding and decoding relies on a common string that the differences are computed against - this string is called the dictionary.

Basic usage:

string dict ="abcdef";VCDiff.Encoder encoder =VCDiff.Encoder (dict);string encoded = encoder->encode ("abcdefghijklmnopqrstuvwxyz");VCDiff.Decoder decoder =VCDiff.Decoder (dict);string decoded = decoder->decode (encoded);

Module Val

Description

This module contains special values used by various modules, e.g. a null value used both by Sql and Standards.JSON.

In many ways these values should be considered constant, but it is possible for a program to replace them with extended versions, provided they don't break the behavior of the base classes defined here. Since there is no good mechanism to handle such extending in several steps, pike libraries should preferably ensure that the base classes defined here provide required functionality directly.

Note

Since resolving using the dot operator in e.g. Val.null is done at compile time, replacement of these values often must take place very early (typically in a loader before the bulk of the pike code is compiled) to be effective in such cases. For this reason, pike libraries should use dynamic resolution through e.g. -> or master()->resolv() instead.

Variable true
Variable false

Boolean Val.true
Boolean Val.false

Description

Objects that represent the boolean values true and false. In a boolean context these evaluate to true and false, respectively.

They produce 1 and 0, respectively, when cast to integer, and "1" and "0" when cast to string. They do however not compare as equal to the integers 1 and 0, or any other values. Val.true only compares (and hashes) as equal with other instances of True (although there should be as few as possible). Similarly, Val.false is only considered equal to other False instances.

Protocols.JSON uses these objects to represent the JSON literals true and false.

Note

The correct way to programmatically recognize these values is something like

if(objectp(something) && ([object]something)->is_val_true) ...

and

if(objectp(something) && ([object]something)->is_val_false) ...

respectively. See Val.null for rationale.

Note

Pike natively uses integers (zero and non-zero) as booleans. These objects don't change that, and unless there's a particular reason to use these objects it's better to stick to e.g. 0 and 1 for boolean values - that is both more efficient and more in line with existing coding practice. These objects are intended for cases where integers and booleans occur in the same place and it is necessary to distinguish them.

Variable local_timezone: int Val.local_timezone
Description: The local timezone without daylight-saving correction.
Note: This value is determined once at process start, and cached for the lifetime of the process.

Variable null

Null Val.null

Description

Object that represents a null value.

In general, null is a value that represents the lack of a real value in the domain of some type. For instance, in a type system with a null value, a variable of string type typically can hold any string and also null to signify no string at all (which is different from the empty string). Pike natively uses the integer 0 (zero) for this, but since 0 also is a real integer it is sometimes necessary to have a different value for null, and then this object is preferably used.

This object is false in a boolean context. It does not cast to anything, and it is not equal to anything else but other instances of Null (which should be avoided).

This object is used by the Sql module to represent SQL NULL, and it is used by Protocols.JSON to represent the JSON literal null.

Note

Do not confuse the null value with UNDEFINED. Although UNDEFINED often is used to represent the lack of a real value, and it can be told apart from an ordinary zero integer with some effort, it is transient in nature (for instance, it automatically becomes an ordinary zero when inserted in a mapping). That makes it unsuitable for use as a reliable null value.

Note

The correct way to programmatically recognize Val.null is something like

if(objectp(something) && ([object]something)->is_val_null) ...

That way it's possible for other code to replace it with an extended class, or create their own variants which needs to behave like Val.null.

FIXME

The Oracle glue currently uses static null objects which won't be affected if this object is replaced.

Method iso_time: stringiso_time(mapping(string:int) tm)
Parameter tm: Standard tm mapping, optionally extended with nsec for nanoseconds.
Returns: ISO formatted time.
See also: mktime()

Method iso_timezone: finalstringiso_timezone(inttimezone)
Parameter timezone: Timezone in seconds west from UTC (must include daylight-saving time adjustment).
Returns: ISO formatted timezone east from UTC.
See also: localtime()

Class Val.Boolean

Description: Common base class for Val.True and Val.False, mainly to facilitate typing. Do not create any instances of this.

Constant is_val_boolean: constantint Val.Boolean.is_val_boolean
Description: Nonzero recognition constant that can be used to recognize both Val.true and Val.false.

Class Val.Date

Description: Lightweight date type. Stores internally in days since epoch. Supports arithmetic with Interval, Timestamp, Time and TimeTZ objects. Cast it to int or float to obtain unix_time.
See also: Interval, Timestamp, Time, TimeTZ, Range

Variable days: int Val.Date.days
Description: Since 1970-01-01 (epoch).

Method create: Val.DateVal.Date(intyear, intmonth, intday)
Val.DateVal.Date(this_programcopy)
Val.DateVal.Date(Timestampcopy)
Val.DateVal.Date(mapping(string:int) tm)
Val.DateVal.Date(intunix_time)
Val.DateVal.Date(floatunix_time)
Val.DateVal.Date()

Class Val.False

Description: Type for the Val.false object. Do not create more instances of this - use Val.false instead.

Inherit Boolean: inherit Boolean : Boolean

Constant is_val_false: constantint Val.False.is_val_false
Description: Nonzero recognition constant.

Class Val.Inet

Description: Lightweight IPv4 and IPv6 address type that stores the netmask and allows simple arithmetic and comparison operators.

Variable address: int Val.Inet.address
Description: IP address converted to an integer. IPv4 addresses will be 32-bit or less.

Variable masklen: int Val.Inet.masklen
Description: Defines the netmask. For both IPv4 and IPv6 addresses, masklen will be 128 in case of full addresses.

Method `<<: bool res = Val.Inet() << that
Description: Is contained by.

Method `>>: bool res = Val.Inet() >> that
Description: Contains.

Method create: Val.InetVal.Inet(intip, void|intmasklen)
Val.InetVal.Inet()
Parameter ip: An IPv4 or IPv6 ip address.
Parameter masklen: Defines the netmask, always in the range between 0 and 128; i.e. for IPv4 addresses you should add 12 * 8 to the actual IPv4-masklen.

Method create: Val.InetVal.Inet(stringip)
Parameter ip: A string defining an IPv4 or IPv6 address with an optional masklen attached. If the address is in IPv6 notation, the range of the masklen is expected to be between 0 and 128. If the address is in IPv4 notation, the range of the masklen is expected to be between 0 and 32.

Class Val.Interval

Description: Lightweight time and date interval type. It stores the interval in integers of nanoseconds, days and months. Supports arithmetic with Time, TimeTZ, Timestamp and Date objects. Cast it to int or float to obtain seconds.
Note: Depending on daylight-saving time, a day may not equal 24 hours.
Note: The number of days in a month depends on the the time of the year.
See also: Timestamp, Date, Time

Inherit Time: inherit Time : Time

Variable days: int Val.Interval.days
Description: Number of days; may not be equal to 24 hours per day, depending on daylight-saving time.

Variable months: int Val.Interval.months
Description: Number of months; the number of days per month varies accordingly.

Method cast: (int)Val.Interval() (float)Val.Interval() (string)Val.Interval() (array)Val.Interval() (mapping)Val.Interval() (multiset)Val.Interval()
Description: Casting intervals with days or months to int or float is not possible since the units are not constant. Casting an interval to string will return a value which is SQL-compliant.

Method tm: mapping(string:int) tm()
Returns: A tm-like mapping which describes the interval. The mapping will include an extra nsec component, and optionally isnegative = 1 if the interval is a negative time interval.
See also: mktime(), gmtime()

Class Val.Null

Description: Type for the Val.null object. Do not create more instances of this - use Val.null instead.

Inherit Null: inherit Builtin.Null : Null

Class Val.Pointer

Description: A wrapper for a passing around raw pointers between modules. Should not be used directly from pike code.

Inherit Pointer: inherit Builtin.Pointer : Pointer

Class Val.Range

Description: Generic lightweight range type. Supports any values for lower and upper boundaries that implement lfun::`<() and lfun::`-(), and preferrably also cast to int and string.
Note: Can only contain a single contiguous range.
Note: The empty range must be stored as (Math.inf, -Math.inf) if assigned directly to from and till.

Variable from: value_type Val.Range.from
Description: The lower inclusive boundary.

Variable till: value_type Val.Range.till
Description: The upper exclusive boundary.

Method `!: bool res = !Val.Range()
Returns: True if range is empty.
See also: isempty()

Method `&: bool res = Val.Range() & that
Description: Overlap: have points in common.

Method `*: this_program res = Val.Range() * that
Description: Intersection

Method `+: this_program res = Val.Range() + that
Description: Union

Method `-: this_program res = Val.Range() - that
Description: Difference

Method `<<: bool res = Val.Range() << that
Description: Strictly left of

Method `>>: bool res = Val.Range() >> that
Description: Strictly right of

Method `|: bool res = Val.Range() | that
Description: Is adjacent to
FIXME: This does NOT seem like a good operator for this operation.

Method contains: boolcontains(this_program|value_typeother)
Returns: True if this range fully contains another range or element.

Method create: Val.RangeVal.Range(value_typefrom, value_typetill)
Val.RangeVal.Range(this_programcopy)
Val.RangeVal.Range()
Parameter from: Lower inclusive boundary for the range. Specify no lower-boundary by filling in -Math.inf.
Parameter till: Upper exclusive boundary for the range. Specify no upper-boundary by filling in Math.inf.
See also: Math.inf

Method interval: mixedinterval()
Returns: Calculates the value of the interval: till - from. Returns 0 if the range is empty.

Method isempty: localboolisempty()
Returns: True if range is empty.
See also: `!()

Method merge: this_programmerge(this_program ... other)
Parameter other: Extends the current range to the smallest range which encompasses itself and all other given ranges.
FIXME: This seems like the operation that `|() ought to do.

Method sql: finalstringsql()
Returns: A string representing the range using SQL-compliant syntax.

Class Val.Time

Description: Lightweight time type. Stores absolute times in a day with nanosecond resolution. Normalised value range is between 00:00:00.000000000 and 23:59:59.999999999. Values outside this range are accepted, and have arithmetically sound results. Supports arithmetic with Interval and Date objects. Cast it to int or float to obtain seconds since 00:00.
See also: Interval, Date, TimeTZ, Range

Inherit Timebase: inherit Timebase : Timebase

Method create: Val.TimeVal.Time(inthour, intmin, void|intsec, void|intnsec)
Val.TimeVal.Time(intsec)
Parameter hour: Hours since epoch.
Parameter min: Minutes since epoch.
Parameter sec: Seconds since epoch.
Parameter nsec: Nanoseconds since epoch.

Method create: Val.TimeVal.Time(mapping(string:int) tm)
Parameter tm: Standard tm mapping, optionally extended with nsec for nanoseconds. Passed values will not be normalised. Days/months/years are ignored.

Method tm: mapping(string:int) tm()
Returns: A tm-like mapping which describes the time. The mapping will include an extra nsec component.
See also: mktime(), gmtime()

Class Val.TimeTZ

Description: Lightweight time type with timezone. Equivalent to Time, but stores a timezone offset as well. Cast it to int or float to obtain seconds since 00:00.
See also: Time, Date, Interval, Range

Inherit Time: inherit Time : Time

Variable timezone: int Val.TimeTZ.timezone
Description: Timezone offset in seconds west from UTC (includes daylight-saving time adjustment).
Note: ISO time format displays the timezone in seconds east from UTC.
See also: localtime()

Method create: Val.TimeTZVal.TimeTZ(mapping(string:int) tm)
Parameter tm: Standard tm mapping, optionally extended with nsec for nanoseconds. Any specified timezone is used as is. Passed values will not be normalised. Days/months/years are ignored.

Method create: Val.TimeTZVal.TimeTZ(intyear, intmonth, intday, inthour, intmin, void|intsec, void|intnsec)
Description: Stores just the time of the day components, but including the correct timezone offset with any daylight-saving correction active on the date specified.
Parameter year: Absolute year (e.g. 1900 == 1900, 2000 = 2000, 2017 == 2017).
Parameter month: Month of the year (January == 1 ... December == 12).
Parameter day: Day of the month (typically between 1 and 31).
Parameter hour: Hour of the day (typically between 0 and 23).
Parameter min: Minutes (typically between 0 and 59).
Parameter sec: Seconds (typically between 0 and 59).
Parameter nsec: Nanoseconds (typically between 0 and 999999999).
Note: Specified values are expected in the localised time (i.e. relative to the current timezone locale, including daylight-saving correction).
Note: If any of these values are offered in a denormalised range, they will be normalised relative to the startdate offered.
See also: Timestamp, Date, Interval, Time

Class Val.Timebase

Description: Base class for time related objects. Supports arithmetic with Interval objects.
Note: Should not be used by itself.
See also: Timestamp, Time, Interval

Variable nsecs: int Val.Timebase.nsecs
Description: Nanoseconds since epoch (for absolute time classes, epoch equals 1970/01/01 00:00:00 UTC).

Variable usecs

int|float Val.Timebase.usecs

Description

Getting

Microseconds since epoch; reflects the equivalent value as the basic member nsecs.

Setting

Microseconds since epoch; reflects the equivalent value as the basic member nsecs.

Method cast: (int)Val.Timebase() (float)Val.Timebase() (string)Val.Timebase() (array)Val.Timebase() (mapping)Val.Timebase() (multiset)Val.Timebase()
Description: Can be casted to string, float and int. Casting it to float and int return unix-time values.
See also: mktime(), gmtime()

Method create: Val.TimebaseVal.Timebase(void|mapping(string:int) tm)
Val.TimebaseVal.Timebase(this_programcopy)
Val.TimebaseVal.Timebase(int|floatsec, void|intnsec)
Parameter sec: Seconds since epoch.
Parameter nsec: Nanoseconds since epoch.

Class Val.Timestamp

Description: Lightweight time and date type. The values point at absolute points in time. The values are stored internally with nanosecond resolution since epoch (1970/01/01 00:00:00 UTC). Supports arithmetic with Interval objects. Cast it to int or float to obtain unix_time.
See also: Interval, Date, Range, localtime(), mktime()

Inherit Timebase: inherit Timebase : Timebase

Method cast: (int)Val.Timestamp() (float)Val.Timestamp() (string)Val.Timestamp() (array)Val.Timestamp() (mapping)Val.Timestamp() (multiset)Val.Timestamp()
Description: When cast to string it returns an ISO formatted timestamp that includes daylight-saving and timezone corrections.

Method create: Val.TimestampVal.Timestamp(intyear, intmonth, intday, void|inthour, void|intmin, void|intsec, void|intnsec)
Val.TimestampVal.Timestamp(intunix_time, void|intnsec)
Parameter year: Absolute year (e.g. 1900 == 1900, 2000 = 2000, 2017 == 2017).
Parameter month: Month of the year (January == 1 ... December == 12).
Parameter day: Day of the month (typically between 1 and 31).
Parameter hour: Hour of the day (typically between 0 and 23).
Parameter min: Minutes (typically between 0 and 59).
Parameter sec: Seconds (typically between 0 and 59).
Parameter nsec: Nanoseconds (typically between 0 and 999999999).
Note: Specified values are expected in the localised time (i.e. relative to the current timezone locale, including daylight-saving correction).
Note: If any of these values are offered in a denormalised range, they will be normalised relative to the startdate offered. I.e. it allows primitive year/month/day/hour/minute/second/nanosecond arithmetic. For more advanced arithmetic you must use Interval objects.
See also: localtime(), mktime()

Method tm: mapping(string:int) tm()
Returns: The same as localtime(), but augmented by an extra member called nsec.
See also: localtime()

Class Val.True

Description: Type for the Val.true object. Do not create more instances of this - use Val.true instead.

Inherit Boolean: inherit Boolean : Boolean

Constant is_val_true: constantint Val.True.is_val_true
Description: Nonzero recognition constant.

Module Web

Description: Modules implementing various web standards.

Method decode_jwk: Crypto.Sign.State|Crypto.MAC.Statedecode_jwk(mapping(string(7bit):string(7bit)) jwk)
Description: Decode a JSON Web Key (JWK).
Returns: Returns an initialized Crypto.Sign.State or Crypto.MAC.State on success and UNDEFINED on failure.

Method decode_jwk: variantCrypto.Sign.State|Crypto.MAC.Statedecode_jwk(string(8bit)jwk)
Description: Decode a JSON Web Key (JWK).
Returns: Returns an initialized Crypto.Sign.State or Crypto.MAC.State on success and UNDEFINED on failure.

Method decode_jwk_set: array(Crypto.Sign.State|Crypto.MAC.State) decode_jwk_set(mapping(string(8bit):array(mapping(string(7bit):string(7bit)))) jwk_set)
Description: Decode a JSON Web Key (JWK) Set.
See also: RFC 7517 section 5, decode_jwk()

Method decode_jwk_set: variantarray(Crypto.Sign.State|Crypto.MAC.State) decode_jwk_set(string(7bit)jwk_set)
Description: Decode a JSON Web Key (JWK) Set.
See also: RFC 7517 section 5, decode_jwk()

Method decode_jws

array|zerodecode_jws(array(Crypto.Sign.State|Crypto.MAC.State)|Crypto.Sign.State|Crypto.MAC.Statesign, string(7bit)jws)

Description

Decode a JSON Web Signature (JWS).

Parameter sign

The asymetric public or MAC key(s) to validate the jws against.

Parameter jws

A JWS as eg returned by encode_jws().

Returns

Returns 0 (zero) on validation failure.

Returns an array with two elements on success:

Array
`mapping(string(7bit):string(7bit)\|int) 0`	The JOSE header.
`mixed1`	The JWS payload.

See RFC 7515 section 3.

See also

encode_jws(), decode_jwt(), Crypto.Sign.State()->jose_decode(), RFC 7515

Method decode_jwt

Description

Decode a JSON Web Token (JWT).

Parameter sign

The asymetric public or MAC key(s) to validate the jwt against.

Parameter jwt

A JWT as eg returned by encode_jwt().

Returns

Returns 0 (zero) on validation failure (this includes validation of expiry times).

Returns a mapping of the claims for the token on success. See RFC 7519 section 4.

Note

The time check of the "nbf" value has a hard coded 60 second grace time (as allowed by RFC 7519 section 4.1.5).

See also

encode_jwt(), decode_jws(), RFC 7519 section 4

Method encode_jwk: string(7bit)encode_jwk(mapping(string(7bit):string(7bit)) jwk)
Description: Encode a JSON Web Key (JWK).

Method encode_jwk: variantstring(7bit)encode_jwk(Crypto.Sign.State|Crypto.MAC.Statesign, bool|voidprivate_key)
Description: Encode a JSON Web Key (JWK).
Parameter sign: The initialized Crypto.Sign.State or Crypto.MAC.State for which a JWK is to be generated.
Parameter private_key: If true the private fields of sign will also be encoded into the result.
Returns: Returns the corresponding JWK.

Method encode_jws

string(7bit)encode_jws(Crypto.Sign.State|Crypto.MAC.Statesign, mixedtbs, string(7bit)|voidmedia_type)

Description

Encode a JSON Web Signature (JWS).

Parameter sign

The asymetric private or MAC key to use for signing the result.

Parameter tbs

The value to sign.

Parameter media_type

The media type of tbs, cf RFC 7515 section 4.1.9.

Returns

Returns 0 (zero) on encoding failure (usually that sign doesn't support JWS.

Returns a corresponding JWS on success.

See also

decode_jwt(), RFC 7515

Method encode_jwt

string(7bit)encode_jwt(Crypto.Sign.State|Crypto.MAC.Statesign, mapping(string:string|int) claims)

Description

Encode a JSON Web Token (JWT). Automatically adds the optional "issued at" timestamp and JWD ID (using UUID v4).

Parameter sign

The asymetric private or MAC key to use for signing the result.

Parameter claims

The set of claims for the token. See RFC 7519 section 4.

Returns

Returns 0 (zero) on encoding failure (usually that sign doesn't support JWS.

Returns a corresponding JWT on success.

Note

The claim "iat" (RFC 7519 section 4.1.6 is added unconditionally, and the claim "jti" (RFC 7519 section 4.1.7) is added if not already present.

See also

decode_jwt(), RFC 7519 section 4

Class Web.OWL

Description: Represents an RDF tuple set from an OWL perspective.

Inherit RDFS: inherit .RDFS : RDFS

Class Web.RDF

Description: Represents an RDF domain which can contain any number of complete statements.

Constant rdf_ns: constantstring Web.RDF.rdf_ns
Description: The RDF XML namespace.

Variable rdf_Seq: RDFResource Web.RDF.rdf_Seq
Description: Seq resource.

Variable rdf_Statement: RDFResource Web.RDF.rdf_Statement
Description: Statement resource.

Variable rdf_first: RDFResource Web.RDF.rdf_first
Description: first resource.

Variable rdf_nil: RDFResource Web.RDF.rdf_nil
Description: nil resource.

Variable rdf_object: RDFResource Web.RDF.rdf_object
Description: object resource.

Variable rdf_predicate: RDFResource Web.RDF.rdf_predicate
Description: predicate resource.

Variable rdf_rest: RDFResource Web.RDF.rdf_rest
Description: rest resource.

Variable rdf_subject: RDFResource Web.RDF.rdf_subject
Description: subject resource.

Variable rdf_type: RDFResource Web.RDF.rdf_type
Description: type resource.

Method _sizeof: intsizeof(Web.RDFarg)
Description: Returns the number of statements in the RDF domain.

Method `|: Web.RDF res = Web.RDF() | x
Description: Modifies the current object to create a union of the current object and the object x.

Method add_statement: this_programadd_statement(Resource|string|multiset(string) subj, Resource|string|multiset(string) pred, Resource|string|multiset(string) obj)
Description: Adds a statement to the RDF set. If any argument is a string, it will be converted into a LiteralResource. If any argument is a multiset with one string in it, it will be converted into a URIResource.
Throws: Throws an exception if any argument couldn't be converted into a Resouce object.

Method decode_n_triple_string: stringdecode_n_triple_string(stringin)
Description: Decodes a string that has been encoded for N-triples serialization.
Bugs: Doesn't correctly decode backslashes that has been encoded with with \u- or \U-notation.

Method dereify: booldereify(Resourcer)
Description: Turns the reified statement r into a normal statement, if possible.
Returns: 1 for success, 0 for failure.

Method dereify_all: int(0..)dereify_all()
Description: Dereifies as many statements as possible. Returns the number of dereified statements.

Method encode_n_triple_string: stringencode_n_triple_string(stringin)
Description: Encodes a string for use as tring in N-triples serialization.

Method find_statements

array(array(Resource)) find_statements(Resource|int(0)subj, Resource|int(0)pred, Resource|int(0)obj)

Description

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.

Returns

An array with arrays of three elements.

Array
`Resource0`	The subject of the statement
`Resource1`	The predicate of the statement
`Resource2`	The object of the statement

Method get_3_tuples: stringget_3_tuples()
Description: Returns a 3-tuple serialization of all the statements in the RDF set.

Method get_n_triples: stringget_n_triples()
Description: Returns an N-triples serialization of all the statements in the RDF set.

Method get_properties: array(Resource) get_properties()
Description: Returns all properties in the domain, e.g. all resources that has been used as predicates.

Method get_reify: Resource|zeroget_reify(Resourcesubj, Resourcepred, Resourceobj)
Description: Returns a resource that is the subject of the reified statement {subj, pred, obj}, if such a resource exists in the RDF domain.

Method get_resource: URIResource|zeroget_resource(stringuri)
Description: Returns an RDF resource with the given URI as identifier, or zero.

Method get_subject_map: mapping(Resource:mapping(Resource:array(Resource))) get_subject_map()
Description: Returns a mapping with all the domains subject resources as indices and a mapping with that subjects predicates and objects as value.

Method get_xml: stringget_xml(void|intno_optimize)
Description: Serialize the RDF domain as an XML string.
Parameter no_optimize: If set, the XML serializer will refrain from doing most (size) optimizations of the output.

Method has_statement: boolhas_statement(Resourcesubj, Resourcepred, Resourceobj)
Description: Returns 1 if the RDF domain contains the relation {subj, pred, obj}, otherwise 0.

Method is_object: boolis_object(Resourcer)
Description: Returns 1 if resource r is used as an object, otherwise 0.

Method is_predicate: boolis_predicate(Resourcer)
Description: Returns 1 if resource r is used as a predicate, otherwise 0.

Method is_subject: boolis_subject(Resourcer)
Description: Returns 1 if resource r is used as a subject, otherwise 0.

Method make_resource: URIResourcemake_resource(stringuri)
Description: Returns an RDF resource with the given URI as identifier, or if no such resrouce exists, creates it and returns it.

Method parse_n_triples: intparse_n_triples(stringin)
Description: Parses an N-triples string and adds the found statements to the RDF set. Returns the number of added relations.
Throws: The parser will throw errors on invalid N-triple input.

Method parse_xml: Web.RDFparse_xml(string|Parser.XML.NSTree.NSNodein, void|stringbase)
Description: 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.

Method reify: Resourcereify(Resourcesubj, Resourcepred, Resourceobj)
Description: Returns the result of get_reify, if any. Otherwise calls reify_low followed by remove_statement of the provided statement {subj, pred, obj}.
Returns: The subject of the reified statement.

Method reify_low: Resourcereify_low(Resourcesubj, Resourcepred, Resourceobj)
Description: 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.
Returns: The subject of the reified statement.

Method remove_statement: boolremove_statement(Resourcesubj, Resourcepred, Resourceobj)
Description: Removes the relation from the RDF set. Returns 1 if the relation did exist in the RDF set.

Class Web.RDF.LiteralResource

Description: Resource identified by literal.

Inherit Resource: inherit Resource : Resource

Variable datatype: string Web.RDF.LiteralResource.datatype
Description: Used to contain rdf:datatype value.

Method create: Web.RDF.LiteralResourceWeb.RDF.LiteralResource(stringliteral)
Description: The resource will be identified by literal.

Method get_literal: stringget_literal()
Description: Returns the literal string.

Method get_xml: stringget_xml()
Description: Returns the literal as an XML string.

Class Web.RDF.RDFResource

Description: Resource used for RDF-technical reasons like reification.

Inherit URIResource: inherit URIResource : URIResource

Method create: Web.RDF.RDFResourceWeb.RDF.RDFResource(stringrdf_id)
Description: The resource will be identified by the identifier rdf_id

Method get_qname: stringget_qname(void|stringns)
Description: Returns the qualifying name.

Class Web.RDF.Resource

Description: 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.
Note: Resources instantiated from this class should not be used in other RDF domain objects.
See also: URIResource, LiteralResource

Method get_3_tuple_name: stringget_3_tuple_name()
Description: Returns the nodes' 3-tuple serialized ID.

Method get_n_triple_name: stringget_n_triple_name()
Description: Returns the nodes' N-triple serialized ID.

Class Web.RDF.URIResource

Description: Resource identified by URI.

Inherit Resource: inherit Resource : Resource

Method create: Web.RDF.URIResourceWeb.RDF.URIResource(stringuri)
Description: Creates an URI resource with the uri as identifier.
Throws: Throws an error if another resource with the same URI already exists in the RDF domain.

Method get_namespace: stringget_namespace()
Description: Returns the namespace this resource URI references to.

Method get_qname: string|zeroget_qname(void|stringns)
Description: Returns the qualifying name, or zero.

Method get_uri: stringget_uri()
Description: Returns the URI the resource references to.

Class Web.RDFS

Description: RDF Schema.

Inherit RDF: inherit .RDF : RDF

Constant rdfs_ns: constantstring Web.RDFS.rdfs_ns
Description: The RDF Schema XML-namespace.

Variable rdfs_Class
Variable rdfs_subClassOf
Variable rdfs_Literal
Variable rdfs_subPropertyOf
Variable rdfs_domain
Variable rdfs_range: RDFSResource Web.RDFS.rdfs_Class
RDFSResource Web.RDFS.rdfs_subClassOf
RDFSResource Web.RDFS.rdfs_Literal
RDFSResource Web.RDFS.rdfs_subPropertyOf
RDFSResource Web.RDFS.rdfs_domain
RDFSResource Web.RDFS.rdfs_range

Method add_Class: voidadd_Class(Resourcec)

Method add_subClassOf: voidadd_subClassOf(Resourcea, Resourceb)

Method add_subPropertyOf: voidadd_subPropertyOf(Resourcea, Resourceb)

Class Web.RDFS.RDFSResource

Inherit URIResource: inherit URIResource : URIResource

Module Web.Api

Description

The Web.Api has modules and classes for communicating with various (RESTful) web api's such as Web.Api.Facebook, Web.Api.Instagram, Web.Api.Twitter etc.

Example

string api_key ="......";string api_secret =".......";string redirect_uri ="http://localhost/insta/";Web.Api.Instagram api;string cookie_file ="my-cookie.txt";int main(int argc,array(string) argv){
  api =Web.Api.Instagram(api_key, api_secret, redirect_uri);// If a stored authentication cookie exists, populate the auth object.if(Stdio.exist(cookie_file)){
    api->auth->set_from_cookie(Stdio.read_file(cookie_file));}if(!api->auth->is_authenticated()){// A cookie existed but the authentication has expiredif(api->auth->is_renewable()){
      write("Trying to refresh token...");if(string data = api->auth->refresh_token())Stdio.write_file(cookie_file, data);
        write("done ok!\n");}else{
        werror("failed!\n");}}// No previous authentication exists. Create a new one...else{// Get the uri to the authentication endpointstring uri = api->auth->get_auth_uri();

      write("Opening \"%s\" in browser.\nCopy the contents of the address ""bar and paste here: ",Standards.URI(uri));

      sleep(2);// For MacProcess.create_process(({"open", uri }));string resp =Stdio.Readline()->read();mapping p =Web.Auth.query_to_mapping(Standards.URI(resp)->query);string code;// If the auth object is OAuth and not OAuth2 this step is required.// Instagram is OAuth2, but Twitter is OAuth1if(p->oauth_token){
        auth->set_authentication(p->oauth_token);
        code = p->oauth_verifier;}else{
        code = p->code;}// Now, get an access tokenif(string data = auth->request_access_token(code)){Stdio.write_file(cookie, data);}else{
        werror("Failed getting an access token. Aborting!\n");return 1;}}}if(api->auth->is_authenticated()){// No UID (arg1) means get the authenticated users stuff// No additional params (arg2)// Run async (arg3)mapping m = api->users->recent(0, 0,lambda(mixed m){
      werror("Insta: %O\n", m);
      exit(0);});return-1;}else{
    werror("No authentication was aquired!\n");return 1;}}

Constant USER_AGENT: constantstring Web.Api.USER_AGENT
Description: Default user agent in HTTP calls

Class Web.Api.Api

Description

Base class for implementing a (RESTful) WebApi like Facebook's Graph API, Instagram's API, Twitter's API and so on.

Note: This class is useless in it self, and is intended to be inherited by classes implementing a given Web.Api.

Look at the code in Web.Api.Github, Web.Api.Instagram, Web.Api.Linkedin etc to see some examples of implementations.

Typedef Callback: typedeffunction(mixed, Protocols.HTTP.Query, mixed ... :void) Web.Api.Api.Callback
Description: Typedef for the async callback method signature.

Typedef Callback: typedeffunction(mixed, Protocols.HTTP.Query|Protocols.HTTP.Promise.Result, mixed ... :void) Web.Api.Api.Callback
Description: Typedef for the async callback method signature.

Typedef ParamsArg: typedefmapping|Web.Auth.Params Web.Api.Api.ParamsArg
Description: Typedef for a parameter argument

Constant ACCESS_TOKEN_PARAM_NAME

protected constantstring Web.Api.Api.ACCESS_TOKEN_PARAM_NAME

Description

In some API's (LinkedIn f ex) this is named something else so it needs to be overridden i cases where it has a different name than the standard one.

Note

Obsolete.

This is only used if AUTHORIZATION_METHOD has been set to "".

Constant API_URI: constantstring Web.Api.Api.API_URI
Description: The default URI to the remote API

Constant AUTHORIZATION_METHOD

protected constantstring Web.Api.Api.AUTHORIZATION_METHOD

Description

Authorization header prefix.

This is typically "Bearer" as per RFC 6750, but some apis use the older "token".

Constant AuthClass: constant Web.Api.Api.AuthClass
Description: Authentication class to use

Constant DECODE_UTF8: protected constantint Web.Api.Api.DECODE_UTF8
Description: If 1Standards.JSON.decode_utf8() will be used when JSON data is decoded.

Variable _auth: protectedWeb.Auth.OAuth2.Client Web.Api.Api._auth
Description: Authorization object.
See also: Web.Auth.OAuth2

Variable _query_objects: protectedmapping(int:array(Protocols.HTTP.Query|Callback)) Web.Api.Api._query_objects
Description: The HTTP query objects when running async.

Variable auth: Web.Auth.OAuth2.Client Web.Api.Api.auth
Description: Getter for the authentication object. Most likely this will be a class derived from Web.Auth.OAuth2.Client.
See also: Web.Auth.OAuth2.Client or Web.Auth.OWeb.Auth.Client
Note: Read only

Variable http_request_timeout: int(0..) Web.Api.Api.http_request_timeout
Description: Request timeout in seconds. Only affects async queries.

Variable utf8_decode: bool Web.Api.Api.utf8_decode
Description: If 1Standards.JSON.decode_utf8() will be used when JSON data is decoded.

Method call: mixedcall(stringapi_method, void|ParamsArgparams, void|stringhttp_method, void|stringdata, void|Callbackcb, mixed ... rest)
Description: Calls a remote API method.
Throws: An exception is thrown if the response status code is other than 200, 301 or 302.
Parameter api_method: The remote API method to call! This should be a Fully Qualified Domain Name
Parameter params: Additional params to send in the request
Parameter http_method: HTTP method to use. GET is default
Parameter data: Inline data to send in a POST request for instance.
Parameter cb: Callback function to get into in async mode
Returns: If JSON is available the JSON response from servie will be decoded and returned. If not, the raw response (e.g a JSON string) will be returned. The exception to this is if the status code in the response is a 30x (a redirect), then the response headers mapping will be returned.

Method close_connections: voidclose_connections()
Description: Forcefully close all HTTP connections. This only has effect in async mode.

Method create: Web.Api.ApiWeb.Api.Api(void|stringclient_id, void|stringclient_secret, void|stringredirect_uri, void|string|array(string)|multiset(string) scope)
Description: Creates a new Api instance
Parameter client_id: The application ID
Parameter client_secret: The application secret
Parameter redirect_uri: Where the authorization page should redirect back to. This must be fully qualified domain name.
Parameter scope: Extended permissions to use for this authentication.

Method default_params: protectedmappingdefault_params()
Description: Return default params

Method delete: mixeddelete(stringapi_method, void|ParamsArgparams, void|Callbackcb, mixed ... rest)
Description: Invokes a call with a DELETE method
Parameter api_method: The remote API method to call
Parameter params
Parameter cb: Callback function to get into in async mode

Method get: mixedget(stringapi_method, void|ParamsArgparams, void|Callbackcb, mixed ... rest)
Description: Invokes a call with a GET method
Parameter api_method: The remote API method to call
Parameter params
Parameter cb: Callback function to get into in async mode

Method get_encoding: protectedstringget_encoding(mappingh)
Description: Returns the encoding from a response
Parameter h: The headers mapping from a HTTP respose

Method get_uri: protectedstringget_uri(stringmethod)
Description: Convenience method for getting the URI to a specific API method
Parameter method

Method make_multipart_message

protectedarray(string) make_multipart_message(mappingp, stringbody)

Description

Creates the body of an Upload request

Parameter p

The API request parameters

Parameter body

Data of the document to upload

Returns

An array with two indices:

The value for the main Content-Type header
The request body

Method parse_canonical_url

mapping(string:string|mapping) parse_canonical_url(stringurl)

Description

This can be used to parse a link resource returned from a REST api. Many API returns stuff like:

{
  ...
  "pagination":{"next":"/api/v1/method/path?some=variables&page=2&per_page=20"}}

If pagination->next is passed to this method it will return a path of /method/path, given that the base URI of the web api is something along the line of https://some.url/api/v1, and a mapping containing the query variables (which can be passed as a parameter to any of the get, post, delete, put methods.

Parameter url

Returns

"path" : string

"params" : mapping

Method patch: mixedpatch(stringapi_method, void|ParamsArgparams, void|Callbackcb, mixed ... rest)
Description: Invokes a call with a PATCH method
Parameter api_method: The remote API method to call
Parameter params
Parameter cb: Callback function to get into in async mode

Method post: mixedpost(stringapi_method, void|ParamsArgparams, void|stringdata, void|Callbackcb, mixed ... rest)
Description: Invokes a call with a POST method
Parameter api_method: The remote API method to call
Parameter params
Parameter data: Eventual inline data to send
Parameter cb: Callback function to get into in async mode

Method put: mixedput(stringapi_method, void|ParamsArgparams, void|Callbackcb, mixed ... rest)
Description: Invokes a call with a PUT method
Parameter api_method: The remote API method to call
Parameter params
Parameter cb: Callback function to get into in async mode

Method unescape_forward_slashes: protectedstringunescape_forward_slashes(strings)
Description: Unescapes escaped forward slashes in a JSON string

Class Web.Api.Api.Method

Description: Internal class meant to be inherited by implementing Api's classes that corresponds to a given API endpoint.

Constant METHOD_PATH

protected constantint Web.Api.Api.Method.METHOD_PATH

Description

API method location within the API

https://api.instagram.com/v1/media/search
............................^^^^^^^

Method _delete: protectedmixed_delete(strings, void|ParamsArgp, void|Callbackcb)
Description: Internal convenience method

Method _get: protectedmixed_get(strings, void|ParamsArgp, void|Callbackcb)
Description: Internal convenience method

Method _patch: protectedmixed_patch(strings, void|ParamsArgp, void|Callbackcb)
Description: Internal convenience method

Method _post: protectedmixed_post(strings, void|ParamsArgp, void|stringdata, void|Callbackcb)
Description: Internal convenience method

Method _put: protectedmixed_put(strings, void|ParamsArgp, void|Callbackcb)
Description: Internal convenience method

Method create: Web.Api.Api.MethodWeb.Api.Api.Method()
Description: Hidden constructor. This class can not be instantiated directly

Module Web.Api.Facebook

Method `(): protectedthis_program`()(stringclient_id, stringclient_secret, void|stringredirect_uri, void|string|array(string)|multiset(string) scope)
Description: Instantiates the default Facebook API. See Web.Api.Api() for further information.
Parameter client_id: Your application key/id
Parameter client_secret: Your application secret
Parameter redirect_uri: The redirect URI after an authentication
Parameter scope: The application scopes to grant access to

Class Web.Api.Facebook.Graph

Inherit parent: inherit Web.Api.Api : parent

Constant API_URI: constantstring Web.Api.Facebook.Graph.API_URI
Description: The base uri to the Graph API

Variable any: Any Web.Api.Facebook.Graph.any
Description: Getter for the Any object which is a generic object for making request to the Facebook Graph API
See also: Any
Note: Read only

Method delete: mappingdelete(stringpath, void|ParamsArgparams, void|Callbackcb)
Description: Make a generic DELETE request to the Facebook Graph API.
Parameter path: What to request. Like me, me/pictures, [some_id]/something.
Parameter params
Parameter cb: Callback for async requests

Method get: mappingget(stringpath, void|ParamsArgparams, void|Callbackcb)
Description: Make a generic GET request to the Facebook Graph API.
Parameter path: What to request. Like me, me/pictures, [some_id]/something.
Parameter params
Parameter cb: Callback for async requests

Method post: mappingpost(stringpath, void|ParamsArgparams, void|stringdata, void|Callbackcb)
Description: Make a generic POST request to the Facebook Graph API.
Parameter path: What to request. Like me, me/pictures, [some_id]/something.
Parameter params
Parameter data
Parameter cb: Callback for async requests

Method put: mappingput(stringpath, void|ParamsArgparams, void|Callbackcb)
Description: Make a generic PUT request to the Facebook Graph API.
Parameter path: What to request. Like me, me/pictures, [some_id]/something.
Parameter params
Parameter cb: Callback for async requests

Class Web.Api.Facebook.Graph.Any

Description: A generic wrapper around Method

Inherit Method: inherit Method : Method

Class Web.Api.Facebook.Graph.Method

Inherit Method: inherit Web.Api.Api.Method : Method

Method delete: mixeddelete(strings, void|ParamsArgp, void|Callbackcb)
Description: Internal convenience method

Method get: mixedget(strings, void|ParamsArgp, void|Callbackcb)
Description: Internal convenience method

Method post: mixedpost(strings, void|ParamsArgp, void|stringdata, void|Callbackcb)
Description: Internal convenience method

Method put: mixedput(strings, void|ParamsArgp, void|Callbackcb)
Description: Internal convenience method

Module Web.Api.Github

Method `(): protectedthis_program`()(stringclient_id, stringclient_secret, void|stringredirect_uri, void|string|array(string)|multiset(string) scope)
Description: Instantiates the default Github API. See Web.Api.Api() for further information.
Parameter client_id: Your application key/id
Parameter client_secret: Your application secret
Parameter redirect_uri: The redirect URI after an authentication
Parameter scope: The application scopes to grant access to

Class Web.Api.Github.Github

Inherit parent: inherit Web.Api.Api : parent

Constant API_URI: constantstring Web.Api.Github.Github.API_URI
Description: The base uri to the Github API

Variable any: Any Web.Api.Github.Github.any
Description: Getter for the Any object which is a generic object for making request to the Github API
See also: Any
Note: Read only

Method delete: mappingdelete(stringpath, void|ParamsArgparams, void|Callbackcb)
Description: Make a generic DELETE request to the Github API.
Parameter path: What to request. Like me, me/pictures, [some_id]/something.
Parameter params
Parameter cb: Callback for async requests

Method get: mappingget(stringpath, void|ParamsArgparams, void|Callbackcb)
Description: Make a generic GET request to the Github API.
Parameter path: What to request. Like me, me/pictures, [some_id]/something.
Parameter params
Parameter cb: Callback for async requests

Method post: mappingpost(stringpath, void|ParamsArgparams, void|stringdata, void|Callbackcb)
Description: Make a generic POST request to the Github API.
Parameter path: What to request. Like me, me/pictures, [some_id]/something.
Parameter params
Parameter data
Parameter cb: Callback for async requests

Method put: mappingput(stringpath, void|ParamsArgparams, void|Callbackcb)
Description: Make a generic PUT request to the Github API.
Parameter path: What to request. Like me, me/pictures, [some_id]/something.
Parameter params
Parameter cb: Callback for async requests

Class Web.Api.Github.Github.Any

Description: A generic wrapper around Method

Inherit Method: inherit Method : Method

Class Web.Api.Github.Github.Method

Inherit Method: inherit Web.Api.Api.Method : Method

Method delete: mixeddelete(strings, void|ParamsArgp, void|Callbackcb)
Description: Internal convenience method

Method get: mixedget(strings, void|ParamsArgp, void|Callbackcb)
Description: Internal convenience method

Method post: mixedpost(strings, void|ParamsArgp, void|stringdata, void|Callbackcb)
Description: Internal convenience method

Method put: mixedput(strings, void|ParamsArgp, void|Callbackcb)
Description: Internal convenience method

Module Web.Api.Google

Method discover

Description

Get a Google API object

Example

This example shows how you can use the Google API
   to find out all the compute zones that exist at Google Compute Engine.
#define SECRET_FILE     "googleserviceaccount.json"#define PROJECT         "somegoogleproject"#define TOKENTIME       3600

string jwt_secret =Stdio.File(SECRET_FILE,"r").read();Web.Api.Google.Base api =Web.Api.Google.discover("compute","v1");void authenticated(){if(!api->auth->is_authenticated()
   || api->auth->expires->unix_time()- time(1)< TOKENTIME / 2)
    api->auth->get_token_from_jwt(jwt_secret);};

authenticated();mixed allzones = api->resrc->zones->list((["project":PROJECT ]));

Class Web.Api.Google.Api

Description: Internal class meant to be inherited by other Google API's

Inherit parent: inherit Web.Api.Api : parent

Class Web.Api.Google.Api.Method

Inherit Method: inherit Web.Api.Api.Method : Method

Method _delete: protectedmixed_delete(strings, void|ParamsArgp, void|Callbackcb)
Description: Internal convenience method

Method _get: protectedmixed_get(strings, void|ParamsArgp, void|Callbackcb)
Description: Internal convenience method

Method _post: protectedmixed_post(strings, void|ParamsArgp, void|Callbackcb)
Description: Internal convenience method

Class Web.Api.Google.Base

Inherit parent: inherit Api : parent

Variable resrc: resource Web.Api.Google.Base.resrc
Note: Read only

Variable valid_scopes: array(string) Web.Api.Google.Base.valid_scopes
Note: Read only

Method create: Web.Api.Google.BaseWeb.Api.Google.Base(mappingdiscovered, mixed ... rest)

Method set_scope: voidset_scope(stringscope)

Class Web.Api.Google.Discovery

Inherit parent: inherit Api : parent

Constant API_URI: protected constantstring Web.Api.Google.Discovery.API_URI
Description: API base URI.

Variable _apis: protectedApis Web.Api.Google.Discovery._apis
Description: Internal singleton objects. Retrieve an apis via apis.

Variable apis: Apis Web.Api.Google.Discovery.apis
Description: Getter for the Apis API
Note: Read only

Class Web.Api.Google.Discovery.Apis

Description: Interface to the Google Discovery Service API

Inherit Method: inherit Method : Method

Method getRest: mixedgetRest(mappingparams, void|Callbackcb)
Description: Retrieve the description of a particular version of an API
Parameter params
Parameter cb

Method list: mixedlist(void|mappingparams, void|Callbackcb)
Description: Retrieve the list of APIs supported at this endpoint
Parameter params
Parameter cb

Module Web.Api.Google.Analytics

Method `(): protectedthis_program`()(stringclient_id, stringclient_secret, void|stringredirect_uri, void|string|array(string)|multiset(string) scope)
Description: Instantiates the default Analytics API. See Web.Api.Api() for further information.
Parameter client_id: Your application key/id
Parameter client_secret: Your application secret
Parameter redirect_uri: The redirect URI after an authentication
Parameter scope: The application scopes to grant access to

Class Web.Api.Google.Analytics.V3

Inherit parent: inherit Web.Api.Google.Api : parent

Constant API_URI: protected constantstring Web.Api.Google.Analytics.V3.API_URI
Description: API base URI.

Variable _core
Variable _realtime
Variable _management: protectedCore Web.Api.Google.Analytics.V3._core
protectedRealTime Web.Api.Google.Analytics.V3._realtime
protectedManagement Web.Api.Google.Analytics.V3._management
Description: Internal singleton objects. Retrieve an instance via core, realtime and management.

Variable core: Core Web.Api.Google.Analytics.V3.core
Description: Getter for the Core API
Note: Read only

Variable management: Management Web.Api.Google.Analytics.V3.management
Description: Getter for the Management API
Note: Read only

Variable realtime: RealTime Web.Api.Google.Analytics.V3.realtime
Description: Getter for the RealTime API
Note: Read only

Class Web.Api.Google.Analytics.V3.Core

Description: Interface to the Google Analytics core API

Inherit Method: inherit Method : Method

Method get: mixedget(mappingparams, void|Callbackcb)
Description: Get data from the core api
Parameter params
Parameter cb

Class Web.Api.Google.Analytics.V3.Management

Description: Interface to the Google Analytics managment API

Inherit Method: inherit Method : Method

Method account_summaries: mixedaccount_summaries(void|ParamsArgparams, void|Callbackcb)
Description: Get account summaries
Parameter params
Parameter cb

Class Web.Api.Google.Analytics.V3.RealTime

Description: Interface to the Google Analytics realtime API

Inherit Method: inherit Method : Method

Method get: mixedget(mappingparams, void|Callbackcb)
Description: Get data from the realtime api
Parameter params
Parameter cb

Module Web.Api.Google.Plus

Method `(): protectedthis_program`()(stringclient_id, stringclient_secret, void|stringredirect_uri, void|string|array(string)|multiset(string) scope)
Description: Instantiates the default Google+ API. See Web.Api.Api() for further information.
Parameter client_id: Your application key/id
Parameter client_secret: Your application secret
Parameter redirect_uri: The redirect URI after an authentication
Parameter scope: The application scopes to grant access to

Class Web.Api.Google.Plus.V1

Inherit Api: inherit Web.Api.Google.Api : Api

Constant API_URI: protected constantstring Web.Api.Google.Plus.V1.API_URI
Description: API base URI.

Variable _people
Variable _activities: privatePeople Web.Api.Google.Plus.V1._people
privateActivities Web.Api.Google.Plus.V1._activities
Description: Internal singleton objects. Get an instance via people and activities.

Variable activities: Activities Web.Api.Google.Plus.V1.activities
Description: Getter for the Activities object which has methods for all activities related Google+ API methods.
See also: https://developers.google.com/+/api/latest/activities
Note: Read only

Variable people: People Web.Api.Google.Plus.V1.people
Description: Getter for the People object which has methods for all people related Google+ API methods.
See also: https://developers.google.com/+/api/latest/people
Note: Read only

Class Web.Api.Google.Plus.V1.Activities

Description

Class implementing the Google+ Activities API. https://developers.google.com/+/api/latest/activities

Retreive an instance of this class through the activities property

Inherit Method: inherit Method : Method

Class Web.Api.Google.Plus.V1.People

Description

Class implementing the Google+ People API. https://developers.google.com/+/api/latest/people

Retreive an instance of this class through the Social.Google.Plus()->people property

Inherit Method: inherit Method : Method

Method get: mappingget(void|stringuser_id, void|Callbackcb)
Description: Get info ablut a person.
Parameter user_id: If empty the currently authenticated user will be fetched.
Parameter cb: Callback for async request

Method list

mappinglist(void|stringuser_id, void|stringcollection, void|ParamsArgparams, void|Callbackcb)

Description

List all of the people in the specified collection.

Parameter user_id

If empty the currently authenticated user will be used.

Parameter collection

If empty "public" activities will be listed. Acceptable values are:

"public"
The list of people who this user has added to one or more circles, limited to the circles visible to the requesting application.

Parameter params

"maxResult" : int

Max number of items ti list

"orderBy" : string

The order to return people in. Acceptable values are:

"alphabetical"
Order the people by their display name.
"best"
Order people based on the relevence to the viewer.

"pageToken" : string

The continuation token, which is used to page through large result sets. To get the next page of results, set this parameter to the value of nextPageToken from the previous response.

Parameter cb

Callback for async request

Module Web.Api.Instagram

Description: Instagram API implementation. https://instagram.com/developer/

Method `(): protectedthis_program`()(stringclient_id, stringclient_secret, void|stringredirect_uri, void|string|array(string)|multiset(string) scope)
Description: Instantiates the default Instagram API. See Web.Api.Api() for further information.
Parameter client_id: Your application key/id
Parameter client_secret: Your application secret
Parameter redirect_uri: The redirect URI after an authentication
Parameter scope: The application scopes to grant access to

Class Web.Api.Instagram.V1

Description: Class for communicating with version 1 of the Instagram API.

Inherit parent: inherit Web.Api.Api : parent

Constant API_URI: protected constantstring Web.Api.Instagram.V1.API_URI
Description: The URI to the Instagram API

Variable _any: privateAny Web.Api.Instagram.V1._any
Description: Singleton Any object. Will be instantiated first time requested.

Variable _comments: privateComments Web.Api.Instagram.V1._comments
Description: Singleton Comments object. Will be instantiated first time requested.

Variable _likes: privateLikes Web.Api.Instagram.V1._likes
Description: Singleton Likes object. Will be instantiated first time requested.

Variable _locations: privateLocations Web.Api.Instagram.V1._locations
Description: Singleton Locations object. Will be instantiated first time requested.

Variable _media: privateMedia Web.Api.Instagram.V1._media
Description: Singleton Media object. Will be instantiated first time requested.

Variable _tags: privateTags Web.Api.Instagram.V1._tags
Description: Singleton Tags object. Will be instantiated first time requested.

Variable _users: privateUsers Web.Api.Instagram.V1._users
Description: Singleton User object. Will be instantiated first time requested.

Variable any: Any Web.Api.Instagram.V1.any
Description: Getter for the Any object which can be used to query any method in the Instagram web api. The METHOD_PATH is set to / in this object.
Note: Read only

Variable comments: Comments Web.Api.Instagram.V1.comments
Description: Getter for the Comments object which has methods for all comments related Instagram API methods.
See also: http://instagram.com/developer/endpoints/comments/
Note: Read only

Variable likes: Likes Web.Api.Instagram.V1.likes
Description: Getter for the Likes object which has methods for all likes related Instagram API methods.
See also: http://instagram.com/developer/endpoints/likes/
Note: Read only

Variable locations: Locations Web.Api.Instagram.V1.locations
Description: Getter for the Locations object which has methods for all locations related Instagram API methods.
See also: http://instagram.com/developer/endpoints/locations/
Note: Read only

Variable media: Media Web.Api.Instagram.V1.media
Description: Getter for the Media object which has methods for all media related Instagram API methods.
See also: http://instagram.com/developer/endpoints/media/
Note: Read only

Variable tags: Tags Web.Api.Instagram.V1.tags
Description: Getter for the Tags object which has methods for all tags related Instagram API methods.
See also: http://instagram.com/developer/endpoints/tags/
Note: Read only

Variable users: Users Web.Api.Instagram.V1.users
Description: Getter for the Users object which has methods for all users related Instagram API methods.
See also: http://instagram.com/developer/endpoints/users/
Note: Read only

Method delete: mappingdelete(stringpath, void|ParamsArgparams, void|Callbackcb)
Description: Make a generic DELETE request to the Instagram API.
Parameter path: What to request. Like me, users/self, [some_id]/something.
Parameter params
Parameter cb: Callback for async requests

Method get: mappingget(stringpath, void|ParamsArgparams, void|Callbackcb)
Description: Make a generic GET request to the Instagram API.
Parameter path: What to request. Like me, users/self, [some_id]/something.
Parameter params
Parameter cb: Callback for async requests

Method post: mappingpost(stringpath, void|ParamsArgparams, string|zerodata, void|Callbackcb)
Description: Make a generic POST request to the Instagram API.
Parameter path: What to request. Like me, users/self, [some_id]/something.
Parameter params
Parameter data: Ignored.
Parameter cb: Callback for async requests

Method put: mappingput(stringpath, void|ParamsArgparams, void|Callbackcb)
Description: Make a generic PUT request to the Instagram API.
Parameter path: What to request. Like me, users/self, [some_id]/something.
Parameter params
Parameter cb: Callback for async requests

Class Web.Api.Instagram.V1.Any

Description: A generic wrapper around Method. This will query the root of the API, and can be used to query methods not implemented in this module.

Inherit Method: inherit Method : Method

Method delete: mixeddelete(strings, void|ParamsArgp, void|Callbackcb)
Description: DELETE data
Parameter s: The path to the Instagram API to query
Parameter p: Parameters to the query
Parameter cb: Async callback

Method get: mixedget(strings, void|ParamsArgp, void|Callbackcb)
Description: GET data
Parameter s: The path to the Instagram API to query
Parameter p: Parameters to the query
Parameter cb: Async callback

Method post: mixedpost(strings, void|ParamsArgp, string|zerodata, void|Callbackcb)
Description: POST data
Parameter s: The path to the Instagram API to query
Parameter p: Parameters to the query
Parameter cb: Async callback

Method put: mixedput(strings, void|ParamsArgp, void|Callbackcb)
Description: PUT data
Parameter s: The path to the Instagram API to query
Parameter p: Parameters to the query
Parameter cb: Async callback

Class Web.Api.Instagram.V1.Comments

Description

Class implementing the Instagram Comments API. http://instagram.com/developer/endpoints/comments/

Retreive an instance of this class via the comments property.

Inherit Method: inherit Method : Method

Method add: mappingadd(stringmedia_id, stringcomment, void|Callbackcb)
Description: Get a full list of comments on a media.
Note: This method is not allowed by default. You have to contact Instagram in order to activate this method. http://bit.ly/instacomments
Note: Required scope: comments
Parameter media_id: The media to retreive comments for
Parameter cb: Callback for async mode

Method list: mappinglist(stringmedia_id, void|Callbackcb)
Description: Get a full list of comments on a media.
Note: Required scope: comments
Parameter media_id: The media to retreive comments for
Parameter cb: Callback for async mode

Method remove: mappingremove(stringmedia_id, stringcomment_id, void|Callbackcb)
Description: Remove a comment either on the authenticated user's media or authored by the authenticated user.
Note: Required scope: comments
Parameter media_id: The media the comment is for
Parameter comment_id: The comment to remove
Parameter cb: Callback for async mode

Class Web.Api.Instagram.V1.Likes

Description

Class implementing the Instagram Likes API. http://instagram.com/developer/endpoints/likes/

Retreive an instance of this class via the likes property.

Inherit Method: inherit Method : Method

Method add: mappingadd(stringmedia_id, void|Callbackcb)
Description: Set a like on this media by the currently authenticated user.
See also: http://instagram.com/developer/endpoints/likes/#post_likes
Note: Required scope: likes
Parameter media_id
Parameter cb

Method list: mappinglist(stringmedia_id, void|Callbackcb)
Description: Get a list of users who have liked this media.
See also: http://instagram.com/developer/endpoints/likes/#get_media_likes
Note: Required scope: likes
Parameter media_id
Parameter cb

Method remove: mappingremove(stringmedia_id, void|Callbackcb)
Description: Remove a like on this media by the currently authenticated user.
See also: http://instagram.com/developer/endpoints/likes/#delete_likes
Note: Required scope: likes
Parameter media_id
Parameter cb

Class Web.Api.Instagram.V1.Locations

Description

Class implementing the Instagram Likes API. http://instagram.com/developer/endpoints/likes/

Retreive an instance of this class via the locations property.

Inherit Method: inherit Method : Method

Method location: mappinglocation(stringlocation_id, void|Callbackcb)
Description: Get information about a location.
See also: http://instagram.com/developer/endpoints/locations/#get_locations
Parameter location_id
Parameter cb

Method recent_media

mappingrecent_media(stringlocation_id, void|ParamsArgparams, void|Callbackcb)

Description

Get a list of recent media objects from a given location. May return a mix of both image and video types.

Parameter location_id

Parameter params

`"min_timestamp" : int`	Return media after this UNIX timestamp
`"min_id" : string`	Return media before this min_id.
`"max_id" : string`	Return media after this max_id.
`"max_timestamp" : int`	Return media before this UNIX timestamp

Parameter cb

Method search

mappingsearch(ParamsArgparams, void|Callbackcb)

Description

Search for a location by geographic coordinate.

Parameter params

`"lat" : float`	Latitude of the center search coordinate. If used, lng is required.
`"distance" : int`	Default is 1000m (distance=1000), max distance is 5000.
`"lng" : float`	Longitude of the center search coordinate. If used, lat is required.
`"foursquare_v2_id" : string\|int`	Returns a location mapped off of a foursquare v2 api location id. If used, you are not required to use lat and lng.
`"foursquare_id" : string\|int`	Returns a location mapped off of a foursquare v1 api location id. If used, you are not required to use lat and lng. Note that this method is deprecated; you should use the new foursquare IDs with V2 of their API.

Parameter cb

Class Web.Api.Instagram.V1.Media

Description

Class implementing the Instagram Media API. http://instagram.com/developer/endpoints/media/

Retreive an instance of this class via the media property

Inherit Method: inherit Method : Method

Method item: mappingitem(stringmedia_id, void|Callbackcb)
Description: Get information about a media object. The returned type key will allow you to differentiate between image and video media. Note: if you authenticate with an OAuth Token, you will receive the user_has_liked key which quickly tells you whether the current user has liked this media item.
See also: http://instagram.com/developer/endpoints/media/#get_media
Parameter media_id
Parameter cb: Callback function when in async mode

Method popular: mappingpopular(void|Callbackcb)
Description: Get a list of what media is most popular at the moment. Can return a mix of image and video types.
Parameter cb: Callback function when in async mode

Method search

mappingsearch(void|ParamsArgparams, void|Callbackcb)

Description

Search for media in a given area. The default time span is set to 5 days. The time span must not exceed 7 days. Defaults time stamps cover the last 5 days. Can return mix of image and video types.

Parameter params

Can have:

`"lat" : string\|float`	Latitude of the center search coordinate. If used, lng is required.
`"min_timestamp" : int`	A unix timestamp. All media returned will be taken later than this timestamp.
`"lng" : string\|float`	Longitude of the center search coordinate. If used, lat is required.
`"max_timestamp" : int`	A unix timestamp. All media returned will be taken earlier than this timestamp.
`"distance" : int`	Default is 1km (distance=1000), max distance is 5km.

Parameter cb

Callback function when in async mode

Class Web.Api.Instagram.V1.Method

Description: Internal convenience class.

Inherit Method: inherit Web.Api.Api.Method : Method

Method _delete: protectedmixed_delete(strings, void|ParamsArgp, void|Callbackcb)
Description: Internal convenience method

Method _get: protectedmixed_get(strings, void|ParamsArgp, void|Callbackcb)
Description: Internal convenience method

Method _post: protectedmixed_post(strings, void|ParamsArgp, string|zerodata, void|Callbackcb)
Description: Internal convenience method

Method _put: protectedmixed_put(strings, void|ParamsArgp, void|Callbackcb)
Description: Internal convenience method

Class Web.Api.Instagram.V1.Tags

Description

Class implementing the Instagram Tags API. http://instagram.com/developer/endpoints/tags/

Retreive an instance of this class via the tags property.

Inherit Method: inherit Method : Method

Method recent

mappingrecent(stringtag_name, void|ParamsArgparams, void|Callbackcb)

Description

Get a list of recently tagged media. Note that this media is ordered by when the media was tagged with this tag, rather than the order it was posted. Use the max_tag_id and min_tag_id parameters in the pagination response to paginate through these objects. Can return a mix of image and video types.

Parameter tag_name

Parameter params

Can be:

`"min_id" : string`	Return media before this min_id.
`"max_id" : string`	Return media after this max_id.

Parameter cb

Callback function when in async mode

Method search: mappingsearch(stringtag_name, Callbackcb)
Description: Search for tags by name. Results are ordered first as an exact match, then by popularity. Short tags will be treated as exact matches.
See also: http://instagram.com/developer/endpoints/tags/#get_tags_search
Parameter tag_name
Parameter cb: Callback function when in async mode

Method tag: mappingtag(stringtag_name, void|Callbackcb)
Description: Get information about a tag object.
See also: http://instagram.com/developer/endpoints/tags/#get_tags
Parameter tag_name
Parameter cb: Callback function when in async mode

Class Web.Api.Instagram.V1.Users

Description

Class implementing the Instagram Users API. http://instagram.com/developer/endpoints/users/

Retreive an instance of this class via the users property

Inherit Method: inherit Method : Method

Method feed

mappingfeed(void|ParamsArgparams, void|Callbackcb)

Description

Get the currently authenticated users feed. http://instagram.com/developer/endpoints/users/#get_users

Parameter params

Valida parameters are:

`"count" : string\|int`	Number of items to return. Default is 20.
`"min_id" : string`	Return media later than this min_id
`"max_id" : string`	Return media earlier than this max_id

Parameter cb

Callback function when in async mode

Method followed_by: mappingfollowed_by(string|voiduser_id, void|Callbackcb)
Description: Get the list of users this user is followed by.
Note: Required scope: relationships
See also: http://instagram.com/developer/endpoints/relationships/#get_users_followed_by
Parameter user_id
Parameter cb: Callback function when in async mode

Method follows: mappingfollows(void|stringuser_id, void|Callbackcb)
Description: Get the list of users this user follows.
Note: Required scope: relationships
See also: http://instagram.com/developer/endpoints/relationships/#get_users_follows
Parameter user_id
Parameter cb: Callback function when in async mode

Method liked

mappingliked(void|ParamsArgparams, void|Callbackcb)

Description

See the authenticated user's list of media they've liked. May return a mix of both image and video types. Note: This list is ordered by the order in which the user liked the media. Private media is returned as long as the authenticated user has permission to view that media. Liked media lists are only available for the currently authenticated user.

http://instagram.com/developer/endpoints/users/#get_users_feed_liked

Parameter params

Valida parameters are:

`"count" : string\|int`	Number of items to return. Default is 20.
`"max_like_id" : string`	Return media liked before this id.

Parameter cb

Callback function when in async mode

Method recent

mappingrecent(void|stringuid, void|ParamsArgparams, void|Callbackcb)

Description

Get the most recent media published by a user. May return a mix of both image and video types. http://instagram.com/developer/endpoints/users/get_users_media_recent

Parameter uid

An Instagram user ID

Parameter params

Valida parameters are:

`"count" : string\|int`	Number of items to return. Default is 20.
`"min_id" : string`	Return media later than this min_id
`"max_id" : string`	Return media earlier than this max_id
`"max_timestamp" : int`	Return media before this UNIX timestamp.
`"min_timestamp" : int`	Return media after this UNIX timestamp.

Parameter cb

Callback function when in async mode

Method relationship: mappingrelationship(stringuser_id, void|Callbackcb)
Description: Get information about a relationship to another user.
Note: Required scope: relationships
See also: http://instagram.com/developer/endpoints/relationships/#get_relationship
Parameter user_id
Parameter cb: Callback function when in async mode

Method relationship_change

mappingrelationship_change(stringuser_id, stringaction, void|Callbackcb)

Description

Modify the relationship between the current user and the target user.

Note

Required scope: relationships

Parameter user_id

The user to change the relationship to

Parameter action

How to change the relationship. Can be:

"follow"
"unfollow"
"block"
"unblock"
"approve"
"deny"

Parameter cb

Callback function if in async mode

Method requested_by: mappingrequested_by(void|Callbackcb)
Description: List the users who have requested this user's permission to follow.
Note: Required scope: relationships
See also: http://instagram.com/developer/endpoints/relationships/#get_incoming_requests
Parameter cb: Callback function when in async mode

Method search

mappingsearch(stringquery, void|intcount, void|Callbackcb)

Description

Search for a user by name.

http://instagram.com/developer/endpoints/users/#get_users_search

Parameter query

A query string.

Parameter count

Max number of users to return

Parameter cb

Callback function when in async mode

Method user: mappinguser(void|stringuid, void|Callbackcb)
Description: Get basic information about a user.
Parameter uid: An Instagram user ID. If not given the currently authenticated user will be fetched
Parameter cb: Callback function when in async mode

Module Web.Api.Linkedin

Method `(): protectedthis_program`()(stringclient_id, stringclient_secret, void|stringredirect_uri, void|string|array(string)|multiset(string) scope)
Description: Instantiates the default Github API. See Web.Api.Api() for further information about the arguments
Parameter client_id: Your application key/id
Parameter client_secret: Your application secret
Parameter redirect_uri: The redirect URI after an authentication
Parameter scope: The application scopes to grant access to

Class Web.Api.Linkedin.V1

Inherit parent: inherit Web.Api.Api : parent

Constant API_URI: constantstring Web.Api.Linkedin.V1.API_URI
Description: The base uri to the API

Variable any: Any Web.Api.Linkedin.V1.any
Description: Getter for the Any object which is a generic object for making request to the Linkedin API
See also: Any
Note: Read only

Method default_params: protectedmappingdefault_params()
Description: Default parameters that goes with every call

Method delete: mappingdelete(stringpath, void|ParamsArgparams, void|Callbackcb)
Description: Make a generic DELETE request to the Linkedin API.
Parameter path: What to request. Like me, me/pictures, [some_id]/something.
Parameter params
Parameter cb: Callback for async requests

Method get: mappingget(stringpath, void|ParamsArgparams, void|Callbackcb)
Description: Make a generic GET request to the Linkedin API.
Parameter path: What to request. Like me, me/pictures, [some_id]/something.
Parameter params
Parameter cb: Callback for async requests

Method post: mappingpost(stringpath, void|ParamsArgparams, void|stringdata, void|Callbackcb)
Description: Make a generic POST request to the Linkedin API.
Parameter path: What to request. Like me, me/pictures, [some_id]/something.
Parameter params
Parameter data
Parameter cb: Callback for async requests

Method put: mappingput(stringpath, void|ParamsArgparams, void|Callbackcb)
Description: Make a generic PUT request to the Linkedin API.
Parameter path: What to request. Like me, me/pictures, [some_id]/something.
Parameter params
Parameter cb: Callback for async requests

Class Web.Api.Linkedin.V1.Any

Description: A generic wrapper around Method

Inherit Method: inherit Method : Method

Class Web.Api.Linkedin.V1.Method

Inherit Method: inherit Web.Api.Api.Method : Method

Method delete: mixeddelete(strings, void|ParamsArgp, void|Callbackcb)
Description: Internal convenience method

Method get: mixedget(strings, void|ParamsArgp, void|Callbackcb)
Description: Internal convenience method

Method post: mixedpost(strings, void|ParamsArgp, void|stringdata, void|Callbackcb)
Description: Internal convenience method

Method put: mixedput(strings, void|ParamsArgp, void|Callbackcb)
Description: Internal convenience method

Module Web.Api.Twitter

Method `(): protectedthis_program`()(stringclient_id, stringclient_secret, void|stringredirect_uri, void|string|array(string)|multiset(string) scope)
Description: Instantiates the default Twitter API. See https://dev.twitter.com/rest/public for further information.
Parameter client_id: Your application key/id
Parameter client_secret: Your application secret
Parameter redirect_uri: The redirect URI after an authentication
Parameter scope: The application scopes to grant access to
See also: Web.Api.Api

Class Web.Api.Twitter.V1_1

Inherit parent: inherit Web.Api.Api : parent

Variable any: Any Web.Api.Twitter.V1_1.any
Description: Getter for the Any object which is a generic object for making request to the Twitter API
See also: Any
Note: Read only

Method default_params: protectedmappingdefault_params()
Description: Default parameters that goes with every call

Method delete: mappingdelete(stringpath, void|ParamsArgparams, void|Callbackcb)
Description: Make a generic DELETE request to the Twitter API.
Parameter path: What to request. Like me, me/pictures, [some_id]/something.
Parameter params
Parameter cb: Callback for async requests

Method get: mappingget(stringpath, void|ParamsArgparams, void|Callbackcb)
Description: Make a generic GET request to the Twitter API.
Parameter path: What to request. Like me, me/pictures, [some_id]/something.
Parameter params
Parameter cb: Callback for async requests

Method post: mappingpost(stringpath, void|ParamsArgparams, void|stringdata, void|Callbackcb)
Description: Make a generic POST request to the Twitter API.
Parameter path: What to request. Like me, me/pictures, [some_id]/something.
Parameter params
Parameter data
Parameter cb: Callback for async requests

Method put: mappingput(stringpath, void|ParamsArgparams, void|Callbackcb)
Description: Make a generic PUT request to the Twitter API.
Parameter path: What to request. Like me, me/pictures, [some_id]/something.
Parameter params
Parameter cb: Callback for async requests

Class Web.Api.Twitter.V1_1.Any

Description: A generic wrapper around Method

Inherit Method: inherit Method : Method

Class Web.Api.Twitter.V1_1.Method

Inherit Method: inherit Web.Api.Api.Method : Method

Method delete: mixeddelete(strings, void|ParamsArgp, void|Callbackcb)
Description: Internal convenience method

Method get: mixedget(strings, void|ParamsArgp, void|Callbackcb)
Description: Internal convenience method

Method post: mixedpost(strings, void|ParamsArgp, void|stringdata, void|Callbackcb)
Description: Internal convenience method

Method put: mixedput(strings, void|ParamsArgp, void|Callbackcb)
Description: Internal convenience method

Module Web.Auth

Description

Various authentication modules and classes.

constant GOOGLE_KEY ="some-key-911bnn5s.apps.googleusercontent.com";constant GOOGLE_SECRET ="5arQDOugDrtIOVklkIet2q2i";Web.Auth.Google.Authorization auth;int main(int argc,array(string) argv){
  auth =Web.Auth.Google.Authorization(GOOGLE_KEY, GOOGLE_SECRET,"http://localhost");// The generated access token will be saved on disk.string progname = replace(sprintf("%O", object_program(auth)),".","_");string cookie = progname +".cookie";// If the cookie exists, set the authentication from the saved valuesif(Stdio.exist(cookie)){
    auth->set_from_cookie(Stdio.read_file(cookie));}// Not authenticated, can mean no previous authentication is done, or that// the authentication has expired. Some services have persistent access tokens// some don'tif(!auth->is_authenticated()){// Try to renew the access token of it's renewableif(auth->is_renewable()){
      write("Trying to refresh token...\n");string data = auth->refresh_access_token();Stdio.write_file(cookie, data);}else{// No argument, start the authentication processif(argc == 1){// Get the uri to the authentication pagestring uri = auth->get_auth_uri();

        write("Opening \"%s\" in browser.\nCopy the contents of the address ""bar into here: ",Standards.URI(uri));

        sleep(1);string open_app;// Macif(Process.run(({"which","open"}))->exitcode == 0){
          open_app ="open";}// Linuxelseif(Process.run(({"which","xdg-open"}))->exitcode == 0){
          open_app ="xdg-open";}// ???else{
          open_app ="open";}Process.create_process(({ open_app, uri }));// Wait for the user to paste the string from the address barstring resp =Stdio.Readline()->read();mapping p =Web.Auth.query_to_mapping(Standards.URI(resp)->query);string code;// This is if the service is OAuth1if(p->oauth_token){
          auth->set_authentication(p->oauth_token);
          code = p->oauth_verifier;}// OAuth2else{
          code = p->code;}// Get the access token and save the response to disk for later use.string data = auth->request_access_token(code);Stdio.write_file(cookie, data);}// If the user gives the access code from command line.else{string data = auth->request_access_token(argv[1]);Stdio.write_file(cookie, data);}}}if(!auth->is_authenticated()){
    werror("Authentication failed");}else{
    write("Congratulations you are now authenticated\n");}}

Method query_to_mapping: mappingquery_to_mapping(stringquery)
Description: Turns a query string into a mapping
Parameter query

Class Web.Auth.Facebook

Description: This class is used to OAuth2 authenticate agains Facebook

Inherit Client: inherit .OAuth2.Client : Client

Enum Web.Auth.Facebook.Scopes

Constant SCOPE_EMAIL
Constant SCOPE_PUBLISH_ACTIONS
Constant SCOPE_ABOUT_ME
Constant SCOPE_ACTIONS_BOOKS
Constant SCOPE_ACTIONS_MUSIC
Constant SCOPE_ACTIONS_NEWS
Constant SCOPE_ACTIONS_VIDEO
Constant SCOPE_ACTIVITIES
Constant SCOPE_BIRTHDAY
Constant SCOPE_EDUCATION_HISTORY
Constant SCOPE_EVENTS
Constant SCOPE_FRIENDS
Constant SCOPE_GAMES_ACTIVITY
Constant SCOPE_GROUPS
Constant SCOPE_HOMETOWN
Constant SCOPE_INTERESTS
Constant SCOPE_LIKES
Constant SCOPE_LOCATION
Constant SCOPE_NOTES
Constant SCOPE_PHOTOS
Constant SCOPE_QUESTIONS
Constant SCOPE_RELATIONSHIP_DETAILS
Constant SCOPE_RELATIONSHIPS
Constant SCOPE_RELIGION_POLITICS
Constant SCOPE_STATUS
Constant SCOPE_SUBSCRIPTIONS
Constant SCOPE_VIDEOS
Constant SCOPE_WEBSITE
Constant SCOPE_WORK_HISTORY: constant Web.Auth.Facebook.SCOPE_EMAIL
constant Web.Auth.Facebook.SCOPE_PUBLISH_ACTIONS
constant Web.Auth.Facebook.SCOPE_ABOUT_ME
constant Web.Auth.Facebook.SCOPE_ACTIONS_BOOKS
constant Web.Auth.Facebook.SCOPE_ACTIONS_MUSIC
constant Web.Auth.Facebook.SCOPE_ACTIONS_NEWS
constant Web.Auth.Facebook.SCOPE_ACTIONS_VIDEO
constant Web.Auth.Facebook.SCOPE_ACTIVITIES
constant Web.Auth.Facebook.SCOPE_BIRTHDAY
constant Web.Auth.Facebook.SCOPE_EDUCATION_HISTORY
constant Web.Auth.Facebook.SCOPE_EVENTS
constant Web.Auth.Facebook.SCOPE_FRIENDS
constant Web.Auth.Facebook.SCOPE_GAMES_ACTIVITY
constant Web.Auth.Facebook.SCOPE_GROUPS
constant Web.Auth.Facebook.SCOPE_HOMETOWN
constant Web.Auth.Facebook.SCOPE_INTERESTS
constant Web.Auth.Facebook.SCOPE_LIKES
constant Web.Auth.Facebook.SCOPE_LOCATION
constant Web.Auth.Facebook.SCOPE_NOTES
constant Web.Auth.Facebook.SCOPE_PHOTOS
constant Web.Auth.Facebook.SCOPE_QUESTIONS
constant Web.Auth.Facebook.SCOPE_RELATIONSHIP_DETAILS
constant Web.Auth.Facebook.SCOPE_RELATIONSHIPS
constant Web.Auth.Facebook.SCOPE_RELIGION_POLITICS
constant Web.Auth.Facebook.SCOPE_STATUS
constant Web.Auth.Facebook.SCOPE_SUBSCRIPTIONS
constant Web.Auth.Facebook.SCOPE_VIDEOS
constant Web.Auth.Facebook.SCOPE_WEBSITE
constant Web.Auth.Facebook.SCOPE_WORK_HISTORY

Constant SCOPE_ADS_MANAGEMENT
Constant SCOPE_ADS_READ
Constant SCOPE_CREATE_EVENT
Constant SCOPE_CREATE_NOTE
Constant SCOPE_EXPORT_STREAM
Constant SCOPE_FRIENDS_ONLINE_PRESENCE
Constant SCOPE_MANAGE_FRIENDLISTS
Constant SCOPE_MANAGE_NOTIFICATIONS
Constant SCOPE_MANAGE_PAGES
Constant SCOPE_PHOTO_UPLOAD
Constant SCOPE_PUBLISH_STREAM
Constant SCOPE_READ_FRIENDLISTS
Constant SCOPE_READ_INSIGHTS
Constant SCOPE_READ_MAILBOX
Constant SCOPE_READ_PAGE_MAILBOXES
Constant SCOPE_READ_REQUESTS
Constant SCOPE_READ_STREAM
Constant SCOPE_RSVP_EVENT
Constant SCOPE_SHARE_ITEM
Constant SCOPE_SMS
Constant SCOPE_STATUS_UPDATE
Constant SCOPE_USER_ONLINE_PRESENCE
Constant SCOPE_VIDEO_UPLOAD
Constant SCOPE_XMPP_LOGIN: constant Web.Auth.Facebook.SCOPE_ADS_MANAGEMENT
constant Web.Auth.Facebook.SCOPE_ADS_READ
constant Web.Auth.Facebook.SCOPE_CREATE_EVENT
constant Web.Auth.Facebook.SCOPE_CREATE_NOTE
constant Web.Auth.Facebook.SCOPE_EXPORT_STREAM
constant Web.Auth.Facebook.SCOPE_FRIENDS_ONLINE_PRESENCE
constant Web.Auth.Facebook.SCOPE_MANAGE_FRIENDLISTS
constant Web.Auth.Facebook.SCOPE_MANAGE_NOTIFICATIONS
constant Web.Auth.Facebook.SCOPE_MANAGE_PAGES
constant Web.Auth.Facebook.SCOPE_PHOTO_UPLOAD
constant Web.Auth.Facebook.SCOPE_PUBLISH_STREAM
constant Web.Auth.Facebook.SCOPE_READ_FRIENDLISTS
constant Web.Auth.Facebook.SCOPE_READ_INSIGHTS
constant Web.Auth.Facebook.SCOPE_READ_MAILBOX
constant Web.Auth.Facebook.SCOPE_READ_PAGE_MAILBOXES
constant Web.Auth.Facebook.SCOPE_READ_REQUESTS
constant Web.Auth.Facebook.SCOPE_READ_STREAM
constant Web.Auth.Facebook.SCOPE_RSVP_EVENT
constant Web.Auth.Facebook.SCOPE_SHARE_ITEM
constant Web.Auth.Facebook.SCOPE_SMS
constant Web.Auth.Facebook.SCOPE_STATUS_UPDATE
constant Web.Auth.Facebook.SCOPE_USER_ONLINE_PRESENCE
constant Web.Auth.Facebook.SCOPE_VIDEO_UPLOAD
constant Web.Auth.Facebook.SCOPE_XMPP_LOGIN

Constant SCOPE_FRIENDS_ABOUT_ME
Constant SCOPE_FRIENDS_ACTIONS_BOOKS
Constant SCOPE_FRIENDS_ACTIONS_MUSIC
Constant SCOPE_FRIENDS_ACTIONS_NEWS
Constant SCOPE_FRIENDS_ACTIONS_VIDEO
Constant SCOPE_FRIENDS_ACTIVITIES
Constant SCOPE_FRIENDS_BIRTHDAY
Constant SCOPE_FRIENDS_EDUCATION_HISTORY
Constant SCOPE_FRIENDS_EVENTS
Constant SCOPE_FRIENDS_GAMES_ACTIVITY
Constant SCOPE_FRIENDS_GROUPS
Constant SCOPE_FRIENDS_HOMETOWN
Constant SCOPE_FRIENDS_INTERESTS
Constant SCOPE_FRIENDS_LIKES
Constant SCOPE_FRIENDS_LOCATION
Constant SCOPE_FRIENDS_NOTES
Constant SCOPE_FRIENDS_PHOTOS
Constant SCOPE_FRIENDS_QUESTIONS
Constant SCOPE_FRIENDS_RELATIONSHIP_DETAILS
Constant SCOPE_FRIENDS_RELATIONSHIPS
Constant SCOPE_FRIENDS_RELIGION_POLITICS
Constant SCOPE_FRIENDS_STATUS
Constant SCOPE_FRIENDS_SUBSCRIPTIONS
Constant SCOPE_FRIENDS_VIDEOS
Constant SCOPE_FRIENDS_WEBSITE
Constant SCOPE_FRIENDS_WORK_HISTORY: constant Web.Auth.Facebook.SCOPE_FRIENDS_ABOUT_ME
constant Web.Auth.Facebook.SCOPE_FRIENDS_ACTIONS_BOOKS
constant Web.Auth.Facebook.SCOPE_FRIENDS_ACTIONS_MUSIC
constant Web.Auth.Facebook.SCOPE_FRIENDS_ACTIONS_NEWS
constant Web.Auth.Facebook.SCOPE_FRIENDS_ACTIONS_VIDEO
constant Web.Auth.Facebook.SCOPE_FRIENDS_ACTIVITIES
constant Web.Auth.Facebook.SCOPE_FRIENDS_BIRTHDAY
constant Web.Auth.Facebook.SCOPE_FRIENDS_EDUCATION_HISTORY
constant Web.Auth.Facebook.SCOPE_FRIENDS_EVENTS
constant Web.Auth.Facebook.SCOPE_FRIENDS_GAMES_ACTIVITY
constant Web.Auth.Facebook.SCOPE_FRIENDS_GROUPS
constant Web.Auth.Facebook.SCOPE_FRIENDS_HOMETOWN
constant Web.Auth.Facebook.SCOPE_FRIENDS_INTERESTS
constant Web.Auth.Facebook.SCOPE_FRIENDS_LIKES
constant Web.Auth.Facebook.SCOPE_FRIENDS_LOCATION
constant Web.Auth.Facebook.SCOPE_FRIENDS_NOTES
constant Web.Auth.Facebook.SCOPE_FRIENDS_PHOTOS
constant Web.Auth.Facebook.SCOPE_FRIENDS_QUESTIONS
constant Web.Auth.Facebook.SCOPE_FRIENDS_RELATIONSHIP_DETAILS
constant Web.Auth.Facebook.SCOPE_FRIENDS_RELATIONSHIPS
constant Web.Auth.Facebook.SCOPE_FRIENDS_RELIGION_POLITICS
constant Web.Auth.Facebook.SCOPE_FRIENDS_STATUS
constant Web.Auth.Facebook.SCOPE_FRIENDS_SUBSCRIPTIONS
constant Web.Auth.Facebook.SCOPE_FRIENDS_VIDEOS
constant Web.Auth.Facebook.SCOPE_FRIENDS_WEBSITE
constant Web.Auth.Facebook.SCOPE_FRIENDS_WORK_HISTORY

Class Web.Auth.Github

Description: This class is used to OAuth2 authenticate against Github

Inherit Client: inherit .OAuth2.Client : Client

Enum Web.Auth.Github.Scopes

Constant SCOPE_REPO
Constant SCOPE_GIST
Constant SCOPE_USER
Constant SCOPE_USER_EMAIL
Constant SCOPE_USER_FOLLOW
Constant SCOPE_PUBLIC_REPO
Constant SCOPE_REPO_DEPLOYMENT
Constant SCOPE_REPO_STATUS
Constant SCOPE_DELETE_REPO
Constant SCOPE_NOTIFICATIONS
Constant SCOPE_READ_REPO_HOOK
Constant SCOPE_WRITE_REPO_HOOK
Constant SCOPE_ADMIN_REPO_HOOK
Constant SCOPE_READ_ORG
Constant SCOPE_WRITE_ORG
Constant SCOPE_ADMIN_ORG
Constant SCOPE_READ_PUBLIC_KEY
Constant SCOPE_WRITE_PUBLIC_KEY
Constant SCOPE_ADMIN_PUBLIC_KEY: constant Web.Auth.Github.SCOPE_REPO
constant Web.Auth.Github.SCOPE_GIST
constant Web.Auth.Github.SCOPE_USER
constant Web.Auth.Github.SCOPE_USER_EMAIL
constant Web.Auth.Github.SCOPE_USER_FOLLOW
constant Web.Auth.Github.SCOPE_PUBLIC_REPO
constant Web.Auth.Github.SCOPE_REPO_DEPLOYMENT
constant Web.Auth.Github.SCOPE_REPO_STATUS
constant Web.Auth.Github.SCOPE_DELETE_REPO
constant Web.Auth.Github.SCOPE_NOTIFICATIONS
constant Web.Auth.Github.SCOPE_READ_REPO_HOOK
constant Web.Auth.Github.SCOPE_WRITE_REPO_HOOK
constant Web.Auth.Github.SCOPE_ADMIN_REPO_HOOK
constant Web.Auth.Github.SCOPE_READ_ORG
constant Web.Auth.Github.SCOPE_WRITE_ORG
constant Web.Auth.Github.SCOPE_ADMIN_ORG
constant Web.Auth.Github.SCOPE_READ_PUBLIC_KEY
constant Web.Auth.Github.SCOPE_WRITE_PUBLIC_KEY
constant Web.Auth.Github.SCOPE_ADMIN_PUBLIC_KEY

Class Web.Auth.Instagram

Description: This class is used to OAuth2 authenticate agains Instagram

Inherit Client: inherit .OAuth2.Client : Client

Constant OAUTH_AUTH_URI: constantstring Web.Auth.Instagram.OAUTH_AUTH_URI
Description: Instagram authorization URI

Constant OAUTH_TOKEN_URI: constantstring Web.Auth.Instagram.OAUTH_TOKEN_URI
Description: Instagram request access token URI

Variable _scope: protectedstring Web.Auth.Instagram._scope
Description: Default scope

Variable valid_scopes: protectedmultiset(string) Web.Auth.Instagram.valid_scopes
Description: Valid Instagram scopes

Class Web.Auth.Linkedin

Description: This class is used to OAuth2 authenticate against LinkedIn

Inherit Client: inherit .OAuth2.Client : Client

Constant DEFAULT_SCOPE: protected constant Web.Auth.Linkedin.DEFAULT_SCOPE
Description: Default scope to use if none is set explicitly

Constant STATE: protected constantint Web.Auth.Linkedin.STATE
Description: Adds the state parameter to the request which will have the value of a random string

Enum Web.Auth.Linkedin.Scopes

Constant SCOPE_R_BASIC
Constant SCOPE_R_NETWORK
Constant SCOPE_RW_GROUPS
Constant SCOPE_R_FULLPROFILE
Constant SCOPE_R_CONTACTINFO
Constant SCOPE_W_MESSAGES
Constant SCOPE_R_EMAILADDRESS
Constant SCOPE_RW_NUS: constant Web.Auth.Linkedin.SCOPE_R_BASIC
constant Web.Auth.Linkedin.SCOPE_R_NETWORK
constant Web.Auth.Linkedin.SCOPE_RW_GROUPS
constant Web.Auth.Linkedin.SCOPE_R_FULLPROFILE
constant Web.Auth.Linkedin.SCOPE_R_CONTACTINFO
constant Web.Auth.Linkedin.SCOPE_W_MESSAGES
constant Web.Auth.Linkedin.SCOPE_R_EMAILADDRESS
constant Web.Auth.Linkedin.SCOPE_RW_NUS

Class Web.Auth.Param

Description

Representation of a parameter.

Many Social web services use a RESTful communication and have similiar API's. This class is suitable for many RESTful web services and if this class doesn't suite a particular service, just inherit this class and rewrite the behaviour where needed.

See also

Params

Variable name: protectedstring Web.Auth.Param.name
Description: The name of the parameter

Variable value: protectedstring Web.Auth.Param.value
Description: The value of the parameter

Method _sprintf: stringsprintf(stringformat, ... Web.Auth.Paramarg ... )
Description: String format method
Parameter t

Method `<: bool res = Web.Auth.Param() < other
Description: Checks if this object is less than other
Parameter other

Method `==: bool res = Web.Auth.Param() == other
Description: Comparer method. Checks if other equals this object
Parameter other

Method `>: bool res = Web.Auth.Param() > other
Description: Checks if this object is greater than other
Parameter other

Method create: Web.Auth.ParamWeb.Auth.Param(stringname, mixedvalue)
Description: Creates a new instance of Param
Parameter name
Parameter value

Method get_name: stringget_name()
Description: Getter for the parameter name

Method get_value: stringget_value()
Description: Getter for the parameter value

Method low_set_value: privatevoidlow_set_value(stringv)
Description: Makes sure v to set as value is in UTF-8 encoding
Parameter v

Method name_value: stringname_value()
Description: Returns the name and value as querystring key/value pair

Method name_value_encoded: stringname_value_encoded()
Description: Same as name_value() except this URL encodes the value.

Method set_name: voidset_name(stringname)
Description: Setter for the parameter name
Parameter name

Method set_value: voidset_value(mixedvalue)
Description: Setter for the parameter value
Parameter value

Class Web.Auth.Params

Description: Parameter collection class
See also: Param

Variable params: protectedarray(Param) Web.Auth.Params.params
Description: The parameters.

Method _indices: array(string) indices(Web.Auth.Paramsarg)
Description: Parameter keys

Method _sprintf: stringsprintf(stringformat, ... Web.Auth.Paramsarg ... )
Description: String format method
Parameter t

Method _values: array(string) values(Web.Auth.Paramsarg)
Description: Parameter values

Method `+: this_program res = Web.Auth.Params() + p
Description: Add p to the array of Parameters
Parameter p
Returns: A new Params object

Method `-: this_program res = Web.Auth.Params() - p
Description: Remove p from the Parameters array of the current object.
Parameter p

Method `[]: Param|zero res = Web.Auth.Params()[ key ]
Description: Index lookup
Parameter key: The name of a Paramerter to find.

Method add_mapping: this_programadd_mapping(mappingvalue)
Description: Add a mapping of key/value pairs to the current instance
Parameter value
Returns: The object being called

Method cast: (int)Web.Auth.Params() (float)Web.Auth.Params() (string)Web.Auth.Params() (array)Web.Auth.Params() (mapping)Web.Auth.Params() (multiset)Web.Auth.Params()
Description: Casting method
Parameter how

Method clone: this_programclone()
Description: Clone the current instance

Method create: Web.Auth.ParamsWeb.Auth.Params(Param ... args)
Description: Creates a new instance of Params
Parameter args

Method get_params: array(Param) get_params()
Description: Returns the array of Parameters

Method sign: stringsign(stringsecret)
Description: Sign the parameters
Parameter secret: The API secret

Method to_mapping: mapping(string:mixed) to_mapping()
Description: Turns the parameters into a mapping

Method to_query: stringto_query()
Description: Turns the parameters into a query string

Class Web.Auth.Tumblr

Description: Tumblr authentication class

Inherit Authentication: inherit .OAuth.Authentication : Authentication

Constant ACCESS_TOKEN_URL: constantstring Web.Auth.Tumblr.ACCESS_TOKEN_URL
Description: The endpoint to send request for an access token

Constant REQUEST_TOKEN_URL: constantstring Web.Auth.Tumblr.REQUEST_TOKEN_URL
Description: The endpoint to send request for a request token

Constant USER_AUTH_URL: constantstring Web.Auth.Tumblr.USER_AUTH_URL
Description: The enpoint to redirect to when authenticating an application

Class Web.Auth.Twitter

Description: Twitter authentication class

Inherit Authentication: inherit Web.Auth.OAuth.Authentication : Authentication

Constant ACCESS_TOKEN_URL: constantstring Web.Auth.Twitter.ACCESS_TOKEN_URL
Description: The endpoint to send request for an access token

Constant REQUEST_TOKEN_URL: constantstring Web.Auth.Twitter.REQUEST_TOKEN_URL
Description: The endpoint to send request for a request token

Constant USER_AUTH_URL: constantstring Web.Auth.Twitter.USER_AUTH_URL
Description: The enpoint to redirect to when authenticating an application

Module Web.Auth.Google

Description: Google authentication classes.

Class Web.Auth.Google.Analytics

Description: Google Analytics authorization class

Inherit Authorization: inherit Authorization : Authorization

Constant SCOPE_RO
Constant SCOPE_RW
Constant SCOPE_EDIT
Constant SCOPE_MANAGE_USERS
Constant SCOPE_MANAGE_USERS_RO: constantstring Web.Auth.Google.Analytics.SCOPE_RO
constantstring Web.Auth.Google.Analytics.SCOPE_RW
constantstring Web.Auth.Google.Analytics.SCOPE_EDIT
constantstring Web.Auth.Google.Analytics.SCOPE_MANAGE_USERS
constantstring Web.Auth.Google.Analytics.SCOPE_MANAGE_USERS_RO
Description: Authentication scopes

Variable _scope: protectedstring Web.Auth.Google.Analytics._scope
Description: Default scope

Variable valid_scopes: multiset(string) Web.Auth.Google.Analytics.valid_scopes
Description: All valid scopes

Class Web.Auth.Google.Authorization

Description: Default Google authorization class

Inherit Client: inherit Web.Auth.OAuth2.Client : Client

Constant OAUTH_AUTH_URI: constantstring Web.Auth.Google.Authorization.OAUTH_AUTH_URI

Constant SCOPE_EMAIL: constantstring Web.Auth.Google.Authorization.SCOPE_EMAIL

Constant SCOPE_OPENID: constantstring Web.Auth.Google.Authorization.SCOPE_OPENID

Constant SCOPE_PROFILE: constantstring Web.Auth.Google.Authorization.SCOPE_PROFILE

Variable valid_scopes: multiset(string) Web.Auth.Google.Authorization.valid_scopes
Description: All valid scopes

Class Web.Auth.Google.Plus

Description: Google+ authorization class

Inherit Authorization: inherit Authorization : Authorization

Constant SCOPE_ME
Constant SCOPE_LOGIN: constantstring Web.Auth.Google.Plus.SCOPE_ME
constantstring Web.Auth.Google.Plus.SCOPE_LOGIN
Description: Authentication scopes

Variable _scope: protectedstring Web.Auth.Google.Plus._scope
Description: Default scope

Variable valid_scopes: protectedmultiset(string) Web.Auth.Google.Plus.valid_scopes
Description: All valid scopes

Module Web.Auth.OAuth

Description

OAuth module

Example

importWeb.Auth.OAuth;string endpoint ="http://twitter.com/users/show.xml";

 Consumer consumer = Consumer(my_consumer_key, my_consumer_secret);
 Token    token    = Token(my_access_token_key, my_access_token_secret);
 Params   params   = Params(Param("user_id", 12345));
 Request  request  = request(consumer, token, params);

 request->sign_request(Signature.HMAC_SHA1, consumer, token);Protocols.HTTP.Query query = request->submit();if(query->status != 200)
   error("Bad response status: %d\n", query->status);

 werror("Data is: %s\n", query->data());

Constant CALLBACK_KEY: constantstring Web.Auth.OAuth.CALLBACK_KEY
Description: Query string variable name for a callback URL.

Constant CONSUMER_KEY_KEY: constantstring Web.Auth.OAuth.CONSUMER_KEY_KEY
Description: Query string variable name for the consumer key.

Constant NONCE_KEY: constantstring Web.Auth.OAuth.NONCE_KEY
Description: Query string variable name for the nonce.

Constant SIGNATURE_KEY: constantstring Web.Auth.OAuth.SIGNATURE_KEY
Description: Query string variable name for the signature.

Constant SIGNATURE_METHOD_KEY: constantstring Web.Auth.OAuth.SIGNATURE_METHOD_KEY
Description: Query string variable name for the signature method.

Constant TIMESTAMP_KEY: constantstring Web.Auth.OAuth.TIMESTAMP_KEY
Description: Query string variable name for the timestamp.

Constant TOKEN_KEY: constantstring Web.Auth.OAuth.TOKEN_KEY
Description: Query string variable name for the token key.

Constant TOKEN_SECRET_KEY: constantstring Web.Auth.OAuth.TOKEN_SECRET_KEY
Description: Query string variable name for the token secret.

Constant VERSION: constantstring Web.Auth.OAuth.VERSION
Description: Verion

Constant VERSION_KEY: constantstring Web.Auth.OAuth.VERSION_KEY
Description: Query string variable name for the version.

Method get_default_params: Paramsget_default_params(Consumerconsumer, Tokentoken)
Description: Returns the default params for authentication/signing.

Method nonce: stringnonce()
Description: Generates a nonce.

Method normalize_uri: stringnormalize_uri(string|Standards.URIuri)
Description: Normalizes uri
Parameter uri: A string or Standards.URI.

Method query_to_params: Paramsquery_to_params(string|Standards.URI|mappingq)
Description: Converts a query string, or a mapping, into a Params object.

Method request: Requestrequest(string|Standards.URIuri, Consumerconsumer, Tokentoken, void|Paramsparams, void|stringhttp_method)
Description: Helper method to create a Request object.
Throws: An error if consumer is null.
Parameter http_method: Defaults to GET.

Class Web.Auth.OAuth.Authentication

Description: The purpose of this class is to streamline OAuth1 with OAuth2. This class will not do much on it's own, since its purpose is to be inherited by some other class implementing a specific authorization service.

Inherit oauth: inherit .Client : oauth

Inherit oauth2: inherit Web.Auth.OAuth2.Client : oauth2

Constant ACCESS_TOKEN_URL: constantstring Web.Auth.OAuth.Authentication.ACCESS_TOKEN_URL
Description: The endpoint to send request for an access token.

Constant REQUEST_TOKEN_URL: constantstring Web.Auth.OAuth.Authentication.REQUEST_TOKEN_URL
Description: The endpoint to send request for a request token.

Constant USER_AUTH_URL: constantstring Web.Auth.OAuth.Authentication.USER_AUTH_URL
Description: The enpoint to redirect to when authorize an application.

Method call: stringcall(string|Standards.URIurl, void|mapping|.Paramsargs, void|stringmethod)
Description: Does the low level HTTP call to a service.
Throws: An error if HTTP status != 200
Parameter url: The full address to the service e.g: http://twitter.com/direct_messages.xml
Parameter args: Arguments to send with the request
Parameter mehod: The HTTP method to use

Method create: Web.Auth.OAuth.AuthenticationWeb.Auth.OAuth.Authentication(stringclient_id, stringclient_secret, void|stringredir, void|string|array(string)|multiset(string) scope)
Description: Creates an OAuth object.
Parameter client_id: The application ID.
Parameter client_secret: The application secret.
Parameter redirect_uri: Where the authorization page should redirect back to. This must be a fully qualified domain name. This can be set/overridden in get_request_token().
Parameter scope: Extended permissions to use for this authentication. This can be set/overridden in get_auth_uri().

Method get_access_token: .Tokenget_access_token(void|stringoauth_verifier)
Description: Fetches an access token.

Method get_auth_uri: stringget_auth_uri(void|mappingargs)

Method get_request_token: .Tokenget_request_token(void|string|Standards.URIcallback_uri, void|boolforce_login)
Description: Fetches a request token.
Parameter callback_uri: Overrides the callback uri in the application settings.
Parameter force_login: If 1 forces the user to provide its credentials at the Twitter login page.

Method is_authenticated: boolis_authenticated()
Description: Returns true if authenticated.

Method low_get_access_token: protectedstringlow_get_access_token(void|stringoauth_verifier)
Description: Fetches an access token.

Method normalize_method: protectedstringnormalize_method(stringmethod)
Description: Normalizes and verifies the HTTP method to be used in a HTTP call.

Method parse_error_xml

mappingparse_error_xml(stringxml)

Description

Parses an error xml tree.

Returns

A mapping:

"request" : string

"error" : string

Method request_access_token: stringrequest_access_token(stringcode)
Description: Same as get_access_token except this returns a string to comply with the OAuth2 authentication process.

Method set_authentication: voidset_authentication(stringkey, void|stringsecret)
Description: Set authentication.

Method set_from_cookie: this_programset_from_cookie(stringencoded_value)
Description: Populate this object with the result from request_access_token().
Returns: The object being called.

Class Web.Auth.OAuth.Client

Description: OAuth client class.
Note: This class is of no use by it self. It's intended to be inherited by classes that uses OAuth authorization.

Variable access_token_url: protectedstring Web.Auth.OAuth.Client.access_token_url
Description: The endpoint to send request for an access token.

Variable consumer: protectedConsumer Web.Auth.OAuth.Client.consumer
Description: The consumer object.

Variable request_token_url: protectedstring Web.Auth.OAuth.Client.request_token_url
Description: The endpoint to send request for a request token.

Variable token: protectedToken Web.Auth.OAuth.Client.token
Description: The token object.

Variable user_auth_url: protectedstring Web.Auth.OAuth.Client.user_auth_url
Description: The enpoint to redirect to when authorize an application.

Method create: Web.Auth.OAuth.ClientWeb.Auth.OAuth.Client(Consumerconsumer, Tokentoken)
Description: Create a new Client.
Note: This class must be inherited

Method get_access_token_url: stringget_access_token_url()
Description: Returns the url for requesting an access token.

Method get_consumer: Consumerget_consumer()
Description: Returns the consumer.

Method get_request_token_url: stringget_request_token_url()
Description: Returns the url for requesting a request token.

Method get_token: Tokenget_token()
Description: Returns the token.

Method get_user_auth_url: stringget_user_auth_url()
Description: Returns the url for authorizing an application.

Method set_token: voidset_token(Tokentoken)
voidset_token(stringtoken_key, stringtoken_secret)
Description: Set the Token.
Parameter key: Either a Token object or a token key.
Parameter secret: The token secret if key is a token key.

Class Web.Auth.OAuth.Consumer

Description: An OAuth user

Variable callback: string|Standards.URI Web.Auth.OAuth.Consumer.callback
Description: Callback url that the remote verifying page will return to.

Variable key: string Web.Auth.OAuth.Consumer.key
Description: Consumer key

Variable secret: string Web.Auth.OAuth.Consumer.secret
Description: Consumer secret

Method create: Web.Auth.OAuth.ConsumerWeb.Auth.OAuth.Consumer(stringkey, stringsecret, void|string|Standards.URIcallback)
Description: Creates a new Consumer object.
Parameter callback: NOTE: Has no effect in this implementation.

Class Web.Auth.OAuth.Param

Description: Represents a query string parameter, i.e. key=value.

Variable name: protectedstring Web.Auth.OAuth.Param.name
Description: Param name

Variable value: protectedstring Web.Auth.OAuth.Param.value
Description: Param value

Method `==: bool res = Web.Auth.OAuth.Param() == other
Description: Comparer method. Checks if other equals this object.

Method `>: bool res = Web.Auth.OAuth.Param() > other
Description: Checks if this object is greater than other.

Method `[]: object|zero res = Web.Auth.OAuth.Param()[ key ]
Description: Index lookup.

Method create: Web.Auth.OAuth.ParamWeb.Auth.OAuth.Param(stringname, mixedvalue)
Description: Creates a new Param.

Method get_encoded_value: stringget_encoded_value()
Description: Returns the value encoded.

Method get_name: stringget_name()
Description: Getter for the name attribute.

Method get_signature: stringget_signature()
Description: Returns the name and value for usage in a signature string.

Method get_value: stringget_value()
Description: Getter for the value attribute.

Method set_name: voidset_name(stringvalue)
Description: Setter for the value attribute.

Method set_value: voidset_value(mixed_value)
Description: Setter for the value attribute.

Class Web.Auth.OAuth.Params

Description: Collection of Param

Variable params: privatearray(Param) Web.Auth.OAuth.Params.params
Description: Storage for Params of this object.

Method _sizeof: int(0..)sizeof(Web.Auth.OAuth.Paramsarg)
Description: Returns the size of the params array.

Method _values: mixedvalues(Web.Auth.OAuth.Paramsarg)
Description: Returns the params.

Method `+: this_program res = Web.Auth.OAuth.Params() + p
Description: Append p to the internal array.
Returns: The object being called.

Method `-: this_program res = Web.Auth.OAuth.Params() - p
Description: Removes p from the internal array.
Returns: The object being called.

Method `[]: mixed res = Web.Auth.OAuth.Params()[ key ]
Description: Index lookup
Returns: If no Param is found returns 0. If multiple Params with name key is found a new Params object with the found params will be retured. If only one Param is found that param will be returned.

Method add_mapping: this_programadd_mapping(mappingargs)
Description: Append mapping args as Param objects.
Returns: The object being called.

Method cast: (mapping)Web.Auth.OAuth.Params()
Description: Supports casting to mapping, which will map parameter names to their values.

Method create: Web.Auth.OAuth.ParamsWeb.Auth.OAuth.Params(Param ... params)
Description: Create a new Params
Parameter params: Arbitrary number of Param objects.

Method get_auth_header: stringget_auth_header()
Description: Returns the params for usage in an authentication header.

Method get_encoded_variables: mappingget_encoded_variables()
Description: Returns the parameters as a mapping with encoded values.
See also: get_variables()

Method get_query_string: stringget_query_string()
Description: Returns the parameters as a query string.

Method get_signature: stringget_signature()
Description: Returns the parameters for usage in a signature base string.

Method get_variables: mappingget_variables()
Description: Returns the parameters as a mapping.

Class Web.Auth.OAuth.Request

Description: Class for building a signed request and querying the remote service.

Variable base_string: protectedstring Web.Auth.OAuth.Request.base_string
Description: The signature basestring.

Variable method: protectedstring Web.Auth.OAuth.Request.method
Description: String representation of the HTTP method.

Variable params: protectedParams Web.Auth.OAuth.Request.params
Description: The parameters to send.

Variable uri: protectedStandards.URI Web.Auth.OAuth.Request.uri
Description: The remote endpoint.

Method add_param: this_programadd_param(Param|stringname, void|stringvalue)
Description: Add a param.
Returns: The object being called.

Method add_params: voidadd_params(Paramsparams)
Description: Add a Params object.

Method cast: (string)Web.Auth.OAuth.Request()
Description: It is possible to case the Request object to a string, which will be the request URL.

Method create: Web.Auth.OAuth.RequestWeb.Auth.OAuth.Request(string|Standards.URIuri, stringhttp_method, void|Paramsparams)
Description: Creates a new Request.
See also: request()
Parameter uri: The uri to request.
Parameter http_method: The HTTP method to use. Either "GET" or "POST".

Method get_param: Param|zeroget_param(stringname)
Description: Get param with name name.

Method get_params: Paramsget_params()
Description: Returns the Params collection.

Method get_signature_base: stringget_signature_base()
Description: Generates a signature base.

Method sign_request: voidsign_request(intsignature_type, Consumerconsumer, Tokentoken)
Description: Signs the request.
Parameter signature_type: One of the types in Signature.

Method submit: Protocols.HTTP.Querysubmit(void|mappingextra_headers)
Description: Send the request to the remote endpoint.

Class Web.Auth.OAuth.Token

Description: Token class.

Variable key
Variable secret: string|zero Web.Auth.OAuth.Token.key
string|zero Web.Auth.OAuth.Token.secret

Method __create__: protectedlocalvoid__create__(string|zerokey, string|zerosecret)

Method cast: (string)Web.Auth.OAuth.Token()
Description: Only supports casting to string wich will return a query string of the object.

Method create: Web.Auth.OAuth.TokenWeb.Auth.OAuth.Token(string|zerokey, string|zerosecret)

Module Web.Auth.OAuth.Signature

Description: Module for creating OAuth signatures

Constant HMAC_SHA1: constantint Web.Auth.OAuth.Signature.HMAC_SHA1
Description: Signature type for hmac sha1 signing.

Constant NONE: protected constantint Web.Auth.OAuth.Signature.NONE
Description: Signature type for the Base class.

Constant PLAINTEXT: constantint Web.Auth.OAuth.Signature.PLAINTEXT
Description: Signature type for plaintext signing.

Constant RSA_SHA1: constantint Web.Auth.OAuth.Signature.RSA_SHA1
Description: Signature type for rsa sha1 signing.

Constant SIGTYPE: constant Web.Auth.OAuth.Signature.SIGTYPE
Description: Signature types to signature key mapping.

Method get_object: Baseget_object(inttype)
Description: Returns a signature class for signing with type.
Throws: An error if type is unknown
Parameter type: Either PLAINTEXT, HMAC_SHA1 or RSA_SHA1.

Class Web.Auth.OAuth.Signature.Base

Description: Base signature class.

Variable method: protectedstring Web.Auth.OAuth.Signature.Base.method
Description: String representation of signature type.

Variable type: protectedint Web.Auth.OAuth.Signature.Base.type
Description: Signature type.

Method build_signature: stringbuild_signature(Requestrequest, Consumerconsumer, Tokentoken)
Description: Builds the signature string.

Method get_method: stringget_method()
Description: Returns the method.

Method get_type: intget_type()
Description: Returns the type.

Class Web.Auth.OAuth.Signature.HmacSha1

Description: HMAC_SHA1 signature.

Inherit Base: inherit Base : Base

Method build_signature: stringbuild_signature(Requestrequest, Consumerconsumer, Tokentoken)
Description: Builds the signature string.

Class Web.Auth.OAuth.Signature.Plaintext

Description: Plaintext signature.

Inherit Base: inherit Base : Base

Method build_signature: stringbuild_signature(Requestrequest, Consumerconsumer, Tokentoken)
Description: Builds the signature string.

Class Web.Auth.OAuth.Signature.RsaSha1

Description: RSA_SHA1 signature. Currently not implemented.

Inherit Base: inherit Base : Base

Method build_signature: stringbuild_signature(Requestrequest, Consumerconsumer, Tokentoken)
Description: Builds the signature string.

Module Web.Auth.OAuth2

Description

OAuth2 client

A base OAuth2 class can be instantiated either via `() (Web.Auth.OAuth2(params...)) or via Web.Auth.OAuth2.Base().

Method `(): protectedBase`()(stringclient_id, stringclient_secret, void|stringredirect_uri, void|string|array(string)|multiset(string) scope)
Description: Instantiate a generic OAuth2 Base class.
Parameter client_id: The application ID.
Parameter client_secret: The application secret.
Parameter redirect_uri: Where the authorization page should redirect back to. This must be a fully qualified domain name. This can be set/overridden in Base()->get_auth_uri() and/or Base()->set_redirect_uri().
Parameter scope: Extended permissions to use for this authentication. This can be set/overridden in Base()->get_auth_uri().

Class Web.Auth.OAuth2.Base

Description: Generic OAuth2 client class.

Constant STATE: protected constantint Web.Auth.OAuth2.Base.STATE
Description: Some OAuth2 verifiers need the STATE parameter. If this is not 0 a random string will be generated and the state parameter will be added to the request.

Constant USER_AGENT: protected constantstring Web.Auth.OAuth2.Base.USER_AGENT
Description: User agent string.

Constant VERSION: protected constantstring Web.Auth.OAuth2.Base.VERSION
Description: Version of this implementation.

Variable _access_type: protectedstring Web.Auth.OAuth2.Base._access_type
Description: Access type of the request.

Variable _client_id: protectedstring Web.Auth.OAuth2.Base._client_id
Description: The application ID.

Variable _client_secret: protectedstring Web.Auth.OAuth2.Base._client_secret
Description: The application secret.

Variable _grant_type

protectedstring Web.Auth.OAuth2.Base._grant_type

Description

GRANT_TYPE_AUTHORIZATION_CODE for apps running on a web server
GRANT_TYPE_IMPLICIT for browser-based or mobile apps
GRANT_TYPE_PASSWORD for logging in with a username and password
GRANT_TYPE_CLIENT_CREDENTIALS for application access

Variable _redirect_uri: protectedstring Web.Auth.OAuth2.Base._redirect_uri
Description: Where the authorization page should redirect to.

Variable _response_type

protectedstring Web.Auth.OAuth2.Base._response_type

Description

RESPONSE_TYPE_CODE for apps running on a webserver
RESPONSE_TYPE_TOKEN for apps browser-based or mobile apps

Variable _scope: protectedstring|array(string)|multiset(string) Web.Auth.OAuth2.Base._scope
Description: The scope of the authorization. Limits the access.

Variable access_token

string Web.Auth.OAuth2.Base.access_token

Description

Getting

Getter for access_token.

Setting

Getter for access_token.

Variable created: Calendar.Second Web.Auth.OAuth2.Base.created
Description: Getter for when the authentication was created.
Note: Read only

Variable expires: Calendar.Second Web.Auth.OAuth2.Base.expires
Description: Getter for when the authentication expires.
Note: Read only

Variable http_request_timeout: int(1..) Web.Auth.OAuth2.Base.http_request_timeout
Description: Request timeout in seconds. Only affects async queries.

Variable refresh_token: string Web.Auth.OAuth2.Base.refresh_token
Description: Getter for refresh_token.
Note: Read only

Variable request_headers: protectedmapping Web.Auth.OAuth2.Base.request_headers
Description: Default request headers.

Variable token_type: string Web.Auth.OAuth2.Base.token_type
Description: Getter for token_type.
Note: Read only

Variable user: mapping Web.Auth.OAuth2.Base.user
Description: Getter for the user mapping which may or may not be set.
Note: Read only

Variable valid_scopes: protectedmultiset(string) Web.Auth.OAuth2.Base.valid_scopes
Description: A mapping of valid scopes for the API.

Method cast: (int)Web.Auth.OAuth2.Base() (float)Web.Auth.OAuth2.Base() (string)Web.Auth.OAuth2.Base() (array)Web.Auth.OAuth2.Base() (mapping)Web.Auth.OAuth2.Base() (multiset)Web.Auth.OAuth2.Base()
Description: If casted to string the access_token will be returned. If casted to int the expires timestamp will be returned.

Method create: Web.Auth.OAuth2.BaseWeb.Auth.OAuth2.Base(stringclient_id, stringclient_secret, void|stringredirect_uri, void|string|array(string)|multiset(string) scope)
Description: Creates an OAuth2 object.
Parameter client_id: The application ID.
Parameter client_secret: The application secret.
Parameter redirect_uri: Where the authorization page should redirect back to. This must be a fully qualified domain name. This can be set/overridden in get_auth_uri() and/or set_redirect_uri().
Parameter scope: Extended permissions to use for this authentication. This can be set/overridden in get_auth_uri().

Method decode_access_token_response: protectedbooldecode_access_token_response(stringr)
Description: Decode the response from an authentication call. If the response was ok the internal mapping gettable will be populated with the members/variables in r.
Parameter r: The response from do_query()

Method do_query: protectedstring|zerodo_query(string|zerooauth_token_uri, Web.Auth.Paramsp, void|function(bool, string:void) async_cb)
Description: Send a request to oauth_token_uri with params p
Parameter async_cb: If given an async request will be made and this function will be called when the request is finished. The first argument passed to the callback will be true or false depending on if the request was successfull or not. The second argument will be a string. If the request failed it will be an error message. If it succeeded it will be the result as a string encoded with predef::encode_value().

Method get_access_type: stringget_access_type()
Description: Getter for the access type, if any.

Method get_auth_uri: stringget_auth_uri(string|zeroauth_uri, void|mappingargs)
Description: Returns an authorization URI.
Parameter auth_uri: The URI to the remote authorization page
Parameter args: Additional argument.

Method get_client_id: stringget_client_id()
Description: Returns the application ID.

Method get_client_secret: stringget_client_secret()
Description: Returns the application secret.

Method get_default_params: protectedWeb.Auth.Paramsget_default_params(void|stringgrant_type)
Description: Returns a set of default parameters.

Method get_grant_type: stringget_grant_type()
Description: Returns the grant_type of the object.

Method get_redirect_uri: stringget_redirect_uri()
Description: Returns the redirect uri.

Method get_scope: mixedget_scope()
Description: Returns the scope/scopes set, if any.

Method get_token_from_jwt: string|zeroget_token_from_jwt(stringjwt, void|stringtoken_endpoint, string|voidsub, void|function(bool, string:void) async_cb)
Description: Get an access_token from a JWT. http://jwt.io/
Parameter jwt: JSON string.
Parameter token_endpoint: URI to the request access_token endpoint.
Parameter sub: Email/id of the requesting user.
Parameter async_callback: If given the request will be made asynchronously. The signature is callback(bool, string). If successful the second argument will be the result encoded with predef::encode_value(), which can be stored and later used to populate an instance via set_from_cookie().
See also: Web.encode_jwt()

Method get_valid_scopes: protectedstringget_valid_scopes(string|array(string)|multiset(string) s)
Description: Returns a space separated list of all valid scopes in s. s can be a comma or space separated string or an array or multiset of strings. Each element in s will be matched against the valid scopes set in the module inheriting this class.

Method has_scope: boolhas_scope(stringscope)
Description: Check if scope exists in this object.

Method is_authenticated: boolis_authenticated()
Description: Do we have a valid authentication.

Method is_expired: boolis_expired()
Description: Checks if this authorization has expired.

Method is_renewable: boolis_renewable()
Description: Checks if the authorization is renewable. This is true if the Web.Auth.OAuth2.Base() object has been populated from Web.Auth.OAuth2.Base()->set_from_cookie(), i.e the user has been authorized but the session has expired.

Method list_valid_scopes: multisetlist_valid_scopes()
Description: Returns the valid scopes.

Method refresh_access_token: string|zerorefresh_access_token(string|zerooauth_token_uri, void|function(bool, string:void) async_cb)
Description: Refreshes the access token, if a refresh token exists in the object.
Parameter oauth_token_uri: Endpoint of the authentication service.
Parameter async_cb: If given an async request will be made and this function will be called when the request is finished. The first argument passed to the callback will be true or false depending on if the request was successfull or not. The second argument will be a string. If the request failed it will be an error message. If it succeeded it will be the result as a string encoded with predef::encode_value().

Method request_access_token

string|zerorequest_access_token(string|zerooauth_token_uri, stringcode, void|function(bool, string:void) async_cb)

Description

Requests an access token.

Throws

An error if the access token request fails.

Parameter oauth_token_uri

An URI received from get_auth_uri().

Parameter code

The code returned from the authorization page via get_auth_uri().

Parameter async_cb

If given an async request will be made and this function will be called when the request is finished. The first argument passed to the callback will be true or false depending on if the request was successfull or not. The second argument will be a string. If the request failed it will be an error message. If it succeeded it will be the result as a string encoded with predef::encode_value().

Returns

If OK a Pike encoded mapping (i.e it's a string) is returned which can be used to populate an Web.Auth.OAuth2 object at a later time.

The mapping looks like

"access_token" : string

"expires" : int

"created" : int

"refresh_token" : string

"token_type" : string

Depending on the authorization service it might also contain more members.

Method set_access_type: voidset_access_type(stringaccess_type)
Description: Set access_type explicilty.
Parameter access_type: Like: offline

Method set_from_cookie: this_programset_from_cookie(stringencoded_value)
Description: Populate this object with the result from request_access_token().
Throws: An error if the decoding of encoded_value fails.
Parameter encoded_value: The value from a previous call to request_access_token() or refresh_access_token().
Returns: The object being called.

Method set_grant_type: voidset_grant_type(GrantTypetype)
Description: Set the grant type to use.

Method set_redirect_uri: voidset_redirect_uri(stringuri)
Description: Setter for the redirect uri.

Method set_scope: voidset_scope(stringscope)
Description: Set scopes.

Method try_get_error: privatemixedtry_get_error(stringdata)
Description: Try to get an error message from data. Only successful if data is a JSON string and contains the key error.

Enum Web.Auth.OAuth2.Base.GrantType

Description: Grant types.

Constant GRANT_TYPE_AUTHORIZATION_CODE: constant Web.Auth.OAuth2.Base.GRANT_TYPE_AUTHORIZATION_CODE

Constant GRANT_TYPE_CLIENT_CREDENTIALS: constant Web.Auth.OAuth2.Base.GRANT_TYPE_CLIENT_CREDENTIALS

Constant GRANT_TYPE_IMPLICIT: constant Web.Auth.OAuth2.Base.GRANT_TYPE_IMPLICIT

Constant GRANT_TYPE_JWT: constant Web.Auth.OAuth2.Base.GRANT_TYPE_JWT

Constant GRANT_TYPE_PASSWORD: constant Web.Auth.OAuth2.Base.GRANT_TYPE_PASSWORD

Constant GRANT_TYPE_REFRESH_TOKEN: constant Web.Auth.OAuth2.Base.GRANT_TYPE_REFRESH_TOKEN

Enum Web.Auth.OAuth2.Base.ResponseType

Description: Response types.

Constant RESPONSE_TYPE_CODE: constant Web.Auth.OAuth2.Base.RESPONSE_TYPE_CODE

Constant RESPONSE_TYPE_TOKEN: constant Web.Auth.OAuth2.Base.RESPONSE_TYPE_TOKEN

Class Web.Auth.OAuth2.Client

Description: This class is intended to be extended by classes implementing different OAuth2 services.

Inherit Base: inherit Base : Base

Constant DEFAULT_SCOPE: protected constantint Web.Auth.OAuth2.Client.DEFAULT_SCOPE
Description: Scope to set if none is set.

Constant OAUTH_AUTH_URI: constantint Web.Auth.OAuth2.Client.OAUTH_AUTH_URI
Description: Authorization URI.

Constant OAUTH_TOKEN_URI: constantint Web.Auth.OAuth2.Client.OAUTH_TOKEN_URI
Description: Request access token URI.

Method get_auth_uri: stringget_auth_uri(void|mappingargs)
Description: Returns an authorization URI.
Parameter args: Additional argument.

Method get_token_from_jwt: stringget_token_from_jwt(stringjwt, void|stringsub, void|function(bool, string:void) async_cb)
Description: Make a JWT (JSON Web Token) authentication.

Method refresh_access_token: stringrefresh_access_token(void|function(bool, string:void) async_cb)
Description: Refreshes the access token, if a refresh token exists in the object.
Parameter async_cb: If given an async request will be made and this function will be called when the request is finished. The first argument passed to the callback will be true or false depending on if the request was successfull or not. The second argument will be a string. If the request failed it will be an error message. If it succeeded it will be the result as a string encoded with predef::encode_value().

Method request_access_token

stringrequest_access_token(stringcode, void|function(bool, string:void) async_cb)

Description

Requests an access token.

Throws

An error if the access token request fails.

Parameter code

The code returned from the authorization page via get_auth_uri().

Parameter async_cb

Returns

If OK a Pike encoded mapping (i.e it's a string) is returned which can be used to populate an Base object at a later time.

The mapping looks like

"access_token" : string

"expires" : int

"created" : int

"refresh_token" : string

"token_type" : string

Depending on the authorization service it might also contain more members.

Module Web.CGI

Class Web.CGI.Request

Description: Retrieves information about a CGI request from the environment and creates an object with the request information easily formatted.

Variable client: array(string) Web.CGI.Request.client

Variable config: multiset(string) Web.CGI.Request.config
Description: If used with Roxen or Caudium webservers, this field will be populated with "config" information.

Variable cookies: mapping(string:string) Web.CGI.Request.cookies

Variable data: string Web.CGI.Request.data

Variable method: string Web.CGI.Request.method

Variable misc: mapping(string:int|string|array(string)) Web.CGI.Request.misc

Variable pragma: multiset(string) Web.CGI.Request.pragma

Variable prestate: multiset(string) Web.CGI.Request.prestate
Description: If used with Roxen or Caudium webservers, this field will be populated with "prestate" information.

Variable prot: string Web.CGI.Request.prot

Variable query
Variable rest_query: string Web.CGI.Request.query
string Web.CGI.Request.rest_query

Variable referer: array(string) Web.CGI.Request.referer

Variable remoteaddr
Variable remotehost: string Web.CGI.Request.remoteaddr
string Web.CGI.Request.remotehost

Variable supports: multiset(string) Web.CGI.Request.supports
Description: If used with Roxen or Caudium webservers, this field will be populated with "supports" information.

Variable variables: mapping(string:array(string)) Web.CGI.Request.variables

Method create: Web.CGI.RequestWeb.CGI.Request()
Description: creates the request object. To use, create a Request object while running in a CGI environment. Environment variables will be parsed and inserted in the appropriate fields of the resulting object.

Module Web.Crawler

Description

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

Class Web.Crawler.ComplexQueue

Inherit Queue: inherit Queue : Queue

Variable stats
Variable policy: Stats Web.Crawler.ComplexQueue.stats
Policy Web.Crawler.ComplexQueue.policy

Method __create__: protectedlocalvoid__create__(Statsstats, Policypolicy)

Method create: Web.Crawler.ComplexQueueWeb.Crawler.ComplexQueue(Statsstats, Policypolicy)

Class Web.Crawler.Crawler

Method create: Web.Crawler.CrawlerWeb.Crawler.Crawler(Queue_queue, function(:void) _page_cb, function(:void) _error_cb, function(:void) _done_cb, function(:void) _prepare_cb, string|array(string)|Standards.URI|array(Standards.URI) start_uri, mixed ... _args)
Parameter _page_cb: 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.
Parameter _error_cb: 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.
Parameter _done_cb: function called when crawl is complete. Accepts mixed ... args and returns void.
Parameter _prepare_cb: 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.
Parameter start_uri: location to start the crawl from.
Parameter _args: optional arguments sent as the last argument to the callback functions.

Class Web.Crawler.GlobRule

Description

A rule that uses glob expressions

Parameter pattern

a glob pattern that the rule will match against.

Example

GlobRule("http://pike.lysator.liu.se/*.xml");

Inherit Rule: inherit Rule : Rule

Variable pattern: string Web.Crawler.GlobRule.pattern

Method __create__: protectedlocalvoid__create__(stringpattern)

Method create: Web.Crawler.GlobRuleWeb.Crawler.GlobRule(stringpattern)

Class Web.Crawler.MemoryQueue

Description: Memory queue

Inherit Queue: inherit Queue : Queue

Method create: Web.Crawler.MemoryQueueWeb.Crawler.MemoryQueue(Stats_stats, Policy_policy, RuleSet_allow, RuleSet_deny)

Method get: int|Standards.URIget()
Description: 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.

Method put: voidput(string|array(string)|Standards.URI|array(Standards.URI) uri)
Description: Put one or several URIs in the queue. Any URIs that were already present in the queue are silently disregarded.

Class Web.Crawler.MySQLQueue

Inherit Queue: inherit Queue : Queue

Method create: Web.Crawler.MySQLQueueWeb.Crawler.MySQLQueue(Stats_stats, Policy_policy, string_host, string_table, void|RuleSet_allow, void|RuleSet_deny)

Class Web.Crawler.Policy

Description: The crawler policy object.

Variable bandwidth_throttling_floating_window_width: int Web.Crawler.Policy.bandwidth_throttling_floating_window_width
Description: Bandwidth throttling floating window width. Defaults to 30.

Variable max_bits_per_second_per_host: int Web.Crawler.Policy.max_bits_per_second_per_host
Description: Maximum number of bits per second, per host. Defaults to off (0).

Variable max_bits_per_second_total: int Web.Crawler.Policy.max_bits_per_second_total
Description: Maximum number of bits per second. Defaults to off (0).

Variable max_concurrent_fetchers: int Web.Crawler.Policy.max_concurrent_fetchers
Description: Maximum number of fetchers. Defaults to 100.

Variable max_concurrent_fetchers_per_host: int Web.Crawler.Policy.max_concurrent_fetchers_per_host
Description: Maximum concurrent fetchers per host. Defaults to 1.

Variable min_delay_per_host: int Web.Crawler.Policy.min_delay_per_host
Description: Minimum delay per host. Defaults to 0.

Class Web.Crawler.Queue

Description: A crawler queue. Does not need to be reentrant safe. The Crawler always runs in just one thread.

Method get: int|Standards.URIget()
Description: 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.

Method put: voidput(string|array(string)|Standards.URI|array(Standards.URI) uri)
Description: Put one or several URIs in the queue. Any URIs that were already present in the queue are silently disregarded.

Class Web.Crawler.RegexpRule

Description: A rule that uses Regexp expressions

Inherit Rule: inherit Rule : Rule

Method create: Web.Crawler.RegexpRuleWeb.Crawler.RegexpRule(stringre)
Parameter re: a string describing the Regexp expression

Class Web.Crawler.Rule

Description: Abstract rule class.

Method check: intcheck(string|Standards.URIuri)

Class Web.Crawler.RuleSet

Description: A set of rules

Method add_rule: voidadd_rule(Rulerule)
Description: add a rule to the ruleset

Method remove_rule: voidremove_rule(Rulerule)
Description: remove a rule from the ruleset

Class Web.Crawler.Stats

Description: Statistics.

Variable window_width
Variable granularity: int Web.Crawler.Stats.window_width
int Web.Crawler.Stats.granularity

Method __create__: protectedlocalvoid__create__(intwindow_width, intgranularity)

Method bytes_read_callback: voidbytes_read_callback(Standards.URIuri, intnum_bytes_read)
Description: This callback is called when data has arrived for a presently crawled URI, but no more often than once a second.

Method close_callback: voidclose_callback(Standards.URIuri)
Description: This callback is called whenever the crawling of a URI is finished or fails.

Method create: Web.Crawler.StatsWeb.Crawler.Stats(intwindow_width, intgranularity)

Module Web.EngineIO

Description

This is an implementation of the Engine.IO server-side communication's driver. It basically is a real-time bidirectional packet-oriented communication's protocol for communicating between a webbrowser and a server.

The driver mainly is a wrapper around Protocols.WebSocket with the addition of two fallback mechanisms that work around limitations imposed by firewalls and/or older browsers that prevent native Protocols.WebSocket connections from functioning.

This module supports the following features:

It supports both UTF-8 and binary packets.
If both sides support Protocols.WebSocket, then packet sizes are essentially unlimited. The fallback methods have a limit on packet sizes from browser to server, determined by the maximum POST request size the involved network components allow.

In most cases, Engine.IO is not used directly in applications. Instead one uses Socket.IO instead.

Example

Sample small implementation of an EngineIO server farm:
class mysocket {inheritWeb.EngineIO.Socket;void echo(string|Stdio.Buffer msg){
    write(0, msg);}}void wsrequest(array(string) protocols,object req){
  httprequest(req);}void httprequest(object req){switch(req.not_query){case"/engine.io/":
      mysocket client =Web.EngineIO.farm(mysocket, req);if(client){
        client.open(client.echo);
        client.write(0,"Hello world!");}break;}}int main(int argc,array(string) argv){Protocols.WebSocket.Port(httprequest, wsrequest, 80);return-1;}

See also

farm, Web.SocketIO, Protocols.WebSocket, http://github.com/socketio/engine.io-protocol, http://socket.io/

Constant protocol: constantint Web.EngineIO.protocol
Description: Engine.IO protocol version.

Variable options: finalmapping Web.EngineIO.options
Description: Global options for all EngineIO instances.
See also: Socket.create(), Gz.compress()

Method farm: finalSocket|zerofarm(programcreatetype, Protocols.WebSocket.Requestreq, void|mapping(string:mixed) options)
Parameter options: Optional options to override the defaults. This parameter is passed down as is to the underlying Socket.
See also: Socket.create()

Enum Web.EngineIO.

Constant BASE64
Constant OPEN
Constant CLOSE
Constant PING
Constant PONG
Constant MESSAGE
Constant UPGRADE
Constant NOOP
Constant ACK
Constant SENDQEMPTY
Constant SHUTDOWN: constant Web.EngineIO.BASE64
constant Web.EngineIO.OPEN
constant Web.EngineIO.CLOSE
constant Web.EngineIO.PING
constant Web.EngineIO.PONG
constant Web.EngineIO.MESSAGE
constant Web.EngineIO.UPGRADE
constant Web.EngineIO.NOOP
constant Web.EngineIO.ACK
constant Web.EngineIO.SENDQEMPTY
constant Web.EngineIO.SHUTDOWN

Class Web.EngineIO.Socket

Description: Runs a single Engine.IO session.

Variable request: finalProtocols.WebSocket.Request Web.EngineIO.Socket.request
Description: Contains the last request seen on this connection. Can be used to obtain cookies etc.

Variable sid: finalstring Web.EngineIO.Socket.sid
Description: The unique session identifier (in the Engine.IO docs referred to as simply: id).

Method close: finalvoidclose()
Description: Close the socket signalling the other side.

Method create

Web.EngineIO.SocketWeb.EngineIO.Socket(Protocols.WebSocket.Requestreq, void|mappingoptions)

Parameter options

Optional options to override the defaults.

`"pingTimeout" : int`	If, the connection is idle for longer than this, the connection is terminated, unit in `ms`.
`"pingInterval" : int`	The browser-client will send a small ping message every `pingInterval ms`.
`"allowUpgrades" : int`	When `true` (default), it allows the server to upgrade the connection to a real `Protocols.WebSocket` connection.
`"compressionLevel" : int`	The gzip compressionlevel used to compress packets.
`"compressionThreshold" : int`	Packets smaller than this will not be compressed.

Method onrequest: finalvoidonrequest(Protocols.WebSocket.Requestreq)
Description: Handle request, and returns a new Socket object if it's a new connection.

Method open: finalvoidopen(void|function(string|Stdio.Buffer:void) _read_cb, void|function(:void) _close_cb, void|function(:void) _lowmark_cb)
Description: Set callbacks and open socket.

Method write: finalvoidwrite(mapping(string:mixed) options, string|Stdio.Buffer ... msgs)
Description: Send text string or binary Stdio.Buffer messages.

Enum Web.EngineIO.Socket.

Constant RUNNING
Constant PAUSED
Constant SCLOSING
Constant RCLOSING: constant Web.EngineIO.Socket.RUNNING
constant Web.EngineIO.Socket.PAUSED
constant Web.EngineIO.Socket.SCLOSING
constant Web.EngineIO.Socket.RCLOSING

Class Web.EngineIO.Socket.Transport

Method close: voidclose()
Description: Close the transport properly, notify the far end.

Method shutdown: voidshutdown()
Description: Shutdown the transport silently.

Module Web.RSS

Description: Represents a RSS (RDF Site Summary) file.

Method parse_xml: Indexparse_xml(string|Parser.XML.Tree.Noden, void|stringbase)
Description: Returns an Index object, populated with the rss information given in the rss file n.

Class Web.RSS.Channel

Description: Represents an RSS channel.

Inherit Thing: inherit Thing : Thing

Variable title
Variable link
Variable description
Variable image
Variable textinput
Variable items: string Web.RSS.Channel.title
string Web.RSS.Channel.link
string Web.RSS.Channel.description
string|Standards.URI Web.RSS.Channel.image
string|Standards.URI Web.RSS.Channel.textinput
array(Item) Web.RSS.Channel.items

Method add_item: voidadd_item(Itemi)
Description: Adds the Itemi to the Channel.

Method remove_item: voidremove_item(Itemi)
Description: Removes the Itemi from the Channel.

Class Web.RSS.Image

Description: Represents an RSS image resource.

Inherit Thing: inherit Thing : Thing

Variable title
Variable url
Variable link: string Web.RSS.Image.title
string Web.RSS.Image.url
string Web.RSS.Image.link

Class Web.RSS.Index

Description: Represents the top level of an RSS index.

Variable channels: array(Channel) Web.RSS.Index.channels
Description: The RSS channels.

Variable images: array(Image) Web.RSS.Index.images
Description: The RSS images.

Variable items: array(Item) Web.RSS.Index.items
Description: The RSS items.

Variable rdf: .RDF Web.RSS.Index.rdf
Description: The underlying RDF representation of the RSS index.

Variable textinputs: array(Textinput) Web.RSS.Index.textinputs
Description: The RSS textinputs.

Method create: Web.RSS.IndexWeb.RSS.Index(.RDF|void_rdf)

Class Web.RSS.Item

Description: Represents an RSS item resource.

Inherit Thing: inherit Thing : Thing

Variable title
Variable link
Variable description: string Web.RSS.Item.title
string Web.RSS.Item.link
string Web.RSS.Item.description

Class Web.RSS.Textinput

Description: Represents an RSS textinput resource.

Inherit Thing: inherit Thing : Thing

Variable title
Variable description
Variable name
Variable link: string Web.RSS.Textinput.title
string Web.RSS.Textinput.description
string Web.RSS.Textinput.name
string Web.RSS.Textinput.link

Class Web.RSS.Thing

Description: The base class for the RSS resources.

Method create: Web.RSS.ThingWeb.RSS.Thing(stringabout, mappingattributes)
Web.RSS.ThingWeb.RSS.Thing(.RDF.Resourceme)
Description: Creates an RSS resource.

Method get_id: .RDF.Resourceget_id()
Description: Returns the RDF.Resource that identifies this RSS resource.

Module Web.SOAP

Description

This is a limited SOAP wsdl parser using Promises.

Example

Web.SOAP.Promise("https://foo.bar/Logon.svc?wsdl").on_success(lambda(Web.SOAP.Client soap){Web.SOAP.Arguments args, sh;
  args               = soap->get_arguments("Logon");
  sh                 = args->LogonRequestMsg;
  sh->Username       ="foo";
  sh->Password       ="bar";
  sh->WebServiceType ="Publisher";

  soap->call(args).on_success(lambda(mapping resp){string token = resp->CredentialToken;});});

Method Promise: finalConcurrent.FuturePromise(stringwsdlurl, void|mappingheaders)
Returns: A Concurrent.Future that eventually delivers a Client.
See also: Client()

Class Web.SOAP.Client

Method call: finalConcurrent.Futurecall(Argumentsargs)
Description: Calls the SOAP method you most recently addressed using get_arguments().
Returns: A Concurrent.Future that eventually delivers a result mapping.
See also: get_arguments()

Method create: Web.SOAP.ClientWeb.SOAP.Client(Protocols.HTTP.Promise.Resultresp)
Description: Usually not called directly.
See also: Promise()

Method get_arguments: finalArgumentsget_arguments(stringmethod)
Description: Primes the Client to perform the call() later. Use the returned structure to pass parameters. Only assigned parameters will be passed to the call.
Returns: A structure describing all arguments for the specified method.
See also: call()

Method get_methods: finalArgumentsget_methods()
Returns: A structure describing all available methods on the current wsdl.

Module Web.Sass

Description: Sass is a scripting language that is interpreted into Cascading Style Sheets (CSS). This module is a glue for libsass.
See also: SASS http://sass-lang.com/

Typedef s8: protected typedefstring(8bit) Web.Sass.s8
Description: Shorthand for string(8bit)

Constant HTTP_IMPORT_NONE
Constant HTTP_IMPORT_GREEDY
Constant HTTP_IMPORT_ANY

constantint Web.Sass.HTTP_IMPORT_NONE
constantint Web.Sass.HTTP_IMPORT_GREEDY
constantint Web.Sass.HTTP_IMPORT_ANY

Description

Description:

`HTTP_IMPORT_NONE`	Default value of `Compiler.http_import`. Prohibits imports over HTTP.
`HTTP_IMPORT_GREEDY`	Allow imports over HTTP only if the returned content type is `text/scss`.
`HTTP_IMPORT_ANY`	Anything goes.

Constant LIBSASS_VERSION: constantstring Web.Sass.LIBSASS_VERSION
Description: The libsass version, as a string, this module was compiled agains.

Constant SASS2SCSS_KEEP_COMMENT
Constant SASS2SCSS_STRIP_COMMENT
Constant SASS2SCSS_CONVERT_COMMENT: constantint Web.Sass.SASS2SCSS_KEEP_COMMENT
constantint Web.Sass.SASS2SCSS_STRIP_COMMENT
constantint Web.Sass.SASS2SCSS_CONVERT_COMMENT
Description: Constants that can be given as option to sass2scss().

Constant STYLE_NESTED
Constant STYLE_EXPANDED
Constant STYLE_COMPACT
Constant STYLE_COMPRESSED

constantint Web.Sass.STYLE_NESTED
constantint Web.Sass.STYLE_EXPANDED
constantint Web.Sass.STYLE_COMPACT
constantint Web.Sass.STYLE_COMPRESSED

Description

Styling of output. Use as argument to Compiler.set_output_style()

`STYLE_NESTED`	The default setting. The output will look like: `a { property: value; other-property: value;} a:hover { property: value;} b { property: value;}`
`STYLE_EXPANDED`	Fully expanded output: `a { property: value; other-property: value;} a:hover { property: value;} b { property: value;}`
`STYLE_COMPACT`	Somewhat minified output: `a { property: value; other-prop: value } a:hover { property: value;} b { property: value;}`
`STYLE_COMPRESSED`	Minified output `a{property:value;other-property:value}a:hover{property:value}b{property:value}`

Method libsass_language_version: stringlibsass_language_version()
Description: Returns the language version of Sass this module was compiled against

Method libsass_version: stringlibsass_version()
Description: Returns the libsass version this module was compiled against

Method sass2scss: string(8bit)sass2scss(string(8bit)data)
string(8bit)sass2scss(string(8bit)data, intoptions)
Description: Convert Sass syntax (i.e. indented syntax) to SCSS syntax.
Parameter data: Sass syntax text to convert to SCSS syntax.
Parameter options: This is a bitwise union of compression level (STYLE_NESTED, STYLE_EXPANDED, STYLE_COMPACT and $[STYLE_COMPRESSED]) and the SASS2SCSS_* constants SASS2SCSS_KEEP_COMMENT, SASS2SCSS_STRIP_COMMENT and SASS2SCSS_CONVERT_COMMENT. It defaults to STYLE_NESTED|SASS2SCSS_KEEP_COMMENT.
Returns: data converted to SCSS syntax.

Method sass2scss_version: stringsass2scss_version()
Description: Returns the sass2scss version this module was compiled against

Class Web.Sass.Api

Description

Low-level Sass/SCSS compiler.

You probably want to use Compiler instead of this class.

See also

Compiler

Variable include_path: string(8bit) Web.Sass.Api.include_path
Description: The base path of @imports. Note! This needs to be set when compile_string() is used.

Variable omit_source_map_url: bool Web.Sass.Api.omit_source_map_url
Description: Set whether writing the sourceMappingUrl=# or not.

Variable output_style: int(2bit) Web.Sass.Api.output_style
Description: Determines the level of compression on the generated output.
See also: STYLE_NESTED, STYLE_EXPANDED, STYLE_COMPACT and STYLE_COMPRESSED.

Variable precision: int Web.Sass.Api.precision
Description: Set the precision of fractional numbers. Default is 5.

Variable sass_syntax: bool Web.Sass.Api.sass_syntax
Description: Set whether the code is Sass syntax, i.e. indented syntax or not. Only necessary when using compile_string()

Variable source_comments: bool Web.Sass.Api.source_comments
Description: Emit comments in the generated CSS indicating the corresponding source line. Default is false.

Variable source_map_embed: bool Web.Sass.Api.source_map_embed
Description: Set whether embedding sourceMappingUrl=# as data uri or not.

Variable source_map_file: string(8bit) Web.Sass.Api.source_map_file
Description: Set the path of the source map file.

Variable source_map_root: string(8bit) Web.Sass.Api.source_map_root
Description: Set the root path of the source files, relative to where the source.map file is written.

Method compile_string

string(8bit)compile_string(string(8bit)source)

Description

Compiles the string source and returns the generated CSS.

Parameter source

The string to compile

Returns

A mapping with the generated CSS and source mapping file if such is set to be generated

`"css" : string(8bit)`	The generated CSS
`"map" : string(8bit)`	The generated source mapping data

Note

If the source contain @import directives you have to explicitly set the include path via include_path.

Class Web.Sass.Compiler

Description

Sass/SCSS compiler.

Example

Web.Sass.Compiler compiler =Web.Sass.Compiler();// Allow for HTTP imports, disallowed by default.
compiler->http_import =Web.Sass.HTTP_IMPORT_ANY;// Minify the output and create a source map file.
compiler->set_options((["output_style":Web.Sass.STYLE_COMPRESSED,"source_map_file":"path/to/write/source.map"]));if(mixed e =catch(compiler->compile_file("input.scss","output.css"))){
  werror("Failed compiling input.scss to output.css\n");}

Inherit Api: inherit Api : Api

Variable check_file_access: bool Web.Sass.Compiler.check_file_access
Description: Should file access be tested right away when paths are set or should that be left to Sass to handle? The default value is true.

Variable http_import: int(0..2) Web.Sass.Compiler.http_import
Description: If a Sass file is importing an external URI this flag determines if thats allowed at all, or if the content type of the imported file has to be in http_import_allow_ct, or if anything goes. Default is HTTP_IMPORT_NONE.
See also: HTTP_IMPORT_NONE, HTTP_IMPORT_GREEDY and HTTP_IMPORT_ANY.

Variable http_import_allow_ct: multiset(s8) Web.Sass.Compiler.http_import_allow_ct
Description: List of allowed content types if http_import is set to HTTP_IMPORT_GREEDY. The default is to allow text/scss and text/sass.

Method compile_file

mapping(s8:s8) compile_file(s8input_file)

Description

Compile the file input_file and return the result

Parameter input_file

The SCSS file to compile

Returns

A mapping with the generated CSS and source mapping file if such is set to be generated

`"css" : string(8bit)`	The generated CSS
`"map" : string(8bit)`	The generated source mapping data

Method compile_file: variantvoidcompile_file(s8input_file, s8output_file)
Description: Compile the file input_file and write the result to output_file. If a source mapping file is set to be generated either via set_options() or source_map_file it will be written as per the value set in the option.
Parameter input_file: The SCSS file to compile
Parameter output_file: The name of the CSS file to save the result in.

Method handle_sass_import

protectedstring|array(string(8bit)) handle_sass_import(string(8bit)path, void|string(8bit)absolute_path, void|string(8bit)relative_path)

Description

Resolve imports in sass/scss files.

Note

In general this method doesn't need to overloaded. In principle it's only necessary if the Sass files reside in a non-standard filesystem.

Note

If overloaded abs_path and rel_path is the absolute and relaive paths of the file containing the import statement path. If the Sass/SCSS files are located in a normal filesystem this method can return the contents of path as a string and libsass will resolve the paths to the imports by itself.

However, if the files are not located in a normal filesystem this function should return an array of two indices, where the first index should be the contents of path and the second the calculated absolute path of path.

Parameter path

This is the value of `path` in @import 'path'.

Parameter absolute_path

This is the absolute path of the file containing the @import statement.

Parameter relative_path

The relative path of absolute_path in relation to the prevoius absolute_path

Returns

`int(0)`	If undefined is returned the import resolution is given back to `libsass`.
`string(8bit)`	The contents of `path`
`array(string(8bit))`	if an array is returned it should contain two indices, where the first if the contents of `path` and the second should be the absolute path `path`. This is only useful (needed) if the Sass files doesn't reside in a normal filesystem that `libsass` can read.

Method set_options

voidset_options(mapping(s8:s8|int) opts)

Description

Set options to the SASS compiler.

Parameter opts

`"output_style" : int`	Any of the `STYLE_NESTED`, `STYLE_EXPANDED`, `STYLE_COMPACT` or `STYLE_COMPRESSED` constants. See also `output_style`.
`"include_path" : string(8bit)`	Path to root of incude files. See also `include_path`.
`"source_map_file" : string(8bit)`	File to write source map file to. See also `source_map_file`.
`"source_comments" : bool`	Turn on/off comments in the output containing info about the source file - line numbers and such. Default of `false`. See also `source_comments`.
`"source_map_embed" : bool`	Turn on/off if a source map should be embedded in the output or not. Default is `false`. See also `source_map_embed`.
`"source_map_root" : string(8bit)`	Set the root path of the source files, relative to where the source.map file is written. See also `source_map_root`
`"omit_source_map_url" : bool`	Omit the #sourceMappingURL or not. See also `omit_source_map_url`
`"sass_syntax" : bool`	Turn on/off Sass syntax, i.e. indented syntax. Only necessary when using `compile_string()`
`"precision" : int`	Floating point precision. See also `precision`.

Module Web.SocketIO

Description

This is an implementation of the Socket.IO server-side communication's driver. It basically is a real-time bidirectional object-oriented communication's protocol for communicating between a webbrowser and a server.

This module supports the following features:

Passing any arbitrarily deep nested data object which can be represented in basic JavaScript datatypes.
In addition to the normal JavaScript datatypes, it also supports passing (nested) binary blobs in an efficient manner.
Every message/event sent, allows for a callback acknowledge to be specified.
Acknowledge callbacks which will be called when the other side actively decides to acknowledge it (not automatically upon message reception).
Acknowledgement messages can carry an arbitrary amount of data.

The driver uses Web.EngineIO as the underlying protocol.

Example

Sample minimal implementation of a SocketIO server farm:
Web.SocketIO.Universe myuniverse;class myclient {inheritWeb.SocketIO.Client;}void echo(myclient id,function sendack,string namespace,string event,mixed ... data){
  id->emit(event, @data);if(sendack)
    sendack("Ack","me","harder");}void wsrequest(array(string) protocols,object req){
  httprequest(req);}void httprequest(object req){switch(req.not_query){case"/socket.io/":
      myclient client = myuniverse.farm(myclient, req);if(client)
        client->emit("Hello world!");break;}}int main(int argc,array(string) argv){
  myuniverse =Web.SocketIO.Universe();// Create universe
  myuniverse.register("", echo);// Register root namespaceProtocols.WebSocket.Port(httprequest, wsrequest, 80);return-1;}

See also

farm, Web.EngineIO, Protocols.WebSocket, http://github.com/socketio/socket.io-protocol, http://socket.io/

Variable options: finalmapping(string:mixed) Web.SocketIO.options
Description: Global options for all SocketIO instances.
See also: SocketIO.Universe.farm()

Method sendackcb: finalvoidsendackcb(function(mixed ... :void) fn, mixedarg)
Description: Convenience function to aid assist in sending the acknowledgment callback.

Enum Web.SocketIO.

Constant CONNECT
Constant DISCONNECT
Constant EVENT
Constant ACK
Constant ERROR
Constant BINARY_EVENT
Constant BINARY_ACK: constant Web.SocketIO.CONNECT
constant Web.SocketIO.DISCONNECT
constant Web.SocketIO.EVENT
constant Web.SocketIO.ACK
constant Web.SocketIO.ERROR
constant Web.SocketIO.BINARY_EVENT
constant Web.SocketIO.BINARY_ACK

Constant CONTAINER: constant Web.SocketIO.CONTAINER

Class Web.SocketIO.Client

Description: Runs a single Socket.IO session.

Variable onclose: function(void:void) Web.SocketIO.Client.onclose

Variable request: Protocols.WebSocket.Request Web.SocketIO.Client.request
Description: Contains the last request seen on this connection. Can be used to obtain cookies etc.
Note: Read only

Variable sid: string Web.SocketIO.Client.sid
Description: This session's unique session id.
Note: Read only

Method close: voidclose()
Description: Close the socket signalling the other side.

Method emit: finalvariantvoidemit(function(Client, mixed ... :void) ack_cb, stringevent, mixed ... data)
finalvariantvoidemit(stringevent, mixed ... data)
finalvariantvoidemit(function(Client, mixed ... :void) ack_cb, mapping(string:mixed) options, stringevent, mixed ... data)
finalvariantvoidemit(mapping(string:mixed) options, stringevent, mixed ... data)
Description: Send text or binary events to the client.

Method write: finalvoidwrite(arraydata, void|function(Client, mixed ... :void) ack_cb, void|mapping(string:mixed) options)
Description: Send text or binary messages to the client. When in doubt use the emit() interface instead. write() allows messages to be sent which do not have a string event-name up front.

Enum Web.SocketIO.Client.

Constant RUNNING
Constant SDISCONNECT
Constant RDISCONNECT: constant Web.SocketIO.Client.RUNNING
constant Web.SocketIO.Client.SDISCONNECT
constant Web.SocketIO.Client.RDISCONNECT

Class Web.SocketIO.Universe

Variable clients: finalmultiset(object) Web.SocketIO.Universe.clients
Description: All SocketIO sessions in this universe.

Method connect: mixedconnect(Clientclient, void|stringnewnamespace)
Description: Connects and disconnects clients.
Returns: 0 upon success, the error itself otherwise.

Method farm: Clientfarm(objectcreatetype, Protocols.WebSocket.Requestreq, void|mappingoptions)
Parameter options: Optional options to override the defaults. This parameter is passed down as-is to the underlying EngineIO.Socket.
See also: EngineIO.farm()

Method lookupcb: protectedstring|function(:void) lookupcb(stringnamespace, arraydata)

Method read: mixedread(stringnamespace, mixedid, function(mixed ... :void) sendackcb, mixed ... data)

Method register: variantvoidregister(stringnamespace, stringevent, void|function(Client, function(mixed ... :void), string, string, mixed ... :void) fn)
variantvoidregister(stringnamespace, void|function(Client, function(mixed ... :void), string, mixed ... :void) fn)
Description: Register worker callback on namespace and event. There can be only one worker per tuple. Workers can be unregistered by omitting fn. Having a default worker per namespace in addition zero or more event specific ones, is supported.

Method seed: protected.EngineIO.Socketseed(Protocols.WebSocket.Requestreq, void|mappingoptions)
Description: Seed farm with EngineIO connection.

Module Yp

Description: 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.

Inherit "___Yp": inherit "___Yp" : "___Yp"

Method default_domain: stringdefault_domain()
Description: Returns the default yp-domain.

Class Yp.Domain

Method all

mapping(string:string) all(stringmap)

Description

Returns the whole map as a mapping.

map is the YP-map to search in. This must be the full map name, you have to use passwd.byname instead of just passwd.

Method create
Method bind

Yp.DomainYp.Domain(string|voiddomain)
voidbind(stringdomain)

Description

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.

See also

Yp.default_domain()

Method map

voidmap(stringmap, function(string, string:void) fun)

Description

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.

Method match: stringmatch(stringmap, stringkey)
Description: Search for the key key in the Yp-map map.
Returns: If there is no key in the map, 0 (zero) will be returned, otherwise the string matching the key will be returned.
Note: key must match exactly, no pattern matching of any kind is done.

Method order

intorder(stringmap)

Description

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.

Method server: stringserver(stringmap)
Description: Returns the hostname of the server serving the map map. map is the YP-map to search in. This must be the full map name. eg passwd.byname instead of just passwd.

Class Yp.Map

Description: Network Information Service aka YP map.

Method _indices: array(string) indices(Yp.Maparg)
Description: Return the keys of the map.

Method _sizeof: intsizeof(Yp.Maparg)
Description: Return the number of entries in this map.

Method _values: array(string) values(Yp.Maparg)
Description: Return the values of the map.

Method match
Method `[]: stringmatch(stringkey)
string res = Yp.Map()[ key ]
Description: 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.
Note: key must match exactly, no pattern matching of any kind is done.

Method all: mapping(string:string) all()
Description: Returns the whole map as a mapping.

Method cast: (mapping)Yp.Map()
Description: Convert the map to a mapping

Method create

Yp.MapYp.Map(stringmap, string|voiddomain)

Description

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.

Note

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.

Method map

voidmap(function(string, string:void) fun)

Description

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

Method order: intorder()
Description: Return the order number for this map.

Method server: stringserver()
Description: Return the server that provides this map.

Module _Charset

Description

Low-level tables and code for the Charset module.

This is probably not the module you want; try the Charset module.

See also

Charset

Method rfc1345

objectrfc1345(stringcharset, bool|voidencoder, string|voidrep, function(string:string)|voidrepcb)

Description

Low-level charset codec factory.

Parameter charset

Canonical name of character set to look up.

Parameter encoder

Flag indicating that an encoder and not a decoder is wanted.

Parameter rep

String to use for characters not representable in the charset. Only used for encoders.

Parameter repcb

Function to call for characters not representable in the charset. Only used for encoders.

This is the main entrypoint into the low-level _Charset module.

Returns

Returns a suitable encoder or decoder on success and 0 (zero) on failure.

See also

Charset.encoder(), Charset.decoder()

Module _Ffmpeg

Constant CODEC_ID_NONE
Constant CODEC_ID_AC3
Constant CODEC_ID_ADPCM_IMA_QT
Constant CODEC_ID_ADPCM_IMA_WAV
Constant CODEC_ID_ADPCM_MS
Constant CODEC_ID_H263
Constant CODEC_ID_H263I
Constant CODEC_ID_H263P
Constant CODEC_ID_MJPEG
Constant CODEC_ID_MPEG1VIDEO
Constant CODEC_ID_MPEG4
Constant CODEC_ID_MP2
Constant CODEC_ID_MP3LAME
Constant CODEC_ID_MSMPEG4V1
Constant CODEC_ID_MSMPEG4V2
Constant CODEC_ID_MSMPEG4V3
Constant CODEC_ID_PCM_ALAW
Constant CODEC_ID_PCM_MULAW
Constant CODEC_ID_PCM_S16BE
Constant CODEC_ID_PCM_S16LE
Constant CODEC_ID_PCM_S8
Constant CODEC_ID_PCM_U16BE
Constant CODEC_ID_PCM_U16LE
Constant CODEC_ID_PCM_U8
Constant CODEC_ID_RAWVIDEO
Constant CODEC_ID_RV10
Constant CODEC_ID_SVQ1
Constant CODEC_ID_VORBIS
Constant CODEC_ID_WMV1
Constant CODEC_ID_WMV2: constant _Ffmpeg.CODEC_ID_NONE
constant _Ffmpeg.CODEC_ID_AC3
constant _Ffmpeg.CODEC_ID_ADPCM_IMA_QT
constant _Ffmpeg.CODEC_ID_ADPCM_IMA_WAV
constant _Ffmpeg.CODEC_ID_ADPCM_MS
constant _Ffmpeg.CODEC_ID_H263
constant _Ffmpeg.CODEC_ID_H263I
constant _Ffmpeg.CODEC_ID_H263P
constant _Ffmpeg.CODEC_ID_MJPEG
constant _Ffmpeg.CODEC_ID_MPEG1VIDEO
constant _Ffmpeg.CODEC_ID_MPEG4
constant _Ffmpeg.CODEC_ID_MP2
constant _Ffmpeg.CODEC_ID_MP3LAME
constant _Ffmpeg.CODEC_ID_MSMPEG4V1
constant _Ffmpeg.CODEC_ID_MSMPEG4V2
constant _Ffmpeg.CODEC_ID_MSMPEG4V3
constant _Ffmpeg.CODEC_ID_PCM_ALAW
constant _Ffmpeg.CODEC_ID_PCM_MULAW
constant _Ffmpeg.CODEC_ID_PCM_S16BE
constant _Ffmpeg.CODEC_ID_PCM_S16LE
constant _Ffmpeg.CODEC_ID_PCM_S8
constant _Ffmpeg.CODEC_ID_PCM_U16BE
constant _Ffmpeg.CODEC_ID_PCM_U16LE
constant _Ffmpeg.CODEC_ID_PCM_U8
constant _Ffmpeg.CODEC_ID_RAWVIDEO
constant _Ffmpeg.CODEC_ID_RV10
constant _Ffmpeg.CODEC_ID_SVQ1
constant _Ffmpeg.CODEC_ID_VORBIS
constant _Ffmpeg.CODEC_ID_WMV1
constant _Ffmpeg.CODEC_ID_WMV2
Description: Various audio and video codecs.
Note: The list of supported codecs depends on Ffmpeg library.

Constant CODEC_TYPE_AUDIO
Constant CODEC_TYPE_VIDEO: constant _Ffmpeg.CODEC_TYPE_AUDIO
constant _Ffmpeg.CODEC_TYPE_VIDEO
Description: Type of codec.

Class _Ffmpeg.ffmpeg

Description: Implements support of all codecs from a nice project Ffmpeg. You can find more info about it at http://ffmpeg.sf.net/.

Method create: _Ffmpeg.ffmpeg_Ffmpeg.ffmpeg(intcodec_name, intencoder)
Description: Create decoder or encoder object.
Parameter codec_name: Internal number of codec, eg. CODEC_ID_MP2.
Parameter encoder: If true, encoder object will be created, decoder object otherwise.

Method decode: mapping|intdecode(stringdata)
Description: Returns a mapping with the new decoded frame and lenght of data which was used for decoding.

Method decode: intdecode(stringdata, function(:void) shuffler)
Description: Decode all data buffer and pass result to shuffler. Returns 1 on success, 0 otherwise.
Note: Shuffler variant isn't implemented, yet.
Note: Usable only in decoder.
See also: create()

Method encode: mapping|intencode(stringdata)
Description: Returns mapping with new encoded frame and length of data which was used for encoding.

Method encode: intencode(stringdata, function(:void) shuffler)
Description: Returns 1 on success, 0 otherwise.
Note: Usable only in encoder
See also: create()

Method get_codec_info: mapping|intget_codec_info()
Description: Returns mapping with info of used codec.
See also: list_codecs()

Method get_codec_status: mapping|intget_codec_status()
Description: Returns a mapping with the actual codec parameters.
See also: set_codec_param()

Method list_codecs: array(mapping) list_codecs()
Description: Gets all supported codecs.
Returns: Array of mapping with codec features.

Method set_codec_param: intset_codec_param(stringname, mixedvalue)
Description: Sets one codec parameter
Parameter name: The name of parameter. One of "sample_rate", "bit_rate", "channels".
Returns: Returns 1 on success, 0 otherwise (parameter not known).
See also: get_codec_params()

Module _Stdio

Class _Stdio.Buffer

Description

A buffer to use as input or buffering when doing I/O. It is similar to String.Buffer, but can only contain 8bit data and is designed for protocol parsing. It is optimized for reading from the beginning and adding to the end, and will try to minimise the amount of data copying that is done.

The class maintains two separate offsets, one for reading and one for writing. The functions that add data all do so at the write offset (the end of the buffer), and reading is done from the read offset (the start of the buffer).

The class can also be used to directly read from and write to filedescriptors if so desired. This eliminates at least one memory copy.

Note

The "avoid copy" part means that a Buffer will never shrink unless you call the trim function.

Method __set_on_write: void__set_on_write(function(:void) write_callback)
Description: This tells the buffer to trigger the write callback for the specified file descriptor when data is added to the buffer.
Note: This is used internally by Stdio.File and SSL.File to handle nonblocking buffered mode, and is not necessarily intended to be used directly by anything but implementations of File or Stream like programs. Do not use this yourself on buffers with Files or Streams in buffer modes.

Method _encode
Method _decode: string(8bit)encode_value(_Stdio.Bufferdata)
_Stdio.Bufferdecode_value(string(8bit)data)
Description: Encode and decode Stdio.Buffer objects. Only the buffer data is kept, no other state is saved.

Method _search

int(-1..)search(_Stdio.Bufferfrom, int(8bit)character, int|voidstart, int(0..)|voidend)

Description

Search forward from the indicated start position for the specified character.

Parameter character

Character to search for.

Parameter start

Start position relative to the current read position of the buffer.

Negative start values are supported and indicate positions prior to the current read position.

Parameter end

Don't search past this position of the buffer.

Returns

Returns the first found position of character relative to the current read position of the buffer on success, and UNDEFINED on not found. The read position is not advanced.

See also

read_cstring(), search(), lfun::_search()

Method _search

int(-1..)search(_Stdio.Bufferfrom, string(8bit)substring, int|voidstart, int|voidend)

Description

Search forward from the indicated start position for the specified substring.

Parameter substring

Substring to search for.

Parameter start

Start position relative to the current read position of the buffer.

Negative start values are supported and indicate positions prior to the current read position.

Parameter end

Don't search past this position of the buffer.

Returns

Returns the first found position of substring relative to the current read position of the buffer on success, and UNDEFINED on not found. The read position is not advanced.

See also

read_cstring(), search(), lfun::_search()

Method _sizeof: intsizeof(_Stdio.Bufferarg)
Description: Returns the buffer size, in bytes. This is how much you can read from the buffer until it runs out of data.

Method `[..]: string(8bit) res = _Stdio.Buffer()[start..end]
Description: Range operator.
Returns: Returns a string of the characters at offset low through high. Returns the empty string if no data is available in the range.

Method `[]: int(-1..255) res = _Stdio.Buffer()[ off ]
Description: Return the character at the specified offset.
Returns: Returns the character at offset off on success, and -1 otherwise.
Note: Indexing with negative offsets was not supported in Pike 8.0 and earlier.

Method `[]=: _Stdio.Buffer()[ off ] = char
Description: Set the character at the specified offset to char.
Note: Indexing with negative offsets was not supported in Pike 8.0 and earlier.

Method add

Bufferadd(AddArgument ... data)

Description

private typedef System.Memory|Stdio.Buffer|String.Buffer BufferObject;
 private typedef BufferObject|string(8bit)|int(8bit)|array(AddArgument) AddArgument;

Add the items in data to the end of the buffer.

The supported argument types are:

`string(8bit)`	An eight bit string.
`int(8bit)`	A single byte
`System.Memory`	A chunk of memory. The whole memory area is added.
`Stdio.Buffer`	A chunk of memory. The whole memory area is added.
`String.Buffer`	A chunk of memory. The whole memory area is added.
`array(AddArgument)`	Add all elements in the array individually. Each element may be any one of the types listed here.

See also

sprintf, add_int8, add_int16, add_int32, add_int and add_hstring

Method add_hint

Bufferadd_hint(inti, int(0..)size_width)

Description

First add the size of the integer when encoded to base 256 as a size_width integer, then add the integer to the buffer, both in network byte order.

size_width must be less than Int.NATIVE_MAX.

Method add_hstring

Bufferadd_hstring(string(8bit)data, int(0..)size_size)
Bufferadd_hstring(Stdio.Bufferdata, int(0..)size_size)
Bufferadd_hstring(System.Memorydata, int(0..)size_size)
Bufferadd_hstring(String.Bufferdata, int(0..)size_size)
Bufferadd_hstring(int(8bit)data, int(0..)size_size)
Bufferadd_hstring(arraydata, int(0..)size_size)
Bufferadd_hstring(int|string(8bit)|Stdio.Buffer|System.Memory|arraydata, int(0..)size_size, int(0..)offset)

Description

Adds length of data followed by data to the buffer.

This is identical to sprintf("%"+size_size+"H",(string)Stdio.Buffer(data)) but significantly faster.

size_size is the number of bytes used to represent the length of the data. It must be less than Int.NATIVE_MAX.

offset is added to the length of the data prior to writing out the length. Typical usage involves adding size_size to account for the room used by the size.

The supported data argument types are

`int(8bit)`	An eight bit character.
`string(8bit)`	An eight bit string.
`System.Memory`	A chunk of memory. The whole memory area is added.
`Stdio.Buffer`	A chunk of memory. The whole memory area is added.
`String.Buffer`	A chunk of memory. The whole memory area is added.
`array`	Add all elements in the array individually. Each element may be any one of the types listed here.

Method add_int

Bufferadd_int(inti, int(0..)width)

Description

Adds a generic integer to the buffer as an (width*8)bit network byteorder number.

width must be less than Int.NATIVE_MAX.

Method add_int16: Bufferadd_int16(int(16bit))
Description: Add a 16-bit network byte order value to the buffer

Method add_int16: Bufferadd_int16(Gmp.mpz)
Description: Add a 16-bit network byte order value to the buffer

Method add_int32: Bufferadd_int32(inti)
Description: Adds a 32 bit network byte order value to the buffer

Method add_int32: Bufferadd_int32(Gmp.mpzi)
Description: Adds a 32 bit network byte order value to the buffer

Method add_int8: Bufferadd_int8(int(8bit))
Description: Adds a single byte to the buffer.

Method add_int8: Bufferadd_int8(Gmp.mpz)
Description: Adds a single byte to the buffer.

Method add_ints

Bufferadd_ints(array(int) integers, int(8bit)len)

Description

Add the integers in the specified array, len bytes per int. Equivalent to calling add_int for each integer, but faster, and if an error occurs the buffer will contain no new data. Either all or none of the integers will be added.

Errors can occur if one of the elements in integers is not actually an integer, if sizeof(integers)*len is bigger than can be represented in a size_t, or if the buffer cannot grow due to an out of memory condition.

Method add_padding: Bufferadd_padding(int(0..)nbytes, int(8bit)|voidbyte)
Description: Add nbytes bytes of padding, if byte is not specified the area will be filled with 0's, otherwise the specified byte will be repeated.

Method allocate: voidallocate(int(0..)n)
Description: Make sure that at least n bytes of space are available in this buffer.

Method cast: (string(8bit))_Stdio.Buffer()
Description: Convert the buffer to a string.
Note: This only works for buffers whose length is less than 0x7fffffff.

Method clear: voidclear()
Description: Clear the buffer.

Method consume

int(0..)|int(-1)consume(int(0..)n)

Description

Discard the first n bytes from the buffer

Returns -1 on error and the amount of space still left otherwise.

Method create

_Stdio.Buffer_Stdio.Buffer(int|voidlen)
_Stdio.Buffer_Stdio.Buffer(string(8bit)contents)
_Stdio.Buffer_Stdio.Buffer(System.Memory|String.Buffercontents)

Description

If passed an integer or no argument, create a buffer of that size, or if no argument is given, 226 bytes.

If contents are specified a new buffer with the contents of the given string/System.Memory or String.Buffer will be created.

Note

In the String.Buffer case the data has to be copied unless there is only one reference to the String.Buffer object, since modifications of the String.Buffer would cause the Buffer to point into invalid memory.

In all other cases this will not copy the string data, instead data will be read from the source until it needs to be modified, so the buffer creation is fast regardless of the length of the string.

However, as an example, if the buffer is created with a 100Gb System.Memory mmap:ed file as the contents and you later on try to modify the buffer using one of the add functions (or sprintf and similar) the old contents will be copied.

You can use read_only() to avoid accidents.

Method input_from

int(-1..)input_from(Stdio.Streamf, int|voidnbytes)

Description

Read data from f into this buffer. If nbytes is not specified, read until there is no more data to read (currently).

Returns the amount of data that was read, or -1 on read error.

Note

Please note that this funcition will read all data from the filedescriptor unless it's set to be non-blocking.

Method lock: objectlock()
Description: Makes this buffer read only until the returned object is released.
Note: This currently simply returns a 0-length subbuffer.

Method match

__deprecated__string(8bit)|int|float|arraymatch(string(8bit)format)

Description

Reads data from the beginning of the buffer to match the specifed format, then return the match.

The non-matching data will be left in the buffer.

This function is very similar to sscanf, but the result is the sum of the matches. Most useful to match a single value.

Returns

Returns the sum of the matching %-expressions, "" if a prefix (but no %-expression) matches and UNDEFINED on mismatch. Note that the addition may throw errors.

Note

Prior to Pike 9.0 0 was returned on mismatch and format was returned on a prefix match.

Example

// Get the next whitespace separated word from the buffer.
    buffer->match("%*[ \t\r\n]%[^ \t\r\n]");// Get the next integer as a string.
    buffer->match("%0s%d");

Deprecated

Replaced by sscanf.

See also

sscanf(), predef::sscanf(), array_sscanf()

Method output_to

int(-1..)output_to(Stdio.Stream|function(string(8bit):int) fun, int(0..)|voidnbytes)

Description

Write data from the buffer to the indicated file.

Parameter fun

Write function. Either one of:

`Stdio.Stream`	A file object in which the function `write()` will be called.
`function(string(8bit):int)`	A function which will be called with a `string(8bit)` to write and is expected to return an `int` indicating the number of bytes successfully written or `-1` on failure.

Parameter nbytes

If nbytes is not specified the whole buffer will be written if possible. Otherwise at most nbytes will be written.

Returns

Will return the number of bytes that have been written successfully.

If no bytes have been written successfully and fun() failed with an error, -1 will be returned.

This function is similar to

int(-1..) output_to(Stdio.Stream|function(string(8bit):int) fun,int(0..)|void nbytes){if(objectp(fun)) fun =([object]fun)->write;int(0..) total;while(sizeof(this)){int(0..) bytes = undefinedp(nbytes)?sizeof(this):nbytes;if(bytes > 0x8000) bytes = 0x8000;string(8bit) chunk = read(bytes);int(-1..) written =([function]fun)(chunk);if(written <= 0){return total || written;}
      total += written;if(written < sizeof(chunk)){
        unread(sizeof(chunk)- written);}if(!undefinedp(nbytes)){
        nbytes -= written;if(!nbytes){break;}}}return total;}

Deprecated

This function is going to get deprecated. In case you want to use it against an Stdio.File like object, please consider using the f->write(buf) API. If you want to use it against a custom write function, please consider supporting the f->write(buf) API in it.

Method range_error

protectedboolrange_error(inthowmuch)

Description

This function is called when an attempt is made to read out of bounds.

The default implementation simply returns 0 (zero).

Override this function to change the behavior.

Parameter howmuch

The argument howmuch indicates how much data is needed:

(1..)

Need howmuch bytes more

0

The amount of data needed is not certain. This most often happens when sscanf or read_json is used

(..-1)

Tried to unread -howmuch bytes. There is usually no way to satisfy the requested range.

The only supported way is to extract the data from the buffer, add the requested amount of "go backbuffer", add the data back, and forward -howmuch bytes.

Returns

true if the operation should be retried, false otherwise.

Do not return true unless you have added data to the buffer, doing so could result in an infinite loop (since no data is added, the range_error will be called again immediately).

Method read

string(8bit)read()

Description

Read all data from the buffer.

If there is not enough data available this returns 0.

This is basically equivalent to (string)buffer, but it also removes the data from the buffer.

See also

try_read()

Method read

string(8bit)read(int(0..)n)

Description

Read n bytes of data from the buffer.

If there is not enough data available this returns 0.

See also

try_read()

Method read_buffer

Bufferread_buffer(int(0..)n)
Bufferread_buffer(int(0..)n, boolcopy)

Description

Same as read, but returns the result as an Buffer.

No data is copied unless copy is specified and true, the new buffer points into the old one.

Note

As long as the subbuffer exists the main buffer is locked in memory.

Usually this is OK, since it often represents something that should be parsed before the next whatever is extracted from the buffer, but do take care.

Method read_cstring

string(8bit)read_cstring(void|int(8bit)sentinel, void|int(8bit)escape)

Description

Reads a \0 terminated C-string and returns the string excluding the terminating \0.

If there is not enough data available return UNDEFINED.

Note that pike string can not be longer than 0x7fffffff bytes (~2Gb).

Parameter sentinel

A different character can be used as end sentinel of the string.

Parameter escape

An optional character used as a prefix to quote the following character. UNDEFINED and the same value as sentinel mean that there is no escape character.

Note

Escape characters (if any) are left untouched in the returned string.

See also

_search()

Method read_hbuffer

Bufferread_hbuffer(intn)
Bufferread_hbuffer(intn, boolcopy)

Description

Same as read_hstring, but returns the result as an Buffer.

No data is copied unless copy is specified and true, the new buffer points into the old one.

Note

As long as the subbuffer exists no data can be added to the main buffer.

Usually this is OK, since it often represents something that should be parsed before the next whatever is extracted from the buffer, but do take care.

If you need to unlink the new buffer after it has been created, call trim in it.

Method read_hint

intread_hint(int(0..)n)

Description

Read a network byte order unsigned number of size n*8 bits, then read another network byte order number of the size indicated by the first size.

Will return -1 if there is not enough buffer space available unless error mode is set to throw errors.

Method read_hstring

string(8bit)read_hstring(int(0..)n, void|intoffset)

Description

Identical in functionality to read(read_number(n)) but faster.

Read a network byte order number of size n*8 bits, then return the indicated number of bytes as a string.

offset is substracted from the specified length prior to reading the string. Typical usage involves substracting n to account for the room used by the size.

If there is not enough data available return 0.

Note that pike string can not be longer than 0x7fffffff bytes (~2Gb).

Method read_int

intread_int(int(0..)n)

Description

Read a network byte order unsigned number of size n*8 bits, then return it.

Will return -1 if there is not enough buffer space available unless error mode is set to throw errors.

See also

read_le_int

Method read_int16: int(16bit)read_int16()

Method read_int24: int(24bit)read_int24()

Method read_int32: int(32bit)read_int32()

Method read_int8: int(8bit)read_int8()

Method read_ints

array(int) read_ints(intn, int(8bit)width)

Description

Read a list of n network byte order unsigned numbers each of size width*8 bits, then return it.

Will return 0 if there is not enough buffer space available unless error mode is set to throw errors.

Method read_json

mixedread_json(int|voidrequire_whitespace_separator)

Description

Read a single JSON expression from the buffer and return it.

If require_whitespace_separator is true there must be a whitespace after each json value (as an example, newline or space).

The JSON is assumed to be utf-8 encoded.

Returns

UNDEFINED if no data is available to read. The read value otherwise.

Note

Unless whitespaces are required this function only really work correctly with objects, arrays and strings.

There is really no way to see where one value starts and the other ends for most other cases

Method read_le_int

intread_le_int(int(0..)n)

Description

Read a little endian byte order unsigned number of size n*8 bits, then return it.

Will return -1 if there is not enough buffer space available unless error mode is set to throw errors.

See also

read_int

Method read_only: voidread_only()
Description: This makes the existing data in the buffer permanently read only.
Note: You can use lock() to do this temporarily.

Method read_sint

intread_sint(intsize)

Description

Read a network byte order two:s complement signed number of size n*8 bits, then return it.

Will return UNDEFINED if there is not enough buffer space available unless error mode is set to throw errors.

Method rewind_on_error
Method rewind_key

RewindKeyrewind_on_error()
RewindKeyrewind_key()

Description

These functions are very similar. The rewind_on_error variant will create an object that, when it goes out of scope without having been destructed explicitly, will cause the buffer to rewind to the location it had when this function is called.

This will happen if you throw an error or otherwise let the object fall out of scope.

Use destruct(RewindKey) or RewindKey.release to stop the buffer from being rewound.

The second version (rewind_key) requires you to explicitly call RewindKey.rewind to do the rewind.

Take some care with these objects, if you create multiple ones at once the results might be somewhat confusing if you do not release them in the reverse order they were created in (then again, you almost certainly really only need one)

You can call RewindKey.update in the generated object to change where it will be rewound to.

The typical use-case of this functionality is when parsing a packet protocol with variable length packets where the length is not immediately known. It saves you from keeping track of how much to rewind if you had not actually gotten the whole packet yet.

Example

void parse_packet(Stdio.Buffer b ){Stdio.Buffer.RewindKey rewind = b->rewind_on_error();
  b->set_error_mode(1);switch( b->read_int8())// packet type{case DATA:int channel = b->read_int8();Stdio.Buffer data = b->read_hbuffer( 4 );// we have read the whole packet, so no longer rewind on error.
      rewind->release();return handle_data_packet( channel, data );}}

Note

Just calling rewind_on_error without assigning the return value to something will not do anything. You need to keep the object around while the rewind-to position is still valid.

Keeping the object around forbids the buffer from moving data inside itself, this means that it can only grow. So do not keep the rewind key when it is not needed.

Method set_error_mode

Bufferset_error_mode(intm)
Bufferset_error_mode(programm)

Description

Set the error mode of this buffer to m.

If true operations that would normally return 0 (like trying to read too much) will instead throw an error. If m is a program a clone of it will be thrown on error.

This is useful when parsing received data, you do not have to verify that each and every read operation suceeds.

However, the non-error mode is more useful when checking to see if a packet/segment/whatever has arrived.

The thrown error object will have the constant buffer_error set to a non-false value.

Example

void read_callback(int i,string(8bit) new_data){
  inbuffer->add( new_data );while( Buffer packet = inbuffer->read_hbuffer(2)){
    packet->set_error_mode(Buffer.THROW_ERROR);if(mixed e =catch( handle_packet( packet )))if( e->buffer_error )
        protocol_error();// illegal data in packetelse
        throw(e);// the other code did something bad}}void handle_packet( Buffer pack ){switch( pack->read_int8()){
    ...
  case HEADER_FRAME:int num_headers = pack->read_int32();for(int i = 0; i<num_headers; i++ )
     headers[pack->read_hstring(2)]= pack->read_hstring(2);
    ...
  }}

Method set_max_waste

voidset_max_waste(floatfactor)

Description

Configure how much free space should be allowed, at most, as a factor of the current buffer size.

The default is 0.5, leaving at most half the buffer as waste.

Method sprintf

Buffersprintf(strict_sprintf_formatformat, sprintf_args ... args)

Description

Appends the output from sprintf at the end of the buffer.

This is somewhat faster than add(sprintf(...)) since no intermediate string is created.

Method sscanf

arraysscanf(string(8bit)format)

Description

Reads data from the beginning of the buffer to match the specifed format, then return an array with the matches.

The non-matching data will be left in the buffer.

See array_sscanf for more information.

See also

match(), predef::sscanf(), array_sscanf()

Method trim

voidtrim()

Description

Frees unused memory.

Note that calling this function excessively will slow things down, since the data often has to be copied.

Note

This function could possibly throw an out-of-memory error if the realloc fails to find a new (smaller) memory area.

Method truncate

int(0..)|int(-1)truncate(int(0..)n)

Description

Truncates the buffer to a length of n bytes.

Returns -1 on error and the number of bytes removed otherwise.

Method try_read: string(8bit)try_read(int(0..)len)
Description: Attempt to read some data from the buffer.
Parameter len: Read at most len bytes from the buffer.
Returns: If the buffer contains less than len bytes of data, the entire buffer contents are returned. Otherwise the first len bytes are returned.
See also: read()

Method unread

int(0..)|int(-1)unread(int(0..)n)

Description

Rewind the buffer n bytes.

Returns

This function returns how many more bytes of buffer is available to rewind, or -1 on error.

Note

Unless you add new data to the buffer using any of the add functions you can always rewind.

You can call unread(0) to see how much.

Class _Stdio.Buffer.RewindKey

Description

The return value of Buffer.rewind_on_error() and Buffer.rewind_key()

This object will cause the buffer to unwind to the position it was at when the object was created either when it is released (when it falls out of scope, explicit destruct does not count) or when rewind is called, depending on which function was used to create it.

Method release: voidrelease()
Description: Do not rewind if the object is released.
Note: This is equivalent to calling destruct() on the object

Method rewind: voidrewind()
Description: Rewinds the buffer explicitly.
Note: Destructs this RewindKey

Method update: voidupdate()
Description: Update the location the buffer will be rewound to to the current position of the buffer.

Class _Stdio.Fd

Method tcdrain: booltcdrain()
Description: Wait for transmission buffers to empty.
Returns: Returns 1 on success and 0 (zero) on failure.
See also: tcflush()

Method tcflush

booltcflush(string(7bit)|voidflush_direction)

Description

Flush queued terminal control messages.

Parameter flush_direction

`"TCIFLUSH"`	Flush received but not read.
`"TCOFLUSH"`	Flush written but not transmitted.
`"TCIOFLUSH"`	Flush both of the above. Default.

Returns

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

See also

tcdrain()

Method tcgetattr
Method tcsetattr

mapping(string(7bit):int) tcgetattr()
inttcsetattr(mapping(string(7bit):int) attr)
inttcsetattr(mapping(string(7bit):int) attr, string(7bit)when)

Description

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

`"ispeed" : int(-1..)`	In baud rate.
`"ospeed" : int(-1..)`	Out baud rate.
`"csize" : int(-1)\|int(5..8)`	Character size in bits.
`"rows" : int`	Terminal rows.
`"columns" : int`	Terminal columns.
`flag_name : bool`	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.
`character_name : int(8bit)`	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.

Example

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

Note

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

Bugs

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

See also

tcsetsize()

Method tcsendbreak

booltcsendbreak(int|voidduration)

Description

Send a break signal.

Parameter duration

Duration to send the signal for. 0 (zero) causes a break signal to be sent for between 0.25 and 0.5 seconds. Other values are operating system dependent:

SunOS: The number of joined break signals as above.
Linux, AIX, Digital Unix, Tru64: The time in milliseconds.
FreeBSD, NetBSD, HP-UX, MacOS: The value is ignored.
Solaris, Unixware: The behavior is changed to be similar to tcdrain().

Returns

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

Method tcsetsize: booltcsetsize(introws, intcols)
Description: Set the number of rows and columns for a terminal.
Returns: Returns 1 on success and 0 (zero) on failure.
See also: tcgetattr(), tcsetattr()

Class _Stdio.UDP

Constant MSG_OOB: constant _Stdio.UDP.MSG_OOB
Description: Flag to specify to read() to read out of band packets.

Constant MSG_PEEK: constant _Stdio.UDP.MSG_PEEK
Description: Flag to specify to read() to cause it to not remove the packet from the input buffer.

Variable _fd: UDP _Stdio.UDP._fd
Note: Read only

Method add_membership

intadd_membership(stringgroup, void|stringaddress)

Description

Join a multicast group.

Parameter group

group contains the address of the multicast group the application wants to join. It must be a valid multicast address.

Parameter address

address is the address of the local interface with which the system should join to the multicast group. If not provided the system will select an appropriate interface.

See also the Unix man page for setsocketopt IPPROTO_IP IP_ADD_MEMBERSHIP and IPPROTO_IPV6 IPV6_JOIN_GROUP.

Note

The address parameter is currently not supported for IPv6.

Note

This function did not support IPv6 in Pike 7.8 and earlier.

See also

drop_membership()

Method bind

UDPbind(int|stringport, string|voidaddress, string|boolno_reuseaddr)

Description

Binds a port for receiving or transmitting UDP.

Parameter port

Either a port number or the name of a service as listed in /etc/services.

Parameter address

Local address to bind to.

Parameter no_reuseaddr

If set to 1, Pike will not set the SO_REUSEADDR option on the UDP port.

Note

SO_REUSEADDR is never applied when binding a random port (bind(0)).

In general, SO_REUSEADDR is not desirable on UDP ports. Unless used for receiving multicast, be sure to never bind a non-random port without setting no_reuseaddr to 1.

Throws

Throws error when unable to bind port.

Method close: boolclose()
Description: Closes an open UDP port.
Note: This method was introduced in Pike 7.5.

Method connect

boolconnect(stringaddress, int|stringport)

Description

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

Returns 1 on success, 0 (zero) otherwise.

Note

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.

See also

bind(), query_address()

Method drop_membership

intdrop_membership(stringgroup, void|stringaddress)

Description

Leave a multicast group.

Parameter group

group contains the address of the multicast group the application wants to join. It must be a valid multicast address.

Parameter address

address is the address of the local interface with which the system should join to the multicast group. If not provided the system will select an appropriate interface.

See also the Unix man page for setsocketopt IPPROTO_IP IP_DROP_MEMBERSHIP and IPPROTO_IPV6 IPV6_LEAVE_GROUP.

Note

The address parameter is currently not supported for IPv6.

Note

This function did not support IPv6 in Pike 7.8 and earlier.

See also

add_membership()

Method dup: Stdio.UDPdup()
Description: Duplicate the udp socket.
See also: fd_factory()

Method enable_broadcast: boolenable_broadcast()
Description: 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: Returns 1 on success, 0 (zero) otherwise.
Note: This is normally only avalable to root users.

Method enable_multicast

boolenable_multicast(stringreply_address)

Description

Set the local device for a multicast socket.

Parameter reply_address

Local address that should appear in the multicast packets.

See also the Unix man page for setsocketopt IPPROTO_IP IP_MULTICAST_IF and IPPROTO_IPV6 IPV6_MULTICAST_IF.

Note

This function did not support IPv6 in Pike 7.8.

Method errno: interrno()
Description: Returns the error code for the last command on this object. Error code is normally cleared when a command is successful.

Method fd_factory

UDPfd_factory()

Description

Factory creating Stdio.UDP objects.

This function is called by dup() and other functions creating new UDP objects.

The default implementation calls object_program(this_object())() to create the new object, and returns the UDP inherit in it.

Note

Note that this function must return the UDP inherit in the object.

See also

dup(), Stdio.File()->fd_factory()

Method get_type: array(int) get_type()
Description: Returns socket type and protocol family.

Method query_address: stringquery_address()
Description: 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.

Method query_backend: Pike.Backendquery_backend()
Description: Return the backend used for the read callback.
See also: set_backend

Method query_fd: intquery_fd()
Description: Gets the file descriptor for this UDP port.

Method query_mtu

intquery_mtu()

Description

Get the Max Transfer Unit for the object (if any).

Returns

`-1`	Returns `-1` if the object is not a socket or if the mtu is unknown.
`(1..)`	Returns a positive value with the mtu on success.

Note

The returned value is adjusted to take account for the IP and UDP headers, so that it should be usable without further adjustment unless further IP options are in use.

Method read

mapping(string:int|string) read()
mapping(string:int|string) read(intflag)

Description

Read from the UDP socket.

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

Returns

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

See also

set_read_callback(), MSG_OOB, MSG_PEEK

Method send

intsend(stringto, int|stringport, stringmessage)
intsend(stringto, int|stringport, stringmessage, intflags)

Description

Send data to a UDP socket.

Parameter to

The recipient address. For connect()ed objects specifying a recipient of either UNDEFINED or "" causes the default recipient to be used.

Parameter port

The recipient port number. For connect()ed objects specifying port number 0 casues the default recipient port to be used.

Parameter flag

A flag bitfield with 1 for out of band data and 2 for don't route flag.

Returns

(0..)

The number of bytes that were actually written.

(..-1)

Failed to send the message. Check errno() for the cause. Common causes are:

`System.EMSGSIZE`	The `message` is too large to send unfragmented.
`System.EWOULDBLOCK`	The send buffers are full.

Throws

Throws errors on invalid arguments and uninitialized object.

Note

Versions of Pike prior to 8.1.5 threw errors also on EMSGSIZE ("Too big message") and EWOULDBLOCK ("Message would block."). These versions of Pike also did not update the object errno on this function failing.

Note

Versions of Pike prior to 8.1.13 did not support the default recipient for connect()ed objects.

See also

connect(), errno(), query_mtu()

Method set_backend: voidset_backend(Pike.Backendbackend)
Description: Set the backend used for the read callback.
Note: 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.
See also: query_backend

Method set_blocking: objectset_blocking()
Description: Sets this object to be blocking.

Method set_buffer

voidset_buffer(intbufsize, stringmode)
voidset_buffer(intbufsize)

Description

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

Note

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

See also

open_socket(), accept()

Method set_fd: UDPset_fd(intfd)
Description: Use the file descriptor fd for UDP.
See also: bind

Method set_multicast_ttl

intset_multicast_ttl(intttl)

Description

Set the time-to-live value of outgoing multicast packets for this socket.

Parameter ttl

The number of router hops sent multicast packets should survive.

It is very important for multicast packets to set the smallest TTL possible. The default before calling this function is 1 which means that multicast packets don't leak from the local network unless the user program explicitly requests it.

See also the Unix man page for setsocketopt IPPROTO_IP IP_MULTICAST_TTL and IPPROTO_IPV6 IPV6_MULTICAST_HOPS.

Note

This function did not support IPv6 in Pike 7.8 and earlier.

See also

add_membership()

Method set_nonblocking: objectset_nonblocking(function(:void)|voidrcb, function(:void)|voidwcb)
Description: Sets this object to be nonblocking and the read and write callbacks.

Method set_type: UDPset_type(intsock_type)
UDPset_type(intsock_type, intfamily)
Description: Sets socket type and protocol family.

Method wait: boolwait(int|floattimeout)
Description: Check for data and wait max. timeout seconds.
Returns: Returns 1 if data are ready, 0 (zero) otherwise.

Class _Stdio._port

Method accept

Stdio.Fileaccept()

Description

Get the first connection request waiting for this port and return it as a connected socket.

If no connection request is waiting and the port is in nonblocking mode (i.e. an accept callback is installed) then zero is returned. Otherwise this function waits until a connection has arrived.

In Pike 7.8 and later the returned object is created via fd_factory().

Note

In Pike 7.7 and later the resulting file object will be assigned to the same backend as the port object.

Method bind

intbind(int|stringport, void|function(:void) accept_callback, void|stringip, void|stringreuse_port)

Description

Opens a socket and binds it to port number on the local machine. If the second argument is present, the socket is set to nonblocking and the callback funcition is called whenever something connects to it. The callback will receive the id for this port as argument and should typically call accept to establish a connection.

If the optional argument ip is given, bind will try to bind to an interface with that host name or IP number. Omitting this will bind to all available IPv4 addresses; specifying "::" will bind to all IPv4 and IPv6 addresses.

If the OS supports TCP_FASTOPEN it is enabled automatically.

If the OS supports SO_REUSEPORT it is enabled if the fourth argument is true.

Returns

1 is returned on success, zero on failure. errno provides further details about the error in the latter case.

See also

accept, set_id

Method bind_unix: intbind_unix(stringpath, void|function(:void) accept_callback)
Description: Opens a Unix domain socket at the given path in the file system. If the second argument is present, the socket is set to nonblocking and the callback funcition is called whenever something connects to it. The callback will receive the id for this port as argument and should typically call accept to establish a connection.
Returns: 1 is returned on success, zero on failure. errno provides further details about the error in the latter case.
Note: This function is only available on systems that support Unix domain sockets.
Note: path had a quite restrictive length limit (~100 characters) prior to Pike 7.8.334.
See also: accept, set_id

Method close: voidclose()
Description: Closes the socket.

Method create

_Stdio._port_Stdio._port(int|stringport, void|function(:void) accept_callback, void|stringip)
_Stdio._port_Stdio._port("stdin", void|function(:void) accept_callback)

Description

When called with an int or any string except "stdin" as first argument, this function does the same as bind() would do with the same arguments.

When called with "stdin" as argument, a socket is created out of the file descriptor 0. This is only useful if that actually IS a socket to begin with, and is equivalent to creating a port and initializing it with listen_fd(0).

See also

bind, listen_fd

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

Method fd_factory

protectedStdio.Fdfd_factory()

Description

Factory creating empty Stdio.Fd objects.

The default implementation creates an empty Stdio.Fd object.

Method listen_fd: intlisten_fd(intfd, void|function(:void) accept_callback)
Description: This function does the same as bind, except that instead of creating a new socket and bind it to a port, it expects the file descriptor fd to be an already open port.
Note: This function is only for the advanced user, and is generally used when sockets are passed to Pike at exec time.
See also: bind, accept

Method query_address

stringquery_address()

Description

Get the address and port of the local socket end-point.

Returns

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 there is some error querying or formatting the address, 0 (zero) is returned and errno() will return the error code.

Throws

An error is thrown if the socket isn't bound.

Method query_backend: Pike.Backendquery_backend()
Description: Return the backend used for the accept callback.
See also: set_backend

Method query_fd: intquery_fd()
Description: Returns the file descriptor number associated with this object.

Method query_id: mixedquery_id()
Description: This function returns the id for this port. The id is normally the first argument to accept_callback.
See also: set_id

Method set_accept_callback: voidset_accept_callback(function(:void)|voidaccept_callback)
Description: Change or remove the accept callback.
Parameter accept_callback: New accept callback.
See also: bind(), listen(), set_id()

Method set_backend: voidset_backend(Pike.Backendbackend)
Description: Set the backend used for the accept callback.
Note: 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.
See also: query_backend

Method set_id: mixedset_id(mixedid)
Description: This function sets the id used for accept_callback by this port. The default id is this_object().
Note: In Pike 8.0 and earlier the default value was 0 (zero) (even though it was documented as above).
See also: query_id, set_accept_callback()

Module _Stdio.IPPROTO

Description: Module containing various IP-protocol options.

Module _Stdio.SOCK

Description: Module containing constants for specifying socket options.

Constant DGRAM: constant _Stdio.SOCK.DGRAM

Constant PACKET: constant _Stdio.SOCK.PACKET

Constant RAW: constant _Stdio.SOCK.RAW

Constant RDM: constant _Stdio.SOCK.RDM

Constant SEQPACKET: constant _Stdio.SOCK.SEQPACKET

Constant STREAM: constant _Stdio.SOCK.STREAM

`NOTICE`	Ignored.
`WARNING`	Calls `MasterObject()->compile_warning()`.
`ERROR`	Calls `MasterObject()->compile_error()`.
`FATAL`	Calls `MasterObject()->compile_error()`.

28. The rest

Namespace 9.0::

Namespace cpp::

Namespace predef::

Advanced use

Enum bool

Class Codec

Class CompilationHandler

Class CompilerEnvironment

Enum CompilerEnvironment.CppDefArgFlags

Enum CompilerEnvironment.CppFlags

Enum CompilerEnvironment.CppMacroFlags

Class CompilerEnvironment.CPP

Class CompilerEnvironment.PikeCompiler

Class CompilerEnvironment.PikeCompiler.CompilerState

Class CompilerEnvironment.define

Class CompilerEnvironment.lock

Class Decoder

Class Encoder

Class Iterator

Class Iterator.CompatIterator

Class MasterObject

Class MasterObject.Codec

Class MasterObject.CompatResolver

Class MasterObject.Decoder

Class MasterObject.Describer

Class MasterObject.Encoder

Class MasterObject.Pike_7_8_master

Class MasterObject.Pike_8_0_master

Class MasterObject.Pike_9_0_master

Class MasterObject.Version

Class MasterObject.dirnode

Class MasterObject.joinnode

Class RandomInterface

Class RandomSystem

Class Reporter

Enum Reporter.SeverityLevel

Class __dirnode

Class __joinnode

Class mklibpike

Class mklibpike.C_Include_Handler

Class string_assignment

Module Arg

Class Arg.LowOptions

Class Arg.OptLibrary

Class Arg.OptLibrary.Default

Class Arg.OptLibrary.Env

Class Arg.OptLibrary.HasOpt

Class Arg.OptLibrary.Int

Class Arg.OptLibrary.MaybeOpt

Class Arg.OptLibrary.Multiple

Class Arg.OptLibrary.NoOpt

Class Arg.OptLibrary.Opt

Class Arg.Options

Class Arg.SimpleOptions

Module Audio

Module Audio.Codec

Class Audio.Codec.decoder

Module Audio.Format

Class Audio.Format.ANY

Class Audio.Format.MP3

Module COM

Module Cache

Class Cache.Data

Class Cache.cache

Module Cache.Policy

Class Cache.Policy.Base

Class Cache.Policy.Multiple

Class Cache.Policy.Null

Class Cache.Policy.Sized

Class Cache.Policy.Timed

Module Cache.Storage

Class Cache.Storage.Base

Class Cache.Storage.Gdbm

Class Cache.Storage.Gdbm.Data

Class Cache.Storage.Memory

Class Cache.Storage.Memory.Data

Class Cache.Storage.MySQL

Class Cache.Storage.MySQL.Data

Class Cache.Storage.Yabu