Inherits from NSObject
Declared in GBTask.h
GBTask.m

Overview

Implements a simpler interface to NSTask.

The class is designed to be completely reusable - it doesn't depend on any project specific object or external library, so you can simply copy the .h and .m files to another project and use it. To run a command instantiate the class and send runCommand: message. You can pass in optional arguments if needed:

GBTask *task = [GBTask task];
[task runCommand:@"/bin/ls", nil]; 
[task runCommand:@"/bin/ls", @"-l", @"-a", nil];

If you want to be continuously notified when output or error is reported by the command (for example when you're running lenghtier commands and want to update user interface so the user is aware something is happening), use block method runCommand:arguments:block:

GBTask *task = [GBTask task];
[task runCommand:@"/bin/ls" arguments:nil block:^(NSString *output, NSString *error) {
	// do something with output and error here...
}];

You can affect how the output and error is reported through by changing the value of reportIndividualLines.

You can reuse the same instance for any number of commands. After the command is finished, you can examine it's results through lastStandardOutput and lastStandardError properties. You can also check the actual command line string used for running the command through lastCommandLine; this value includes the command and all parameters in a single string. If any parameter contains whitespace, it is embedded into quotes. All these properties work the same regardless of the way you run the command.

Tasks

Initialization & disposal

  • + task Returns autoreleased instance of the class.

Running commands

  • – runCommand: Runs the given command with optional arguments.
  • – runCommand:arguments:block: Runs the given command and optional arguments using the given block to continuously report back any output or error received from the command while it's running.
  •   reportIndividualLines Specifies whether output reported while the command is running is split to individual lines or not. property

Last results

  •   lastCommandLine Returns last command line including all arguments as passed to runCommand: the last it was sent. property
  •   lastStandardOutput Returns string emited to standard output pipe the last time runCommand: was sent. property
  •   lastStandardError Returns string emited to standard error pipe the last time runCommand: was sent. property

Properties

lastCommandLine

Returns last command line including all arguments as passed to runCommand: the last it was sent.

@property (readonly, retain) NSString *lastCommandLine

See Also

Declared In

GBTask.h

lastStandardError

Returns string emited to standard error pipe the last time runCommand: was sent.

@property (readonly, retain) NSString *lastStandardError

See Also

Declared In

GBTask.h

lastStandardOutput

Returns string emited to standard output pipe the last time runCommand: was sent.

@property (readonly, retain) NSString *lastStandardOutput

See Also

Declared In

GBTask.h

reportIndividualLines

Specifies whether output reported while the command is running is split to individual lines or not.

@property (assign) BOOL reportIndividualLines

Discussion

If set to YES, any output from standard output and error is first split to individual lines, then each line is reported separately. This can be useful in cases where multiple lines are reported in one block call, but we want to handle them line by line. Turning the option on does reduce runtime performance, so be sure to measure it. Defaults to NO.

Declared In

GBTask.h

Class Methods

task

Returns autoreleased instance of the class.

+ (id)task

Declared In

GBTask.h

Instance Methods

runCommand:

Runs the given command with optional arguments.

- (BOOL)runCommand:(NSString *)command

Parameters

command
Full path to the command to run.
...
A comma separated list of arguments to substitute into the format.

Return Value

Returns YES if command succedded, NO otherwise.

Discussion

The command is run synchronously; the application is halted until the command completes. All standard output and error from the command is copied to lastStandardOutput and lastStandardError properties. If you're interested in these values, check the values. The result of the method is determined from lastStandardError value - if it contains non-empty string, error is reported, otherwise success. This should work for most commands, but if you use it on a command that emits errors to standard output, you should not rely solely on method result to determine success - you should instead parse the output string for indications of errors!

Internally, sending this message is equivalent to sending runCommand:arguments:block: with wrapping all the arguments into an NSArray and passing nil for block!

Exceptions

NSException
Thrown if the given command is invalid or cannot be started.

See Also

Declared In

GBTask.h

runCommand:arguments:block:

Runs the given command and optional arguments using the given block to continuously report back any output or error received from the command while it's running.

- (BOOL)runCommand:(NSString *)command arguments:(NSArray *)arguments block:(GBTaskReportBlock)block

Parameters

command
Full path to the command to run.
arguments
Array of arguments or nil if no arguments are used.
block
Block to use for continuous reporting or nil to not use block.

Return Value

Returns YES if command succedded, NO otherwise.

Discussion

In contrast to runCommand:, this method uses the given block to report any string received on standard output or error, immediately when the command emits it. The block reports only the type of input received - if output is received only, error is nil and vice versa. In addition, all strings are concatenated and copied into lastStandardOutput and lastStandardError respectively. However these properties are only useful after the method returns. To change the way reporting is handled, use reportIndividualLines property. Note that if nil is passed for block, the method simply reverts to normal handling and doesn't use block.

The command is run synchronously; the application is halted until the command completes. All standard output and error from the command is copied to lastStandardOutput and lastStandardError properties. The result of the method is determined from lastStandardError value - if it contains non-empty string, error is reported, otherwise success. This should work for most commands, but if you use it on a command that emits errors to standard output, you should not rely solely on method results to determine success - you should instea parse the output string for indications of errors!

Exceptions

NSException
Thrown if the given command is invalid or cannot be started.

See Also

Declared In

GBTask.h