<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>System.Console.GetOpt</title><link href="ocean.css" rel="stylesheet" type="text/css" title="Ocean" /><script src="haddock-util.js" type="text/javascript"></script><script type="text/javascript">//<![CDATA[
window.onload = function () {pageLoad();setSynopsis("mini_System-Console-GetOpt.html");};
//]]>
</script></head><body><div id="package-header"><ul class="links" id="page-menu"><li><a href="index.html">Contents</a></li><li><a href="doc-index.html">Index</a></li></ul><p class="caption">base-4.5.1.0: Basic libraries</p></div><div id="content"><div id="module-header"><table class="info"><tr><th>Portability</th><td>portable</td></tr><tr><th>Stability</th><td>experimental</td></tr><tr><th>Maintainer</th><td>libraries@haskell.org</td></tr><tr><th>Safe Haskell</th><td>Safe</td></tr></table><p class="caption">System.Console.GetOpt</p></div><div id="table-of-contents"><p class="caption">Contents</p><ul><li><a href="#g:1">GetOpt
</a></li><li><a href="#g:2">Examples
</a><ul><li><a href="#g:3">Interpreting flags as concrete values
</a></li><li><a href="#g:4">Interpreting flags as transformations of an options record
</a></li></ul></li></ul></div><div id="description"><p class="caption">Description</p><div class="doc"><p>This library provides facilities for parsing the command-line options
in a standalone program. It is essentially a Haskell port of the GNU
<code>getopt</code> library.
</p></div></div><div id="synopsis"><p id="control.syn" class="caption expander" onclick="toggleSection('syn')">Synopsis</p><ul id="section.syn" class="hide" onclick="toggleSection('syn')"><li class="src short"><a href="#v:getOpt">getOpt</a> :: <a href="System-Console-GetOpt.html#t:ArgOrder">ArgOrder</a> a -> [<a href="System-Console-GetOpt.html#t:OptDescr">OptDescr</a> a] -> [<a href="Data-String.html#t:String">String</a>] -> ([a], [<a href="Data-String.html#t:String">String</a>], [<a href="Data-String.html#t:String">String</a>])</li><li class="src short"><a href="#v:getOpt-39-">getOpt'</a> :: <a href="System-Console-GetOpt.html#t:ArgOrder">ArgOrder</a> a -> [<a href="System-Console-GetOpt.html#t:OptDescr">OptDescr</a> a] -> [<a href="Data-String.html#t:String">String</a>] -> ([a], [<a href="Data-String.html#t:String">String</a>], [<a href="Data-String.html#t:String">String</a>], [<a href="Data-String.html#t:String">String</a>])</li><li class="src short"><a href="#v:usageInfo">usageInfo</a> :: <a href="Data-String.html#t:String">String</a> -> [<a href="System-Console-GetOpt.html#t:OptDescr">OptDescr</a> a] -> <a href="Data-String.html#t:String">String</a></li><li class="src short"><span class="keyword">data</span> <a href="#t:ArgOrder">ArgOrder</a> a<ul class="subs"><li>= <a href="#v:RequireOrder">RequireOrder</a> </li><li>| <a href="#v:Permute">Permute</a> </li><li>| <a href="#v:ReturnInOrder">ReturnInOrder</a> (<a href="Data-String.html#t:String">String</a> -> a) </li></ul></li><li class="src short"><span class="keyword">data</span> <a href="#t:OptDescr">OptDescr</a> a = <a href="#v:Option">Option</a> [<a href="Data-Char.html#t:Char">Char</a>] [<a href="Data-String.html#t:String">String</a>] (<a href="System-Console-GetOpt.html#t:ArgDescr">ArgDescr</a> a) <a href="Data-String.html#t:String">String</a></li><li class="src short"><span class="keyword">data</span> <a href="#t:ArgDescr">ArgDescr</a> a<ul class="subs"><li>= <a href="#v:NoArg">NoArg</a> a </li><li>| <a href="#v:ReqArg">ReqArg</a> (<a href="Data-String.html#t:String">String</a> -> a) <a href="Data-String.html#t:String">String</a> </li><li>| <a href="#v:OptArg">OptArg</a> (<a href="Data-Maybe.html#t:Maybe">Maybe</a> <a href="Data-String.html#t:String">String</a> -> a) <a href="Data-String.html#t:String">String</a> </li></ul></li></ul></div><div id="interface"><h1 id="g:1">GetOpt
</h1><div class="top"><p class="src"><a name="v:getOpt" class="def">getOpt</a> :: <a href="System-Console-GetOpt.html#t:ArgOrder">ArgOrder</a> a -> [<a href="System-Console-GetOpt.html#t:OptDescr">OptDescr</a> a] -> [<a href="Data-String.html#t:String">String</a>] -> ([a], [<a href="Data-String.html#t:String">String</a>], [<a href="Data-String.html#t:String">String</a>])</p><div class="doc"><p>Process the command-line, and return the list of values that matched
(and those that didn't). The arguments are:
</p><ul><li> The order requirements (see <code><a href="System-Console-GetOpt.html#t:ArgOrder">ArgOrder</a></code>)
</li><li> The option descriptions (see <code><a href="System-Console-GetOpt.html#t:OptDescr">OptDescr</a></code>)
</li><li> The actual command line arguments (presumably got from
<code><a href="System-Environment.html#v:getArgs">getArgs</a></code>).
</li></ul><p><code><a href="System-Console-GetOpt.html#v:getOpt">getOpt</a></code> returns a triple consisting of the option arguments, a list
of non-options, and a list of error messages.
</p></div></div><div class="top"><p class="src"><a name="v:getOpt-39-" class="def">getOpt'</a> :: <a href="System-Console-GetOpt.html#t:ArgOrder">ArgOrder</a> a -> [<a href="System-Console-GetOpt.html#t:OptDescr">OptDescr</a> a] -> [<a href="Data-String.html#t:String">String</a>] -> ([a], [<a href="Data-String.html#t:String">String</a>], [<a href="Data-String.html#t:String">String</a>], [<a href="Data-String.html#t:String">String</a>])</p><div class="doc"><p>This is almost the same as <code><a href="System-Console-GetOpt.html#v:getOpt">getOpt</a></code>, but returns a quadruple
consisting of the option arguments, a list of non-options, a list of
unrecognized options, and a list of error messages.
</p></div></div><div class="top"><p class="src"><a name="v:usageInfo" class="def">usageInfo</a> :: <a href="Data-String.html#t:String">String</a> -> [<a href="System-Console-GetOpt.html#t:OptDescr">OptDescr</a> a] -> <a href="Data-String.html#t:String">String</a></p><div class="doc"><p>Return a string describing the usage of a command, derived from
the header (first argument) and the options described by the
second argument.
</p></div></div><div class="top"><p class="src"><span class="keyword">data</span> <a name="t:ArgOrder" class="def">ArgOrder</a> a </p><div class="doc"><p>What to do with options following non-options
</p></div><div class="subs constructors"><p class="caption">Constructors</p><table><tr><td class="src"><a name="v:RequireOrder" class="def">RequireOrder</a></td><td class="doc"><p>no option processing after first non-option
</p></td></tr><tr><td class="src"><a name="v:Permute" class="def">Permute</a></td><td class="doc"><p>freely intersperse options and non-options
</p></td></tr><tr><td class="src"><a name="v:ReturnInOrder" class="def">ReturnInOrder</a> (<a href="Data-String.html#t:String">String</a> -> a)</td><td class="doc"><p>wrap non-options into options
</p></td></tr></table></div></div><div class="top"><p class="src"><span class="keyword">data</span> <a name="t:OptDescr" class="def">OptDescr</a> a </p><div class="doc"><p>Each <code><a href="System-Console-GetOpt.html#t:OptDescr">OptDescr</a></code> describes a single option.
</p><p>The arguments to <code><a href="System-Console-GetOpt.html#v:Option">Option</a></code> are:
</p><ul><li> list of short option characters
</li><li> list of long option strings (without "--")
</li><li> argument descriptor
</li><li> explanation of option for user
</li></ul></div><div class="subs constructors"><p class="caption">Constructors</p><table><tr><td class="src"><a name="v:Option" class="def">Option</a> [<a href="Data-Char.html#t:Char">Char</a>] [<a href="Data-String.html#t:String">String</a>] (<a href="System-Console-GetOpt.html#t:ArgDescr">ArgDescr</a> a) <a href="Data-String.html#t:String">String</a></td><td class="doc empty"> </td></tr></table></div></div><div class="top"><p class="src"><span class="keyword">data</span> <a name="t:ArgDescr" class="def">ArgDescr</a> a </p><div class="doc"><p>Describes whether an option takes an argument or not, and if so
how the argument is injected into a value of type <code>a</code>.
</p></div><div class="subs constructors"><p class="caption">Constructors</p><table><tr><td class="src"><a name="v:NoArg" class="def">NoArg</a> a</td><td class="doc"><p>no argument expected
</p></td></tr><tr><td class="src"><a name="v:ReqArg" class="def">ReqArg</a> (<a href="Data-String.html#t:String">String</a> -> a) <a href="Data-String.html#t:String">String</a></td><td class="doc"><p>option requires argument
</p></td></tr><tr><td class="src"><a name="v:OptArg" class="def">OptArg</a> (<a href="Data-Maybe.html#t:Maybe">Maybe</a> <a href="Data-String.html#t:String">String</a> -> a) <a href="Data-String.html#t:String">String</a></td><td class="doc"><p>optional argument
</p></td></tr></table></div></div><h1 id="g:2">Examples
</h1><div class="doc"><p>To hopefully illuminate the role of the different data structures,
here are the command-line options for a (very simple) compiler,
done in two different ways.
The difference arises because the type of <code><a href="System-Console-GetOpt.html#v:getOpt">getOpt</a></code> is
parameterized by the type of values derived from flags.
</p></div><h2 id="g:3">Interpreting flags as concrete values
</h2><div class="doc"><p>A simple choice for the type associated with flags is to define a type
<code>Flag</code> as an algebraic type representing the possible flags and their
arguments:
</p><pre> module Opts1 where
import System.Console.GetOpt
import Data.Maybe ( fromMaybe )
data Flag
= Verbose | Version
| Input String | Output String | LibDir String
deriving Show
options :: [OptDescr Flag]
options =
[ Option ['v'] ["verbose"] (NoArg Verbose) "chatty output on stderr"
, Option ['V','?'] ["version"] (NoArg Version) "show version number"
, Option ['o'] ["output"] (OptArg outp "FILE") "output FILE"
, Option ['c'] [] (OptArg inp "FILE") "input FILE"
, Option ['L'] ["libdir"] (ReqArg LibDir "DIR") "library directory"
]
inp,outp :: Maybe String -> Flag
outp = Output . fromMaybe "stdout"
inp = Input . fromMaybe "stdin"
compilerOpts :: [String] -> IO ([Flag], [String])
compilerOpts argv =
case getOpt Permute options argv of
(o,n,[] ) -> return (o,n)
(_,_,errs) -> ioError (userError (concat errs ++ usageInfo header options))
where header = "Usage: ic [OPTION...] files..."
</pre><p>Then the rest of the program will use the constructed list of flags
to determine it's behaviour.
</p></div><h2 id="g:4">Interpreting flags as transformations of an options record
</h2><div class="doc"><p>A different approach is to group the option values in a record of type
<code>Options</code>, and have each flag yield a function of type
<code>Options -> Options</code> transforming this record.
</p><pre> module Opts2 where
import System.Console.GetOpt
import Data.Maybe ( fromMaybe )
data Options = Options
{ optVerbose :: Bool
, optShowVersion :: Bool
, optOutput :: Maybe FilePath
, optInput :: Maybe FilePath
, optLibDirs :: [FilePath]
} deriving Show
defaultOptions = Options
{ optVerbose = False
, optShowVersion = False
, optOutput = Nothing
, optInput = Nothing
, optLibDirs = []
}
options :: [OptDescr (Options -> Options)]
options =
[ Option ['v'] ["verbose"]
(NoArg (\ opts -> opts { optVerbose = True }))
"chatty output on stderr"
, Option ['V','?'] ["version"]
(NoArg (\ opts -> opts { optShowVersion = True }))
"show version number"
, Option ['o'] ["output"]
(OptArg ((\ f opts -> opts { optOutput = Just f }) . fromMaybe "output")
"FILE")
"output FILE"
, Option ['c'] []
(OptArg ((\ f opts -> opts { optInput = Just f }) . fromMaybe "input")
"FILE")
"input FILE"
, Option ['L'] ["libdir"]
(ReqArg (\ d opts -> opts { optLibDirs = optLibDirs opts ++ [d] }) "DIR")
"library directory"
]
compilerOpts :: [String] -> IO (Options, [String])
compilerOpts argv =
case getOpt Permute options argv of
(o,n,[] ) -> return (foldl (flip id) defaultOptions o, n)
(_,_,errs) -> ioError (userError (concat errs ++ usageInfo header options))
where header = "Usage: ic [OPTION...] files..."
</pre><p>Similarly, each flag could yield a monadic function transforming a record,
of type <code>Options -> IO Options</code> (or any other monad), allowing option
processing to perform actions of the chosen monad, e.g. printing help or
version messages, checking that file arguments exist, etc.
</p></div></div></div><div id="footer"><p>Produced by <a href="http://www.haskell.org/haddock/">Haddock</a> version 2.11.0</p></div></body></html>
distrib
>
Mageia
>
5
>
i586
>
media
>
core-release
>
by-pkgid
>
6e204a966e8c42d976f99a1700ce5f20
>
files
>
2321
