drmarkusvoss / pumla Goto Github PK

Is your feature request related to a problem? Please describe.
Currently the parsing in "cmd_utils.py" is very hacky, using string operations like "split" and "strip". This is not very sustainable and extendable. Currently only the UML aspect of PlantUML is covered by pumla for re-usability, so everything between "@startuml" and "@enduml", but from principle it could also be extended to gannt charts etc, to allow re-usability for also other domain models covered by PlantUML. In order to support C4model, also an extension to the parsing is needed very likely.

Describe the solution you'd like
parsing with e.g. regex would make it much more robust, maintainable and extendable.

Describe the bug
Title says it all... with "pip install ." the file created with "pumla init" is basically corrupt, in consequence you won't get any working diagrams...

Desktop (please complete the following information):

• pumla version: 0.8.3

Describe the bug
The idea of the PUMLARUAInternals macro was that there is no more need to encapsulate the internals explicitly with the global variable to turn display of the internals on/off. But if in the internals other re-usable assets are shown, then turning it off prevents these elements to be shown at all on a diagram (depending on their sequence of placement), as in the finalize step the encapsulating "internals rectangle" box is removed and concluding also the inside elements are removed.

To Reproduce
See the internals elements of the tempSys.puml example. In the "allElements.puml" diagram, without the encapsulation of the globals, you do not see e.g. elements "displayTemp" etc. on the diagram if the global variable to show internals is set too false.

Expected behavior
I do not want to have extra " !if ($PUMVarShowBodyInternals)" around the internals, otherwise the PUMLARUAInternals is not a benefit, so expected behavior is that not showing internal elements of tempSys, which is e.g. displayTemp, that when using "PUMLAPutAllElements()" and at the same time "!$PUMVarShowBodyInternals = %false()", then it does not have the side-effect to not show displayTemp at all, only not on the inside. With the extra " !if ($PUMVarShowBodyInternals)" around the internals it works, but it is not nice.

Screenshots
If applicable, add screenshots to help explain your problem.

Desktop (please complete the following information):

• pumla version 0.8.2

Additional context
Add maybe extra logic into the finalize? Or rethink the finalize-principle? Or have another loop checking that really all elements are there with global variables per element?

Is your feature request related to a problem? Please describe.
The current cheat sheets do not contain the tagged values. When dealing with variance, you want to have an overview on which tagged values the elements have.

Describe the solution you'd like
Adding the tagged values to the existing cheat sheets would overload them. So an additional one for the tagged values would be good. Or better 3 additional ones: for elements, relations and connections.

Is your feature request related to a problem? Please describe.
Most users are probably used to running a new tool with --help to get started. pumla only reports version and author in this case.

Describe the solution you'd like
I suggest to use a common library like argparse to do the argument parsing. It will also generate the necessary code for the --help argument for you. Using the library, will probably also help readability of the arg-parsing code in pumla and you might be able to simply move some of the documentation from the user guide directly into the source code. Hence keeping it all cohesive and consistent.

Describe alternatives you've considered
None

Additional context

Describe the bug
when the update on the WeatherStation example is called, the parent for the instances w1..w4 is not found anymore.
That is due to the wrong parsing of "FullyInstantiableClass". Reason is, it was a typo-fix, before it was called "FullyInstantiatableClass". The regexparser pattern for that did not get corrected when the correct spelling in the API and examples was introduced.

Desktop (please complete the following information):

• pumla version: 0.9.1

Is your feature request related to a problem? Please describe.
An editor plugin could give quick help on macro usage, generate unique aliases and do auto-completion for the macros.
also support for the command line tool might be supported?

$PUMVarShowBodyInternals does not seem to consider PUMLAParent as suggested in the Users Guide.

I have a system and a subsystem, and I would like to create a system architecture diagram which shows the subsystem nested within the system, by defining 'PUMLAPARENT: system in the subsystem .puml file.

system.puml

'PUMLAMR
'PUMLAPARENT: -
@startuml
!include pumla_macros.puml
!include modelrepo_json.puml

PUMLAReUsableAsset("System", system , component)

@enduml

subsystem.puml

'PUMLAMR
'PUMLAPARENT: system

@startuml
!include pumla_macros.puml
!include modelrepo_json.puml

PUMLAReUsableAsset("Subsystem", subsystem , component)
PUMLAReUsableAssetFinalize()

@enduml

systemArchitecture.puml

@startuml
!include pumla_macros.puml
!include modelrepo_json.puml
!$PUMVarShowBodyInternals = %true()

PUMLAPutElement(system)

@enduml

However, the systemArchitecture diagram shows only the system component. Is this not how this functionality was intended to be used?

