Objective-Everything Release 5.  Copyright ©1994-1998 by TipTop Software, Inc.  All Rights Reserved.

  Integration with C

Objective-WebScript facilitates integration of the WebScript language with compiled C code and data structures. C symbols are accessible from WebScript by sending a message to the C global variable, or to the TTCDatum class.

The Objective-Everything system maintains a global table of type names and symbol names.  When the system starts up, it loads these tables from the module directories of each module that is loaded: Mod.framework/Resources/Mod.cfun, where, Mod is ObjCore, ObjAppKit, ObjWebScript, ObjTcl, ObjPy, etc.  See CFun in the "Resource Files" section for detail.  In addition, any user-specific definitions provided in ~/.AppInfo/Objective/User.cfun will be automatically loaded at startup as well.  At runtime, you can load any additional definitions.

NOTE: ObjWebScript gives you full and unrestricted access to C.  Although ObjWebScript by default does check for invalid memory access and such, just like in C, be careful not to crash the system.

All of the examples below are executed in an AppKit interactor.  To run an AppKit interactor, simply double-click on ObjShell.app.  This is relevant only because some examples below operate on the $NSApp object which is non-existent or nil if the appkit is not running, or invoke the NSRunAlertPanel() function.

Type System

In Objective-WebScript, you use the standard C/ObjC syntax to specify types.  All C/ObjC types are supported.

[TTInterp cdefine:"stuff.."]

Declare/define C stuff, i.e., types, functions, globals, classes, categories, protocols, etc., using the C/ObjC syntax.

Example:

