Multilingual Wiki Documentation

You are currently using syntax.
In an attempt to improve PlantUML documentation...
Please do not use this website for your own diagrams.
You can click here and use the online server here for your own documentation.

Wiki Toc    Recent changes    View page history    Add new chapter    Reorder page    Raw

Issue about 命名空间 and 包

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.

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.

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.

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.

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.

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

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:

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