Objective-C framework for running shell scripts.
Documentation and API reference can be found at: http://doc.xs-labs.com/ShellKit/
ShellKit provides a test executable.
For complete examples, please take a look at the source code.
Various shell informations, like paths for commands, can be retrieved using the SKShell class:
[ [ SKShell currentShell ] commandIsAvailable: @"xcodebuild" ]
NSString * path = [ [ SKShell currentShell ] pathForCommand: @"xcodebuild" ]Arbitrary shell commands can be run using the SKShell class.
Note that commands are executed using the shell defined in the SHELL environment variable, invoked as a login shell.
Data for stdin can be provided; stdout and stderr can be retrieved.
[ [ SKShell currentShell ] runCommand: @"ls -al"
completion: ^( int status, NSString * output, NSString * error )
{
NSLog( @"%i", status );
NSLog( @"%@", output );
NSLog( @"%@", error );
}
];A shell command can by run by using the SKTask object:
SKTask * task;
task = [ SKTask taskWithShellScript: @"ls -al" ];
[ task run ];The task is run synchronously, and its output, if any, will be automatically printed to stdout.
The task will print the executed command prior to running, and print a status message once it's terminated, along with the elapsed time:
[ ShellKit ]> 🚦 Running task: ls -al
total 536
drwxr-xr-x 5 macmade staff 170 May 11 23:49 .
drwxr-xr-x@ 4 macmade staff 136 May 11 22:18 ..
-rwxr-xr-x 1 macmade staff 124624 May 11 23:49 ShellKit-Test
drwxr-xr-x 7 macmade staff 238 May 11 23:48 ShellKit.framework
-rw-r--r-- 1 macmade staff 143936 May 11 23:48 libShellKit-Static.a
[ ShellKit ]> ✅ Task completed successfully (63 ms)
A task can have sub-tasks, to try to recover from a failure:
SKTask * task;
task = [ SKTask taskWithShellScript: @"false" recoverTask: [ SKTask taskWithShellScript: @"true" ] ];
[ task run ];Here, the false task will obviously fail, but it will then execute the true task, set as recovery.
As true will succeed, the false task will also succeed:
[ ShellKit ]> 🚦 Running task: false
[ ShellKit ]> ⚠️ Task failed - Trying to recover...
[ ShellKit ]> 🚦 Running task: true
[ ShellKit ]> ✅ Task completed successfully (66 ms)
[ ShellKit ]> ✅ Task recovered successfully (66 ms)
A task can be marked as optional by using the SKOptionalTask.
In such a case, the task will succeed, regardless of its exit status:
SKOptionalTask * task;
task = [ SKOptionalTask taskWithShellScript: @"false" ];
[ task run ];[ ShellKit ]> 🚦 Running task: false
[ ShellKit ]> ❌ Error - Task exited with status 1
[ ShellKit ]> ✅ Task is marked as optional - Not failing
Multiple tasks can be grouped in a SKTaskGroup object:
SKTask * t1;
SKTask * t2;
SKTaskGroup * group;
t1 = [ SKTask taskWithShellScript: @"true" ];
t2 = [ SKTask taskWithShellScript: @"true" ];
group = [ SKTaskGroup taskGroupWithName: @"task-group" tasks: @[ t1, t2 ] ];
[ group run ];The group will try to run each task.
If a task fails, the whole group will also fail.
[ ShellKit ]> [ task-group ]> 🚦 Running 2 tasks
[ ShellKit ]> [ task-group ]> [ #1 ]> 🚦 Running task: true
[ ShellKit ]> [ task-group ]> [ #1 ]> ✅ Task completed successfully (64 ms)
[ ShellKit ]> [ task-group ]> [ #2 ]> 🚦 Running task: true
[ ShellKit ]> [ task-group ]> [ #2 ]> ✅ Task completed successfully (65 ms)
[ ShellKit ]> [ task-group ]> ✅ 2 tasks completed successfully (132 ms)
A task group may also contain other task groups:
SKTask * t1;
SKTask * t2;
SKTaskGroup * g1;
SKTaskGroup * g2;
t1 = [ SKTask taskWithShellScript: @"true" ];
t2 = [ SKTask taskWithShellScript: @"true" ];
g1 = [ SKTaskGroup taskGroupWithName: @"child-group" tasks: @[ t1, t2 ] ];
g2 = [ SKTaskGroup taskGroupWithName: @"parent-group" tasks: @[ g1 ] ];
[ g2 run ];The hierarchy of groups will be reflected by the prompt, like:
[ ShellKit ]> [ parent-group ]> [ #1 ]> [ child-group ]> [ #1 ]> 🚦 Running task: true
Note that task groups can also run custom classes, as long as they conform to the SKRunableObject protocol.
A task may contain variables, that will be substituted when running.
A variable has the following form:
%{name}%
The variable name may contain letters from A to Z (uppercase or lowercase) and numbers from 0 to 9.
Variables are passed using the run: method of SKTask and SKTaskGroup.
SKTask * task;
task = [ SKTask taskWithShellScript: @"ls %{args}% %{dir}%" ];
[ task run: @{ @"args" : @"-al", @"dir" : @"/usr" } ];In the example above, the executed script will be: ls -al /usr.
If no value is provided for a variable, the task will fail:
SKTask * task;
task = [ SKTask taskWithShellScript: @"echo %{hello}% %{foo}% %{bar}%" ];
[ task run: @{ @"hello" : @"hello, world" } ];[ ShellKit ]> 🚦 Running task: echo hello, world %{foo}% %{bar}%
[ ShellKit ]> ⚠️ No value provided value for variable: foo
[ ShellKit ]> ⚠️ No value provided value for variable: bar
[ ShellKit ]> ❌ Error - Script contains unsubstituted variables
Messages can be printed very easily.
For this purpose, the SKShell class provides several methods, like the following one:
- ( void )printMessage: ( NSString * )format
status: ( SKStatus )status
color: ( SKColor )color,
...;The status represents an optional icon.
Colors can also be used, if the terminal supports it.
As an example:
[ [ SKShell currentShell ] printMessage: @"hello, %@"
status: SKStatusDebug
color: SKColorCyan,
@"world"
];will produce:
🚸 hello, world
The prompt can be customised to reflect the hierarchy of the invoked commands.
For instance:
[ SKShell currentShell ].promptParts = @[ @"foo", @"bar" ];Then, every printed message will be prefixed by:
[ foo ]> [ bar ]> ... message ...
ShellKit is released under the terms of the MIT license.
Owner: Jean-David Gadina - XS-Labs
Web: www.xs-labs.com
Blog: www.noxeos.com
Twitter: @macmade
GitHub: github.com/macmade
LinkedIn: ch.linkedin.com/in/macmade/
StackOverflow: stackoverflow.com/users/182676/macmade