Swiftpack.co - Package - Carthage/Commandant

Commandant

Commandant is a Swift framework for parsing command-line arguments, inspired by Argo (which is, in turn, inspired by the Haskell library Aeson).

Reviewed by Hound

Example

With Commandant, a command and its associated options could be defined as follows:

struct LogCommand: CommandProtocol {
	typealias Options = LogOptions

	let verb = "log"
	let function = "Reads the log"

	func run(_ options: Options) -> Result<(), YourErrorType> {
		// Use the parsed options to do something interesting here.
		return ()
	}
}

struct LogOptions: OptionsProtocol {
	let lines: Int
	let verbose: Bool
	let logName: String

	static func create(_ lines: Int) -> (Bool) -> (String) -> LogOptions {
		return { verbose in { logName in LogOptions(lines: lines, verbose: verbose, logName: logName) } }
	}

	static func evaluate(_ m: CommandMode) -> Result<LogOptions, CommandantError<YourErrorType>> {
		return create
			<*> m <| Option(key: "lines", defaultValue: 0, usage: "the number of lines to read from the logs")
			<*> m <| Option(key: "verbose", defaultValue: false, usage: "show verbose output")
			<*> m <| Argument(usage: "the log to read")
	}
}

Then, each available command should be added to a registry:

let commands = CommandRegistry<YourErrorType>()
commands.register(LogCommand())
commands.register(VersionCommand())

After which, arguments can be parsed by simply invoking the registry:

var arguments = CommandLine.arguments

// Remove the executable name.
assert(!arguments.isEmpty)
arguments.remove(at: 0)

if let verb = arguments.first {
	// Remove the command name.
	arguments.remove(at: 0)

	if let result = commands.run(command: verb, arguments: arguments) {
		// Handle success or failure.
	} else {
		// Unrecognized command.
	}
} else {
	// No command given.
}

For real-world examples, see the implementation of the Carthage command-line tool.

License

Commandant is released under the MIT license.

Github

link
Stars: 400

Dependencies

Releases

0.17.0 - 2019-04-13 02:38:39

