Safe Haskell	Safe-Inferred
Language	GHC2021

Ormolu

Contents

Top-level formatting functions
Configuration
Cabal info
Fixity overrides and module re-exports
Working with exceptions

Description

A formatter for Haskell source code. This module exposes the official stable API, other modules may be not as reliable.

Synopsis

ormolu :: MonadIO m => Config RegionIndices -> FilePath -> Text -> m Text
ormoluFile :: MonadIO m => Config RegionIndices -> FilePath -> m Text
ormoluStdin :: MonadIO m => Config RegionIndices -> m Text
data Config region = Config {
- cfgDynOptions :: ![DynOption]
- cfgFixityOverrides :: !FixityOverrides
- cfgModuleReexports :: !ModuleReexports
- cfgDependencies :: !(Set PackageName)
- cfgUnsafe :: !Bool
- cfgDebug :: !Bool
- cfgCheckIdempotence :: !Bool
- cfgSourceType :: !SourceType
- cfgColorMode :: !ColorMode
- cfgRegion :: !region
}
data ColorMode
- = Never
- | Always
- | Auto
data RegionIndices = RegionIndices {
- regionStartLine :: !(Maybe Int)
- regionEndLine :: !(Maybe Int)
}
data SourceType
- = ModuleSource
- | SignatureSource
defaultConfig :: Config RegionIndices
detectSourceType :: FilePath -> SourceType
refineConfig :: SourceType -> Maybe CabalInfo -> Maybe FixityOverrides -> Maybe ModuleReexports -> Config region -> Config region
newtype DynOption = DynOption {
- unDynOption :: String
}
data CabalSearchResult
- = CabalNotFound
- | CabalDidNotMention CabalInfo
- | CabalFound CabalInfo
data CabalInfo = CabalInfo {
- ciPackageName :: !PackageName
- ciDynOpts :: ![DynOption]
- ciDependencies :: !(Set PackageName)
- ciCabalFilePath :: !FilePath
}
getCabalInfoForSourceFile :: MonadIO m => FilePath -> m CabalSearchResult
data FixityOverrides
defaultFixityOverrides :: FixityOverrides
data ModuleReexports
defaultModuleReexports :: ModuleReexports
getDotOrmoluForSourceFile :: MonadIO m => FilePath -> m (FixityOverrides, ModuleReexports)
data OrmoluException
- = OrmoluParsingFailed SrcSpan String
- | OrmoluOutputParsingFailed SrcSpan String
- | OrmoluASTDiffers TextDiff [RealSrcSpan]
- | OrmoluNonIdempotentOutput TextDiff
- | OrmoluUnrecognizedOpts (NonEmpty String)
- | OrmoluCabalFileParsingFailed FilePath (NonEmpty PError)
- | OrmoluMissingStdinInputFile
- | OrmoluFixityOverridesParseError (ParseErrorBundle Text Void)
withPrettyOrmoluExceptions :: ColorMode -> IO ExitCode -> IO ExitCode

Top-level formatting functions

ormolu Source #

Arguments

:: MonadIO m
=> Config RegionIndices	Ormolu configuration
-> FilePath	Location of source file
-> Text	Input to format
-> m Text

Format a Text.

The function

Needs IO because some functions from GHC that are necessary to setup parsing context require IO. There should be no visible side-effects though.
Takes file name just to use it in parse error messages.
Throws OrmoluException.

NOTE: The caller is responsible for setting the appropriate value in the cfgSourceType field. Autodetection of source type won't happen here, see detectSourceType.

ormoluFile Source #

Arguments

:: MonadIO m
=> Config RegionIndices	Ormolu configuration
-> FilePath	Location of source file
-> m Text	Resulting rendition

Load a file and format it. The file stays intact and the rendered version is returned as Text.

NOTE: The caller is responsible for setting the appropriate value in the cfgSourceType field. Autodetection of source type won't happen here, see detectSourceType.

ormoluStdin Source #

Arguments

:: MonadIO m
=> Config RegionIndices	Ormolu configuration
-> m Text	Resulting rendition

