2. How to use GNATformat

GNATformat is available as a command line tool or as a library.

2.1. As a command line tool

The gnatformat command line works as other GNAT tools by providing GNAT project file (.gpr):

gnatformat -P [project_name].gpr

For the given project, this command will format the files from all closures of mains or library entry points, recursing on all the subprojects and stopping when a project is marked as externally built.

In order to customize your formatting, a few options are available and can be listed by executing the gnatformat --help command.

The available global options are:

  • --help, -h: print a help message and exit.

  • --project, -P: specify the project file to load; the .gpr extension can be omitted if the file is in the current directory

  • -X: allows to specify an external reference to a scenario variable.

  • --no-subprojects: only process the root project, not the subprojects.

  • -U: process all files, not only those that are in the closure of mains.

  • --verbose: prints additional logs.

  • --version, -v: shows the version of the tool.

  • --check: exit with error code 1 if the input is not formatted correctly and print the name of files that would be formatted.

  • --pipe, -p: print the result to stdout instead of editing the files on disk.

  • --keep-going, -k: print the result to stdout instead of editing the files on disk.

The specific options allowing to customize the formatting of your sources are:

  • --unparsing-configuration: allows to specify a custom unparsing configuration file to be used instead of the default one.

  • --width, -w: allows to specify the maximum line length. In the absence of this option, the default value is 79.

  • --indentation, -i: allows to specify the indentation size. In the absence of this option, the default value is 3.

  • --indentation-kind: allows to specify the indentation kind (i.e., tabs or spaces). In the absence of this option, the choice by default is spaces.

  • --indentation-continuation: allows to specify the continuation line indentation size. In the absence of this option, the default value is indentation - 1.

  • --end-of-line: allows you to choose the end of line sequence (i.e., lf or crlf). In the absence of this option, the default value is lf.

  • --charset: allows you to specify the charset to use for source decoding. In absence of this option, the default value is iso-8859-1.

  • --ignore: allows you to to specify a file with the source file names that must not be formatted.

  • --gitdiff: allows you to format only the lines added since a given commit.

  • --range-format: allows to enter in selection range formatting mode.

  • --start-line, -SL: allows to specify the selection’s start line number for range formatting.

  • --start-column, -SC: allows to specify the selection’s start column number for range formatting.

  • --end-line, -EL: allows to specify the selection’s end line number for range formatting.

  • --end-column, -EC: allows to specify the selection’s end column number for range formatting.

2.2. As a library

The formatting functionality is also available via a library.

In order to use it as a libray, the API is located in the (gnatformat-formattng.ads) and the entry point is the function Gnatformat.Formatting.Format having the following interface:

function Format
   (Unit           : Libadalang.Analysis.Analysis_Unit;
    Format_Options : Gnatformat.Configuration.Format_Options_Type;
    Configuration  :
      Langkit_Support.Generic_API.Unparsing.Unparsing_Configuration :=
        Gnatformat.Configuration.Default_Unparsing_Configuration)
    return Ada.Strings.Unbounded.Unbounded_String;
 --  Formats the given Unit using the provided Format_Options and
 --  Configuration.

where:

  • Unit is a Libadalang analysis unit node correspondin to the file to be formatted,

  • Format_Options are formatting the options that are specified through the (.gpr) project file,

  • Configuration uses a predefined configuration, i.e. the Default_Unparsing_Configuration, that implements the formatting rules according to the coding style described in the GNAT Coding Style guide.

This entry point can be used in order to integrate with other tools.

On our side, the gnatformat library is included in the Ada Language Server and can therefore be used through IDEs like GNAT Studio and Visual Studio Code.