File Exchange

image thumbnail

m2uml

version 2.0.2 (1000 KB) by per isakson
m2uml generates UML class diagrams from m-code

56 Downloads

Updated 03 Oct 2020

View Version History

View License

This version of m2uml is a complete rewrite and it has some new features.

1. m2uml uses a semi-automated method to generate a class diagram for a user-selected set of classes. Reverse engineering of the Matlab code generates the entire inheritance tree structure. The class diagram is displayed in the Matlab web browser.

2. Tooltips: The classes, properties and methods show their H1-lines as tooltip.

3. Hyperlinks: Clicking the name of a class, propety or method opens the file in the Matlab editor and moves the cursor to the specified item. These hyperlinks makes m2uml a navigation tool.

4. The class box has (optionally) an extra compartment for TODO/FIXME annotations. These annotations have tooltips and hyperlinks.

5. New: Nested packages, see image in upper left corner of this page.

6. New: Custom documentation that is integrated in the Help Browser of Matlab.

7. New: Extensive possibilities to customise the class diagram, e.g display input and output arguments of methods

8. New: m2uml comes in a MATLAB toolbox file (mltbx). See the Matlab documentation regarding installing and uninstalling.

m2uml is based on PlantUML and Graphviz. m2uml retrieves information from the Matlab-code and outputs PlantUML-code. PlantUML uses GraphViz and draws the class diagram. To make a local installation of PlantUML see http://plantuml.com/starting.

However, experiments with m2uml don't require installations of PlantUML and Graphviz. PlantUML-code may be created locally and converted to a diagram in the cloud, e.g. at https://www.planttext.com/.

Cite As

per isakson (2020). m2uml (https://www.mathworks.com/matlabcentral/fileexchange/59722-m2uml), MATLAB Central File Exchange. Retrieved .

Comments and Ratings (38)

Nikita Balyschew

Hi Per,
after followig suggestions fro Alain I've gotten following error... Any suggestions?

Many thanks in advance!

Error using reshape
Size vector must have at least two elements.

Error in m2uml.GeneralizationScanner/create_generalization_array (line 44)
for super = reshape( clsmeta.SuperclassList, 1,[] )

Error in m2uml.GeneralizationScanner/add_generalizations_to_hierarchy_root (line 25)
, this.create_generalization_array( cls ) ];

Error in m2uml.create_PlantUML_script>create_PlantUML_script__ (line 181)
add_generalizations_to_hierarchy_root( m2uml.GeneralizationScanner(), pus )

Error in m2uml.create_PlantUML_script>create_PlantUML_script_ (line 124)
puml_code = create_PlantUML_script__( inv.Classes, options, inv.Arrows );

Error in m2uml.create_PlantUML_script (line 82)
puml_ffs = create_PlantUML_script_( inarg{:} );

Error in m2uml_v20_user_interface (line 80)
puml = m2uml.create_PlantUML_script ...

per isakson

Hi Alain,
Thank you for reporting! I'm not that well connected and don't reach Matlab from here. I'll look into the issues. /per

Alain

Hi Per,
The folder tmp4mltbx_ was installed properly...But apparently, it does not get added to the Matlab path by the toolbox installer... At least, it did not on my PC (tried with both R17b and R19b).
For testing, I just added the tmp4mltbx_ folder to the Matlab path manually, and the missing 'InputPreprocessor' error disappeared :-)
After adjusting a couple options in the factory_options.m script, as per your documentation, I was able to run your ThreeSmallExamplesScript.m, with one small caveat; it seems that the m2uml.depict_graphic_file(...) script (in Line 66 of ThreeSmallExamplesScript.m) is missing in the current toolbox; but replacing the call with m2uml.display_class_diagram() seems to work...

per isakson

@Alain, According to the Function tab, the class, InputPreprocessor, exists in the folder, tmp4mltbx_ (far down the list). Didn't that folder install properly?

Alain

Cannot get it to work. It is apparently missing a dependency (InputPreprocessor)

Joan Vazquez

KoosvdB

Great tool!
I also would like to use it for subpackages, but unfortunately that is not working as Max Philipp May already mentioned.
Workaround from alex_7 might work for a small code repository, but not for mine unfortunately.
I suppose my dependencies are too complex for this workaround.

I am looking forward to the new version that handles nested packages!

per isakson

The hyperlinks are back in version 1.2019.11

per isakson

