Repository files navigation

A source code beautifier for C, C++, C#, Objective-C, D, Java, Pawn and Vala.

• Highly configurable - 857 configurable options as of version 0.81.0

• add/remove spaces

  • sp_before_sparen:Add or remove space before '(' of 'if', 'for', 'switch', 'while', etc.
  • sp_compare:Add or remove space around compare operator '<', '>', '==', etc

• add/remove newlines

  • nl_if_brace:Add or remove newline between 'if' and '{'
  • nl_brace_while:Add or remove newline between '}' and 'while' of 'do' statement

• add/remove blanklines

  • eat_blanks_before_close_brace:Whether to remove blank lines before '}'
  • nl_max:The maximum consecutive newlines (3 = 2 blank lines)

• indent code

  • indent_switch_case:indent_switch_case: Spaces to indent 'case' from 'switch'
  • indent_class_colon:Whether to indent the stuff after a leading base class colon

• align code

  • align_func_params:Align variable definitions in prototypes and functions
  • align_struct_init_span:The span for aligning struct initializer values (0=don't align)

• modify code

  • mod_full_brace_for:Add or remove braces on single-line 'for' statement
  • mod_paren_on_return:Add or remove unnecessary paren on 'return' statement

Here is an exampleconfiguration file,and here is abeforeandafterC source example.That should give you a pretty good idea of what Uncrustify can do.

Pre compiled binaries for Windows can be downloaded from theReleases page or from theSourceforge website.

Python is an "interpreted high-level programming language for general-purpose programming", for this project it is needed to extend the capabilities of CMake.

CMake is a tool that generates build systems(Makefiles, Visual Studio project files, Xcode project files and others).

To generate a build system for Uncrustify using CMake on UNIX-like systems, create abuild folder and run CMake from it, making sure to specify Release mode:

mkdir buildcd buildcmake -DCMAKE_BUILD_TYPE=Release ..

Other systems may require other flags (e.g.cmake -G Xcode .. for Xcode).

Then use the build tools of your build system (in many cases this willsimply bemake, but on Windows it could be MSBuild or Visual Studio).Or use CMake to invoke it:

cmake --build. --config Release

If testing is enabled, CMake generates atest target, which you canbuild using your build system tools (usuallymake test). This can alsobe invoked using CTest:

ctest -V -C Debug

There is also aninstall target, which can be used to install theUncrustify executable (typicallymake install).

Some build systems are single-configuration, which means you specify thebuild type when running CMake (by setting theCMAKE_BUILD_TYPEvariable), and the generated files then build that configuration.

An example of a single-configuration build system are Makefiles. You canbuild the Release or Debug configurations of Uncrustify (from the build folder) with:

cmake -DCMAKE_BUILD_TYPE=Release ..make

or

cmake -DCMAKE_BUILD_TYPE=Debug ..make

Other build systems are multi-configuration, which means you specify thebuild type when building.

An example of a multi-configuration build system are Visual Studios projectfiles. When you open the project in Visual Studio, you can select whichconfiguration to build. You can also do this while building from thecommand line withcmake --build . --config Debug.

Post any bugs to the issue tracker found on the projects GitHub page:https://github.com/uncrustify/uncrustify/issues

Please include the following with your issue:

• a description of what is not working right
• input code sufficient to demonstrate the issue
• expected output code
• configuration options used to generate the output

More about this is in theISSUE_TEMPLATE

Look at the Wiki

Look here

If you want to add a feature, fix a bug, or implement missingfunctionality, feel free to do so! Patches are welcome!Here are some areas that need attention:

• Patches for Objective-C support. We really need someone who knowsthis language as it has more than plenty open issues. A good startingpoint would be to integrate changes made in theUnity fork
• Test Java support and provide feedback (or patches!)
• Test Embedded SQL to see what works
• A logo of some sort
• Anything else that you want to do to make it better?

Firstly take a look at theCONTRIBUTING.md

Currently we have two continuous integration systems that test your PRs,TravisCI and Appveyor.Tested are the test cases, the formatting of the code base andthe output of the command line options.

Test cases can be found in thetests/ directory. Every file ending with.test is a test set. Inside each line with these components is asingle test:testNr[!] testConfigFileName testInputFileName [lang]

The configuration filetestConfigFileName has to be located insidetests/config,the input filetestInputFileName insidetests/input/<testSetName>/,and expected results file inside thetests/expected/<testSetName>/directory.Expected results have the following naming convention:testNr-testInputFileName.

Optionally a! can follow thetestNr to enable a custom rerunconfiguration.Rerun configurations need to be named like this:testConfigFileName(without extension)+.rerun+.extension

Also, optionally a language for the input can be provided withlang.

The codebase has to be formatted by the options set up inforUncrustifySources.cfg. Failing to format the sources correctly willcause TravisCI build failures.

The Command line interface (CLI) output is tested by thetest_cli_options.py script. It is located inside oftests/cli/ and operateson the subdirectories of that folder.

If a PR is altering the CLI output, files inside those directories mightneed to be manually updated. This often happens when options areadded, removed, or altered. Keep in mind that the version string line(example:# Uncrustify-0.69.0_f) of outputs from commands like--show-config should be replaced with a blank line.

The first method is to use uncrustify itself to get debug information.Using:

uncrustify -c myExample.cfg -f myExample.cpp -p myExample.p -L A2>myExample.A

you get two files for the first information.The p-file gives you details of the parsing process and indentation.

# Line                Tag              Parent          Columns Br/Lvl/pp     Flag   Nl  Text#   1>              CLASS[               NONE][  1/  1/  6/  0][0/0/0][  10070000][0-0] class#   1>               TYPE[              CLASS][  7/  7/ 14/  1][0/0/0][  10000000][0-0]       Capteur#   1>         BRACE_OPEN[              CLASS][ 15/ 15/ 16/  1][0/0/0][ 100000400][0-0]               {

The A-file gives you many details about the run itself, where the process is running through,which values have the most important variables.

tokenize(2351): orig line is 1, orig col is 1, Text() 'class', type is CLASS, orig col_end is 6tokenize(2351): orig line is 1, orig col is 7, Text() 'Capteur', type is WORD, orig col_end is 14tokenize(2351): orig line is 1, orig col is 15, Text() '{', type is BRACE_OPEN, orig col_end is 16

You can also dump the parsing information of each formatting step using the 'dump steps' option.

uncrustify -c myExample.cfg -f myExample.cpp -ds dump

This will create a series of 'dump_nnn.log' files, each containing the parsing information atspecific points of the formatting process ('dump_000.log' will list the formatting options in use).

You can combine this option with -p and -L to get a lot of detailed debugging information.

uncrustify -c myExample.cfg -f myExample.cpp -p myExample.p -L A2>myExample.A -ds dump

It might be useful to add some code lines to see where something is happening.Use the packageunc_tools.Remove the comment at line:

#defineDEVELOP_ONLY

Import the package:

#include"unc_tools.h"

Add at some places the line:

prot_the_line(__LINE__,6,0);

Compile again with DEBUG option.

If you need a new option, there are a few steps to follow.Take as example the optionsp_trailing_ret_t

First define the option:

• Insert the code below to the file src/options.h_NOTE:This file is processed by make_options.py, and must conform to a particularformat. Option groups are marked by '//begin ' (in upper case; this exampleis lower case to prevent being considered a region marker for code folding)followed by the group description. Options consist of two lines ofdeclaration preceded by one or more lines of C++ comments. The comments formthe option description and are taken verbatim, aside from stripping theleading '// '. Only comments immediately preceding an option declaration,with no blank lines, are taken as part of the description, so a blank linemay be used to separate notations from a description.An option declaration is 'extern TYPE\nNAME;', optionally followed by' // = VALUE' if the option has a default value that is different from thedefault-constructed value type of the option. The 'VALUE' must be valid C++code, and is taken verbatim as an argument when creating the option'sinstantiation. Note also that the line break, as shown, is required._

// Add or remove space around trailing return operator '->'.extern Option<iarf_e>sp_trailing_ret_t;

• Insert the code below to the file src/space.cpp

if (first->Is(CT_TRAILING_RET_T))   {// Add or remove space around trailing return operator '->'.log_rule("sp_trailing_ret_t");return(options::sp_trailing_ret_t());   }

We are pretty sure that nothing OS-specific is used in the code base.The software has been previously tested on the following operating systems:

• Linux
• QNX
• OS X
• FreeBSD, NetBSD, OpenBSD
• Sun Solaris 9
• Windows (binary available)

NOTE This application works reasonably well but it has bugs. Donotapply it on your whole codebase without checking the results!

Here are ways to run it:

uncrustify -c mystyle.cfg -f somefile.c -o somefile.c.uncuncrustify -c mystyle.cfg -f somefile.c> somefile.c.uncuncrustify -c mystyle.cfg somefile.cuncrustify -c mystyle.cfg --no-backup somefile.cuncrustify -c mystyle.cfg*.cuncrustify -c mystyle.cfg --no-backup*.c

The-c flag selects the configuration file.The-f flag specifies the input file.The-o flag specifies the output file.If flag-f is used without flag-o the output will be send tostdout.

Alternatively, multiple or single files that should be processed can bespecified at the command end without flags.If the flag--no-backup is missing, every file is saved with the initialname and an additional suffix (can be changed with --suffix).

For more options descriptions call:

uncrustify -h

Uncrustify usually reads configuration files that are passed via the-cflag. If the flag is not provided, Uncrustify will try to find aconfiguration file via theUNCRUSTIFY_CONFIG environment variable or afile with the name.uncrustify.cfg oruncrustify.cfg in your home folder.

To get a list of:

• all available options use:

  uncrustify --show-config

• all available options in a usable configuration file format use:

  uncrustify --update-config

  or

  uncrustify --update-config-with-doc

  As the names suggest, both options can produce output that adds newlyintroduced options to your old configuration file. For this your oldconfiguration file has to be passed via the-c flag:

  uncrustify --update-config-with-doc -c path/to/your.cfg

Example configuration files that can be used as a starting point can befound in theetc/ directory (such asben.cfg).

Modify to your liking. Use a quality side-by-side diff tool to determineif the program did what you wanted. Repeat until your style is refined.

To ease the process a bit, some 3rd party tools are available:

• Universal Indent GUI - Across-platform graphical configuration file editor for many codebeautifiers, including Uncrustify. This is currently unmaintained.
• Universal Indent GUI TQt - Amaintained port of the above tool provided by the Trinity Desktop Environment (TDE) team.See how to install binary packages for your distrohere.
  Note you don't need to install TDE to run Universal Indent GUI TQt,it only needs a few libraries. Therefore it can easily be used in anyother desktop environment.
• uncrustify_config - A webconfiguration tool based on Uncrustify's emscripten interface.
• UncrustifyX - Uncrustifyutility and documentation browser for Mac OS X

Under Windows:Uncrustify is a command-line tool, if you run it by double-clicking theexecutable, it will open a command prompt run the executable(which prints the help message), and then immediately close the windowas uncrustify exits.

You can open the command prompt (which is an interactive terminalwindow that allows you to run commands without it closing as soon asthey exit) and run uncrustify.exe there.

Have a lookhere

Have a look athttps://plugins.jetbrains.com/plugin/17528-uncrustify