Skip to content

Trivadis/plsql-formatter-settings

main
Switch branches/tags
Code

PL/SQL & SQL Formatter Settings

Introduction

This repository provides formatter settings for the coding style rules of the Trivadis PL/SQL & SQL Coding Guidelines.

Settings are primarily provided for

These settings have been defined and tested with the product versions mentioned above. They might not work in other versions.

JDK 8 or 11 is required for SQLDev and SQLcl. The standalone tvdformat.jar works with JDK 8, 11, 17.

See releases for settings supporting older versions.

Deviating Settings

Please note that these settings do not comply with rule 5. Line breaks are placed after a comma and not before. All other rules are followed. However, you can easily change this in the preferences.

Change Line Breaks On Comma

Installation

Common

Clone this repository or download the ZIP file and extract it.

SQLcl

See sqlcl/README.md.

Standalone Formatter

See standalone/README.md

SQL Developer

  1. Start SQL Developer
  2. Open Preferences
  3. Select Code Editor -> Format -> Advanced Format
  4. Press Import... Advanced Format
  5. Select trivadis_advanced_format.xml
  6. Press Open
  7. Select Code Editor -> Format -> Advanced Format -> Custom Format
  8. Press Import... Custom Format
  9. Select trivadis_custom_format.arbori
  10. Press Open
  11. Press OK to save the settings

Git pre-commit Hook

See hook/README.md.

Nice to Know

Lightweight Formatter

The Arbori program implements a lightweight formatter which accepts different coding styles. If you need a heavyweight formatter to enforce the conformity of your code, you will need to use the default Arbori program provided by the SQL Developer team.

In any case, you can use our SQLcl JavaScript format.js, the standalone formatter or the Git pre-commit hook to format your code.

Disable Formatter

The formatter is enabled by default. You can disable the formatter with a single-line or multi-line comment containing @formatter:off. From that point on, whitespace are kept as is. To re-enable the formatter use @formatter:on.

Supported Marker Comment Action Origin
@formatter:off Disables formatter Eclipse IDE
@formatter:on Enables formatter Eclipse IDE
noformat start Disables formatter PL/SQL Developer
noformat end Enables formatter PL/SQL Developer

The marker comments are case sensitive.

Here's an example showing the code after calling the formatter:

-- @formatter:off
select decode(dummy, 'X', 1 
                   , 'Y', 2
                   , 'Z', 3
                        , 0) /* @formatter:on */
  from dual;

Arbori

SQL Developer uses its own parse tree query language called Arbori for its advanced formatter configuration. Here is some additional information that might be useful if you plan to tweak the behavior of the formatter yourself.

Links

Thank you, Vadim Tropashko for providing this valuable information.

JavaScript Global Variables

To get the most out of the dynamic JavaScript actions from an Arbori program, you should know the following global variables and their corresponding Java class.

Variable Type JAR File
struct oracle.dbtools.app.Format dbtools-common.jar
target oracle.dbtools.parser.Parsed dbtools-common.jar
tuple HashMap<String, oracle.dbtools.parser.ParseNode> dbtools-common.jar
logger oracle.dbtools.util.Logger dbtools-common.jar

Settings for other Products

Formatter settings are also provided for the following products:

Product Version File
Allround Automations PL/SQL Developer 14.0.6 trivadis_beautifier.br
JetBrains DataGrip 2021.1 trivadis.xml
Quest Toad for Oracle 14.1 trivadis_fmtplus.opt

Please refer to the vendor's documentation for instructions on how to import these settings.

Issues

Please file your bug reports, enhancement requests, questions and other support requests within Github's issue tracker.

How to Contribute

  1. Describe your idea by submitting an issue
  2. Fork the PL/SQL & SQL Formatter Settings respository
  3. Create a branch, commit and publish your changes and enhancements
  4. Create a pull request

License

The Trivadis PL/SQL & SQL Formatter Settings are licensed under the Apache License, Version 2.0. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0.