BridgePlus Script Library v1.3.2
Important: Scripts using BridgePlus cannot be edited in Script Editor in Mojave and later because of new security settings. You need to use Script Debugger. Also, if you are running Catalina, you may receive a message saying the library is damaged, when it is not. This is the result of new Gatekeeper checks. Unfortunately there is no equivalent to control-click-and-open for script libraries, which resolves this issue for applications. If you face this issue, you will need to remove the quarantine attributes of the library before you can use it. A longer-term solution is still in development.
BridgePlus is an AppleScript script library for use under OS X 10.9 and later. For typical scripters, it includes a collection of handlers based on the functionality of ASObjC Runner.app. For AppleScriptObjC users, there are commands that support improved bridging between AppleScript and Cocoa, as well as direct access to the extended functionality.
OS X El Capitan has introduced several great improvements to AppleScriptObjC, including bridging of file/NSURL and date/NSDate classes. BridgePlus provides similar functionality for users of OS X 10.9 and 10.10, making it easier to create backwards-compatible scripts. It also simplifies the process for El Capitan users.
BridgePlus should be installed with any other script libraries in a folder called Script Libraries inside your ~/Library folder. You can also embed it directly in script applications and bundles; see below.
To use it, you insert the line use BridgePlus : script "BridgePlus" near the start of your script. Your script is likely to also require a use scripting additions statement, and if you wish to use AppleScriptObjC, a use framework "Foundation" statement. By including use BridgePlus : script "BridgePlus", the library's terminology will be loaded and can be used anywhere in the script.
Basic use
If you do not intend to use AppleScriptObjC, BridgePlus has one relevant command defined in its dictionary: open lib description. Calling this command will open the ReadMe document listing all the available handlers. You call it like this:
use BridgePlus : script "BridgePlus"
open lib description
To call one of the handlers, you address the library. For example, there is a sorting handler:
on sortListOfNumbers:listOfNumbers
You would use it like this:
use BridgePlus : script "BridgePlus"
set sortedList to BridgePlus's sortListOfNumbers:{9, 2, 7, 3, 6, 4}
Use the open lib description command to see the full list of supported handlers.
Basic AppleScriptObjC use
BridgePlus has two commands for conversion between Cocoa and AppleScript classes when using AppleScriptObjC. The commands are Cocoaify, which takes an AppleScript value and attempts to turn it it into its Cocoa equivalent, and Asify from, which takes a Cocoa value and attempts to convert it to its AppleScript equivalent.
To see the library's dictionary you can option-drag it over Script Debugger's icon, or via Open Dictionary… in Script Editor after you have added it to ~/Library/Script Libraries.
In many cases, uses of AppleScriptObjC involves three steps: converting an AppleScript value to its Cocoa equivalent, calling instance method(s) on the Cocoa object, and converting the resulting Cocoa value back to an AppleScript value. For example:
use framework "Foundation"
set anArray to current application's NSArray's arrayWithArray:someList
set anArray to anArray's sortedArrayUsingSelector:"compare:"
set aList to anArray as list
This can be rewritten using BridgePlus.scptd as:
use framework "Foundation"
use script "BridgePlus"
set anArray to Cocoaify someList
set anArray to anArray's sortedArrayUsingSelector:"compare:"
set aList to ASify from anArray
That's a bit simpler, but not drastically so. However, the advantage of using Cocoaify and ASify from is that they provide conversions that are otherwise not available before El Capitan. The specific differences are these:
* With Cocoaify, if the AppleScript value is a date, or a list or record containing a date, those dates will be converted to NSDates. Similarly, any aliases or files will be converted to NSURLs. This matches the ability of El Capitan.
* With ASify from, if the Cocoa value is an NSDate, or it is an NSArray or NSDictionary containing an NSDate, such NSDates will be converted to AppleScript dates. Similarly, any NSURLs will be converted to files («class furl»). This matches the ability of El Capitan.
* When Cocoa values containing floating-point numbers are converted to reals either by using as real or as part of the coercion of a list or record, before OS X 10.11 they can lose precision — for example, 1.2 will be returned as 1.200000047684. With ASify from, this does not happen.
So, for example, if the list in the example above was a list of AppleScript dates, they would be sorted under Mavericks or later; without BridgePlus or El Capitan they would first have to be individually converted via handlers, and individually converted back after the sort. The code would be considerably more complex.
Advanced AppleScriptObjC use
The BridgePlus.scptd bundle contains a framework that includes many methods useful to scripters. The library does not contain terminology for these methods, but by including use script "BridgePlus" in your scripts, you can access these methods directly.
These methods are in a class called SMSForder, and many of them are based on the functionality of the now-deprecated ASObjC Runner.app. To see the header for this class, use the command open framework header. The framework is, in fact, an updated version of the ASObjCExtras.framework, renamed to avoid any clashes.
Before you can use a method from SMSForder, you need to use at least one command from the BridgePlus.scptd library. This can be load framework, or any other command (for example, Cocoaify "").
Here is a simple example:
use script "BridgePlus" version "1.3"
load framework
set newList to ASify from (current application's SMSForder's colsToRowsIn:{{1, 2, 3}, {4, 5, 6}, {7, 8, 9}, {10, 11, 12}} |error|:(missing value))
--> {{1, 4, 7, 10}, {2, 5, 8, 11}, {3, 6, 9, 12}}
Note that you do not — indeed, should not — include use framework "BridgePlus" if you are using the script library; the framework will not be found that way. The combination of use script "BridgePlus" and a call to one of the framework's commands will load it.
As of version 1.3.1, the load framework command returns a reference to the SMSForder class. So you can do this:
use script "BridgePlus" version "1.3.1"
set theForder to load framework
set newList to ASify from (theForder's colsToRowsIn:{{1, 2, 3}, {4, 5, 6}, {7, 8, 9}, {10, 11, 12}} |error|:(missing value))
--> {{1, 4, 7, 10}, {2, 5, 8, 11}, {3, 6, 9, 12}}
The SMSForder methods are documented here. This is a work in progress.
Deployment
By putting BridgePlus.scptd in your ~/Library/Script Libraries folder, you make it available to all your scripts. To use it in scripts you deploy elsewhere, you can add it to a script bundle — either an applet, or a .scptd file. It needs to be in a folder called Script Libraries, inside the bundle's /Contents/Resources folder.
If you plan to codesign a bundle containing the library, you need to codesign the BridgePlus.framework within BridgePlus.scptd first.
If you use it in an Xcode project, you can also add BridgePlus.framework separately as a normal framework, and then remove it from within the BridgePlus.scptd bundle. In this way, recent versions of Xcode will take care of codesigning the framework for you.
You can download BridgePlus 1.3.2 here.
You can use and distribute this library and framework, together or separately, free of charge. There are no guarantees or warranties whatsoever. Use at your own risk.
