cmdtheline-0.1.0.0: Declaritive command-line option parsing and documentation library.

Safe HaskellSafe-Infered

System.Console.CmdTheLine

Contents

Synopsis

Documentation

module System.Console.CmdTheLine.Term

module System.Console.CmdTheLine.Arg

module System.Console.CmdTheLine.ArgVal

Terms

CmdTheLine is centered around the Term Applicative Functor. It allows us to define command line programs like the following. 

 import System.Console.CmdTheLine
 import Control.Applicative

 -- Define a flag argument under the names '--silent' and '-s'
 silent :: Term Bool
 silent = flag $ optInfo [ "silent", "s" ]

 -- Define the 0th positional argument, defaulting to the value '"world"' in
 -- absence.
 greeted :: Term String
 greeted = pos 0 "world" posInfo { argName = "GREETED" }
 
 hello :: Bool -> String -> IO ()
 hello silent str =
   if silent
      then return ()
      else putStrLn $ "Hello, " ++ str ++ "!"

 term :: Term (IO ())
 term = foo <$> silent <*> greeted
 
 termInfo :: TermInfo
 termInfo = def { termName = "Hello", version = "1.0" }
 
 main :: IO ()
 main = run ( term, termInfo )

CmdTheLine then generates usage, help in the form of man-pages, and manages all the related tedium of getting values from the command line into our program so we can go on thinking in regular Haskell functions.

See the accompanying examples(including the above) provided under the doc/examples directory of the distributed package, or go to http://github.com/eli-frey/cmdtheline and peruse them there.

data Term a Source

The underlying Applicative of the library. A Term represents a value in the context of being computed from the command line arguments.

Instances

data TermInfo Source

Information about a Term. It is recommended that TermInfos be created by customizing the Default instance, as in 

 termInfo = def
   { termName = "caroline-no"
   , termDoc  = "carry a line off"
   }

Constructors

TermInfo 

Fields

termName :: String

The name of the command or program represented by the term. Defaults to "".

termDoc :: String

Documentation for the term. Defaults to "".

termSection :: String

The section under which to place the terms documentation. Defaults to "COMMANDS".

stdOptSection :: String

The section under which to place a term's argument's documentation by default. Defaults to "OPTIONS".

version :: String

A version string. Must be left blank for commands. Defaults to "".

man :: [ManBlock]

A list of ManBlocks to append to the default [ManBlock]. Defaults to [].

Instances

class Default a where

A class for types with a default value.

Methods

def :: a

The default value for this type.

Instances

Manpages

data ManBlock Source

Any String argument to a ManBlock constructor may contain the following significant forms for a limited kind of meta-programing.

  • $(i,text): italicizes text.
  • $(b,text): bolds text.
  • $(mname): evaluates to the name of the default term if there are choices of commands, or the only term otherwise.
  • $(tname): evaluates to the name of the currently evaluating term.

Additionally, text inside the content portion of an I constructor may contain one of the following significant forms.

  • $(argName): evaluates to the name of the argument being documented.

Constructors

S String

A section title.

P String

A paragraph.

I String String

A label-content pair. As in an argument definition and its accompanying documentation.

NoBlank

Suppress the normal blank line following a P or an I.

Instances

Argument information

data ArgInfo Source

Information about an argument. The following fields are exported for your use.

argName
:: String A name to be used in the documentation to refer to the argument's value. Defaults to "".

argDoc
:: String A documentation string for the argument. Defaults to "".

argSection
:: String The section under which to place the argument's documentation. Defaults to "OPTIONS" for optional arguments and "ARGUMENTS" for positional arguments.

Instances

User error reporting

There is nothing stopping you from printing and formating your own error messages. However, some of the time you will want more tight integration with the library. That is what Fail, the Err monad, and ret are for.

Here is a snippet of an example program that can be found at doc/examples/fail.hs in the library distribution tarball, or at http://github.com/eli-frey/cmdtheline. 

 import System.Console.CmdTheLine
 import Control.Applicative

 import Text.PrettyPrint ( fsep   -- Paragraph fill a list of 'Doc'.
                         , text   -- Make a 'String' into a 'Doc'.
                         , quotes -- Quote a 'Doc'.
                         , (<+>)  -- Glue two 'Doc' together with a space.
                         )

 import Data.List ( intersperse )

 failMsg, failUsage, success :: [String] -> Err String
 failMsg   strs = Left  . MsgFail   . fsep $ map text strs
 failUsage strs = Left  . UsageFail . fsep $ map text strs
 success   strs = Right . concat $ intersperse " " strs

 help :: String -> Err String
 help name
   | any (== name) cmdNames = Left . HelpFail Pager $ Just name
   | name == ""             = Left $ HelpFail Pager Nothing
   | otherwise              =
     Left . UsageFail $ quotes (text name) <+> text "is not the name of a command"

 noCmd :: Err String
 noCmd = Left $ HelpFail Pager Nothing

We can now turn any of these functions into a Term String by lifting into Term and passing the result to ret to fold the Err monad into the library. Here is an example of what it might look like to do this with noCmd. 

 noCmdTerm :: Term (Err String)
 noCmdTerm = pure noCmd

 prepedNoCmdTerm :: Term String
 prepedNoCmdTerm = ret noCmdTerm

data Fail Source

Constructors

MsgFail Doc

An arbitrary message to be printed on failure.

UsageFail Doc

A message to be printed along with the usage on failure.

HelpFail HelpFormat (Maybe String)

A format to print the help in and an optional name of the term to print help for. If Nothing is supplied, help will be printed for the currently evaluating term.

data HelpFormat Source

The format to print help in.

Constructors

Pager 
Plain 
Groff 

Instances

type Err a = Either Fail aSource

A monad for values in the context of possibly failing with a helpful message.

ret :: Term (Err a) -> Term aSource

ret term folds term's Err context into the library to be handled internally and as seamlessly as other error messages that are built in.