rb-appscript

8. Real vs. Generic References

Real vs. generic references

References may be either 'real' or 'generic'. A real reference relates to a specific application, while a generic reference doesn't. Generic references provide a convenient shortcut for writing literal references without having to specify an application each time.

A real reference begins with an app call, followed by a by_name, by_id, by_creator, by_pid, by_url call that identifies the application whose object(s) it refers to, e.g.:

app.by_name('TextEdit').documents.end
app.by_url('eppc://my-mac.local/Finder').home.folders.name

(Remember than app.by_name('TextEdit') can be shortened to app('TextEdit') for convenience.

A generic reference begins with app, con or its and does not identify the application to which it relates, e.g.:

app.documents.end
con.word[3]
its.name.begins_with('d')

Generic references are only evaluated when used used within real references, either as selectors:

app('Finder').home.folders[its.name.begins_with('d')].get

app('Tex-Edit Plus').windows[1].text[con.words[2], con.words[-2]].get

or as command parameters:

app('TextEdit').make(
    :new => :word, 
    :at => app.documents[1].words.end, 
    :with_data => 'Hello')

app('Finder').desktop.duplicate(
    :to => app.home.folders['Desktop Copy'])

Comparing and hashing references

Application references can be compared for equality and are hashable (so can be used as dictionary keys). For two real references to be considered equal, both must have the same application path or url and reference structure. Examples:

puts app('TextEdit').documents[1] == \
    app.by_id('com.apple.textedit').documents[1].get
# Result: true; both references evaluate to the same
#     application path and reference

puts app('Finder').home == app('Finder').home.get
# Result: false; app('Finder').home.get returns a
#     different reference to the same location

For two generic references to be equal, both must have the same reference structure. Note that comparing generic references to real references will always return a false result.