2. Interface
The scriptingadditions
method
The OSAX.scripting_additions
method returns the names of all installed scripting additions:
require "osax"
p OSAX.scripting_additions
# Result: ["Digital Hub Scripting", "StandardAdditions", ...]
The osax
method
The OSAX.osax
method provides a convenient shortcut for creating new ScriptingAddition
instances.
osax(name=nil, app_name=nil) -- convenience method for
creating a new ScriptingAddition instance
name : String | nil -- scripting addition's name
(nil = "StandardAdditions")
app_name : String | nil -- target application's name/path, or nil
for current application
Result : ScriptingAddition
For example:
require "osax"
sa = OSAX.osax
p sa
# Result: #<OSAX::ScriptingAddition
# name="StandardAdditions"
# target=AEM::Application.current>
In addition, the osax
function accepts an application name as an optional second argument, allowing you to specify the application you want to handle the scripting addition's commands, e.g.:
OSAX.osax("StandardAdditions", "System Events")
is shorthand for:
OSAX::ScriptingAddition.new("StandardAdditions").by_name("System Events")
To specify applications by other means (e.g. URL), create a ScriptingAddition
object first, then call the appropriate by...
method.
For convenience, if both arguments are nil then a ScriptingAddition
object for StandardAdditions is created and returned. This object is also cached internally for efficiency and returned as-is in subsequent calls; thus, for example:
sa = osax
sa.some_command
sa.another_command
could also be written as:
osax.some_command
osax.another_command
without the additional overhead of creating a new ScriptingAddition object each time.
The ScriptingAddition
class
ScriptingAddition -- represents a single scripting addition and its
target application
Constructors:
ScriptingAddition.new(name, terms=nil) -- make a ScriptingAddition
object for the specified scripting addition, targeted
at the current application
name: string -- a scripting addition's name,
e.g. "StandardAdditions"; basically its filename
minus the '.osax' suffix
terms : module or nil -- an optional terminology glue
module,as exported by Terminology.dump; if
given, ScriptingAddition will use this instead
of retrieving the terminology dynamically
Methods:
# Introspection:
commands -- returns names of all available commands
parameters(command_name) -- returns a command's parameter names
# Specifying a different target application:
# Each of the following methods returns a new ScriptingAddition
# instance targeted at the specified application. The arguments
# are the same as for the by_name, by_creator, etc. methods in
# appscript.
by_name(name) -- name or full path of application, e.g. "Finder"
by_creator(creator) -- four-character creator code, e.g. "ttxt"
by_id(id) -- bundle id, e.g. "com.apple.ical"
by_pid(pid) -- Unix process ID, e.g. 4005
by_url(url) -- eppc URL, e.g. "eppc://jukebox-mac.local/iTunes"