JVCL Interpreter

JvInterpreter allows you to embed powerful command language into your Delphi/C++Builder application. You can use it to create macros, scripts, reports, custom forms and other means to make your application more flexible and powerful. JvInterpreter has the following features:

• simple Pascal syntax, with support for procedures, local and global variables of simple data types, variant and array types in your script
• allows to manipulate published properties and standard events from script without any additional work
• support for OLE automation calls (control Excel, Word and other OLE enabled applications from your script)
• support for calls to DLLs
• support for assigning of script procedures to your application events
• allows binding of your application procedures, classes, records and enum types to interpreter language
• ready bindings to most standard VCL components

The future version will have even more features (many of them are already implemented in JVCL CVS, download daily CVS snapshots to have a look at them):

• support for record, classes and dynamic arrays declaration from script
• allows binding of your application interfaces (IInterface and IUnknown descendants) to interpreter language
• debugger
• support for declaring new datatypes, specific to your application

JvInterpreter was first developed by Andrei Prygounkov as a part of RALib library. Now it is developed as a part of JEDI-VCL (JVCL) library by JVCL developers. Refer to JVCL page for information about license, downloading, bug reporting, contributing and so on. Please note that JvInterpreter is broken in JVCL 2.10, so you should patch it with updated JvInterpreter files.

As our help team is overdriven and help is incomplete, here are answers for most common questions. Also take a look at JvInterpreter examples (you can find them in examples\RALib folder of your JVCL installation).

How can I embed JvInterpreter into my program?

Drop a JvInterpreterProgram component on your form/datamodule. Assign script text to Pas property. Call Run method. It will look for a procedure named 'main' in your script and run it. Use this script for testing:

unit HelloWorldFromJvInterpreter;

procedure Main;
begin
  ShowMessage('Hello world!');
end;

end.

If you don't use "Build with runtime packages" option then it will most likely complain about undeclared identifier ShowMessage. You can manually add unit JvInterpreter_all.pas from your JVCL installation to your project to correct the problem.

How can I tell JvInterpreter to run specific procedure/function from a user script?

Use a CallFunction method. Suppose you need to call this script function:

unit JvInterpreterFunctionCall;

function MyPlus(A, B: Integer): Integer;
begin
  Result := A + B;
end;

end.

Then in Delphi write:

FuncResult := JvInterpreterProgram1.CallFunction('MyPlus', nil, [10, 20]);

You should get 30 in FuncResult.

How can I supply some arguments/parameters from my application to a user script?

Use OnGetValue event. Suppose you need to supply some object as a variable named 'MyApplication' in your script. Then write:

procedure TForm1.JvInterpreterProgram1GetValue(Sender: TObject; Identifier: string;
  var Value: Variant; Args: TJvInterpreterArgs; var Done: Boolean);
begin
  if AnsiSameText(Identifier, 'MyApplication') then
  begin
    Value := O2V(MyApplicationObject);
    Done := True;
  end;
end;

How can I bind procedures/class methods from my application for use in a script?

There is a global variable GlobalJvInterpreterAdapter in unit JvInterpreter. You should use its methods such as AddGet, AddClass, AddSet and so on from initialization part of your unit. See units that implement binding for standart VCL components as examples. Start with JvInterpreter_all.pas and then study, for example, JvInterpreter_StdCtrls.pas from your JVCL installation.

I need an editor component with syntax highlighting for script editing

Use JvHLEditor, that is also a part of JVCL library. Also take a look at JEDI-Editor.

I need a form designer & object inspector for use in conjunction with JvInterpreter

JvInspector is the perfect object inspector. It is also a part of JVCL library. Unfortunately, JVCL doesn't contain a form designer yet. I use ExtLib 2.1 (info on torry.net, download). Some hints of using JvInterpreter with form designer:

1. Describe a 'Self' variable using OnGetValue event. It should point to a form. Also describe in OnGetValue all components owned by form. Here is the sample:

procedure TForm1.JvInterpreterProgram1GetValue(Sender: TObject; Identifier: string;
  var Value: Variant; Args: TJvInterpreterArgs; var Done: Boolean);
var
  I: Integer;
begin
  if AnsiSameText(Identifier, 'Self') then
  begin
    Value := O2V(DesignedForm);
    Done := True;
    Exit;
  end;
  
  for I := 0 to DesignedForm.ComponentCount - 1 do
  begin
    if AnsiSameText(Identifier, DesignedForm.Components[I].Name) then
    begin
      Value := O2V(DesignedForm.Components[I]);
      Done := True;
      Exit;
    end;
  end;
end;

2. As ExtLib doesn't support visual event editing, assign events in a main procedure of the script. Here is a sample script:

unit SampleJvInterpreterFormWithACloseButton;

procedure CloseButtonClick(Sender: TObject);
begin
  Self.Close;
end;

procedure Main;
begin
  CloseButton.OnClick := CloseButtonClick;
end;

end.

Should you develop a better way, please e-mail it to me :) My e-mail: ode !at! prbank !dot! ru.

Dmitry