Safe Haskell | None |
---|---|
Language | Haskell2010 |
Formatter
is a (potential) formatter for a file. It contains a method,
runFormat
, which takes a relative path to a file and, by inspecting the
path alone, must decide whether to format the file or not. To specify if the
file will be formatted by that formatter, it returns a FormattingDirective
.
If the FormattingDirective
is Format
then that constructor supplies a
function which can take the FileContent
, and return a FormattingResult
.
In turn, the FormattingResult
specifies the result of formatting.
To implement a new Formatter
, return a new Formatter
instance, which
inspects the file path and, if the file can be formatted by that Formatter
,
return a Format
constructor containing the formatting operation.
All aspects of the Formatter
operation are pure or "effectively pure". If
IO
operations are required, they should be implemented in
unsafePerformIO
as effectively-pure operations.
Synopsis
- newtype Formatter = Formatter {
- runFormat :: Path Rel File -> FormattingDirective
- data FormattingDirective
- data FormattingResult a
- = NotFormatted
- | Unchanged
- | Changed !a
- | Error !ErrorMessage
- newtype FileContent = FileContent {}
- newtype ErrorMessage = ErrorMessage {}
- runFormatIO :: RunMode -> Formatter -> Path Abs Dir -> Path Rel File -> IO (FormattingResult ())
- readRelativeFile :: Path Abs Dir -> Path Rel File -> IO (Either ErrorMessage FileContent)
- readAbsoluteFile :: Path Abs File -> IO (Either ErrorMessage FileContent)
- writeRelativeFile :: Path Abs Dir -> Path Rel File -> FileContent -> IO (Either ErrorMessage ())
- writeAbsoluteFile :: Path Abs File -> FileContent -> IO (Either ErrorMessage ())
- isUnchanged :: FormattingResult a -> Bool
- fileContentToUtf8 :: FileContent -> Maybe (Path Rel File) -> Either ErrorMessage Text
- utf8TextToFileContent :: Text -> FileContent
Types
Formatting
Formatter.
Formatter | |
|
data FormattingDirective Source #
Formatting directive.
This indicates whether formatting can proceed or not.
DoNotFormat | Do not format the file any further. |
Format (FileContent -> FormattingResult FileContent) | Formatter, which, given the content of a file returns a formatting result. This is a pure function. For some formatters, it may be necessary to run
this action using |
data FormattingResult a Source #
Result of running a formatter.
The type parameter a
is the type of values returned when formatting has
changed.
NotFormatted | The formatter decided not to format the file after inspecting it. |
Unchanged | Formatting completed successfully, without changes. |
Changed !a | Formatting completed successfully, and there are new contents. |
Error !ErrorMessage | An error occurred while formatting. |
Instances
Eq a => Eq (FormattingResult a) Source # | |
Defined in Formatter (==) :: FormattingResult a -> FormattingResult a -> Bool # (/=) :: FormattingResult a -> FormattingResult a -> Bool # |
Miscellaneous
newtype FileContent Source #
Content of a file for formatting.
Instances
Eq FileContent Source # | |
Defined in Formatter (==) :: FileContent -> FileContent -> Bool # (/=) :: FileContent -> FileContent -> Bool # |
newtype ErrorMessage Source #
Error message.
Instances
Eq ErrorMessage Source # | |
Defined in Formatter (==) :: ErrorMessage -> ErrorMessage -> Bool # (/=) :: ErrorMessage -> ErrorMessage -> Bool # |
IO Actions
:: RunMode | Run mode: either we're only checking, or we're also formatting. |
-> Formatter | Formatter to run. |
-> Path Abs Dir | Parent / project directory. |
-> Path Rel File | Path to the file (relative to the above parent directory). |
-> IO (FormattingResult ()) | Formatting result (without capturing the formatted output). |
Run a formatter in IO on a single file.
This operation checks if the formatter can run on the provided file. If it
can run then the file is loaded, and the formatter is run. If the run mode is
Format
then the new formatted output is written to the file,
otherwise the file is left as-is.
:: Path Abs Dir | Path to the parent directory of the file. |
-> Path Rel File | Path of the file relative to the parent directory. |
-> IO (Either ErrorMessage FileContent) | IO action containing the file content. |
Read a relative file into FileContent
.
If the action is unsuccessful then an ErrorMessage
is returned.
:: Path Abs File | Path of the file to write. |
-> IO (Either ErrorMessage FileContent) | IO action. |
Read an absolute file into FileContent
.
If the action is unsuccessful then an ErrorMessage
is returned.
:: Path Abs Dir | Path of the parent directory of the file. |
-> Path Rel File | Path of the file relative to the parent directory. |
-> FileContent | Content of the file. |
-> IO (Either ErrorMessage ()) | IO action that writes the file content. |
Write a relative file from FileContent
.
If the action is unsuccessful then an ErrorMessage
is returned.
:: Path Abs File | Absolute path of the file to write. |
-> FileContent | Content of the file. |
-> IO (Either ErrorMessage ()) | IO action. |
Write an absolute file from FileContent
If the action is unsuccessful then an ErrorMessage
is returned.
Functions
Tests
isUnchanged :: FormattingResult a -> Bool Source #
Return True
if a FormattingResult
indicates definitively that a file
was unchanged after successful processing.
Conversions
:: FileContent | Content to convert to UTF-8. |
-> Maybe (Path Rel File) | Path to the relative file, if known (used for error messages). |
-> Either ErrorMessage Text | Either an error message, or the file read as UTF-8 text. |
Convert FileContent
from an underlying ByteString
to UTF-8.
If this operation fails with a unicode error, the underlying exception is
converted to an ErrorMessage
.
utf8TextToFileContent Source #
:: Text | Text to encode. |
-> FileContent | Text encoded as |
Encode Text
as FileContent
in UTF-8.