Documentation of HCL and REGEX

Question

I saw in the plantuml repository that a description for EBNF existed and that there was now a reference from README.md to it (pull request #1275  thanks  @The-Lu).

In the plantuml code I saw also that there are possibilities for:

- regex, probably related to the question https://forum.plantuml.net/17112/regex-railroad-diagrams?show=17112#q17112,

- hcl, no idea what it is / where hcl stands for.

Are there for this:

- example(s)

- documentation

Comments

Great start!

Cant wait to see more as it gets flushed out...

I would suggest the same start/end indicators as in ebnf.

Great job so far!

---

I think named groups and backreferences might be a major stumbling block when you get to it, so rather then wait:

https://www.regular-expressions.info/refext.html

---

hcl is just a specific kind of json document for configuring go applications...

I would suggest since json is already supported, this is not needed.

---

The big areas missing so far...

1. Unicode... /u /x and /p escapes
2. Range qualifiers a{1,5} ... 1 to 5 "a" characters
3. Rendering of groups... I would expect comment to draw a box around the left item, and add a yellow note

See 

• http://alphadoc.plantuml.com/doc/markdown/en/regex

---

Great job so far... I see two things that would need fixed.
1: unicode symbols are not working/displayed.
2: group like things need work
I suggest we wrap these group things in something that looks like a package in a class diagram (a box around the group that indicates details about the group).... this also applies for repetitions (ie: this thing 5 or more times), but would just need to look a bit different so one could tell the 2 apart.

I THINK those 2 things MAY wrap things up... if not, it would probably be very close... to the point that the remaining issues might actually be good enough for most people.

See alphadoc for more details, and as always let us know if you have questions!

Answer 1

Hello A., and all,

That's a call for papers..

If you want to contribute, here are some beginning for those topics:

• http://alphadoc.plantuml.com/doc/markdown/en/regex

@startregex
repetitionZeroOrMore: a*
@endregex

• http://alphadoc.plantuml.com/doc/markdown/en/hcl

@starthcl
{
key = "value"
}
@endhcl

Enjoy,
Regards,
Th.

Comments

I fully agree that it looks like That's a call for papers..

problem is that in both case is is unknown what is all excepted and furthermore I tried 2 simple cases:

Regex:

@startregex
repetitionZeroOrMore a*
repetitionOneOrMore a+

@endregex

and here we only see the last expression.

And when trying a bit more complicated example from a page like https://hcl.readthedocs.io/en/latest/language_design.html I got always a stack dump even though I'm using : PlantUML version 1.2023.1beta5 (Unknown compile time)

---

Regex is really undocumented, but should work.

HCL is both undocumented and not working :-)

---

I just submitted 2 issues in respect to the problems I see:

- HCL: https://github.com/plantuml/plantuml/issues/1279

- REGEX: https://github.com/plantuml/plantuml/issues/1280,

@ plantuml your example just shows just 1 regular expressing (and just the expression) but the answer from @Th-Lu suggested that it was possible to label a regular expression and I thought it might also be a good thing to have more than one named regular expression so that e.g (f)lex regular expressions can be shown or regular expressions as shown to define with computer language syntax (like in the Annex A (informative) Grammar summary of the C++ standard, see https://github.com/cplusplus/draft)

---

I would do regex as a document by it self, before dealing with them inside ebnf, but thats just me.

---

I would use https://www.regular-expressions.info/tutorial.html as a starting point/reference of syntax, and try to get a "railroad diagram" (see ebnf) for regexes...

I think most of the actual diagramming part is there... but yes, the syntax would be wildly differant.

The most noteable delta I can see (there are probably others) would be named groups, might want to figure out how to draw those first.

Again this is something that would be extremely useful if only 50% of actual regex is supported, so dont think everything needs done before setting it off into the wild...

At a minimum if you can handle common regex patterns (ssn, phone number, isbn, etc...) and have some clue on how to display groupings of things... I think it may have some value to send it out in the world at that point.

---

I do NOT know what a HCL is.

---

Hello A., T., and all,

HCL is the HashiCorp Configuration Language or Human Configuration Language.

Ref.:

• https://github.com/hashicorp/hcl
• https://www.linode.com/docs/guides/introduction-to-hcl/
• https://www.octopus.com/blog/state-of-config-file-formats
• https://www.hcl2json.com

Good dev... good doc...
Regards.

---

Regex is really undocumented, but should work.

Here is a simple not working example: 

@startregex
(?:[%s]*\\{([^{}]*)\\})?
@endregex

Regards.

---

Thanks, we're going to have a look at it!

---

I was expecting only one regex per diagram...

Although you might want to allow them to be embedded in others (ebnf for example).

So the only first... need to think about that.

---

Was not what I was expecting, but... why not seems fine to me.