Generate diagrams for your Prolog module applications

Resources
1

As some of you are aware, Logtalk diagrams tool also supports generating diagrams for Prolog module applications. Work is under way on a new version of the tool, which you can preview using the current Logtalk git version. Feedback most welcome.

To illustrate what the tool is capable of, we can start with a simple Prolog module open source application from Anne, available at:

https://github.com/SWI-Prolog-Education/talespin-annie

This application is contained in a single directory. To generate diagrams for it, after cloning the repository, we can use the queries:

$ cd ~/talespin-annie
$ swilgt
...

?- {diagrams(loader)}.
...
true.

?- [run].
true.

?- working_directory(TaleSpin,TaleSpin),
   file_search_path(swi, SWIHome),
   atom_concat(SWIHome, '/library', Library),
   git_hash(Hash, []),
   atomic_list_concat(['https://github.com/SWI-Prolog-Education/talespin-annie/tree/',Hash,'/'], Git),
   diagrams::directory(
       talespin,
       '.',
       [
           zoom(true),
           path_url_prefixes(TaleSpin, Git, ''),
           path_url_prefixes(Library, 'https://github.com/SWI-Prolog/swipl-devel/tree/master/library/', ''),
           omit_path_prefixes([TaleSpin, Library]),
           title('TaleSpin application'),
           layout(top_to_bottom)
        ]
   ).

?- ^D
% halt

$ lgt2svg
...

It looks a bit complex but that’s because we’re generating diagrams that link to both the application and the SWI-Prolog GitHub repositories for the latest commit. After the conversion of the diagrams to SVG, we get:

  1. File loading and file dependency diagrams:

https://logtalk.org/diagrams/talespin/talespin_file_load_diagram.svg
https://logtalk.org/diagrams/talespin/talespin_file_dependency_diagram.svg

These diagrams show what is explicitly loaded versus the actual file dependencies. Clicking on the grey area, which represents a directory, and clicking on a node, representing a file, links to those elements in the GitHub repository tree.

  1. Entity diagrams:

https://logtalk.org/diagrams/talespin/talespin_entity_diagram.svg

This diagram shows the actual application entities, modules in this case. Besides navigating to the directory and files, you can also click on the zoom icons to access the predicate cross-referencing diagrams for each of the modules. In the cross-referencing diagrams, you can click a predicate node to go to the predicate definition on GiutHub or click on the calls edge labels to go to the source file line where the call takes place.

An alternative view provides cross-referencing information between entities:

https://logtalk.org/diagrams/talespin/talespin_xref_diagram.svg

These (and other) diagrams are specially useful for complex applications. Consider as an example ClioPatria:

https://github.com/ClioPatria/ClioPatria

In this case, we generate the diagrams using the queries:

?- [cliopatria].
% Updating GIT version stamps in the background.
true.

?- working_directory(ClioPatria,ClioPatria,
   file_search_path(swi, SWIHome),
   atom_concat(SWIHome, '/library', Library),
   git_hash(Hash, []),
   atomic_list_concat(['https://github.com/ClioPatria/ClioPatria/tree/',Hash,'/'], Git),
   diagrams::rdirectory(
       cliopatria,
       '.',
       [
           zoom(true),
           path_url_prefixes(ClioPatria, Git, ''),
           path_url_prefixes(Library, 'https://github.com/SWI-Prolog/swipl-devel/tree/master/library/', ''),
           omit_path_prefixes([ClioPatria, Library]),
           exclude_directories([web, test, scripts, w3c, etc, rdf, 'Windows', 'Java']),
           layout(top_to_bottom)
       ]
   ).

As the ClioPatria application is distributed in several directories, we use here the rdirectory/3 predicate and also exclude directories that don’t contain Prolog code. A call to the lgt2svg script and we’re ready to browse the diagrams. Let’s start with the directory diagrams:

https://logtalk.org/diagrams/cliopatria/cliopatria_directory_load_diagram.svg
https://logtalk.org/diagrams/cliopatria/cliopatria_directory_dependency_diagram.svg

In these diagrams, the zoom icon takes you to the file loading and file dependency diagrams for the chosen directory.

The entity diagram is, as you expect, a big one:

https://logtalk.org/diagrams/cliopatria/cliopatria_entity_diagram.svg

As before, the zoom icon leads to the predicate cross-referencing diagrams for the chosen module. There’s also a module cross-referencing diagram:

https://logtalk.org/diagrams/cliopatria/cliopatria_xref_diagram.svg

For more details on the diagrams tool, see:

https://logtalk.org/tools.html#diagrams

For a full list of the diagram customization options see:

https://github.com/LogtalkDotOrg/logtalk3/blob/5c58a886c453f1cabc40ba83da182e62c2e73b05/tools/diagrams/NOTES.md

The support for generating Prolog module application diagrams is a subset of the tool features for Logtalk applications (which include e.g. generating diagrams with links to API documentation). Still, I hope you find this tool useful if you’re only using modules in your applications.

Cheers,
Paulo

2

P.S. Updated all linked diagrams after user feedback. Improved, in particular, the directory and entity diagrams and implemented a new option to control output of nodes for external resources.