How to Use the Command 'brittany' (with Examples)

Brittany is a command-line tool used for formatting Haskell source files. This utility helps maintain consistent code style and readability across Haskell projects by automatically arranging and styling your code according to preset or customizable preferences. Brittany is an invaluable tool for developers who want to ensure that their Haskell code is clean, uniform, and adheres to modern formatting standards.

Use case 1: Format a Haskell Source File and Print the Result to stdout

Code:

brittany path/to/file.hs

Motivation:

In many cases, developers want to quickly check or demonstrate how a Haskell file can be reformatted without actually changing the file on disk. This approach allows developers to preview how Brittany will clean up their code, making it a quick and safe way to visualize potential changes.

Explanation:

• brittany: The command-line tool for formatting Haskell files.
• path/to/file.hs: The specified path to the Haskell source file that will be processed.

Example Output:

When using this command, the console output will display the nicely formatted version of your Haskell code from file.hs. For instance, if your original code was messy or misaligned, Brittany will print the polished result directly to your terminal, enhancing readability.

Use case 2: Format All Haskell Source Files in the Current Directory In-Place

Code:

brittany --write-mode=inplace *.hs

Motivation:

Making code consistent across entire projects is crucial for maintaining quality and ease of collaboration. By formatting all Haskell source files in a directory in place, you assure that every piece of code is up to date with your desired style standards, thus contributing to overall code health and project readiness.

Explanation:

• --write-mode=inplace: This option tells Brittany to modify the files directly, updating them with the formatted code instead of just displaying the result.
• *.hs: This wildcard pattern targets all Haskell files in the current directory, ensuring seamless formatting of multiple files in one operation.

Example Output:

Upon execution, Brittany updates every Haskell file in the directory with a consistently formatted style. You might see terminal messages indicating successful updates. The final result is a uniform style throughout your codebase, enhancing project cohesion.

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 particularly useful in continuous integration scenarios where you need to validate code style standards as part of your automated build process. By utilizing Brittany’s exit code capability, you can enforce coding standards without manual oversight.

Explanation:

• --check-mode: This flag causes Brittany to run as a formatter check, indicating via exit code whether changes are needed.
• path/to/file.hs: Represents the file being checked for conformity to the formatting guidelines.

Example Output:

If the file needs reformatting, Brittany returns a non-zero exit code, which can be captured in CI pipelines to automatically fail builds or alert developers. Successful formatting will return a zero exit code, ensuring compliance with formatting standards.

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:

Each team or project might have specific style guides dictating coding format preferences, such as indent size or line length. By permitting customization, Brittany allows developers to adhere to whatever formatting conventions are required, ensuring code fits well with existing codebases or personal preferences.

Explanation:

• --indent 4: Instructs Brittany to use four spaces for each indentation level, tailoring the format to a precise style requirement.
• --columns 100: Sets the maximum line length to 100 characters, providing flexibility to meet line length guidelines.
• path/to/file.hs: The file being formatted, directed by the specific indent and column width settings.

Example Output:

The output is a file refashioned according to the specified indentation and line length, offering a neat and readable code layout. By crafting coherent visual structures, this aids developers in maintaining and expanding the codebase over time.

Use case 5: Format a Haskell Source File According to the Style Defined in the Specified Configuration File

Code:

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

Motivation:

Organizations often roll out specific configuration rules which all developers must follow. Brittany leverages configuration files, allowing teams to easily disseminate those formatting rules, ensuring that everyone adheres to the same stylistic framework without the burden of manual checks.

Explanation:

• --config-file path/to/config.yaml: Specifies the configuration file, typically stored in version control, that details how Brittany should format files according to predefined style guidelines.
• path/to/file.hs: Denotes the source file to be reformatted utilizing the rules outlined in the config file.

Example Output:

When used, Brittany processes file.hs conforming entirely to the specified configurations, allowing both enforcement of and adherence to a project’s unique formatting standards. This ensures uniformity and ease of code integration across different team members.

Conclusion:

Brittany aids Haskell developers in preserving high-quality, consistent, and readable code by automating the formatting process. Through its versatile range of options, Brittany supports various customization needs, whether it’s simple file formatting, in-place modifications, or adherence to strict configuration standards. With its integration into continuous workflows, Brittany proves to be an essential tool for cohesive Haskell development practices.