py-appscript manual | 9. Reference forms

#

## 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[1].paragraphs[1:5]

#### By name

Syntax:

    elements[selector]
            selector : str -- 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 : int -- index of object

Examples:

    words[3]
    items[-1]

Note: elements are one-indexed (AEM-style indexing), not zero-indexed (Python-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.last -- last element
    elements.middle -- middle element
    elements.any -- random element
    elements -- all elements

Examples:

    documents.first
    paragraphs.last
    files.any
    items

#### 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 : class -- class of element (see Classes and Enumerated Types)

Examples:

    words[3].next(k.word)
    paragraphs[-1].previous(k.character)

#### By range

Range references select all elements between and including two references indicating the beginning and end of the range. The beginning and end references are normally declared relative to the container of the elements being selected. Appscript defines a constant, `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 beginning and end 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 : str | int | reference -- beginning of range
            stop : str | int | reference -- end of range

Examples:

    folders['Documents':'Movies']
    documents[1:3]
    text[con.characters[5]:con.words[-2]]

Note: elements are one-indexed (AEM-style indexing), not zero-indexed (Python-style indexing).

#### 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` constant. 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 operators on the reference being tested. Each method takes a test reference or a value as its sole argument.

  Syntax:

      reference < value
      reference <= value
      reference == value
      reference != value
      reference > value
      reference >= value
      reference.beginswith(value)
      reference.endswith(value)
      reference.contains(value)
      reference.isin(value)
      reference.doesnotbeginwith(value)
      reference.doesnotendwith(value)
      reference.doesnotcontain(value)
      reference.isnotin(value)
              value : reference or value

  Examples:

      its == ''
      its.size > 1024
      its.words.first.beginswith('A')
      its.characters.first == its.characters.last

- Zero or more logical tests, implemented as properties/methods on conditional tests. The `AND()` and `OR()` methods take one or more conditional or logic tests as arguments.

  Syntax:

      test.AND(test, ...)
      test.OR(test, ...)
      test.NOT

  Examples:

      (its == '').NOT
      (its.size > 1024).AND(its.size < 10240)
      its.words[1].beginswith('A').OR(
          its.words[2].contains('ce'), its.words[1] == 'Foo')

Note: conditional tests must be written with a test reference as the first operand otherwise an error will occur, e.g. write `its.size >= 1024` not `1024 < its.size`

### 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