Command Argument Library - Beta

Community Showcase
1

Hi everyone,

Command Argument Library, or cmd-arg-lib is now in beta, version 0.4.2.

During the last three months the library has evolved from a "little brother" prototype to a feature complete library.

Overview:

  • Command argument definition
    • Arguments mirror an annotated work function's parameters
    • Parsing strategy is fixed, based solely on the work function's parameters
    • Work functions have a well defined, documented, domain
    • Any argument in the work function's domain can be parsed (including, say, negative integers)
  • Simple command line utilties
    • Write a work function
    • Annotate it with @MainFunction
      • The macro wraps the work function in main()
      • main() parses command arguments and passes them to the work function
    • Errors thrown by main() are caught and printed.
  • Meta-services
    • All triggered by meta-flags
    • Strings - e.g., print a version number
    • Help screens
      • Any number of them, any names
      • Flexible layout - an array of ShowElement
      • Any number of headers, notes, usage lines, descriptions, in any order
      • Complete control over which parameters are described and in what order
      • Complete control over what parameters appear in a usage line and in what order
      • Everything line-wraps, including customized usage lines
    • Manual pages
      • Defined the same way as help screens
      • Easy to add sections defined using mdoc macros
    • Tree diagrams for hierarchical commands
      • Diagram at top level covers the entire structure
      • Optionally provide tree envocation at any depth
    • Completion scripts
      • Eventually will be in a separate module
      • Currently included in cmd-arg-lib as a convenience
      • Supports fish and zsh
      • Works for hierarchical command structures
  • Exception - a public enum
    • case stdoutMessage(String) // Text to be printed to stdout
    • case stderrMessage(String) // Text to be printed to stderr
    • case errors([String]) // Errors to be renedered in an ErrorScreen
  • ErrorScreen
    • Shown when an Exception.errrors(let messages) is caught by a wrapper function generated by one of the library's macros
    • Shows multiple line-wrapped error messages
    • Refers to help (if a help screen has been provide), including the names of command(s) invoked
    • The internal parser reports all errors encountere by throwing Exception.errors()
    • Prefer Exception.errors() to provide a consistent experience for users
  • Hierarchical command trees
    • All elements are instances of the same struct, StatefulCommand<T>
      • name, synopis, subcommands,
      • a method of type: StatefulCommandAction<T>, called when the command is encountered
    • StatefulCommandAction<T>
      • A work function annotated by the @CommandAction macro
      • The generated commandAction parses command arguments and passes them on to the work function
      • The work function is the same as for @MainFunction macro except that it takes a state parameter, [T] and returns [T]
    • There is syntatic suger for stateless commands:
      • typealias SimpleCommand = StatefulCommand<Void>
      • The work function does not have the [T] parameter
    • Command work functions can be developed and debugged independently of the enclosing Command
    • Any command in the structure can define its own meta services

Please give cmd-arg-lib a try. I think that it has some unique aspects that showcase some of Swift's strengths. I also think that it fills a void (e.g., try generating a manual page with Swfit Argument Parser tools).

I have released an auxilary package cmd-arg-lib-package-manager which, in conjunction with swift-package-manager, makes it easy to initialize packages that use cmd-arg-lib; and easy to install the associated executable products. It provides a command line utility, calpm with two subcommands: init and install. You might want to compare calpm init with swift package init. Compare the help screens. Test the help screens' line wrapping. Try command completion. Try to use the initialized packages without referencing documentation.

Assuming sufficient interest and support, I would like to see this library released fully open sourced.

A big step in that direction is your feedback.

Thanks for reading.

2 Likes