Full disclosure that I am trying to implement this on Windows 10 with WSL installed. I have had to make two minor changes to the python scripts (changing forward slashes to back slashes) and all other functions seem to be stable.

Describe the bug
see caption

Desktop (please complete the following information):

• pumla version 0.9.0

Additional context
Add any other context about the problem here.

Is your feature request related to a problem? Please describe.
Currently the model elements provided by the C4-PlantUML extension are not supported to be re-used.

Describe the solution you'd like
Support for re-use of the C4-PlantUML extension model elements.

Describe the bug
When the example ReUsableAsset
PUMLAReUsableAsset("Temperature Sensor B (dC)", ...)
is parsed, the parser cannot deal with the brackets in the name "(dC)". It writes the name wrong into the modelrepo_json.puml database, like this:
{"name": "Temperature Sensor B (dC", "alias": "tempSensorBdC" ...

Desktop (please complete the following information):

• on Raspi with Python 3.7 and Mac with Python 3.8.2
• pumla version: v0.8.3

Is your feature request related to a problem? Please describe.
Currently the user has to define unique aliases (elements) and IDs (connections/relations) for the re-usable assets. If you work with several teams there might come up clashes by coincidence.

Describe the solution you'd like
4 ideas:
A: have macros that automatically create unique IDs (checking the modelrepo for existing IDs to avoid clashes)
B: have the command line pumla make a unique ID proposal
C: outsource this to the editor, e.g. a pumla editor plugin (e.g. for pycharm and VS Code)
D: only have the "pumla update" check for alias/ID clashes and report errors

Is your feature request related to a problem? Please describe.
Currently pumla does not support the rendering of diagrams. You have to do it manually.

Describe the solution you'd like
It would be cool if it is possible to call something like
pumla render
which would make pumla call PlantUML on all pumla diagrams (of the input folder) and create PNGs in the output folder. Of course, in order to do so, pumla must know the installation place of the PlantUML library or it must be on the global path.

Is your feature request related to a problem? Please describe.
The current markdown files for

• Readme
• Examples
• Modelling Guideline
• User's Guide
  do not have a table of contents, so you must scroll and search a lot.

A table of content at the beginning would help.

Is your feature request related to a problem? Please describe.
use Hyperlinks on elements so that a architecture documentation comes out that can be clicked onto the elements and
leads you to that element description. That makes sense if you also create the markdowns (e.g. according to Arc42).

Describe the bug
see description

Desktop (please complete the following information):

• pumla version 0.9.0

Additional context
Add any other context about the problem here.

Is your feature request related to a problem? Please describe.
A hierarchical tree view of cheat sheet contents would be nice to see the parent/child dependencies.

Is your feature request related to a problem? Please describe.
to solve the bug that the footer cannot be configured to vanish in the project-specific config file (issue #31), the global config now only acts as a template. it would be good to have it working as a default "fallback" and have some check with error message or warning that the default is used and the project is not setup correctly...

Is your feature request related to a problem? Please describe.
Currently interfaces are just named bobbles. There is no "type" information behind (in a diagram you can of course model it with PlantUML), but incompatible interfaces could be connected.

Describe the solution you'd like
An interface type repository could host the interface types, that could be used as types of interface-ports (bobbles and half-circles). If they use the same type, they are compatible. The data would need to be in the model-repo, then an compatibility check could be done on whether the same type is behind the port. You could activate type checks, that could lead to an "error" or "warning" note instead of connecting. Connection only if valid.

This adds more semantics to the models. But especially if you want to have detailed information on your ports and want to be able to expose it easily in a re-usable way, than this makes sense.

Describe alternatives you've considered
Alternative is not considering types on ports. Keeps the tool smaller. But I think it is a useful feature, and I don't see how it could be done with plain PlantUML.

Additional context
Interfaces could be described with classes and then have a specially named relation to the ports.

Describe the bug
Argument order in User's Guide:
PUMLARelation(startalias : string, endalias : string, "reltype" : string, "reltxt" : string (optional), "relid" : string (optional))

Real argument order (example):
PUMLARelation(tempSensorBdC, "..>", tempSensorB, "use", "tempSensorBdCRel#1")

Desktop (please complete the following information):

• pumla version v0.8.5

Is your feature request related to a problem? Please describe.
The integration and interaction of the tool with other tools in other programming languages is not so easy. Not possible to access the contents of the model repository (other than parsing it).

Describe the solution you'd like
extension of the pumla CLI to have commands like:
pumla getjson elements
pumla getjson relations
pumla getjson connections
pumla getjson element <element_alias>
The result should be a JSON syntax output to the command line with the related content of the model repository.

Implementation hints
should be really easy to implement as the output is basically already generated for the modelrepo_json.pum. Now just the contents need to be provided separately and not in "PlantUML Preprocessor-JSON syntax", but plain JSON, so it can be written to a file and parsed as correct JSON file.

Is your feature request related to a problem? Please describe.
So far, I used the file "ideas_storage.puml", a PlantUML diagram with ideas described in notes, as idea backlog.

Describe the solution you'd like
Now, since with pumla v0.8 I opened up the issues tracker, the ideas that are left open from the ideas storage should be transferred to issues and the ideas storage file should be deleted.

Is your feature request related to a problem? Please describe.
Similar as the "InjectChildElements". When modeling the standard example for the C4
model, the need for this arose, as I also want to model re-usable relations that are
related to the embedding context, like here:
PUMLAC4System_Boundary(techtribes, "techtribes.js") { PUMLAInjectChildElements(techtribes) PUMLAInjectChildRelations(techtribes) }

Describe the solution you'd like
That means, not only the macro must be added, but also relations need to have a "parent" attribute to be dealt with.

Describe alternatives you've considered
Not providing it would be a solution, but with what reasoning can't I have child relations, when I can have child elements?

Describe the bug
If you try to use PUMLAPutRelationsForElement with C4REL, it generate a line like

element1 C4Rel element2 : action

And that's break the plantuml generation.

Is your feature request related to a problem? Please describe.
currently, you can use a Plugin in an IDE for rendering the PlantUML images or dealing by hand with the installation and triggering of PlantUML to render the pumla diagrams.

Describe the solution you'd like
it would be great if there is download (of compatible version) and installation (defined directory) support by pumla to install the PlantUML library in a way that it can be easily used (other feature request) and triggered directly by pumla.

Describe the solution you'd like
Currently the blacklist files do not allow for comments. In bigger projects with more developers it might be very useful to explain why certain folders of a project shall not be considered to be searched for pumla files.
Therefore, the request is to enhance the pumla_blacklist.txt file parsing to allow comments that are ignored from functional point of view.

Is your feature request related to a problem? Please describe.
A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]

Describe the solution you'd like
The workflow that will be created with #9 addresses the usage of pumla with an existing repository where pumla artifacts already exist. Another workflow would be needed to setup a project from scratch with pumla. There also the init would need to be called, but additionally also e.g. the pumla_blacklist.txt and pumla_prj_cfg.puml can be setup as first version.
The new "pumla_macros.puml" that will then be stored in the project root folder, will also include "pumla_prj_cfg.puml" from the project repo. The current "pumla_global_cfg.puml" could then be used as template, the file itself will not anymore be included by other ".puml" files.

Additional context
This shall only be implemented after issue #9 is solved, because the concepts of these two need to be aligned.

If we follow the python packaging guide, then pumla can be easily installed using pip and distributed as a wheel. The latter allows to upload it to pypi and simply install it by pip install pumla.

Moreover, this would make pumla feel look and feel like other python packages easing contributions.

Is your feature request related to a problem? Please describe.
if a file is marked with "'PUMLAMR", then it can be assumed that there would be at least one re-usable item in the file. Furthermore, for the macros, pumla update can make checks if the right number of arguments is given. Also the "duplicate alias" can be checked, and "pumla update" can throw errors on all of these "unmet expectations".

Describe the solution you'd like
"pumla update" doing more checks on the files for correct macro usage, furthermore checks for the rules in the modeling guideline, where possible.

Is your feature request related to a problem? Please describe.
When you use pumla for different projects on your computer, these may be in very different locations of your computers directory structure. When you just have one installation of pumla, the include paths of your projects may look very long. Furthermore, projects that are stored within a VCS like git, can be checked out at different locations and on each computer where it gets checked out pumla may be installed at a different location. That would end up in patching all pumla files after e.g. a git clone.

Describe the solution you'd like
Create an initialization routine like e.g. catkin_init or something like that. So a call like
pumla init
called in the root directory of your project using pumla should lead to a "jumper-file" called "pumla_macros.puml" that includes the "pumla_macros_main.puml" that is stored in the pumla source/installation folder. The new "pumla_macros.puml" would then include the "pumla_macros_main.puml" by absolute or relative path, as the concrete locations are well known when the "init" is called. The generated "pumla_macros.puml" should not be checked in into the VCS, but everytime at checkout/clone be generated first (git hook?) at the same root location.

Describe alternatives you've considered
Alternative is that all projects do not include the pumla_macros.puml from a local pumla installation on the hard disk, but always refer to the original raw files on GitHub, e.g. including like that:

!include https://raw.githubusercontent.com/DrMarkusVoss/pumla/main/pumla_macros.puml

But then the user or the using company is pretty dependent on an external source.

Additional context
Add any other context or screenshots about the feature request here.