Regression: double include of a file (1.2018.10 -> 1.2018.11/12)

Question

Hi,

It apears to me that we currently have a regression bug. This issue came up some versions ago already and was solved in http://forum.plantuml.net/3389/error-generating-when-same-file-included-different-diagram.

The behavior changed how double includes are treated between version 1.2018.10 and 1.2018.11. In version 10 the second include of the same file was simply ignored without error and the image is generated. Starting with version 11 we have a error message that this file was already included.

Test setup

include.iuml

@startuml
!define createComponent(X) component "X" as X##comp
@enduml

test.puml

@startuml
!include include.iuml
createComponent(1)
'accidentally include the file the second time which needs to be ignored
!include include.iuml
createComponent(2)

1comp --> 2comp
@enduml

Can somebody confirm that?

BR,

Michael

Comments

I get the message with 1.2018.12beta16 as well I didn't backtrack.

@plantuml
I don't agree with the fact that it is not possible to include a file twice. I think the user has to decide what to do, it might be possible that he has code for the first time a routine is called and for a second time the file is included (e.g. by means of if constructs).
It is possible to have twice a define with the same name name, the second occurrence silently overrules the first occurrence.
I would opt more for a "C-like" approach regarding include files and defines.

Answer 1

@mgrol
Thanks for the report and sorry about that.
This is fixed in last beta http://beta.plantuml.net/plantuml.jar

@albert

I don't agree with the fact that it is not possible to include a file twice.

Yes, this was a bad decision taken a long time ago.

Unfortunately, it's difficult to change the behaviour of !include because it would impact many existing PlantUML diagrams.

As workaround, you can use !include_many that has the same behaviour as #include C-version.

Maybe we will introduce a new !include_once feature that will act like the actual !include implementation.
Then, in some hypothetical future, we could switch the actual behaviour of !include from !include_once to !include_many
But this may be confusing for users.
What do you think about it ?

Comments

@plantuml
I can live with that approach.
I completely overlooked the !include_many directive. In general I find it also more intuitive to explicitely opt-out multiple includes from a specific file rather that using this as a default behavior.

I think it is rather a general decision to allow or not allow duplicate includes, as you mentioned already. Just my two cents. If I think about that library functionality, which you added to plantuml some versions ago, multiple includes are necessary. If you want to write files that depend on each other but they need to be self-sustained, it is very likely that they include the same file more than once.
Long story short. Having !include_many and a new !include_once would be a handy feature.

BR,
Michael

---

Assuming that foo.iuml contains:

@startuml
alice -> bob : ping
@enduml

With last beta http://beta.plantuml.net/plantuml.jar you can have :

@startuml
!include_once foo.iuml
!include_once foo.iuml
alice -> bob : one ping line
@enduml

@startuml
!include_many foo.iuml
!include_many foo.iuml
alice -> bob : two ping lines
@enduml

@startuml
!default_include many
!include foo.iuml
!include foo.iuml
alice -> bob : two ping lines
@enduml

@startuml
!default_include once
!include foo.iuml
!include foo.iuml
alice -> bob : one ping line
@enduml

---

I agree that out of consistency it is hard to change some, unfortunately,  bad behavior from the past. The '!default_include many' is a good compromise. I looked at the latest manual I could find (as mentioned at http://wiki.plantuml.net/site/index) but didn't find anything in there about this behavior.
I stressed this point a few times earlier but an update of the manual is definitely required with all the possible directives etc. (I know time is limited and fixing bugs has a higher priority).

---

Yes, documentation is really out-of-date.
So please update http://wiki.plantuml.net/site/preprocessing (write access is free!) with anything you have noticed. We are currently focusing on code and let users update the documentation :-)