.. index:: diagram(Format)
.. _diagram/1:

**category**

``diagram(Format)``
===================

Common predicates for generating diagrams.

| **Author:** Paulo Moura
| **Version:** 2.11
| **Date:** 2017/11/27

| **Compilation flags:**
|    ``static``


| **Provides:**
|    :ref:`logtalk::message_prefix_stream/4 <logtalk/0::message_prefix_stream/4>`
|    :ref:`logtalk::message_tokens//2 <logtalk/0::message_tokens//2>`

Public interface
----------------

.. raw:: html

   <div id="libraries/3"> </div>

.. index:: libraries/3
.. _diagram/1::libraries/3:

``libraries/3``
^^^^^^^^^^^^^^^

Creates a diagram for a set of libraries using the specified options. The Project argument is used as a prefix for the diagram file name.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``libraries(Project,Libraries,Options)``
| **Mode and number of proofs:**
|    ``libraries(+atom,+list(atom),+list(compound))`` - ``one``


.. raw:: html

   <div id="libraries/2"> </div>

.. index:: libraries/2
.. _diagram/1::libraries/2:

``libraries/2``
^^^^^^^^^^^^^^^

Creates a diagram for a set of libraries using the default options. The Project argument is used as a prefix for the diagram file name.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``libraries(Project,Libraries)``
| **Mode and number of proofs:**
|    ``libraries(+atom,+list(atom))`` - ``one``


.. raw:: html

   <div id="libraries/1"> </div>

.. index:: libraries/1
.. _diagram/1::libraries/1:

``libraries/1``
^^^^^^^^^^^^^^^

Creates a diagram for a set of libraries using the default options. The prefix "libraries" is used for the diagram file name.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``libraries(Libraries)``
| **Mode and number of proofs:**
|    ``libraries(+list(atom))`` - ``one``


.. raw:: html

   <div id="all_libraries/1"> </div>

.. index:: all_libraries/1
.. _diagram/1::all_libraries/1:

``all_libraries/1``
^^^^^^^^^^^^^^^^^^^

Creates a diagram for all loaded libraries using the specified options.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``all_libraries(Options)``
| **Mode and number of proofs:**
|    ``all_libraries(+list(compound))`` - ``one``


.. raw:: html

   <div id="all_libraries/0"> </div>

.. index:: all_libraries/0
.. _diagram/1::all_libraries/0:

``all_libraries/0``
^^^^^^^^^^^^^^^^^^^

Creates a diagram for all loaded libraries using default options.

| **Compilation flags:**
|    ``static``

| **Mode and number of proofs:**
|    ``all_libraries`` - ``one``


.. raw:: html

   <div id="rlibrary/2"> </div>

.. index:: rlibrary/2
.. _diagram/1::rlibrary/2:

``rlibrary/2``
^^^^^^^^^^^^^^

Creates a diagram for a library and its sub-libraries using the specified options.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``rlibrary(Library,Options)``
| **Mode and number of proofs:**
|    ``rlibrary(+atom,+list(compound))`` - ``one``


.. raw:: html

   <div id="rlibrary/1"> </div>

.. index:: rlibrary/1
.. _diagram/1::rlibrary/1:

``rlibrary/1``
^^^^^^^^^^^^^^

Creates a diagram for a library and its sub-libraries using default options.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``rlibrary(Library)``
| **Mode and number of proofs:**
|    ``rlibrary(+atom)`` - ``one``


.. raw:: html

   <div id="library/2"> </div>

.. index:: library/2
.. _diagram/1::library/2:

``library/2``
^^^^^^^^^^^^^

Creates a diagram for a library using the specified options.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``library(Library,Options)``
| **Mode and number of proofs:**
|    ``library(+atom,+list(compound))`` - ``one``


.. raw:: html

   <div id="library/1"> </div>

.. index:: library/1
.. _diagram/1::library/1:

``library/1``
^^^^^^^^^^^^^

Creates a diagram for a library using default options.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``library(Library)``
| **Mode and number of proofs:**
|    ``library(+atom)`` - ``one``


.. raw:: html

   <div id="directories/3"> </div>

.. index:: directories/3
.. _diagram/1::directories/3:

``directories/3``
^^^^^^^^^^^^^^^^^

Creates a diagram for a set of directories using the specified options. The Project argument is used as a prefix for the diagram file name.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``directories(Project,Directories,Options)``
| **Mode and number of proofs:**
|    ``directories(+atom,+list(atom),+list(compound))`` - ``one``


.. raw:: html

   <div id="directories/2"> </div>

.. index:: directories/2
.. _diagram/1::directories/2:

``directories/2``
^^^^^^^^^^^^^^^^^

