Integrating RegexBuddy Using COM Automation

If you are a software developer, and some of your products support regular expressions, make your customers happy and provide tight integration with RegexBuddy. That way, they can edit the regexes they use in your software with RegexBuddy at the click of a button, without having to manually copy and paste regexes between your software and RegexBuddy.

On the Microsoft Windows platform, RegexBuddy provides a COM Automation interface, which you can easily import and call from any development tool or language that supports COM. The interface enables you to launch RegexBuddy, and send and receive regex actions in response to the user’s actions. It is a single instance interface, which means that each application has its own private instance of RegexBuddy.

Take a look at PowerGREP and EditPad Pro to see how convenient they make it to edit a regular expression with RegexBuddy.

Demo Applications Implementing RegexBuddy’s COM Automation

At http://download.jgsoft.com/buddy/RegexBuddy4Clients.zip you can download two sample applications that communicate with RegexBuddy through its COM Automation interface. One is written in Delphi 2009 (Win32) and the other one is written in Visual Studio 2010 using C#. The examples show how to use InitAction and FinishAction to communicate with RegexBuddy and how to fall back on any older version of RegexBuddy if the user does not have RegexBuddy 4.

Importing RegexBuddy’s Type Library

RegexBuddy’s installer automatically registers RegexBuddy’s automation interface with Windows. To automate RegexBuddy via COM, you need to import its type library. It is stored in RegexBuddy4.exe, which is installed under C:\Program Files\Just Great Software\RegexBuddy 4\ by default.

In Delphi, select Component|Import Component from the menu. Select “Import a Type Library” and click Next. Select “RegexBuddy API” version “4.0” from RegexBuddy4.exe and click Next. Choose a palette page and a directory, make sure Generate Component Wrappers is ticked, and click Next. Install into a new or existing package as you prefer. Three new component called TRegexBuddyIntf, TRegexBuddyIntf3, and TRegexBuddyIntf4 appear on the component palette. These components implement the methods and events you can use to communicate with RegexBuddy. Drop TRegexBuddyIntf on a form or data module. Set ConnectKind to ckNewInstance, and make sure AutoConnect is False. This ensures your application has its own instance of RegexBuddy, and that RegexBuddy only appears when the user actually wants to edit a regular expression. Call the component’s Connect() method the first time the user wants to edit a regular expression with RegexBuddy. For efficiency, do not call the Disconnect() method until your application terminates (at which point it is called automatically). Assign an event handler either to OnFinishRegex or OnFinishAction, depending on which way of communication you prefer (see below). You can use TRegexBuddyIntf3 or TRegexBuddyIntf4 instead if you want to use the new methods in RegexBuddy 3 or 4. Calling Connect() on these components will raise an exception if the user has an older version of RegexBuddy. You can fall back to TRegexBuddyIntf when that happens. Once a call to Connect() succeeds, your application should not make any other calls to Connect() so that only one instance of the TRegexBuddyIntf component is live. Otherwise, it will launch multiple instances of RegexBuddy. Doing so would not cause any errors, but does waste resources.

In Visual Studio, right-click on “References” in the Solution Explorer, and pick “Add Reference”. Switch to the COM tab, and choose “RegexBuddy API” version “4.0” from RegexBuddy4.exe. After adding the reference, import the RegexBuddy namespace with using RegexBuddy. Then you can easily access the RegexBuddyIntf4 class. Create a new object from this class the first time the user wants to edit a regular expression with RegexBuddy. Use the same object for all subsequent times the user wants to edit the same or another regex. Do not delete the object until your application terminates. Each time you create an object of RegexBuddyIntf4, a new RegexBuddy instance is launched. You also need to create an instance of either IRegexBuddyIntfEvents_FinishRegexEventHandler or IRegexBuddyIntfEvents_FinishActionEventHandler and assign it to the FinishRegex or FinishAction event of your RegexBuddyIntf4 object. Do not assign both. Only assign the one you will actually use.

Note that to successfully communicate with RegexBuddy, two-way communication is required. Your application not only needs to call the methods of the RegexBuddyIntf interface to send the regular expression to RegexBuddy. It also needs to implement an event sink for either the FinishRegex() or FinishAction() method defined in the IRegexBuddyIntfEvents interface. Not all development and scripting tools that can call COM automation objects can also implement event sinks. The tool must support “early binding”.

