feat(pintora-diagrams): support line comment that starts with '%%'

- docs: basic syntax

demo/src/live-editor/App.tsx

@@ -80,15 +80,7 @@ const AppLayout = () => {
         console.warn('error recovering data from storage', error)
       }
     }
-    code = `
-    activityDiagram
-start
-while (check filesize ?) is (not empty)
-  :read file;
-endwhile (empty)
-:close file;
-    
-    `
+
     if (code) {
       store.dispatch(actions.updateEditorCode({ code, syncToPreview: true }))
     }

packages/pintora-diagrams/src/activity/parser/activityDiagram.ne

@@ -1,6 +1,6 @@
 @{%
 import * as moo from '@hikerpig/moo'
-import { tv, textToCaseInsensitiveRegex, VALID_TEXT_REGEXP } from '../../util/parser-shared'
+import { tv, textToCaseInsensitiveRegex, VALID_TEXT_REGEXP, COMMENT_LINE_REGEXP } from '../../util/parser-shared'
 import type { ApplyPart } from '../db'
 
 let lexer = moo.compile({
@@ -15,6 +15,7 @@ let lexer = moo.compile({
   R_BRACKET: { match: /\}/ },
   START_NOTE: textToCaseInsensitiveRegex('@note'),
   END_NOTE: textToCaseInsensitiveRegex('@end_note'),
+  COMMENT_LINE: COMMENT_LINE_REGEXP,
   VALID_TEXT: { match: VALID_TEXT_REGEXP, fallback: true },
 })
 
@@ -34,6 +35,7 @@ function extractChildren(o) {
 @builtin "string.ne"
 @builtin "whitespace.ne"
 @include "../../util/parser-grammars/config.ne"
+@include "../../util/parser-grammars/comment.ne"
 
 start -> __ start {% (d) => d[1] %}
 	| "activityDiagram" document __:? {%
@@ -77,6 +79,7 @@ statement ->
   | noteStatement
   | arrowLabelStatement
   | configClause _ %NEWLINE
+  | comment _ %NEWLINE
 
 conditionSentence ->
     "if" %SPACE:+ wordsInParens %SPACE:+ "then" (%SPACE:+ wordsInParens):? %SPACE:* %NEWLINE line:* elseClause:? _ "endif" _ %NEWLINE {%

packages/pintora-diagrams/src/component/__tests__/component-parser.spec.js

@@ -293,4 +293,15 @@ componentDiagram
       },
     ])
   })
+
+  it('can parse comments', () => {
+    parse(
+      stripStartEmptyLines(`
+componentDiagram
+  %% comment here
+  `),
+    )
+    const ir = db.getDiagramIR()
+    expect(ir.interfaces).toEqual({})
+  })
 })

packages/pintora-diagrams/src/component/parser/componentDiagram.ne

@@ -1,12 +1,13 @@
 @{%
 import * as moo from '@hikerpig/moo'
-import { tv, VALID_TEXT_REGEXP } from '../../util/parser-shared'
+import { tv, VALID_TEXT_REGEXP, COMMENT_LINE_REGEXP } from '../../util/parser-shared'
 
 const commonTopRules = {
   NEWLINE: { match: /\n/, lineBreaks: true },
   SPACE: {match: /\s+/, lineBreaks: true},
   L_SQ_BRACKET: { match: /\[/ },
   R_SQ_BRACKET: { match: /\]/ },
+  COMMENT_LINE: COMMENT_LINE_REGEXP,
 }
 
 const commonTextRules = {
@@ -35,6 +36,7 @@ export function setYY(v) {
 @builtin "string.ne"
 @builtin "whitespace.ne"
 @include "../../util/parser-grammars/config.ne"
+@include "../../util/parser-grammars/comment.ne"
 
 start -> __ start
   | "componentDiagram" document {%
@@ -66,6 +68,7 @@ statement ->
       }
     %}
   | configClause _ %NEWLINE
+  | comment _ %NEWLINE
 
 UMLElement ->
     group {%

packages/pintora-diagrams/src/er/__tests__/er-parser.spec.js

@@ -49,4 +49,15 @@ erDiagram
       },
     })
   })