There is a new problem with the hyperlinks. Matlab web() correctly displays svg-files created with PlantUML version 1.2018.09. Both the hyperlinks and the tooltips works well. However, with PlantUML version 1.2019.07 (and 1.2019.09) the hyper-links "are gone". The pointer doesn't turn into a hand and there is no visible response to left-clicking.

I don't know whether to blame the Matlab web() or PlantUML. I've reported to the PlantUML forum and received an answer that they will look into it.

Christian Tolks

Thank you for this tool. I struggled around with several toolboxes to create UML charts, but this is working fine and gives nice results.
Nevertheless, under Linux filespec2fqn.m throws an error at line 53 because "ca1" is only a scalar cell. I changed
line 51: ca1 = regexp( filespec, '\+', 'split', 'once' ); which is working for me.
I also did this in file filespec2constructor_name.m in line 30.
Second, as Mike Whincup mentioned hyperlink behavior has changed. I also found this issue in
TodoFixme.m, so I changed to
line 88: format_spec = '%s%s {field} %c%s [[[ %s {%s} ]]]';

per isakson

Thank you for volunteering to provide some tests/requirements. I think MWEs of tiny class definition files together with description in plain English would be useful. (I'm still using my own testing framework, which predates the Matlab framework.)

I have no repository. However, I have this question at Matlab Answers, "What's required of an automatic UML Class Diagrams tool to be useful?", https://se.mathworks.com/matlabcentral/answers/308970-what-s-required-of-an-automatic-uml-class-diagrams-tool-to-be-useful
It's straightforward to create an answer and attach files, e.g zip-files, to that answer.

Lockywolf

Sorry for taking so much to respond. My workload in unreasonable.

I am not sure I can publish my working code (or, rather, I am sure I cannot), but I'd happily provide you with tests, as I get my hands to writing them.

Do you have some http://gitlab.com or http://github.com repository?

Anyway, thanks for your work.

per isakson

Thank you for the question.
I'm making a total rewrite. The old code was too frustrating to work with.
"very heavy matlab features" - Matlab is a moving target. The new code handles nested packages and multiple inheritance. The code is working. However, it needs documentation and could do with more tests.
May I ask for help with testing? Please upload small test cases on "heavy features" to the question, "What's required of an automatic UML Class Diagrams tool to be useful?", in MATLAB Answers.
I'll look into private directories.

Lockywolf

Hi! Are you planning to continue the development of this wonderful piece of software?

I really need some visualization tool for my code, but I use some very heavy matlab features, such as private directories, multiple inheritance and such.

alex_7

Hi @Max Philipp May,
my solution to the subpackage problem is following:
% Copy Libraries in new folder
status = copyfile('+Libraries','Libraries');
libraries = dir(fullfile('Libraries','+*'));
for iLibrary = 1 : length(libraries)
mFiles = dir(fullfile('Libraries', libraries(iLibrary).name, '*.m'));
for iFile = 1 : length(mFiles)
filename = fullfile('Libraries', libraries(iLibrary).name, mFiles(iFile).name);
text = fileread(filename);
text = strrep(text,'Libraries.', '');
fid = fopen(filename, 'w');

% Write the new text
fwrite(fid, text);
fclose(fid);
end
end

1)It will copy the contents of the super package in a new folder.
2)It will go through the new folder and remove the namespace of the super package
Then the m2uml works just fine :)

Sean de Wolski

Hi Per,

It's having trouble with a "private" folder in an @Class definition folder containing functions used by the class. "Undefined function x"

per isakson

@Damiano Fraizzoli

Thanks for your comment and suggestion. I've been working of a function, RelationshipSniffer, which is intended to do exactly what you suggest. It's doable, but I face some problems with "depend on interface, not concrete implementation". I will upload.

per isakson

@Mike Whincup

Thank you for your comments and debugging. The hyperlink feature was brand new when I included them in m2uml and this is the first (as far as can remember) time I'm bitten by changes of the syntax of PlantUml.

Mike Whincup

I note that when a property SetAccess is Immutable, its 'visibility' is set to Private (which is the best fit), but when a property is Constant, the 'visibility' is not set to private. For consistency of presentation I have applied the following hack to the beginning of the visibility_ function and the associated property-related calls...

function [vis,num] = visibility_ ( access_list , varargin ) %

if nargin > 1
cellConst = varargin{1};
for jj = 1 : length( access_list )
if cellConst{jj}
access_list{jj} = 'immutable';
end
end
end

...

Mike Whincup

Righto, I've found the solution for the link incompatibilities with PlantUML.
They've changes the syntax for hyperlinks in the latest versions as described here: http://plantuml.com/link
Make the following changes to fix this...

