-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Command line flag parser, very similar to Google's gflags
--   
--   The <tt>HFlags</tt> library supports easy definition of command line
--   flags, reimplementing the ideas from Google's <tt>gflags</tt>
--   (<a>http://code.google.com/p/gflags</a>).
--   
--   Command line flags can be declared in any file at the toplevel, using
--   <a>defineFlag</a>. At runtime, the actual values are assigned to the
--   toplevel <tt>flags_name</tt> constants. Those can be used purely
--   throughout the program.
--   
--   At the beginning of the <tt>main</tt> function, <tt>$initHFlags
--   "program description"</tt> has to be called to initialize the flags.
--   All flags will be initialized that are transitively reachable via
--   imports from <tt>main</tt>. This means, that any Haskell package can
--   easily define command line flags with <tt>HFlags</tt>. This feature is
--   demonstrated by
--   <a>http://github.com/errge/hflags/blob/master/examples/ImportExample.hs</a>
--   and
--   <a>http://github.com/errge/hflags/tree/master/examples/package</a>.
--   
--   A simple example (more in the
--   <a>http://github.com/errge/hflags/tree/master/examples</a> directory):
--   
--   <pre>
--   #!/usr/bin/env runhaskell
--   
--   {-# LANGUAGE TemplateHaskell #-}
--   
--   import HFlags
--   
--   <a>defineFlag</a> "name" "Indiana Jones" "Who to greet."
--   <a>defineFlag</a> "r:repeat" (3 + 4 :: Int) "Number of times to repeat the message."
--   
--   main = do s &lt;- $initHFlags "Simple program v0.1"
--             sequence_ $ replicate flags_repeat greet
--             putStrLn $ "Your additional arguments were: " ++ show s
--             putStrLn $ "Which is the same as: " ++ show HFlags.arguments
--     where
--       greet = putStrLn $ "Hello " ++ flags_name ++ ", very nice to meet you!"
--   </pre>
--   
--   At <tt>initHFlags</tt> time, the library also tries to gather flags
--   out of environment variables. <tt>HFLAGS_verbose=True</tt> is
--   equivalent to specify --verbose=True. This environment feature only
--   works with long options and the user has to specify a value even for
--   Bools.
--   
--   <i>Since version 0.2, you mustn't put the initHFlags in a parentheses
--   with the program description. Just</i> <tt>$initHFlags</tt>, <i>it's
--   cleaner.</i>
--   
--   See <a>http://github.com/errge/hflags/tree/master/changelog</a> for
--   recent changes.
@package hflags
@version 0.4.3


-- | The <tt>HFlags</tt> library supports easy definition of command line
--   flags, reimplementing the ideas from Google's <tt>gflags</tt>
--   (<a>http://code.google.com/p/gflags</a>).
--   
--   Command line flags can be declared in any file at the toplevel, using
--   <a>defineFlag</a>. At runtime, the actual values are assigned to the
--   toplevel <tt>flags_name</tt> constants. Those can be used purely
--   throughout the program.
--   
--   At the beginning of the <tt>main</tt> function, <tt>$<a>initHFlags</a>
--   "program description"</tt> has to be called to initialize the flags.
--   All flags will be initialized that are transitively reachable via
--   imports from <tt>main</tt>. This means, that any Haskell package can
--   easily define command line flags with <tt>HFlags</tt>. This feature is
--   demonstrated by
--   <a>http://github.com/errge/hflags/blob/master/examples/ImportExample.hs</a>
--   and
--   <a>http://github.com/errge/hflags/tree/master/examples/package</a>.
--   
--   A simple example (more in the
--   <a>http://github.com/errge/hflags/tree/master/examples</a> directory):
--   
--   <pre>
--   #!/usr/bin/env runhaskell
--   
--   {-# LANGUAGE TemplateHaskell #-}
--   
--   import HFlags
--   
--   defineFlag "name" "Indiana Jones" "Who to greet."
--   defineFlag "r:repeat" (3 + 4 :: Int) "Number of times to repeat the message."
--   
--   main = do s &lt;- $initHFlags "Simple program v0.1"
--             sequence_ $ replicate flags_repeat greet
--             putStrLn $ "Your additional arguments were: " ++ show s
--             putStrLn $ "Which is the same as: " ++ show HFlags.arguments
--     where
--       greet = putStrLn $ "Hello " ++ flags_name ++ ", very nice to meet you!"
--   </pre>
--   
--   At <a>initHFlags</a> time, the library also tries to gather flags out
--   of environment variables. <tt>HFLAGS_verbose=True</tt> is equivalent
--   to specifying <tt>--verbose=True</tt> on the command line. This
--   environment feature only works with long options and the user has to
--   specify a value even for <tt>Bool</tt>s.
--   
--   <i>Since version 0.2, you mustn't put the initHFlags in a parentheses
--   with the program description. Just</i> <tt>$initHFlags</tt>, <i>it's
--   cleaner.</i>
module HFlags

-- | The most flexible way of defining a flag. For an example see
--   <a>http://github.com/errge/hflags/blob/master/examples/ComplexExample.hs</a>.
--   For most things <a>defineFlag</a> should be enough instead.
--   
--   The parameters:
--   
--   <ul>
--   <li>name of the flag (<tt>l:long</tt> syntax if you want to have the
--   short option <tt>l</tt> for this flag),</li>
--   <li>expression quoted and type signed default value,</li>
--   <li>help string identifying the type of the argument (e.g.
--   INTLIST),</li>
--   <li>read function, expression quoted,</li>
--   <li>show function, expression quoted,</li>
--   <li>help string for the flag.</li>
--   </ul>
defineCustomFlag :: String -> ExpQ -> String -> ExpQ -> ExpQ -> String -> Q [Dec]

-- | This just forwards to <a>defineCustomFlag</a> with <tt>[| read |]</tt>
--   and <tt>[| show |]</tt>. Useful for flags where the type is not an
--   instance of <a>FlagType</a>. For examples, see
--   <a>http://github.com/errge/hflags/blob/master/examples/ComplexExample.hs</a>.
--   
--   The parameters:
--   
--   <ul>
--   <li>name of the flag (<tt>l:long</tt> syntax if you want to have the
--   short option <tt>l</tt> for this flag),</li>
--   <li>expression quoted and type signed default value,</li>
--   <li>help string identifying the type of the argument (e.g.
--   INTLIST),</li>
--   <li>help string for the flag.</li>
--   </ul>
defineEQFlag :: String -> ExpQ -> String -> String -> Q [Dec]

-- | Class of types for which the easy <a>defineFlag</a> syntax is
--   supported.
class FlagType t

-- | The <tt>defineFlag</tt> function defines a new flag.
--   
--   The parameters:
--   
--   <ul>
--   <li>name of the flag (<tt>l:long</tt> syntax if you want to have the
--   short option <tt>l</tt> for this flag),,</li>
--   <li>default value,</li>
--   <li>help string for the flag.</li>
--   </ul>
defineFlag :: FlagType t => String -> t -> String -> Q [Dec]

-- | Has to be called from the main before doing anything else:
--   
--   <pre>
--   main = do args &lt;- $initHFlags "Simple program v0.1"
--             ...
--   </pre>
--   
--   <i>Since version 0.2, you mustn't put the initHFlags in a parentheses
--   with the program description. Just</i> <tt>$initHFlags</tt>, <i>it's
--   cleaner.</i>
--   
--   Internally, it uses Template Haskell trickery to gather all the
--   instances of the Flag class and then generates a call to
--   <tt>initFlags</tt> with the appropriate data gathered together from
--   those instances to a list.
--   
--   Type after splicing is <tt>String -&gt; IO [String]</tt>.
initHFlags :: ExpQ

-- | Same as initHFlags, but makes it possible to introduce programmatic
--   defaults based on user supplied flag values.
--   
--   The second parameter has to be a function that gets the following
--   alists:
--   
--   <ul>
--   <li>defaults,</li>
--   <li>values from HFLAGS_* environment variables,</li>
--   <li>command line options.</li>
--   </ul>
--   
--   Has to return an alist that contains the additional defaults that will
--   override the default flag values (but not the user supplied values:
--   environment or command line).
--   
--   Type after splicing is <tt>String -&gt; DependentDefaults -&gt; IO
--   [String]</tt>. Where:
--   
--   <ul>
--   <li><pre>type AList = [(String, String)]</pre></li>
--   <li><pre>type DependentDefaults = AList -&gt; AList -&gt; AList -&gt;
--   AList</pre></li>
--   </ul>
initHFlagsDependentDefaults :: ExpQ

-- | Contains the non-parsed, non-option parts of the command line, the
--   arguments. Can only be used after <a>initHFlags</a> has been called.
arguments :: [String]

-- | Contains the non-parsed, option parts of the command line, if
--   <tt>--undefok</tt> is in use. This can be useful, when you have to
--   pass these options to other libraries, e.g. <tt>criterion</tt> or
--   <tt>GTK</tt>. Can only be used after <a>initHFlags</a> has been
--   called.
undefinedOptions :: [String]

-- | Every flag the program supports has to be defined through a new
--   phantom datatype and the Flag instance of that datatype.
--   
--   But users of the library shouldn't worry about this class or the
--   implementation details behind these functions, just use the
--   <tt>defineFlag</tt> Template Haskell function for defining new flags.
class Flag a
getFlagData :: Flag a => a -> FlagData

-- | This is a temporary hack to force visibility of flags inside
--   libraries, by making the module that defines the flag orphan. For
--   usage example, check out
--   <a>http://github.com/errge/hflags/blob/master/examples/package/Tup.hs</a>.
--   A proper fix is already proposed for GHC 7.8, see
--   <a>http://ghc.haskell.org/trac/ghc/ticket/7867</a>.
data MakeThisOrphan
MakeThisOrphan :: MakeThisOrphan

-- | A global <a>IORef</a> for the communication between <a>initHFlags</a>
--   and <tt>flags_*</tt>. This is a map between flag name and current
--   value.
globalHFlags :: IORef (Maybe (Map String String))

-- | A global <a>IORef</a> for the easy access to the arguments.
globalArguments :: IORef (Maybe [String])

-- | A global <a>IORef</a> for the easy access to the undefined options, if
--   <tt>--undefok</tt> is used. Useful, if you have to pass these options
--   to another library, e.g. <tt>criterion</tt> or <tt>GTK</tt>.
globalUndefinedOptions :: IORef (Maybe [String])
instance HFlags.FlagType GHC.Types.Bool
instance HFlags.FlagType GHC.Types.Char
instance HFlags.FlagType GHC.Types.Int
instance HFlags.FlagType GHC.Integer.Type.Integer
instance HFlags.FlagType GHC.Base.String
instance HFlags.FlagType GHC.Types.Double
instance HFlags.FlagType Data.Text.Internal.Text
instance GHC.Show.Show HFlags.FlagData
