Syntax Diagrams for APEXlang

Introduction

The APEXlang API Reference documentation went live a few days ago. You can also download the APEXlang EBNF grammar. In this post, Kris Rice explains the value of having an EBNF.

Since the APEXlang grammar is available as EBNF, it can be used to generate syntax diagrams. These diagrams (also known as railroad diagrams) make the language easier to explore and provide a visual complement to the API Reference.

In this blog post, I explain how to produce the syntax diagrams for APEXlang.

What Is EBNF

Wikipedia describes the Extended Backus-Naur Form. However, it’s important to notice that there are several variants of EBNF.

APEXlang EBNF

The APEXlang EBNF grammar uses a variant of the BNF in the SQL:2023 standard, with some extensions explained at the top of the apexlang.ebnf file.

(* Syntax conventions
   <nl> is significant: component declarations, groups, properties, and closing delimiters are line-oriented.
   [ X ] means optional X. { X } means zero or more X. A | B means either A or B.
*)

(* Syntax conventions
   <nl> is significant: component declarations, groups, properties, and closing delimiters are line-oriented.
   [ X ] means optional X. { X } means zero or more X. A | B means either A or B.
*)

Square brackets [] indicate optionality, while curly brackets {} enclose a repeated group as defined in ISO/IEC 14977. However, the apexlang.ebnf file does not fully use this ISO EBNF standard. apexlang.ebnf uses ::= while the ISO standard uses a simple = for symbol definitions. This variant resembles a Wirth EBNF with comments.

Here’s the definition of the app rule in the apexlang.ebnf file.

<app> ::= "app" [ <required-ws> <component-id> ] <ws> "(" <line-end> { <app-body-line> } <indent> ")" <line-end>

<app> ::= "app" [ <required-ws> <component-id> ] <ws> "(" <line-end> { <app-body-line> } <indent> ")" <line-end>

Syntax Diagram

This is the syntax diagram, or railroad diagram, for the app rule.

I produced this syntax diagram with the Railroad Diagram Generator (RR) by Gunter Rademacher. However, this tool requires a W3C EBNF as input. In other words, the original apexlang.ebnf produces runtime errors.

W3C EBNF

Fortunately, it is straightforward to convert the APEXlang EBNF grammar to W3C EBNF. For the current APEXlang grammar, the conversion can be performed entirely through automated text transformations without manual edits.

Here is a list of the most important replacement actions:

The rule app in W3C EBNF looks as follows after applying these changes:

app ::= "app" ( required-ws component-id )? ws "(" line-end ( app-body-line )* indent ")" line-end

app ::= "app" ( required-ws component-id )? ws "(" line-end ( app-body-line )* indent ")" line-end

See Convert.java for the complete conversion program.

Syntax Diagrams on GitHub

You cannot produce the complete syntax diagrams in the online version of the Railroad Diagram Generator because the APEXlang grammar is huge, and you will get a timeout when trying.

So, you need to run the tool locally. I’ve created a GitHub workflow that downloads apexlang.ebnf, converts it to a W3C EBNF, and generates an HTML file containing all syntax diagrams. Finally, the workflow publishes the result:

• APEXlang grammar converted to W3C EBNF
• APEXlang syntax diagrams produced by RR

The advantage of syntax diagrams is that they show all usages of a symbol, allowing you to navigate quickly to the relevant definition.

Outlook

The next step is to build a parser for APEXlang and use this as the basis for linting. This would enable APEXlang source code to be automatically validated, helping both developers and AI agents to produce code that conforms to defined quality standards.

Looking further ahead, we are considering providing full support for APEXlang within the dbLinter tool suite. Currently, dbLinter analyses only SQL and PL/SQL code blocks embedded in APEXlang files. Full APEXlang support is a natural evolution. Stay tuned!