ExMacOSControl.Error exception (ExMacOSControl v0.1.2)

Structured error handling for macOS automation operations.

This module provides a comprehensive error handling system with:

Structured error types for common failure scenarios
Parsing of osascript error output
Helpful error messages with remediation steps
Exception behavior for seamless integration with Elixir error handling

Error Types

The following error types are supported:

:syntax_error - Invalid AppleScript/JXA syntax
:execution_error - Runtime error during script execution
:timeout - Script execution exceeded the timeout limit
:not_found - Script file or application not found
:permission_denied - Accessibility or automation permissions required
:unsupported_platform - Operation attempted on non-macOS platform

Examples

# Create a syntax error
iex> error = ExMacOSControl.Error.syntax_error("Expected end of line", line: 5)
iex> error.type
:syntax_error

# Parse osascript error output
iex> stderr = "syntax error: Expected end of line but found identifier. (-2741)"
iex> error = ExMacOSControl.Error.parse_osascript_error(stderr, 1)
iex> error.type
:syntax_error

# Get remediation steps
iex> error = ExMacOSControl.Error.permission_denied("Accessibility required")
iex> steps = ExMacOSControl.Error.remediation_steps(error)
iex> Enum.count(steps) > 0
true

# Raise as exception
iex> error = ExMacOSControl.Error.timeout("Script timed out", timeout: 5000)
iex> raise error
** (ExMacOSControl.Error) Script execution timed out after 5000ms

Summary

Types

error_type()

Error type indicating the category of failure.

t()

Structured error with type, message, and additional details.

Functions

exception(msg)

Formats the error as a string for exception messages.

execution_error(message, opts \\ [])

Creates an execution error.

not_found(message, opts \\ [])

Creates a not found error.

parse_osascript_error(stderr, exit_code)

Parses osascript error output into a structured error.

permission_denied(message, opts \\ [])

Creates a permission denied error.

remediation_steps(error)

Provides remediation steps for an error.

syntax_error(message, opts \\ [])

Creates a syntax error.

timeout(message, opts \\ [])

Creates a timeout error.

unsupported_platform(message, opts \\ [])

Creates an unsupported platform error.

Types

error_type()

@type error_type() ::
  :syntax_error
  | :execution_error
  | :timeout
  | :not_found
  | :permission_denied
  | :unsupported_platform

Error type indicating the category of failure.

t()

@type t() :: %ExMacOSControl.Error{
  __exception__: true,
  details: map(),
  message: String.t(),
  type: error_type()
}

Structured error with type, message, and additional details.

Functions

exception(msg)

@spec exception(keyword()) :: t()

Formats the error as a string for exception messages.

Includes the error message and relevant details, along with remediation steps when applicable.

execution_error(message, opts \\ [])

@spec execution_error(
  String.t(),
  keyword()
) :: t()

Creates an execution error.

Parameters

message - Description of the execution error
opts - Optional keyword list with additional details

Examples

iex> error = ExMacOSControl.Error.execution_error("Invalid index")
iex> error.type
:execution_error

not_found(message, opts \\ [])

@spec not_found(
  String.t(),
  keyword()
) :: t()

Creates a not found error.

Parameters

message - Description of what was not found
opts - Optional keyword list with additional details (e.g., :app, :file)

Examples

iex> error = ExMacOSControl.Error.not_found("Application not found", app: "Foo")
iex> error.type
:not_found
iex> error.details.app
"Foo"

parse_osascript_error(stderr, exit_code)

@spec parse_osascript_error(String.t(), integer()) :: t()

Parses osascript error output into a structured error.

Analyzes stderr output and exit codes from osascript to determine the error type and extract relevant information.

Parameters

stderr - The stderr output from osascript
exit_code - The exit code from osascript

Examples

iex> stderr = "syntax error: Expected end of line but found identifier. (-2741)"
iex> error = ExMacOSControl.Error.parse_osascript_error(stderr, 1)
iex> error.type
:syntax_error

iex> stderr = "execution error: Finder got an error: Can't get window 1. (-1719)"
iex> error = ExMacOSControl.Error.parse_osascript_error(stderr, 1)
iex> error.type
:execution_error

permission_denied(message, opts \\ [])

@spec permission_denied(
  String.t(),
  keyword()
) :: t()

Creates a permission denied error.

Parameters

message - Description of the permission issue
opts - Optional keyword list with additional details

Examples

iex> error = ExMacOSControl.Error.permission_denied("Accessibility permissions required")
iex> error.type
:permission_denied

remediation_steps(error)

@spec remediation_steps(t()) :: [String.t()]

Provides remediation steps for an error.

Returns a list of actionable steps the user can take to resolve the error.

Parameters

error - The error to provide remediation for

Examples

iex> error = ExMacOSControl.Error.permission_denied("Accessibility required")
iex> steps = ExMacOSControl.Error.remediation_steps(error)
iex> is_list(steps)
true

syntax_error(message, opts \\ [])

@spec syntax_error(
  String.t(),
  keyword()
) :: t()

Creates a syntax error.

Parameters

message - Description of the syntax error
opts - Optional keyword list with additional details (e.g., :line, :column)

Examples

iex> error = ExMacOSControl.Error.syntax_error("Expected end of line", line: 5)
iex> error.type
:syntax_error
iex> error.details.line
5

timeout(message, opts \\ [])

@spec timeout(
  String.t(),
  keyword()
) :: t()

Creates a timeout error.

Parameters

message - Description of the timeout
opts - Optional keyword list with additional details (e.g., :timeout in milliseconds)

Examples

iex> error = ExMacOSControl.Error.timeout("Script exceeded timeout", timeout: 5000)
iex> error.type
:timeout
iex> error.details.timeout
5000

unsupported_platform(message, opts \\ [])

@spec unsupported_platform(
  String.t(),
  keyword()
) :: t()

Creates an unsupported platform error.

Parameters

message - Description of the platform issue
opts - Optional keyword list with additional details (e.g., :platform)

Examples

iex> error = ExMacOSControl.Error.unsupported_platform("Not running on macOS", platform: :linux)
iex> error.type
:unsupported_platform
iex> error.details.platform
:linux