2 added 185 characters in body
source | link

But it is not strictly necessary, and if you don't think it would save you time you probably should not do it. 

You couldcan, of course, parse the input directly into your chosen Java object model or directly into HTML. ANTLR is great but as previous answer suggests there is a significant setup and learning curve.

But it is not strictly necessary. You could parse the input directly into your chosen Java object model or into HTML.

But it is not necessary, and if you don't think it would save you time you probably should not do it. 

You can, of course, parse the input directly into your chosen Java object model or directly into HTML. ANTLR is great but as previous answer suggests there is a significant setup and learning curve.

1
source | link

Why not convert it to a form where existing tools can parse it?

This DSL looks like it could easily be converted to XML.

There appear to be four types of 'Elements' in the example.

  • Elements that follow the pattern [tag-name]*[/tag-name]
  • Elements that follow the pattern {{tag-name}}*{{/tag-name}}
  • Self-closing Elements that have the pattern {{tag-name=value-string}}
  • A free-standing text element with no surrounding tags

Speculation: It appears the two types of elements are not expected to be interleaved, e.g.

  • [x]{{y}}blah [/x] blah{{/y}}

How about a cheap to code conversion to XML?

If this is correct you could decide how you would like each of these patterns converted to XML elements. For example:

  • Convert "[tag-name]" to <tag-name> and "[/tag-name]" to </tag-name>

  • Convert "{{tag-name}}" and "{{/tag-name}}" to <cc-tag-name> and </cc-tag-name>

  • Convert "{{tag-name=value-string}}" to <tag-name>value</tag-name> or <tag-name value=value-string/> for example

  • Leave free-standing text nodes as-is. XML (and HTML) supports those already.

You could do this conversion using global replace with three regex. You could do it with a hand-coded recursive parser-converter (that would be pretty small).

Although most people would probably prefer regex for this job, I would tend to write the hand coded converter in this case because I would like to put some structure validation into the process, e.g. to log or handle the case where elements are interleaved in a way XML will not support.

I would like to find out early on whether the source data violates my assumptions.

You need to know the valid character set and escaping rules.

If you have a large volume of input data to read, you are likely to encounter odd cases, such as unfamiliar unicode characters that may need normalizing, or may be expressed in some form of "entity" notation in the data.

At the very least you need to know how [, ], {{, }}, / are escaped when they occur in text and are not part of markup. If you don't handle this there's a good chance your process will fail on some dictionary entries.

The documentation might tell you these things. It's worth a look.

OK Great. We have XML but we wanted HTML

The point of converting into XML is that you are then free to use the many free open-source tools for parsing XML, transforming XML, deserializing XML into Objects of your design.

When you generate HTML you will make a lot of decisions that are not included in this input data.

  • Navigation: How will users navigate to different entries? Will entries always display in full detail, or will there also be a short form?

  • Formatting, presentation: Mapping this markup into your html structure and css style sheets. Some sections of the input look like they might want margins/indenting that are not included in the markup.

  • Search: For decent user experience you may need to also extract indexing terms from this markup and load them to a text search service.

  • Accessibility: if that's part of your requirements.

  • Images? If there are any, they may need preprocessing.

You may want parse it into POJO's (e.g. with Jackson or other reflection based deserializer) and use html templates (e.g. Freemarker, Thymeleaf, Velocity, even JSP). You'll probably want css styles separate from the main text of the documents if only for flexibility to change presentation without reprocessing all data.

Putting the data in XML or some other well-supported format lets you choose from many tools for these more complex tasks.

But it is not strictly necessary. You could parse the input directly into your chosen Java object model or into HTML.