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


-- | A simple, forward build system.
--   
--   Dib is a simple, forward build system consisting of a library and a
--   driver application. Build scripts are written in Haskell instead of a
--   bespoke language.
@package dib
@version 0.7.2


-- | Module exposing the <a>Stage</a> type and related type wrappers, along
--   with a convenience <a>emptyStage</a>.
module Dib.Stage

-- | Type describing a build stage. Takes a name, an
--   <a>InputTransformer</a>, <a>DepScanner</a>, additional dependencies,
--   and the builder function.
data Stage
Stage :: Text -> InputTransformer -> DepScanner -> [Text] -> StageFunc -> Stage

-- | Type wrapper for functions transforming a list of <a>SrcTransform</a>s
--   into a list of <a>SrcTransform</a>s suitable for passing into the
--   <a>DepScanner</a>.
type InputTransformer = ([SrcTransform] -> [SrcTransform])

-- | Type wrapper for a function that takes a <a>SrcTransform</a> and
--   produces a <a>SrcTransform</a> with dependencies included in the
--   input.
type DepScanner = (SrcTransform -> IO SrcTransform)

-- | Type wrapper for a function that given a <a>SrcTransform</a>, produces
--   either a <a>SrcTransform</a> containing the output files in the input,
--   or an error.
type StageFunc = (SrcTransform -> IO StageResult)

-- | A stage that does nothing and just passes the <a>SrcTransform</a>s
--   through.
emptyStage :: Stage


-- | C dependency scanner. Runs a stripped-down pre-processor to scan for
--   include files (recursively).
module Dib.Scanners.CDepScanner

-- | Takes in a list of include directories, extra dependencies, a
--   <a>SrcTransform</a>, and returns a new <a>SrcTransform</a> with the
--   dependencies injected into the source side.
cDepScanner :: [FilePath] -> SrcTransform -> IO SrcTransform
instance Control.Monad.State.Class.MonadState Dib.Scanners.CDepScanner.ParseState Dib.Scanners.CDepScanner.DepGatherer
instance Control.Monad.IO.Class.MonadIO Dib.Scanners.CDepScanner.DepGatherer
instance GHC.Base.Monad Dib.Scanners.CDepScanner.DepGatherer
instance GHC.Base.Applicative Dib.Scanners.CDepScanner.DepGatherer
instance GHC.Base.Functor Dib.Scanners.CDepScanner.DepGatherer
instance GHC.Show.Show Dib.Scanners.CDepScanner.ParseState
instance GHC.Show.Show Dib.Scanners.CDepScanner.Dependency
instance GHC.Classes.Eq Dib.Scanners.CDepScanner.Dependency
instance GHC.Classes.Ord Dib.Scanners.CDepScanner.Dependency


-- | Module that exposes all of the various <a>GatherStrategy</a> types and
--   functions for dealing with them.
module Dib.Gatherers

-- | <a>Gatherer</a> that will return exactly one file.
data SingleFileGatherer

-- | <a>Gatherer</a> that will return all files in a given directory (but
--   not its subdirectories) that pass the filter.
data DirectoryGatherer

-- | <a>Gatherer</a> that will return all files in a given directory tree
--   that pass the filter.
data FileTreeGatherer

-- | Existential data type for wrapping <a>GatherStrategy</a>s so they can
--   be used as a uniform type.
data Gatherer

-- | <a>Gatherer</a> that will run a command and return an empty list.
--   Useful for making clean <a>Target</a>s. Use sparingly.
data CommandGatherer

-- | Convenience function to turn a <a>GatherStrategy</a> into a
--   <a>Gatherer</a>.
wrapGatherStrategy :: GatherStrategy s => s -> Gatherer

-- | Runs a list of <a>Gatherer</a>s and returns the concatenation of their
--   output.
runGatherers :: [Gatherer] -> IO [Text]

-- | Constructs a <a>Gatherer</a> that returns a single file.
makeSingleFileGatherer :: Text -> Gatherer

-- | Constructs a <a>Gatherer</a> that returns all files in a directory
--   (but not its subdirectories) that match a given filter.
makeDirectoryGatherer :: Text -> FilterFunc -> Gatherer

-- | Constructs a <a>Gatherer</a> that returns all files in a directory
--   tree that match a given filter.
makeFileTreeGatherer :: Text -> FilterFunc -> Gatherer

-- | Constructs a <a>Gatherer</a> that runs an arbitrary <a>IO</a> action.
makeCommandGatherer :: IO () -> Gatherer

-- | Filter function that returns all files.
matchAll :: FilterFunc

-- | Filter function that returns files with a given extension.
matchExtension :: Text -> FilterFunc

-- | Filter function that returns files with a given extension that don't
--   match exclusion rules.
matchExtensionExcluded :: Text -> [Text -> Bool] -> FilterFunc

-- | Filter function that returns files that match any of a list of
--   extensions.
matchExtensions :: [Text] -> FilterFunc

