Older blog entries for conrad (starting at number 45)

UI.Command

I just uploaded the first cut of UI.Command, a Haskell framework for "friendly commandline programs". I hacked this together last year by pulling the command handling and documentatation generation bits out of hogg. The result is a fairly simple way of adding self-documentation, help text and man page generation to a commandline tool; it's especially useful for developing little tools that go along with libraries.

It works a lot like various web frameworks, but for building commandline apps. To use it, you first declare the various bits of metadata about your application:

hello :: Application () ()
hello = def {
                appName = "hello",
                appVersion = "0.1",
                appAuthors = ["Joe R. Hacker"],
                appBugEmail = "bugs@example.com",
                appShortDesc = "UI.Command example program",
                appLongDesc = longDesc,
                appCategories = ["Greetings", "Cat Math"],
                appSeeAlso = ["tractorgen"],
                appProject = "Haskell",
                appCmds = [world, times]
        }

longDesc = "a demonstration program for the UI.Command framework."

For each of the commands you want to support, you then declare a Command like this:

world :: Command ()
world = defCmd {
                cmdName = "world",
                cmdHandler = worldHandler,
                cmdCategory = "Greetings",
                cmdShortDesc = "An implementation of the standard software greeting."
        }

worldHandler = liftIO $ putStrLn "Hello world!"

and finally, use UI.Command's appMain:

main :: IO ()
main = appMain hello

The result is a commandline program:

$ hello world
Hello world!

that can print out its own help text:

$ hello 
UI.Command example program
Usage: hello [--version] [--help] command [args]

  a demonstration program for the UI.Command framework.

Greetings:
  world         An implementation of the standard software greeting.

Cat Math:
  times         A repetition of salutation

Miscellaneous:
  help          Display help for a specific cmdcommand
  man           Generate Unix man page for specific cmdcommand

Please report bugs to <bugs@example.com>

$ hello help world
hello world: 
Usage: hello world [options]

  An implementation of the standard software greeting.

and also generate its own man pages:

$ hello man world
.TH HELLO 1 "April 2010" "hello" "Haskell" 

.SH SYNOPSIS

.B hello
.RI world
[
.I OPTIONS
]


.SH DESCRIPTION



An implementation of the standard software greeting.
.SH AUTHORS

hello was written by Joe R. Hacker

This manual page was autogenerated by
.B hello man world.

Please report bugs to <bugs@example.com>

The next step would be to port the syntax-checking parts of hogg selfcheck which checks that the help examples pass through getOpt without errors.