Formatter

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.

Types

Formatting

newtype Formatter

Formatter.

Constructors

Formatter

Fields

• runFormat :: Path Rel File -> FormattingDirective

  Run the formatter.

  This accepts a relative path to a file and returns a formatting directive for that file. This is a pure function: it can only inspect the name of the file, it should NOT try to perform any IO.

Instances

Semigroup Formatter

Defined in Formatter

Methods

(<>) :: Formatter -> Formatter -> Formatter

sconcat :: NonEmpty Formatter -> Formatter

stimes :: Integral b => b -> Formatter -> Formatter

Monoid Formatter

Defined in Formatter

Methods

mempty :: Formatter

mappend :: Formatter -> Formatter -> Formatter

mconcat :: [Formatter] -> Formatter

data FormattingDirective

Formatting directive.

This indicates whether formatting can proceed or not.

Constructors

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 unsafePerformIO, but in that case, every effort should still be made to ensure it behaves as a pure function.

data FormattingResult a

Result of running a formatter.

The type parameter a is the type of values returned when formatting has changed.

Constructors

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)

Defined in Formatter

Methods

(==) :: FormattingResult a -> FormattingResult a -> Bool

(/=) :: FormattingResult a -> FormattingResult a -> Bool

Miscellaneous

newtype FileContent

Content of a file for formatting.

Constructors

FileContent

Fields

• unFileContent :: ByteString

Instances

Eq FileContent

Defined in Formatter

Methods

(==) :: FileContent -> FileContent -> Bool

(/=) :: FileContent -> FileContent -> Bool

newtype ErrorMessage

Error message.

Constructors

ErrorMessage

Fields

• unErrorMessage :: ShortText

Instances

Eq ErrorMessage

Defined in Formatter

Methods

(==) :: ErrorMessage -> ErrorMessage -> Bool

(/=) :: ErrorMessage -> ErrorMessage -> Bool

IO Actions

runFormatIO

Arguments

:: 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.

readRelativeFile

Arguments

:: 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.

readAbsoluteFile

Arguments

:: 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.

writeRelativeFile

Arguments

:: 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.

writeAbsoluteFile

Arguments

:: 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

Return True if a FormattingResult indicates definitively that a file was unchanged after successful processing.

Conversions

fileContentToUtf8

Arguments

:: 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

Arguments

:: Text

Text to encode.

-> FileContent

Text encoded as FileContent.

Encode Text as FileContent in UTF-8.