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


-- | A liberalised re-implementation of cpp, the C pre-processor.
--   
--   Cpphs is a re-implementation of the C pre-processor that is both more
--   compatible with Haskell, and itself written in Haskell so that it can
--   be distributed with compilers.
--   
--   This version of the C pre-processor is pretty-much feature-complete
--   and compatible with traditional (K&R) pre-processors. Additional
--   features include: a plain-text mode; an option to unlit literate code
--   files; and an option to turn off macro-expansion.
@package cpphs
@version 1.20.8


-- | Part of this code is from "Report on the Programming Language
--   Haskell", version 1.2, appendix C.
module Language.Preprocessor.Unlit

-- | <a>unlit</a> takes a filename (for error reports), and transforms the
--   given string, to eliminate the literate comments from the program
--   text.
unlit :: FilePath -> String -> String


-- | Include the interface that is exported
module Language.Preprocessor.Cpphs
runCpphs :: CpphsOptions -> FilePath -> String -> IO String
runCpphsPass1 :: CpphsOptions -> FilePath -> String -> IO [(Posn, String)]
runCpphsPass2 :: BoolOptions -> [(String, String)] -> FilePath -> [(Posn, String)] -> IO String
runCpphsReturningSymTab :: CpphsOptions -> FilePath -> String -> IO (String, [(String, String)])

-- | Run a first pass of cpp, evaluating #ifdef's and processing
--   #include's, whilst taking account of #define's and #undef's as we
--   encounter them.
cppIfdef :: FilePath -> [(String, String)] -> [String] -> BoolOptions -> String -> IO [(Posn, String)]

-- | tokenise is, broadly-speaking, Prelude.words, except that: * the input
--   is already divided into lines * each word-like "token" is categorised
--   as one of {Ident,Other,Cmd} * #define's are parsed and returned
--   out-of-band using the Cmd variant * All whitespace is preserved intact
--   as tokens. * C-comments are converted to white-space (depending on
--   first param) * Parens and commas are tokens in their own right. * Any
--   cpp line continuations are respected. No errors can be raised. The
--   inverse of tokenise is (concatMap deWordStyle).
tokenise :: Bool -> Bool -> Bool -> Bool -> [(Posn, String)] -> [WordStyle]

-- | Each token is classified as one of Ident, Other, or Cmd: * Ident is a
--   word that could potentially match a macro name. * Cmd is a complete
--   cpp directive (#define etc). * Other is anything else.
data WordStyle
Ident :: Posn -> String -> WordStyle
Other :: String -> WordStyle
Cmd :: (Maybe HashDefine) -> WordStyle

-- | Walk through the document, replacing calls of macros with the expanded
--   RHS.
macroPass :: [(String, String)] -> BoolOptions -> [(Posn, String)] -> IO String

-- | Walk through the document, replacing calls of macros with the expanded
--   RHS. Additionally returns the active symbol table after processing.
macroPassReturningSymTab :: [(String, String)] -> BoolOptions -> [(Posn, String)] -> IO (String, [(String, String)])

-- | Cpphs options structure.
data CpphsOptions
CpphsOptions :: [FilePath] -> [FilePath] -> [(String, String)] -> [String] -> [FilePath] -> BoolOptions -> CpphsOptions
[infiles] :: CpphsOptions -> [FilePath]
[outfiles] :: CpphsOptions -> [FilePath]
[defines] :: CpphsOptions -> [(String, String)]
[includes] :: CpphsOptions -> [String]

-- | Files to #include before anything else
[preInclude] :: CpphsOptions -> [FilePath]
[boolopts] :: CpphsOptions -> BoolOptions

-- | Options representable as Booleans.
data BoolOptions
BoolOptions :: Bool -> Bool -> Bool -> Bool -> Bool -> Bool -> Bool -> Bool -> Bool -> Bool -> Bool -> BoolOptions

-- | Leave #define and #undef in output of ifdef?
[macros] :: BoolOptions -> Bool

-- | Place #line droppings in output?
[locations] :: BoolOptions -> Bool

-- | Write #line or {-# LINE #-} ?
[hashline] :: BoolOptions -> Bool

-- | Keep #pragma in final output?
[pragma] :: BoolOptions -> Bool

-- | Remove C eol (//) comments everywhere?
[stripEol] :: BoolOptions -> Bool

-- | Remove C inline (/**/) comments everywhere?
[stripC89] :: BoolOptions -> Bool

-- | Lex input as Haskell code?
[lang] :: BoolOptions -> Bool

-- | Permit stringise # and catenate ## operators?
[ansi] :: BoolOptions -> Bool

-- | Retain newlines in macro expansions?
[layout] :: BoolOptions -> Bool

-- | Remove literate markup?
[literate] :: BoolOptions -> Bool

-- | Issue warnings?
[warnings] :: BoolOptions -> Bool

-- | Parse all command-line options.
parseOptions :: [String] -> Either String CpphsOptions

-- | Default options.
defaultCpphsOptions :: CpphsOptions

-- | Default settings of boolean options.
defaultBoolOptions :: BoolOptions

-- | Source positions contain a filename, line, column, and an inclusion
--   point, which is itself another source position, recursively.
data Posn
Pn :: String -> !Int -> !Int -> (Maybe Posn) -> Posn

-- | Constructor. Argument is filename.
newfile :: String -> Posn

-- | Increment column number by given quantity.
addcol :: Int -> Posn -> Posn

-- | Increment row number, reset column to 1.
newline :: Posn -> Posn

-- | Increment column number, tab stops are every 8 chars.
tab :: Posn -> Posn

-- | Increment row number by given quantity.
newlines :: Int -> Posn -> Posn

-- | Update position with a new row, and possible filename.
newpos :: Int -> Maybe String -> Posn -> Posn

-- | cpp-style printing of file position
cppline :: Posn -> String

-- | haskell-style printing of file position
haskline :: Posn -> String

-- | Conversion from a cpp-style "#line" to haskell-style pragma.
cpp2hask :: String -> String

-- | Project the filename.
filename :: Posn -> String

-- | Project the line number.
lineno :: Posn -> Int

-- | Project the directory of the filename.
directory :: Posn -> FilePath

-- | Sigh. Mixing Windows filepaths with unix is bad. Make sure there is a
--   canonical path separator.
cleanPath :: FilePath -> FilePath