Scripting support

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

For applications, there are two possibilities, to make them scriptable. One is custom, that means, that you have to create scripting mechanisms by yourself. The other is automatic, where the developer only needs to add few lines of code and several menu items to his application.

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"]

Automated scripting in applications

StepTalk provideas a bundle that allows users to 'script' their applications automatically. With this bundle, it instantly allows users of the application to:

• extend the behaviour of application by adding their own functionality
• automate tasks in the application
• create a batch task

The Application Scripting bundle is installed together with StepTalk. Note: the bundle needs a refresh, as it is quite out-dated.

Creating a scriptable application

As usual, first think of objects you want to provide for scripting. Then create ScriptingInfo.plist file as described above. For example a file for a Mail application would be:

{
    STClasses =
    (
        MessageComposition,
        InternetAddress
    );
}

Use the Project Center application to include the file or put this line to your makefile:

MyApp_RESOURCE_FILES = ScriptingInfo.plist

Then include the bundle loading code. Copy files STScriptingSupport.h and STScriptingSupport.m from ApplicationScripting/Support directory to your project and add them to your project or add the following line to your makefile:

   MyApp_OBJC_FILES += STScriptingSupport.m

Funally, make scripting available to the user:

   #import "STScriptingSupport.h"
   ...
       if([[NSApp isScriptingSupported])
       {
           [[menu addItemWithTitle: @"Scripting"

action: NULL

                    keyEquivalent: @""];

           [[menu setSubmenu: [[NSApp scriptingMenu]
                    forItem: menu itemWithTitle:@"Scripting";
       }
   ...

Note: what is needed to do that with Gormin a simple way?

The scripts

See: Script management