Add a formatter for a proper OO model

[paduc]

I'm using PlantUML and this great parser to describe my Typescript classes.

Could we imagine an output being a ts/js object that contains the relationships between the class objects ?

Instead of a list of nodes and edges I would like to have an object I can traverse and only contains OOP concepts (not display concepts like visibility or links).

I'm thinking of something a bit like this:

const model = {
  nodes: [{
    name: "MyClass",
    type: "class",
    members: [
      {
        name: "create",
        type: "method",
        isStatic: true,
        isAbstract: false,
        visibility: "public",
        arguments: [{
          type: "Int", // could also be a reference to a class/interface node
          name: "age"
        }],
        returnType: {
          name: "MyClass",
          // ... reference to the MyClass node
        }
      }
    ],
    extends: [ 
      // direct reference to another class node
    ],
    implements: [
      // direct reference to an interface node
    ]
  }]
}

(The direct references would cause circularity which would prevent serialisation but that is not the point)

Would this type of formatter find a place in plantuml-parser ?

[Enteee]

I thought about this for quite some time, and I think I get your idea. Because that's exactly what I have done with the graph formatter. And I came to the following conclusion:

Formatters maintained in this repository must produce output which is automatically verifiable by the use of an external parser. If that's given, we can write an automated test case for this formatter which will guarantee maintainability of the formatter's code.

This means for your request: If we can make this formatter compatible to the input of a tool which parses the formatter's output, I am all in for this feature. However, if we do invent our own output format, then we are just transpiling the AST into some other not standardized format. And for this I don't see any value. Also it will be almost impossible to maintain.

But, if you need this custom intermediate representation without going the full step of making it compatible to some other tool (i.e. a source code generator, your own parser, ... ) . It should be easy to keep this formatter somewhere external. You can then call that custom formatter using the programmatic API.

I could even implement some command line support for this. Like:

  --formatter, -f  formatter to use
                              prefix with '@' to load formatter from file. 
                              i.e. -f @myformatter.js
                              [choices: "default", "graph"] [default: "default"]

What do you think about that?

I am happy to discuss and help you writing that formatter even if you need to keep it external. But I do hope that you understand my decision.

Side note: The graph formatter is not automatically verifiable. It currently only serves the purpose of an example. It should be removed once we have our first external verifiable formatter.

[paduc]

Hi @Enteee !

Thanks for putting so much thought into my issue and explaining your decision. I totally agree.

Indeed my need is an intermediate representation and specific to what I want to achieve with it, not generic. So this formatter / intermediate representation should be located inside my project or as an external standalone library. As long as plantuml-parser returns a JavaScript object that is a complete representation of the contents of a PlantUML, I should be able to build whatever representation I need.

There is one aspect which might have its place in the plantuml-parser representation though. When the PlantUML allows two syntax for a type of relationship, shouldn’t the representation express that relationship in a single manner ?
For example, « A extends B » can be expressed by « class A extends B » or « B <|— A ». Shouldn’t both these syntax return exactly the same output ?

[Enteee]

There is one aspect which might have its place in the plantuml-parser representation though. When the PlantUML allows two syntax for a type of relationship, shouldn’t the representation express that relationship in a single manner ?
For example, « A extends B » can be expressed by « class A extends B » or « B <|— A ». Shouldn’t both these syntax return exactly the same output ?

When #40 is implemented: class A extends B will be expressed as attribute of A whereas A --|> B will have the effect that there will be a separate relation object in the AST. Which is - in my opinion - correct. Even if the two notation are mostly used to express a is-a - relationship, the AST should reflect them differently. Following a few points why I think this is the correct thing to do:

• A formatter should be able to distinguish between A --|> B and class A extend B if needed.
• A --|> B is valid syntax in a component diagram, but component A extend B is not.
• Inheritance expressed using A --|> B can appear anywhere in the diagram (even before the class declaration). Keeping track of this state in the parser will make the parser very hard to maintain.

I would say, If you need --|> expressed as attribute on the class, this should be easy enough to do in your customer formatter. Putting this inside the parser will be lots of hassle for almost no gain.

[paduc]

Ok I get it ! No loss of information between the PlantUML input and the parser output.

You’re right, I’ll be handling the structure in my higher-level formatter.

[Enteee]

Thank you for your understanding @paduc .