RegexBuddyIntf Interface

The RegexBuddyIntf COM automation interface provides the following methods:

void IndicateApp(BSTR AppName, uint Wnd)

Call IndicateApp right after connecting to the COM interface. AppName will be displayed in RegexBuddy’s caption bar, to make it clear that this instance is connected to your application. Wnd is the handle of your application’s top-level form where the regex is used. RegexBuddy will call SetForegroundWindow(Wnd) to activate your application when the user is done with RegexBuddy (i.e. after a call to FinishAction or FinishRegex). You can call IndicateApp as often as you want, as long as you also call it right after connecting to the COM interface.

void InitAction(VARIANT Action)

Call InitAction to make RegexBuddy show up with the given RegexBuddy Action. RegexBuddy will follow up with a call to FinishAction when the user closes RegexBuddy by clicking the Send button.

BOOL CheckActionVersion(uint Version)

Returns TRUE if RegexBuddy supports this version of the RegexBuddy Action COM Variant Structure. RegexBuddy 1.x.x and 2.x.x support only version 1. RegexBuddy 3.0.0 and later support versions 1 and 3. RegexBuddy 4.0.0 and later support versions 1, 3, and 4. There is no version 2. These versions of the COM structure are supported regardless of whether you’re using RegexBuddyIntf, RegexBuddyIntf3, or RegexBuddyIntf4.

You should call this function with the highest version that your application supports. Newly developed applications should support versions 4, 3, and 1. If the function returns FALSE, call it again with a lower version, until you reach version 1. Version 1 is always supported. There’s no need to call CheckActionVersion for version 1. RegexBuddy will always use version 1 of the variant structure unless a call to CheckActionVersion returned TRUE.

If you will be calling Convert() with ConvertBeforeSend set to TRUE then it is sufficient to call CheckActionVersion(4) because the conversion ensures that RegexBuddy will send back a flavor that your application support. If you’re not calling Convert() with ConvertBeforeSend, then calling only CheckActionVersion(4) allows RegexBuddy to send back an action with any application or regex flavor supported by RegexBuddy, including flavors added in future versions.

RegexBuddy 4.1.0 and later allow you to tell RegexBuddy which application and regular expression flavor identifiers your application supports. Pass 410 for Version to request and indicate support for flavors supported by RegexBuddy 4.1.0 (but not flavors added in post-4.1.0 releases) and to use version 4 of the COM structure. If CheckActionVersion(410) returns FALSE, call CheckActionVersion(4) to check whether the user has RegexBuddy 4.0.x (which by definition can’t send back flavors added in 4.1.0 or later).

RegexBuddy 4.1.0 also return TRUE if you call CheckActionVersion(400) to restrict the flavors to those available in RegexBuddy 4.0.0. But all RegexBuddy 4.0.x releases return FALSE when you call CheckActionVersion(400) even though they support all 4.0.0 flavors because the ability to check for flavor versions was added in 4.1.0.

uint GetWindowHandle()

Returns the window handle of RegexBuddy’s top window, which is either the main window, or the topmost modal dialog box in RegexBuddy. Pass this to SetForegroundWindow() after calling InitRegex or InitAction. SetForegroundWindow() only works when called by the thread that has input focus, so RegexBuddy cannot bring itself to front. That is your application’s duty. Likewise, RegexBuddy will bring your application to front after calling FinishAction, using the window handle you passed on in IndicateApp().)

void InitRegex(BSTR Regex, uint StringType)

Deprecated. This method does not allow the regex flavor or matching modes to be passed, which have a significant impact on how the regular expression is interpreted. Use InitAction instead. The only reason to call InitRegex would be to have RegexBuddy 1.x.x or 2.x.x interpret the regex using a string type, as version 1 of the RegexBuddy Action Variant Structure does not have an element to set the string style.

InitRegex makes RegexBuddy show up with the given regular expression. If you call InitRegex, then RegexBuddy will call FinishRegex instead of FinishAction when the user closes RegexBuddy by clicking the Send button. This means you’ll need to assign event handler to FinishRegex instead of FinishAction if you want to use InitRegex. Regex is the regular expression that the user will edit in RegexBuddy. Can be an empty string. StringType tells RegexBuddy how to interpret the string you provided. Pass one of the integers listed in this table. By using a StringType other than zero, you can let RegexBuddy take care of adding and removing quote characters, escaping characters, etc. If you pass an unsupported string type, “as is” will be used instead.

