Go to the first, previous, next, last section, table of contents.
In order to use GNUstep-Guile, you must link the libgstep_guile library into
your program along with the standard Guile library (libguile) and the
GNUstep foundation library (gstep-base). You will probably also want to
link in the libgg_base library (to ensure that all the Foundation classes
get linked into your application) and possibly the libgg_gui and the gstep_gui
libraries (to get the AppKit classes) and libgg_gdl2 and associated classes
for GDL2 (EOF) support.
If you are using shared libraries (the default) then you probably don't
need to link in libgg_base, libgg_gui or libgg_gdl2 explicitly, and
don't even need to link libgstep_guile, as the guile software can load
these libraries (and the main GNUstel libraries) automatically at runtime.
If this is the case, you can ignore the instructions about linking below,
and just do a
`(use-modules (languages gstep-guile gstep-guile))'
command to load the gstep-guile module. This will autom atomatically
make the GNUstep base library available. To make the gui library
and gdl2 library available
you need to do
`(gstep-gui)' and
`(gstep-gdl2)' to load those libraries.
When you install gstep-guile, a copy of the library is put in the Guile
modules directory so that you can use the guile command
`(use-modules (languages gstep-guile gstep-guile))'
to get it dynamically loaded rather than having to link it into your program
at compile-time. This will not work if you have built the library for
static linking (in which case you need to link the libraries into your
program explicitly).
It is also possible for you to work with other Foundation libraries such as
libFoundation.
This library IS restricted to working with the gcc objc runtime -
unless someone wants to add support for other runtimes.
The library also depends upon an NSMethodSignature extension
available in a gstep-base and in libFoundation. I don't know if
Rhapsody has a similar undocumented extension.
Your program (if static linked) must call the function 'gstep_init()'
to tell the guile library about the gstep_guile stuff.
This should be done near the start of
the 'main' function whose address is passed as the third parameter to
'gh_enter()' when you invoke the guile system. If this means nothing to
you - please read the Guile documentation for information on how to call
guile from within your program.
If you want to have the OpenStep foundation `C' functions and constants
available (as well as all the classes in the OpenStep foundation library -
rather than just those used in your Objective-C program) you will also
need to call 'gstep_link_base()' immediately after calling 'gstep_init()'
and link your program with the 'gg_base' library. If you do not do this
then the only foundation classes available to Guile will be those that you
have used in your main program (plus a few used internally by the gstep-guile
library).
Similarly, if you want to have the OpenStep appkit `C' functions and
constants available (as well as all the classes in the OpenStep appkit
library - rather than just those used in your Objective-C program) you
will also need to call 'gstep_link_gui()' and link your program with the
'gg_gui' library. If you do not do this then the only appkit classes
available to Guile will be those that you have used in your main program.
Once you have a working program, you will probably want to load in some
definitions of guile procedures and macros which make it easy to use the
facilities in gstep_guile. This distribution includes a Guile module
file ('gstep-guile.scm') which is placed in the standard modules directory
so that you can use it with `(use-modules (languages gstep-guile))'.
To aid in using gstep-guile from within your Objective-C programs, some parts
of the gstep-guile library are made available as external symbols so that you
can call functions from C/ObjectiveC in much the same way that you would do
things from within Guile.
The minimum you need to know is that you need to call `gstep_init()'
before starting the Guile system, and `gstep_link_base()' if you need
full access to the OpenStep foundation.
Other functions you can call from ObjectiveC (declared in gstep_guile.h) are -
-
`SCM gstep_id2scm(id obj, BOOL shouldRetain);'
This function creates a scheme object encapsulating the ObjectiveC object
`obj'. If a scheme object already exists for this encapsulation, the
existing object is returned. The `shouldRetain' flag is used to specify
whether the object has already been retained or not.
If `shouldRetain==YES' then the ObjectiveC object is retained unless an
existing scheme object is being returned.
If `shouldRetain==NO' then the object is assumed to already be retained
and will not be retained again. Either way, the ObjectiveC object will be
released when the scheme object is garbage collected.
-
`id gstep_scm2id(SCM obj);'
This function returns the ObjectiveC object encapsulated by the scheme object
`obj'.
-
`void gstep_fixup_id(SCM obj);'
This function converts the scheme value encapsulating an ObjectiveC object to
one containing the 'nil' object. The retain count for the object being
removed is not modified. You might use this if your code had
destroyed the ObjectiveC object, and you need to make Guile aware that the
object has gone away. Normally, you should not need to use this!
`obj'.
-
`SCM gstep_scm_id_p(SCM obj);'
This function returns a scheme boolean (#t or #f) depending on whether the
scheme object `obj' encapsulates an ObjectiveC object or not.
-
`int gstep_id_p(SCM obj);'
This function returns a C integer (1 or 0) depending on whether the
scheme object `obj' encapsulates an ObjectiveC object or not.
-
`SCM gstep_voidpscm(voidp* ptr, BOOL malloced, BOOL lenKnown, int len);'
This function creates a scheme object encapsulating the pointer to a memory
location `ptr'.
The `malloced' flag is used to specify if the area of memory pointed
to has been allocated using malloc() (in which case it will be freed when the
scheme object is garbage collected).
The `lenKnown' flag is used to say if the length of the area of memory
is known. If the length is known, the `len' value is stored as part of
the scheme object and the library is able to perform boundary checking when
storing data into and reading data from the area of memory. You should always
tell the library the length if you can - to do otherwise risks a crash if
you try to access unallocated memory through the pointer.
If you are creating a handle to some C data structure that is merely to be
passed as input to some methods or functions, you should create it as having
a known length of zero. This will prevent any attempts to write into it
from within Guile
-
`void* gstep_scm2voidp(SCM obj);'
This function returns the pointer to void encapsulated by the scheme object
`obj'.
-
`int gstep_scm2voidplength(SCM obj);'
This function returns the length of the area of memory pointed to by the
voidp scheme object. If the length is not known, this function returns -1.
-
`SCM gstep_scm_voidp_p(SCM obj);'
This function returns a scheme boolean (#t or #f) depending on whether the
scheme object `obj' encapsulates a pointer to abstract memory or not.
-
`int gstep_voidp_p(SCM obj);'
This function returns a C integer (1 or 0) depending on whether the
scheme object `obj' encapsulates a pointer to memory or not.
-
`int gstep_voidp_p(SCM obj);'
This function returns a C integer (1 or 0) depending on whether the
scheme object `obj' encapsulates a pointer to memory or not.
Once you have linked gstep-base and gstep_guile into your program
(if necessary) and have loaded the gstep-guile module (using the
`(use-modules (languages gstep-guile))' command),
you can start programming with GNUstep objects from within Guile.
Gstep-guile provides you with a selection of primitives, macros and procedures
to perform basic Guile to Objective-C interaction, and also provides some
specific facilities to help you use the OpenStep libraries.
-
The classes defined in the OpenStep Foundation API are defined as Guile
variables so that you may use them directly. This definition is performed
in link_base.m, and should automatically be available.
-
The numeric constants used by the OpenStep Foundation API are defined as
Guile variables so that you may pass them to objc methods. This definition
is performed in link_base.m, and should automatically be available.
-
The string constants used by the OpenStep Foundation API are defined as
Guile variables so that you may pass them to objc methods. This definition
is performed in link_base.m, and should automatically be available.
-
Most of the functions used by the OpenStep Foundation API are defined as
Guile primitives. Their definitions are performed in link_base.m, and
should automatically be available.
-
If the GNUstep GUI library was available on the system where gstep-guile
was configured and built, you can use
`(gstep-gui)' to dynamically link that library and make its classes
and constants available for use.
-
If the GNUstep GDL2 library was available on the system where gstep-guile
was configured and built, you can use
`(gstep-gdl2)' to dynamically link that library and make its classes
and constants available for use.
-
The new type `voidp' permits pointers to be passed to and from
Objective-C methods. You can use this to work with `NSData' objects.
The GNUstep-Guile library provides the following primitives -
-
`(gstep-msg-send receiver method args)'
is used to send a message to an object. It takes two or more arguments, the
first is the object to which the message is to be sent, the second is a string
which is the name of the method (the selector), and subsequent arguments are
the arguments to be sent.
-
`(gstep-sup-send receiver method args)'
is used to send a message to an object specifying that the superclasses
implementation of the method should be executed. It takes two or more
arguments, the first is the object to which the message is to be sent,
the second is a string which is the name of the method (the selector),
and subsequent arguments are the arguments to be sent.
This is intended for use within guile procedures which implement methods
of objc clases ... to allow them to invoke the corresponding methods in
superclasses.
-
`(gstep-ivarnames obj)'
is used to return a list of the names of the instance variables of the
object `obj'.
NB. If `obj' is a class, this procedure returns a list of the names
of the instance variables of an object of that class.
-
`(gstep-get-ivar obj name)'
is used to return the value of the instance variable `name' in the
object `obj'. The object must be an instance, not a class.
-
`(gstep-ptr-ivar obj name)'
is used to return a voidp which points to the instance variable `name'
in the object `obj'. The object must be an instance, not a class.
-
`(gstep-set-ivar obj name value)'
is used to change the value of the instance variable `name' in the
object `obj'. The object must be an instance, not a class.
The procedure returns true on success, false on failure.
-
`(gstep-new-class name super variables instance-methods class-methods)'
is used to create a new Objective-C class. The new class will have the name
`name' and will inherit from the super-class `super'.
NB. The super class MUST be NSObject or one of it's descendents.
The `variables' parameter is a list of instance variable specifications.
The `instance-methods' parameter is a list of instance method specifications.
The `class-methods' parameter is a list of class method specifications.
A variable specification is a pair of values -
a string giving the variable name,
and a string giving the variable type.
A method specification is a list of three items -
a string giving the method name,
a string giving the method type specification,
and a procedure to be called when the method is invoked.
The procedure will be invoked with three arguments - the object for which it
was called, the method name by which it was called, and a list containing
the arguments sent to it.
Permissible types are -
- `@' id
- `#' Class
- `:' SEL
- `c' char
- `C' unsigned char
- `s' short
- `S' unsigned short
- `i' int
- `I' unsigned int
- `l' long
- `L' unsigned long
- `f' float
- `d' double
- `*' char* (string)
- `v' void (only valid as the return type)
The type specification for a variable consists of one of the above types
(excluding void).
The type specification for a method is a string consisting of a return
type specification followed by parameter type specifications, the first
two of which must be `@' to denote an object, and `:' to denote
a selector.
In addition to the above type specifications, a structure type may be
specified as a sequence of the above types (excluding void) enclosed in
curly brackets -
eg. {iicc} specified a structure consisting of two integers and two
characters.
You may use the prefix `^' where what you actually want is a pointer
to an item of the type. When passing a pointer as a method argument, you
must supply a `voidp' item which points to data of the correct type.
When a pointer type result is returned by a method, you will get a
`voidp' item returned.
-
`(gstep-methods obj)'
is used to return a list of the types and names of the methods of the
object `obj'.
NB. If `obj' is a class, this procedure returns a list of the class
methods, otherwise it returns the instance methods.
-
`(gstep-class-methods name methods)'
is used to add class (factory) methods to an existing class, where `name'
is the name of the class and `methods' is a list of method specifications
as in `gstep-new-class'.
-
`(gstep-instance-methods name methods)'
is used to add instance methods to an existing class, where `name' is the
name of the class and `methods' is a list of method specifications as in
`gstep-new-class'.
-
`(gstep-id? datum)'
is used to test whether a guile data object is an objective-c object.
-
`(gstep-get-nil)'
is used to return the `nil' object. This is typically used to test
for equality against the value returned by `gstep-msg-send'.
Upon library initialisation, gstep-guile defines a top-level variable
'gstep-nil' to this value, so you should not need to use this primitive
directly.
-
`(gstep-lookup-class name)'
is used to lookup a class whose name matches the string or symbol it is
given. If a class of the specified name exists, it is returned, otherwise
the procedure returns `nil'.
-
`(gstep-lookup-protocol name)'
is used to lookup a protocol whose name matches the string it is given.
If a protocol of the specified name exists, it is returned, otherwise
the procedure returns `nil'.
-
`(gstep-class-names)'
is used to return the names of all existing objective-c class objects.
-
`(gstep-protocol-names)'
is used to return the names of all existing objective-c protocol objects.
-
`(gstep-id->voidp obj)'
is used to create a voidp item from an objective-c object so that the
object can be passed to functions and methods that expect abstract pointers.
NB. The original objective-c object is still 'owned' by guile and may be
garbage collected, leaving the new voidp item with a bad memory reference,
so you must be VERY careful using this procedure.
-
`(voidp-gstep-id ptr)'
is used to convert an abstract pointer to an objective-c object under
guiles management. The voidp MUST point to an objective-c object before
you use this.
-
`(string->voidp string)'
is used to copy the Guile string into a newly created `voidp' data
item so that it can be passed to an Objective-C method expecting a pointer
as an argument.
-
`(voidp? item)'
is used to test to see if a guile data item is actually a pointer to raw
data (a `voidp').
-
`(voidp->set! item, offset, string)'
is used to copy the Guile string into an existing `voidp' data item
at the specified byte offset. If the length of the `voidp' item is
known then range checking will be performed - otherwise this can be used
to trash memory!
-
`(voidp->string item offset length)'
is used to create a new Guile string using 'length' bytes of data from
'offset' in the region of memory pointed to by the `voidp' 'item'.
If the length of the `voidp' item is known then range checking will
be performed - otherwise this can cause an illegal memory access!
-
`(voidp-length item)'
is used to return the length of the memory buffer pointed to by the
`voidp' item. If the length of the data area is not known then
value returned by this is undefined.
-
`(voidp-length? item)'
returns #t if the length of the area of memory pointed to by 'item' is
known, #f otherwise.
-
`(voidp-set-length! item length)'
may be used to change the information about the length of the data pointed
to by 'item'. If you are given a `voidp' item by the Objective-C
system, you should use this primitive to set the length of the data it
has given you (assuming you know this), so that range checking may be performed.
-
`(voidp-malloc? item)'
returns #t if the area of memory pointed to by 'item' is known to have been
allocated using malloc, and the Guile system is free to deallocate it when
the `voidp' item is garbage-collected.
-
`(voidp-set-malloc! item flag)'
may be used to change the information about whether the Guile system should
deallocate the buffer pointed to by 'item' when 'item' is garbage-collected.
You may want to do this if you have 'passed ownership' of the memory to the
Objective-C world.
-
`(voidp-nil)'
Returns a pointer to the nil address (zero).
-
`(voidp->list item type length)'
Attempts to treat the data pointed to by `item' as an array of
`length' data items of type `type'. These items are converted
to Guile data items and returned in a list.
-
`(list->voidp type)'
This treats `list' as a list of data items (all of which should be the
same type) to be converted into an array of Objective-C data items.
The conversion is done using the type information string `type' and the
resulting array is returned as a `voidp'
The scheme source file 'gstep-guile.scm' implements a Guile module which
provides you with scheme procedures and macros to make better use of the
primitives provided by the library -
-
`([] receiver method-and-args)'
is used to send a message to 'receiver', which may be either an object or a
string naming a class. Everything following 'receiver' and before the closing
bracket is used like a normal objc method and arguments list.
-
`(gstep-send receiver method-and-args)'
is just like `[]' except that, if `receiver' is neither a string
nor a variable bound in the top-level environment, it will be treated as
the name of a class - and class lookup will be automatically be performed
before it is used.
-
`($$ string)'
is a shorthand way of creating an NSString object from the supplied guile
string.
This is equivalent to `([] "NSString" stringWithCString: string)'
-
`(gstep-nsstring->string string)'
is a shorthand way of creating a Guile string object from the supplied
NSString object.
-
`(string->gstep-nsstring string)'
is another way of creating an NSString object from the supplied guile
string.
-
`(gstep-nsstring string)'
Convert from an NSString object to a Guile string or vice versa.
-
`(gstep-nsstring? string)'
Check to see if an object is an instance of NSString.
-
`(gstep-class name)'
is a simple wrapper for gstep-lookup-class.
-
`(gstep-protocol name)'
is a simple wrapper for gstep-lookup-protocol.
-
`(selector name)'
lets you pass a selector to a method - actually this just converts the
symbol `name' into a string.
-
`(gstep-bool? val)'
Checks to see if the value given is an OpenStep boolean (integer 0 or 1).
-
`(gstep-bool val)'
Converts between OpenStep boolean and Guile boolean values.
-
`(gstep-bool->bool val)'
Converts an OpenStep boolean (integer value) to a Guile boolean.
-
`(bool->gstep-bool val)'
Converts a Guile boolean to an OpenStep boolean (integer value).
-
`(NSMakeRange location length)'
Creates a list containing the specified location and length - suitable for
passing to methods expecting NSRange structures.
-
`(NSRange-length range)'
Returns the length element of the specified range.
-
`(NSRange-location range)'
Returns the location element of the specified range.
-
`(NSRange-setLength! range length)'
Sets the length element of the specified range.
-
`(NSRange-setLocation! range location)'
Sets the location element of the specified range.
The passing of standard `C' data types is by value - so the data is
actually copied from a guile data item to a `C' one as it is passed
into the objc world and is copied from the `C' data item to a guile
on when it is returned to the guile world.
There are two exceptions to this, the objc object - these are always passed
as pointers (by reference), and other pointers such as pointers to arrays
and abstract data - these are passed as `voidp' items.
Within the guile world, objc objects are first-class data items -
gstep-guile adds a guile data type which encapsulates a pointer to an objc
object and is the equivalent of the 'id' type in objc.
When an object is passed from the guile world to the objc world, the pointer
to the objc object is unwrapped from the guile data item and passed.
When an object is passed from the objc world to the guile world, a guile
data item is created to wrap it.
Gstep-guile also adds the `voidp' data type which is used to pass
abstract pointers to data between the Objective-C and Guile worlds.
An Objective-C method which expects a pointer (other than a string or
object) as an argument must be passed a `voidp' item.
An Objective-C method which returns a pointer (other than a string or
object) will return it as a `voidp' item.
The `voidp' type is used to encapsulate arbitrary pointers to data
(usually arrays of other types). Primitives are supplied to manipulate
`voidp' items - conversion to/from Guile strings and lists of
Guile objects.
There is essentially a single mechanism for passing data from one world
to the other - the `gstep-msg-send' primitive.
The `C' data types `char', `unsigned char', `short',
`unsigned short', `int', `unsigned int', `long', and
`unsigned long' all appear in the guile world as numbers.
The numeric constants used by the OpenStep API are defined as Guile variables
when gstep-guile is initialised, so that you may pass them to objc methods.
These constants are compiled into link_base.m and you will need to modify
that file if I have missed any.
Guile strings are copied into standard `C' strings in the objc world and
`C' strings are copied into guile strings when they are passed back to
the guile world.
The string constants used by the OpenStep API are defined as Guile variables
when gstep-guile is initialised, so that you may pass them to objc methods.
These constants are compiled into link_base.m and you will need to modify
that file if I have missed any.
Objc structures are represented as lists in the guile world, with nested
structures being represented as lists of lists. I chose the list
representation rather than guiles structure data type because guile
structures seemed to offer little advantage over lists and are less
obvious to someone coming from a lisp or scheme programming background,
also, guile provides a richer set of primitives for manipulating lists
than it does for structures.
For instance
`([] str rangeOfString: sub)' invokes the `rangeOfString:' method
to find the substring `sub' in the string `str' and return an
NSRange structure describing the substring found. The NSRange structure
consists of two integers, so the actual value returned in the guile world
is a list containing two numbers. The order of the values in the list is
the same as the order of the values in the structure.
Go to the first, previous, next, last section, table of contents.