Main Page | Modules | Alphabetical List | Data Structures | File List | Data Fields | Globals | Related Pages

Environment Utilities


Detailed Description

Utility functions and structures for implementing environments.

This module provides a set of structures and utility functions for implement environments and class environments. These are not part of the core API, since they are C specific (higher level languages provide reflection capabilities that can be used to implement the functionality provided by this module).


Files

file  envutil.h
 Utility functions for implementing environments and class environments in C.

Data Structures

struct  sobj_envutil_method
 A formal method name and signature associated with a callback handling the method call. More...

Defines

#define SOBJ_ENVUTIL_METHOD_MISMATCH   ((struct sobj *)1)
 Constant indicating a parameter mismatch.

Typedefs

typedef sobjsobj_envutil_method_fn (struct sobj_envutil_method *se_method, struct sobj_env_class *se_class, struct sobj_env *se_env, struct sobj *se_object, struct sobj **se_args)
 Function type for method callbacks registered in sobj_envutil_method structures.

Functions

sobj_envutil_methodnew_sobj_envutil_method (const char *name, sobj_envutil_method_fn *method_callback)
 Create a new instance of a method object.
void sobj_envutil_method_add_prm (struct sobj_envutil_method *method, const char *name, bool variable)
 Add a formal parameter to a method object.
sobjsobj_envutil_method_call (struct sobj_envutil_method *method, struct sobj_env_class *env_class, struct sobj_env *env, struct sobj *object, struct sobj *args)
 Call the specified method object.
sobjsobj_envutil_call (struct sobj_envutil_method **method_list, struct sobj_env_class *env_class, struct sobj_env *env, struct sobj *object, struct sobj *selector, struct sobj *args)
 Dispatch a method call using a specified method list.


Define Documentation

#define SOBJ_ENVUTIL_METHOD_MISMATCH   ((struct sobj *)1)
 

Constant indicating a parameter mismatch.

This constant is returned by the sobj_envutil_method_call() or sobj_envutil_call() function to indicate a signature mismatch.


Typedef Documentation

typedef struct sobj* sobj_envutil_method_fn(struct sobj_envutil_method *se_method, struct sobj_env_class *se_class, struct sobj_env *se_env, struct sobj *se_object, struct sobj **se_args)
 

Function type for method callbacks registered in sobj_envutil_method structures.

Parameters:
se_method The method object.
se_class The class environment.
se_env The environment object.
se_object The called object (this).
se_args Vector of argument objects. For variable parameters, a null-pointer is used to indicate a parameter omission.
Returns:
The function should return the result object of the method call, or a null-pointer to indicate an error condition.
Note:
The function may use the environment object for error reporting. If a complete error report was sent to the environment object, the so_error flag should be set. If the function returns null and the so_error flag is clear, a standard error message is sent to the environment object.


Function Documentation

struct sobj_envutil_method* new_sobj_envutil_method const char *  name,
sobj_envutil_method_fn method_callback
 

Create a new instance of a method object.

The method object created is initialized with the specified name and method callback. The reference counter is set to 0.

Parameters:
name The name of the method.
method_callback The method callback function implementing the method.
Returns:
A new instance of a method object.

struct sobj* sobj_envutil_call struct sobj_envutil_method **  method_list,
struct sobj_env_class env_class,
struct sobj_env env,
struct sobj object,
struct sobj selector,
struct sobj args
 

Dispatch a method call using a specified method list.

The function matches the specified method call against a specified method list. If a method with a matching name is found in the list, the function sobj_envutil_method_call() is called. If that call yeilds a result or an error condition, the function assumes that the called method matches the call expression and returns the result to the caller. If the sobj_envutil_method_call() function returns SOBJ_ENVUTIL_METHOD_MISMATCH continues to scan the method list.

Parameters:
method_list The list of methods to be scanned. This is a vector of pointers to sobj_envutil_method objects, terminated with a null-pointer.
env_class The class environment object handling the method call.
env The environment object. This may not be a null-pointer.
object The called object.
selector The selector from the selection expression in the call expression object (second operand of the first operand of the call expression). This has to be a string object without a classname.
args The argument array from the call expression object.
Returns:
The function returns the return value from the matching sobj_envutil_method_call() function call, or the special value SOBJ_ENVUTIL_METHOD_MISMATCH if none of the specified method objects matches the method call.

void sobj_envutil_method_add_prm struct sobj_envutil_method method,
const char *  name,
bool  variable
 

Add a formal parameter to a method object.

The function adds a fixed or variable parameter to the parameter list of the specified method object. It is required that all fixed parameters are added before any variable parameters.

Parameters:
method The method object.
name The name of the method.
variable Flag indicating if the formal parameter added is a fixed or a variable parameter. If variable is true, a variable parameter is added.

struct sobj* sobj_envutil_method_call struct sobj_envutil_method method,
struct sobj_env_class env_class,
struct sobj_env env,
struct sobj object,
struct sobj args
 

Call the specified method object.

The function analyzes the args parameter, which is an assoicative array holding the arguments in the original call expression object. A mix of positional and named arguments is accepted, with the restriction that the positional arguments have to be placed before the named arguments, every fixed parameter must match exactly one positional or named parameter and every variable parameter must match at most one positional or named parameter.

The arguments are ordered in the order of the formal parameters. Unspecified variable parameters are represented by null-pointers.

Parameters:
method The method object.
env_class The class environment object handling the method call.
env The environment object. This may not be a null-pointer.
object The called object.
args The argument array from the call expression object.
Returns:
The function returns the value returned by the method callback function (which is either an sobj pointer or a null-pointer in case of an error), or the special constant value SOBJ_ENVUTIL_METHOD_MISMATCH if the specified args parameter does not match the method signature.
Note:
If the method callback function indicates an error (by returning a null-pointer) and the so_error flag of the environment object is not set by the method callback, then a standard error message is generated and the so_error and so_error_id fields of the environment env are set.


Generated on Sat Jul 23 16:07:33 2005 for sobject by  doxygen 1.3.9.1