Bug/5123 allow attribute names to be escaped on er diagram

[ejscribner]

📑 Summary

Enables special characters within backticked strings for the attributeName in an ER Diagram.

Resolves #5123

📏 Design Decisions

To allow more flexibility in an attributeName, I've used backticks to escape all special characters that a user might need to put there.

This approach:

1. Doesn't break the current (stricter) parsing functionality as it just adds a new BACKTICK_STRING token
2. Allows for much increased flexibility if users need it

📋 Tasks

Make sure you

• 📖 have read the contribution guidelines
• 💻 have added necessary unit/e2e tests.
• 📓 have added documentation. Make sure MERMAID_RELEASE_VERSION is used for all new features.
• 🔖 targeted develop branch

[netlify]

✅ Deploy Preview for mermaid-js ready!

Name	Link
🔨 Latest commit	779178c
🔍 Latest deploy log	https://app.netlify.com/sites/mermaid-js/deploys/65aeca7ff1743e0008133bf6
😎 Deploy Preview	https://deploy-preview-5138--mermaid-js.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Comparison is base (7b62466) 43.04% compared to head (779178c) 79.35%.

Additional details and impacted files

@@             Coverage Diff              @@
##           develop    #5138       +/-   ##
============================================
+ Coverage    43.04%   79.35%   +36.31%     
============================================
  Files           23      167      +144     
  Lines         5018    13873     +8855     
  Branches        21      707      +686     
============================================
+ Hits          2160    11009     +8849     
+ Misses        2857     2711      -146     
- Partials         1      153      +152     

Flag	Coverage Δ
e2e	85.16% <ø> (?)
unit	43.04% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

see 163 files with indirect coverage changes

[nirname]

Awesome! Some minor changes and this will be ok

[nirname]

Is it possible to add backtick within attribute name as well? I am asking because we are trying to allow basically any characters within attribute name with this PR. Minor

[ejscribner]

Adding one more backtick in the name causes a parse error, and adding a second one breaks it into two attributes. For example:

String `geo.`acc`uracy` 

becomes:

I'm not sure if there is a way around this behavior, other than maybe changing the escape characters from backticks to something else. Let me know if you have suggestions here 🙂

[nirname]

They should be escaped then. Common practice is to use escapement character, like \ (\\ and \` respectively for \ and `) or duplicating characters, like "hello""quotes" (csv uses that approach), or using another character as wrapper (like double backtick for markdown)

[nirname]

I am not sure which approach to pick up, they all have some flaws but it's better to think about such a feature beforehand because it is a real pain to introduce something like this later without braking backwards compatibility

[ejscribner]

Thanks for the review @nirname, fixed the easy ones. Let me know if you have any ideas or thoughts on the backticks in attribute name one.

[nirname]

Please, do not forget to add some documentation describing this, otherwise people wont be aware of that feature.

[nirname]

Sorry for the long response.

@ejscribner please add some documentation describing this feature

@sidharthv96 @aloisklink what do you think on escapement syntax for backtics?

[nirname]

There are 2 main options

Escape using `` double backtick

source	outcome
backticked string with `` in it	backticked string with ` in it
backticked string with \ in it	backticked string with \ in it
backticked string with in it`	error

Escape using \ backslash

source	outcome
backticked string with \ in it`	backticked string with ` in it
backticked string with \\ in it	backticked string with \ in it
backticked string with in it`	error

[nirname]

Code is OK. We need some documentation covering this feature to continue

[mjpieters]

I would love to see this land.

We use https://github.com/k1LoW/tbls/ to generate database documentation including Mermaid ER diagrams. However, I currently have to disable generating Mermaid ERDs for a specific database view that uses some special characters in the column names (<= and > respectively), as these can't be escaped with the current mermaid syntax.

Is there any way I can help pull this over the line?

[nirname]

@mjpieters Yes, you definitely can. This is half-ready. Whether @ejscribner is going to continue on this or not, you can always take what has already been done, open new PR to the issue #5123 and we can continue over there.

Anyway you can help with a piece of advise so we could come up with convenient format for escaping, and I could complete the feature myself. It's up to you, any help appreciated.

[nirname]

I'll assign myself to this PR so it would be easier to find this among other issues. Doesn't necessarily mean we continue this very branch.

[stevemuench]

Also very interested in seeing this feature land. Oracle table column names frequently have a dollar-sign in them and would love to be able to render data types like varchar2(32) with parens in the name via appropriate escaping.

[mjpieters]

There are 2 main options
[...]

There is another option: accept character references, so ` or <, or something based on these. See below.

Normally, I'd say you should pick an option that is consistent with the syntax used by other mermaid diagrams. Unfortunately, there is no consistency here:

• Flowchart uses modified character references (entity escapes); entities start with # instead of & and mix decimal number and named references (HTML references use &#..; for decimal number references, and &x...; for hexadecimal number references, whereas flowchart mixes these two styles).
• Class Diagrams let you use either backticks or bracketed double quotes to define class labels, so you can switch between them as needed
• Sankey is CSV-based and so uses doubled double quotes

GIven that mermaid is specifically designed to be embedded inside Markdown documents, I'd go with the backslash to escape backticks (and backslashes, because you need to support escaping a backslash too).