How Does Formatting Work?<\/h2>\n\n\n\n
Formatting is all about adding (or removing) whitespace (line breaks, spaces or tabs) between significant tokens. That sounds easy. Well, it’s not. Because the formatting requirements are very different. Ultimately, it’s all about beautifying the code. And almost every developer has their own views on what makes code look good. Furthermore, it is technically demanding to provide a tool suite that can handle different coding styles via configuration.<\/p>\n\n\n\n
The following figure illustrates the formatting process in SQL Developer.<\/p>\n\n\n\n I will explain each step and component in the next chapters.<\/p>\n\n\n\n Please note that these are conceptual components, the actual implementation might look different.<\/p>\n\n\n\n The parser reads the unformatted plain SQL or PL\/SQL input and generates a parse-tree. The parse-tree is a hierarchical representation of the significant tokens of the input. In other words, there is neither whitespace nor comments in a parse-tree.<\/p>\n\n\n\n Each node in the parse-tree includes the start and end position within the plain SQL input.<\/p>\n\n\n\n The formatter needs the parse-tree and the code formatting configuration as input.<\/p>\n\n\n\n SQL Developer stores the configuration in the preferences.<\/p>\n\n\n\n The formatter provides the following Java callback functions (in the order how they are expected to be called):<\/p>\n\n\n\n Each callback functions gets the parameters These provided Java callback functions have two issues.<\/p>\n\n\n\n First of all, you don’t know what they do. Granted, there are some comments in the provided Arbori program, and also a description in the SQL Developer Users Guide<\/a>, but this will only give you a rough idea. For example, it leaves you in the dark why `indentedNodes` has two callback functions and both must be called.<\/p>\n\n\n\n Second, you cannot process selected nodes differently. You must write an enhancement request so that the SQL Developer team can provide the necessary callback functionality in a future release. This is cumbersome.<\/p>\n\n\n\n Thankfully, the SQL Developer team has added a JavaScript callback feature in version 19.2. This allows you to embed callback functions directly into your Arbori program. Now you can really add and remove whitespace wherever you want. The global variable Basically, the result of this process is a list of whitespace per position.<\/p>\n\n\n\n The serializer loops through the leaf nodes of the parse-tree. It retrieves the leading whitespace for a node’s start position and extracts the token text from the pure SQL input using the node’s start and end position. And then the serializer writes the whitespace and the token text to the final result. The formatted SQL.<\/p>\n\n\n\n In fact, the process is actually a bit more complicated. It adds whitespace to mandatory nodes, for instance.<\/p>\n\n\n\n Moreover, the serializer performs some “formatting” without Arbori. For example, it converts the case of identifiers and keywords according to the configuration (properties). Therefore, it is not possible to change the case of a token with an Arbori program. It might be possible by configuring a custom Java formatter class, but that’s another story.<\/p>\n\n\n\n For this example I use the The default is used for the ![\"\"](\"https:\/\/www.salvis.com\/blog\/wp-content\/uploads\/2020\/04\/arbori-overview.png\")
<\/a><\/figure>\n\n\n\n1. Parser<\/h3>\n\n\n\n
2. Formatter<\/h3>\n\n\n\n
\n
Code Editor<\/code> -> Format<\/code> -> Advanced Format<\/code> for configuration properties such as Line breaks on comma<\/code> (after<\/code>, before<\/code>, none<\/code>).<\/li>\n\n\n\nCode Editor<\/code> -> Format<\/code> -> Advanced Format<\/code> -> Custom Format<\/code> for the Arbori program used to handle whitespace.<\/li>\n<\/ul>\n\n\n\n2.1 Provided Java Callback Functions<\/h4>\n\n\n\n
\n
target<\/code> (the parse-tree) and tuple<\/code> (node to be processed). As an Arbori developer you do not have to care about how to populate these parameters. It’s done automatically. target<\/code> is a global variable and tuple<\/code> is the result row of an Arbori query. Basically, you only need to query the nodes and call the callback functions. The position in an Arbori program defines the execution order.<\/p>\n\n\n\n2.2 JavaScript Callback Functions<\/h4>\n\n\n\n
struct<\/code> gives you access to the instance of the formatter and the configuration properties. As a result, you can manage the whitespace before a position of a node through the methods getNewline<\/code> and putNewline<\/code>.<\/p>\n\n\n\n2.3 The Result<\/h4>\n\n\n\n
3. Serializer<\/h3>\n\n\n\n
Example Using Provided Java Callback Function<\/h2>\n\n\n\n
Setup<\/h3>\n\n\n\n
Advanced Format<\/code> according the trivadis_advanced_format.xml<\/a> file. Here’s a screenshot of the configuration settings of my SQL Developer 19.4.0 installation:<\/p>\n\n\n\n![\"\"](\"https:\/\/www.salvis.com\/blog\/wp-content\/uploads\/2020\/04\/advanced_format.png\")
<\/a><\/figure>\n\n\n\nCustom Format<\/code>.<\/p>\n\n\n\nDefault Formatter Result<\/h3>\n\n\n\n