Commit 153a225d authored by Oleg Grenrus's avatar Oleg Grenrus
Browse files

Add / correct haddocks

parent 73492bd2
......@@ -63,6 +63,7 @@ import Distribution.Text (disp, display)
freeTextFieldParser :: FieldParser String
freeTextFieldParser = dropDotLines <$ Parsec.spaces <*> many Parsec.anyChar
where
-- Example package with dot lines
-- http://hackage.haskell.org/package/copilot-cbmc-0.1/copilot-cbmc.cabal
dropDotLines "." = "."
dropDotLines x = intercalate "\n" . map dotToEmpty . lines $ x
......@@ -75,7 +76,7 @@ freeTextFieldParser = dropDotLines <$ Parsec.spaces <*> many Parsec.anyChar
-- PackageDescription
-------------------------------------------------------------------------------
-- TODO: other-files isn't used in any cabla file on Hackage.
-- TODO: other-files isn't used in any cabal file on Hackage.
pkgDescrFieldDescrs :: [FieldDescr PackageDescription]
pkgDescrFieldDescrs =
[ simpleField "name"
......
......@@ -22,15 +22,16 @@ import System.FilePath (normalise)
import qualified Text.Parsec as Parsec
-- | Parser error.
data PError = PError Position String
deriving (Show)
-- | We do classify warnings.
-- | Type of parser warning. We do classify warnings.
--
-- Different application may decide not to show some, or have fatal behaviour on others
data PWarnType
= PWTOther -- ^ Unclassified warning
| PWTUTF
| PWTUTF -- ^ Invalid UTF encoding
| PWTBoolCase -- ^ @true@ or @false@, not @True@ or @False@
| PWTGluedOperators -- ^ @&&!@
| PWTVersionTag -- ^ there are version with tags
......@@ -48,7 +49,7 @@ data PWarnType
| PWTLexBOM
deriving (Eq, Ord, Show, Enum, Bounded)
-- | Parser warning.
data PWarning = PWarning !PWarnType !Position String
deriving (Show)
......@@ -64,20 +65,25 @@ showPError fpath (PError pos msg) =
-- Field parser
-------------------------------------------------------------------------------
type FieldParser = Parsec.Parsec String [PWarning]
-- | Field value parsers.
type FieldParser = Parsec.Parsec String [PWarning] -- :: * -> *
-------------------------------------------------------------------------------
-- Position
-------------------------------------------------------------------------------
-- | 1-indexed row and column positions in a file.
data Position = Position
{-# UNPACK #-} !Int -- row
{-# UNPACK #-} !Int -- column
deriving (Eq, Show)
-- | Shift position by n columns to the right.
incPos :: Int -> Position -> Position
incPos n (Position row col) = Position row (col + n)
-- | Shift position to beginning of next row.
retPos :: Position -> Position
retPos (Position row _col) = Position (row + 1) 1
......
{-# LANGUAGE DeriveFunctor #-}
-- | Cabal-like file AST types: 'Field', 'Section' etc
--
-- These types are parametrized by an annotation.
module Distribution.Parsec.Types.Field (
-- * Cabal file
Field (..),
......@@ -34,14 +37,23 @@ fieldAnn :: Field ann -> ann
fieldAnn (Field (Name ann _) _) = ann
fieldAnn (Section (Name ann _) _ _) = ann
-- | A line of text representing the value of a field from a Cabal file.
-- A field may contain multiple lines.
--
-- /Invariant:/ 'ByteString' has no newlines.
data FieldLine ann = FieldLine !ann !ByteString
deriving (Eq, Show, Functor)
-- | Section arguments, e.g. name of the library
data SectionArg ann
= SecArgName !ann !ByteString
-- ^ identifier
| SecArgStr !ann !String
-- ^ quoted string
| SecArgNum !ann !ByteString
-- ^ integral number
| SecArgOther !ann !ByteString
-- ^ everything else, mm. operators (e.g. in if-section conditionals)
deriving (Eq, Show, Functor)
-- | Extract annotation from 'SectionArg'.
......@@ -55,13 +67,16 @@ sectionArgAnn (SecArgOther ann _) = ann
-- Name
-------------------------------------------------------------------------------
-- | A field name.
--
-- /Invariant/: 'ByteString' is lower-case ASCII.
data Name ann = Name !ann !ByteString
deriving (Eq, Show, Functor)
mkName :: ann -> ByteString -> Name ann
mkName ann bs = Name ann (B.map Char.toLower bs)
getName :: Name a -> ByteString
getName :: Name ann -> ByteString
getName (Name _ bs) = bs
nameAnn :: Name ann -> ann
......
{-# LANGUAGE CPP #-}
-- | A parse result type for parsers from AST to Haskell types.
module Distribution.Parsec.Types.ParseResult (
ParseResult,
runParseResult,
......@@ -16,7 +17,7 @@ import Prelude ()
import Distribution.Parsec.Types.Common
(PError (..), PWarnType (..), PWarning (..), Position (..))
-- | A monad with failure and accumulating errors
-- | A monad with failure and accumulating errors and warnings.
newtype ParseResult a = PR { runPR :: PRState -> (Maybe a, PRState) }
data PRState = PRState ![PWarning] ![PError]
......@@ -24,6 +25,8 @@ data PRState = PRState ![PWarning] ![PError]
emptyPRState :: PRState
emptyPRState = PRState [] []
-- | Destruct a 'ParseResult' into the emitted warnings and errors, and
-- possibly the final result if there were no errors.
runParseResult :: ParseResult a -> ([PWarning], [PError], Maybe a)
runParseResult pr = case runPR pr emptyPRState of
(res, PRState warns errs)
......@@ -35,7 +38,6 @@ instance Functor ParseResult where
fmap f (PR pr) = PR $ \s -> case pr s of
(r, s') -> (fmap f r, s')
-- | Note: this is not a Monad!
instance Applicative ParseResult where
pure x = PR $ \s -> (Just x, s)
-- | Make it concat perrors
......@@ -52,7 +54,7 @@ instance Monad ParseResult where
(Just x, s') -> runPR (k x) s'
-- | "Recover" the parse result, so we can proceed parsing.
-- 'runParseResult' will still result 'Nothing', if there are recorded errors.
-- 'runParseResult' will still result in 'Nothing', if there are recorded errors.
recoverWith :: ParseResult a -> a -> ParseResult a
recoverWith (PR f) x = PR $ \s -> case f s of
(Nothing, s') -> (Just x, s')
......@@ -67,10 +69,13 @@ parseWarnings' newWarns = PR $ \(PRState warns errs) ->
(Just (), PRState (warns ++ newWarns) errs)
-- | Add an error, but not fail the parser yet.
--
-- For fatal failure use 'parseFatalFailure'
parseFailure :: Position -> String -> ParseResult ()
parseFailure pos msg = PR $ \(PRState warns errs) ->
(Just (), PRState warns (PError pos msg : errs))
-- | Add an fatal error.
parseFatalFailure :: Position -> String -> ParseResult a
parseFatalFailure pos msg = PR $ \(PRState warns errs) ->
(Nothing, PRState warns (PError pos msg : errs))
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment