[View]  [Edit]  [Lock]  [References]  [Attachments]  [History]  [Home]  [Changes]  [Search]  [Help] 

[S8] Builders and wrapping native objects

Access to native objects is implemented as a minimal set of extensions to Smalltalk syntax (see [S8] Extensions to Smalltalk syntax).
So direct access is as simple and transparent as using the correct expression to lookup for a native object or calling native functions as native message sends.
As each native access means writing source code, it is reccomended to implement wrappers to access native objects, API libraries and modules provided by host environment.

The Builders framework

The "Builders" framework is valuable when implementing big API interfaces and libraries.
The main goal of Builders is to avoid typing and semantic errors when implementing an API.
Years of experience using Smalltalk to interface operating system objects is condensed in the Builders framework.
Using builders is more powerful that hiding complexity using primitives; and is more productive than using "magic" tools than hides non debuggable code.

The builders generate methods using S8 Smalltalk extension syntax from a collection of literals specifying an API/protocoll/library.
The code generated is normal S8 code and NOT dependent on the platform you are running; so you can generate code in one platform to be run in another platform (e.g. you can implement classes in windows console mode to be run in Android or Raspberry Pi using Lua VMs).
The code is NOT dependent on the VM your objects are running, so the same classes (.st source) can be compiled for diferent VMs to access the same O.S. objects (e.g. you can use the same .st file for android applications running on top of node.js or Lua VMs, accessing Java objects transparently).

Using builders

The Builders framework implements messages starting with #build...
To learn more on what/where the framework provides support, search for references of messages starting with #build (Open the References in U8 and search with option "searchSource:" for string "build").
There is two places where Builders are used in a clean S8 environment
  1. Behavior support - see Builders.st
  2. NativeObject support - see Natives.st

Behavior support

Browse category "Builders-api" in Behavior, instance side.
The builders there implement basic methods for accessing instance variables.

NativeObjects and Libraries

The class NativeObject implement a basic wrapper to a native object.
It is reccomended to subclass NativeObject for each species of native object you want to interact with.
The class side methods in NativeObject under category "builders" implement accessors common interfaces to native instances.
Getter and setters are used to access properies at native layer; and calls are transfermed to common messages to the wrapper instance.

Extending the framework

To learn how to use the framework see the implementation of libraries and packages in your platform.
A list of use cases follows, browse the sources in the following files to learn how to implemenet interfaces to native objects/libraries/API,etc