RegexBuddyIntf3 Interface

RegexBuddy 3.0.0 and later provide an additional interface called RegexBuddyIntf3. This interface descends from RegexBuddyIntf, so all the above methods are also supported by RegexBuddyIntf3. You can use this interface to make use of the new functionality in RegexBuddy 3. If your application is unable to instantiate this interface, it should fall back on RegexBuddyIntf. If you don’t want to use the additional functionality, your application can simply use RegexBuddyIntf which works with all versions of RegexBuddy.

void SetTestString(BSTR Subject)

Call SetTestString to put (a sample of) the data your application will use the regular expression on into the Test panel in RegexBuddy. That way the user can instantly test the regex on the data it’ll actually be used on. You should only use SetTestString if the data is not stored as a file on disk. Otherwise, SetTestFile is more efficient.

void SetTestFile(BSTR Filename)

Call SetTestFile to make RegexBuddy load one of the files your application will use the regular expression on into the Test panel. That way the user can instantly test the regex on the data it’ll actually be used on.

void DebugAtPos(uint CharPos)

Show RegexBuddy’s debugger output for the match attempt starting at character position CharPos in the file. The first character in the file has position zero. Note that if matches are highlighted on the Test panel, and CharPos is in the middle of a highlighted match, the debugger will begin at the start of that match rather than at CharPos. The Debug button on the Test panel does the same.

void DebugAfterPos(uint CharPos)

Like DebugAtPos, but continues showing debugging output for all match attempts following the one at CharPos.

void DebugAll()

Show RegexBuddy’s debugger output for all match attempts in the whole test subject.

void AllowOptions(VARIANT Options)

Deprecated. RegexBuddy 4 does not allow options to be disabled, because that creates problems with loading regexes from libraries or from the history. In RegexBuddy 4, calling AllowOptions() with the 5th element in the array (regular expression flavor) set to FALSE has the same effect as calling Convert() with the ConvertBeforeSend argument set to TRUE and the flavor set to the same flavor as passed via InitAction(). If both the 3rd and 5th element are FALSE, then the regex is also converted the same free-spacing setting as passed to InitAction(). Passing TRUE for the 3rd or 5th element has no effect other than to cancel the effects of a previous call with FALSE values. All other elements are always ignored.

RegexBuddy 3 allows you to call AllowOptions to disable options that cannot be changed in your application and thus have to be always on or off. This method takes a variant that should be an array of 6 Boolean values.

If you set any of these to FALSE, the user will be unable to change that option in RegexBuddy 3. Your application can still change the options via the InitAction method. In fact, it should do so, to make sure the options in RegexBuddy correspond with those actually used in your application.

RegexBuddyIntf4 Interface

RegexBuddy 4.0.0 and later provide yet an additional interface called RegexBuddyIntf4. This interface descends from RegexBuddyIntf3, so all the above methods, including the deprecated ones, are also supported by RegexBuddyIntf4. You can use this interface to make use of the new functionality in RegexBuddy 4. If your application is unable to instantiate this interface, it should fall back on RegexBuddyIntf3 or RegexBuddyIntf. If you don’t want to use the additional functionality, your application can simply use RegexBuddyIntf3 or RegexBuddyIntf.

void Convert(VARIANT Options, BOOL Show, BOOL ConvertBeforeSend)

Set the drop-down lists on the Convert panel according to the Options argument. This argument should be an array with three elements.

If you pass TRUE as the Show argument, then RegexBuddy immediately activates the Convert panel.

You should pass TRUE as the ConvertBeforeSend argument if your application can only work with one specific regex flavor. RegexBuddy then forces the regular expression to be converted to this flavor when the user clicks the Send button. If the conversion succeeds without warning, the converted regex is passed to your application via FinishAction(). If it doesn’t, the Send button activates the Convert panel (regardless of the Show argument), changes the combo boxes to the values you passed the most recent call to Convert(), and informs the user that the conversion must be accepted before the regex can be sent back to your application.