This release drops support for Swift 4.2. Only Swift 5 is now supported.

  • Remove Result dependency (#146, #151). Thanks @daltonclaybrook & @giginet!

Thank you @mdiep & @giginet for reviewing pull requests!

0.16.0 - 2019-04-08 00:47:30

This release drops support for Swift 4.0/4.1 (#142) and is likely the last release to support Swift 4.2.

Added

  • Allow setting the help command's description (#136). Thanks @Pyroh!
  • Support Swift 4.2 (#137). Thanks @ikesyo!
  • Support Swift 5.0 (#142). Thanks @norio-nomura!

Thank you to @mdiep, @ikesyo, @blender and @norio-nomura for reviewing pull requests!

0.15.0 - 2018-07-20 11:52:22

This release drops support for Swift 3.x (#135).

Added

  • Add CocoaPods support (#132, #134). Thanks @phatblat!

Changed

  • Update Result to 4.0 (#130). Thanks @ikesyo!

Thank you to @mdiep, @ikesyo, @NachoSoto and @blender for reviewing pull requests!

0.14.0 - 2018-06-16 01:50:08

Added

  • Add Argument.usageParameter to improve help messages (#129) Thanks @benasher44!

Fixed

  • Improve Xcode 9.3 and Swift 4.1 support (#123, #125, #126, #127) Thanks @ikesyo!

Thank you to @mdiep and @blender for reviewing pull requests!

0.13.0 - 2018-02-01 21:31:53

Added

  • Return self from register(_:) for method chaining (#111) Thanks @ikesyo!
  • Support strict argument values (#117) Thanks @nekrich!

Removed

  • Removed deprecated APIs (#106) Thanks @ikesyo!

Fixed

  • Use default command if options are present (#101) Thanks @xinsight!
  • Improve support for Xcode 8.3 and later & Swift 3.1 and later (#103, #109, #112, #113, #115) Thanks @ikesyo & @iosdevzone!
  • Fix scrambled commands (#118) Thanks @ikesyo!

Thank you to @mdiep for reviewing pull requests!

0.12.0 - 2017-03-08 04:37:19

Added

  • Support for arguments array in Option (#86) Thanks @Antondomashnev!

Fixed

  • Swift 3.1 compatibility, especially on Linux (#97, #99) Thanks @ikesyo!
  • Fix switch keys being ignored when a Switch contains a flag (#95, #96) Thanks @natanrolnik!

Thank you to @mdiep for reviewing pull requests!

0.11.3 - 2016-11-07 23:26:41

Fixed

  • [CI] Fix Travis deploy (#81). Thanks @jpsim!
  • [SwiftPM] Remove test dependencies from Package.swift on Linux (#83). Thanks @ikesyo!
  • [SwiftPM] Loosen Result version constraint (#84). Thanks @ikesyo!

Thank you to @mdiep for reviewing pull requests!

0.11.2 - 2016-10-14 17:02:45

  • Add missing @availables to enums to help consumers upgrade to new Swift 3 APIs.
  • Fix build issue on Linux using SPM.

Thanks @ikesyo, @NachoSoto, @norio-nomura and @mdiep for making this release possible 🎉.

0.11.1 - 2016-09-22 12:51:58

This release drops support for Swift 2.2 and 2.3.

Fixed

  • Semantic Versioning (and Swift Package Manager) compatibility (#75, 4e056dd).

Thank you to @mitsuse for filing the issue!

0.11 - 2016-09-21 13:31:50

This release drops support for Swift 2.2 and 2.3.

Added

  • Support for Swift 3.0 (#69). Thanks @norio-nomura!

Thank you to @ikesyo and @mdiep for reviewing pull requests!

0.10.1 - 2016-07-18 08:04:20

Added

  • Support for Swift 2.3 and Xcode 8 (#68, #70). Swift 2.2 is still supported. Thanks @ikesyo!

Thank you to @mdiep for reviewing pull requests!

0.10.0 - 2016-03-31 03:00:43

This release drops support for Swift 2.1.

Added

  • Support for Swift 3.0 (#62, #63). Thanks @mdiep and @norio-nomura!

Thank you to @mdiep and @ikesyo for reviewing pull requests!

0.9.0 - 2016-03-27 22:23:46

Added

  • Support for Swift 2.2 (#60). Thanks @ikesyo!
  • A public initializer to NoOptions so that tests can be written for commands that take NoOptions (#55). Thanks @younata!

Improved

  • BREAKING CHANGE :warning: Option now requires a default value and supports Optional arguments (#58). Thanks @mdiep and @ikesyo!

Thank you to @ikesyo for improvements to the codebase! Thank you to @mdiep and @ikesyo for reviewing pull requests!

0.8.3 - 2016-02-02 00:56:37

Added

  • Subcommand mechanism where subcommands can be implemented by other executables in $PATH (#51). Thanks @ikesyo!
  • Support for Swift Package Manager (#50). Thanks @jpsim!

Improved

  • The implementation of NoError has been replaced by the one in Result (#52). Thanks @ikesyo!

Thank you to @mdiep and @NachoSoto for reviewing pull requests.

0.8.2 - 2016-01-08 13:03:18

Fixed

  • Incorrect OptionsType handling which affected built-in HelpCommand (e.g. https://github.com/realm/SwiftLint/pull/312#issuecomment-168558053) (#47). Thanks @ikesyo!

Thank you to @ikesyo for continued improvements to the codebase. Thank you also to @mdiep for reviewing pull requests.

0.8.1 - 2015-12-18 01:28:20

Fixed

  • Error handling of commands that broke in 0.8 (#44). Thanks @ikesyo!

Thank you to @ikesyo for continued improvements to the codebase. Thank you also to @mdiep and @NachoSoto for reviewing pull requests.

0.8 - 2015-12-14 17:51:12

This release includes a number of breaking changes meant to improve and simplify Commandant's design.

Improved

  • CommandTypes now specify an OptionsType, which is parsed automatically (#41). Thanks @mdiep!
  • Unrecognized arguments will now cause an error (#40). Thanks @ikesyo!
  • Positional arguments can now be specified using Arguments (#42). Thanks @ikesyo!

Thank you to @NachoSoto, @ikesyo, @mdiep, and @norio-nomura for reviewing pull requests!

0.7.0 - 2015-11-26 08:09:16

This release is meant for use with Xcode 7.1 and Swift 2.1.

Improved

  • Update Result to 1.0 (#39). Thanks @ikesyo!

Thank you to @neilpa for reviewing PRs!

0.7.0-beta.1 - 2015-10-30 01:09:00

This release is meant for use with Xcode 7.1 and Swift 2.1.

Improved

  • Update to Swift 2 (#30, #31, #32, #35, #38). Thanks @jpsim, @mrackwitz, @neilpa and @ikesyo!
  • Add a CommandRegistry.main() variant which takes explicit arguments array (#33). Thanks @natestedman!
  • Rename CommandOf to AnyCommand for consistentency with the standard lib (#37). Thanks @ikesyo!

Fixed

  • Reflect Result's parameterized error to documentations (#36). Thanks @ikesyo!

Thank you to @mdiep, @jpsim, @ikesyo, @jdhealy and @neilpa for reviewing PRs!

0.6.1 - 2015-08-08 01:27:29

  • [fixed] Correctly checking out Box and Result submodules (#27)

0.6: Think Inside the Box - 2015-05-05 22:54:58

Replaces the defunct LlamaKit with antitypical/Result.

0.5: You Get an Error, and YOU Get an Error - 2015-04-14 06:03:48

Adds single-character flags for booleans (#24, thanks @neilpa!) and parameterizes CommandantError by any custom error type from the consumer (#23).

0.4: Partition - 2015-03-17 04:09:15

Upgrades to Swift 1.2b3 (#22).

0.3: Land of Wats - 2015-03-06 07:04:11

Upgrades dependencies (#21), and makes jspahrsummers/xcconfigs into a private dependency (#20).

0.2: Now With Help - 2015-02-13 19:05:54

Adds a HelpCommand, a CommandRegistry.main() entry point, and moves testing dependencies into Cartfile.private.

0.1 - 2014-11-22 07:49:30

Initial release