automating-numbers

Automating Numbers (JXA-first, AppleScript discovery)

Relationship to the macOS automation skill

• Standalone for Numbers, aligned with automating-mac-apps patterns.
• Use automating-mac-apps for permissions, shell, and UI scripting guidance.
• PyXA Installation: To use PyXA examples in this skill, see the installation instructions in automating-mac-apps skill (PyXA Installation section).

Core Framing

• Numbers AppleScript dictionary is AppleScript-first; discover there.
• JXA provides logic and data processing.
• Objects are specifiers; read via methods, write via assignments.
• Handle errors from Numbers operations using try/catch blocks and Application error checking.

Workflow (default)

1. Discover terms in Script Editor (Numbers dictionary).
2. Prototype minimal AppleScript commands.
3. Port to JXA and add defensive checks.
4. Prefer batch reads and clipboard shim for writes.
5. Use UI scripting only for dictionary gaps.

Validation Checklist

• Empty document handling works without errors
• Data integrity verified after batch operations
• Numbers UI remains responsive after automation runs
• Errors logged with specific Numbers object paths
• Sheet/table indices validated before access
• Clipboard shim restores original clipboard contents

Examples

Basic table read (JXA - Legacy):

const numbers = Application('Numbers');
const doc = numbers.documents[0];
const sheet = doc.sheets[0];
const table = sheet.tables[0];
const data = table.rows.whose({_not: [{cells: []}]})().map(row => row.cells().map(c => c.value()));

Basic table read (PyXA - Recommended):

import PyXA

numbers = PyXA.Numbers()

# Get first document, sheet, and table
doc = numbers.documents()[0]
sheet = doc.sheets()[0]
table = sheet.tables()[0]

# Read all rows with data
rows = table.rows()
data = []

for row in rows:
    cells = row.cells()
    if cells:  # Skip empty rows
        row_data = [cell.value() for cell in cells]
        data.append(row_data)

print("Table data:", data)