wos% [TTInterp cdefine:"
%--> struct mystruct { 
%-->   int anInt; 
%-->   double aDouble; 
%-->   id anObject; 
%-->   char *aString; 
%-->   NSArray *anArray; 
%--> }; 
%--> typedef struct mystruct *xyz; 
%--> double cos(double); 
%--> extern int errno; 
%--> "];

This registers "struct mystruct" and type "xyz" in the global C type table.  It also registers function "cos" and global "errno" with the specified prototypes in the global symbol table.

TTCType class

+ ctypeWithTypeString:(NSString*)name;

Returns an autoreleased type object for the C-syntax type name.

+ ctypeWithEncoding:(const char *)enc;

Returns an autoreleased type object for the ObjC encoding enc.

- (NSString*)typeString;

Returns C-syntax representation of the represented type.

- (const char *)encoding;

Returns ObjC encoding of the represented type.

- (NSString*)expandedTypeString;

Returns C-syntax representation of the represented type. The representation is expanded as much as possible.

- (NSString*)prettyTypeString;

Returns the "prettyfied" C-syntax representation of the represented type.

- (int)typeSize;

Returns the byte size of the represented type.

- (int)typeAlignment;

Returns the byte alignment of the represented type.

- (TTCDatum*)datumMalloc:(int)count;

Allocates a datum of the receivers type from the memory heap, and returns the autoreleased datum object.

- (void)defineTypeName:(NSString*)name;

Defines the represented type to be accessible via name. This is equivalent to typedef in C.

Example:

wos% id t=[TTCType ctypeWithTypeString:"NSRect"];
wos% t.typeString();
"NSRect"
wos% [interp printf:"%@\n",t.expandedTypeString()];
struct {
  struct {
    float x;
    float y;
  } origin;
  struct {
    float width;
    float height;
  } size;
}
nil
wos% t.encoding();
"{?=\"origin\"{?=\"x\"f\"y\"f}\"size\"{?=\"width\"f\"height\"f}}"

wos% id t2=[TTCType ctypeWithTypeString:"struct mystruct"];
wos% t2.defineTypeName("mystruct_t");
nil
wos% [[TTCType ctypeWithTypeString:"mystruct_t"] encoding];
"{mystruct=\"anInt\"i\"aDouble\"d\"anObject\"@\"aString\"*\"anArray\"@}"
wos% t2.encoding()
"{mystruct=\"anInt\"i\"aDouble\"d\"anObject\"@\"aString\"*\"anArray\"@}"
wos% t2.expandedTypeString();
"struct mystruct {\n  int anInt;\n  double aDouble;\n  id anObject;\n  STR aString;\n  id anArray;\n}"
wos% t2.typeSize();
24

C Data

The TTCDatum class is used to represent C data.  Internally C datum has two properties: type and address.

TTCDatum class

+ cdatumWithName:(NSString*)name;

Returns an autoreleased datum object corresponding to the global symbol name.

+ cdatumWithEncoding:(const char *)enc atAddress:(void *)addr;

Returns an autoreleased datum object corresponding to C datum at address addr with ObjC encoding enc.

+ cdatumWithCDatum:(TTCDatum*)datum;

Returns an autoreleased copy of datum.

+ cdatumForObject:(id)obj;

Returns an autoreleased datum object corresponding to arbitrary object obj.

Example:

wos% id d;
wos% d=[TTCDatum cdatumForObject:[NSApplication sharedApplication]];
<TTCDatum: ^{?="isa"#"_nextResponder"...}@0x...>
wos% [interp printf:"%@\n", [d typeString]];
struct {
  Class isa;
  id _nextResponder;
  NSEvent* _currentEvent;
  NSMutableArray* _windowList;
  id _keyWindow;
  id _mainWindow;
  id _delegate;
  ...
}
nil
+ cdatumForString:(NSString*)string;

Given a string representation of a datum, returns a datum object.

Example:

wos% d=[TTCDatum cdatumForString:"NSApp"];  // The NSApp global
<TTCDatum: NSApp>
wos% d=[TTCDatum cdatumForString:"^i@0x0"];  // Pointer to integer at NULL address.
<TTCDatum: ^i@0x0>
- (void*)address;

Returns the datum address.

- (unsigned long)addrOf;

Returns the datum address as an unsigned integer value.

- (const char *)encoding;

Returns ObjC encoding of the datum's type.

- (TTCType*)ctype;

Defines the represented type to be accessible via name. This is equivalent to typedef in C.

- (NSString*)typeString;

Returns C-syntax type description of the datum's type.

- (int)sizeOf;

Datums byte size.

- (void)defineDatumName:(NSString*)nm;

Defines the datum to be accessible via name. This is equivalent to defining a global variable or extern function in C.

Invocation and Value access

- (id)callWithCount:(int)count arguments:(id*)args;

If the datum represents a C function, invoke the function with provided arguments.

Note that registered functions can be directly invoked using the ObjC-syntax as follows:

[TTCDatum function_name:arg0 :arg1 :arg2 :...];
- (id)fetch;

Retrieves the value from the memory location, provided that the datum represents a C datum in memory.

- (id)valueForKey:(NSString*)key;

Similar to fetch, except that you can use key to specify a "."-separated path to a subdatum. Each element of the path can be:

&
the datum itself
*
dereferences the datum.
name
accesses element name of the structure or union datum.  name must be a valid element name for the structure/union.
i
where i is an integer. pointer datum: dereferences the datum at the offset. array datum: access the i-th array element. structure/union datum: access i-th struct/union element.
- (void)store:(id)val;

Stores the value into the datum's memory location.

- (void)takeValue:(id)val forKey:(NSString*)key;

Similar to store:, except that you can use key to specify a "."-separated path to subdatum, as described in -valueForKey:.

Allocation, deallocation, offset

- (void)datumRealloc:(int)count;

Reallocates pointer datum to hold count items of its type.

- (void)datumFree;

Frees memory allocated for the datum.

- (void)datumOffset:(int)idx;

Pointer arithmetic: offset pointer datum address.

Type Conversion

WebScript uses the "everything is an object" type model.  The WebScript's default type conversion mechanism is used for converting arguments when a message is sent.  However, when you invoke a C-function or fetch/store a TTCDatum, the Objective-Everything type conversion is used which is a superset of the default WebScript conversion.


[previous][contents][next]