-- | Filter function that returns files that match any of a list of
--   extensions, but don't match the exclusion rules.
matchExtensionsExcluded :: [Text] -> [Text -> Bool] -> FilterFunc
instance Dib.Types.GatherStrategy Dib.Types.SingleFileGatherer
instance Dib.Types.GatherStrategy Dib.Types.DirectoryGatherer
instance Dib.Types.GatherStrategy Dib.Types.FileTreeGatherer
instance Dib.Types.GatherStrategy Dib.Types.CommandGatherer


-- | Module that exposes the <a>Target</a> data type and a handful of
--   convenience functions for dealing with <a>Target</a>s.
module Dib.Target

-- | Describes a build target. Takes a name, checksum function, list of
--   dependencies, list of <a>Stage</a>s, and a list of <a>Gatherer</a>s.
data Target
Target :: Text -> ChecksumFunc -> [Target] -> [Stage] -> [Gatherer] -> Target

-- | Adds a dependency on another <a>Target</a>.
addDependency :: Target -> Target -> Target

-- | Adds a dependency on a list of <a>Target</a>s.
addDependencies :: Target -> [Target] -> Target

-- | Gets dependencies of a <a>Target</a>.
getDependencies :: Target -> [Target]

-- | Makes a <a>Target</a> that doesn't build anything but can be used as a
--   meta <a>Target</a>, i.e. the "all" target in make.
makePhonyTarget :: Text -> [Target] -> Target

-- | Makes a <a>Target</a> that runs an arbitrary <a>IO</a> action.
makeCommandTarget :: Text -> [Target] -> IO () -> Target

-- | Computes a checksum from the direct dependencies of a target
targetDepChecksum :: Target -> Word32


-- | A trivial builder that copies a directory tree from one location to
--   another.
module Dib.Builders.Copy

-- | The <a>makeCopyTarget</a> function makes a target that copies a
--   directory tree. It takes a name, a source directory, destination
--   directory, and gather filter.
makeCopyTarget :: Text -> Text -> Text -> FilterFunc -> [Text] -> Target


-- | <h1>Introduction</h1>
--   
--   Dib is a light-weight, forward build system embedded in Haskell. Dib
--   represents the build products as a chain of operations starting at the
--   input. Reverse build systems such as Make and Jam instead attempt to
--   figure out the operations to perform starting at the desired output
--   and tracing back through a set of rules to find the correct input
--   file. Dib has no such notion of "rules" and the general thought
--   process for writing a build script answers the question "I have these
--   files, how do I build them into the thing I want?", versus a reverse
--   build system which answers (recursively) "I want this product, what
--   files do I need to use as input?".
--   
--   <h1>Concepts</h1>
--   
--   <ul>
--   <li><a>Target</a> - The most granluar unit of a build. Represents a
--   desired outcome: e.g. an executable, a folder of files, etc...
--   Contains <a>Stage</a>s, which do the actual work. Somewhat
--   unfortunately, a 'Target'\'s name is its only identifier in the cache
--   database, so debug/release and multiplatform <a>Target</a> variants
--   should be named accordingly to prevent full-rebuilds when switching
--   between them.</li>
--   <li><a>Stage</a> - A portion of a pipeline for transforming input data
--   into output data. These separate major portions of a pipeline: e.g.
--   building source code into object files, linking object files into an
--   executable, copying some data into place. <a>Target</a>s can have
--   multiple <a>Stage</a>s, which are executed in sequence, the output of
--   one is used as the input to the next.</li>
--   <li><a>Gatherer</a> - Used to generate the initial input
--   <a>SrcTransform</a>s for the first <a>Stage</a> of a
--   <a>Target</a>.</li>
--   <li><a>SrcTransform</a> - Represents a mapping from input to output.
--   Comes in four varieties: <a>OneToOne</a>, <a>OneToMany</a>,
--   <a>ManyToOne</a>, <a>ManyToMany</a>. Some examples: compiling a C
--   source file into an object file initially begins as a <a>OneToOne</a>,
--   but is converted into a <a>ManyToOne</a> through dependency scanning
--   (adding the dependencies to the input exploits the internal timestamp
--   database for free). Copying files from one location to another would
--   just be a simple <a>OneToOne</a>. A tool that takes in one file and
--   generates a bunch of output files would use <a>OneToMany</a>.</li>
--   </ul>
--   
--   <h1>Getting Started</h1>
--   
--   Dib is both a library and an executable. The executable exists to
--   cause a rebuild of the build script whenever it changes, and also as a
--   convenience for invoking both the build and execution correctly. It's
--   recommended that it be used for everything except extraordinary use
--   cases. It can also generate an initial build script through the use of
--   <tt>dib --init</tt>. Run the dib executable with no options for more
--   information on the available templates.
--   
--   An example of using the C Builder to build an executable called
--   "myProject" with its source code in the "src/" directory is as
--   follows:
--   
--   <pre>
--   module Main where
--   
--   import Dib
--   import Dib.Builders.C
--   import qualified Data.Text as T
--   
--   projectInfo = defaultGCCConfig {
--     outputName = "myProject",
--     targetName = "myProject",
--     srcDir = "src",
--     compileFlags = "",
--     linkFlags = "",
--     outputLocation = ObjAndBinDirs "obj" ".",
--     includeDirs = ["src"]
--   }
--   
--   project = makeCTarget projectInfo
--   clean = makeCleanTarget projectInfo
--   
--   targets = [project, clean]
--   
--   main = dib targets
--   </pre>
--   
--   This was generated with <tt>dib --init c myProject gcc src</tt>.
--   
--   A build script is expected to declare the available <a>Target</a>s and
--   then pass them to the <a>dib</a> function. Only the top-level
--   <a>Target</a>s need to be passed to <a>dib</a>; it will scrape out the
--   dependencies from there. The first <a>Target</a> in the list is the
--   default <a>Target</a> to build if the dib executable is called with no
--   arguments.
--   
--   <h2>Additional Information</h2>
--   
--   Arguments can be passed on the command line to the dib executable.
--   These can be retrieved in the build with <a>getArgDict</a>. The user
--   is also free to use environment variables as parameter input.
--   
--   The invocation might look like the following: <tt>dib <a>target</a>
--   <a>key</a>=<a>value</a> <a>key</a>=<a>value</a> ...</tt>. Please note
--   that there are no spaces between the keys and values. Quoted strings
--   are untested and unlikely to work correctly. The <a>Target</a> is
--   optional, and can appear anywhere in the command. If no <a>Target</a>
--   is specified, the default will be used.
module Dib