Read input from stdin and format it.

NOTE: The caller is responsible for setting the appropriate value in the cfgSourceType field. Autodetection of source type won't happen here, see detectSourceType.

Configuration

data Config region Source #

Ormolu configuration.

Constructors

Config

Fields

cfgDynOptions :: ![DynOption]
Dynamic options to pass to GHC parser
cfgFixityOverrides :: !FixityOverrides
Fixity overrides
cfgModuleReexports :: !ModuleReexports
Module reexports to take into account when doing fixity resolution
cfgDependencies :: !(Set PackageName)
Known dependencies, if any
cfgUnsafe :: !Bool
Do formatting faster but without automatic detection of defects
cfgDebug :: !Bool
Output information useful for debugging
cfgCheckIdempotence :: !Bool
Checks if re-formatting the result is idempotent
cfgSourceType :: !SourceType
How to parse the input (regular haskell module or Backpack file)
cfgColorMode :: !ColorMode
Whether to use colors and other features of ANSI terminals
cfgRegion :: !region
Region selection

Instances

Instances details

Functor Config Source #
Instance details Defined in Ormolu.Config Methods fmap :: (a -> b) -> Config a -> Config b # (<$) :: a -> Config b -> Config a #
Generic (Config region) Source #
Instance details Defined in Ormolu.Config Associated Types type Rep (Config region) :: Type -> Type # Methods from :: Config region -> Rep (Config region) x # to :: Rep (Config region) x -> Config region #
Show region => Show (Config region) Source #
Instance details Defined in Ormolu.Config Methods showsPrec :: Int -> Config region -> ShowS # show :: Config region -> String # showList :: [Config region] -> ShowS #
Eq region => Eq (Config region) Source #
Instance details Defined in Ormolu.Config Methods (==) :: Config region -> Config region -> Bool # (/=) :: Config region -> Config region -> Bool #
type Rep (Config region) Source #
Instance details Defined in Ormolu.Config type Rep (Config region) = D1 ('MetaData "Config" "Ormolu.Config" "ormolu-0.7.6.0-AxJRayAwpTU4TXUxkLQn6Q" 'False) (C1 ('MetaCons "Config" 'PrefixI 'True) (((S1 ('MetaSel ('Just "cfgDynOptions") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 [DynOption]) :: S1 ('MetaSel ('Just "cfgFixityOverrides") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 FixityOverrides)) :: (S1 ('MetaSel ('Just "cfgModuleReexports") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 ModuleReexports) :: (S1 ('MetaSel ('Just "cfgDependencies") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 (Set PackageName)) :: S1 ('MetaSel ('Just "cfgUnsafe") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Bool)))) :: ((S1 ('MetaSel ('Just "cfgDebug") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Bool) :: S1 ('MetaSel ('Just "cfgCheckIdempotence") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Bool)) :: (S1 ('MetaSel ('Just "cfgSourceType") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 SourceType) :: (S1 ('MetaSel ('Just "cfgColorMode") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 ColorMode) :*: S1 ('MetaSel ('Just "cfgRegion") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 region))))))

data ColorMode Source #

Whether to use colors and other features of ANSI terminals.

Constructors

Never
Always
Auto

Instances

Instances details

Show ColorMode Source #
Instance details Defined in Ormolu.Terminal Methods showsPrec :: Int -> ColorMode -> ShowS # show :: ColorMode -> String # showList :: [ColorMode] -> ShowS #
Eq ColorMode Source #
Instance details Defined in Ormolu.Terminal Methods (==) :: ColorMode -> ColorMode -> Bool # (/=) :: ColorMode -> ColorMode -> Bool #

data RegionIndices Source #

Region selection as the combination of start and end line numbers.

Constructors

RegionIndices
Fields regionStartLine :: !(Maybe Int) Start line of the region to format regionEndLine :: !(Maybe Int) End line of the region to format

Instances

Instances details

Show RegionIndices Source #
Instance details Defined in Ormolu.Config Methods showsPrec :: Int -> RegionIndices -> ShowS # show :: RegionIndices -> String # showList :: [RegionIndices] -> ShowS #
Eq RegionIndices Source #
Instance details Defined in Ormolu.Config Methods (==) :: RegionIndices -> RegionIndices -> Bool # (/=) :: RegionIndices -> RegionIndices -> Bool #

data SourceType Source #

Type of sources that can be formatted by Ormolu.

Constructors

ModuleSource	Consider the input as a regular Haskell module
SignatureSource	Consider the input as a Backpack module signature

Instances

Instances details

Show SourceType Source #
Instance details Defined in Ormolu.Config Methods showsPrec :: Int -> SourceType -> ShowS # show :: SourceType -> String # showList :: [SourceType] -> ShowS #
Eq SourceType Source #
Instance details Defined in Ormolu.Config Methods (==) :: SourceType -> SourceType -> Bool # (/=) :: SourceType -> SourceType -> Bool #

defaultConfig :: Config RegionIndices Source #

Default Config RegionIndices.

detectSourceType :: FilePath -> SourceType Source #

Detect SourceType based on the file extension.

refineConfig Source #

Arguments

:: SourceType	Source type to use
-> Maybe CabalInfo	Cabal info for the file, if available
-> Maybe FixityOverrides	Fixity overrides, if available
-> Maybe ModuleReexports	Module re-exports, if available
-> Config region	`Config` to refine
-> Config region	Refined `Config`

Refine a Config by incorporating given SourceType, CabalInfo, and fixity overrides FixityMap. You can use detectSourceType to deduce SourceType based on the file extension, getCabalInfoForSourceFile to obtain CabalInfo and getFixityOverridesForSourceFile for FixityMap.

Since: 0.5.3.0

newtype DynOption Source #

A wrapper for dynamic options.

Constructors

DynOption
Fields unDynOption :: String

Instances

Instances details

Show DynOption Source #
Instance details Defined in Ormolu.Config Methods showsPrec :: Int -> DynOption -> ShowS # show :: DynOption -> String # showList :: [DynOption] -> ShowS #
Eq DynOption Source #
Instance details Defined in Ormolu.Config Methods (==) :: DynOption -> DynOption -> Bool # (/=) :: DynOption -> DynOption -> Bool #
Ord DynOption Source #
Instance details Defined in Ormolu.Config Methods compare :: DynOption -> DynOption -> Ordering # (<) :: DynOption -> DynOption -> Bool # (<=) :: DynOption -> DynOption -> Bool # (>) :: DynOption -> DynOption -> Bool # (>=) :: DynOption -> DynOption -> Bool # max :: DynOption -> DynOption -> DynOption # min :: DynOption -> DynOption -> DynOption #

Cabal info

data CabalSearchResult Source #

The result of searching for a .cabal file.

Since: 0.5.3.0

Constructors

CabalNotFound	Cabal file could not be found
CabalDidNotMention CabalInfo	Cabal file was found, but it did not mention the source file in question
CabalFound CabalInfo	Cabal file was found and it mentions the source file in question

Instances

Instances details

Show CabalSearchResult Source #
Instance details Defined in Ormolu.Utils.Cabal Methods showsPrec :: Int -> CabalSearchResult -> ShowS # show :: CabalSearchResult -> String # showList :: [CabalSearchResult] -> ShowS #
Eq CabalSearchResult Source #
Instance details Defined in Ormolu.Utils.Cabal Methods (==) :: CabalSearchResult -> CabalSearchResult -> Bool # (/=) :: CabalSearchResult -> CabalSearchResult -> Bool #

data CabalInfo Source #

Cabal information of interest to Ormolu.

Constructors

CabalInfo
Fields ciPackageName :: !PackageName Package name ciDynOpts :: ![DynOption] Extension and language settings in the form of `DynOption`s ciDependencies :: !(Set PackageName) Direct dependencies ciCabalFilePath :: !FilePath Absolute path to the cabal file

Instances

Instances details

Show CabalInfo Source #
Instance details Defined in Ormolu.Utils.Cabal Methods showsPrec :: Int -> CabalInfo -> ShowS # show :: CabalInfo -> String # showList :: [CabalInfo] -> ShowS #
Eq CabalInfo Source #
Instance details Defined in Ormolu.Utils.Cabal Methods (==) :: CabalInfo -> CabalInfo -> Bool # (/=) :: CabalInfo -> CabalInfo -> Bool #

getCabalInfoForSourceFile Source #

Arguments

:: MonadIO m
=> FilePath	Haskell source file
-> m CabalSearchResult	Extracted cabal info, if any

Locate a .cabal file corresponding to the given Haskell source file and obtain CabalInfo from it.

Fixity overrides and module re-exports

data FixityOverrides Source #

Map from the operator name to its FixityInfo.

Instances

Instances details

Show FixityOverrides Source #
Instance details Defined in Ormolu.Fixity.Internal Methods showsPrec :: Int -> FixityOverrides -> ShowS # show :: FixityOverrides -> String # showList :: [FixityOverrides] -> ShowS #
Eq FixityOverrides Source #
Instance details Defined in Ormolu.Fixity.Internal Methods (==) :: FixityOverrides -> FixityOverrides -> Bool # (/=) :: FixityOverrides -> FixityOverrides -> Bool #

defaultFixityOverrides :: FixityOverrides Source #

Fixity overrides to use by default.

data ModuleReexports Source #

Module re-exports

Instances

Instances details

Show ModuleReexports Source #
Instance details Defined in Ormolu.Fixity.Internal Methods showsPrec :: Int -> ModuleReexports -> ShowS # show :: ModuleReexports -> String # showList :: [ModuleReexports] -> ShowS #
Eq ModuleReexports Source #
Instance details Defined in Ormolu.Fixity.Internal Methods (==) :: ModuleReexports -> ModuleReexports -> Bool # (/=) :: ModuleReexports -> ModuleReexports -> Bool #

defaultModuleReexports :: ModuleReexports Source #

Module re-exports to apply by default.

getDotOrmoluForSourceFile Source #

Arguments

:: MonadIO m
=> FilePath	`CabalInfo` already obtained for this source file
-> m (FixityOverrides, ModuleReexports)

Attempt to locate and parse an .ormolu file. If it does not exist, default fixity map and module reexports are returned. This function maintains a cache of fixity overrides and module re-exports where cabal file paths act as keys.

Working with exceptions

data OrmoluException Source #

Ormolu exception representing all cases when Ormolu can fail.

Constructors

OrmoluParsingFailed SrcSpan String	Parsing of original source code failed
OrmoluOutputParsingFailed SrcSpan String	Parsing of formatted source code failed
OrmoluASTDiffers TextDiff [RealSrcSpan]	Original and resulting ASTs differ
OrmoluNonIdempotentOutput TextDiff	Formatted source code is not idempotent
OrmoluUnrecognizedOpts (NonEmpty String)	Some GHC options were not recognized
OrmoluCabalFileParsingFailed FilePath (NonEmpty PError)	Cabal file parsing failed
OrmoluMissingStdinInputFile	Missing input file path when using stdin input and accounting for .cabal files
OrmoluFixityOverridesParseError (ParseErrorBundle Text Void)	A parse error in a fixity overrides file

Instances

Instances details

Exception OrmoluException Source #
Instance details Defined in Ormolu.Exception Methods toException :: OrmoluException -> SomeException # fromException :: SomeException -> Maybe OrmoluException # displayException :: OrmoluException -> String #
Show OrmoluException Source #
Instance details Defined in Ormolu.Exception Methods showsPrec :: Int -> OrmoluException -> ShowS # show :: OrmoluException -> String # showList :: [OrmoluException] -> ShowS #

withPrettyOrmoluExceptions Source #

Arguments

:: ColorMode	Color mode
-> IO ExitCode	Action that may throw an exception
-> IO ExitCode

Inside this wrapper OrmoluException will be caught and displayed nicely.