---

This file is part of Logtalk https://logtalk.org/ SPDX-FileCopyrightText: 1998-2024 Paulo Moura <pmoura@logtalk.org> SPDX-License-Identifier: Apache-2.0

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

% start by loading the tool:

| ?- logtalk_load(diagrams(loader)). ...

% check the default options used when generating an entity diagram:

| ?- entity_diagram(dot)::default_options(DefaultOptions). DefaultOptions = ... yes

% load an example for testing but be sure that the "source_data" flag is on:

| ?- set_logtalk_flag(source_data, on), logtalk_load(points(loader)). ...

% generating an entity diagram for a source file using default options:

| ?- entity_diagram(dot)::file(points). yes

% generating a predicate call cross-referencing diagram for a source file % using default options:

| ?- xref_diagram(dot)::file(points). yes

% we can also generate a predicate call cross-referencing diagram for a % single entity showing its internal dependencies:

| ?- xref_diagram(dot)::entity(point). yes

% same but with predicate node local file system URLs:

| ?- xref_diagram(dot)::entity(point, [url_prefixes('','')]). yes

% load another example for testing:

| ?- logtalk_load(searching(loader)). ...

% generating a file loading dependencies diagram for all source files in a % library using default options and the default graph language (DOT):

| ?- file_load_diagram::library(searching). yes

% load all the tools for testing:

| ?- set_logtalk_flag(source_data, on), logtalk_load([library(all_loader), tools(loader), ports(loader), wrapper(loader), lgtunit(tap_output), lgtunit(tap_report), lgtunit(xunit_output), lgtunit(xunit_report)]). ...

% it's also possible to generate diagrams for a library and all its % sub-libraries using the rlibrary/1-2 methods instead of the library/1 % method (the zoom(true) automatically generates all sub-diagrams % for linking when converting the `.dot` files to SVG):

| ?- library_load_diagram(dot)::rlibrary(tools, [zoom(true)]). yes

% we can also generate a diagram showing dependency relations between % files (due to a file containing an entity that refers to an entity % in another file):

| ?- file_dependency_diagram::library(searching). yes

% all methods that generate a diagram have a variant that allows the % specification of the options to be used when generating a diagram

% when generating a diagram for public publishing, it's often possible % to shorten file paths in order to remove a user-dependent prefix:

| ?- file_dependency_diagram::library(searching, [omit_path_prefixes(['$LOGTALKUSER'])]). yes

% some final output formats such as SVG support tooltips and URL links; % the URL prefixes can be specified so that clicking in a cluster open % the corresponding directory (local or remote), clicking on a file node % opens the corresponding file, and clicking on an entity or predicate % node opens its documentation:

| ?- entity_diagram::library(core, [title('Logtalk core entities'), node_type_captions(true), url_prefixes('https://github.com/LogtalkDotOrg/logtalk3/tree/master/', 'https://logtalk.org/library/'), omit_path_prefixes(['$LOGTALKUSER', '$LOGTALKHOME'])]). true.

| ?- xref_diagram::entity(logtalk, [title('logtalk built-in object'), url_prefixes('https://github.com/LogtalkDotOrg/logtalk3/tree/master/', 'https://logtalk.org/library/'), omit_path_prefixes(['$LOGTALKUSER', '$LOGTALKHOME'])]). true.

| ?- inheritance_diagram::rlibrary(tools, [title('Logtalk development tools'), url_prefixes('https://github.com/LogtalkDotOrg/logtalk3/tree/master/', 'https://logtalk.org/library/'), omit_path_prefixes(['$LOGTALKUSER', '$LOGTALKHOME'])]). yes

% when the source code is evolving, is best to link to a specific commit % so that e.g. line numbers in links to clauses will always be valid. For % example, assuming a git clone of the Logtalk repo at $HOME/logtalk3:

| ?- set_logtalk_flag(source_data,on), logtalk_load([git(loader), tools(loader), issue_creator(loader), ports_profiler(loader),tutor(loader), wrapper(loader), lgtunit(coverage_report), lgtunit(automation_report), lgtunit(minimal_output), lgtunit(tap_output), lgtunit(tap_report), lgtunit(xunit_output), lgtunit(xunit_report), lgtunit(xunit_net_v2_output), lgtunit(xunit_net_v2_report)]). yes

| ?- git::commit_hash('$HOME/logtalk3', Hash), atom_concat('https://github.com/LogtalkDotOrg/logtalk3/tree/', Hash, GitHub), library_load_diagram::rlibrary(tools, [title('Logtalk development tools'), zoom(true), path_url_prefixes('$LOGTALKUSER/',GitHub,'https://logtalk.org/library/'), path_url_prefixes('$LOGTALKHOME/',GitHub,'https://logtalk.org/library/'), omit_path_prefixes(['$LOGTALKUSER/','$LOGTALKHOME/','$HOME/']), exclude_directories(['$HOME/logtalk_packs/', '$HOME/lib'])]). yes

