rb-appscript

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"