Close Menu

shinvocation

ShInvocation is a lightweight library for simplifying the process of handling system process invocation in Objective-C. It provides a simple interface to execute shell commands, capture their output, handle errors, and more. With ShInvocation, you can easily integrate command-line functionality into your iOS or Mac applications.

Features

  • Straightforward API for executing shell commands
  • Ability to capture command output as a string
  • Option to stream command output line-by-line
  • Error handling with customizable responses
  • Support for asynchronous command execution
  • Simple and intuitive syntax

Installation

To integrate ShInvocation into your project, you can use CocoaPods. Simply add the following line to your Podfile:

// Podfile
pod 'ShInvocation'

Usage

Basic Invocation

Here’s an example that demonstrates how to use ShInvocation for basic command invocation:

// Import the ShInvocation module
#import <ShInvocation/ShInvocation.h>

// Create a new invocation
ShInvocation *invocation = [[ShInvocation alloc] init];

// Set the desired command
invocation.command = @"echo Hello, World!";

// Execute the command synchronously
NSString *output = [invocation execute];

// Print the command output
NSLog(@"%@", output);

Asynchronous Execution

Executing commands asynchronously can be particularly useful in scenarios where you don’t want to block the main thread. Here’s an example of how to perform asynchronous execution with ShInvocation:

// ...

// Execute the command asynchronously
[invocation executeWithCompletion:^(NSString * _Nullable output, NSError * _Nullable error) {
    if (!error) {
        NSLog(@"%@", output);
    } else {
        NSLog(@"Command execution failed with error: %@", error.localizedDescription);
    }
}];

Output Streaming

If you prefer to process the command output line-by-line rather than capturing it as a whole, you can make use of the streamOutput property. Here’s an example:

// ...

// Enable output streaming
invocation.streamOutput = YES;
    
// Execute the command synchronously
[invocation executeWithOutputHandler:^(NSString * _Nonnull line) {
    NSLog(@"%@", line);
}];

Error Handling

ShInvocation provides customizable error handling to help you deal with command execution failures. You can customize the error behavior by implementing the errorPolicy property. Here’s an example:

// ...

// Define the desired error policy
invocation.errorPolicy = ShInvocationErrorPolicyFailOnNonzeroExitCode;

// Execute the command
NSError *error;
if (![invocation executeWithError:&error]) {
    NSLog(@"Command execution failed with error: %@", error.localizedDescription);
}

Conclusion

ShInvocation is a powerful yet lightweight library that simplifies the process of executing shell commands in Objective-C. By providing a simple and intuitive API, it allows you to incorporate command-line functionality into your iOS or Mac applications with ease. Whether you need to execute commands synchronously or asynchronously, capture command output, or handle errors, ShInvocation has got you covered.