From 7f1702a830115d5c1180a76112206fcb11956ace Mon Sep 17 00:00:00 2001 From: Monika Kurovszky Date: Fri, 23 Aug 2024 16:33:08 +0200 Subject: [PATCH] Addding content for gnatformat user manual --- user_manual/user-guide/configuration.rst | 63 +++++++++++++++++++++++- user_manual/user-guide/usage.rst | 34 ++++++++++--- 2 files changed, 89 insertions(+), 8 deletions(-) diff --git a/user_manual/user-guide/configuration.rst b/user_manual/user-guide/configuration.rst index 88a5cad..b48c7f2 100644 --- a/user_manual/user-guide/configuration.rst +++ b/user_manual/user-guide/configuration.rst @@ -5,8 +5,67 @@ Configuring |GNATformat| |GNATformat| provides few configurable options that can be provided: - * as command line arguments, * as project attributes defined at the :file:`.gpr` level. -TO BE CONTINUED! + +The command line arguments +-------------------------- + +The formatting of your sources can be customized by the following options: + +* ``--width`` to be used if the maximum line length in your sources needs to be specified. + If not defined, the default value is set to ``79``. +* ``--indentation`` is an option allowing to specify the line's indentation size if needed. + By default its value is set to ``3``. +* ``--indentation-kind`` is an option that can be used to specify the indentation kind. + The possible values are ``tabs`` or ``spaces``. By default, this value is set to ``spaces``. +* ``--indentation-continuation`` is an option allowing to specify the continuation line + indentation size in case of your source code line should break relatively to the previous line. + By default this value is set to ``indentation - 1``. +* ``--end-of-line`` is an option allowing to choose the end of line sequence in your file + (i.e., ``lf`` or ``crlf``). By default, this value is set to ``lf``. +* ``--charset`` is an option allowing to specify the charset to use for the sources decoding. + +The tool allows as well the usage of a custom unparsing configuration file. This file can be +specified instead of the default one using the ``--unparsing-configuration`` switch taking as +argument the custom configuration file name. However, for the moment this is only an internal +switch and its usage is limited for development proposes. + + +The project file attributes +--------------------------- + +The formatting of your sources can be customized through the (:file:`.gpr`) project file by defining +a specific package called ``package Format``. +In this package all the attributes corresponding to the command line arguments can be added. There is +a one to one correspondence between the command line arguments and (:file:`.gpr`) project file attributes. +The attribute has the same functionality as its associated command line argument and can be customized +in order to comply with a specific source code formatting use case. + +The lines below shows the implementation of the ``Format`` package as part of project file (:file:`.gpr`):: + + package Format is + + for Indentation ("Ada") use "3"; -- this is the default + + for Indentation ("some_source.ads") use "4"; + + for Indentation_Kind ("Ada") use "spaces"; -- this is the default + + for Indentation_Kind ("some_source.ads") use "tabs"; + + for Width ("Ada") use "79"; -- this is the default + + for Width ("some_source.ads") use "99"; + + for End_Of_Line ("Ada") use "lf"; -- this is the default + + for End_Of_Line ("some_source.ads") use "crlf"; + + for Charset ("Ada") use "iso-8869-1"; -- this is the default + + for Charset ("some_source.ads") use "utf-8"; + + end Format; + diff --git a/user_manual/user-guide/usage.rst b/user_manual/user-guide/usage.rst index c5fd4c3..15b7aa3 100644 --- a/user_manual/user-guide/usage.rst +++ b/user_manual/user-guide/usage.rst @@ -49,14 +49,36 @@ The specific options allowing to customize the formatting of your sources are: In the absence of this, 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, the default value is ``lf``. +* ``--charset``: allows you to specify the charset to use for source decoding. As a libray ----------- -The formatting functionality is also available as via 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 (:file:`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: +* the ``Unit`` is a Libadalang analysis unit node correspondin to the file to be formatted +* the ``Format_Options`` are formatting the options that are specified through the (:file:`.gpr`) + project file +* the ``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-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 |ALS| and can therefore be used through +IDEs like |GNATStudio| and |VSCode|. -This ``gnatformat`` library is included in the |ALS| and can therefore be used through IDEs -like |GNATStudio| and |VSCode|. - - -TO BE COMPLETED!!!