-- | Data type for expressing mapping of input files to output files
data SrcTransform

-- | One input to one output file.
OneToOne :: Text -> Text -> SrcTransform

-- | One input file to many output files.
OneToMany :: Text -> [Text] -> SrcTransform

-- | Many input files to one output file.
ManyToOne :: [Text] -> Text -> SrcTransform

-- | Many input to many output files.
ManyToMany :: [Text] -> [Text] -> SrcTransform

-- | The function that should be called to dispatch the build. Takes a list
--   of the top-level (root) <a>Target</a>s.
dib :: [Target] -> IO ()

-- | Returns the argument dictionary.
getArgDict :: IO ArgDict

-- | Adds all of the variables in the execution environment into the
--   argument dictionary. Allows for make-like variable passing.
addEnvToDict :: ArgDict -> [(String, String)] -> IO ArgDict

-- | Makes a function that can be used to look up a value in the argument
--   dictionary, returning a default value if the argument does not exist.
makeArgDictLookupFunc :: String -> String -> ArgDict -> String

-- | Makes a function that can be used to look up a value in the argument
--   dictionary, returning a default value if the argument does not exist,
--   and checking success against a list of valid values. Returns an error
--   string on Left, and success string on Right.
makeArgDictLookupFuncChecked :: String -> String -> [String] -> ArgDict -> Either String String


-- | Module containing utility functions and common functionality.
module Dib.Util

-- | Given a directory, returns the list of subdirectories.
getSubDirectories :: FilePath -> IO [FilePath]

-- | A utility function for handling <a>ExitCode</a>s in
--   <tt>StageFunction</tt>s.
handleExitCode :: ExitCode -> Text -> String -> IO StageResult


-- | The Simple builder allows you to execute a <a>OneToOne</a>
--   trasformation given a function that generates a command line from the
--   source and target files.
module Dib.Builders.Simple

-- | The <a>makeSimpleTarget</a> function generates a target. It takes a
--   name, source directory, destination directory, destination extension,
--   gather filter, and a function to build the command line.
makeSimpleTarget :: Text -> Text -> Text -> Text -> FilterFunc -> [Text] -> (String -> String -> String) -> Target


-- | A builder for C/C++ code.
module Dib.Builders.C

-- | The record type that is used to pass configuration info for the C
--   builder.
data CTargetInfo
CTargetInfo :: Text -> Text -> Text -> BuildLocation -> Text -> Text -> Text -> Text -> Text -> Text -> Text -> Text -> Text -> Text -> Text -> [Text] -> [Text] -> [Text] -> [Text] -> Bool -> CTargetInfo

-- | The data type for specifying where built files end up.
data BuildLocation

-- | Specifies that object files will end up adjacent to their source files
--   and the executable will be in the same directory as the dib.hs file.
InPlace :: BuildLocation

-- | Specifies that the object files and executable will go in a certain
--   directory.
BuildDir :: Text -> BuildLocation

-- | Specifies that the object files will go in the first directory and the
--   executable in the second directory.
ObjAndBinDirs :: Text -> Text -> BuildLocation

-- | Given a <a>CTargetInfo</a>, produces a <a>Target</a>
makeCTarget :: CTargetInfo -> Target

-- | Given a <a>CTargetInfo</a>, produces a <a>Target</a> that will clean
--   the project.
makeCleanTarget :: CTargetInfo -> Target

-- | Given a <a>CTargetInfo</a>, will make the directories required to
--   build the project.
makeBuildDirs :: CTargetInfo -> IO ()

-- | An empty configuration.
emptyConfig :: CTargetInfo

-- | A default configuration for gcc.
defaultGCCConfig :: CTargetInfo

-- | A default configuration for g++.
defaultGXXConfig :: CTargetInfo

-- | A default configuration for clang.
defaultClangConfig :: CTargetInfo