+
+  it('can parse comments', () => {
+    parse(
+      stripStartEmptyLines(`
+erDiagram
+  %% comment here
+  `),
+    )
+    const ir = db.getDiagramIR()
+    expect(Object.keys(ir.entities).length).toBe(0)
+  })
 })

packages/pintora-diagrams/src/er/parser/erDiagram.ne

@@ -1,6 +1,6 @@
 @{%
 import * as moo from '@hikerpig/moo'
-import { tv, VALID_TEXT_REGEXP } from '../../util/parser-shared'
+import { tv, VALID_TEXT_REGEXP, COMMENT_LINE_REGEXP } from '../../util/parser-shared'
 
 let lexer = moo.compile({
   NEWLINE: { match: /\n/, lineBreaks: true },
@@ -16,6 +16,7 @@ let lexer = moo.compile({
   LEFT_BRACE: /\{/,
   RIGHT_BRACE: /\}/,
   CONFIG_DIRECTIVE: /@config/, // for config.ne
+  COMMENT_LINE: COMMENT_LINE_REGEXP,
   VALID_TEXT: { match: VALID_TEXT_REGEXP, fallback: true },
 })
 
@@ -31,6 +32,7 @@ export function setYY(v) {
 @builtin "string.ne"
 @builtin "whitespace.ne"
 @include "../../util/parser-grammars/config.ne"
+@include "../../util/parser-grammars/comment.ne"
 
 start -> __ start
   | "erDiagram" document
@@ -66,6 +68,7 @@ statement ->
         yy.addConfig(styleParam)
       }
     %}
+  | comment _ %NEWLINE
 
 entityName ->
     %VALID_TEXT {% id %}

packages/pintora-diagrams/src/mindmap/parser/mindmap.ne

@@ -1,6 +1,6 @@
 @{%
 import * as moo from '@hikerpig/moo'
-import { tv, VALID_TEXT_REGEXP, MOO_NEWLINE } from '../../util/parser-shared'
+import { tv, VALID_TEXT_REGEXP, MOO_NEWLINE, COMMENT_LINE_REGEXP } from '../../util/parser-shared'
 import type { ApplyPart } from '../db'
 
 let lexer = moo.compile({
@@ -12,6 +12,7 @@ let lexer = moo.compile({
   SEMICOLON: /;/,
   COLON: /:/,
   CONFIG_DIRECTIVE: /@config/, // for config.ne
+  COMMENT_LINE: COMMENT_LINE_REGEXP,
   VALID_TEXT: { match: VALID_TEXT_REGEXP, fallback: true },
 })
 
@@ -27,6 +28,7 @@ export function setYY(v) {
 @builtin "string.ne"
 @builtin "whitespace.ne"
 @include "../../util/parser-grammars/config.ne"
+@include "../../util/parser-grammars/comment.ne"
 
 start -> __ start
   | "mindmap" document
@@ -61,6 +63,7 @@ statement ->
       }
     %}
   | configClause _ %NEWLINE
+  | comment _ %NEWLINE
 
 levelNotation ->
     (%ASTERISKS | %PLUS) {%

packages/pintora-diagrams/src/sequence/__tests__/sequence-parser.spec.js

@@ -501,4 +501,15 @@ sequenceDiagram
       },
     ])
   })
+
+  it('can parse comments', () => {
+    const example = stripStartEmptyLines(`
+sequenceDiagram
+  %% comment in one line
+  A->>B: m1
+  `)
+    parse(example)
+    const ir = db.getDiagramIR()
+    expect(ir.messages.length).toBe(1)
+  })
 })

packages/pintora-diagrams/src/sequence/parser.ts

