<!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.3.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></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-Char.html#t:String">String</a>] -> ([a], [<a href="Data-Char.html#t:String">String</a>], [<a href="Data-Char.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-Char.html#t:String">String</a>] -> ([a], [<a href="Data-Char.html#t:String">String</a>], [<a href="Data-Char.html#t:String">String</a>], [<a href="Data-Char.html#t:String">String</a>])</li><li class="src short"><a href="#v:usageInfo">usageInfo</a> :: <a href="Data-Char.html#t:String">String</a> -> [<a href="System-Console-GetOpt.html#t:OptDescr">OptDescr</a> a] -> <a href="Data-Char.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-Char.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-Char.html#t:String">String</a>] (<a href="System-Console-GetOpt.html#t:ArgDescr">ArgDescr</a> a) <a href="Data-Char.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-Char.html#t:String">String</a> -> a) <a href="Data-Char.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-Char.html#t:String">String</a> -> a) <a href="Data-Char.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-Char.html#t:String">String</a>] -> ([a], [<a href="Data-Char.html#t:String">String</a>], [<a href="Data-Char.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>System.Environment.getArgs</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-Char.html#t:String">String</a>] -> ([a], [<a href="Data-Char.html#t:String">String</a>], [<a href="Data-Char.html#t:String">String</a>], [<a href="Data-Char.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-Char.html#t:String">String</a> -> [<a href="System-Console-GetOpt.html#t:OptDescr">OptDescr</a> a] -> <a href="Data-Char.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-Char.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-Char.html#t:String">String</a>] (<a href="System-Console-GetOpt.html#t:ArgDescr">ArgDescr</a> a) <a href="Data-Char.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-Char.html#t:String">String</a> -> a) <a href="Data-Char.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-Char.html#t:String">String</a> -> a) <a href="Data-Char.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.9.2</p></div></body></html>