17. The rest

  Namespace 7.4::

    Method hash

      `int hash(string s)`
      `int hash(string s, int max)`

    Description

      Return an integer derived from the string s. The same string will always hash to the same value, also between processes.

      If max is given, the result will be >= 0 and < max, otherwise the result will be >= 0 and <= 0x7fffffff.

    Note

      This function is provided for backward compatibility reasons.

      This function is byte-order dependant for wide strings.

    See also

      predef::hash(), 7.0::hash()

  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.

    Directive #require

      `#require`

    Description

      If the directive evaluates to false, the source file will be considered to have failed dependencies, and will not be found by the resolver. In practical terms the cpp() call will return zero.

    See also

      #if

    Variable __COUNTER__

      `int(1..) __COUNTER__`

    Description

      This define contains a unique counter (unless it has been expanded Inte.NATIVE_MAX times) represented as an integer.

    Constant __OS2__

      `constant __OS2__`

    Description

      This define is defined when the Pike is running on IBM OS/2.

  Namespace predef::

    Constant FUSE_MAJOR_VERSION
    Constant FUSE_MINOR_VERSION

      `constant FUSE_MAJOR_VERSION`
      `constant FUSE_MINOR_VERSION`

    Description

      The version of FUSE

    Constant HKEY_CLASSES_ROOT
    Constant HKEY_LOCAL_MACHINE
    Constant HKEY_CURRENT_USER
    Constant HKEY_USERS

      `constant int HKEY_CLASSES_ROOT`
      `constant int HKEY_LOCAL_MACHINE`
      `constant int HKEY_CURRENT_USER`
      `constant int HKEY_USERS`

    Description

      Root handles in the Windows registry.

    Note

      These constants are only available on Win32 systems.

    See also

      RegGetValue(), RegGetValues(), RegGetKeyNames()

    Method RegGetKeyNames

      `array(string) RegGetKeyNames(int hkey, string key)`

    Description

      Get a list of value key names from the register.

    Parameter `hkey`

      One of the following:

      `HKEY_CLASSES_ROOT`
      `HKEY_LOCAL_MACHINE`
      `HKEY_CURRENT_USER`
      `HKEY_USERS`

    Parameter `key`

      A registry key.

    Returns

      Returns an array of value keys stored at the specified location if any. Returns `UNDEFINED` on missing key. Throws errors on other failures.

    Example

          > RegGetKeyNames(HKEY_CURRENT_USER, "Keyboard Layout");
            (1) Result: ({
              "IMEtoggle",
              "Preload",
              "Substitutes",
              "Toggle"
             })

    Note

      This function threw errors on missing key in Pike 7.6 and earlier (see System.RegGetKeyNames_76()).

    Note

      This function is only available on Win32 systems.

    See also

      RegGetValue(), RegGetValues(), System.RegGetKeyNames_76()

    Method RegGetValue

      `string|int|array(string) RegGetValue(int hkey, string key, string index)`

    Description

      Get a single value from the register.

    Parameter `hkey`

      One of the following:

      `HKEY_CLASSES_ROOT`
      `HKEY_LOCAL_MACHINE`
      `HKEY_CURRENT_USER`
      `HKEY_USERS`

    Parameter `key`

      Registry key.

    Parameter `index`

      Value name.

    Returns

      Returns the value stored at the specified location in the register if any. Returns `UNDEFINED` on missing keys, throws errors on other failures.

    Note

      This function threw errors on missing keys in Pike 7.6 and earlier (see System.RegGetValue_76()).

    Note

      This function is only available on Win32 systems.

    See also

      RegGetValues(), RegGetKeyNames(), System.RegGetValue_76()

    Method RegGetValues

      `mapping(string:string|int|array(string)) RegGetValues(int hkey, string key)`

    Description

      Get multiple values from the register.

    Parameter `hkey`

      One of the following:

      `HKEY_CLASSES_ROOT`
      `HKEY_LOCAL_MACHINE`
      `HKEY_CURRENT_USER`
      `HKEY_USERS`

    Parameter `key`

      Registry key.

    Returns

      Returns a mapping with all the values stored at the specified location in the register if any. Returns `UNDEFINED` on missing key. Throws errors on other failures.

    Example

          > RegGetValues(HKEY_CURRENT_USER, "Keyboard Layout\\Preload");
          (5) Result: ([
            "1":"0000041d"
           ])

    Note

      This function threw errors on missing key in Pike 7.6 and earlier (see System.RegGetValues_76()).

    Note

      This function is only available on Win32 systems.

    See also

      RegGetValue(), RegGetKeyNames(), System.RegGetValues_76()

    Constant TOKENIZE_KEEP_ESCAPES

      `constant 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()

    Constant UNDEFINED

      `constant UNDEFINED`

    Description

      The undefined value; ie a zero for which zero_type() returns 1.

    Method _Static_assert

      `void _Static_assert(int constant_expression, string constant_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 __empty_program

      `program __empty_program(int|void line, string|void file)`

    Method __handle_sprintf_format

      `type __handle_sprintf_format(string attr, string fmt, type arg_type, type cont_type)`

    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.

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

    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

    Method __parse_pike_type

      `string(8bit) __parse_pike_type(string(8bit) t)`

    Constant __placeholder_object

      `constant __placeholder_object`

    Description

      Object used internally by the compiler.

    See also

      __null_program

    Method _disable_threads

      `_disable_threads _disable_threads()`

    Description

      This function first posts a notice to all threads that it is time to stop. It then waits until all threads actually *have* stopped, and then then returns a lock object. All other threads will be blocked from running until that object has been freed/destroyed.

      It's mainly useful to do things that require a temporary uid/gid change, since on many OS the effective user and group applies to all threads.

    Note

      You should make sure that the returned object is freed even if some kind of error is thrown. That means in practice that it should only have references (direct or indirect) from function local variables. Also, it shouldn't be referenced from cyclic memory structures, since those are only destructed by the periodic gc. (This advice applies to mutex locks in general, for that matter.)

    See also

      gethrdtime()

    Method call_out
    Method _do_call_outs
    Method find_call_out
    Method remove_call_out
    Method call_out_info

      `mixed call_out(function(:void) f, float|int delay, mixed ... args)`
      `void _do_call_outs()`
      `int find_call_out(function(:void) f)`
      `int find_call_out(mixed id)`
      `int remove_call_out(function(:void) f)`
      `int remove_call_out(function(:void) id)`
      `array(array) call_out_info()`

    Description

      These are aliases for the corresponding functions in Pike.DefaultBackend.

    See also

      Pike.Backend()->call_out(), Pike.Backend()->_do_call_outs(), Pike.Backend()->find_call_out(), Pike.Backend()->remove_call_out(), Pike.Backend()->call_out_info()

    Method _exit

      `void _exit(int returncode)`

    Description

      This function does the same as exit, but doesn't bother to clean up the Pike interpreter before exiting. This means that no destructors will be called, caches will not be flushed, file locks might not be released, and databases might not be closed properly.

      Use with extreme caution.

    See also

      exit()

    Method _next

      `mixed _next(mixed x)`

    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 _prev

      `mixed _prev(mixed x)`

    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

      `int _refs(string|array|mapping|multiset|function(:void)|object|program o)`

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

    Variable _static_modules

      `object _static_modules`

    Description

      This is an object containing the classes for all static (ie non-dynamic) C-modules.

      In a typic Pike with support for dynamic modules the contained module classes are:

      Builtin

      Gmp

      _Stdio

      _math

      _system

      If the Pike binary lacks support for dynamic modules, all C-modules will show up here.

    Method _typeof

      `type _typeof(mixed x)`

    Description

      Return the runtime type of x.

    See also

      typeof()

    Method `!

      `bool `!(object|function(:void) arg)`
      `int(1..1) `!(int(0..0) arg)`
      `int(0..0) `!(mixed arg)`

    Description

      Logical not.

      Every expression with the `!` operator becomes a call to this function, i.e. `!a` is the same as `predef::`!(a)`.

      It's also used when necessary to test truth on objects, i.e. in a statement `if (o) ...` where `o` is an object, the test becomes the equivalent of `!!o` so that any lfun::`!() the object might have gets called.

    Returns

      If arg is an object that implements lfun::`!(), that function will be called.

      If arg is `0` (zero), a destructed object, or a function in a destructed object, `1` will be returned.

      Otherwise `0` (zero) will be returned.

    Note

      No float is considered false, not even `0.0`.

    See also

      `==(), `!=(), lfun::`!()

    Method `!=

      `bool `!=(mixed arg1, mixed arg2, mixed ... extras)`

    Description

      Inequality test.

      Every expression with the `!=` operator becomes a call to this function, i.e. `a!=b` is the same as `predef::`!=(a,b)`.

      This is the inverse of `==(); see that function for further details.

    Returns

      Returns `1` if the test is successful, `0` otherwise.

    See also

      `==()

    Method `%

      `mixed `%(object arg1, mixed arg2)`
      `mixed `%(mixed arg1, object arg2)`
      `string `%(string arg1, int arg2)`
      `array `%(array arg1, int arg2)`
      `float `%(float arg1, float|int arg2)`
      `float `%(int arg1, float arg2)`
      `int `%(int arg1, int arg2)`

    Description

      Modulo.

      Every expression with the `%` operator becomes a call to this function, i.e. `a%b` is the same as `predef::`%(a,b)`.

    Returns

      If arg1 is an object that implements lfun::`%() then that function will be called with arg2 as the single argument.

      If arg2 is an object that implements lfun::``%() then that function will be called with arg2 as the single argument.

      Otherwise the result will be as follows:

      `arg1` can have any of the following types:

      `string|array` | If arg2 is positive, the result will be the last ``%(<font face='courier'>sizeof`(<font face='courier'>arg1), <font face='courier'>arg2) elements of arg1. If arg2 is negative, the result will be the first ``%(<font face='courier'>sizeof`(<font face='courier'>arg1), -<font face='courier'>arg2) elements of arg1.
      `int|float` | The result will be `<font face='courier'>arg1` - <font face='courier'>arg2*<font face='courier'>floor(<font face='courier'>arg1/<font face='courier'>arg2). The result will be a float if either arg1 or arg2 is a float, and an int otherwise.

      For numbers, this means that

      1. `a % b` always has the same sign as `b` (typically `b` is positive; array size, rsa modulo, etc, and `a` varies a lot more than `b`).

      2. The function `f(x) = x % n` behaves in a sane way; as `x` increases, `f(x)` cycles through the values `0,1, ..., n-1, 0, ...`. Nothing strange happens when you cross zero.

      3. The `%` operator implements the binary "mod" operation, as defined by Donald Knuth (see the Art of Computer Programming, 1.2.4). It should be noted that Pike treats %-by-0 as an error rather than returning 0, though.

      4. `/` and `%` are compatible, so that `a == b*<font face='courier'>floor`(a/b) + a%b for all `a` and `b`.

    See also

      `/, floor()

    Method `&

      `mixed `&(mixed arg1)`
      `mixed `&(mixed arg1, mixed arg2, mixed ... extras)`
      `mixed `&(object arg1, mixed arg2)`
      `mixed `&(mixed arg1, object arg2)`
      `int `&(int arg1, int arg2)`
      `string `&(string arg1, string arg2)`
      `array `&(array arg1, array arg2)`
      `mapping `&(mapping arg1, mapping arg2)`
      `mapping `&(mapping arg1, array arg2)`
      `mapping `&(mapping arg1, multiset arg2)`
      `multiset `&(multiset arg1, multiset arg2)`
      `type `&(type|program arg1, type|program arg2)`

    Description

      Bitwise and/intersection.

      Every expression with the `&` operator becomes a call to this function, i.e. `a&b` is the same as `predef::`&(a,b)`.

    Returns

      If there's a single argument, that argument is returned.

      If there are more than two arguments the result is: ``&(`&(<font face='courier'>arg1`, <font face='courier'>arg2), @<font face='courier'>extras).

      Otherwise, if arg1 is an object with an lfun::`&(), that function is called with arg2 as argument, and its result is returned.

      Otherwise, if arg2 is an object with an lfun::``&(), that function is called with arg1 as argument, and its result is returned.

      Otherwise the result depends on the argument types:

      `arg1` can have any of the following types:

      `int` | Bitwise and of arg1 and arg2.
      `string` | The result is a string where each character is the bitwise and of the characters in the same position in arg1 and arg2. The arguments must be strings of the same length.
      `array|mapping|multiset` | The result is like arg1 but only with the elements/indices that match any in arg2 (according to `== and, in the case of mappings, hash_value).
      `type|program` | Type intersection of arg1 and arg2.

      The function is not destructive on the arguments - the result is always a new instance.

    See also

      `|(), lfun::`&(), lfun::``&()

    Method `()
    Method call_function

      `mixed `()(function(:void) fun, mixed ... args)`
      `mixed call_function(function(:void) fun, mixed ... args)`

    Description

      Call a function.

      Calls the function fun with the arguments specified by args.

    See also

      lfun::`()()

    Method `*

      `mixed `*(mixed arg1)`
      `mixed `*(object arg1, mixed arg2, mixed ... extras)`
      `mixed `*(mixed arg1, object arg2)`
      `array `*(array arg1, int arg2)`
      `array `*(array arg1, float arg2)`
      `string `*(string arg1, int arg2)`
      `string `*(string arg1, float arg2)`
      `string `*(array(string) arg1, string arg2)`
      `array `*(array(array) arg1, array arg2)`
      `float `*(float arg1, int|float arg2)`
      `float `*(int arg1, float arg2)`
      `int `*(int arg1, int arg2)`
      `mixed `*(mixed arg1, mixed arg2, mixed ... extras)`

    Description

      Multiplication/repetition/implosion.

      Every expression with the `*` operator becomes a call to this function, i.e. `a*b` is the same as `predef::`*(a,b)`. Longer `*` expressions are normally optimized to one call, so e.g. `a*b*c` becomes `predef::`*(a,b,c)`.

    Returns

      If there's a single argument, that argument will be returned.

      If the first argument is an object that implements lfun::`*(), that function will be called with the rest of the arguments.

      If there are more than two arguments, the result will be ``*(`*(<font face='courier'>arg1`, <font face='courier'>arg2), @<font face='courier'>extras).

      If arg2 is an object that implements lfun::``*(), that function will be called with arg1 as the single argument.

      Otherwise the result will be as follows:

      `arg1` can have any of the following types:

      `array`

      `arg2` can have any of the following types:

      `int|float` | The result will be arg1 concatenated arg2 times.
      `string|array` | The result will be the elements of arg1 concatenated with arg2 interspersed.

      `string` | The result will be arg1 concatenated arg2 times.
      `int|float` | The result will be `<font face='courier'>arg1` * <font face='courier'>arg2, and will be a float if either arg1 or arg2 is a float.

    Note

      In Pike 7.0 and earlier the multiplication order was unspecified.

    See also

      `+(), `-(), `/(), lfun::`*(), lfun::``*()

    Method `+

      `mixed `+(mixed arg)`
      `mixed `+(object arg, mixed ... more)`
      `int `+(int arg, int ... more)`
      `float `+(float|int arg, float|int ... more)`
      `string `+(string|float|int arg, string|float|int ... more)`
      `array `+(array arg, array ... more)`
      `mapping `+(mapping arg, mapping ... more)`
      `multiset `+(multiset arg, multiset ... more)`

    Description

      Addition/concatenation.

      Every expression with the `+` operator becomes a call to this function, i.e. `a+b` is the same as `predef::`+(a,b)`. Longer `+` expressions are normally optimized to one call, so e.g. `a+b+c` becomes `predef::`+(a,b,c)`.

    Returns

      If there's a single argument, that argument is returned.

      If arg is an object with only one reference and an lfun::`+=(), that function is called with the rest of the arguments, and its result is returned.

      Otherwise, if arg is an object with an lfun::`+(), that function is called with the rest of the arguments, and its result is returned.

      Otherwise, if any of the other arguments is an object that has an lfun::``+(), the first such function is called with the arguments leading up to it, and `+() is then called recursively with the result and the rest of the arguments.

      Otherwise, if arg is UNDEFINED and the other arguments are either arrays, mappings or multisets, the first argument is ignored and the remaining are added together as described below. This is useful primarily when appending to mapping values since `m[x] += ({foo})` will work even if `m[x]` doesn't exist yet.

      Otherwise the result depends on the argument types:

      `int|float` | The result is the sum of all the arguments. It's a float if any argument is a float.
      `string|int|float` | If any argument is a string, all will be converted to strings and concatenated in order to form the result.
      `array` | The array arguments are concatened in order to form the result.
      `mapping` | The result is like arg but extended with the entries from the other arguments. If the same index (according to hash_value and `==) occur in several arguments, the value from the last one is used.
      `multiset` | The result is like arg but extended with the entries from the other arguments. Subsequences with orderwise equal indices (i.e. where `< returns false) are concatenated into the result in argument order.

      The function is not destructive on the arguments - the result is always a new instance.

    Note

      In Pike 7.0 and earlier the addition order was unspecified.

      The treatment of UNDEFINED was new in Pike 7.0.

    See also

      `-(), lfun::`+(), lfun::``+()

    Method `-

      `mixed `-(mixed arg1)`
      `mixed `-(mixed arg1, mixed arg2, mixed ... extras)`
      `mixed `-(object arg1, mixed arg2)`
      `mixed `-(mixed arg1, object arg2)`
      `int `-(int arg1, int arg2)`
      `float `-(float arg1, int|float arg2)`
      `float `-(int|float arg1, float arg2)`
      `string `-(string arg1, string arg2)`
      `array `-(array arg1, array arg2)`
      `mapping `-(mapping arg1, array arg2)`
      `mapping `-(mapping arg1, mapping arg2)`
      `mapping `-(mapping arg1, multiset arg2)`
      `multiset `-(multiset arg1, multiset arg2)`

    Description

      Negation/subtraction/set difference.

      Every expression with the `-` operator becomes a call to this function, i.e. `-a` is the same as `predef::`-(a)` and `a-b` is the same as `predef::`-(a,b)`. Longer `-` expressions are normally optimized to one call, so e.g. `a-b-c` becomes `predef::`-(a,b,c)`.

    Returns

      If there's a single argument, that argument is returned negated. If arg1 is an object with an lfun::`-(), that function is called without arguments, and its result is returned.

      If there are more than two arguments the result is: ``-(`-(<font face='courier'>arg1`, <font face='courier'>arg2), @<font face='courier'>extras).

      Otherwise, if arg1 is an object with an lfun::`-(), that function is called with arg2 as argument, and its result is returned.

      Otherwise, if arg2 is an object with an lfun::``-(), that function is called with arg1 as argument, and its result is returned.

      Otherwise the result depends on the argument types:

      `arg1` can have any of the following types:

      `int|float` | The result is `<font face='courier'>arg1` - <font face='courier'>arg2, and is a float if either arg1 or arg2 is a float.
      `string` | The result is arg1 with all nonoverlapping occurrences of the substring arg2 removed. In cases with two overlapping occurrences, the leftmost is removed.
      `array|mapping|multiset` | The result is like arg1 but without the elements/indices that match any in arg2 (according to `== and, in the case of mappings, hash_value).

      The function is not destructive on the arguments - the result is always a new instance.

    Note

      In Pike 7.0 and earlier the subtraction order was unspecified.

    See also

      `+()

    Method `->

      `mixed `->(object arg, string index)`
      `mixed `->(int arg, string index)`
      `mixed `->(array arg, string index)`
      `mixed `->(mapping arg, string index)`
      `bool `->(multiset arg, string index)`
      `mixed `->(program arg, string index)`

    Description

      Arrow indexing.

      Every non-lvalue expression with the `->` operator becomes a call to this function. `a->b` is the same as `predef::`^(a,"b")` where `"b"` is the symbol `b` in string form.

      This function behaves like `[], except that the index is passed literally as a string instead of being evaluated.

    Returns

      If arg is an object that implements lfun::`->(), that function will be called with index as the single argument.

      Otherwise the result will be as follows:

      `arg` can have any of the following types:

      `object` | The non-protected (ie public) symbol named index will be looked up in arg.
      `int` | The bignum function named index will be looked up in arg.
      `array` | An array of all elements in arg arrow indexed with index will be returned.
      `mapping` | If index exists in arg the corresponding value will be returned. Otherwise `UNDEFINED` will be returned.
      `multiset` | If index exists in arg, `1` will be returned. Otherwise `UNDEFINED` will be returned.
      `program` | The non-protected (ie public) constant symbol index will be looked up in arg.

    Note

      In an expression `a->b`, the symbol `b` can be any token that matches the identifier syntax - keywords are disregarded in that context.

    Note

      An arrow indexing expression in an lvalue context, i.e. where the index is being assigned a new value, uses `->= instead of this function.

    See also

      `[](), lfun::`->(), ::`->(), `->=

    Method `->=

      `mixed `->=(object arg, string index, mixed val)`
      `mixed `->=(mapping arg, string index, mixed val)`
      `bool `->=(multiset arg, string index, bool val)`

    Description

      Arrow index assignment.

      Every lvalue expression with the `->` operator becomes a call to this function, i.e. `a->b=c` is the same as `predef::`->=(a,"b",c)` where `"b"` is the symbol `b` in string form.

      This function behaves like `[]=, except that the index is passed literally as a string instead of being evaluated.

      If arg is an object that implements lfun::`->=(), that function will be called with index and val as the arguments.

      `arg` can have any of the following types:

      `object` | The non-protected (ie public) variable named index will be looked up in arg, and assigned val.
      `array|mapping` | Index index in arg will be assigned val.
      `multiset` | If val is `0` (zero), one occurrance of index in arg will be removed. Otherwise index will be added to arg if it is not already there.

    Returns

      val will be returned.

    Note

      In an expression `a->b=c`, the symbol `b` can be any token that matches the identifier syntax - keywords are disregarded in that context.

    Note

      An arrow indexing expression in a non-lvalue context, i.e. where the index is being queried instead of assigned, uses `-> instead of this function.

    See also

      `[]=(), lfun::`->=(), `->

    Method `/

      `mixed `/(object arg1, mixed arg2)`
      `mixed `/(mixed arg1, object arg2)`
      `array(string) `/(string arg1, int arg2)`
      `array(string) `/(string arg1, float arg2)`
      `array(array) `/(array arg1, int arg2)`
      `array(array) `/(array arg1, float arg2)`
      `array(string) `/(string arg1, string arg2)`
      `array(array) `/(array arg1, array arg2)`
      `float `/(float arg1, int|float arg2)`
      `float `/(int arg1, float arg2)`
      `int `/(int arg1, int arg2)`
      `mixed `/(mixed arg1, mixed arg2, mixed ... extras)`

    Description

      Division/split.

      Every expression with the `/` operator becomes a call to this function, i.e. `a/b` is the same as `predef::`/(a,b)`.

    Returns

      If there are more than two arguments, the result will be ``/(`/(<font face='courier'>arg1`, <font face='courier'>arg2), @<font face='courier'>extras).

      If arg1 is an object that implements lfun::`/(), that function will be called with arg2 as the single argument.

      If arg2 is an object that implements lfun::``/(), that function will be called with arg1 as the single argument.

      Otherwise the result will be as follows:

      `arg1` can have any of the following types:

      `string`

      `arg2` can have any of the following types:

      `int|float` | The result will be and array of arg1 split in segments of length arg2. If arg2 is negative the splitting will start from the end of arg1.
      `string` | The result will be an array of arg1 split at each occurrence of arg2. Note that the segments that matched against arg2 will not be in the result.

      `array`

      `arg2` can have any of the following types:

      `int|float` | The result will be and array of arg1 split in segments of length arg2. If arg2 is negative the splitting will start from the end of arg1.
      `array` | The result will be an array of arg1 split at each occurrence of arg2. Note that the elements that matched against arg2 will not be in the result.

      `float|int` | The result will be `<font face='courier'>arg1` / <font face='courier'>arg2. If both arguments are int, the result will be truncated to an int. Otherwise the result will be a float.

    Note

      Unlike in some languages, the function f(x) = x/n (x and n integers) behaves in a well-defined way and is always rounded down. When you increase x, f(x) will increase with one for each n:th increment. For all x, (x + n) / n = x/n + 1; crossing zero is not special. This also means that / and % are compatible, so that a = b*(a/b) + a%b for all a and b.

    See also

      `%

    Method `<

      `bool `<(mixed arg1, mixed arg2, mixed ... extras)`

    Description

      Less than test.

      Every expression with the `<` operator becomes a call to this function, i.e. `a<b` is the same as `predef::`<(a,b)`.

    Returns

      Returns `1` if the test is successful, `0` otherwise.

    See also

      `<=(), `>(), `>=()

    Method `<<

      `int `<<(int arg1, int arg2)`
      `mixed `<<(object arg1, int|object arg2)`
      `mixed `<<(int arg1, object arg2)`

    Description

      Left shift.

      Every expression with the `<<` operator becomes a call to this function, i.e. `a<<b` is the same as `predef::`<<(a,b)`.

      If arg1 is an object that implements lfun::`<<(), that function will be called with arg2 as the single argument.

      If arg2 is an object that implements lfun::``<<(), that function will be called with arg1 as the single argument.

      Otherwise arg1 will be shifted arg2 bits left.

    See also

      `>>()

    Method `<=

      `bool `<=(mixed arg1, mixed arg2, mixed ... extras)`

    Description

      Less than or equal test.

      Every expression with the `<=` operator becomes a call to this function, i.e. `a<=b` is the same as `predef::`<=(a,b)`.

    Returns

      Returns `1` if the test is successful, `0` otherwise.

    Note

      For total orders, e.g. integers, this is the inverse of `>().

    See also

      `<(), `>(), `>=()

    Method `==

      `bool `==(mixed arg1, mixed arg2, mixed ... extras)`

    Description

      Equality test.

      Every expression with the `==` operator becomes a call to this function, i.e. `a==b` is the same as `predef::`==(a,b)`.

      If more than two arguments are given, each argument is compared with the following one as described below, and the test is successful iff all comparisons are successful.

      If the first argument is an object with an lfun::`==(), that function is called with the second as argument, unless the second argument is the same as the first argument. The test is successful iff its result is nonzero (according to `!).

      Otherwise, if the second argument is an object with an lfun::`==(), that function is called with the first as argument, and the test is successful iff its result is nonzero (according to `!).

      Otherwise, if the arguments are of different types, the test is unsuccessful. Function pointers to programs are automatically converted to program pointers if necessary, though.

      Otherwise the test depends on the type of the arguments:

      `int` | Successful iff the two integers are numerically equal.
      `float` | Successful iff the two floats are numerically equal and not NaN.
      `string` | Successful iff the two strings are identical, character for character. (Since all strings are kept unique, this is actually a test whether the arguments point to the same string, and it therefore run in constant time.)
      `array|mapping|multiset|object|function(:void)|program|type` | Successful iff the two arguments point to the same instance.

    Returns

      Returns `1` if the test is successful, `0` otherwise.

    Note

      Floats and integers are not automatically converted to test against each other, so e.g. `0==0.0` is false.

    Note

      Programs are not automatically converted to types to be compared type-wise.

    See also

      `!(), `!=()

    Method `>

      `bool `>(mixed arg1, mixed arg2, mixed ... extras)`

    Description

      Greater than test.

      Every expression with the `>` operator becomes a call to this function, i.e. `a>b` is the same as `predef::`>(a,b)`.

    Returns

      Returns `1` if the arguments are strictly decreasing, and `0` (zero) otherwise.

    See also

      `<(), `<=(), `>=()

    Method `>=

      `bool `>=(mixed arg1, mixed arg2, mixed ... extras)`

    Description

      Greater than or equal test.

      Every expression with the `>=` operator becomes a call to this function, i.e. `a>=b` is the same as `predef::`>=(a,b)`.

    Returns

      Returns `1` if the test is successful, `0` otherwise.

    Note

      For total orders, e.g. integers, this is the inverse of `<().

    See also

      `<=(), `>(), `<()

    Method `>>

      `int `>>(int arg1, int arg2)`
      `mixed `>>(object arg1, int|object arg2)`
      `mixed `>>(int arg1, object arg2)`

    Description

      Right shift.

      Every expression with the `>>` operator becomes a call to this function, i.e. `a>>b` is the same as `predef::`>>(a,b)`.

      If arg1 is an object that implements lfun::`>>(), that function will be called with arg2 as the single argument.

      If arg2 is an object that implements lfun::``>>(), that function will be called with arg1 as the single argument.

      Otherwise arg1 will be shifted arg2 bits right.

    See also

      `<<()

    Method `[..]

      `mixed `[..](object arg, mixed start, int start_type, mixed end, int end_type)`
      `string `[..](string arg, int start, int start_type, int end, int end_type)`
      `array `[..](array arg, int start, int start_type, int end, int end_type)`

    Description

      Extracts a subrange.

      This is the function form of expressions with the `[..]` operator. arg is the thing from which the subrange is to be extracted. start is the lower bound of the subrange and end the upper bound.

      start_type and end_type specifies how the start and end indices, respectively, are to be interpreted. The types are either Pike.INDEX_FROM_BEG, Pike.INDEX_FROM_END or Pike.OPEN_BOUND. In the last case, the index value is insignificant.

      The relation between `[..]` expressions and this function is therefore as follows:

      a[i..j] <=> `[..] (a, i, Pike.INDEX_FROM_BEG, j, Pike.INDEX_FROM_BEG) a[i..<j] <=> `[..] (a, i, Pike.INDEX_FROM_BEG, j, Pike.INDEX_FROM_END) a[i..] <=> `[..] (a, i, Pike.INDEX_FROM_BEG, 0, Pike.OPEN_BOUND) a[<i..j] <=> `[..] (a, i, Pike.INDEX_FROM_END, j, Pike.INDEX_FROM_BEG) a[<i..<j] <=> `[..] (a, i, Pike.INDEX_FROM_END, j, Pike.INDEX_FROM_END) a[<i..] <=> `[..] (a, i, Pike.INDEX_FROM_END, 0, Pike.OPEN_BOUND) a[..j] <=> `[..] (a, 0, Pike.OPEN_BOUND, j, Pike.INDEX_FROM_BEG) a[..<j] <=> `[..] (a, 0, Pike.OPEN_BOUND, j, Pike.INDEX_FROM_END) a[..] <=> `[..] (a, 0, Pike.OPEN_BOUND, 0, Pike.OPEN_BOUND)

    The subrange is specified as follows by the two bounds:

    - If the lower bound refers to an index before the lowest allowable (typically zero) then it's taken as an open bound which starts at the first index (without any error).

    - Correspondingly, if the upper bound refers to an index past the last allowable then it's taken as an open bound which ends at the last index (without any error).

    - If the lower bound is less than or equal to the upper bound, then the subrange is the inclusive range between them, i.e. from and including the element at the lower bound and up to and including the element at the upper bound.

    - If the lower bound is greater than the upper bound then the result is an empty subrange (without any error).

  Returns

    The returned value depends on the type of arg:

    `arg` can have any of the following types:

    `string` | A string with the characters in the range is returned.
    `array` | An array with the elements in the range is returned.

    `object`

    If the object implements lfun::`[..], that function is called with the four remaining arguments.

    As a compatibility measure, if the object does not implement lfun::`[..] but lfun::`[] then the latter is called with the bounds transformed to normal from-the-beginning indices in array-like fashion:

    ``[..] (a, i, Pike.INDEX_FROM_BEG, j, Pike.INDEX_FROM_BEG)`

      Calls `a->`[] (i, j)`

    ``[..] (a, i, Pike.INDEX_FROM_BEG, j, Pike.INDEX_FROM_END)`

      Calls `a->`[] (i, a->_sizeof()-1-j)`

    ``[..] (a, i, Pike.INDEX_FROM_BEG, 0, Pike.OPEN_BOUND)`

      Calls `a->`[] (i, <font face='courier'>Int.NATIVE_MAX`)

    ``[..] (a, i, Pike.INDEX_FROM_END, j, Pike.INDEX_FROM_BEG)`

      Calls `a->`[] (a->_sizeof()-1-i, j)`

    ``[..] (a, i, Pike.INDEX_FROM_END, j, Pike.INDEX_FROM_END)`

      Calls `a->`[] (a->_sizeof()-1-i, a->_sizeof()-1-j)`, except that `a->_sizeof()` is called only once.

    ``[..] (a, i, Pike.INDEX_FROM_END, 0, Pike.OPEN_BOUND)`

      Calls `a->`[] (a->_sizeof()-1-i, <font face='courier'>Int.NATIVE_MAX`)

    ``[..] (a, 0, Pike.OPEN_BOUND, j, Pike.INDEX_FROM_BEG)`

      Calls `a->`[] (0, j)`

    ``[..] (a, 0, Pike.OPEN_BOUND, j, Pike.INDEX_FROM_END)`

      Calls `a->`[] (0, a->_sizeof()-1-j)`

    ``[..] (a, 0, Pike.OPEN_BOUND, 0, Pike.OPEN_BOUND)`

      Calls `a->`[] (0, <font face='courier'>Int.NATIVE_MAX`)

    Note that Int.NATIVE_MAX might be replaced with an even larger integer in the future.

  See also

    lfun::`[..], `[]

  Method `[]

    `mixed `[](object arg, mixed index)`
    `mixed `[](object arg, string index)`
    `function(:void) `[](int arg, string index)`
    `int `[](string arg, int index)`
    `mixed `[](array arg, int index)`
    `mixed `[](array arg, mixed index)`
    `mixed `[](mapping arg, mixed index)`
    `bool `[](multiset arg, mixed index)`
    `mixed `[](program arg, string index)`
    `mixed `[](object arg, mixed start, mixed end)`
    `string `[](string arg, int start, int end)`
    `array `[](array arg, int start, int end)`

  Description

    Indexing.

    This is the function form of expressions with the `[]` operator, i.e. `a[i]` is the same as `predef::`[](a,i)`.

  Returns

    If arg is an object that implements lfun::`[](), that function is called with the index argument.

    Otherwise, the action depends on the type of arg:

    `arg` can have any of the following types:

    `object` | The non-protected (i.e. public) symbol named index is looked up in arg.
    `int` | The bignum function named index is looked up in arg. The bignum functions are the same as those in the Gmp.mpz class.
    `string` | The character at index index in arg is returned as an integer. The first character in the string is at index `0` and the highest allowed index is therefore `sizeof(<font face='courier'>arg`)-1. A negative index number accesses the string from the end instead, from `-1` for the last char back to `-sizeof(<font face='courier'>arg`) for the first.

    `array`

    If index is an int, index number index of arg is returned. Allowed index number are in the range `[-sizeof(<font face='courier'>arg`)..sizeof(<font face='courier'>arg)-1]; see the string case above for details.

    If index is not an int, an array of all elements in arg indexed with index are returned. I.e. it's the same as doing `column(<font face='courier'>arg`, <font face='courier'>index).

    `mapping` | If index exists in arg the corresponding value is returned. Otherwise `UNDEFINED` is returned.
    `multiset` | If index exists in arg, `1` is returned. Otherwise `UNDEFINED` is returned.
    `program` | The non-protected (i.e. public) constant symbol index is looked up in arg.

    As a compatibility measure, this function also performs range operations if it's called with three arguments. In that case it becomes equivalent to:

    `[..] (arg, start, Pike.INDEX_FROM_BEG, end, Pike.INDEX_FROM_BEG)

  See `[..] for further details.

Note

  An indexing expression in an lvalue context, i.e. where the index is being assigned a new value, uses `[]= instead of this function.

See also

  `->(), lfun::`[](), `[]=, `[..]

Method `[]=

  `mixed `[]=(object arg, mixed index, mixed val)`
  `mixed `[]=(object arg, string index, mixed val)`
  `mixed `[]=(array arg, int index, mixed val)`
  `mixed `[]=(mapping arg, mixed index, mixed val)`
  `bool `[]=(multiset arg, mixed index, bool val)`

Description

  Index assignment.

  Every lvalue expression with the `[]` operator becomes a call to this function, i.e. `a[b]=c` is the same as `predef::`[]=(a,b,c)`.

  If arg is an object that implements lfun::`[]=(), that function will be called with index and val as the arguments.

  `arg` can have any of the following types:

  `object` | The non-protected (ie public) variable named index will be looked up in arg, and assigned val.
  `array|mapping` | Index index in arg will be assigned val.
  `multiset` | If val is `0` (zero), one occurrance of index in arg will be removed. Otherwise index will be added to arg if it is not already there.

Returns

  val will be returned.

Note

  An indexing expression in a non-lvalue context, i.e. where the index is being queried instead of assigned, uses `[] instead of this function.

See also

  `->=(), lfun::`[]=(), `[]

Method `^

  `mixed `^(mixed arg1)`
  `mixed `^(mixed arg1, mixed arg2, mixed ... extras)`
  `mixed `^(object arg1, mixed arg2)`
  `mixed `^(mixed arg1, object arg2)`
  `int `^(int arg1, int arg2)`
  `string `^(string arg1, string arg2)`
  `array `^(array arg1, array arg2)`
  `mapping `^(mapping arg1, mapping arg2)`
  `multiset `^(multiset arg1, multiset arg2)`
  `type `^(program|type arg1, program|type arg2)`

Description

  Exclusive or.

  Every expression with the `^` operator becomes a call to this function, i.e. `a^b` is the same as `predef::`^(a,b)`.

Returns

  If there's a single argument, that argument is returned.

  If there are more than two arguments, the result is: ``^(`^(<font face='courier'>arg1`, <font face='courier'>arg2), @<font face='courier'>extras).

  Otherwise, if arg1 is an object with an lfun::`^(), that function is called with arg2 as argument, and its result is returned.

  Otherwise, if arg2 is an object with an lfun::``^(), that function is called with arg1 as argument, and its result is returned.

  Otherwise the result depends on the argument types:

  `arg1` can have any of the following types:

  `int` | Bitwise exclusive or of arg1 and arg2.
  `string` | The result is a string where each character is the bitwise exclusive or of the characters in the same position in arg1 and arg2. The arguments must be strings of the same length.

  `array`

  The result is an array with the elements in arg1 that doesn't occur in arg2 concatenated with those in arg2 that doesn't occur in arg1 (according to `==). The order between the elements that come from the same argument is kept.

  Every element is only matched once against an element in the other array, so if one contains several elements that are equal to each other and are more than their counterparts in the other array, the rightmost remaining elements are kept.

  `mapping` | The result is like arg1 but with the entries from arg1 and arg2 whose indices are different between them (according to hash_value and `==).
  `multiset` | The result is like arg1 but with the entries from arg1 and arg2 that are different between them (according to hash_value and `==). Subsequences with orderwise equal entries (i.e. where `< returns false) are handled just like the array case above.
  `type|program` | The result is a type computed like this: `(<font face='courier'>arg1`&~<font face='courier'>arg2)|(~<font face='courier'>arg1&<font face='courier'>arg2).

  The function is not destructive on the arguments - the result is always a new instance.

See also

  `&(), `|(), lfun::`^(), lfun::``^()

Method `|

  `mixed `|(mixed arg1)`
  `mixed `|(mixed arg1, mixed arg2, mixed ... extras)`
  `mixed `|(object arg1, mixed arg2)`
  `mixed `|(mixed arg1, object arg2)`
  `int `|(int arg1, int arg2)`
  `string `|(string arg1, string arg2)`
  `array `|(array arg1, array arg2)`
  `mapping `|(mapping arg1, mapping arg2)`
  `multiset `|(multiset arg1, multiset arg2)`
  `type `|(program|type arg1, program|type arg2)`

Description

  Bitwise or/union.

  Every expression with the `|` operator becomes a call to this function, i.e. `a|b` is the same as `predef::`|(a,b)`.

Returns

  If there's a single argument, that argument is returned.

  If there are more than two arguments, the result is: ``|(`|(<font face='courier'>arg1`, <font face='courier'>arg2), @<font face='courier'>extras).

  Otherwise, if arg1 is an object with an lfun::`|(), that function is called with arg2 as argument, and its result is returned.

  Otherwise, if arg2 is an object with an lfun::``|(), that function is called with arg1 as argument, and its result is returned.

  Otherwise the result depends on the argument types:

  `arg1` can have any of the following types:

  `int` | Bitwise or of arg1 and arg2.
  `string` | The result is a string where each character is the bitwise or of the characters in the same position in arg1 and arg2. The arguments must be strings of the same length.

  `array`

  The result is an array with the elements in arg1 concatenated with those in arg2 that doesn't occur in arg1 (according to `==). The order between the elements that come from the same argument is kept.

  Every element in arg1 is only matched once against an element in arg2, so if arg2 contains several elements that are equal to each other and are more than their counterparts in arg1, the rightmost remaining elements in arg2 are kept.

  `mapping` | The result is like arg1 but extended with the entries from arg2. If the same index (according to hash_value and `==) occur in both, the value from arg2 is used.
  `multiset` | The result is like arg1 but extended with the entries in arg2 that doesn't already occur in arg1 (according to `==). Subsequences with orderwise equal entries (i.e. where `< returns false) are handled just like the array case above.
  `type|program` | Type union of arg1 and arg2.

  The function is not destructive on the arguments - the result is always a new instance.

See also

  `&(), lfun::`|(), lfun::``|()

Method `~

  `mixed `~(object arg)`
  `int `~(int arg)`
  `float `~(float arg)`
  `type `~(type|program arg)`
  `string `~(string arg)`

Description

  Complement/inversion.

  Every expression with the `~` operator becomes a call to this function, i.e. `~a` is the same as `predef::`~(a)`.

Returns

  The result will be as follows:

  `arg` can have any of the following types:

  `object` | If arg implements lfun::`~(), that function will be called.
  `int` | The bitwise inverse of arg will be returned.
  `float` | The result will be `-1.0 - <font face='courier'>arg`.
  `type|program` | The type inverse of arg will be returned.
  `string` | If arg only contains characters in the range 0 - 255 (8-bit), a string containing the corresponding 8-bit inverses will be returned.

See also

  `!(), lfun::`~()

Method abs

  `float abs(float f)`
  `int abs(int f)`
  `object abs(object f)`

Description

  Return the absolute value for f. If f is an object it must implement lfun::`< and unary lfun::`-.

Method access

  `int access(string path, string|void mode)`

Description

  access() checks if the calling process can access the file path. Symbolic links are dereferenced.

Parameter `mode`

  The mode specifies the accessibility checks to be performed, and is either not specified or empty, in which case access() just tests if the file exists, or one or more of the characters `"rwx"`.

  r, w, and x test whether the file exists and grants read, write, and execute permissions, respectively.

  The check is done using the calling process's real UID and GID, rather than the effective IDs as is done when actually attempting an operation (e.g., open(2)) on the file. This allows set-user-ID programs to easily determine the invoking user's authority.

  If the calling process is privileged (i.e., its real UID is zero), then an X_OK check is successful for a regular file if execute permission is enabled for any of the file owner, group, or other.

Returns

  `1` | When the file is accessible using the given permissions.

  `0`

  When the file is not accessible, in which case errno is set to one of the following values:

  `EACCESS` | Access denied.
  `ELOOP` | Too many symbolic links.
  `ENAMETOOLONG` | The path is too long.
  `ENOENT` | The file does not exist.
  `ENOTDIR` | One of the directories used in path is not, in fact, a directory.
  `EROFS` | The filesystem is read only and write access was requested.

  Other errors can occur, but are not directly related to the requested path, such as `ENOMEM`, etc.

See also

  errno(), Stdio.File

Method acos

  `float acos(int|float f)`

Description

  Return the arcus cosine value for f. The result will be in radians.

See also

  cos(), asin()

Method acosh

  `float acosh(int|float f)`

Description

  Return the hyperbolic arcus cosine value for f.

See also

  cosh(), asinh()

Method add_constant

  `void add_constant(string name, mixed value)`
  `void add_constant(string name)`

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 aggregate

  `array aggregate(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

  `mapping aggregate_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

  `multiset aggregate_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 alarm

  `int alarm(int seconds)`

Description

  Set an alarm clock for delivery of a signal.

  alarm() arranges for a SIGALRM signal to be delivered to the process in seconds seconds.

  If seconds is `0` (zero), no new alarm will be scheduled.

  Any previous alarms will in any case be canceled.

Returns

  Returns the number of seconds remaining until any previously scheduled alarm was due to be delivered, or zero if there was no previously scheduled alarm.

Note

  This function is only available on platforms that support signals.

See also

  ualarm(), signal(), call_out()

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

  `array allocate(int size)`
  `array allocate(int size, mixed init)`

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

  `array array_sscanf(string data, string format)`

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 arrayp

  `int arrayp(mixed arg)`

Description

  Returns `1` if arg is an array, `0` (zero) otherwise.

See also

  intp(), programp(), mappingp(), stringp(), objectp(), multisetp(), floatp(), functionp()

Method asin

  `float asin(int|float f)`

Description

  Return the arcus sine value for f. The result will be in radians.

See also

  sin(), acos()

Method asinh

  `float asinh(int|float f)`

Description

  Return the hyperbolic arcus sine value for f.

See also

  sinh(), acosh()

Method atan

  `float atan(int|float f)`

Description

  Returns the arcus tangent value for f. The result will be in radians.

See also

  tan(), asin(), acos(), atan2()

Method atan2

  `float atan2(float f1, float f2)`

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

  `float atanh(int|float f)`

Description

  Returns the hyperbolic arcus tangent value for f.

See also

  tanh(), asinh(), acosh()

Method atexit

  `void atexit(function(:void) callback)`

Description

  This function puts the callback in a queue of callbacks to call when pike exits. The call order is reversed, i.e. callbacks that have been added earlier are called after callback.

Note

  Please note that atexit callbacks are not called if Pike exits abnormally.

See also

  exit(), _exit()

Method backtrace

  `array(Pike.BacktraceFrame) backtrace()`

Description

  FIXME: This documentation is not up to date!

  Get a description of the current call stack.

  The description is returned as an array with one entry for each call frame on the stack.

  Each entry has this format:

  Array
  `string file` | A string with the filename if known, else zero.
  `int line` | An integer containing the linenumber if known, else zero.
  `function(:void) fun` | The function that was called at this level.
  `mixed|void ... args` | The arguments that the function was called with.

  The current call frame will be last in the array.

Note

  Please note that the frame order may be reversed in a later version (than 7.1) of Pike to accommodate for deferred backtraces.

  Note that the arguments reported in the backtrace are the current values of the variables, and not the ones that were at call-time. This can be used to hide sensitive information from backtraces (eg passwords).

See also

  catch(), throw()

Method basename

  `string basename(string x)`

Description

  Returns the last segment of a path.

See also

  dirname(), explode_path()

Method basetype

  `string basetype(mixed x)`

Description

  Same as sprintf("%t",x);

See also

  sprintf()

Method callablep

  `int callablep(mixed arg)`

Description

  Returns `1` if arg is a callable, `0` (zero) otherwise.

See also

  mappingp(), programp(), arrayp(), stringp(), objectp(), multisetp(), floatp(), intp()

Method cd

  `int cd(string s)`

Description

  Change the current directory for the whole Pike process.

Returns

  Returns `1` for success, `0` (zero) otherwise.

See also

  getcwd()

Method ceil

  `float ceil(int|float f)`

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 column

  `array column(array data, mixed index)`

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 combine_path
Method combine_path_unix
Method combine_path_nt
Method combine_path_amigaos

  `string combine_path(string path, string ... paths)`
  `string combine_path_unix(string path, string ... paths)`
  `string combine_path_nt(string path, string ... paths)`
  `string combine_path_amigaos(string path, string ... paths)`

Description

  Concatenate a number of paths to a straightforward path without any `"//"`, `"/.."` or `"/."`. If any path argument is absolute then the result is absolute and the preceding arguments are ignored. If the result is relative then it might have leading `".."` components. If the last nonempty argument ends with a directory separator then the result ends with that too. If all components in a relative path disappear due to subsequent `".."` components then the result is `"."`.

  combine_path_unix() concatenates in UNIX style, which also is appropriate for e.g. URL:s ("/" separates path components and absolute paths start with "/"). combine_path_nt() concatenates according to NT filesystem conventions ("/" and "\" separates path components and there might be a drive letter in front of absolute paths). combine_path_amigaos() concatenates according to AmigaOS filesystem conventions.

  combine_path() is equivalent to combine_path_unix() on UNIX-like operating systems, and equivalent to combine_path_nt() on NT-like operating systems, and equivalent to combine_path_amigaos() on AmigaOS-like operating systems.

See also

  getcwd(), Stdio.append_path()

Method compile

  `program compile(string source, CompilationHandler|void handler, int|void major, int|void minor, program|void target, object|void placeholder)`

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

  `program compile_file(string filename, object|void handler, void|program p, void|object o)`

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 `<font face='courier'>compile_string`(<font face='courier'>Stdio.read_file(<font face='courier'>filename), <font face='courier'>filename).

See also

  compile(), compile_string(), cpp()

Method compile_string

  `program compile_string(string source, void|string filename, object|void handler, void|program p, void|object o, void|int _show_if_constant_errors)`

Description

  Compile the Pike code in the string source into a program. If filename is not specified, it will default to `"-"`.

  Functionally equal to `<font face='courier'>compile`(<font face='courier'>cpp(<font face='courier'>source, <font face='courier'>filename)).

See also

  compile(), cpp(), compile_file()

Method copy_value

  `mixed copy_value(mixed value)`

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

  `float cos(int|float f)`

Description

  Return the cosine value for f. f should be specified in radians.

See also

  acos(), sin(), tan()

Method cosh

  `float cosh(int|float f)`

Description

  Return the hyperbolic cosine value for f.

See also

  acosh(), sinh(), tanh()

Method cpp

  `string cpp(string data, mapping|string|void current_file, int|string|void charset, object|void handler, void|int compat_major, void|int compat_minor, void|int picky_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" : int|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.

See also

  compile()

Method crypt

  `string(7bit) crypt(string password)`
  `bool crypt(string typed_password, string crypted_password)`

Description

  This function crypts and verifies a short string (only the first 8 characters are significant).

  The first syntax crypts the string password into something that is hopefully hard to decrypt.

  The second syntax is used to verify typed_password against crypted_password, and returns `1` if they match, and `0` (zero) otherwise.

Note

  Note that strings containing null characters will only be processed up until the null character.

Method ctime

  `string ctime(int timestamp)`

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

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

Method decode_value

  `mixed decode_value(string coded_value, void|Codec codec)`

Description

  Decode a value from the string coded_value.

  This function takes a string created with encode_value() or encode_value_canonic() and converts it back to the value that was coded.

  If codec is specified, it's used as the codec for the decode. If 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.

See also

  encode_value(), encode_value_canonic()

Method delay

  `void delay(int|float s)`

Description

  This function makes the program stop for s seconds.

  Only signal handlers can interrupt the sleep. Other callbacks are not called during delay. Beware that this function uses busy-waiting to achieve the highest possible accuracy.

See also

  signal(), sleep()

Method describe_backtrace

  `string describe_backtrace(mixed trace, void|int linewidth)`

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

  `string describe_error(mixed err)`

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

  `void destruct(void|object o)`

Description

  Mark an object as destructed.

  Calls `o->destroy()`, and then clears all variables in the object. If no argument is given, the current object is destructed.

  All pointers and function pointers to this object will become zero. The destructed object will be freed from memory as soon as possible.

Method destructedp

  `int destructedp(mixed arg)`

Description

  Returns `1` if arg is a destructed object, `0` (zero) otherwise.

See also

  zero_type, undefinedp, intp

Method dirname

  `string dirname(string x)`

Description

  Returns all but the last segment of a path. Some example inputs and outputs:

  Expression | Value
  dirname("/a/b") | "/a"
  dirname("/a/") | "/a"
  dirname("/a") | "/"
  dirname("/") | "/"
  dirname("") | ""

See also

  basename(), explode_path()

Method encode_value

  `string encode_value(mixed value, Codec|void codec)`

Description

  Code a value into a string.

  This function takes a value, and converts it to a string. This string can then be saved, sent to another Pike process, packed or used in any way you like. When you want your value back you simply send this string to decode_value() and it will return the value you encoded.

  Almost any value can be coded, mappings, floats, arrays, circular structures etc.

  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 `<font face='courier'>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 encode_value_canonic(mixed value, object|void codec)`

Description

  Code a value into a string on canonical form.

  Takes a value and converts it to a string on canonical form, much like encode_value(). The canonical form means that if an identical value is encoded, it will produce exactly the same string again, even if it's done at a later time and/or in another Pike process. The produced string is compatible with decode_value().

Note

  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(int n)`
  `array enumerate(int n, void|mixed step, void|mixed start, 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

  `int equal(mixed a, mixed b)`

Description

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

  For all types but arrays, multisets and mappings, this operation is the same as doing `<font face='courier'>a` == <font face='courier'>b. For arrays, mappings and multisets however, their contents are checked recursively, and if all their contents are the same and in the same place, they are considered equal.

See also

  copy_value()

Method errno

  `int errno()`

Description

  This function returns the system error from the last file operation.

Note

  Note that you should normally use Stdio.File->errno() instead.

See also

  Stdio.File->errno(), strerror()

Method error

  `void error(sprintf_format f, sprintf_args ... args)`

Description

  Throws an error. A more readable version of the code `throw( ({ sprintf(f, @args), backtrace() }) )`.

Method exece

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

Description

  This function transforms the Pike process into a process running the program specified in the argument file with the arguments args.

  If the mapping env is present, it will completely replace all environment variables before the new program is executed.

Returns

  This function only returns if something went wrong during `exece(2)`, and in that case it returns `0` (zero).

Note

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

  This function is not available on all platforms.

See also

  Process.create_process(), fork(), Stdio.File->pipe()

Method exit

  `void exit(int returncode, void|string fmt, mixed ... extra)`

Description

  Exit the whole Pike program with the given returncode.

  Using exit() with any other value than `0` (zero) indicates that something went wrong during execution. See your system manuals for more information about return codes.

  The arguments after the returncode will be used for a call to werror to output a message on stderr.

See also

  _exit()

Method exp

  `float exp(float|int f)`

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 explode_path

  `array(string) explode_path(string p)`

Description

  Split a path p into its components.

  This function divides a path into its components. This might seem like it could be done by dividing the string on <tt>"/"</tt>, but that will not work on some operating systems. To turn the components back into a path again, use combine_path().

Method file_stat

  `Stdio.Stat file_stat(string path, void|bool symlink)`

Description

  Stat a file.

  If the argument symlink is `1` symlinks will not be followed.

Returns

  If the path specified by path doesn't exist `0` (zero) will be returned.

  Otherwise an object describing the properties of path will be returned.

Note

  In Pike 7.0 and earlier this function returned an array with 7 elements. The old behaviour can be simulated with the following function:

  array(int) file_stat(string path, void|int(0..1) symlink) { File.Stat st = predef::file_stat(path, symlink); if (!st) return 0; return (array(int))st; }

See also

  Stdio.Stat, Stdio.File->stat()

Method file_truncate

  `int file_truncate(string file, int length)`

Description

  Truncates the file file to the length specified in length.

Returns

  Returns 1 if ok, 0 if failed.

Method filesystem_stat

  `mapping(string:int) filesystem_stat(string path)`

Description

  Returns a mapping describing the properties of the filesystem containing the path specified by path.

Returns

  If a filesystem cannot be determined `0` (zero) will be returned.

  Otherwise a mapping(string:int) with the following fields will be returned:

  `"blocksize" : int` | Size in bytes of the filesystem blocks.
  `"blocks" : int` | Size of the entire filesystem in blocks.
  `"bfree" : int` | Number of free blocks in the filesystem.
  `"bavail" : int` | Number of available blocks in the filesystem. This is usually somewhat less than the `"bfree"` value, and can usually be adjusted with eg tunefs(1M).
  `"files" : int` | Total number of files (aka inodes) allowed by this filesystem.
  `"ffree" : int` | Number of free files in the filesystem.
  `"favail" : int` | Number of available files in the filesystem. This is usually the same as the `"ffree"` value, and can usually be adjusted with eg tunefs(1M).
  `"fsname" : string` | Name assigned to the filesystem. This item is not available on all systems.
  `"fstype" : string` | Type of filesystem (eg `"nfs"`). This item is not available on all systems.

Note

  Please note that not all members are present on all OSs.

See also

  file_stat()

Method filter

  `mixed filter(mixed arr, void|mixed fun, mixed ... extra)`

Description

  Filters the elements in arr through fun.

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

  array
  multiset
  string

    Each element is filtered with fun. The return value is of the same type as arr and it contains the elements that fun accepted. fun is applied in order to each element, and that order is retained between the kept elements.

    If fun is an array, it should have the same length as arr. In this case, the elements in arr are kept where the corresponding positions in fun are nonzero. Otherwise fun is used as described below.

  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.

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

  function

    fun is called for each element. It gets the current element as the first argument and extra as the rest. The element is kept if it returns true, otherwise it's filtered out.

  object

    The object is used as a function like above, i.e. the lfun::`() method in it is called.

  multiset
  mapping

    fun is indexed with each element. The element is kept if the result is nonzero, otherwise it's filtered out.

  "zero or left out"

    Each element that is callable is called with extra as arguments. The element is kept if the result of the call is nonzero, otherwise it's filtered out. Elements that aren't callable are also filtered out.

  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 floatp

  `int floatp(mixed arg)`

Description

  Returns `1` if arg is a float, `0` (zero) otherwise.

See also

  intp(), programp(), arrayp(), multisetp(), objectp(), mappingp(), stringp(), functionp()

Method floor

  `float floor(int|float f)`

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 fork

  `object fork()`

Description

  Fork the process in two.

  Fork splits the process in two, and for the parent it returns a pid object for the child. Refer to your Unix manual for further details.

Note

  This function can cause endless bugs if used without proper care.

  This function is disabled when using threads.

  This function is not available on all platforms.

  The most common use for fork is to start sub programs, which is better done with Process.create_process().

See also

  Process.create_process()

Method function_name

  `string function_name(function(:void)|program f)`

Description

  Return the name of the function or program f.

  If f is a global function defined in the runtime `0` (zero) will be returned.

See also

  function_object()

Method function_object

  `object function_object(function(:void) f)`

Description

  Return the object the function f is in.

  If f is a global function defined in the runtime `0` (zero) will be returned.

  Zero will also be returned if f is a constant in the parent class. In that case function_program() can be used to get the parent program.

See also

  function_name(), function_program()

Method function_program

  `program function_program(function(:void)|program f)`

Description

  Return the program the function f is in.

  If f is a global function defined in the runtime `0` (zero) will be returned.

See also

  function_name(), function_object()

Method functionp

  `int functionp(mixed arg)`

Description

  Returns `1` if arg is a function, `0` (zero) otherwise.

See also

  mappingp(), programp(), arrayp(), stringp(), objectp(), multisetp(), floatp(), intp()

Method gc

  `int gc()`

Description

  Force garbage collection.

  This function checks all the memory for cyclic structures such as arrays containing themselves and frees them if appropriate. It also frees up destructed objects and things with only weak references.

  Normally there is no need to call this function since Pike will call it by itself every now and then. (Pike will try to predict when 20% of all arrays/object/programs in memory is 'garbage' and call this routine then.)

Returns

  The amount of garbage is returned. This is the number of arrays, mappings, multisets, objects and programs that had no nonweak external references during the garbage collection. It's normally the same as the number of freed things, but there might be some difference since destroy() functions are called during freeing, which can cause more things to be freed or allocated.

See also

  Pike.gc_parameters, Debug.gc_status

Method get_active_compilation_handler

  `CompilationHandler get_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_error_handler

  `CompilationHandler get_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

  `array get_backtrace(object|array err)`

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_dir

  `array(string) get_dir(void|string dirname)`

Description

  Returns an array of all filenames in the directory dirname, or `0` (zero) if the directory does not exist. When no dirname is given, current work directory is used.

See also

  mkdir(), cd()

Method get_groups_for_user

  `array(int) get_groups_for_user(int|string user)`

Description

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

Parameter `user`

  UID or loginname of the user

Returns

  Array
  `array 0..` | Information about all the users groups

See also

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

Method get_iterator

  `Iterator get_iterator(object|array|mapping|multiset|string data)`

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 it's called in it to create the iterator. If data is an object that lacks lfun::_get_iterator then it's assumed to already be an iterator object, and is simply returned.
  `array` | If data is an array, an Array.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 get_profiling_info

  `array(int|mapping(string:array(int))) get_profiling_info(program prog)`

Description

  Get profiling information.

Returns

  Returns an array with two elements.

  Array
  `int num_clones` | The first element is the number of times the program prog has been instantiated.

  `mapping(string:array(int)) fun_prof_info`

  The second element is mapping from function name to an array with three elements.

  Array
  `int num_calls` | The first element is the number of times the function has been called.
  `int total_time` | The second element is the total time (in milliseconds) spent executing this function, and any functions called from it.
  `int self_time` | The third element is the time (in milliseconds) actually spent in this function so far.

Note

  This function is only available if the runtime was compiled with the option `--with-profiling`.

Method get_weak_flag

  `int get_weak_flag(array|mapping|multiset m)`

Description

  Returns the weak flag settings for m. It's a combination of Pike.WEAK_INDICES and Pike.WEAK_VALUES.

Method getcwd

  `string getcwd()`

Description

  Returns the current working directory.

See also

  cd()

Method getgrgid

  `array(int|string|array(string)) getgrgid(int gid)`

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
  `string 0` | Group name
  `string 1` | Group password (encrypted)
  `int 2` | ID of the group
  `array 3..` | Array with UIDs of group members

See also

  getgrent() getgrnam()

Method getgrnam

  `array(int|string|array(string)) getgrnam(string str)`

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
  `string 0` | Group name
  `string 1` | Group password (encrypted)
  `int 2` | ID of the group
  `array 3..` | Array with UIDs of group members

See also

  getgrent() getgrgid()

Method gethrdtime

  `int gethrdtime(void|int nsec)`

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

  `int gethrtime(void|int nsec)`

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

  `int gethrvtime(void|int nsec)`

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

  `int getpid()`

Description

  Returns the process ID of this process.

See also

  System.getppid(), System.getpgrp()

Method getpwnam

  `array(int|string) getpwnam(string str)`

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
  `string 0` | Users username (loginname)
  `string 1` | User password (encrypted)
  `int 2` | Users ID
  `int 3` | Users primary group ID
  `string 4` | Users real name an possibly some other info
  `string 5` | Users home directory
  `string 6` | Users shell

See also

  getpwuid() getpwent()

Method getpwuid

  `array(int|string) getpwuid(int uid)`

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
  `string 0` | Users username (loginname)
  `string 1` | User password (encrypted)
  `int 2` | Users ID
  `int 3` | Users primary group ID
  `string 4` | Users real name an possibly some other info
  `string 5` | Users home directory
  `string 6` | Users shell

See also

  getpwnam() getpwent()

Method getxattr

  `string getxattr(string file, string attr, void|bool symlink)`

Description

  Return the value of a specified attribute, or 0 if it does not exist.

Method glob

  `bool glob(string glob, string str)`
  `bool glob(array(string) glob, string str)`
  `array(string) glob(string glob, 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. A question sign ('?') matches any character and an asterisk ('*') matches a string of arbitrary length. All other characters only match themselves.
  `array(string)` | the function returns true, or keeps a string, if any of the given patterns match

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

See also

  sscanf(), Regexp

Method gmtime

  `mapping(string:int) gmtime(int timestamp)`

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.

See also

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

Method has_index

  `int has_index(string haystack, int index)`
  `int has_index(array haystack, int index)`
  `int has_index(mapping|multiset|object|program haystack, mixed index)`

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

  `int has_prefix(string|object s, string prefix)`

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

  `int has_suffix(string s, string suffix)`

Description

  Returns `1` if the string s ends with suffix, returns `0` (zero) otherwise.

See also

  has_prefix(), has_value(), search()

Method has_value

  `int has_value(string haystack, string value)`
  `int has_value(string haystack, int value)`
  `int has_value(array|mapping|object|program haystack, mixed value)`

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

  `int hash(string s)`
  `int hash(string s, int max)`

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 7.5. If you want a hash that is compatible with Pike 7.4 and earlier, use 7.4::hash(). 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 7.0::hash().

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(), 7.4::hash(), hash_value

Method hash_7_0

  `int hash_7_0(string s)`
  `int hash_7_0(string s, int max)`

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(), 7.4::hash()

Method hash_7_4

  `__deprecated__ int hash_7_4(string s)`
  `__deprecated__ int hash_7_4(string s, int max)`

Deprecated

  Replaced by 7.4::hash.

See also

  7.4::hash(), hash()

Method hash_value

  `int hash_value(mixed value)`

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

  hash(), lfun::__hash()

Method indices

  `array indices(string|array|mapping|multiset|object x)`

Description

  Return an array of all valid indices for the value x.

  For strings and arrays this is simply an array of ascending numbers.

  For mappings and multisets, the array might contain any value.

  For objects which define lfun::_indices() that return value is used.

  For other objects an array with all non-protected symbols is returned.

See also

  values(), types(), lfun::_indices()

Method intp

  `int intp(mixed arg)`

Description

  Returns `1` if arg is an int, `0` (zero) otherwise.

See also

  mappingp(), programp(), arrayp(), stringp(), objectp(), multisetp(), floatp(), functionp()

Method is_absolute_path

  `int is_absolute_path(string p)`

Description

  Check if a path p is fully qualified (ie not relative).

Returns

  Returns 1 if the path is absolute, 0 otherwise.

Constant is_sql_null

  `constant int is_sql_null`

Description

  SQL Null marker.

Deprecated

  Replaced by is_val_null.

Constant is_val_null

  `constant int is_val_null`

Description

  Nonzero recognition constant.

Method kill

  `bool kill(int pid, int signal)`

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|object limit(int|float|object minval, int|float|object x, int|float|object maxval)`

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(string file, void|bool symlink)`

Description

  Return an array of all extended attributes set on the file

Method load_module

  `program load_module(string module_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(int timestamp)`

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 savings time.
  `"timezone" : int` | Offset from UTC, including daylight savings time adjustment.

  An error is thrown if the localtime(2) call failed on the system. It's platform dependent what time ranges that function can handle, e.g. Windows doesn't handle a negative timestamp.

Note

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

See also

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

Method log

  `float log(int|float f)`

Description

  Return the natural logarithm of f. `exp( log(x) ) == x` for x > 0.

See also

  pow(), exp()

Method lower_case

  `string lower_case(string s)`
  `int lower_case(int c)`

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_delete

  `mixed m_delete(object|mapping map, mixed index)`

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

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

Returns

  The value that was removed will be returned.

Note

  Note that m_delete() changes map destructively.

See also

  mappingp()

Method map

  `mixed map(mixed arr, void|mixed fun, mixed ... extra)`

Description

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

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

  array
  multiset
  string

    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.

  fun is applied in different ways depending on its type:

  function

    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.

  multiset
  mapping

    fun is indexed with each element. The result of that is collected.

  "zero or left out"

    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 mappingp

  `int mappingp(mixed arg)`

Description

  Returns `1` if arg is a mapping, `0` (zero) otherwise.

See also

  intp(), programp(), arrayp(), stringp(), objectp(), multisetp(), floatp(), functionp()

Method master

  `object master()`

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|object max(int|float|object, int|float|object ... args)`
  `string max(string, string ... args)`
  `int(0..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|object min(int|float|object, int|float|object ... args)`
  `string min(string, string ... args)`
  `int(0..0) min()`

Description

  Returns the smallest value among args. Compared objects must implement the lfun::`< method.

See also

  max() and limit()

Method mkdir

  `int mkdir(string dirname, void|int mode)`

Description

  Create a directory.

  If mode is specified, it's will be used for the new directory after being `&`'ed with the current umask (on OS'es that support this).

Returns

  Returns `0` (zero) on failure, `1` otherwise.

See also

  rm(), cd(), Stdio.mkdirhier()

Method mkmapping

  `mapping mkmapping(array ind, array val)`

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

  `multiset mkmultiset(array a)`

Description

  This function creates a multiset from an array.

See also

  aggregate_multiset()

Method mktime

  `int mktime(mapping(string:int) tm)`
  `int mktime(int sec, int min, int hour, int mday, int mon, int year, int|void isdst, int|void tz)`

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" : bool` | Is daylight savings time.
  `"timezone" : int` | The timezone offset from UTC in seconds. If left out, the time will be calculated in the local timezone.

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

Note

  On some operating systems (notably AIX and Win32), dates before 00:00:00 UTC, Jan 1, 1970 are not supported.

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

See also

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

Method multisetp

  `int multisetp(mixed arg)`

Description

  Returns `1` if arg is a multiset, `0` (zero) otherwise.

See also

  intp(), programp(), arrayp(), stringp(), objectp(), mappingp(), floatp(), functionp()

Method mv

  `int mv(string from, string to)`

Description

  Rename or move a file or directory.

  If the destination already exists, it will be replaced. Replacement often only works if to is of the same type as from, i.e. a file can only be replaced by another file and so on. Also, a directory will commonly be replaced only if it's empty.

  On some OSs this function can't move directories, only rename them.

Returns

  Returns `0` (zero) on failure, `1` otherwise. Call errno() to get more error info on failure.

See also

  rm()

Method next_object

  `object next_object(object o)`
  `object next_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 normalize_path

  `string normalize_path(string path)`

Description

  Replaces "\" with "/" if runing on MS Windows. It is adviced to use System.normalize_path instead.

Method object_program

  `program|function(:void) object_program(mixed o)`

Description

  Return the program from which o was instantiated. If the object was instantiated from a class using parent references the generating function will be returned.

  If o is not an object or has been destructed `0` (zero) will be returned.

Method object_variablep

  `bool object_variablep(object o, string var)`

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

  `int objectp(mixed arg)`

Description

  Returns `1` if arg is an object, `0` (zero) otherwise.

See also

  mappingp(), programp(), arrayp(), stringp(), functionp(), multisetp(), floatp(), intp()

Method pow

  `int|float pow(float|int n, float|int x)`
  `mixed pow(object n, float|int|object x)`

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 programp

  `int programp(mixed arg)`

Description

  Returns `1` if arg is a program, `0` (zero) otherwise.

See also

  mappingp(), intp(), arrayp(), stringp(), objectp(), multisetp(), floatp(), functionp()

Method query_num_arg

  `int query_num_arg()`

Description

  Returns the number of arguments given when the previous function was called.

  This is useful for functions that take a variable number of arguments.

See also

  call_function()

Method random

  `mixed random(object o)`

Description

  If random is called with an object, lfun::random will be called in the object.

See also

  lfun::_random()

Method random

  `int random(int max)`

Description

  This function returns a random number in the range `0 .. <font face='courier'>max`-1.

See also

  random_seed()

Method random

  `float random(float max)`

Description

  This function returns a random number in the range `0 .. <font face='courier'>max`-ɛ.

See also

  random_seed()

Method random

  `mixed random(array|multiset x)`

Description

  Returns a random element from x.

Method random

  `array random(mapping m)`

Description

  Returns a random index-value pair from the mapping.

Method random_seed

  `void random_seed(int seed)`

Description

  This function sets the initial value for the random generator.

See also

  random()

Method random_string

  `string random_string(int len)`

Description

  Returns a string of random characters 0-255 with the length len.

Method removexattr

  `void removexattr(string file, string attr, void|bool symlink)`

Description

  Remove the specified extended attribute.

Method replace

  `string replace(string s, string from, string to)`
  `string replace(string s, array(string) from, array(string) to)`
  `string replace(string s, array(string) from, string to)`
  `string replace(string s, mapping(string:string) replacements)`
  `array replace(array a, mixed from, mixed to)`
  `mapping replace(mapping a, mixed from, mixed to)`

Description

  Generic replace function.

  This function can do several kinds replacement operations, the different syntaxes do different things as follows:

  If all the arguments are strings, a copy of s with every occurrence of from replaced with to will be returned. Special case: to will be inserted between every character in s if from is the empty string.

  If the first argument is a string, and the others array(string), a string with every occurrance of from[i] in s replaced with to[i] will be returned. Instead of the arrays from and to a mapping equvivalent to `<font face='courier'>mkmapping`(<font face='courier'>from, <font face='courier'>to) can be used.

  If the first argument is an array or mapping, the values of a which are `==() with from will be replaced with to destructively. a will then be returned.

Note

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

Method replace_master

  `void replace_master(object o)`

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

  `string reverse(string s, int|void start, int|void end)`
  `array reverse(array a, int|void start, int|void end)`
  `int reverse(int i, int|void start, int|void end)`

Description

  Reverses a string, array or int.

Parameter `s`

  String to reverse.

Parameter `a`

  Array to reverse.

Parameter `i`

  Integer 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`.

  This function reverses a string, char by char, an array, value by value or an int, bit by bit and returns the result. It's not destructive on the input value.

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

See also

  sscanf()

Method rm

  `int rm(string f)`

Description

  Remove a file or directory.

Returns

  Returns `0` (zero) on failure, `1` otherwise.

See also

  mkdir(), Stdio.recursive_rm()

Method round

  `float round(int|float f)`

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

  `array rows(mixed data, array index)`

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

  `int search(string haystack, string|int needle, int|void start)`
  `int search(array haystack, mixed needle, int|void start)`
  `mixed search(mapping haystack, mixed needle, mixed|void start)`
  `mixed search(object haystack, mixed needle, mixed|void start)`

Description

  Search for needle in haystack. Return the position of needle in haystack or `-1` if not found.

  If the optional argument start is present search is started at this position.

  `haystack` can have any of the following types:

  `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. If needle isn't present in the mapping, zero is returned, and zero_type() will return 1 for this zero.

  `object`

  When haystack is an object implementing lfun::_search(), the result of calling lfun::_search() with needle will be returned.

  If haystack is an object that doesn't implement lfun::_search() it is assumed to be an Iterator, and implement Iterator()->index(), Iterator()->value(), and Iterator()->next(). search() will then start comparing elements with `==() until a match with needle is found. If needle is found haystack will be advanced to the element, and the iterator index will be returned. If needle is not found, haystack will be advanced to the end (and will thus evaluate to false), and a zero with zero_type 1 will be returned.

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

  `int set_priority(string level, int(0..)|void pid)`

Method set_weak_flag

  `array|mapping|multiset set_weak_flag(array|mapping|multiset m, int state)`

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

  `void setxattr(string file, string attr, string value, int flags, void|bool symlink)`

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

  `int sgn(mixed value)`
  `int sgn(mixed value, mixed zero)`

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(int sig, function(int|void:void) callback)`
  `function(int|void:void) signal(int sig)`

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

  `string signame(int sig)`

Description

  Returns a string describing the signal sig.

See also

  kill(), signum(), signal()

Method signum

  `int signum(string sig)`

Description

  Get a signal number given a descriptive string.

  This function is the inverse of signame().

See also

  signame(), kill(), signal()

Method sin

  `float sin(int|float f)`

Description

  Returns the sine value for f. f should be specified in radians.

See also

  asin(), cos(), tan()

Method sinh

  `float sinh(int|float f)`

Description

  Returns the hyperbolic sine value for f.

See also

  asinh(), cosh(), tanh()

Method sizeof

  `int sizeof(string arg)`
  `int sizeof(array arg)`
  `int sizeof(mapping arg)`
  `int sizeof(multiset arg)`
  `int sizeof(object arg)`

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

  `void sleep(int|float s, void|int abort_on_signal)`

Description

  This function makes the program stop for s seconds.

  Only signal handlers can interrupt the sleep, and only when abort_on_signal is set. If more than one thread is running the signal must be sent to the sleeping thread. Other callbacks are not called during sleep.

  If s is zero then this thread will yield to other threads but not sleep otherwise. Note that Pike yields internally at regular intervals so it's normally not necessary to do this.

See also

  signal(), delay()

Method sort

  `array sort(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

  `string sprintf(strict_sprintf_format format, 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 size. Breaks between words (possibly skipping or adding spaces). Can not be used together with `'/'`.
  `'/'` | Column mode with rough line break (break at exactly field size 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.
  `"width" : int(0..)|void` | Field width.
  `"flag_left" : bool|void` | Indicates that the output should be left-aligned.
  `"indent" : int(0..)|void` | Indentation level 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.
  `'X'` | Uppercase signed hexadecimal integer.
  `'c'` | Character. If a fieldsize has been specified this will output the low-order bytes of the integer in network (big endian) byte order. To get little endian byte order, negate the field size.
  `'f'` | Float. (Locale dependent formatting.)
  `'g'` | Heuristically chosen representation of float. (Locale dependent formatting.)
  `'G'` | Like `%g`, but uses uppercase `E` for exponent.
  `'e'` | Exponential notation float. (Locale dependent output.)
  `'E'` | Like `%e`, but uses uppercase `E` for exponent.
  `'F'` | Binary IEEE representation of float (`%4F` gives single precision, `%8F` gives double precision) 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.
  `'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

  The `'q'` operator was added in Pike 7.7.

Note

  Support for specifying modifiers via a mapping was added in Pike 7.8. This support can be tested for with the constant String.__HAVE_SPRINTF_STAR_MAPPING__.

Note

  Support for specifying little endian byte order to `'F'` was added in Pike 7.8. This support can be tested for with the constant String.__HAVE_SPRINTF_NEGATIVE_F__.

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",screen_width, "THE END"); THE END (14) Result: 71 > write("%|*s\n", ([ "width":screen_width ]), "ALTERNATIVE END"); ALTERNATIVE END (15) Result: 71

See also

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

Constant sprintf_args

  `constant sprintf_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

  `constant sprintf_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

  `constant sprintf_result`

Description

  Type constant used for typing the return value from sprintf().

See also

  strict_sprintf_format, sprintf_format, sprintf()

Method sqrt

  `float sqrt(float f)`
  `int sqrt(int i)`
  `mixed sqrt(object o)`

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

  `int sscanf(string data, string format, 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 an opcode, rather than a pike function) with the values extracted from the data according to the format specification. Only the variables up to the last matching directive of the format string are touched.

  The format string can contain strings separated by special matching directives like `%d`, `%s` `%c` and `%f`. Every such directive corresponds to one of the lvalues, in order they are listed. An lvalue is the name of a variable, a name of a local variable, an index in an array, mapping or object. It is because of these lvalues that sscanf can not be implemented as a normal function.

  Whenever a percent character is found in the format string, a match is performed, according to which operator and modifiers follow it:

  `"%b"` | Reads a binary integer (`"0101"` makes `5`)
  `"%d"` | Reads a decimal integer (`"0101"` makes `101`).
  `"%o"` | Reads an octal integer (`"0101"` makes `65`).
  `"%x"` | Reads a hexadecimal integer (`"0101"` makes `257`).
  `"%D"` | Reads an integer that is either octal (leading zero), hexadecimal (leading 0x) or decimal. (`"0101"` makes `65`).

  `"%c"`

  Reads one character and returns it as an integer (`"0101"` makes `48`, or `'0'`, leaving `"101"` for later directives). Using the field width and endianness modifiers, you can decode integers of any size and endianness. For example `"%-2c"` decodes `"0101"` into `12592`, leaving `"01"` fot later directives. The sign modifiers can be used to modify the signature of the data, making `"%+1c"` decode `"ä"` into `-28`.

  `"%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 strerror

  `string strerror(int errno)`

Description

  This function returns a description of an error code. The error code is usually obtained from eg Stdio.File->errno().

Note

  On some platforms the string returned can be somewhat nondescriptive.

Constant strict_sprintf_format

  `constant strict_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()

Method string_filter_non_unicode

  `string(1..) string_filter_non_unicode(string s)`

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(string s, int(0..2)|void byteorder)`

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

  `string(8bit) string_to_utf8(string s)`
  `string(8bit) string_to_utf8(string s, int extended)`

Description

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

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

  If extended is 1 then characters outside the valid ranges are accepted too and encoded using the same algorithm. Such encoded characters are however not UTF-8 compliant.

See also

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

Method stringp

  `int stringp(mixed arg)`

Description

  Returns `1` if arg is a string, `0` (zero) otherwise.

See also

  intp(), programp(), arrayp(), multisetp(), objectp(), mappingp(), floatp(), functionp()

Method strlen

  `int strlen(string|multiset|array|mapping|object thing)`

Description

  Alias for sizeof.

Deprecated

  Replaced by sizeof.

Method tan

  `float tan(int|float f)`

Description

  Returns the tangent value for f. f should be specified in radians.

See also

  atan(), sin(), cos()

Method tanh

  `float tanh(int|float f)`

Description

  Returns the hyperbolic tangent value for f.

See also

  atanh(), sinh(), cosh()

Constant this

  `constant this`

Description

  Builtin read only variable that evaluates to the current object.

See also

  this_program, this_object()

Method this_object

  `object this_object(void|int level)`

Description

  Returns the object we are currently evaluating in.

  level might be used to access the object of a surrounding class: The object at level 0 is the current object, the object at level 1 is the one belonging to the class that surrounds the class that the object comes from, and so on.

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.

Constant this_program

  `constant this_program`

Description

  Builtin constant that evaluates to the current program.

See also

  this, this_object()

Method throw

  `mixed|void throw(mixed value)`

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

  `int time()`
  `int time(int(1..1) one)`
  `float time(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 latest done by the pike process is returned again. That's slightly faster but can be wildly inaccurate. Pike queries the time internally when a thread has waited for something, typically in sleep or in a backend (see Pike.Backend).

  The third syntax can be used to measure time more preciely than one second. It return how many seconds has passed since t. The precision of this function varies from system to system.

See also

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

Method trace

  `int trace(int level, void|string facility, void|int all_threads)`

Description

  This function changes the trace level for the subsystem identified by facility to level. If facility is zero or left out, it changes the global trace level which affects all subsystems.

  Enabling tracing causes messages to be printed to stderr. A higher trace level includes the output from all lower levels. The lowest level is zero which disables all trace messages.

  See the `-t` command-line option for more information.

Parameter `level`

  If facility is specified then there is typically only one trace level for it, i.e. it's an on-or-off toggle. The global trace levels, when facility isn't specified, are:

  `1` | Trace calls to Pike functions and garbage collector runs.
  `2` | Trace calls to builtin functions.
  `3` | Trace every interpreted opcode.
  `4` | Also trace the opcode arguments.

Parameter `facility`

  Valid facilities are:

  `"gc"`

  Trace the doings of the garbage collector. The setting is never thread local. level has two different meanings:
  1..2

    Trace the start and end of each gc run.

  3..

    Additionally show info about the collected garbage, to aid hunting down garbage problems. This currently shows gc'd trampolines. Note that the output can be very bulky and is somewhat low-level technical. Also note that pike currently has to be configured with `--with-rtldebug` to enable this.

Parameter `all_threads`

  Trace levels are normally thread local, so changes affect only the current thread. To change the level in all threads, pass a nonzero value in this argument.

Returns

  The old trace level in the current thread is returned.

Method types

  `array(type) types(string|array|mapping|multiset|object x)`

Description

  Return an array of all valid indices for the value x.

  For strings this is simply an array with `int`

  For arrays, mappings and multisets this is simply an array with `mixed`.

  For objects which define lfun::_types() that return value is used.

  For other objects an array with type types for all non-protected symbols is returned.

Note

  This function was added in Pike 7.9.

See also

  indices(), values(), lfun::_types()

Method ualarm

  `int ualarm(int useconds)`

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 undefinedp

  `int undefinedp(mixed arg)`

Description

  Returns `1` if arg is undefined, `0` (zero) otherwise.

See also

  zero_type, destructedp, intp

Method unicode_to_string

  `string unicode_to_string(string(8bit) s, int(0..2)|void byteorder)`

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.

Note

  This function did not decode surrogates in Pike 7.2 and earlier.

See also

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

Method upper_case

  `string upper_case(string s)`
  `int upper_case(int c)`

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

  `string utf8_to_string(string(8bit) s)`
  `string utf8_to_string(string(8bit) s, int extended)`

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

Method values

  `array values(string|array|mapping|multiset|object x)`

Description

  Return an array of all possible values from indexing the value x.

  For strings an array of int with the ISO10646 codes of the characters in the string is returned.

  For a multiset an array filled with ones (`1`) is returned.

  For arrays a single-level copy of x is returned.

  For mappings the array may contain any value.

  For objects which define lfun::_values() that return value is used.

  For other objects an array with the values of all non-protected symbols is returned.

See also

  indices(), types(), lfun::_values()

Method version

  `string version()`

Description

  Report the version of Pike. Does the same as

  sprintf("Pike v%d.%d release %d", __REAL_VERSION__, __REAL_MINOR__, __REAL_BUILD__);

See also

  __VERSION__, __MINOR__, __BUILD__, __REAL_VERSION__, __REAL_MINOR__, __REAL_BUILD__,

Method werror

  `int werror(string fmt, mixed ... args)`

Description

  Writes a string on stderr. Works just like Stdio.File.write on Stdio.stderr.

Method write

  `int write(string fmt, mixed ... args)`

Description

  Writes a string on stdout. Works just like Stdio.File.write on Stdio.stdout.

Method zero_type

  `int zero_type(mixed a)`

Description

  Return the type of zero.

  There are many types of zeros out there, or at least there are two. One is returned by normal functions, and one returned by mapping lookups and find_call_out() when what you looked for wasn't there. The only way to separate these two kinds of zeros is zero_type().

Returns

  When doing a find_call_out() or mapping lookup, zero_type() on this value will return `1` if there was no such thing present in the mapping, or if no such `call_out` could be found.

  If the argument to zero_type() is a destructed object or a function in a destructed object, `2` will be returned.

  In all other cases zero_type() will return `0` (zero).

See also

  find_call_out()

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:

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

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

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

    `void compile_error(string filename, int line, string msg)`

  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

    `void compile_exception(mixed exception)`

  Description

    Called by compile() and cpp() if they trigger exceptions.

  Method compile_warning

    `void compile_warning(string filename, int line, string msg)`

  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)|object get_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

    `mixed handle_import(string path, string filename, CompilationHandler handler)`

  Description

    Called by compile() and cpp() to handle import directives specifying specific paths.

  Returns

    Returns the resolved value, or UNDEFINED on failure.

  Method handle_include

    `string handle_include(string header_file, string current_file, bool is_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

    `string read_include(string filename)`

  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

    `mixed resolv(string symbol, string filename, CompilationHandler handler)`

  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

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

  Method compile

    `program compile(string source, CompilationHandler|void handler, int|void major, int|void minor, program|void target, object|void placeholder)`

  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 get_compilation_handler

  `object get_compilation_handler(int major, int minor)`

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)|object get_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..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 handle_inherit

  `program handle_inherit(string inh, string current_file, object|void handler)`

Description

  Look up an inherit inh.

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

See also

  MasterObject()->handle_inherit().

Inherit Reporter

  inherit Reporter : Reporter

Description

  Implements the Reporter API.

See also

  Reporter()->report(), Reporter()->SeverityLevel

Method resolv

  `mixed resolv(string identifier, string filename, object|void handler)`

Description

  Look up identifier in the current context.

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

CLASS CompilerEnvironment.PikeCompiler

  Description

    The Pike compiler.

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

  Method apply_attribute_constant

    `type apply_attribute_constant(string attr, mixed value, type arg_type, void cont_type)`

  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.

    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 implements the `"sprintf_format"`, `"sscanf_format"` and `"sscanf_76_format"` attributes.

  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_type_attribute

    `bool apply_type_attribute(string attribute, type a, type|void b)`

  Description

    Type attribute handler.

  Parameter `attribute`

    Attribute that a had.

  Parameter `a`

    Type of the value being called.

  Parameter `b`

    Type of the first argument in the call, or UNDEFINED if no more arguments.

    Called during type checking when a has been successfully had a partial evaluation with the argument b and a had the type attribute attribute before the evaluation.

    The default implementation implements the "deprecated" attribute.

  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

    `void change_compiler_compatibility(int major, int minor)`

  Description

    Change compiler to attempt to be compatible with Pike major.minor.

  Method compile

    `program compile()`

  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

    `CompilerEnvironment.PikeCompiler CompilerEnvironment.PikeCompiler(string|void source, CompilationHandler|void handler, int|void major, int|void minor, program|void target, object|void placeholder)`

  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 get_compilation_handler

    `object get_compilation_handler(int major, int minor)`

  Description

    Get compatibility handler for Pike major.minor.

  Note

    This function is called by change_compiler_compatibility().

  Method get_default_module

    `mapping(string:mixed)|object get_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..0)` | Use the builtin constant table.

  Note

    This function is called by change_compiler_compatibility().

  Method handle_inherit

    `program handle_inherit(string inh)`

  Description

    Look up an inherit inh in the current program.

  Method pop_type_attribute

    `bool pop_type_attribute(string attribute, type a, type b)`

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

  Returns

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

  See also

    push_type_attribute()

  Method push_type_attribute

    `bool push_type_attribute(string attribute, type a, type b)`

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

  Returns

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

  See also

    pop_type_attribute()

  Method report

    `void report(SeverityLevel severity, string filename, int linenumber, string subsystem, string message, 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:

    1. Call handler->report().

    2. Call handler->compile_warning() or handler->compile_error() depending on severity.

    3. Call compat->report().

    4. Call compat->compile_warning() or compat->compile_error() depending on severity.

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

    `mixed resolv(string identifier, string filename, object handler)`

  Description

    Resolve the symbol identifier.

    The default implementation calls the corresponding function in any active handler, and otherwise falls back to CompilerEnvironment()->resolv() in the parent object.

  CLASS CompilerEnvironment.PikeCompiler.CompilerState

    Description

      Keeps the state of a single program/class during compilation.

    Note

      Not in use yet!

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(program p)`

  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(string data)`

  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

    `object objectof(string data)`

  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

    `program programof(string data)`

  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

    `mixed nameof(object|function(:void)|program x)`

  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; `!() will only return true then, and index and value will return UNDEFINED. An iterator in that state need not keep track of positions, so it's undefined what happens if it's "moved back" into the set of items.

    Backward movement for iterators is optional. It's supported if and only if `-() is defined, but even then it's undefined how far back the iterator can move. Therefore iterators may support only a limited amount of backward movement, e.g. when they access a stream through a limited buffer. If such an iterator is moved back past the limit then it'll behave as if it's pointing entirely outside the data set (see above).

    An iterator that doesn't support backward movement at all should throw an error if it's attempted.

  See also

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

  Method _random

    `void random( Iterator arg )`

  Description

    If this function is defined then it sets the iterator to point to a random item in the accessible set. The random distribution should be rectangular within that set, and the pseudorandom sequence provided by random should be used.

  Method _sizeof

    `int sizeof( Iterator arg )`

  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 `!

    `bool res = !Iterator()`

  Description

    Returns `0` (zero) when the iterator points to an item, `1` otherwise.

  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

    next, `+=, `-

  Method `+=

    `Iterator() += steps`

  Description

    Advance this iterator the specified number of steps and return it. The amount may be negative to move backwards. If the iterator doesn't support backward movement it should throw an exception in that case.

  Note

    foreach calls this function with a step value of `1` if next() doesn't exist for compatibility with Pike 7.6 and earlier.

  Note

    foreach will call this function even when the the iterator has more than one reference. If you want to loop over a copy of the iterator, you can create a copy by adding `0` (zero) to it:

    Iterator iterator; ... foreach(iterator+0; mixed index; mixed value) { ... }

Note

  Even though this function is sufficient for foreach to advance the iterator, next() is the preferred API. next() has the additional advantage of not being an lfun, so it is possible to advance the iterator by hand.

See also

  next, `+, `-

Method `-

  `Iterator res = Iterator() - steps`

Description

  This lfun should be defined if and only if the iterator supports backward movement to some degree. It should back up the specified number of steps. The amount may be negative to move forward.

See also

  next, `+, `+=

Method create

  `Iterator Iterator(void|mixed data)`

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

Method first

  `optional bool first()`

Description

  If this function is defined then it resets the iterator to point to 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 index

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

Method next

  `int next()`

Description

  If this function is defined it should advance the iterator one step, just like `<font face='courier'>`+=`(1) would do.

Note

  This is the preferred way to advance the iterator, since it reduces the overhead.

Note

  This function was optional in Pike 7.6 and earlier.

Returns

  Returns `1` if it succeeded in advancing, and `0` (zero) if it has reached the end of the iterator.

See also

  `+, `+=, `-

Method set_index

  `optional void set_index(zero index)`

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.

Method value

  `mixed value()`

Description

  Returns the current value, or UNDEFINED if the iterator doesn't point to any item.

CLASS MasterObject

  Description

    Master control program for Pike.

  See also

    predef::master(), predef::replace_master()

  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

  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.

  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.

  Method asyncp

    `bool asyncp()`

  Description

    Returns 1 if we´re in async-mode, e.g. if the main method has returned a negative number.

  Method backend_thread

    `object backend_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 basename

    `string basename(string x)`

  Description

    Returns the last segment of a path.

  See also

    dirname(), explode_path()

  Constant bt_max_string_len

    `constant int 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.

  Method cast_to_object

    `object cast_to_object(string oname, string current_file, object|void current_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

    `object cast_to_object(string str, string|void current_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

    `program cast_to_program(string pname, string current_file, object|void handler)`

  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

    `program cast_to_program(string str, string|void current_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()

  Variable cflags

    `string MasterObject.cflags`

  Description

    Flags suitable for use when compiling Pike C modules

  Variable compat_major

    `int MasterObject.compat_major`

  Variable compat_minor

    `int MasterObject.compat_minor`

  Method compile_error

    `void compile_error(string file, int line, string err)`

  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

    `int compile_exception(array|object trace)`

  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_file

    `program compile_file(string filename, object|void handler, void|program p, void|object o)`

  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 `<font face='courier'>compile_string`(<font face='courier'>Stdio.read_file(<font face='courier'>filename), <font face='courier'>filename).

  See also

    compile(), compile_string(), cpp()

  Method compile_string

    `program compile_string(string source, void|string filename, object|void handler, void|program p, void|object o, void|int _show_if_constant_errors)`

  Description

    Compile the Pike code in the string source into a program. If filename is not specified, it will default to `"-"`.

    Functionally equal to `<font face='courier'>compile`(<font face='courier'>cpp(<font face='courier'>source, <font face='courier'>filename)).

  See also

    compile(), cpp(), compile_file()

  Method compile_warning

    `void compile_warning(string file, int line, string err)`

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

  Variable currentversion

    `Version MasterObject.currentversion`

  Description

    Version information about the current Pike version.

  Method decode_charset

    `string decode_charset(string data, string charset)`

  Description

    This function is called by cpp() when it wants to do character code conversion.

  Method decode_charset

    `string decode_charset(string raw, string charset)`

  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

    `string describe_backtrace(mixed trace, void|int linewidth)`

  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_backtrace

    `string describe_backtrace(mixed exception)`

  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
    `string msg` | 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_error

    `string describe_error(mixed err)`

  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 describe_function

    `string describe_function(function(:void) f)`

  Method describe_module

    `string describe_module(object|program mod, array(object)|void ret_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 describe_object(object o)`

  Method describe_program

    `string describe_program(program|function(:void) p)`

  Method dirname

    `string dirname(string x)`

  Description

    Returns all but the last segment of a path. Some example inputs and outputs:

    Expression | Value
    dirname("/a/b") | "/a"
    dirname("/a/") | "/a"
    dirname("/a") | "/"
    dirname("/") | "/"
    dirname("") | ""

  See also

    basename(), explode_path()

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

  Method enable_source_cache

    `void enable_source_cache()`

  Description

    Enable caching of sources from compile_string()

  Method error

    `void error(sprintf_format f, sprintf_args ... args)`

  Description

    Throws an error. A more readable version of the code `throw( ({ sprintf(f, @args), backtrace() }) )`.

  Method explode_path

    `array(string) explode_path(string p)`

  Description

    Split a path p into its components.

    This function divides a path into its components. This might seem like it could be done by dividing the string on <tt>"/"</tt>, but that will not work on some operating systems. To turn the components back into a path again, use combine_path().

  Method fc_reverse_lookup

    `string fc_reverse_lookup(object obj)`

  Description

    Returns the path for obj in fc, if it got any.

  Method get_backtrace

    `array get_backtrace(object|array err)`

  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_compat_master

    `object get_compat_master(int major, int minor)`

  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

    `CompilationHandler get_compilation_handler(int major, int minor)`

  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

    `mixed 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

    `int get_precompiled_mtime(string id)`

  Description

    Given an identifier returned by query_precompiled_names, returns the mtime of the precompiled entry. Returns -1 if there is no entry.

  Method getenv

    `mapping(string:string) getenv(void|int force_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

    `string getenv(string varname, void|int force_update)`

  Description

    Query the value of a specific environment variable.

  Parameter `varname`

    Environment variable to query.

  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 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 handle_error

    `void handle_error(array|object trace)`

  Description

    This function is called when an error occurs that is not caught with catch().

  Method handle_error

    `void handle_error(mixed exception)`

  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_inherit

    `program handle_inherit(string pname, string current_file, object|void handler)`

  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.

  Variable include_prefix

    `string MasterObject.include_prefix`

  Description

    Prefix for Pike-related C header files.

  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_7_8_master

    protected inherit Pike_7_8_master : Pike_7_8_master

  Description

    Namespaces for compat masters.

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

  See also

    get_compat_master()

  Method is_absolute_path

    `int is_absolute_path(string p)`

  Description

    Check if a path p is fully qualified (ie not relative).

  Returns

    Returns 1 if the path is absolute, 0 otherwise.

  Variable ldflags

    `string MasterObject.ldflags`

  Description

    Flags suitable for use when linking Pike C modules

  Method master_read_file

    `string master_read_file(string file)`

  Method module_defined

    `array(string) module_defined(object|program mod)`

  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 normalize_path

    `string normalize_path(string path)`

  Description

    Replaces "\" with "/" if runing on MS Windows. It is adviced to use System.normalize_path instead.

  Method objects_reverse_lookup

    `program objects_reverse_lookup(object obj)`

  Description

    Returns the program for obj, if known to the master.

  Constant out_of_date_warning

    `constant int 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.

  Method program_path_to_name

    `string program_path_to_name(string path, void|string module_prefix, void|string module_suffix, void|string object_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

    `string programs_reverse_lookup(program prog)`

  Description

    Returns the path for prog in programs, if it got any.

  Method putenv

    `void putenv(string varname, void|string value)`

  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 query_precompiled_names

    `array(string) query_precompiled_names(string fname)`

  Description

    Returns identifiers (e.g. file names) of potentially precompiled files in priority order.

  Method read_precompiled

    `string read_precompiled(string id)`

  Description

    Given an identifier returned by query_precompiled_names, returns the precompiled entry. Can assume the entry exists.

  Method runtime_warning

    `void runtime_warning(string where, string what, 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 runtime_warning

    `void runtime_warning(string subsystem, string msg, mixed|void data)`

  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.

  Parameter `msg`

    Warning message. Currently the following messages may be generated:

    `"bad_cycle"` | A cycle where the destruction order isn't deterministic was detected by the garbage collector. data will in this case contain an array of the elements in the cycle.

  Parameter `data`

    Optional data that further describes the warning specified by msg.

  Method set_inhibit_compile_errors

    `void set_inhibit_compile_errors(mixed behaviour)`

  Description

    Set the compile error, warning and exception behaviour.

  Parameter `behaviour`

    The desired behaviour. One of:

    `int(0..0)` | Output compilation errors and warnings to `stderr`. This is the default behaviour.
    `int(1..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

    `object show_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

  Variable show_if_constant_errors

    `int MasterObject.show_if_constant_errors`

  Method strlen

    `int strlen(string|multiset|array|mapping|object thing)`

  Description

    Alias for sizeof.

  Deprecated

    Replaced by sizeof.

  Method thread_quanta_exceeded

    `void thread_quanta_exceeded(Thread.Thread thread, int ns)`

  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

    `void unregister(program p)`

  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?

  Variable want_warnings

    `int MasterObject.want_warnings`

  Description

    If not zero compilation warnings will be written out on stderr.

  Method werror

    `int werror(string fmt, mixed ... args)`

  Description

    Writes a string on stderr. Works just like Stdio.File.write on Stdio.stderr.

  Method write

    `int write(string fmt, mixed ... args)`

  Description

    Writes a string on stdout. Works just like Stdio.File.write on Stdio.stdout.

  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.

    Method create

      `MasterObject.Codec MasterObject.Codec(void|mixed encoded)`

    Description

      The optional argument is the thing to encode; it's passed on to Encoder.

    Inherit Decoder

      inherit Decoder : Decoder

    Inherit Encoder

      inherit Encoder : Encoder

  CLASS MasterObject.CompatResolver

    Description

      Resolver of symbols not located in the program being compiled.

    Method add_include_path

      `void add_include_path(string tmp)`

    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

      `void add_module_path(string tmp)`

    Description

      Add a directory to search for modules.

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

    See also

      remove_module_path()

    Method add_predefine

      `void add_predefine(string name, mixed value)`

    Description

      Add a define (without arguments) which will be implicitly defined in cpp calls.

    Method add_program_path

      `void add_program_path(string tmp)`

    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.CompatResolver MasterObject.CompatResolver(mixed version, CompatResolver|void fallback_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.

    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

    Method get_default_module

      `mapping get_default_module()`

    Method get_predefines

      `mapping get_predefines()`

    Description

      Returns a mapping with the current predefines.

    Method handle_include

      `string handle_include(string f, string current_file, int local_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

    Variable handler_root_modules

      `mapping(object:joinnode) MasterObject.CompatResolver.handler_root_modules`

    Description

      Lookup from handler module to corresponding root_module.

    Method instantiate_static_modules

      `protected mapping(string:mixed) instantiate_static_modules(object|mapping static_modules)`

    Description

      Instantiate static modules in the same way that dynamic modules are instantiated.

    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

    Method read_include

      `string read_include(string f)`

    Method remove_include_path

      `void remove_include_path(string tmp)`

    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

      `void remove_module_path(string tmp)`

    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

      `void remove_predefine(string name)`

    Description

      Remove a define from the set that are implicitly defined in cpp calls.

    Method remove_program_path

      `void remove_program_path(string tmp)`

    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

      `mixed resolv(string identifier, string|void current_file, object|void current_handler)`

    Method resolv_base

      `mixed resolv_base(string identifier, string|void current_file, object|void current_handler)`

    Method resolv_or_error

      `mixed resolv_or_error(string identifier, string|void current_file, void|object current_handler)`

    Description

      Same as resolv, but throws an error instead of returning UNDEFINED if the resolv failed.

    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.

  CLASS MasterObject.Decoder

    Description

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

    Method create

      `MasterObject.Decoder MasterObject.Decoder(void|string fname, void|int mkobj, void|object handler)`

    Method decode_object

      `array(mixed) decode_object(object o, mixed data)`

    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 before lfun::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()

    Variable fname
    Variable mkobj
    Variable handler

      `void|string MasterObject.Decoder.fname`
      `void|int MasterObject.Decoder.mkobj`
      `void|object MasterObject.Decoder.handler`

  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.Encoder MasterObject.Encoder(void|mixed encoded)`

    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|array nameof(mixed what, 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. `<font face='courier'>module_object`[0] will receive the found object.

  CLASS MasterObject.Pike_7_6_master

    Description

      Pike 7.6 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.6.

    Deprecated

      Replaced by predef::MasterObject.

    See also

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

    Variable environment

      `mapping(string:array(string)) MasterObject.Pike_7_6_master.environment`

    Description

      Mapping containing the environment variables.

      The mapping currently has the following structure:

      `index : array(string)`

      Note that the index is lower_case()'d on NT.

      Array
      `string varname` | Variable name with case intact.
      `string value` | Variable value.

    Note

      This mapping should not be accessed directly; use getenv() and putenv() instead. This mapping is not publicly accessible in pikes newer than 7.6.

    Note

      This mapping is not compatible with Process.create_process(); use the mapping returned from calling getenv() without arguments instead.

    Bugs

      This mapping is not the real environment; it is just a copy of the environment made at startup. Pike does attempt to keep track of changes in the mapping and to reflect them in the real environment, but avoid accessing this mapping if at all possible.

  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.7 and 7.8.

    Deprecated

      Replaced by predef::MasterObject.

    See also

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

    Inherit Pike_7_6_master

      inherit Pike_7_6_master : Pike_7_6_master

  CLASS MasterObject.Version

    Description

      Contains version information about a Pike version.

    Method `<
    Method `>
    Method `==
    Method __hash

      `int res = MasterObject.Version() < v`
      `int res = MasterObject.Version() > v`
      `int res = MasterObject.Version() == v`
      `int hash_value( MasterObject.Version arg )`

    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.Version MasterObject.Version(int major, int minor)`

    Description

      Set the version in the object.

    Variable major
    Variable minor

      `int MasterObject.Version.major`
      `int MasterObject.Version.minor`

    Description

      The major and minor parts of the version.

  CLASS MasterObject.dirnode

    Description

      Module node representing a single directory.

    See also

      joinnode

    Variable dirname
    Variable compilation_handler
    Variable name

      `string MasterObject.dirnode.dirname`
      `object|void MasterObject.dirnode.compilation_handler`
      `string|void MasterObject.dirnode.name`

    Method create

      `MasterObject.dirnode MasterObject.dirnode(string dirname, object|void compilation_handler, string|void name)`

  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`
      `object|void MasterObject.joinnode.compilation_handler`
      `joinnode|mapping(mixed:int(0..0))|void MasterObject.joinnode.fallback_module`
      `string|void MasterObject.joinnode.name`

    Method create

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

CLASS Reporter

  Description

    API for reporting parse errors and similar.

  Method report

    `void report(SeverityLevel severity, string filename, int(1..) linenumber, string subsystem, string message, 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.

  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 output to Stdio.stderr.

  Note

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

  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 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 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 LowOptions class and then start adding supported arguments:

      class MyArguments {
          inherit Arg.LowOptions;
          Opt verbose = NoOpt("-v")|NoOpt("--verbose");
          Opt help = MaybeOpt("--help");
          Opt output = HasOpt("--output")|HasOpt("-o");
       };

  Then, in main:

      MyArguments args = MyArguments(argv);

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

Constant REST

  `constant Arg.REST`

Description

  Constant used by Arg.parse() to indicate the remaining objects.

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

  Variable application

    `protected string Arg.LowOptions.application`

  Variable argv

    `protected array(string) Arg.LowOptions.argv`

  Method create

    `Arg.LowOptions Arg.LowOptions(array(string) _argv, void|mapping(string:string) env)`

  Inherit OptLibrary

    protected inherit OptLibrary : OptLibrary

  Variable opts

    `protected mapping(string:Opt) Arg.LowOptions.opts`

  Method unhandled_argument

    `protected bool unhandled_argument(array(string) argv, mapping(string:string) env)`

  Variable values

    `protected mapping(string:int(1..1)|string) Arg.LowOptions.values`

CLASS Arg.OptLibrary

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

      `protected string __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

      `mixed get_value(array(string) argv, mapping(string:string) env, int|string previous)`

    Description

      Should return 1 for set options or a string containing the value of the option. Returning 0 means the option was not set (or matched). To properly chain arguments parsers, return `::get_value(argv, env, previous)` instead of `0`, 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

  Method unhandled_argument

    `protected bool|string unhandled_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

    `bool unhandled_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.decoder Audio.Codec.decoder(string|void codecname, 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|int decode(int|void partial)`

      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 from_file(Audio.Format.ANY file)`

      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

        `mapping get_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

        `int check_format()`

      Description

        Check if data are correctly formated.

      Method get_data

        `string get_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

        `string get_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

        `mapping get_map()`

      Method get_sample

        `mapping get_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_program read_file(string filename, int|void nocheck)`

      Description

        Reads data from file

      See also

        read_streamed

      Method read_streamed

        `this_program read_streamed(string filename, int|void nocheck)`

      Description

        Reads data from stream

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

      See also

        read_file

      Method read_string

        `this_program read_string(string data, int|void nocheck)`

      Description

        Reads data from string

    CLASS Audio.Format.MP3

      Description

        A MP3 file parser with ID3 tag support.

      Method get_frame

        `mapping|int get_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 ])

      Inherit ANY

        inherit .module.ANY : ANY

Module Builtin

  Method _get_setter

    `function(mixed_void:void) _get_setter(object o, string varname)`

  Description

    Get a setter for the variable named varname in object o.

  Returns

    Returns a Setter()->`()() for the variable if it exists, and `UNDEFINED` otherwise.

  See also

    object_variablep()

  Method _take_over_initial_predefines

    `mapping(string:mixed) _take_over_initial_predefines()`

  CLASS Builtin.Null

    Description

      This class is used to implement the low-level aspects of Val.Null.

    Note

      This class should typically not be used directly. Use Val.Null instead.

    Note

      This class was previously available as Sql.Null. Any such use should be replaced with Val.Null.

    Deprecated

      Replaced by Val.Null.

    See also

      Val.Null, Val.null

    Method encode_json

      `string encode_json()`

    Description

      Defined for use with Standards.JSON.encode, so that it formats NULL as `null`.

  CLASS Builtin.Setter

    Description

      Internal class for implementing setters.

      This class is used by _get_setter().

    See also

      _get_setter()

    Method `()

      `void res = Builtin.Setter()()`

    Description

      Set the variable for the setter to val.

      This is the function returned by _get_setter().

  CLASS Builtin.automap_marker

    Description

      This is an internal class used by __automap__().

      It may show up during module dumping or in backtraces and the like.

      It should in normal circumstances never be used directly.

    See also

      __automap__(), map()

    Method create

      `Builtin.automap_marker Builtin.automap_marker(array arr, int depth)`

    Parameter `arr`

      Array that __automap__() is to loop over.

    Parameter `depth`

      Recursion depth of arr where the loop will be.

Module Bz2

  Description

    The Bz2 module contains functions to compress and uncompress strings using the same algorithm as the program `bzip2`. Compressing and decompressing can be done in streaming mode feeding the compress and decompress objects with arbitrarily large pieces of data.

    The Bz2 module consists of three classes; Bz2.Deflate, Bz2.Inflate and Bz2.File. Bz2.Deflate is used to compress data and Bz2.Inflate is used to uncompress data. Bz2.File is used to handle Bzip2 files.

  Note

    Note that this module is only available if libbzip2 was available when Pike was compiled.

    Note that although the functions in Inflate and Deflate use the same algorithm as `bzip2`, they do not use the exact same format, so you can not directly zip files or unzip zip-files using those functions. That is why there exists a third class for files.

  Inherit Bz2

    inherit "___Bz2" : Bz2

  CLASS Bz2.Deflate

    Description

      Bz2.Deflate is a builtin program written in C. It interfaces the packing routines in the bzlib library.

    Note

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

    See also

      Bz2.Inflate()

    Method create

      `Bz2.Deflate Bz2.Deflate(int(1..9)|void block_size)`

    Description

      If given, block_size should be a number from 1 to 9 indicating the block size used when doing compression. The actual block size will be a 100000 times this number. Low numbers are considered 'fast', higher numbers are considered 'slow' but give better packing. The parameter is set to 9 if it is omitted.

      This function can also be used to re-initialize a Bz2.Deflate object so it can be re-used.

    Method deflate

      `string deflate(string data, int(0..2)|void flush_mode)`

    Description

      This function performs bzip2 style compression on a string data and returns the packed data. Streaming can be done by calling this function several times and concatenating the returned data.

      The optional argument flush_mode should be one of the following:

      `Bz2.BZ_RUN` | Runs Bz2.Deflate->feed()
      `Bz2.BZ_FLUSH` | Runs Bz2.Deflate->read()
      `Bz2.BZ_FINISH` | Runs Bz2.Deflate->finish()

    See also

      Bz2.Inflate->inflate()

    Method feed

      `void feed(string data)`

    Description

      This function feeds the data to the internal buffers of the Deflate object. All data is buffered until a read or a finish is done.

    See also

      Bz2.Deflate->read() Bz2.Deflate->finish()

    Method finish

      `string finish(string data)`

    Description

      This method feeds the data to the internal buffers of the Deflate object. Then it compresses all buffered data adds a end of data marker ot it, returns the compressed data as a string, and reinitializes the deflate object.

    See also

      Bz2.Deflate->feed() Bz2.Deflate->read()

    Method read

      `string read(string data)`

    Description

      This function feeds the data to the internal buffers of the Deflate object. Then it compresses all buffered data and returns the compressed data as a string

    See also

      Bz2.Deflate->feed() Bz2.Deflate->finish()

  CLASS Bz2.File

    Description

      Low-level implementation of read/write support for Bzip2 files

    Note

      This class is currently not available on Windows.

    Method close

      `bool close()`

    Description

      closes the file

    Method create

      `Bz2.File Bz2.File()`
      `Bz2.File Bz2.File(string filename, void|string mode)`

    Description

      Creates a Bz2.File object

    Method eof

      `bool eof()`

    Returns

      1 if EOF has been reached, 0 otherwise

    Inherit File

      inherit Bz2::File : File

    Method line_iterator

      `String.SplitIterator|Stdio.LineIterator line_iterator(int|void trim)`

    Description

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

    Method open

      `bool open(string file, void|string mode)`

    Description

      Opens a file for I/O.

    Parameter `file`

      The name of the file to be opened

    Parameter `mode`

      Mode for the file operations. Can be either "r" (read) or "w". Read is default.

    Method read

      `string read(int len)`

    Description

      Reads len (uncompressed) bytes from the file. If len is omitted the whole file is read. If read is unsuccessful, 0 is returned.

    Method read_function

      `function(:string) read_function(int nbytes)`

    Description

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

    Method read_open

      `bool read_open(string file)`

    Description

      Opens a file for reading.

    Parameter `file`

      The name of the file to be opened

    Method write

      `int write(string data)`

    Description

      Writes the data to the file.

    Returns

      the number of bytes written to the file.

    Method write_open

      `bool write_open(string file)`

    Description

      Opens a file for writing.

    Parameter `file`

      The name of the file to be opened

  CLASS Bz2.Inflate

    Description

      Bz2.Inflate is a builtin program written in C. It interfaces the unpacking routines in the libz library.

    Note

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

    See also

      Deflate

    Method create

      `Bz2.Inflate Bz2.Inflate()`

    Method inflate

      `string inflate(string data)`

    Description

      This function performs bzip2 style decompression. It can do decompression with arbitrarily large pieces of data. When fed with data, it decompresses as much as it can and buffers the rest.

    Example

          while(..){
             foo = compressed_data[i..i+9];
             uncompressed_concatenated_data += inflate_object->inflate(foo);
             i = i+10;
           }

    See also

      Bz2.Deflate->deflate()

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

    Method create

      `Cache.Data Cache.Data(void|mixed value, void|int expire_time, void|float preciousness)`

    Description

      expire_time is relative and in seconds.

    Variable ctime

      `int Cache.Data.ctime`

    Description

      creation-time

    Method data

      `mixed data()`

    Description

      A method in order to allow for lazy computation

    Variable etime

      `int Cache.Data.etime`

    Description

      expiry-time (if supplied). 0 otherwise

    Method recursive_low_size

      `int recursive_low_size(mixed whatfor)`

    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

      `int size()`

    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

      `void alookup(string key, function(string, mixed, mixed ... :void) callback, int|float timeout, 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

      `void async_cleanup_cache()`

    Method create

      `Cache.cache Cache.cache(Cache.Storage.Base storage_mgr, Cache.Policy.Base policy_mgr, void|int cleanup_cycle_delay)`

    Description

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

    Method delete

      `void delete(string key, void|bool hard)`

    Description

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

    Method lookup

      `mixed lookup(string key)`

    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

      `void start_cleanup_cycle()`

    Method store

      `void store(string key, mixed value, void|int max_life, void|float preciousness, 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

      `void threaded_cleanup_cycle()`

  Module Cache.Policy

    CLASS Cache.Policy.Base

      Description

        Base class for cache expiration policies.

      Method expire

        `void expire(Cache.Storage.Base storage)`

      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.

      Method create

        `Cache.Policy.Multiple Cache.Policy.Multiple(Cache.Policy.Base ... policies)`

      Method expire

        `void expire(Cache.Storage.Base storage)`

      Description

        This expire function calls the expire functions in all of the sub-policies in turn.

      Inherit Base

        inherit Cache.Policy.Base : Base

    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.

      Method expire

        `void expire(Cache.Storage.Base storage)`

      Description

        This is an expire function that does nothing.

      Inherit Base

        inherit Cache.Policy.Base : Base

    CLASS Cache.Policy.Sized

      Description

        An LRU, size-constrained expiration policy manager.

      Thanks

        Thanks to Francesco Chemolli <kinkie@roxen.com> for the contribution.

      Method create

        `Cache.Policy.Sized Cache.Policy.Sized(int max, void|int min)`

      Method expire

        `void expire(Cache.Storage.Base storage)`

      Inherit Base

        inherit Cache.Policy.Base : Base

    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

        `void aget(string key, function(string, int(0..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

        `mixed delete(string key, void|bool hard)`

      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..0)|string first()`
        `int(0..0)|string next()`

      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..0)|Cache.Data get(string key, void|bool notouch)`

      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

        `void set(string key, mixed value, void|int max_life, void|float preciousness, 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.

      Method create

        `Cache.Storage.Gdbm Cache.Storage.Gdbm(string path)`

      Description

        A GDBM storage-manager must be hooked to a GDBM Database.

      Inherit Base

        inherit Cache.Storage.Base : Base

      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.

      Method get

        `int(0..0)|Cache.Data get(string key, void|int notouch)`

      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)

      Inherit Base

        inherit Cache.Storage.Base : Base

      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.

      Method create

        `Cache.Storage.MySQL Cache.Storage.MySQL(string sql_url)`

      Inherit Base

        inherit Cache.Storage.Base : Base

      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.

      Method create

        `Cache.Storage.Yabu Cache.Storage.Yabu(string path)`

      Inherit Base

        inherit Cache.Storage.Base : Base

      CLASS Cache.Storage.Yabu.Data

        Inherit Data

          inherit Cache.Data : Data

Module Calendar

  Description

    Time and day system

    Q: I need to parse some date in a non-strict format, like the one in the HTTP or mail protocol, or from a user web form.

    A: Calendar.dwim_day, or Calendar.dwim_time, should solve your problem.

    > Calendar.dwim_day("1/2/3"); Result: Day(Thu 2 Jan 2003) > Calendar.dwim_day("1 aug 2001"); Result: Day(Wed 1 Aug 2001)

    > Calendar.dwim_time("1 aug 2001 23:14 EDT"); Result: Minute(Wed 1 Aug 2001 23:14 EDT) > Calendar.dwim_time("2001 2 3 23:14:23 UTC+9"); Result: Second(Sat 3 Feb 2001 23:14:23 UTC+9)

    If it doesn't, and it should, report the problem to me and I'll see what I can do. Note that the timezones are rather unpredictable - if it doesn't get it, you will get the default (local) timezone.

    -------------------------------------------------------------------------

    Q: The dwim_* functions are too slow.

    A: They are not written to be fast, but to do good guessing.

    If you know the format, you should use the Calendar.parse function:

    > Calendar.parse("%Y-%M-%D %h:%m","2040-11-08 2:46"); Result: Minute(Thu 8 Nov 2040 2:46 CET) > Calendar.parse("%Y w%W %e %h:%m %p %z","1913 w4 monday 2:14 pm CET"); Result: Minute(Mon 20 Jan 1913 14:14 CET)

    These are the format characters: %Y absolute year %y dwim year (70-99 is 1970-1999, 0-69 is 2000-2069) %M month (number, name or short name) (needs %y) %W week (needs %y) %D date (needs %y, %m) %d short date (20000304, 000304) %a day (needs %y) %e weekday (needs %y, %w) %h hour (needs %d, %D or %W) %m minute (needs %h) %s second (needs %m) %f fraction of a second (needs %s) %t short time (205314, 2053) %z zone %p "am" or "pm" %n empty string (to be put at the end of formats)

    and you can also use "%*[....]" to skip some characters, as in sscanf().

    If this is too slow, there is currently no solution in Pike to do this faster, except possibly sscanf and manual calculations/ time object creation.

    -------------------------------------------------------------------------

    Q: How do I get from unix time (time(2)) to a unit and back?

    A: Calendar.Unit("unix",time()) unit->unix_time()

    > Calendar.Day("unix",987654321); Result: Day(Thu 19 Apr 2001) > Calendar.Second("unix",987654321); Result: Second(Thu 19 Apr 2001 6:25:21 CEST)

    > Calendar.Day()->unix_time(); Result: 979081200

    Note that you will get the time for the start of the unit. Unix time is timezone independant.

    The day-of-time units (seconds, hours, etc) uses this as internal representation of time.

    -------------------------------------------------------------------------

    Q: I'm a mad astronomer, how do I do the same conversions with julian day numbers?

    A: Julian day numbers are used as the internal representation for the day, and for most other bigger-then-time-of-day calculations.

    > Calendar.Day("julian",2454545); Result: Day(Wed 19 Mar 2008) > Calendar.Second("julian",2430122.0); Result: Second(Tue 6 May 1941 13:00:00 CET)

    Julian day numbers from day units and bigger are integers, representing the new julian number on that day. Julian day numbers from time of day units are represented in floats.

    > Calendar.Day()->julian_day(); Result: 2451920 > Calendar.Second()->julian_day(); Result: 2451919.949595

    Watch out for the float precision, though. If you haven't compiled your Pike with --with-double-precision, this gives you awkwardly low precision - 6 hours.

    -------------------------------------------------------------------------

    Q: How do I convert a "Second(Sat 3 Feb 2001 23:14:23 UTC+9)" object to my timezone?

    A: ->set_timezone(your timezone)

    > Calendar.dwim_time("2001 2 3 23:14:23 PST") ->set_timezone("Europe/Stockholm"); Result: Second(Sun 4 Feb 2001 8:14:23 CET)

    > Calendar.dwim_time("2001 2 3 23:14:23 PST") ->set_timezone("locale"); Result: Second(Sun 4 Feb 2001 8:14:23 CET)

    -------------------------------------------------------------------------

    Q: How do I print my time object?

    A: ->format_xxx();

    You can either print it unit-sensitive,

    > Calendar.dwim_time("2001 2 3 23:14:23 PST")->format_nice(); Result: "3 Feb 2001 23:14:23" > Calendar.Week()->format_nice(); Result: "w2 2001" > Calendar.now()->format_nicez(); Result: "10 Jan 10:51:15.489603 CET"

    or in a format not depending on the unit,

    > Calendar.Week()->format_ymd(); Result: "2001-01-08" > Calendar.Day()->format_time(); Result: "2001-01-10 00:00:00"

    This is all the formats:

    format_ext_time "Wednesday, 10 January 2001 10:49:57" format_ext_time_short "Wed, 10 Jan 2001 10:49:57 CET" format_ext_ymd "Wednesday, 10 January 2001" format_iso_time "2001-01-10 (Jan) -W02-3 (Wed) 10:49:57 UTC+1" format_iso_ymd "2001-01-10 (Jan) -W02-3 (Wed)" format_mod "10:49" format_month "2001-01" format_month_short "200101" format_mtime "2001-01-10 10:49" format_time "2001-01-10 10:49:57" format_time_short "20010110 10:49:57" format_time_xshort "010110 10:49:57" format_tod "10:49:57" format_tod_short "104957" format_todz "10:49:57 CET" format_todz_iso "10:49:57 UTC+1" format_week "2001-w2" format_week_short "2001w2" format_iso_week "2001-W02" format_iso_week_short "200102" format_xtime "2001-01-10 10:49:57.539198" format_xtod "10:49:57.539658" format_ymd "2001-01-10" format_ymd_short "20010110" format_ymd_xshort "010110"

    format_ctime "Wed Jan 10 10:49:57 2001\n" format_smtp "Wed, 10 Jan 2001 10:49:57 +0100" format_http "Wed, 10 Jan 2001 09:49:57 GMT"

    -------------------------------------------------------------------------

    Q: How old am I?

    A: First, you need to create the time period representing your age.

    > object t=Calendar.dwim_time("1638 dec 23 7:02 pm") ->distance(Calendar.now()); Result: Fraction(Thu 23 Dec 1638 19:02:00.000000 LMT - Wed 10 Jan 2001 10:53:33.032856 CET)

    Now, you can ask for instance how many years this is:

    > t->how_many(Calendar.Year); Result: 362

    Or how many 17 seconds it is:

    > t->how_many(Calendar.Second()*17); Result: 672068344

    A note here is to use ->distance, and not ->range, since that will include the destination unit too:

    > Calendar.dwim_day("00-01-02")->range(Calendar.Week(2000,2)) ->how_many(Calendar.Day()); Result: 15 > Calendar.dwim_day("00-01-02")->distance(Calendar.Week(2000,2)) ->how_many(Calendar.Day()); Result: 8

    -------------------------------------------------------------------------

    Q: In 983112378 days, what weekday will it be?

    A: (this weekday + 983112378) % 7 ;)

    or take this day, add the number, and ask the object:

    > (Calendar.Day()+983112378)->week_day_name(); Result: "Saturday"

    "+int" will add this number of the unit to the unit; this means that Calendar.Year()+2 will move two years forward, but Calendar.now()+2 will not move at all - since now has zero size.

    To add a number of another time unit, simply do that:

    > Calendar.Day()+3*Calendar.Year(); Result: Day(Sat 10 Jan 2004) > Calendar.Day()+3*Calendar.Minute()*134; Result: Minute(Wed 10 Jan 2001 6:42 CET - Thu 11 Jan 2001 6:42 CET)

    The last result here is because the resulting time still will be as long as the first.

    -------------------------------------------------------------------------

    Q: Are there other calendars?

    A: Yes.

    Calendar.Day is really a shortcut to Calendar.ISO.Day; this is tuned in the localization.h file.

    There is currently:

    Gregorian This is the base module for Julian style calendars; despite the name. Most calendars of today are in sync with the Gregorian calendar. ISO This inherits the Gregorian calendar to tweak it to conform to the ISO standards. Most affected are weeks, which starts on Monday in the ISO calendar. This is also the default calendar. Discordian The Discordian calendar as described in Principia Discordia is in sync with the Gregorian calendar (although some claim that it should be the Julian - I go with what I can read from my Principia Discordia). The module inherits and tweaks the Gregorian module. Coptic The Coptic calendar is by some sources ("St. Marks' Coptic Orthodox Church" web pages) is for now on in sync with the Gregorian Calendar, so this module too inherits and tweaks the Gregorian module. It needs to be adjusted for historical use. Julian This is the Julian calendar, with the small changes to the Gregorian calendar (leap years). Badi (Baha'i) The Badi calendar used by the Baha'i religion is based on the solar year. For the time being it is in sync with the Gregorian calendar.

    Islamic This is the Islamic calendar, using the 'Calendrical Calculations' rules for new moon. It is based directly on the YMD module. Stardate This is the (TNG) Stardate calendar, which consists of one time unit only, the Tick (1000 Tick is one earth year). It is based directly on TimeRanges.

    -------------------------------------------------------------------------

    Q: How do I convert between the calendars?

    A: You give the unit to be converted to the constructor of the unit you want it to be.

    > Calendar.Coptic.Day(Calendar.dwim_day("14 feb 1983")); Result: Day(Mon 7 Ams 1699) > Calendar.Islamic.Minute(Calendar.dwim_day("14 feb 1983")); Result: Minute(aha 29 Rebîul-âchir 1403 AH 13:00 CET - ith 1 Djumâda'l-ûla 1403 AH 13:00 CET) > Calendar.Day(Calendar.Stardate.Tick(4711)); Result: Day(Sat 17 Sep 2327 0:00 sharp)

    -------------------------------------------------------------------------

    Q: Isn't there a <my country> calendar?

    A: <your country> uses the ISO calendar, with just different names for the months. Language is a parameter to the calendar units, as well as the timezone.

    You set the language by using ->set_language(yourlanguage).

    > t->set_language("pt")->format_ext_ymd(); Result: "Quarta-feira, 10 Janeiro 2001" > t->set_language("roman")->format_ext_ymd(); Result: "Mercurii dies, X Ianuarius MMDCCLIII ab urbe condita"

    Note that all languages aren't supported. If you miss your favourite language or I got it all wrong (or have some time over to help me out), look in the Language.pmod file and send me an update.

    Or send me a list of the weekdays and month names (please start with Monday and January).

    Currently, these languages are supported:

    name code ------------------------------- ISO (default, aka English)

    Afrikaans af afr (South Africa), Austrian de_AT Basque eu eus (Spain) Catalan ca cat (Catalonia) Croatian hr hrv Danish da dan Dutch nl nld English en eng Estonian et est Faroese fo fao Finnish fi fin French fr fra Galician gl glg (Spain) German de deu Greenlandic kl kal Hungarian hu hun Icelandic is isl Irish ga gle (Gaelic) Italian it ita Latvian lv lav Lithuanian lt lit Norwegian no nor Persian fa fas (Iran) Polish pl pol Portugese pt por Romanian ro ron Serbian sr srp (Yugoslavia) Slovenian sl slv Spanish es spa Swedish sv swe Turkish tr Welsh cy cym

    Latin la lat Roman (Roman Latin)

    -------------------------------------------------------------------------

    Q: Isn't there a <whatever> calendar?

    A: Not if it isn't listed above. I'll appreciate any implementation help if you happen to have the time over to implement some calendar.

    I know I miss these:

    Chinese Jewish or Hebreic Maya

    Of these, the two first are based on astronomical events, which I haven't had the time to look into yet, but the last - Maya - is totally numeric.

    -------------------------------------------------------------------------

    Q: I don't like that weeks starts on Mondays. Every school kids knows that weeks start on Sundays.

    A: According to the ISO 8601 standard, weeks start on mondays.

    If you don't like it, edit the Calendar.pmod/localization.h file to use the Gregorian calendar instead of the ISO.

    Or use Calendar.Gregorian.Day, etc.

    -------------------------------------------------------------------------

    Q: How do I find out which days are red in a specific region?

    A: Events.<region>

    - contains the events for the region, as a SuperEvent. You can ask this object to filter out the holidays,

    Events.se->holidays();

    which will be a superevent containing only holidays.

    To use this information, you can for instance use ->scan, here in an example to see what red days there are in Sweden the current month:

    > Calendar.Events.se->filter_flag("h")->scan(Calendar.Month()); Result: ({ /* 6 elements */ Day(Sun 7 Jan 2001), Day(Sun 14 Jan 2001), Day(Sun 21 Jan 2001), Day(Sun 28 Jan 2001), Day(Sat 6 Jan 2001), Day(Mon 1 Jan 2001) })

    -------------------------------------------------------------------------

    Q: How accurate are the events information?

    A: For some regions, very. For most region, not very.

    The first reason is lack of information of this kind on the web, especially sorted into useful rules (like "the third monday after 23 dec", not "8 jan").

    The second reason is lack of time and interest to do research, which is a rather tedious job.

    If you want to help, the check your region in the events/regions file and send us <pike@roxen.com> a patch.

    Don't send me "the x region is all wrong!" mails without telling me how it should look.

    -------------------------------------------------------------------------

    Q: My timezone says it's DST. It's wrong.

    A: No it isn't. But:

    o The local timezone detector failed to find your timezone by itself, or found the wrong timezone.

    o or you use the wrong timezone.

    To make sure the right timezone is used, use the standard timezone names. Those aren't "CET" or "PST", but "Europe/Amsterdam" or "America/Dawson".

    You can tune the default timezone by editing Calendar.pmod/localization.h.

    OR this may be in the future and you have a changed DST rule and uses an old Pike. Then you can either download a new version or download new timezone data files from the ftp address below (if the internet still is there).

FIXME

  This needs to be reformatted as documentation.

Constant nulltimerange

  `constant Calendar.nulltimerange = TimeRange`

Description

  This represents the null time range, which, to differ from the zero time range (the zero-length time range), isn't placed in time. This is the result of for instance `& between two strict non-overlapping timeranges - no time at all.

  It has a constant, `is_nulltimerange`, which is non-zero. ``!` on this timerange is true.

CLASS Calendar.Calendar

  Description

    This is the base class of the calendars.

  Method now

    `Calendar.TimeRanges.TimeRange now()`

  Description

    Give the zero-length time period of the current time.

CLASS Calendar.Ruleset

  Description

    This is the container class for rules.

  Method `==

    `bool res = Calendar.Ruleset() == other`

  Method clone

    `this_program clone()`

  Method set_abbr2zone

    `this_program set_abbr2zone(mapping(string:string) abbr2zone)`

  Description

    Sets the guess-mapping for timezones. Default is the mapping:

    Abbreviation | Interpretation | UTC
    AMT | America/Manaus | UTC-4
    AST | America/Curacao | UTC-4
    CDT | America/Costa_Rica | UTC-5
    CST | America/El Salvador | UTC-6
    EST | America/Panama | UTC-5
    GST | Asia/Dubai | UTC+4
    IST | Asia/Jerusalem | UTC+2
    WST | Australia/Perth | UTC+8

  See also

    YMD.parse

  Method set_language

    `this_program set_language(string|Calendar.Rule.Language lang)`

  Method set_rule

    `this_program set_rule(Calendar.Rule.Language|Calendar.Rule.Timezone rule)`

  Method set_timezone

    `this_program set_timezone(string|Calendar.Rule.Timezone t)`

CLASS Calendar.SuperTimeRange

  Description

    This class handles the cases where you have a time period with holes. These can be created by the `^` or `|` operators on time ranges.

  Method create

    `Calendar.SuperTimeRange Calendar.SuperTimeRange(array(TimeRange) parts)`

  Description

    A SuperTimeRange must have at least two parts, two time ranges. Otherwise, it's either not a time period at all or a normal time period.

  Inherit TimeRange

    inherit TimeRange : TimeRange

Module Calendar.Austrian

  Description

    Same as the ISO calendar, but with austrian as the default language.

    This calendar exist only for backwards compatible purposes.

  Inherit ISO

    inherit Calendar.ISO : ISO

Module Calendar.Badi

  Description

    This is the Badi calendar, used in the Baha'i religion.

  Method daystart_offset

    `int daystart_offset()`

  Description

    Returns the offset to the start of the time range object

  Inherit YMD

    inherit Calendar.YMD : YMD

  CLASS Calendar.Badi.Vahid

    Inherit YMD

      inherit YMD : YMD

    Method year

      `Year year()`
      `Year year(int n)`
      `Year year(string name)`

    Description

      Return a year in the vahid by number or name:

      `vahid->year("Alif")`

Module Calendar.Coptic

  Description

    This is the Coptic Orthodox Church calendar, that starts the 11th or 12th September and has 13 months.

  Note

    The (default) names of the months are different then other the emacs calendar; I do not know which ones are used - the difference seem to be only the transcription of the phonetic sounds (B <-> P, etc).

    I do not know for how long back the calendar is valid, either. My sources claim that the calendar is synchronized with the Gregorian calendar, which is odd.

  Inherit Gregorian

    inherit Calendar.Gregorian : Gregorian

Module Calendar.Discordian

  Description

    The Discordian calendar, as described on page 34 in the fourth edition of Principia Discordia.

    Chaotic enough, it's quite simpler then the Gregorian calendar; weeks are 5 days, and evens up on a year. Months are 73 days.

    The leap day is inserted at the 60th day of the first month (Chaos), giving the first month 74 days. The description of the calendar is a "perpetual date converter from the gregorian to the POEE calendar", so the leap years are the same as the gregorians.

    The Principia calls months "seasons", but for simplicity I call them months in this calendar.

    If anyone know more about how to treat the leap day - now it is inserted in the month and week where it lands, rather then being separated from month and weeks, I'm interested to know.

    - Mirar, Pope of POEE.

  Inherit Gregorian

    inherit Calendar.Gregorian : Gregorian

Module Calendar.Event

  CLASS Calendar.Event.Date

    Description

      This class represents the event of a given gregorian date. For instance, `Event.Date(12,10)->next(Day())` finds the next 12 of October.

    Method create

      `Calendar.Event.Date Calendar.Event.Date(int(1..31) month_day, int(1..12) month)`

    Description

      The event is created by a given month day and a month number (1=January, 12=December).

    Inherit Day_Event

      inherit Day_Event : Day_Event

  CLASS Calendar.Event.Date_Weekday

    Description

      This class represents the event that a given gregorian date appears a given weekday. For instance, `Event.Date_Weekday(12,10,5)->next(Day())` finds the next 12 of October that is a friday.

    Method create

      `Calendar.Event.Date_Weekday Calendar.Event.Date_Weekday(int month_day, int month, int weekday)`

    Description

      The event is created by a given month day, a month number (1=January, 12=December), and a weekday number (1=Monday, 7=Sunday).

    Note

      The week day numbers used are the same as the day of week in the ISO calendar - the Gregorian calendar has 1=Sunday, 7=Saturday.

    Inherit Day_Event

      inherit Day_Event : Day_Event

  CLASS Calendar.Event.Day_Event

    Description

      Day_Event is an abstract class, extending Event for events that are single days, using julian day numbers for the calculations.

    Constant NODAY

      `constant int Calendar.Event.Day_Event.NODAY`

    Description

      Returned from scan_jd if the even searched for did not exist.

    Inherit Event

      inherit Event : Event

    Constant is_day_event

      `constant int Calendar.Event.Day_Event.is_day_event`

    Description

      This constant may be used to identify Day_Event objects.

    Method next

      `Calendar.TimeRanges.TimeRange next(void|Calendar.TimeRanges.TimeRange from, void|bool including)`

    Description

      Uses the virtual method scan_jd.

    See also

      Event.next

    Method previous

      `Calendar.TimeRanges.TimeRange previous(void|Calendar.TimeRanges.TimeRange from, void|bool including)`

    Description

      Uses the virtual method scan_jd.

    See also

      Event.previous

    Method scan_jd

      `int scan_jd(Calendar.Calendar realm, int jd, int(-1..-1)|int(1..1) direction)`

    Description

      This method has to be defined, and is what really does some work.

    Parameter `direction`

      `1` | Forward (next),
      `-1` | Backward (previous).

    Returns

      It should return the next or previous julian day (>jd) when the event occurs, or the constant NODAY if it doesn't.

  CLASS Calendar.Event.Easter

    Description

      This class represents an easter.

    Method create

      `Calendar.Event.Easter Calendar.Event.Easter(void|int shift)`

    Description

      shift is the year to shift from old to new style easter calculation. Default is 1582.

    Method easter_yd

      `int easter_yd(int y, int yjd, int leap)`

    Description

      Calculates the year day for the easter.

    Inherit Day_Event

      inherit Day_Event : Day_Event

  CLASS Calendar.Event.Easter_Relative

    Description

      This class represents an easter relative event.

    Method create

      `Calendar.Event.Easter_Relative Calendar.Event.Easter_Relative(string id, string name, int offset)`

    Inherit Easter

      inherit Easter : Easter

  CLASS Calendar.Event.Event

    Description

      Event is an abstract class, defining what methods an Event need to have.

    Method `|
    Method ``|

      `SuperEvent res = Calendar.Event.Event() | with`
      `SuperEvent res = with | Calendar.Event.Event()`

    Description

      Joins several events into one SuperEvent.

    Method describe

      `string describe()`

    Description

      Returns a description of the event.

    Constant is_event

      `constant int Calendar.Event.Event.is_event`

    Description

      This constant may be used to identify an event object.

    Method next
    Method previous

      `Calendar.TimeRanges.TimeRange next(void|Calendar.TimeRanges.TimeRange from, void|bool including)`
      `Calendar.TimeRanges.TimeRange previous(void|Calendar.TimeRanges.TimeRange from, void|bool including)`

    Description

      This calculates the next or previous occurance of the event, from the given timerange's start, including any event occuring at the start if that flag is set.

      It returns zero if there is no next event.

      These methods are virtual in the base class.

    Method scan

      `array(Calendar.TimeRanges.TimeRange) scan(Calendar.TimeRanges.TimeRange in)`

    Description

      This calculates the eventual events that is contained or overlapped by the given timerange. scan uses next, if not overloaded.

    Example

          Calendar.Event.Easter()->scan(Calendar.Year(2000))
               => ({ Day(Sun 23 Apr 2000) })

    Note

      scan can return an array of overlapping timeranges.

      This method must use `in->calendar_object->`type to create the returned timeranges, and must keep the ruleset.

    Method scan_events

      `mapping(Calendar.TimeRanges.TimeRange:Event) scan_events(Calendar.TimeRanges.TimeRange in)`

    Description

      Returns a mapping with time ranges mapped to events.

  CLASS Calendar.Event.Gregorian_Fixed

    Description

      A set date of year, counting leap day in February, used for the Gregorian fixed events in the events list.

    See also

      Julian_Fixed

    Method create

      `Calendar.Event.Gregorian_Fixed Calendar.Event.Gregorian_Fixed(string id, string name, int(1..31) month_day, int(1..12) month, int extra)`

    Inherit Day_Event

      inherit Day_Event : Day_Event

    Constant is_fixed

      `constant int Calendar.Event.Gregorian_Fixed.is_fixed`

    Description

      This constant may be used to identify Gregorian_Fixed objects.

  CLASS Calendar.Event.Julian_Fixed

    Description

      A set date of year, counting leap day in February, used for the Gregorian fixed events in the events list.

    See also

      Gregorian_Fixed

    Inherit Gregorian_Fixed

      inherit Gregorian_Fixed : Gregorian_Fixed

    Constant is_julian_fixed

      `constant int Calendar.Event.Julian_Fixed.is_julian_fixed`

    Description

      This constant may be used to identify Julian_Fixed objects.

  CLASS Calendar.Event.Monthday_Weekday

    Description

      This class represents the event that a given gregorian day of month appears a given weekday. For instance, `Event.Monthday_Weekday(13,5)->next(Day())` finds the next friday the 13th.

    Method create

      `Calendar.Event.Monthday_Weekday Calendar.Event.Monthday_Weekday(int month_day, int weekday)`

    Description

      The event is created by a given month day, and a weekday number (1=Monday, 7=Sunday).

    Note

      The week day numbers used are the same as the day of week in the ISO calendar - the Gregorian calendar has 1=Sunday, 7=Saturday.

    Inherit Day_Event

      inherit Day_Event : Day_Event

  CLASS Calendar.Event.Monthday_Weekday_Relative

    Description

      This class represents a monthday weekday relative event or n:th special weekday event, e.g. "fourth sunday before 24 dec" => md=24,mn=12,wd=7,n=-4

    Method create

      `Calendar.Event.Monthday_Weekday_Relative Calendar.Event.Monthday_Weekday_Relative(string id, string name, int(1..31) md, int(1..12) mn, int(1..7) _wd, int _n, void|bool _inclusive)`

    Inherit Gregorian_Fixed

      inherit Gregorian_Fixed : Gregorian_Fixed

  CLASS Calendar.Event.Nameday

    Description

      This is created by the Namedays classes to represent an event for a name.

    Inherit Day_Event

      inherit Day_Event : Day_Event

    Constant is_nameday

      `constant int Calendar.Event.Nameday.is_nameday`

    Description

      This constant may be used to identify Nameday objects.

  CLASS Calendar.Event.Namedays

    Description

      This contains a ruleset about namedays.

    Inherit Event

      inherit Event : Event

    Constant is_namedays

      `constant int Calendar.Event.Namedays.is_namedays`

    Description

      This constant may be used to identify Namedays.

    Method namedays

      `mapping(Calendar.TimeRanges.TimeRange:array(string)) namedays(Calendar.TimeRanges.TimeRange t)`

    Description

      Gives back an table of days with names that occur during the time period. Note that days without names will not appear in the returned mapping.

    Method names

      `array(string) names(Calendar.TimeRanges.TimeRange t)`

    Description

      Gives back an array of names that occur during the time period, in no particular order.

  CLASS Calendar.Event.NullEvent

    Description

      A non-event.

    Inherit Event

      inherit Event : Event

    Constant is_nullevent

      `constant int Calendar.Event.NullEvent.is_nullevent`

    Description

      This constant may be used to identify a NullEvent.

  CLASS Calendar.Event.Orthodox_Easter_Relative

    Description

      This class represents an orthodox easter relative event.

    Method create

      `Calendar.Event.Orthodox_Easter_Relative Calendar.Event.Orthodox_Easter_Relative(string id, string name, int offset)`

    Inherit Easter_Relative

      inherit Easter_Relative : Easter_Relative

  CLASS Calendar.Event.Solar

    Description

      This class represents a solar event as observed from Earth.

      The event_type is one of

      `0` | Northern hemisphere spring equinox.
      `1` | Northern hemisphere summer solstice.
      `2` | Northern hemisphere autumn equinox.
      `3` | Northern hemisphere winter solstice.

    Method create

      `Calendar.Event.Solar Calendar.Event.Solar(int|void event_type)`

    Variable event_type

      `int|void Calendar.Event.Solar.event_type`

    Inherit Day_Event

      inherit Day_Event : Day_Event

    Constant periodic_table

      `protected constant Calendar.Event.Solar.periodic_table`

    Description

      Array

      `array(float) 0..`

      Array
      `float 0` | Amplitude in days.
      `float 1` | Cosine phase in radians in year 2000.
      `float 2` | Period in radians/year.

    Method previous

      `Calendar.TimeRanges.TimeRange previous(void|Calendar.TimeRanges.TimeRange from, void|bool including)`

    Description

      Uses the virtual method scan_jd.

    See also

      Event.previous

    Method scan_jd

      `int scan_jd(Calendar.Calendar realm, int jd, int(1..1)|int(-1..-1) direction)`

    Note

      Returns unixtime in UTC to avoid losing the decimals!

    Method solar_event

      `array(int|float) solar_event(int y)`

    Description

      Calculate the next event.

      Based on Meeus Astronomical Algorithms Chapter 27.

  CLASS Calendar.Event.SuperEvent

    Description

      This class holds any number of events, and adds the functionality of event flags.

    Note

      Scanning (scan_events,next,etc) will drop flag information. Dig out what you need with holidays et al first.

    Method filter_flag
    Method holidays
    Method flagdays

      `SuperEvent filter_flag(string flag)`
      `SuperEvent holidays()`
      `SuperEvent flagdays()`

    Description

      Filter out the events that has a certain flag set. Holidays (flag "h") are the days that are marked red in the calendar (non-working days), Flagdays (flag "f") are the days that the flag should be visible in (only some countries).

    Inherit Event

      inherit Event : Event

  CLASS Calendar.Event.SuperNamedays

    Description

      Container for merged Namedays objects. Presumes non-overlapping namedays

    Method create

      `Calendar.Event.SuperNamedays Calendar.Event.SuperNamedays(array(Nameday) namedayss, string id)`

    Variable namedayss
    Variable id

      `array(Nameday) Calendar.Event.SuperNamedays.namedayss`
      `string Calendar.Event.SuperNamedays.id`

    Inherit Event

      inherit Event : Event

  CLASS Calendar.Event.TZShift_Event

    Description

      Event containing information about when a timezone is changed.

    Inherit Event

      inherit Event : Event

    Method scan_history

      `protected Calendar.TimeRanges.TimeRange scan_history(Calendar.Rule.Timezone tz, Calendar.TimeRanges.TimeRange from, int direction, bool including)`

    Method scan_rule

      `protected Calendar.TimeRanges.TimeRange scan_rule(Calendar.Rule.Timezone tz, Calendar.TimeRanges.TimeRange from, int direction, int including)`

    Method scan_shift

      `protected Calendar.TimeRanges.TimeRange scan_shift(Calendar.Rule.Timezone tz, Calendar.TimeRanges.TimeRange from, int direction, int including)`

  CLASS Calendar.Event.Weekday

    Description

      This class represents any given weekday. For instance, `Event.Weekday(5)->next(Day())` finds the next friday.

      These are also available as the pre-defined events Events.monday, Events.tuesday, Events.wednesday, Events.thursday, Events.friday, Events.saturday and Events.sunday.

    Method create

      `Calendar.Event.Weekday Calendar.Event.Weekday(int weekday, void|string id)`

    Description

      The event is created by a given weekday number (1=Monday, 7=Sunday).

    Note

      The week day numbers used are the same as the day of week in the ISO calendar - the Gregorian calendar has 1=Sunday, 7=Saturday.

    Inherit Day_Event

      inherit Day_Event : Day_Event

Module Calendar.Events

  Description

    The Event system

    Q: How do I find out which days are red in a specific region?

    A: Events.<region>

    - contains the events for the region, as a SuperEvent. You can ask this object to filter out the holidays,

    Events.se.holidays();

  Which will be a superevent containing only holidays.

  To use this information, you can for instance use ->scan, here in an example to see what red days there were in Sweden in 2001

      > Calendar.Events.se->filter_flag("h")->scan(Calendar.Month());
             Result: ({ /* 6 elements */
            		   Day(Sun 7 Jan 2001),
            		   Day(Sun 14 Jan 2001),
            		   Day(Sun 21 Jan 2001),
            		   Day(Sun 28 Jan 2001),
            		   Day(Sat 6 Jan 2001),
            		   Day(Mon 1 Jan 2001)

Method `[]
Method `->

  `Event.Event `[](string region)`
  `Event.Event `->(string region)`

Description

  return the Event object for the specified region or the specified named event.

Module Calendar.Gregorian

  Description

    This is the standard conservative christian calendar, used regularly in some countries - USA, for instance - and which derivate - the ISO calendar - is used in most of Europe.

  Inherit YMD

    inherit Calendar.YMD : YMD

Module Calendar.ISO

  Description

    This is the standard western calendar, which is a derivate of the Gregorian calendar, but with weeks that starts on Monday instead of Sunday.

  Inherit Gregorian

    inherit Calendar.Gregorian : Gregorian

Module Calendar.Islamic

  Description

    This is the islamic calendar. Due to some sources, they decide the first day of the new months on a month-to-month basis (sightings of the new moon), so it's probably not that accurate. If someone can confirm (or deny) accuracy better than that, please contact me so I can change this statement.

    It's vaugely based on rules presented in algorithms by Dershowitz, Reingold and Clamen, 'Calendrical Calculations'. It is the same that's used in Emacs calendar mode.

  Bugs

    I have currently no idea how the arabic countries count the week. Follow the same rules as ISO for now... The time is also suspicious; the day really starts at sunset and not midnight, the hours of the day is not correct. Also don't know what to call years before 1 - go for "BH"; positive years are "AH", anno Hegirac.

  Inherit YMD

    inherit Calendar.YMD : YMD

Module Calendar.Julian

  Description

    This is the Julian calendar, conjured up by the old Romans when their calendar were just too weird. It was used by the christians as so far as the 18th century in some parts of the world. (Especially the protestantic and orthodox parts.)

  Note

    Don't confuse the julian day with the Julian calendar. The former is just a linear numbering of days, used in the Calendar module as a common unit for absolute time.

  Inherit Gregorian

    inherit Calendar.Gregorian : Gregorian

Module Calendar.Rule

  CLASS Calendar.Rule.Timezone

    Description

      Contains a time zone.

    Method create

      `Calendar.Rule.Timezone Calendar.Rule.Timezone(int offset, string name)`

    Parameter `offset`

      Offset to UTC, not counting DST.

    Parameter `name`

      The name of the time zone.

    Method raw_utc_offset

      `int raw_utc_offset()`

    Description

      Returns the offset to UTC, not counting DST.

    Method tz_jd

      `array tz_jd(int julian_day)`

    FIXME

      This method takes one integer argument, ignores it and returns an array with the UTC offset and the timezone name.

    Method tz_ux

      `array tz_ux(int unixtime)`

    FIXME

      This method takes one integer argument, ignores it and returns an array with the UTC offset and the timezone name.

Module Calendar.Stardate

  Description

    This implements TNG stardates.

  Method now

    `cTick now()`

  Description

    Give the zero-length time period of the current time.

  CLASS Calendar.Stardate.cTick

    Method create

      `Calendar.Stardate.cTick Calendar.Stardate.cTick(mixed ... args)`
      `Calendar.Stardate.cTick Calendar.Stardate.cTick(int|float date)`
      `Calendar.Stardate.cTick Calendar.Stardate.cTick()`

    Description

      Apart from the standard creation methods (julian day, etc), you can create a stardate from the stardate number. The length of the period will then be zero.

      You can also omit any arguments to create now.

    Bugs

      Since the precision is limited to the float type of Pike you can get non-precise results:

      > Calendar.Second(Calendar.Stardate.Day(Calendar.Year())); Result: Second(Fri 31 Dec 1999 23:59:18 CET - Sun 31 Dec 2000 23:59:18 CET)

  Method format_long
  Method format_short
  Method format_vshort

    `string format_long(void|int precision)`
    `string format_short(void|int precision)`
    `string format_vshort(void|int precision)`

  Description

    Format the stardate tick nicely. Precision is the number of decimals. Defaults to 3.

    long | "-322537.312" |
    short | "77463.312" | (w/o >100000-component)
    vshort | "7463.312" | (w/o >10000-component)

  Inherit TimeRange

    inherit Calendar.TimeRange : TimeRange

  Method number_of_days

    `int number_of_days()`

  Description

    This gives back the Gregorian/Earth/ISO number of days, for convinience and conversion to other calendars.

  Method number_of_seconds

    `int number_of_seconds()`

  Description

    This gives back the Gregorian/Earth/ISO number of seconds, for convinience and conversion to other calendars.

  Method tic

    `float tic()`

  Description

    This gives back the start of the stardate period, as a float.

  Method tics

    `float tics()`

  Description

    This gives back the number of stardate tics in the period.

Module Calendar.Swedish

  Description

    Same as the ISO calendar, but with Swedish as the default language.

    This calendar exist only for backwards compatible purposes.

  Inherit ISO

    inherit Calendar.ISO : ISO

Module Calendar.TZnames

  Description

    This module contains listnings of available timezones, in some different ways

  Method _zone_tab
  Method zone_tab

    `string _zone_tab()`
    `array(array) zone_tab()`

  Description

    This returns the raw respectively parsed zone tab file from the timezone data files.

    The parsed format is an array of zone tab line arrays,

        ({ string country_code,
           string position,
           string zone_name,
           string comment })

    To convert the position to a Geography.Position, simply feed it to the constructor.

  Constant abbr2zones

    `constant Calendar.TZnames.abbr2zones = mapping(string:array(string))`

  Description

    This mapping is used to look up abbreviation to the possible regional zones.

    It looks like this:

        ([ "CET": ({ "Europe/Stockholm", <i>[...]</i> }),
           "CST": ({ "America/Chicago", "Australia/Adelaide", <i>[...]</i> }),
           <i>[...]</i> }),

    Note this: Just because it's noted "CST" doesn't mean it's a unique timezone. There is about 7 *different* timezones that uses "CST" as abbreviation; not at the same time, though, so the DWIM routines checks this before it's satisfied. Same with some other timezones.

    For most timezones, there is a number of region timezones that for the given time are equal. This is because region timezones include rules about local summer time shifts and possible historic shifts.

    The YMD.parse functions can handle timezone abbreviations by guessing.

  Method zonenames

    `array(string) zonenames()`

  Description

    This reads the zone.tab file and returns name of all standard timezones, like "Europe/Belgrade".

  Constant zones

    `constant Calendar.TZnames.zones = mapping(string:array(string))`

  Description

    This constant is a mapping that can be used to loop over to get all the region-based timezones.

    It looks like this:

        ([ "America": ({ "Los_Angeles", "Chicago", <i>[...]</i> }),
           "Europe":  ({ "Stockholm", <i>[...]</i> }),
           <i>[...]</i> }),

    Please note that loading all the timezones can take some time, since they are generated and compiled on the fly.

Module Calendar.Time

  Description

    Base for time of day in calendars, ie calendars with hours, minutes, seconds

    This module can't be used by itself, but is inherited by other modules (ISO by YMD, for instance).

  Inherit TimeRanges

    inherit TimeRanges : TimeRanges

  CLASS Calendar.Time.Fraction

    Description

      A Fraction is a part of a second, and/or a time period with higher resolution then a second.

      It contains everything that is possible to do with a Second, and also some methods of grabbing the time period with higher resolution.

    Note

      Internally, the fraction time period is measured in nanoseconds. A shorter or more precise time period then in nanoseconds is not possible within the current Fraction class.

    Method create

      `Calendar.Time.Fraction Calendar.Time.Fraction()`
      `Calendar.Time.Fraction Calendar.Time.Fraction("unix", int|float unixtime)`
      `Calendar.Time.Fraction Calendar.Time.Fraction("unix", int|float unixtime, int|float len)`
      `Calendar.Time.Fraction Calendar.Time.Fraction(int y, int m, int d, int h, int m, int s, int ns)`

    Description

      It is possible to create a Fraction in three ways, either "now" with no arguments or from a unix time (as from `time(2)`), or the convenience way from ymd-hms integers.

      If created from unix time, both the start of the period and the size of the period can be given in floats, both representing seconds. Note that the default float precision in pike is rather low (same as 'float' in C, the 32 bit floating point precision, normally about 7 digits), so beware that the resolution might bite you. (Internally in a Fraction, the representation is an integer.)

      If created without explicit length, the fraction will always be of zero length.

    Inherit Second

      inherit Second : Second

    Method now

      `TimeofDay now()`

    Description

      Give the zero-length time period of the current time.

    Method set_ruleset
    Method ruleset

      `Calendar set_ruleset(Ruleset r)`
      `Ruleset ruleset()`

    Description

      Set or read the ruleset for the calendar. set_ruleset returns a new calendar object, but with the new ruleset.

    Method set_timezone
    Method timezone

      `Calendar set_timezone(Timezone tz)`
      `Calendar set_timezone(string|Timezone tz)`
      `TimeZone timezone()`

    Description

      Set or get the current timezone (including dst) rule. set_timezone returns a new calendar object, as the called calendar but with another set of rules.

      Example:

          > Calendar.now();
          Result: Fraction(Fri 2 Jun 2000 18:03:22.010300 CET)
          > Calendar.set_timezone(Calendar.Timezone.UTC)->now();
          Result: Fraction(Fri 2 Jun 2000 16:03:02.323912 UTC)

  CLASS Calendar.Time.Hour

    Inherit TimeofDay

      inherit TimeofDay : TimeofDay

  CLASS Calendar.Time.Minute

    Inherit TimeofDay

      inherit TimeofDay : TimeofDay

  CLASS Calendar.Time.Second

    Inherit TimeofDay

      inherit TimeofDay : TimeofDay

  CLASS Calendar.Time.SuperTimeRange

    Method second
    Method seconds
    Method number_of_seconds
    Method minute
    Method minutes
    Method number_of_minutes
    Method hour
    Method hours
    Method number_of_hours

      `Second second()`
      `Second second(int n)`
      `array(Second) seconds()`
      `array(Second) seconds(int first, int last)`
      `int number_of_seconds()`
      `Minute minute()`
      `Minute minute(int n)`
      `array(Minute) minutes()`
      `array(Minute) minutes(int first, int last)`
      `int number_of_minutes()`
      `Hour hour()`
      `Hour hour(int n)`
      `array(Hour) hours()`
      `array(Hour) hours(int first, int last)`
      `int number_of_hours()`

    Description

      Similar to TimeofDay, the Time::SuperTimeRange has a number of methods for digging out time parts of the range. Since a SuperTimeRange is a bit more complex - the major reason for its existance it that it contains holes, this calculation is a bit more advanced too.

      If a range contains the seconds, say, 1..2 and 4..5, the third second (number 2, since we start from 0) in the range would be number 4, like this:

          no   means this second
          0    1
          1    2
          2    4      <- second three is missing,
          3    5         as we don't have it in the example range

      number_of_seconds() will in this example therefore also report 4, not 5, even if the time from start of the range to the end of the range is 5 seconds.

    Inherit SuperTimeRange

      inherit TimeRanges.SuperTimeRange : SuperTimeRange

  CLASS Calendar.Time.TimeofDay

    Description

      Virtual class used by e.g. Hour.

    Method call_out

      `void call_out(function(:void) fun, mixed ...args)`

    Description

      Creates a call_out to this point in time.

    Method create

      `Calendar.Time.TimeofDay Calendar.Time.TimeofDay()`
      `Calendar.Time.TimeofDay Calendar.Time.TimeofDay(int unixtime)`

    Description

      In addition to the wide range of construction arguments for a normal TimeRange (see TimeRange.create), a time of day can also be constructed with unixtime as single argument consisting of the unix time - as returned from `time(2)` - of the time unit start.

      It can also be constructed without argument, which then means "now", as in "this minute".

    Method datetime

      `mapping datetime()`

    Description

      This gives back a mapping with the relevant time information (representing the start of the period);

           ([ "year":     int        // year number (2000 AD=2000, 1 BC==0)
              "month":    int(1..)   // month of year
              "day":      int(1..)   // day of month
              "yearday":  int(1..)   // day of year
              "week":     int(1..)   // week of year
              "week_day": int(1..)   // day of week (depending on calendar)

              "hour":     int(0..)   // hour of day, including dst
              "minute":   int(0..59) // minute of hour
              "second":   int(0..59) // second of minute
              "fraction": float      // fraction of second
              "timezone": int        // offset to utc, including dst

              "unix":     int        // unix time
              "julian":   float      // julian day
           ]);

    Method format_iso_ymd
    Method format_ymd
    Method format_ymd_short
    Method format_ymd_xshort
    Method format_iso_week
    Method format_iso_week_short
    Method format_week
    Method format_week_short
    Method format_month
    Method format_month_short
    Method format_iso_time
    Method format_time
    Method format_time_short
    Method format_iso_short
    Method format_time_xshort
    Method format_mtime
    Method format_xtime
    Method format_tod
    Method format_xtod
    Method format_mod
    Method format_nice
    Method format_nicez

      `string format_iso_ymd()`
      `string format_ymd()`
      `string format_ymd_short()`
      `string format_ymd_xshort()`
      `string format_iso_week()`
      `string format_iso_week_short()`
      `string format_week()`
      `string format_week_short()`
      `string format_month()`
      `string format_month_short()`
      `string format_iso_time()`
      `string format_time()`
      `string format_time_short()`
      `string format_iso_short()`
      `string format_time_xshort()`
      `string format_mtime()`
      `string format_xtime()`
      `string format_tod()`
      `string format_xtod()`
      `string format_mod()`
      `string format_nice()`
      `string format_nicez()`

    Description

      Format the object into nice strings;

          iso_ymd        "2000-06-02 (Jun) -W22-5 (Fri)" [2]
          ext_ymd        "Friday, 2 June 2000" [2]
          ymd            "2000-06-02"
          ymd_short      "20000602"
          ymd_xshort     "000602" [1]
          iso_week       "2000-W22"
          iso_week_short "2000W22"
          week           "2000-w22" [2]
          week_short     "2000w22" [2]
          month          "2000-06"
          month_short    "200006" [1]
          iso_time       "2000-06-02 (Jun) -W22-5 (Fri) 20:53:14 UTC+1" [2]
          ext_time       "Friday, 2 June 2000, 20:53:14" [2]
          ctime          "Fri Jun  4 20:53:14 2000\n" [2] [3]
          http           "Fri, 02 Jun 2000 19:53:14 GMT" [4]
          time           "2000-06-02 20:53:14"
          time_short     "20000602 20:53:14"
          time_xshort    "000602 20:53:14"
          iso_short      "20000602T20:53:14"
          mtime          "2000-06-02 20:53"
          xtime          "2000-06-02 20:53:14.000000"
          todz           "20:53:14 CET"
          todz_iso       "20:53:14 UTC+1"
          tod            "20:53:14"
          tod_short      "205314"
          xtod           "20:53:14.000000"
          mod            "20:53"
          nice           "2 Jun 20:53", "2 Jun 2000 20:53:14" [2][5]
          nicez          "2 Jun 20:53 CET" [2][5]
          smtp           "Fri, 2 Jun 2000 20:53:14 +0100" [6]
          commonlog      "02/Jun/2000:20:53:14 +0100" [2]

      `[1]` note conflict (think 1 February 2003)
      `[2]` language dependent
      `[3]` as from the libc function ctime()
      `[4]` as specified by the HTTP standard; this is always in GMT, ie, UTC. The timezone calculations needed will be executed implicitly. It is not language dependent.
      `[5]` adaptive to type and with special cases for yesterday, tomorrow and other years
      `[6]` as seen in Date: headers in mails

    Method hour_no
    Method minute_no
    Method second_no
    Method fraction_no

      `int hour_no()`
      `int minute_no()`
      `int second_no()`
      `float fraction_no()`

    Description

      This gives back the number of the time unit, on this day. Fraction is a float number, 0<=fraction<1.

    Method hour
    Method hours
    Method number_of_hours

      `Hour hour()`
      `Hour hour(int n)`
      `array(Hour) hours()`
      `array(Hour) hours(int first, int last)`
      `int number_of_hours()`

    Description

      hour() gives back the timerange representing the first or nth Hour of the called object. Note that hours normally starts to count at zero, so `->hour(2)` gives the third hour within the range.

      An Hour is in the Calendar perspective as any other time range not only 60 minutes, but also one of the (normally) 24 hours of the day, precisely.

      hours() give back an array of all the hours containing the time periods called. With arguments, it will give back a range of those hours, in the same enumeration as the n to hour().

      number_of_hours() simple counts the number of hours containing the called time period.

      Note: The called object doesn't have to *fill* all the hours it will send back, it's enough if it exist in those hours:

              > object h=Calendar.Time.Hour();
              Result: Hour(265567)
              > h->hours();
              Result: ({ /* 1 element */
                          Hour(265567)
                      })
              > h+=Calendar.Time.Minute();
              Result: Minute(265567:01+60m)
              > h->hours();
              Result: ({ /* 2 elements */
                          Hour(265567),
                          Hour(265568)
                      })

    Inherit TimeRange

      inherit TimeRange : TimeRange

    Method julian_day

      `float julian_day()`

    Description

      This calculates the corresponding julian day, from the time range. Note that the calculated day is the beginning of the period, and is a float - julian day standard says .00 is midday, 12:00 pm.

    Note

      Normal pike (ie, 32 bit) floats (without --with-double-precision) has a limit of about 7 digits, and since we are about julian day 2500000, the precision on time of day is very limited.

    Method minute
    Method minutes
    Method number_of_minutes

      `Minute minute()`
      `Minute minute(int n)`
      `array(Minute) minutes()`
      `array(Minute) minutes(int first, int last)`
      `int number_of_minutes()`

    Description

      minute() gives back the timerange representing the first or nth Minute of the called object. Note that minutes normally starts to count at zero, so `->minute(2)` gives the third minute within the range.

      An Minute is in the Calendar perspective as any other time range not only 60 seconds, but also one of the (normally) 60 minutes of the Hour, precisely.

      minutes() give back an array of all the minutes containing the time periods called. With arguments, it will give back a range of those minutes, in the same enumeration as the n to minute().

      number_of_minutes() simple counts the number of minutes containing the called time period.

    Method move_seconds
    Method move_ns

      `TimeRange move_seconds(int seconds)`
      `TimeRange move_ns(int nanoseconds)`

    Description

      These two methods gives back the time range called moved the specified amount of time, with the length intact.

      The motion is relative to the original position in time; 10 seconds ahead of 10:42:32 is 10:42:42, etc.

    Method second
    Method seconds
    Method number_of_seconds

      `Second second()`
      `Second second(int n)`
      `array(Second) seconds()`
      `array(Second) seconds(int first, int last)`
      `int number_of_seconds()`

    Description

      second() gives back the timerange representing the first or nth Second of the called object. Note that seconds normally starts to count at zero, so `->second(2)` gives the third second within the range.

      seconds() give back an array of all the seconds containing the time periods called. With arguments, it will give back a range of those seconds, in the same enumeration as the n to second().

      number_of_seconds() simple counts the number of seconds containing the called time period.

    Method set_size_seconds
    Method set_size_ns

      `TimeRange set_size_seconds(int seconds)`
      `TimeRange set_size_ns(int nanoseconds)`

    Description

      These two methods allows the time range to be edited by size of specific units.

    Method unix_time

      `int unix_time()`

    Description

      This calculates the corresponding unix time, - as returned from `time(2)` - from the time range. Note that the calculated unix time is the beginning of the period.

Module Calendar.TimeRanges

  CLASS Calendar.TimeRanges.TimeRange

    Description

      This is the base class (usually implemented by e.g. Calendar subclasses like Calendar.Second) for any time measurement and calendrar information. It defines all the things you can do with a time range or any time period.

      A TimeRange doubles as both a fixed period in time, and an amount of time. For instance, a week plus a day moves the week-period one day ahead (unaligning it with the week period, and thereby reducing it to just 7 days), no matter when in time the actual day were.

    Method `==
    Method _equal

      `bool res = Calendar.TimeRanges.TimeRange() == compared_to`
      `bool equal(Calendar.TimeRanges.TimeRange from, TimeRange compared_to)`

    Description

      These two overloads the operator ``==` and the result of the `equal` function.

      a`==`b is considered true if the two timeranges are of the same type, have the same rules (language, timezone, etc) and are the same timerange.

      `equal(`a`,`b`)` are considered true if a and b are the same timerange, exactly the same as the equals method.

      The `__hash` method is also present, to make timeranges possible to use as keys in mappings.

      known bugs: _equal is not currently possible to overload, due to weird bugs, so equal uses `== for now.

    Method `&

      `TimeRange res = Calendar.TimeRanges.TimeRange() & with`

    Description

      Gives the cut on the called time period with another time period. The result is zero if the two periods doesn't overlap.

          >- the past          the future -<
           |-------called-------|
                |-------other--------|
                >----- cut -----<

    Method `*

      `TimeRange res = Calendar.TimeRanges.TimeRange() * n`

    Description

      This changes the amount of time in the time period. `t*17` is the same as doing `t->set_size(t,17)`.

    Method `+
    Method `-

      `TimeRange res = Calendar.TimeRanges.TimeRange() + n`
      `TimeRange res = Calendar.TimeRanges.TimeRange() + offset`
      `TimeRange res = Calendar.TimeRanges.TimeRange() - m`
      `TimeRange res = Calendar.TimeRanges.TimeRange() - x`

    Description

      This calculates the (promoted) time period either n step away or with a given offset. These functions does use add to really do the job:

          t+n         t->add(n)             t is a time period
          t-n         t->add(-n)            offset is a time period
          t+offset    t->add(1,offset)      n is an integer
          t-offset    t->add(-1,offset)
          n+t         t->add(n)
          n-t         illegal
          offset+t    offset->add(1,t)      | note this!
          offset-t    offset->add(-1,t)     |

      Mathematic rules:

          x+(t-x) == t    x is an integer or a time period
          (x+t)-x == t    t is a time period
          (t+x)-x == t
          o-(o-t) == t    o is a time period
          t++ == t+1
          t-- == t-1

    Note

      a-b does not give the distance between the start of a and b. Use the distance() function to calculate that.

      The integer used to `+, `- and add are the number of steps the motion will be. It does never represent any fixed amount of time, like seconds or days.

    Method `/
    Method split

      `array(TimeRange) res = Calendar.TimeRanges.TimeRange() / n`
      `array(TimeRange) split(int|float n, object void|TimeRangewith)`

    Description

      This divides the called timerange into n pieces. The returned timerange type is not neccesarily of the same type as the called one. If the optional timerange is specified then the resulting timeranges will be multiples of that range (except for the last one).

      known bugs: These are currently not defined for supertimeranges.

    Method `/
    Method how_many

      `int res = Calendar.TimeRanges.TimeRange() / with`
      `int how_many(TimeRange with)`

    Description

      This calculates how many instances of the given timerange has passed during the called timerange.

      For instance, to figure out your age, create the timerange of your lifespan, and divide with the instance of a Year.

    Method `<
    Method `>

      `bool res = Calendar.TimeRanges.TimeRange() < compared_to`
      `bool res = Calendar.TimeRanges.TimeRange() > compared_to`

    Description

      These operators sorts roughty on the periods place in time. The major use might be to get multiset to work, besides sorting events clearly defined in time.

    Method `^

      `TimeRange res = Calendar.TimeRanges.TimeRange() ^ with`

    Description

      Gives the exclusive-or on the called time period and another time period, ie the union without the cut. The result is zero if the two periods were the same.

          >- the past          the future -<
           |-------called-------|
                |-------other--------|
           <----|               |---->   - exclusive or

    Method `|

      `TimeRange res = Calendar.TimeRanges.TimeRange() | with`

    Description

      Gives the union on the called time period and another time period.

          >- the past          the future -<
           |-------called-------|
                |-------other--------|
           <----------union---------->

    Method add

      `TimeRange add(int n, void|TimeRange step)`

    Description

      calculates the (promoted) time period n steps away; if no step is given, the step's length is of the same length as the called time period.

      It is not recommended to loop by adding the increment time period to a shorter period; this can cause faults, if the shorter time period doesn't exist in the incremented period. (Like week 53, day 31 of a month or the leap day of a year.)

      Recommended use are like this:

             // loop over the 5th of the next 10 months
             TimeRange month=Month()+1;
             TimeRange orig_day=month()->day(5);
             for (int i=0; i<10; i++)
             {
                month++;
                TimeRange day=month->place(orig_day);
                <i>...use day...</i>
             }

    Method beginning
    Method end

      `TimeRange beginning()`
      `TimeRange end()`

    Description

      This gives back the zero-sized beginning or end of the called time period.

      rule: `range(t->beginning(),t->end())==t`

    Method calendar

      `Calendar calendar()`

    Description

      Simply gives back the calendar in use, for instance Calendar.ISO or Calendar.Discordian.

    Method strictly_preceeds
    Method preceeds
    Method is_previous_to
    Method overlaps
    Method contains
    Method equals
    Method is_next_to
    Method succeeds
    Method strictly_succeeds

      `bool strictly_preceeds(TimeRange what)`
      `bool preceeds(TimeRange what)`
      `bool is_previous_to(TimeRange what)`
      `bool overlaps(TimeRange what)`
      `bool contains(TimeRange what)`
      `bool equals(TimeRange what)`
      `bool is_next_to(TimeRange what)`
      `bool succeeds(TimeRange what)`
      `bool strictly_succeeds(TimeRange what)`

    Description

      These methods exists to compare two periods of time on the timeline.

                    case            predicates

           <-- past       future ->

           |----A----|              A strictly preceeds B,
                        |----B----| A preceeds B

           |----A----|              A strictly preceeds B, A preceeds B,
                     |----B----|    A is previous to B, A touches B

               |----A----|          A preceeds B,
                     |----B----|    A overlaps B, A touches B

               |-------A-------|    A preceeds B, A ends with B
                     |----B----|    A overlaps B, A contains B, A touches B,

               |-------A-------|    A preceeds B,  A succeeds B,
                   |---B---|        A overlaps B, A contains B, A touches B

                  |----A----|       A overlaps B, A touches B, A contains B
                  |----B----|       A equals B, A starts with B, A ends with B

               |-------A-------|    A succeeds B, A starts with B
               |----B----|          A overlaps B, A contains B, A touches B

                     |----A----|    A succeeds B,
               |----B----|          A overlaps B, A touches B

                     |----A----|    A strictly succeeds B, A succeeds B
           |----B----|              A is next to B, A touches B

                       |----A----|  A strictly succeeds B,
           |----B----|              A succeeds B

    Note

      These methods only check the range of the first to the last time in the period; use of combined time periods (SuperTimeRanges) might not give you the result you want.

    See also

      `&amp;

    Method create

      `Calendar.TimeRanges.TimeRange Calendar.TimeRanges.TimeRange(TimeRange from)`

    Description

      Create the timerange from another timerange.

      This is useful when converting objects from one calendar to another. Note that the ruleset will be transferred to the new object, so this method can't be used to convert between timezones or languges - use set_timezone, set_language or set_ruleset to achieve this.

    Note

      The size of the new object may be inexact; a Month object can't comprehend seconds, for instance.

    Method create

      `Calendar.TimeRanges.TimeRange Calendar.TimeRanges.TimeRange("julian", int|float julian_day)`

    Description

      Create the timerange from a julian day, the standardized method of counting days. If the timerange is more then a day, it will at least enclose the day.

    Method create

      `Calendar.TimeRanges.TimeRange Calendar.TimeRanges.TimeRange("unix", int unixtime)`
      `Calendar.TimeRanges.TimeRange Calendar.TimeRanges.TimeRange("unix", int unixtime, int seconds_len)`

    Description

      Create the timerange from unix time (as given by `time(2)`), with eventually the size of the time range in the same unit, seconds.

    Method range
    Method space
    Method distance

      `TimeRange range(TimeRange other)`
      `TimeRange space(TimeRange other)`
      `TimeRange distance(TimeRange other)`

    Description

      Derives different time periods in between the called timerange and the parameter timerange.

          >- the past          the future -<
           |--called--|         |--other--|
           >------------ range -----------<
                      >--space--<
           >----- distance -----<

      See also: add, TimeRanges.range, TimeRanges.space, TimeRanges.distance

    Method set_language
    Method language

      `TimeRange set_language(Rule.Language lang)`
      `TimeRange set_language(string lang)`
      `Language language()`

    Description

      Set or get the current language rule.

    Method next
    Method prev

      `TimeRange next()`
      `TimeRange prev()`

    Description

      Next and prev are compatible and convinience functions; `a->next()` is exactly the same as `a+1`; `a=a->next()` is `a++`.

    Method offset_to

      `int offset_to(TimeRange x)`

    Description

      Calculates offset to x; this compares two timeranges and gives the integer offset between the two starting points.

      This is true for suitable a and b: `a+a->offset_to(b)==b`

      By suitable means that a and b are of the same type and size. This is obviously true only if a+n has b as a possible result for any n.

    Method place

      `TimeRange place(TimeRange this)`
      `TimeRange place(TimeRange this, bool force)`

    Description

      This will place the given timerange in this timerange, for instance, day 37 in the year - `Year(1934)->place(Day(1948 d37)) => Day(1934 d37)`.

    Note

      The rules how to place things in different timeranges can be somewhat 'dwim'.

    Method set_ruleset
    Method ruleset

      `TimeRange set_ruleset(Ruleset r)`
      `TimeRange ruleset(Ruleset r)`

    Description

      Set or get the current ruleset.

    Note

      this may include timezone shanges, and change the time of day.

    Method set_size

      `TimeRange set_size(TimeRange size)`
      `TimeRange set_size(int n, TimeRange size)`

    Description

      Gives back a new (or the same, if the size matches) timerange with the new size. If n are given, the resulting size will be n amounts of the given size.

    Note

      A negative size is not permitted; a zero one are.

    Method set_timezone
    Method timezone

      `TimeRange set_timezone(Timezone tz)`
      `TimeRange set_timezone(string tz)`
      `TimeZone timezone()`

    Description

      Set or get the current timezone (including dst) rule.

    Note

      The time-of-day may very well change when you change timezone.

      To get the time of day for a specified timezone, select the timezone before getting the time of day:

      `Year(2003)->...->set_timezone(TimeZone.CET)->...->hour(14)->...`

    Method subtract

      `TimeRange subtract(TimeRange what)`

    Description

      This subtracts a period of time from another;

          >- the past          the future -<
          |-------called-------|
               |-------other--------|
          <---->  <- called->subtract(other)

          |-------called-------|
               |---third---|
          <---->           <---> <- called->subtract(third)

Module Calendar.Timezone

  Description

    This module contains all the predefined timezones. Index it with whatever timezone you want to use.

    Example: `Calendar.Calendar my_cal= Calendar.ISO->set_timezone(Calendar.Timezone["Europe/Stockholm"]);`

    A simpler way of selecting timezones might be to just give the string to set_timezone; it indexes by itself:

    `Calendar.Calendar my_cal= Calendar.ISO->set_timezone("Europe/Stockholm");`

  Note

    Do not confuse this module with Ruleset.Timezone, which is the base class of a timezone object.

    `"CET"` and some other standard abbreviations work too, but not all of them (due to more then one country using them).

    Do not call set_timezone too often, but remember the result if possible. It might take some time to initialize a timezone object.

    There are about 504 timezones with 127 different daylight saving rules. Most of them historic.

    The timezone information comes from ftp://elsie.nci.nih.gov/pub/ and are not made up from scratch. Timezone bugs may be reported to the timezone mailing list, tz@elsie.nci.nih.gov, preferable with a `cc` to mirar+pike@mirar.org. /Mirar

  See also

    TZnames

  Constant locale

    `constant Calendar.Timezone.locale = Rule.Timezone`

  Description

    This contains the local timezone, found from various parts of the system, if possible.

  Constant localtime

    `constant Calendar.Timezone.localtime = Rule.Timezone`

  Description

    This is a special timezone, that uses localtime() and tzname to find out what current offset and timezone string to use.

    locale uses this if there is no other way of finding a better timezone to use.

    This timezone is limited by localtime and libc to the range of `time_t`, which is a MAXINT on most systems - 13 Dec 1901 20:45:52 to 19 Jan 2038 3:14:07, UTC.

Module Calendar.YMD

  Description

    base for all Roman-kind of Calendars, ie, one with years, months, weeks and days

  Method datetime

    `mapping(string:int) datetime(int|void unix_time)`

  Description

    Replacement for localtime; gives back a mapping:

         ([ "year":     int        // year number (2000 AD=2000, 1 BC==0)
            "month":    int(1..)   // month of year
            "day":      int(1..)   // day of month
            "yearday":  int(1..)   // day of year
            "week":     int(1..)   // week of year
            "week_day": int(1..)   // day of week (depending on calendar)
            "unix":     int        // unix time
            "julian":   float      // julian day
            "hour":     int(0..)   // hour of day, including dst
            "minute":   int(0..59) // minute of hour
            "second":   int(0..59) // second of minute
            "fraction": float      // fraction of second
            "timezone": int        // offset to utc, including dst
         ]);

    This is the same as calling Second()->datetime().

  Method datetime_name
  Method datetime_short_name

    `string datetime_name(int|void unix_time)`
    `string datetime_short_name(int|void unix_time)`

  Description

    Compat functions; same as format_iso and format_iso_short.

  Method deltat

    `float deltat(int unadjusted_utc)`

  Description

    Terrestrial Dynamical Time difference from standard time.

    An approximation of the difference between TDT and UTC in fractional seconds at the specified time.

    The zero point is 1901-06-25T14:23:01 UTC (unix time -2162281019), ie the accumulated number of leap seconds since then is returned.

  Returns

  Note

    The function is based on polynomials provided by NASA, and the result may differ from actual for dates after 2004.

  Method dwim_day

    `Day dwim_day(string date)`
    `Day dwim_day(string date, TimeRange context)`

  Description

    Tries a number of different formats on the given date (in order):

        <ref>parse</ref> format                  as in
        "%y-%M-%D (%M) -W%W-%e (%e)"  "2000-03-20 (Mar) -W12-1 (Mon)"
        "%y-%M-%D"                    "2000-03-20", "00-03-20"
        "%M%/%D/%y"                   "3/20/2000"
        "%D%*[ /]%M%*[ /-,]%y"        "20/3/2000" "20 mar 2000" "20/3 -00"
        "%e%*[ ]%D%*[ /]%M%*[ /-,]%y" "Mon 20 Mar 2000" "Mon 20/3 2000"
        "-%y%*[ /]%D%*[ /]%M"         "-00 20/3" "-00 20 mar"
        "-%y%*[ /]%M%*[ /]%D"         "-00 3/20" "-00 march 20"
        "%y%*[ /]%D%*[ /]%M"          "00 20 mar" "2000 20/3"
        "%y%*[ /]%M%*[ /]%D"          "2000 march 20"
        "%D%.%M.%y"                   "20.3.2000"
        "%D%*[ -/]%M"                 "20/3" "20 mar" "20-03"
        "%M%*[ -/]%D"                 "3/20" "march 20"
        "%M-%D-%y"                    "03-20-2000"
        "%D-%M-%y"                    "20-03-2000"
        "%e%*[- /]%D%*[- /]%M"        "mon 20 march"
        "%e%*[- /]%M%*[- /]%D"        "mon/march/20"
        "%e%*[ -/wv]%W%*[ -/]%y"      "mon w12 -00" "1 w12 2000"
        "%e%*[ -/wv]%W"               "mon w12"
        "%d"                          "20000320", "000320"
        "today"                       "today"
        "last %e"                     "last monday"
        "next %e"                     "next monday"

  Note

    Casts exception if it fails to dwim out a day. "dwim" means do-what-i-mean.

  Method dwim_time

    `Day dwim_time(string date_time)`
    `Day dwim_time(string date_time, object TimeRangecontext)`

  Description

    Tries a number of different formats on the given date_time.

  Note

    Casts exception if it fails to dwim out a time. "dwim" means do-what-i-mean.

  Method format_iso
  Method format_iso_short
  Method format_iso_tod
  Method format_day_iso
  Method format_day_iso_short

    `string format_iso(void|int unix_time)`
    `string format_iso_short(void|int unix_time)`
    `string format_iso_tod(void|int unix_time)`
    `string format_day_iso(void|int unix_time)`
    `string format_day_iso_short(void|int unix_time)`

  Description

    Format the object into nice strings;

        iso    "2000-06-02 (Jun) -W22-5 (Fri) 11:57:18 CEST"
        iso_short   "2000-06-02 11:57:18"
        iso_tod     "11:57:18"

  Inherit Time

    inherit Time : Time

  Method parse

    `TimeRange parse(string fmt, string arg)`

  Description

    parse a date, create relevant object fmt is in the format "abc%xdef..." where abc and def is matched, and %x is one of those time units:

        %Y absolute year
        %y dwim year (70-99 is 1970-1999, 0-69 is 2000-2069)
        %M month (number, name or short name) (needs %y)
        %W week (needs %y)
        %D date (needs %y, %m)
        %d short date (20000304, 000304)
        %a day (needs %y)
        %e weekday (needs %y, %w)
        %h hour (needs %d, %D or %W)
        %m minute (needs %h)
        %s second (needs %m)
        %S seconds since the Epoch (only combines with %f)
        %f fraction of a second (needs %s or %S)
        %t short time (205314, 2053)
        %z zone
        %p "am" or "pm"
        %n empty string (to be put at the end of formats)

  Returns

    0 if format doesn't match data, or the appropriate time object.

  Note

    The zone will be a guess if it doesn't state an exact regional timezone (like "Europe/Stockholm") - most zone abbriviations (like "CET") are used by more then one region with it's own daylight saving rules. Also beware that for instance CST can be up to four different zones, central Australia or America being the most common.

        Abbreviation Interpretation
        AMT          America/Manaus       [UTC-4]
        AST          America/Curacao      [UTC-4]
        CDT          America/Costa_Rica   [UTC-6]
        CST          America/El Salvador  [UTC-6]
        EST          America/Panama       [UTC-5]
        GST          Asia/Dubai           [UTC+4]
        IST          Asia/Jerusalem       [UTC+2]
        WST          Australia/Perth      [UTC+8]

    This mapping is modifiable in the ruleset, see Ruleset.set_abbr2zone.

  CLASS Calendar.YMD.Day

    Method create

      `Calendar.YMD.Day Calendar.YMD.Day("unix", int unix_time)`
      `Calendar.YMD.Day Calendar.YMD.Day("julian", int|float julian_day)`
      `Calendar.YMD.Day Calendar.YMD.Day(int year, int month, int day)`
      `Calendar.YMD.Day Calendar.YMD.Day(int year, int year_day)`
      `Calendar.YMD.Day Calendar.YMD.Day(int julian_day)`

    Description

      It's possible to create the day by using five different methods; either the normal way - from standard unix time or the julian day, and also, for more practical use, from year, month and day, from year and day of year, and from julian day without extra fuzz.

    Inherit YMD

      inherit YMD : YMD

  CLASS Calendar.YMD.Fraction

    Inherit Fraction

      inherit Time.Fraction : Fraction

    Inherit YMD

      inherit YMD : YMD

  CLASS Calendar.YMD.Hour

    Inherit Hour

      inherit Time.Hour : Hour

    Inherit YMD

      inherit YMD : YMD

  CLASS Calendar.YMD.Minute

    Inherit Minute

      inherit Time.Minute : Minute

    Inherit YMD

      inherit YMD : YMD

  CLASS Calendar.YMD.Month

    Inherit YMD

      inherit YMD : YMD

  CLASS Calendar.YMD.Second

    Inherit Second

      inherit Time.Second : Second

    Inherit YMD

      inherit YMD : YMD

  CLASS Calendar.YMD.SuperTimeRange

    Inherit SuperTimeRange

      inherit Time.SuperTimeRange : SuperTimeRange

  CLASS Calendar.YMD.Week

    Description

      The Calendar week represents a standard time period of a week. In the Gregorian calendar, the standard week starts on a sunday and ends on a saturday; in the ISO calendar, it starts on a monday and ends on a sunday.

      The week are might not be aligned to the year, and thus the week may cross year borders and the year of the week might not be the same as the year of all the days in the week. The basic rule is that the week year is the year that has the most days in the week, but since week number only is specified in the ISO calendar - and derivates - the week number of most calendars is the week number of most of the days in the ISO calendar, which modifies this rule for the Gregorian calendar; the week number and year is the same as for the ISO calendar, except for the sundays.

      When adding, moving and subtracting months to a week, it falls back to using days.

      When adding, moving or subtracting years, if tries to place the moved week in the resulting year.

    Method create

      `Calendar.YMD.Week Calendar.YMD.Week("unix", int unix_time)`
      `Calendar.YMD.Week Calendar.YMD.Week("julian", int|float julian_day)`
      `Calendar.YMD.Week Calendar.YMD.Week(int year, int week)`

    Description

      It's possible to create the standard week by using three different methods; either the normal way - from standard unix time or the julian day, and also, for more practical use, from year and week number.

      Can be less than 1 for the first week of the year if it begins in the previous year.

    Method day

      `Day day()`
      `Day day(int n)`
      `Day day(string name)`

    Description

      The Week type overloads the day() method, so it is possible to get a specified weekday by string:

      `week->day("sunday")`

      The integer and no argument behavior is inherited from YMD().

    Note

      the weekday-from-string routine is language dependent.

    Inherit YMD

      inherit YMD : YMD

  CLASS Calendar.YMD.YMD

    Description

      Base (virtual) time period of the Roman-kind of calendar.

    Method datetime

      `mapping datetime()`

    Description

      This gives back a mapping with the relevant time information (representing the start of the period);

           ([ "year":     int        // year number (2000 AD=2000, 1 BC==0)
              "month":    int(1..)   // month of year
              "day":      int(1..)   // day of month
              "yearday":  int(0..)   // day of year
              "week":     int(1..)   // week of year
              "week_day": int(0..)   // day of week
              "timezone": int        // offset to utc, including dst

              "unix":     int        // unix time
              "julian":   int        // julian day
           // for compatibility:
              "hour":     0          // hour of day, including dst
              "minute":   0          // minute of hour
              "second":   0          // second of minute
              "fraction": 0.0        // fraction of second
           ]);

    Note

      Day of week is compatible with old versions, ie, 0 is sunday, 6 is saturday, so it shouldn't be used to calculate the day of the week with the given week number. Year day is also backwards compatible, ie, one (1) less then from the year_day() function.

      If this function is called in a Week object that begins with the first week of a year, it returns the previous year if that is where the week starts. To keep the representation unambiguous, the returned week number is then one more than the number of weeks in that year.

      E.g. Week(2008,1)->datetime() will return year 2007 and week 53 since the first week of 2008 starts in 2007.

    Method day

      `Day day()`
      `Day day(int n)`

    Description

      Get day number n in the current range.

      If n is negative, it is counted from the end of the range.

    Method days

      `array(Day) days(int|void from, object int|voidto)`

    Description

      Get the days in the current range.

    Method format_iso_ymd
    Method format_ymd
    Method format_ymd_short
    Method format_ymd_xshort
    Method format_iso_week
    Method format_iso_week_short
    Method format_week
    Method format_week_short
    Method format_month
    Method format_month_short
    Method format_iso_time
    Method format_time
    Method format_time_short
    Method format_time_xshort
    Method format_mtime
    Method format_xtime
    Method format_tod
    Method format_todz
    Method format_xtod
    Method format_mod

      `string format_iso_ymd()`
      `string format_ymd()`
      `string format_ymd_short()`
      `string format_ymd_xshort()`
      `string format_iso_week()`
      `string format_iso_week_short()`
      `string format_week()`
      `string format_week_short()`
      `string format_month()`
      `string format_month_short()`
      `string format_iso_time()`
      `string format_time()`
      `string format_time_short()`
      `string format_time_xshort()`
      `string format_mtime()`
      `string format_xtime()`
      `string format_tod()`
      `string format_todz()`
      `string format_xtod()`
      `string format_mod()`

    Description

      Format the object into nice strings;

          iso_ymd        "2000-06-02 (Jun) -W22-5 (Fri)" [2]
          ext_ymd        "Friday, 2 June 2000" [2]
          ymd            "2000-06-02"
          ymd_short      "20000602"
          ymd_xshort     "000602" [1]
          iso_week       "2000-W22"
          iso_week_short "2000W22"
          week           "2000-w22" [2]
          week_short     "2000w22" [2]
          month          "2000-06"
          month_short    "200006" [1]
          iso_time       "2000-06-02 (Jun) -W22-5 (Fri) 00:00:00 UTC+1" [2]
          ext_time       "Friday, 2 June 2000, 00:00:00" [2]
          ctime          "Fri Jun  2 00:00:00 2000\n" [2] [3]
          http           "Fri, 02 Jun 2000 00:00:00 GMT" [4]
          time           "2000-06-02 00:00:00"
          time_short     "20000602 00:00:00"
          time_xshort    "000602 00:00:00"
          iso_short      "2000-06-02T00:00:00"
          mtime          "2000-06-02 00:00"
          xtime          "2000-06-02 00:00:00.000000"
          tod            "00:00:00"
          tod_short      "000000"
          todz           "00:00:00 CET"
          todz_iso       "00:00:00 UTC+1"
          xtod           "00:00:00.000000"
          mod            "00:00"

      `[1]` note conflict (think 1 February 2003)
      `[2]` language dependent
      `[3]` as from the libc function ctime()
      `[4]` as specified by the HTTP standard; not language dependent.

      The iso variants aim to be compliant with ISO-8601.

    Method fraction_no
    Method hour_no
    Method julian_day
    Method leap_year
    Method minute_no
    Method month_day
    Method month_no
    Method second_no
    Method utc_offset
    Method week_day
    Method week_no
    Method year_day
    Method year_no
    Method month_name
    Method month_shortname
    Method month_day_name
    Method week_day_name
    Method week_day_shortname
    Method week_name
    Method year_name
    Method tzname
    Method tzname_iso
    Method unix_time

      `float fraction_no()`
      `int hour_no()`
      `int julian_day()`
      `int leap_year()`
      `int minute_no()`
      `int month_day()`
      `int month_no()`
      `int second_no()`
      `int utc_offset()`
      `int week_day()`
      `int week_no()`
      `int year_day()`
      `int year_no()`
      `string month_name()`
      `string month_shortname()`
      `string month_day_name()`
      `string week_day_name()`
      `string week_day_shortname()`
      `string week_name()`
      `string year_name()`
      `string tzname()`
      `string tzname_iso()`
      `int unix_time()`

    Description

      Returns the unix time integer corresponding to the start of the time range object. (An unix time integer is UTC.)

    Method second
    Method minute
    Method seconds
    Method number_of_seconds
    Method minutes
    Method number_of_minutes
    Method hour
    Method hours
    Method number_of_hours

      `Second second()`
      `Second second(int n)`
      `Minute minute(int hour, int minute, int second)`
      `array(Second) seconds()`
      `array(Second) seconds(int first, int last)`
      `int number_of_seconds()`
      `Minute minute()`
      `Minute minute(int n)`
      `Minute minute(int hour, int minute)`
      `array(Minute) minutes()`
      `array(Minute) minutes(int first, int last)`
      `int number_of_minutes()`
      `Hour hour()`
      `Hour hour(int n)`
      `array(Hour) hours()`
      `array(Hour) hours(int first, int last)`
      `int number_of_hours()`

    Inherit TimeRange

      inherit TimeRange : TimeRange

    Method number_of_days

      `int number_of_days()`

    Description

      Get the number of days in the current range.

  CLASS Calendar.YMD.Year

    Description

      This is the time period of a year.

    Method create

      `Calendar.YMD.Year Calendar.YMD.Year("unix", int unix_time)`
      `Calendar.YMD.Year Calendar.YMD.Year("julian", int|float julian_day)`
      `Calendar.YMD.Year Calendar.YMD.Year(int year)`
      `Calendar.YMD.Year Calendar.YMD.Year(string year)`
      `Calendar.YMD.Year Calendar.YMD.Year(TimeRange range)`

    Description

      It's possible to create the standard year by using three different methods; either the normal way - from standard unix time or the julian day, and also, for more practical use, from the year number.

    Inherit TimeRange

      inherit TimeRange : TimeRange

    Inherit YMD

      inherit YMD : YMD

    Method month

      `Month month()`
      `Month month(int n)`
      `Month month(string name)`

    Description

      The Year type overloads the month() method, so it is possible to get a specified month by string:

      `year->month("April")`

      The integer and no argument behavior is inherited from YMD().

    Method week

      `Week week()`
      `Week week(int n)`
      `Week week(string name)`

    Description

      The Year type overloads the week() method, so it is possible to get a specified week by name:

      `year->week("17")` `year->week("w17")`

      The integer and no argument behavior is inherited from YMD().

      This is useful, since the first week of a year not always (about half the years, in the ISO calendar) is numbered '1'.

Module Charset

  Description

    The Charset module supports a wide variety of different character sets, and it is flexible in regard of the names of character sets it accepts. The character case is ignored, as are the most common non-alaphanumeric characters appearing in character set names. E.g. `"iso-8859-1"` works just as well as `"ISO_8859_1"`. All encodings specified in RFC 1345 are supported.

    First of all the Charset module is capable of handling the following encodings of Unicode:

    - utf7, utf8, utf16, utf16be, utf16le, utf32, utf32be, utf32le, utf75 and utf7½

      UTF encodings

    - shiftjis, euc-kr, euc-cn and euc-jp

    Most, if not all, of the relevant code pages are represented, as the following list shows. Prefix the numbers as noted in the list to get the wanted codec:

    - 037, 038, 273, 274, 275, 277, 278, 280, 281, 284, 285, 290, 297, 367, 420, 423, 424, 437, 500, 819, 850, 851, 852, 855, 857, 860, 861, 862, 863, 864, 865, 866, 868, 869, 870, 871, 880, 891, 903, 904, 905, 918, 932, 936, 950 and 1026

      These may be prefixed with `"cp"`, `"ibm"` or `"ms"`.

    - 1250, 1251, 1252, 1253, 1254, 1255, 1256, 1257 and 1258

      These may be prefixed with `"cp"`, `"ibm"`, `"ms"` or `"windows"`

    - mysql-latin1

      The default charset in MySQL, similar to `cp1252`.

    +359 more.

  Note

    In Pike 7.8 and earlier this module was named Locale.Charset.

  Method decode_error

    `void decode_error(string err_str, int err_pos, string charset, void|string reason, void|mixed ... args)`

  Description

    Throws a DecodeError exception. See DecodeError.create for details about the arguments. If args is given then the error reason is formatted using `sprintf(<font face='courier'>reason`, @<font face='courier'>args).

  Method decoder

    `Decoder decoder(string name)`

  Description

    Returns a charset decoder object.

  Parameter `name`

    The name of the character set to decode from. Supported charsets include (not all supported charsets are enumerable): "iso_8859-1:1987", "iso_8859-1:1998", "iso-8859-1", "iso-ir-100", "latin1", "l1", "ansi_x3.4-1968", "iso_646.irv:1991", "iso646-us", "iso-ir-6", "us", "us-ascii", "ascii", "cp367", "ibm367", "cp819", "ibm819", "iso-2022" (of various kinds), "utf-7", "utf-8" and various encodings as described by RFC1345.

  Throws

    If the asked-for name was not supported, an error is thrown.

  Method decoder_from_mib

    `Decoder decoder_from_mib(int mib)`

  Description

    Returns a decoder for the encoding schema denoted by MIB mib.

  Method encode_error

    `void encode_error(string err_str, int err_pos, string charset, void|string reason, void|mixed ... args)`

  Description

    Throws an EncodeError exception. See EncodeError.create for details about the arguments. If args is given then the error reason is formatted using `sprintf(<font face='courier'>reason`, @<font face='courier'>args).

  Method encoder

    `Encoder encoder(string name, string|void replacement, function(string:string)|void repcb)`

  Description

    Returns a charset encoder object.

  Parameter `name`

    The name of the character set to encode to. Supported charsets include (not all supported charsets are enumerable): "iso_8859-1:1987", "iso_8859-1:1998", "iso-8859-1", "iso-ir-100", "latin1", "l1", "ansi_x3.4-1968", "iso_646.irv:1991", "iso646-us", "iso-ir-6", "us", "us-ascii", "ascii", "cp367", "ibm367", "cp819", "ibm819", "iso-2022" (of various kinds), "utf-7", "utf-8" and various encodings as described by RFC1345.

  Parameter `replacement`

    The string to use for characters that cannot be represented in the charset. It's used when repcb is not given or when it returns zero. If no replacement string is given then an error is thrown instead.

  Parameter `repcb`

    A function to call for every character that cannot be represented in the charset. If specified it's called with one argument - a string containing the character in question. If it returns a string then that one will replace the character in the output. If it returns something else then the replacement argument will be used to decide what to do.

  Throws

    If the asked-for name was not supported, an error is thrown.

  Method encoder_from_mib

    `Encoder encoder_from_mib(int mib, string|void replacement, function(string:string)|void repcb)`

  Description

    Returns an encoder for the encoding schema denoted by MIB mib.

  Method normalize

    `string normalize(string in)`

  Description

    All character set names are normalized through this function before compared.

  Method set_decoder

    `void set_decoder(string name, Decoder decoder)`

  Description

    Adds a custom defined character set decoder. The name is normalized through the use of normalize.

  Method set_encoder

    `void set_encoder(string name, Encoder encoder)`

  Description

    Adds a custom defined character set encoder. The name is normalized through the use of normalize.

  CLASS Charset.DecodeError

    Description

      Error thrown when decode fails (and no replacement char or replacement callback has been registered).

    FIXME

      This error class is not actually used by this module yet - decode errors are still thrown as untyped error arrays. At this point it exists only for use by other modules.

    Variable charset

      `string Charset.DecodeError.charset`

    Description

      The decoding charset, typically as known to Charset.decoder.

    Note

      Other code may produce errors of this type. In that case this name is something that Charset.decoder does not accept (unless it implements exactly the same charset), and it should be reasonably certain that Charset.decoder never accepts that name in the future (unless it is extended to implement exactly the same charset).

    Variable err_pos

      `int Charset.DecodeError.err_pos`

    Description

      The failing position in err_str.

    Variable err_str

      `string Charset.DecodeError.err_str`

    Description

      The string that failed to be decoded.

    Inherit Generic

      inherit Error.Generic : Generic

  CLASS Charset.Decoder

    Description

      Virtual base class for charset decoders.

    Example

          string win1252_to_string( string data )
             {
               return Charset.decoder("windows-1252")->feed( data )->drain();
             }

    Variable charset

      `string Charset.Decoder.charset`

    Description

      Name of the charset - giving this name to decoder returns an instance of the same class as this object.

    Note

      This is not necessarily the same name that was actually given to decoder to produce this object.

    Method clear

      `this_program clear()`

    Description

      Clear buffers, and reset all state.

    Returns

      Returns the current object to allow for chaining of calls.

    Method drain

      `string drain()`

    Description

      Get the decoded data, and reset buffers.

    Returns

      Returns the decoded string.

    Method feed

      `this_program feed(string s)`

    Description

      Feeds a string to the decoder.

    Parameter `s`

      String to be decoded.

    Returns

      Returns the current object, to allow for chaining of calls.

  CLASS Charset.EncodeError

    Description

      Error thrown when encode fails (and no replacement char or replacement callback has been registered).

    FIXME

      This error class is not actually used by this module yet - encode errors are still thrown as untyped error arrays. At this point it exists only for use by other modules.

    Variable charset

      `string Charset.EncodeError.charset`

    Description

      The encoding charset, typically as known to Charset.encoder.

    Note

      Other code may produce errors of this type. In that case this name is something that Charset.encoder does not accept (unless it implements exactly the same charset), and it should be reasonably certain that Charset.encoder never accepts that name in the future (unless it is extended to implement exactly the same charset).

    Variable err_pos

      `int Charset.EncodeError.err_pos`

    Description

      The failing position in err_str.

    Variable err_str

      `string Charset.EncodeError.err_str`

    Description

      The string that failed to be encoded.

    Inherit Generic

      inherit Error.Generic : Generic

  CLASS Charset.Encoder

    Description

      Virtual base class for charset encoders.

    Variable charset

      `string Charset.Encoder.charset`

    Description

      Name of the charset - giving this name to encoder returns an instance of the same class as this one.

    Note

      This is not necessarily the same name that was actually given to encoder to produce this object.

    Inherit Decoder

      inherit Decoder : Decoder

    Description

      An encoder only differs from a decoder in that it has an extra function.

    Method set_replacement_callback

      `void set_replacement_callback(function(string:string) rc)`

    Description

      Change the replacement callback function.

    Parameter `rc`

      Function that is called to encode characters outside the current character encoding.

  Module Charset.Tables

    Module Charset.Tables.iso88591

      Description

        Codec for the ISO-8859-1 character encoding.

Module Colors

  Method cmyk_to_rgb

    `array(int(8bit)) cmyk_to_rgb(array(int(0..100)) cmyk)`
    `array(int(8bit)) cmyk_to_rgb(int(0..100) c, int(0..100) m, int(0..100) y, int(0..100) k)`

  Description

    This function return the RGB value of the color describe by the provided CMYK value. It is essentially calling Image.Color.cmyk(c,m,y,k)->rgb()

  See also

    Colors.rgb_to_cmyk() Image.Color.cmyk()

  Method color_name

    `string color_name(array(int(8bit)) rgb)`

  Description

    Tries to find a name to color described by the provided RGB values. Partially an inverse function to Colors.parse_color(), although it can not find all the names that Colors.parse_color() can find RGB values for. Returns the colors rgb hex value prepended with "#" upon failure.

  Method hsv_to_rgb

    `array(int(8bit)) hsv_to_rgb(array(int(8bit)) hsv)`
    `array(int(8bit)) hsv_to_rgb(int(8bit) h, int(8bit) s, int(8bit) v)`

  Description

    This function returns the RGB value of the color described by the provided HSV value. It is essentially calling Image.Color.hsv(h,s,v)->rgb().

  See also

    Colors.rgb_to_hsv() Image.Color.hsv()

  Method parse_color

    `array(int(8bit)) parse_color(string name, void|array(int) def)`

  Description

    This function returns the RGB values that corresponds to the color that is provided by name to the function. It is essentially calling Image.Color.guess(), but returns the default value (or black if none is provided) if it failes.

  Method rgb_to_cmyk

    `array(int(0..100)) rgb_to_cmyk(array(int(8bit)) rgb)`
    `array(int(0..100)) rgb_to_cmyk(int(8bit) r, int(8bit) g, int(8bit) b)`

  Description

    This function returns the CMYK value of the color described by the provided RGB value. It is essentially calling Image.Color.rgb(r,g,b)->cmyk().

  See also

    Colors.cmyk_to_rgb() Image.Color.Color.cmyk()

  Method rgb_to_hsv

    `array(int(8bit)) rgb_to_hsv(array(int(8bit)) rgb)`
    `array(int(8bit)) rgb_to_hsv(int(8bit) r, int(8bit) g, int(8bit) b)`

  Description

    This function returns the HSV value of the color described by the provided RGB value. It is essentially calling Image.Color.rgb(r,g,b)->hsv().

  See also

    Colors.hsv_to_rgb() Image.Color.Color.hsv()

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

    `int read(function(array(int|string), int:void) callback, Stdio.File|string logfile, void|int offset)`

  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
    `string remote_host` |
    `int(0..0)|string ident_user` |
    `int(0..0)|string auth_user` |
    `int year` |
    `int month` |
    `int day` |
    `int hours` |
    `int minutes` |
    `int seconds` |
    `int timezone` |
    `int(0..0)|string method` | One of "GET", "POST", "HEAD" etc.
    `int(0..0)|string path` |
    `string protocol` | E.g. "HTTP/1.0"
    `int reply_code` | One of 200, 404 etc.
    `int bytes` |

    The second callback argument is the current offset to the end of the current line.

  Parameter `offset`

    The position in the file where the parser should begin.

Module Crypto

  Description

    Various cryptographic classes and functions.

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

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

    As the cryptographic services offered from this module isn't necessarily used for security applications, none of the strings inputted or outputted are marked as secure. This is up to the caller.

  Note

    This module is only available if Pike has been compiled with Nettle enabled (this is the default).

  Variable Buffer

    `__deprecated__ program Crypto.Buffer`

  Description

    This class has moved to submodules of the respective ciphers.

  Method make_crypt_md5

    `string(8bit) make_crypt_md5(string(8bit) password, void|string(8bit) salt)`

  Description

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

  See also

    verify_crypt_md5

  Method rot13

    `string(8bit) rot13(string(8bit) data)`

  Description

    Convenience function that accesses the crypt function of a substitution object keyed to perform standard ROT13 (de)ciphering.

  Method verify_crypt_md5

    `bool verify_crypt_md5(string(8bit) password, string(7bit) hash)`

  Description

    Verifies the password against the crypt_md5 hash.

  Throws

    May throw an exception if the hash value is bad.

  See also

    make_crypt_md5

  CLASS Crypto.AEAD

    Description

      Abstract class for AEAD algorithms.

    Inherit AEAD

      inherit Nettle.AEAD : AEAD

  CLASS Crypto.BlockCipher

    Description

      Abstract class for block cipher algorithms. Contains some tools useful for all block ciphers.

      Contains the CBC submodule.

    Inherit BlockCipher

      inherit Nettle.BlockCipher : BlockCipher

  CLASS Crypto.BlockCipher16

    Description

      Abstract class for block cipher algorithms with a 16 byte block size. Contains some tools useful for all such block ciphers.

      Contains the GCM submodule.

    Inherit BlockCipher16

      inherit Nettle.BlockCipher16 : BlockCipher16

  CLASS Crypto.Buffer

    Description

      This class has moved to submodules of the respective ciphers.

    Deprecated

      Replaced by BlockCipher.Buffer.

    Method create

      `Crypto.Buffer Crypto.Buffer(CipherState|program fun, mixed ... args)`

  CLASS Crypto.BufferedCipher

    Description

      Abstract class for block cipher meta algorithms.

      Contains the Buffer submodule.

    Inherit BufferedCipher

      inherit Nettle.BufferedCipher : BufferedCipher

  CLASS Crypto.CBC

    Description

      This class has moved to submodules of the respective ciphers.

    Deprecated

      Replaced by BlockCipher.CBC.

    Method create

      `Crypto.CBC Crypto.CBC(CipherState|program fun, mixed ... args)`

  CLASS Crypto.Cipher

    Description

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

    Note

      Typically only inherited directly by stream ciphers.

    Note

      It is however convenient for typing as it contains the minimum base level API for a cipher.

    See also

      BufferedCipher, BlockCipher, BlockCipher16

    Inherit Cipher

      inherit Nettle.Cipher : Cipher

  CLASS Crypto.HMAC

    Description

      HMAC, defined by RFC-2104

    Method `()

      `Crypto.MAC.State res = Crypto.HMAC()()`

    Description

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

    Method create

      `Crypto.HMAC Crypto.HMAC(.Hash h, int|void b)`

    Parameter `h`

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

    Parameter `b`

      The block size of one compression block, in octets. Defaults to block_size() of h.

    Method pkcs_digest

      `string(8bit) pkcs_digest(string(8bit) s)`

    Description

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

    See also

      Standards.PKCS.Signature.build_digestinfo

    Method raw_hash

      `string(8bit) raw_hash(string(8bit) s)`

    Description

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

  CLASS Crypto.Hash

    Description

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

    Inherit Hash

      inherit Nettle.Hash : Hash

  CLASS Crypto.MAC

    Description

      Abstract class for MAC algorithms.

    Inherit MAC

      inherit Nettle.MAC : MAC

  CLASS Crypto.Pipe

    Description

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

  CLASS Crypto.Sign

    Description

      Abstract class for signature algorithms. Contains some tools useful for all signatures.

    Method `()

      `State res = Crypto.Sign()()`

    Description

      Calling `() will return a State object.

    Method name

      `string(7bit) name()`

    Description

      Returns the printable name of the signing algorithm.

  CLASS Crypto.Substitution

    Description

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

    Method decrypt

      `string(8bit) decrypt(string(8bit) c)`

    Description

      Decrypts the cryptogram c.

    Method encrypt

      `string(8bit) encrypt(string(8bit) m)`

    Description

      Encrypts the message m.

    Method filter

      `string filter(string m, void|multiset(int) save)`

    Description

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

    Method set_ACA_K1_key

      `this_program set_ACA_K1_key(string key, void|int offset, void|array(string) alphabet)`

    Description

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

    Method set_ACA_K2_key

      `this_program set_ACA_K2_key(string key, void|int offset, void|array(string) alphabet)`

    Description

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

    Method set_ACA_K3_key

      `this_program set_ACA_K3_key(string key, int offset, void|array(string) alphabet)`

    Description

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

    Method set_ACA_K4_key

      `this_program set_ACA_K4_key(string key1, string key2, void|int offset, void|array(string) alphabet)`

    Description

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

    Method set_key

      `this_program set_key(mapping(string:string|array(string)) key)`

    Description

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

    Throws

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

    Method set_null_chars

      `this_program set_null_chars(int|float p, array(string) chars)`

    Description

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

    Parameter `p`

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

    Parameter `chars`

      An array of one character strings.

    Method set_rot_key

      `this_program set_rot_key(void|int steps, void|array(string) alphabet)`

    Description

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

  Module Crypto.AES

    Description

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

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

    Inherit AES

      inherit Nettle.AES : AES

    Module Crypto.AES.POLY1305

      Method `()

        `State `()(string(8bit) password)`

      Description

        Get a POLY1305 State object initialized with a password.

      Inherit POLY1305_AES

        inherit Nettle.POLY1305_AES : POLY1305_AES

    Module Crypto.AES.UMAC128

      Description

        UMAC is a familty of message digest functions based on universal hashing and AES that is specified in RFC 4418. They differ mainly in the size of the resulting digest.

        UMAC128 outputs a digest of 128 bits or 16 octets.

      See also

        UMAC32, UMAC64, UMAC96

      Method `()

        `State `()(string(8bit) password)`

      Description

        Get a UMAC128 State object initialized with a password.

      Inherit UMAC128_AES

        inherit Nettle.UMAC128_AES : UMAC128_AES

    Module Crypto.AES.UMAC32

      Description

        UMAC is a familty of message digest functions based on universal hashing and AES that is specified in RFC 4418. They differ mainly in the size of the resulting digest.

        UMAC32 outputs a digest of 32 bits or 4 octets.

      See also

        UMAC64, UMAC96, UMAC128

      Method `()

        `State `()(string(8bit) password)`

      Description

        Get a UMAC32 State object initialized with a password.

      Inherit UMAC32_AES

        inherit Nettle.UMAC32_AES : UMAC32_AES

    Module Crypto.AES.UMAC64

      Description

        UMAC is a familty of message digest functions based on universal hashing and AES that is specified in RFC 4418. They differ mainly in the size of the resulting digest.

        UMAC64 outputs a digest of 64 bits or 8 octets.

      See also

        UMAC32, UMAC96, UMAC128

      Method `()

        `State `()(string(8bit) password)`

      Description

        Get a UMAC64 State object initialized with a password.

      Inherit UMAC64_AES

        inherit Nettle.UMAC64_AES : UMAC64_AES

    Module Crypto.AES.UMAC96

      Description

        UMAC is a familty of message digest functions based on universal hashing and AES that is specified in RFC 4418. They differ mainly in the size of the resulting digest.

        UMAC96 outputs a digest of 96 bits or 12 octets.

      See also

        UMAC32, UMAC64, UMAC128

      Method `()

        `State `()(string(8bit) password)`

      Description

        Get a UMAC96 State object initialized with a password.

      Inherit UMAC96_AES

        inherit Nettle.UMAC96_AES : UMAC96_AES

  Module Crypto.Arcfour

    Description

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

    Inherit ARCFOUR

      inherit Nettle.ARCFOUR : ARCFOUR

  Module Crypto.Arctwo

    Description

      Arctwo is a block cipher, also known under the trade marked name RC2.

      The cipher is quite weak, and should not be used for new software.

    Inherit ARCTWO

      inherit Nettle.ARCTWO : ARCTWO

  Module Crypto.Blowfish

    Description

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

    Inherit BLOWFISH

      inherit Nettle.BLOWFISH : BLOWFISH

  Module Crypto.CAST

    Description

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

    Inherit CAST128

      inherit Nettle.CAST128 : CAST128

  Module Crypto.Camellia

    Description

      The Camellia 128-bit block cipher.

    Inherit CAMELLIA

      inherit Nettle.CAMELLIA : CAMELLIA

  Module Crypto.ChaCha20

    Description

      ChaCha20 is a stream cipher by D. J. Bernstein.

    Note

      This module is not available in all versions of Nettle.

    Inherit CHACHA

      inherit Nettle.CHACHA : CHACHA

    Module Crypto.ChaCha20.POLY1305

      Description

        This is an AEAD cipher consisting of the CHACHA cipher and a MAC based on the POLY1305 algorithm.

      Note

        Note that this is an AEAD cipher, while AES.POLY1305 (aka POLY1305-AES) is a MAC.

      Note

        Note also that the POLY1305 algorithm used here is NOT identical to the one in the AES.POLY1305 MAC. The iv/nonce handling differs.

      Note

        This module is not available in all versions of Nettle.

      Inherit CHACHA_POLY1305

        inherit Nettle.CHACHA_POLY1305 : CHACHA_POLY1305

  Module Crypto.DES

    Description

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

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

      DES also has some weak keys.

    Inherit DES

      inherit Nettle.DES : DES

  Module Crypto.DES3

    Description

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

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

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

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

    Inherit DES3

      inherit Nettle.DES3 : DES3

  Module Crypto.DH

    Description

      Diffie-Hellman key-exchange related stuff.

    Variable FFDHE2048

      `Parameters Crypto.DH.FFDHE2048`

    Description

      Finite Field Diffie-Hellman 2048

      From Negotiated FF-DHE for TLS draft 04, December 2014, Appendix A.1.

    Variable FFDHE2432

      `Parameters Crypto.DH.FFDHE2432`

    Description

      Finite Field Diffie-Hellman 2432

      From Negotiated FF-DHE for TLS draft 03, November 2014, Appendix A.1.

    Variable FFDHE3072

      `Parameters Crypto.DH.FFDHE3072`

    Description

      Finite Field Diffie-Hellman 3072

      From Negotiated FF-DHE for TLS draft 04, December 2014, Appendix A.2.

    Variable FFDHE4096

      `Parameters Crypto.DH.FFDHE4096`

    Description

      Finite Field Diffie-Hellman 4096

      From Negotiated FF-DHE for TLS draft 04, December 2014, Appendix A.3.

    Variable FFDHE6144

      `Parameters Crypto.DH.FFDHE6144`

    Description

      Finite Field Diffie-Hellman 6144

      From Negotiated FF-DHE for TLS draft 02, October 2014, Appendix A.4.

    Variable FFDHE8192

      `Parameters Crypto.DH.FFDHE8192`

    Description

      Finite Field Diffie-Hellman 8192

      From Negotiated FF-DHE for TLS draft 04, December 2014, Appendix A.4.

    Variable MODPGroup1

      `Parameters Crypto.DH.MODPGroup1`

    Description

      MODP Group 1 (768 bit) (aka First Oakley Group (aka ORM96 group 1)).

      RFC 2409 6.1

    Note

      Not allowed for use with FIPS 140.

    Variable MODPGroup14

      `Parameters Crypto.DH.MODPGroup14`

    Description

      MODP Group 14 (2048 bit).

      RFC 3526 3

    Variable MODPGroup15

      `Parameters Crypto.DH.MODPGroup15`

    Description

      MODP Group 15 (3072 bit).

      RFC 3526 3

    Variable MODPGroup16

      `Parameters Crypto.DH.MODPGroup16`

    Description

      MODP Group 16 (4096 bit).

      RFC 3526 5

    Variable MODPGroup17

      `Parameters Crypto.DH.MODPGroup17`

    Description

      MODP Group 17 (6144 bit).

      RFC 3526 6

    Variable MODPGroup18

      `Parameters Crypto.DH.MODPGroup18`

    Description

      MODP Group 18 (8192 bit).

      RFC 3526 7

    Variable MODPGroup2

      `Parameters Crypto.DH.MODPGroup2`

    Description

      MODP Group 2 (1024 bit) (aka Second Oakley Group (aka ORM96 group 2)).

      RFC 2409 6.2

    Note

      Not allowed for use with FIPS 140.

    Variable MODPGroup22

      `Parameters Crypto.DH.MODPGroup22`

    Description

      MODP Group 22 (1024-bit with 160-bit Subgroup).

      RFC 5114 2.1

    Variable MODPGroup23

      `Parameters Crypto.DH.MODPGroup23`

    Description

      MODP Group 23 (2048-bit with 224-bit Subgroup).

      RFC 5114 2.2

    Variable MODPGroup24

      `Parameters Crypto.DH.MODPGroup24`

    Description

      MODP Group 24 (2048-bit with 256-bit Subgroup).

      RFC 5114 2.3

    Variable MODPGroup5

      `Parameters Crypto.DH.MODPGroup5`

    Description

      MODP Group 5 (1536 bit).

      RFC 3526 2

    Note

      Not allowed for use with FIPS 140.

    CLASS Crypto.DH.Parameters

      Description

        Diffie-Hellman parameters.

      Method create

        `Crypto.DH.Parameters Crypto.DH.Parameters(Gmp.mpz|int p, Gmp.mpz|int|void g, Gmp.mpz|int|void q)`

      Description

        Initialize the set of Diffie-Hellman parameters.

      Parameter `p`

        The prime for the group.

      Parameter `g`

        The generator for the group. Defaults to `2`.

      Parameter `q`

        The order of the group. Defaults to `(p-1)/2`.

      Method create

        `Crypto.DH.Parameters Crypto.DH.Parameters(this_program other)`

      Description

        Initialize the set of Diffie-Hellman parameters.

      Parameter `other`

        Copy the parameters from this object.

      Method create

        `Crypto.DH.Parameters Crypto.DH.Parameters(Crypto.DSA.State dsa)`

      Description

        Initialize the set of Diffie-Hellman parameters.

      Parameter `dsa`

        Copy the parameters from this object.

      Variable g

        `Gmp.mpz Crypto.DH.Parameters.g`

      Description

        Generator.

      Method generate_keypair

        `array(Gmp.mpz) generate_keypair(function(int(0..):string(8bit)) rnd)`

      Description

        Generate a Diffie-Hellman key pair.

      Returns

        Returns the following array:

        Array
        `Gmp.mpz 0` | The generated public key.
        `Gmp.mpz 1` | The corresponding private key.

      Inherit DH_Params

        inherit Nettle.DH_Params : DH_Params

      Variable order

        `__deprecated__ Gmp.mpz Crypto.DH.Parameters.order`

      Description

        Alias for q.

      Deprecated

        Replaced by q.

      Variable p

        `Gmp.mpz Crypto.DH.Parameters.p`

      Description

        Prime.

      Variable q

        `Gmp.mpz Crypto.DH.Parameters.q`

      Description

        Subgroup size.

      Method validate

        `bool validate(int(0..) effort)`

      Description

        Validate that the DH Parameters doesn't have obvious security weaknesses. It will first attempt to verify the prime p using Donald Knuth's probabilistic primality test with provided effort. This has a chance of pow(0.25,effort) to produce a false positive. An effort of 0 skipps this step. The second test verifies that g is of high order.

  Module Crypto.DSA

    Description

      The Digital Signature Algorithm DSA is part of the NIST Digital Signature Standard DSS, FIPS-186 (1993).

    Method `()

      `protected State `()()`

    Description

      Calling `() will return a State object.

    Inherit Sign

      inherit Crypto.Sign : Sign

    Method name

      `string(8bit) name()`

    Description

      Returns the string `"DSA"`.

    CLASS Crypto.DSA.State

      Method _equal

        `bool equal(Crypto.DSA.State from, mixed other)`

      Description

        Compares the keys of this DSA object with something other.

      Method generate_key

        `variant this_program generate_key(int p_bits, int q_bits)`

      Description

        Generates DSA parameters (p, q, g) and key (x, y). Depending on Nettle version q_bits can be 160, 224 and 256 bits. 160 works for all versions.

      Method generate_key

        `variant this_program generate_key()`

      Description

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

      Method get_g

        `Gmp.mpz get_g()`

      Description

        Returns the DSA generator (g).

      Method get_p

        `Gmp.mpz get_p()`

      Description

        Returns the DSA modulo (p).

      Method get_q

        `Gmp.mpz get_q()`

      Description

        Returns the DSA group order (q).

      Method get_x

        `Gmp.mpz get_x()`

      Description

        Returns the DSA private key (x).

      Method get_y

        `Gmp.mpz get_y()`

      Description

        Returns the DSA public key (y).

      Method hash

        `Gmp.mpz hash(string(8bit) msg, .Hash h)`

      Description

        Makes a DSA hash of the messge msg.

      Inherit this_program

        inherit ::this_program : this_program

      Method name

        `string(8bit) name()`

      Description

        Returns the string `"DSA"`.

      Method pkcs_algorithm_identifier

        `Sequence pkcs_algorithm_identifier()`

      Description

        Returns the AlgorithmIdentifier as defined in RFC5280 section 4.1.1.2 including the DSA parameters.

      Method pkcs_public_key

        `Sequence pkcs_public_key()`

      Description

        Creates a SubjectPublicKeyInfo ASN.1 sequence for the object. See RFC 5280 section 4.1.2.7.

      Method pkcs_sign

        `string(8bit) pkcs_sign(string(8bit) message, .Hash h)`

      Description

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

      Method pkcs_signature_algorithm_id

        `Sequence pkcs_signature_algorithm_id(.Hash hash)`

      Description

        Returns the PKCS-1 algorithm identifier for DSA and the provided hash algorithm. Only SHA1 supported.

      Method pkcs_verify

        `bool pkcs_verify(string(8bit) message, .Hash h, string(8bit) sign)`

      Description

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

      Method public_key_equal

        `bool public_key_equal(this_program dsa)`

      Description

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

      Method raw_sign

        `array(Gmp.mpz) raw_sign(Gmp.mpz h, void|Gmp.mpz k)`

      Description

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

      Method raw_verify

        `bool raw_verify(Gmp.mpz h, Gmp.mpz r, Gmp.mpz s)`

      Description

        Verify the signature r,s against the message h.

      Method set_private_key

        `this_program set_private_key(Gmp.mpz secret)`

      Description

        Sets the private key, the x parameter, in this DSA object.

      Method set_public_key

        `this_program set_public_key(Gmp.mpz modulo, Gmp.mpz order, Gmp.mpz generator, Gmp.mpz key)`

      Description

        Sets the public key in this DSA object.

      Parameter `modulo`

        This is the p parameter.

      Parameter `order`

        This is the group order q parameter.

      Parameter `generator`

        This is the g parameter.

      Parameter `kye`

        This is the public key y parameter.

      Method set_random

        `this_program set_random(function(int(0..):string(8bit)) r)`

      Description

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

      Method sign_rsaref

        `__deprecated__ string(8bit) sign_rsaref(string(8bit) msg)`

      Description

        Make a RSA ref signature of message msg.

      Method sign_ssl

        `__deprecated__ string(8bit) sign_ssl(string(8bit) msg)`

      Description

        Make an SSL signature of message msg.

      Method verify_rsaref

        `__deprecated__ bool verify_rsaref(string(8bit) msg, string(8bit) s)`

      Description

        Verify a RSA ref signature s of message msg.

      Method verify_ssl

        `__deprecated__ bool verify_ssl(string(8bit) msg, string(8bit) s)`

      Description

        Verify an SSL signature s of message msg.

  Module Crypto.ECC

    Description

      Elliptic Curve Cipher Constants.

      This module contains constants used with elliptic curve algorithms.

    CLASS Crypto.ECC.Curve

      Description

        The definition of an elliptic curve.

        Objects of this class are typically not created by the user.

      See also

        SECP_192R1, SECP_224R1, SECP_256R1, SECP_384R1, SECP_521R1

      Inherit ECC_Curve

        inherit Nettle.ECC_Curve : ECC_Curve

      Method pkcs_algorithm_identifier

        `Sequence pkcs_algorithm_identifier()`

      Description

        Returns the AlgorithmIdentifier as defined in RFC5480 section 2.

      Method pkcs_ec_parameters

        `Identifier pkcs_ec_parameters()`

      Description

        Returns the PKCS-1 elliptic curve parameters for the curve. cf RFC 5480 2.1.1.

      Method pkcs_named_curve_id

        `Identifier pkcs_named_curve_id()`

      Description

        Returns the PKCS-1 elliptic curve identifier for the curve. cf RFC 5480 2.1.1.

      CLASS Crypto.ECC.Curve.ECDSA

        Description

          Elliptic Curve Digital Signing Algorithm

        Method _equal

          `bool equal(Crypto.ECC.Curve.ECDSA from, mixed other)`

        Description

          Compares the keys of this ECDSA object with something other.

        Method generate_key

          `this_program generate_key()`

        Description

          Generate a new set of private and public keys on the current curve.

        Method get_curve

          `Curve get_curve()`

        Description

          Return the curve.

        Method get_public_key

          `string(8bit) get_public_key()`

        Description

          Get the ANSI x9.62 4.3.6 encoded uncompressed public key.

        Inherit ECDSA

          inherit ECC_Curve::ECDSA : ECDSA

        Method key_size

          `int(0..) key_size()`

        Description

          Return the size of the private key in bits.

        Method pkcs_algorithm_identifier

          `Sequence pkcs_algorithm_identifier()`

        Description

          Returns the AlgorithmIdentifier as defined in RFC5480 section 2.1.1 including the ECDSA parameters.

        Method pkcs_public_key

          `Sequence pkcs_public_key()`

        Description

          Creates a SubjectPublicKeyInfo ASN.1 sequence for the object. See RFC 5280 section 4.1.2.7.

        Method pkcs_sign

          `string(8bit) pkcs_sign(string(8bit) message, .Hash h)`

        Description

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

        Method pkcs_signature_algorithm_id

          `Sequence pkcs_signature_algorithm_id(.Hash hash)`

        Description

          Returns the PKCS-1 algorithm identifier for ECDSA and the provided hash algorithm. Only SHA-1 and SHA-2 based hashes are supported currently.

        Method pkcs_verify

          `bool pkcs_verify(string(8bit) message, .Hash h, string(8bit) sign)`

        Description

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

        Method public_key_equal

          `bool public_key_equal(this_program ecdsa)`

        Description

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

        Method set_private_key

          `this_program set_private_key(Gmp.mpz|int k)`

        Description

          Set the private key.

        Note

          Throws errors if the key isn't valid for the curve.

        Method set_public_key

          `this_program set_public_key(Gmp.mpz|int x, Gmp.mpz|int y)`

        Description

          Change to the selected point on the curve as public key.

        Note

          Throws errors if the point isn't on the curve.

        Method set_public_key

          `variant this_program set_public_key(string(8bit) key)`

        Description

          Change to the selected point on the curve as public key.

        Parameter `key`

          The public key encoded according to ANSI x9.62 4.3.6.

        Note

          Throws errors if the point isn't on the curve.

        Method set_random

          `this_program set_random(function(int:string(8bit)) r)`

        Description

          Set the random function, used to generate keys and parameters, to the function r.

        Method size

          `int size()`

        Description

          Return the curve size in bits.

    Module Crypto.ECC.SECP_192R1

      Inherit Curve

        inherit Curve : Curve

    Module Crypto.ECC.SECP_224R1

      Inherit Curve

        inherit Curve : Curve

    Module Crypto.ECC.SECP_256R1

      Inherit Curve

        inherit Curve : Curve

    Module Crypto.ECC.SECP_384R1

      Inherit Curve

        inherit Curve : Curve

    Module Crypto.ECC.SECP_521R1

      Inherit Curve

        inherit Curve : Curve

  Module Crypto.GOST94

    Description

      The GOST94 or GOST R 34.11-94 hash algorithm is a Soviet-era algorithm used in Russian government standards, defined in RFC 4357.

    Inherit GOST94

      inherit Nettle.GOST94 : GOST94

  Module Crypto.IDEA

    Description

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

    Inherit IDEA

      inherit Nettle.IDEA : IDEA

  Module Crypto.Koremutake

    Description

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

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

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

    Method decrypt

      `int decrypt(string c)`

    Description

      Decode a koremutake string into an integer.

    Method encrypt

      `string encrypt(int m)`

    Description

      Encode an integer as a koremutake string.

  Module Crypto.MD2

    Description

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

    Inherit MD2

      inherit Nettle.MD2 : MD2

  Module Crypto.MD4

    Description

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

    Inherit MD4

      inherit Nettle.MD4 : MD4

  Module Crypto.MD5

    Description

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

    Method crypt_hash

      `string(7bit) crypt_hash(string(8bit) password, string(7bit) salt, int|void rounds)`

    Description

      This is a convenience alias for Nettle.crypt_md5(), that uses the same API as the other hashes.

    Note

      The rounds parameter is currently ignored. For forward compatibility, either leave out, or specify as `1000`.

    See also

      Nettle.Hash()->crypt_hash(), crypt_md5()

    Inherit MD5

      inherit Nettle.MD5 : MD5

  Module Crypto.NT

    CLASS Crypto.NT.CryptContext

      Description

        Class representing an HCRYPTPROV handle.

      Method create

        `Crypto.NT.CryptContext Crypto.NT.CryptContext(string(8bit) name, string(8bit) csp, int type, int flags)`

      Parameter `name`

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

      Parameter `csp`

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

      Method read

        `string(8bit) read(int size, string(8bit)|void init)`

      Description

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

  Module Crypto.PGP

    Description

      PGP stuff. See RFC 4880.

    Method decode

      `mapping(string:string|mapping) decode(string s)`

    Description

      Decodes PGP data.

    Method decode_radix64

      `mapping(string:mixed) decode_radix64(string data)`

    Description

      Decode ASCII armour.

    Method encode_radix64

      `string encode_radix64(string data, string type, void|mapping(string:string) extra)`

    Description

      Encode PGP data with ASCII armour.

    Method verify_signature

      `int verify_signature(string text, string sig, string pubkey)`

    Description

      Verify text against signature sig with the public key pubkey.

  Module Crypto.Password

    Description

      Password handling.

      This module handles generation and verification of password hashes.

    See also

      verify(), hash(), crypt()

    Method hash

      `string(7bit) hash(string(8bit) password, string(7bit)|void scheme, int|void rounds)`

    Description

      Generate a hash of password suitable for verify().

    Parameter `password`

      Password to hash.

    Parameter `scheme`

      Password hashing scheme. If not specified the strongest available will be used.

      If an unsupported scheme is specified an error will be thrown.

      Supported schemes are:

      Crypt(3C)-style:

      `UNDEFINED` | Use the strongest crypt(3C)-style hash that is supported.
      `"crypt"`
      `"{crypt}"`
      `"6"` | SHA512.crypt_hash() with 96 bits of salt and a default of `5000` rounds.
      `"$6$"`
      `"5"` | SHA256.crypt_hash() with 96 bits of salt and a default of `5000` rounds.
      `"$5$"`
      `"1"` | MD5.crypt_hash() with 48 bits of salt and `1000` rounds.
      `"$1$"`
      `""` | predef::crypt() with 12 bits of salt.

      LDAP (RFC2307)-style. Don't use these if you can avoid it, since they are suspectible to attacks. In particular avoid the unsalted variants at all costs:

      `"ssha"` | SHA1.hash() with 96 bits of salt appended to the password.
      `"{ssha}"`
      `"smd5"` | MD5.hash() with 96 bits of salt appended to the password.
      `"{smd5}"`
      `"sha"` | SHA1.hash() without any salt.
      `"{sha}"`
      `"md5"` | MD5.hash() without any salt.
      `"{md5}"`

    Parameter `rounds`

      The number of rounds to use in parameterized schemes. If not specified the scheme specific default will be used.

    Returns

      Returns a string suitable for verify(). This means that the hashes will be prepended with the suitable markers.

    Note

      Note that the availability of SHA512 depends on the version of Nettle that Pike has been compiled with.

    Note

      This function was added in Pike 7.8.755.

    See also

      verify(), predef::crypt(), Nettle.crypt_md5(), Nettle.Hash()->crypt_hash()

    Method verify

      `int verify(string(8bit) password, string(8bit) hash)`

    Description

      Verify a password against a hash.

      This function attempts to support most common password hashing schemes. The hash can be on any of the following formats.

      LDAP-style (RFC2307) hashes:

      `"{SHA}XXXXXXXXXXXXXXXXXXXXXXXXXXXX"` | The `XXX` string is taken to be a MIME.encode_base64 SHA1 hash of the password. Source: OpenLDAP FAQ http://www.openldap.org/faq/data/cache/347.html.
      `"{SSHA}XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"` | The `XXX` string is taken to be a MIME.encode_base64 string in which the first 20 chars are an SHA1 hash and the remaining chars the salt. The input for the hash is the password concatenated with the salt. Source: OpenLDAP FAQ http://www.openldap.org/faq/data/cache/347.html.
      `"{MD5}XXXXXXXXXXXXXXXXXXXXXXXX"` | The `XXX` string is taken to be a MIME.encode_base64 MD5 hash of the password. Source: OpenLDAP FAQ http://www.openldap.org/faq/data/cache/418.html.
      `"{SMD5}XXXXXXXXXXXXXXXXXXXXXXXXXXXX"` | The `XXX` string is taken to be a MIME.encode_base64 string in which the first 16 chars are an MD5 hash and the remaining chars the salt. The input for the hash is the password concatenated with the salt. Source: OpenLDAP FAQ http://www.openldap.org/faq/data/cache/418.html.
      `"{CRYPT}XXXXXXXXXXXXX"` | The `XX` string is taken to be a crypt(3C)-style hash. This is the same thing as passing the `XXX` string without any preceding method name within `{...}`. I.e. it's interpreted according to the crypt-style hashes below.

      Crypt-style hashes:

      `"$6$SSSSSSSSSSSSSSSS$XXXXXXXXXXXXXXXXXXXXXX"` | The string is interpreted according to the "Unix crypt using SHA-256 and SHA-512" standard Version 0.4 2008-4-3, where `SSSSSSSSSSSSSSSS` is up to 16 characters of salt, and the string `XXX` the result of SHA512.crypt_hash() with `5000` rounds. Source: Unix crypt using SHA-256 and SHA-512 http://www.akkadia.org/drepper/SHA-crypt.txt
      `"$6$rounds=RR$SSSSSSSSSSSSSSSS$XXXXXXXXXXXXXXXXXXXXXX"` | This is the same algorithm as the one above, but with the number of rounds specified by `RR` in decimal. Note that the number of rounds is clamped to be within `1000` and `999999999` (inclusive). Source: Unix crypt using SHA-256 and SHA-512 http://www.akkadia.org/drepper/SHA-crypt.txt
      `"$5$SSSSSSSSSSSSSSSS$XXXXXXXXXXXXXXXXXXXXXX"` | The string is interpreted according to the "Unix crypt using SHA-256 and SHA-512" standard Version 0.4 2008-4-3, where `SSSSSSSSSSSSSSSS` is up to 16 characters of salt, and the string `XXX` the result of SHA256.crypt_hash() with `5000` rounds. Source: Unix crypt using SHA-256 and SHA-512 http://www.akkadia.org/drepper/SHA-crypt.txt
      `"$5$rounds=RR$SSSSSSSSSSSSSSSS$XXXXXXXXXXXXXXXXXXXXXX"` | This is the same algorithm as the one above, but with the number of rounds specified by `RR` in decimal. Note that the number of rounds is clamped to be within `1000` and `999999999` (inclusive). Source: Unix crypt using SHA-256 and SHA-512 http://www.akkadia.org/drepper/SHA-crypt.txt
      `"$1$SSSSSSSS$XXXXXXXXXXXXXXXXXXXXXX"` | The string is interpreted according to the GNU libc2 extension of `crypt(3C)` where `SSSSSSSS` is up to 8 chars of salt and the `XXX` string is an MD5-based hash created from the password and the salt. Source: GNU libc http://www.gnu.org/software/libtool/manual/libc/crypt.html.
      `"XXXXXXXXXXXXX"` | The `XXX` string (which doesn't begin with `"{"`) is taken to be a password hashed using the classic unix `crypt(3C)` function. If the string contains only chars from the set `[a-zA-Z0-9./]` it uses DES and the first two characters as salt, but other alternatives might be possible depending on the `crypt(3C)` implementation in the operating system.
      `""` | The empty password hash matches all passwords.

    Returns

      Returns `1` on success, and `0` (zero) otherwise.

    Note

      This function was added in Pike 7.8.755.

    See also

      hash(), predef::crypt()

  Module Crypto.RIPEMD160

    Description

      RIPEMD160 is a hash function designed by Hans Dobbertin, Antoon Bosselaers, and Bart Preneel, as a strengthened version of RIPEMD (which, like MD4 and MD5, fails the collision-resistance requirement). It produces message digests of 160 bits, or 20 octets.

    Inherit RIPEMD160

      inherit Nettle.RIPEMD160 : RIPEMD160

  Module Crypto.RSA

    Method `()

      `protected State `()(mapping(string(8bit):Gmp.mpz|int)|void params)`

    Description

      Calling `() will return a State object.

    Inherit Sign

      inherit Crypto.Sign : Sign

    Method name

      `string(8bit) name()`

    Description

      Returns the string `"RSA"`.

    CLASS Crypto.RSA.State

      Method _equal

        `bool equal(Crypto.RSA.State from, mixed other)`

      Description

        Compares the keys of this RSA object with something other.

      Method block_size

        `int block_size()`

      Description

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

      Method cooked_get_d

        `__deprecated__ string(8bit) cooked_get_d()`

      Description

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

      Method cooked_get_e

        `__deprecated__ string(8bit) cooked_get_e()`

      Description

        Returns the RSA public exponent (e) as a binary string.

      Method cooked_get_n

        `__deprecated__ string(8bit) cooked_get_n()`

      Description

        Returns the RSA modulo (n) as a binary string.

      Method cooked_get_p

        `__deprecated__ string(8bit) cooked_get_p()`

      Description

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

      Method cooked_get_q

        `__deprecated__ string(8bit) cooked_get_q()`

      Description

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

      Method cooked_sign

        `__deprecated__ string(8bit) cooked_sign(string(8bit) digest)`

      Description

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

      Method create

        `Crypto.RSA.State Crypto.RSA.State(mapping(string(8bit):Gmp.mpz|int)|void params)`

      Description

        Can be initialized with a mapping with the elements n, e, d, p and q.

      Method crypt

        `string(8bit) crypt(string(8bit) s)`

      Description

        Encrypt or decrypt depending on set mode.

      See also

        set_encrypt_key, set_decrypt_key

      Method decrypt

        `string(8bit) decrypt(string(8bit) s)`

      Description

        Decrypt a message encrypted with encrypt.

      Method encrypt

        `string(8bit) encrypt(string(8bit) s, function(int:string(8bit))|void r)`

      Description

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

      Parameter `r`

        Optional random function to be passed down to rsa_pad.

      Method generate_key

        `this_program generate_key(int(128..) bits, void|int|Gmp.mpz e)`

      Description

        Generate a valid RSA key pair with the size bits using the random function set with set_random(). The public exponent e will be used, which defaults to 65537. Keys must be at least 89 bits.

      Method generate_key

        `variant __deprecated__ this_program generate_key(int(128..) bits, function(int(0..):string(8bit)) rnd)`

      Description

        Compatibility with Pike 7.8.

      Method get_d

        `Gmp.mpz get_d()`

      Description

        Returns the RSA private exponent (d), if known.

      Method get_e

        `Gmp.mpz get_e()`

      Description

        Returns the RSA public exponent (e).

      Method get_n

        `Gmp.mpz get_n()`

      Description

        Returns the RSA modulo (n).

      Method get_p

        `Gmp.mpz get_p()`

      Description

        Returns the first RSA prime (p), if known.

      Method get_q

        `Gmp.mpz get_q()`

      Description

        Returns the second RSA prime (q), if known.

      Inherit this_program

        inherit ::this_program : this_program

      Method key_size

        `int(0..) key_size()`

      Description

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

      Method name

        `string(8bit) name()`

      Description

        Returns the string `"RSA"`.

      Method pkcs_public_key

        `Sequence pkcs_public_key()`

      Description

        Calls Standards.PKCS.RSA.build_public_key with this object as argument.

      Method pkcs_sign

        `string(8bit) pkcs_sign(string(8bit) message, .Hash h)`

      Description

        Signs the message with a PKCS-1 signature using hash algorithm h. This is equivalent to I2OSP(RSASP1(OS2IP(RSAES-PKCS1-V1_5-ENCODE(message)))) in PKCS#1 v2.2.

      Method pkcs_signature_algorithm_id

        `Sequence pkcs_signature_algorithm_id(.Hash hash)`

      Description

        Calls Standards.PKCS.RSA.signatue_algorithm_id with the provided hash.

      Method pkcs_verify

        `bool pkcs_verify(string(8bit) message, .Hash h, string(8bit) sign)`

      Description

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

      Method public_key_equal

        `bool public_key_equal(this_program rsa)`

      Description

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

      Method raw_sign

        `Gmp.mpz raw_sign(string(8bit) digest)`

      Description

        Pads the digest with rsa_pad type 1 and signs it. This is equivalent to RSASP1(OS2IP(RSAES-PKCS1-V1_5-ENCODE(message))) in PKCS#1 v2.2.

      Method raw_verify

        `bool raw_verify(string(8bit) digest, Gmp.mpz s)`

      Description

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

      See also

        rsa_pad, raw_sign

      Method rsa_pad

        `Gmp.mpz rsa_pad(string(8bit) message, int(1..2) type, function(int(0..):string(8bit))|void random)`

      Description

        Pads the message to the current block size with method type and returns the result as an integer. This is equivalent to OS2IP(RSAES-PKCS1-V1_5-ENCODE(message)) in PKCS#1 v2.2.

      Parameter `type`

        `1` | The message is padded with `0xff` bytes.
        `2` | The message is padded with random data, using the random function if provided. Otherwise the default random function set in the object will be used.

      Method rsa_unpad

        `string(8bit) rsa_unpad(Gmp.mpz block, int type)`

      Description

        Reverse the effect of rsa_pad.

      Method set_decrypt_key

        `this_program set_decrypt_key(array(Gmp.mpz) key)`

      Description

        Sets the public key to keyand the mod to decryption.

      See also

        set_encrypt_key, crypt

      Method set_encrypt_key

        `this_program set_encrypt_key(array(Gmp.mpz) key)`

      Description

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

      See also

        set_decrypt_key, crypt

      Method set_private_key

        `this_program set_private_key(Gmp.mpz|int priv, array(Gmp.mpz|int)|void extra)`

      Description

        Sets the private key.

      Parameter `priv`

        The private RSA exponent, often called d.

      Parameter `extra`

        Array
        `Gmp.mpz|int 0` | The first prime, often called p.
        `Gmp.mpz|int 1` | The second prime, often called q.

      Method set_public_key

        `this_program set_public_key(Gmp.mpz|int modulo, Gmp.mpz|int pub)`

      Description

        Sets the public key.

      Parameter `modulo`

        The RSA modulo, often called n. This value needs to be >=12.

      Parameter `pub`

        The public RSA exponent, often called e.

      Method set_random

        `this_program set_random(function(int(0..):string(8bit)) r)`

      Description

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

  Module Crypto.Random

    Description

      This module contains a pseudo random number generator (PRNG) designed to give you the best possible random number generation. The current design is based on the Fortuna PRNG, but uses the system random source as input.

    Method add_entropy

      `void add_entropy(string(8bit) data)`

    Description

      Inject additional entropy into the random generator. One possible use is to persist random data between executions of an application. The internal state is approximately 256 bits, so storing 32 bytes from random_string() at shutdown and injecting them through add_entropy() agan at startup should carry over the entropy. Note that this doesn't affect the independent initialization that happens in the generator at startup, so the output sequence will be different than if the application had continued uninterrupted.

    Parameter `data`

      The random string.

    Method random

      `Gmp.mpz random(int top)`

    Description

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

    Method random_string

      `string(8bit) random_string(int len)`

    Description

      Returns a string of length len with random content. The content is generated by a Fortuna random generator that is updated with output from /dev/urandom on UNIX and CryptGenRandom on NT.

  Module Crypto.SALSA20

    Description

      The SALSA20 stream cipher.

    Inherit SALSA20

      inherit Nettle.SALSA20 : SALSA20

  Module Crypto.SALSA20R12

    Description

      The SALSA20 stream cipher reduced to just 12 rounds.

    Inherit SALSA20R12

      inherit Nettle.SALSA20R12 : SALSA20R12

  Module Crypto.SHA1

    Description

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

    Inherit SHA1

      inherit Nettle.SHA1 : SHA1

  Module Crypto.SHA224

    Description

      SHA224 is another hash function specified by NIST, intended as a replacement for SHA1, generating larger digests. It outputs hash values of 224 bits, or 28 octets.

    Inherit SHA224

      inherit Nettle.SHA224 : SHA224

  Module Crypto.SHA256

    Description

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

    Inherit SHA256

      inherit Nettle.SHA256 : SHA256

  Module Crypto.SHA384

    Description

      SHA384 is another hash function specified by NIST, intended as a replacement for SHA1, generating larger digests. It outputs hash values of 384 bits, or 48 octets.

    Inherit SHA384

      inherit Nettle.SHA384 : SHA384

  Module Crypto.SHA3_224

    Description

      SHA-3-224 is another hash function specified by NIST, intended as a replacement for SHA-2. It outputs hash values of 224 bits, or 28 octets.

    Inherit SHA3_224

      inherit Nettle.SHA3_224 : SHA3_224

  Module Crypto.SHA3_256

    Description

      SHA-3-256 is another hash function specified by NIST, intended as a replacement for SHA-2. It outputs hash values of 256 bits, or 32 octets.

    Inherit SHA3_256

      inherit Nettle.SHA3_256 : SHA3_256

  Module Crypto.SHA3_384

    Description

      SHA-3-386 is another hash function specified by NIST, intended as a replacement for SHA-2. It outputs hash values of 256 bits, or 48 octets.

    Inherit SHA3_384

      inherit Nettle.SHA3_384 : SHA3_384

  Module Crypto.SHA3_512

    Description

      SHA-3-512 is another hash function specified by NIST, intended as a replacement for SHA-2. It outputs hash values of 512 bits, or 64 octets.

    Inherit SHA3_512

      inherit Nettle.SHA3_512 : SHA3_512

  Module Crypto.SHA512

    Description

      SHA512 is another hash function specified by NIST, intended as a replacement for SHA1, generating larger digests. It outputs hash values of 512 bits, or 64 octets.

    Inherit SHA512

      inherit Nettle.SHA512 : SHA512

  Module Crypto.Serpent

    Description

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

    Inherit SERPENT

      inherit Nettle.SERPENT : SERPENT

  Module Crypto.Twofish

    Description

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

    Inherit Twofish

      inherit Nettle.Twofish : Twofish

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.Audio DVB.Audio(int card_number)`
      `DVB.Audio DVB.Audio()`

    Description

      Create a Audio object.

    Parameter `card_number`

      The number of card equipment.

    Method mixer

      `int mixer(int left, int right)`
      `int mixer(int both)`

    Description

      Sets output level on DVB audio device.

    Method mute

      `int mute(int mute)`
      `int mute()`

    Description

      Mute or unmute audio device.

    Method status

      `mapping status()`

    Description

      Returns mapping of current audio device status.

  CLASS DVB.Stream

    Description

      Represents an elementary data stream (PES).

    Method close

      `void close()`

    Description

      Closes an open stream.

    See also

      read()

    Method destroy

      `int destroy()`

    Description

      Purge a stream reader.

    See also

      DVB.dvb()->stream(), read()

    Method read

      `string|int read()`

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

  CLASS DVB.dvb

    Description

      Main class.

    Method analyze_pat

      `mapping analyze_pat()`

    Description

      Return mapping of all PMT.

      sid:prognum

    Method analyze_pmt

      `array(mapping)|int analyze_pmt(int sid, int prognum)`

    Description

      Parse PMT table.

    See also

      analyze_pat()

    Method create

      `DVB.dvb DVB.dvb(int card_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

      `mapping fe_info()`

    Description

      Return info of a frondend device.

    Note

      The information heavily depends on driver. Many fields contain dumb values.

    Method fe_status

      `mapping|int fe_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|int get_pids()`

    Description

      Returns mapping with info of currently tuned program's pids.

    See also

      tune()

    Method stream

      `DVB.Stream stream(int pid, int|function(:void) rcb, int ptype)`
      `DVB.Stream stream(int pid, int|function(:void) rcb)`
      `DVB.Stream stream(int pid)`

    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

      `int tune(int(2bit) lnb, int freq, bool|string pol, int sr)`

    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

  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

    `mixed describe(mixed x)`

  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

    `int describe_encoded_value(string data)`

  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(program p)`

  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
    `int modifiers` | Bitfield with the modifiers for the symbol.
    `string symbol_name` | Name of the symbol.
    `type value_type` | Value type for the symbol.
    `int symbol_type` | Type of symbol.
    `int symbol_offset` | Offset into the code or data area for the symbol.
    `int inherit_offset` | Offset in the inherit table to the inherit containing the symbol.
    `int inherit_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

    `void disassemble(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

    `void dmalloc_set_name(string filename, int(1..) linenumber)`

  Note

    Only available when compiled with dmalloc.

  Method dump_backlog

    `void dump_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

    `void dump_dmalloc_locations(string|array|mapping|multiset|function(:void)|object|program|type o)`

  Note

    Only available when compiled with dmalloc.

  Method dump_program_tables

    `void dump_program_tables(program p, int(0..)|void indent)`

  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.

  Note

    In Pike 7.8.308 and earlier indent wasn't supported.

  Method gc_set_watch

    `void gc_set_watch(array|multiset|mapping|object|function(:void)|program|string x)`

  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 list_open_fds

    `void list_open_fds()`

  Note

    Only available when compiled with dmalloc.

  Method locate_references

    `void locate_references(string|array|mapping|multiset|function(:void)|object|program|type o)`

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

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

    `string pp_memory_usage()`

  Description

    Returns a pretty printed version of the output from memory_usage.

  Method pp_object_usage

    `string pp_object_usage()`

  Description

    Returns a pretty printed version of the output from count_objects (with added estimated RAM usage)

  Method reset_dmalloc

    `void reset_dmalloc()`

  Note

    Only available when compiled with dmalloc.

  Method size_object

    `int size_object(object o)`

  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

    `void verify_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.

  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, ([ "indent":2 ]))
           (2) Result: Debug.Subject
           > abs(class { inherit Debug.Subject; int `<(mixed ... args) { return 1; } }());
           create()
           `-()
           destroy()
           (3) Result: 0
           > pow(s,2);
           `[]("pow")
           Attempt to call the NULL-value
           Unknown program: 0(2)

  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.Tracer Debug.Tracer(int level)`

    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

      `array indices( Debug.Wrapper arg )`

    Method _sizeof

      `int sizeof( Debug.Wrapper arg )`

    Method _sprintf

      `string sprintf(string format, ... Debug.Wrapper arg ... )`

    Method _values

      `array values( Debug.Wrapper arg )`

    Method `!

      `bool res = !Debug.Wrapper()`

    Method `->

      `mixed res = Debug.Wrapper()->X`

    Method `[]

      `mixed res = Debug.Wrapper()[ x ]`

    Method create

      `Debug.Wrapper Debug.Wrapper(object x)`

  Module Debug.Profiling

    Method display

      `void display(int|void num, string|array(string)|void pattern, string|array(string)|void exclude)`

    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

      `array(array(string|float|int)) get_prof_info(string|array(string)|void include, string|array(string)|void exclude)`

    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
      `string name` | The name of the function
      `float number_of_calls` | The number of calls
      `float self_time` | The self CPU time
      `float cpu_time` | The self CPU time, including children.
      `float self_time_pct` | The self CPU time as percentage of total time.
      `float cpu_time_pct` | The self CPU time, including children, as percentage of total time.
      `string function_line` | This is the location in the source of the start of the function

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

Module Error

  Method mkerror

    `object mkerror(mixed error)`

  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.

    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

      `string sprintf(string format, ... Error.Generic arg ... )`

    Method `[]

      `array|string res = Error.Generic()[ index ]`

    Description

      Index operator.

      Simulates an array

      Array
      `string msg` | Error message as returned by message.
      `array backtrace` | Backtrace as returned by backtrace.

    Note

      The error message is always terminated with a newline.

    See also

      backtrace()

    Method backtrace

      `array backtrace()`

    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 `({<font face='courier'>message`(), <font face='courier'>backtrace()}).

    Method create

      `Error.Generic Error.Generic(string message, void|array(backtrace_frame|array(mixed)) backtrace)`

    Method describe

      `string describe()`

    Description

      Return a readable error report that includes the backtrace.

    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 message

      `string message()`

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

    `function(:void) `()(void|string path)`

  Description

    FIXME: Document this function

  Method get_filesystem

    `program get_filesystem(string what)`

  Description

    FIXME: Document this function

  Method parse_mode

    `int parse_mode(int old, int|string mode)`

  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

      `int apply()`

    Description

      FIXME: Document this function

    Method cd

      `Base cd(string|void directory)`

    Description

      Change directory within the filesystem. Returns a new filesystem object with the given directory as cwd.

    Method chmod

      `void chmod(string filename, int|string mode)`

    Description

      Change mode of a file or directory.

    Method chown

      `void chown(string filename, int|object owner, int|object group)`

    Description

      Change ownership of the file or directory

    Method chroot

      `Base chroot(void|string directory)`

    Description

      Change the root of the filesystem.

    Method cwd

      `string cwd()`

    Description

      Returns the current working directory within the filesystem.

    Method find

      `array find(void|function(Stat:int) mask, mixed ... extra)`

    Description

      FIXME: Document this function

    Method get_dir

      `array(string) get_dir(void|string directory, void|string|array glob)`

    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|string directory, void|string|array glob)`

    Description

      Returns stat-objects for the files and directories matching the given glob within the given directory.

    See also

      [get_dir]

    Method mkdir

      `int mkdir(string directory, void|int|string mode)`

    Description

      Create a new directory

    Method open

      `Stdio.File open(string filename, string mode)`

    Description

      Open a file within the filesystem

    Returns

      A Stdio.File object.

    Method rm

      `int rm(string filename)`

    Description

      Remove a file from the filesystem.

    Method stat

      `Stat stat(string file, int|void lstat)`

    Description

      Return a stat-object for a file or a directory within the filesystem.

  CLASS Filesystem.Stat

    Description

      Describes the stat of a file

    Method attach_statarray

      `void attach_statarray(array(int) a)`

    Description

      Fills the stat-object with data from a Stdio.File.stat() call.

    Method cd

      `object cd()`

    Description

      Change to the stated directory.

    Returns

      the directory if the stated object was a directory, 0 otherwise.

    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 nice_date

      `string nice_date()`

    Description

      Returns the date of the stated object as cleartext.

    Method open

      `Stdio.File open(string mode)`

    Description

      Open the stated file within the filesystem

    Returns

      a [Stdio.File] object

    See also

      [Stdio.File]

    Method set_type

      `void set_type(string x)`

    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 and door
    See also

      [isfifo], [ischr], [isdir], [isblk], [isreg], [islnk], [issock], [isdoor]

  CLASS Filesystem.System

    Description

      Implements an abstraction of the normal filesystem.

    Method create

      `Filesystem.System Filesystem.System(void|string directory, void|string root, void|int fast, void|Filesystem.Base parent)`

    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

    Inherit Base

      inherit Filesystem.Base : Base

  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.Traversion Filesystem.Traversion(string path, void|bool symlink, void|bool ignore_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

      `float progress(void|float share)`

    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 stat()`

    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

        System.FSEvents, System.Inotify

      Method adjust_monitor

        `protected void adjust_monitor(Monitor m)`

      Description

        Update the position in the monitor_queue for the monitor m to account for an updated next_poll value.

      Method attr_changed

        `void attr_changed(string path, Stdio.Stat st)`

      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.

      Variable backend

        `protected Pike.Backend Filesystem.Monitor.basic.backend`

      Description

        Backend to use.

        If `0` (zero) - use the default backend.

      Method backend_check

        `protected void backend_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

        `protected string canonic_path(string path)`

      Description

        Canonicalize a path.

      Parameter `path`

        Path to canonicalize.

      Returns

        The default implementation returns `combine_path(path, ".")`, i.e. no trailing slashes.

      Method check

        `int check(int|void max_wait, int|void max_cnt, mapping(string:int)|void ret_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

        `void check_all(mapping(string:int)|void ret_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

        `protected bool check_monitor(Monitor m, MonitorFlags|void flags)`

      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

        `void clear()`

      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.

      Variable co_id

        `protected mixed Filesystem.Monitor.basic.co_id`

      Description

        Call-out identifier for backend_check() if in nonblocking mode.

        Set to `1` when non_blocking mode without call_outs is in use.

      See also

        set_nonblocking(), set_blocking()

      Method create

        `Filesystem.Monitor.basic Filesystem.Monitor.basic(int|void max_dir_check_interval, int|void file_interval_factor, int|void stable_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

        `void data_changed(string path)`

      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.

      Constant default_file_interval_factor

        `protected constant int 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 constant int 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 constant int 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().

      Method eventstream_callback

        `protected void eventstream_callback(string path, int flags, int event_id)`

      Description

        This function is called when the FSEvents EventStream detects a change in one of the monitored directories.

      Method file_created

        `void file_created(string path, Stdio.Stat st)`

      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.

      Method file_deleted

        `void file_deleted(string path)`

      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.

      Method file_exists

        `void file_exists(string path, Stdio.Stat st)`

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

        Overload this to do something useful.

      Method inotify_event

        `protected void inotify_event(int wd, int event, int cookie, string(8bit) path)`

      Description

        Event callback for Inotify.

      Method is_monitored

        `bool is_monitored(string path)`

      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 monitor

        `void monitor(string path, MonitorFlags|void flags, int(0..)|void max_dir_check_interval, int(0..)|void file_interval_factor, int(0..)|void stable_time)`

      Description

        Register a path for monitoring.

      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

        `protected DefaultMonitor monitor_factory(string path, MonitorFlags|void flags, int(0..)|void max_dir_check_interval, int(0..)|void file_interval_factor, int(0..)|void stable_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

      Variable monitor_queue

        `protected ADT.Heap Filesystem.Monitor.basic.monitor_queue`

      Description

        Heap containing active Monitors that need polling.

        The heap is sorted on Monitor()->next_poll.

      Variable monitors

        `protected mapping(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 release

        `void release(string path, MonitorFlags|void flags)`

      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

        `protected void release_monitor(Monitor m)`

      Description

        Release a single Monitor from monitoring.

      See also

        release()

      Method set_backend

        `void set_backend(Pike.Backend|void backend)`

      Description

        Change backend.

      Parameter `backend`

        Backend to use. `0` (zero) for the default backend.

      Method set_blocking

        `void set_blocking()`

      Description

        Turn off nonblocking mode.

      See also

        set_nonblocking()

      Method set_file_interval_factor

        `void set_file_interval_factor(int file_interval_factor)`

      Description

        Set the default_file_interval_factor.

      Method set_max_dir_check_interval

        `void set_max_dir_check_interval(int max_dir_check_interval)`

      Description

        Set the default_max_dir_check_interval.

      Method set_nonblocking

        `void set_nonblocking(int|void t)`

      Description

        Turn on nonblocking mode.

      Parameter `t`

        Suggested time in seconds until next call of check().

        Register suitable callbacks with the backend to automatically call 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 stable_data_change

        `void stable_data_change(string path, Stdio.Stat st)`

      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.

      Method update_monitor

        `protected void update_monitor(Monitor m, Stdio.Stat st)`

      Description

        Calculate a suitable time for the next poll of this monitor.

      Parameter `m`

        Monitor to update.

      Parameter `st`

        New stat for the monitor.

        This function is called by check_monitor() to schedule the next check.

      ENUM Filesystem.Monitor.basic.MonitorFlags

        Description

          Flags for Monitors.

      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-accellerated Monitor.

        Inherit Monitor

          inherit Monitor : Monitor

      CLASS Filesystem.Monitor.basic.InotifyMonitor

        Description

          Inotify-accellerated Monitor.

        Inherit Monitor

          inherit Monitor : Monitor

      CLASS Filesystem.Monitor.basic.Monitor

        Description

          Monitoring information for a single filesystem path.

        See also

          monitor()

        Method attr_changed

          `protected void attr_changed(string path, Stdio.Stat st)`

        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 bump

          `void bump(MonitorFlags|void flags, int|void seconds)`

        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

          `protected void call_callback(function(string, Stdio.Stat|void:void) cb, string path, Stdio.Stat|void st)`

        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

          `bool check(MonitorFlags|void flags)`

        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

          `void check_for_release(int mask, int flags)`

        Description

          Check if this monitor should be removed automatically.

        Method create

          `Filesystem.Monitor.basic.Monitor Filesystem.Monitor.basic.Monitor(string path, MonitorFlags flags, int max_dir_check_interval, int file_interval_factor, int stable_time)`

        Method file_created

          `protected void file_created(string path, Stdio.Stat st)`

        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

          `protected void file_deleted(string path, Stdio.Stat|void old_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().

        Method file_exists

          `protected void file_exists(string path, Stdio.Stat st)`

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

        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`

        Inherit Element

          inherit ADT.Heap.Element : Element

        Method monitor

          `protected void monitor(string path, int flags, int max_dir_interval, int file_interval_factor, int stable_time)`

        Description

          Called to create a sub monitor.

        Method register_path

          `protected void register_path(int|void initial)`

        Description

          Register the Monitor with the monitoring system.

        Parameter `initial`

          Indicates that the Monitor is newly created.

        Method stable_data_change

          `protected void stable_data_change(string path, Stdio.Stat st)`

        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

          `protected bool status_change(Stdio.Stat old_st, Stdio.Stat st, int orig_flags, int flags)`

        Description

          Called when the status has changed for an existing file.

        Method unregister_path

          `protected void unregister_path(int|void dying)`

        Description

          Unregister the Monitor from the monitoring system.

        Parameter `dying`

          Indicates that the Monitor is being destructed.

        Method update

          `protected void update(Stdio.Stat st)`

        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

      Method get_monitors

        `mapping(string:Monitor) get_monitors()`

      Description

        Return the set of active monitors.

      Inherit "symlinks.pike"

        inherit "symlinks.pike" : "symlinks.pike"

    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

      Method allocate_symlink

        `protected int allocate_symlink(string sym)`

      Description

        Allocates a symlink id for the link sym.

      Method attr_changed

        `void attr_changed(string path, Stdio.Stat st)`

      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.

      Variable available_ids

        `protected int Filesystem.Monitor.symlinks.available_ids`

      Description

        Bitmask of all unallocated symlink ids.

      Method file_created

        `void file_created(string path, Stdio.Stat st)`

      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

        `void file_exists(string path, Stdio.Stat st)`

      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.

      Inherit basic

        inherit Filesystem.Monitor.basic : basic

      Method stable_data_change

        `void stable_data_change(string path, Stdio.Stat st)`

      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.

      Variable symlink_ids

        `protected mapping(string:int) Filesystem.Monitor.symlinks.symlink_ids`

      Description

        Mapping from symlink name to symlink id.

      Variable symlink_targets

        `protected mapping(string:string) Filesystem.Monitor.symlinks.symlink_targets`

      Description

        Mapping from symlink name to symlink target.

      CLASS Filesystem.Monitor.symlinks.DefaultMonitor

        Description

          Monitoring information for a single filesystem path.

          With support for expansion of symbolic links.

        See also

          monitor()

        Method attr_changed

          `protected void attr_changed(string path, Stdio.Stat st)`

        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

          `protected void call_callback(function(string, mixed ... :void) cb, string path, Stdio.Stat|void st)`

        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

          `void check_for_release(int mask, int flags)`

        Description

          Check if this monitor should be removed automatically.

        Method check_symlink

          `protected void check_symlink(string path, Stdio.Stat st, int|void inhibit_notify)`

        Description

          Check whether a symlink has changed.

        Method file_created

          `protected void file_created(string path, Stdio.Stat st)`

        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

          `protected void file_deleted(string path, Stdio.Stat old_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

          `protected void file_exists(string path, Stdio.Stat st)`

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

        Inherit DefaultMonitor

          inherit basic::DefaultMonitor : DefaultMonitor

        Description

          Based on Filesystem.Monitor.basic.DefaultMonitor.

        Method low_call_callback

          `void low_call_callback(function(string, mixed ... :void) cb, mapping(string:int) state, mapping(string:string) symlink_targets, string path, Stdio.Stat|void st, string|void symlink)`

        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

          `protected void monitor(string path, int flags, int max_dir_interval, int file_interval_factor, int stable_time)`

        Description

          Called to create a sub monitor.

        Method stable_data_change

          `protected void stable_data_change(string path, Stdio.Stat st)`

        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

          `protected bool status_change(Stdio.Stat old_st, Stdio.Stat st, int orig_flags, int flags)`

        Description

          Called when the status has changed for an existing file.

        Variable symlinks

          `int Filesystem.Monitor.symlinks.DefaultMonitor.symlinks`

        Description

          Mask of symlink ids that can reach this monitor.

        Method zap_symlink

          `protected void zap_symlink(string path)`

        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

      `constant int Filesystem.Tar.EXTRACT_CHOWN`

    Description

      Set owning user and group from the tar records.

    Constant EXTRACT_ERR_ON_UNKNOWN

      `constant int 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

      `constant int 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

      `constant int Filesystem.Tar.EXTRACT_SKIP_MODE`

    Description

      Don't set any permission bits from the tar records.

    Constant EXTRACT_SKIP_MTIME

      `constant int 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

        `void extract(string src_dir, string dest_dir, void|string|function(string, Filesystem.Stat:int|string) filter, void|int flags)`

      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

      Method chmod

        `void chmod(string filename, int|string mode)`

      FIXME

        Not implemented yet.

      Method chown

        `void chown(string filename, int|object owner, int|object group)`

      FIXME

        Not implemented yet.

      Method create

        `Filesystem.Tar._TarFS Filesystem.Tar._TarFS(_Tar _tar, string _wd, string _root, Filesystem.Base _parent)`

      Inherit System

        inherit Filesystem.System : System

      Method rm

        `int rm(string filename)`

      FIXME

        Not implemented yet.

    CLASS Filesystem.Tar.`()

      Method create

        `Filesystem.Tar.`() Filesystem.Tar.`()(string filename, void|Filesystem.Base parent, void|object file)`

      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.

      Inherit _TarFS

        inherit _TarFS : _TarFS

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"

  Method run

    `void run(Operations handler, 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 constant int Fuse.Operations.DT_BLK`

    Description

      Block special directory entry

    Constant DT_CHR

      `final constant int Fuse.Operations.DT_CHR`

    Description

      Character special directory entry

    Constant DT_DIR

      `final constant int Fuse.Operations.DT_DIR`

    Description

      Directory directory entry

    Constant DT_FIFO

      `final constant int Fuse.Operations.DT_FIFO`

    Description

      FIFO directory entry

    Constant DT_LNK

      `final constant int Fuse.Operations.DT_LNK`

    Description

      Symlink directory entry

    Constant DT_REG

      `final constant int Fuse.Operations.DT_REG`

    Description

      Normal file directory entry

    Constant DT_SOCK

      `final constant int Fuse.Operations.DT_SOCK`

    Description

      Socket directory entry

    Constant DT_UNKNOWN

      `final constant int 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 constant int Fuse.Operations.O_ACCMODE`

    Description

      Mask for read/write/rdwr

    Constant O_APPEND

      `final constant int Fuse.Operations.O_APPEND`

    Description

      Open for append

    Constant O_RDONLY

      `final constant int Fuse.Operations.O_RDONLY`

    Description

      Open read only

    Constant O_RDWR

      `final constant int Fuse.Operations.O_RDWR`

    Description

      Open read/write only

    Constant O_WRONLY

      `final constant int Fuse.Operations.O_WRONLY`

    Description

      Open write only

    Method access

      `int access(string path, int mode)`

    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

      `int chmod(string path, int mode)`

    Description

      Change the permission of a file or directory

    Returns

      errno or 0

    Method chown

      `int chown(string path, int uid, int gid)`

    Description

      Change the owner of a file or directory

    Returns

      errno or 0

    Method creat

      `int creat(string path, int mode, int flag)`

    Description

      Create and open or just open the given path

    Method flush

      `int flush(string path, int flags)`

    Description

      Write unwritten data.

    Method fsync

      `int fsync(string path, int datasync)`

    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(string path)`

    Description

      Stat a file.

    Note

      This function is required.

    Returns

      A Stdio.Stat object or an errno.

    Method getxattr

      `string getxattr(string path, string name)`

    Description

      Get the extended attribute name on path

    Method link

      `int link(string source, string destination)`

    Description

      Create a hard link from source to destination.

    Returns

      errno or 0

    Method listxattr

      `array(string)|int listxattr(string path)`

    Description

      Return a list of all available extended attributes on path

    Method lock

      `mapping(string:int)|int lock(string path, int mode, 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

      `int mkdir(string path, int mode)`

    Description

      Create a directory.

    Returns

      errno or 0

    Method mknod

      `int mknod(string path, int mode, int rdev)`

    Description

      Create a node (file, device special, or named pipe). See man 2 mknod

    Returns

      errno or 0

    Method open

      `int open(string path, int mode)`

    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(string path, int len, int offset)`

    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

      `int readdir(string path, 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(string path)`

    Description

      Read a symlink.

    Returns

      The symlink contents or errno

    Method release

      `int release(string path)`

    Description

      The inverse of open.

    Note

      The file might very well be openend multiple times. Keep reference counts.

    Method removexattr

      `int removexattr(string path, string name)`

    Description

      Remove the extended attribute name from path

    Method rename

      `int rename(string source, string destination)`

    Description

      Rename source to destination.

    Returns

      errno or 0

    Method rmdir

      `int rmdir(string path)`

    Description

      Remove a directory

    Returns

      errno or 0

    Method setxattr

      `int setxattr(string path, string name, string value, int flags)`

    Description

      Set the extended attrbiute name on path to value

    Method statfs

      `mapping(string:int) statfs(string path)`

    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

      `int symlink(string source, string destination)`

    Description

      Create a symlink from source to destination.

    Returns

      errno or 0

    Method truncate

      `int truncate(string path, int new_length)`

    Description

      Shrink or enlarge a file

    Returns

      errno or 0

    Method unlink

      `int unlink(string path)`

    Description

      Remove a file

    Returns

      errno or 0

    Method utime

      `int utime(string path, int atime, int mtime)`

    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

      `int utimens(string path, int atime, int mtime)`

    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

      `int write(string path, string data, int offset)`

    Description

      Write data to the file. Should write all data.

    Returns

      errno or amount written (bytes)

Module GDK

  Description

    GDK wrapper module.

    This is a convenience module that is identical to either either the GDK2 or the GDK1 module depending on which (if any) of them is available.

  See also

    GDK1, GDK2

  Constant Atom

    `constant GDK.Atom`

Module GDK1

  Constant Atom

    `constant GDK1.Atom`

  CLASS GDK1.Bitmap

    Description

      A bitmap is a black and white pixmap. Most commonly used as masks for images, widgets and pixmaps.

      NOIMG

    Method create

      `GDK1.Bitmap GDK1.Bitmap(int|Image.Image xsize_or_image, int|void ysize, string|void bitmap)`

    Description

      Create a new GDK1.Bitmap object. Argument is either an Image.Image object, or {xsisze,ysize,xbitmapdata}.

    Method destroy

      `GDK1.Bitmap destroy()`

    Description

      Destructor. Destroys the bitmap. This will free the bitmap on the X-server.

    Inherit Drawable

      inherit GDK1.Drawable : Drawable

    Method ref

      `GDK1.Bitmap ref()`

    Description

      Add a reference

    Method unref

      `GDK1.Bitmap unref()`

    Description

      Remove a reference

  CLASS GDK1.Color

    Description

      The GDK1.Color object is used to represent a color. When you call GDK1.Color(r,g,b) the color will be allocated from the X-server. The constructor can return an exception if there are no more colors to allocate. NOIMG

    Method blue

      `int blue()`

    Description

      Returns the blue color component.

    Method create

      `GDK1.Color GDK1.Color(object|int color_or_r, int|void g, int|void b)`

    Description

      r g and b are in the range 0 to 255, inclusive. If color is specified, it should be an Image.Color object, and the only argument.

    Method destroy

      `GDK1.Color destroy()`

    Description

      Destroys the color object. Please note that this function does not free the color from the X-colormap (in case of pseudocolor) right now.

    Method green

      `int green()`

    Description

      Returns the green color component.

    Method image_color_object

      `Image.Color.Color image_color_object()`

    Description

      Return a Image.Color.Color instance. This gives better precision than the rgb function.

    Method pixel

      `int pixel()`

    Description

      Returns the pixel value of the color. See GDK1.Image->set_pixel.

    Method red

      `int red()`

    Description

      Returns the red color component.

    Method rgb

      `array rgb()`

    Description

      Returns the red green and blue color components as an array.

  CLASS GDK1.DragContext

    Description

      The drag context contains all information about the drag'n'drop connected to the signal to which it is an argument.

      NOIMG

    Method drag_abort

      `GDK1.DragContext drag_abort(int time)`

    Description

      Abort the drag

    Method drag_drop

      `GDK1.DragContext drag_drop(int time)`

    Method drag_finish

      `GDK1.DragContext drag_finish(int success, int del, int time)`

    Description

      If success is true, the drag succeded. If del is true, the source should be deleted. time is the current time.

    Method drag_set_icon_default

      `GDK1.DragContext drag_set_icon_default()`

    Description

      Use the default drag icon associated with the source widget.

    Method drag_set_icon_pixmap

      `GDK1.DragContext drag_set_icon_pixmap(GDK1.Pixmap p, GDK1.Bitmap b, int hot_x, int hot_y)`

    Description

      Set the drag pixmap, and optionally mask. The hot_x and hot_y coordinates will be the location of the mouse pointer, relative to the upper left corner of the pixmap.

    Method drag_set_icon_widget

      `GDK1.DragContext drag_set_icon_widget(GTK1.Widget widget, int hot_x, int hot_y)`

    Description

      Set the drag widget. This is a widget that will be shown, and then dragged around by the user during this drag.

    Method drag_status

      `GDK1.DragContext drag_status(int action, int time)`

    Description

      Setting action to -1 means use the suggested action

    Method drop_reply

      `GDK1.DragContext drop_reply(int ok, int time)`

    Method get_action

      `int get_action()`

    Description

      One of GDK_ACTION_ASK, GDK_ACTION_COPY, GDK_ACTION_DEFAULT, GDK_ACTION_LINK, GDK_ACTION_MOVE and GDK_ACTION_PRIVATE;

    Method get_actions

      `int get_actions()`

    Description

      A bitwise or of one or more of GDK_ACTION_ASK, GDK_ACTION_COPY, GDK_ACTION_DEFAULT, GDK_ACTION_LINK, GDK_ACTION_MOVE and GDK_ACTION_PRIVATE;

    Method get_is_source

      `int get_is_source()`

    Description

      Is this application the source?

    Method get_protocol

      `int get_protocol()`

    Description

      One of GDK_DRAG_PROTO_MOTIF, GDK_DRAG_PROTO_ROOTWIN and GDK_DRAG_PROTO_XDND

    Method get_source_widget

      `GTK1.Widget get_source_widget()`

    Description

      Return the drag source widget.

    Method get_start_time

      `int get_start_time()`

    Description

      The start time of this drag, as a unix time_t (seconds since 0:00 1/1 1970)

    Method get_suggested_action

      `int get_suggested_action()`

    Description

      One of GDK_ACTION_ASK, GDK_ACTION_COPY, GDK_ACTION_DEFAULT, GDK_ACTION_LINK, GDK_ACTION_MOVE and GDK_ACTION_PRIVATE;

  CLASS GDK1.Drawable

    Description

      The GDK1.Bitmap, GDK1.Window and GDK1.Pixmap classes are all GDK drawables.

      This means that you can use the same set of functions to draw in them.

      Pixmaps are offscreen drawables. They can be drawn upon with the standard drawing primitives, then copied to another drawable (such as a GDK1.Window) with window->draw_pixmap(), set as the background for a window or widget, or otherwise used to show graphics (in a W(Pixmap), as an example). The depth of a pixmap is the number of bits per pixels. Bitmaps are simply pixmaps with a depth of 1. (That is, they are monochrome bitmaps - each pixel can be either on or off).

      Bitmaps are mostly used as masks when drawing pixmaps, or as a shape for a GDK1.Window or a W(Widget)

    Method clear

      `GDK1.Drawable clear(int|void x, int|void y, int|void width, int|void height)`

    Description

      Either clears the rectangle defined by the arguments, of if no arguments are specified, the whole drawable.

    Method copy_area

      `GDK1.Drawable copy_area(GDK1.GC gc, int xdest, int ydest, GTK1.Widget source, int xsource, int ysource, int width, int height)`

    Description

      Copies the rectangle defined by xsource,ysource and width,height from the source drawable, and places the results at xdest,ydest in the drawable in which this function is called.

    Method draw_arc

      `GDK1.Drawable draw_arc(GDK1.GC gc, int filledp, int x1, int y1, int x2, int y2, int angle1, int angle2)`

    Description

      Draws a single circular or elliptical arc. Each arc is specified by a rectangle and two angles. The center of the circle or ellipse is the center of the rectangle, and the major and minor axes are specified by the width and height. Positive angles indicate counterclockwise motion, and negative angles indicate clockwise motion. If the magnitude of angle2 is greater than 360 degrees, it is truncated to 360 degrees.

    Method draw_bitmap

      `GDK1.Drawable draw_bitmap(GDK1.GC gc, GDK1.Bitmap bitmap, int xsrc, int ysrc, int xdest, int ydest, int width, int height)`

    Description

      Draw a GDK(Bitmap) in this drawable. NOTE: This drawable must be a bitmap as well. This will be fixed in GTK 1.3

    Method draw_image

      `GDK1.Drawable draw_image(GDK1.GC gc, GDK1.Image image, int xsrc, int ysrc, int xdest, int ydest, int width, int height)`

    Description

      Draw the rectangle specified by xsrc,ysrc+width,height from the GDK(Image) at xdest,ydest in the destination drawable

    Method draw_line

      `GDK1.Drawable draw_line(GDK1.GC gc, int x1, int y1, int x2, int y2)`

    Description

      img_begin w = GTK1.DrawingArea()->set_usize(100,100); delay: g = GDK1.GC(w)->set_foreground( GDK1.Color(255,0,0) ); delay: for(int x = 0; x<10; x++) w->draw_line(g,x*10,0,100-x*10,99); img_end

    Method draw_pixmap

      `GDK1.Drawable draw_pixmap(GDK1.GC gc, GDK1.Pixmap pixmap, int xsrc, int ysrc, int xdest, int ydest, int width, int height)`

    Description

      Draw the rectangle specified by xsrc,ysrc+width,height from the GDK(Pixmap) at xdest,ydest in the destination drawable

    Method draw_point

      `GDK1.Drawable draw_point(GDK1.GC gc, int x, int y)`

    Description

      img_begin w = GTK1.DrawingArea()->set_usize(10,10); delay: g = GDK1.GC(w)->set_foreground( GDK1.Color(255,0,0) ); delay: for(int x = 0; x<10; x++) w->draw_point(g, x, x); img_end

    Method draw_rectangle

      `GDK1.Drawable draw_rectangle(GDK1.GC gc, int filledp, int x1, int y1, int x2, int y2)`

    Description

      img_begin w = GTK1.DrawingArea()->set_usize(100,100); delay: g = GDK1.GC(w)->set_foreground( GDK1.Color(255,0,0) ); delay: for(int x = 0; x<10; x++) w->draw_rectangle(g,0,x*10,0,100-x*10,99); img_end img_begin w = GTK1.DrawingArea()->set_usize(100,100); delay: g = GDK1.GC(w); delay: for(int x = 0; x<30; x++) { delay: g->set_foreground(GDK1.Color(random(255),random(255),random(255)) ); delay: w->draw_rectangle(g,1,x*10,0,100-x*10,99); delay: } img_end

    Method draw_text

      `GDK1.Drawable draw_text(GDK1.GC gc, GDK1.Font font, int x, int y, string text, int forcewide)`

    Description

      y is used as the baseline for the text. If forcewide is true, the string will be expanded to a wide string even if it is not already one. This is useful when writing text using either unicode or some other 16 bit font.

    Method get_geometry

      `mapping get_geometry()`

    Description

      Get width, height position and depth of the drawable as a mapping.

      ([ "x":xpos, "y":ypos, "width":xsize, "height":ysize, "depth":bits_per_pixel ])

    Method xid

      `int xid()`

    Method xsize

      `int xsize()`

    Description

      Returns the width of the drawable specified in pixels

    Method ysize

      `int ysize()`

    Description

      Returns the height of the drawable specified in pixels

  CLASS GDK1.Event

    Method _index

      `protected mixed _index(string ind)`

    Method cast

      `(mapping)GDK1.Event()`

    Method destroy

      `GDK1.Event destroy()`

  CLASS GDK1.Font

    Description

      The GdkFont data type represents a font for drawing on the screen. These functions provide support for loading fonts, and also for determining the dimensions of characters and strings when drawn with a particular font.

      Fonts in X are specified by a X Logical Font Description. The following description is considerably simplified. For definitive information about XLFD's see the X reference documentation. A X Logical Font Description (XLFD) consists of a sequence of fields separated (and surrounded by) '-' characters. For example, Adobe Helvetica Bold 12 pt, has the full description: "-adobe-helvetica-bold-r-normal--12-120-75-75-p-70-iso8859-1"

      The fields in the XLFD are:

      Foundry | the company or organization where the font originated.
      Family | the font family (a group of related font designs).
      Weight | A name for the font's typographic weight For example, 'bold' or 'medium').
      Slant | The slant of the font. Common values are 'R' for Roman, 'I' for italoc, and 'O' for oblique.
      Set Width | A name for the width of the font. For example, 'normal' or 'condensed'.
      Add Style | Additional information to distinguish a font from other fonts of the same family.
      Pixel Size | The body size of the font in pixels.
      Point Size | The body size of the font in 10ths of a point. (A point is 1/72.27 inch)
      Resolution X | The horizontal resolution that the font was designed for.
      Resolution Y | The vertical resolution that the font was designed for .
      Spacing | The type of spacing for the font - can be 'p' for proportional, 'm' for monospaced or 'c' for charcell.
      Average Width | The average width of a glyph in the font. For monospaced and charcell fonts, all glyphs in the font have this width
      Charset Registry | The registration authority that owns the encoding for the font. Together with the Charset Encoding field, this defines the character set for the font.
      Charset Encoding | An identifier for the particular character set encoding.

      When specifying a font via a X logical Font Description, '*' can be used as a wildcard to match any portion of the XLFD. For instance, the above example could also be specified as "-*-helvetica-bold-r-normal--*-120-*-*-*-*-iso8859-1"

      It is generally a good idea to use wildcards for any portion of the XLFD that your program does not care about specifically, since that will improve the chances of finding a matching font.

    Method char_width

      `int char_width(int character)`

    Description

      Return the width, in pixels, of the specified character, if rendered with this font. The character can be between 0 and 65535, the character encoding is font specific.

    Method create

      `GDK1.Font GDK1.Font(string|void font_name)`

    Description

      Create a new font object. The string is the font XLFD.

    Method destroy

      `GDK1.Font destroy()`

    Description

      Free the font, called automatically by pike when the object is destroyed.

  CLASS GDK1.GC

    Description

      A GC, or Graphics Context, is used for most low-level drawing operation.

      As an example, the foreground color, background color and drawing function is stored in the GC.

      NOIMG

    Method copy

      `GDK1.GC copy(GDK1.GC source)`

    Description

      Copy all attributes from the source GC

    Method create

      `GDK1.GC GDK1.GC(GTK1.Widget context, mapping|void attributes)`

    Description

      The argument is a either a W(Widget) or a GDK(Drawable) in which the gc will be valid.

    Method destroy

      `GDK1.GC destroy()`

    Description

      Free the gc, called automatically by pike when the object is destroyed.

    Method get_values

      `mapping get_values()`

    Description

      Get all (or rather most) values from the GC.

    Method set_background

      `GDK1.GC set_background(GDK1.Color color)`

    Description

      Set the background to the specified GDK1.Color.

    Method set_clip_mask

      `GDK1.GC set_clip_mask(GDK1.Bitmap mask)`

    Description

      Set the clip mask to the specified GDK1.Bitmap

    Method set_clip_origin

      `GDK1.GC set_clip_origin(int x, int y)`

    Description

      Set the clip mask origin to the specified point.

    Method set_clip_rectangle

      `GDK1.GC set_clip_rectangle(GDK1.Rectangle rect)`

    Description

      Sets the clip mask for a graphics context from a rectangle. The clip mask is interpreted relative to the clip origin.

    Method set_clip_region

      `GDK1.GC set_clip_region(GDK1.Region rect)`

    Description

      Sets the clip mask for a graphics context from a region. The clip mask is interpreted relative to the clip origin.

    Method set_dashes

      `GDK1.GC set_dashes(int offset, array dashes)`

    Description

      Sets the way dashed-lines are drawn. Lines will be drawn with alternating on and off segments of the lengths specified in dashes. The manner in which the on and off segments are drawn is determined by the line_style value of the GC.

    Method set_fill

      `GDK1.GC set_fill(int fill)`

    Description

      Set the fill method to fill.

    Method set_font

      `GDK1.GC set_font(GDK1.Font font)`

    Description

      Set the font to the specified GDK1.Font.

    Method set_foreground

      `GDK1.GC set_foreground(GDK1.Color color)`

    Description

      Set the foreground to the specified GDK1.Color.

    Method set_function

      `GDK1.GC set_function(int fun)`

    Description

      Set the function to the specified one. One of GDK1.Xor, GDK1.Invert and GDK1.Copy.

    Method set_line_attributes

      `GDK1.GC set_line_attributes(int line_width, int line_style, int cap_style, int join_style)`

    Description

      Control how lines are drawn. line_style is one of GDK1.LineSolid, GDK1.LineOnOffDash and GDK1.LineDoubleDash. cap_style is one of GDK1.CapNotLast, GDK1.CapButt, GDK1.CapRound and GDK1.CapProjecting. join_style is one of GDK1.JoinMiter, GDK1.JoinRonud and GDK1.JoinBevel.

    Method set_stipple

      `GDK1.GC set_stipple(GDK1.Bitmap stipple)`

    Description

      Set the background type. Fill must be GDK_STIPPLED or GDK_OPAQUE_STIPPLED

    Method set_subwindow

      `GDK1.GC set_subwindow(int draw_on_subwindows)`

    Description

      If set, anything drawn with this GC will draw on subwindows as well as the window in which the drawing is done.

    Method set_tile

      `GDK1.GC set_tile(GDK1.Pixmap tile)`

    Description

      Set the background type. Fill must be GDK_TILED

    Method set_ts_origin

      `GDK1.GC set_ts_origin(int x, int y)`

    Description

      Set the origin when using tiles or stipples with the GC. The tile or stipple will be aligned such that the upper left corner of the tile or stipple will coincide with this point.

  CLASS GDK1.Image

    Description

      A gdk (low level) image. Mainly used for W(Image) objects.

      NOIMG

    Method create

      `GDK1.Image GDK1.Image(int|void fast_mode, Image.Image|void image)`

    Description

      Create a new GDK1.Image object. The firstargument is either 0, which indicates that you want a 'slow' image. If you use '1', you indicate that you want a 'fast' image. Fast images are stored in shared memory, and thus are not sent over any network. But please limit your usage of fast images, they use up a possibly limited system resource set. See the man page for shmget(2) for more information on the limits on shared segments on your system.

      A 'fast' image will automatically revert back to 'slow' mode if no shared memory is available.

      If the second argument is specified, it is the actual image data.

    Method destroy

      `GDK1.Image destroy()`

    Description

      Destructor. Destroys the image. Automatically called by pike when the object is destructed.

    Method get_pixel

      `int get_pixel(int x, int y)`

    Description

      Get the pixel value of a pixel as a X-pixel value. It is usualy not very easy to convert this value to a rgb triple. See get_pnm.

    Method get_pnm

      `string get_pnm()`

    Description

      Returns the data in the image as a pnm object. Currently, this is always a P6 (true color raw) image. This could change in the future. To get a pike image object do 'Image.PNM.decode( gdkimage->get_pnm() )'

    Method grab

      `GDK1.Image grab(GTK1.Widget widget, int xoffset, int yoffset, int width, int height)`

    Description

      Call this function to grab a portion of a widget (argument 1) to the image. Grabbing non-toplevel widgets may produce unexpected results. To get the size of a widget use -&gt;xsize() and -&gt;ysize(). To get the offset of the upper left corner of the widget, relative to it's X-window (this is what you want for the offset arguments), use -&gt;xoffset() and -&gt;yoffset().

    Method set

      `GDK1.Image set(Image.Image|int image_or_xsize, int|void ysize)`

    Description

      Call this to set this image to either the contents of a pike image or a blank image of a specified size.

    Method set_pixel

      `GDK1.Image set_pixel(int x, int y, int pixel)`

    Description

      Set the pixel value of a pixel. Please note that the pixel argument is a X-pixel value, which is not easily gotten from a RGB color. See get_pixel and set.

  CLASS GDK1.Pixmap

    Description

      This class creates a GDK1.Pixmap from either an GDK1.Image or Image.Image object (or a numeric ID, see your X-manual for XIDs). The GDK1.Pixmap object can be used in a lot of different GTK widgets. The most notable is the W(Pixmap) widget.

      NOIMG

    Method create

      `GDK1.Pixmap GDK1.Pixmap(int|object image)`

    Description

      Create a new GDK1.Pixmap object. Argument is a GDK1.Image object or a Image.Image object

    Method destroy

      `GDK1.Pixmap destroy()`

    Description

      Destructor. Destroys the pixmap.

    Inherit Drawable

      inherit GDK1.Drawable : Drawable

    Method ref

      `GDK1.Pixmap ref()`

    Method set

      `GDK1.Pixmap set(GDK1.Image image)`

    Description

      Argument is a GDK1.Image object or an Image.Image object. It is much faster to use an gdkImage object, especially one allocated in shared memory. This is only an issue if you are going to change the contents of the pixmap often, toggling between a small number of images.

    Method unref

      `GDK1.Pixmap unref()`

  CLASS GDK1.Rectangle

    Method cast

      `(mapping)GDK1.Rectangle()
      (array)GDK1.Rectangle()
      `

    Description

      Normally used like (mapping)rectangle or (array)rectangle.

    Method create

      `GDK1.Rectangle GDK1.Rectangle(int x, int y, int width, int height)`

    Description

      Create a new rectangle

      NOIMG

    Method destroy

      `GDK1.Rectangle destroy()`

    Method set

      `GDK1.Rectangle set(int x, int y, int width, int height)`

    Description

      Set the upper left corner and the size of the rectangle.

  CLASS GDK1.Region

    Method create

      `GDK1.Region GDK1.Region()`

    Description

      Create a new (empty) region

      NOIMG

    Method destroy

      `GDK1.Region destroy()`

    Method equal

      `int equal(GDK1.Region victim)`

    Description

      Return true if the region used as an argument is equal to the current region. Also available as a==b when a is a region.

    Method intersect

      `GDK1.Region intersect(GDK1.Region victim)`

    Description

      Computes the intersection of the given region and the region. Also available as region &amp; region

    Method offset

      `GDK1.Region offset(int dx, int dy)`

    Description

      Offset(move) the region by dx,dy pixels.

    Method point_in

      `int point_in(int x, int y)`

    Description

      Returns true if the given point resides in the given region

    Method rect_in

      `int rect_in(GDK1.Rectangle r)`

    Description

      Returns true if the given rectangle resides inside the given region

    Method shrink

      `GDK1.Region shrink(int dx, int dy)`

    Description

      reduces the size of a region by a specified amount. Positive values shrink the size of the region, and negative values expand the region.

    Method subtract

      `GDK1.Region subtract(GDK1.Region victim)`

    Description

      Computes the difference of the given region and the region. Also available as region - region

    Method union

      `GDK1.Region union(GDK1.Region victim)`

    Description

      Computes the union of the given rectangle or region and the region. Also available as region | rectangle, region | region, region + region and region + rectangle.

    Method xor

      `GDK1.Region xor(GDK1.Region victim)`

    Description

      Computes the exlusive or of the given region and the region. Also available as region ^ region

  CLASS GDK1.Window

    Description

      a GDK1.Window object.

      NOIMG

    Method change_property

      `GDK1.Window change_property(GDK1.Atom property, GDK1.Atom type, int mode, string data)`

    Description

      mode is one of GDK_PROP_MODE_APPEND, GDK_PROP_MODE_PREPEND and GDK_PROP_MODE_REPLACE

    Method children

      `array children()`

    Description

      Returns an array of GDK1.Window objects.

    Method create

      `GDK1.Window GDK1.Window(GDK1.Window parent, mapping|void attributes)`

    Description

      Not for non-experts. I promise.

    Method delete_property

      `GDK1.Window delete_property(GDK1.Atom a)`

    Method get_geometry

      `mapping get_geometry()`

    Description

      Returns ([ "x":xpos, "y":ypos, "width":width, "height":height, "depth":bits_per_pixel ])

    Method get_pointer

      `mapping get_pointer(int deviceid)`

    Description

      Get the position of the specified device in this window.

    Method get_property

      `mapping get_property(GDK1.Atom atom, int|void offset, int|void delete_when_done)`

    Description

      Returns the value (as a string) of the specified property. The arguments are:

      property: The property atom, as an example GDK1.Atom.__SWM_VROOT offset (optional): The starting offset, in elements delete_when_done (optional): If set, the property will be deleted when it has been fetched.

      Example usage: Find the 'virtual' root window (many window managers put large windows over the screen)

             GDK1.Window root = GTK1.root_window();
             array maybe=root->children()->
                         get_property(GDK1.Atom.__SWM_VROOT)-({0});
             if(sizeof(maybe))
               root=GDK1.Window( maybe[0]->data[0] );

    Inherit Drawable

      inherit GDK1.Drawable : Drawable

    Method is_viewable

      `int is_viewable()`

    Description

      Return 1 if the window is mapped.

    Method is_visible

      `int is_visible()`

    Description

      Return 1 if the window, or a part of the window, is visible right now.

    Method lower

      `GDK1.Window lower()`

    Description

      Lower this window if the window manager allows that.

    Method move_resize

      `GDK1.Window move_resize(int x, int y, int w, int h)`

    Description

      Move and resize the window in one call.

    Method raise

      `GDK1.Window raise()`

    Description

      Raise this window if the window manager allows that.

    Method set_background

      `GDK1.Window set_background(GDK1.Color to)`

    Description

      Set the background color or image. The argument is either a GDK1.Pixmap or a GDK1.Color object.

    Method set_bitmap_cursor

      `GDK1.Window set_bitmap_cursor(GDK1.Bitmap image, GDK1.Bitmap mask, GDK1.Color fg, GDK1.Color bg, int xhot, int yhot)`

    Description

      xhot,yhot are the locations of the x and y hotspot relative to the upper left corner of the cursor image.

    Method set_cursor

      `GDK1.Window set_cursor(int new_cursor)`

    Description

      Change the window cursor.<table border="0" cellpadding="3" cellspacing="0"> CURS(GDK1.Arrow) CURS(GDK1.BasedArrowDown) CURS(GDK1.BasedArrowUp) CURS(GDK1.Boat) CURS(GDK1.Bogosity) CURS(GDK1.BottomLeftCorner) CURS(GDK1.BottomRightCorner) CURS(GDK1.BottomSide) CURS(GDK1.BottomTee) CURS(GDK1.BoxSpiral) CURS(GDK1.CenterPtr) CURS(GDK1.Circle) CURS(GDK1.Clock) CURS(GDK1.CoffeeMug) CURS(GDK1.Cross) CURS(GDK1.CrossReverse) CURS(GDK1.Crosshair) CURS(GDK1.DiamondCross) CURS(GDK1.Dot) CURS(GDK1.Dotbox) CURS(GDK1.DoubleArrow) CURS(GDK1.DraftLarge) CURS(GDK1.DraftSmall) CURS(GDK1.DrapedBox) CURS(GDK1.Exchange) CURS(GDK1.Fleur) CURS(GDK1.Gobbler) CURS(GDK1.Gumby) CURS(GDK1.Hand1) CURS(GDK1.Hand2) CURS(GDK1.Heart) CURS(GDK1.Icon) CURS(GDK1.IronCross) CURS(GDK1.LeftPtr) CURS(GDK1.LeftSide) CURS(GDK1.LeftTee) CURS(GDK1.Leftbutton) CURS(GDK1.LlAngle) CURS(GDK1.LrAngle) CURS(GDK1.Man) CURS(GDK1.Middlebutton) CURS(GDK1.Mouse) CURS(GDK1.Pencil) CURS(GDK1.Pirate) CURS(GDK1.Plus) CURS(GDK1.QuestionArrow) CURS(GDK1.RightPtr) CURS(GDK1.RightSide) CURS(GDK1.RightTee) CURS(GDK1.Rightbutton) CURS(GDK1.RtlLogo) CURS(GDK1.Sailboat) CURS(GDK1.SbDownArrow) CURS(GDK1.SbHDoubleArrow) CURS(GDK1.SbLeftArrow) CURS(GDK1.SbRightArrow) CURS(GDK1.SbUpArrow) CURS(GDK1.SbVDoubleArrow) CURS(GDK1.Shuttle) CURS(GDK1.Sizing) CURS(GDK1.Spider) CURS(GDK1.Spraycan) CURS(GDK1.Star) CURS(GDK1.Target) CURS(GDK1.Tcross) CURS(GDK1.TopLeftArrow) CURS(GDK1.TopLeftCorner) CURS(GDK1.TopRightCorner) CURS(GDK1.TopSide) CURS(GDK1.TopTee) CURS(GDK1.Trek) CURS(GDK1.UlAngle) CURS(GDK1.Umbrella) CURS(GDK1.UrAngle) CURS(GDK1.Watch) CURS(GDK1.Xterm) </table>

    Method set_events

      `GDK1.Window set_events(int events)`

    Description

      events is a bitwise or of one or more of the following constants: GDK1.ExposureMask, GDK1.PointerMotionMask, GDK1.PointerMotion_HINTMask, GDK1.ButtonMotionMask, GDK1.Button1MotionMask, GDK1.Button2MotionMask, GDK1.Button3MotionMask, GDK1.ButtonPressMask, GDK1.ButtonReleaseMask, GDK1.KeyPressMask, GDK1.KeyReleaseMask, GDK1.EnterNotifyMask, GDK1.LeaveNotifyMask, GDK1.FocusChangeMask, GDK1.StructureMask, GDK1.PropertyChangeMask, GDK1.VisibilityNotifyMask, GDK1.ProximityInMask, GDK1.ProximityOutMask and GDK1.AllEventsMask

    Method set_icon

      `GDK1.Window set_icon(GDK1.Pixmap pixmap, GDK1.Bitmap mask, GDK1.Window window)`

    Description

      Set the icon to the specified image (with mask) or the specified GDK1.Window. It is up to the window manager to display the icon. Most window manager handles window and pixmap icons, but only a few can handle the mask argument. If you want a shaped icon, the only safe bet is a shaped window.

    Method set_icon_name

      `GDK1.Window set_icon_name(string name)`

    Description

      Set the icon name to the specified string.

    Method shape_combine_mask

      `GDK1.Window shape_combine_mask(GDK1.Bitmap mask, int xoffset, int yoffset)`

    Description

      Set the shape of the widget, or, rather, it's window, to that of the supplied bitmap.

  CLASS GDK1._Atom

    Description

      An X-atom. You most likely want to use GDK1.Atom.atom_name instead of GDK1._Atom(name).

    Method create

      `GDK1._Atom GDK1._Atom(string atom_name, int|void only_if_exists)`

    Description

      Create a new low-level atom. You should normally not call this function directly. Use GDK1.Atom[name] instead of GDK1._Atom(name,0).

    Method get_name

      `string get_name()`

    Description

      Returns the name of the atom.

Module GDK2

  Constant Atom

    `constant GDK2.Atom`

Module GLUE

  Description

    GL Universal Environment

  Method PushPop

    `void PushPop(function(:void) f)`

  Description

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

  Example

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

  Method add_reinit_callback

    `void add_reinit_callback(function(void:void) f)`

  Description

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

  See also

    remove_reinit_callback

  Method allocate_light

    `int allocate_light()`

  Description

    Allocate a hardwareaccelerated lightsource from OpenGL.

  Returns

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

  See also

    free_light

  Method debug_stuff

    `mapping(string:mixed) debug_stuff()`

  Description

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

  Method draw_box

    `void draw_box(float x0, float y0, float x1, float y1, array(Image.Color.Color)|Image.Color.Color c, void|array(float)|float a)`

  Description

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

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

  Method draw_line

    `void draw_line(float x0, float y0, float x1, float y1, Image.Color.Color c, void|float a)`
    `void draw_line(float x0, float y0, float z0, float x1, float y1, float z1, Image.Color.Color c, void|float a)`

  Method draw_obox

    `void draw_obox(float x0, float y0, float x1, float y1, array(Image.Color.Color)|Image.Color.Color c, void|array(float)|float a)`

  Description

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

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

  Method draw_polygon

    `void draw_polygon(array(float) coords, Image.Color.Color c, float a)`

  Method free_light

    `void free_light(int l)`

  Description

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

  Parameter `l`

    Id which has been allocated using allocate_light.

  See also

    allocate_light

  Method get_all_lists

    `array(List) get_all_lists()`

  Description

    Returns all defined lists. Only available on Windows.

  Method get_all_textures

    `array(BaseTexture) get_all_textures()`

  Description

    Returns a list of all current textures.

  Method get_aspect

    `float get_aspect()`

  Description

    Returns the screen aspect.

  See also

    set_aspect

  Method get_depth

    `int get_depth()`

  Description

    Returns the current color depth.

  See also

    set_depth

  Method get_drivers

    `array(string) get_drivers()`

  Description

    Returns the name of the available drivers.

  See also

    init

  Method get_gl_flags

    `int get_gl_flags()`

  Description

    Returns the GL flags currently used.

  See also

    set_gl_flags

  Method get_screen_mode

    `bool get_screen_mode()`

  Description

    Returns 1 if in fullscreen mode, otherwise 0.

  See also

    toggle_fullscreen

  Method get_texture_mem_usage

    `int get_texture_mem_usage()`

  Description

    Returns the number of bytes used by the textures.

  Method has_extension

    `bool has_extension(string ext)`

  Description

    Checks if the GL extension ext is currently supported.

  Method hide_cursor

    `void hide_cursor()`

  Description

    Hide the mouse cursor.

  Method init

    `void init(void|mapping(string:mixed) options)`

  Description

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

  Throws

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

  Parameter `options`

    `"driver_names" : string|array(string)` | The name of a driver or a list of drivers to try, in given order. If no driver name is given, the list given by get_drivers is used.
    `"event_callback" : function(.Events.Event:void)` | This callback is called with a Events.Event object whenever an event is trapped by the driver. If no event callback is given, a callback that calls `exit(0)` on Escape and Exit events is used.
    `"resize_callback" : function(float, bool:void)` | This callback is called with the aspect whenever the drawing area is resized, either by an event or explicitly by the program.
    `"fullscreen" : bool` | Set fullscreen/window mode. 1 is fullscreen, 0 is window. Defaults to fullscreen.
    `"resolution" : array(int)` | Sets the resolution of the drawing area. Defaults to ({ 800, 600 }).
    `"aspect" : float` | Sets the aspect of the drawing area. Defaults to 1.333333 (4:3).
    `"depth" : int` | Sets the color depth of the drawing area. Defaults to 32.
    `"title" : string` | Sets the window title to this string.
    `"icon_title" : string` | Sets the icon title to this string.
    `"fast_mipmap" : bool` | Use GL_NEAREST_MIMAP_NEAREST instead of GL_LINEAR_MIPMAP_LINEAR, which also is the default.
    `"rotation" : float` | The rotation in z-axis of the drawing field.
    `"mirror" : string` | Mirroring in x and/or y axis.

  See also

    get_drivers

  Method make_rect_texture

    `BaseTexture make_rect_texture(mapping|Image.Image image, string|void name)`

  Description

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

  See also

    make_texture

  Method make_texture

    `BaseTexture make_texture(mapping|Image.Image image, string|void name)`

  Description

    Create a texture. Mainly here for symetry with make_rect_texture

  See also

    Texture, make_rect_texture

  Method mirror_screen

    `void mirror_screen(string how)`

  Description

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

  Parameter `how`

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

  Method only_dynlists

    `bool only_dynlists()`

  Description

    Returns `1` if all defined lists are DynList lists.

  Method pushpop_depth

    `int(0..) pushpop_depth()`

  Description

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

  Method remove_reinit_callback

    `void remove_reinit_callback(function(void:void) f)`

  Description

    Removes a reinitialization callback.

  See also

    add_reinit_callback

  Method set_aspect

    `void set_aspect(float asp)`
    `void set_aspect(int w, int h)`

  Description

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

  See also

    get_aspect

  Method set_depth

    `void set_depth(int _depth)`

  Description

    Sets the color depth.

  See also

    get_depth

  Method set_gl_flags

    `void set_gl_flags(int _gl_flags)`

  Description

    Sets the GL flags.

  See also

    get_gl_flags

  Method set_resolution

    `void set_resolution(int w, int h)`

  Description

    Sets the resolution to wxh pixels.

  See also

    xsize, ysize

  Method set_screen_rotation

    `void set_screen_rotation(float deg)`

  Description

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

  Method show_cursor

    `void show_cursor()`

  Description

    Show the mouse cursor.

  Method swap_buffers

    `void swap_buffers()`

  Description

    Swap the drawing buffer and the viewing buffer.

  Method toggle_fullscreen

    `void toggle_fullscreen(void|bool _fullscreen)`

  Description

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

  See also

    get_screen_mode

  Method xsize
  Method ysize

    `int xsize()`
    `int ysize()`

  Description

    Returns the screen width/height.

  See also

    set_resolution

  CLASS GLUE.BaseDWIM

    Description

      A mixin class with a dwim create function.

    Method create

      `GLUE.BaseDWIM GLUE.BaseDWIM(mixed ... args)`

    Description

      This create function has the following heuristic:

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

      `"image" : Image.Image` | The texture image.
      `"xsize" : int` | The image dimensions. If not provided, the dimensions of the `"image"` member will be used.
      `"ysize" : int`
      `"height" : int`
      `"width" : int`
      `"alpha" : int` | The alpha mode.
      `"mipmap" : bool` | Should the texture be mipmapped or not.
      `"clamp" : bool` | Should the texture be clamped or not.
      `"mode" : int` | The texture mode.
      `"debug" : string` | The debug name associated with this texture.

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

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

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

  CLASS GLUE.BaseTexture

    Description

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

    Method _sizeof

      `int sizeof( GLUE.BaseTexture arg )`

    Description

      Returns the size of memory allocated by the texture.

    Method `>

      `bool res = GLUE.BaseTexture() > x`

    Description

      Textures can be sorted according to texture id.

    Method clear

      `void clear()`

    Description

      Clears the texture.

    Method construct

      `void construct(int width, int height, int _alpha, mapping|void imgs, int(2bit)|void flags, int|void _mode, string|void debug_text)`

    Description

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

    Parameter `_alpha`

      The alpha mode the texture is operating in.

      `0` | RGB
      `1` | RGBA
      `2` | ALPHA
      `3` | LUM
      `4` | LUM+ALPHA

    Parameter `_mode`

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

    Parameter `debug_text`

      A string that can be used to identify this texture.

    Method coords

      `void coords(float x, float y)`

    Description

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

    Method create

      `GLUE.BaseTexture GLUE.BaseTexture(mixed ... args)`

    Description

      Calls construct with args.

    Method create_texture

      `void create_texture(mapping|void imgs, int(2bit)|void flags, int|void width, int|void height)`

    Description

      Actually creates the texture.

    Parameter `imgs`

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

      `"image" : Image.Image` | The actual image to be used as texture. It will be cropped/padded to meet the dimensions given in width and height.
      `"alpha" : Image.Image` | Optional image to be used as alpha channel, depending on the alpha value given to create/construct.

    Parameter `flags`

      If `1`, the texture will be mipmapped. If bit 1 (`2`) is set, texture will not be wrapped but clamped.

    Parameter `width`
    Parameter `height`

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

    See also

      resize

    Variable debug

      `string GLUE.BaseTexture.debug`

    Description

      A string to identify the texture.

    Method destroy

      `protected void destroy()`

    Description

      Properly deallocates the texture.

    Method draw

      `void draw(float x, float y, float z, float w, float h)`

    Description

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

    Method draw_region

      `void draw_region(float x, float y, float z, float w, float h, float s0, float q0, float ss, float qs)`

    Description

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

    Method get_id

      `int get_id()`

    Description

      Returns the id of this texture.

    Variable width_u
    Variable height_u

      `float GLUE.BaseTexture.width_u`
      `float GLUE.BaseTexture.height_u`

    Description

      Utilization in percent.

    Variable i_width
    Variable i_height

      `int GLUE.BaseTexture.i_width`
      `int GLUE.BaseTexture.i_height`

    Description

      Image dimensions

    Method make_mipmap

      `void make_mipmap(mapping imgs, int|void imode, int|void dx, int|void dy)`

    Description

      Renders a mipmap of the image/partial image imgs.

    Parameter `imgs`

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

    Parameter `imode`

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

    Parameter `dx`
    Parameter `dy`

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

    See also

      create_texture

    Method paste

      `void paste(Image.Image i, Image.Image a, int x, int y)`

    Description

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

    Method resize

      `void resize(int width, int height, mapping|void imgs, int(2bit)|void flags, bool|void nocreate)`

    Description

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

    See also

      construct

    Method set_image_data

      `void set_image_data(Image.Image|mapping(string:mixed) data, bool|void no_resize)`

    Description

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

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

    Parameter `data`

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

      `"rgb" : Image.Image` | Texture image data.
      `"alpha" : Image.Image` | Optional alpha channel.
      `"luminance" : Image.Image` | Optional luminance channel.

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

      `"mem" : System.Memory` | The shared memory segment.
      `"mem_w" : int` | The width and height of the memory segment.
      `"mem_h" : int`
      `"mem_format" : int` | The format of the memory segment, e.g. GL.GL_RGB.
      `"mem_type" : int` | The low level format of the memory segment, e.g. GL.GL_UNSIGNED_BYTE.

    Variable t_width
    Variable t_height

      `int GLUE.BaseTexture.t_width`
      `int GLUE.BaseTexture.t_height`

    Description

      Texture dimensions

    Variable texture_type

      `int GLUE.BaseTexture.texture_type`

    Description

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

    Method use

      `void use()`

    Description

      Use the generated texture (GL.glBindTexture).

  CLASS GLUE.DynList

    Description

      A displaylist that is generated on demand.

    Note

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

    Method call

      `void call()`

    Description

      Call the displaylist, ie draw it.

    Method create

      `GLUE.DynList GLUE.DynList(function(:void)|void f)`

    Description

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

    Parameter `f`

      Function which contains the GL commands that generates the displaylist.

    Inherit List

      inherit List : List

    Method init

      `void init()`

    Description

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

    Method modeswitch

      `void modeswitch()`

    Description

      Called by videodriver when a video mode change occurs.

    Method set_generator

      `void set_generator(function(:void) _generator)`

    Description

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

  CLASS GLUE.Font

    Description

      A font.

    Method create

      `GLUE.Font GLUE.Font(Image.Fonts.Font f, float|void _scale_width, float|void _scale_spacing)`

    Method get_character

      `array(int|BaseTexture|Region) get_character(int c)`

    Description

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

    Note

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

    Method text_extents

      `array(float) text_extents(string text, float h)`

    Description

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

    Method write

      `array(List|float) write(string text, float h, void|float|Region roi, string|void align)`

    Description

      Create a display list that writes text.

    Parameter `text`

      The text to write.

    Parameter `h`

      The font height

    Parameter `roi`

      The region, if supplied, to restrict writing to.

    Parameter `align`

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

    Method write_now

      `array(float) write_now(string text, float h, void|float|Region roi, string|void align)`

    Description

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

    CLASS GLUE.Font.Character

      Description

        A character to draw.

      Method draw

        `void draw()`

      Description

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

      Inherit Region

        inherit Region : Region

      Variable pos

        `Region GLUE.Font.Character.pos`

      Description

        Character position in texture txt.

      Method set_data

        `void set_data(Region _pos, BaseTexture _txt, void|Region _slice)`

      Description

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

      Variable slice

        `Region GLUE.Font.Character.slice`

      Description

        Slice of character to be shown.

      Variable txt

        `BaseTexture GLUE.Font.Character.txt`

      Description

        Texture holding the character.

  CLASS GLUE.List

    Description

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

    See also

      DynList

    Method `>

      `bool res = GLUE.List() > x`

    Description

      List objects can be sorted according to list id.

    See also

      get_id

    Method begin

      `void begin(bool|void run)`

    Description

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

    See also

      end, compile

    Method call

      `void call()`

    Description

      Execute the commands in the list.

    Method compile

      `void compile(function(:void) f)`

    Description

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

    See also

      begin

    Method create

      `GLUE.List GLUE.List(void|function(:void) f)`

    Description

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

    See also

      call

    Example

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

    Method destroy

      `protected void destroy()`

    Description

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

    Method end

      `void end()`

    Description

      Finish the list definition.

    See also

      begin, compile

    Method get_id

      `int get_id()`

    Description

      Returns this lists' id.

  CLASS GLUE.RectangleDWIMTexture

    Description

      Convenience version of the RectangleTexture class.

    Inherit BaseDWIM

      inherit BaseDWIM : BaseDWIM

    Description

      Convenience methods

    Inherit RectangleTexture

      inherit RectangleTexture : RectangleTexture

    Description

      Texture base

  CLASS GLUE.RectangleTexture

    Description

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

    Inherit BaseTexture

      inherit BaseTexture : BaseTexture

  CLASS GLUE.Region

    Description

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

    Method `&

      `Region res = GLUE.Region() & R`

    Description

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

    Method create

      `GLUE.Region GLUE.Region(float x, float y, float w, float h)`

    Variable x
    Variable y
    Variable w
    Variable h

      `float GLUE.Region.x`
      `float GLUE.Region.y`
      `float GLUE.Region.w`
      `float GLUE.Region.h`

    Method inside

      `bool inside(Region R)`

    Description

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

    Constant is_region

      `constant int GLUE.Region.is_region`

    Description

      All region objects have this constant.

    Method move

      `void move(float xp, float yp)`

    Description

      Move the region xp units right and yp units down.

    Method outside

      `bool outside(Region R)`

    Description

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

    Method resize

      `void resize(float xs, float ys)`

    Description

      Make the region xs units wider and ys units higher.

  CLASS GLUE.SquareMesh

    Description

      A mesh of squares.

    Method create

      `GLUE.SquareMesh GLUE.SquareMesh(function(float, float:Math.Matrix) calculator)`

    Description

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

    Method draw

      `void draw()`

    Description

      Draw the mesh.

    Method recalculate

      `void recalculate()`

    Description

      Recalculate the mesh.

    Method set_lighting

      `void set_lighting(bool do_lighting)`

    Description

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

    Method set_size

      `void set_size(int x, int y)`

    Description

      Set the size of the mesh

    Method set_texture

      `void set_texture(BaseTexture tex)`

    Description

      Set a texture to be mapped on the mesh.

    Method surface_normal

      `Math.Matrix surface_normal(int x, int y)`

    Description

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

  CLASS GLUE.Texture

    Description

      Convenience version of the Texture class.

    Inherit BaseDWIM

      inherit BaseDWIM : BaseDWIM

    Description

      Convenience methods

    Inherit BaseTexture

      inherit BaseTexture : BaseTexture

    Description

      Texture base

  Module GLUE.Events

    Description

      GLUE Event abstraction.

    Constant BACKSPACE
    Constant DELETE
    Constant TAB
    Constant F1
    Constant F2
    Constant F3
    Constant F4
    Constant F5
    Constant F6
    Constant F7
    Constant F8
    Constant F9
    Constant F10
    Constant F11
    Constant F12
    Constant ESCAPE
    Constant UP
    Constant DOWN
    Constant LEFT
    Constant RIGHT
    Constant PGUP
    Constant PGDWN
    Constant ENTER
    Constant SPACE
    Constant HOME
    Constant END
    Constant PAUSE
    Constant INSERT
    Constant SCROLL_LOCK
    Constant SYS_REQ
    Constant PRINT_SCRN
    Constant CAPSLOCK
    Constant MENU
    Constant NUMLOCK
    Constant A
    Constant B
    Constant C
    Constant D
    Constant E
    Constant F
    Constant G
    Constant H
    Constant I
    Constant J
    Constant K
    Constant L
    Constant M
    Constant N
    Constant O
    Constant P
    Constant Q
    Constant R
    Constant S
    Constant T
    Constant U
    Constant V
    Constant W
    Constant X
    Constant Y
    Constant Z

      `constant int GLUE.Events.BACKSPACE`
      `constant int GLUE.Events.DELETE`
      `constant int GLUE.Events.TAB`
      `constant int GLUE.Events.F1`
      `constant GLUE.Events.F2`
      `constant GLUE.Events.F3`
      `constant GLUE.Events.F4`
      `constant GLUE.Events.F5`
      `constant GLUE.Events.F6`
      `constant GLUE.Events.F7`
      `constant GLUE.Events.F8`
      `constant GLUE.Events.F9`
      `constant GLUE.Events.F10`
      `constant GLUE.Events.F11`
      `constant GLUE.Events.F12`
      `constant int GLUE.Events.ESCAPE`
      `constant int GLUE.Events.UP`
      `constant int GLUE.Events.DOWN`
      `constant int GLUE.Events.LEFT`
      `constant int GLUE.Events.RIGHT`
      `constant int GLUE.Events.PGUP`
      `constant int GLUE.Events.PGDWN`
      `constant int GLUE.Events.ENTER`
      `constant int GLUE.Events.SPACE`
      `constant int GLUE.Events.HOME`
      `constant int GLUE.Events.END`
      `constant int GLUE.Events.PAUSE`
      `constant int GLUE.Events.INSERT`
      `constant int GLUE.Events.SCROLL_LOCK`
      `constant int GLUE.Events.SYS_REQ`
      `constant int GLUE.Events.PRINT_SCRN`
      `constant int GLUE.Events.CAPSLOCK`
      `constant int GLUE.Events.MENU`
      `constant int GLUE.Events.NUMLOCK`
      `constant int GLUE.Events.A`
      `constant int GLUE.Events.B`
      `constant int GLUE.Events.C`
      `constant int GLUE.Events.D`
      `constant int GLUE.Events.E`
      `constant int GLUE.Events.F`
      `constant int GLUE.Events.G`
      `constant int GLUE.Events.H`
      `constant int GLUE.Events.I`
      `constant int GLUE.Events.J`
      `constant int GLUE.Events.K`
      `constant int GLUE.Events.L`
      `constant int GLUE.Events.M`
      `constant int GLUE.Events.N`
      `constant int GLUE.Events.O`
      `constant int GLUE.Events.P`
      `constant int GLUE.Events.Q`
      `constant int GLUE.Events.R`
      `constant int GLUE.Events.S`
      `constant int GLUE.Events.T`
      `constant int GLUE.Events.U`
      `constant int GLUE.Events.V`
      `constant int GLUE.Events.W`
      `constant int GLUE.Events.X`
      `constant int GLUE.Events.Y`
      `constant int GLUE.Events.Z`

    Description

      Numeric constant representing a key.

    Method ALT

      `Event ALT(int|Event X)`
      `array(Event) ALT(array(int|Event) X)`

    Description

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

    Constant BUTTON_1
    Constant BUTTON_2
    Constant BUTTON_3
    Constant BUTTON_4
    Constant BUTTON_5

      `constant int GLUE.Events.BUTTON_1`
      `constant int GLUE.Events.BUTTON_2`
      `constant int GLUE.Events.BUTTON_3`
      `constant int GLUE.Events.BUTTON_4`
      `constant int GLUE.Events.BUTTON_5`

    Description

      Numeric constant representing a mouse button.

    Method CTRL

      `Event CTRL(int|Event X)`
      `array(Event) CTRL(array(int|Event) X)`

    Description

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

    Constant EXIT

      `constant int GLUE.Events.EXIT`

    Description

      Numeric constant representing an exit event.

    Constant KNOWN_MODIFIERS

      `constant GLUE.Events.KNOWN_MODIFIERS`

    Description

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

    Constant LSHIFT
    Constant RSHIFT
    Constant LCTRL
    Constant RCTRL
    Constant LALT
    Constant RALT

      `constant int GLUE.Events.LSHIFT`
      `constant int GLUE.Events.RSHIFT`
      `constant int GLUE.Events.LCTRL`
      `constant int GLUE.Events.RCTRL`
      `constant int GLUE.Events.LALT`
      `constant int GLUE.Events.RALT`

    Description

      Numeric constant representing a modifier key.

    Constant MODIFIERS

      `constant GLUE.Events.MODIFIERS`

    Description

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

    Constant MOUSE_UP
    Constant MOUSE_DOWN
    Constant MOUSE_LEFT
    Constant MOUSE_RIGHT
    Constant MOUSE_ABS

      `constant int GLUE.Events.MOUSE_UP`
      `constant int GLUE.Events.MOUSE_DOWN`
      `constant int GLUE.Events.MOUSE_LEFT`
      `constant int GLUE.Events.MOUSE_RIGHT`
      `constant int GLUE.Events.MOUSE_ABS`

    Description

      Numeric constant representing a mouse movement.

    Method SHFT

      `Event SHFT(int|Event X)`
      `array(Event) SHFT(array(int|Event) X)`

    Description

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

    Constant _ALT

      `constant int GLUE.Events._ALT`

    Description

      Integer constant representing alternate.

    Constant _CTRL

      `constant int GLUE.Events._CTRL`

    Description

      Integer constant representing control.

    Constant _SHFT

      `constant int GLUE.Events._SHFT`

    Description

      Integer constant representing shift.

    Method is_modifier

      `bool is_modifier(int k)`

    Description

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

    Constant key_names

      `constant GLUE.Events.key_names`

    Description

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

    CLASS GLUE.Events.Event

      Description

        Contains an event.

      Method create

        `GLUE.Events.Event GLUE.Events.Event(int|void _key, bool|void _press, string|void _data, int|void _modifiers, float|void pressure)`

      Method dup

        `this_program dup()`

      Description

        Returns a copy of this Event object.

      Variable press

        `bool GLUE.Events.Event.press`

      Description

        Press event or release event.

      Variable pressure

        `float GLUE.Events.Event.pressure`

      Description

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

Module GSSAPI

  Description

    This is pike glue for GSS-API ver 2 as specified in RFC 2743.

    GSS-API is used to authenticate users and servers, and optionally also to encrypt communication between them. The API is generic and can be used without any knowledge of the actual implementation of these security services, which is typically provided by the operating system.

    The most common implementation at the time of writing is Kerberos, which means that the main benefit of this API is to allow clients and servers to authenticate each other using Kerberos, thereby making single sign-on possible in a Kerberized environment.

    All functions in this module that wraps GSS-API routines might throw GSSAPI.Error, and by default they do for all such errors. Only in some special cases do they return when a GSS-API error has happened, and that is noted in the documentation.

  Constant INITIATE
  Constant ACCEPT
  Constant BOTH

    `constant int GSSAPI.INITIATE`
    `constant int GSSAPI.ACCEPT`
    `constant int GSSAPI.BOTH`

  Description

    Flags for indicating how a GSSAPI.Cred object may be used:

    INITIATE

      The credential can only be used to initiate security contexts (i.e. using GSSAPI.InitContext).

    ACCEPT

      The credential can only be used to accept security contexts (i.e. using GSSAPI.AcceptContext).

    BOTH

      The credential may be used both to initiate or accept security contexts.

  Constant DELEG_FLAG
  Constant MUTUAL_FLAG
  Constant REPLAY_FLAG
  Constant SEQUENCE_FLAG
  Constant CONF_FLAG
  Constant INTEG_FLAG
  Constant ANON_FLAG
  Constant PROT_READY_FLAG
  Constant TRANS_FLAG

    `constant int GSSAPI.DELEG_FLAG`
    `constant int GSSAPI.MUTUAL_FLAG`
    `constant int GSSAPI.REPLAY_FLAG`
    `constant int GSSAPI.SEQUENCE_FLAG`
    `constant int GSSAPI.CONF_FLAG`
    `constant int GSSAPI.INTEG_FLAG`
    `constant int GSSAPI.ANON_FLAG`
    `constant int GSSAPI.PROT_READY_FLAG`
    `constant int GSSAPI.TRANS_FLAG`

  Description

    Bitfield flags returned by e.g. GSSAPI.Context.services to denote various services that are available in the context.

    Brief descriptions of the flags:

    GSSAPI.DELEG_FLAG

      Delegation. See RFC 2743 section 1.2.9.

    GSSAPI.MUTUAL_FLAG

      Mutual authentication (actually, acceptor authentication). See RFC 2743 sections 1.1.1.3 and 1.2.5.

    GSSAPI.REPLAY_FLAG

      Per-message replay detection. See RFC 2743 section 1.2.3.

    GSSAPI.SEQUENCE_FLAG

      Per-message sequencing. See RFC 2743 section 1.2.3.

    GSSAPI.CONF_FLAG

      Per-message confidentiality. See RFC 2743 section 1.2.2.

    GSSAPI.INTEG_FLAG

      Per-message integrity. See RFC 2743 section 1.2.2.

    GSSAPI.ANON_FLAG

      Anonymous authentication. See RFC 2743 section 1.2.5.

    GSSAPI.PROT_READY_FLAG

      Might be set before the context establishment has finished, to denote that per-message protection already is available. See RFC 2743 section 1.2.7. Is always set in GSSAPI.Context and derived classes when the context is established.

    GSSAPI.TRANS_FLAG

      The context can be transferred between processes using GSSAPI.Context.export. See RFC 2743 section 1.2.10.

  Constant BAD_MECH
  Constant BAD_NAME
  Constant BAD_NAMETYPE
  Constant BAD_BINDINGS
  Constant BAD_STATUS
  Constant BAD_SIG
  Constant NO_CRED
  Constant NO_CONTEXT
  Constant DEFECTIVE_TOKEN
  Constant DEFECTIVE_CREDENTIAL
  Constant CREDENTIALS_EXPIRED
  Constant CONTEXT_EXPIRED
  Constant FAILURE
  Constant BAD_QOP
  Constant UNAUTHORIZED
  Constant UNAVAILABLE
  Constant DUPLICATE_ELEMENT
  Constant NAME_NOT_MN

    `constant int GSSAPI.BAD_MECH`
    `constant int GSSAPI.BAD_NAME`
    `constant int GSSAPI.BAD_NAMETYPE`
    `constant int GSSAPI.BAD_BINDINGS`
    `constant int GSSAPI.BAD_STATUS`
    `constant int GSSAPI.BAD_SIG`
    `constant int GSSAPI.NO_CRED`
    `constant int GSSAPI.NO_CONTEXT`
    `constant int GSSAPI.DEFECTIVE_TOKEN`
    `constant int GSSAPI.DEFECTIVE_CREDENTIAL`
    `constant int GSSAPI.CREDENTIALS_EXPIRED`
    `constant int GSSAPI.CONTEXT_EXPIRED`
    `constant int GSSAPI.FAILURE`
    `constant int GSSAPI.BAD_QOP`
    `constant int GSSAPI.UNAUTHORIZED`
    `constant int GSSAPI.UNAVAILABLE`
    `constant int GSSAPI.DUPLICATE_ELEMENT`
    `constant int GSSAPI.NAME_NOT_MN`

  Description

    Constants for routine errors in major status codes like GSSAPI.Error.major_status. See RFC 2743 section 1.2.1.1. Note that major status codes have to be masked with GSSAPI.ERROR_MASK before comparison with these.

    Brief descriptions of the flags:

    GSSAPI.BAD_BINDINGS

      Channel binding mismatch.

    GSSAPI.BAD_MECH

      Unsupported mechanism requested.

    GSSAPI.BAD_NAME

      Invalid name provided.

    GSSAPI.BAD_NAMETYPE

      Name of unsupported type provided.

    GSSAPI.BAD_STATUS

      Invalid input status selector.

    GSSAPI.BAD_MIC

      Token had invalid integrity check.

    GSSAPI.CONTEXT_EXPIRED

      Specified security context expired.

    GSSAPI.CREDENTIALS_EXPIRED

      Expired credentials detected.

    GSSAPI.DEFECTIVE_CREDENTIAL

      Defective credential detected.

    GSSAPI.DEFECTIVE_TOKEN

      Defective token detected.

    GSSAPI.FAILURE

      Failure, unspecified at GSS-API level. GSSAPI.Error.minor_status should provide further details.

    GSSAPI.NO_CONTEXT

      No valid security context specified.

    GSSAPI.NO_CRED

      No valid credentials provided.

    GSSAPI.BAD_QOP

      Unsupported QOP value.

    GSSAPI.UNAUTHORIZED

      Operation unauthorized.

    GSSAPI.UNAVAILABLE

      Operation unavailable.

    GSSAPI.DUPLICATE_ELEMENT

      Duplicate credential element requested.

    GSSAPI.NAME_NOT_MN

      Name contains multi-mechanism elements.

  Constant CONTINUE_NEEDED
  Constant DUPLICATE_TOKEN
  Constant OLD_TOKEN
  Constant UNSEQ_TOKEN
  Constant GAP_TOKEN

    `constant int GSSAPI.CONTINUE_NEEDED`
    `constant int GSSAPI.DUPLICATE_TOKEN`
    `constant int GSSAPI.OLD_TOKEN`
    `constant int GSSAPI.UNSEQ_TOKEN`
    `constant int GSSAPI.GAP_TOKEN`

  Description

    Bitfield flags for informatory codes in major status codes like GSSAPI.Error.major_status. See RFC 2743 section 1.2.1.1. Any combination of these might optionally be combined with one routine error constant to form a major status code.

    Brief descriptions of the flags:

    GSSAPI.CONTINUE_NEEDED

      Continuation call to routine required.

    GSSAPI.DUPLICATE_TOKEN

      Duplicate per-message token detected.

    GSSAPI.OLD_TOKEN

      Timed-out per-message token detected.

    GSSAPI.UNSEQ_TOKEN

      Reordered (early) per-message token detected.

    GSSAPI.GAP_TOKEN

      Skipped predecessor token(s) detected.

  Constant ERROR_MASK

    `constant int GSSAPI.ERROR_MASK`

  Description

    Bitfield mask for the routine error part of major status codes like GSSAPI.Error.major_status. After applying this mask, the status values may be compared to any of the routine error constants.

  Constant INFO_MASK

    `constant int GSSAPI.INFO_MASK`

  Description

    Bitfield mask for the informatory part of major status codes like GSSAPI.Error.major_status.

  Constant NT_HOSTBASED_SERVICE
  Constant NT_USER_NAME
  Constant NT_MACHINE_UID_NAME
  Constant NT_STRING_UID_NAME
  Constant NT_ANONYMOUS
  Constant NT_EXPORT_NAME
  Constant KRB5_NT_PRINCIPAL_NAME

    `constant string GSSAPI.NT_HOSTBASED_SERVICE`
    `constant string GSSAPI.NT_USER_NAME`
    `constant string GSSAPI.NT_MACHINE_UID_NAME`
    `constant string GSSAPI.NT_STRING_UID_NAME`
    `constant string GSSAPI.NT_ANONYMOUS`
    `constant string GSSAPI.NT_EXPORT_NAME`
    `constant string GSSAPI.KRB5_NT_PRINCIPAL_NAME`

  Description

    OIDs on dotted-decimal form for the GSS-API mechanism-independent name types, and some selected mechanism-specific ones:

    NT_HOSTBASED_SERVICE

      Name type for a service associated with a host computer. The syntax is `service@hostname` where the `@hostname` part may be omitted for the local host. See RFC 2743 section 4.1.

    NT_USER_NAME

      Name type for a named user on a local system. The syntax is `username`. See RFC 2743 section 4.2.

    NT_MACHINE_UID_NAME

      Name type for a numeric user identifier corresponding to a user on a local system. The string representing a name of this type should contain a locally-significant user ID, represented in host byte order. See RFC 2743 section 4.3.

    NT_STRING_UID_NAME

      Name type for a string of digits representing the numeric user identifier of a user on a local system. This name type is similar to the Machine UID Form, except that the buffer contains a string representing the user ID. See RFC 2743 section 4.4.

    NT_ANONYMOUS

      Name type to identify anonymous names. See RFC 2743 section 4.5.

    NT_EXPORT_NAME

      Name type for the Mechanism-Independent Exported Name Object type, which is the type of the names returned by GSSAPI.Name.export. See RFC 2743 section 4.7.

    KRB5_NT_PRINCIPAL_NAME

      Name type for a Kerberos principal. See RFC 1964 section 2.1.1.

  Method describe_services

    `string describe_services(int services)`

  Description

    Returns a string that compactly describes the given services, which is taken as a bitfield of `GSSAPI.*_FLAG` flags.

    The returned string contains capitalized names for the flags reminiscent of the GSSAPI.*_FLAG constants, separated by `"|"`.

  Method indicate_mechs

    `multiset(string) indicate_mechs()`

  Description

    Returns the OIDs for the available mechanism in the GSS-API implementation. The OIDs are returned on dotted-decimal form.

    This wraps `GSS_Indicate_mechs` according to RFC 2743 section 2.4.2.

  Method major_status_messages

    `array(string) major_status_messages(int major_status)`

  Description

    Given a major status code like GSSAPI.Error.major_status (or more commonly GSSAPI.Context.last_major_status in this case), returns an array containing messages for all the status values in it. The returned string(s) presumably don't end with linefeeds.

    This wraps `GSS_Display_status` according to RFC 2743 section 2.4.1.

  Method minor_status_messages

    `array(string) minor_status_messages(int minor_status, void|string mech)`

  Description

    Given a mechanism-specific minor status code like GSSAPI.Error.minor_status, returns an array containing messages for all the status values in it. The returned string(s) presumably don't end with linefeeds.

    This wraps `GSS_Display_status` according to RFC 2743 section 2.4.1.

  Parameter `minor_status`

    The mechanism-specific minor status.

  Parameter `mech`

    The mechanism that produced the status code. If this is zero or left out, a system default mechanism is used.

  Method names_for_mech

    `multiset(string) names_for_mech(string mech)`

  Description

    Returns the OIDs for the name types that the given mech supports. Both mech and the returned OID strings are on dotted-decimal form.

    This wraps `GSS_Inquire_names_for_mech` according to RFC 2743 section 2.4.12.

  CLASS GSSAPI.AcceptContext

    Description

      Variant of Context which is used on the acceptor side.

    Method accept

      `string accept(string remote_token)`

    Description

      Accepts a remotely initiated security context.

      This wraps `GSS_Accept_sec_context` according to RFC 2743 section 2.2.2.

      The underlying mechanism might require several tokens to be passed back and forth to establish the context. If is_established returns zero after a call to this function then the caller must wait for a token from the remote peer to feed as remote_token in another call to this function.

    Parameter `remote_token`

      A token from the remote peer, as returned by a call to GSSAPI.InitContext.init or some other `GSS_Init_sec_context` wrapper.

    Returns

      If a string is returned then it must be passed to the remote peer which will feed it to GSSAPI.InitContext.init or some other `GSS_Init_sec_context` wrapper. An empty string is never returned.

      Zero is returned if there is no token to send to the remote peer. Note that is_established might still return zero in that case, meaning more remote tokens are necessary.

    Note

      This function might block on network connections to remote authentication servers.

    Method create

      `GSSAPI.AcceptContext GSSAPI.AcceptContext(void|Cred cred, void|int required_services)`

    Description

      Creates a context for acceptor use. This function only accepts parameters to be used later during the accept call. If there are semantic problems with them, such as if the credentials are stale, then they will be signalled later by accept.

    Parameter `cred`

      Credentials for the identity this context claims. The credentials for the default principal (if any) is used if zero or left out.

    Parameter `required_services`

      Bitfield of `GSSAPI.*_FLAG` flags specifying all services that must be provided in the context. If the context fail to provide any of them then it is closed and a GSSAPI.MissingServicesError is thrown.

      GSSAPI.PROT_READY_FLAG is ignored in this parameter. The fact that a user calls a per-message function indicates that this service is required at that point, and a GSSAPI.MissingServicesError is thrown if it isn't.

    Note

      Channel bindings (RFC 2743, section 1.1.6) are not yet implemented since that feature appear to not be in much active use, and its format is not completely specified (RFC 2744, section 3.11).

    Method delegated_cred

      `Cred delegated_cred()`

    Description

      Returns the delegated credentials from the initiator if the delegation (c.f. GSSAPI.DELEG_FLAG) service is in use.

    Inherit Context

      inherit Context : Context

  CLASS GSSAPI.Context

    Description

      Class representing a security context; see RFC 2743 section 1.1.3. The user usually instantiates one of the two inheriting classes GSSAPI.InitContext or GSSAPI.AcceptContext, based on whether the context should act as initiator or acceptor for the connection. This class is instantiated directly for imported contexts.

    Note

      If a Context object for a partly or completely established context is destructed, `GSS_Delete_sec_context` (RFC 2743, section 2.2.3) is called. That function might do blocking network I/O, which due to pike's object management might occur essentially anytime in any thread if the object isn't explicitly destructed. To avoid that, it's strongly recommended to call delete in contexts that are no longer used.

    Method create

      `GSSAPI.Context GSSAPI.Context(string interprocess_token, void|int required_services)`

    Description

      Creates a context by importing an inter-process token.

      This wraps `GSS_Import_sec_context` according to RFC 2743 section 2.2.9.

    Parameter `interprocess_token`

      The inter-process token which has been created by export or some other `GSS_Export_sec_context` wrapper.

    Parameter `required_services`

      Bitfield of `GSSAPI.*_FLAG` flags specifying all services that must be provided in the context. If the context fail to provide any of them then it is closed and a GSSAPI.MissingServicesError is thrown.

      GSSAPI.PROT_READY_FLAG is ignored in this parameter. The fact that a user calls a per-message function indicates that this service is required at that point, and a GSSAPI.MissingServicesError is thrown if it isn't.

    Note

      It is not possible to retrieve delegated credentials from an imported context. That is a GSS-API limitation.

    Method delete

      `void delete()`

    Description

      Frees the resources for the context, provided it is in use. Does nothing otherwise.

      This wraps `GSS_Delete_sec_context` according to RFC 2743 section 2.2.3.

    Note

      This function might block on network connections to remote authentication servers.

    Note

      In compliance with recommendations in GSS-API v2, the optional output token is never used in the call to `GSS_Delete_sec_context`.

    Method export

      `string export()`

    Description

      Exports this context so that it can be imported in another process, providing the inter-process context transfer service is available (c.f. GSSAPI.TRANS_FLAG).

      This wraps `GSS_Export_sec_context` according to RFC 2743 section 2.2.8.

      The returned string is intended to be fed to GSSAPI.Context.create (or some other `GSS_Import_sec_context` wrapper) in the receiving process.

      This operation frees the context in this object.

    Method get_mic

      `string get_mic(string message, void|int qop)`

    Description

      Calculates and returns a MIC (message integrity checksum) for the given message that allows the receiver to verify its origin and integrity through verify_mic or some other `GSS_VerifyMIC` wrapper.

      This wraps `GSS_GetMIC` according to RFC 2743 section 2.3.1.

      This function requires that the context is established, or that the early per-message protection service is available (c.f. GSSAPI.PROT_READY_FLAG. If not, a GSSAPI.MissingServicesError is thrown (but the context is not closed).

    Parameter `message`

      The message for which the MIC is to be calculated. It may be of zero length.

    Parameter `qop`

      The quality of protection. This is a mechanism-specific value that lets the user direct how the underlying mechanism calculates the MIC. See RFC 2743, section 1.2.4.

      Zero or left out means use the default method.

    Method is_established
    Method services
    Method locally_initiated
    Method source_name
    Method target_name
    Method lifetime
    Method mech

      `int is_established()`
      `int services()`
      `int locally_initiated()`
      `Name source_name()`
      `Name target_name()`
      `int(0..) lifetime()`
      `string mech()`

    Description

      Functions to query various properties about the context.

      These wrap `GSS_Inquire_context` according to RFC 2743 section 2.2.6.

      is_established()

        Returns nonzero as soon as the context has been established. That means no further rounds through GSSAPI.InitContext.init or GSSAPI.AcceptContext.accept, that the remote peer is authenticated as required, and that the set of available services is complete (see services).

      services()

        Returns a bitfield of `GSSAPI.*_FLAG` flags for the services that the context (currently) provides. This field is complete only when the context establishment has finished, i.e. when is_established returns nonzero.

        See also GSSAPI.describe_services.

      locally_initiated()

        Returns nonzero if the context is an initiator, zero if it is an acceptor. (This is mainly useful in imported contexts.)

      source_name()

        Returns the name of the context initiator. The name is always an MN. Returns an anonymous name if used on the acceptor side and the anonymous authentication service (c.f. GSSAPI.ANON_FLAG) was used.

      target_name()

        Returns the name of the context acceptor. If a name is returned then it is always an MN.

        Zero is returned on the initiator side if the initiator didn't specify a target name and the acceptor did not authenticate itself (should never happen if mutual authentication (c.f. GSSAPI.MUTUAL_FLAG) is a required service).

        The returned object is not necessarily the same one as was passed to GSSAPI.InitContext.create, even though they are likely to compare as equal (they might not be equal if the passed name wasn't an MN).

      lifetime()

        Returns the validity lifetime left for the context. Returns zero if the context has expired, or Int.inf if there is no time limit (in older pikes without Int.inf a large positive integer is returned instead).

      mech()

        Returns the mechanism that provides the context. The returned value is its OID on dotted-decimal form.

      These functions don't throw errors if the context is missing or not completely established, even though they might not be able to query the proper values then (GSS-API implementations are known to not be completely reliable in handling these queries for partly established contexts). The functions instead return zero.

    Method last_confidential

      `int last_confidential()`

    Description

      Returns nonzero if the last call to wrap or unwrap provided confidentiality for the message, i.e. if wrap encrypted it or if unwrap decrypted it. Zero is returned otherwise.

    Method last_major_status
    Method last_minor_status

      `int last_major_status()`
      `int last_minor_status()`

    Description

      Returns the major and minor status codes from the last operation that called a GSS-API routine, with the exception of those that wrap `GSS_Inquire_context`.

    Method last_qop

      `int last_qop()`

    Description

      Returns the quality of protection provided by the last call to verify_mic or unwrap.

    Method process_token

      `void process_token(string remote_token)`

    Description

      Passes the given remote_token to the mechanism.

      This wraps `GSS_Process_context_token` according to RFC 2743 section 2.2.4.

      This is used for tokens that are received outside the handshaking between `GSS_Init_sec_context` (GSSAPI.InitContext.init) and `GSS_Accept_sec_context` (GSSAPI.AcceptContext.accept).

      An example is when GSSAPI.InitContext.init returns a final token and flags the context as established, but the acceptor context detects an error and sends a failure token back. That token is processed using this function since GSSAPI.InitContext.init doesn't handle any more tokens by then.

    Note

      This function might change context state.

    Note

      This function might block on network connections to remote authentication servers. However, if the remote token is the result of `GSS_Delete_sec_context` on the remote side then it will not block.

    Method required_services

      `int required_services(void|int services)`

    Description

      Gets and optionally sets the set of services that must be provided in the context. The returned and given value is a bitfield of the `GSSAPI.*_FLAG` constants.

      This is mainly useful to change the per-message service flags that verify_mic and unwrap use to decide whether a condition is an error or not.

    Parameter `services`

      New set of required services. If this is not given then the set is not changed.

      If the context is established and services contain a service which isn't currently provided then the context is closed and a GSSAPI.MissingServicesError is thrown immediately.

      GSSAPI.PROT_READY_FLAG is ignored in this parameter.

    Returns

      Returns the current set of required services (after setting them to services, if provided).

    See also

      GSSAPI.describe_services

    Method unwrap

      `string unwrap(string message, void|int accept_encrypted_only)`

    Description

      Verifies the origin and integrity of the given message using the MIC included in it, and also decrypts the message if it was encrypted. The message has been calculated by the sender using wrap or some other `GSS_Wrap` wrapper.

      This wraps `GSS_Unwrap` according to RFC 2743 section 2.3.4.

      This function requires that the context is established, or that the early per-message protection service is available (c.f. GSSAPI.PROT_READY_FLAG. If not, a GSSAPI.MissingServicesError is thrown (but the context is not closed).

    Parameter `message`

      The message to be unwrapped.

    Parameter `accept_encrypted_only`

      If this is nonzero then it is an error if message isn't encrypted, and zero is returned in that case (the status returned by last_major_status will still indicate success, though).

    Returns

      Zero is returned if the verification fails with GSSAPI.DEFECTIVE_TOKEN or GSSAPI.BAD_MIC.

      Zero is also returned if message isn't encrypted and accept_encrypted_only is set.

      Otherwise the message is successfully decrypted (provided it was encrypted to begin with), and its origin and integrity checks out, but it might still be considered wrong depending on whether the replay detection or sequencing services are required (see required_services):

      If replay detection (c.f. GSSAPI.REPLAY_FLAG) is required then zero is returned if the message is duplicated (GSSAPI.DUPLICATE_TOKEN) or old (GSSAPI.OLD_TOKEN).

      If sequencing (c.f. GSSAPI.SEQUENCE_FLAG) is required then in addition to the replay detection conditions, zero is also returned if the message is out of sequence (GSSAPI.UNSEQ_TOKEN or GSSAPI.GAP_TOKEN).

      Otherwise the unwrapped message is returned, which is valid according to the currently required services (note however that requiring the confidentiality service does not imply that an error is signalled whenever an unencrypted message is received - see instead accept_encrypted_only above).

    Throws

      Any GSS-API errors except GSSAPI.DEFECTIVE_TOKEN and GSSAPI.BAD_MIC are thrown.

    Note

      This function sets the value returned by last_confidential and last_qop.

    Note

      Even if the message is considered valid by the return value, last_major_status may be called to check for the informatory codes mentioned above.

    Method verify_mic

      `int verify_mic(string message, string mic)`

    Description

      Verifies the origin and integrity of the given message using the given mic, which has been calculated by the sender using get_mic or some other `GSS_GetMIC` wrapper.

      This wraps `GSS_VerifyMIC` according to RFC 2743 section 2.3.2.

      This function requires that the context is established, or that the early per-message protection service is available (c.f. GSSAPI.PROT_READY_FLAG. If not, a GSSAPI.MissingServicesError is thrown (but the context is not closed).

    Returns

      Zero is returned if the verification fails with GSSAPI.DEFECTIVE_TOKEN or GSSAPI.BAD_MIC.

      Otherwise the message origin and integrity checks out, but it might still be considered wrong depending on whether the replay detection or sequencing services are required (see required_services):

      If replay detection (c.f. GSSAPI.REPLAY_FLAG) is required then zero is returned if the message is duplicated (GSSAPI.DUPLICATE_TOKEN) or old (GSSAPI.OLD_TOKEN).

      If sequencing (c.f. GSSAPI.SEQUENCE_FLAG) is required then in addition to the replay detection conditions, zero is also returned if the message is out of sequence (GSSAPI.UNSEQ_TOKEN or GSSAPI.GAP_TOKEN).

      Otherwise nonzero is returned to indicate that the message is valid according to the currently required services.

    Throws

      Any GSS-API errors except GSSAPI.DEFECTIVE_TOKEN and GSSAPI.BAD_MIC are thrown.

    Note

      This function sets the value returned by last_qop.

    Note

      Regardless whether the message is considered valid or not by the return value, last_major_status may be called to check for routine errors or the informatory codes mentioned above.

    Method wrap

      `string wrap(string message, void|int encrypt, void|int qop)`

    Description

      Calculates a MIC (message integrity checksum) for the given message, and returns it together with the message, which is optionally encrypted. The returned value can be verified and (if applicable) decrypted by the receiver using unwrap or some other `GSS_Unwrap` wrapper.

      This wraps `GSS_Wrap` according to RFC 2743 section 2.3.3.

      This function requires that the context is established, or that the early per-message protection service is available (c.f. GSSAPI.PROT_READY_FLAG. If not, a GSSAPI.MissingServicesError is thrown (but the context is not closed).

    Parameter `message`

      The message to be wrapped. It may be of zero length.

    Parameter `encrypt`

      Set to nonzero to request that the message is encrypted. Otherwise only a MIC is calculated and the returned value contains the unencrypted message.

      If this is set and the confidentiality service (c.f. GSSAPI.CONF_FLAG) is required then the returned value is always encrypted. Otherwise it might not be encrypted anyway, and a call to last_confidential will tell if it is or not.

    Parameter `qop`

      The quality of protection. This is a mechanism-specific value that lets the user direct how the underlying mechanism calculates the MIC. See RFC 2743, section 1.2.4.

      Zero or left out means use the default method.

    Note

      This function sets the value returned by last_confidential.

    See also

      wrap_size_limit

    Method wrap_size_limit

      `int(0..) wrap_size_limit(int(0..) output_size, int encrypt, void|int qop)`

    Description

      Returns the maximum size of an input string to wrap that would produce no more than output_size bytes in the resulting output.

      This wraps `GSS_Wrap_size_limit` according to RFC 2743 section 2.2.7.

      with_confidentiality and qop are the same as in the call to wrap.

  CLASS GSSAPI.Cred

    Description

      Objects of this class hold one or more credentials that the current process can use to assert identities; see RFC 2743 section 1.1.1.

    Note

      If a Cred object is destructed, `GSS_Release_cred` (RFC 2743, section 2.1.2) is called. The RFC doesn't preclude that that function might do blocking network I/O, which due to pike's object management might occur essentially anytime in any thread if the object isn't explicitly destructed. To avoid that, it's recommended to call release in credential objects that are no longer used.

    Method name
    Method cred_usage
    Method mechs
    Method lifetime
    Method init_lifetime
    Method accept_lifetime

      `GSSAPI.Name name(void|string mech)`
      `int cred_usage(void|string mech)`
      `multiset(string) mechs()`
      `int(0..)|Int.inf lifetime()`
      `int(0..)|Int.inf init_lifetime(string mech)`
      `int(0..)|Int.inf accept_lifetime(string mech)`

    Description

      Functions to query various properties about the credentials.

      These wrap `GSS_Inquire_cred` according to RFC 2743 section 2.1.3 if mech is not given, and `GSS_Inquire_cred_by_mech` according to section 2.1.5 otherwise.

    Parameter `mech`

      If this is given then the credential for that specific mechanism is queried. mech contains the OID of the mechanism on dotted-decimal form.

      Some of the query functions can only be used for a specific mechanism, in which case mech is required. Some can only be used on the credentials in general, and the mech argument is not applicable. Some can be used both ways, and then mech is optional.

        `name (void|string mech)` Returns the name of the identity that the credential(s) assert. If mech is given then the returned name is a Mechanism Name (MN).

        The returned GSSAPI.Name object is always a newly created one, even though it typically compares as equal with the ones given to acquire or add.

        `cred_usage (void|string mech)` Returns how the credential(s) may be used, one of GSSAPI.INITIATE, GSSAPI.ACCEPT or GSSAPI.BOTH.

        If mech is not given then the returned usage value reflects the union of the capabilities in all credentials.

        `mechs()` Returns the set of mechanisms supported by the credential. The returned value is a multiset of strings with OIDs on dotted-decimal form.

        `lifetime()` Returns the shortest validity lifetime left in any of the mechanisms that are part of the credentials, for either initiator or acceptor use.

        Returns zero if some part of the credentials has expired.

        Returns Int.inf if there is no time limit (in older pikes without Int.inf a large positive integer is returned instead).

        `init_lifetime (string mech)` Returns the validity lifetime left for initiator use.

        Returns zero if the credential has expired for this use or if its usage is GSSAPI.ACCEPT.

        Returns Int.inf if there is no time limit (in older pikes without Int.inf a large positive integer is returned instead).

        `accept_lifetime (string mech)` Returns the validity lifetime left for acceptor use.

        Returns zero if the credential has expired for this use or if its usage is GSSAPI.INITIATE.

        Returns Int.inf if there is no time limit (in older pikes without Int.inf a large positive integer is returned instead).

    Note

      RFC 2743 doesn't preclude that these functions might block on network connections to remote authentication servers.

    Method acquire

      `void acquire(Name|string name, int cred_usage, void|multiset(string) desired_mechs, void|int(0..) desired_time)`

    Description

      Acquire initial credentials for this object. It is an error if it already has some credentials.

      This wraps `GSS_Acquire_cred` according to RFC 2743 section 2.1.1.

    Parameter `name`

      The name of the identity for which credentials should be acquired. It is up to the GSS-API implementation to check whether the running process is authorized to act on behalf of this identity.

      This can be either a GSSAPI.Name object or a string. In the latter case, the string is converted to a GSS-API name according to a mechanism-specific default printable syntax, i.e. just like if it would be given as the sole argument to GSSAPI.Name.create.

      If this is zero then credentials for the default principal (if any) are retrieved.

    Parameter `cred_usage`

      Specifies how the credential will be used. One of GSSAPI.INITIATE, GSSAPI.ACCEPT or GSSAPI.BOTH.

    Parameter `desired_mechs`

      The mechanisms that the credentials should cover, as a multiset containing their OIDs on dotted-decimal form. If zero or left out then a default set provided by the GSS-API implementation is used.

      It is an error to pass an empty multiset.

    Parameter `desired_time`

      Number of seconds the credentials should remain valid. The GSS-API implementation may return credentials that are valid both longer and shorter than this. Zero or left out means use the maximum permitted time.

    Note

      This function might block on network connections to remote authentication servers.

    Method add

      `void add(Name|string name, int cred_usage, string desired_mech, void|int(0..)|array(int(0..)) desired_time)`

    Description

      Adds another credential element to this object. If this object has no credentials already then it will get the default credentials in addition to this specified one.

      This wraps `GSS_Add_cred` according to RFC 2743 section 2.1.4.

    Parameter `name`

      The name of the identity for which a credential should be acquired. It is up to the GSS-API implementation to check whether the running process has sufficient privileges to act on behalf of this identity.

      This can be either a GSSAPI.Name object or a string. In the latter case, the string is converted to a GSS-API name according to a mechanism-specific default printable syntax, i.e. just like if it would be given as the sole argument to GSSAPI.Name.create.

      If this is zero then a credential for the default principal (if any) are retrieved.

    Parameter `cred_usage`

      Specifies how the credential will be used. One of GSSAPI.INITIATE, GSSAPI.ACCEPT or GSSAPI.BOTH.

    Parameter `desired_mech`

      The mechanism that the credential should cover, as an OID on dotted-decimal form.

    Parameter `desired_time`

      Number of seconds the credential should remain valid. The GSS-API implementation may return a credential that is valid both longer and shorter than this. Zero or left out means use the maximum permitted time.

      This can also be an array containing two elements. In that case the first element applies to the credential when it is used to initiate contexts, and the second element applies to use for acceptor contexts.

    Note

      This function might block on network connections to remote authentication servers.

    Method release

      `void release()`

    Description

      Frees the resources for the credential.

      This wraps `GSS_Release_cred` according to RFC 2743 section 2.1.2.

    Note

      This function might block on network connections to remote authentication servers.

  CLASS GSSAPI.Error

    Description

      Error object used for GSS-API errors.

    Method create

      `GSSAPI.Error GSSAPI.Error(void|int major, void|int minor, void|string mech, void|string message, void|array backtrace)`

    Parameter `major`

      Initial value for major_status.

    Parameter `minor`

      Initial value for minor_status.

    Parameter `mech`

      Object identifier on dotted-decimal form for the mechanism that minor applies to.

    Parameter `message`

      Error message. This is prepended to the message generated from major_status and/or minor_status. `": "` is inserted in between.

    Parameter `backtrace`

      Backtrace. The current backtrace for the calling function is used if left out.

    Constant is_gssapi_error
    Constant error_type

      `constant int GSSAPI.Error.is_gssapi_error`
      `constant string GSSAPI.Error.error_type`

    Description

      Object recognition constants.

    Inherit Error.Generic

      inherit Error.Generic : Error.Generic

    Variable major_status

      `int GSSAPI.Error.major_status`

    Description

      The major status code. This is a bitwise OR of one routine error code and zero or more supplementary error info bits.

      See RFC 2743 section 1.2.1.1 and RFC 2744 section 3.9.1. Note that the calling errors mentioned in RFC 2744 are never thrown.

    See also

      major_status_messages

    Method major_status_messages

      `array(string) major_status_messages()`

    Description

      Returns an array containing messages for all the status values in major_status. See GSSAPI.major_status_messages for further details.

    Variable minor_status

      `int GSSAPI.Error.minor_status`

    Description

      The minor status code specific for the mechanism.

    See also

      minor_status_messages, minor_status_mech

    Method minor_status_mech

      `string minor_status_mech()`

    Description

      Returns the OID for the mechanism that is used to interpret the minor status, or zero if no mechanism has been set. It is returned on dotted-decimal form.

    Method minor_status_messages

      `array(string) minor_status_messages()`

    Description

      Returns an array containing messages for all the status values in minor_status. See GSSAPI.minor_status_messages for further details.

  CLASS GSSAPI.InitContext

    Description

      Variant of Context which is used on the initiator side.

    Method create

      `GSSAPI.InitContext GSSAPI.InitContext(void|Cred cred, void|Name|string target_name, void|string mech, void|int required_services, void|int desired_services, void|int(0..) desired_time)`

    Description

      Creates a context for initiator use. This function only accepts parameters to be used later during the init call. If there are semantic problems with them, such as if the credentials are stale or the mechanism isn't supported, then they will be signalled later by init.

    Parameter `cred`

      Credentials for the identity this context claims. The credentials for the default principal (if any) is used if zero or left out.

    Parameter `target_name`

      The name of the target.

      This can be either a GSSAPI.Name object or a string. In the latter case, the string is converted to a GSS-API name according to a mechanism-specific default printable syntax, i.e. just like if it would be given as the sole argument to GSSAPI.Name.create.

      Some mechanisms support unnamed targets (as allowed in GSS-API v2, update 1) and in such cases this may be zero or left out.

    Parameter `mech`

      The mechanism to use. It is given as an OID on dotted-decimal form. The GSS-API implementation chooses this using system settings if it's zero or left out, which is the recommended way.

    Parameter `required_services`

      Bitfield of `GSSAPI.*_FLAG` flags specifying all services that must be provided in the context. If the context fail to provide any of them then it is closed and a GSSAPI.MissingServicesError is thrown.

      GSSAPI.PROT_READY_FLAG is ignored in this parameter. The fact that a user calls a per-message function indicates that this service is required at that point, and a GSSAPI.MissingServicesError is thrown if it isn't.

    Parameter `desired_services`

      Bitfield of `GSSAPI.*_FLAG` flags specifying the context services that are wanted but not required. I.e. errors won't be thrown if any of these aren't provided. The services specified in required_services are implicit, so they need not be repeated here.

      GSSAPI.PROT_READY_FLAG is ignored in this parameter.

    Parameter `desired_time`

      The desired context validity time in seconds. Zero or left out means use the default.

    Note

      Channel bindings (RFC 2743, section 1.1.6) are not yet implemented since that feature appear to not be in much active use, and its format is not completely specified (RFC 2744, section 3.11).

    Inherit Context

      inherit Context : Context

    Method init

      `string init(void|string remote_token)`

    Description

      Initiates a security context to send to a remote peer.

      This wraps `GSS_Init_sec_context` according to RFC 2743 section 2.2.1.

      The underlying mechanism might require several tokens to be passed back and forth to establish the context. If is_established returns zero after a call to this function then the caller must wait for a token from the remote peer to feed as remote_token in another call to this function.

    Parameter `remote_token`

      A token from the remote peer, as returned by a call to GSSAPI.AcceptContext.accept (or some other `GSS_Accept_sec_context` wrapper) in it. This is zero or left out on the initial call, but used later if the remote peer sends back tokens to process as part of the context establishment.

    Returns

      If a string is returned then it must be passed to the remote peer which will feed it to GSSAPI.AcceptContext.accept or some other `GSS_Accept_sec_context` wrapper. An empty string is never returned.

      Zero is returned if there is no token to send to the remote peer. Note that is_established might still return zero in that case, meaning more remote tokens are necessary.

    Note

      This function might block on network connections to remote authentication servers.

  CLASS GSSAPI.MissingServicesError

    Description

      Error object used when one or more required services are missing in a GSSAPI.Context object.

    Method create

      `GSSAPI.MissingServicesError GSSAPI.MissingServicesError(void|int missing_services)`

    Parameter `missing_services`

      Initial value for services.

    Constant is_gssapi_missing_services_error
    Constant error_type

      `constant int GSSAPI.MissingServicesError.is_gssapi_missing_services_error`
      `constant string GSSAPI.MissingServicesError.error_type`

    Description

      Object recognition constants.

    Inherit Error.Generic

      inherit Error.Generic : Error.Generic

    Variable services

      `int GSSAPI.MissingServicesError.services`

    Description

      Bitfield of `GSSAPI.*_FLAG` flags for the missing services that caused the error.

    See also

      GSSAPI.describe_services

  CLASS GSSAPI.Name

    Description

      An object of this class contains a name on the internal form which is required by the GSS-API functions. See RFC 2743, section 1.1.5.

    Method __hash

      `int hash_value( GSSAPI.Name arg )`

    Description

      Tries to export the name (see export) and if that succeeds returns a hash made from the exported name string. Otherwise a normal hash based on this object is returned.

      This means that mechanism names (MNs) can be used as indices in mappings without getting duplicate entries for the same identity.

    Method `==

      `int res = GSSAPI.Name() == other`

    Description

      Returns true if other is a GSSAPI.Name which contains a name that refers to the same identity as this one.

      This wraps `GSS_Compare_name` according to RFC 2743 section 2.4.3.

      If either GSSAPI.Name object is uninitialized or contains an anonymous identity then they are considered different, unless it is the very same GSSAPI.Name object (that is an inherent pike behavior).

    Throws

      An error is thrown if the names are incomparable, or if either of them are ill-formed.

    Method canonicalize

      `Name canonicalize(string mech)`

    Description

      Returns a GSSAPI.Name containing the canonical mechanism name (MN) of this name. The mechanism is given as a dotted-decimal OID in mech.

      This wraps `GSS_Canonicalize_name` according to RFC 2743 section 2.4.14.

    Note

      This function might block on network connections to remote authentication servers.

    Method create

      `GSSAPI.Name GSSAPI.Name(string name, void|string name_type)`

    Description

      This wraps `GSS_Import_name` according to RFC 2743 section 2.4.5.

    Parameter `name`

      A name on string form (a contiguous string name in GSS-API parlance).

    Parameter `name_type`

      The OID on dotted-decimal form for the type of the name in name. If left out, name is parsed according to a mechanism-specific default printable syntax.

    Note

      If name is the result of export or a similar function then name_type should be GSSAPI.NT_EXPORT_NAME.

    Method display_name
    Method display_name_type

      `string display_name()`
      `string display_name_type()`

    Description

      display_name returns a representation of the name for display purposes, and display_name_type returns an OID on dotted-decimal form for the type of that name.

      If no type was given to create then display_name_type might return zero.

      This wraps `GSS_Display_name` according to RFC 2743 section 2.4.4.

    See also

      The `GSSAPI.NT_*` constants.

    Method export

      `string export(void|string mech)`

    Description

      Returns the name on the exported format. If mech isn't given then the name has to be a mechanism name (MN). If mech is given then the name is canonicalized according to that mechanism before being exported (see canonicalize).

      This wraps `GSS_Export_name` according to RFC 2743 section 2.4.15.

    Note

      This function might block on network connections to remote authentication servers if mech is specified.

    Method mechs

      `multiset(string) mechs()`

    Description

      Returns the OIDs for the mechanisms that might be able to process this name. The returned OID strings are on dotted-decimal form.

      This wraps `GSS_Inquire_mechs_for_name` according to RFC 2743 section 2.4.13.

    Note

      Some older GSS-API v2 implementations lack this funcion.

Module GTKSupport

  CLASS GTKSupport.Alert

    Method create

      `GTKSupport.Alert GTKSupport.Alert(string text, string|void title)`

    Inherit Dialog

      inherit GTK1.Dialog : Dialog

    Method ok

      `GTK1.Button ok()`

    Description

      Returns the ok Button object.

  CLASS GTKSupport.SClist

    Description

      A Clist with scrollbars. Defines the same interface as Clist.

  CLASS GTKSupport.pDrawingArea

    Description

      A Drawing area with backing store. Basically, the only difference from a drawing area widget is that this one never loose it's contents unless you do paint over them.

      It also use quite a significant amount of memory if the backing pixmap has many bitplanes, and the drawing area is large.

    See also

      GTK1.DrawingArea

    Inherit DrawingArea

      inherit GTK1.DrawingArea : DrawingArea

  Module GTKSupport.MenuFactory

    Method MenuFactory

      `array(object) MenuFactory(MenuDef ... definition)`

    Description

      This is the function that actually builds the menubar.

    Example

          import GTK1.MenuFactory;
           [GTK1.MenuBar bar, GTK1.AcceleratorTable map] =
            MenuFactory(
              MenuDef( "File/New", new_file, 0, "A-N" ),
              MenuDef( "File/Open", new_file, 1, "A-O" ),
              MenuDef( "File/Save", save_file, 0, "A-S" ),
              MenuDef( "File/<separator>", 0, 0 ),
              MenuDef( "File/Quit", _exit, 0, "A-Q" ),
            );

    Returns

      Array
      `GTK1.MenuBar 0` | GTK1.MenuBar
      `GTK1.AcceleratorTable 1` | GTK1.AcceleratorTable

    Method PopupMenuFactory

      `array(object) PopupMenuFactory(MenuDef ... definition)`

    Description

      Identical to MenuFactory, but creates popup menus instead.

    Returns

      Array
      `GTK1.Menu 0` | GTK1.Menu
      `GTK1.AccelGroup 1` | GTK1.AccelGroup

    Method get_menubar_mapping

      `mapping get_menubar_mapping()`

    Description

      Returns a (flat) mapping `([ path:GTK1.MenuItem ])`.

    Note

      This function can only be called after the menubar is created.

    Method set_menubar_modify_callback

      `void set_menubar_modify_callback(function(:void) to)`

    Description

      The function passed as the argument to this function will be called each time the accelerator key mapping is changed by the user with the new mapping as the argument.

    Note

      This function is only used when the menubar is created, once you are done with the menubar creation, the callbacks for that menubar will be fixed.

    CLASS GTKSupport.MenuFactory.MenuDef

      Description

        Definition of a menu item.

      Method assign_shortcut

        `void assign_shortcut(string sc)`

      Description

        Sets a new shortcut as the current one.

        The shortcut syntax is: m[m[..]]-key, where m is one or more modifier character, and key is the desired key (NOTE: Key must be in the range 0-255 currently, this will hopefully be fixed by the GTK people in the future)

        The modifiers are:

        `"s"` | Shift
        `"c"` | Control
        `"a"` | Modifier 1 (called alt by the GTK people, that's not true, though)
        `"1"`
        `"g"` | Modifier 2 (called altgr by the GTK people, that's not true, though)
        `"2"`
        `"m"` | Modifier 3 (not mapped by the GTK people, meta on _my_ keyboard)
        `"3"`
        `"h"` | Modifier 4 (not mapped by the GTK people, hyper on _my_ keyboard)
        `"4"`
        `"u"` | Modifier 5 (not mapped by the GTK people, super on _my_ keyboard)
        `"5"`

      Method create

        `GTKSupport.MenuFactory.MenuDef GTKSupport.MenuFactory.MenuDef(string path, function(:void)|void cb, mixed|void cbarg, string|void binding, int|void right)`

      Parameter `path`

        Path is the menupath. A submenu will be created for each "Directory" in the path, and menuitems will be created for the "files". There are two special cases: The "file" `"<separator>"` will create a thin line. The "file"-prefix `"<check>"` will make the menuitem a checkmenuitem instead of a normal menuitem.

      Parameter `cb`
      Parameter `cbarg`

        The second and third arguments are the callback function and the first callback function argument. If the callback function argument is an array, the indices of the array will be pushed as arguments. To call the function with an array as the only argument, make an array with the array in. The callback function will be called like `callback( arg, widget )`, or if arg is an array, `callback( arg[0], arg[1], ..., widget )`.

      Parameter `shortcut`

        The fourth argument, shortcut, is the shortcut to bind to this menu item. The shortcut can be changed later on by calling assign_shortcut, or by the user by pressing the desired keycombination over the menu item.

        The shortcut syntax is: m[m[..]]-key, where m is one or more modifier character, and key is the desired key (NOTE: Key must be in the range 0-255 currently, this will hopefully be fixed by the GTK people in the future)

        The modifiers are:

        `"s"` | Shift
        `"c"` | Control
        `"a"` | Modifier 1 (called alt by the GTK people, that's not true, though)
        `"1"`
        `"g"` | Modifier 2 (called altgr by the GTK people, that's not true, though)
        `"2"`
        `"m"` | Modifier 3 (not mapped by the GTK people, meta on _my_ keyboard)
        `"3"`
        `"h"` | Modifier 4 (not mapped by the GTK people, hyper on _my_ keyboard)
        `"4"`
        `"u"` | Modifier 5 (not mapped by the GTK people, super on _my_ keyboard)
        `"5"`

      Parameter `right`

        Currently ignored.

  Module GTKSupport.Util

    Method decode_image

      `mapping decode_image(string data, mapping|array|void tocolor)`

    Description

      Decodes an image as a GDK1.Pixmap.

    Returns

      `"format" : string` | The MIME content type of the image.
      `"alpha" : GDK1.Bitmap` | The alpha channel of the image, if any. Otherwise `0`.
      `"img" : GDK1.Bitmap` | The decoded image.

    Method load_image

      `mapping load_image(string filename, array|void bgcol)`

    Description

      Loads and decodes an image as a GDK1.Pixmap.

    Returns

      `"format" : string` | The MIME content type of the image.
      `"alpha" : GDK1.Bitmap` | The alpha channel of the image, if any. Otherwise `0`.
      `"img" : GDK1.Bitmap` | The decoded image.

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.

    Method ECEF

      `array(float) ECEF()`

    Description

      Returns the current position as Earth Centered Earth Fixed Cartesian Coordinates.

    Returns

      ({ X, Y, Z })

    Method GEOREF

      `string GEOREF()`

    Description

      Gives the full GEOREF position for the current position, e.g. "LDJA0511".

    Method RT38

      `array(float) RT38()`

    Method UTM

      `string UTM(int precision)`

    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

      `string UTM_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

      `int UTM_zone_number()`

    Description

      Returns the UTM zone number for the current longitude, with correction for the Svalbard deviations.

    Method __hash

      `int hash_value( Geography.Position arg )`

    Method _sprintf

      `string sprintf(string format, ... Geography.Position arg ... )`

    Method `<

      `int res = Geography.Position() < pos`

    Method `==

      `int res = Geography.Position() == pos`

    Method `>

      `int res = Geography.Position() > pos`

    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.

    Method approx_height

      `float approx_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.Position Geography.Position(int|float lat, int|float long, void|int|float alt)`
      `Geography.Position Geography.Position(string lat, string long)`
      `Geography.Position Geography.Position(string position)`
      `Geography.Position Geography.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

      `float eccentricity_squared()`

    Description

      Returns the first eccentricity squared for the selected earth approximation ellipsoid.

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

    Method euclidian_distance

      `float euclidian_distance(this_program p)`

    Description

      Calculate the euclidian distance between two Geography.Position. Result is in meter. This uses the ECEF function.

    Method flattening

      `float flattening()`

    Description

      Returns the flattening factor for the selected earth approximation ellipsoid.

    Variable lat

      `float Geography.Position.lat`

    Description

      Latitude (N--S) of the position, in degrees. Positive number is north, negative number is south.

    Method latitude
    Method longitude

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

    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"

    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 set_ellipsoid

      `bool set_ellipsoid(string name)`
      `bool set_ellipsoid(float equatorial_radius, float polar_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

      `void set_from_RT38(int|float|string x_n, int|float|string y_e)`

    Description

      Sets the longitude and lattitude from the given RT38 coordinates.

    Method set_from_UTM

      `void set_from_UTM(int zone_number, string zone_designator, float UTME, float UTMN)`

    Description

      Sets the longitude and lattitude from the given UTM coordinates.

    Method standard_grid

      `string standard_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

    Method `[]
    Method `->

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

    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.

  Variable countries

    `array(Country) Geography.Countries.countries`

  Description

    All known countries.

  Method from_domain

    `Country from_domain(string domain)`

  Description

    Look up a country from a domain name. Returns zero if the domain doesn't map to a country. Note that there are some valid domains that 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

    `Country from_domain(string name)`

  Description

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

  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 as-known-as, if any

    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

      `string continent()`

    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.

    Variable fips10

      `string Geography.Countries.Country.fips10`

    Description

      FIPS 10-character code; "Federal Information Processing Standards 10-3" etc, used by some goverments in the US.

    Variable former

      `int Geography.Countries.Country.former`

    Description

      Flag that is set if this country doesn't exist anymore. (eg USSR.)

    Variable iso2

      `string Geography.Countries.Country.iso2`

    Description

      ISO 2-character code aka domain name

Module Geography.GeoIP

  Method parse_77

    `void parse_77(string line, object tree)`

  Description

    Parsing function for geoip databases in the format used my http://software77.net/.

  Method parse_maxmind

    `void parse_maxmind(string line, object tree)`

  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

      `mixed from_ip(string ip)`

    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.

    Method create

      `Geography.GeoIP.IPv4 Geography.GeoIP.IPv4(string file_name, function(string, ADT.CritBit.IPv4Tree:void) fun)`
      `Geography.GeoIP.IPv4 Geography.GeoIP.IPv4(ADT.CritBit.IPv4Tree tree)`

    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.

    Inherit IP

      inherit IP : IP

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

    `constant int 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

    `constant int 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

    `constant int 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

    `array(array) find_all_options(array(string) argv, array(array(array(string)|string|int)) options, void|int(-1..1) posix_me_harder, void|int throw_errors)`

  Description

    This function does the job of several calls to find_option(). The main advantage of this is that it allows it to handle the `POSIX_ME_HARDER` environment variable better. When 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
    `string name` | Name is a tag used to identify the option in the output.
    `int type` | Type is one of Getopt.HAS_ARG, Getopt.NO_ARG and Getopt.MAY_HAVE_ARG and it affects how the error handling and parsing works. You should use HAS_ARG for options that require a path, a number or similar. NO_ARG should be used for options that do not need an argument, such as `--version`. MAY_HAVE_ARG should be used for options that may or may not need an argument.

    `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|mixed default` | This is the default value a MAY_HAVE_ARG option will have in the output if it was set but not assigned any value.

    Only the first three elements need to be included.

  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
    `string name` | Option identifier name from the input.
    `mixed value` | 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

    `string|bool find_option(array(string) argv, array(string)|string shortform, array(string)|string|void longform, array(string)|string|void envvars, string|bool|void def, int|void throw_errors)`

  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..0)|zero` | The option does not require a value.
    `int(1..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) argv, void|int(-1..1) posix_me_harder, void|int throw_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

    `constant int Git.MODE_DIR`

  Description

    A subdirectory.

  Constant MODE_EXE

    `constant int Git.MODE_EXE`

  Description

    A normal, but executable file.

  Constant MODE_FILE

    `constant int Git.MODE_FILE`

  Description

    A normal (non-executable) file.

  Constant MODE_GITLINK

    `constant int Git.MODE_GITLINK`

  Description

    A gitlink (aka submodule reference).

  Constant MODE_SYMLINK

    `constant int Git.MODE_SYMLINK`

  Description

    A symbolic link.

  Constant NULL_SHA1

    `constant string Git.NULL_SHA1`

  Description

    The NULL SHA1.

  Method git

    `string git(string git_dir, string command, 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 and error on failure.

  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 hash_blob

    `string hash_blob(string data)`

  Description

    Hash algorithm for blobs that is compatible with git.

  Method low_git

    `Process.Process low_git(mapping(string:mixed) options, string git_dir, string command, 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.

  CLASS Git.Export

    Description

      Framework for creating a command-stream suitable for git-fast-import.

    Method blob

      `void blob(string blob, string|void marker)`

    Description

      Upload data.

    Parameter `blob`

      Data to upload.

    Parameter `marker`

      Optional export marker for referring to the data.

    Method cat_blob

      `void cat_blob(string dataref)`

    Description

      Output a blob on the `cat-blob-fd`.

    Parameter `dataref`

      Reference to the blob to output.

    Method checkpoint

      `void checkpoint()`

    Description

      Flush state to disk.

    Method command

      `void command(sprintf_format cmd, sprintf_args ... args)`

    Description

      Send a raw command.

    Method commit

      `void commit(string ref, string|void commit_marker, string|void author_info, string committer_info, string message, 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.Export Git.Export()`
      `Git.Export Git.Export(Stdio.File fd)`
      `Git.Export Git.Export(string git_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

      `int done()`

    Description

      End the command-stream and wait for completion.

    Method export

      `void export(string file_name, string|void git_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

      `void feature(string feature, string|void arg)`

    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"`
      `"notes"` | Require that the backend supports the notemodify subcommand.
      `"done"` | Require the stream to terminate with a done command.

    Method filecopy

      `void filecopy(string from, string to)`

    Description

      Copy a file or directory.

    Method filedelete

      `void filedelete(string path)`

    Description

      Delete a file.

    Method filedeleteall

      `void filedeleteall()`

    Description

      Delete all files.

      Used to start a commit from a clean slate.

    Method filemodify

      `void filemodify(int mode, string path, string|void dataref)`

    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

      `void filerename(string from, string to)`

    Description

      Rename a file or directory.

    Method ls

      `void ls(string path, string|void dataref)`

    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

      `void notemodify(string commit, string|void dataref)`

    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

      `void option(string option)`

    Description

      Set backend options.

    Method progress

      `void progress(string message)`

    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

      `void reset(string ref, string|void committish)`

    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

      `void tag(string name, string committish, string tagger_info, string message)`

    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/

  Method fac

    `Gmp.mpz fac(int x)`

  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.

    Method __hash

      `int hash_value( Gmp.mpf arg )`

    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

      `string sprintf(string format, ... Gmp.mpf arg ... )`

    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 = 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 create

      `Gmp.mpf Gmp.mpf(void|int|string|float|object x, void|int(0..) precision)`
      `Gmp.mpf Gmp.mpf(string x, int(0..) precision, int(2..36) base)`

    Method get_float

      `float get_float()`

    Description

      Returns the value of the object as a float.

    Method get_int

      `int|object get_int()`

    Method get_precision

      `int(0..) get_precision()`

    Description

      Returns the current precision, in bits.

    Method get_string

      `string get_string()`

    Method set_precision

      `Gmp.mpf set_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

      `int sgn()`

  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

      `int hash_value( Gmp.mpq arg )`

    Method _is_type

      `bool res = is_type(Gmp.mpq())`

    Method _sprintf

      `string sprintf(string format, ... Gmp.mpq arg ... )`

    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.mpq Gmp.mpq(void|string|int|float|Gmp.mpz|Gmp.mpq x)`
      `Gmp.mpq Gmp.mpq(int numerator, int denominator)`
      `Gmp.mpq Gmp.mpq(string x, int base)`

    Method den

      `int den()`

    Description

      Returns the denominator. It is always positive.

    Method get_float

      `float get_float()`

    Method get_int

      `int get_int()`

    Method get_string

      `string get_string(void|int decimal_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.mpq invert()`

    Method num

      `int num()`

    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

      `int hash_value( Gmp.mpz arg )`

    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.mpz decode_value(string(8bit) data)`

    Method _encode

      `string(8bit) encode_value(Gmp.mpz data)`

    Method _random

      `Gmp.mpz random( Gmp.mpz arg )`

    Method _sprintf

      `string sprintf(string format, ... Gmp.mpz arg ... )`

    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 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.mpz bin(int k)`

    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.

  Note

    This function is currently (Pike 7.8) not available with old releases of the gmp libraries.

  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.

  See also

    cast_to_int, cast_to_float, cast_to_string

  Method cast_to_float

    `float cast_to_float()`

  Method cast_to_int

    `int cast_to_int()`

  Method cast_to_string

    `string cast_to_string()`

  Method create

    `Gmp.mpz Gmp.mpz()`
    `Gmp.mpz Gmp.mpz(string|int|float|object value)`
    `Gmp.mpz Gmp.mpz(string value, int(2..36)|int(256..256)|int(-256..-256) base)`

  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), 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..36]` can be prefixed with `"+"` or `"-"`. 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.

  Method digits

    `string digits(void|int(2..36)|int(256..256)|int(-256..-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-36 and `256` and `-256`. The default base is 10.

  See also

    cast_to_string

  Method fac

    `Gmp.mpz fac()`

  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.mpz gcd(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.mpz x)`

  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.mpz x)`

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 invert

  `Gmp.mpz invert(int|float|Gmp.mpz x)`

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.mpz next_prime(void|int count, void|int limit)`

Method popcount

  `int popcount()`

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) or
  ``Gmp.mpz pow(int|float|Gmp.mpz x)`

Description

  Return this mpz object raised to x. The case when zero is raised to zero yields one.

See also

  powm

Method powm

  `Gmp.mpz powm(int|string|float|Gmp.mpz exp, int|string|float|Gmp.mpz mod)`

Description

  Return `( this->pow(<font face='courier'>exp`) ) % <font face='courier'>mod.

See also

  pow

Method probably_prime_p

  `bool probably_prime_p(int count)`

Description

  Return 1 if this mpz object is a prime, and 0 most of the time if it is not.

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). The higher value, the more probable it is that the number is a prime. Default value is 25.

Method sgn

  `int sgn()`

Description

  Return the sign of the integer, i.e. `1` for positive numbers and `-1` for negative numbers.

Method size

  `int(0..) size(void|int base)`

Description

  Return how long this mpz would be represented in the specified base. The default base is 2.

Method small_factor

  `int small_factor(void|int(1..) limit)`

Method sqrt

  `Gmp.mpz res = sqrt([Gmp.mpz]a) or
  ``Gmp.mpz sqrt()`

Description

  Return the the truncated integer part of the square root of this mpz object.

Method sqrtrem

  `array(Gmp.mpz) sqrtrem()`

Module Gnome

  CLASS Gnome.About

    Description

      A standard way of providing a small about box for your application. You provide the name of your application, version, copyright, a list of authors and some comments about your application. It also allows the programmer to provide a logo to be displayed.

      `Gnome.About( "Example", "1.0", "(c) Roxen IS 2000\n(c) IDA, LiU 2002", ({"Per Hedbor"}), "Some nice documentation\nabout this example" );`

    Method create

      `Gnome.About Gnome.About(string title, string version, string copyright, array authors, string comment, string|void logo)`

    Description

      Creates a new GNOME About dialog. title, version, copyright, and authors are displayed first, in that order. comments is typically the location for multiple lines of text, if necessary. (Separate with "\n".) logo is the filename of a optional pixmap to be displayed in the dialog, typically a product or company logo of some sort; omit this argument if no logo file is available.

    Inherit Dialog

      inherit Gnome.Dialog : Dialog

  CLASS Gnome.App

    Description

      Toplevel GNOME applications would normally use one Gnome.App widget as their toplevel window. You can create as many Gnome.App widgets as you want, for example, some people use one GnomeApp per document their application loads.

      Once you have created one instance of this widget, you would add your main application view information to this window by using set_contents() routine.

      The GnomeApp has support for including a menubar, one or more toolbars and a statusbar for your application. It also takes care of intalling the accelerators for you when used in conjuction with the gnome-app-helper routines. The toolbars are inserted into Gnome.Dock widgets.

      The gnome-app-helper module provides various helper routines to simplify the configuration of your menus and toolbars, but you can create those yourself and use the set_menus(), add_toolbar(), set_toolbar(), add_dock_item() and add_docked().

    Method add_dock_item

      `Gnome.App add_dock_item(Gnome.DockItem item, int placement, int band_num, int band_position, int|void offset)`

    Description

      Create a new Gnome.DockItem widget containing widget, and add it to app's dock with the specified layout information. Notice that, if automatic layout configuration is enabled, the layout is overridden by the saved configuration, if any.

      item : Item to be added to app's dock placement : Placement for the new dock item, one of Gnome.DockTop, Gnome.DockRight, Gnome.DockBottom, Gnome.DockLeft and Gnome.DockFloating band_num : Number of the band where the dock item should be placed band_position : Position of the new dock item in band band_num offset : Offset from the previous dock item in the band; if there is no previous item, offset from the beginning of the band.

    Method add_docked

      `Gnome.App add_docked(GTK1.Widget widget, string name, int behavior, int placement, int band_num, int band_position, int|void offset)`

    Description

      Create a new Gnome.DockItem widget containing widget, and add it to app's dock with the specified layout information. Notice that, if automatic layout configuration is enabled, the layout is overridden by the saved configuration, if any.

      widget : Widget to be added to app's dock name : Name for the dock item that will contain toolbar behavior : Behavior for the new dock item. One of GNOME_DOCK_ITEM_BEH_EXCLUSIVE, GNOME_DOCK_ITEM_BEH_LOCKED, GNOME_DOCK_ITEM_BEH_NEVER_FLOATING, GNOME_DOCK_ITEM_BEH_NEVER_HORIZONTAL, GNOME_DOCK_ITEM_BEH_NEVER_VERTICAL and GNOME_DOCK_ITEM_BEH_NORMAL placement : Placement for the new dock item, one of Gnome.DockTop, Gnome.DockRight, Gnome.DockBottom, Gnome.DockLeft and Gnome.DockFloating band_num : Number of the band where the dock item should be placed band_position : Position of the new dock item in band band_num offset : Offset from the previous dock item in the band; if there is no previous item, offset from the beginning of the band.

    Method add_toolbar

      `Gnome.App add_toolbar(GTK1.Toolbar toolbar, string name, int behavior, int placement, int band_num, int band_position, int|void offset)`

    Description

      Create a new Gnome.DockItem widget containing toolbar, and add it to app's dock with the specified layout information. Notice that, if automatic layout configuration is enabled, the layout is overridden by the saved configuration, if any.

      toolbar : Toolbar to be added to app's dock name : Name for the dock item that will contain toolbar behavior : Behavior for the new dock item. One or more of GNOME_DOCK_ITEM_BEH_EXCLUSIVE, GNOME_DOCK_ITEM_BEH_LOCKED, GNOME_DOCK_ITEM_BEH_NEVER_FLOATING, GNOME_DOCK_ITEM_BEH_NEVER_HORIZONTAL, GNOME_DOCK_ITEM_BEH_NEVER_VERTICAL and GNOME_DOCK_ITEM_BEH_NORMAL placement : Placement for the new dock item, one of Gnome.DockTop, Gnome.DockRight, Gnome.DockBottom, Gnome.DockLeft and Gnome.DockFloating band_num : Number of the band where the dock item should be placed band_position : Position of the new dock item in band band_num offset : Offset from the previous dock item in the band; if there is no previous item, offset from the beginning of the band.

    Method create

      `Gnome.App Gnome.App(string appname, string|void title)`

    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

      `Gnome.App enable_layout_config(int enable)`

    Description

      Specify whether the the dock's layout configuration should be automatically saved via gnome-config whenever it changes, or not.

    Method error

      `Gnome.Dialog error(string error)`

    Description

      An important fatal error; if it appears in the statusbar, it might gdk_beep() and require acknowledgement.

    Method flash

      `Gnome.App flash(string flash)`

    Description

      Flash the message in the statusbar for a few moments; if no statusbar, do nothing. For trivial little status messages, e.g. "Auto saving..."

    Method get_dock

      `Gnome.Dock get_dock()`

    Description

      retrieved the Gnome.Dock widget contained in the App

    Method get_dock_item_by_name

      `Gnome.DockItem get_dock_item_by_name(string name)`

    Inherit Window

      inherit GTK1.Window : Window

    Method message

      `Gnome.Dialog message(string message)`

    Description

      A simple message, in an OK dialog or the status bar. Requires confirmation from the user before it goes away. Returns 0 or a dialog widget. If 0, the message is displayed in the status bar.

    Method ok_cancel

      `Gnome.App ok_cancel(string question, function(:void) callback, mixed cb_arg2)`

    Description

      Ask a ok or cancel question and call the callback when it's answered.

    Method ok_cancel_modal

      `Gnome.App ok_cancel_modal(string question, function(:void) callback, mixed cb_arg2)`

    Description

      Ask a ok or cancel question, block the application while it is asked, and call the callback when it's answered.

    Method progress_manual

      `Gnome.AppProgressKey progress_manual(string prompt)`

    Method progress_timeout

      `Gnome.AppProgressKey progress_timeout(string prompt, int interval, function(:void) cb, mixed cb_arg1)`

    Method question

      `Gnome.App question(string question, function(:void) reply_callback, mixed cb_arg2)`

    Description

      Ask a yes or no question, and call the callback when it's answered.

    Method question_modal

      `Gnome.App question_modal(string question, function(:void) callback, mixed cb_arg2)`

    Description

      Ask a yes or no question, block the application while it is asked, and call the callback when it's answered.

    Method request_password

      `Gnome.App request_password(string question, function(:void) callback, mixed cb_arg2)`

    Description

      As request string, but do not show the string

    Method request_string

      `Gnome.App request_string(string question, function(:void) callback, mixed cb_arg2)`

    Description

      Request a string, and call the callback when it's answered.

    Method set_contents

      `Gnome.App set_contents(GTK1.Widget contents)`

    Description

      Sets the status bar of the application window.

    Method set_menus

      `Gnome.App set_menus(GTK1.MenuBar menu_bar)`

    Description

      Sets the menu bar of the application window.

    Method set_statusbar

      `Gnome.App set_statusbar(GTK1.Widget statusbar)`

    Description

      Sets the status bar of the application window.

    Method set_toolbar

      `Gnome.App set_toolbar(GTK1.Toolbar toolbar)`

    Description

      Sets the main toolbar of the application window.

    Method warning

      `Gnome.Dialog warning(string warning)`

    Description

      A not-so-important error, but still marked better than a flash

  CLASS Gnome.AppProgressKey

    Description

      Wrapper for the opaque GnomeAppProgressKey type

    Method destroy

      `Gnome.AppProgressKey destroy()`

    Method done

      `Gnome.AppProgressKey done()`

    Method set

      `Gnome.AppProgressKey set(float percent)`

  CLASS Gnome.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 `Gnome.Appbar( 1, 1, Gnome.PreferencesUser )->set_progress( 0.4 );`

      Signals: clear_prompt Emitted when the prompt is cleared

      user_response Emitted when the user hits enter after a prompt

    Method clear_prompt

      `Gnome.Appbar clear_prompt()`

    Description

      Remove any prompt.

    Method clear_stack

      `Gnome.Appbar clear_stack()`

    Description

      Remove all status messages from appbar, and display default status message (if present).

    Method create

      `Gnome.Appbar Gnome.Appbar(int has_progress, int has_status, int interactivity)`

    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 Gnome.PREFERENCES_NEVER, it is never interactive. If it is set to Gnome.PREFERENCES_USER we respect user preferences from ui-properties. If it's Gnome.PREFERENCES_ALWAYS we are interactive whether the user likes it or not. Basically, if your app supports both interactive and not (for example, if you use the gnome-app-util interfaces), you should use Gnome.PREFERENCES_USER. Otherwise, use the setting you support. Please note that "interactive" mode is not functional now; GtkEntry is inadequate and so a custom widget will be written eventually.

    Method get_progress

      `GTK1.Progress get_progress()`

    Description

      Returns GTK1.Progress widget pointer, so that the progress bar may be manipulated further.

    Method get_response

      `string get_response()`

    Description

      Get the response to the prompt, if any.

    Inherit Hbox

      inherit GTK1.Hbox : Hbox

    Method pop

      `Gnome.Appbar pop()`

    Description

      Remove current status message, and display previous status message, if any. It is OK to call this with an empty stack.

    Method push

      `Gnome.Appbar push(string what)`

    Description

      Push a new status message onto the status bar stack, and display it.

    Method refresh

      `Gnome.Appbar refresh()`

    Description

      Reflect the current state of stack/default. Useful to force a set_status to disappear.

    Method set_default

      `Gnome.Appbar set_default(string default_status)`

    Description

      What to show when showing nothing else; defaults to "".

    Method set_progress

      `Gnome.Appbar set_progress(float percentage)`

    Description

      Sets progress bar to the given percentage. Pure sugar - with a bad name, in light of the get_progress name which is not the opposite of set_progress. Maybe this function should die.

    Method set_prompt

      `Gnome.Appbar set_prompt(string prompt, int modal)`

    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

      `Gnome.Appbar set_status(string status)`

    Description

      Sets the status label without changing widget state; next set or push will destroy this permanently.

  CLASS Gnome.AppletWidget

    Description

      Applets are basically GNOME applications whose window sits inside the panel. Also the panel "takes care" of the applets by providing them with session saving and restarting, window management (inside of the panel), and a context menu.

      The simplest applet one can write would be along the lines of:

           int main( int argc, array argv )
           {
             Gnome.init( "hello", "1.0", argv, 0 );
             Gnome.AppletWidget("hello")-&gt;add(GTK1.Label("Hello World!"))-&gt;show_all();
             GTK1.applet_widget_gtk_main();
           }

      This creates an applet which just sits on the panel, not really doing anything, in real life the label would be substituted by something which actually does something useful. As you can see the applet doesn't really take care of restarting itself.

      For the applet to be added to the menus, you need to install two files. Your x.gnorba file goes into $sysconfdir/CORBA/servers/ and the x.desktop file goes into $prefix/share/applets/&lt;category&gt;/.

      Example hello.desktop:

           [Desktop Entry]
            Name=Hello Applet
            Comment=An example Hello World type Applet
            Type=PanelApplet
            Exec=hello.pike
            Icon=gnome-hello.png
            Terminal=0

      Example hello.gnorba:

           [hello]
            type=exe
            repo_id=IDL:GNOME/Applet:1.0
            description=Hello Applet
            location_info=hello.pike

      One thing to keep in mind is that the Exec line for the .desktop doesn't actually get executed when the Type is PanelApplet. The Exec line should be the GOAD ID specified in the .gnorba file (the "hello" enclosed by brackets). For a simple applet all you need to do is replace the hello.pike with the name of your applet executable.

      When the user right clicks on the applet, a menu appears, this is all handeled by the panel, so in order to add items to it you use a special interface to "add callbacks" to the menu. A very simple example would be (making our hello applet even more feature full):

           void hello_there()
           {
             write( "Hello there, indeed!\n" );
           }

           int main( int argc, array argv )
           {
             Gnome.AppletWidget w;
             Gnome.init( "hello", "1.0", argv, 0 );
             w = Gnome.AppletWidget("hello");
             w-&gt;add(GTK1.Label("Hello World!"))-&gt;show_all();
             w-&gt;register_callback( "hello", "Hello there", hello_there, 0 );
             GTK1.applet_widget_gtk_main();
           }

      Now the user will see a "Hello There" menu item on the applet menu, and when selected, the applet will print "Hello There". Useful huh?

      Note that the first argument to the register_callback is just a string identifier of this callback, and can really be whatever you want. But it should NOT be translated as the label (the 2nd argument) should be.

      Signals: back_change

      change_orient

      change_pixel_size

      change_position

      tooltip_state

    Method abort_load

      `Gnome.AppletWidget abort_load()`

    Description

      Abort the applet loading, once applet has been created, this is a way to tell the panel to forget about us if we decide we want to quit before we add the actual applet to the applet-widget. This is only useful before before add() is called.

    Method add

      `Gnome.AppletWidget add(GTK1.Widget what)`

    Description

      Add a child (widget) to the applet. This finishes the handshaking with the panel started in applet_widget_new. You should never call this function twice for the same applet. If you have already created an applet widget, but need to cancel the loading of the applet, use abort_load.

    Method callback_set_sensitive

      `Gnome.AppletWidget callback_set_sensitive(string name, int sensitive)`

    Description

      Sets the sensitivity of a menu item in the applet's context menu.

    Method create

      `Gnome.AppletWidget Gnome.AppletWidget(string applet_name)`

    Description

      Make a new applet and register us with the panel, if you decide to cancel the load before calling add, you should call abort_load.

    Method get_free_space

      `int get_free_space()`

    Description

      Gets the free space left that you can use for your applet. This is the number of pixels around your applet to both sides. If you strech by this amount you will not disturb any other applets. If you are on a packed panel 0 will be returned.

    Method get_globcfgpath

      `string get_globcfgpath()`

    Method get_panel_orient

      `int get_panel_orient()`

    Description

      Gets the orientation of the panel this widget is on. it can be one of GNOME_Panel_ORIENT_DOWN, GNOME_Panel_ORIENT_LEFT, GNOME_Panel_ORIENT_RIGHT and GNOME_Panel_ORIENT_UP. This is not the position of the panel, but rather the direction that the applet should be "reaching out". So any arrows should for example point in this direction. It will be OrientUp or OrientDown for horizontal panels and OrientLeft or OrientRight for vertical panels

    Method get_panel_pixel_size

      `int get_panel_pixel_size()`

    Description

      Gets the width of the panel in pixels. This is not the actual size, but the recomended one. The panel may be streched if the applets use larger sizes then this.

    Method get_privcfgpath

      `string get_privcfgpath()`

    Inherit Plug

      inherit GTK1.Plug : Plug

    Method register_callback

      `Gnome.AppletWidget register_callback(string name, string menutext, function(:void) callback_cb, mixed callback_arg)`

    Description

      Adds a menu item to the applet's context menu. The name should be a path that is separated by '/' and ends in the name of this item. You need to add any submenus with register_callback_dir.

    Method register_callback_dir

      `Gnome.AppletWidget register_callback_dir(string name, string menutext)`

    Description

      Adds a submenu to the applet's context menu. The name should be the full path of the new submenu with the name of the new submenu as the last part of the path. The name can, but doesn't have to be terminated with a '/'.

    Method register_stock_callback

      `Gnome.AppletWidget register_stock_callback(string name, string stock_type, string menutext, function(:void) callback_cb, mixed callback_arg)`

    Description

      Adds a menu item to the applet's context menu with a stock GNOME pixmap. This works almost exactly the same as register_callback.

    Method register_stock_callback_dir

      `Gnome.AppletWidget register_stock_callback_dir(string name, string stock_type, string menutext)`

    Description

      Adds a submenu to the applet's context menu with a stock GNOME pixmap. This is similiar to register_callback_dir.

    Method remove

      `Gnome.AppletWidget remove()`

    Description

      Remove the plug from the panel, this will destroy the applet. You can only call this once for each applet.

    Method send_position

      `Gnome.AppletWidget send_position(int enable)`

    Description

      If you need to get a signal everytime this applet changes position relative to the screen, you need to run this function with TRUE for enable and bind the change_position signal on the applet. This signal can be quite CPU/bandwidth consuming so only applets which need it should use it. By default change_position is not sent.

    Method set_tooltip

      `Gnome.AppletWidget set_tooltip(string to)`

    Description

      Set a tooltip on the entire applet that will follow the tooltip setting from the panel configuration.

    Method set_widget_tooltip

      `Gnome.AppletWidget set_widget_tooltip(GTK1.Widget widget, string text)`

    Description

      Set a tooltip on the widget that will follow the tooltip setting from the panel configuration.

    Method sync_config

      `Gnome.AppletWidget sync_config()`

    Description

      Tell the panel to save our session here (just saves, no shutdown). This should be done when you change some of your config and want the panel to save it's config, you should NOT call this in the session_save handler as it will result in a locked panel, as it will actually trigger another session_save signal for you. However it also asks for a complete panel save, so you should not do this too often, and only when the user has changed some preferences and you want to sync them to disk. Theoretically you don't even need to do that if you don't mind loosing settings on a panel crash or when the user kills the session without logging out properly, since the panel will always save your session when it exists.

    Method unregister_callback

      `Gnome.AppletWidget unregister_callback(string name)`

    Description

      Remove a menu item from the applet's context menu. The name should be the full path to the menu item. This will not remove any submenus.

    Method unregister_callback_dir

      `Gnome.AppletWidget unregister_callback_dir(string name)`

    Description

      Removes a submenu from the applet's context menu. Use this instead of unregister_callback to remove submenus. The name can be, but doesn't have to be terminated with a '/'. If you have not removed the subitems of this menu, it will still be shown but without it's title or icon. So make sure to first remove any items and submenus before calling this function.

  CLASS Gnome.Calculator

    Description

      This widget provides a simple calculator that you can embed in your applications for doing quick computations.

      The widget consists of a fully functional calculator including standard arithmetic functions as well as trigonometric capabilities, exponents, factorials, nested equations, and others. `Gnome.Calculator()`

      Signals: result_changed This signal is emited by the widget when the result has been changed.

    Method clear

      `Gnome.Calculator clear(int reset)`

    Description

      Resets the calculator back to zero. If reset is TRUE, results stored in memory and the calculator mode are cleared also.

    Method create

      `Gnome.Calculator Gnome.Calculator()`

    Description

      Create a new calculator widget

    Method get_result

      `float get_result()`

    Description

      Value currently stored in calculator buffer.

    Inherit Vbox

      inherit GTK1.Vbox : Vbox

    Method set

      `Gnome.Calculator set(float result)`

    Description

      Sets the value stored in the calculator's result buffer to the given result.

  CLASS Gnome.ColorPicker

    Description

      This widget provides color selection facilities to your application. The widget appears as a button which contains a "color swatch" of the currently selected color. When the button is pressed, the widget presents the user with a color selection dialog where the color can be selected.

      You can select the color to be displayed in a number of ways: floating point values for the red, green and blue channels, integers in the range 0 to 65,535, or integers in the range 0 to 255, depending on your needs. `Gnome.ColorPicker();`

      Signals: color_set This signal is emitted when the user changes the color on the color selector. The values passed to this signal are the red, green, blue and alpha channels selected in integer form in the range 0 to 65535.

    Method create

      `Gnome.ColorPicker Gnome.ColorPicker()`

    Description

      Creates a new GNOME color picker widget. This returns a widget in the form of a small button containing a swatch representing the current selected color. When the button is clicked, a color-selection dialog will open, allowing the user to select a color. The swatch will be updated to reflect the new color when the user finishes.

    Method get

      `mapping get()`

    Description

      Returns a mapping ([ "d":([ "r":rvalue, "g":gvalue, "b":bvalue, "a":avalue ]), "i8":([ ... ]), "i16":([ .. ]) ]);

    Inherit Button

      inherit GTK1.Button : Button

    Method set_d

      `Gnome.ColorPicker set_d(float r, float g, float b, float a)`

    Description

      Set color shown in the color picker widget using floating point values. The values range between 0.0 and 1.0.

    Method set_dither

      `Gnome.ColorPicker set_dither(int dither)`

    Description

      Sets whether the picker should dither the color sample or just paint a solid rectangle.

    Method set_i16

      `Gnome.ColorPicker set_i16(int r, int g, int b, int a)`

    Description

      Set color shown in the color picker widget using integer values. The values range between 0 and 65535.

    Method set_i8

      `Gnome.ColorPicker set_i8(int r, int g, int b, int a)`

    Description

      Set color shown in the color picker widget using integer values. The values range between 0 and 255.

    Method set_title

      `Gnome.ColorPicker set_title(string title)`

    Description

      Sets the title for the color selection dialog

    Method set_use_alpha

      `Gnome.ColorPicker set_use_alpha(int use_alpha)`

    Description

      Sets whether or not the picker should use the alpha channel.

  CLASS Gnome.DateEdit

    Description

      The GnomeDateEdit widget provides a way to enter dates and times with a helper calendar to let the user select the date. `Gnome.DateEdit(time(),1,1);`

      `Gnome.DateEdit(time(),0,1);`

      Signals: date_changed

      time_changed

    Method create

      `Gnome.DateEdit Gnome.DateEdit(int the_time, int show_time, int use_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_date

      `int get_date()`

    Description

      Returns the configured time

    Inherit Hbox

      inherit GTK1.Hbox : Hbox

    Method set_popup_range

      `Gnome.DateEdit set_popup_range(int low_hour, int high_hour)`

    Description

      Sets the range of times that will be provide by the time popup selectors.

    Method set_time

      `Gnome.DateEdit set_time(int the_time)`

    Description

      Changes the displayed date and time in the GnomeDateEdit widget to be the one represented by the_time.

  CLASS Gnome.Dialog

    Description

      Gnome.Dialog gives dialogs a consistent look and feel, while making them more convenient to program. Gnome.Dialog makes it easy to use stock buttons, makes it easier to handle delete_event, and adds some cosmetic touches (such as a separator above the buttons, and a bevel around the edge of the window).

      Signals: clicked

      close

    Method append_button_with_pixmap

      `Gnome.Dialog append_button_with_pixmap(string name, string pixmap_file)`

    Method button_connect

      `Gnome.Dialog button_connect(int button, function(:void) callback_cb, mixed callback_arg)`

    Description

      Simply a signal_connect to the "clicked" signal of the specified button.

    Method close

      `Gnome.Dialog close()`

    Description

      See also close_hides(). This function emits the "close" signal( which either hides or destroys the dialog (destroy by default). If you connect to the "close" signal, and your callback returns TRUE, the hide or destroy will be blocked. You can do this to avoid closing the dialog if the user gives invalid input, for example.

      Using close() in place of hide() or destroy() allows you to easily catch all sources of dialog closure, including delete_event and button clicks, and handle them in a central location.

    Method create

      `Gnome.Dialog Gnome.Dialog(string title, string ... buttons)`

    Description

      Creates a new Gnome.Dialog, with the given title, and any button names in the arg list. Buttons can be simple names, such as "My Button", or gnome-stock defines such as GNOME.StockButtonOK, etc. The last argument should be NULL to terminate the list.

      Buttons passed to this function are numbered from left to right, starting with 0. So the first button in the arglist is button 0, then button 1, etc. These numbers are used throughout the Gnome.Dialog API.

    Method editable_enters

      `Gnome.Dialog editable_enters(GTK1.Editable widget)`

    Description

      Normally if there's an editable widget (such as GtkEntry) in your dialog, pressing Enter will activate the editable rather than the default dialog button. However, in most cases, the user expects to type something in and then press enter to close the dialog. This function enables that behavior.

    Method get_vbox

      `GTK1.Vbox get_vbox()`

    Inherit Window

      inherit GTK1.Window : Window

    Method run

      `int run()`

    Description

      Blocks until the user clicks a button or closes the dialog with the window manager's close decoration (or by pressing Escape).

      You need to set up the dialog to do the right thing when a button is clicked or delete_event is received; you must consider both of those possibilities so that you know the status of the dialog when run() returns. A common mistake is to forget about Escape and the window manager close decoration; by default, these call close(), which by default destroys the dialog. If your button clicks do not destroy the dialog, you don't know whether the dialog is destroyed when run() returns. This is bad.

      So you should either close the dialog on button clicks as well, or change the close() behavior to hide instead of destroy. You can do this with close_hides().

    Method run_and_close

      `int run_and_close()`

    Description

      See run(). The only difference is that this function calls close() before returning if the dialog was not already closed.

    Method set_accelerator

      `Gnome.Dialog set_accelerator(int button, int accelerator_key, int accelerator_mode)`

    Method set_close

      `Gnome.Dialog set_close(int click_closes)`

    Description

      This is a convenience function so you don't have to connect callbacks to each button just to close the dialog. By default, Gnome.Dialog has this parameter set the FALSE and it will not close on any click. (This was a design error.) However, almost all the Gnome.Dialog subclasses, such as Gnome.MessageBox and Gnome.PropertyBox, have this parameter set to TRUE by default.

    Method set_default

      `Gnome.Dialog set_default(int button)`

    Description

      The default button will be activated if the user just presses return. Usually you should make the least-destructive button the default. Otherwise, the most commonly-used button.

    Method set_parent

      `Gnome.Dialog set_parent(GTK1.Window parent)`

    Description

      Dialogs have "parents," usually the main application window which spawned them. This function will let the window manager know about the parent-child relationship. Usually this means the dialog must stay on top of the parent, and will be minimized when the parent is. Gnome also allows users to request dialog placement above the parent window (vs. at the mouse position, or at a default window manger location).

    Method set_sensitive

      `Gnome.Dialog set_sensitive(int button, int sensitive)`

    Description

      Calls set_sensitive() on the specified button number.

  CLASS Gnome.Dock

    Description

      GnomeDock is a container widget designed to let users move around widgets such as toolbars, menubars and so on.

      Every GnomeDock contains a widget called the "client area". On the four sides of the client area, there are four "dock areas", which can contain an arbitrary number of dockable widgets. All the dockable widgets should be GnomeDockItem widgets; the GnomeDockItem widget can in turn contain any kind of widget, and implements the dragging functionality: every GnomeDockItem has a handle that users can use to move them within the dock, or even move them outside it, so that they become "floating items".

      Every "dock area" is implemented by means of zero or more "dock bands": a dock band is a horizontal or vertical stripe containing one or more dock items, and is implemented by the GnomeDockBand widget. Items are ordered from top to bottom in vertical bands, and from left to right in horizontal bands. Every dock item in a band is given an offset value that defines the distance, in pixels, from the previous item in the same band; if the item is first in the band, the offset defines the distance from the start of the band.

      As a consequence, the position of an item in the dock can be specified by means of the following values: a "placement" specifying what area is being used (top, bottom, left, right), a "band number" specifying the number of the band within the specified area, a "position" within the band and a "offset" from the previous item in the same band.

      Signals: layout_changed

    Method add_floating_item

      `Gnome.Dock add_floating_item(Gnome.DockItem item, int x, int y, int orientation)`

    Description

      Add item to dock and make it floating at the specified (x, y) coordinates (relative to the root window of the screen).

    Method add_item

      `Gnome.Dock add_item(Gnome.DockItem item, int placement, int band_num, int position, int offset, int new_band)`

    Description

      Add item to dock. placement can be either Gnome.DOCK_TOP, Gnome.DOCK_RIGHT, Gnome.DOCK_BOTTOM or Gnome.DOCK_LEFT, and specifies what area of the dock should contain the item. If in_new_band is TRUE, a new dock band is created at the position specified by band_num; otherwise, the item is added to the band_num'th band.

    Method allow_floating_items

      `Gnome.Dock allow_floating_items(int allow)`

    Method create

      `Gnome.Dock Gnome.Dock()`

    Method get_client_area

      `GTK1.Widget get_client_area()`

    Method get_item_by_name

      `Gnome.DockItem get_item_by_name(string name)`

    Inherit Container

      inherit GTK1.Container : Container

    Method set_client_area

      `Gnome.Dock set_client_area(GTK1.Widget area)`

    Description

      Specify a widget for the dock's client area.

  CLASS Gnome.DockBand

    Description

      Gnome.DockBand is a widget implementing a "dock band", i.e. a horizontal or vertical stripe containing dockable widgets.

      The application programmer does not normally need to use Gnome.DockBand directly; they are mostly used by the W(GnomeDock) widget to implement its functionality. For an explanation of the way dock bands are used within a dock, check out the documentation for the W(GnomeDock) widget.

    Method append

      `int append(Gnome.DockItem child, int offset)`

    Description

      Add child to the band with the specified offset as the last element.

    Method create

      `Gnome.DockBand Gnome.DockBand()`

    Description

      Create a new Gnome.DockBand widget.

    Method get_child_offset

      `int get_child_offset(GTK1.Widget child)`

    Description

      Retrieve the offset of the child

    Method get_item_by_name

      `Gnome.DockItem get_item_by_name(string name)`

    Description

      Retrieve a named item from the band.

    Method get_num_children

      `int get_num_children()`

    Description

      Retrieve the number of children

    Method get_orientation

      `int get_orientation()`

    Description

      Retrieve the orientation

    Inherit Container

      inherit GTK1.Container : Container

    Method insert

      `int insert(Gnome.DockItem child, int offset, int position)`

    Description

      Add child to the band at the specified position, with the specified offset from the previous item (or from the beginning of the band, if this is the first item).

    Method layout_add

      `Gnome.DockBand layout_add(Gnome.DockLayout layout, int placement, int band_num)`

    Method prepend

      `int prepend(Gnome.DockItem child, int offset)`

    Description

      Add child to the band with the specified offset as the first element.

    Method set_child_offset

      `Gnome.DockBand set_child_offset(GTK1.Widget child, int offset)`

    Description

      Set the offset for the specified child of the band.

    Method set_orientation

      `Gnome.DockBand set_orientation(int orientation)`

    Description

      Set the orientation.

  CLASS Gnome.DockItem

    Method create

      `Gnome.DockItem Gnome.DockItem(string name, int behavior)`

    Description

      Create a new GnomeDockItem named name, with the specified behavior. Gnome.DockItemBehExclusive specifies that the dock item is always the only one in its band. Gnome.DockItemBehNeverFloating specifies that users cannot detach the dock item from the dock. Gnome.DockItemBehNeverVertical specifies that the dock item must be kept horizontal, and users cannot move it to a vertical band. Gnome.DockItemBehNeverHorizontal specifies that the dock item must be kept horizontal, and users cannot move it to a vertical band. Gnome.DockItemBehLocked specifies that users cannot drag the item around.

    Method get_behavior

      `int get_behavior()`

    Method get_child

      `GTK1.Widget get_child()`

    Description

      Retrieve the child of the item.

    Method get_name

      `string get_name()`

    Description

      Retrieve the name

    Method get_orientation

      `int get_orientation()`

    Method get_shadow_type

      `int get_shadow_type()`

    Description

      One of SHADOW_ETCHED_IN, SHADOW_ETCHED_OUT, SHADOW_IN, SHADOW_NONE and SHADOW_OUT

    Inherit Bin

      inherit GTK1.Bin : Bin

    Method set_orientation

      `Gnome.DockItem set_orientation(int orientation)`

    Method set_shadow_type

      `Gnome.DockItem set_shadow_type(int shadow_type)`

    Description

      One of SHADOW_ETCHED_IN, SHADOW_ETCHED_OUT, SHADOW_IN, SHADOW_NONE and SHADOW_OUT

  CLASS Gnome.DockLayout

    Description

      The Gnome.DockLayout widget is meant to make it simple for programmers to handle the layout of a GnomeDock widget.

      Gnome.DockLayout can contain an arbitrary number of W(Gnome.DockItem) widgets, each of them with its own placement information. It is possible to "extract" a layout from an existing W(GnomeDock) widget, as well as adding the items present in a Gnome.DockLayout to it. Moreover, Gnome.DockLayout is able to create a layout configuration string that can be later used to re-construct the layout on a brand new Gnome.DockLayout widget.

      As a consequence, Gnome.DockLayout is very useful to save and retrieve W(GnomeDock) configurations into files. For example, W(GnomeApp) uses Gnome.DockLayout to create a default layout configuration, override it with the user-specific configuration file, and finally apply it to it's W(GnomeDock).

    Method add_floating_item

      `int add_floating_item(Gnome.DockItem item, int x, int y, int orientation)`

    Description

      Add item to the layout as a floating item with the specified (x, y) position and orientation.

    Method add_item

      `int add_item(Gnome.DockItem item, int placement, int band_num, int band_position, int offset)`

    Description

      Add item to the layout with the specified parameters.

    Method add_to_dock

      `int add_to_dock(Gnome.Dock dock)`

    Description

      Add all the items in this layout to the specified dock

    Method create

      `Gnome.DockLayout Gnome.DockLayout()`

    Description

      Create a new Gnome.DockLayout widget.

    Method create_string

      `string create_string()`

    Description

      Generate a string describing the layout

    Method get_item

      `Gnome.DockLayoutItem get_item(Gnome.DockItem item)`

    Description

      Retrieve a dock layout item.

    Method get_item_by_name

      `Gnome.DockLayoutItem get_item_by_name(string name)`

    Description

      Retrieve the dock layout item named name

    Inherit Object

      inherit GTK1.Object : Object

    Method parse_string

      `Gnome.DockLayout parse_string(string str)`

    Description

      Parse the layout string str, and move around the items in layout accordingly.

    Method remove_item

      `int remove_item(Gnome.DockItem item)`

    Description

      Remove the specified item from the layout.

    Method remove_item_by_name

      `int remove_item_by_name(string name)`

    Description

      Remove the specified item from the layout.

  CLASS Gnome.DockLayoutItem

    Description

      Information about an item in a gnome_dock_layout

    Method get_item

      `Gnome.DockItem get_item()`

    Description

      The W(gnome_dock_item) this information applies to.

    Method get_placement

      `int get_placement()`

    Description

      One of

    Method position

      `mapping position()`

    Description

      Get the position of the item

  CLASS Gnome.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 Gnome.Druid widget, and the set of W(Gnome.DruidPage) widgets. The Gnome.Druid widget is the main widget that interacts with the user. It has a Next, a Prev, and a Cancel button, and acts as a container for the pages. It is not a top-level window, so it needs to be put in a W(GTK1.Window) in almost all cases. The W(Gnome.DruidPage) is a virtual widget, from which all of the actual content of the page inherits from. There are currently three of these available within gnome-libs.

      GNOME druids are fairly simple to program with. You start by creating a GnomeDruid into which you put all of your pages. This widget will handle the presentation of the W(GnomeDruidPage) widgets.

      You then create all appropriate W(GnomeDruidPage) widgets. There are three implementations of these, although there is no reason why more couldn't be written. They are the W(GnomeDruidPageStart), the W(GnomeDruidPageStandard), and the W(GnomeDruidPageFinish). The W(GnomeDruidPageStandard) acts as a W(Container), and is probably the most commonly used druid page. The other ones, as their names might suggest, are used at the endpoints of the druid. More information on the specific properties of these widgets can be found on their respective pages.

      You will need to add the pages to the druid in order for them to appear. The druid itself keeps an internal list of all pages, and using the prepend_page(), append_page(), and insert_page() functions will place them into it.

      Signals: cancel This signal is emitted when the "cancel" button has been pressed. Note that the current druid page has the option to trap the signal and use it, if need be, preventing this signal from being emitted.

    Method append_page

      `Gnome.Druid append_page(Gnome.DruidPage page)`

    Description

      This will append a GnomeDruidPage into the internal list of pages that the druid has.

    Method create

      `Gnome.Druid Gnome.Druid()`

    Description

      Create a new druid

    Inherit Container

      inherit GTK1.Container : Container

    Method insert_page

      `Gnome.Druid insert_page(Gnome.DruidPage back_page, Gnome.DruidPage page)`

    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

      `Gnome.Druid prepend_page(Gnome.DruidPage page)`

    Description

      This will prepend a GnomeDruidPage into the internal list of pages that the druid has.

    Method set_buttons_sensitive

      `Gnome.Druid set_buttons_sensitive(int beck_sensitive, int next_sensitive, int cancel_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

      `Gnome.Druid set_page(Gnome.DruidPage page)`

    Description

      This will make page the currently showing page in the druid. page must already be in the druid.

    Method set_show_finish

      `Gnome.Druid set_show_finish(int show_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".

  CLASS Gnome.DruidPage

    Description

      This widget is a virtual widget to define the interface to a druid page. It's descendants are placed in a W(Gnome.Druid) widget.

      Signals: back

      cancel

      finish

      next

      prepare

    Inherit Bin

      inherit GTK1.Bin : Bin

  CLASS Gnome.DruidPageFinish

    Description

      This is a W(GnomeDruidPage).

    Method create

      `Gnome.DruidPageFinish Gnome.DruidPageFinish()`

    Description

      Creates a new Gnome.DruidPageStandard widget.

    Inherit DruidPage

      inherit Gnome.DruidPage : DruidPage

    Method set_bg_color

      `Gnome.DruidPageFinish set_bg_color(GDK1.Color color)`

    Description

      This will set the background color to be the specified color.

    Method set_logo_bg_color

      `Gnome.DruidPageFinish set_logo_bg_color(GDK1.Color color)`

    Description

      This will set the background color of the logo

    Method set_text

      `Gnome.DruidPageFinish set_text(string text)`

    Description

      Set the text

    Method set_text_color

      `Gnome.DruidPageFinish set_text_color(GDK1.Color color)`

    Description

      Set the text color

    Method set_textbox_color

      `Gnome.DruidPageFinish set_textbox_color(GDK1.Color color)`

    Description

      This will set the textbox color to be the specified color.

    Method set_title

      `Gnome.DruidPageFinish set_title(string title)`

    Description

      Set the title

    Method set_title_color

      `Gnome.DruidPageFinish set_title_color(GDK1.Color color)`

    Description

      Set the title color

  CLASS Gnome.DruidPageStandard

    Description

      This is a W(GnomeDruidPage).

    Method create

      `Gnome.DruidPageStandard Gnome.DruidPageStandard()`

    Description

      Creates a new Gnome.DruidPageStandard widget.

    Inherit DruidPage

      inherit Gnome.DruidPage : DruidPage

    Method set_bg_color

      `Gnome.DruidPageStandard set_bg_color(GDK1.Color color)`

    Description

      This will set the background color to be the specified color.

    Method set_logo_bg_color

      `Gnome.DruidPageStandard set_logo_bg_color(GDK1.Color color)`

    Description

      This will set the background color of the logo

    Method set_title

      `Gnome.DruidPageStandard set_title(string title)`

    Description

      Set the title

    Method set_title_color

      `Gnome.DruidPageStandard set_title_color(GDK1.Color color)`

    Description

      Set the title color

  CLASS Gnome.DruidPageStart

    Description

      This is a W(GnomeDruidPage). It is meant to be used to introduce the user to what is being installed in a consistent manner.

    Method create

      `Gnome.DruidPageStart Gnome.DruidPageStart()`

    Description

      Creates a new Gnome.DruidPageStart widget.

    Inherit DruidPage

      inherit Gnome.DruidPage : DruidPage

    Method set_bg_color

      `Gnome.DruidPageStart set_bg_color(GDK1.Color color)`

    Description

      This will set the background color to be the specified color.

    Method set_logo_bg_color

      `Gnome.DruidPageStart set_logo_bg_color(GDK1.Color color)`

    Description

      This will set the background color of the logo

    Method set_text

      `Gnome.DruidPageStart set_text(string text)`

    Description

      Set the text

    Method set_text_color

      `Gnome.DruidPageStart set_text_color(GDK1.Color color)`

    Description

      Set the text color

    Method set_textbox_color

      `Gnome.DruidPageStart set_textbox_color(GDK1.Color color)`

    Description

      This will set the textbox color to be the specified color.

    Method set_title

      `Gnome.DruidPageStart set_title(string title)`

    Description

      Set the title

    Method set_title_color

      `Gnome.DruidPageStart set_title_color(GDK1.Color color)`

    Description

      Set the title color

  CLASS Gnome.Entry

    Description

      This widget is a wrapper around the GtkEntry widget, but it provides a history mechanism for all the input entered into the widget. The way this works is that a special identifier is provided when creating the GnomeEntry widget, and this identifier is used to load and save the history of the text.

      `Gnome.Entry( "history" )`

    Method append_history

      `Gnome.Entry append_history(int save, string text)`

    Description

      Adds a history item of the given text to the tail of the history list inside gentry. If save is TRUE, the history item will be saved in the config file (assuming that gentry's history id is not 0).

    Method create

      `Gnome.Entry Gnome.Entry(string|void history_id)`

    Description

      Creates a new GnomeEntry widget. If history_id is not 0, then the history list will be saved and restored between uses under the given id.

    Method gtk_entry

      `GTK1.Entry gtk_entry()`

    Description

      Obtain pointer to Gnome.Entry's internal GTK1.Entry text entry

    Inherit Combo

      inherit GTK1.Combo : Combo

    Method load_history

      `Gnome.Entry load_history()`

    Description

      Loads a stored history list from the GNOME config file, if one is available. If the history id of gentry is 0, nothing occurs.

    Method prepend_history

      `Gnome.Entry prepend_history(int save, string text)`

    Description

      Adds a history item of the given text to the head of the history list inside gentry. If save is TRUE, the history item will be saved in the config file (assuming that gentry's history id is not 0).

    Method save_history

      `Gnome.Entry save_history()`

    Description

      Force the history items of the widget to be stored in a configuration file. If the history id of gentry is 0, nothing occurs.

    Method set_history_id

      `Gnome.Entry set_history_id(string|void history_id)`

    Description

      Set or clear the history id of the GnomeEntry widget. If history_id is 0, the widget's history id is cleared. Otherwise, the given id replaces the previous widget history id.

  CLASS Gnome.FileEntry

    Description

      This widget provides an entry box with history (a W(GnomeEntry)) and a button which can pop up a file selector dialog box W(GtkFileSelection). It also accepts DND drops from the filemanager and other sources. `Gnome.FileEntry("","")`

      Signals: browse_clicked Signal emitted when the "browse" button is clicked. This is so that you can add stuff to the file selector or to override this method.

    Method create

      `Gnome.FileEntry Gnome.FileEntry(string history_id, string browse_dialog_title)`

    Description

      Creates a new Gnome.FileEntry widget.

    Method get_full_path

      `string get_full_path(int file_must_exist)`

    Description

      Gets the full absolute path of the file from the entry. If file_must_exist is false, nothing is tested and the path is returned. If file_must_exist is true, then the path is only returned if the path actually exists. In case the entry is a directory entry (see set_directory), then if the path exists and is a directory then it's returned; if not, it is assumed it was a file so we try to strip it, and try again.

    Method gnome_entry

      `Gnome.Entry gnome_entry()`

    Description

      Get the W(GnomeEntry) component of the widget for lower-level manipulation.

    Method gtk_entry

      `GTK1.Entry gtk_entry()`

    Description

      Get the W(Entry) component of the widget for lower-level manipulation.

    Inherit Hbox

      inherit GTK1.Hbox : Hbox

    Method set_default_path

      `Gnome.FileEntry set_default_path(string path)`

    Description

      Set the default path of browse dialog to path. The default path is only used if the entry is empty or if the current path of the entry is not an absolute path, in which case the default path is prepended to it before the dialog is started.

    Method set_directory

      `Gnome.FileEntry set_directory(int directory_entry)`

    Description

      Sets whether this is a directory only entry. If directory_entry is true, then get_full_path will check for the file being a directory, and the browse dialog will have the file list disabled.

    Method set_modal

      `Gnome.FileEntry set_modal(int is_modal)`

    Description

      Sets the modality of the browse dialog.

    Method set_title

      `Gnome.FileEntry set_title(string browse_dialog_title)`

    Description

      Set the title of the browse dialog to browse_dialog_title. The new title will go into effect the next time the browse button is pressed.

  CLASS Gnome.FontPicker

    Description

      GnomeFontPicker - Button that displays current font; click to select new font. `Gnome.FontPicker();`

      `Gnome.FontPicker()->set_mode( Gnome.FontPickerModeFontInfo );`

      Signals: font_set

    Method create

      `Gnome.FontPicker Gnome.FontPicker()`

    Description

      Create a new font pick button

    Method fi_set_show_size

      `Gnome.FontPicker fi_set_show_size(int show_size)`

    Description

      If show_size is TRUE, font size will be displayed along with font chosen by user. This only applies if current button mode is Gnome.FontPickerModeFontInfo.

    Method fi_set_use_font_in_label

      `Gnome.FontPicker fi_set_use_font_in_label(int use_font_in_label, int size)`

    Description

      If use_font_in_label is TRUE, font name will be written using font chosen by user and using size passed to this function. This only applies if current button mode is Gnome.FontPickerModeFontInfo.

    Method get_font

      `GDK1.Font get_font()`

    Description

      Retrieves the font from the font selection dialog.

    Method get_font_name

      `string get_font_name()`

    Description

      Retrieve name of font from font selection dialog.

    Method get_mode

      `int get_mode()`

    Description

      Returns current font picker button mode (or what to show).

    Method get_preview_text

      `string get_preview_text()`

    Description

      Retrieve preview text from font selection dialog if available.

    Inherit Button

      inherit GTK1.Button : Button

    Method set_font_name

      `int set_font_name(string fontname)`

    Description

      Set or update the currently displayed font in the font picker dialog

    Method set_mode

      `Gnome.FontPicker set_mode(int mode)`

    Description

      Set value of subsequent font picker button mode (or what to show). Mode is one of GNOME_FONT_PICKER_MODE_FONT_INFO, GNOME_FONT_PICKER_MODE_PIXMAP, GNOME_FONT_PICKER_MODE_UNKNOWN and GNOME_FONT_PICKER_MODE_USER_WIDGET

    Method set_preview_text

      `Gnome.FontPicker set_preview_text(string text)`

    Description

      Set preview text in font picker, and in font selection dialog if one is being displayed.

    Method set_title

      `Gnome.FontPicker set_title(string title)`

    Description

      Sets the title for the font selection dialog.

    Method uw_set_widget

      `Gnome.FontPicker uw_set_widget(GTK1.Widget widget)`

    Description

      Set the user-supplied widget as the inside of the font picker. This only applies with Gnome.FontPickerModeUserWidget.

  CLASS Gnome.Href

    Description

      This widget is a GtkButton button that contains a URL. When clicked it invokes the configured browser for the URL you provided.

      `Gnome.Href( "http://www.gnome.org", "GNOME Web Site" )`

      `Gnome.Href( "http://www.gnome.org" )`

    Method create

      `Gnome.Href Gnome.Href(string url, string|void label)`

    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_label

      `string get_label()`

    Description

      Returns the contents of the label widget used to display the link text.

    Method get_url

      `string get_url()`

    Description

      Return the url

    Inherit Button

      inherit GTK1.Button : Button

    Method set_label

      `Gnome.Href set_label(string label)`

    Description

      Sets the internal label widget text (used to display a URL's link text) to the given value.

    Method set_url

      `Gnome.Href set_url(string url)`

    Description

      Sets the internal URL

  CLASS Gnome.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.

    Method create

      `Gnome.IconEntry Gnome.IconEntry(string history_id, string title)`

    Description

      Creates a new icon entry widget

    Method get_filename

      `string get_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 gnome_entry

      `Gnome.Entry gnome_entry()`

    Description

      Get the W(GnomeEntry) widget that's part of the entry

    Method gnome_file_entry

      `Gnome.FileEntry gnome_file_entry()`

    Description

      Get the W(GnomeFileEntry) widget that's part of the entry

    Method gtk_entry

      `GTK1.Entry gtk_entry()`

    Description

      Get the W(Entry) widget that's part of the entry

    Inherit Vbox

      inherit GTK1.Vbox : Vbox

    Method set_pixmap_subdir

      `Gnome.IconEntry set_pixmap_subdir(string subdir)`

    Description

      Sets the subdirectory below gnome's default pixmap directory to use as the default path for the file entry.

  CLASS Gnome.IconList

    Description

      The GNOME icon list widget can hold a number of icons with captions. The icons on the list can be selected (various selection methods are supported). The programmer can enable caption-editing for the icons. This parameters is configured when you create the icon list widget. You can control the type of selection mode you desire by using the set_selection_mode() function.

      Signals: select_icon

      text_changed

      unselect_icon

    Method append

      `Gnome.IconList append(string icon_filename, string text)`

    Description

      Appends an icon to the specified icon list. The icon's image is loaded from the specified file, and it is inserted at the pos index.

    Method clear

      `Gnome.IconList clear()`

    Description

      Clears the contents for the icon list by removing all the icons. If destroy handlers were specified for any of the icons, they will be called with the appropriate data.

    Method create

      `Gnome.IconList Gnome.IconList(int icon_widt, int flags)`

    Description

      Creates a new icon list widget. The icon columns are allocated a width of icon_width pixels. Icon captions will be word-wrapped to this width as well.

      If flags has the Gnome.IconListIsEditable flag set, then the user will be able to edit the text in the icon captions, and the "text_changed" signal will be emitted when an icon's text is changed.

    Method find_icon_from_data

      `int find_icon_from_data(object data)`

    Description

      Find a icon in the list that has the given user data. If no icon is found, -1 is returned.

    Method freeze

      `Gnome.IconList freeze()`

    Description

      Freezes an icon list so that any changes made to it will not be reflected on the screen until it is thawed with thaw(). It is recommended to freeze the icon list before inserting or deleting many icons, for example, so that the layout process will only be executed once, when the icon list is finally thawed.

      You can call this function multiple times, but it must be balanced with the same number of calls to thaw() before the changes will take effect.

    Method get_icon_at

      `int get_icon_at(int x, int y)`

    Description

      Returns the index of the icon that is under the specified coordinates, which are relative to the icon list's window. If there is no icon in that position, -1 is returned.

    Method get_icon_data

      `object get_icon_data(int icon)`

    Description

      Return the data associated with a icon, or 0.

    Method get_selected_icons

      `array get_selected_icons()`

    Description

      Return an array with the currently selected icons

    Method icon_is_visible

      `int icon_is_visible(int pos)`

    Description

      returns 1 if the icon whose index is pos is visible.

    Inherit Widget

      inherit GTK1.Widget : Widget

    Method insert

      `Gnome.IconList insert(int pos, string icon_filename, string text)`

    Description

      Inserts an icon in the specified icon list. The icon's image is loaded from the specified file, and it is inserted at the pos index.

    Method moveto

      `Gnome.IconList moveto(int pos, float yalign)`

    Description

      Makes the icon whose index is pos be visible on the screen. The icon list gets scrolled so that the icon is visible. An alignment of 0.0 represents the top of the visible part of the icon list, and 1.0 represents the bottom. An icon can be centered on the icon list using 0.5 as the yalign.

    Method remove

      `Gnome.IconList remove(int pos)`

    Description

      Removes the icon at index position pos. If a destroy handler was specified for that icon, it will be called with the appropriate data.

    Method select_icon

      `Gnome.IconList select_icon(int idx)`

    Description

      Selects the specified icon.

    Method set_col_spacing

      `Gnome.IconList set_col_spacing(int pixels)`

    Description

      Sets the spacing to be used between columns of icons.

    Method set_hadjustment

      `Gnome.IconList set_hadjustment(GTK1.Adjustment hadj)`

    Description

      Sets the adjustment to be used for horizontal scrolling. This is normally not required, as the icon list can be simply inserted in a W(ScrolledWindow) and scrolling will be handled automatically.

    Method set_icon_border

      `Gnome.IconList set_icon_border(int pixels)`

    Description

      Set the width of the border to be displayed around an icon's image. This is currently not implemented.

    Method set_icon_data

      `Gnome.IconList set_icon_data(int icon, object data)`

    Description

      Set the user data associated with the specified icon. This data can be used to find icons, and when an icon is selected it can be easily retrieved using get_icon_data.

      You can only use objects as icon data right now

    Method set_icon_width

      `Gnome.IconList set_icon_width(int w)`

    Description

      Sets the amount of horizontal space allocated to the icons, i.e. the column width of the icon list

    Method set_row_spacing

      `Gnome.IconList set_row_spacing(int pixels)`

    Description

      Sets the spacing to be used between rows of icons.

    Method set_selection_mode

      `Gnome.IconList set_selection_mode(int mode)`

    Description

      One of SELECTION_BROWSE, SELECTION_EXTENDED, SELECTION_MULTIPLE and SELECTION_SINGLE.

    Method set_separators

      `Gnome.IconList set_separators(string sep)`

    Description

      Set the characters that can be used as word separators when doing word-wrapping of the text captions.

    Method set_text_spacing

      `Gnome.IconList set_text_spacing(int pixels)`

    Description

      Sets the spacing to be used between the icon and its caption

    Method set_vadjustment

      `Gnome.IconList set_vadjustment(GTK1.Adjustment hadj)`

    Description

      Sets the adjustment to be used for vertical scrolling. This is normally not required, as the icon list can be simply inserted in a W(ScrolledWindow) and scrolling will be handled automatically.

    Method thaw

      `Gnome.IconList thaw()`

    Description

      Unfreeze the icon list

    Method unselect_all

      `Gnome.IconList unselect_all()`

    Description

      Unselect all icons.

    Method unselect_icon

      `Gnome.IconList unselect_icon(int idx)`

    Description

      Unselects the specified icon.

  CLASS Gnome.IconSelection

    Method add_defaults

      `Gnome.IconSelection add_defaults()`

    Description

      Adds the default pixmap directory into the selection widget.

    Method add_directory

      `Gnome.IconSelection add_directory(string dir)`

    Description

      Adds the icons from the directory dir to the selection widget.

    Method clear

      `Gnome.IconSelection clear(int|void not_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

      `Gnome.IconSelection Gnome.IconSelection()`

    Description

      reates a new icon selection widget, it uses a W(GnomeIconList) for the listing of icons

    Method get_icon

      `string get_icon(int full_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.

    Inherit Vbox

      inherit GTK1.Vbox : Vbox

    Method select_icon

      `Gnome.IconSelection select_icon(string filename)`

    Description

      Selects the icon filename. This icon must have already been added and shown

    Method show_icons

      `Gnome.IconSelection show_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.

  CLASS Gnome.Less

    Description

      This widget implements a graphical "more" command. It allows the user to view a text file. There are various possible ways to specify the contents to display: loading the data from a file (by providing a filename) or by loading it from an open file data stream or from the output of a Unix command.

      `Gnome.Less()->show_string("Example string\nshown in this\nwidget")`

      `Gnome.Less()->show_file("/usr/dict/words" );`

      `Gnome.Less()->show_command( "psrinfo -v" )`

    Method clear

      `Gnome.Less clear()`

    Description

      Clears all the text

    Method create

      `Gnome.Less Gnome.Less()`

    Description

      Creates a new GnomeLess widget.

    Inherit Vbox

      inherit GTK1.Vbox : Vbox

    Method reshow

      `Gnome.Less reshow()`

    Description

      Re-displays all of the text in the GnomeLess widget gl. If the font has changed since the last show/reshow of text, it will update the current text to the new font.

    Method set_fixed_font

      `Gnome.Less set_fixed_font(int fixed)`

    Description

      Specifies whether or not new text should be displayed using a fixed font. Pass TRUE in fixed to use a fixed font, or FALSE to revert to the default GtkText font.

      Note: This will not affect text already being displayed. If you use this function after adding text to the widget, you must show it again by using gnome_less_reshow or one of the gnome_less_show commands.

    Method set_font

      `Gnome.Less set_font(GDK1.Font font)`

    Description

      Sets the font of the text to be displayed in the GnomeLess widget gl to font. Note: This will not affect text already being displayed. If you use this function after adding text to the widget, you must show it again by using reshow or one of the show commands.

    Method show_command

      `Gnome.Less show_command(string command_line)`

    Description

      Runs the shell command specified in command_line, and places the output of that command in the GnomeLess widget specified by gl. Replaces any text already being displayed in the widget.

    Method show_file

      `Gnome.Less show_file(string file)`

    Description

      Displays a file in a GnomeLess widget. Replaces any text already being displayed in the widget.

    Method show_filestream

      `Gnome.Less show_filestream(Stdio.File stream)`

    Method show_string

      `Gnome.Less show_string(string data)`

    Description

      Displays a string in the GnomeLess widget gl. Replaces any text already being displayed.

    Method write_file

      `int write_file(string path)`

    Description

      Writes the text displayed in the GnomeLess widget gl to the file specified by path.

    Method write_filestream

      `int write_filestream(Stdio.File fd)`

  CLASS Gnome.MessageBox

    Description

      The GnomeMessageBox widget creates dialog boxes (of type GnomeDialog) that contain a severity level (indicated by an icon and a title), a message to be displayed and a list of buttons that will be in the dialog.

      The programmer will use strings desired for each button. If the strings are any of the GNOME_STOCK macros, then instead of creating a button with the text, the button will be a GNOME stock button with a stock icon.

      The list of known types for message boxes are: GNOME_MESSAGE_BOX_ERROR, GNOME_MESSAGE_BOX_GENERIC, GNOME_MESSAGE_BOX_INFO, GNOME_MESSAGE_BOX_QUESTION and GNOME_MESSAGE_BOX_WARNING. `Gnome.MessageBox( "This is a nice message", Gnome.MessageBoxInfo, Gnome.StockButtonOk, Gnome.StockButtonCancel );`

      `Gnome.MessageBox( "This is another not so nice message", Gnome.MessageBoxError, Gnome.StockButtonClose, Gnome.StockButtonCancel );`

    Method create

      `Gnome.MessageBox Gnome.MessageBox(string message, string messagebox_type, string ... buttons)`

    Description

      Creates a dialog box of type message_box_type with message. A number of buttons are inserted on it. You can use the GNOME stock identifiers to create gnome stock buttons.

    Inherit Dialog

      inherit Gnome.Dialog : Dialog

  CLASS Gnome.NumberEntry

    Description

      Provides an entry line for numbers. This routine does not attempt to do any validation on the valid number ranges, but provides a button that will let the user bring up a calculator to fill in the value of the entry widget. `Gnome.NumberEntry("", "Select a number...");`

    Method create

      `Gnome.NumberEntry Gnome.NumberEntry(string history_id, string calc_dialog_title)`

    Description

      Creates a new number entry widget, with a history id and title for the calculator dialog.

    Method get_number

      `float get_number()`

    Description

      Get the current number from the entry

    Method gnome_entry

      `Gnome.Entry gnome_entry()`

    Description

      Get the W(GnomeEntry) component of the Gnome.NumberEntry for lower-level manipulation.

    Method gtk_entry

      `GTK1.Entry gtk_entry()`

    Description

      Get the W(Entry) component of the Gnome.NumberEntry for Gtk+-level manipulation.

    Inherit Hbox

      inherit GTK1.Hbox : Hbox

    Method set_title

      `Gnome.NumberEntry set_title(string title)`

    Description

      Set the title of the calculator dialog to calc_dialog_title. Takes effect the next time the calculator button is pressed.

  CLASS Gnome.PaperSelector

    Description

      `Gnome.PaperSelector()`

    Method create

      `Gnome.PaperSelector Gnome.PaperSelector()`

    Method get_bottom_margin

      `float get_bottom_margin()`

    Method get_height

      `float get_height()`

    Method get_left_margin

      `float get_left_margin()`

    Method get_name

      `string get_name()`

    Method get_right_margin

      `float get_right_margin()`

    Method get_top_margin

      `float get_top_margin()`

    Method get_width

      `float get_width()`

    Inherit Vbox

      inherit GTK1.Vbox : Vbox

  CLASS Gnome.PixmapEntry

    Description

      Entry for large images with a preview. Unlike GnomeIconEntry, it does not scale the images to a specific size and shows them 1:1. This is perfect for selection of backgrounds and such. It also allows DND to be performed on the preview box. It also provides all the GnomeEntry functionality as well. `Gnome.PixmapEntry("","browse...",1);`

    Method create

      `Gnome.PixmapEntry Gnome.PixmapEntry(string history_id, string browse_dialog_title, int do_preview)`

    Description

      Creates a new pixmap entry widget, if do_preview is false, the preview is hidden but the files are still loaded so that it's easy to show it. For a pixmap entry without preview, use the W(GnomeFileEntry) widget.

    Method get_filename

      `string get_filename()`

    Description

      Gets the filename of the image if the preview successfully loaded.

    Method gnome_entry

      `Gnome.Entry gnome_entry()`

    Description

      Get the W(GnomeEntry) component of the W(GnomePixmapEntry) widget for lower-level manipulation.

    Method gnome_file_entry

      `Gnome.FileEntry gnome_file_entry()`

    Description

      Get the W(GnomeFileEntry) component of the W(GnomePixmapEntry) widget for lower-level manipulation.

    Inherit Vbox

      inherit GTK1.Vbox : Vbox

    Method set_pixmap_subdir

      `Gnome.PixmapEntry set_pixmap_subdir(string dir)`

    Description

      Sets the default path for the file entry. The new subdirectory should be specified relative to the default GNOME pixmap directory.

    Method set_preview

      `Gnome.PixmapEntry set_preview(int do_preview)`

    Description

      Sets whether or not previews of the currently selected pixmap should be shown in the file selector.

    Method set_preview_size

      `Gnome.PixmapEntry set_preview_size(int min_w, int min_h)`

    Description

      Sets the minimum size of the preview frame in pixels.

  CLASS Gnome.PropertyBox

    Description

      The Gnome.PropertyBox widget simplifies coding a consistent dialog box for configuring properties of any kind.

      The Gnome.PropertyBox is a toplevel widget (it will create its own window), inside it contains a GtkNotebook which is used to hold the various property pages.

      The box will include ok, cancel, apply and help buttons (the actual buttons depends on the settings the user has, for example, apply can be hidden). The ok and apply buttons will start up in non-sensitive state, the programmer needs to configure the widgets inserted into the property box to inform the widget of any state changes to enable the ok and apply buttons. This is done by calling the changed() function.

      To use this widget, you create the widget and then you call append_page() for each property page you want in the property box.

      The widget emits two signals: "apply" and "help". To make a functional dialog box you will want to connect to at least the "apply" signal. Your function will be invoked once for each page and one more time at the end, passing a special value of -1 for the page number.

      Signals: apply This signal is invoked with the page number that is being applied. The signal is emited with the special page number -1 when it has finished emiting the signals for all of the property pages.

      help This signal is invoked when the user clicks on the help button in the property box. An argument is passed that identifies the currently active page number.

    Method append_page

      `int append_page(GTK1.Widget child, GTK1.Widget tab_label)`

    Description

      Appends a new page to the Gnome.PropertyBox. widget is the widget that is being inserted, and tab_label will be used as the label for this configuration page.

    Method changed

      `Gnome.PropertyBox changed()`

    Description

      When a setting has changed, the code needs to invoke this routine to make the Ok/Apply buttons sensitive.

    Method create

      `Gnome.PropertyBox Gnome.PropertyBox()`

    Description

      Creates a new Gnome.PropertyBox widget.

    Inherit Dialog

      inherit Gnome.Dialog : Dialog

    Method set_state

      `Gnome.PropertyBox set_state(int state)`

  CLASS Gnome.Scores

    Description

      This is a high-scores dialog box. The GNOME libraries also handle loading/saving systemwide high scores in a secure way.

      `Gnome.Scores( 17, ({ "per" })*17, map((array(float))indices(allocate(17)),`*,42), map(indices(allocate(17)), `*, 10 ), 1 )`

    Method create

      `Gnome.Scores Gnome.Scores(int n_scores, array names, array scores, array times, int clear)`

    Inherit Dialog

      inherit Gnome.Dialog : Dialog

    Method set_color

      `Gnome.Scores set_color(int pos, GDK1.Color color)`

    Method set_current_player

      `Gnome.Scores set_current_player(int index)`

    Method set_def_color

      `Gnome.Scores set_def_color(GDK1.Color color)`

    Method set_logo_label_title

      `Gnome.Scores set_logo_label_title(string txt)`

    Method set_logo_pixmap

      `Gnome.Scores set_logo_pixmap(string logofile)`

    Method set_logo_widget

      `Gnome.Scores set_logo_widget(GTK1.Widget widget)`

  CLASS Gnome.StatusDocklet

    Description

      Some apps want to embed a very small icon or widget in the panel to display the status of the app. This can be done without the operational overhead of an applet. The status docklet will embed a 22 by 22 window inside the panel. This is not a separate applet and thus is minimally intrusive to the user and is meant for very temporary status displays for which a full applet would not be appropriate.

      The way StatusDocklet works is a little different from how the AppletWidget works. Firstly, StatusDocklet object is not a widget, it is just an abstract GTK+ object. You create a new StatusDocklet object and then bind the "build_plug" signal which is emitted when the panel was contacted and a widget must be built. After binding the "build_plug" signal, you call run() to actually start trying to contacting the panel. StatusDocklet is safe to use without a panel. By default it will try to locate a panel for 15 minutes and after that it will give up. It will also handle panel restarts by default. If it does, your widget will be destroyed and "build_plug" will be emitted again when the new panel starts. Even though the panel will never restart by itself, the user might not run session management and thus might restart panel by hand, or due to a bug, the panel might crash and restart itself.

      Docklets are not available in GNOME 1.0.

      Signals: build_plug This signal is emitted when you actually need to build the widget that you want to place inside the plug in the status docklet. It should be 22 by 22, and if it is larger it will be cropped.

    Method create

      `Gnome.StatusDocklet Gnome.StatusDocklet()`

    Description

      Creates a new status docklet object with the default parameters. By default the docklet object will try to contact a panel 20 times. It will try to find a panel every 15 seconds. You need to bind the build_plug signal in which you build your own widget and add it to the provided container. By default the docklet object will handle a panel restart, in which case your widget will be destroyed and when the panel is contacted again the build_plug signal will be emitted again. You also must call the status_docklet_run function after you bind the build_plug signal.

    Method get_plug

      `GTK1.Plug get_plug()`

    Description

      the current W(plug) holding the docklet

    Inherit Object

      inherit GTK1.Object : Object

    Method run

      `Gnome.StatusDocklet run()`

    Description

      Search for the panel and add the plug if it finds it. This function is also called internally from the timeout. If called externally more times, a panel lookup will be forced and one try will be wasted. You need to call this function at least once after binding the build_plug signal to tell the status docklet to start looking for the panel. If the status docklet handles restarts you don't have to call this function ever again.

Module Gnome2

Module Graphics

  Module Graphics.Graph

    Method pie
    Method bars
    Method sumbars
    Method line
    Method norm
    Method graph

      `Image.Image pie(mapping(string:mixed) diagram_data)`
      `Image.Image bars(mapping(string:mixed) diagram_data)`
      `Image.Image sumbars(mapping(string:mixed) diagram_data)`
      `Image.Image line(mapping(string:mixed) diagram_data)`
      `Image.Image norm(mapping(string:mixed) diagram_data)`
      `Image.Image graph(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, string type)`

    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.

    Inherit create_pie

      protected inherit .create_pie : create_pie

    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 Gz

  Description

    The Gz module contains functions to compress and uncompress strings using the same algorithm as the program `gzip`. Compressing can be done in streaming mode or all at once.

    The Gz module consists of two classes; Gz.deflate and Gz.inflate. Gz.deflate is used to pack data and Gz.inflate is used to unpack data. (Think "inflatable boat")

  Note

    Note that this module is only available if the gzip library was available when Pike was compiled.

    Note that although these functions use the same algorithm as `gzip`, they do not use the exact same format, so you cannot directly unzip gzipped files with these routines. Support for this will be added in the future.

  Method compress

    `string(8bit) compress(string(8bit)|String.Buffer|System.Memory|Stdio.Buffer data, void|bool raw, void|int(0..9) level, void|int strategy, void|int(8..15) window_size)`

  Description

    Encodes and returns the input data according to the deflate format defined in RFC 1951.

  Parameter `data`

    The data to be encoded.

  Parameter `raw`

    If set, the data is encoded without the header and footer defined in RFC 1950. Example of uses is the ZIP container format.

  Parameter `level`

    Indicates the level of effort spent to make the data compress well. Zero means no packing, 2-3 is considered 'fast', 6 is default and higher is considered 'slow' but gives better packing.

  Parameter `strategy`

    The strategy to be used when compressing the data. One of the following.

    `DEFAULT_STRATEGY` | The default strategy as selected in the zlib library.
    `FILTERED` | This strategy is intented for data created by a filter or predictor and will put more emphasis on huffman encoding and less on LZ string matching. This is between DEFAULT_STRATEGY and HUFFMAN_ONLY.
    `RLE` | This strategy is even closer to the HUFFMAN_ONLY in that it only looks at the latest byte in the window, i.e. a window size of 1 byte is sufficient for decompression. This mode is not available in all zlib versions.
    `HUFFMAN_ONLY` | This strategy will turn of string matching completely, only doing huffman encoding. Window size doesn't matter in this mode and the data can be decompressed with a zero size window.
    `FIXED` | In this mode dynamic huffman codes are disabled, allowing for a simpler decoder for special applications. This mode is not available in all zlib versions.

  Parameter `window_size`

    Defines the size of the LZ77 window from 256 bytes to 32768 bytes, expressed as 2^x.

  See also

    deflate, inflate, uncompress

  Method crc32

    `int crc32(string(8bit) data, void|int start_value)`

  Description

    This function calculates the standard ISO3309 Cyclic Redundancy Check.

  Inherit "___Gz"

    inherit "___Gz" : "___Gz"

  Method uncompress

    `string(8bit) uncompress(string(8bit)|String.Buffer|System.Memory|Stdio.Buffer data, void|bool raw)`

  Description

    Uncompresses the data and returns it. The raw parameter tells the decoder that the indata lacks the data header and footer defined in RFC 1950.

  CLASS Gz.File

    Description

      Allows the user to open a Gzip archive and read and write it's contents in an uncompressed form, emulating the Stdio.File interface.

    Note

      An important limitation on this class is that it may only be used for reading or writing, not both at the same time. Please also note that if you want to reopen a file for reading after a write, you must close the file before calling open or strange effects might be the result.

    Method create

      `Gz.File Gz.File(void|string|int|Stdio.Stream file, void|string mode)`

    Parameter `file`

      Filename or filedescriptor of the gzip file to open, or an already open Stream.

    Parameter `mode`

      mode for the file. Defaults to "rb".

    See also

      open Stdio.File

    Inherit _file

      inherit _file : _file

    Method open

      `int open(string|int|Stdio.Stream file, void|string mode)`

    Parameter `file`

      Filename or filedescriptor of the gzip file to open, or an already open Stream.

    Parameter `mode`

      mode for the file. Defaults to "rb". May be one of the following:

      rb

        read mode

      wb

        write mode

      ab

        append mode

      For the wb and ab mode, additional parameters may be specified. Please se zlib manual for more info.

    Returns

      non-zero if successful.

    Method read

      `int|string read(void|int length)`

    Description

      Reads data from the file. If no argument is given, the whole file is read.

  CLASS Gz._file

    Description

      Low-level implementation of read/write support for GZip files

    Method close

      `int close()`

    Description

      closes the file

    Returns

      1 if successful

    Method create

      `Gz._file Gz._file(void|string|Stdio.Stream gzFile, void|string mode)`

    Description

      Opens a gzip file for reading.

    Method eof

      `bool eof()`

    Returns

      1 if EOF has been reached.

    Method open

      `int open(string|int|Stdio.Stream file, void|string mode)`

    Description

      Opens a file for I/O.

    Parameter `file`

      The filename or an open filedescriptor or Stream for the GZip file to use.

    Parameter `mode`

      Mode for the fileoperations. Defaults to read only.

    Note

      If the object already has been opened, it will first be closed.

    Method read

      `int|string read(int len)`

    Description

      Reads len (uncompressed) bytes from the file. If read is unsuccessful, 0 is returned.

    Method seek

      `int seek(int pos, void|int type)`

    Description

      Seeks within the file.

    Parameter `pos`

      Position relative to the searchtype.

    Parameter `type`

      SEEK_SET = set current position in file to pos SEEK_CUR = new position is current+pos SEEK_END is not supported.

    Returns

      New position or negative number if seek failed.

    Method setparams

      `int setparams(int level, int strategy)`

    Description

      Sets the encoding level and strategy

    Parameter `level`

      Level of the compression. 0 is the least compression, 9 is max. 8 is default.

    Parameter `strategy`

      Set strategy for encoding to one of the following: DEFAULT_STRATEGY FILTERED HUFFMAN_ONLY

    Method tell

      `int tell()`

    Returns

      the current position within the file.

    Method write

      `int write(string data)`

    Description

      Writes the data to the file.

    Returns

      the number of bytes written to the file.

  CLASS Gz.deflate

    Description

      This class interfaces with the compression routines in the libz library.

    Note

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

    See also

      Gz.inflate(), Gz.compress(), Gz.uncompress()

    Method create

      `Gz.deflate Gz.deflate(int(-9..9)|void level, int|void strategy, int(8..15)|void window_size)`
      `Gz.deflate Gz.deflate(mapping options)`

    Description

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

      If a mapping is passed as the only argument, it will accept the parameters described below as indices, and additionally it accepts a `string` as `dictionary`.

    Parameter `level`

      Indicates the level of effort spent to make the data compress well. Zero means no packing, 2-3 is considered 'fast', 6 is default and higher is considered 'slow' but gives better packing.

      If the argument is negative, no headers will be emitted. This is needed to produce ZIP-files, as an example. The negative value is then negated, and handled as a positive value.

    Parameter `strategy`

      The strategy to be used when compressing the data. One of the following.

      `DEFAULT_STRATEGY` | The default strategy as selected in the zlib library.
      `FILTERED` | This strategy is intented for data created by a filter or predictor and will put more emphasis on huffman encoding and less on LZ string matching. This is between DEFAULT_STRATEGY and HUFFMAN_ONLY.
      `RLE` | This strategy is even closer to the HUFFMAN_ONLY in that it only looks at the latest byte in the window, i.e. a window size of 1 byte is sufficient for decompression. This mode is not available in all zlib versions.
      `HUFFMAN_ONLY` | This strategy will turn of string matching completely, only doing huffman encoding. Window size doesn't matter in this mode and the data can be decompressed with a zero size window.
      `FIXED` | In this mode dynamic huffman codes are disabled, allowing for a simpler decoder for special applications. This mode is not available in all zlib versions.

    Parameter `window_size`

      Defines the size of the LZ77 window from 256 bytes to 32768 bytes, expressed as 2^x.

    Method deflate

      `string(8bit) deflate(string(8bit)|String.Buffer|System.Memory|Stdio.Buffer data, int|void flush)`

    Description

      This function performs gzip style compression on a string data and returns the packed data. Streaming can be done by calling this function several times and concatenating the returned data.

      The optional argument flush should be one of the following:

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

    See also

      Gz.inflate->inflate()

  CLASS Gz.inflate

    Description

      This class interfaces with the uncompression routines in the libz library.

    Note

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

    See also

      deflate, compress, uncompress

    Method create

      `Gz.inflate Gz.inflate(int|void window_size)`
      `Gz.inflate Gz.inflate(mapping options)`

    Description

      If called with a mapping as only argument, `create` accepts the entries `window_size` (described below) and `dictionary`, which is a string to be set as dictionary.

      The window_size value is passed down to inflateInit2 in zlib.

      If the argument is negative, no header checks are done, and no verification of the data will be done either. This is needed for uncompressing ZIP-files, as an example. The negative value is then negated, and handled as a positive value.

      Positive arguments set the maximum dictionary size to an exponent of 2, such that 8 (the minimum) will cause the window size to be 256, and 15 (the maximum, and default value) will cause it to be 32Kb. Setting this to anything except 15 is rather pointless in Pike.

      It can be used to limit the amount of memory that is used to uncompress files, but 32Kb is not all that much in the great scheme of things.

      To decompress files compressed with level 9 compression, a 32Kb window size is needed. level 1 compression only requires a 256 byte window.

      If the options version is used you can specify your own dictionary in addition to the window size.

      `dictionary : string`
      `window_size : int`

    Method end_of_stream

      `string(8bit) end_of_stream()`

    Description

      This function returns 0 if the end of stream marker has not yet been encountered, or a string (possibly empty) containg any extra data received following the end of stream marker if the marker has been encountered. If the extra data is not needed, the result of this function can be treated as a logical value.

    Method inflate

      `string(8bit) inflate(string(8bit)|String.Buffer|System.Memory|Stdio.Buffer data)`

    Description

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

    Example

          // whole file

      write(Gz.inflate()->inflate(stdin->read(0x7fffffff));

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

  See also

    Gz.deflate->deflate(), Gz.decompress

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.Loop HTTPAccept.Loop(Stdio.Port port, RequestProgram program, function(RequestProgram:void) request_handler, int cache_size, bool keep_log, int timeout)`

    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

      `int log_as_commonlog_to_file(Stdio.Stream fd)`

    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

      `int log_size()`

    Description

      Returns the number of entries waiting to be logged.

    Method logp

      `bool logp()`

    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 '?'.

    Method output

      `void output(string data)`

    Description

      Send data directly to the remote side.

    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

    Method reply

      `void reply(string data)`
      `void reply(string headers, Stdio.File fd, int len)`
      `void reply(int(0..0) ignore, Stdio.File fd, int len)`

    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

      `void reply_with_cache(string data, 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.

    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

Module Java

  Method JArray

    `jobject JArray(array a)`

  Method JBoolean

    `jobject JBoolean(int i)`

  Method JFloat

    `jobject JFloat(float f)`

  Method JHashMap

    `jobject JHashMap(mapping m)`

  Method JInteger

    `jobject JInteger(int i)`

  Method JString

    `jobject JString(string s)`

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

  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 Languages

  Module Languages.PLIS

    Description

      PLIS, Permuted Lisp. A Lisp language somewhat similar to scheme.

    Method default_environment

      `Environment default_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

    `void init_functions(Environment environment)`

  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

    `void init_specials(Environment environment)`

  Description

    Adds the special functions quote, set!, setq, while, define, defmacro, lambda, if, and, or, begin and catch to the environment.

  Method main

    `void main()`

  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 \"PLIS: \"))) (if line (let ((res (catch (eval (read-string line) (global-environment))))) (display res) (loop))))) (loop))

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

  Method add_path

    `bool add_path(string path)`

  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.

  Inherit __joinnode

    inherit __joinnode : __joinnode

  Method remove_path

    `void remove_path(string path)`

  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 needs to change locale often. It is even possible for different threads to use different locales at the same time.

    The highest level of the locale system is called projects. Usually one program consists of only one project, but for bigger applications, or highly modular applications it is possible for several projects to coexist.

    Every project in turn contains several unique tokens, each one representing an entity that is different depending on the currently selected locale.

  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 call

  `function(:void) call(string project, string lang, string name, void|function(:void)|string fb)`

Description

  Returns a localized function If function not found, tries fallback function fb, or fallback language fb instead

Method get_objects

  `mapping(string:object) get_objects(string lang)`

Description

  Reads in and returns a mapping with all the registred projects' LocaleObjects in the language 'lang'

Method list_languages

  `array(string) list_languages(string project)`

Description

  Returns a list of all registered languages for a specific project.

Method register_project

  `void register_project(string name, string path, void|string path_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

  `void set_default_project_path(string path)`

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

  `string translate(string project, string lang, string|int id, string fallback)`

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.

  Method create

    `Locale.DeferredLocale Locale.DeferredLocale(string project, function(:string) get_lang, string|int key, string fallback)`

  Variable project
  Variable get_lang
  Variable key
  Variable fallback

    `protected string Locale.DeferredLocale.project`
    `protected function(:string) Locale.DeferredLocale.get_lang`
    `protected string|int Locale.DeferredLocale.key`
    `protected string Locale.DeferredLocale.fallback`

  Method get_identifier

    `array get_identifier()`

  Description

    Return the data nessesary to recreate this "string".

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.

  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.

  Note

    This category isn't available on all platforms.

  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

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

  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

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

  Description

    Return a translated version of msg within the context of the specified domain and current locale for the specified category. Calling dcgettext with category Locale.Gettext.LC_MESSAGES gives the same result as dgettext.

    If there is no translation available, msg is returned.

  Note

    Obsoleted by gettext() in Pike 7.3.

  See also

    bindtextdomain, textdomain, gettext, setlocale, localeconv

  Method dgettext

    `string dgettext(string domain, string msg)`

  Description

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

  Note

    Obsoleted by gettext() in Pike 7.3.

  See also

    bindtextdomain, textdomain, gettext, setlocale, localeconv

  Method gettext

    `string gettext(string msg)`
    `string gettext(string msg, string domain)`
    `string gettext(string msg, string domain, int category)`

  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.

  Note

    Prior to Pike 7.3 this function only accepted one argument, and the other functionality was provided by dgettext() and dcgettext().

  See also

    bindtextdomain, textdomain, setlocale, localeconv

  Method localeconv

    `mapping localeconv()`

  Description

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

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

    `int setlocale(int category, string locale)`

  Description

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

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

    The argument category determines which functions are influenced by the new locale 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

    `string textdomain(void|string domain)`

  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.

    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.

    Method date

      `string date(int timestamp, string|void mode)`

    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

      `string day(int(1..7) num)`

    Description

      Returns the name of weekday number num.

    Constant days

      `constant Locale.Language.abstract.days`

    Description

      Array(string) with the days of the week, beginning with Sunday.

    Constant english_name

      `constant string Locale.Language.abstract.english_name`

    Description

      The name of the language in english.

    Constant iso_639_1

      `optional constant int 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

      `constant int Locale.Language.abstract.iso_639_2`

    Description

      String with the language code in ISO-639-2/T (three character code).

    Constant iso_639_2B

      `constant int 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.

    Method month

      `string month(int(1..12) num)`

    Description

      Returns the name of month number num.

    Constant months

      `constant Locale.Language.abstract.months`

    Description

      Array(string) with the months of the year, beginning with January.

    Constant name

      `constant string Locale.Language.abstract.name`

    Description

      The name of the langauge. E.g. "svenska" for Swedish.

    Method number

      `string number(int i)`

    Description

      Returns the number i as a string.

    Method ordered

      `string ordered(int i)`

    Description

      Returns the ordered number i as a string.

    Method short_day

      `string short_day(int(1..7) num)`

    Description

      Returns an abbreviated weekday name from the weekday number num.

    Method short_month

      `string short_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.

  Method decode

    `string|StringRange decode(string|StringRange data, string encoding)`

  Description

    Extract raw data from an encoded string suitable for transport between systems.

    The encoding can be any of

    `"7bit"`
    `"8bit"`
    `"base64"`
    `"binary"`
    `"quoted-printable"`
    `"x-uue"`
    `"x-uuencode"`

    The encoding string is not case sensitive.

  See also

    MIME.encode()

  Method decode_base64

    `string decode_base64(string encoded_data)`

  Description

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

  See also

    MIME.encode_base64(), MIME.decode()

  Method decode_base64url

    `string decode_base64url(string x)`

  Description

    Decode strings according to RFC 4648 base64url encoding.

  Method decode_qp

    `string decode_qp(string encoded_data)`

  Description

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

  See also

    MIME.encode_qp(), MIME.decode()

  Method decode_uue

    `string decode_uue(string encoded_data)`

  Description

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

  See also

    MIME.encode_uue(), MIME.decode()

  Method decode_word

    `array(string) decode_word(string word)`

  Description

    Extracts the textual content and character set from an encoded word as specified by RFC 1522. 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(string txt)`

  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_tokenized MIME.decode_words_text_remapped

  Method decode_words_text_remapped

    `string decode_words_text_remapped(string txt)`

  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(string phrase, int|void flags)`

  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_labled MIME.decode_words_tokenized_remapped MIME.decode_words_text

  Method decode_words_tokenized_labled

    `array(array(string|int|array(array(string)))) decode_words_tokenized_labled(string phrase, int|void flags)`

  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(string phrase, int|void flags)`

  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(string phrase, int|void flags)`

  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_remapped MIME.decode_words_text_remapped

  Method encode

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

  Description

    Encode raw data into something suitable for transport to other systems.

    The encoding can be any of

    `"7bit"`
    `"8bit"`
    `"base64"`
    `"binary"`
    `"quoted-printable"`
    `"x-uue"`
    `"x-uuencode"`

    The encoding string is not case sensitive. For the `x-uue` encoding, an optional filename string may be supplied.

    If a nonzero value is passed as no_linebreaks, the result string will not contain any linebreaks (`base64` and `quoted-printable` only).

  See also

    MIME.decode()

  Method encode_base64

    `string encode_base64(string data, void|int no_linebreaks)`

  Description

    This function encodes data using the `base64` transfer encoding.

    If a nonzero value is passed as no_linebreaks, the result string will not contain any linebreaks.

  See also

    MIME.decode_base64(), MIME.encode()

  Method encode_base64url

    `string encode_base64url(string x)`

  Description

    Encode strings according to RFC 4648 base64url encoding.

  Method encode_qp

    `string encode_qp(string data, void|int no_linebreaks)`

  Description

    This function encodes data using the `quoted-printable` (a.k.a. quoted-unreadable) transfer encoding.

    If a nonzero value is passed as no_linebreaks, the result string will not contain any linebreaks.

  Note

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

  See also

    MIME.decode_qp(), MIME.encode()

  Method encode_uue

    `string encode_uue(string encoded_data, void|string filename)`

  Description

    This function encodes data using the `x-uue` transfer encoding.

    The optional argument filename specifies an advisory filename to include in the encoded data, for extraction purposes.

    This function can also be used to produce generic UUEncoded files.

  See also

    MIME.decode_uue(), MIME.encode()

  Method encode_word

    `string encode_word(string|array(string) word, string encoding)`

  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

    `string encode_words_quoted(array(array(string)|int) phrase, string encoding)`

  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

    `string encode_words_quoted_labled(array(array(string|int|array(string|array(string)))) phrase, string encoding)`

  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

    `string encode_words_quoted_labled_remapped(array(array(string|int)) phrase, string encoding, string|function(string:string) charset, string|void replacement, function(string:string)|void repcb)`

  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

    `string encode_words_quoted_remapped(array(string|int) phrase, string encoding, string|function(string:string) charset, string|void replacement, function(string:string)|void repcb)`

  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

    `string encode_words_text(array(string|array(string)) phrase, string encoding)`

  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

    `string encode_words_text_remapped(string text, string encoding, string|function(string:string) charset, string|void replacement, function(string:string)|void repcb)`

  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

    `string ext_to_media_type(string extension)`

  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

    `string generate_boundary()`

  Description

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

  Method guess_subtype

    `string guess_subtype(string type)`

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

  Inherit ___MIME

    inherit ___MIME : ___MIME

  Method parse_headers

    `array(mapping(string:string)|string) parse_headers(string message)`
    `array(mapping(string:array(string))|string) parse_headers(string message, int(1..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 occurr multiple times will have their contents NUL separated, unless use_multiple has been specified, in which case the contents will be arrays.

  Method quote

    `string quote(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 (`int`s) 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

    `string quote_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|object reconstruct_partial(array(object) collection)`

  Description

    This function will attempt to reassemble a fragmented message from its parts.

    The array collection should contain MIME.Message objects forming a complete set of parts for a single fragmented message. The order of the messages in 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 tokenize

    `array(string|int) tokenize(string header, int|void flags)`

  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. `int`s).

    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(string header, int|void flags)`

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

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

    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

    Method create

      `MIME.Message MIME.Message()`
      `MIME.Message MIME.Message(string message)`
      `MIME.Message MIME.Message(string message, mapping(string:string|array(string)) headers, array(object)|void parts)`
      `MIME.Message MIME.Message(string message, mapping(string:string|array(string)) headers, array(object)|void parts, bool guess)`

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

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

    Method get_filename

      `string get_filename()`

    Description

      This method tries to find a suitable filename should you want to save the body data to disk.

      It will examine the `filename` attribute of the `Content-Disposition` header, and failing that the `name` attribute of the `Content-Type` header. If neither attribute is set, the method returns 0.

    Note

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

    Method getdata

      `string getdata()`

    Description

      This method returns the raw data of the message body entity.

      The type and subtype attributes indicate how this data should be interpreted.

    See also

      setdata(), getencoded(), data

    Method getencoded

      `string getencoded()`

    Description

      This method returns the data of the message body entity, encoded using the current transfer encoding.

      You should never have to call this function.

    See also

      getdata()

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

    Method is_partial

      `array(string|int) is_partial()`

    Description

      If this message is a part of a fragmented message (i.e. has a Content-Type of `message/partial`), an array with three elements is returned.

      The first element is an identifier string. This string should be used to group this message with the other fragments of the message (which will have the same id string).

      The second element is the sequence number of this fragment. The first part will have number 1, the next number 2 etc.

      The third element of the array is either the total number of fragments that the original message has been split into, or 0 of this information 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()

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

    Method parse_param

      `protected void parse_param(mapping(string:string) params, array(string|int) entry, string header, int|void guess, array(string|int)|void entry2)`

    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

      `void setboundary(string boundary)`

    Description

      Sets the `boundary` parameter of the `Content-Type` header.

      This is equivalent of calling `setparam("boundary", <font face='courier'>boundary`).

    See also

      setparam()

    Method setcharset

      `void setcharset(string charset)`

    Description

      Sets the `charset` parameter of the `Content-Type` header.

      This is equivalent of calling `setparam("charset", <font face='courier'>charset`).

    See also

      setparam()

    Method setdata

      `void setdata(string data)`

    Description

      Replaces the body entity of the data with a new piece of raw data.

      The new data should comply to the format indicated by the type and subtype attributes.

    Note

      Do not use this method unless you know what you are doing.

    See also

      getdata(), setencoded, data

    Method setdisp_param

      `void setdisp_param(string param, string value)`

    Description

      Set or modify the named parameter of the `Content-Disposition` header.

      A common parameters is e.g. `filename`.

    Note

      It is not allowed to modify the `Content-Disposition` header directly, please use this function instead.

    See also

      setparam(), get_filename()

    Method setencoding

      `void setencoding(string encoding)`

    Description

      Select a new transfer encoding for this message.

      The `Content-Transfer-Encoding` header will be modified accordingly, and subsequent calls to getencoded will produce data encoded using the new encoding.

      See MIME.encode() for a list of valid encodings.

    See also

      getencoded(), MIME.encode()

    Method setparam

      `void setparam(string param, string value)`

    Description

      Set or modify the named parameter of the `Content-Type` header.

      Common parameters include `charset` for text messages, and `boundary` for multipart messages.

    Note

      It is not allowed to modify the `Content-Type` header directly, please use this function instead.

    See also

      setcharset(), setboundary(), setdisp_param()

    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

  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 Math

  Method choose

    `int choose(int n, int k)`

  Description

    Calculate binomial koefficient n choose k.

    This is equvivalent to `n!/(k!*(n-k)!)`.

  Method convert_angle

    `int|float convert_angle(int|float angle, string from, string to)`

  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.

  Constant e

    `constant Math.e`

  Description

    The constant e (2.7182818284590452354).

  Method factor

    `array(int) factor(int x)`

  Description

    Factorize the integer x. The returned list of factors will be sorted biggest to smallest factor.

  Note

    This function is only available when Pike has been compiled with bignums.

  Note

    In Pike versions prior to v8.0, only primes `<= 8161` were considered.

  Constant inf

    `constant Math.inf`

  Description

    Floating point infinity.

  Inherit "___Math"

    inherit "___Math" : "___Math"

  Method log10

    `float log10(int|float x)`

  Description

    The 10-logarithm of x.

  Method log2

    `float log2(int|float x)`

  Description

    The 2-logarithm of x.

  Method logn

    `float logn(int|float n, int|float x)`

  Description

    The n-logatirhm of x.

  Constant nan

    `constant Math.nan`

  Description

    Floating point not-a-number (e.g. inf/inf).

  Constant pi

    `constant Math.pi`

  Description

    The constant pi (3.14159265358979323846).

  CLASS Math.Angle

    Description

      Represents an angle.

    Method __hash

      `int hash_value( Math.Angle arg )`

    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

      `void about_face()`

    Description

      Turns the direction of the angle half a turn. Equal to `add(180,"deg")`.

    Method add

      `Angle add(float|int angle)`
      `Angle add(float|int angle, string type)`
      `Angle add(Angle angle)`

    Description

      Adds the provided angle to the current angle. The result is normalized within 360 degrees.

    Variable angle

      `int|float Math.Angle.angle`

    Description

      The actual keeper of the angle value.

    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

      `Angle clone_me()`

    Description

      Returns a copy of the object.

    Method cos

      `float cos()`

    Description

      Returns the cosinus for the angle.

    Method create

      `Math.Angle Math.Angle()`
      `Math.Angle Math.Angle(int|float radians)`
      `Math.Angle Math.Angle(int|float angle, string type)`

    Description

      If an angle object is created without arguments it will have the value 0 radians.

    Method degree

      `int|float degree()`

    Description

      Returns the number of degrees, including minutes and seconds as decimals.

    Method format_dms

      `string format_dms()`

    Description

      Returns degrees, minutes and seconds as a string, e.g. 47°6'36.00".

    Method get

      `int|float get(string type)`

    Description

      Gets the value in the provided type.

    Method gon

      `int|float gon()`

    Description

      Returns the number of gons.

    Method left_face

      `void left_face()`

    Description

      Turns the direction of the angle a quarter of a turn to the left. Equal to `add(90,"deg")`.

    Method minute

      `int minute()`

    Description

      Returns the number of minute.

    Method normalize

      `void normalize()`

    Description

      Normalizes the angle to be within one turn.

    Method rad

      `float rad()`

    Description

      Returns the number of radians.

    Method right_face

      `void right_face()`

    Description

      Turns the direction of the angle a quarter of a turn to the right. Equal to `subtract(90,"deg")`.

    Method second

      `float second()`

    Description

      Returns the number of seconds.

    Method set

      `Angle set(string type, int|float _angle)`

    Description

      Sets the angle value and type to the given value and type.

    Method set_degree

      `Angle set_degree(int|float degree)`

    Description

      Sets the angle to the provided degree. Alters the type to degrees. Returns the current object.

    Method set_dms

      `Angle set_dms(int degrees)`
      `Angle set_dms(int degrees, int minutes)`
      `Angle set_dms(int degrees, int minutes, float seconds)`

    Description

      Set degrees, minues and seconds. Returns the current angle object.

    Method set_gon

      `Angle set_gon(int|float gon)`

    Description

      Set the angle to the provided gons. Alters the type to gons. Returns the current angle object.

    Method set_rad

      `Angle set_rad(int|float rad)`

    Description

      Set the angle to the provided radians. Alters the type to radians. Returns the current angle object.

    Method set_streck

      `Angle set_streck(int|float str)`

    Description

      Set the angle to the provided strecks. Alters the type to streck. Returns the current angle object.

    Method sin

      `float sin()`

    Description

      Returns the sinus for the angle.

    Method streck

      `float|int streck()`

    Description

      Returns the number of strecks.

    Method subtract

      `Angle subtract(float|int angle)`
      `Angle subtract(float|int angle, string type)`
      `Angle subtract(Angle angle)`

    Description

      Subtracts the provided angle from the current angle. The result is normalized within 360 degrees.

    Method tan

      `float tan()`

    Description

      Returns the tangen for the angle.

    Variable type

      `string Math.Angle.type`

    Description

      The type of the angle value. Is either "deg", "rad", "gon" or "str".

  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()`
      `Matrix mult(object with)`

    Description

      Matrix multiplication.

    Method `+
    Method ``+
    Method add

      `Matrix res = Math.Matrix() + with`
      `Matrix res = with + Math.Matrix()`
      `Matrix add(object with)`

    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()`
      `Matrix sub(object with)`

    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

      `Matrix convolve(object with)`

    Description

      Convolve called matrix with the argument.

    Method create

      `Math.Matrix Math.Matrix(array(array(int|float)) matrix_2d)`
      `Math.Matrix Math.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.Matrix Math.Matrix(int n, int m)`
      `Math.Matrix Math.Matrix(int n, int m, string type)`
      `Math.Matrix Math.Matrix(int n, int m, float|int init)`

    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.Matrix Math.Matrix(string type, int size)`

    Description

      When type is `"identity"` the matrix is initializes as a square identity matrix.

    Method create

      `Math.Matrix Math.Matrix(string type, int size, float rads, Matrix axis)`
      `Math.Matrix Math.Matrix(string type, int size, float rads, float x, float y, float z)`

    Description

      When type is `"rotate"` the matrix is initialized as a rotation matrix.

    Method cross

      `Matrix cross(object with)`

    Description

      Matrix cross-multiplication.

    Method dot_product

      `float dot_product(object with)`

    Description

      Matrix dot product.

    Method max
    Method min

      `Matrix max()`
      `Matrix min()`

    Description

      Produces the maximum or minimum value of all the elements in the matrix.

    Method norm
    Method norm2
    Method normv

      `float norm()`
      `float norm2()`
      `Matrix normv()`

    Description

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

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

      It is only usable with 1xn or nx1 matrices.

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

    Method sum

      `Matrix sum()`

    Description

      Produces the sum of all the elements in the matrix.

    Method transpose

      `Matrix transpose()`

    Description

      Returns the transpose of the matrix as a new object.

    Method vect

      `array vect()`

    Description

      Return all the elements of the matrix as an array of numbers

    Method xsize

      `int xsize()`

    Description

      Returns the width of the matrix.

    Method ysize

      `int ysize()`

    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.FFT Math.Transforms.FFT(void|int n, void|bool exact)`

      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.

  Variable ANY

    `string 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) cidr_to_netmask(string cidr)`

  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
    `int ip` | The binary representation of the IP address.
    `int mask` | The bitmask.

    Returns 0 if the string could not be parsed.

  Method clear_cache

    `void clear_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

    `NetworkType get_network_type(int|string ipstr, bool|void separate_6)`

  Description

    Determine the network type of a given host

  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

    "localhost", "local", "private", "multicast", "teredo", "6to4" or "global"

    "localhost" is the local computer.

    "local" is the local network

    "private" is a private network, such as 10.0.0.0/8 or fc00::/7 that is not also a local network.

    "multicast" is a multicast address

    "teredo" and "6to4" is an address in the teredo and 6to4 tunneling system, respectively.

    "global" is a global address that does not match any other category

  Method has_ipv4

    `bool has_ipv4()`

  Description

    Returns true if the local host has a public IPv4 address

  Method has_ipv6

    `bool has_ipv6()`

  Description

    Returns true if the local host has a public IPv6 address

  Method host_to_cidr

    `string host_to_cidr(int|string ip)`

  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) ip_and_port_of(RemoteAddressObject|string|int(0..0) inc, bool|void local_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

    `bool ip_in_block(int net, int mask, int|string ip)`

  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

    `bool ip_less_global(int|string which, int|string towhat, bool|void prefer_v4)`

  Description

    Returns true if which is less globally accessible than towhat.

  Method ip_of

    `string ip_of(RemoteAddressObject|string|int(0..0) inc, bool|void local_address, string|void def)`

  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 ip_to_string(int ip, bool|void v6_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

    `bool is_ipv6(int|string ip)`

  Description

    Returns true if the IP ip is a IPV6 IP.

  Method is_local_host

    `bool is_local_host(RemoteAddressObject|string|int host, bool|void only_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

    `string is_local_network(RemoteAddressObject|int|string host)`

  Description

    Returns non-zero if host is on one of the local networks, and if so which interface it is on.

  Method local_host

    `string local_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|void include_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|void include_localhost)`

  Description

    Much like local_ips, but returns the IP:s parsed to the integer raw format.

  Method local_networks

    `IpRangeLookup local_networks()`

  Description

    Returns an IpRangeLookup that can be used to find the interface for an IP address.

  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.

  Method netmask_to_cidr

    `int netmask_to_cidr(string mask)`

  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 normalize_address(string a)`

  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

    `string port_of(RemoteAddressObject|string|int(0..0) inc, bool|void local_address, string|void def)`

  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)|void exclude_types, bool|void separate_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

    `IpRangeLookup special_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

    `int string_to_ip(string ips)`

  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

    `bool valid_domain_name(string hostname)`

  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.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 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.IpRangeLookup NetUtils.IpRangeLookup(mapping(mixed:array(string)) ranges, int|void _debug)`

    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

      `mixed lookup(int|string ipstr)`

    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

      `Range lookup_range(int|string ipstr)`

    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.

      Variable info

        `mixed NetUtils.IpRangeLookup.Range.info`

      Inherit NetMask

        inherit NetMask : NetMask

  CLASS NetUtils.NetMask

    Description

      Persistent representation of a network + mask.

    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.NetMask NetUtils.NetMask(string cidr)`

    Description

      Construct a new NetMask object from the given CIDR.

    Parameter `cidr`

      An IP and mask in CIDR notation.

    Method ip_in

      `bool ip_in(int|string ip)`

    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.

    Variable mask

      `int NetUtils.NetMask.mask`

    Description

      The network mask

    Variable net

      `int NetUtils.NetMask.net`

    Description

      The network number

  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 Nettle

  Description

    Low level crypto functions used by the Crypto module. Unless you are doing something very special, you would want to use the Crypto module instead.

  Method crypt_md5

    `string(7bit) crypt_md5(string(8bit) password, string(8bit) salt, void|string(8bit) magic)`

  Description

    Does the crypt_md5 abrakadabra (MD5 + snakeoil). It is assumed that salt does not contain "$".

    The password memory will be cleared before released.

  Method dsa_generate_keypair

    `array(Gmp.mpz) dsa_generate_keypair(int p_bits, int q_bits, function(int(0..):string(8bit)) rnd)`

  Description

    Generates a DSA key pair with p_bits number of bits (sometimes referred to as L) for p, and q_bits number of bits (sometimes referred to as N) for q, using the random function rnd.

    Valid combinations as per FIPS 186-3 are

           p_bits  q_bits
           1024    160
           2048    224 (rejected by some versions of Hogweed)
           2048    256
           3072    256

  Returns

    Array
    `Gmp.mpz 0` | The value p, the modulo.
    `Gmp.mpz 1` | The value q, the group order.
    `Gmp.mpz 2` | The value g, the generator.
    `Gmp.mpz 3` | The value y, the public value.
    `Gmp.mpz 4` | The value x, the private value.

  Method rsa_generate_keypair

    `array(Gmp.mpz) rsa_generate_keypair(int bits, int e, function(int(0..):string(8bit)) rnd)`

  Description

    Generates an RSA key pair with a bits sized modulus (n), using the provided value for e and random function rnd.

  Returns

    Array
    `Gmp.mpz 0` | The value n, the modulo.
    `Gmp.mpz 1` | The value d, the private exponent.
    `Gmp.mpz 2` | The value p, a prime.
    `Gmp.mpz 3` | The value q, a prime.

  Method rsa_unpad

    `int(0..) rsa_unpad(string(8bit) data, int type)`

  Description

    Unpads a message that has been padded according to RSAES-PKCS1-V1_5-ENCODE(message) in PKCS#1 v2.2. The padding method used on the original message must be provided in the type parameter. All content dependent processing is done in constant time for the same padding type and data length.

  CLASS Nettle.AEAD

    Description

      Represents information about an Authenticated Encryption with Associated Data (AEAD) algorithm, such as name, key size, digest size, and block size.

    Method block_size

      `int(0..) block_size()`

    Returns

      The block size of the AEAD algorithm.

    Note

      Note that AEAD algorithms often support automatic padding, so that the last block does not need to be complete.

    Method digest_size

      `int(0..) digest_size()`

    Description

      Returns the size of a MAC digest.

    Inherit AEAD

      inherit __builtin.Nettle.AEAD : AEAD

    Method iv_size

      `int(0..) iv_size()`

    Description

      Returns the size of the iv/nonce of the AEAD algorithm (if any).

      Returns `0` (zero) if there is no configurable iv/nonce.

    Method key_size

      `int(0..) key_size()`

    Returns

      The recommended key size for the cipher.

    Method name

      `string(8bit) name()`

    Returns

      A human readable name for the algorithm.

    CLASS Nettle.AEAD.State

      Description

        Base class for AEAD contexts.

      Method block_size

        `int(0..) block_size()`

      Returns

        The block size for this cipher.

      Note

        The default implementation just calls Cipher::block_size() in the parent.

      Method crypt

        `string(8bit) crypt(string(8bit) data)`

      Description

        Encrypts or decrypts data, using the current key. Neither the input nor output data is automatically memory scrubbed, unless String.secure has been called on them.

      Parameter `data`

        Data must be an integral number of blocks, except for the last segment.

      Returns

        The encrypted or decrypted data.

      Method digest

        `string(8bit) digest(int|void length)`

      Description

        Generates a digest, and resets the AEAD contents.

        Also updates the iv/nonce (if any).

      Parameter `length`

        If the length argument is provided, the digest is truncated to the given length.

      Returns

        The digest.

      Method digest_size

        `int(0..) digest_size()`

      Description

        Returns the size of a MAC digest.

      Inherit State

        inherit AEAD::State : State

      Method iv_size

        `int(0..) iv_size()`

      Description

        Returns the size of the iv/nonce of the AEAD algorithm (if any).

        Returns `0` (zero) if there is no configurable iv/nonce.

      Method key_size

        `int(0..) key_size()`

      Returns

        The actual key size for this cipher.

      Method make_key

        `string(8bit) make_key()`

      Description

        Generate a key by calling Crypto.Random.random_string and initialize this object for encryption with that key.

      Returns

        The generated key. The key memory will be cleared before released.

      See also

        set_encrypt_key

      Method name

        `string(8bit) name()`

      Returns

        A human readable name for the algorithm.

      Note

        The default implementation just calls Cipher::name() in the parent.

      Method set_decrypt_key

        `State set_decrypt_key(string(8bit) key)`

      Description

        Initializes the object for decryption. The key memory will be cleared before released.

      See also

        set_encrypt_key, crypt

      Method set_encrypt_key

        `State set_encrypt_key(string(8bit) key)`

      Description

        Initializes the object for encryption. The key memory will be cleared before released.

      See also

        set_decrypt_key, crypt

      Method set_iv

        `State set_iv(string(8bit) iv)`

      Description

        Set the iv/nonce (if supported) for the AEAD.

      Returns

        Returns `this` in order to simplify chaining of function calls.

      Method update

        `State update(string(8bit) data)`

      Description

        Add some more associated data.

        All associated data typically needs to be added before any data to actually encrypt.

      Returns

        Returns `this` in order to simplify chaining of function calls.

  CLASS Nettle.AES

    Description

      Implementation of the AES cipher.

    Inherit BlockCipher16

      inherit BlockCipher16 : BlockCipher16

    CLASS Nettle.AES.State

      Description

        State for AES encyption.

      Inherit State

        inherit Cipher::State : State

  CLASS Nettle.ARCFOUR

    Description

      Implementation of the ARCFOUR cipher.

    Inherit Cipher

      inherit Cipher : Cipher

    CLASS Nettle.ARCFOUR.State

      Description

        State for ARCFOUR encyption.

      Inherit State

        inherit Cipher::State : State

  CLASS Nettle.ARCTWO

    Description

      Implementation of the ARCTWO cipher.

    Inherit BlockCipher

      inherit BlockCipher : BlockCipher

    CLASS Nettle.ARCTWO.State

      Description

        State for PIKE_NAME encyption.

      Inherit State

        inherit Cipher::State : State

      Method set_decrypt_key

        `State set_decrypt_key(string(8bit) key, void|int ekb)`

      Description

        Initializes the object for decryption. The key memory will be cleared before released.

      Parameter `ekb`

        The effective number of bits in the key.

        `UNDEFINED` | Derive from the key size (ie `8 * sizeof(key)`).
        `0` | Convenience alias for max (ie `1024`).
        `(1..1024)` | Reduce the effective key size to the specified number of bits.

      See also

        set_encrypt_key, crypt

      Method set_encrypt_key

        `State set_encrypt_key(string(8bit) key, int|void ekb)`

      Description

        Initializes the object for encryption. The key memory will be cleared before released.

      Parameter `ekb`

        The effective number of bits in the key.

        `UNDEFINED` | Derive from the key size (ie `8 * sizeof(key)`).
        `0` | Convenience alias for max (ie `1024`).
        `(1..1024)` | Reduce the effective key size to the specified number of bits.

      See also

        set_decrypt_key, crypt

  CLASS Nettle.BLOWFISH

    Description

      Implementation of the BLOWFISH cipher.

    Inherit BlockCipher

      inherit BlockCipher : BlockCipher

    CLASS Nettle.BLOWFISH.State

      Description

        State for BLOWFISH encyption.

      Inherit State

        inherit Cipher::State : State

  CLASS Nettle.BlockCipher

    Description

      Base class for all block ciphers.

      Extends the BufferedCipher class with various operating modes.

    Inherit BlockCipher

      inherit __builtin.Nettle.BlockCipher : BlockCipher

    Inherit BufferedCipher

      inherit BufferedCipher : BufferedCipher

    Module Nettle.BlockCipher.CBC

      Description

        Implementation of the cipher block chaining mode (CBC).

        Works as a wrapper for the cipher implemented by overloading the parent class (Cipher).

      See also

        Crypto.CBC, GCM

      Inherit BufferedCipher

        inherit BufferedCipher : BufferedCipher

      CLASS Nettle.BlockCipher.CBC.State

        Method block_size

          `int(1..) block_size()`

        Description

          Returns the block size of the encapsulated cipher.

        Method create

          `Nettle.BlockCipher.CBC.State Nettle.BlockCipher.CBC.State()`

        Description

          Initialize the CBC state with the Cipher::State object returned by substate_factory(). This is usually the State for the cipher implemented in the parent module.

        Method crypt

          `string(8bit) crypt(string(8bit) data)`

        Description

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

          Neither the input or output data is not automatically memory scrubbed, unless String.secure has been called on the data.

        Inherit State

          inherit Cipher::State : State

        Method iv_size

          `int(1..) iv_size()`

        Description

          Returns the size for the initialization vector

        Method key_size

          `int(1..) key_size()`

        Description

          Returns the key size of the encapsulated cipher.

        Method name

          `string(8bit) name()`

        Description

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

        Method set_decrypt_key

          `this_program set_decrypt_key(string(8bit) key, int|void flags)`

        Description

          Prepare the cipher and the wrapper for decrypting with the given key. The key memory will be cleared before released.

        Method set_encrypt_key

          `this_program set_encrypt_key(string(8bit) key, int|void flags)`

        Description

          Prepare the cipher and the wrapper for encrypting with the given key. The key memory will be cleared before released.

        Method set_iv

          `this_program set_iv(string(8bit) iv)`

        Description

          Set the initialization vector to iv. The iv memory will be cleared before released.

        Method substate_factory

          `Cipher::State substate_factory()`

        Description

          Returns the Cipher::State object that this object is to operate on.

          Defaults to creating the State for the cipher implemented in the parent module.

    Module Nettle.BlockCipher.CFB

      Description

        Implementation of Cipher Feed-Back mode (CFB).

      See also

        CBC, GCM

      Method `()

        `State res = Nettle.BlockCipher()()`

      Returns

        Returns a new State object.

      Inherit BufferedCipher

        inherit BufferedCipher : BufferedCipher

      Method name

        `string(8bit) name()`

      Description

        Returns the base cipher name appended with the string `".CFB"`.

      CLASS Nettle.BlockCipher.CFB.State

        Description

          The state for a CFB instance.

        Method block_size

          `int(1..) block_size()`

        Description

          Returns the block size of the encapsulated cipher.

        Method create

          `Nettle.BlockCipher.CFB.State Nettle.BlockCipher.CFB.State()`

        Description

          Initialize the CFB state with the Cipher::State object returned by substate_factory(). This is usually the State for the cipher implemented in the parent module.

        Method crypt

          `string(8bit) crypt(string(8bit) data)`

        Description

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

          The length of data MUST be a multiple of the block size for all calls except the last.

          Neither the input or output data is not automatically memory scrubbed, unless String.secure has been called on the data.

        See also

          update(), digest()

        Inherit State

          inherit BufferedCipher::State : State

        Method iv_size

          `int(1..) iv_size()`

        Description

          Returns the size for the initialization vector

        Method key_size

          `int(1..) key_size()`

        Description

          Returns the key size of the encapsulated cipher.

        Method name

          `string(8bit) name()`

        Description

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

        Variable obj

          `object Nettle.BlockCipher.CFB.State.obj`

        Note

          Read only

        Method set_decrypt_key

          `this_program set_decrypt_key(string(8bit) key, int|void flags)`

        Description

          Prepare the cipher and the wrapper for decrypting with the given key. The key memory will be cleared before released.

        Note

          Note that this operation does not by itself reset the context sufficiently to start a new message; set_iv() needs to be called too.

        See also

          set_encrypt_key(), set_iv()

        Method set_encrypt_key

          `this_program set_encrypt_key(string(8bit) key, int|void flags)`

        Description

          Prepare the cipher and the wrapper for encrypting with the given key. The key memory will be cleared before released.

        Note

          Note that this operation does not by itself reset the context sufficiently to start a new message; set_iv() needs to be called too.

        See also

          set_decrypt_key(), set_iv()

        Method set_iv

          `this_program set_iv(string(8bit) iv)`

        Description

          Set the initialization vector to iv. The iv memory will be cleared before released.

        Note

          iv must have the length reported by iv_size().

        See also

          set_encrypt_key(), set_decrypt_key().

        Method substate_factory

          `Cipher::State substate_factory()`

        Description

          Returns the Cipher::State object that this object is to operate on.

          Defaults to creating the State for the cipher implemented in the parent module.

    Module Nettle.BlockCipher.CTR

      Description

        Implementation of Counter Mode (CTR).

        This cipher mode works like a stream cipher with a block size >= 1. This means that the same key and initialization vector (aka counter) should never be reused, since a simple xor would reveal information about the plain text. It also means that it should never be used without a suiteable Message Authentication Code (MAC).

      See also

        CBC, GCM, Buffer

      Method `()

        `State res = Nettle.BlockCipher()()`

      Returns

        Returns a new State object.

      Inherit Cipher

        inherit __builtin.Nettle.Cipher : Cipher

      Method name

        `string(8bit) name()`

      Description

        Returns the base cipher name appended with the string `".CTR"`.

      CLASS Nettle.BlockCipher.CTR.State

        Description

          The state for a CTR instance.

        Method block_size

          `int(1..) block_size()`

        Description

          Returns the block size of the encapsulated cipher.

        Method create

          `Nettle.BlockCipher.CTR.State Nettle.BlockCipher.CTR.State()`

        Description

          Initialize the CTR state with the Cipher::State object returned by substate_factory(). This is usually the State for the cipher implemented in the parent module.

        Method crypt

          `string(8bit) crypt(string(8bit) data)`

        Description

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

          The length of data MUST be a multiple of the block size for all calls except the last.

          Neither the input or output data is not automatically memory scrubbed, unless String.secure has been called on the data.

        See also

          update(), digest()

        Inherit State

          inherit Cipher::State : State

        Method iv_size

          `int(1..) iv_size()`

        Description

          Returns the size for the initialization vector

        Method key_size

          `int(1..) key_size()`

        Description

          Returns the key size of the encapsulated cipher.

        Method name

          `string(8bit) name()`

        Description

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

        Variable obj

          `object Nettle.BlockCipher.CTR.State.obj`

        Note

          Read only

        Method set_decrypt_key

          `this_program set_decrypt_key(string(8bit) key, int|void flags)`

        Description

          Prepare the cipher and the wrapper for decrypting with the given key. The key memory will be cleared before released.

        Note

          Note that this operation does not by itself reset the context sufficiently to start a new message; set_iv() needs to be called too.

        See also

          set_encrypt_key(), set_iv()

        Method set_encrypt_key

          `this_program set_encrypt_key(string(8bit) key, int|void flags)`

        Description

          Prepare the cipher and the wrapper for encrypting with the given key. The key memory will be cleared before released.

        Note

          Note that this operation does not by itself reset the context sufficiently to start a new message; set_iv() needs to be called too.

        See also

          set_decrypt_key(), set_iv()

        Method set_iv

          `this_program set_iv(string(8bit) iv)`

        Description

          Set the initialization vector to iv. The iv memory will be cleared before released.

        Note

          iv must have the length reported by iv_size().

        See also

          set_encrypt_key(), set_decrypt_key().

        Method substate_factory

          `Cipher::State substate_factory()`

        Description

          Returns the Cipher::State object that this object is to operate on.

          Defaults to creating the State for the cipher implemented in the parent module.

    Module Nettle.BlockCipher.OFB

      Description

        Implementation of Output Feed-Back mode (OFB).

        This cipher mode works like a stream cipher with a block size >= 1. This means that the same key and initialization vector (aka counter) should never be reused, since a simple xor would reveal information about the plain text. It also means that it should never be used without a suiteable Message Authentication Code (MAC).

      See also

        CFB, CBC, CTR, GCM

      Method `()

        `State res = Nettle.BlockCipher()()`

      Returns

        Returns a new State object.

      Inherit BufferedCipher

        inherit BufferedCipher : BufferedCipher

      Method name

        `string(8bit) name()`

      Description

        Returns the base cipher name appended with the string `".OFB"`.

      CLASS Nettle.BlockCipher.OFB.State

        Description

          The state for a OFB instance.

        Method block_size

          `int(1..) block_size()`

        Description

          Returns the block size of the encapsulated cipher.

        Method create

          `Nettle.BlockCipher.OFB.State Nettle.BlockCipher.OFB.State()`

        Description

          Initialize the OFB state with the Cipher::State object returned by substate_factory(). This is usually the State for the cipher implemented in the parent module.

        Method crypt

          `string(8bit) crypt(string(8bit) data)`

        Description

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

          The length of data MUST be a multiple of the block size for all calls except the last.

          Neither the input or output data is not automatically memory scrubbed, unless String.secure has been called on the data.

        See also

          update(), digest()

        Inherit State

          inherit BufferedCipher::State : State

        Method iv_size

          `int(1..) iv_size()`

        Description

          Returns the size for the initialization vector

        Method key_size

          `int(1..) key_size()`

        Description

          Returns the key size of the encapsulated cipher.

        Method name

          `string(8bit) name()`

        Description

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

        Variable obj

          `object Nettle.BlockCipher.OFB.State.obj`

        Note

          Read only

        Method set_decrypt_key

          `this_program set_decrypt_key(string(8bit) key, int|void flags)`

        Description

          Prepare the cipher and the wrapper for decrypting with the given key. The key memory will be cleared before released.

        Note

          Note that this operation does not by itself reset the context sufficiently to start a new message; set_iv() needs to be called too.

        See also

          set_encrypt_key(), set_iv()

        Method set_encrypt_key

          `this_program set_encrypt_key(string(8bit) key, int|void flags)`

        Description

          Prepare the cipher and the wrapper for encrypting with the given key. The key memory will be cleared before released.

        Note

          Note that this operation does not by itself reset the context sufficiently to start a new message; set_iv() needs to be called too.

        See also

          set_decrypt_key(), set_iv()

        Method set_iv

          `this_program set_iv(string(8bit) iv)`

        Description

          Set the initialization vector to iv. The iv memory will be cleared before released.

        Note

          iv must have the length reported by iv_size().

        See also

          set_encrypt_key(), set_decrypt_key().

        Method substate_factory

          `Cipher::State substate_factory()`

        Description

          Returns the Cipher::State object that this object is to operate on.

          Defaults to creating the State for the cipher implemented in the parent module.

    Module Nettle.BlockCipher.PCBC

      Description

        Implementation of the propagating cipher block chaining mode (PCBC).

        This mode is also known as plaintext cipher block chaining (from Kerberos v4).

        Works as a wrapper for the cipher implemented by overloading the parent class (Cipher).

      See also

        CBC, GCM

      Inherit _CBC

        inherit _CBC : _CBC

      CLASS Nettle.BlockCipher.PCBC.State

        Method crypt

          `string(8bit) crypt(string(8bit) data)`

        Description

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

          Neither the input or output data is not automatically memory scrubbed, unless String.secure has been called on the data.

        Inherit State

          inherit _CBC::State : State

        Method name

          `string(8bit) name()`

        Description

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

  CLASS Nettle.BlockCipher16

    Description

      This is the BlockCipher class extended with algorithms that require a block size of `16` bytes.

    See also

      Cipher, BlockCipher, BufferedCipher, GCM

    Inherit BlockCipher

      inherit BlockCipher : BlockCipher

    Module Nettle.BlockCipher16.CCM

      Description

        Implementation of the Counter with Cipher Block Chaining Message Authentication Code mode (CCM).

        Works as a wrapper for the cipher implemented by overloading the parent class (BlockCipher16).

        This is a so-called authenticated encryption with associated data (AEAD) algorithm, and in addition to encryption also provides message digests.

        The operation of CCM is specified in NIST Special Publication 800-38C.

      Note

        This mode of operation is not suited for streaming operation, as the sizes of the associated data and payload data need to be known for the CBC-MAC operation to start. Currently this means that the associated data and payload data are buffered until State()->digest() is called.

      See also

        CCM8, CBC, GCM, CTR

      Method digest_size

        `int(4..16) digest_size()`

      Description

        Default digest size.

      Returns

        Returns `16`, but overloading via inherit is supported, and may return any even number in the range `[4..16]`.

      Note

        Note that the digest length is folded into the digest, so it doesn't simply imply a truncation.

      Inherit AEAD

        inherit __builtin.Nettle.AEAD : AEAD

      Inherit CTR

        inherit BlockCipher::CTR : CTR

      Method name

        `string(8bit) name()`

      Description

        Returns the name of the base cipher with `".CCM"` appended.

      CLASS Nettle.BlockCipher16.CCM.State

        Method create

          `Nettle.BlockCipher16.CCM.State Nettle.BlockCipher16.CCM.State()`

        Method digest

          `string(8bit) digest(int(4..16)|void bytes)`

        Description

          Returns the CBC-MAC digest of the specified size.

        Parameter `bytes`

          Size in bytes for the desired digest. Any even number in the range `[4..16]`. If not specified the value from calling digest_size() will be used.

        Note

          Note that the digest length is folded into the digest, so it doesn't simply imply a truncation.

        See also

          digest_size(), global::digest_size()

        Method digest_size

          `int(4..16) digest_size()`

        Description

          Default digest size.

          This function is used by digest() to determine the digest size if no argument was given.

        Returns

          The default implementation returns the result from calling global::digest_size(), but overloading via inherit is supported, and may return any even number in the range `[4..16]`.

        Note

          Note that the digest length is folded into the digest, so it doesn't simply imply a truncation.

        See also

          digest(), CCM::digest_size()

        Inherit State

          inherit CTR::State : State

    Module Nettle.BlockCipher16.CCM8

      Description

        Special case of CCM where the default digest size has been truncated to `8` bytes.

      See also

        CCM, CBC, GCM, CTR

      Method digest_size

        `int(4..16) digest_size()`

      Description

        Default digest size.

      Returns

        Returns `8`, but overloading via inherit is supported, and may return any even number in the range `[4..16]`.

      Inherit CCM

        inherit CCM : CCM

      Method name

        `string(8bit) name()`

      Description

        Returns the name of the base cipher with `".CCM8"` appended.

    Module Nettle.BlockCipher16.EAX

      Description

        Implementation of the EAX mode.

        Works as a wrapper for the cipher implemented by overloading the parent class (BlockCipher16).

        This is a so-called authenticated encryption with associated data (AEAD) algorithm, and in addition to encryption also provides message digests.

      Note

        This mode of operation was specified as a reaction to the limitiations of the BlockCipher16.CCM mode.

      Note

        Note that this module is not available in all versions of Nettle.

      See also

        CBC, CTR, BlockCipher16.CCM, BlockCipher16.GCM

      Method digest_size

        `int(1..) digest_size()`

      Description

        Default digest size.

      Returns

        Returns BlockCipher::block_size(), but overloading via inherit is supported, and may return any positive number `<= BlockCipher::block_size()`.

      Inherit AEAD

        inherit __builtin.Nettle.AEAD : AEAD

      Method name

        `string(8bit) name()`

      Description

        Returns the name of the base cipher with `".EAX"` appended.

      CLASS Nettle.BlockCipher16.EAX.State

        Method block_size

          `int(16..16) block_size()`

        Description

          Returns the block size of the encapsulated cipher, which is always `16` for EAX.

        Method create

          `Nettle.BlockCipher16.EAX.State Nettle.BlockCipher16.EAX.State()`

        Method digest

          `string(8bit) digest(int(1..16)|void bytes)`

        Description

          Returns the OMAC digest of the specified size.

        Parameter `bytes`

          Size in bytes for the desired digest. Any number in the range `[1..16]`. If not specified the value from calling digest_size() will be used.

        See also

          digest_size(), global::digest_size()

        Method digest_size

          `int(1..16) digest_size()`

        Description

          Default digest size.

          This function is used by digest() to determine the digest size if no argument was given.

        Returns

          The default implementation returns the result from calling EAX::digest_size(), but overloading via inherit is supported, and may return any even number in the range `[1..16]`.

        See also

          digest(), EAX::digest_size()

        Inherit State

          inherit AEAD::State : State

        Method iv_size

          `int(16..16) iv_size()`

        Description

          Returns the recommended size for the initialization vector (ie `16`).

          Other sizes are allowed, but will be compressed or expanded to this size using the encapsulated cipher.

        Method key_size

          `int(1..) key_size()`

        Description

          Returns the key size of the encapsulated cipher.

        Method name

          `string(8bit) name()`

        Description

          Returns the string `"x.EAX"` where x is the encapsulated algorithm.

        Method set_decrypt_key

          `this_program set_decrypt_key(string(8bit) key, int|void flags)`

        Description

          Prepare the cipher and the wrapper for decrypting with the given key. The key memory will be cleared before released.

        Note

          Note that this operation does not by itself reset the context sufficiently to start a new message; set_iv() needs to be called too.

        See also

          set_encrypt_key(), set_iv()

        Method set_encrypt_key

          `this_program set_encrypt_key(string(8bit) key, int|void flags)`

        Description

          Prepare the cipher and the wrapper for encrypting with the given key. The key memory will be cleared before released.

        Note

          Note that this operation does not by itself reset the context sufficiently to start a new message; set_iv() needs to be called too.

        See also

          set_decrypt_key(), set_iv()

        Method substate_factory

          `Cipher::State substate_factory()`

        Description

          Returns the Cipher::State object that this object is to operate on.

          Defaults to creating the State for the cipher implemented in the parent module.

    Module Nettle.BlockCipher16.GCM

      Description

        Implementation of the Galois Counter Mode (GCM).

        Works as a wrapper for the cipher implemented by overloading the parent class (BlockCipher16).

        This is a so-called authenticated encryption with associated data (AEAD) algorithm, which in addition to encryption also provides message digests.

        The operation of GCM is specified in NIST Special Publication 800-38D.

        Typically accessed as `Crypto.AES.GCM` or `Crypto.Camellia.GCM`

      Note

        Note that this module is not available in all versions of Nettle.

      See also

        CBC

      Method block_size

        `int(16..16) block_size()`

      Description

        Returns the block size of the encapsulated cipher, which is always `16` for GCM.

      Method digest_size

        `int(16..16) digest_size()`

      Description

        Returns the size of the generated digest, which is always `16` for GCM.

      Inherit AEAD

        inherit __builtin.Nettle.AEAD : AEAD

      Method iv_size

        `int(12..12) iv_size()`

      Description

        Returns the recommended size for the initialization vector (ie `12`).

        Other sizes are allowed, but will be compressed or expanded to this size using the encapsulated cipher.

      Method name

        `string(8bit) name()`

      Description

        Returns the name of the base cipher with `".GCM"` appended.

      CLASS Nettle.BlockCipher16.GCM.State

        Description

          The state for a GCM instance.

        Method block_size

          `int(16..16) block_size()`

        Description

          Returns the block size of the encapsulated cipher, which is always `16` for GCM.

        Method create

          `Nettle.BlockCipher16.GCM.State Nettle.BlockCipher16.GCM.State()`

        Description

          Initialize the GCM state with the Cipher::State object returned by substate_factory(). This is usually the State for the cipher implemented in the parent module.

        Method crypt

          `string(8bit) crypt(string(8bit) data)`

        Description

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

          The length of data MUST be a multiple of the block size (ie `16`) for all calls except the last.

          Neither the input or output data is not automatically memory scrubbed, unless String.secure has been called on the data.

        See also

          update(), digest()

        Method digest

          `string(8bit) digest()`

        Description

          Generate a message digest for the data accumulated so far.

        Note

          set_iv() needs to be called to start the next message.

        See also

          update(), digest()

        Method digest_size

          `int(16..16) digest_size()`

        Description

          Returns the size of the generated digest, which is always `16` for GCM.

        Inherit State

          inherit AEAD::State : State

        Method iv_size

          `int(12..12) iv_size()`

        Description

          Returns the recommended size for the initialization vector (ie `12`).

          Other sizes are allowed, but will be compressed or expanded to this size using the encapsulated cipher.

        Method key_size

          `int(1..) key_size()`

        Description

          Returns the key size of the encapsulated cipher.

        Method name

          `string(8bit) name()`

        Description

          Returns the string `"x.GCM"` where x is the encapsulated algorithm.

        Method set_decrypt_key

          `this_program set_decrypt_key(string(8bit) key, int|void flags)`

        Description

          Prepare the cipher and the wrapper for decrypting with the given key. The key memory will be cleared before released.

        Note

          Note that this operation does not by itself reset the context sufficiently to start a new message; set_iv() needs to be called too.

        See also

          set_encrypt_key(), set_iv()

        Method set_encrypt_key

          `this_program set_encrypt_key(string(8bit) key, int|void flags)`

        Description

          Prepare the cipher and the wrapper for encrypting with the given key. The key memory will be cleared before released.

        Note

          Note that this operation does not by itself reset the context sufficiently to start a new message; set_iv() needs to be called too.

        See also

          set_decrypt_key(), set_iv()

        Method set_iv

          `this_program set_iv(string(8bit) iv)`

        Description

          Set the initialization vector to iv. The iv memory will be cleared before released.

          Also resets all state needed to start a new message.

        Note

          For ivs of length other than `12`, an encryption or decryption key must have been set first.

        See also

          set_encrypt_key(), set_decrypt_key().

        Method substate_factory

          `Cipher::State substate_factory()`

        Description

          Returns the Cipher::State object that this object is to operate on.

          Defaults to creating the State for the cipher implemented in the parent module.

        Method update

          `void update(string(8bit) public_data)`

        Description

          Add public_data to be authenticated.

          The length of public_data MUST be a multiple of the block size (ie `16`) for all calls except the last.

          All calls of update() need to be performed before any calls of crypt().

  CLASS Nettle.BufferedCipher

    Description

      Extends the Cipher class with the Buffer meta cipher. This is in turn inherited by the BlockCipher class, which is the base class for all block ciphers.

    Inherit Cipher

      inherit Cipher : Cipher

    Module Nettle.BufferedCipher.Buffer

      Description

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

      Example

            class Encrypter
               {
                 protected Crypto.Cipher buffer;
                 void create(string key)
                 {
                   buffer = Crypto.AES.CBC.Buffer();
                   buffer->set_encrypt_key(key);
                 }
                 string feed(string data)
                 {
                   return buffer->crypt(data);
                 }
                 string drain()
                 {
                   return buffer->pad(Crypto.PAD_PKCS7);
                 }
               }

      See also

        BlockCipher.CBC, BlockCipher16.GCM

      Method `()

        `State res = Nettle.BufferedCipher()()`

      Returns

        Returns a new State object.

      Inherit Cipher

        inherit __builtin.Nettle.Cipher : Cipher

      CLASS Nettle.BufferedCipher.Buffer.State

        Description

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

        Example

              class Encrypter
                 {
                   protected Crypto.Cipher buffer;
                   void create(string key)
                   {
                     buffer = Crypto.AES.CBC.Buffer();
                     buffer->set_encrypt_key(key);
                   }
                   string feed(string data)
                   {
                     return buffer->crypt(data);
                   }
                   string drain()
                   {
                     return buffer->pad(Crypto.PAD_PKCS7);
                   }
                 }

        See also

          BlockCipher.CBC, BlockCipher16.GCM

        Method block_size

          `int(1..) block_size()`

        Description

          Get the block size of the contained block crypto.

        Method create

          `Nettle.BufferedCipher.Buffer.State Nettle.BufferedCipher.Buffer.State()`

        Description

          Initialize the buffer with the Cipher::State object returned by substate_factory(). This is usually the State for the cipher implemented in the parent module.

        Method crypt

          `string(8bit) crypt(string(8bit) data)`

        Description

          Encrypt or decrypt some data.

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

          Neither the input or output data is not automatically memory scrubbed, unless String.secure has been called on the data.

        Method iv_size

          `int(0..) iv_size()`

        Description

          Get the iv size of the contained block crypto.

        Method key_size

          `int(1..) key_size()`

        Description

          Get the key size of the contained block crypto.

        Method name

          `string(8bit) name()`

        Description

          Returns the name of the wrapped cipher with `".Buffer"` appended.

        Method pad

          `string(8bit) pad(void|int method)`

        Description

          Pad and encrypt any data left in the buffer. The output data is not automatically memory scrubbed, unless String.secure is called on the data.

        Parameter `method`

          The type of padding to apply to the buffer.

          `Crypto.PAD_ISO_10126` | Pads according to ISO 10126, which means filling all extra space with random data and putting the size of the non-payload data last.
          `Crypto.PAD_TLS` | Pads according to RFC 5246 section 6.2.3.2, meaning that all extra space is filled with the size of the padding. Note that this size has an off by one difference to the other schemas, so 0 means 1 byte of padding.
          `Crypto.PAD_SSL`
          `Crypto.PAD_ANSI_X923` | Pads according to ANSI X.923, which means filling all extra space with zero and putting the size of the non-payload data last.
          `Crypto.PAD_PKCS7` | Pads according to PKCS7 / RFC 3852, which means filling all extra space with the size of the extra space.
          `Crypto.PAD_ZERO` | Fills the extra space with null bytes. To correctly remove the padding the clear text data must not end with a null byte. In that case the data would have to be manually padded/unpadded before/after calling crypt().

          Defaults to Crypto.PAD_SSL for compatibility reasons.

        See also

          unpad()

        Method set_decrypt_key

          `this_program set_decrypt_key(string(8bit) key, void|int flags)`

        Description

          Set the decryption key. The key memory will be cleared before released.

        Note

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

        Method set_encrypt_key

          `this_program set_encrypt_key(string(8bit) key, void|int flags)`

        Description

          Set the encryption key. The key memory will be cleared before released.

        Note

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

        Method set_iv

          `this_program set_iv(string(8bit) iv)`

        Description

          Set the initialization vector to iv.

        Method substate_factory

          `Cipher::State substate_factory()`

        Description

          Returns the Cipher::State object that this object is to operate on.

          Defaults to creating the State for the cipher implemented in the parent module.

        Method unpad

          `string(8bit) unpad(string(8bit) data, void|int method)`

        Description

          Decrypt and unpad a block of data. Neither the input or output data is not automatically memory scrubbed, unless String.secure has been called on the data.

          This performs the reverse operation of pad(). The padding will be verified to be correct, if possible. If not, zero is returned.

        Parameter `method`

          The type of padding that was applied to the original buffer.

          `Crypto.PAD_SSL`
          `Crypto.PAD_TLS`
          `Crypto.PAD_ISO_10126`
          `Crypto.PAD_ANSI_X923`
          `Crypto.PAD_PKCS7`
          `Crypto.PAD_ZERO`

          Defaults to Crypto.PAD_SSL for compatibility reasons.

        See also

          pad()

  CLASS Nettle.CAMELLIA

    Description

      Implementation of the CAMELLIA cipher.

    Inherit BlockCipher16

      inherit BlockCipher16 : BlockCipher16

    CLASS Nettle.CAMELLIA.State

      Description

        State for CAMELLIA encyption.

      Inherit State

        inherit Cipher::State : State

  CLASS Nettle.CAST128

    Description

      Implementation of the CAST128 cipher.

    Inherit BlockCipher

      inherit BlockCipher : BlockCipher

    CLASS Nettle.CAST128.State

      Description

        State for CAST128 encyption.

      Inherit State

        inherit Cipher::State : State

  CLASS Nettle.CHACHA

    Description

      Implementation of the CHACHA stream cipher.

    Note

      Note that this class is not available in all versions of Nettle.

    Inherit BlockCipher

      inherit BlockCipher : BlockCipher

    CLASS Nettle.CHACHA.State

      Description

        State for CHACHA encyption.

      Method crypt

        `string(8bit) crypt(string(8bit) data)`

      Description

        Encrypts or decrypts data, using the current key. Neither the input nor output data is automatically memory scrubbed, unless String.secure has been called on them.

      Parameter `data`

        Usually an integral number of blocks, except for the last segement in a run. The decoder must get partial blocks at the same places as the encoder, otherwise they will get out of sync.

      Returns

        The encrypted or decrypted data.

      Inherit State

        inherit Cipher::State : State

      Method set_iv

        `object set_iv(string(8bit) iv)`

      Description

        Set the initialization vector (aka nonce) and reset the block counter to zero.

      Parameter `iv`

        An 8-byte long string which is only to be used once for every key.

      Note

        This function MUST be called in addition to set_encrypt_key() or set_decrypt_key().

      Note

        The same iv should NEVER be reused with the same key!

  CLASS Nettle.CHACHA_POLY1305

    Description

      Implementation of the CHACHA_POLY1305 AEAD algorithm.

    Inherit AEAD

      inherit AEAD : AEAD

    CLASS Nettle.CHACHA_POLY1305.State

      Description

        State for CHACHA_POLY1305 encyption.

      Inherit State

        inherit AEAD::State : State

  CLASS Nettle.Cipher

    Description

      Represents information about a cipher algorithm, such as name, key size, and block size.

    Method block_size

      `int(1..) block_size()`

    Returns

      The block size of the cipher (1 for stream ciphers).

    Inherit Cipher

      inherit __builtin.Nettle.Cipher : Cipher

    Method key_size

      `int(1..) key_size()`

    Returns

      The recommended key size for the cipher.

    Method name

      `string(8bit) name()`

    Returns

      A human readable name for the algorithm.

    CLASS Nettle.Cipher.State

      Description

        Base class for cipher contexts.

      Method block_size

        `int(1..) block_size()`

      Returns

        The block size for this cipher.

      Note

        The default implementation just calls Cipher::block_size() in the parent.

      Method crypt

        `string(8bit) crypt(string(8bit) data)`

      Description

        Encrypts or decrypts data, using the current key. Neither the input nor output data is automatically memory scrubbed, unless String.secure has been called on them.

      Parameter `data`

        For block ciphers, data must be an integral number of blocks.

      Returns

        The encrypted or decrypted data.

      Inherit State

        inherit Cipher::State : State

      Method key_size

        `int(1..) key_size()`

      Returns

        The actual key size for this cipher.

      Method make_key

        `string(8bit) make_key()`

      Description

        Generate a key by calling Crypto.Random.random_string and initialize this object for encryption with that key.

      Returns

        The generated key. The key memory will be cleared before released.

      See also

        set_encrypt_key

      Method name

        `string(8bit) name()`

      Returns

        A human readable name for the algorithm.

      Note

        The default implementation just calls Cipher::name() in the parent.

      Method set_decrypt_key

        `State set_decrypt_key(string(8bit) key, void|int flags)`

      Description

        Initializes the object for decryption. The key memory will be cleared before released.

      See also

        set_encrypt_key, crypt

      Method set_encrypt_key

        `State set_encrypt_key(string(8bit) key, void|int flags)`

      Description

        Initializes the object for encryption. The key memory will be cleared before released.

      See also

        set_decrypt_key, crypt

  CLASS Nettle.DES

    Description

      Implementation of the Data Encryption Standard (DES) crypto algorithm.

    Method fix_parity

      `string(8bit) fix_parity(string(8bit) key)`

    Description

      Sets the last bit in every byte in key to reflect the parity. If a seven byte key is used, it will be expanded into eight bytes. If a key longer than eight characters is used, it will be truncated to eight characters.

    Inherit BlockCipher

      inherit BlockCipher : BlockCipher

    CLASS Nettle.DES.State

      Description

        State for DES encyption

      Method fix_parity

        `string(8bit) fix_parity(string(8bit) key)`

      Description

        Sets the last bit in every byte in key to reflect the parity. If a seven byte key is used, it will be expanded into eight bytes. If a key longer than eight characters is used, it will be truncated to eight characters.

      Inherit State

        inherit Cipher::State : State

  CLASS Nettle.DES3

    Description

      Implementation of the DES3 cipher algorithm.

    Method fix_parity

      `string(8bit) fix_parity(string(8bit) key)`

    Description

      Sets the last bit in every byte in key to reflect the parity. If a 21 byte key is used, it will be expanded into 24 bytes. If a key longer than 24 characters is used, it will be truncated to 24 characters.

    Inherit BlockCipher

      inherit BlockCipher : BlockCipher

    CLASS Nettle.DES3.State

      Description

        State for DES3 encyption

      Inherit State

        inherit Cipher::State : State

  CLASS Nettle.DH_Params

    Description

      Diffie-Hellman Parameters.

    Variable g

      `Gmp.mpz Nettle.DH_Params.g`

    Description

      Generator.

    Method generate

      `void generate(int p_bits, int q_bits, function(int(0..):string(8bit)) rnd)`

    Description

      Generate a new set of Diffie-Hellman parameters.

    Note

      Throws errors for unsupported parameters.

    Note

      This function is not available in all installations of Pike.

    Method generate_keypair

      `array(Gmp.mpz) generate_keypair(function(int(0..):string(8bit)) rnd)`

    Description

      Generate a Diffie-Hellman key pair.

    Returns

      Returns the following array:

      Array
      `Gmp.mpz 0` | The generated public key.
      `Gmp.mpz 1` | The corresponding private key.

    Variable p

      `Gmp.mpz Nettle.DH_Params.p`

    Description

      Prime.

    Variable q

      `Gmp.mpz Nettle.DH_Params.q`

    Description

      Order.

  CLASS Nettle.ECC_Curve

    Description

      Elliptic Curve Definition

    Method `*

      `Point res = Nettle.ECC_Curve() * scalar`

    Description

      Multiply the curve by a scalar.

      This can be used to get the public key from a private key.

    Returns

      Returns a new Point on the curve.

    Method create

      `Nettle.ECC_Curve Nettle.ECC_Curve(int(0..) family, int(0..) field_size, int(0..) revision)`

    Description

      Initialize the curve.

    Inherit ECC_Curve

      inherit __builtin.Nettle.ECC_Curve : ECC_Curve

    Method name

      `string(7bit) name()`

    Description

      Returns the name of the curve.

    Method new_scalar

      `Gmp.mpz new_scalar(function(int(0..):string(8bit)) rnd)`

    Parameter `rnd`

      Randomness function to use as source.

    Returns

      Returns a random scalar suitable to use as an ECDSA private key or as an ECDH exponent.

    Method point_mul

      `Point point_mul(Gmp.mpz|int x, Gmp.mpz|int y, Gmp.mpz|int scalar)`

    Description

      Multiply a point on the curve by a scalar.

      A typical use is for Elliptic Curve Diffie Hellman (ECDH) key exchange.

      This is equivalent to `(Point(x, y) * scalar)`.

    Returns

      Returns the new Point on the curve.

    Throws

      Throws an error if the point (x, y) isn't on the curve.

    Method size

      `int size()`

    Returns

      Returns the size in bits for a single coordinate on the curve.

    CLASS Nettle.ECC_Curve.ECDSA

      Description

        Elliptic Curve Digital Signing Algorithm

      Method generate_key

        `void generate_key()`

      Description

        Generate a new set of private and public keys on the current curve.

      Method get_curve

        `ECC_Curve get_curve()`

      Description

        Get the elliptic curve that is in use.

      Method get_private_key

        `Gmp.mpz get_private_key()`

      Description

        Get the private key.

      Method get_x

        `Gmp.mpz get_x()`

      Description

        Get the x coordinate of the public key.

      See also

        get_y()

      Method get_y

        `Gmp.mpz get_y()`

      Description

        Get the y coordinate of the public key.

      See also

        get_x()

      Inherit Sign

        inherit __builtin.Nettle.Sign : Sign

      Method name

        `string(7bit) name()`

      Description

        Returns the string `"ECDSA"` followed by the parenthesized name of the curve.

      Method raw_sign

        `array(Gmp.mpz) raw_sign(string(8bit) digest)`

      Description

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

      Method raw_verify

        `bool raw_verify(string(8bit) digest, Gmp.mpz r, Gmp.mpz s)`

      Description

        Verify the signature r, s against the message digest digest.

      Method set_private_key

        `void set_private_key(Gmp.mpz|int k)`

      Description

        Set the private key (and corresponding private key).

      Note

        Throws errors if the key isn't valid for the curve.

      Method set_public_key

        `void set_public_key(Gmp.mpz|int x, Gmp.mpz|int y)`

      Description

        Change to the selected point on the curve as public key.

      Note

        Throws errors if the point isn't on the curve.

      Method set_random

        `void set_random(function(int(0..):string(8bit)) r)`

      Description

        Set the random function, used to generate keys and parameters, to the function r.

    CLASS Nettle.ECC_Curve.Point

      Description

        A point on an elliptic curve.

      Method `*

        `Point res = Nettle.ECC_Curve.Point() * scalar`

      Description

        Multiply the point on the curve by a scalar.

        A typical use is for Elliptic Curve Diffie Hellman (ECDH) key exchange.

      Returns

        Returns the new point on the curve.

      Method get_curve

        `ECC_Curve get_curve()`

      Description

        Get the elliptic curve that is in use.

      Method get_x

        `Gmp.mpz get_x()`

      Description

        Get the x coordinate of the point.

      See also

        get_y()

      Method get_y

        `Gmp.mpz get_y()`

      Description

        Get the y coordinate of the point.

      See also

        get_x()

      Inherit Point

        inherit ECC_Curve::Point : Point

      Method name

        `string(7bit) name()`

      Description

        Returns the string `"Point"` followed by the parenthesized name of the curve.

      Method set

        `void set(Gmp.mpz|int x, Gmp.mpz|int y)`

      Description

        Change to the selected point on the curve.

      Note

        Throws errors if the point isn't on the curve.

  CLASS Nettle.Fortuna

    Description

      Implements the Fortuna PRNG generator, designed by Niels Ferguson and Bruce Schneier and described in Practical Cryptography. Web published exerpt at https://www.schneier.com:443/fortuna.pdf

      This implementation uses AES256 to generate output and SHA256 to generate keys.

      To use this class an entropy accumulator needs to be implemented and supply the reseed() method with new entopy.

    Method random_string

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

    Description

      Generates len amount of pseudo random data. In contrast with the Fortuna PseudoRandomData function, which only allows 2^20 bytes of random data per call, the necessary rekey operations are here performed internally, so no such restrictions apply.

    Method reseed

      `void reseed(string(8bit) data)`

    Description

      Generates new a new key based on the provided additional entropy.

  CLASS Nettle.GOST94

    Description

      Implementation of the GOST94 hash algorithm.

    Inherit Hash

      inherit Hash : Hash

    CLASS Nettle.GOST94.State

      Description

        State for GOST94 hashing.

      Inherit State

        inherit Hash::State : State

  CLASS Nettle.Hash

    Description

      Represents information about a hash algorithm, such as name, digest size, and internal block size.

    Method block_size

      `int(0..) block_size()`

    Description

      Returns the internal block size of the hash algorithm.

    Method crypt_hash

      `string(7bit) crypt_hash(string(8bit) password, string(8bit) salt, int rounds)`

    Description

      Password hashing function in crypt_md5()-style.

      Implements the algorithm described in http://www.akkadia.org/drepper/SHA-crypt.txt.

      This is the algorithm used by `crypt(2)` in methods `$5$` (SHA256) and `$6$` (SHA512).

      The password memory will be cleared before released.

    See also

      crypt_md5()

    Method digest_size

      `int(0..) digest_size()`

    Description

      Returns the size of a hash digest.

    Method hash

      `string(8bit) hash(string(8bit) data)`

    Description

      Works as a (faster) shortcut for `State()->update(data)->digest()`, where State is the hash state class corresponding to this Hash.

    See also

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

    Method hash

      `string(8bit) hash(Stdio.File file, void|int bytes)`

    Description

      Works as a (faster) shortcut for `State()->update(Stdio.read_file(file))->digest()`, where State is the hash state class corresponding to this Hash.

    Parameter `bytes`

      The number of bytes of the file object file that should be hashed. Negative numbers are ignored and the whole file is hashed.

    See also

      Stdio.File, State()->update() and State()->digest().

    Inherit Hash

      inherit __builtin.Nettle.Hash : Hash

    Method name

      `string(8bit) name()`

    Description

      Returns a human readable name for the algorithm.

    CLASS Nettle.Hash.State

      Description

        Base class for hashing contexts.

      Method digest

        `string(8bit) digest(int|void length)`

      Description

        Generates a digest, and resets the hashing contents.

      Parameter `length`

        If the length argument is provided, the digest is truncated to the given length.

      Returns

        The digest.

      Inherit State

        inherit Hash::State : State

      Method update

        `State update(string(8bit) data)`

      Description

        Hashes more data.

      Returns

        Returns `this` in order to simplify chaining of function calls.

  CLASS Nettle.IDEA

    Description

      Implementation of the IDEA cipher.

    Inherit BlockCipher

      inherit BlockCipher : BlockCipher

    CLASS Nettle.IDEA.State

      Description

        State for IDEA encyption.

      Inherit State

        inherit Cipher::State : State

  CLASS Nettle.MAC

    Description

      Represents information about a MAC algorithm, such as name, key size, digest size, and internal block size.

    Method block_size

      `int(0..) block_size()`

    Description

      Returns the internal block size of the MAC algorithm.

    Method digest_size

      `int(0..) digest_size()`

    Description

      Returns the size of a MAC digest.

    Inherit MAC

      inherit __builtin.Nettle.MAC : MAC

    Method iv_size

      `int(0..) iv_size()`

    Description

      Returns the size of the iv/nonce of the MAC algorithm (if any).

      Returns `0` (zero) if there is no configurable iv/nonce.

    Method key_size

      `int(0..) key_size()`

    Description

      Returns the recommended size for the secret key for the MAC algorithm.

    Method name

      `string(8bit) name()`

    Description

      Returns a human readable name for the algorithm.

    CLASS Nettle.MAC.State

      Description

        Base class for MAC contexts.

      Method `()

        `string(8bit) res = Nettle.MAC.State()()`

      Description

        Acts as the combination of update() followed by digest().

      Note

        Also updates the iv/nonce (if any).

      Method create

        `Nettle.MAC.State Nettle.MAC.State(string(8bit) key)`

      Description

        Initialize the MAC with a password.

        It also resets any iv/nonce to it's default.

      Method digest

        `string(8bit) digest(int|void length)`

      Description

        Generates a digest, and resets the MAC contents.

        Also updates the iv/nonce (if any).

      Parameter `length`

        If the length argument is provided, the digest is truncated to the given length.

      Returns

        The digest.

      Inherit State

        inherit MAC::State : State

      Method set_iv

        `State set_iv(string(8bit) iv)`

      Description

        Set the iv/nonce (if supported) for the MAC.

      Returns

        Returns `this` in order to simplify chaining of function calls.

      Method update

        `State update(string(8bit) data)`

      Description

        Hashes more data.

      Returns

        Returns `this` in order to simplify chaining of function calls.

  CLASS Nettle.MD2

    Description

      Implementation of the MD2 hash algorithm.

    Inherit Hash

      inherit Hash : Hash

    CLASS Nettle.MD2.State

      Description

        State for MD2 hashing.

      Inherit State

        inherit Hash::State : State

  CLASS Nettle.MD4

    Description

      Implementation of the MD4 hash algorithm.

    Inherit Hash

      inherit Hash : Hash

    CLASS Nettle.MD4.State

      Description

        State for MD4 hashing.

      Inherit State

        inherit Hash::State : State

  CLASS Nettle.MD5

    Description

      Implementation of the MD5 hash algorithm.

    Inherit Hash

      inherit Hash : Hash

    CLASS Nettle.MD5.State

      Description

        State for MD5 hashing.

      Inherit State

        inherit Hash::State : State

  CLASS Nettle.POLY1305_AES

    Description

      Implementation of the POLY1305_AES MAC algorithm.

    Inherit MAC

      inherit MAC : MAC

    CLASS Nettle.POLY1305_AES.State

      Description

        State for POLY1305_AES macing.

      Inherit State

        inherit MAC::State : State

  CLASS Nettle.RIPEMD160

    Description

      Implementation of the RIPEMD160 hash algorithm.

    Inherit Hash

      inherit Hash : Hash

    CLASS Nettle.RIPEMD160.State

      Description

        State for RIPEMD160 hashing.

      Inherit State

        inherit Hash::State : State

  CLASS Nettle.SALSA20

    Description

      Implementation of the SALSA20 cipher.

    Inherit BlockCipher

      inherit BlockCipher : BlockCipher

    CLASS Nettle.SALSA20.State

      Description

        State for SALSA20 encyption.

      Inherit State

        inherit Cipher::State : State

      Method set_iv

        `object set_iv(string(8bit) iv)`

      Description

        Set the initialization vector (aka nonce) and reset the block counter to zero.

      Parameter `iv`

        An 8-byte long string which is only to be used once for every key.

      Note

        This function MUST be called in addition to set_encrypt_key() or set_decrypt_key().

      Note

        The same iv should NEVER be reused with the same key!

  CLASS Nettle.SALSA20R12

    Description

      Implementation of the SALSA20 cipher reduced to 12 rounds.

    Inherit SALSA20

      inherit SALSA20 : SALSA20

  CLASS Nettle.SERPENT

    Description

      Implementation of the SERPENT cipher.

    Inherit BlockCipher16

      inherit BlockCipher16 : BlockCipher16

    CLASS Nettle.SERPENT.State

      Description

        State for SERPENT encyption.

      Inherit State

        inherit Cipher::State : State

  CLASS Nettle.SHA1

    Description

      Implementation of the SHA1 hash algorithm.

    Inherit Hash

      inherit Hash : Hash

    CLASS Nettle.SHA1.State

      Description

        State for SHA1 hashing.

      Inherit State

        inherit Hash::State : State

  CLASS Nettle.SHA224

    Description

      Implementation of the SHA224 hash algorithm.

    Inherit Hash

      inherit Hash : Hash

    CLASS Nettle.SHA224.State

      Description

        State for SHA224 hashing.

      Inherit State

        inherit Hash::State : State

  CLASS Nettle.SHA256

    Description

      Implementation of the SHA256 hash algorithm.

    Inherit Hash

      inherit Hash : Hash

    CLASS Nettle.SHA256.State

      Description

        State for SHA256 hashing.

      Inherit State

        inherit Hash::State : State

  CLASS Nettle.SHA384

    Description

      Implementation of the SHA384 hash algorithm.

    Inherit Hash

      inherit Hash : Hash

    CLASS Nettle.SHA384.State

      Description

        State for SHA384 hashing.

      Inherit State

        inherit Hash::State : State

  CLASS Nettle.SHA3_224

    Description

      Implementation of the SHA3_224 hash algorithm.

    Inherit Hash

      inherit Hash : Hash

    CLASS Nettle.SHA3_224.State

      Description

        State for SHA3_224 hashing.

      Inherit State

        inherit Hash::State : State

  CLASS Nettle.SHA3_256

    Description

      Implementation of the SHA3_256 hash algorithm.

    Inherit Hash

      inherit Hash : Hash

    CLASS Nettle.SHA3_256.State

      Description

        State for SHA3_256 hashing.

      Inherit State

        inherit Hash::State : State

  CLASS Nettle.SHA3_384

    Description

      Implementation of the SHA3_384 hash algorithm.

    Inherit Hash

      inherit Hash : Hash

    CLASS Nettle.SHA3_384.State

      Description

        State for SHA3_384 hashing.

      Inherit State

        inherit Hash::State : State

  CLASS Nettle.SHA3_512

    Description

      Implementation of the SHA3_512 hash algorithm.

    Inherit Hash

      inherit Hash : Hash

    CLASS Nettle.SHA3_512.State

      Description

        State for SHA3_512 hashing.

      Inherit State

        inherit Hash::State : State

  CLASS Nettle.SHA512

    Description

      Implementation of the SHA512 hash algorithm.

    Inherit Hash

      inherit Hash : Hash

    CLASS Nettle.SHA512.State

      Description

        State for SHA512 hashing.

      Inherit State

        inherit Hash::State : State

  CLASS Nettle.Twofish

    Description

      Implementation of the Twofish cipher.

    Inherit BlockCipher16

      inherit BlockCipher16 : BlockCipher16

    CLASS Nettle.Twofish.State

      Description

        State for Twofish encyption.

      Inherit State

        inherit Cipher::State : State

  CLASS Nettle.UMAC128_AES

    Description

      Implementation of the UMAC128_AES MAC algorithm.

    Inherit MAC

      inherit MAC : MAC

    CLASS Nettle.UMAC128_AES.State

      Description

        State for UMAC128_AES macing.

      Inherit State

        inherit MAC::State : State

  CLASS Nettle.UMAC32_AES

    Description

      Implementation of the UMAC32_AES MAC algorithm.

    Inherit MAC

      inherit MAC : MAC

    CLASS Nettle.UMAC32_AES.State

      Description

        State for UMAC32_AES macing.

      Inherit State

        inherit MAC::State : State

  CLASS Nettle.UMAC64_AES

    Description

      Implementation of the UMAC64_AES MAC algorithm.

    Inherit MAC

      inherit MAC : MAC

    CLASS Nettle.UMAC64_AES.State

      Description

        State for UMAC64_AES macing.

      Inherit State

        inherit MAC::State : State

  CLASS Nettle.UMAC96_AES

    Description

      Implementation of the UMAC96_AES MAC algorithm.

    Inherit MAC

      inherit MAC : MAC

    CLASS Nettle.UMAC96_AES.State

      Description

        State for UMAC96_AES macing.

      Inherit State

        inherit MAC::State : State

  CLASS Nettle.Yarrow

    Description

      Yarrow is a family of pseudo-randomness generators, designed for cryptographic use, by John Kelsey, Bruce Schneier and Niels Ferguson. Yarrow-160 is described in a paper at http://www.schneier.com/paper-yarrow.html, and it uses SHA1 and triple-DES, and has a 160-bit internal state. Nettle implements Yarrow-256, which is similar, but uses SHA256 and AES to get an internal state of 256 bits.

    Method create

      `Nettle.Yarrow Nettle.Yarrow(void|int sources)`

    Description

      The number of entropy sources that will feed entropy to the random number generator is given as an argument to Yarrow during instantiation.

    See also

      update

    Method force_reseed

      `void force_reseed()`

    Description

      By calling this function entropy is moved from the slow pool to the fast pool. Read more about Yarrow before using this.

    Method get_seed

      `string(8bit) get_seed()`

    Description

      Returns part of the internal state so that it can be saved for later seeding. This method is deprecated. Instead read the min_seed_size number of bytes from the random_string method.

    See also

      seed(), random_string()

    Method is_seeded

      `bool is_seeded()`

    Description

      Returns 1 if the random generator is seeded and ready to generator output. 0 otherwise.

    See also

      seed

    Method min_seed_size

      `int(0..) min_seed_size()`

    Description

      Returns the minimal number of characters that the seed needs to properly seed the random number generator.

    See also

      seed

    Method needed_sources

      `int(0..) needed_sources()`

    Description

      The number of sources that must reach the threshold before a slow reseed will happen.

    Method random_string

      `string(8bit) random_string(int length)`

    Description

      Returns a pseudo-random string of the requested length.

    Method seed

      `Yarrow seed(string(8bit) data)`

    Description

      The random generator needs to be seeded before it can be used. The seed must be at least 32 characters long. The seed could be stored from a previous run by inserting the value returned from previous random_string call.

    Returns

      Returns the called object.

    See also

      min_seed_size, is_seeded

    Method update

      `bool update(string(8bit) data, int source, int entropy)`

    Description

      Inject additional entropy into the random number generator.

    See also

      create

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::destroy.

  Note

    Object.DESTRUCT_EXPLICIT is `0` and Object.DESTRUCT_CLEANUP is `1` for compatibility.

  Method secure

    `object secure(object str)`

  Description

    Marks the object as secure, which will clear the memory area before freeing the object.

  See also

    String.secure()

Module Odbc

  Description

    Low-level interface to Open DataBase Connectivity SQL-drivers.

  Note

    You typically don't want to access this module directly, but instead use Sql.Sql() with an `"odbc://"` or `"dsn://"` URL.

  See also

    Sql.Sql()

  Method connect_lock

    `bool connect_lock(void|int enable)`

  Description

    Enable or disable a mutex that serializes all ODBC SQLConnect calls (i.e. when ODBC connections are created). This lock might be necessary to work around bugs in ODBC drivers.

  Parameter `enable`

    Enables the mutex if nonzero, disables it otherwise. The state is not changed if this argument is left out.

  Returns

    The old state of the flag.

  Note

    This is currently enabled by default due to bugs in the current FreeTDS library (version 0.63), but that might change if the demand for this kludge ceases in the future. Therefore, if this setting is important to you then always set it explicitly. Hopefully most users don't need to bother with it.

  Method list_dbs

    `array(string) list_dbs()`

  Description

    List the configured ODBC database sources.

  CLASS Odbc.odbc

    Description

      Low-level connection to an ODBC or DSN database.

    Note

      You typically don't want to access this module directly, but instead use the Sql.odbc or Sql.dsn created by Sql.Sql().

    See also

      Sql.odbc, Sql.dsn

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

      `int add_bookmark(string text, int parent, int open)`

    Method add_launchlink

      `object add_launchlink(float llx, float lly, float urx, float ury, string filename)`

    Method add_locallink

      `object add_locallink(float llx, float lly, float urx, float ury, int page, string dest)`

    Method add_pdflink

      `object add_pdflink(float llx, float lly, float urx, float ury, string filename, int page, string dest)`

    Method add_weblink

      `object add_weblink(float llx, float lly, float urx, float ury, string url)`

    Method arc

      `object arc(float x, float y, float r, float start, float end)`

    Method attach_file

      `object attach_file(float llx, float lly, float urx, float ury, string filename, string description, string author, string mimetype, string icon)`

    Method begin_page

      `PDF begin_page()`
      `PDF begin_page(float width, float height)`

    Description

      note: Defaults to a4, portrait

    Method circle

      `object circle(float x, float y, float r)`

    Method close

      `PDF close()`

    Method close_image

      `object close_image(int image)`

    Method concat

      `object concat(float a, float b, float c, float d, float e, float f)`

    Method continue_text

      `PDF continue_text(string s)`

    Method create

      `PDF.PDFgen PDF.PDFgen()`

    Method curveto

      `object curveto(float x1, float y1, float x2, float y2, float x3, float y3)`

    Method end_page

      `PDF end_page()`

    Method findfont

      `int findfont(string fontname)`
      `int findfont(string fontname, void|string encoding, void|int embed)`

    Method get_parameter

      `string get_parameter(string key)`
      `string get_parameter(string key, float modifier)`

    Method get_value

      `float get_value(string key)`
      `float get_value(string key, float modifier)`

    Method lineto

      `object lineto(float x, float y)`

    Method moveto

      `object moveto(float x, float y)`

    Method open_CCITT

      `int open_CCITT(string filename, int width, int height, int BitReverse, int K, int BlackIs1)`

    Method open_file

      `int open_file(string filename)`

    Method open_image

      `int open_image(string type, string source, string data, int width, int height, int components, int bpc, string params)`

    Method open_image_file

      `int open_image_file(string type, string filename)`
      `int open_image_file(string type, string filename, void|string stringparam, void|int intparam)`

    Method place_image

      `object place_image(int image, float x, float y, float scale)`

    Method rect

      `object rect(float x, float y, float width, float height)`

    Method rotate

      `object rotate(float phi)`

    Method scale

      `object scale(float sx, float sy)`

    Method set_border_color

      `object set_border_color(float red, float green, float blue)`

    Method set_border_dash

      `object set_border_dash(float b, float w)`

    Method set_border_style

      `object set_border_style(string style, float width)`

    Method set_info

      `float set_info(string key, string info)`

    Method set_parameter

      `float set_parameter(string key, string parameter)`

    Method set_text_pos

      `object set_text_pos(float x, float y)`

    Method set_value

      `float set_value(string key, float value)`

    Method setdash

      `object setdash(float b, float w)`

    Method setflat

      `object setflat(float flatness)`

    Method setfont

      `PDF setfont(int n, float size)`

    Method setgray

      `object setgray(float gray)`

    Method setgray_fill

      `object setgray_fill(float gray)`

    Method setgray_stroke

      `object setgray_stroke(float gray)`

    Method setlinecap

      `object setlinecap(int linecap)`

    Method setlinejoin

      `object setlinejoin(int linejoin)`

    Method setlinewidth

      `object setlinewidth(float width)`

    Method setmiterlimit

      `object setmiterlimit(float miter)`

    Method setrgbcolor

      `object setrgbcolor(float red, float green, float blue)`

    Method setrgbcolor_fill

      `object setrgbcolor_fill(float red, float green, float blue)`

    Method setrgbcolor_stroke

      `object setrgbcolor_stroke(float red, float green, float blue)`

    Method show

      `PDF show(string s)`

    Method show_boxed

      `int show_boxed(string text, float x, float y, float width, float height, string mode)`
      `int show_boxed(string text, float x, float y, float width, float height, string mode, string feature)`

    Method showxy

      `PDF showxy(string s, float x, float y)`

    Method skew

      `object skew(float alpha, float beta)`

    Method stringwidth

      `float stringwidth(string text, int font, float size)`

    Method translate

      `object translate(float tx, float ty)`

Module Pango

Module Pike

  Constant Backend

    `constant Pike.Backend`

  Description

    The class of the DefaultBackend.

    Typically something that has inherited __Backend.

  See also

    __Backend, DefaultBackend

  Constant INDEX_FROM_BEG
  Constant INDEX_FROM_END
  Constant OPEN_BOUND

    `constant Pike.INDEX_FROM_BEG`
    `constant Pike.INDEX_FROM_END`
    `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.

  Variable SmallBackend

    `program Pike.SmallBackend`

  Description

    This is the most suitable backend implementation if you only want to monitor a small number of Stdio.File objects.

  Constant WEAK_INDICES
  Constant WEAK_VALUES
  Constant WEAK

    `constant Pike.WEAK_INDICES`
    `constant Pike.WEAK_VALUES`
    `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__

    `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

    `int count_memory(int|mapping(string:int) options, array|multiset|mapping|object|program|string|type|int ... 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 get_first_arg_type(type fun_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 get_return_type(type fun_type)`

  Description

    Check what a function of the type fun_type will return if called with no arguments.

  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`.
    `"float_size" : int` | The number of bits in the native floating point type. Usually `32` or `64`.
    `"auto_bignum" : bool` | Present if integers larger than the native size are automatically converted into bignums.

  Method get_type_attributes

    `array(string) get_type_attributes(type t)`

  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(mixed x)`

  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

    `int implicit_gc_real_time(void|int nsec)`

  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 low_check_call(type fun_type, type arg_type)`
    `type low_check_call(type fun_type, type arg_type, int flags)`

  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.

  Returns

    Returns a continuation type on success.

    Returns `0` (zero) on failure.

  Method soft_cast

    `type soft_cast(type to, type from)`

  Description

    Return the resulting type from a soft cast of from to to.

  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.BacktraceFrame arg )`

    Method _sprintf

      `string sprintf(string format, ... Pike.BacktraceFrame arg ... )`

    Method `[]

      `mixed res = Pike.BacktraceFrame()[ index ]`

    Description

      The BacktraceFrame object can be indexed as an array.

    Method `[]=

      `Pike.BacktraceFrame()[ index ] = value`

  CLASS Pike.MasterCodec

    Description

      This is a bare-bones codec that is used when loading a dumped master.

    See also

      Codec

    Method decode_object

      `object decode_object(object obj, mixed data)`

    Description

      Calls `obj->_decode(<font face='courier'>data`).

    Method functionof

      `mixed functionof(mixed symbol)`

    Description

      Look up a function in all_constants().

    Method objectof

      `mixed objectof(mixed symbol)`

    Description

      Look up an object in all_constants().

    Method programof

      `mixed programof(mixed symbol)`

    Description

      Look up a program in all_constants().

  CLASS Pike.PollBackend

    Description

      Backend implemented with `poll(2)` (SVr4, POSIX).

    See also

      Backend

    Method `()

      `float|int(0..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()

    Inherit __Backend

      inherit __Backend : __Backend

  CLASS Pike.PollDeviceBackend

    Description

      Backend implemented with `/dev/poll` (Solaris, OSF/1 and IRIX), `epoll(2)` (Linux) or `kqueue(2)` (MacOS X, FreeBSD, OpenBSD, etc).

    See also

      Backend

    Method `()

      `float|int(0..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

      `int enable_core_foundation(bool enable)`

    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

      `int enable_external_runloop(bool enable)`

    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.

    Inherit __Backend

      inherit __Backend : __Backend

    Method query_core_foundation_enabled

      `int query_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

      `void set_signal_event_callback(int signum, function(:void) cb)`

    Note

      This function is a noop except for the `kqueue` case.

  CLASS Pike.SelectBackend

    Description

      Backend based on the classic `select(2)` system call from BSD.

    Method `()

      `float|int(0..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()

    Inherit __Backend

      inherit __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

      `void add_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

      `void add_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

      `void alarm_alarm_alarm()`

    Description

      Explicitly trigger the watchdog, if enough CPU time has been used. This is not normally called manually.

    Method create

      `Pike.Watchdog Pike.Watchdog(int t)`

    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

      `void ping()`

    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

      `void print_debug()`

    Description

      Output thread stacktraces, memory and profiling (if available) debug information to stderr.

    Method really_trigger_watchdog_promise

      `void really_trigger_watchdog_promise()`

    Description

      Really trigger the watchdog, killing the current process. This is not normally called manually.

    Method set_delay

      `void set_delay(int t)`

    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.

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

      `float|int(0..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

      `void add_file(Stdio.File|Stdio.FILE f)`

    Description

      Register a file to be handled by this backend.

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

    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 call_out

      `array call_out(function(:void) f, float|int delay, 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
      `int time_left` | Time remaining in seconds until the call_out is to be performed.
      `int(0..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.__Backend Pike.__Backend()`

    Method executing_thread

      `Thread.Thread executing_thread()`
      `int executing_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

      `int find_call_out(function(:void) f)`
      `int find_call_out(array id)`

    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

      `int id()`

    Description

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

    Method remove_call_out

      `int remove_call_out(function(:void) f)`
      `int remove_call_out(array id)`

    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

        `protected array Pike.__Backend.CallOut.args`

      Description

        The array containing the function and arguments.

      Method create

        `Pike.__Backend.CallOut Pike.__Backend.CallOut(int|float seconds, mixed fun, 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.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.Security

  Description

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

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

    A credential object in essence holds three values:

      `user` -- The owner.

      `allow_bits` -- Run-time access permissions.

      `data_bits` -- Data access permissions.

  Constant BIT_CALL

    `constant Pike.Security.BIT_CALL`

  Description

    Allow calling of functions.

  Constant BIT_CONDITIONAL_IO

    `constant Pike.Security.BIT_CONDITIONAL_IO`

  Description

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

  Constant BIT_DESTRUCT

    `constant Pike.Security.BIT_DESTRUCT`

  Description

    Allow use of destruct.

  Constant BIT_INDEX

    `constant Pike.Security.BIT_INDEX`

  Description

    Allow indexing.

  Constant BIT_NOT_SETUID

    `constant Pike.Security.BIT_NOT_SETUID`

  Description

    Don't change active credentials on function call.

  Constant BIT_SECURITY

    `constant Pike.Security.BIT_SECURITY`

  Description

    Allow usage of security related functions.

  Constant BIT_SET_INDEX

    `constant Pike.Security.BIT_SET_INDEX`

  Description

    Allow setting of indices.

  Method call_with_creds

    `mixed call_with_creds(Creds creds, mixed func, mixed ... args)`

  Description

    Call with credentials.

    Sets the current credentials to creds, and calls `<font face='courier'>func`(@<font face='courier'>args). If creds is `0` (zero), the credentials from the current object will be used.

  Note

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

  Method get_current_creds

    `Creds get_current_creds()`

  Description

    Get the current credentials

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

  See also

    call_with_creds()

  Method get_object_creds

    `Creds get_object_creds(object|program|function(:void)|array|mapping|multiset o)`

  Description

    Get the credentials from o.

    Returns `0` if o does not have any credentials.

  CLASS Pike.Security.Creds

    Description

      The credentials object.

    Method apply

      `void apply(object|program|function(:void)|array|mapping|multiset o)`

    Description

      Set the credentials for o to this credentials object.

    Note

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

    Method create

      `Pike.Security.Creds Pike.Security.Creds(User user, int allow_bits, int data_bits)`

    Description

      Initialize a new credentials object.

    Parameter `allow_bits`

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

    Parameter `data_bits`

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

    Throws

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

    Method get_allow_bits

      `int get_allow_bits()`

    Description

      Get the allow_bit bitmask.

    Method get_data_bits

      `int get_data_bits()`

    Description

      Get the data_bits bitmask.

    Method get_default_creds

      `Creds get_default_creds()`

    Description

      Get the default credentials.

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

    See also

      set_default_creds()

    Method get_user

      `object get_user()`

    Description

      Get the user part.

    Method set_default_creds

      `void set_default_creds(Creds creds)`

    Description

      Set the default credentials

    Note

      The current creds must have the allow bit BIT_SECURITY set.

    See also

      get_default_creds()

  CLASS Pike.Security.User

    Description

      Virtual class for User objects, used in Creds objects.

    Method valid_io

      `int(2bit)|array valid_io(string fun, string type, mixed ... args)`

    Description

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

    Method valid_open

      `int(2bit)|string valid_open(string type, object current, string filename, string flags, int access)`

    Description

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

    Parameter `type`

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

    Parameter `current`

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

    Parameter `filename`

      The file name requested.

    Parameter `flags`

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

    Parameter `access`

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

    Returns

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

      `0` | The user was not allowed to open the file. ERRNO will be set to EPERM and an exception is thrown.
      `1` | Do nothing, i.e. valid_open has initilized the current object with an open file. This can (natuarally) only be returned if a current object was given, which is not always the case.
      `2` | The user was allowed to open the file and the open code proceeds.
      `3` | The user was not allowed to open the file and an exception is thrown.

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

      `int bytes_sent()`

    Description

      Return the number of bytes sent.

    Method finish

      `void finish()`

    Description

      Terminate and reinitialize the pipe.

    Method input

      `void input(object obj)`

    Description

      Add an input file to this pipe.

    Method output

      `void output(object obj, int|void start_pos)`

    Description

      Add an output file object.

    Method set_done_callback

      `void set_done_callback(void|function(mixed:mixed) done_cb, void|mixed id)`

    Description

      Set the callback function to be called when all the outputs have been sent.

    Method set_output_closed_callback

      `void set_output_closed_callback(void|function(mixed, object:mixed) close_cb, void|mixed id)`

    Description

      Set the callback function to be called when one of the outputs has been closed from the other side.

    Method start

      `void start()`

    Description

      Start sending the input(s) to the output(s).

    Method version

      `string version()`

    Description

      Return the version of the module.

    Method write

      `void write(string bytes)`

    Description

      Add an input string to this pipe.

Module Process

  Method daemon

    `void daemon(int nochdir, int noclose, 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

    `int exec(string file, string ... foo)`

  Method get_forkd_default

    `bool get_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

    `string popen(string command)`

  Description

    Executes command as a shell statement ("`/bin/sh -c <font face='courier'>command`" for Unix, "`cmd /c <font face='courier'>command`" for Windows), waits until it has finished and returns the result as a string.

  See also

    system, spawn

  Method popen

    `Stdio.FILE popen(string command, string mode)`

  Description

    Open a "process" for reading or writing. The command is executed as a shell statement ("`/bin/sh -c <font face='courier'>command`" for Unix, "`cmd /c <font face='courier'>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

  Method run

    `mapping run(string|array(string) cmd, void|mapping modifiers)`

  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. Since the point of this function is to handle those you can not supply your own.

    If `modifiers->stdin` is set to a string it will automaticly be converted to a pipe that is fed to stdin of the started process.

  See also

    Process.Process create_process

  Returns

    `"stdout" : string` | Everything the process wrote on stdout.
    `"stderr" : string` | Everything the process wrote on stderr.
    `"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 therefor adviceable to set up rlimits if the output has a potential to be very large.

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

  Method search_path

    `string search_path(string command)`

  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

    `void set_forkd_default(bool mode)`

  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

    `string sh_quote(string s)`

  Method spawn

    `Process spawn(string command, void|Stdio.Stream stdin, void|Stdio.Stream stdout, void|Stdio.Stream stderr, )`

  Description

    Spawns a process that executes command as a command shell statement ("`/bin/sh -c <font face='courier'>command`" for Unix, "`cmd /c <font face='courier'>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

  Method spawn_pike

    `Process spawn_pike(array(string) argv, void|mapping(string:mixed) options, array(string)|void launcher)`

  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(string s, bool|void nt_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

    `int system(string command, void|Stdio.Stream stdin, void|Stdio.Stream stdout, void|Stdio.Stream stderr)`

  Description

    Executes command as a shell statement ("`/bin/sh -c <font face='courier'>command`" for Unix, "`cmd /c <font face='courier'>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.

  See also

    spawn, popen

  CLASS Process.ForkdDecoder

    Description

      Decoder for data received by Tools.Standalone.forkd.

    See also

      ForkdEncoder

    Method create

      `Process.ForkdDecoder Process.ForkdDecoder(array(Stdio.Fd) fds)`

    Variable fds

      `array(Stdio.Fd) Process.ForkdDecoder.fds`

  CLASS Process.ForkdEncoder

    Description

      Encoder for data to be sent to Tools.Standalone.forkd.

    See also

      ForkdDecoder

    Method create

      `Process.ForkdEncoder Process.ForkdEncoder(Stdio.File remote_fd)`

    Variable remote_fd

      `Stdio.File Process.ForkdEncoder.remote_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

    Method create

      `Process.Process Process.Process(string|array(string) command_args, void|mapping(string:mixed) modifiers)`

    Parameter `command_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`

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

    Inherit create_process

      inherit create_process : create_process

    Description

      Based on create_process.

  CLASS Process.Spawn

    Method create

      `Process.Spawn Process.Spawn(string cmd, void|array(string) args, void|mapping(string:string) env, string|void cwd, void|array(Stdio.File|void) ownpipes, void|array(Stdio.File|void) fds_to_close)`

    Method kill

      `int kill(int signal)`

    Method wait

      `int wait()`

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

    Method cont

      `void cont(int|void signal)`

    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

      `void exit()`

    Description

      Cause the traced process to exit.

    Note

      This function may only be called for stopped processes.

    See also

      cont(), wait()

    Inherit create_process

      inherit create_process : create_process

    Method wait

      `int wait()`

    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

    Method create

      `Process.create_process Process.create_process(array(string) command_args, void|mapping modifiers)`

    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` | 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.
      `"chroot" : string` | 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.
      `"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..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

    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"`, `"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

      `bool kill(int signal)`

    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.

    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 pid

      `int pid()`

    Description

      Returns the process identifier of the process.

    Method set_priority

      `int set_priority(string priority)`

    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

    Note

      Prior to Pike 7.5 the value 1 was returned for exited processes.

    Method wait

      `int wait()`

    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 Regexp

  Method `()

    `SimpleRegexp `()(void|string regexp)`

  Description

    Convenience/compatibility method to get a SimpleRegexp object.

  Inherit "___Regexp"

    inherit "___Regexp" : "___Regexp"

  Method match

    `bool match(string regexp, string data)`

  Description

    Calls Regexp.PCRE.Plain.match in a temporary regexp object. Faster to type but slower to run...

  Method replace

    `string replace(string regexp, string data, 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

    `array split(string regexp, string data)`

  Description

    Calls Regexp.PCRE.Plain.split in a temporary regexp object. Faster to type but slower to run...

  Method split2

    `array split2(string regexp, string data)`

  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.

    Method _encode
    Method _decode

      `string(8bit) encode_value(Regexp.SimpleRegexp data)
      `Regexp.SimpleRegexp decode_value(string(8bit) data)``

    Description

      Regexp objects can be encoded and decoded.

    See also

      encode_value, decode_value

    Method create

      `Regexp.SimpleRegexp Regexp.SimpleRegexp(string re)`

    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.

    Inherit _SimpleRegexp

      inherit _SimpleRegexp : _SimpleRegexp

    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 match

      `int match(string str)`

    Description

      Returns 1 if str matches the regexp bound to the regexp object. Zero otherwise.

    Method replace

      `string replace(string in, string|function(string:string) transform)`

    Method split

      `array(string) split(string s)`

    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

    Method `()

      `StudiedWidestring `()(string pattern, void|int options, void|object table)`

    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.

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

    Inherit "____Regexp_PCRE"

      inherit "____Regexp_PCRE" : "____Regexp_PCRE"

    Method split_subject

      `array(string) split_subject(string subject, 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

        `bool match(string subject, void|int startoffset)`

      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_program matchall(string subject, 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

    `string replace(string subject, string|function(:void) with, mixed|void ... 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

  `string replace1(string subject, 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

  `string replace_positional(string subject, string subst)`

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..0) split(string subject, void|int startoffset)`

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..0) split2(string subject, void|int startoffset)`

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.

  Method exec

    `array(int)|int exec(string subject, void|int startoffset)`

  Description

    The exec function is wrapped to give the correct indexes for the widestring.

  Inherit Plain

    inherit Plain : Plain

CLASS Regexp.PCRE._pcre

  Method _sprintf

    `string sprintf(string format, ... Regexp.PCRE._pcre arg ... )`

  Method create

    `Regexp.PCRE._pcre Regexp.PCRE._pcre(string pattern, void|int options, void|object table)`

  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|array exec(string subject, void|int startoffset)`

  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 `<font face='courier'>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

    `int get_stringnumber(string stringname)`

  Description

    returns the number of a named subpattern

  Method info

    `mapping info()`

  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

    `object study()`

  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

      `void async(mixed ... args)`

    Description

      Call the wrapped remote function asynchronously.

    Parameter `args`

      Arguments to send to the remote function.

    See also

      sync(), `()()

    Method create

      `Remote.Call Remote.Call(string objectid, string name, object connection, object context, int async)`

    Method exists

      `int exists()`

    Description

      Check whether the wrapped function actually exists at the other end.

    Method is_async

      `int is_async()`

    Returns

      Whether asynchronous mode is active or not.

    See also

      set_async()

    Method set_async

      `void set_async(int a)`

    Description

      Change to/from asynchronous mode.

    See also

      is_async()

    Method sync

      `mixed sync(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.

    Method close

      `void close()`

    Description

      Close the connection.

    Method closed

      `int closed()`

    Description

      Check if the connection is closed.

    Variable con

      `Remote.Connection Remote.Client.con`

    Description

      Connection to the Remote.Server.

    Method create

      `Remote.Client Remote.Client(string host, int port, void|int nice, void|int timeout, void|int max_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

      `object get(string name)`

    Description

      Get a named object from the remote server.

    Method provide

      `void provide(string name, mixed thing)`

    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

      `void set_close_callback(function(:void) f)`

    Description

      Set the callback to call when the connection is closed.

  CLASS Remote.Connection

    Method add_close_callback

      `void add_close_callback(function(:void) f, mixed ... args)`

    Description

      Add a function that is called when the connection is closed.

    Method call_async

      `void call_async(array data)`

    Description

      Make a call but don't wait for the result

    Method call_sync

      `mixed call_sync(array data)`

    Description

      Make a call and wait for the result

    Method close

      `void close()`

    Description

      Closes the connection nicely, after waiting in outstanding calls in both directions.

    Method connect

      `int connect(string host, int port, void|int timeout)`

    Description

      This function is called by clients to connect to a server.

    Method create

      `Remote.Connection Remote.Connection(void|int nice, void|int max_call_threads)`

    Parameter `nice`

      If set, no errors will be thrown.

    Method error_message

      `string error_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

      `object get_named_object(string name)`

    Description

      Get a named object provided by the server.

    Method remove_close_callback

      `void remove_close_callback(array f)`

    Description

      Remove a function that is called when the connection is closed.

    Method start_server

      `void start_server(object c, object cx)`

    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

      `void add(object o, string id)`

    Method create

      `Remote.Context Remote.Context(string b, object|void cn)`

    Method decode

      `mixed decode(array a)`

    Method decode_call

      `function(:void)|object decode_call(array data)`

    Method decode_existp

      `int decode_existp(array data)`

    Method describe

      `string describe(array data)`

    Method encode

      `array encode(mixed val)`

    Method encode_call

      `array encode_call(object|string o, string|function(:void) f, array args, int type)`

    Method function_for

      `object function_for(string id)`

    Method id_for

      `string id_for(mixed thing)`

    Method object_for

      `object object_for(string id)`

    Method set_server_context

      `void set_server_context(object ctx, object cn)`

  CLASS Remote.Obj

    Description

      Wrapper for a remote object.

    Method `->

      `mixed res = Remote.Obj()->X`

    Method `[]

      `mixed res = Remote.Obj()[ f ]`

    Method create

      `Remote.Obj Remote.Obj(string id, object connection, object context)`

    Method exists

      `int exists()`

    Method get_function

      `mixed get_function(string f)`

  CLASS Remote.Server

    Description

      Remote RPC server.

    Method close

      `void close()`

    Description

      Shut down the Remote.Server for new connections.

    Method close_all

      `void close_all()`

    Description

      Shut down the Remote.Server and terminate all current clients.

    Method closed

      `int closed()`

    Description

      Check if the Remote.Server is closed.

    Variable connections

      `array(Connection) Remote.Server.connections`

    Description

      Open connections.

    Method create

      `Remote.Server Remote.Server(string host, int port, void|int max_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.

    Variable port

      `Stdio.Port Remote.Server.port`

    Description

      Port for the Remote.Server.

    Method provide

      `void provide(string name, mixed thing)`

    Description

      Provide a named thing to the Remote.Client(s).

    Parameter `name`

      Name to provide thing under.

    Parameter `thing`

      Thing to provide.

    Variable sctx

      `Minicontext Remote.Server.sctx`

    Description

      Server context.

    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

      `void cancel_scan()`

    Method create

      `SANE.Scanner SANE.Scanner(string name)`

    Method get_option

      `mixed get_option(string name)`

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

      `void nonblocking_row_scan(function(Image.Image, int, Scanner, int:void) callback)`

    Method row_scan

      `void row_scan(function(Image.Image, int, Scanner:void) callback)`

    Method set_option

      `void set_option(string name, mixed new_value)`
      `void set_option(string name)`

    Description

      If no value is specified, the option is set to it's default value

    Method simple_scan

      `Image.Image simple_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

    `int blit_surface(SDL.Surface src, SDL.Surface dst, SDL.Rect|void srcrect, SDL.Rect|void dstrect)`

  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|void cd_name(int drive)`

  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

    `int cd_num_drives()`

  Returns

    The number of CD-ROM drives on the system.

  See also

    SDL.cd_name()

  Method enable_unicode

    `int enable_unicode(int enable)`

  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

    `int flip(SDL.Surface|void screen)`

  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

    `void|string get_error()`

  Description

    Get the last internal SDL error.

  Returns

    The error string, or zero if there was no error.

  Method get_key_state

    `string get_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

  `int get_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

  `void|object get_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

  `void|object get_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

  `int gl_get_attribute(int attribute)`

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

  `void gl_set_attribute(int attribute, int value)`

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

  `void gl_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

  `int grab_input(int mode)`

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

  `int iconify_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

  `void init(int flags)`

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

  `void init_sub_system(int flags)`

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

  `int joystick_event_state(int state)`

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

  `string joystick_name(int device_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

  `int joystick_opened(int device_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

  `void joystick_update()`

Description

  Updates the state of all open joysticks attached to the system.

Method num_joysticks

  `int num_joysticks()`

Returns

  The number of joysticks available to the system.

See also

  SDL.Joystick

Method open_audio

  `void open_audio(int frequency, int format, int channels, int bufsize)`

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

  `void pump_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

  `void quit()`

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

  `void quit_sub_system(int flags)`

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

  `void set_caption(string title, string icon)`

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

  `int set_gamma(float red, float green, float blue)`

FIXME

  Document this function

Method set_video_mode

  `object set_video_mode(int width, int height, int bpp, int flags)`

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

  `int show_cursor(int show)`

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

  `int toggle_fullscreen(void|SDL.Surface screen)`

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

  `void update_rect(int x, int y, int w, int h, SDL.Surface|void screen)`

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

  `void|string video_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

  `int video_mode_ok(int width, int height, int bpp, int flags)`

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

  `void warp_mouse(int xpos, int ypos)`

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

  `int was_init(int flags)`

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

  Method create

    `SDL.CD SDL.CD(int drive)`

  FIXME

    Document this function

  Variable current_frame

    `int SDL.CD.current_frame`

  FIXME

    Document this variable

  Variable current_track

    `int SDL.CD.current_track`

  FIXME

    Document this variable

  Method eject

    `int eject()`

  FIXME

    Document this function

  Variable id

    `int SDL.CD.id`

  FIXME

    Document this variable

  Variable numtracks

    `int SDL.CD.numtracks`

  FIXME

    Document this variable

  Method pause

    `int pause()`

  FIXME

    Document this function

  Method play

    `int play(int start, int length)`

  FIXME

    Document this function

  Method play_tracks

    `int play_tracks(int start_track, int start_frame, int ntracks, int nframes)`

  FIXME

    Document this function

  Method resume

    `int resume()`

  FIXME

    Document this function

  Method status

    `int status()`

  FIXME

    Document this function

  Method stop

    `int stop()`

  FIXME

    Document this function

  Method track

    `CDTrack track(int track)`

  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

    `int get()`

  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

    `int poll()`

  Description

    Polls for currently pending events.

  Returns

    1 if there are currently pending events, otherwise 0.

  Method wait

    `int wait()`

  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.Joystick SDL.Joystick(int device_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

    `float get_axis(int axis)`

  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(int ball)`

  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

    `int get_button(int button)`

  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

    `int get_hat(int hat)`

  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

    `int index()`

  Returns

    The index of this joystick.

  Method name

    `string name()`

  Returns

    The implementation-dependent name of this joystick.

  See also

    SDL.joystick_name()

  Method num_axes

    `int num_axes()`

  Returns

    The number of axes available for this joystick.

  Method num_balls

    `int num_balls()`

  Returns

    The number of trackballs available for this joystick.

  Method num_buttons

    `int num_buttons()`

  Returns

    The number of buttons available for this joystick.

  Method num_hats

    `int num_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.Music SDL.Music(string fname)`

  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

    `object fade_in(int ms, int|void loops)`

  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

    `object fade_out(int ms)`

  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

    `int fading()`

  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

    `object halt()`

  Description

    Stops music playback immediately, including any fader effects.

  Returns

    The SDL.Music object.

  Method pause

    `object pause()`

  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

    `int paused()`

  Description

    Determines if the music is already paused.

  Returns

    `1` if the music is paused, otherwise `0`.

  Method play

    `object play(int|void loops)`

  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

    `int playing()`

  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

    `object resume()`

  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

    `object rewind()`

  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

    `float set_volume(float vol)`

  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

    `float volume()`

  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.Color get_rgb(int pixel)`

  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(int pixel)`

  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

    `int map_rgb(int r, int g, int b)`
    `int map_rgb(Image.Color.Color color)`

  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

    `int map_rgba(int r, int g, int b, int a)`
    `int map_rgba(Image.Color.Color color, int a)`

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

  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.Rect SDL.Rect()`
    `SDL.Rect SDL.Rect(int(-32768..32767) x, int(-32768..32767) y)`
    `SDL.Rect SDL.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.

  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.

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

  Method blit

    `object blit(SDL.Surface dst, SDL.Rect|void srcrect, SDL.Rect|void dstrect)`

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

  Variable clip_rect

    `SDL.Rect SDL.Surface.clip_rect`

  Description

    This is the clipping rectangle as set by set_clip_rect().

  Method convert_surface

    `object convert_surface(SDL.PixelFormat fmt, int flags)`

  FIXME

    Document this function

  Method display_format

    `SDL.Surface display_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.Surface display_format_alpha()`

  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.

    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

    `object fill(int color)`

  Description

    Fill the entire surface with a solid color.

  See also

    fill_rect()

  Method fill_rect

    `object fill_rect(int color, SDL.Rect dstrect)`

  Description

    Fill a rectangle with a solid color.

  See also

    fill()

  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.

  Method get_pixel

    `int get_pixel(int x, int y)`

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

  Variable w
  Variable h

    `int SDL.Surface.w`
    `int SDL.Surface.h`

  Description

    The width and height of the surface in pixels.

  Method init

    `SDL.Surface init(int flags, int width, int height, int depth, int Rmask, int Gmask, int Bmask, int Amask)`

  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

    `int lock()`

  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

    `object set_alpha(int flag, int alpha)`

  FIXME

    Document this function

  Method set_clip_rect

    `object set_clip_rect(SDL.Rect rect)`

  FIXME

    Document this function

  Method set_color_key

    `object set_color_key(int flag, int key)`

  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.Surface set_image(Image.Image image, int|void flags)`
    `SDL.Surface set_image(Image.Image image, Image.Image alpha, int|void flags)`

  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

    `int set_pixel(int x, int y, int pixel)`

  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

    `void unlock()`

  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

    `ResultSet do_query_and(array(string) words, array(int) field_coefficients, array(int) proximity_coefficients, int cutoff, 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
    `int 0` | body
    `int 1..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
    `int 0` | spread: 0 (Perfect hit)
    `int 1` | spread: 1-5
    `int 2` | spread: 6-10
    `int 3` | spread: 11-20
    `int 4` | spread: 21-40
    `int 5` | spread: 41-80
    `int 6` | spread: 81-160
    `int 7` | 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

    `ResultSet do_query_or(array(string) words, array(int) field_coefficients, array(int) proximity_coefficients, int cutoff, 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
    `int 0` | body
    `int 1..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
    `int 0` | spread: 0 (Perfect hit)
    `int 1` | spread: 1-5
    `int 2` | spread: 6-10
    `int 3` | spread: 11-20
    `int 4` | spread: 21-40
    `int 5` | spread: 41-80
    `int 6` | spread: 81-160
    `int 7` | 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

    `ResultSet do_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
    `int 0` | body
    `int 1..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`.

  CLASS Search.Blob

    Method add

      `void add(int docid, int field, int offset)`

    Method create

      `Search.Blob Search.Blob(void|string initial)`

    Method data

      `string data()`

    Method memsize

      `int memsize()`

    Method merge

      `void merge(string data)`

    Method remove

      `void remove(int doc_id)`

    Method remove_list

      `void remove_list(array(int) docs)`

  CLASS Search.Blobs

    Method add_words

      `void add_words(int docid, array(string) words, int field_id)`

    Description

      Add all the words in the 'words' array to the blobs

    Method memsize

      `int memsize()`

    Description

      Returns the in-memory size of the blobs

    Method read

      `array read()`

    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 octed order.

      As a side-effect, this function 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

      `void add(int, array, int, int)`

    Method memsize

      `int memsize()`

    Description

      Returns the in-memory size of the linkfarm

    Method read

      `array read()`

    Description

      returns ({ int word_id, Blob b }) or 0

  CLASS Search.MergeFile

    Method create

      `Search.MergeFile Search.MergeFile(Stdio.File _fd)`

    Method merge_mergefiles

      `void merge_mergefiles(Search.MergeFile a, Search.MergeFile b)`

    Method write_blobs

      `void write_blobs(_WhiteFish.Blobs blobs)`

  CLASS Search.RankingProfile

    Method copy

      `this_program copy()`

    Description

      Returns a copy of this object.

    Method create

      `Search.RankingProfile Search.RankingProfile(void|int cutoff, void|array(int) proximity_ranking, void|Search.Database.Base db, void|array(int)|mapping(string:int) field_ranking)`

    Description

      cutoff defaults to 8, proximity_ranking defaults to `({ 8, 7, 6, 5, 4, 3, 2, 1, })` and field_ranking defaults to `({ 17, 0, 147 }) + allocate(62)`. db is only needed if field_ranking is provided as a mapping.

    Variable cutoff

      `int Search.RankingProfile.cutoff`

    Variable field_ranking

      `array(int) Search.RankingProfile.field_ranking`

    Variable proximity_ranking

      `array(int) Search.RankingProfile.proximity_ranking`

  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

      `int sizeof( Search.ResultSet arg )
      `int size()``

    Description

      Return the size of this resultset, in entries.

    Method intersect
    Method `&

      `ResultSet intersect(ResultSet a)`
      `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`
      `ResultSet or(ResultSet a)`

    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 `-

      `ResultSet sub(ResultSet a)`
      `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

      `ResultSet add_ranking(ResultSet a)`

    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

      `ResultSet dup()`

    Description

      Return a new resultset with the same contents as this one.

    Method memsize

      `int memsize()`

    Description

      Return the size of this resultset, in bytes.

    Method overhead

      `int overhead()`

    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(int first, int nelems)`

    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

      `void sort()`

    Description

      Sort this ResultSet according to ranking.

    Method sort

      `void sort()`

    Description

      Sort this ResultSet according to ranking.

    Method sort_docid

      `void sort_docid()`

    Description

      Sort this ResultSet according to document id.

    Method test

      `ResultSet test(int nelems, int start, int incr)`

    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

        `int allocate_field_id(string field)`

      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.Base Search.Database.Base(string db_url)`

      Description

        Initialize the database object.

      Parameter `path`

        The URL that identifies the underlying database storage

      Method get_blob

        `string get_blob(string word, int num, 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

        `int get_database_size()`

      Description

        Returns the size, in bytes, of the search database.

      Method get_document_id

        `int get_document_id(string uri, void|string language, void|int do_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

        `int get_field_id(string field, void|int do_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

        `int get_lastmodified(Standards.URI|string|array(Standards.URI|string) uri, void|string language)`

      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|string uri, void|string language, 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|int count)`

      Description

        Returns a list of the count most common words in the database. count defaults to `10`.

      Method get_num_deleted_documents

        `int get_num_deleted_documents()`

      Description

        Returns the number of deleted documents in the database.

      Method get_num_words

        `int get_num_words()`

      Description

        Returns the number of distinct words in the database.

      Method get_uri_and_language

        `mapping get_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

        `int get_uri_id(string uri, void|int do_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

        `void insert_words(Standards.URI|string uri, void|string language, string field, 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

        `void list_url_by_prefix(string url_prefix, function(string:void) cb)`

      Description

        Calls cb for all uri:s that match uri_prefix.

      Method remove_document

        `void remove_document(string|Standards.URI uri, void|string language)`

      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

        `void remove_document_prefix(string|Standards.URI uri)`

      Description

        Removes all documents that matches the provided uri prefix.

      Parameter `uri`

        The URI prefix of the documents to delete.

      Method remove_field

        `void remove_field(string field)`

      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

        `void remove_metadata(Standards.URI|string uri, void|string language)`

      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

        `void remove_uri(string|Standards.URI uri)`

      Description

        Remove URI from the database.

      Parameter `uri`

        The URI of the resource being removed.

      Method remove_uri_prefix

        `void remove_uri_prefix(string|Standards.URI uri)`

      Description

        Remove URI prefix from the database.

      Parameter `uri`

        The URI prefix of the resource being removed.

      Method safe_remove_field

        `void safe_remove_field(string field)`

      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

        `void set_lastmodified(Standards.URI|string uri, void|string language, int when)`

      Description

        Set last modification time for uri, language to mtime (seconds since `1970-01-01T00:00:00 UTC`).

      Method set_metadata

        `void set_metadata(Standards.URI|string uri, void|string language, 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

        `void set_sync_callback(function(:void) f)`

      Description

        Sets a function to be called when sync has been completed.

      Method sync

        `void sync()`

      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

        `constant Search.Filter.Base.contenttypes`

      Description

        The MIME content types this class can filter.

      Method filter

        `.Output filter(Standards.URI uri, string|Stdio.File data, string content_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.

      Method fix_relative_links

        `void fix_relative_links(Standards.URI base_uri)`

      Description

        Modifies relative links in links to be relative to base_uri.

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

  Module Search.Grammar

    Method getDefaultFields

      `multiset(string) getDefaultFields()`

    Method optimize

      `ParseNode optimize(ParseNode node, string|void parentOp)`

    Method remove_stop_words

      `void remove_stop_words(ParseNode node, array(string) stop_words)`

    CLASS Search.Grammar.AbstractParser

      Method create

        `Search.Grammar.AbstractParser Search.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

      Method create

        `Search.Grammar.DefaultParser Search.Grammar.DefaultParser(mapping(string:mixed)|void opt)`

      Inherit AbstractParser

        protected inherit .AbstractParser : AbstractParser

      Inherit Lexer

        protected inherit .Lexer : Lexer

      Variable options

        `mapping(string:mixed) Search.Grammar.DefaultParser.options`

      Method parse

        `ParseNode parse(string q)`

    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(string query)`

      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.

  Module Search.Indexer

    Method extension_to_type

      `string extension_to_type(string extension)`

    Method filename_to_type

      `string filename_to_type(string filename)`

    Method filter_and_index

      `Search.Filter.Output filter_and_index(Search.Database.Base db, string|Standards.URI uri, void|string language, string|Stdio.File data, string content_type, void|mapping headers, void|string default_charset)`

    Method index_document

      `void index_document(Search.Database.Base db, string|Standards.URI uri, void|string language, mapping fields)`

    Method remove_document

      `void remove_document(Search.Database.Base db, string|Standards.URI uri, void|string language)`

  Module Search.Query

    Method execute

      `array(Search.ResultSet|array(string)) execute(Search.Database.Base db, Search.Grammar.AbstractParser parser, string query, Search.RankingProfile ranking, void|array(string) stop_words, void|search_order order)`

    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.ResultSet 0` | 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.)

  Module Search.Queue

    CLASS Search.Queue.Base

      Description

        Virtual base class for the Search crawler state.

      Method add_uri

        `void add_uri(Standards.URI uri, int recurse, string template, void|int force)`

      Description

        Add an URI to be crawled.

      Method clear

        `void clear()`

      Description

        Clear and empty the entire queue.

      Method clear_cache

        `void clear_cache()`

      Description

        Clear any RAM caches.

      Method clear_md5

        `void clear_md5(int ... stages)`

      Description

        Clear the content MD5 for all URIs at the specified stages.

      Method clear_stage

        `void clear_stage(int ... stages)`

      Description

        Reset all URIs at the specified stage to stage `0` (zero).

      Method get

        `int|Standards.URI get()`

      Method get_extra

        `mapping get_extra(Standards.URI uri)`

      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|int stage)`

      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.

      Inherit Queue

        inherit Web.Crawler.Queue : Queue

      Method num_with_stage

        `int num_with_stage(int ... stage)`

      Returns

        Returns the number of URIs at the specified stage(s).

      Method put

        `void put(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

        `void remove_stage(int stage)`

      Description

        Remove all URIs at the specified stage.

      Method remove_uri

        `void remove_uri(string|Standards.URI uri)`

      Description

        Remove an URI from the queue.

      Method remove_uri_prefix

        `void remove_uri_prefix(string|Standards.URI uri)`

      Description

        Remove all URIs with the specified prefix from the queue.

      Method set_md5

        `void set_md5(Standards.URI uri, string md5)`

      Description

        Set the content MD5 for an URI.

      Method set_recurse

        `void set_recurse(Standards.URI uri, int recurse)`

      Description

        Set the recurse mode for an URI.

      Method set_stage

        `void set_stage(Standards.URI uri, int stage)`

      Description

        Set the stage for a single URI.

      ENUM Search.Queue.Base.Stage

        Description

          The queue stage levels.

    CLASS Search.Queue.MySQL

      Description

        Search crawler state stored in a Mysql database.

      Method create

        `Search.Queue.MySQL Search.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

        `int get_stage(Standards.URI uri)`

      Returns

        Returns the current stage for the specified URI.

      See also

        set_stage()

      Inherit Base

        inherit .Base : Base

      Method reset_stage

        `void reset_stage(string|void uri_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

      `void flush_profile(int p)`

    Description

      Flushes the profile p from all ProfileCache objects obtained with get_profile_cache.

    Method get_profile_cache

      `ProfileCache get_profile_cache(string db_name)`

    Description

      Returns a ProfileCache for the profiles stored in the database db_name.

    Method get_profile_storage

      `mapping get_profile_storage(string db_name)`

    Description

      Returns a profile storage mapping, which will be shared between all callers with the same db_name given.

    Method get_scheduler

      `Scheduler get_scheduler(string db_name)`

    Description

      Returns a scheduler for the given profile database.

    Method normalize

      `string normalize(string in)`

    Description

      Normalize the input string. Performs unicode NFKD normalization and then lowercases the whole string

    Method tokenize

      `array(string) tokenize(string in)`

    Description

      Tokenize the input string (Note: You should first call normalize on it)

    Method tokenize_and_normalize

      `array(string) tokenize_and_normalize(string what)`

    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

        `int add_program_name(int code, string name)`

      Method create

        `Search.Utils.Logger Search.Utils.Logger(Sql.Sql db_object, int profile, int stderr_logging)`
        `Search.Utils.Logger Search.Utils.Logger(string db_url, int profile, int stderr_logging)`

      Method get_log

        `array(array(string|int)) get_log(int profile, array(string) types, int from, int to)`

      Method log_error

        `void log_error(int code, void|string extra, void|int log_profile)`

      Method log_event

        `void log_event(int code, string type, void|string extra, void|int log_profile)`

      Method log_notice

        `void log_notice(int code, void|string extra, void|int log_profile)`

      Method log_warning

        `void log_warning(int code, void|string extra, void|int log_profile)`

    CLASS Search.Utils.ProfileCache

      Method create

        `Search.Utils.ProfileCache Search.Utils.ProfileCache(string db_name)`

      Variable db_name

        `string Search.Utils.ProfileCache.db_name`

      Method flush_cache

        `void flush_cache()`

      Description

        Empty the whole cache.

      Method flush_profile

        `void flush_profile(int p)`

      Description

        Flushes profile entry p from the profile cache.

      Method get_db_profile_number

        `int get_db_profile_number(string name)`

      Description

        Returns the profile number for the given database profile.

      Method get_profile_entry

        `ProfileEntry get_profile_entry(string db_name, void|string query_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

        `int get_query_profile_number(string name)`

      Description

        Returns the profile number for the given query profile.

      Method get_value_mapping

        `mapping get_value_mapping(int profile)`

      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(int profile_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

        `bool check_timeout()`

      Description

        Checks if it is time to check if the profile values are to old.

      Method create

        `Search.Utils.ProfileEntry Search.Utils.ProfileEntry(int database_profile_id, int query_profile_id, ProfileCache cache)`

      Parameter `cache`

        The parent cache object.

      Method get_database

        `Search.Database.MySQL get_database()`

      Description

        Returns a cached search database for the current database profile.

      Method get_database_value

        `mixed get_database_value(string index)`

      Description

        Returns the database profile value index.

      Method get_query_value

        `mixed get_query_value(string index)`

      Description

        Returns the query profile value index.

      Method get_ranking

        `Search.RankingProfile get_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

        `void new_entry(int latency, 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

    `void deserialize(object o, function(function(mixed:void), string, type:void) deserializer)`

  Description

    Call lfun::_deserialize() in o.

  See also

    serialize(), lfun::_deserialize(), Serializable()->_deserialize()

  Method serialize

    `void serialize(object o, 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.

    Method _decode

      `Serializer.Encodeable decode_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.Encodeable data)`

    Description

      Callback for encoding the object. Returns a mapping from variable name to value.

      Called automatically by encode_value, not normally called manually.

    Inherit Serializable

      inherit Serializable : Serializable

  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

      `protected void _deserialize(object o, 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

      `protected void _deserialize_variable(function(function(mixed:void), string, type:void) deserializer, function(mixed:void) setter, string symbol, type symbol_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

    `protected void _serialize(object o, 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

    `protected void _serialize_variable(function(mixed, string, type:void) serializer, mixed value, string symbol, type symbol_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.

    Method add_source

      `void add_source(mixed source, int|void start, int|void length)`

    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

      string

        An ordinary 8-bit wide pike string.

      System.Memory

        An initialized instance of the System.Memory class.

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

    Method create

      `Shuffler.Shuffle Shuffler.Shuffle(object fd, object shuffler, mixed throttler, mixed backend)`

    Description

      This object is normally not created directly, instead use Shuffler()->shuffle

    Method pause

      `void pause()`

    Description

      Temporarily pause all data transmission

    Method sent_data

      `int sent_data()`

    Description

      Returns the amount of data that has been sent so far.

    Method set_done_callback

      `void set_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

      `void set_request_arg(mixed arg)`

    Description

      Sets the extra argument sent to Throttler()->request() and Throttler()->give_back.

    Method set_throttler

      `void set_throttler(Throttler t)`

    Description

      Calling this function overrides the Shuffler global throttler.

    Variable shuffler

      `Shuffler Shuffler.Shuffle.shuffler`

    Description

      The Shuffler that owns this Shuffle object

    Method start

      `void start()`

    Description

      Start sending data from the sources.

    Method state

      `int state()`

    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

      `void stop()`

    Description

      Stop all data transmission, and then call the done callback

    Variable throttler

      `Throttler Shuffler.Shuffle.throttler`

    Description

      The Throttler that is associated with this Shuffle object, if any.

  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

      `void pause()`

    Description

      Pause all Shuffle objects associated with this Shuffler

    Method set_backend

      `void set_backend(Pike.Backend b)`

    Description

      Set the backend that will be used by all Shuffle objects created from this shuffler.

    Method set_throttler

      `void set_throttler(Throttler t)`

    Description

      Set the throttler that will be used in all Shuffle objects created from this shuffler, unless overridden in the Shuffle objects.

    Method shuffle

      `Shuffle shuffle(Stdio.NonblockingStream destination)`

    Description

      Create a new Shuffle object.

      The destination has to support nonblocking I/O.

    Method start

      `void start()`

    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

      `void give_back(Shuffle shuffle, int amount)`

    Description

      This function will be called by the Shuffle object to report that some data assigned to it by this throttler was unusued, and can be given to another Shuffle object instead.

    Method request

      `void request(Shuffle shuffle, int amount, 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.

    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

      `void add_query_variable(string name, string value)`

    Description

      Adds the provided query variable to the already existing ones. Will overwrite an existing variable with the same name.

    Method add_query_variables

      `void add_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.

    Variable authority

      `string Standards.URI.authority`

    Description

      Authority component of URI (formerly called net_loc, from RFC 2396 known as authority)

    Variable base_uri

      `this_program Standards.URI.base_uri`

    Description

      The base URI object, if present

    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.URI Standards.URI(URI uri)`
      `Standards.URI Standards.URI(URI uri, URI base_uri)`
      `Standards.URI Standards.URI(URI uri, string base_uri)`
      `Standards.URI Standards.URI(string uri)`
      `Standards.URI Standards.URI(string uri, URI base_uri)`
      `Standards.URI Standards.URI(string uri, string base_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.

    Variable fragment

      `string Standards.URI.fragment`

    Description

      The fragment part of URI. May be 0 if not present.

    Method get_http_path_query

      `string get_http_path_query()`

    Description

      Return the path and query part of the URI, coded according to RFC 1738.

    Method get_http_query

      `string get_http_query()`

    Description

      Return the query part, coded according to RFC 1738, or zero.

    Method get_path_query

      `string get_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)`.

    Variable host
    Variable user
    Variable password

      `string Standards.URI.host`
      `string Standards.URI.user`
      `string 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 Standards.URI.query`

    Description

      Query component of URI. May be 0 if not present.

    Method reparse_uri

      `void reparse_uri()`
      `void reparse_uri(URI base_uri)`
      `void reparse_uri(string base_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.

    Variable scheme

      `string Standards.URI.scheme`

    Description

      Scheme component of URI

    Method set_query_variables

      `void set_query_variables(mapping(string:string) vars)`

    Description

      Sets the query variables from the provided mapping.

  Module Standards.ASN1

    Method decode_der_oid

      `string decode_der_oid(string der_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

      `string encode_der_oid(string dotted_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.Object der_decode(Stdio.Buffer data, mapping(int:program) types)`

      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.

      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 secure_der_decode(string(8bit) data, mapping(int:program)|void types)`

      Description

        Works just like simple_der_decode, except it will return `0` if there is trailing data in the provided ASN.1 data.

      See also

        simple_der_decode

      Method simple_der_decode

        `.Types.Object simple_der_decode(string(8bit) data, mapping(int:program)|void types)`

      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

        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

          `Standards.ASN1.Decode.Constructed Standards.ASN1.Decode.Constructed(int cls, int tag, string(8bit) raw, array(.Types.Object) elements)`

        Method get_der_content

          `string(8bit) get_der_content()`

        Description

          Get raw encoded contents of object

        Inherit Compound

          inherit .Types.Compound : Compound

      CLASS Standards.ASN1.Decode.Primitive

        Description

          Primitive unconstructed ASN1 data type.

        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

          `Standards.ASN1.Decode.Primitive Standards.ASN1.Decode.Primitive(int cls, int tag, string(8bit) raw)`

        Method get_der_content

          `string(8bit) get_der_content()`

        Description

          Get raw encoded contents of object

        Inherit Object

          inherit Types.Object : 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

      `bool asn1_IA5_valid(string s)`

    Method asn1_bmp_valid

      `bool asn1_bmp_valid(string s)`

    Method asn1_broken_teletex_valid

      `bool asn1_broken_teletex_valid(string s)`

    Method asn1_printable_valid

      `bool asn1_printable_valid(string s)`

    Description

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

    Method asn1_universal_valid

      `int(0..0) asn1_universal_valid(string s)`

    Method asn1_utf8_valid

      `int(1..1) asn1_utf8_valid(string s)`

    Description

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

    Method extract_cls

      `int(2bit) extract_cls(int i)`

    Description

      Extract ASN1 type class from a combined tag.

    See also

      make_combined_tag

    Method extract_tag

      `int extract_tag(int i)`

    Description

      Extract ASN1 type tag from a combined tag.

    See also

      make_combined_tag

    Method make_combined_tag

      `int make_combined_tag(int cls, int tag)`

    Description

      Combines tag and class to a single integer, for internal uses.

    Parameter `cls`

      ASN1 type class (0..3).

    Parameter `tag`

      ASN1 type tag (1..).

    Returns

      The combined tag.

    See also

      extract_tag, extract_cls

    CLASS Standards.ASN1.Types.BMPString

      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

      Description

        Bit string object

      Inherit Object

        inherit Object : Object

      Method set_from_ascii

        `this_program set_from_ascii(string(8bit) s)`

      Description

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

      Method set_length

        `this_program set_length(int len)`

      Description

        Sets the length of the bit string to len number of bits. Will only work correctly on strings longer than len bits.

      Variable value

        `string(8bit) Standards.ASN1.Types.BitString.value`

      Description

        value of object

    CLASS Standards.ASN1.Types.Boolean

      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

      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

      Description

        Compound object primitive

      Variable elements

        `array(Object) Standards.ASN1.Types.Compound.elements`

      Description

        Contents of compound object.

      Inherit Object

        inherit Object : Object

    CLASS Standards.ASN1.Types.Enumerated

      Description

        Enumerated object

      Inherit Integer

        inherit Integer : Integer

    CLASS Standards.ASN1.Types.GeneralizedTime

      Method get_posix

        `int get_posix()`

      Inherit UTC

        inherit UTC : UTC

      Method set_posix

        `variant this_program set_posix(Calendar.ISO_UTC.Second second)`

    CLASS Standards.ASN1.Types.IA5String

      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

      Description

        Object identifier object

      Method append

        `this_program append(int ... args)`

      Description

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

      Variable id

        `array(int) Standards.ASN1.Types.Identifier.id`

      Description

        value of object

      Inherit Object

        inherit Object : Object

    CLASS Standards.ASN1.Types.Integer

      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.MetaExplicit Standards.ASN1.Types.MetaExplicit(int cls, int tag, mapping(int:program)|void types)`

    CLASS Standards.ASN1.Types.Null

      Description

        Null object

      Inherit Object

        inherit Object : Object

    CLASS Standards.ASN1.Types.Object

      Description

        Generic, abstract base class for ASN1 data types.

      Method get_cls

        `int get_cls()`

      Description

        Get the class of this object.

      Returns

        The class of this object.

      Method get_combined_tag

        `int 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_der_content

        `string(8bit) get_der_content()`

      Description

        Return the DER payload.

      Method get_tag

        `int get_tag()`

      Description

        Get the tag for this object.

      Returns

        The tag for this object.

    CLASS Standards.ASN1.Types.OctetString

      Description

        Octet string object

      Inherit String

        inherit String : String

    CLASS Standards.ASN1.Types.PrintableString

      Description

        PrintableString object

      Inherit String

        inherit String : String

    CLASS Standards.ASN1.Types.Sequence

      Description

        Sequence object

      Inherit Compound

        inherit Compound : Compound

    CLASS Standards.ASN1.Types.Set

      Description

        Set object

      Inherit Compound

        inherit Compound : Compound

    CLASS Standards.ASN1.Types.String

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

      Description

        This used to be a string encoded with the T.61 character coding, and has been obsolete since the early 1990:s.

      See also

        BrokenTeletexString

      Inherit BrokenTeletexString

        inherit BrokenTeletexString : BrokenTeletexString

    CLASS Standards.ASN1.Types.UTC

      Description

        UTCTime

        RFC 2459 4.1.2.5.1

      Method get_posix

        `int get_posix()`

      Inherit String

        inherit String : String

      Method set_posix

        `variant this_program set_posix(Calendar.ISO_UTC.Second second)`

    CLASS Standards.ASN1.Types.UTF8String

      Description

        UTF8 string object

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

        Variable width encoding, see rfc2279.

      Inherit String

        inherit String : String

    CLASS Standards.ASN1.Types.UniversalString

      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

      Inherit String

        inherit String : String

Module Standards.BSON

  Description

    Tools for handling the BSON structured data format. See http://www.bsonspec.org/.

  Variable MaxKey

    `object Standards.BSON.MaxKey`

  Variable MinKey

    `object Standards.BSON.MinKey`

  Method decode

    `mixed decode(string bson)`

  Description

    Decode a BSON formatted document string into a native Pike data structure.

  Method decode_array

    `array decode_array(string bsonarray)`

  Description

    Decode a BSON formatted string containing multiple data structures

  Method encode

    `string encode(mapping m, int|void query_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.

  Method encode_array

    `string encode_array(array(mapping) documents)`

  Description

    Encode an array of data structures as a BSON formatted string

  CLASS Standards.BSON.Binary

    Method create

      `Standards.BSON.Binary Standards.BSON.Binary(string _data, int|void _subtype)`

  CLASS Standards.BSON.Javascript

    Method create

      `Standards.BSON.Javascript Standards.BSON.Javascript(string _data)`

  CLASS Standards.BSON.ObjectId

    Method create

      `Standards.BSON.ObjectId Standards.BSON.ObjectId(string|void _id)`

  CLASS Standards.BSON.Regex

    Method create

      `Standards.BSON.Regex Standards.BSON.Regex(string _regex, string _options)`

  CLASS Standards.BSON.Symbol

    Method create

      `Standards.BSON.Symbol Standards.BSON.Symbol(string _data)`

  CLASS Standards.BSON.Timestamp

    Method create

      `Standards.BSON.Timestamp Standards.BSON.Timestamp(int|void _timestamp)`

Module Standards.EXIF

  Description

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

  Method get_properties

    `mapping get_properties(Stdio.File file)`

  Description

    Retrieve the EXIF properties of the given file.

  Parameter `file`

    The Stdio.File object containing wanted EXIF properties.

  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(string code)`

  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
  `string region`
  `string division`
  `string name`
  `string type`

Method division_code_to_name

  `string division_code_to_name(string code)`

Description

  Similar to division_code_to_line(), but only returns the name

Method division_guess_to_codes

  `array(string) division_guess_to_codes(string code)`

Description

  Return an array of possible division codes given a division name.

Returns

  Array

  `array(string) regions`

  Array
  `string region`
  `string division`
  `string name`
  `string type`

Method division_guess_to_lines

  `array(array(string)) division_guess_to_lines(string name)`

Description

  Return an array of possible divisions given a division name.

Returns

  Array

  `array(string) regions`

  Array
  `string region`
  `string division`
  `string name`
  `string type`

Method division_name_to_line
Method division_name_to_code

  `array(string) division_name_to_line(string name)`
  `string division_name_to_code(string code)`

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

  `string region_code_to_name(string code)`

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

  `string region_name_to_code(string code)`

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(string region)`

Description

  Given a region (country etc) return all divisions codes in that region

Method region_to_divisions

  `array(array(string)) region_to_divisions(string region)`

Description

  Given a region (country etc) return all divisions in that region

Returns

  Array

  `array(string) regions`

  Array
  `string region`
  `string division`
  `string name`
  `string type`

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 neccessary during the implementation of the full standard.

  Method decode_string

    `string decode_string(string in, int type)`

  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(string in)`

  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(int in, void|int no_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

    `string resynchronise(string in)`

  Description

    Reverses the effects of unsyncronisation done according to ID3v2.4.0-structure section 6.1.

  See also

    unsynchronise

  Method synchsafe_to_int

    `int synchsafe_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

    `string unsynchronise(string in)`

  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 bytes_left

      `int bytes_left()`

    Description

      The number of bytes left before reaching the limit set by set_limit.

    Method create

      `Standards.ID3.Buffer Standards.ID3.Buffer(Stdio.File buffer)`

    Method peek

      `string peek()`

    Description

      Preview the next byte. Technically it is read from the encapsulated buffer and put locally to avoid seeking.

    Method read

      `string read(int bytes)`

    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

      `void set_limit(int bytes)`

    Description

      Set an artificial EOF bytes bytes further into the buffer.

  CLASS Standards.ID3.ExtendedHeader

    Method create

      `Standards.ID3.ExtendedHeader Standards.ID3.ExtendedHeader(void|Buffer buffer)`

    Method decode

      `void decode(Buffer buffer)`

    Method encode

      `string encode()`

  CLASS Standards.ID3.Frame

    Description

      Manages the common frame information.

    Method create

      `Standards.ID3.Frame Standards.ID3.Frame(string|Buffer in, TagHeader thd)`

  CLASS Standards.ID3.FrameData

    Description

      Abstract class for frame data.

    Method changed

      `bool changed()`

    Description

      Is the content altered?

    Method create

      `Standards.ID3.FrameData Standards.ID3.FrameData(void|string data)`

  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

    Method _indices

      `array indices( Standards.ID3.Tag arg )`

    Description

      Indices will return the indices of the tag object.

    Method _values

      `array values( Standards.ID3.Tag arg )`

    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.Tag Standards.ID3.Tag(Stdio.File fd)`

    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.

    Constant version

      `constant Standards.ID3.Tag.version`

    Description

      The version of the encapsulated tag in the form `"%d.%d.%d"`.

  CLASS Standards.ID3.TagHeader

    Description

      Represents an ID3v2 header.

    Method create

      `Standards.ID3.TagHeader Standards.ID3.TagHeader(void|Buffer buffer)`

    Method decode

      `void decode(Buffer buffer)`

    Description

      Decode a tag header from buffer and store its data in this object.

    Method encode

      `string encode()`

    Description

      Encode the data in this tag and return as a string.

    Method set_flag_unsynchronisation

      `bool set_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.Tagv2 Standards.ID3.Tagv2(void|Buffer|Stdio.File buffer, 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 ftp://ftp.rfc-editor.org/in-notes/rfc3490.txt.

  Variable Punycode

    `object Standards.IDNA.Punycode`

  Description

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

  Method nameprep

    `string nameprep(string s, bool|void allow_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 to_ascii(string s, bool|void allow_unassigned, bool|void use_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

    `string to_unicode(string s)`

  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 zone_to_ascii(string s, bool|void allow_unassigned, bool|void use_std3_ascii_rules)`

  Description

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

  Method zone_to_unicode

    `string zone_to_unicode(string s)`

  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 get_information(Stdio.File fd)`

  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 convert_b_to_t(string code)`

  Description

    Converts an ISO 639-2/B code to an ISO 639-2/T code.

  Method convert_t_to_b

    `string convert_t_to_b(string code)`

  Description

    Converts an ISO 639-2/T code to an ISO 639-2/B code.

  Method get_language

    `string get_language(string code)`

  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

    `string get_language_b(string code)`

  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

    `string get_language_t(string code)`

  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

    `string map_639_1(string code)`

  Description

    Look up the ISO 639-2/T code given an ISO 639-1 code in lower case.

  Method map_to_639_1

    `string map_to_639_1(string code)`

  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 Standards.JSON.ASCII_ONLY`
    `constant Standards.JSON.HUMAN_READABLE`
    `constant Standards.JSON.PIKE_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.

  Method decode

    `array|mapping|string|float|int|object decode(string s)`

  Description

    Decodes a JSON string.

  Throws

    Throws an exception in case the data contained in `s` is not valid JSON.

  Method decode_utf8

    `array|mapping|string|float|int|object decode_utf8(string s)`

  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

    `string encode(int|float|string|array|mapping|object val, void|int flags, void|function(:void)|object|program|string callback)`

  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

    `string escape_string(string str, void|int flags)`

  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

  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 validate

    `int validate(string s)`

  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

    `int validate_utf8(string s)`

  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.

    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.

    Inherit Generic

      inherit Error.Generic : Generic

  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.Validator Standards.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

      `private bool has_schema_array(mapping(string:mixed) schema, string property)`

    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

      `private bool has_schema_array_mapping(mapping(string:mixed) schema, string property)`

    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

      `private bool has_schema_array_string(mapping(string:mixed) schema, string property)`

    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

      `private bool has_schema_boolean(mapping(string:mixed) schema, string property)`

    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

      `private bool has_schema_integer(mapping(string:mixed) schema, string property)`

    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

      `private bool has_schema_mapping(mapping(string:mixed) schema, string property)`

    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

      `private bool has_schema_mapping_mapping(mapping(string:mixed) schema, string property)`

    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

      `private bool has_schema_number(mapping(string:mixed) schema, string property)`

    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

      `private bool has_schema_string(mapping(string:mixed) schema, string property)`

    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

      `private bool is_JSON_boolean(mixed value)`

    Returns

      1 if the specified `value` is either Standards.JSON.true or Standards.JSON.false.

    Method validate

      `string validate(mixed json)`

    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

      `private string validate_array(string key, mixed value, 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

      `private string validate_integer(string key, mixed value, 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

      `private string validate_item_type(string key, mixed value, mapping schema)`

    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

      `private string validate_number(string key, mixed value, 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

      `private string validate_object(string key, mixed value, 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

      `private string validate_properties(string key, mixed value, mapping schema)`

    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

      `private string validate_string(string key, mixed value, 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.PEM

  Description

    Support for parsing PEM-style messages, defined in RFC1421. Encapsulation defined in RFC934.

  Method build

    `string build(string tag, string data, void|mapping(string:string) headers, void|string checksum)`

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

  Method decrypt_body

    `string 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 derive_key

    `string(8bit) derive_key(string(8bit) password, string(8bit) salt, int bytes)`

  Description

    Key derivation function used in PEM.

  FIXME

    Derived from OpenSSL. Is there any proper specification?

    It seems to be related to PBKDF1 from RFC2898.

  Method simple_decode

    `string simple_decode(string 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 Standards.PEM.Message.body`

    Description

      The decode message body.

    Variable headers

      `mapping(string:string) Standards.PEM.Message.headers`

    Description

      Encapsulated headers. If headers occurred multiple times, they will be concatenated to the value with a null character as delimiter.

    Variable post

      `string Standards.PEM.Message.post`

    Description

      Post-encapsulation boundary string.

    Variable pre

      `string Standards.PEM.Message.pre`

    Description

      Pre-encapsulation boundary string.

    Variable trailer

      `string Standards.PEM.Message.trailer`

    Description

      Message trailer, like RFC4880 checksum.

  CLASS Standards.PEM.Messages

    Description

      The Messages class acts as an envelope for a PEM message file or stream.

    Method create

      `Standards.PEM.Messages Standards.PEM.Messages(string data)`

    Description

      A Messages object is created with the file or stream data.

    Variable fragments

      `array(string|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: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.

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 7292

  Method parse_private_key

    `Crypto.Sign.State parse_private_key(Sequence seq)`

  Description

    Parse a PKCS#8 PrivateKeyInfo (cf RFC 5208 section 5).

  See also

    RSA.parse_private_key(), DSA.parse_private_key()

  Method parse_private_key

    `variant Crypto.Sign.State parse_private_key(string key)`

  Module Standards.PKCS.CSR

    Description

      Handling of Certificate Signing Requests (PKCS-10, RFC 2314, RFC 2986)

    Method build_csr

      `Sequence build_csr(Crypto.Sign sign, Sequence name, mapping(string:array(Object)) attributes, Crypto.Hash|void hash)`

    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

      `Sequence sign_cri(CRI cri, Crypto.Sign sign, Crypto.Hash hash)`

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

      Variable attributes

        `void Standards.PKCS.CSR.CRI.attributes`

      Description

        Subject attributes.

      Inherit Sequence

        inherit Sequence : Sequence

      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

      `variant Sequence build_distinguished_name(mapping args)`

    Method build_distinguished_name

      `variant Sequence build_distinguished_name(array args)`

    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(Sequence dn)`

    Description

      Perform the reverse operation of build_distinguished_name().

    See also

      build_distinguished_name()

    Method get_certificate_issuer

      `__deprecated__ Sequence get_certificate_issuer(string cert)`

    Description

      Return the certificate issuer RDN from a certificate string.

    Parameter `cert`

      A string containing an X509 certificate.

      Note that the certificate usually must be decoded using Standards.PEM.simple_decode().

    Returns

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

    Deprecated

      Replaced by Standards.X509.decode_certificate.

    Method get_certificate_subject

      `__deprecated__ Sequence get_certificate_subject(string cert)`

    Description

      Return the certificate subject RDN from a certificate string.

    Parameter `cert`

      A string containing an X509 certificate.

      Note that the certificate usually must be decoded using PEM.simpe_decode().

    Returns

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

    Deprecated

      Replaced by Standards.X509.decode_certificate.

    Method get_dn_string

      `string get_dn_string(Sequence dnsequence)`

    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

      `Sequence algorithm_identifier(Crypto.DSA|void dsa)`

    Description

      Returns the AlgorithmIdentifier as defined in RFC5280 section 4.1.1.2. Optionally the DSA parameters are included, if a DSA object is given as argument.

    Method build_private_key

      `Sequence build_private_key(Crypto.DSA dsa)`

    Description

      Creates a PrivateKeyInfo ASN.1 sequence for the given rsa object. See RFC 5208 section 5.

    Method build_public_key

      `Sequence build_public_key(Crypto.DSA dsa)`

    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.DSA parse_private_key(Sequence seq)`

    Method parse_private_key

      `variant Crypto.DSA parse_private_key(string key)`

    Method parse_public_key

      `Crypto.DSA parse_public_key(string key, Gmp.mpz p, Gmp.mpz q, Gmp.mpz g)`

    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

      `string private_key(Crypto.DSA dsa)`

    Method public_key

      `string public_key(Crypto.DSA dsa)`

    Description

      Generates the DSAPublicKey value, as specified in RFC2459.

    Method signature_algorithm_id

      `Sequence signature_algorithm_id(Crypto.Hash hash)`

    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

      `protected mapping(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 parse_ec_parameters(string ec_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_ec_parameters

      `variant Crypto.ECC.Curve parse_ec_parameters(Standards.ASN1.Types.Identifier|void named_curve)`

    Method parse_private_key

      `Crypto.ECC.SECP_521R1.ECDSA parse_private_key(Sequence a, Crypto.ECC.Curve|void c)`

    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

      `variant Crypto.ECC.SECP_521R1.ECDSA parse_private_key(string(8bit) ec_private_key, Crypto.ECC.Curve|void c)`

    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 private_key

      `string(8bit) private_key(Crypto.ECC.SECP_521R1.ECDSA ecdsa)`

    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.

  Module Standards.PKCS.Identifiers

    Description

      Various ASN.1 identifiers used by PKCS.

  Module Standards.PKCS.RSA

    Description

      RSA operations and types as described in PKCS-1.

    Method algorithm_identifier

      `Sequence algorithm_identifier()`

    Description

      Returns the AlgorithmIdentifier as defined in RFC5280 section 4.1.1.2.

    Method build_private_key

      `Sequence build_private_key(Crypto.RSA rsa)`

    Description

      Creates a PrivateKeyInfo ASN.1 sequence for the given rsa object. See RFC 5208 section 5.

    Method build_public_key

      `Sequence build_public_key(Crypto.RSA rsa)`

    Description

      Creates a SubjectPublicKeyInfo ASN.1 sequence for the given rsa object. See RFC 5280 section 4.1.2.7.

    Method parse_private_key

      `Crypto.RSA.State parse_private_key(Sequence seq)`

    Description

      Decode a RSAPrivateKey structure

    Parameter `key`

      RSAPrivateKey provided in ASN.1 format

    Returns

      Crypto.RSA object

    Method parse_private_key

      `variant Crypto.RSA.State parse_private_key(string key)`

    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.State parse_public_key(string key)`

    Description

      Decode a DER-coded RSAPublicKey structure

    Parameter `key`

      RSAPublicKey provided in ASN.1 DER-encoded format

    Returns

      Crypto.RSA object

    Method private_key

      `string private_key(Crypto.RSA rsa)`

    Description

      Create a DER-coded RSAPrivateKey structure

    Parameter `rsa`

      Crypto.RSA object

    Returns

      ASN1 coded RSAPrivateKey structure

    Method public_key

      `string public_key(Crypto.RSA rsa)`

    Description

      Create a DER-coded RSAPublicKey structure

    Parameter `rsa`

      Crypto.RSA object

    Returns

      ASN1 coded RSAPublicKey structure

    Method signature_algorithm_id

      `Sequence signature_algorithm_id(Crypto.Hash hash)`

    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

      `string build_digestinfo(string msg, Crypto.Hash hash)`

    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

      `Signed sign(Sequence tbs, Crypto.Sign sign, Crypto.Hash hash)`

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

      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.

      Inherit Sequence

        inherit Sequence : Sequence

      Method sign

        `this_program sign(Crypto.Sign sign, Crypto.Hash hash)`

      Description

        Sign tbs with the provided sign and hash.

        Sets algorithm and signature.

      Returns

        Returns the Signed object.

      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.

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

    RFC4122: 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

    `constant string Standards.UUID.NameSpace_DNS`

  Description

    Name space UUID for DNS.

  Constant NameSpace_OID

    `constant string Standards.UUID.NameSpace_OID`

  Description

    Name space UUID for OID.

  Constant NameSpace_URL

    `constant string Standards.UUID.NameSpace_URL`

  Description

    Name space UUID for URL.

  Constant NameSpace_X500

    `constant string Standards.UUID.NameSpace_X500`

  Description

    Name space UUID for X500.

  Constant Nil_UUID

    `constant string Standards.UUID.Nil_UUID`

  Description

    The Nil UUID.

  Method format_uuid

    `string format_uuid(string uuid)`

  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

    `UUID make_dns(string name)`

  Description

    Creates a DNS UUID with the given DNS name.

  Method make_dns

    `UUID make_dns(string name)`

  Description

    Creates a DNS UUID with the given DNS name.

  Method make_null

    `UUID make_null()`

  Description

    Creates a null UUID object.

  Method make_oid

    `UUID make_oid(string name)`

  Description

    Creates an OID UUID with the given OID.

  Method make_oid

    `UUID make_oid(string name)`

  Description

    Creates an OID UUID with the given OID.

  Method make_url

    `UUID make_url(string name)`

  Description

    Creates a URL UUID with the given URL.

  Method make_url

    `UUID make_url(string name)`

  Description

    Creates a URL UUID with the given URL.

  Method make_version1

    `UUID make_version1(int node)`

  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

    `UUID make_version3(string name, string|UUID namespace)`

  Description

    Creates a version 3 UUID with a name string and a binary representation of a name space UUID.

  Method make_version4

    `UUID make_version4()`

  Description

    Creates a version 4 (random) UUID.

  Method make_version5

    `UUID make_version5(string name, string|UUID namespace)`

  Description

    Creates a version 5 UUID with a name string and a binary representation of a name space UUID.

  Method make_x500

    `UUID make_x500(string name)`

  Description

    Creates an X500 UUID with the gived X500 address.

  Method make_x500

    `UUID make_x500(string name)`

  Description

    Creates an X500 UUID with the gived X500 address.

  Method parse_uuid

    `string parse_uuid(string uuid)`

  Description

    Returns the binary representation of the UUID uuid.

  Method set_clock_state

    `void set_clock_state(int last_time, int seq)`

  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.

    Method create

      `Standards.UUID.UUID Standards.UUID.UUID(void|string in)`

    Description

      Optionally created with a string or binary representation of a UUID.

    Method encode

      `string encode()`

    Description

      Encodes a binary representation of the UUID.

    Variable node

      `int Standards.UUID.UUID.node`

    Description

      The UUID node. Should be 48 bit.

    Method posix_time

      `int posix_time()`

    Description

      Returns the posix time of the UUID.

    Method str

      `string str()`

    Description

      Creates a string representation of the UUID.

    Method str_variant

      `string str_variant()`

    Description

      Returns a string representation of the variant, e.g. `"IETF draft variant"`.

    Method str_version

      `string str_version()`

    Description

      Returns a string representation of the version, e.g. `"Name-based (MD5)"`.

    Method time_hi_and_version

      `int time_hi_and_version()`

    Description

      Returns the time_hi_and_version field.

    Method time_low

      `int time_low()`

    Description

      Returns the time_low field.

    Method time_mid

      `int time_mid()`

    Description

      Returns the time_mid field.

    Variable timestamp

      `int Standards.UUID.UUID.timestamp`

    Description

      60 bit value representing the time stamp.

    Method urn

      `string urn()`

    Description

      Creates a URN representation of the UUID.

    Method validate

      `void validate()`

    Description

      Validates the current UUID.

    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.

Module Standards.X509

  Description

    Functions to generate and validate RFC2459 style X.509 v3 certificates.

  Method decode_certificate

    `TBSCertificate decode_certificate(string|object cert)`

  Description

    Decodes a certificate and verifies that it is structually sound. Returns a TBSCertificate object if ok, otherwise `0`.

  Method load_authorities

    `mapping(string:array(Verifier)) load_authorities(string|array(string)|void root_cert_dirs)`

  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.

  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"`, it is assumed to contain a concatenation of all the certificates in the directory.

  See also

    verify_certificate(), verify_certificate_chain()

  Method make_extension

    `Sequence make_extension(Identifier id, Object ext, void|int critical)`

  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

    `string make_selfsigned_certificate(Crypto.Sign.State c, int ttl, mapping|array name, mapping(Identifier:Sequence)|void extensions, void|Crypto.Hash h, void|int serial)`

  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

    `TBSCertificate make_tbs(Sequence issuer, Sequence algorithm, Sequence subject, Sequence keyinfo, Integer serial, Sequence validity, array|int(0..0)|void extensions)`

  Description

    Creates the ASN.1 TBSCertificate sequence (see RFC2459 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

    `variant TBSCertificate make_tbs(Sequence issuer, Sequence algorithm, Sequence subject, Sequence keyinfo, Integer serial, int ttl, array|int(0..0)|void extensions)`

  Description

    Creates the ASN.1 TBSCertificate sequence (see RFC2459 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.State parse_private_key(Sequence seq)`

  Description

    DWIM-parse the ASN.1-sequence for a private key.

  Method parse_private_key

    `variant Crypto.Sign.State parse_private_key(string private_key)`

  Description

    DWIM-parse the DER-sequence for a private key.

  Method sign_key

    `string sign_key(Sequence issuer, Crypto.Sign.State c, Crypto.Sign.State ca, Crypto.Hash h, Sequence subject, int serial, int ttl, array|mapping|void extensions)`

  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

    `Sequence sign_tbs(TBSCertificate tbs, Crypto.Sign.State sign, Crypto.Hash hash)`

  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 verify_ca_certificate(string|TBSCertificate tbs)`

  Description

    Verifies that all extensions mandated for certificate signing certificates are present and valid.

  Method verify_certificate

    `TBSCertificate verify_certificate(string s, mapping(string:Verifier|array(Verifier)) authorities)`

  Description

    Decodes a certificate, checks the signature. Returns the TBSCertificate structure, or 0 if decoding or verification failes. The valid time range for the certificate is not checked.

    Authorities is a mapping from (DER-encoded) names to a verifiers.

  Note

    This function allows self-signed certificates, and it doesn't check that names or extensions make sense.

  Method verify_certificate_chain

    `mapping verify_certificate_chain(array(string) cert_chain, mapping(string:Verifier|array(Verifier)) authorities, int|void require_trust)`

  Description

    Decodes a certificate chain, oredered 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 it's 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 failurew, 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 or CERT_CHAIN_BROKEN.
    `"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.

  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.

    See Standards.PKCS.Certificate.get_dn_string for converting the RDN to an X500 style string.

  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.

    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. RFC3280 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. RFC3280 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. RFC3280 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. RFC3280 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. RFC3280 4.2.1.2.

    Variable extensions

      `mapping(Identifier:Object) Standards.X509.TBSCertificate.extensions`

    Note

      optional

    Note

      Read only

    Inherit Sequence

      inherit Sequence : Sequence

    Method init

      `this_program init(array|Object asn1)`

    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.

    Variable internal_critical

      `protected multiset Standards.X509.TBSCertificate.internal_critical`

    Note

      optional

    Variable internal_extensions

      `protected mapping(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`

    Method low_set

      `protected void low_set(int index, Sequence|Integer val)`

    Parameter `index`

      Index in a v1 certificate.

    Parameter `val`

      New value for index.

    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`

  CLASS Standards.X509.Verifier

    Method verify

      `bool verify(Sequence algorithm, string(8bit) msg, string(8bit) signature)`

    Description

      Verifies the signature of the certificate msg using the indicated hash algorithm.

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

      `WixNode get_module_xml(Directory dir, string id, string version, string|void manufacturer, string|void description, string|void guid, string|void comments, string|void installer_version)`

    Note

      Modifies dir if it contains files at the root level.

Module System

  Description

    This module embodies common operating system calls, making them available to the Pike programmer.

  Method AllocConsole

    `int AllocConsole()`

  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

    `int AttachConsole(int pid)`

  Description

    Attaches calling process to a specific console.

  Parameter `pid`
  Note

    Only available on certain Windows systems.

  Returns

    0 on success, non-zero otherwise.

  Constant CPU_TIME_IMPLEMENTATION

    `constant string 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

    `constant string 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

    `constant int 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

  Method FreeConsole

    `int FreeConsole()`

  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

    `string GetComputerName()`

  Description

    Retrieves the NetBIOS name of the local computer.

  Note

    This function is Windows specific, and is not available on all systems.

  Method GetFileAttributes

    `int GetFileAttributes(string 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(mixed:mixed) GetNamedSecurityInfo(string name, int|void type, int|void flags)`

  Note

    This function is only available on some Win32 systems.

  See also

    SetNamedSecurityInfo()

  Method GetUserName

    `string GetUserName()`

  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.

  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

  Method LogonUser

    `object LogonUser(string username, string|int(0..0) domain, string password, int|void logon_type, int|void logon_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.

  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 token 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..0) sys, string account)`

  Note

    This function is only available on some Win32 systems.

  Method NetGetAnyDCName

    `string NetGetAnyDCName(string|int(0..0) server, string domain)`

  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

    `string NetGetDCName(string|int(0..0) server, string domain)`

  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

    `array(string|array(string|int)) NetGroupEnum(string|int(0..0)|void server, int|void level)`

  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..0) server, string group, int|void level)`

  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..0)|void server, int|void level)`

  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..0) server, string group, int|void level)`

  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..0) server, string|int(0..0) client, string|int(0..0) user, int level)`

  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

    `array(string|array(string|int)) NetUserEnum(string|int(0..0)|void server, int|void level, int|void filter)`

  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..0) server, string user, int|void level)`

  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(string username, string|int(0..0) server, int|void level)`

  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..0) server, string user, int|void level, int|void flags)`

  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..0) server, int level)`

  Parameter `level`

    One of

    `0`
    `1`

  Note

    This function is only available on some Win32 systems.

  Constant REAL_TIME_IMPLEMENTATION

    `constant string 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

    `constant string 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

    `constant int 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 RegGetKeyNames_76

    `array(string) RegGetKeyNames_76(int hkey, string key)`

  Description

    Get a list of value key names from the register (COMPAT).

    Pike 7.6 compatibility implementation of RegGetKeyNames(). The difference being that this function throws errors when keys are missing.

  Note

    This function is only available on Win32 systems.

  See also

    RegGetValue(), RegGetValues_76(), RegGetKeyNames()

  Method RegGetValue_76

    `string|int|array(string) RegGetValue_76(int hkey, string key, string index)`

  Description

    Get a single value from the register (COMPAT).

    Pike 7.6 compatibility implementation of RegGetValue(). The difference being that this function throws errors when keys are missing.

  Note

    This function is only available on Win32 systems.

  See also

    RegGetKeyNames_76(), RegGetValues_76(), RegGetValue()

  Method RegGetValues_76

    `mapping(string:string|int|array(string)) RegGetValues_76(int hkey, string key)`

  Description

    Get multiple values from the register (COMPAT).

    Pike 7.6 compatibility implementation of RegGetValues(). The difference being that this function throws errors when keys are missing.

  Note

    This function is only available on Win32 systems.

  See also

    RegGetValue_76(), RegGetKeyNames_76(), RegGetValues()

  Method SetFileAttributes

    `int SetFileAttributes(string filename)`

  Description

    Set the file attributes for the specified file.

  Note

    This function is only available on Win32 systems.

  See also

    GetFileAttributes()

  Method SetNamedSecurityInfo

    `array(mixed) SetNamedSecurityInfo(string name, mapping(string:mixed) options)`

  Note

    This function is only available on some Win32 systems.

  See also

    GetNamedSecurityInfo()

  Method chmod

    `void chmod(string path, int mode)`

  Description

    Sets the protection mode of the specified path.

  Note

    Throws errors on failure.

  See also

    Stdio.File->open(), errno()

  Method chown

    `void chown(string path, int uid, int gid, void|int symlink)`

  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

    `int chroot(string newroot)`
    `int chroot(Stdio.File newroot)`

  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

    `void cleargroups()`

  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 closelog

    `void closelog()`

  FIXME

    Document this function.

  Method daemon

    `int daemon(int nochdir, int noclose)`

  Description

    Low level system daemon() function, see also Process.daemon()

  Method dumpable

    `bool dumpable(bool|void val)`

  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

    `int endgrent()`

  Description

    Closes the /etc/groups file after using the getgrent function.

  See also

    get_all_groups() getgrent() setgrent()

  Method endpwent

    `int endpwent()`

  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 get_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(string domain, string path, string property)`

  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 get_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

    `int getegid()`

  Description

    Get the effective group ID.

  See also

    setuid, getuid, setgid, getgid, seteuid, geteuid, setegid

  Method geteuid

    `int geteuid()`

  Description

    Get the effective user ID.

  See also

    setuid, getuid, setgid, getgid, seteuid, getegid, setegid

  Method getgid

    `int getgid()`

  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
    `string 0` | Group name
    `string 1` | Group password (encrypted)
    `int 2` | ID of the group
    `array 3..` | 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(string addr)`

  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(string hostname)`

  Description

    Returns an array with information about the specified host.

  Returns

    The returned array contains the following:

    Array
    `string hostname` | 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

    `string gethostname()`

  Description

    Returns a string with the name of the host.

  Note

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

  Method getitimer

    `array(float) getitimer(int timer)`

  Description

    Shows the state of the selected timer.

  Returns

    Array
    `float 0` | The interval of the timer.
    `float 1` | 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
    `float 0` | Load average over the last minute.
    `float 1` | Load average over the last 5 minutes.
    `float 2` | Load average over the last 15 minutes.

  Method getpgrp

    `int getpgrp(int|void pid)`

  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

    `int getpid()`

  Description

    Returns the process ID of this process.

  See also

    getppid, getpgrp

  Method getppid

    `int getppid()`

  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
    `string 0` | Users username (loginname)
    `string 1` | User password (encrypted)
    `int 2` | Users ID
    `int 3` | Users primary group ID
    `string 4` | Users real name an possibly some other info
    `string 5` | Users home directory
    `string 6` | Users shell

    0 if EOF.

  See also

    get_all_users() getpwnam() getpwent() setpwent() endpwent()

  Method getrlimit

    `array(int) getrlimit(string resource)`

  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
    `int 0` | The soft limit for the resource. `-1` means no limit.
    `int 1` | 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

    `int getsid(int|void pid)`

  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

    `int getuid()`

  Description

    Get the real user ID.

  See also

    setuid, setgid, getgid, seteuid, geteuid, setegid, getegid

  Method hardlink

    `void hardlink(string from, string to)`

  Description

    Create a hardlink named to from the file from.

  Note

    This function is not available on all platforms.

  See also

    symlink(), mv(), rm()

  Inherit _system

    inherit _system : _system

  Method initgroups

    `void initgroups(string name, int base_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

    `bool innetgr(string netgroup, string|void machine, string|void user, string|void domain)`

  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

    `float nanosleep(int|float seconds)`

  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

    `string normalize_path(string path)`

  Description

    Normalize an existing Windows file system path.

    The following transformations are currently done:

    - 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

    `void openlog(string ident, int options, facility)`

  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

    `int rdtsc()`

  Description

    Executes the rdtsc (clock pulse counter) instruction and returns the result.

  Method readlink

    `string readlink(string path)`

  Description

    Returns what the symbolic link path points to.

  Note

    This function is not available on all platforms.

  See also

    symlink()

  Method resolvepath

    `string resolvepath(string 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

    `int setegid(int egid)`

  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

    `int seteuid(int euid)`

  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

    `int setgid(int gid)`

  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

    `int setgrent()`

  Description

    Rewinds the getgrent pointer to the first entry

  See also

    get_all_groups() getgrent() endgrent()

  Method setgroups

    `void setgroups(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

    `float setitimer(int timer, int|float value)`

  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

    `int setpgrp()`

  Description

    Make this process a process group leader.

  Note

    Not supported on all platforms.

  Method setproctitle

    `void setproctitle(string title, mixed ... extra)`

  Description

    Sets the processes title.

  Method setpwent

    `int setpwent()`

  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

    `int setresgid(int rgid, int egid, int sgid)`

  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

    `int setresuid(int ruid, int euid, int suid)`

  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

    `bool setrlimit(string resource, int soft, int hard)`

  Description

    Sets the soft and the hard process limit on a resource.

  See also

    getrlimit, getrlimits

  Method setsid

    `int setsid()`

  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

    `int setuid(int uid)`

  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

    `int sleep(int seconds)`

  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

    `void symlink(string from, string to)`

  Description

    Create a symbolic link named to that points to from.

  Note

    This function is not available on all platforms.

  See also

    hardlink(), readlink(), mv(), rm()

  Method sync

    `void sync()`

  Description

    Flush operating system disk buffers to permanent storage.

  Note

    On some operating systems this may require administrative privileges.

  Method syslog

    `void syslog(int priority, string msg)`

  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

    `int umask(void|int mask)`

  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

    `void usleep(int usec)`

  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

    `void utime(string path, int atime, int mtime, void|int symlink)`

  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

      `int sizeof( System.Memory arg )`

    Description

      returns the size of the memory (bytes). note: throws if not allocated

    Method `[]

      `int res = System.Memory()[ pos ]`
      `string res = System.Memory()[ pos1 ]`

    Method `[]=

      `System.Memory()[ pos ] = char`
      `System.Memory()[ pos1 ] = pos2`

    Method allocate

      `void allocate(int bytes)`
      `void allocate(int bytes, 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.Memory System.Memory()`
      `System.Memory System.Memory(string|Stdio.File filename_to_mmap)`
      `System.Memory System.Memory(int shmkey, int shmsize, int shmflg)`
      `System.Memory System.Memory(int bytes_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

      `void free()`

    Description

      Free the allocated or <tt>mmap</tt>ed memory.

    Method mmap
    Method mmap_private

      `int mmap(string|Stdio.File file)`
      `int mmap(string|Stdio.File file, int offset, int size)`
      `int mmap_private(string|Stdio.File file)`
      `int mmap_private(string|Stdio.File file, int offset, int size)`

    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 pread(int(0..) pos, int(0..) len)`
      `string pread16(int(0..) pos, int(0..) len)`
      `string pread32(int(0..) pos, int(0..) len)`
      `string pread16i(int(0..) pos, int(0..) len)`
      `string pread32i(int(0..) pos, int(0..) len)`
      `string pread16n(int(0..) pos, int(0..) len)`
      `string pread32n(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

      `int pwrite(int(0..) pos, string data)`
      `int pwrite16(int(0..) pos, string data)`
      `int pwrite32(int(0..) pos, string data)`
      `int pwrite16i(int(0..) pos, string data)`
      `int pwrite32i(int(0..) pos, string data)`

    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

      `bool valid()`

    Description

      returns 1 if the memory is valid, 0 if not allocated

    Method writeable

      `bool writeable()`

    Description

      returns 1 if the memory is writeable, 0 if not

  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.

    Method asctime

      `string asctime()`

    Description

      Return a string representing the time. Mostly useful for debug purposes, the exact format is 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.TM System.TM(int t)`

    Description

      Create a new TM initialized from a unix time_t. The timezone will always be UTC when using this function.

    Method create

      `System.TM System.TM()`

    Description

      Construct a new TM, all fields will be set to 0.

    Method create

      `System.TM System.TM(int year, int(0..11) mon, int(1..31) mday, int(0..24) hour, int(0..59) min, int(0..59) sec, string|void timezone)`

    Description

      Construct a new time using the given values. Slightly faster than setting them individually.

    Method gmtime

      `bool gmtime(int time)`

    Description

      Initialize the struct tm to the UTC time for the specified unix time_t.

    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 savings are in effect. If this field is -1 (the default) it (and the timezone info) will be updated automatically using the timezone rules.

    Method localtime

      `bool localtime(int time)`

    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

      See also Gettext.setlocale

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

      %k

        The hour (24-hour clock) as a decimal number (range 0 to 23); single digits are preceded by a blank. (See also `%H`.)

      %l

        The hour (12-hour clock) as a decimal number (range 1 to 12); single digits are preceded by a blank. (See also `%I`.)

      %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`.

    Method strptime

      `bool strptime(string(1..255) format, string(1..255) data)`

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

    Method unix_time

      `int unix_time()`

    Description

      Return the unix time corresponding to this time_t. If no time can be parsed from the structure -1 is returned.

    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 System.TM.zone`

    Description

      The timezone of this structure

  CLASS System.Time

    Description

      The current time as a structure containing a sec and a usec member.

    Method create

      `System.Time System.Time(int fast)`

    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.

    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.

  CLASS System.Timer

    Method create

      `System.Timer System.Timer(int|void fast)`

    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

      `float get()`

    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

      `float peek()`

    Description

      Return the time in seconds since the last time get was called.

  Module System.FSEvents

    Method describe_event_flag

      `string describe_event_flag(int mask)`

    Description

      describe the event flags associated with an event.

    Returns

      a string describing the flags set.

    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

    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.

      Method create

        `System.FSEvents.BlockingEventStream System.FSEvents.BlockingEventStream(array(string) paths, float latency, int|void since_when, int|void flags)`

      Inherit EventStream

        inherit .EventStream : EventStream

      Method read_event

        `mixed read_event(void|float timeout)`

      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

        `void add_path(string path)`

      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.EventStream System.FSEvents.EventStream(array(string) paths, float latency, int|void since_when, int|void flags)`

      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

        `void flush_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

        `void flush_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

        `int is_started()`

      Description

        Has start() been called?

      Constant kFSEventStreamCreateFlagFileEvents

        `constant System.FSEvents.EventStream.kFSEventStreamCreateFlagFileEvents`

      Description

        Available in MacOS X 10.7 and newer.

      Constant kFSEventStreamCreateFlagIgnoreSelf

        `constant System.FSEvents.EventStream.kFSEventStreamCreateFlagIgnoreSelf`

      Description

        Available in MacOS X 10.6 and newer.

      Constant kFSEventStreamCreateFlagNoDefer

        `constant System.FSEvents.EventStream.kFSEventStreamCreateFlagNoDefer`

      Constant kFSEventStreamCreateFlagNone

        `constant System.FSEvents.EventStream.kFSEventStreamCreateFlagNone`

      Constant kFSEventStreamCreateFlagWatchRoot

        `constant System.FSEvents.EventStream.kFSEventStreamCreateFlagWatchRoot`

      Constant kFSEventStreamEventFlagChangeOwner

        `constant System.FSEvents.EventStream.kFSEventStreamEventFlagChangeOwner`

      Description

        Available in MacOS X 10.7 and newer.

      Constant kFSEventStreamEventFlagEventIdsWrapped

        `constant System.FSEvents.EventStream.kFSEventStreamEventFlagEventIdsWrapped`

      Constant kFSEventStreamEventFlagFinderInfoMod

        `constant System.FSEvents.EventStream.kFSEventStreamEventFlagFinderInfoMod`

      Description

        Available in MacOS X 10.7 and newer.

      Constant kFSEventStreamEventFlagHistoryDone

        `constant System.FSEvents.EventStream.kFSEventStreamEventFlagHistoryDone`

      Constant kFSEventStreamEventFlagInodeMetaMod

        `constant System.FSEvents.EventStream.kFSEventStreamEventFlagInodeMetaMod`

      Description

        Available in MacOS X 10.7 and newer.

      Constant kFSEventStreamEventFlagIsDir

        `constant System.FSEvents.EventStream.kFSEventStreamEventFlagIsDir`

      Description

        Available in MacOS X 10.7 and newer.

      Constant kFSEventStreamEventFlagIsFile

        `constant System.FSEvents.EventStream.kFSEventStreamEventFlagIsFile`

      Description

        Available in MacOS X 10.7 and newer.

      Constant kFSEventStreamEventFlagIsSymlink

        `constant System.FSEvents.EventStream.kFSEventStreamEventFlagIsSymlink`

      Description

        Available in MacOS X 10.7 and newer.

      Constant kFSEventStreamEventFlagItemCreated

        `constant System.FSEvents.EventStream.kFSEventStreamEventFlagItemCreated`

      Description

        Available in MacOS X 10.7 and newer.

      Constant kFSEventStreamEventFlagItemModified

        `constant System.FSEvents.EventStream.kFSEventStreamEventFlagItemModified`

      Description

        Available in MacOS X 10.7 and newer.

      Constant kFSEventStreamEventFlagItemRemoved

        `constant System.FSEvents.EventStream.kFSEventStreamEventFlagItemRemoved`

      Description

        Available in MacOS X 10.7 and newer.

      Constant kFSEventStreamEventFlagKernelDropped

        `constant System.FSEvents.EventStream.kFSEventStreamEventFlagKernelDropped`

      Constant kFSEventStreamEventFlagMount

        `constant System.FSEvents.EventStream.kFSEventStreamEventFlagMount`

      Constant kFSEventStreamEventFlagMustScanSubDirs

        `constant System.FSEvents.EventStream.kFSEventStreamEventFlagMustScanSubDirs`

      Constant kFSEventStreamEventFlagNone

        `constant System.FSEvents.EventStream.kFSEventStreamEventFlagNone`

      Constant kFSEventStreamEventFlagRenamed

        `constant System.FSEvents.EventStream.kFSEventStreamEventFlagRenamed`

      Description

        Available in MacOS X 10.7 and newer.

      Constant kFSEventStreamEventFlagRootChanged

        `constant System.FSEvents.EventStream.kFSEventStreamEventFlagRootChanged`

      Constant kFSEventStreamEventFlagUnmount

        `constant System.FSEvents.EventStream.kFSEventStreamEventFlagUnmount`

      Constant kFSEventStreamEventFlagUserDropped

        `constant System.FSEvents.EventStream.kFSEventStreamEventFlagUserDropped`

      Constant kFSEventStreamEventFlagXattrMod

        `constant System.FSEvents.EventStream.kFSEventStreamEventFlagXattrMod`

      Description

        Available in MacOS X 10.7 and newer.

      Constant kFSEventStreamEventIdSinceNow

        `constant System.FSEvents.EventStream.kFSEventStreamEventIdSinceNow`

      Method set_callback

        `void set_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

        `void start()`

      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

        `void stop()`

      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

      `string describe_mask(int mask)`

    Description

      Turn an event mask into a human readable representation. This is used for debugging purpose.

    Method parse_event

      `array(string|int) parse_event(string data)`

    Description

      Parses one inotify_event struct from `data`.

    Returns

      Returns an array consisting of

      Array
      `int 0` | The watch descriptor returned by _Instance()->add_watch() when the watch for this file was added.
      `int 1` | An integer that describes the event that occured. See the inotify manpage for a list of possible events and their numerical identifiers.
      `int 2` | An integer cookie that can be used to group together different events that were triggered by moving a file from one location to another.
      `string 3` | 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.
      `int 4` | 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.

      Method add_watch

        `int add_watch(string filename, int mask, 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.

      Inherit _Instance

        inherit _Instance : _Instance

    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 inferface use System.Inotify.Instance.

      See also

        System.Inotify.Instance

      Method add_watch

        `int add_watch(string file, int mask)`

      Description

        Add a watch for a certain file or directory and specific events. Adding more than one watch for one file 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.

      Note

        Subdirectories are not watched. If you want to watch subdirectories as well, you need to add watches for them individually.

      See also

        rm_watch(), parse_event()

      Variable event_callback

        `private function(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 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

        `void poll()`

      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
        `int 1` | The watch descriptor that was triggered.
        `int 2` | The event that was triggerend (one of `IN_*`).
        `int 3` | An integer cookie used to identify grouped events.
        `string 4` | 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

        `int query_fd()`

      Returns

        Returns the file descriptor associated with this inotify instance.

      Method rm_watch

        `int rm_watch(int wd)`

      Description

        Remove a watch.

      Parameter `wd`

        The watch descriptor that was returned by add_watch().

      Method set_backend

        `void set_backend(Pike.Backend backend)`

      Description

        Set the backend used for callbacks.

      See also

        set_event_callback(), set_nonblocking(), poll()

      Method set_blocking

        `void set_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

        `void set_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

        `void set_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

        `void add_handle(NotificationHandle handle)`

      Method poll

        `NotificationHandle|int poll(void|float timeout)`

    CLASS System.Wnotify.NotificationHandle

      Method create

        `System.Wnotify.NotificationHandle System.Wnotify.NotificationHandle(string path, int watch_subtree, int filter)`

      Method get_error

        `int get_error()`

Module Thread

  Method `()

    `optional __deprecated__ Thread `()(mixed f, mixed ... args)`

  Description

    Create a new thread.

  Deprecated

    Replaced by predef::Thread.Thread.

  Method all_threads

    `array(Thread.Thread) all_threads()`

  Description

    This function returns an array with the thread ids of all threads.

  See also

    Thread()

  Method get_thread_quanta

    `int(0..) get_thread_quanta()`

  Returns

    Returns the current thread quanta in nanoseconds.

  See also

    set_thread_quanta(), gethrtime()

  Method set_thread_quanta

    `int(0..) set_thread_quanta(int(0..) ns)`

  Description

    Set the thread quanta.

  Parameter `ns`

    New thread quanta in nanoseconds. A value of zero (default) disables the thread quanta checks.

    When enabled MasterObject.thread_quanta_exceeded() will be called when a thread has spent more time than the quanta without allowing another thread to run.

  Note

    Setting a non-zero value that is too small to allow for MasterObject.thread_quanta_exceeded() to run is NOT a good idea.

  Returns

    Returns the previous thread quanta in nanoseconds.

  See also

    set_thread_quanta(), gethrtime()

  Method this_thread

    `Thread.Thread this_thread()`

  Description

    This function returns the object that identifies this thread.

  See also

    Thread()

  Method thread_set_concurrency

    `void thread_set_concurrency(int concurrency)`

  FIXME

    Document this function

  CLASS Thread.Condition

    Description

      Implementation of condition variables.

      Condition variables are used by threaded programs to wait for events happening in other threads.

    Note

      Condition variables are only available on systems with thread support. The Condition class is not simulated otherwise, since that can't be done accurately without continuations.

    See also

      Mutex

    Method broadcast

      `void broadcast()`

    Description

      broadcast() wakes up all threads currently waiting for this condition.

    See also

      signal()

    Method signal

      `void signal()`

    Description

      signal() wakes up one of the threads currently waiting for the condition.

    Note

      Sometimes more than one thread is woken up.

    See also

      broadcast()

    Method wait

      `void wait(Thread.MutexKey mutex_key)`
      `void wait(Thread.MutexKey mutex_key, int(0..)|float seconds)`
      `void wait(Thread.MutexKey mutex_key, int(0..) seconds, int(0..999999999) nanos)`

    Description

      Wait for condition.

      This function makes the current thread sleep until the condition variable is signalled or the timeout is reached.

    Parameter `mutex_key`

      A Thread.MutexKey object for a Thread.Mutex. It will be unlocked atomically before waiting for the signal and then relocked atomically when the signal is received or the timeout is reached.

    Parameter `seconds`

      Seconds to wait before the timeout is reached.

    Parameter `nanos`

      Nano (1/1000000000) seconds to wait before the timeout is reached. This value is added to the number of seconds specified by seconds.

      A timeout of zero seconds disables the timeout.

      The thread that sends the signal should have the mutex locked while sending it. Otherwise it's impossible to avoid races where signals are sent while the listener(s) haven't arrived to the wait calls yet.

    Note

      The support for timeouts was added in Pike 7.8.121, which was after the first public release of Pike 7.8.

    Note

      Note that the timeout is approximate (best effort), and may be exceeded if eg the mutex is busy after the timeout.

    Note

      In Pike 7.2 and earlier it was possible to call wait() without arguments. This possibility was removed in later versions since it unavoidably leads to programs with races and/or deadlocks.

    Note

      Note also that any threads waiting on the condition will be woken up when it gets destructed.

    See also

      Mutex->lock()

  CLASS Thread.Farm

    Description

      A thread farm.

    Method debug_status

      `string debug_status()`

    Description

      Get some statistics for the thread farm.

    Method run

      `Result run(function(:void) f, mixed ... args)`

    Description

      Register a job for the thread farm.

    Parameter `f`

      Function to call with @args to perform the job.

    Parameter `args`

      The parameters for f.

    Returns

      Returns a Result object for the job.

    Note

      In Pike 7.8 and earlier this function was broken and returned a Result object that wasn't connected to the job.

    See also

      run_async()

    Method run_async

      `void run_async(function(:void) f, mixed ... args)`

    Description

      Register a job for the thread farm where the return value from f is ignored.

    Parameter `f`

      Function to call with @args to perform the job.

    Parameter `args`

      The parameters for f.

    See also

      run()

    Method run_multiple

      `Result run_multiple(array(array(function(:void)|array)) fun_args)`

    Description

      Register multiple jobs.

    Parameter `fun_args`

      An array of arrays where the first element is a function to call, and the second is a corresponding array of arguments.

    Returns

      Returns a Result object with an array with one element for the result for each of the functions in fun_args.

    Note

      Do not modify the elements of fun_args before the result is available.

    Note

      If any of the functions in fun_args throws and error, all of the accululated results (if any) will be dropped from the result, and the first backtrace be provided.

    See also

      run_multiple_async()

    Method run_multiple_async

      `void run_multiple_async(array fun_args)`

    Description

      Register multiple jobs where the return values are to be ignored.

    Parameter `fun_args`

      An array of arrays where the first element is a function to call, and the second is a corresponding array of arguments.

    Note

      Do not modify the elements of fun_args before the result is available.

    See also

      run_multiple()

    Method set_max_num_threads

      `int set_max_num_threads(int(1..) to)`

    Description

      Set the maximum number of worker threads that the thread farm may have.

    Parameter `to`

      The new maximum number.

      If there are more worker threads than to, the function will wait until enough threads have finished, so that the total is to or less.

      The default maximum number of worker threads is `20`.

    CLASS Thread.Farm.Handler

      Description

        A worker thread.

      Method debug_status

        `string debug_status()`

      Description

        Get some statistics about the worker thread.

    CLASS Thread.Farm.Result

      Description

        An asynchronous result.

      Method `()

        `mixed res = Thread.Farm.Result()()`

      Description

        Wait for completion.

      Method provide

        `void provide(mixed what)`

      Description

        Register a completed result.

      Parameter `what`

        The result to register.

      Method provide_error

        `void provide_error(mixed what)`

      Description

        Register a failure.

      Parameter `what`

        The corresponding backtrace.

      Method result

        `mixed result()`

      Returns

        Returns the result if available, a backtrace on failure, and `0` (zero) otherwise.

      Method set_done_cb

        `void set_done_cb(function(:void) to)`

      Description

        Register a callback to be called when the result is available.

      Parameter `to`

        Callback to be called. The first argument to the callback will be the result or the failure backtrace, and the second `0` (zero) on success, and `1` on failure.

      Method status

        `int status()`

      Returns

        `1` | Returns `1` when the result is available.
        `0` | Returns `0` (zero) when the result hasn't arrived yet.
        `-1` | Returns negative on failure.

  CLASS Thread.Fifo

    Description

      Fifo implements a fixed length first-in, first-out queue. A fifo is a queue of values and is often used as a stream of data between two threads.

    See also

      Queue

    Method create

      `Thread.Fifo Thread.Fifo()`
      `Thread.Fifo Thread.Fifo(int size)`

    Description

      Create a fifo. If the optional size argument is present it sets how many values can be written to the fifo without blocking. The default size is 128.

    Inherit lock

      inherit Mutex : lock

    Inherit r_cond

      inherit Condition : r_cond

    Inherit w_cond

      inherit Condition : w_cond

    Method read

      `mixed read()`

    Description

      This function retrieves a value from the fifo. Values will be returned in the order they were written. If there are no values present in the fifo the current thread will sleep until some other thread writes one.

    See also

      try_read(), read_array(), write()

    Method read_array

      `array read_array()`

    Description

      This function returns all values in the fifo as an array. The values in the array will be in the order they were written. If there are no values present in the fifo the current thread will sleep until some other thread writes one.

    See also

      read(), try_read_array()

    Method size

      `int size()`

    Description

      This function returns the number of elements currently in the fifo.

    See also

      read(), write()

    Method try_read

      `mixed try_read()`

    Description

      This function retrieves a value from the fifo if there is any there. Values will be returned in the order they were written. If there are no values present in the fifo then UNDEFINED will be returned.

    See also

      read()

    Method try_read_array

      `array try_read_array()`

    Description

      This function returns all values in the fifo as an array but doesn't wait if there are no values there. The values in the array will be in the order they were written.

    See also

      read_array()

    Method try_write

      `int try_write(mixed value)`

    Description

      Append a value to the end of the fifo. If there is no more room in the fifo then zero will be returned, otherwise the number of items in the fifo after the write is returned.

    See also

      read()

    Method write

      `int write(mixed value)`

    Description

      Append a value to the end of the fifo. If there is no more room in the fifo the current thread will sleep until space is available. The number of items in the queue after the write is returned.

    See also

      read()

  CLASS Thread.Local

    Description

      Thread local variable storage.

      This class allows you to have variables which are separate for each thread that uses it. It has two methods: get() and set(). A value stored in an instance of Local can only be retrieved by that same thread.

    Note

      This class is simulated when Pike is compiled without thread support, so it's always available.

    Method get

      `mixed get()`

    Description

      Get the thread local value.

      This returns the value prevoiusly stored in the Local object by the set() method by this thread.

    See also

      set()

    Method set

      `mixed set(mixed value)`

    Description

      Set the thread local value.

      This sets the value returned by the get method.

      Calling this method does not affect the value returned by get() when it's called by another thread (ie multiple values can be stored at the same time, but only one value per thread).

    Returns

      This function returns its argument.

    Note

      Note that the value set can only be retreived by the same thread.

    See also

      get()

  CLASS Thread.Mutex

    Description

      Mutex is a class that implements mutual exclusion locks. Mutex locks are used to prevent multiple threads from simultaneously execute sections of code which access or change shared data. The basic operations for a mutex is locking and unlocking. If a thread attempts to lock an already locked mutex the thread will sleep until the mutex is unlocked.

    Note

      This class is simulated when Pike is compiled without thread support, so it's always available.

      In POSIX threads, mutex locks can only be unlocked by the same thread that locked them. In Pike any thread can unlock a locked mutex.

    Method current_locking_key

      `Thread.MutexKey current_locking_key()`

    Description

      This mutex method returns the key object currently governing the lock on this mutex. 0 is returned if the mutex isn't locked.

    See also

      Thread()

    Method current_locking_thread

      `Thread.Thread current_locking_thread()`

    Description

      This mutex method returns the object that identifies the thread that has locked the mutex. 0 is returned if the mutex isn't locked.

    See also

      Thread()

    Method lock

      `MutexKey lock()`
      `MutexKey lock(int type)`

    Description

      This function attempts to lock the mutex. If the mutex is already locked by a different thread the current thread will sleep until the mutex is unlocked. The value returned is the 'key' to the lock. When the key is destructed or has no more references the mutex will automatically be unlocked.

      The type argument specifies what lock() should do if the mutex is already locked by this thread:

      `0` | Throw an error.
      `1` | Sleep until the mutex is unlocked. Useful if some other thread will unlock it.
      `2` | Return zero. This allows recursion within a locked region of code, but in conjunction with other locks it easily leads to unspecified locking order and therefore a risk for deadlocks.

    Note

      If the mutex is destructed while it's locked or while threads are waiting on it, it will continue to exist internally until the last thread has stopped waiting and the last MutexKey has disappeared, but further calls to the functions in this class will fail as is usual for destructed objects.

    Note

      Pike 7.4 and earlier destructed any outstanding lock when the mutex was destructed, but threads waiting in lock still got functioning locks as discussed above. This is inconsistent no matter how you look at it, so it was changed in 7.6. The old behavior is retained in compatibility mode for applications that explicitly destruct mutexes to unlock them.

    See also

      trylock()

    Method trylock

      `MutexKey trylock()`
      `MutexKey trylock(int type)`

    Description

      This function performs the same operation as lock(), but if the mutex is already locked, it will return zero instead of sleeping until it's unlocked.

    See also

      lock()

  CLASS Thread.MutexKey

    Description

      Objects of this class are returned by Mutex()->lock() and Mutex()->trylock(). They are also passed as arguments to Condition()->wait().

      As long as they are held, the corresponding mutex will be locked.

      The corresponding mutex will be unlocked when the object is destructed (eg by not having any references left).

    See also

      Mutex, Condition

  CLASS Thread.Queue

    Description

      Queue implements a queue, or a pipeline. The main difference between Queue and Fifo is that Queue will never block in write(), only allocate more memory.

    FIXME

      Ought to be made API-compatible with ADT.Queue.

    See also

      Fifo, ADT.Queue

    Inherit lock

      inherit Mutex : lock

    Inherit r_cond

      inherit Condition : r_cond

    Method peek_array

      `array peek_array()`

    Description

      Returns a snapshot of all the values in the queue, in the order they were written. The values are still left in the queue, so if other threads are reading from it, the returned value should be considered stale already on return.

    Method read

      `mixed read()`

    Description

      This function retrieves a value from the queue. Values will be returned in the order they were written. If there are no values present in the queue the current thread will sleep until some other thread writes one.

    See also

      try_read(), write()

    Method read_array

      `array read_array()`

    Description

      This function returns all values in the queue as an array. The values in the array will be in the order they were written. If there are no values present in the queue the current thread will sleep until some other thread writes one.

    See also

      read(), try_read_array()

    Method size

      `int size()`

    Description

      This function returns the number of elements currently in the queue.

    See also

      read(), write()

    Method try_read

      `mixed try_read()`

    Description

      This function retrieves a value from the queue if there is any there. Values will be returned in the order they were written. If there are no values present in the fifo then UNDEFINED will be returned.

    See also

      write()

    Method try_read_array

      `array try_read_array()`

    Description

      This function returns all values in the queue as an array but doesn't wait if there are no values there. The values in the array will be in the order they were written.

    See also

      read_array()

    Method write

      `int write(mixed value)`

    Description

      This function puts a value last in the queue. If the queue is too small to hold the value it will be expanded to make room. The number of items in the queue after the write is returned.

    See also

      read()

  CLASS Thread.Thread

    Method _sprintf

      `string sprintf(string format, ... Thread.Thread arg ... )`

    Description

      Returns a string identifying the thread.

    Method backtrace

      `array(mixed) backtrace()`

    Description

      Returns the current call stack for the thread.

    Returns

      The result has the same format as for predef::backtrace().

    See also

      predef::backtrace()

    Method create

      `Thread.Thread Thread.Thread(function(mixed ... :mixed|void) f, mixed ... args)`

    Description

      This function creates a new thread which will run simultaneously to the rest of the program. The new thread will call the function f with the arguments args. When f returns the thread will cease to exist.

      All Pike functions are 'thread safe' meaning that running a function at the same time from different threads will not corrupt any internal data in the Pike process.

    Returns

      The returned value will be the same as the return value of this_thread() for the new thread.

    Note

      This function is only available on systems with POSIX or UNIX or WIN32 threads support.

    See also

      Mutex, Condition, this_thread()

    Method id_number

      `protected int id_number()`

    Description

      Returns an id number identifying the thread.

    Note

      This function was added in Pike 7.2.204.

    Method interrupt

      `void interrupt()`
      `void interrupt(string msg)`

    Description

      Interrupt the thread with the message msg.

    FIXME

      The argument msg is currently ignored.

    Note

      Interrupts are asynchronous, and are currently not queued.

    Method kill

      `void kill()`

    Description

      Interrupt the thread, and terminate it.

    Note

      Interrupts are asynchronous, and are currently not queued.

    Method status

      `int status()`

    Description

      Returns the status of the thread.

    Returns

      `Thread.THREAD_NOT_STARTED`
      `Thread.THREAD_RUNNING`
      `Thread.THREAD_EXITED`
      `Thread.THREAD_ABORTED`

    Method wait

      `mixed wait()`

    Description

      Waits for the thread to complete, and then returns the value returned from the thread function.

    Throws

      Rethrows the error thrown by the thread if it exited by throwing an error.

Module Tools

  CLASS Tools.PV

    Description

      Display a image on the screen. Requires GTK.

    Typedef PVImage

      `typedef Standards.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.Image get_as_image(PVImage i)`

    Description

      Return the current image as a Image object, with the alpha combining done.

    Inherit Window

      inherit GTK.Window : Window

    Method save

      `void save(string filename, string|void format)`

    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

      `void scale(float factor)`

    Description

      Scale the image before display with the specified factor.

    Method set_alpha_colors

      `void set_alpha_colors(Image.Color.Color c1, Image.Color.Color|void c2)`

    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

      `void set_alpha_mode(AlphaMode m)`

    Description

      Set the alpha combining mode. m is one of Squares, Solid, None and AlphaOnly.

    Method set_image

      `void set_image(PVImage i)`

    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.

      Method create

        `Tools.AutoDoc.AutoDocError Tools.AutoDoc.AutoDocError(SourcePosition position, string part, string message)`

      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`

    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

        `string magic(string s, int quote)`

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

      Constant EOF

        `constant string Tools.AutoDoc.PikeParser.EOF`

      Description

        The end of file marker.

      Constant WITH_NL

        `constant int Tools.AutoDoc.PikeParser.WITH_NL`

      Description

        Newline indicator flag value.

      Method create

        `Tools.AutoDoc.PikeParser Tools.AutoDoc.PikeParser(string|void s, string|SourcePosition|void _filename, int|void line, .Flags|void flags)`

      Variable currentPosition

        `SourcePosition Tools.AutoDoc.PikeParser.currentPosition`

      Description

        The current position in the source.

      Method eat

        `string eat(multiset(string)|string token)`

      Description

        Consume one token, error if not (one of) the expected in token.

      Method eatIdentifier

        `string eatIdentifier(void|int allowScopePrefix)`

      Description

        Expect an identifier.

      Note

        Also `::ident`, `scope::ident`.

      Note

        This function also converts old-style getters and setters into new-style.

      Method eatLiteral

        `string eatLiteral()`

      Description

        Expect a literal constant.

      See also

        parseLiteral()

      Method getReadDocComments

        `int getReadDocComments()`

      Returns

        Returns the number of documentation comments that have been returned by readToken().

      Inherit PikeObjects

        protected inherit .PikeObjects : PikeObjects

      Method literalType

        `Type literalType(string literal)`

      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

        `string lookAhead(int offset, int|void with_newlines)`

      Description

        Peek offset tokens ahead, skipping newlines, unless with_newlines is set.

      See also

        peekToken()

      Method parseArgList

        `array parseArgList(int|void allowLiterals)`

      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

      `ArrayType parseArray()`

    Description

      Parse an array type.

    Method parseDecl

      `PikeObject|array(PikeObject) parseDecl(mapping|void args)`

    Description

      Parse the next Pike declaration from the token stream.

    Note

      parseDecl() reads ONLY THE HEAD, NOT the `";"` or `"{" .. "}"` !!!

    Method parseFunction

      `FunctionType parseFunction()`

    Description

      Parse a function type.

    Method parseIdents

      `string|void parseIdents()`

    Description

      Parse a '.'-separated identitifer string.

    Note

      Also parses stuff preceded by `"scope::"` or `"::"`

    Method parseInt

      `IntType parseInt()`

    Description

      Parse an integer type.

    Method parseLiteral

      `void|string parseLiteral()`

    Description

      Parse the next literal constant (if any) from the token stream.

    Method parseMapping

      `MappingType parseMapping()`

    Description

      Parse a mapping type.

    Method parseModifiers

      `array(string) parseModifiers()`

    Description

      Parse a set of modifiers from the token stream.

    Method parseMultiset

      `MultisetType parseMultiset()`

    Description

      Parse a multiset type.

    Method parseOrType

      `Type parseOrType()`

    Description

      Parse a union type.

    Method parseString

      `StringType parseString()`

    Description

      Parse a string type.

    Method peekToken

      `string peekToken(int|void with_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

      `string readToken(int|void with_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

      `void setTokens(array(string) t, array(int) p)`

    Method skip

      `void skip(multiset(string)|string tokens)`

    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

      `void skipBlock()`

    Description

      Skip passed a matched pair of parenthesis, brackets or braces.

    Method skipNewlines

      `void skipNewlines()`

    Description

      Skip past any newlines.

    Method skipUntil

      `void skipUntil(multiset(string)|string tokens)`

    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(string s, int line)`

    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.

    Method copy

      `SourcePosition copy()`

    Returns

      Returns a copy of the current object.

    Method create

      `Tools.AutoDoc.SourcePosition Tools.AutoDoc.SourcePosition(string filename, int firstline, int|void lastline)`

    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 xml

      `string xml(Flags|void flags)`

    Returns

      Returns a string with an XML-fragment describing the source position.

  Module Tools.AutoDoc.DocParser

    Constant EOF

      `constant Tools.AutoDoc.DocParser.EOF`

    Description

      End of file marker.

    Inherit PikeObjects

      inherit .PikeObjects : PikeObjects

    Variable keywordtype

      `mapping(string:DocTokenType) Tools.AutoDoc.DocParser.keywordtype`

    Description

      The DocTokenTypes for the documentation @-keywords.

    Method splitDocBlock

      `array(array(Token)) splitDocBlock(string block, SourcePosition position)`

    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

        `string getDoc(string context)`

      Returns

        Returns the documentation corresponding to the context as an XML string.

      Note

        getMetaData() must be called before this function.

      Method getMetaData

        `MetaData getMetaData()`

      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.

      Method create

        `Tools.AutoDoc.DocParser.Parse Tools.AutoDoc.DocParser.Parse(string|array(Token) s, SourcePosition|void sp, .Flags|void flags)`

      Description

        Parse a documentation string s.

      Method doc

        `string doc(string context)`

      Returns

        Returns the documentation corresponding to the context as an XML string.

      Note

        metadata() must be called before this function.

      Inherit DocParserClass

        inherit DocParserClass : DocParserClass

      Method metadata

        `MetaData metadata()`

      Returns

        Returns the MetaData for the documentation string.

  Module Tools.AutoDoc.PikeExtractor

    Method extractClass

      `Class extractClass(string s, void|string filename, void|string className, void|.Flags flags)`

    Description

      Extract documentation for a Pike class (aka program).

    See also

      extractNamespace(), extractModule()

    Method extractModule

      `Module extractModule(string s, void|string filename, void|string moduleName, void|.Flags flags)`

    Description

      Extract documentation for a Pike module.

    See also

      extractNamespace(), extractClass()

    Method extractNamespace

      `NameSpace extractNamespace(string s, void|string filename, void|string namespaceName, void|.Flags flags)`

    Description

      Extract documentation for a Pike namespace.

    See also

      extractModule(), extractClass()

    Inherit DocParser

      protected inherit .DocParser : DocParser

  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.

    Variable EmptyDoc

      `protected Documentation Tools.AutoDoc.PikeObjects.EmptyDoc`

    Description

      The empty Documentation.

    Inherit "module.pmod"

      protected inherit "module.pmod" : "module.pmod"

    Inherit Tree

      protected inherit Parser.XML.Tree : Tree

    CLASS Tools.AutoDoc.PikeObjects.ArrayType

      Description

        The class for representing array types.

      See also

        Type

      Method create

        `Tools.AutoDoc.PikeObjects.ArrayType Tools.AutoDoc.PikeObjects.ArrayType()`

      Inherit Type

        inherit Type : Type

      Variable valuetype

        `Type Tools.AutoDoc.PikeObjects.ArrayType.valuetype`

      Description

        The Type of the array elements.

    CLASS Tools.AutoDoc.PikeObjects.AttributeType

      Description

        The class for representing attributed types.

      See also

        Type

      Variable attribute

        `string Tools.AutoDoc.PikeObjects.AttributeType.attribute`

      Description

        The name of the attribute.

      Method create

        `Tools.AutoDoc.PikeObjects.AttributeType Tools.AutoDoc.PikeObjects.AttributeType()`

      Inherit Type

        inherit Type : Type

      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.

    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

        `constant string 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

        `constant string Tools.AutoDoc.PikeObjects.Class.objtype`

    CLASS Tools.AutoDoc.PikeObjects.Constant

      Description

        Represents a named constant.

      Inherit PikeObject

        inherit PikeObject : PikeObject

      Constant objtype

        `constant string 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

        `constant string 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.

      Method create

        `Tools.AutoDoc.PikeObjects.DocGroup Tools.AutoDoc.PikeObjects.DocGroup(array(PikeObject) objs, Documentation doc)`

      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 xml

        `string xml(.Flags|void flags)`

      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

      Method create

        `Tools.AutoDoc.PikeObjects.Documentation Tools.AutoDoc.PikeObjects.Documentation(string|void text, string|void xml, SourcePosition|void position)`

      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`

    CLASS Tools.AutoDoc.PikeObjects.Enum

      Description

        The enum container.

      Method addChild

        `void addChild(DocGroup c)`

      Description

        Adds c to the set of children.

      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.

      Inherit PikeObject

        inherit PikeObject : PikeObject

      Constant objtype

        `constant string Tools.AutoDoc.PikeObjects.Enum.objtype`

    CLASS Tools.AutoDoc.PikeObjects.EnumConstant

      Description

        The values inside `enum Foo { ... }`

      Inherit PikeObject

        inherit PikeObject : PikeObject

      Constant objtype

        `constant string Tools.AutoDoc.PikeObjects.EnumConstant.objtype`

    CLASS Tools.AutoDoc.PikeObjects.FloatType

      Description

        The class for representing the float type.

      See also

        Type

      Method create

        `Tools.AutoDoc.PikeObjects.FloatType Tools.AutoDoc.PikeObjects.FloatType()`

      Inherit Type

        inherit Type : Type

    CLASS Tools.AutoDoc.PikeObjects.FunctionType

      Description

        The class for representing function types.

      See also

        Type

      Variable argtypes

        `array(Type) Tools.AutoDoc.PikeObjects.FunctionType.argtypes`

      Description

        An array with types for the arguments to the function.

      Method create

        `Tools.AutoDoc.PikeObjects.FunctionType Tools.AutoDoc.PikeObjects.FunctionType()`

      Inherit Type

        inherit Type : Type

      Variable returntype

        `Type Tools.AutoDoc.PikeObjects.FunctionType.returntype`

      Description

        The type for the return value of the function.

    CLASS Tools.AutoDoc.PikeObjects.Import

      Description

        Representation of an import.

      Inherit Inherit

        inherit Inherit : Inherit

      Constant objtype

        `constant string Tools.AutoDoc.PikeObjects.Import.objtype`

    CLASS Tools.AutoDoc.PikeObjects.Inherit

      Description

        Representation of an inherit.

      Variable classname

        `string Tools.AutoDoc.PikeObjects.Inherit.classname`

      Description

        Name of the class that is inherited.

      Inherit PikeObject

        inherit PikeObject : PikeObject

      Constant objtype

        `constant string Tools.AutoDoc.PikeObjects.Inherit.objtype`

    CLASS Tools.AutoDoc.PikeObjects.IntType

      Description

        The class for representing integer types.

      See also

        Type

      Method create

        `Tools.AutoDoc.PikeObjects.IntType Tools.AutoDoc.PikeObjects.IntType()`

      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.

    CLASS Tools.AutoDoc.PikeObjects.MappingType

      Description

        The class for representing mapping types.

      See also

        Type

      Method create

        `Tools.AutoDoc.PikeObjects.MappingType Tools.AutoDoc.PikeObjects.MappingType()`

      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.

      Inherit Type

        inherit Type : Type

    CLASS Tools.AutoDoc.PikeObjects.Method

      Description

        Represents a function.

      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.

      Inherit PikeObject

        inherit PikeObject : PikeObject

      Constant objtype

        `constant string Tools.AutoDoc.PikeObjects.Method.objtype`

      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

      Method create

        `Tools.AutoDoc.PikeObjects.MixedType Tools.AutoDoc.PikeObjects.MixedType()`

      Inherit Type

        inherit Type : Type

    CLASS Tools.AutoDoc.PikeObjects.Modifier

      Description

        A modifier range, e.g.:

        final protected { ... <<declarations>> ... }

    Inherit _Class_or_Module

      inherit _Class_or_Module : _Class_or_Module

    Constant objtype

      `constant string 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

      `constant string Tools.AutoDoc.PikeObjects.Module.objtype`

  CLASS Tools.AutoDoc.PikeObjects.MultisetType

    Description

      The class for representing multiset types.

    See also

      Type

    Method create

      `Tools.AutoDoc.PikeObjects.MultisetType Tools.AutoDoc.PikeObjects.MultisetType()`

    Variable indextype

      `Type Tools.AutoDoc.PikeObjects.MultisetType.indextype`

    Description

      The type for the indices of the multiset.

    Inherit Type

      inherit Type : Type

  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

      `constant string Tools.AutoDoc.PikeObjects.NameSpace.objtype`

  CLASS Tools.AutoDoc.PikeObjects.ObjectType

    Description

      The class for representing object types.

    See also

      Type

    Variable classname

      `string Tools.AutoDoc.PikeObjects.ObjectType.classname`

    Description

      The name of the class for the object.

    Method create

      `Tools.AutoDoc.PikeObjects.ObjectType Tools.AutoDoc.PikeObjects.ObjectType()`

    Inherit Type

      inherit Type : Type

  CLASS Tools.AutoDoc.PikeObjects.OrType

    Description

      The class for representing union types.

    See also

      Type

    Method create

      `Tools.AutoDoc.PikeObjects.OrType Tools.AutoDoc.PikeObjects.OrType()`

    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.

  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

    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.

    Constant objtype

      `constant string Tools.AutoDoc.PikeObjects.PikeObject.objtype`

    Description

      The object type identifier.

    Variable position

      `SourcePosition Tools.AutoDoc.PikeObjects.PikeObject.position`

    Description

      The source position where the entity was found.

    Method print

      `string print()`

    Returns

      Returns a string with a Pike syntax representation of the entity.

    Variable squeezedInDoc

      `Documentation Tools.AutoDoc.PikeObjects.PikeObject.squeezedInDoc`

    Method xml

      `string xml(.Flags|void flags)`

    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

    Variable classname

      `string Tools.AutoDoc.PikeObjects.ProgramType.classname`

    Description

      The name of the class (if any).

    Method create

      `Tools.AutoDoc.PikeObjects.ProgramType Tools.AutoDoc.PikeObjects.ProgramType()`

    Inherit Type

      inherit Type : Type

  CLASS Tools.AutoDoc.PikeObjects.StringType

    Description

      The class for representing string types.

    See also

      Type

    Method create

      `Tools.AutoDoc.PikeObjects.StringType Tools.AutoDoc.PikeObjects.StringType()`

    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.

  CLASS Tools.AutoDoc.PikeObjects.Type

    Description

      The base class for representing types.

    Method create

      `Tools.AutoDoc.PikeObjects.Type Tools.AutoDoc.PikeObjects.Type(string name)`

    Variable name

      `string Tools.AutoDoc.PikeObjects.Type.name`

    Method print

      `string print()`

    Returns

      Returns a string with a Pike-syntax representation of the type.

    Method xml

      `string xml(.Flags|void flags)`

    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

    Method create

      `Tools.AutoDoc.PikeObjects.TypeType Tools.AutoDoc.PikeObjects.TypeType()`

    Inherit Type

      inherit Type : Type

    Variable subtype

      `Type Tools.AutoDoc.PikeObjects.TypeType.subtype`

    Description

      The subtype of the type.

  CLASS Tools.AutoDoc.PikeObjects.Typedef

    Description

      Represents a typedef.

    Inherit PikeObject

      inherit PikeObject : PikeObject

    Constant objtype

      `constant string Tools.AutoDoc.PikeObjects.Typedef.objtype`

    Variable type

      `Type Tools.AutoDoc.PikeObjects.Typedef.type`

    Description

      Typedef Type.

  CLASS Tools.AutoDoc.PikeObjects.VarargsType

    Description

      The class for representing varargs types.

    See also

      Type

    Method create

      `Tools.AutoDoc.PikeObjects.VarargsType Tools.AutoDoc.PikeObjects.VarargsType(Type t)`

    Inherit Type

      inherit Type : Type

    Variable type

      `Type Tools.AutoDoc.PikeObjects.VarargsType.type`

    Description

      The type that is varargs.

  CLASS Tools.AutoDoc.PikeObjects.Variable

    Description

      Represents a variable.

    Inherit PikeObject

      inherit PikeObject : PikeObject

    Constant objtype

      `constant string 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

    Method create

      `Tools.AutoDoc.PikeObjects.VoidType Tools.AutoDoc.PikeObjects.VoidType()`

    Inherit Type

      inherit Type : Type

  CLASS Tools.AutoDoc.PikeObjects.ZeroType

    Description

      The class for representing the zero type.

    See also

      Type

    Method create

      `Tools.AutoDoc.PikeObjects.ZeroType Tools.AutoDoc.PikeObjects.ZeroType()`

    Inherit Type

      inherit Type : Type

  CLASS Tools.AutoDoc.PikeObjects._Class_or_Module

    Description

      Base class for representing classes, modules and namespaces.

    See also

      Class, Module, NameSpace, AutoDoc, Modifier

    Method AddChild

      `void AddChild(_Class_or_Module c)`

    Description

      Adds c to the set of children.

    Method AddGroup

      `void AddGroup(DocGroup d)`

    Description

      Adds d to the set of docGroups.

    Method AddInherit

      `void AddInherit(PikeObject p)`

    Description

      Adds p to the set of inherits.

    Variable children

      `array(_Class_or_Module) Tools.AutoDoc.PikeObjects._Class_or_Module.children`

    Description

      Entities that are children to this entity.

    Method containsDoc

      `int containsDoc()`

    Returns

      Returns `1` if there is any documentation at all for 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>

    Method findChild

      `PikeObject findChild(string name)`

    Returns

      Returns the first child with the name name if any.

    Method findObject

      `DocGroup findObject(string name)`

    Returns

      Returns the first DocGroup that documents an entity with the name name if any.

    Inherit PikeObject

      inherit PikeObject : PikeObject

    Variable inherits

      `array(Inherit|Import) Tools.AutoDoc.PikeObjects._Class_or_Module.inherits`

    Description

      Inherits and Imports that affect the symbol lookup for the entity.

Module Tools.AutoDoc.ProcessXML

  Method extractXML

    `string extractXML(string filename, int|void pikeMode, string|void type, string|void name, array(string)|void parentModules, void|.Flags flags)`

  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

    `void handleAppears(SimpleNode root, .Flags|void flags)`

  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.

  Inherit "module.pmod"

    protected inherit "module.pmod" : "module.pmod"

  Inherit Tree

    protected inherit Parser.XML.Tree : Tree

  Method mergeTrees

    `void mergeTrees(SimpleNode dest, SimpleNode source)`

  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

    `string moveImages(string docXMLFile, string imageSourceDir, string imageDestDir, int|void quiet)`

  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

    `void postProcess(SimpleNode root, string|void logfile, .Flags|void flags)`

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

    Description

      A symbol lookup scope.

    Method addImplicitInherits

      `void addImplicitInherits(string|void fallback_namespace)`

    Description

      This function improves the symbol resolution by adding implicit inherits for modules in compatibility namespaces.

Module Tools.Hilfe

  Method format_hr_time

    `string format_hr_time(int i)`

  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

      `string doc(string what, string with)`

    Description

      A more elaborate documentation of the command. This should be less than 68 characters per line.

    Method exec

      `void exec(Evaluator e, string line, 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

      `string help(string what)`

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

    Description

      This class implements the actual Hilfe interpreter. It is accessible as ___Hilfe from Hilfe expressions.

    Method add_buffer

      `void add_buffer(string s)`

    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

      `void add_input_hook(function(:void)|object new)`

    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

      `void add_input_line(string s)`

    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

      `void add_writer(object|function(string:int(0..)) new)`

    Description

      Adds another output function.

    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.

    Method evaluate

      `void evaluate(string a, bool show_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.

    Variable functions

      `mapping(string:function(:void)) Tools.Hilfe.Evaluator.functions`

    Description

      The locally defined functions (name:value).

    Method hilfe_compile

      `object hilfe_compile(string f, void|string new_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.

    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;

    Method parse_expression

      `string parse_expression(Expression expr)`

    Description

      Parses a Pike expression. Returns 0 if everything went well, or a string with an error message otherwise.

    Method print_version

      `void print_version()`

    Description

      Displays the current version of Hilfe.

    Variable programs

      `mapping(string:program) Tools.Hilfe.Evaluator.programs`

    Description

      The locally defined programs (name:value).

    Method remove_input_hook

      `void remove_input_hook(function(:void)|object old)`

    Description

      Removes a function from the input hook.

    See also

      add_input_hook

    Method remove_writer

      `void remove_writer(object|function(:void) old)`

    Description

      Removes an output function.

    Method reset_evaluator

      `void reset_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.

    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 evaulation time (int). If the evaluated expression didn't return anything (e.g. a for loop) then 0 will be given as the result string.

    Method safe_write

      `int safe_write(array(string)|string in, mixed ... args)`

    Description

      An output method that shouldn't crash.

    Variable state

      `ParserState Tools.Hilfe.Evaluator.state`

    Description

      Keeps the state, e.g. multiline input in process etc.

    Method std_reswrite

      `void std_reswrite(function(:void) w, string sres, int num, mixed res)`

    Description

      The standard reswrite function.

    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.

  CLASS Tools.Hilfe.Expression

    Description

      Represents a Pike expression

    Method _sizeof

      `int sizeof( Tools.Hilfe.Expression arg )`

    Description

      The number of non-whitespace tokens in the expression.

    Method `[]

      `string 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 check_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

      `string code()`

    Description

      Returns the expression verbatim.

    Method create

      `Tools.Hilfe.Expression Tools.Hilfe.Expression(array(string) t)`

    Parameter `t`

      An array of Pike tokens.

    Method depth

      `int depth(int f)`

    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(string token, int(0..)|void pos)`

    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

      `bool in_sscanf(int f)`

    Description

      Returns 1 if the current position is within a sscanf expression.

    Method is_block

      `bool is_block(int pos)`

    Description

      Is there a block starting at pos?

  CLASS Tools.Hilfe.GenericAsyncHilfe

    Method create

      `Tools.Hilfe.GenericAsyncHilfe Tools.Hilfe.GenericAsyncHilfe(Stdio.File infile, Stdio.File outfile)`

    Variable infile
    Variable outfile

      `Stdio.File Tools.Hilfe.GenericAsyncHilfe.infile`
      `Stdio.File Tools.Hilfe.GenericAsyncHilfe.outfile`

    Inherit Evaluator

      inherit Evaluator : Evaluator

  CLASS Tools.Hilfe.GenericHilfe

    Method create

      `Tools.Hilfe.GenericHilfe Tools.Hilfe.GenericHilfe(Stdio.FILE in, Stdio.File out)`

    Inherit Evaluator

      inherit Evaluator : Evaluator

  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 : 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 outputted in the other. The parser object is accessible as ___Hilfe->state from Hilfe expressions.

    Method datap

      `int datap()`

    Description

      Returns true if there is any waiting expression that can be fetched with read.

    Method feed

      `void feed(array(string) tokens)`

    Description

      Feed more tokens into the state.

    Method finishedp

      `bool finishedp()`

    Description

      Are we in the middle of an expression. Used e.g. for changing the Hilfe prompt when entering multiline expressions.

    Method flush

      `void flush()`

    Description

      Clear the current state.

    Method push_string

      `array(string) push_string(string line)`

    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

      `void show_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

      `string status()`

    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.

    Method create

      `Tools.Hilfe.StdinHilfe Tools.Hilfe.StdinHilfe(void|array(string) init)`

    Description

      Any hilfe statements given in the init array will be executed once .hilferc has been executed.

    Inherit Evaluator

      inherit Evaluator : Evaluator

    Variable readline

      `Stdio.Readline Tools.Hilfe.StdinHilfe.readline`

    Description

      The readline object,

    Method save_history

      `void save_history()`

    Description

      Saves the user input history, if possible, when called.

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

    `string make_absolute_path(string path, string|void cwd)`

  CLASS Tools.Install.ProgressBar

    Description

      A class keeping some methods and state to conveniently render ASCII progress bars to stdout.

    Method create

      `Tools.Install.ProgressBar Tools.Install.ProgressBar(string name, int cur, int max, float|void phase_base, float|void phase_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

      `void set_current(int _cur)`

    Description

      Change the amount of progress without updating on stdout.

    Method set_name

      `void set_name(string _name)`

    Description

      Change the name of the progress bar without updating on stdout.

    Method set_phase

      `void set_phase(float _phase_base, float _phase_size)`

    Method update

      `int update(int increment)`

    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

    Method absolute_path

      `string absolute_path(string path)`

    Method edit

      `string edit(mixed ... args)`

    Method edit_directory

      `string edit_directory(mixed ... args)`

    Method edit_filename

      `string edit_filename(mixed ... args)`

    Inherit Readline

      inherit Stdio.Readline : Readline

    Method set_cwd

      `void set_cwd(string _cwd)`

    Method trap_signal

      `void trap_signal(int n)`

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

      `void add(string what, 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

      `string get_latest_pike()`

    Description

      Return the latest copyright holder of Pike.

    Method get_text

      `string get_text()`

    Description

      Returns the copyrights as a string, suitable for saving as a file.

  Module Tools.Legal.License

    Method get_text

      `string get_text()`

    Description

      Returns all the licenses as a string, suitable for saving as a file.

Module Tools.MasterHelp

  Description

    This module contains usage strings for the master()->_main().

  Method do_help

    `string do_help(string|int what)`

  Description

    Select a suitable help message.

  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.

Module Tools.Monger

  CLASS Tools.Monger.MongerDeveloper

    Method add_new_version

      `int add_new_version(string module_name, string version, string changes, string license)`

    Method delete_dependency

      `int delete_dependency(string module_name, string version, string dependency, string min_version, string max_version)`

    Method get_dependencies

      `array get_dependencies(string module_name, string version)`

    Method set_auth

      `void set_auth(string _username, string _password)`

    Description

      set the username and password for accessing the remote repository.

    Method set_default_directory

      `void set_default_directory()`

    Description

      sets the default directory for working and storing configurations ($HOME/.monger)

    Method set_default_repository

      `void set_default_repository()`

    Description

      sets the default repository location (modules.gotpike.org)

    Method set_dependency

      `int set_dependency(string module_name, string version, string dependency, string min_version, string max_version, bool required)`

    Method set_directory

      `void set_directory(string _directory)`

    Description

      sets the monger directory to use for working and storing configurations.

    Method set_module_source

      `int set_module_source(string module_name, string version, string filename)`

    Method set_repository

      `void set_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

      `int set_version_active(string module_name, string version, int active)`

    Method update_version

      `int update_version(string module_name, string version, string|void changes, string|void license)`

    Method user_change_email

      `int user_change_email(string|void _username, string _newemail)`

    Method user_change_password

      `int user_change_password(string|void _username, string _newpassword)`

Module Tools.PEM

  Description

    Support for parsing PEM-style messages.

  Deprecated

    Replaced by Standards.PEM.

  CLASS Tools.PEM.EncapsulatedMsg

    Description

      Represents an encapsulated message.

    Variable body

      `string Tools.PEM.EncapsulatedMsg.body`

    Description

      Contains the raw message body. Access through decoded_body to get the decoded message.

    Variable boundary

      `string Tools.PEM.EncapsulatedMsg.boundary`

    Description

      Contains the raw boundary string. Access through get_boundary to get the decoded boundary string.

    Method canonical_body

      `string canonical_body()`

    Description

      Returns the raw body with all newlines as `"\r\n"`.

    Method decoded_body

      `string decoded_body()`

    Description

      Returns decoded base64 encoded message body

    Method get_boundary

      `string get_boundary()`

    Description

      Returns decoded boundary string.

    Variable headers

      `mapping(string:string) Tools.PEM.EncapsulatedMsg.headers`

    Description

      Contains the message headers, or `0`.

    Method to_string

      `string to_string()`

    Description

      Returns the message body and headers in the standard message format.

  CLASS Tools.PEM.Msg

    Description

      Disassembles PGP and PEM style messages with parts separated by "-----BEGIN FOO-----" and "-----END FOO-----".

    Method create

      `Tools.PEM.Msg Tools.PEM.Msg(string s)`

    Description

      Creates a decoded PEM message

    Parameter `s`

      A string containing a PEM encoded message to be decoded.

    Variable final_text

      `string Tools.PEM.Msg.final_text`

    Description

      Contains any text following the PEM message.

    Variable initial_text

      `string Tools.PEM.Msg.initial_text`

    Description

      Contains any text preceeding the PEM message.

    Variable parts

      `mapping(string:EncapsulatedMsg) Tools.PEM.Msg.parts`

    Description

      The decoded PEM message, as an array of EncapsulatedMsg objects indexed by message name, such as "CERTIFICATE".

  CLASS Tools.PEM.RFC934

    Description

      Represents an RFC934 text message.

    Method create

      `Tools.PEM.RFC934 Tools.PEM.RFC934(string data)`

    Description

      Decodes an RFC 934 encoded message.

    Variable encapsulated

      `array(EncapsulatedMsg) Tools.PEM.RFC934.encapsulated`

    Variable final_boundary

      `string Tools.PEM.RFC934.final_boundary`

    Variable final_text

      `string Tools.PEM.RFC934.final_text`

    Method get_final_boundary

      `string get_final_boundary()`

    Variable initial_text

      `string Tools.PEM.RFC934.initial_text`

    Method to_string

      `string to_string()`

Module Tools.Shoot

  CLASS Tools.Shoot.Test

    Constant name

      `constant string Tools.Shoot.Test.name`

    Description

      The name of the test.

    Method perform

      `int perform()`

    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.

Module Tools.Standalone

  CLASS Tools.Standalone.autodoc_to_html

    Description

      AutoDoc XML to HTML converter.

    See also

      tree_split

    Method image_prefix

      `string image_prefix()`

    Description

      Path to where in the destination filesystem the images are.

    Variable lay

      `mapping Tools.Standalone.autodoc_to_html.lay`

    Description

      Layout template headers and trailers.

    Method parse_text

      `string parse_text(Node n, void|String.Buffer ret)`

    Description

      Typically called with a <group/> node or a sub-node that is a container.

  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.

      Variable fds

        `array(Stdio.Fd) Tools.Standalone.forkd.ForkStream.fds`

      Description

        The remote file descriptors received so far in order.

      Inherit File

        inherit Stdio.File : File

  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.

    Method get_version

      `string get_version()`

    Description

      Attempt to get the version for the Pike source tree.

    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.

  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

  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.

    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.

    Inherit process_files

      inherit Toole.Standalone.process_files : process_files

    Method main

      `int(0..) main(int argc, 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.

    Variable overwrite

      `bool Tools.Standalone.process_files.overwrite`

    Description

      0 to make backups, 1 to overwrite (default)

    Method process

      `string process(string input, 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

      `bool process_file(string path, 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(string path, 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

    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.

Module Tools.Testsuite

  Method log_msg

    `void log_msg(string msg, 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

    `void log_msg_cont(string msg, 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

    `void log_status(string msg, 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

    `void log_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

    `void report_result(int succeeded, int failed, void|int skipped)`

  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.

Module Tools.X509

  Description

    Functions to generate and validate RFC2459 style X.509 v3 certificates.

  Deprecated

    Replaced by Standards.X509.

  Constant CERT_BAD_SIGNATURE

    `constant int Tools.X509.CERT_BAD_SIGNATURE`

  Constant CERT_CHAIN_BROKEN

    `constant int Tools.X509.CERT_CHAIN_BROKEN`

  Constant CERT_INVALID

    `constant int Tools.X509.CERT_INVALID`

  Constant CERT_ROOT_UNTRUSTED

    `constant int Tools.X509.CERT_ROOT_UNTRUSTED`

  Constant CERT_TOO_NEW

    `constant int Tools.X509.CERT_TOO_NEW`

  Constant CERT_TOO_OLD

    `constant int Tools.X509.CERT_TOO_OLD`

  Constant CERT_UNAUTHORIZED_CA

    `constant int Tools.X509.CERT_UNAUTHORIZED_CA`

  Method decode_certificate

    `__deprecated__ TBSCertificate decode_certificate(string|object cert)`

  Method dsa_sign_key

    `__deprecated__ string dsa_sign_key(Sequence issuer, Crypto.DSA dsa, Sequence subject, string public_key, int serial, int ttl, array|void extensions)`

  Parameter `issuer`

    Distinguished name for the issuer.

  Parameter `rsa`

    RSA parameters for the issuer.

  Parameter `subject`

    Distinguished name for the subject.

  Parameter `public_key`

    DER-encoded integer. See Standards.PKCS.DSA.public_key().

  Parameter `serial`

    Serial number for this key and issuer.

  Parameter `ttl`

    Validity time in seconds for this signature to be valid.

  Parameter `extensions`

    Set of extensions.

  Returns

    Returns a DER-encoded certificate.

  Method make_selfsigned_dsa_certificate

    `__deprecated__ string make_selfsigned_dsa_certificate(Crypto.DSA dsa, int ttl, array name, array|void extensions)`

  Method make_selfsigned_rsa_certificate

    `__deprecated__ string make_selfsigned_rsa_certificate(Crypto.RSA rsa, int ttl, array name, array|void extensions)`

  Method make_tbs

    `__deprecated__ Sequence make_tbs(object issuer, object algorithm, object subject, object keyinfo, object serial, int ttl, array extensions)`

  Method make_time

    `__deprecated__ UTC make_time(int t)`

  Description

    Creates a Standards.ASN1.Types.UTC object from the posix time t.

  Method make_verifier

    `__deprecated__ Verifier make_verifier(Object _keyinfo)`

  Method parse_time

    `__deprecated__ mapping(string:int) parse_time(UTC asn1)`

  Description

    Returns a mapping similar to that returned by gmtime

  Returns

    `"year" : int`
    `"mon" : int`
    `"mday" : int`
    `"hour" : int`
    `"min" : int`
    `"sec" : int`

  Method rsa_sign_digest

    `__deprecated__ string rsa_sign_digest(Crypto.RSA rsa, object digest_id, string digest)`

  Method rsa_sign_key

    `__deprecated__ string rsa_sign_key(Sequence issuer, Crypto.RSA rsa, Sequence subject, string public_key, int serial, int ttl, array|void extensions)`

  Parameter `issuer`

    Distinguished name for the issuer.

  Parameter `rsa`

    RSA parameters for the issuer.

  Parameter `subject`

    Distinguished name for the issuer.

  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.

  Method rsa_verify_digest

    `__deprecated__ bool rsa_verify_digest(Crypto.RSA rsa, object digest_id, string digest, string s)`

  Method time_compare

    `__deprecated__ int(-1..1) time_compare(mapping(string:int) t1, mapping(string:int) t2)`

  Description

    Comparision function between two "date" mappings of the kind that parse_time returns.

  Method verify_certificate

    `__deprecated__ TBSCertificate verify_certificate(string s, mapping authorities)`

  Description

    Decodes a certificate, checks the signature. Returns the TBSCertificate structure, or 0 if decoding or verification failes.

    Authorities is a mapping from (DER-encoded) names to a verifiers.

  Note

    This function allows self-signed certificates, and it doesn't check that names or extensions make sense.

  Method verify_certificate_chain

    `__deprecated__ mapping verify_certificate_chain(array(string) cert_chain, mapping authorities, int|void require_trust)`

  Description

    Decodes a certificate chain, checks the signatures. Verifies that the chain is unbroken, and that all certificates are in effect (time-wise.)

    Returns a mapping with the following contents, depending on the verification of the certificate chain:

    `"error_code" : int` | Error describing type of verification failure, if verification failed. May be one of the following: CERT_TOO_NEW, CERT_TOO_OLD, CERT_ROOT_UNTRUSTED, CERT_BAD_SIGNATURE, CERT_INVALID, CERT_UNAUTHORIZED_CA or CERT_CHAIN_BROKEN
    `"error_cert" : 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" : string` | Standards.ASN1.Sequence of the authority RDN that verified the chain.
    `"cn" : string` | Standards.ASN1.Sequence of the common name RDN of the leaf certificate.

  Parameter `cert_chain`

    An array of certificates, with the relative-root last. Each certificate should be a DER-encoded certificate.

  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.

    See Standards.PKCS.Certificate.get_dn_string for converting the RDN to an X500 style string.

  CLASS Tools.X509.TBSCertificate

    Variable algorithm

      `Sequence Tools.X509.TBSCertificate.algorithm`

    Variable der

      `string Tools.X509.TBSCertificate.der`

    Variable extensions

      `object Tools.X509.TBSCertificate.extensions`

    Note

      optional

    Method init

      `this_program init(Object asn1)`

    Variable issuer

      `Sequence Tools.X509.TBSCertificate.issuer`

    Variable issuer_id

      `BitString Tools.X509.TBSCertificate.issuer_id`

    Note

      optional

    Variable not_after

      `mapping Tools.X509.TBSCertificate.not_after`

    Variable not_before

      `mapping Tools.X509.TBSCertificate.not_before`

    Variable public_key

      `Verifier Tools.X509.TBSCertificate.public_key`

    Variable serial

      `Gmp.mpz Tools.X509.TBSCertificate.serial`

    Variable subject

      `Sequence Tools.X509.TBSCertificate.subject`

    Variable subject_id

      `BitString Tools.X509.TBSCertificate.subject_id`

    Note

      optional

    Variable version

      `int Tools.X509.TBSCertificate.version`

  CLASS Tools.X509.rsa_verifier

    Inherit Verifier

      inherit Verifier : Verifier

    Method init

      `this_program init(string key)`

    Method verify

      `bool verify(Sequence algorithm, string msg, string signature)`

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

    `string|array `()(string|array(string) commands, string|array(string) data, void|int suppress)`

Module Unicode

  Method is_rtlchar

    `int is_rtlchar(int c)`

  Description

    Returns `1` if the character is a RTL character or indicator, otherwise `0`.

  Method is_rtlstring

    `int is_rtlstring(string s)`

  Description

    Returns `1` if the string contains RTL characters or RTL indicators, otherwise `0`.

  Method is_wordchar

    `int is_wordchar(int c)`

  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

    `string normalize(string data, string method)`

  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(string input)`

  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(string input)`

  Description

    A less wasteful equivalent of `<font face='courier'>split_words`(<font face='courier'>normalize(<font face='courier'>input, "NFKD")).

  Constant version

    `constant Unicode.version`

  Description

    Contains the version of the current Unicode database as a string, e.g. `"5.0.0"`.

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 represents 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) && something->is_val_true) ...

  and

      if (objectp(something) && 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 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) && 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.

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

    `constant int Val.Boolean.is_val_boolean`

  Description

    Nonzero recognition constant that can be used to recognize both Val.true and Val.false.

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

    `constant int Val.False.is_val_false`

  Description

    Nonzero recognition constant.

CLASS Val.Null

  Description

    Type for the Val.null object. Do not create more instances of this - use Val.null instead.

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

    `constant int Val.True.is_val_true`

  Description

    Nonzero recognition constant.

Module Web

  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.

    Method _sizeof

      `int sizeof( Web.RDF arg )`

    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_program add_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

      `string decode_n_triple_string(string in)`

    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

      `bool dereify(Resource r)`

    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

      `string encode_n_triple_string(string in)`

    Description

      Encodes a string for use as tring in N-triples serialization.

    Method find_statements

      `array(array(Resource)) find_statements(Resource|int(0..0) subj, Resource|int(0..0) pred, Resource|int(0..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
      `Resource 0` | The subject of the statement
      `Resource 1` | The predicate of the statement
      `Resource 2` | The object of the statement

    Method get_3_tuples

      `string get_3_tuples()`

    Description

      Returns a 3-tuple serialization of all the statements in the RDF set.

    Method get_n_triples

      `string get_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 get_reify(Resource subj, Resource pred, Resource obj)`

    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 get_resource(string uri)`

    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

      `string get_xml(void|int no_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

      `bool has_statement(Resource subj, Resource pred, Resource obj)`

    Description

      Returns 1 if the RDF domain contains the relation {subj, pred, obj}, otherwise 0.

    Method is_object

      `bool is_object(Resource r)`

    Description

      Returns `1` if resource r is used as an object, otherwise `0`.

    Method is_predicate

      `bool is_predicate(Resource r)`

    Description

      Returns `1` if resource r is used as a predicate, otherwise `0`.

    Method is_subject

      `bool is_subject(Resource r)`

    Description

      Returns `1` if resource r is used as a subject, otherwise `0`.

    Method make_resource

      `URIResource make_resource(string uri)`

    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

      `int parse_n_triples(string in)`

    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.RDF parse_xml(string|Parser.XML.NSTree.NSNode in, void|string base)`

    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.

    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.

    Constant rdf_ns

      `constant string Web.RDF.rdf_ns`

    Description

      The RDF XML namespace.

    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 reify

      `Resource reify(Resource subj, Resource pred, Resource obj)`

    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

      `Resource reify_low(Resource subj, Resource pred, Resource obj)`

    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

      `bool remove_statement(Resource subj, Resource pred, Resource obj)`

    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.

      Method create

        `Web.RDF.LiteralResource Web.RDF.LiteralResource(string literal)`

      Description

        The resource will be identified by literal.

      Variable datatype

        `string Web.RDF.LiteralResource.datatype`

      Description

        Used to contain rdf:datatype value.

      Method get_literal

        `string get_literal()`

      Description

        Returns the literal string.

      Method get_xml

        `string get_xml()`

      Description

        Returns the literal as an XML string.

      Inherit Resource

        inherit Resource : Resource

    CLASS Web.RDF.RDFResource

      Description

        Resource used for RDF-technical reasons like reification.

      Method create

        `Web.RDF.RDFResource Web.RDF.RDFResource(string rdf_id)`

      Description

        The resource will be identified by the identifier rdf_id

      Method get_qname

        `string get_qname(void|string ns)`

      Description

        Returns the qualifying name.

      Inherit URIResource

        inherit URIResource : URIResource

    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

        `string get_3_tuple_name()`

      Description

        Returns the nodes' 3-tuple serialized ID.

      Method get_n_triple_name

        `string get_n_triple_name()`

      Description

        Returns the nodes' N-triple serialized ID.

    CLASS Web.RDF.URIResource

      Description

        Resource identified by URI.

      Method create

        `Web.RDF.URIResource Web.RDF.URIResource(string uri)`

      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

        `string get_namespace()`

      Description

        Returns the namespace this resource URI references to.

      Method get_qname

        `string get_qname(void|string ns)`

      Description

        Returns the qualifying name, or zero.

      Method get_uri

        `string get_uri()`

      Description

        Returns the URI the resource references to.

      Inherit Resource

        inherit Resource : Resource

  CLASS Web.RDFS

    Description

      RDF Schema.

    Method add_Class

      `void add_Class(Resource c)`

    Method add_subClassOf

      `void add_subClassOf(Resource a, Resource b)`

    Method add_subPropertyOf

      `void add_subPropertyOf(Resource a, Resource b)`

    Inherit RDF

      inherit .RDF : RDF

    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`

    Constant rdfs_ns

      `constant string Web.RDFS.rdfs_ns`

    Description

      The RDF Schema XML-namespace.

    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.

    Constant USER_AGENT

      `constant string 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.

      Constant ACCESS_TOKEN_PARAM_NAME

        `protected constant string 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

      Constant API_URI

        `constant int Web.Api.Api.API_URI`

      Description

        The URI to the remote API

      Constant AuthClass

        `protected constant Web.Api.Api.AuthClass`

      Description

        Authentication class to use

      Typedef Callback

        `typedef function(mapping, Protocols.HTTP.Query:void) Web.Api.Api.Callback`

      Description

        Typedef for the async callback method signature.

      Constant DECODE_UTF8

        `protected constant int Web.Api.Api.DECODE_UTF8`

      Description

        If `1` Standards.JSON.decode_utf8() will be used when JSON data is decoded.

      Typedef ParamsArg

        `typedef mapping|Web.Auth.Params Web.Api.Api.ParamsArg`

      Description

        Typedef for a parameter argument

      Variable _auth

        `protected Web.Auth.OAuth2.Client Web.Api.Api._auth`

      Description

        Authorization object.

      See also

        Web.Auth.OAuth2

      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

      Method call

        `mixed call(string api_method, void|ParamsArg params, void|string http_method, void|string data, void|Callback cb)`

      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 create

        `Web.Api.Api Web.Api.Api(string client_id, string client_secret, void|string redirect_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

        `protected mapping default_params()`

      Description

        Return default params

      Method delete

        `mixed delete(string api_method, void|ParamsArg params, void|Callback cb)`

      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

        `mixed get(string api_method, void|ParamsArg params, void|Callback cb)`

      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

        `protected string get_encoding(mapping h)`

      Description

        Returns the encoding from a response

      Parameter `h`

        The headers mapping from a HTTP respose

      Method get_uri

        `protected string get_uri(string method)`

      Description

        Convenience method for getting the URI to a specific API method

      Parameter `method`

      Variable http_request_timeout

        `int(0..) Web.Api.Api.http_request_timeout`

      Description

        Request timeout in seconds. Only affects async queries.

      Method parse_canonical_url

        `mapping(string:string|mapping) parse_canonical_url(string url)`

      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

      `mixed patch(string api_method, void|ParamsArg params, void|Callback cb)`

    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

      `mixed post(string api_method, void|ParamsArg params, void|string data, void|Callback cb)`

    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

      `mixed put(string api_method, void|ParamsArg params, void|Callback cb)`

    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

      `protected string unescape_forward_slashes(string s)`

    Description

      Unescapes escaped forward slashes in a JSON string

    Variable utf8_decode

      `bool Web.Api.Api.utf8_decode`

    Description

      If `1` Standards.JSON.decode_utf8() will be used when JSON data is decoded.

    CLASS Web.Api.Api.Method

      Description

        Internal class ment to be inherited by implementing Api's classes that corresponds to a given API endpoint.

      Constant METHOD_PATH

        `protected constant int Web.Api.Api.Method.METHOD_PATH`

      Description

        API method location within the API

        https://api.instagram.com/v1/media/search ............................^^^^^^^

    Method _delete

      `protected mixed _delete(string s, void|ParamsArg p, void|Callback cb)`

    Description

      Internal convenience method

    Method _get

      `protected mixed _get(string s, void|ParamsArg p, void|Callback cb)`

    Description

      Internal convenience method

    Method _patch

      `protected mixed _patch(string s, void|ParamsArg p, void|Callback cb)`

    Description

      Internal convenience method

    Method _post

      `protected mixed _post(string s, void|ParamsArg p, void|string data, void|Callback cb)`

    Description

      Internal convenience method

    Method _put

      `protected mixed _put(string s, void|ParamsArg p, void|Callback cb)`

    Description

      Internal convenience method

    Method create

      `Web.Api.Api.Method Web.Api.Api.Method()`

    Description

      Hidden constructor. This class can not be instantiated directly

Module Web.Api.Facebook

  Method `()

    `protected this_program `()(string client_id, string client_secret, void|string redirect_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

    Constant API_URI

      `constant string 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

      `mapping delete(string path, void|ParamsArg params, void|Callback cb)`

    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

      `mapping get(string path, void|ParamsArg params, void|Callback cb)`

    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

    Inherit parent

      inherit Web.Api.Api : parent

    Method post

      `mapping post(string path, void|ParamsArg params, void|string data, void|Callback cb)`

    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

      `mapping put(string path, void|ParamsArg params, void|Callback cb)`

    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

      Method delete

        `mixed delete(string s, void|ParamsArg p, void|Callback cb)`

      Description

        Internal convenience method

      Method get

        `mixed get(string s, void|ParamsArg p, void|Callback cb)`

      Description

        Internal convenience method

      Inherit Method

        inherit Web.Api.Api.Method : Method

      Method post

        `mixed post(string s, void|ParamsArg p, void|string data, void|Callback cb)`

      Description

        Internal convenience method

      Method put

        `mixed put(string s, void|ParamsArg p, void|Callback cb)`

      Description

        Internal convenience method

Module Web.Api.Github

  Method `()

    `protected this_program `()(string client_id, string client_secret, void|string redirect_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

    Constant API_URI

      `constant string 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

      `mapping delete(string path, void|ParamsArg params, void|Callback cb)`

    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

      `mapping get(string path, void|ParamsArg params, void|Callback cb)`

    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

    Inherit parent

      inherit Web.Api.Api : parent

    Method post

      `mapping post(string path, void|ParamsArg params, void|string data, void|Callback cb)`

    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

      `mapping put(string path, void|ParamsArg params, void|Callback cb)`

    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

      Method delete

        `mixed delete(string s, void|ParamsArg p, void|Callback cb)`

      Description

        Internal convenience method

      Method get

        `mixed get(string s, void|ParamsArg p, void|Callback cb)`

      Description

        Internal convenience method

      Inherit Method

        inherit Web.Api.Api.Method : Method

      Method post

        `mixed post(string s, void|ParamsArg p, void|string data, void|Callback cb)`

      Description

        Internal convenience method

      Method put

        `mixed put(string s, void|ParamsArg p, void|Callback cb)`

      Description

        Internal convenience method

Module Web.Api.Google

  CLASS Web.Api.Google.Api

    Description

      Internal class ment to be inherited by other Google API's

    Inherit parent

      inherit Web.Api.Api : parent

    CLASS Web.Api.Google.Api.Method

      Method _delete

        `protected mixed _delete(string s, void|ParamsArg p, void|Callback cb)`

      Description

        Internal convenience method

      Method _get

        `protected mixed _get(string s, void|ParamsArg p, void|Callback cb)`

      Description

        Internal convenience method

      Method _post

        `protected mixed _post(string s, void|ParamsArg p, void|Callback cb)`

      Description

        Internal convenience method

      Inherit Method

        inherit Web.Api.Api.Method : Method

  Module Web.Api.Google.Analytics

    Method `()

      `protected this_program `()(string client_id, string client_secret, void|string redirect_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

      Constant API_URI

        `protected constant string Web.Api.Google.Analytics.V3.API_URI`

      Description

        API base URI.

      Variable _core
      Variable _realtime
      Variable _management

        `protected Core Web.Api.Google.Analytics.V3._core`
        `protected RealTime Web.Api.Google.Analytics.V3._realtime`
        `protected Management 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

      Inherit parent

        inherit Web.Api.Google.Api : parent

      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

        Method get

          `mixed get(mapping params, void|Callback cb)`

        Description

          Get data from the core api

        Parameter `params`
        Parameter `cb`

        Inherit Method

          inherit Method : Method

      CLASS Web.Api.Google.Analytics.V3.Management

        Description

          Interface to the Google Analytics managment API

        Method account_summaries

          `mixed account_summaries(void|ParamsArg params, void|Callback cb)`

        Description

          Get account summaries

        Parameter `params`
        Parameter `cb`

        Inherit Method

          inherit Method : Method

      CLASS Web.Api.Google.Analytics.V3.RealTime

        Description

          Interface to the Google Analytics realtime API

        Method get

          `mixed get(mapping params, void|Callback cb)`

        Description

          Get data from the realtime api

        Parameter `params`
        Parameter `cb`

        Inherit Method

          inherit Method : Method

  Module Web.Api.Google.Plus

    Method `()

      `protected this_program `()(string client_id, string client_secret, void|string redirect_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

      Constant API_URI

        `protected constant string Web.Api.Google.Plus.V1.API_URI`

      Description

        API base URI.

      Variable _people
      Variable _activities

        `private People Web.Api.Google.Plus.V1._people`
        `private Activities 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

      Inherit Api

        inherit Web.Api.Google.Api : Api

      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

        Method get

          `mapping get(void|string user_id, void|Callback cb)`

        Description

          Get info ablut a person.

        Parameter `user_id`

          If empty the currently authenticated user will be fetched.

        Parameter `cb`

          Callback for async request

        Inherit Method

          inherit Method : Method

        Method list

          `mapping list(void|string user_id, void|string collection, void|ParamsArg params, void|Callback cb)`

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

    `protected this_program `()(string client_id, string client_secret, void|string redirect_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.

    Constant API_URI

      `protected constant string Web.Api.Instagram.V1.API_URI`

    Description

      The URI to the Instagram API

    Variable _any

      `private Any Web.Api.Instagram.V1._any`

    Description

      Singleton Any object. Will be instantiated first time requested.

    Variable _comments

      `private Comments Web.Api.Instagram.V1._comments`

    Description

      Singleton Comments object. Will be instantiated first time requested.

    Variable _likes

      `private Likes Web.Api.Instagram.V1._likes`

    Description

      Singleton Likes object. Will be instantiated first time requested.

    Variable _locations

      `private Locations Web.Api.Instagram.V1._locations`

    Description

      Singleton Locations object. Will be instantiated first time requested.

    Variable _media

      `private Media Web.Api.Instagram.V1._media`

    Description

      Singleton Media object. Will be instantiated first time requested.

    Variable _tags

      `private Tags Web.Api.Instagram.V1._tags`

    Description

      Singleton Tags object. Will be instantiated first time requested.

    Variable _users

      `private Users 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

    Method delete

      `mapping delete(string path, void|ParamsArg params, void|Callback cb)`

    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

      `mapping get(string path, void|ParamsArg params, void|Callback cb)`

    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

    Inherit parent

      inherit Web.Api.Api : parent

    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

    Method post

      `mapping post(string path, void|ParamsArg params, string data, void|Callback cb)`

    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`
    Parameter `cb`

      Callback for async requests

    Method put

      `mapping put(string path, void|ParamsArg params, void|Callback cb)`

    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

    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

    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.

      Method delete

        `mixed delete(string s, void|ParamsArg p, void|Callback cb)`

      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

        `mixed get(string s, void|ParamsArg p, void|Callback cb)`

      Description

        GET data

      Parameter `s`

        The path to the Instagram API to query

      Parameter `p`

        Parameters to the query

      Parameter `cb`

        Async callback

      Inherit Method

        inherit Method : Method

      Method post

        `mixed post(string s, void|ParamsArg p, string data, void|Callback cb)`

      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

        `mixed put(string s, void|ParamsArg p, void|Callback cb)`

      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.

      Method add

        `mapping add(string media_id, string comment, void|Callback cb)`

      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

      Inherit Method

        inherit Method : Method

      Method list

        `mapping list(string media_id, void|Callback cb)`

      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

        `mapping remove(string media_id, string comment_id, void|Callback cb)`

      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.

      Method add

        `mapping add(string media_id, void|Callback cb)`

      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`

      Inherit Method

        inherit Method : Method

      Method list

        `mapping list(string media_id, void|Callback cb)`

      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

        `mapping remove(string media_id, void|Callback cb)`

      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

        `mapping location(string location_id, void|Callback cb)`

      Description

        Get information about a location.

      See also

        http://instagram.com/developer/endpoints/locations/#get_locations

      Parameter `location_id`
      Parameter `cb`

      Method recent_media

        `mapping recent_media(string location_id, void|ParamsArg params, void|Callback cb)`

      Description

        Get a list of recent media objects from a given location. May return a mix of both image and video types.

      See also

        http://instagram.com/developer/endpoints/locations/#get_locations_media_recent

      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

        `mapping search(ParamsArg params, void|Callback cb)`

      Description

        Search for a location by geographic coordinate.

      See also

        http://instagram.com/developer/endpoints/locations/#get_locations_search

      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

        `mapping item(string media_id, void|Callback cb)`

      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

        `mapping popular(void|Callback cb)`

      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

        `mapping search(void|ParamsArg params, void|Callback cb)`

      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.

      Method _delete

        `protected mixed _delete(string s, void|ParamsArg p, void|Callback cb)`

      Description

        Internal convenience method

      Method _get

        `protected mixed _get(string s, void|ParamsArg p, void|Callback cb)`

      Description

        Internal convenience method

      Method _post

        `protected mixed _post(string s, void|ParamsArg p, string data, void|Callback cb)`

      Description

        Internal convenience method

      Method _put

        `protected mixed _put(string s, void|ParamsArg p, void|Callback cb)`

      Description

        Internal convenience method

      Inherit Method

        inherit Web.Api.Api.Method : 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

        `mapping recent(string tag_name, void|ParamsArg params, void|Callback cb)`

      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.

      See also

        http://instagram.com/developer/endpoints/tags/#get_tags_media_recent

      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

        `mapping search(string tag_name, Callback cb)`

      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

        `mapping tag(string tag_name, void|Callback cb)`

      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

      Method feed

        `mapping feed(void|ParamsArg params, void|Callback cb)`

      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

        `mapping followed_by(string|void user_id, void|Callback cb)`

      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

        `mapping follows(void|string user_id, void|Callback cb)`

      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

      Inherit Method

        inherit Method : Method

      Method liked

        `mapping liked(void|ParamsArg params, void|Callback cb)`

      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

        `mapping recent(void|string uid, void|ParamsArg params, void|Callback cb)`

      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

        `mapping relationship(string user_id, void|Callback cb)`

      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

        `mapping relationship_change(string user_id, string action, void|Callback cb)`

      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" and "deny"
      Parameter `cb`

        Callback function if in async mode

      Method requested_by

        `mapping requested_by(void|Callback cb)`

      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

        `mapping search(string query, void|int count, void|Callback cb)`

      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

        `mapping user(void|string uid, void|Callback cb)`

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

    `protected this_program `()(string client_id, string client_secret, void|string redirect_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

    Constant API_URI

      `constant string 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

      `protected mapping default_params()`

    Description

      Default parameters that goes with every call

    Method delete

      `mapping delete(string path, void|ParamsArg params, void|Callback cb)`

    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

      `mapping get(string path, void|ParamsArg params, void|Callback cb)`

    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

    Inherit parent

      inherit Web.Api.Api : parent

    Method post

      `mapping post(string path, void|ParamsArg params, void|string data, void|Callback cb)`

    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

      `mapping put(string path, void|ParamsArg params, void|Callback cb)`

    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

      Method delete

        `mixed delete(string s, void|ParamsArg p, void|Callback cb)`

      Description

        Internal convenience method

      Method get

        `mixed get(string s, void|ParamsArg p, void|Callback cb)`

      Description

        Internal convenience method

      Inherit Method

        inherit Web.Api.Api.Method : Method

      Method post

        `mixed post(string s, void|ParamsArg p, void|string data, void|Callback cb)`

      Description

        Internal convenience method

      Method put

        `mixed put(string s, void|ParamsArg p, void|Callback cb)`

      Description

        Internal convenience method

Module Web.Api.Twitter

  Method `()

    `protected this_program `()(string client_id, string client_secret, void|string redirect_uri, void|string|array(string)|multiset(string) scope)`

  Description

    Instantiates the default Twitter 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.Twitter.V1_1

    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

      `protected mapping default_params()`

    Description

      Default parameters that goes with every call

    Method delete

      `mapping delete(string path, void|ParamsArg params, void|Callback cb)`

    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

      `mapping get(string path, void|ParamsArg params, void|Callback cb)`

    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

    Inherit parent

      inherit Web.Api.Api : parent

    Method post

      `mapping post(string path, void|ParamsArg params, void|string data, void|Callback cb)`

    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

      `mapping put(string path, void|ParamsArg params, void|Callback cb)`

    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

      Method delete

        `mixed delete(string s, void|ParamsArg p, void|Callback cb)`

      Description

        Internal convenience method

      Method get

        `mixed get(string s, void|ParamsArg p, void|Callback cb)`

      Description

        Internal convenience method

      Inherit Method

        inherit Web.Api.Api.Method : Method

      Method post

        `mixed post(string s, void|ParamsArg p, void|string data, void|Callback cb)`

      Description

        Internal convenience method

      Method put

        `mixed put(string s, void|ParamsArg p, void|Callback cb)`

      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 values if (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't if (!auth->is_authenticated()) { // Try to renew the access token of it's renewable if (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 process if (argc == 1) { // Get the uri to the authentication page string 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;

    // Mac if (Process.run(({ "which", "open" }))->exitcode == 0) { open_app = "open"; } // Linux else if (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 bar string resp = Stdio.Readline()->read(); mapping p = Web.Auth.query_to_mapping(Standards.URI(resp)->query); string code;

    // This is if the service is OAuth1 if (p->oauth_token) { auth->set_authentication(p->oauth_token); code = p->oauth_verifier; } // OAuth2 else { 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

  `mapping query_to_mapping(string query)`

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

CLASS Web.Auth.Github

  Description

    This class is used to OAuth2 authenticate against Github

  Inherit Client

    inherit .OAuth2.Client : Client

CLASS Web.Auth.Instagram

  Description

    This class is used to OAuth2 authenticate agains Instagram

  Constant OAUTH_AUTH_URI

    `constant string Web.Auth.Instagram.OAUTH_AUTH_URI`

  Description

    Instagram authorization URI

  Constant OAUTH_TOKEN_URI

    `constant string Web.Auth.Instagram.OAUTH_TOKEN_URI`

  Description

    Instagram request access token URI

  Variable _scope

    `protected string Web.Auth.Instagram._scope`

  Description

    Default scope

  Inherit Client

    inherit .OAuth2.Client : Client

  Variable valid_scopes

    `protected multiset(string) Web.Auth.Instagram.valid_scopes`

  Description

    Valid Instagram scopes

CLASS Web.Auth.Linkedin

  Description

    This class is used to OAuth2 authenticate against LinkedIn

  Constant DEFAULT_SCOPE

    `protected constant Web.Auth.Linkedin.DEFAULT_SCOPE`

  Description

    Default scope to use if none is set explicitly

  Constant STATE

    `protected constant int Web.Auth.Linkedin.STATE`

  Description

    Adds the `state` parameter to the request which will have the value of a random string

  Inherit Client

    inherit .OAuth2.Client : Client

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

  Method _sprintf

    `string sprintf(string format, ... Web.Auth.Param arg ... )`

  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.Param Web.Auth.Param(string name, mixed value)`

  Description

    Creates a new instance of Param

  Parameter `name`
  Parameter `value`

  Method get_name

    `string get_name()`

  Description

    Getter for the parameter name

  Method get_value

    `string get_value()`

  Description

    Getter for the parameter value

  Method low_set_value

    `private void low_set_value(string v)`

  Description

    Makes sure v to set as value is in UTF-8 encoding

  Parameter `v`

  Variable name

    `protected string Web.Auth.Param.name`

  Description

    The name of the parameter

  Method name_value

    `string name_value()`

  Description

    Returns the name and value as querystring key/value pair

  Method name_value_encoded

    `string name_value_encoded()`

  Description

    Same as name_value() except this URL encodes the value.

  Method set_name

    `void set_name(string name)`

  Description

    Setter for the parameter name

  Parameter `name`

  Method set_value

    `void set_value(mixed value)`

  Description

    Setter for the parameter value

  Parameter `value`

  Variable value

    `protected string Web.Auth.Param.value`

  Description

    The value of the parameter

CLASS Web.Auth.Params

  Description

    Parameter collection class

  See also

    Param

  Method _indices

    `array(string) indices( Web.Auth.Params arg )`

  Description

    Parameter keys

  Method _sprintf

    `string sprintf(string format, ... Web.Auth.Params arg ... )`

  Description

    String format method

  Parameter `t`

  Method _values

    `array(string) values( Web.Auth.Params arg )`

  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 res = Web.Auth.Params()[ key ]`

  Description

    Index lookup

  Parameter `key`

    The name of a Paramerter to find.

  Method add_mapping

    `this_program add_mapping(mapping value)`

  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_program clone()`

  Description

    Clone the current instance

  Method create

    `Web.Auth.Params Web.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

  Variable params

    `protected array(Param) Web.Auth.Params.params`

  Description

    The parameters.

  Method sign

    `string sign(string secret)`

  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

    `string to_query()`

  Description

    Turns the parameters into a query string

CLASS Web.Auth.Twitter

  Description

    Twitter authentication class

  Constant ACCESS_TOKEN_URL

    `constant string Web.Auth.Twitter.ACCESS_TOKEN_URL`

  Description

    The endpoint to send request for an access token

  Constant REQUEST_TOKEN_URL

    `constant string Web.Auth.Twitter.REQUEST_TOKEN_URL`

  Description

    The endpoint to send request for a request token

  Constant USER_AUTH_URL

    `constant string Web.Auth.Twitter.USER_AUTH_URL`

  Description

    The enpoint to redirect to when authenticating an application

  Inherit Authentication

    inherit Web.Auth.OAuth.Authentication : Authentication

Module Web.Auth.Google

  Description

    Google authentication classes.

  CLASS Web.Auth.Google.Analytics

    Description

      Google Analytics authorization class

    Constant SCOPE_RO
    Constant SCOPE_RW
    Constant SCOPE_EDIT
    Constant SCOPE_MANAGE_USERS
    Constant SCOPE_MANAGE_USERS_RO

      `constant string Web.Auth.Google.Analytics.SCOPE_RO`
      `constant string Web.Auth.Google.Analytics.SCOPE_RW`
      `constant string Web.Auth.Google.Analytics.SCOPE_EDIT`
      `constant string Web.Auth.Google.Analytics.SCOPE_MANAGE_USERS`
      `constant string Web.Auth.Google.Analytics.SCOPE_MANAGE_USERS_RO`

    Description

      Authentication scopes

    Variable _scope

      `protected string Web.Auth.Google.Analytics._scope`

    Description

      Default scope

    Inherit Authorization

      inherit Authorization : Authorization

    Variable valid_scopes

      `protected multiset(string) Web.Auth.Google.Analytics.valid_scopes`

    Description

      All valid scopes

  CLASS Web.Auth.Google.Authorization

    Description

      Default Google authorization class For more info see https://developers.google.com/+/web/api/rest/oauth

    Constant OAUTH_AUTH_URI

      `constant string Web.Auth.Google.Authorization.OAUTH_AUTH_URI`

    Constant OAUTH_TOKEN_URI

      `constant string Web.Auth.Google.Authorization.OAUTH_TOKEN_URI`

    Constant SCOPE_EMAIL

      `constant string Web.Auth.Google.Authorization.SCOPE_EMAIL`

    Constant SCOPE_OPENID

      `constant string Web.Auth.Google.Authorization.SCOPE_OPENID`

    Constant SCOPE_PROFILE

      `constant string Web.Auth.Google.Authorization.SCOPE_PROFILE`

    Inherit Client

      inherit Web.Auth.OAuth2.Client : Client

    Variable valid_scopes

      `protected multiset(string) Web.Auth.Google.Authorization.valid_scopes`

    Description

      All valid socpes

  CLASS Web.Auth.Google.Plus

    Description

      Google+ authorization class

    Constant SCOPE_ME
    Constant SCOPE_LOGIN

      `constant string Web.Auth.Google.Plus.SCOPE_ME`
      `constant string Web.Auth.Google.Plus.SCOPE_LOGIN`

    Description

      Authentication scopes

    Variable _scope

      `protected string Web.Auth.Google.Plus._scope`

    Description

      Default scope

    Inherit Authorization

      inherit Authorization : Authorization

    Variable valid_scopes

      `protected multiset(string) Web.Auth.Google.Plus.valid_scopes`

    Description

      All valid scopes

Module Web.Auth.OAuth

  Description

    OAuth module

    Example

    import Web.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

  `constant string Web.Auth.OAuth.CALLBACK_KEY`

Description

  Query string variable name for a callback URL.

Constant CONSUMER_KEY_KEY

  `constant string Web.Auth.OAuth.CONSUMER_KEY_KEY`

Description

  Query string variable name for the consumer key.

Constant NONCE_KEY

  `constant string Web.Auth.OAuth.NONCE_KEY`

Description

  Query string variable name for the nonce.

Constant SIGNATURE_KEY

  `constant string Web.Auth.OAuth.SIGNATURE_KEY`

Description

  Query string variable name for the signature.

Constant SIGNATURE_METHOD_KEY

  `constant string Web.Auth.OAuth.SIGNATURE_METHOD_KEY`

Description

  Query string variable name for the signature method.

Constant TIMESTAMP_KEY

  `constant string Web.Auth.OAuth.TIMESTAMP_KEY`

Description

  Query string variable name for the timestamp.

Constant TOKEN_KEY

  `constant string Web.Auth.OAuth.TOKEN_KEY`

Description

  Query string variable name for the token key.

Constant TOKEN_SECRET_KEY

  `constant string Web.Auth.OAuth.TOKEN_SECRET_KEY`

Description

  Query string variable name for the token secret.

Constant VERSION

  `constant string Web.Auth.OAuth.VERSION`

Description

  Verion

Constant VERSION_KEY

  `constant string Web.Auth.OAuth.VERSION_KEY`

Description

  Query string variable name for the version.

Method get_default_params

  `Params get_default_params(Consumer consumer, Token token)`

Description

  Returns the default params for authentication/signing.

Method nonce

  `string nonce()`

Description

  Generates a `nonce`.

Method normalize_uri

  `string normalize_uri(string|Standards.URI uri)`

Description

  Normalizes uri

Parameter `uri`

  A `string` or Standards.URI.

Method query_to_params

  `Params query_to_params(string|Standards.URI|mapping q)`

Description

  Converts a query string, or a mapping, into a Params object.

Method request

  `Request request(string|Standards.URI uri, Consumer consumer, Token token, void|Params params, void|string http_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.

  Constant ACCESS_TOKEN_URL

    `constant int Web.Auth.OAuth.Authentication.ACCESS_TOKEN_URL`

  Description

    The endpoint to send request for an access token.

  Constant REQUEST_TOKEN_URL

    `constant int Web.Auth.OAuth.Authentication.REQUEST_TOKEN_URL`

  Description

    The endpoint to send request for a request token.

  Constant USER_AUTH_URL

    `constant int Web.Auth.OAuth.Authentication.USER_AUTH_URL`

  Description

    The enpoint to redirect to when authorize an application.

  Method call

    `string call(string|Standards.URI url, void|mapping|.Params args, void|string method)`

  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.Authentication Web.Auth.OAuth.Authentication(string client_id, string client_secret, void|string redir, 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

    `.Token get_access_token(void|string oauth_verifier)`

  Description

    Fetches an access token.

  Method get_auth_uri

    `string get_auth_uri(void|mapping args)`

  Method get_request_token

    `.Token get_request_token(void|string|Standards.URI callback_uri, void|bool force_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.

  Inherit oauth

    inherit .Client : oauth

  Inherit oauth2

    inherit Web.Auth.OAuth2.Client : oauth2

  Method is_authenticated

    `bool is_authenticated()`

  Description

    Returns true if authenticated.

  Method low_get_access_token

    `protected string low_get_access_token(void|string oauth_verifier)`

  Description

    Fetches an access token.

  Method normalize_method

    `protected string normalize_method(string method)`

  Description

    Normalizes and verifies the HTTP method to be used in a HTTP call.

  Method parse_error_xml

    `mapping parse_error_xml(string xml)`

  Description

    Parses an error xml tree.

  Returns

    A mapping:

    `"request" : string`
    `"error" : string`

  Method request_access_token

    `string request_access_token(string code)`

  Description

    Same as get_access_token except this returns a string to comply with the OAuth2 authentication process.

  Method set_authentication

    `void set_authentication(string key, void|string secret)`

  Description

    Set authentication.

  Method set_from_cookie

    `this_program set_from_cookie(string encoded_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

    `protected string Web.Auth.OAuth.Client.access_token_url`

  Description

    The endpoint to send request for an access token.

  Variable consumer

    `protected Consumer Web.Auth.OAuth.Client.consumer`

  Description

    The consumer object.

  Method create

    `Web.Auth.OAuth.Client Web.Auth.OAuth.Client(Consumer consumer, Token token)`

  Description

    Create a new Client.

  Note

    This class must be inherited

  Method get_access_token_url

    `string get_access_token_url()`

  Description

    Returns the url for requesting an access token.

  Method get_consumer

    `Consumer get_consumer()`

  Description

    Returns the consumer.

  Method get_request_token_url

    `string get_request_token_url()`

  Description

    Returns the url for requesting a request token.

  Method get_token

    `Token get_token()`

  Description

    Returns the token.

  Method get_user_auth_url

    `string get_user_auth_url()`

  Description

    Returns the url for authorizing an application.

  Variable request_token_url

    `protected string Web.Auth.OAuth.Client.request_token_url`

  Description

    The endpoint to send request for a request token.

  Method set_token

    `void set_token(Token token)`
    `void set_token(string token_key, string token_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.

  Variable token

    `protected Token Web.Auth.OAuth.Client.token`

  Description

    The token object.

  Variable user_auth_url

    `protected string Web.Auth.OAuth.Client.user_auth_url`

  Description

    The enpoint to redirect to when authorize an application.

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.

  Method create

    `Web.Auth.OAuth.Consumer Web.Auth.OAuth.Consumer(string key, string secret, void|string|Standards.URI callback)`

  Description

    Creates a new Consumer object.

  Parameter `callback`

    NOTE: Has no effect in this implementation.

  Variable key

    `string Web.Auth.OAuth.Consumer.key`

  Description

    Consumer key

  Variable secret

    `string Web.Auth.OAuth.Consumer.secret`

  Description

    Consumer secret

CLASS Web.Auth.OAuth.Param

  Description

    Represents a query string parameter, i.e. `key=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 res = Web.Auth.OAuth.Param()[ key ]`

  Description

    Index lookup.

  Method create

    `Web.Auth.OAuth.Param Web.Auth.OAuth.Param(string name, mixed value)`

  Description

    Creates a new Param.

  Method get_encoded_value

    `string get_encoded_value()`

  Description

    Returns the value encoded.

  Method get_name

    `string get_name()`

  Description

    Getter for the name attribute.

  Method get_signature

    `string get_signature()`

  Description

    Returns the name and value for usage in a signature string.

  Method get_value

    `string get_value()`

  Description

    Getter for the value attribute.

  Variable name

    `protected string Web.Auth.OAuth.Param.name`

  Description

    Param name

  Method set_name

    `void set_name(string value)`

  Description

    Setter for the value attribute.

  Method set_value

    `void set_value(mixed _value)`

  Description

    Setter for the value attribute.

  Variable value

    `protected string Web.Auth.OAuth.Param.value`

  Description

    Param value

CLASS Web.Auth.OAuth.Params

  Description

    Collection of Param

  Method _sizeof

    `int(0..) sizeof( Web.Auth.OAuth.Params arg )`

  Description

    Returns the size of the params array.

  Method _values

    `mixed values( Web.Auth.OAuth.Params arg )`

  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_program add_mapping(mapping args)`

  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.Params Web.Auth.OAuth.Params(Param ... params)`

  Description

    Create a new Params

  Parameter `params`

    Arbitrary number of Param objects.

  Method get_auth_header

    `string get_auth_header()`

  Description

    Returns the params for usage in an authentication header.

  Method get_encoded_variables

    `mapping get_encoded_variables()`

  Description

    Returns the parameters as a mapping with encoded values.

  See also

    get_variables()

  Method get_query_string

    `string get_query_string()`

  Description

    Returns the parameters as a query string.

  Method get_signature

    `string get_signature()`

  Description

    Returns the parameters for usage in a signature base string.

  Method get_variables

    `mapping get_variables()`

  Description

    Returns the parameters as a mapping.

  Variable params

    `private array(Param) Web.Auth.OAuth.Params.params`

  Description

    Storage for Params of this object.

CLASS Web.Auth.OAuth.Request

  Description

    Class for building a signed request and querying the remote service.

  Method add_param

    `this_program add_param(Param|string name, void|string value)`

  Description

    Add a param.

  Returns

    The object being called.

  Method add_params

    `void add_params(Params params)`

  Description

    Add a Params object.

  Variable base_string

    `protected string Web.Auth.OAuth.Request.base_string`

  Description

    The signature basestring.

  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.Request Web.Auth.OAuth.Request(string|Standards.URI uri, string http_method, void|Params params)`

  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 get_param(string name)`

  Description

    Get param with name name.

  Method get_params

    `Params get_params()`

  Description

    Returns the Params collection.

  Method get_signature_base

    `string get_signature_base()`

  Description

    Generates a signature base.

  Variable method

    `protected string Web.Auth.OAuth.Request.method`

  Description

    String representation of the HTTP method.

  Variable params

    `protected Params Web.Auth.OAuth.Request.params`

  Description

    The parameters to send.

  Method sign_request

    `void sign_request(int signature_type, Consumer consumer, Token token)`

  Description

    Signs the request.

  Parameter `signature_type`

    One of the types in Signature.

  Method submit

    `Protocols.HTTP.Query submit(void|mapping extra_headers)`

  Description

    Send the request to the remote endpoint.

  Variable uri

    `protected Standards.URI Web.Auth.OAuth.Request.uri`

  Description

    The remote endpoint.

CLASS Web.Auth.OAuth.Token

  Description

    Token class.

  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.Token Web.Auth.OAuth.Token(string key, string secret)`

  Variable key
  Variable secret

    `string Web.Auth.OAuth.Token.key`
    `string Web.Auth.OAuth.Token.secret`

Module Web.Auth.OAuth.Signature

  Description

    Module for creating OAuth signatures

  Constant HMAC_SHA1

    `constant int Web.Auth.OAuth.Signature.HMAC_SHA1`

  Description

    Signature type for hmac sha1 signing.

  Constant NONE

    `protected constant int Web.Auth.OAuth.Signature.NONE`

  Description

    Signature type for the Base class.

  Constant PLAINTEXT

    `constant int Web.Auth.OAuth.Signature.PLAINTEXT`

  Description

    Signature type for plaintext signing.

  Constant RSA_SHA1

    `constant int 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

    `Base get_object(int type)`

  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.

    Method build_signature

      `string build_signature(Request request, Consumer consumer, Token token)`

    Description

      Builds the signature string.

    Method get_method

      `string get_method()`

    Description

      Returns the method.

    Method get_type

      `int get_type()`

    Description

      Returns the type.

    Variable method

      `protected string Web.Auth.OAuth.Signature.Base.method`

    Description

      String representation of signature type.

    Variable type

      `protected int Web.Auth.OAuth.Signature.Base.type`

    Description

      Signature type.

  CLASS Web.Auth.OAuth.Signature.HmacSha1

    Description

      HMAC_SHA1 signature.

    Method build_signature

      `string build_signature(Request request, Consumer consumer, Token token)`

    Description

      Builds the signature string.

    Inherit Base

      inherit Base : Base

  CLASS Web.Auth.OAuth.Signature.Plaintext

    Description

      Plaintext signature.

    Method build_signature

      `string build_signature(Request request, Consumer consumer, Token token)`

    Description

      Builds the signature string.

    Inherit Base

      inherit Base : Base

  CLASS Web.Auth.OAuth.Signature.RsaSha1

    Description

      RSA_SHA1 signature. Currently not implemented.

    Method build_signature

      `string build_signature(Request request, Consumer consumer, Token token)`

    Description

      Builds the signature string.

    Inherit Base

      inherit Base : Base

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

    `protected Base `()(string client_id, string client_secret, void|string redirect_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 constant int 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 constant string Web.Auth.OAuth2.Base.USER_AGENT`

    Description

      User agent string.

    Constant VERSION

      `protected constant string Web.Auth.OAuth2.Base.VERSION`

    Description

      Version of this implementation.

    Variable _access_type

      `protected string Web.Auth.OAuth2.Base._access_type`

    Description

      Access type of the request.

    Variable _client_id

      `protected string Web.Auth.OAuth2.Base._client_id`

    Description

      The application ID.

    Variable _client_secret

      `protected string Web.Auth.OAuth2.Base._client_secret`

    Description

      The application secret.

    Variable _grant_type

      `protected string 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

      `protected string Web.Auth.OAuth2.Base._redirect_uri`

    Description

      Where the authorization page should redirect to.

    Variable _response_type

      `protected string 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

      `protected string|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`.

    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.Base Web.Auth.OAuth2.Base(string client_id, string client_secret, void|string redirect_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().

    Variable created

      `Calendar.Second Web.Auth.OAuth2.Base.created`

    Description

      Getter for when the authentication was `created`.

    Note

      Read only

    Method decode_access_token_response

      `protected bool decode_access_token_response(string r)`

    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

      `protected string do_query(string oauth_token_uri, Web.Auth.Params p, 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().

    Variable expires

      `Calendar.Second Web.Auth.OAuth2.Base.expires`

    Description

      Getter for when the authentication `expires`.

    Note

      Read only

    Method get_access_type

      `string get_access_type()`

    Description

      Getter for the access type, if any.

    Method get_auth_uri

      `string get_auth_uri(string auth_uri, void|mapping args)`

    Description

      Returns an authorization URI.

    Parameter `auth_uri`

      The URI to the remote authorization page

    Parameter `args`

      Additional argument.

    Method get_client_id

      `string get_client_id()`

    Description

      Returns the application ID.

    Method get_client_secret

      `string get_client_secret()`

    Description

      Returns the application secret.

    Method get_default_params

      `protected Web.Auth.Params get_default_params(void|string grant_type)`

    Description

      Returns a set of default parameters.

    Method get_grant_type

      `string get_grant_type()`

    Description

      Returns the `grant_type` of the object.

    Method get_redirect_uri

      `string get_redirect_uri()`

    Description

      Returns the redirect uri.

    Method get_scope

      `mixed get_scope()`

    Description

      Returns the scope/scopes set, if any.

    Method get_token_from_jwt

      `string get_token_from_jwt(string jwt, string token_endpoint, string|void sub, 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().

    Method get_valid_scopes

      `protected string get_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

      `bool has_scope(string scope)`

    Description

      Check if scope exists in this object.

    Variable http_request_timeout

      `int(1..) Web.Auth.OAuth2.Base.http_request_timeout`

    Description

      Request timeout in seconds. Only affects async queries.

    Method is_authenticated

      `bool is_authenticated()`

    Description

      Do we have a valid authentication.

    Method is_expired

      `bool is_expired()`

    Description

      Checks if this authorization has expired.

    Method is_renewable

      `bool is_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

      `multiset list_valid_scopes()`

    Description

      Returns the valid scopes.

    Method refresh_access_token

      `string refresh_access_token(string oauth_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().

    Variable refresh_token

      `string Web.Auth.OAuth2.Base.refresh_token`

    Description

      Getter for `refresh_token`.

    Note

      Read only

    Method request_access_token

      `string request_access_token(string oauth_token_uri, string code, 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_url().

    Parameter `code`

      The code returned from the authorization page via get_auth_url().

    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.

    Variable request_headers

      `protected mapping Web.Auth.OAuth2.Base.request_headers`

    Description

      Default request headers.

    Method set_access_type

      `void set_access_type(string access_type)`

    Description

      Set access_type explicilty.

    Parameter `access_type`

      Like: offline

    Method set_from_cookie

      `this_program set_from_cookie(string encoded_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

      `void set_grant_type(GrantType type)`

    Description

      Set the grant type to use.

    Method set_redirect_uri

      `void set_redirect_uri(string uri)`

    Description

      Setter for the redirect uri.

    Method set_scope

      `void set_scope(string scope)`

    Description

      Set scopes.

    Variable token_type

      `string Web.Auth.OAuth2.Base.token_type`

    Description

      Getter for `token_type`.

    Note

      Read only

    Method try_get_error

      `private mixed try_get_error(string data)`

    Description

      Try to get an error message from data. Only successful if data is a JSON string and contains the key `error`.

    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

      `protected multiset(string) Web.Auth.OAuth2.Base.valid_scopes`

    Description

      A mapping of valid scopes for the API.

    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.

    Constant DEFAULT_SCOPE

      `protected constant int Web.Auth.OAuth2.Client.DEFAULT_SCOPE`

    Description

      Scope to set if none is set.

    Constant OAUTH_AUTH_URI

      `constant int Web.Auth.OAuth2.Client.OAUTH_AUTH_URI`

    Description

      Authorization URI.

    Constant OAUTH_TOKEN_URI

      `constant int Web.Auth.OAuth2.Client.OAUTH_TOKEN_URI`

    Description

      Request access token URI.

    Method get_auth_uri

      `string get_auth_uri(void|mapping args)`

    Description

      Returns an authorization URI.

    Parameter `args`

      Additional argument.

    Method get_token_from_jwt

      `string get_token_from_jwt(string jwt, void|string sub, void|function(bool, string:void) async_cb)`

    Description

      Make an JWT (JSON Web Token) authentication.

    Inherit Base

      inherit Base : Base

    Method refresh_access_token

      `string refresh_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

      `string request_access_token(string code, 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_url().

    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 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`

    Method create

      `Web.CGI.Request Web.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.

    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`

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

    Method create

      `Web.Crawler.ComplexQueue Web.Crawler.ComplexQueue(Stats stats, Policy policy)`

    Inherit Queue

      inherit Queue : Queue

    Variable stats
    Variable policy

      `Stats Web.Crawler.ComplexQueue.stats`
      `Policy Web.Crawler.ComplexQueue.policy`

  CLASS Web.Crawler.Crawler

    Method create

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

    Method create

      `Web.Crawler.GlobRule Web.Crawler.GlobRule(string pattern)`

    Inherit Rule

      inherit Rule : Rule

    Variable pattern

      `string Web.Crawler.GlobRule.pattern`

  CLASS Web.Crawler.MemoryQueue

    Description

      Memory queue

    Method create

      `Web.Crawler.MemoryQueue Web.Crawler.MemoryQueue(Stats _stats, Policy _policy, RuleSet _allow, RuleSet _deny)`

    Method get

      `int|Standards.URI get()`

    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.

    Inherit Queue

      inherit Queue : Queue

    Method put

      `void put(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

    Method create

      `Web.Crawler.MySQLQueue Web.Crawler.MySQLQueue(Stats _stats, Policy _policy, string _host, string _table, void|RuleSet _allow, void|RuleSet _deny)`

    Inherit Queue

      inherit Queue : Queue

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

    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

      `void put(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

    Method create

      `Web.Crawler.RegexpRule Web.Crawler.RegexpRule(string re)`

    Parameter `re`

      a string describing the Regexp expression

    Inherit Rule

      inherit Rule : Rule

  CLASS Web.Crawler.Rule

    Description

      Abstract rule class.

    Method check

      `int check(string|Standards.URI uri)`

  CLASS Web.Crawler.RuleSet

    Description

      A set of rules

    Method add_rule

      `void add_rule(Rule rule)`

    Description

      add a rule to the ruleset

    Method remove_rule

      `void remove_rule(Rule rule)`

    Description

      remove a rule from the ruleset

  CLASS Web.Crawler.Stats

    Description

      Statistics.

    Method bytes_read_callback

      `void bytes_read_callback(Standards.URI uri, int num_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

      `void close_callback(Standards.URI uri)`

    Description

      This callback is called whenever the crawling of a URI is finished or fails.

    Method create

      `Web.Crawler.Stats Web.Crawler.Stats(int window_width, int granularity)`

    Variable window_width
    Variable granularity

      `int Web.Crawler.Stats.window_width`
      `int Web.Crawler.Stats.granularity`

Module Web.RSS

  Description

    Represents a RSS (RDF Site Summary) file.

  Method parse_xml

    `Index parse_xml(string|Parser.XML.Tree.Node n, void|string base)`

  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.

    Method add_item

      `void add_item(Item i)`

    Description

      Adds the Item i to the Channel.

    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`

    Inherit Thing

      inherit Thing : Thing

    Method remove_item

      `void remove_item(Item i)`

    Description

      Removes the Item i 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.

    Method create

      `Web.RSS.Index Web.RSS.Index(.RDF|void _rdf)`

    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.

  CLASS Web.RSS.Item

    Description

      Represents an RSS item resource.

    Variable title
    Variable link
    Variable description

      `string Web.RSS.Item.title`
      `string Web.RSS.Item.link`
      `string Web.RSS.Item.description`

    Inherit Thing

      inherit Thing : Thing

  CLASS Web.RSS.Textinput

    Description

      Represents an RSS textinput resource.

    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`

    Inherit Thing

      inherit Thing : Thing

  CLASS Web.RSS.Thing

    Description

      The base class for the RSS resources.

    Method create

      `Web.RSS.Thing Web.RSS.Thing(string about, mapping attributes)`
      `Web.RSS.Thing Web.RSS.Thing(.RDF.Resource me)`

    Description

      Creates an RSS resource.

    Method get_id

      `.RDF.Resource get_id()`

    Description

      Returns the RDF.Resource that identifies this RSS resource.

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.

  Method default_domain

    `string default_domain()`

  Description

    Returns the default yp-domain.

  Inherit "___Yp"

    inherit "___Yp" : "___Yp"

  CLASS Yp.Domain

    Method all

      `mapping(string:string) all(string map)`

    Description

      Returns the whole map as a mapping.

      map is the YP-map to search in. This must be the full map name, you have to use `passwd.byname` instead of just `passwd`.

    Method create
    Method bind

      `Yp.Domain Yp.Domain(string|void domain)`
      `void bind(string domain)`

    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

      `void map(string map, 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

      `string match(string map, string key)`

    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

      `int order(string map)`

    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

      `string server(string map)`

    Description

      Returns the hostname of the server serving the map map. map is the YP-map to search in. This must be the full map name. eg `passwd.byname` instead of just `passwd`.

  CLASS Yp.Map

    Description

      Network Information Service aka YP map.

    Method _indices

      `array(string) indices( Yp.Map arg )`

    Description

      Return the keys of the map.

    Method _sizeof

      `int sizeof( Yp.Map arg )`

    Description

      Return the number of entries in this map.

    Method _values

      `array(string) values( Yp.Map arg )`

    Description

      Return the values of the map.

    Method match
    Method `[]

      `string match(string key)`
      `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.Map Yp.Map(string map, string|void domain)`

    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

      `void map(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

      `int order()`

    Description

      Return the order number for this map.

    Method server

      `string server()`

    Description

      Return the server that provides this map.

Module ZXID

  Description

    ZXID is a library that implements SAML 2.0, Liberty ID-WSF 2.0 and XACML 2.0.

    This module implements a wrapper for ZXID. The interface is similar to the C one, but using generally accepted Pike syntax.

  Inherit ZXID

    inherit "___ZXID" : ZXID

  Method mapping_to_query

    `string(8bit) mapping_to_query(mapping(string(8bit):string(8bit)) map)`

  Description

    Convert a mapping of query variables to a query string.

  Method version

    `int version()`

  Description

    Return the numeric version of the zxid library.

  CLASS ZXID.Configuration

    Description

      A set of configuration parameters for a ZXID context.

      This is typically overloaded with new definitions for the various callback functions.

    Method create

      `ZXID.Configuration ZXID.Configuration(string|mapping(string(8bit):string(8bit)) conf)`

    Description

      Create a new Configuration.

    Parameter `conf`

      ZXID configuration parameters. Either as a configuration string (as per the ZXID book chapter 7 and 10), or as a mapping of parameter settings. These are the most common parameters:

      `"PATH" : string(8bit)` | Path to the directory containing the `"zxid.conf"` file.
      `"URL" : string(8bit)` | URL of the SP.
      `"CDC_URL" : string(8bit)` | The Common Domain URL.

    Method idp_list

      `mapping(string(8bit):mapping(string(8bit):string(8bit))) idp_list()`

    Description

      Return a list of known identity providers.

    Returns

      Returns a mapping from IdP EID to display name (if any).

    Inherit Configuration

      inherit ZXID::Configuration : Configuration

    CLASS ZXID.Configuration.Session

      Description

        Represents the current session state for a user.

      Variable auth_info

        `mapping(string:mixed) ZXID.Configuration.Session.auth_info`

      Method authenticate

        `mixed authenticate(string(8bit) uri_path, string(8bit)|mapping(string(8bit):string(8bit)) query)`

      Description

        Authenticate via SAML given the query-string query.

      Returns

        `mapping(string(8bit):string(8bit))` | Returns a mapping when interaction with the browser is needed.
        `string` | Returns a string to ask for some specific actions.
        `zero` | Returns `0` (zero) on successfull authentication. auth_info will be set with the corresponding user information.

      Throws

        Throws errors on most error conditions.

      Method authenticate

        `string(8bit) authenticate(string(8bit) uri_path, string(8bit) query)`

      Description

        Authenticate via SAML given the query-string query.

      Parameter `uri_path`

        Current URI path (before '?').

      Parameter `query`

        Query variables (after '?').

      Returns

        Returns JSON-encoded data on success, and various other strings otherwise.

      Method create

        `ZXID.Configuration.Session ZXID.Configuration.Session(string|void session_id)`

      Description

        Create a new or look up an existing session.

      Method get_auth_info

        `mapping(string:mixed) get_auth_info()`

      Inherit Session

        inherit Configuration::Session : Session

      Variable session_id

        `string(8bit) ZXID.Configuration.Session.session_id`

      Description

        Session id (if any).

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(int codec_name, int encoder)`

    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|int decode(string data)`

    Description

      Returns a mapping with the new decoded frame and lenght of data which was used for decoding.

    Method decode

      `int decode(string data, 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 get_codec_info

      `mapping|int get_codec_info()`

    Description

      Returns mapping with info of used codec.

    See also

      list_codecs()

    Method get_codec_status

      `mapping|int get_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

      `int set_codec_param(string name, mixed value)`

    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 __builtin

  Module __builtin.Nettle

    CLASS __builtin.Nettle.AEAD

      Description

        Base class for AEAD (Authenticated Encryption with Associated Data) algorithms.

        AEAD algorithms behave like a combination of a Cipher and a HMAC.

        Note that no actual AEAD algorithm is implemented in the base class. They are implemented in classes that inherit this class.

      Method `()

        `State res = __builtin.Nettle.AEAD()()`

      Description

        Calling `() will return a State object.

      Inherit Cipher

        inherit __builtin.Nettle.Cipher : Cipher

      Inherit __Hash

        inherit __builtin.Nettle.__Hash : __Hash

      CLASS __builtin.Nettle.AEAD.State

        Description

          This is the context for a single incrementally updated AEAD cipher.

          Most of the functions here are only prototypes, and need to be overrided via inherit.

        Inherit State

          inherit Cipher::State : State

        Inherit State

          inherit __Hash::State : State

    CLASS __builtin.Nettle.BlockCipher

      Description

        Base class for block cipher algorithms.

        Implements some common convenience functions, and prototypes.

        It also implements operating modes other than ECB.

        Note that no actual cipher algorithm is implemented in the base class. They are implemented in classes that inherit this class.

      Inherit Cipher

        inherit .Cipher : Cipher

      Module __builtin.Nettle.BlockCipher.CTR

        Description

          Implementation of Counter Mode (CTR). Works as a wrapper for the cipher algorithm in the parent module.

          This cipher mode works like a stream cipher with a block size >= 1. This means that the same key and initialization vector (aka counter) should never be reused, since a simple xor would reveal information about the plain text. It also means that it should never be used without a suiteable Message Authentication Code (MAC).

        See also

          CBC, CCM, GCM, MAC

        Inherit Cipher

          inherit .Cipher : Cipher

        Method name

          `string(7bit) name()`

        Description

          Returns the name of the base cipher extended with `".CTR"`.

        CLASS __builtin.Nettle.BlockCipher.CTR.State

          Description

            The state for the embedded algorithm

          Inherit this_program

            inherit ::this_program : this_program

    CLASS __builtin.Nettle.Cipher

      Description

        Base class for cipher algorithms.

        Implements some common convenience functions, and prototypes.

        Note that no actual cipher algorithm is implemented in the base class. They are implemented in classes that inherit (usually via predef::Nettle.Cipher) this class.

      See also

        predef::Nettle.Cipher, Crypto.Cipher

      Method `()

        `State res = __builtin.Nettle.Cipher()()`

      Description

        Calling `() will return a State object.

      Method block_size

        `int(0..) block_size()`

      Returns

        The block size of the cipher (`1` for stream ciphers).

      Method decrypt

        `string decrypt(string(8bit) key, string(8bit) data)`

      Description

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

      Method encrypt

        `string encrypt(string(8bit) key, string(8bit) data)`

      Description

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

      Method key_size

        `int(0..) key_size()`

      Returns

        The recommended key size for the cipher.

      Method name

        `string(7bit) name()`

      Description

        Returns a human readable name for the algorithm.

      CLASS __builtin.Nettle.Cipher.State

        Description

          This is the context for a single incrementally updated cipher.

          Most of the functions here are only prototypes, and need to be overrided via inherit.

        Method block_size

          `int(0..) block_size()`

        Returns

          The block size of the cipher (`1` for stream ciphers).

          Defaults to just returning `global::block_size()`.

        Method crypt

          `string(8bit) crypt(string(8bit) data)`

        Description

          Encrypts or decrypts data, using the current key. Neither the input nor output data is automatically memory scrubbed, unless String.secure has been called on them.

        Parameter `data`

          For block ciphers, data must be an integral number of blocks.

        Returns

          The encrypted or decrypted data.

        Method key_size

          `int(0..) key_size()`

        Returns

          The actual key size for this cipher.

          Defaults to just returning `global::key_size()`.

        Method make_key

          `string(8bit) make_key()`

        Description

          Generate a key by calling Crypto.Random.random_string and initialize the object for encryption with that key.

        Returns

          The generated key.

        See also

          set_encrypt_key

        Method name

          `string(7bit) name()`

        Description

          Returns a human readable name for the algorithm.

          Defaults to just returning `global::name()`.

        Method set_decrypt_key

          `this_program set_decrypt_key(string(8bit) key, void|int force)`

        Description

          Initializes the object for decryption.

        See also

          set_encrypt_key, crypt

        Method set_encrypt_key

          `this_program set_encrypt_key(string(8bit) key, void|int force)`

        Description

          Initializes the object for encryption.

        See also

          set_decrypt_key, crypt

    CLASS __builtin.Nettle.ECC_Curve

      Description

        Base class for Elliptic Curve Definitions.

      See also

        Crypto.ECC.Curve, Nettle.ECC_Curve

      CLASS __builtin.Nettle.ECC_Curve.Point

        Description

          Base class for a point on an elliptic curve.

        Method create

          `__builtin.Nettle.ECC_Curve.Point __builtin.Nettle.ECC_Curve.Point(Gmp.mpz|int x, Gmp.mpz|int y)`
          `__builtin.Nettle.ECC_Curve.Point __builtin.Nettle.ECC_Curve.Point(Stdio.Buffer|string(7bit) data)`

        Description

          Initialize to the selected point on the curve.

        Note

          Throws errors if the point isn't on the curve.

        Method encode

          `string encode()`

        Description

          Serialize the Point.

          The default implementation serializes according to ANSI x9.62 encoding #4 (uncompressed point format).

    CLASS __builtin.Nettle.Hash

      Description

        Base class for hash algorithms.

        Implements common meta functions, such as key expansion algoritms and convenience functions.

        Note that no actual hash algorithm is implemented in the base class. They are implemented in classes that inherit this class.

      Method P_hash

        `string P_hash(string password, string salt, int rounds, int bytes)`

      Description

        This is the Password-Based Key Derivation Function used in TLS.

      Parameter `password`

        The prf secret.

      Parameter `salt`

        The prf seed.

      Parameter `rounds`

        Ignored.

      Parameter `bytes`

        The number of bytes to generate.

      Method `()

        `State res = __builtin.Nettle.Hash()()`

      Description

        Calling `() will return a State object.

      Method crypt_hash

        `string crypt_hash(string password, string salt, int rounds)`

      Description

        Password hashing function in crypt_md5()-style.

        Implements the algorithm described in http://www.akkadia.org/drepper/SHA-crypt.txt.

        This is the algorithm used by `crypt(2)` in methods `$5$` (SHA256) and `$6$` (SHA512).

      See also

        crypt_md5()

      Method hash

        `string hash(string data)`
        `string hash(Stdio.File file, void|int bytes)`

      Description

        Shortcut for hashing some data.

      Parameter `data`

        String to hash.

      Parameter `file`

        Stdio.File object to read some data to hash from.

      Parameter `bytes`

        The number of bytes of the file object file that should be hashed. Negative numbers are ignored and the whole file is hashed.

        Works as a (possibly faster) shortcut for `State(data)->digest()`, where State is the hash state class corresponding to this Hash.

      See also

        Stdio.File, State()->update() and State()->digest().

      Inherit __Hash

        inherit .__Hash : __Hash

      Method openssl_pbkdf

        `string openssl_pbkdf(string password, string salt, int rounds, int bytes)`

      Description

        Password Based Key Derivation Function from OpenSSL.

        This when used with Crypto.MD5 and a single round is the function used to derive the key to encrypt Standards.PEM body data.

      FIXME

        Derived from OpenSSL. Is there any proper specification?

        It seems to be related to PBKDF1 from RFC2898.

      See also

        pbkdf1(), pbkdf2(), crypt_password()

      Method pbkdf1

        `string pbkdf1(string password, string salt, int rounds, int bytes)`

      Description

        Password Based Key Derivation Function #1 from RFC 2898. This method is compatible with the one from PKCS#5 v1.5.

      Parameter `password`
      Parameter `salt`

        Password and salt for the keygenerator.

      Parameter `rounds`

        The number of iterations to rehash the input.

      Parameter `bytes`

        The number of bytes of output. Note that this has an upper limit of the size of a single digest.

      Returns

        Returns the derived key.

      Note

        RFC 2898 does not recommend this function for anything else than compatibility with existing applications, due to the limits in the length of the generated keys.

      See also

        pbkdf2(), openssl_pbkdf(), crypt_password()

      Method pbkdf2

        `string pbkdf2(string password, string salt, int rounds, int bytes)`

      Description

        Password Based Key Derivation Function #2 from RFC 2898, PKCS#5 v2.0.

      Parameter `password`
      Parameter `salt`

        Password and salt for the keygenerator.

      Parameter `rounds`

        The number of iterations to rehash the input.

      Parameter `bytes`

        The number of bytes of output.

      Returns

        Returns the derived key.

      See also

        pbkdf1(), openssl_pbkdf(), crypt_password()

      Method pkcs_digest

        `string pkcs_digest(string s)`

      Description

        Make a PKCS-1 digest info block with the message s.

      See also

        Standards.PKCS.build_digestinfo()

      Module __builtin.Nettle.Hash.HMAC

        Description

          HMAC (Hashing for Message Authenticity Control) for the hash algorithm.

          RFC 2104.

        See also

          Crypto.HMAC

        Method `()

          `State res = __builtin.Nettle.Hash()()`

        Description

          Returns a new State object initialized with a password.

        Inherit MAC

          inherit .MAC : MAC

        Method iv_size

          `int(0..0) iv_size()`

        Description

          HMAC has no modifiable iv.

        Method key_size

          `int(0..) key_size()`

        Description

          Returns the block size of the encapsulated hash.

        Note

          Other key sizes are allowed, and will be expanded/compressed to this size.

        CLASS __builtin.Nettle.Hash.HMAC.State

          Description

            The HMAC hash state.

          Method `()

            `string res = __builtin.Nettle.Hash.HMAC.State()()`

          Description

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

            This works as a combined update() and digest().

          Method create

            `__builtin.Nettle.Hash.HMAC.State __builtin.Nettle.Hash.HMAC.State(string passwd, void|int b)`

          Parameter `passwd`

            The secret password (K).

          Method digest_info

            `string digest_info(string text)`

          Description

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

          Inherit this_program

            inherit ::this_program : this_program

          Method set_iv

            `this_program set_iv(string(8bit) iv)`

          Description

            HMAC does not have a modifiable iv.

    CLASS __builtin.Nettle.MAC

      Description

        Base class for Message Authentication Codes (MAC)s.

        These are hashes that have been extended with a secret key.

      Inherit __Hash

        inherit .__Hash : __Hash

      Method iv_size

        `int(0..) iv_size()`

      Description

        Returns the size of the iv/nonce (if any).

        Some MACs like eg Crypto.SHA1.HMAC have fixed ivs, in which case this function will return `0`.

      Method key_size

        `int(0..) key_size()`

      Description

        Returns the recomended size of the key.

      CLASS __builtin.Nettle.MAC.State

        Description

          The state for the MAC.

        Method create

          `__builtin.Nettle.MAC.State __builtin.Nettle.MAC.State(string key)`

        Parameter `key`

          The secret key for the hash.

        Inherit this_program

          inherit ::this_program : this_program

        Method iv_size

          `int(0..) iv_size()`

        Description

          Returns the size of the iv/nonce (if any).

          Some MACs like eg Crypto.SHA1.HMAC have fixed ivs, in which case this function will return `0`.

        Method key_size

          `int(0..) key_size()`

        Description

          Returns the recomended size of the key.

    CLASS __builtin.Nettle.Sign

      Description

        Base class for cryptographic signature algorithms.

        Typical classes implementing this API are Crypto.RSA, Crypto.DSA and Crypto.ECC.Curve.ECDSA.

      Method _equal

        `bool equal(__builtin.Nettle.Sign from, mixed x)`

      Description

        Check whether two objects are equvivalent.

        This includes checking both the public and private keys.

      See also

        public_key_equal()

      Method key_size

        `int(0..) key_size()`

      Description

        Returns the number of bits in the private key.

      Method name

        `string(7bit) name()`

      Description

        Returns the printable name of the signing algorithm.

      Method pkcs_algorithm_identifier

        `Sequence pkcs_algorithm_identifier()`

      Description

        Returns the PKCS-1 AlgorithmIdentifier.

      Method pkcs_public_key

        `Sequence pkcs_public_key()`

      Description

        Creates a SubjectPublicKeyInfo ASN.1 sequence for the object. See RFC 5280 section 4.1.2.7.

      Method pkcs_sign

        `string(8bit) pkcs_sign(string(8bit) message, .Hash h)`

      Description

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

      Method pkcs_signature_algorithm_id

        `Sequence pkcs_signature_algorithm_id(.Hash hash)`

      Description

        Returns the PKCS-1 algorithm identifier for the signing algorithm with the provided hash algorithm.

      Method pkcs_verify

        `bool pkcs_verify(string(8bit) message, .Hash h, string(8bit) sign)`

      Description

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

      Method public_key_equal

        `bool public_key_equal(this_program other)`

      Description

        Check whether the public key is the same in two objects.

      Note

        This function differs from _equal() in that only the public key is regarded, and that it only needs to regard objects implementing Crypto.Sign.

      See also

        _equal()

    CLASS __builtin.Nettle.__Hash

      Description

        Base class for hash algorithms.

        Note that no actual hash algorithm is implemented in the base class. They are implemented in classes that inherit this class.

      Method block_size

        `int(1..) block_size()`

      Description

        Returns the internal block size of the hash algorithm.

      Method digest_size

        `int(0..) digest_size()`

      Description

        Returns the size of a hash digests.

      Method name

        `string name()`

      Description

        Returns a human readable name for the algorithm.

      CLASS __builtin.Nettle.__Hash.State

        Description

          This is the context for a single incrementally updated hash.

          Most of the functions here are only prototypes, and need to be overrided via inherit.

        Method block_size

          `int(1..) block_size()`

        Description

          Returns the internal block size of the hash algorithm.

        Method create

          `__builtin.Nettle.__Hash.State __builtin.Nettle.__Hash.State(string|void data)`

        Description

          Create the new context, and optionally add some initial data to hash.

          The default implementation calls update() with data if any, so there's usually no reason to override this function, since overriding update() should be sufficient.

        Method digest

          `string digest(int|void length)`

        Description

          Generates a digests, and resets the hashing contents.

        Parameter `length`

          If the length argument is provided, the digest is truncated to the given length.

        Returns

          The digest.

        Method digest_size

          `int(0..) digest_size()`

        Description

          Returns the size of a hash digests.

        Method init

          `this_program init(string|void data)`

        Description

          Reset the context, and optionally add some initial data to the hash.

        Method name

          `string name()`

        Description

          Returns a human readable name for the algorithm.

        Method update

          `this_program update(string data)`

        Description

          Add some more data to hash.

Module spider

  Method _dump_obj_table

    `array(array(string|int)) _dump_obj_table()`

  Method _low_program_name

    `string _low_program_name(program prog)`

  Method discdate

    `string discdate(int time)`

  Method fd_info

    `string fd_info(int fd)`

  Method parse_accessed_database

    `array(mapping(string:int)|int) parse_accessed_database(string database)`

  Method parse_html

    `string parse_html(string html, mapping(string:function(string, mapping(string:string), mixed ... :string|array)) tag_callbacks, mapping(string:function(string, mapping(string:string), string, mixed ... :string|array)) container_callbacks, mixed ... extras)`

  Method parse_html_lines

    `string parse_html_lines(string html, mapping(string:function(string, mapping(string:string), int, mixed ... :string|array)) tag_callbacks, mapping(string:function(string, mapping(string:string), string, int, mixed ... :string|array)) container_callbacks, mixed ... extras)`

  Method set_end_quote

    `void set_end_quote(int quote)`

  Method set_start_quote

    `void set_start_quote(int quote)`

  Method stardate

    `string stardate(int time, int precision)`