The convert-before-send mode remains in effect until you call Convert() with ConvertBeforeSend set to FALSE. Doing so does change the drop-down lists on the Convert panel unless you pass NULL as the Options argument.

void SetTestStringEx(BSTR Subject, VARIANT Options)

Call SetTestStringEx to put (a sample of) the data your application will use the regular expression on into the Test panel in RegexBuddy. That way the user can instantly test the regex on the data it’ll actually be used on. You should only use SetTestStringEx if the data is not stored as a file on disk. Otherwise, SetTestFileEx is more efficient. The Meta argument should be an array with 3 elements.

void SetTestFileEx(BSTR Filename, VARIANT Options)

Call SetTestFileEx to make RegexBuddy load one of the files your application will use the regular expression on into the Test panel. That way the user can instantly test the regex on the data it’ll actually be used on. The Meta argument should be an array with 3 elements.

RegexBuddyIntfEvents Interface

FinishRegex(BSTR Regex, uint StringType)

You must provide an event handler for this event if you call InitRegex. After calling InitRegex, RegexBuddy will call FinishRegex when the user closes RegexBuddy by clicking the Send button. RegexBuddy will provide the final regular expression, using the same string type as you used in the last call to InitRegex.

FinishAction(VARIANT Action)

You must provide an event handler for this event if you call InitAction. After calling InitAction, RegexBuddy will call FinishAction when the user closes RegexBuddy by clicking the Send button. RegexBuddy will pass the same version of the variant structure to FinishAction as you passed to InitAction.

If the user closes RegexBuddy without clicking the Send button, your application will not receive a call to FinishRegex or FinishAction.

Which Methods to Call and Events to Handle

In summary, you must call IndicateApp immediately after connecting to RegexBuddy. Then, call either InitRegex or InitAction each time the user wants to edit a regular expression with RegexBuddy. RegexBuddy follows up a call to InitRegex or InitAction with a corresponding call to FinishRegex or FinishAction. If you call InitRegex or InitAction again before receiving a call to FinishRegex or FinishAction, the effects of the previous call to InitRegex or InitAction are canceled.

Note that in RegexBuddy 3.0.0 and later, both RegexBuddyIntf and RegexBuddyIntf3 support version 3 of the COM variant structure. You only need to instantiate RegexBuddyIntf3 if you want to call the additional methods it offers.

RegexBuddy Action COM Variant Structure

The InitAction method and the FinishAction event handler of RegexBuddy’s COM interface pass the RegexBuddy Action as a Variant array. All elements must be present in the array, even those that are not applicable for the given kind of action or regular expression flavor. The values that do not apply are used as the defaults if the user changes the kind of action in RegexBuddy. RegexBuddy also fills elements that do not apply when calling FinishAction. You can ignore those. If the specified regular expression flavor does not allow a matching mode to be toggled, then it doesn’t matter whether you specify TRUE or FALSE for that mode. RegexBuddy will only use modes that the flavor actually supports.

If you called CheckActionVersion(1) or if all your calls to CheckActionVersion() returned FALSE, then you should use version 1 of the variant structure.

There is no version 2 of the variant structure.

If you called CheckActionVersion(3) and RegexBuddy returned TRUE, then you should use version 3 of the variant structure:

If you called CheckActionVersion(4) and RegexBuddy returned TRUE, then you should use version 4 of the variant structure:

Custom Application COM Variant Structure

Version 4 of the RegexBuddy Action COM variant structure allows you to specify a custom application in element 4. To do so, pass an array with these elements:

Working with a List of Actions

RegexBuddy 3.0.0 and later can work with a list of regular expressions via InitAction() and FinishAction(). If you invoke RegexBuddy this way, your list of regular expressions will replace the History feature in RegexBuddy.

RegexBuddy will also pass all regular expressions in the History list to FinishAction(), using the Variant array as described in this section. If the History list holds only one regular expression, RegexBuddy will still pass an array [0x103, 1, [action]]. RegexBuddy will always return at least one regular expression, since the user cannot delete the last regular expression in the History list. It can be blank though.

If you called CheckActionVersion(3) and RegexBuddy returned TRUE, then you should pass the list of actions this way:

If you called CheckActionVersion(4) and RegexBuddy returned TRUE, then you should pass the list of actions this way: