Multilingual Wiki Documentation

You are currently using syntax.
In an attempt to improve PlantUML documentation...

Recent changes    Wiki Toc    View page history    Reorder page    Raw

Issue about Namespace and Package

Right now, the management of namespace and package may sound odd to users.

The real reason for this is some bad design decision made 10 years ago.

So here is our new proposal:

Merge the notion of package or namespace in PlantUML so that package or namespace will be synonymous and behave as in all regular programming languages.

  • and keep the actual behaviour of PlantUML.
  • I understand that I may have to add set separator none to some old class diagrams to let them work as today.
  • that won't break ascending compatibility.

You just have to click on one of the buttons to vote.

You have to add !pragma useNewPackage directive to your diagrams to activate the new package behaviour.
PlantUML Team
Welcome !
All contributions made here are public.
Thanks for helping us to improve PlantUML documentation !
Anonymous2020/01/03 09:23:25
BallAndSocket sould be supported.
Example: classA --(interfaceA) )-- classB
Anonymous2020/02/04 03:01:26
I'm missing something. I vote "Ok, implement this". However, doesn't that mean that I understand I may have to add "set separator .". I.e dot rather than none.

Beta testing this new feature

The pool shows that the vast majority of users are welcoming this change.

Since this change may have some impact on existing diagrams, we are going to move slowly on this new feature.

Note that many diagrams are impacted by this changes:

Other diagrams (including sequence diagrams and activity beta diagrams) are not impacted.

For starting, we need feedback from users to know if we still are on the right path. So last beta last beta plantuml.jar and the online server provides now a convenient way for testing this feature.

Those versions temporary implement both behaviours. You just have to add !pragma useNewPackage directive to activate the new package behaviour.

If you are already using PlantUML, it is very important that you test now this beta feature. Indeed, nothing has been definitively settled yet, so feedback will help us to find out any regressions.

This way, we will commit the right change for you. And when this beta feature will become the default behaviour, your diagrams will be safe.
PlantUML Team
You can use this chat to ask questions or to give any feedback on Beta testing this new feature
Anonymous2020/02/04 04:26:02
To me PlantUML is defined more by it's behavior than by the documentation. For some years I've used nested namespaces, i.e. namespace boxes are displayed inside namespace boxes. I understand that nested namespaces are supported by the UML-standard. However, I now fail to find a reference to the PlantUML documentation.

With this new beta I fail to display nested namespaces. (I tested on-line.) Commenting out "!pragma useNewPackage" makes the nested namespaces display as I have come to expect.

Please say that this new behavior is not by design.

/ poi
PlantUML Team
Thanks for your feedback.
Don't worry, this is still a beta, so we are going to enable nested namespaces back.
We will update this page when this will be ready.
Our goal here is really to point out every issue in the beta before releasing it officially.

Proposition of new behaviour

You can use !pragma useNewPackage to enable the new behaviour.

By default, the double colon :: will be interpreted by PlantUML as a separator.

Even if package are not explicitly nested, they will be printed as nested:

@startuml
!pragma useNewPackage
package net {
  class foo1
}

package net::entities {
  class foo2
}

package net::entities::sub {
  class foo3
}
@enduml

The following diagrams will give the same image:

@startuml
!pragma useNewPackage
package net {
  class foo1
 
  package entities {
    class foo2
    
    package sub {
      class foo3
    }
  }
}
@enduml

or

@startuml
!pragma useNewPackage
class net::foo1
class net::entities::foo2
class net::entities::sub::foo3
@enduml

Note that if you prefer, you could change package to namespace in those examples and you will get the same image.
PlantUML Team
You can use this chat to ask questions or to give any feedback on Proposition of new behaviour
Anonymous2019/12/14 14:13:36
I really don't like this change. I've just started using PlantUML and learning JSON. This seems to go against my intuition.
PlantUML Team
Could you detail your idea ? This change is unrelated to JSON, so I'm confused.
Anonymous2020/01/08 03:50:47
I like `set separator <character>`. I also like the containment syntax. That is important to be able to do cleanly and picking up that hint from the "package" declaration is a useful bit of syntax. --Frotz
Anonymous2020/01/09 10:18:45
What would be rendered if the top-level namespace / package is empty, except for another namespace? Will it still render as a box in a box, or will the name of the inner namespace be rendered as "net.entities"?
Anonymous2020/01/23 17:04:57
Looks good to me. Will a multi-char separator be support for C++ style namespaces?

E.g. class a::b::c
PlantUML Team
Yes: you'll have to declare :
set separator ::
Anonymous2020/01/26 17:12:04
This looks great. Currently, I have to nest package declaration, and to use indentation to remember the nesting level.
Anonymous2020/01/31 21:07:18
How does this work with spaces in names? For your third example, would it be net."with space" as foo? "with space" as net.foo?
PlantUML Team
Right now, it does not work with spaces in names. Is there a real need here ? We could enable quote for this, for example :
PlantUML Team
"net::a long name with space::foo"
Anonymous2020/02/04 05:24:39
I was a bit quick to write my message in the Beta testing section.

The syntax of the second example is what I'm using and what I call nested namespace, nested code and nested diagram.

However, I've have several PlantUML scripts with this nested syntax, which don't produce nested diagrams. They do produce nested diagrams with the version 1.2019.11. They contain more code elements, but nothing exotic.

I've not yet boiled it down to a minimal working example.

/ poi
Anonymous2020/02/04 05:27:37
Somewhere I saw the word "namespaceSeparator"

/ poi
Anonymous2020/02/04 21:32:57
quite good!
Anonymous2020/02/22 06:06:22
amazing

Separator change

Following first poll result, the double colon :: is the default separator. You can still vote so that we decide to confirm this.

What should be the default value for set separator directive:

  • This will help compatibility with the legacy behaviour of PlantUML.
  • This is consistent with Java/C#/C++ usage.
  • This is consistent with UML standard, and will also help compatibility with legacy PlantUML
  • You don't like the first choices.

As said, right now, in last beta, the double colon :: is the default separator. But you can change it using set separator directive.

@startuml
!pragma useNewPackage
package net {
  class foo1
}

package net::entities {
  class foo2
}

package net::entities::sub {
  class foo3
}
@enduml
class net::entities::sub::foo4

This separator feature would also be useful to retrieve the current behaviour, if you don't want the double colon :: to be interpreted as a separator.

For example, you could have:

@startuml
!pragma useNewPackage
set separator none
package net {
  class foo1
}

package net.entities {
  class foo2
}

package net.entities.sub {
  class foo3
}
@enduml

Here we fall back to the actual drawing of legacy PlantUML version.

Once again, you could change package to namespace in those examples and you will get the same images.

If using set separator none do not give you an acceptable result, please contact us.
PlantUML Team
You can use this chat to ask questions or to give any feedback on Separator change
Anonymous2019/12/15 09:52:43
what about a sequence of characters (e.g. '::') as a separator? I assume the new solution does include this.
PlantUML Team
With the new solution, you will be able to use "set separator ::" if you want to.
Anonymous2020/01/10 21:39:13
How about a no separator option to disable it? like "set separator off".
Anonymous2020/01/11 16:36:15
Isn't double colon a uml way to define nested packages?
I'd prefer to use "::" as a default separator, not "."
PlantUML Team
We've just opened a poll about the default separator.
Anonymous2020/02/04 05:35:38
I use '.', since Matlab uses '.'. However, that's not a big deal. I assume I can put "set separator ." in my config-file.

I noted that I must put "set separator ." in the beginning of the script, whereas I can put "skinparam name value" anywhere in the script.

/ poi
Anonymous2020/02/18 19:00:36
Hi guys, what ever the choice made in plantuml language, this should be very use full to be able to configure the rendering of this separator to . or :: as wanted by user =)

Nested namespaces

Setting separator to none disable the merge of nested packages. For example, compare :

@startuml
!pragma useNewPackage
namespace f1 {
  namespace f2 {
    class f3
  }
}
@enduml

and

@startuml
!pragma useNewPackage
set separator none
namespace f1 {
  namespace f2 {
    class f3
  }
}
@enduml

PlantUML Team
You can use this chat to ask questions or to give any feedback on Nested namespaces

Feedback

If during your tests you find some issues:

  • non-working diagram
  • regression with set separator none on your diagram

please give us some feedback. You can either:

PlantUML Team
You can use this chat to ask questions or to give any feedback on Feedback


Please report any bugs to plantuml@gmail.com or here.
This website is still in beta testing.