Scripting support

From GNUstepWiki
Revision as of 08:29, 18 February 2005 by Stefan Urbanek (talk | contribs)
Jump to navigation Jump to search

Introduction

Note: if something is not clear, add questions under the discussion tab or ask the author directly.

To make a tool or an application scriptable you need to prepare:

  • objects for scripting
  • scripting context
  • mechanism for script execution


Objects to be used for scripting

What do you offer to users? What should users customise? What should users talk to? As scripting deals with objects, you need to think about the objects you would like to make available to the user.

It is up to developer to prepare a list of object names and ways of getting the objects.

Scripting context or environment

Like on our speech, we use references to object without any closer specification. How we do know what objects wer are refering to? From the conversation context. It is similar in the scripting language.

A simple context contains a map (or a dictionary, if you like), of object names and actual objects. Related classes: STContext or STEnvironment.

Creating scripting environment

To prepare a scripting environment.

#import <StepTalk/STEnvironment.h>

STEnvironment *environment;

environment = [STEnvironment environmentWithDefaultDescription]

or

description = [STEnvironmentDescription descriptionWithName:name]
environment = [STEnvironment environmentWithDescription:description];

Environment serves besides other things also like namespace for objects and you have to register all objects that you would like to have accesible by name:

[environment setObject:object forName:@"ObjectName"];

like in:

[environment setObject:MyApplication forName:@"Application"];


Executing a script

One way to execute scripts is by using a 'conversation' objects. Conversations are made in a environment and using specified language. The language may change during scripting conversation.

#import <StepTalk/STConversation.h>

conversation = [STConversation conversationWithEnvironment: environment language: @"Smalltalk"];

To get names of all available languages use [STLanguage allLanguageNames] and to get the name of the default language use [STLanguage defaultLanguageName].

Now when you have opened a conversation in an environment you can run the script string. It is better to guard the execution with an exception handler:


id        result;

NS_DURING
    result = [conversation runScriptInString:string];
NS_HANDLER
    /* handle an exception */
NS_ENDHANDLER


Note: the result handling will change in future StepTalk releases. The result will be no more returned by the direct execution message, byt you will need to request the result separately. There are several reasons for that, including better handling of remote scripting environments (long distance conversations).

To change a language of script conversation, just use:

 [conversation setLanguage:@"ObjectiveC"]