Creates a diagram for a set of directories using the default options. The Project argument is used as a prefix for the diagram file name.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``directories(Project,Directories)``
| **Mode and number of proofs:**
|    ``directories(+atom,+list(atom))`` - ``one``


.. raw:: html

   <div id="directory/3"> </div>

.. index:: directory/3
.. _diagram/1::directory/3:

``directory/3``
^^^^^^^^^^^^^^^

Creates a diagram for a directory using the specified options. The Project argument is used as a prefix for the diagram file name.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``directory(Project,Directory,Options)``
| **Mode and number of proofs:**
|    ``directory(+atom,+atom,+list(compound))`` - ``one``


.. raw:: html

   <div id="directory/2"> </div>

.. index:: directory/2
.. _diagram/1::directory/2:

``directory/2``
^^^^^^^^^^^^^^^

Creates a diagram for a directory using default options. The Project argument is used as a prefix for the diagram file name.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``directory(Project,Directory)``
| **Mode and number of proofs:**
|    ``directory(+atom,+atom)`` - ``one``


.. raw:: html

   <div id="directory/1"> </div>

.. index:: directory/1
.. _diagram/1::directory/1:

``directory/1``
^^^^^^^^^^^^^^^

Creates a diagram for a directory using default options. The name of the directory is used as a prefix for the diagram file name.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``directory(Directory)``
| **Mode and number of proofs:**
|    ``directory(+atom)`` - ``one``


.. raw:: html

   <div id="files/3"> </div>

.. index:: files/3
.. _diagram/1::files/3:

``files/3``
^^^^^^^^^^^

Creates a diagram for a set of files using the specified options. The file can be specified by name, basename, full path, or using library notation. The Project argument is used as a prefix for the diagram file name.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``files(Project,Files,Options)``
| **Mode and number of proofs:**
|    ``files(+atom,+list(atom),+list(compound))`` - ``one``


.. raw:: html

   <div id="files/2"> </div>

.. index:: files/2
.. _diagram/1::files/2:

``files/2``
^^^^^^^^^^^

Creates a diagram for a set of files using the default options. The file can be specified by name, basename, full path, or using library notation. The Project argument is used as a prefix for the diagram file name.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``files(Project,Files)``
| **Mode and number of proofs:**
|    ``files(+atom,+list(atom))`` - ``one``


.. raw:: html

   <div id="files/1"> </div>

.. index:: files/1
.. _diagram/1::files/1:

``files/1``
^^^^^^^^^^^

Creates a diagram for a set of files using the default options. The file can be specified by name, basename, full path, or using library notation. The prefix "files" is used for the diagram file name.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``files(Files)``
| **Mode and number of proofs:**
|    ``files(+list(atom))`` - ``one``


.. raw:: html

   <div id="all_files/1"> </div>

.. index:: all_files/1
.. _diagram/1::all_files/1:

``all_files/1``
^^^^^^^^^^^^^^^

Creates a diagram for all loaded files using the specified options.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``all_files(Options)``
| **Mode and number of proofs:**
|    ``all_files(+list(compound))`` - ``one``


.. raw:: html

   <div id="all_files/0"> </div>

.. index:: all_files/0
.. _diagram/1::all_files/0:

``all_files/0``
^^^^^^^^^^^^^^^

Creates a diagram for all loaded files using default options.

| **Compilation flags:**
|    ``static``

| **Mode and number of proofs:**
|    ``all_files`` - ``one``


.. raw:: html

   <div id="format_object/1"> </div>

.. index:: format_object/1
.. _diagram/1::format_object/1:

``format_object/1``
^^^^^^^^^^^^^^^^^^^

Returns the identifier of the object implementing the graph language currently being used. Fails if none is specified.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``format_object(Object)``
| **Mode and number of proofs:**
|    ``format_object(-object_identifier)`` - ``zero_or_one``


.. raw:: html

   <div id="diagram_name_suffix/1"> </div>

.. index:: diagram_name_suffix/1
.. _diagram/1::diagram_name_suffix/1:

``diagram_name_suffix/1``
^^^^^^^^^^^^^^^^^^^^^^^^^

Returns the diagram name suffix.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``diagram_name_suffix(Suffix)``
| **Mode and number of proofs:**
|    ``diagram_name_suffix(-atom)`` - ``one``


.. raw:: html

   <div id="default_option/1"> </div>

.. index:: default_option/1
.. _diagram/1::default_option/1:

``default_option/1``
^^^^^^^^^^^^^^^^^^^^

Enumerates by backtracking the default options used when generating a diagram.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``default_option(DefaultOption)``
| **Mode and number of proofs:**
|    ``default_option(?compound)`` - ``zero_or_more``


.. raw:: html

   <div id="default_options/1"> </div>

.. index:: default_options/1
.. _diagram/1::default_options/1:

``default_options/1``
^^^^^^^^^^^^^^^^^^^^^

Returns a list of the default options used when generating a diagram.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``default_options(DefaultOptions)``
| **Mode and number of proofs:**
|    ``default_options(-list(compound))`` - ``one``


Protected interface
-------------------

.. raw:: html

   <div id="merge_options/2"> </div>

.. index:: merge_options/2
.. _diagram/1::merge_options/2:

``merge_options/2``
^^^^^^^^^^^^^^^^^^^

Merges the user options with the default options, returning the list of options used when generating a diagram. Path arguments in options are expanded to full paths. Also ensures that all directory paths end with a slash.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``merge_options(UserOptions,Options)``
| **Mode and number of proofs:**
|    ``merge_options(+list(compound),-list(compound))`` - ``one``


.. raw:: html

   <div id="output_rlibrary/3"> </div>

.. index:: output_rlibrary/3
.. _diagram/1::output_rlibrary/3:

``output_rlibrary/3``
^^^^^^^^^^^^^^^^^^^^^

Generates diagram output for a library and its sub-libraries using the specified options.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``output_rlibrary(Library,Path,Options)``
| **Mode and number of proofs:**
|    ``output_rlibrary(+atom,+atom,+list(compound))`` - ``one``


.. raw:: html

   <div id="output_library/3"> </div>

.. index:: output_library/3
.. _diagram/1::output_library/3:

``output_library/3``
^^^^^^^^^^^^^^^^^^^^

Generates diagram output for a library using the specified options.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``output_library(Library,Path,Options)``
| **Mode and number of proofs:**
|    ``output_library(+atom,+atom,+list(compound))`` - ``one``


.. raw:: html

   <div id="output_files/2"> </div>

.. index:: output_files/2
.. _diagram/1::output_files/2:

``output_files/2``
^^^^^^^^^^^^^^^^^^

Generates diagram output for a list of files using the specified options.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``output_files(Files,Options)``
| **Mode and number of proofs:**
|    ``output_files(+list,+list(compound))`` - ``one``


.. raw:: html

   <div id="output_file/4"> </div>

.. index:: output_file/4
.. _diagram/1::output_file/4:

``output_file/4``
^^^^^^^^^^^^^^^^^

Generates diagram output for a file using the specified options.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``output_file(Path,Basename,Directory,Options)``
| **Mode and number of proofs:**
|    ``output_file(+atom,+atom,+atom,+list(compound))`` - ``one``


.. raw:: html

   <div id="output_externals/1"> </div>

.. index:: output_externals/1
.. _diagram/1::output_externals/1:

``output_externals/1``
^^^^^^^^^^^^^^^^^^^^^^

Outputs external entities using the specified options.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``output_externals(Options)``
| **Mode and number of proofs:**
|    ``output_externals(+list(compound))`` - ``one``


.. raw:: html

   <div id="reset/0"> </div>

.. index:: reset/0
.. _diagram/1::reset/0:

``reset/0``
^^^^^^^^^^^

Resets all temporary information used when generating a diagram.

| **Compilation flags:**
|    ``static``

| **Mode and number of proofs:**
|    ``reset`` - ``one``


.. raw:: html

   <div id="output_node/6"> </div>

.. index:: output_node/6
.. _diagram/1::output_node/6:

``output_node/6``
^^^^^^^^^^^^^^^^^

Outputs a graph node.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``output_node(Identifier,Label,Caption,Contents,Kind,Options)``
| **Mode and number of proofs:**
|    ``output_node(+nonvar,+nonvar,+nonvar,+list(nonvar),+atom,+list(compound))`` - ``one``


.. raw:: html

   <div id="edge/5"> </div>

.. index:: edge/5
.. _diagram/1::edge/5:

``edge/5``
^^^^^^^^^^

Enumerates, by backtracking, all saved edges.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``edge(From,To,Labels,Kind,Options)``
| **Mode and number of proofs:**
|    ``edge(?nonvar,?nonvar,?list(nonvar),?atom,?list(compound))`` - ``zero_or_more``


.. raw:: html

   <div id="output_edges/1"> </div>

.. index:: output_edges/1
.. _diagram/1::output_edges/1:

``output_edges/1``
^^^^^^^^^^^^^^^^^^

Outputs all edges.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``output_edges(Options)``
| **Mode and number of proofs:**
|    ``output_edges(+list(compound))`` - ``one``


.. raw:: html

   <div id="save_edge/5"> </div>

.. index:: save_edge/5
.. _diagram/1::save_edge/5:

``save_edge/5``
^^^^^^^^^^^^^^^

Saves a graph edge.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``save_edge(From,To,Labels,Kind,Options)``
| **Mode and number of proofs:**
|    ``save_edge(+nonvar,+nonvar,+list(nonvar),+atom,+list(compound))`` - ``one``


.. raw:: html

   <div id="not_excluded_file/3"> </div>

.. index:: not_excluded_file/3
.. _diagram/1::not_excluded_file/3:

``not_excluded_file/3``
^^^^^^^^^^^^^^^^^^^^^^^

True when the given file is not excluded from the generated output. Excluded files may be specified by full path or by basename and with or without extension.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``not_excluded_file(ExcludedFiles,Path,Basename)``
| **Mode and number of proofs:**
|    ``not_excluded_file(+list(atom),+atom,+atom)`` - ``zero_or_one``


.. raw:: html

   <div id="output_file_path/4"> </div>

.. index:: output_file_path/4
.. _diagram/1::output_file_path/4:

``output_file_path/4``
^^^^^^^^^^^^^^^^^^^^^^

Returns the output file path.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``output_file_path(Name,Options,Format,Path)``
| **Mode and number of proofs:**
|    ``output_file_path(+atom,+list(atom),+object_identifier,-atom)`` - ``one``


.. raw:: html

   <div id="locate_file/5"> </div>

.. index:: locate_file/5
.. _diagram/1::locate_file/5:

``locate_file/5``
^^^^^^^^^^^^^^^^^

Locates a file given its name, basename, full path, or library notation representation.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``locate_file(File,Basename,Extension,Directory,Path)``
| **Mode and number of proofs:**
|    ``locate_file(+atom,+atom,+atom,+atom,-atom)`` - ``one``


.. raw:: html

   <div id="ground_entity_identifier/3"> </div>

.. index:: ground_entity_identifier/3
.. _diagram/1::ground_entity_identifier/3:

``ground_entity_identifier/3``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Converts an entity identifier to a ground term.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``ground_entity_identifier(Kind,Identifier,GroundIdentifier)``
| **Mode and number of proofs:**
|    ``ground_entity_identifier(+atom,+callable,-callable)`` - ``one``


.. raw:: html

   <div id="filter_file_extension/3"> </div>

.. index:: filter_file_extension/3
.. _diagram/1::filter_file_extension/3:

``filter_file_extension/3``
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Filters the file name extension depending on the file_extensions/1 option.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``filter_file_extension(Basename,Options,Name)``
| **Mode and number of proofs:**
|    ``filter_file_extension(+atom,+list(compound),-atom)`` - ``one``


.. raw:: html

   <div id="add_link_options/3"> </div>

.. index:: add_link_options/3
.. _diagram/1::add_link_options/3:

``add_link_options/3``
^^^^^^^^^^^^^^^^^^^^^^

Adds urls/2 and tooltip/1 link options (for use by the graph language) based on the specified path to the list of options.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``add_link_options(Path,Options,GraphOptions)``
| **Mode and number of proofs:**
|    ``add_link_options(+atom,+list(compound),-list(compound))`` - ``one``


.. raw:: html

   <div id="omit_path_prefix/3"> </div>

.. index:: omit_path_prefix/3
.. _diagram/1::omit_path_prefix/3:

``omit_path_prefix/3``
^^^^^^^^^^^^^^^^^^^^^^

Removes a prefix from a path, returning the relative path, when using the option omit_path_prefixes/1. Used mainly for contructing file node identitifers and captions.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``omit_path_prefix(Path,Options,Relative)``
| **Mode and number of proofs:**
|    ``omit_path_prefix(+atom,+list(compound),-atom)`` - ``one``


.. raw:: html

   <div id="add_node_zoom_option/5"> </div>

.. index:: add_node_zoom_option/5
.. _diagram/1::add_node_zoom_option/5:

``add_node_zoom_option/5``
^^^^^^^^^^^^^^^^^^^^^^^^^^

Adds node zoom options when using the zoom option.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``add_node_zoom_option(Identifier,Suffix,Options,NodeOptions0,NodeOptions)``
| **Mode and number of proofs:**
|    ``add_node_zoom_option(+atom,+atom,+list(compound),+list(compound),-list(compound))`` - ``one``


Private predicates
------------------

.. raw:: html

   <div id="edge_/5"> </div>

.. index:: edge_/5
.. _diagram/1::edge_/5:

``edge_/5``
^^^^^^^^^^^

Table of saved edges.

| **Compilation flags:**
|    ``dynamic``

| **Template:**
|    ``edge_(From,To,Labels,Kind,Options)``
| **Mode and number of proofs:**
|    ``edge_(?nonvar,?nonvar,?list(nonvar),?atom,?list(compound))`` - ``zero_or_more``


Operators
---------

(none)

Remarks
-------

(none)

