Table of Contents

Overview

TMS Scripter adds scripting to Delphi and C++Builder applications. Your application runs scripts written in JavaScript, Pascal or Basic syntax, and the scripts work with the objects, functions and variables that the application makes available to them. With scripts, users can change what an application does - automate tasks, add business rules, customize forms, extend it with plugins - without recompiling it. For the users who write the scripts, a VCL application can include a ready-to-use IDE with a code editor, a form designer and a debugger.

TMS Scripter product page: https://www.tmssoftware.com/site/scriptstudiopro.asp

TMS Software site: https://www.tmssoftware.com

How it works

The application registers the classes and objects that scripts can use, gives the scripter the source code of a script, and executes it. In this example, a script reads and changes an order of the application:

uses
  atScripter, Vcl.ScripterInit;

procedure ApplyRules(Scripter: TatScripter; Order: TOrder; const FileName: string);
begin
  // Makes the TOrder class and the Order object available to the script
  Scripter.DefineClassByRTTI(TOrder);
  Scripter.AddObject('Order', Order);

  // Loads the script from a file and runs it
  Scripter.SourceCode.LoadFromFile(FileName);
  Scripter.Execute;
end;

TOrder is an ordinary class of the application, with Total and Discount properties: nothing in it is specific to scripting. The rule itself lives in a script file, which can be changed without recompiling the application:

if Order.Total > 1000 then
  Order.Discount := 0.05;

The same rule in JavaScript and in Basic:

if (Order.Total > 1000)
  Order.Discount = 0.05;

If Order.Total > 1000 Then Order.Discount = 0.05

The scripter runs Pascal scripts by default. To run scripts in the other languages, create them with TatBaseScripter.​Add​Script, as explained in Cross-language feature.

Features

Script languages

  • JavaScript, Pascal and Basic syntax, on the same engine. A script can use scripts written in the other languages: call their routines, read and write their variables, and create their forms and classes.
  • Forms declared in script: a form file (.dfm) gives the design of the form, and the script gives its behavior and event handlers.
  • Classes declared in script, with properties and methods, used by other scripts like any other object.
  • Built-in routines for strings, conversions, math, dates, dialogs, text files and COM automation, the same in all languages.
  • Calls to DLL functions, declared in the script itself.

See Writing scripts and the language references for JavaScript, Pascal and Basic.

Integration with the application

  • Classes and records registered by RTTI with a single call, or member by member when you need full control over what scripts see.
  • Components, objects, functions, global variables and constants of the application available to scripts by name.
  • Calls in both directions: Delphi code calls the functions of a script, passes parameters, reads the results, and reads and writes script variables.
  • Script event handlers: scripts can handle the events of Delphi components.
  • Libraries group the registration of classes and functions, to share it between scripters. Ready-made libraries make the classes of RTL, VCL and database units available to scripts, and the Import Tool generates libraries for other units.

See Extending scripter.

Running and debugging

See Working with scripter.

Editing scripts

  • Scripter IDE for VCL applications: projects with several script units and forms, a code editor with code completion and parameter hints, a form designer with component palette and object inspector, and a debugger. Show it with a single call, or build your own IDE from the same components. See Integrated Development Environment.
  • Syntax highlighting memo: TScrMemo edits scripts with syntax highlighting for the three languages, in any VCL form. See The syntax highlighting memo.

Main components

Component Use it to
TatScripter Run scripts in all languages. This is the component for most applications.
TIDEScripter Run scripts that are edited and debugged in the Scripter IDE. It descends from TatScripter.
TIDEEngine and TIDEDialog Manage script projects and show the Scripter IDE.
TScrMemo Edit scripts with syntax highlighting, using a styler for each language such as TScrJavaScript​Memo​Styler.

All scripter components descend from TatCustomScripter, which holds the common properties and methods for compiling, executing and debugging scripts. In this guide, scripter means any of them.

Platforms and frameworks

With Delphi 10.4 Sydney and later, the scripting engine runs in VCL, FireMonkey and console applications, on all the platforms of Delphi: Windows, macOS, Linux, iOS and Android. With older Delphi versions, it runs in VCL and console applications on Windows. The Scripter IDE and TScrMemo are VCL controls, available on Windows only.

Use in VCL applications

Add unit Vcl.ScripterInit to the uses clause of your project or of any unit. It sets up the scripter for VCL: dialogs such as ShowMessage and forms declared in scripts are VCL dialogs and forms. Without it, executing a script raises the error "Virtual Machine class not specified".

Use in FireMonkey applications

Add unit FMX.ScripterInit to the uses clause of your project or of any unit. Then use the scripter just as in a VCL application: scripts can create FireMonkey controls and forms, and run forms declared in scripts. The demo Forms/DynamicControlsFMX shows scripts that create FireMonkey controls and forms at runtime.

The Scripter IDE and the syntax highlighting memo are not available in FireMonkey applications.

Use in console applications

Windows console applications run scripts without any extra unit. The ShowMessage and InputQuery routines of the scripts write to and read from the console, using the TConsoleScripter​Machine class.

On Linux, these routines do nothing by default. To make them use the console as well, set the default machine class at the start of your application:

atScript.DefaultMachineClass := TConsoleScripterMachine;

Where to start

  • Run your first script: Getting started shows the minimum code, and Extending scripter shows how to give scripts access to your application.
  • Try the demos: the README.md file of the demos folder lists all of them. Start with Basics/HelloScripter, then open the Playground: one application with small scenarios about every topic of this guide. Choose a scenario, read its script and the Delphi code behind it, run it, change the script and run it again.
  • Write scripts: Writing scripts is written for the users of your application who write the scripts, and you can give these chapters to them.
  • C++Builder: C++Builder Examples has the C++Builder equivalent of the Delphi examples of this guide.

Rebuilding packages

To rebuild the packages, use the "Packages Rebuild Tool" utility that is installed with TMS Scripter: it has an icon in the Start Menu. Run it, select the Delphi versions for which the packages must be rebuilt, and click "Install". You can also rebuild the packages manually, by opening the package files in the Delphi IDE.

In this section:

Working with scripter

Using the scripter component in your application: running scripts, calling subroutines, passing parameters, loading script libraries and debugging.

Extending scripter

Integrating scripter with your application: registering classes, methods, properties, functions, variables and libraries so scripts can use them.

Writing scripts

For the script author: the Pascal, Basic and JavaScript languages, the built-in routines, and declaring forms and classes in script. These chapters can be given to the users who write scripts.

Pascal language reference
Basic language reference
JavaScript language reference
Built-in routines
Calling DLL functions

Integrated Development Environment

The ready-to-use IDE for writing scripts and designing forms, available for VCL applications.

The syntax highlighting memo

Using the TScrMemo control that provides syntax highlighting for Pascal, Basic and JavaScript scripts.

C++Builder Examples

C++Builder examples equivalent to every Delphi example in this guide.