A versatile, modular library for building command-line apps.
While developing the command-line interface to Emporter.app, I really wanted a simple library to build a high quality, easy-to-use tool with modest styling requirements. I needed to be able to:
- Parse command-line arguments in a type-safe way
- Compose multiple small, easy-to-understand commands
- Output colored text
- Output tables of dynamic data with consistent widths
- Ship a fully self-contained binary (not an app bundle)
- Testable
Using Swift wasn't a viable option because of its lack of support for static libraries and ABI instability. Again, the goal here was to ship a single executable.
To my dismay, there weren't simply any options. After crying a little on the inside, I decided that I wouldn't let this happen to anyone, ever again. And here we are.
The main header YDCommandKit.h integrates with Xcode's Quick Help. After importing YDCommandKit into your project, you should be able navigate through the documentation when referencing the YD namespace.
The headers are really helpful, too. The main ones to pay attention to are:
You can check out the source to emporter-cli to see every feature within YDCommandKit used extensively. Each command is implemented in its own file and should be pretty easy to follow. It even has a custom class for drawing terminal windows using the APIs from this package. A great deal of effort went into making a minimal API without too many assumptions with how it should be used.
intmain(int argc, constchar * argv[]) {
int result = 0;
@autoreleasepool {
result = [[MainCommand new] run];
}
return result;
}
@interfaceMainCommand : YDCommand@end@implementationMainCommand : NSObject {
NSString *_foo;
}
- (instancetype)init {
self = [superinit];
if (self == nil) returnnil;
self.usage = @"[OPTIONS] [ARGS...]";
self.variables = @[[YDCommandVariable string:&_foo name:@"--foo" usage:@"Wow, type safety!"]];
self.allowsMultipleArguments = YES;
return self;
}
- (YDCommandReturnCode)executeWithArguments:(NSArray<NSString*>*)args {
[YDStandardOut appendFormat:@"Foo = %@; args = %@\n", _foo, args];
return YDCommandReturnCodeOK;
}
app --foo bar a b c would output Foo = bar; args = (a,b,c)
It's worth noting that --foo=bar is perfectly acceptable, and you can define aliases for variables so that -f bar would work, too. It'd look something like this:
[[YDCommandVariable string:&_foo name:@"--foo"usage:@"Wow, type safety!"] variableWithAlias:@"-f"]YDCommandOutputStyle redForeground = YDCommandOutputStyleWithForegroundColor(YDCommandOutputStyleRedColor);
YDCommandOutputStyle blueBackground = YDCommandOutputStyleWithBackgroundColor(YDCommandOutputStyleBlueColor);
[YDStandardOut applyStyle:redForeground withinBlock:^(id<YDCommandOutputWriter> output) { [output appendString:@"I'm red "];
// Style blocks are nestable and support inheritance
[output applyStyle:blueBackground withinBlock:^(id<YDCommandOutputWriter> output) {
[output appendString:@"and blue"];
}];
}];You don't have to nest blocks whenever you have "complex" styles. YDCommandOutputStyleMake lets you define a foreground/background color, with text attributes, which can be applied in one block.
- Add
YDCommandKit.xcodeprojto your Xcode project or workspace - Add a dependency to your target (Build Phases > Target Dependencies) to
libYDCommandKit.a - Link
libEmporterKit.ato your target (Build Phases > Link Binary With Libraries) - Update your project build settings
- Add
YDCommandKit/**to Header Search Paths - Add
-lstdc++to Other Linker Flags
- Add
#import "YDCommandKit.h"and make something awesome!
Add all files from YDCommandKit/ to your target.
I'm not a CocoaPods / Carthage user, but feel free to make a pull request to add support for either.
BSD 3 Clause. See LICENSE.
(c) 2019 Young Dynasty