GSoC 2019 Report: Adding NetBSD KNF to clang-format, Part 2

This report was prepared by Manikishan Ghantasala as a part of Google Summer of Code 2019

This report encloses the progress of the project Add KNF (NetBSD style) clang-format configuration during the second coding period of GSoC 2019.

Clang-format

Clang-format is a powerful code formatter which is a part of clang. Clang-format formats the code either by a configuration file .clang-format or can be chosen from some predefined coding styles namely LLVM, Google, Chromium, Mozilla, WebKit.

The final goal of the project is to add a new style NetBSD along with them by patching the libFormat to support the missing styles and add the configuration according to NetBSD KNF.

clang-format -style=NetBSD

Style options introduced in the first coding period:

1. BitFieldDeclarationsOnePerLine
2. SortNetBSDIncludes

You can also take a look at the first report to learn more about these style options.

Work done in the second coding period

I have worked on the following styles during this second coding period.

1. Withdrawn SortNetBSDIncludes and modified existing sortIncludes.
2. Modified spacesBeforeTralingComments to support block comments.
3. New style option alignConsecutiveListElements introduced.

Sortincludes:

The native SortIncludes sorts the includes/headers in alphabetical order. And we also have IncludeCategories which allows setting custom priorities to group the includes matching via a regex after sorting.

Example:

Configuration:

    
    IncludeCategories:
        -Regex:	        ^<(a|b|c)/
         Priority:	1

        -Regex:	        ^<(foo)/
         Priority:	2

        -Regex:	        .*
         Priority:	3
    

Input

    
        #include exe.h
        #include gaz.h
        #include <a/dee.h>
        #include <foo/b.h>
        #include <a/bee.h>
        #include <exc.h>
        #include <b/dee.h>
        #include <c/abc.h>
        #include <foo/a.h>

    

Output

    
        #include <a/bee.h>
        #include <a/dee.h>
        #include <b/dee.h>
        #include <c/abc.h>

        #include <foo/a.h>
        #include <foo/b.h>

        #include <exc.h>
        #include gaz.h>


    

Modified SortIncludes

The new sortIncludes supports to give custom priority for sorting in addition to grouping priority. Now the IncludeCategories have a new field named SortPriority along with Priority to set the priority while sorting the includes, and the default priority will be alphabetical. The usage and working of the new IncludeCategories style shown in the following example.

Example

    
    IncludeCategories:
        -Regex:	        <^c/
         Priority:	1
         SortPriority:	0

        -Regex:	        ^<(a|b)/
         Priority:	1
         SortPriority:	1

        -Regex:	        ^<(foo)/
         Priority:	2

        -Regex:	        .*
         Priority:	3   
    

Input

    
        #include exe.h
        #include <a/dee.h>
        #include <foo/b.h>
        #include <a/bee.h>
        #include <exc.h>
        #include <b/dee.h>
        #include <c/abc.h>
        #include <foo/a.h>
    

Output

    
        #include <c/abc.h>
        #include <a/bee.h>
        #include <a/dee.h>
        #include <b/dee.h>
        
        #include <foo/a.h>
        #include <foo/b.h>
        
        #include <exc.h>
        #include gaz.h
        
    

As we observe in the above example, the includes having the same Priority are grouped, and SortPriority defines the sort priority.

The patch was accepted and ready to merge, and you can find the patch here -> SortIncludesPatch. This patch also introduces the NetBSD style to clang-format with configurations to supported styles.

Spaces Before Trailing Comments

This option is also a native style option in clang-format which enables a user to decide the number of spaces to be given before trailing comments (// - comments) but not block comments (/* - comments). The reason for this is that block comments have different usage patterns and different exceptional cases. The following is an example of the native style option.

    
    SpacesBeforeTrailingComments: 3

    void f() {
    	if (true) {  //foo
            f();     //bar
    	}            //foo1
    }

    

Modifications to spaceBeforeTrailingComments:

I am working on modifying this style option to support block comments by covering cases where block comments are used. There are some cases yet to be covered. Once the patch is ready, this is the deliverable

The initial revision can be found here -> patch

    
    SpacesBeforeTrailingComments: 3


    void f() {
        if (true) {  /*foo */
            f();     /*bar */
    	}            /*foo1*/
    }
    

AlignConsecutiveListElements

AlignConsecutiveListElements is a new style option that I am going to introduce to clang-format. This style option aligns elements in consecutive definitions, declarations of lists. The style is not yet ready to patch, and I have to modify a lot of functionalities in alignTokens() which aligns tokens to support this style.

Example:

Input

    
    keys[] = {
        	{"all", f_all, 0 },
        	{ "cbreak", f_cbreak, F_OFFOK },
        	{"cols", f_columns, F_NEEDARG },
        	{ "columns", f_columns, F_NEEDARG },
        };
    

Output

    
    keys[] = {
        	{ "all",        f_all,      0 },
        	{ "cbreak",     _cbreak,    F_OFFOK },
        	{ "cols",       f_columns,  F_NEEDARG },
        	{ "columns",    f_columns,  F_NEEDARG },
        };
    

The blocker to this style is the nested structure for list declarations, alignTokens() should be equipped to parse the nested list declarations to support this style option. I will make sure this style option is available by the next report.

Further plans

For the next phase, I will make all the style options that were modified or introduced till now during the first two phases mergeable to upstream along with required unit tests. With these style options ready, I will test the new clang-format with NetBSD style patched across NetBSD source and check for bugs. After the testing will try to fix the bugs and get the NetBSDStyle ready for the final evaluation.

Summary

In the final coding period, the main focus will be on testing the new/modified style options and fix them. Add any missing styles for NetBSD and get the NetBSDStyle by the final evaluation.

I want to thank my mentors Michal, Christos and developers of both LLVM and NetBSD for supporting to complete this project.

[0 comments]