Difference between revisions of "Scripting support"

From GNUstepWiki
Jump to navigation Jump to search
 
(6 intermediate revisions by 2 users not shown)
Line 10: Line 10:
  
 
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.
 
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.
 +
 +
In brief, to add scripting you have to do:
 +
 +
# set-up and provide a scripting context/environment ([[STContect]] or [[STEnvironment]])
 +
# prepare a conversation with the environment ([[STConversation]])
 +
# use the conversation to execute a script in a scripting language
  
 
=== Objects to be used for scripting ===
 
=== Objects to be used for scripting ===
Line 55: Line 61:
 
  conversation = [STConversation conversationWithEnvironment: environment language: @"Smalltalk"];
 
  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].
+
To get names of all available languages:
 +
 
 +
STLanguageManager *languageManager;
 +
NSArray *languages;
 +
NSString *defaultLanguage;
 +
 +
languageManager = [STLanguageManager defaultManager];
 +
 +
languages = [languageManager availableLanguages];
 +
defaultLanguage = [languageManager defaultLanguage];
 +
 
  
 
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:
 
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:
Line 61: Line 77:
  
 
  id        result;
 
  id        result;
+
 
 
  NS_DURING
 
  NS_DURING
    result = [conversation runScriptInString:string];
+
    [conversation interpretScript:string];
 +
    result = [conversation result];
 
  NS_HANDLER
 
  NS_HANDLER
    /* handle an exception */
+
    /* handle an exception */
 
  NS_ENDHANDLER
 
  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).''
+
''Note: the result handling will change in future StepTalk releases. The result will be no longer be returned by the direct execution message, but instead will need to be requested separately. There are several reasons for this change, including better handling of remote scripting environments (long distance conversations).''
  
 
To change a language of script conversation, just use:
 
To change a language of script conversation, just use:
  
 
   [conversation setLanguage:@"ObjectiveC"]
 
   [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"]];
 +
        }
 +
    ...
 +
 +
''FIXME: what is needed to do that with [[Gorm]] in a simple way?''
 +
 +
=== The scripts ===
 +
 +
See: [[Script management]]
  
 
[[Category:Scripting]]
 
[[Category:Scripting]]

Latest revision as of 11:36, 17 September 2005

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.

In brief, to add scripting you have to do:

  1. set-up and provide a scripting context/environment (STContect or STEnvironment)
  2. prepare a conversation with the environment (STConversation)
  3. use the conversation to execute a script in a scripting language

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:

STLanguageManager *languageManager;
NSArray *languages;
NSString *defaultLanguage; 

languageManager = [STLanguageManager defaultManager];

languages = [languageManager availableLanguages];
defaultLanguage = [languageManager defaultLanguage];


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
   [conversation interpretScript:string];
   result = [conversation result];
NS_HANDLER
   /* handle an exception */
NS_ENDHANDLER


Note: the result handling will change in future StepTalk releases. The result will be no longer be returned by the direct execution message, but instead will need to be requested separately. There are several reasons for this change, 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"]];
       }
   ...

FIXME: what is needed to do that with Gorm in a simple way?

The scripts

See: Script management