ExMacOSControl.Script (ExMacOSControl v0.1.2)

View Source

Simple DSL for building AppleScript programmatically.

This module provides a minimal, pragmatic DSL for constructing common AppleScript patterns using Elixir syntax. It's designed for simple use cases like tell blocks and basic commands.

Note: This is an optional helper. For complex scripts, use raw AppleScript strings with ExMacOSControl.run_applescript/1.

Examples

alias ExMacOSControl.Script

# Basic tell block
script = Script.tell("Finder", [
  "activate"
])

# Generates:
# tell application "Finder"
#   activate
# end tell

ExMacOSControl.run_applescript(script)

# Tell block with commands and arguments
script = Script.tell("Finder", [
  "activate",
  Script.cmd("open", "Macintosh HD")
])

# Generates:
# tell application "Finder"
#   activate
#   open "Macintosh HD"
# end tell

# Nested tell blocks
script = Script.tell("System Events", [
  Script.tell_obj("process", "Safari", [
    "set frontmost to true"
  ])
])

# Generates:
# tell application "System Events"
#   tell process "Safari"
#     set frontmost to true
#   end tell
# end tell

Limitations

This DSL is intentionally minimal and does NOT support:

  • Complex control flow (if/while/repeat)
  • Variable assignments
  • Handlers/subroutines
  • Full AppleScript language coverage

For these cases, use raw AppleScript strings instead.

Summary

Functions

cmd(command, arg)

Generates a command with arguments.

tell(app_name, commands)

Creates a tell block for an application.

tell_obj(object_type, object_name, commands)

Creates a tell block for a specific object.

Functions

cmd(command, arg)

@spec cmd(
  String.t(),
  String.t() | number() | boolean() | [String.t() | number() | boolean()]
) ::
  String.t()

Generates a command with arguments.

The argument will be automatically quoted if it's a string. For lists, all-numeric lists are formatted as AppleScript lists (e.g., {0, 0, 800, 600}), while other lists are formatted as space-separated quoted values.

Parameters

  • command - The command string
  • arg - The argument (string, number, boolean, or list)

Returns

A string containing the command with its argument.

Examples

alias ExMacOSControl.Script

# Single string argument
Script.cmd("open", "Macintosh HD")
# => "open \"Macintosh HD\""

# Single numeric argument
Script.cmd("set volume", 50)
# => "set volume 50"

# Single boolean argument
Script.cmd("set muted", true)
# => "set muted true"

# List of strings
Script.cmd("make", ["new", "window"])
# => "make \"new\" \"window\""

# List of numbers (formatted as AppleScript list)
Script.cmd("set bounds of window 1 to", [0, 0, 800, 600])
# => "set bounds of window 1 to {0, 0, 800, 600}"

tell(app_name, commands)

@spec tell(String.t(), [String.t()]) :: String.t()

Creates a tell block for an application.

Generates an AppleScript tell application block with the given application name and commands.

Parameters

  • app_name - The name of the application (e.g., "Finder", "Safari")
  • commands - A list of command strings to execute within the tell block

Returns

A string containing the formatted AppleScript code.

Examples

alias ExMacOSControl.Script

# Simple tell block
Script.tell("Finder", ["activate"])
# => "tell application \"Finder\"\n  activate\nend tell"

# Multiple commands
Script.tell("Finder", [
  "activate",
  Script.cmd("open", "Macintosh HD")
])
# => "tell application \"Finder\"\n  activate\n  open \"Macintosh HD\"\nend tell"

tell_obj(object_type, object_name, commands)

@spec tell_obj(String.t(), String.t(), [String.t()]) :: String.t()

Creates a tell block for a specific object.

Generates an AppleScript tell block targeting a specific object (like a process, window, or document) with the given commands.

Parameters

  • object_type - The type of object (e.g., "process", "window", "document")
  • object_name - The name of the object
  • commands - A list of command strings to execute within the tell block

Returns

A string containing the formatted AppleScript code.

Examples

alias ExMacOSControl.Script

# Tell a specific process
Script.tell_obj("process", "Safari", ["set frontmost to true"])
# => "tell process \"Safari\"\n  set frontmost to true\nend tell"