| Copyright | (c) 2017 Dominic Orchard Andrew Rice Mistral Contrastin Matthew Danish |
|---|---|
| License | Apache-2.0 |
| Maintainer | dom.orchard@gmail.com |
| Stability | experimental |
| Safe Haskell | None |
| Language | Haskell2010 |
Camfort.Analysis
Description
This module defines the AnalysisT monad transformer, which encapsulates common
functionality for analyses:
- Logging via the
MonadLoggerclass - Early exit via
failAnalysisor 'failAnalysis'' - Error recovery via
catchAnalysisTorloggingAnalysisError - Providing access to the analysis environment via
analysisModFiles
Synopsis
- data AnalysisT e w m a
- type PureAnalysis e w = AnalysisT e w Identity
- mapAnalysisT :: Monad m => (e -> e') -> (w -> w') -> AnalysisT e w m a -> AnalysisT e' w' m a
- generalizePureAnalysis :: Monad m => PureAnalysis e w a -> AnalysisT e w m a
- class MonadLogger e w m => MonadAnalysis e w m where
- failAnalysis :: Origin -> e -> m a
- analysisModFiles :: m ModFiles
- failAnalysis' :: (MonadAnalysis e w m, Spanned o) => o -> e -> m a
- catchAnalysisT :: Monad m => (LogMessage e -> AnalysisT e w m a) -> AnalysisT e w m a -> AnalysisT e w m a
- loggingAnalysisError :: (Monad m, Describe w, Describe e) => AnalysisT e w m a -> AnalysisT e w m (Maybe a)
- analysisLiftLogger :: (Monad m, Describe w, Describe e) => LoggerT e w m a -> AnalysisT e w m a
- data AnalysisResult e r
- _ARFailure :: forall e r e. Prism (AnalysisResult e r) (AnalysisResult e r) (Origin, e) (Origin, e)
- _ARSuccess :: forall e r r. Prism (AnalysisResult e r) (AnalysisResult e r) r r
- data AnalysisReport e w r = AnalysisReport {
- _arSourceFile :: !FilePath
- _arMessages :: ![SomeMessage e w]
- _arResult :: !(AnalysisResult e r)
- arMessages :: forall e w r w. Lens (AnalysisReport e w r) (AnalysisReport e w r) [SomeMessage e w] [SomeMessage e w]
- arResult :: forall e w r r. Lens (AnalysisReport e w r) (AnalysisReport e w r) (AnalysisResult e r) (AnalysisResult e r)
- describeReport :: (Describe e, Describe w, Describe r) => Text -> Maybe LogLevel -> AnalysisReport e w r -> Text
- putDescribeReport :: (Describe e, Describe w, Describe r, MonadIO m) => Text -> Maybe LogLevel -> Bool -> AnalysisReport e w r -> m ()
- runAnalysisT :: (Monad m, Describe e, Describe w) => FilePath -> LogOutput m -> LogLevel -> ModFiles -> AnalysisT e w m a -> m (AnalysisReport e w a)
- class Monad m => MonadLogger e w m | m -> e w where
- logError :: Origin -> e -> m ()
- logError' :: Spanned a => a -> e -> m ()
- logWarn :: Origin -> w -> m ()
- logWarn' :: Spanned a => a -> w -> m ()
- logInfo :: Origin -> Text -> m ()
- logInfo' :: Spanned a => a -> Text -> m ()
- logInfoNoOrigin :: Text -> m ()
- logDebug :: Origin -> Text -> m ()
- logDebug' :: Spanned a => a -> Text -> m ()
- data Origin = Origin {}
- atSpanned :: (MonadLogger e w m, Spanned a) => a -> m Origin
- atSpannedInFile :: Spanned a => FilePath -> a -> Origin
- data LogOutput m
- logOutputStd :: MonadIO m => Bool -> LogOutput m
- logOutputNone :: Monad m => Bool -> LogOutput m
- data LogLevel
- class Describe a where
- describe :: a -> Text
- describeBuilder :: a -> Builder
- describeShow :: Show a => a -> Text
- (<>) :: Semigroup a => a -> a -> a
- class ExitCodeOfReport a where
- exitCodeOf :: a -> Int
- exitCodeOfSet :: [a] -> Int
Analysis monad
data AnalysisT e w m a Source #
The analysis monad transformer. Will usually be based on Identity (see
PureAnalysis) or IO.
Has error messages of type e and warnings of type w.
Instances
type PureAnalysis e w = AnalysisT e w Identity Source #
A pure analysis computation which cannot do any IO.
Combinators
mapAnalysisT :: Monad m => (e -> e') -> (w -> w') -> AnalysisT e w m a -> AnalysisT e' w' m a Source #
Change the error and warning types in an analysis. To change the
underlying monad use hoist.
generalizePureAnalysis :: Monad m => PureAnalysis e w a -> AnalysisT e w m a Source #
class MonadLogger e w m => MonadAnalysis e w m where Source #
Minimal complete definition
Nothing
Methods
failAnalysis :: Origin -> e -> m a Source #
Report a critical error in the analysis at a particular source location and exit early.
default failAnalysis :: (MonadTrans t, MonadAnalysis e w m', m ~ t m') => Origin -> e -> m a Source #
analysisModFiles :: m ModFiles Source #
Get the ModFiles from the analysis environment.
default analysisModFiles :: (MonadTrans t, MonadAnalysis e w m', m ~ t m') => m ModFiles Source #
Instances
failAnalysis' :: (MonadAnalysis e w m, Spanned o) => o -> e -> m a Source #
Report a critical failure in the analysis at no particular source location and exit early.
catchAnalysisT :: Monad m => (LogMessage e -> AnalysisT e w m a) -> AnalysisT e w m a -> AnalysisT e w m a Source #
Run the given analysis and recover with the given handler function if it fails.
loggingAnalysisError :: (Monad m, Describe w, Describe e) => AnalysisT e w m a -> AnalysisT e w m (Maybe a) Source #
Run the given analysis. If it succeeds, return its result value. Otherwise,
log the error it creates and return Nothing.
This allows errors in analysis sub-programs to be collected rather than halting the entire analysis.
analysisLiftLogger :: (Monad m, Describe w, Describe e) => LoggerT e w m a -> AnalysisT e w m a Source #
Given a logging computation, lift it into an analysis monad.
Analysis results
data AnalysisResult e r Source #
Instances
_ARFailure :: forall e r e. Prism (AnalysisResult e r) (AnalysisResult e r) (Origin, e) (Origin, e) Source #
_ARSuccess :: forall e r r. Prism (AnalysisResult e r) (AnalysisResult e r) r r Source #
data AnalysisReport e w r Source #
When an analysis is run, it produces a report consisting of the logs it collect as it ran. In addition, it either fails at a certain location or succeeds with a result value.
Constructors
| AnalysisReport | |
Fields
| |
Instances
arMessages :: forall e w r w. Lens (AnalysisReport e w r) (AnalysisReport e w r) [SomeMessage e w] [SomeMessage e w] Source #
arResult :: forall e w r r. Lens (AnalysisReport e w r) (AnalysisReport e w r) (AnalysisResult e r) (AnalysisResult e r) Source #
describeReport :: (Describe e, Describe w, Describe r) => Text -> Maybe LogLevel -> AnalysisReport e w r -> Text Source #
Produce a human-readable version of an AnalysisReport, at the given
verbosity level. Giving Nothing for the log level hides all logs.
putDescribeReport :: (Describe e, Describe w, Describe r, MonadIO m) => Text -> Maybe LogLevel -> Bool -> AnalysisReport e w r -> m () Source #
Running analyses
Arguments
| :: (Monad m, Describe e, Describe w) | |
| => FilePath | The name of the file the analysis is being run on. This is only used for logging. |
| -> LogOutput m | The logging output function, e.g. |
| -> LogLevel | The logging verbosity level. |
| -> ModFiles | The list of analysis modfiles. |
| -> AnalysisT e w m a | The analysis transformer to run. |
| -> m (AnalysisReport e w a) |
Run an analysis computation and collect the report.
Logging
See Camfort.Analysis.Logger for more detailed documentation.
class Monad m => MonadLogger e w m | m -> e w where Source #
MTL-style type class for monads that support logging.
Minimal complete definition
Nothing
Methods
logError :: Origin -> e -> m () Source #
Log an error message at the given Origin.
logError' :: Spanned a => a -> e -> m () Source #
Log an error message. The origin is the current default source file, with the source span of the given piece of Fortran syntax.
logWarn :: Origin -> w -> m () Source #
Log a warning message at the given Origin.
logWarn' :: Spanned a => a -> w -> m () Source #
Log a warning message. The origin is the current default source file, with the source span of the given piece of Fortran syntax.
logInfo :: Origin -> Text -> m () Source #
Log an information message at the given Origin.
logInfo' :: Spanned a => a -> Text -> m () Source #
Log an information message. The origin is the current default source file, with the source span of the given piece of Fortran syntax.
logInfoNoOrigin :: Text -> m () Source #
Log an information message with no origin. For example, use this when printing output about the progress of an analysis which cannot be associated with a particular bit of source code.
logDebug :: Origin -> Text -> m () Source #
Log a debugging message at the given Origin.
logDebug' :: Spanned a => a -> Text -> m () Source #
Log a debugging message. The origin is the current default source file, with the source span of the given piece of Fortran syntax.
Instances
Message origins
A message origin, containing a file and a source span.
Instances
| Eq Origin Source # | |
| Ord Origin Source # | |
| Show Origin Source # | |
| Generic Origin Source # | |
| NFData Origin Source # | |
Defined in Camfort.Analysis.Logger | |
| Describe Origin Source # | |
| type Rep Origin Source # | |
Defined in Camfort.Analysis.Logger type Rep Origin = D1 ('MetaData "Origin" "Camfort.Analysis.Logger" "camfort-1.0.1-inplace" 'False) (C1 ('MetaCons "Origin" 'PrefixI 'True) (S1 ('MetaSel ('Just "_oFile") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 FilePath) :*: S1 ('MetaSel ('Just "_oSpan") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 SrcSpan))) | |
atSpanned :: (MonadLogger e w m, Spanned a) => a -> m Origin Source #
Make an origin at the source span of a piece of Fortran syntax, in the current file.
atSpannedInFile :: Spanned a => FilePath -> a -> Origin Source #
Make an origin at the source span of a piece of Fortran syntax, in the given file.
Log outputs
Arguments
| :: MonadIO m | |
| => Bool | If |
| -> LogOutput m |
Output logs to standard output (i.e. the console).
Arguments
| :: Monad m | |
| => Bool | If |
| -> LogOutput m |
Output no logs.
Log levels
A logging level. At each logging level, only produce output at that level or lower.
Constructors
| LogError | At level |
| LogWarn | At level |
| LogInfo | At level |
| LogDebug | At level |
Describe class
class Describe a where Source #
A type class for efficiently converting values to human-readable output.
Can be automatically instantiated for Show types, but this will not be very
human-readable for a lot of types.
Minimal complete definition
Nothing
Methods
describe :: a -> Text Source #
Convert the value to a human-readable output as a strict Text value.
describeBuilder :: a -> Builder Source #
Convert the value to human-readable output in a text Builder which can
be efficiently concatenated with other Builders.
default describeBuilder :: Show a => a -> Builder Source #
Instances
describeShow :: Show a => a -> Text Source #
(<>) :: Semigroup a => a -> a -> a infixr 6 #
An associative operation.
>>>[1,2,3] <> [4,5,6][1,2,3,4,5,6]
Exit Code of reports
class ExitCodeOfReport a where Source #
Minimal complete definition
Nothing
Methods
exitCodeOf :: a -> Int Source #
Interpret an exit code from report (default 0)
exitCodeOfSet :: [a] -> Int Source #
Interpret an exit code from a set of reports (default: maximises absolute value)