Property.m Line 100:
format_spec = '%s%s {field} %c%s [[[ %s {%s} ]]]';

Operation.m Line 87:
str = sprintf( '%s%s %c%s() [[[ %s {%s} ]]]' ...

Mike Whincup

Have you considered pushing your code to GitHub? I'm sure you would get more developers helping you.

Mike Whincup

Hi! Thanks for all your hard work. I'm sure there are many, many people hoping to improve their documentation and code through this.
Unfortunately, I have a problem with the hyperlinks.
For example, when I try your first example, I get the following output:
@startuml
title <b>BN_Singleton</b>
class Singleton << (A,#E6FFE6) >> [[matlab:matlab.desktop.editor.openDocument('C:\Users\Mike\Documents\Git\singleton\Singleton.m'){SINGLETON Abstract Class for Singleton OOP Design Pattern}]] {
{field} -singletonData [[ {No tooltip} ]]
____
+Singleton() [[ matlab:matlab.desktop.editor.openAndGoToFunction('C:\Users\Mike\Documents\Git\singleton\Singleton.m','Singleton') {No H1-line} ]]
+setSingletonData() [[ matlab:matlab.desktop.editor.openAndGoToFunction('C:\Users\Mike\Documents\Git\singleton\Singleton.m','setSingletonData') {No H1-line} ]]
+getSingletonData() [[ matlab:matlab.desktop.editor.openAndGoToFunction('C:\Users\Mike\Documents\Git\singleton\Singleton.m','getSingletonData') {No H1-line} ]]
}
class SingletonImpl << (S,#E6FFE6) >> [[matlab:matlab.desktop.editor.openDocument('C:\Users\Mike\Documents\Git\singleton\SingletonImpl.m'){SINGLETONIMPL Concrete Implementation of Singleton OOP Design Pattern}]] {
{field} +myData [[ {No tooltip} ]]
____
-SingletonImpl() [[ matlab:matlab.desktop.editor.openAndGoToFunction('C:\Users\Mike\Documents\Git\singleton\SingletonImpl.m','SingletonImpl') {Initialise your custom properties.} ]]
+instance() [[ matlab:matlab.desktop.editor.openAndGoToFunction('C:\Users\Mike\Documents\Git\singleton\SingletonImpl.m','instance') {No H1-line} ]]
+myOperation() [[ matlab:matlab.desktop.editor.openAndGoToFunction('C:\Users\Mike\Documents\Git\singleton\SingletonImpl.m','myOperation') {Just assign the input value to singletonData. See Singleton} ]]
}
SingletonImpl -up-|> Singleton
@enduml

This exposes the URLs longhand in the icons, whether I use the online PlantText or whether I use a local plantuml.jar file.
I don't imagine this is how you wanted it. Can you please help?

Damiano Fraizzoli

Hi! Thankyou very much for this tool. I was wondering if there is a way of getting associations automatically with your code (the idea would to cancel the unnecensary ones in a second moment.
Thanks

per isakson

@Max Philipp May, thank you for reporting.

No, you are not doing anything wrong. m2uml doesn't handle packages in packages. And I don't think there is a simple fix. I'll look into it, but ... .

Max Philipp May

Hi, maybe it's my fault, but if I try to generate a diagram for class which is contained in a sub package of a package, i.e., '...\+core\+data\exampleClass' I got an error in line 35 of 'PlantUmlAdapter.m'. So the error occurs, e.g., for '[~] = m2uml.run('Example',{'core.data.exampleClass'},{});'. Any suggestions what I've done wrong?

per isakson

An updated version of get_H1_line.m, which returns an appropriate string when the method is defined in a superclass, is attached to a comment to the question, https://uk.mathworks.com/matlabcentral/answers/308970-what-s-required-of-an-automatic-uml-class-diagrams-tool-to-be-useful

per isakson

@Andrew Joslin, thank you for your comment.

I'm a bit puzzled by your proposal. Maybe, I'm missing something.

Yes, an error is thrown for H1=get_H1_line(filespec,fnc-name) if fnc_name doesn't exist in filespec (by design). However, there are two exceptions 1) implicit constructor and 2) the method is defined in a separate file in a class-folder.

Question: Did you get this error when you executed m2uml or get_H1_line in isolation? (My intention is that m2uml shall only call get_H1_line with fnc_name defined in filespec. If the error is thrown when called from m2uml the problem is somewhere else in the code. I have never seen the error when running m2uml.)

The reason I made get_H1_line is speed (compared to help). I hesitate to involve superclasses in this function. And want to honor single responsibility.

I find UML tricky. I use UML Distilled by Fowler (and the Internet). Your comment suggests that a method, which is defined in a superclass, shall be displayed in both the superclass and the subclass. I understand that a method shall be displayed in both the superclass and the subclass only if its overloaded in the subclass. (That makes the diagram more compact, which is good.) However, I haven't seen that written down explicitly.

I have a considerable back-log and plan to submit a new version.

I would appreciate more details on the case which caused the error. If you want to attach files and screen-clips make it an answer to https://uk.mathworks.com/matlabcentral/answers/308970-what-s-required-of-an-automatic-uml-class-diagrams-tool-to-be-useful

Andrew Joslin

Excellent tool, thanks for submitting!

I might have found a bug in get_H1_line.m that you might want to know about (user error is possible).
For me, it throws an error when the method in the "fnc_name" variable is inherited from a superclass. In this instance, the 2 cases defined in the code ("1. Implicit contructor of class", and "2. Inherited from superclass") don't seem to cover the 3rd case where the method is inherited from the superclass.

Setting variable "H1" to "['Inherited from ' <comma-separated list of superclasses which have this method>]" would fix the problem, though I don't think it would ever result in more than one item in the list of superclasses.

Hope this helps.

Peter Németh

per isakson

It's by design. The reason was that the width of the diagram explodes.

function [out1,out2]=method(obj,inp1,inp2)

Doesn't the same apply to the output parameters? And Matlab allows more than one. What format should be used for the method line? I want the method name to the left of the parameter names.

The solution is to let the user decide by choosing among options.

Zoltán Csáti

Does not recognise method input parameters. E.g.

function method(obj, inp1, inp2)
% Implementation
end

results in method() in the diagram.

per isakson

Regarding "Interface and Interface2D". I stumbled into something similar. In my case the reason was that the constructor of the class, "Interface2D", by mistake was named "Interface". That raises the question whether the class diagram should indicate the "color" of the code analyzer.

Regarding matlab.mixin.Copyable. Under the hood of Matlab has a complex (and growing?) structure of nested packages. And their names are often long. I agree, this can and shall not be displayed in the diagrams. However, how much information can be and is desirable to communicated with one letter? KISS.

Zoltán Csáti

matlab.mixin.Copyable is not inhereted properly (see the screenshot below). In my opinion, it should be handled just as the handle class (i.e. not display in the class diagram) as matlab.mixin.Copyable only serves for deep copying of handle classes.

Here is a screenshot: http://imgur.com/a/MdeJD

Zoltán Csáti

@per isakson
which('Interface') returns only the class Interface but not the class Interface2D.

per isakson

@Zoltán Csáti, thank you for your comment.

which('Interface') shouldn't return both Interface and Interface2D - or do I miss something. Does that really happen?

The rationale behind which(file_name,'-all') is to avoid that Matlab files shadows user defined files. Furthermore, I want to assert that the user doesn't have modules with identical names on the search path. However, this function is the wrong place to do that. I'll do something to it, but please modify your copy in the meantime.

The aggregation/composition relationships have caused me problems. 1) There is no "easy" way to extract that information from the m-code or the meta-object. 2) I might be missing some nuances of the UML-standard, but I don't care that much. 3) Matlab isn't a pure OO-language; I need to include functions in the diagram. (For example, I often implement factories with function.)

Anyhow, my highest priority is to show "all" dependencies.

Suggestions are welcome!

Zoltán Csáti

Superb package. I would have one suggestion though: when classes begin with the same name (e.g. Interface and Interface2D in my case), the assertion on line 14 of has_explicit_constructor.m fails. The quick fix of using filespec{1} = which( file_name ); instead of filespec = which ( file_name, 'all' ); solves this issue.
Is it possible to somehow extract the aggregation/composition relationships?

per isakson

I write "Next read "m2uml 1.1 - Hyper-links and tool-tips", but there is no corresponding light-bulb-link in the right column. I cannot figure out why.

The zip-file contains html\m2uml_v11_hyperlinks_tooltips_publish.html,
which displays fine in my local browser.

Vandana Rajan

MATLAB Release Compatibility
Created with R2018b
Compatible with R2017b and later releases
Platform Compatibility
Windows macOS Linux
Acknowledgements

Inspired by: youemel

Community Treasure Hunt

Find the treasures in MATLAB Central and discover how the community can help you!

Start Hunting!