@@ -6,7 +6,13 @@ setYY(db)
 
 export const parse = genParserWithRules(grammar, {
   postProcess(results) {
-    db.apply(results as any)
-    return results
+    let validResults = results
+    // another hack to avoid duplicate results,
+    // @FIXME: need to fix activityDiagram.ne grammar and remove this hack
+    if (Array.isArray(results[0])) {
+      validResults = results[0]
+    }
+    db.apply(validResults as any)
+    return validResults
   },
 })

packages/pintora-diagrams/src/sequence/parser/sequenceDiagram.ne

@@ -1,11 +1,11 @@
 @{%
 import * as moo from '@hikerpig/moo'
-import { tv, textToCaseInsensitiveRegex, VALID_TEXT_REGEXP, COLOR_REGEXP } from '../../util/parser-shared'
+import { tv, textToCaseInsensitiveRegex, VALID_TEXT_REGEXP, COLOR_REGEXP, COMMENT_LINE_REGEXP } from '../../util/parser-shared'
 
 let lexer = moo.states({
   main: {
     NEWLINE: { match: /\n/, lineBreaks: true },
-    SPACE: {match: /\s+/, lineBreaks: true},
+    SPACE: {match: / +/, lineBreaks: false },
     QUOTED_WORD: /\"[^"]*\"/,
     START_NOTE: textToCaseInsensitiveRegex('@note'),
     END_NOTE: textToCaseInsensitiveRegex('@end_note'),
@@ -31,6 +31,7 @@ let lexer = moo.states({
       { match: /right\sof/, type: () => 'RIGHT_OF' },
     ],
     COLOR: /#[a-zA-Z0-9]+/,
+    COMMENT_LINE: COMMENT_LINE_REGEXP,
     WORD: { match: VALID_TEXT_REGEXP, fallback: true },
   },
   line: {
@@ -50,6 +51,7 @@ export function setYY(v) {
 @builtin "string.ne"
 @builtin "whitespace.ne"
 @include "../../util/parser-grammars/config.ne"
+@include "../../util/parser-grammars/comment.ne"
 
 start -> __ start {% (d) => d[1] %}
 	| "sequenceDiagram" document __:? {%
@@ -156,6 +158,7 @@ statement ->
       }
     %}
   | configClause _ %NEWLINE
+  | comment _ %NEWLINE
 
 participantWord ->
     "participant"

packages/pintora-diagrams/src/util/parser-grammars/comment.ne

@@ -0,0 +1,5 @@
+@{%
+export const COMMENT_LINE = /%%.*/
+%}
+
+comment -> %COMMENT_LINE {% (d) => null %}

packages/pintora-diagrams/src/util/parser-shared.ts

@@ -29,3 +29,5 @@ export const COLOR_REGEXP = /#[a-zA-Z0-9]+/
 export const MOO_NEWLINE = { match: /\n/, lineBreaks: true }
 
 // export const CONFIG_DIRECTIVE = /@config/
+
+export const COMMENT_LINE_REGEXP = /%%.*/

website/docs/getting-started/basic-syntax.mdx

@@ -0,0 +1,25 @@
+---
+title: Basic Syntax
+---
+
+## Syntax Structure
+
+All Diagrams definitions begin with a declaration of the diagram type, followed by the definitions of the diagram and its contents.
+
+For example, the DSL below specify a component diagram by the `componentDiagram` declaration.
+
+```pintora play
+componentDiagram
+  [Pintora] --> [DiagramRegistry] : Get diagram by type
+```
+
+## Comments
+
+You can add line comment with `%%` prefixed, the content in that line will not be rendered.
+
+```pintora play
+sequenceDiagram
+  %% here is line comment
+  %% another line comment
+  A-->B: Hi there!
+```

website/docs/getting-started/usage.mdx

@@ -1,5 +1,6 @@
 ---
 title: Usage
+sidebar_position: 1
 ---
 
 ## Browser

website/i18n/zh-CN/docusaurus-plugin-content-docs/current/getting-started/usage.mdx

@@ -1,5 +1,6 @@
 ---
 title: 使用方法
+sidebar_position: 1
 ---
 
 ## Browser