cql syntax (wip)

.vitepress/config.js

@@ -194,10 +194,12 @@ if (process.env.VITE_CAPIRE_EXTRA_ASSETS) {
 import { dl } from '@mdit/plugin-dl'
 import * as MdAttrsPropagate from './lib/md-attrs-propagate'
 import * as MdTypedModels from './lib/md-typed-models'
+import * as MdDiagramSvg from './lib/md-diagram-svg'
 
 config.markdown.config = md => {
   MdAttrsPropagate.install(md)
   MdTypedModels.install(md)
+  MdDiagramSvg.install(md)
   md.use(dl)
 }
 

.vitepress/lib/md-diagram-svg.ts

@@ -0,0 +1,22 @@
+import { MarkdownEnv, MarkdownRenderer } from 'vitepress'
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+export function install(md: MarkdownRenderer) {
+  const defaultImage =
+    md.renderer.rules.image ||
+    ((tokens, idx, options, env, self) => self.renderToken(tokens, idx, options))
+
+  md.renderer.rules.image = (tokens, idx, options, env: MarkdownEnv, self) => {
+    const token = tokens[idx]
+    const src = token.attrGet('src') || ''
+
+    if (!/\.svg\?raw$/.test(src)) {
+        return defaultImage(tokens, idx, options, env, self)
+    }
+    const mdDir = dirname(env.realPath ?? env.path)
+    const filePath = join(mdDir, src.replace('?raw', ''))
+    const content = readFileSync(filePath, 'utf-8')
+    return `<span class="diagram">${content}</span>`
+  }
+}

.vitepress/theme/styles.scss

@@ -312,6 +312,18 @@ img, video.bright {
   }
 }
 
+// Raw svg diagrams
+.diagram {
+  all: initial; // preserve original svg formatting
+  .dark & { // recolor in dark mode
+    filter: brightness(.884) invert(1) hue-rotate(177deg);
+  }
+  svg {
+    max-width: 100%;
+    height: auto;
+    margin: 30px auto;
+  }
+}
 
 
 .VPBadge {

cds/cql.md

@@ -14,9 +14,27 @@ CDS Query Language (CQL) is based on standard SQL, which it enhances by...
 [[toc]]
 
 
+## SELECT
+
+![](./assets/cql/select.drawio.svg?raw)
+
+> Using: [Query Source](#query-source), [Select Item](#select-item), [Expressions](./cxl#expr), Ordering Term
+
+
+## Query Source
+
+![](./assets/cql/query-source.drawio.svg?raw)
+
+## Select Item
+
+![](./assets/cql/select-item.drawio.svg?raw)
+
+
 ## Postfix Projections
 {#postfix-projections}
 
+![](./assets/cql/postfix-projection.drawio.svg?raw)
+
 CQL allows to put projections, that means, the `SELECT` clause, behind the `FROM` clause enclosed in curly braces. For example, the following are equivalent:
 
 ```sql
@@ -29,6 +47,10 @@ SELECT from Authors { name, address.street }
 ### Nested Expands <Beta />
 {#nested-expands}
 
+
+![](./assets/cql/nested-expand.drawio.svg?raw)
+
+
 Postfix projections can be appended to any column referring to a struct element or an association and hence be nested.
 This allows **expand** results along associations and hence read deeply structured documents:
 
@@ -125,6 +147,8 @@ results = [
 
 ### Nested Inlines <Beta /> {#nested-inlines}
 
+![](./assets/cql/nested-inline.drawio.svg?raw)
+
 Put a **`"."`** before the opening brace to **inline** the target elements and avoid writing lengthy lists of paths to read several elements from the same target. For example:
 
 ```sql
@@ -466,3 +490,8 @@ extend BookReviews with columns {
   book : Association to Books on book.ID = bookID
 };
 ```
+
+
+## Ordering Term
+
+![](./assets/cql/ordering-term.drawio.svg?raw)