| ?- git::commit_hash('$HOME/logtalk3', Hash), atomic_list_concat(['https://github.com/LogtalkDotOrg/logtalk3/tree/',Hash,'/'],GitHub), directory_load_diagram::rdirectory(tools, '$LOGTALKUSER/tools', [title('Logtalk development tools'), zoom(true), path_url_prefixes('$LOGTALKUSER/',GitHub,'https://logtalk.org/library/'), path_url_prefixes('$LOGTALKHOME/',GitHub,'https://logtalk.org/library/'), omit_path_prefixes(['$LOGTALKUSER/','$LOGTALKHOME/','$HOME/']), exclude_directories(['$HOME/logtalk_packs/', '$HOME/lib'])]). yes

% we can also generate diagrams with links to local directories and files % which open in selected text editors. For example:

| ?- library_load_diagram::rlibrary(tools, [title('Logtalk development tools'), zoom(true), url_prefixes('vscode://file/','$LOGTALKUSER/docs/')]). yes

% the utility objects diagrams/0-1 allows generating all supported diagrams % at once:

| ?- diagrams::rlibrary(tools, [title('Logtalk development tools'), url_prefixes('https://github.com/LogtalkDotOrg/logtalk3/tree/master/', 'https://logtalk.org/library/'), omit_path_prefixes(['$LOGTALKUSER', '$LOGTALKHOME'])]). yes

% SWI-Prolog/YAP "csv" module entity and cross-referencing diagrams:

| ?- {diagrams(loader)}, use_module(library(csv)), entity_diagram::files(csv, [csv,record,pure_input,debug,option,error], [node_type_captions(true),layout(top_to_bottom)]). yes

| ?- {diagrams(loader)}, use_module(library(csv)), xref_diagram::files(csv, [csv,record,pure_input,debug,option,error], [node_type_captions(true),layout(top_to_bottom)]). yes

| ?- {diagrams(loader)}, current_prolog_flag(home, Home), atom_concat(Home, '/library', Path), use_module(library(csv)), xref_diagram::entity(csv, [node_type_captions(true),layout(top_to_bottom),url_prefixes('https://github.com/SWI-Prolog/swipl-devel/tree/master/library/', 'http://www.swi-prolog.org/pldoc/man?section='), omit_path_prefixes([Path])]).

% SWI-Prolog libraries entity diagram (with links to GitHub SWI-Prolog % repository and the modules documentation in the SWI-Prolog website):

| ?- Libraries = [aggregate, apply, assoc, broadcast, charsio, check, clpfd, csv, debug, gensym, lists, nb_set, www_browser, option, optparse, ordsets, pairs, pio, predicate_options, prolog_pack, prolog_xref, quasi_quotations, random, readutil, record, simplex, thread_pool, ugraphs, url, varnumbers], forall(member(Library,Libraries), use_module(library(Library),[])). yes

% note in the next goal that we must refer to the "pairs" module file % using its full path as using only the name would pick the "pairs" % Logtalk object instead

| ?- {diagrams(loader)}, module_property(pairs, file(PairsFile)), findall(Path, file_search_path(library, Path), Paths), current_prolog_flag(home, Home), atom_concat(Home, '/library', HomePath), entity_diagram::files('SWI-Prolog library', [aggregate, apply, assoc, broadcast, charsio, check, clpfd, csv, debug, gensym, lists, nb_set, www_browser, option, optparse, ordsets, PairsFile, pio, predicate_options, prolog_pack, prolog_xref, quasi_quotations, random, readutil, record, simplex, thread_pool, ugraphs, url, varnumbers], [url_prefixes('https://github.com/SWI-Prolog/swipl-devel/tree/master/library/', 'http://www.swi-prolog.org/pldoc/man?section='), entity_url_suffix_target('',''), omit_path_prefixes([HomePath| Paths]), layout(top_to_bottom)]). yes

% SWI-Prolog based ClioPatria application (git version) linked diagrams % % the required query is complex due to the use of submodules for the SWI-Prolog % packages, and thus separate git repositories; here we take into account only % the "http", "pldoc", and "semweb" packages

| ?- [cliopatria]. ...

| ?- working_directory(ClioPatria,ClioPatria), getenv('HOME', Home), file_search_path(swi, SWIHome), atom_concat(SWIHome, '/library', Library), atom_concat(SWIHome, '/library/http', SWIhttp), atom_concat(SWIHome, '/library/pldoc', SWIpldoc), atom_concat(SWIHome, '/library/semweb', SWIsemweb), git_hash(Hash, []), atom_concat('https://github.com/ClioPatria/ClioPatria/tree/', Hash, Git), diagrams::rdirectory(cliopatria, '.', [ title('ClioPatria - an RDF application platform'), zoom(true), path_url_prefixes(ClioPatria, Git, ''), path_url_prefixes(SWIhttp, 'https://github.com/SWI-Prolog/packages-http/tree/master/', ''), path_url_prefixes(SWIpldoc, 'https://github.com/SWI-Prolog/packages-pldoc/tree/master/', ''), path_url_prefixes(SWIsemweb, 'https://github.com/SWI-Prolog/packages-semweb/tree/master/', ''), path_url_prefixes(Library, 'https://github.com/SWI-Prolog/swipl-devel/tree/master/library/', ''), omit_path_prefixes([ClioPatria, SWIhttp, SWIpldoc, SWIsemweb, Library, Home]), exclude_directories([web, test, scripts, w3c, etc, rdf, 'Windows', 'Java']), layout(top_to_bottom) ]). ...