ObjNL.lsp

Module index

Module: ObjNL

Objective newLISP - Real Object Oriented Programming for newLISP

Version: 1.0
Author: Greg Slepak
Location: http://www.taoeffect.com/newlisp/ObjNL.lsp.txt

Introductory Guide

The official guide is highly recommended reading if you are planning on using Objective newLISP.

What is Objective newLISP?

Objective newLISP is a new and exciting way of doing real object oriented programming in newLISP where instances are passed by reference and can easily hold references to other objects while maintaining their own mutable state.

It supports most of the object oriented concepts you'll find in other languages. It supports inheritance, interfaces (aka protocols), as well as class and instance variables.

Objects are passed by reference, so there's no problem with passing an object through multiple user-defined functions and modifying it.

Accessing instance variables no longer requires a function call plus a list traversal. Simply access the symbol directly.

Objective newLISP also enhances newLISP by providing convenient and safe macros for deep reference access.

With Objective newLISP it is possible to take full advantage of everything object-oriented programming has to offer.

Conventions

There are very few conventions in ObjNL, but there are some:

• Classes should be written in camel-case and begin with a capital letter.
• ObjNL reserves the @ character for itself to prefix symbols of special meaning. You should avoid prefixing your symbols with it if possible.

Requirements

newLISP 10.1.9 or higher is strongly recommended, but any version after 10.1 should work.

Version history

1.0 • initial release

- § -

ObjNL

syntax: ObjNL

ObjNL is the root class for Objective newLISP. All other classes ultimately inherit from it. It defines several instance and class variables:

• @self to refer to the current object (be it an instance or class).
• @self-sym is the symbol that represents the @self context.
• @class is the context representing the class this object belongs to.
• @super refers to the super-class of this object.
• @interfaces a list of interfaces that this object conforms to.
• @rc an integer representing the retain count of this object.

- § -

ObjNL:ObjNL

syntax: (ObjNL:ObjNL)

The constructor is the default function. It is called by instantiate.

The default implementation simply returns true.

- § -

ObjNL:dealloc

syntax: (ObjNL:dealloc)

Called by deallocate to give the object an opportunity to release resources and objects.

- § -

ObjNL:equals

syntax: (ObjNL:equals ctx-obj)

Provides a method for classes to define what it means for objects to be equal.

The default implementation returns true if two objects are the same instance.

- § -

new-class

syntax: (new-class sym-class [ctx-super [list-interfaces]])
parameter: sym-class - The name of the class
parameter: ctx-super - The superclass, accessible through @super
parameter: list-interfaces - Any contexts to "mixin", accessible through @interfaces

return: The context of the new class created.

- § -

instantiate

syntax: (instantiate ctx-class [arg-1 ...])

Returns a new instance of ctx-class by calling its constructor and passing in any arguments. If the constructor returns nil then the instance is deallocated and nil is returned.

The returned object must be deallocated using the deallocate function.

- § -

add-interface

syntax: (add-interface ctx-iface ctx-obj)

Uses the function new to add ctx-iface to the object and adds the interface to ctx-objs @interfaces.

- § -

deallocate

syntax: (deallocate ctx-obj)

Calls the objects dealloc method and then delete's the object.

NOTE: On versions of newLISP prior to 10.1.9 this is a fairly slow operation, make sure to use at least version 10.1.9 with Objective newLISP.

- § -

implements?

syntax: (implements? ctx-interface ctx-obj)

return: true or nil as to whether this ctx-obj implements ctx-interface.

- § -

retain

syntax: (retain ctx-obj)

Increment's ctx-obj's retain count and returns the object.

- § -

release

syntax: (release ctx-obj)

Decrement's ctx-obj's retain count. Deallocates the object if the retain count hits zero.

- § -

autorelease

syntax: (autorelease ctx-obj)

Adds ctx-obj to the current MAIN:@autorelease pool and returns the object.

- § -

push-autorelease-pool

syntax: (push-autorelease-pool)

Pushes a new autorelease pool onto the MAIN:@autorelease stack.

- § -

pop-autorelease-pool

syntax: (pop-autorelease-pool)

Pops the current MAIN:@autorelease pool and releases the objects in it.

- § -

.

syntax: (. obj field-1 [field-2 [field-n]])

The dot macro is used for "deep value access":

example:

 (new-class 'Foo)
 (new-class 'Bar)
 (context Bar)
 (define (Bar:Bar f)
 	(setf foo f)
 	true ; -> do not deallocate us if 'f' is nil
 )
 (context Foo)
 (define (Foo:Foo b)
 	(setf bar b)
 	true ; -> do not deallocate us if 'b' is nil
 )
 (context MAIN)
 (setf f (instantiate Foo (instantiate Bar)))
 (set (.& f bar foo) f) ; => Foo#1
 (. f bar foo bar)      ; => Bar#1

- § -

.&

syntax: (.& obj field-1 [field-2 [field-n]])

The dot-reference macro is similar to the dot macro, except it returns the context-qualified symbol for the final field instead of its value ("deep symbol access"). This allows you to combine it with set.

see: '.' macro for example usage.


- ∂ -
generated with newLISP  and newLISPdoc