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


-- | Remove cpp annotations to get the source ready for static analysis.
--   
--   Remove cpp annotations using the configuration with which you build
--   the package, to get the source ready for static analysis with a
--   parsing library like haskell-src-exts.
@package preprocessor
@version 0.1.0.0


-- | After cpp preprocessing, the file is left by the compilation pipeline
--   in the output format of the <tt>cpp</tt> program, described in <a>this
--   section</a> of the C Preprocessor manual.
--   
--   By default, the <tt>cpp</tt> program inserts blank lines to preserve
--   line numbering, but only if the number of blank lines to be created is
--   not too high (&lt;6 or so). Otherwise a linemarker is created, to
--   reduce the size of the generated file, of the form:
--   
--   <pre>
--   # linenum filename flags
--   </pre>
--   
--   As cpp doesn't have an option to output only blank lines and keeping
--   the line numbering, the following functions parse a file with
--   linemarkers separating it in <tt>CppOutputComponents</tt> (the source
--   chunks between the linemarkers), and pad them with the appropriate
--   amount of blank lines.
module Language.C.Preprocessor.Remover.Internal.AddPadding

-- | Substitutes the lineMarker in the content of a file with the
--   appropriate blank line padding.
addPadding :: FilePath -> String -> String

-- | A <a>LineMarker</a> follows the structure described <a>here</a>. We
--   only retain the linenumber and the file the line is referring to. Note
--   that the filename is surrounded by quotation marks in the cpp output,
--   but not in this representation.
data LineMarker
LineMarker :: Int -> FilePath -> LineMarker
[beginsAtLine] :: LineMarker -> Int
[filePath] :: LineMarker -> FilePath

-- | <pre>
--   &gt;&gt;&gt; isLineMarker "# 42 \"/path/to/file\""
--   True
--   </pre>
isLineMarker :: String -> Bool

-- | <pre>
--   &gt;&gt;&gt; parseLineMarker "# 42 \"/path/to/file\""
--   LineMarker {beginsAtLine = 42, filePath = "/path/to/file"}
--   </pre>
parseLineMarker :: String -> LineMarker

-- | A <a>CppOutputComponent</a> is constituted by a <a>LineMarker</a> and
--   the block of code till the next <a>LineMarker</a>.
data CppOutputComponent
CppOutputComponent :: LineMarker -> [String] -> CppOutputComponent
[lineMarker] :: CppOutputComponent -> LineMarker
[sourceBlock] :: CppOutputComponent -> [String]

-- | Given the lines of a file, parses the CppOutputComponents. Note that a
--   file that doesn't need cpp preprocessing doesn't have any
--   <a>LineMarker</a>. In that case a dummy component is created, with an
--   empty path.
parseCppOutputComponents :: [String] -> [CppOutputComponent]

-- | Discard the parts of cpp output which correspond to cpp include files.
--   If there's a unique component then we return that one, otherwise we
--   return all the components relative to our file other than the first
--   (which has no real meaning).
discardUnusefulComponents :: FilePath -> [CppOutputComponent] -> [CppOutputComponent]

-- | Adds padding to the source blocks to mantain the correct line numbers
--   of the source code.
reconstructSource :: [CppOutputComponent] -> [String]
instance GHC.Show.Show Language.C.Preprocessor.Remover.Internal.AddPadding.CppOutputComponent
instance GHC.Show.Show Language.C.Preprocessor.Remover.Internal.AddPadding.LineMarker


module Language.C.Preprocessor.Remover.Internal.Types

-- | <a>CppOptions</a> represent the options which are passed, through the
--   ghc api, to the cpp preprocessing program. For reference, <a>here</a>
--   is the part of the gcc manual corresponding to the preprocessing
--   options.
data CppOptions
CppOptions :: [String] -> [FilePath] -> [FilePath] -> CppOptions

-- | CPP #define macros. Corresponds to a <tt>-D</tt> option for the cpp
--   program.
[cppDefine] :: CppOptions -> [String]

-- | CPP Includes directory. Corresponds to a <tt>-I</tt> option for the
--   cpp program.
[cppInclude] :: CppOptions -> [FilePath]

-- | CPP pre-include file. Corresponds to a <tt>-include</tt> option for
--   the cpp program.
[cppFile] :: CppOptions -> [FilePath]

-- | <pre>
--   &gt;&gt;&gt; emptyCppOptions
--   CppOptions {cppDefine = [], cppInclude = [], cppFile = []}
--   </pre>
emptyCppOptions :: CppOptions

-- | ProjectDir is the directory which contains the .cabal file for the
--   project.
type ProjectDir = FilePath

-- | The path of the main <tt>.cabal</tt> file of the project.
type CabalFilePath = FilePath
instance GHC.Show.Show Language.C.Preprocessor.Remover.Internal.Types.CppOptions


module Language.C.Preprocessor.Remover.Internal.Preprocess

-- | Parse a module with specific instructions for the C pre-processor.
parseModuleWithCpp :: CppOptions -> FilePath -> IO String

-- | Invoke GHC's <a>preprocess</a> function at the cpp phase, adding the
--   options specified in the first argument.
getPreprocessedSrcDirect :: GhcMonad m => CppOptions -> FilePath -> m String


-- | This library preprocesses the cpp directives in haskell source code (a
--   task not usually done by parsing libraries), to prepare it for static
--   analysis, e.g. with <a>haskell-src-exts</a>.
--   
--   The design of the library is guided by two principles:
--   
--   <ul>
--   <li>Line numbering with the original file should be preserved: if a
--   line isn't related to cpp preprocessing, it conserves its position.
--   This is done to make eventual failings with the parsing library easier
--   to locate.</li>
--   <li>It should offer a very simple API, shielding the user from the
--   understandings of how cabal options are passed around, and trying to
--   automatically find all the required information in the project. The
--   user is expected to use only the two functions in this module.</li>
--   </ul>
--   
--   Currently this tool <b>requires</b> the library to have been built
--   with stack (it searches for some files generated in
--   <tt>.stack-work</tt>). In the future I'll probably lift this
--   restriction (if you need it before, please open a ticket). The files
--   marked as internal are exported for documentation purposes only.
module Language.C.Preprocessor.Remover

-- | Given the path to the cabal file, this returns the paths to all the
--   exposed modules of the <tt>library</tt> section.
getLibExposedModulesPath :: CabalFilePath -> IO [FilePath]

-- | Given the path to a file in a stack-build project, returns the content
--   of the preprocessed file. The line numbering of the original file is
--   preserved.
preprocessFile :: FilePath -> IO String