9. Reference Forms
Property reference
A property either contains a simple value or represents a one-to-one relationship between two application objects. Properties either describe the application object (its name, class, size, color, preferences, etc.) or provide a convenient reference to other object(s) of interest to users (e.g. home, current_track).
Syntax:
reference.property
Examples:
textedit.name
textedit.documents[1].text
finder.home.files.name
Element references
Elements represent a one-to-many relationship between application objects. Elements usually reflect the containment structure of the application object model and generally provide multiple ways of referencing some or all of those objects (e.g. characters/words/paragraphs of documents by index/relative-position/range/filter).
All Elements
Syntax:
reference.elements
Examples:
finder.home.folders
textedit.windows
textedit.documents.paragraphs.words
by Name
Syntax:
elements[selector]
selector : String -- name of object (as matches its 'name' property)
Examples:
disks['Macintosh HD']
files['index.html']
Note: applications usually treat object names as case-insensitive. Where multiple element have the same name, a by-name reference only identifies the first element found with that name. (Tip: to identify all elements with a particular name, use a by-filter reference instead.)
by Index
Syntax:
elements[selector]
selector : Fixnum | Bignum -- index of object
Examples:
words[3]
items[-1]
Note: elements are one-indexed (AEM-style indexing), not zero-indexed (Ruby-style indexing).
by ID
Syntax:
elements.ID(selector)
selector : anything -- object's id
Examples:
windows.ID(4321)
by Absolute Position
Syntax:
elements.first -- first element
elements.middle -- middle element
elements.last -- last element
elements.any -- random element
Examples:
documents.first
paragraphs.last
files.any
by Relative Position
Syntax:
elements[selector].previous(class) -- nearest element of a given class to appear
before the specified element
elements[selector].next(class) -- nearest element of a given class to appear
after the specified element
class : Symbol -- class of element (see Classes and Enumerated Types)
Examples:
words[3].next(:word)
paragraphs[-1].previous(:character)
by Range
Range references select all elements between and including two references indicating the start and stop of the range. The start and stop references are normally declared relative to the container of the elements being selected. Appscript defines an object, con
(short for 'container'), to indicate this container; for example, to indicate the third paragraph of the currrent container object:
con.paragraphs[3]
For convenience, the range reference also allows start and stop references to be written in shorthand form where their element class is the same as the elements being selected; thus:
ref.paragraphs[con.paragraphs[3], con.paragraphs[-1]]
can also be written as:
ref.paragraphs[3:-1]
Some applications can handle more complex range references. For example, the following will work in Tex-Edit Plus:
ref.words[con.characters[5], con.paragraphs[-2]]
Syntax:
elements[start, stop]
start : Fixnum | Bignum | String | Reference -- beginning of range
stop : Fixnum | Bignum | String | Reference -- end of range
Examples:
folders['Documents', 'Movies']
documents[1, 3]
text[con.characters[5], con.words[-2]]
Note: ranges are specified as [start-position, stop-position] (AEM-style ranges), not [start-position, length] (Ruby-style ranges).
by Filter
A reference to each element that satisfies one or more conditions specified by a test expression:
elements[testExpression]
Test expressions consist of the following:
A reference to each element being tested, represented by appscript's
its
object. This object supports all valid reference forms, allowing you to construct references to its properties and elements. For example:its its.size its.words.first
One or more conditional tests, implemented as methods on the reference being tested. Each method takes a test reference or a value as its sole argument.
Syntax:
reference.lt(value) # < reference.le(value) # <= reference.eq(value) # == reference.ne(value) # != reference.gt(value) # > reference.ge(value) # >= reference.begins_with(value) reference.ends_with(value) reference.contains(value) reference.is_in(value) reference.does_not_begin_with(value) reference.does_not_end_with(value) reference.does_not_contain(value) reference.is_not_in(value) value : reference or value
Examples:
its.eq('') its.size.gt(1024) its.words.first.begins_with('A') its.characters.first.eq(its.characters.last)
Zero or more logical tests, implemented as properties/methods on conditional tests. The
and
andor
methods take one or more conditional or logic tests as arguments.Syntax:
test.and(test, ...) test.or(test, ...) test.not
Examples:
its.eq('').not its.size.gt(1024).and(its.size.lt(10240)) its.words[1].begins_with('A').or( its.words[2].contains('ce'), its.words[1].eq('Foo'))
Insertion location
Insertion locations can be specified at the beginning or end of all elements, or before or after a specified element or element range.
Syntax:
elements.beginning
elements.end
elements[selector].before
elements[selector].after
Examples:
documents.end
paragraphs[1].before