Merge pull request #349 from Edirom/ftr/xquery-style-conformant

Unify XQuery and XQuery modules format and indentation

CONTRIBUTING.md

@@ -9,8 +9,9 @@
 1. Use whitespaces, not tabs to indent code
 2. Close file with a newline character
 
+# XQuery Styleguide
 
-# XQuery
+For formatting of XQuery files we generally rely on the basic configuration of Synchrosoft’s oXygen XML software family and its “Format & Indent” function.
 
 ## xqDoc
 
@@ -21,41 +22,158 @@ We use [xqDoc](https://xqdoc.org) for documenting the XQueries in this repositor
 
 ## XQuery document structure
 
-### XQuery version
+### XQuery version declaration
 
 ```xquery
 xquery version 3.1;
 ```
 
-### License Statement
+### Beginning comments
+
+For now, the beginning comments should only include the following:
 
 ```xquery
 (:
-For LICENSE-Details please refer to the LICENSE file in the root directory of this repository.
-:)
+ : Copyright: For LICENSE-Details please refer to the LICENSE file in the root directory of this repository.
+ :)
+
+ ```
+The beginning comments and the structuring comments (see below) of the prolog are separated by a blank line.
+
+### Prolog
+
+1. The parts of the prolog, are introduced by a comment followed by a new line.
+2. The below form of the comments and the order of the parts is prescriptive.
+3. Each part of the prolog ends with a blank line.
+
+```xquery
+(: IMPORTS ================================================================= :)
+
+```
+
+Sort imports by type:
+1. All `import module namespace` statements registered with eXist-db
+2. All `import module namespace` statements of custom modules that are not registered with eXist-db. Always use relative URIs for unregistered `import module namespace` statements.
+3. Separate groups with a blank line.
+4. In the groups sort alphabetically by prefix.
+
+```xquery
+(: NAMESPACE DECLARATIONS ================================================== :)
+
+```
+
+All `declare namespace` statements, sorted alphabetically by prefix.
+
+```xquery
+(: OPTION DECLARATIONS ===================================================== :)
+
+
+```
+All `declare option` statements.
+
+```xquery
+(: VARIABLE DECLARATIONS =================================================== :)
+
+```
+1. Use `declare variable` statements for all required external parameters
+2. All global variable declarations, i.e. `declare variable` statements.
+3. Separate these two groups with a blank line.
+4. In the groups, sort alphabetically.
+
+```xquery
+(: FUNCTION DECLARATIONS =================================================== :)
+
 ```
 
-### File Header
+1. All `declare function` statements.
+2. All function declarations have to be preceded by an xqDoc comment.
+3. The xqDoc comment and function declaration belonging together are not separated by blank lines – not even one ;-)
+4. The comment-function-groups are separated by blank lines.
 
-1. `declare namespace` statements
-   * sort alphabetically by prefix
-2. `import module namespace` statements of registered modules
-   * sort alphabetically by prefix
-3. `import module namespace` statements of custom modules
-   * sort alphabetically by prefix
-   * Always use relative URIs for `import module namespace` statements that import for modules not registered with eXist-db.
+A prototypical example:
 
-### Declare variables
+```xquery
+(: FUNCTION DECLARATIONS =========================================== :)
+
+(:~
+ :
+ :)
+declare function eg:addComment($comment as xs:string, $function as function())
+as xs:string
+{
+   …
+}
+
+(:~
+ :)
+declare function eg:addComment($comment as xs:string, $function as function())
+as xs:string
+{
+   …
+}
+```
+
+### Query body
+
+The Query body start after a structuring comment as follows:
+
+```xquery
+(: QUERY BODY ============================================================== :)
+
+```
+
+#### Strings
+
+Note: this is derived from the current usage in Edirom-Online code
+
+* escape with U+00027 APOSTROPHE: `'`
+
+### Literal results
+
+TODO: how should literal results be indented, especially when they are long, e.g., as in the case of [getAudioPlayer.xql](add/data/xql/getAudioPlayer.xql).
 
-* Use `declare variable` statements for all required external parameters
+### let statements
+
+Short variable definitions should be in a single line:
+
+```xquery
+let $lang := 'de'
+```
+
+Longer assignments, especially when the contain if-else-statements or FLWOR-expressions, should break after `:=` and then indent a further level, before following the rules applicable to the respective statements, e.g.:
+
+```xquery
+let $elems :=
+   for $p in $participants
+   let $id := substring-after($p, '#')
+   return doc($doc)/id($id)
+```
 
 ### Function declarations
 
-* functions have to be preceded by an xqDoc comment
+```xquery
+(:~
+ : XQdoc comment
+ :
+ …
+ :
+ :)
+declare function prefix:function-name( $paramOne as datatype, §paramTwo as datatype )
+as datatype
+{
+   …
+};
+
+```
+
+- [ ] at the moment return datatypes and opening curly braces of function declarations are still in the same line as the `declare function` statement
+- [ ] break long function argument
 
-### XQuery body
+### HowTo ToDo:s
 
-* Strings: escape with U+00027 APOSTROPHE: `'`
+- [ ] literal results formatting
+- [ ] nested return statements
+- [ ] parenthesis placement
 
 
 # Javascript
@@ -77,7 +195,7 @@ An example of using the function would be:
 
 ```javascript
 window.doAJAXRequest('data/xql/getAnnotationMeta.xql',
-    'GET', 
+    'GET',
     {
         uri: uri,
         lang: lang
@@ -87,3 +205,4 @@ window.doAJAXRequest('data/xql/getAnnotationMeta.xql',
     }, this)
 );
 ```
+

add/data/xql/checkTextGridLogin.xql

@@ -1,15 +1,22 @@
-xquery version "3.0";
+xquery version "3.1";
 
-declare namespace html="http://www.w3.org/1999/xhtml";
-declare namespace h="http://exist-db.org/xquery/httpclient";
+(:
+ : Copyright: For LICENSE-Details please refer to the LICENSE file in the root directory of this repository.
+ :)
 
-let $sessionId := request:get-parameter('sessionId', '')
+(: IMPORTS ================================================================= :)
+
+import module namespace httpclient = "http://exist-db.org/xquery/httpclient";
+
+(: NAMESPACE DECLARATIONS ================================================== :)
 
-let $test := httpclient:head(xs:anyURI('http://textgridlab.org/1.0/tgcrud/rest/textgrid:208dw/data?sessionId=' || $sessionId),
-                    false(), ())
+declare namespace html = "http://www.w3.org/1999/xhtml";
 
+(: QUERY BODY ============================================================== :)
+
+let $sessionId := request:get-parameter('sessionId', '')
+let $test := httpclient:head(xs:anyURI('http://textgridlab.org/1.0/tgcrud/rest/textgrid:208dw/data?sessionId=' || $sessionId), false(), ())
 let $status := $test/root()/httpclient:response/string(@statusCode)
 let $status := response:set-status-code(xs:int($status))
-
 return
-    $status
+    $status