Formatting XPath/XQuery: Preferences, Conventions

[ChristianGruen]

In #1060, the formatting of code examples in the spec was unified. This issue is about discussing the formatting rules and (ideally) to define conventions for newly added code. If we don’t manage to define rules, the existing specs should provide enough examples for all syntactical constructs to be inspired by.

To start with, one suggestion in yesterday’s meeting was to choose a more compact presentation. Empty maps, empty arrays, and functions with an empty body are currently formatted as follows:

map { }, { },
array { }, [ ],
function { }, fn { }, fn($x) { }

We could remove the inner whitespace:

map {}, {},
array {}, [],
function {}, fn {}, fn($x) {}

[ChristianGruen]

Since I had already formatted empty arrays as [], I have removed inner whitespace in empty arrays and functions in #1121 as suggested.

[line-o]

let's talk about if-else next:

I have seen three formattings

1. no parenthesis, EXPR on separate line, indented

if (CONDITION) then
  EXPR
else
  EXPR

2. parenthesis, then on the same line as if

if (CONDITION) then (
  EXPR
) else (
  EXPR
)

3. if, then and else on their own lines, always use parenthesis

if (CONDITION)
then (EXPR)
else (EXPR)

• if EXPR is spanning multiple lines then

if (CONDITION)
then (
  EXPR
)
else (
  EXPR
)

[ChristianGruen]

My suggestion would be to use:

if (CONDITION) then EXPR1 else EXPR2

(: and :)

if (CONDITION1) then (
  EXPR1
) else if (CONDITION2) then (
  EXPR2
) else (
  EXPR3
)

(: and :)

if (CONDITION1) {
  EXPR1
} else if (CONDITION2) {
  EXPR2
}

[line-o]

@ChristianGruen Is your third formatting proposal with curly braces a new syntax?

I can live with option 2 (always use parenthesis on multi-line then and else expressions), although most of my code to date uses option 3 (always use parenthesis with then and else on their own lines).

[ChristianGruen]

@ChristianGruen Is your third formatting proposal with curly braces a new syntax?

Yes; it’s particularly helpful if the else branch is not required: https://qt4cg.org/specifications/xquery-40/xquery-40-diff.html#id-conditionals. Of course this syntax could also be used for one-liners:

if (CONDITION) { EXPR1 } else { EXPR2}
if (CONDITION) { EXPR1 }

[line-o]

I would like us to then also find a proposal for multi-line variable declarations and definitions

let $var :=
    if (CONDITION1) then (
        EXPR1
    ) else (
        EXPR2
    )

same goes for declare variable $my:var := EXPR;

And there is more to talk about

• arrow expressions (when spanning multiple lines do we indent or not?)
• function definitions and declarations
  • placement of curly-braces
  • formatting long parameter definitions
  • how to format annotations

[ChristianGruen]

I would like us to then also find a proposal for multi-line variable declarations and definitions

My favorite syntax is the one that I used for e.g. fn:sort-with or fn:do-until:

let $var := if (CONDITION) then SHORT-EXPR1 else SHORT-EXPR2
return if (CONDITION2) then SHORT-EXPR1 else SHORT-EXPR2

(: or :)

let $var1 := if (CONDITION1) then (
  EXPR1a-IF-TOO-LONG-FOR-SINGLE-LINE
) else (
  EXPR1b-IF-TOO-LONG-FOR-SINGLE-LINE
)
return (
  let $var2 := if (CONDITION2) then (
    EXPR2a-IF-TOO-LONG-FOR-SINGLE-LINE
  ) else (
    EXPR2b-IF-TOO-LONG-FOR-SINGLE-LINE
  )
  return if (CONDITION3) then (
    EXPR3-IF-TOO-LONG-FOR-SINGLE-LINE
  ) else (
    EXPR4-IF-TOO-LONG-FOR-SINGLE-LINE
  )
)

I tend to use additional parentheses for educational purposes. What is “too long” currently depends on the screen layout of the specification documents.

If we want to identify the preferred syntax of the previous editors, we could (with some lines of XQuery/XSLT) analyze and quantify the existing variants used in the draft.

[line-o]

I would like to add that we always add a space between the opening and closing curly braces and the enclosed expression:

if (@price gt 100) {@discount}

from the example in the spec would become

if (@price gt 100) { @discount }

If the enclosed expression is empty the braces we should collapse the spaces as for empty maps

if (@a eq 1) {} else { @a }