How to use the command 'brittany' (with examples)

Brittany is a command-line tool used for pretty-printing Haskell source files. It formats Haskell code according to a specific coding style to improve readability and maintainability.

Use case 1: Format a Haskell source file and print the result to stdout

Code:

brittany path/to/file.hs

Motivation: This use case is helpful when you want to see how a Haskell source file would look after it has been formatted by Brittany. It allows you to preview the changes before applying them permanently.

Explanation:

• brittany is the command to execute Brittany.
• path/to/file.hs is the path to the Haskell source file that you want to format.

Example output:

-- Before formatting
main = do
putStrLn "Hello, World!"

-- After formatting
main = do
  putStrLn "Hello, World!"

Use case 2: Format all Haskell source files in the current directory in-place

Code:

brittany --write-mode=inplace *.hs

Motivation: This use case is useful when you want to automatically format all Haskell files in a directory without creating backup files. By using the --write-mode=inplace option, Brittany will overwrite the original file with the formatted version.

Explanation:

• brittany is the command to execute Brittany.
• --write-mode=inplace specifies that the files should be updated in-place without creating backups.
• *.hs is a wildcard that matches all Haskell source files in the current directory.

Example output: (No output will be displayed if the formatting is successful)

Use case 3: Check whether a Haskell source file needs changes and indicate the result through the program’s exit code

Code:

brittany --check-mode path/to/file.hs

Motivation: This use case is beneficial when you want to determine whether a Haskell file needs formatting changes without actually modifying the file. By using the --check-mode option, Brittany will return a non-zero exit code if changes are required, allowing you to incorporate it into scripts or CI/CD pipelines.

Explanation:

• brittany is the command to execute Brittany.
• --check-mode specifies that Brittany should only check if the file needs formatting changes without making any modifications.
• path/to/file.hs is the path to the Haskell source file that you want to check.

Example output:

Formatting required for path/to/file.hs

Use case 4: Format a Haskell source file using the specified amount of spaces per indentation level and line length

Code:

brittany --indent 4 --columns 100 path/to/file.hs

Motivation: This use case is useful when you want to customize the formatting style according to your preferences. By using the --indent and --columns options, you can specify the number of spaces per indentation level and the maximum line length.

Explanation:

• brittany is the command to execute Brittany.
• --indent 4 sets the number of spaces per indentation level to 4.
• --columns 100 sets the maximum line length to 100 characters.
• path/to/file.hs is the path to the Haskell source file that you want to format.

Example output:

-- Before formatting
main = do
  putStrLn "Hello, World!"

-- After formatting
main = do
    putStrLn "Hello, World!"

Use case 5: Format a Haskell source file according to the style defined in the specified config file

Code:

brittany --config-file path/to/config.yaml path/to/file.hs

Motivation: This use case is helpful when you want to apply a specific formatting style defined in a configuration file. By using the --config-file option, Brittany will use the style rules specified in the config file to format the Haskell source file.

Explanation:

• brittany is the command to execute Brittany.
• --config-file path/to/config.yaml specifies the path to the YAML configuration file.
• path/to/file.hs is the path to the Haskell source file that you want to format.

Example output:

-- Before formatting
main = do
    putStrLn "Hello, World!"

-- After formatting
main = do
  putStrLn "Hello, World!"

Conclusion:

The command brittany is a powerful tool for formatting Haskell source files. It provides various options to customize the formatting style and offers features like checking for required formatting changes without modifying the file. By using the examples provided in this article, you can effectively utilize Brittany to improve the consistency and readability of your Haskell codebase.