From de3e9e1e74465fdd8aec11374b4335363c7b8570 Mon Sep 17 00:00:00 2001 From: hikerpig Date: Thu, 3 Feb 2022 14:53:18 +0800 Subject: [PATCH] feat(pintora-diagrams): support line comment that starts with '%%' - docs: basic syntax --- demo/src/live-editor/App.tsx | 10 +------- .../src/activity/parser/activityDiagram.ne | 5 +++- .../__tests__/component-parser.spec.js | 11 ++++++++ .../src/component/parser/componentDiagram.ne | 5 +++- .../src/er/__tests__/er-parser.spec.js | 11 ++++++++ .../src/er/parser/erDiagram.ne | 5 +++- .../src/mindmap/parser/mindmap.ne | 5 +++- .../__tests__/sequence-parser.spec.js | 11 ++++++++ .../pintora-diagrams/src/sequence/parser.ts | 10 ++++++-- .../src/sequence/parser/sequenceDiagram.ne | 7 ++++-- .../src/util/parser-grammars/comment.ne | 5 ++++ .../src/util/parser-shared.ts | 2 ++ website/docs/getting-started/basic-syntax.mdx | 25 +++++++++++++++++++ website/docs/getting-started/usage.mdx | 1 + .../current/getting-started/usage.mdx | 1 + 15 files changed, 97 insertions(+), 17 deletions(-) create mode 100644 packages/pintora-diagrams/src/util/parser-grammars/comment.ne create mode 100644 website/docs/getting-started/basic-syntax.mdx diff --git a/demo/src/live-editor/App.tsx b/demo/src/live-editor/App.tsx index c11daa75..07542b0a 100644 --- a/demo/src/live-editor/App.tsx +++ b/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 })) } diff --git a/packages/pintora-diagrams/src/activity/parser/activityDiagram.ne b/packages/pintora-diagrams/src/activity/parser/activityDiagram.ne index 5337cc8d..5edbc779 100644 --- a/packages/pintora-diagrams/src/activity/parser/activityDiagram.ne +++ b/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 {% diff --git a/packages/pintora-diagrams/src/component/__tests__/component-parser.spec.js b/packages/pintora-diagrams/src/component/__tests__/component-parser.spec.js index 96224f32..1f3eee0c 100644 --- a/packages/pintora-diagrams/src/component/__tests__/component-parser.spec.js +++ b/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({}) + }) }) diff --git a/packages/pintora-diagrams/src/component/parser/componentDiagram.ne b/packages/pintora-diagrams/src/component/parser/componentDiagram.ne index ee6f460b..ecffee20 100644 --- a/packages/pintora-diagrams/src/component/parser/componentDiagram.ne +++ b/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 {% diff --git a/packages/pintora-diagrams/src/er/__tests__/er-parser.spec.js b/packages/pintora-diagrams/src/er/__tests__/er-parser.spec.js index 18b1ddad..0281fc5d 100644 --- a/packages/pintora-diagrams/src/er/__tests__/er-parser.spec.js +++ b/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) + }) }) diff --git a/packages/pintora-diagrams/src/er/parser/erDiagram.ne b/packages/pintora-diagrams/src/er/parser/erDiagram.ne index 96c13698..b02cf4c2 100644 --- a/packages/pintora-diagrams/src/er/parser/erDiagram.ne +++ b/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 %} diff --git a/packages/pintora-diagrams/src/mindmap/parser/mindmap.ne b/packages/pintora-diagrams/src/mindmap/parser/mindmap.ne index b4b4ede5..cd08a0f3 100644 --- a/packages/pintora-diagrams/src/mindmap/parser/mindmap.ne +++ b/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) {% diff --git a/packages/pintora-diagrams/src/sequence/__tests__/sequence-parser.spec.js b/packages/pintora-diagrams/src/sequence/__tests__/sequence-parser.spec.js index 2c9e04e5..f69dae9f 100644 --- a/packages/pintora-diagrams/src/sequence/__tests__/sequence-parser.spec.js +++ b/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) + }) }) diff --git a/packages/pintora-diagrams/src/sequence/parser.ts b/packages/pintora-diagrams/src/sequence/parser.ts index 5d0574e6..27c6bf4e 100644 --- a/packages/pintora-diagrams/src/sequence/parser.ts +++ b/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 }, }) diff --git a/packages/pintora-diagrams/src/sequence/parser/sequenceDiagram.ne b/packages/pintora-diagrams/src/sequence/parser/sequenceDiagram.ne index a53ec2b9..db3d4323 100644 --- a/packages/pintora-diagrams/src/sequence/parser/sequenceDiagram.ne +++ b/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" diff --git a/packages/pintora-diagrams/src/util/parser-grammars/comment.ne b/packages/pintora-diagrams/src/util/parser-grammars/comment.ne new file mode 100644 index 00000000..9a9f238e --- /dev/null +++ b/packages/pintora-diagrams/src/util/parser-grammars/comment.ne @@ -0,0 +1,5 @@ +@{% +export const COMMENT_LINE = /%%.*/ +%} + +comment -> %COMMENT_LINE {% (d) => null %} diff --git a/packages/pintora-diagrams/src/util/parser-shared.ts b/packages/pintora-diagrams/src/util/parser-shared.ts index dc446728..36e9c83d 100644 --- a/packages/pintora-diagrams/src/util/parser-shared.ts +++ b/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 = /%%.*/ diff --git a/website/docs/getting-started/basic-syntax.mdx b/website/docs/getting-started/basic-syntax.mdx new file mode 100644 index 00000000..bec65c8a --- /dev/null +++ b/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! +``` diff --git a/website/docs/getting-started/usage.mdx b/website/docs/getting-started/usage.mdx index f011c65d..6aa64ee4 100644 --- a/website/docs/getting-started/usage.mdx +++ b/website/docs/getting-started/usage.mdx @@ -1,5 +1,6 @@ --- title: Usage +sidebar_position: 1 --- ## Browser diff --git a/website/i18n/zh-CN/docusaurus-plugin-content-docs/current/getting-started/usage.mdx b/website/i18n/zh-CN/docusaurus-plugin-content-docs/current/getting-started/usage.mdx index a684e946..f6020511 100644 --- a/website/i18n/zh-CN/docusaurus-plugin-content-docs/current/getting-started/usage.mdx +++ b/website/i18n/zh-CN/docusaurus-plugin-content-docs/current/getting-started/usage.mdx @@ -1,5 +1,6 @@ --- title: 使用方法 +sidebar_position: 1 --- ## Browser