PS01 - Using the RemObjects Pascal Script
使用RemObjects Pascal Script
This article provides an overview of the new RemObjects Pascal Script and explains how to create some simple scripts.
这篇文章提供了RemObjects Pascal Script的一个概览，以及说明了如何去创建一些简单的脚本。
Pascal Script comprises two different parts:
Compiler (uPSCompiler.pas)
Runtime (uPSRuntime.pas)
Pascal Script由两个部分组成：
编译嚣(UPSCompiler.pas)
运行时(uPSRuntime.pas)
The two parts have no interdependencies on each other. You can use them directly, or you can use them in the TPSScript component, which can be found in the uPSComponent.pas unit, and wraps them both in one easy to use class.
这两部分之间是没有相互依赖的。你可以直接使用她们，或才你可以透过TPSSCript组件来使用她们，TPSSCript组件在uPSComponent.pas单元中，她对上述两个部分进行一些包装以便我们可以很容易的使用。
To use the component version of Pascal Script, you must first place it on your form or data module, set or assign the script property, call the Compile method, and call the Execute method. Compile errors, warnings or hints can be found in the CompilerMessages array property, while runtime errors can be found by reading the ExecErrorToString property.
要使用Pascal Script组件，你首先要将它从组件面板中拖置窗体或module中，然後设置它的script属性，然後调用它的Compile方法进行编译，再然後调用它的Execute方法来执行脚本。编译的errors,hints,warnings可以通过其属性CompilerMessages取得，这个属性是一个数组。如果是运行时的错误，则可以通过属性ExecErrorToString取得。
The following example will compile and execute an empty script ("begin end."):
下面的例子将编译并执行一个空脚本("begin end."):
var
Messages: string;
compiled: boolean;
begin
ce.Script.Text := 'begin end.';
Compiled := Ce.Compile;
for i := 0 to ce.CompilerMessageCount -1 do
Messages := Messages +
ce.CompilerMessages[i].MessageToString +
#13#10;
if Compiled then
Messages := Messages + 'Succesfully compiled'#13#10;
ShowMessage('Compiled Script: '#13#10+Messages);
if Compiled then begin
if Ce.Execute then
ShowMessage('Succesfully Executed')
else
ShowMessage('Error while executing script: '+
Ce.ExecErrorToString);
end;
end;
By default, the component only adds a few standard functions to the scripting engine (the exact list can be found at the top of uPSComponents.pas).
缺省情况下，组件只加入一少部分标准的functions到脚本引擎中(具体可以在uPSComponents.pas单元头中找到)
Besides the standard functions, there are a few libraries included with Pascal Script:
TPSDllPlugin Allow scripts to use dll functions, the syntax is like:
function FindWindow(C1, C2: PChar): Longint; external 'FindWindowA@user32.dll stdcall';
TPSImport_Classes Import library for TObject and the Classes unit.
TPSImport_DateUtils Import library for date/time related functions.
TPSImport_ComObj Access COM Objects from your scripts.
TPSImport_DB Import library for db.pas.
TPSImport_Forms Import library for the Forms & Menus units.
TPSImport_Controls Import library to Controls.pas and Graphics.pas.
TPSImport_StdCtrls Import library for ExtCtrls and Buttons.
To use these libraries, add them to your form or data module, select the [...] button next to the plugins property of the TPSCompiler component, add a new item and set the Plugin property to the plugin component.
要使用这些libraries,将它们从组件面板中拖至窗体数据data module中，然後设置TPSCompiler的plugins属性，在其中增加条目，并将条目指向这些plugin组件。
Besides the standard libraries, you can easily add new functions to the scripting engine. In order to do that, create a new method you would like to expose to the scripting engine, for example:
除了这些标准的libraries之外，你还可以很方便地向脚本引擎中添加新的函数。要做到这一点，创建一个你要加入到脚本中的method，如下例：
procedure TForm1.ShowNewMessage(const Message: string);
begin
ShowMessage('ShowNewMessage invoked:'#13#10+Message);
end;
Then, assign an event handler to the OnCompile event and use the AddMethod method of TPSCompiler to add the actual method:
然後，在TPSCompiler 的OnCompile事件中将该方法添加入脚本中：
A sample script that uses this function could look like this:
这样， 你就可以在脚本中使用这个函数，如下：
begin
ShowNewMessage('Show This !');
end.
Advanced Features
高级功能
Pascal Script includes a preprocessor that allows you to use defines ({$IFDEF}, {$ELSE}, {$ENDIF}) and include other files in your script ({$I filename.inc}). To enable these features, you must set the UsePreprocessor property to true and the MainFileName property to match the name of the script in the Script property. The Defines property specifies which defines are set by default, and the OnNeedFile event is called when an include file is needed.
Pascal Script包含了一个预处理程序，以便你可以在脚本中使用编译预定义(defines)({$IFDEF}, {$ELSE}, {$ENDIF}) 以及在脚本中包含其它脚本 ({$I filename.inc})。要达到这个功能，你需要设置UsePreprocessor属性为true，and the MainFileName property to match the name of the script in the Script property. 。Defines属性指定要缺省时定义哪些defines；OnNeedFile事件代码在需要包含的文件时被执行。
function TForm1.ceNeedFile(Sender: TObject;
const OrginFileName: String;
var FileName, Output: String): Boolean;
var
path: string;
f: TFileStream;
begin
Path := ExtractFilePath(ParamStr(0)) + FileName;
try
F := TFileStream.Create(Path, fmOpenRead or fmShareDenyWrite);
except
Result := false;
exit;
end;
try
SetLength(Output, f.Size);
f.Read(Output[1], Length(Output));
finally
f.Free;
end;
Result := True;
end;
When these properties are set, the CompilerMessages array property will include the file name these messages occur in.
当这些属性被设置以後，CompilerMessages属性可就将可能包含这些文件名。
Additionally, you can call scripted functions from Delphi. The following sample will be used as a script:
另外，你可以在Delphi中调用脚本里的函数。如下函数被定义在脚本中，後面将会在delphi中被调用：
function TestFunction(Param1: Double; Data: String): Longint;
begin
ShowNewMessage('Param1: '+FloatToString(param1)
+#13#10+'Data: '+Data);
Result := 1234567;
end;
begin
end.
Before this scripted function can be used, it has to be checked to match its parameter and result types, which can be done in the OnVerifyProc event.
在使用调用这个函数之前，必须对其进行一个校验，校验其参数和返回值类型，在OnVerifyProc执行这个校验。
procedure TForm1.CEVerifyProc(Sender: TPSScript;
Proc: TPSInternalProcedure;
const Decl: String;
var Error: Boolean);
begin
if Proc.Name = 'TESTFUNCTION' then begin
if not ExportCheck(Sender.Comp, Proc,
[btS32, btDouble, btString], [pmIn, pmIn]) then begin
Sender.Comp.MakeError('', ecCustomError, 'Function header for
TestFunction does not match.');
Error := True;
end
else begin
Error := False;
end;
end
else
Error := False;
end;
The ExportCheck function checks if the parameters match. In this case, btu8 is a boolean (the result type), btdouble is the first parameter, and btString the second parameter. [pmIn, pmIn] specifies that both parameters are IN parameters. To call this scripted function, you have to create an event declaration for this function and call that.
ExportCheck函数检查参数的匹配情况。在这个例子中，btu8是一个布尔型(返回值类型)，btdouble是第一个参数，btString是第二个参数。[pmIn, pmIn]表示两个参数都是输入参数。要调用这个脚本函数，你需要为它创建一个函数类型声明。
type
TTestFunction = function (Param1: Double;
Data: String): Longint of object;
//...
var
Meth: TTestFunction;
Meth := TTestFunction(ce.GetProcMethod('TESTFUNCTION'));
if @Meth = nil then
raise Exception.Create('Unable to call TestFunction');
ShowMessage('Result: '+IntToStr(Meth(pi, DateTimeToStr(Now))));
It's also possible to add variables to the script engine, which can be used from within the script. To do this, you have to use the AddRegisteredVariable function. You can set this in the OnExecute event :
还可以向脚本引擎中添加变量，然後就可以在脚本中使用这些变量 。要做到这一点，你需要使用AddRegisteredVariable函数。可以在OnExecute设置它：
procedure TForm1.ceExecute(Sender: TPSScript);
begin
CE.SetVarToInstance('SELF', Self);
// ^^^ For class variables
VSetInt(CE.GetVariable('MYVAR'), 1234567);
end;
To read this variable back, after the script has finished executing, you can use the OnAfterExecute event:
若要再去读取这个变量的值，在脚本执行完成後，在OnAfterExecute事件中访问：
VGetInt(CE.GetVariable('MYVAR')).
Registering external variables to the script engine is also possible. It's a two step process, first, in the OnCompile event, add the types to the script using the AddRegisteredPTRVariable function.
注册一个外部变量到脚本引擎中也是可以的。这需要两个步骤，首先在OnCompile事件中使用AddRegisteredPTRVariable函数将变量类型添加到脚本中。
procedure TMyForm.PSScriptCompile(Sender: TPSScript);
begin
Sender.AddRegisteredPTRVariable('MyClass', 'TButton');
Sender.AddRegisteredPTRVariable('MyVar', 'Longint');
end;
This will register the external MyClass and MyVar variables. Second, attach a pointer to these variables in the OnExecute event:
这样就注册了MyClass 和 MyVar这两个变量。第二步，在OnExecute中通过将变量值的地址指针传给变量来实现给变量赋值：
There are two types of variables in Pascal Script, base types, which are simple types (see the table below), and class types. Base types are registered in the uPSUtils.pas unit and can be located using the FindBaseType function. Class types have to be located by name, using the FindNamedType. Changes to these variables have a direct effect on the actual variable.
在Pascal Script中有两种类型的变量，一种是基本类型，包含一些简单的类型，下面会列出；另一种是类类型。基本类型是在uPSUtils.pas被注册进去的，可以通过FindBaseType函数找到。类类型需要使用FindNamedType函数通过名称找到。改变这些变量将直接地影响到实际的变量。
The component version of Pascal Script also supports execution of scripted functions. This works by using the ExecuteFunction method.
Pascal Script组件同样也支持脚本函数。这通过ExecuteFunction来调用。
This will execute the function called 'TestFunction' with 3 parameters, a float, an integer and a string. The result will be passed back to ShowMessage.
这个例子将执行一个名为TestFunction的函数，这个函数包含3个参数，一个float,一个integer和一个string。函数的返回值传回给ShowMessage。
Notes:
For some functions and constants, it might be necessary to add: uPSCompiler.pas, uPSRuntime.pas and/or uPSUtils.pas to your uses list.
The script engine never calls Application.ProcessMessages by itself, so your application might hang, while the script is running. To avoid this, you can add Application.ProcessMessages to the TPSScript.OnLine event.
It's possible to import your own classes in the script engine. Pascal Script includes a tool to create import libraries in the /Unit-Importing/ directory.
It's possible to import your own classes in the script engine. Pascal Script includes a tool to create import libraries in the Bin directory.
For examples on how to use the compiler and runtime separately, see the Import and Kylix samples.
The Debug requires SynEdit http://synedit.sourceforge.net/.
注意：
一些必要的函数和常量应该被加入到uses 列表中：uPSCompiler.pas, uPSRuntime.pas, uPSUtils.pas；
脚本引擎不会自行调用Application.ProcessMessages，因此在脚本执行时你的应用程序可能会终止。要避免这一点，你可以将Application.ProcessMessages加入到TPSScript的OnLine事件中；
可能需要在脚本中引入你自己的类，Pascal Script包含一个工具以便创建引入的库，这个工具在Unit-Importing目录中；
可能需要在脚本中引入你自己的类，Pascal Script包含一个工具以便创建引入的库，这个工具在Bin目录中；
安装目录中可以找到单独使用Comiler和Runtim的实例；
脚本调试需要SynEdit http://synedit.sourceforge.net/.
