# hs.task

Execute processes in the background and capture their output

Notes:

• This is not intended to be used for processes which never exit. While it is possible to run such things with hs.task, it is not possible to read their output while they run and if they produce significant output, eventually the internal OS buffers will fill up and the task will be suspended.
• An hs.task object can only be used once

---

# API Overview

Functions - API calls offered directly by the extension

• new

Methods - API calls which can only be made on an object returned by a constructor

• closeInput
• environment
• interrupt
• isRunning
• pause
• pid
• resume
• setCallback
• setEnvironment
• setInput
• setStreamingCallback
• setWorkingDirectory
• start
• terminate
• terminationReason
• terminationStatus
• waitUntilExit
• workingDirectory

---

# API Documentation

# Functions

# new

| | | | --------------------------------------------|-------------------------------------------------------------------------------------| | Signature | hs.task.new(launchPath, callbackFn[, streamCallbackFn][, arguments]) -> hs.task object | | Type | Function | | Description | Creates a new hs.task object | | Parameters |

• launchPath - A string containing the path to an executable file. This must be the full path to an executable and not just an executable which is in your environment's path (e.g. /bin/ls rather than just ls).
• callbackFn - A callback function to be called when the task terminates, or nil if no callback should be called. The function should accept three arguments: exitCode - An integer containing the exit code of the process stdOut - A string containing the standard output of the process stdErr - A string containing the standard error output of the process
• streamCallbackFn - A optional callback function to be called whenever the task outputs data to stdout or stderr. The function must return a boolean value - true to continue calling the streaming callback, false to stop calling it. The function should accept three arguments: task - The hs.task object or nil if this is the final output of the completed task. stdOut - A string containing the standard output received since the last call to this callback stdErr - A string containing the standard error output received since the last call to this callback
• arguments - An optional table of command line argument strings for the executable

| | Returns |

• An hs.task object

| | Notes |

• The arguments are not processed via a shell, so you do not need to do any quoting or escaping. They are passed to the executable exactly as provided.
• When using a stream callback, the callback may be invoked one last time after the termination callback has already been invoked. In this case, the task argument to the stream callback will be nil rather than the task userdata object and the return value of the stream callback will be ignored.

| | Examples | None | | Source | extensions/task/libtask.m line 176 |

---

# Methods

# closeInput

---

# environment

---

# interrupt

---

# isRunning

---

# pause

---

# pid

---

# resume

---

# setCallback

---

# setEnvironment

---

# setInput

---

# setStreamingCallback

---

# setWorkingDirectory

---

# start

---

# terminate

---

# terminationReason

---

# terminationStatus

---

# waitUntilExit

---

# workingDirectory

---

---