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

.. rst-class:: right

**category**

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

* ``Format`` - Graph language file format.


Common predicates for generating diagrams.

| **Availability:** 
|    ``logtalk_load(diagrams(loader))``

| **Author:** Paulo Moura
| **Version:** 3:0:0
| **Date:** 2024-03-06

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


| **Extends:**
|    ``public`` :ref:`options <options/0>`
| **Provides:**
|    :ref:`logtalk::message_prefix_stream/4 <logtalk/0::message_prefix_stream/4>`
|    :ref:`logtalk::message_tokens//2 <logtalk/0::message_tokens//2>`
| **Uses:**
|    :ref:`graph_language_registry <graph_language_registry/0>`
|    :ref:`list <list/0>`
|    :ref:`logtalk <logtalk/0>`
|    :ref:`modules_diagram_support <modules_diagram_support/0>`
|    :ref:`os <os/0>`
|    :ref:`pairs <pairs/0>`
|    :ref:`type <type/0>`
|    :ref:`user <user/0>`

| **Remarks:**
|    (none)

| **Inherited public predicates:**
|     :ref:`options_protocol/0::check_option/1`  :ref:`options_protocol/0::check_options/1`  :ref:`options_protocol/0::default_option/1`  :ref:`options_protocol/0::default_options/1`  :ref:`options_protocol/0::option/2`  :ref:`options_protocol/0::option/3`  :ref:`options_protocol/0::valid_option/1`  :ref:`options_protocol/0::valid_options/1`  

.. contents::
   :local:
   :backlinks: top

Public predicates
-----------------

.. 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``


------------

.. 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``


------------

.. 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``


------------

.. 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``


------------

.. 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``


------------

.. 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``


------------

.. 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``


------------

.. 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``


------------

.. 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``


------------

.. 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``


------------

.. 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``


------------

.. index:: rdirectory/3
.. _diagram/1::rdirectory/3:

``rdirectory/3``
^^^^^^^^^^^^^^^^

Creates a diagram for a directory and its sub-directories using the specified options. The ``Project`` argument is used as a prefix for the diagram file name.

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

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


------------

.. index:: rdirectory/2
.. _diagram/1::rdirectory/2:

``rdirectory/2``
^^^^^^^^^^^^^^^^

Creates a diagram for a directory and its sub-directories using default options. The ``Project`` argument is used as a prefix for the diagram file name.

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

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


------------

.. index:: rdirectory/1
.. _diagram/1::rdirectory/1:

``rdirectory/1``
^^^^^^^^^^^^^^^^

Creates a diagram for a directory and its sub-directories using default options. The name of the directory is used as a prefix for the diagram file name.

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

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


------------

.. 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``


------------

.. 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``


------------

.. 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``


------------

.. 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``


------------

.. 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``


------------

.. 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``


------------

.. 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``


------------

.. 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``


------------

.. 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``


------------

.. index:: diagram_description/1
.. _diagram/1::diagram_description/1:

``diagram_description/1``
^^^^^^^^^^^^^^^^^^^^^^^^^

Returns the diagram description.

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

| **Template:**
|    ``diagram_description(Description)``
| **Mode and number of proofs:**
|    ``diagram_description(-atom)`` - ``one``


------------

.. 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``


------------

Protected predicates
--------------------

.. index:: diagram_caption/3
.. _diagram/1::diagram_caption/3:

``diagram_caption/3``
^^^^^^^^^^^^^^^^^^^^^

Creates a diagram caption from the diagram description and the subject and its kind.

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

| **Template:**
|    ``diagram_caption(Kind,Subject,Description)``
| **Mode and number of proofs:**
|    ``diagram_caption(+atom,+callable,-atom)`` - ``one``


------------

.. 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``


------------

.. 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``


------------

.. index:: output_rdirectory/3
.. _diagram/1::output_rdirectory/3:

``output_rdirectory/3``
^^^^^^^^^^^^^^^^^^^^^^^

Generates diagram output for a directory and its sub-directories using the specified options.

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

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


------------

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

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

Output external nodes using the specified options depending on the value of the boolean option ``externals/1``.

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

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


------------

.. 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``


------------

.. 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``


------------

.. index:: output_sub_diagrams/1
.. _diagram/1::output_sub_diagrams/1:

``output_sub_diagrams/1``
^^^^^^^^^^^^^^^^^^^^^^^^^

Outputs sub-diagrams using the specified options.

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

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


------------

.. 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``


------------

.. 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``


------------

.. index:: node/6
.. _diagram/1::node/6:

``node/6``
^^^^^^^^^^

Enumerates, by backtracking, all saved nodes.

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

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


------------

.. 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``


------------

.. 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``


------------

.. 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``


------------

.. index:: output_missing_externals/1
.. _diagram/1::output_missing_externals/1:

``output_missing_externals/1``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Outputs missing external nodes (usually due to unloaded resources) that are referenced from edges.

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

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


------------

.. 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``


------------

.. 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``


------------

.. index:: locate_library/2
.. _diagram/1::locate_library/2:

``locate_library/2``
^^^^^^^^^^^^^^^^^^^^

Locates a library given its name.

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

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


------------

.. index:: locate_directory/2
.. _diagram/1::locate_directory/2:

``locate_directory/2``
^^^^^^^^^^^^^^^^^^^^^^

Locates a directory given its name or full path.

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

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


------------

.. 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``


------------

.. 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``


------------

.. 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``


------------

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

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

Adds ``url/1``, ``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,LinkingOptions)``
| **Mode and number of proofs:**
|    ``add_link_options(+atom,+list(compound),-list(compound))`` - ``one``


------------

.. 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 constructing directory and file node identifiers 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``


------------

.. index:: add_node_zoom_option/4
.. _diagram/1::add_node_zoom_option/4:

``add_node_zoom_option/4``
^^^^^^^^^^^^^^^^^^^^^^^^^^

Adds node zoom options when using the zoom option.

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

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


------------

.. index:: message_diagram_description/1
.. _diagram/1::message_diagram_description/1:

``message_diagram_description/1``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Diagram description for progress messages.

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

| **Template:**
|    ``message_diagram_description(Description)``
| **Mode and number of proofs:**
|    ``message_diagram_description(?atom)`` - ``one``


------------

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

.. index:: node_/6
.. _diagram/1::node_/6:

``node_/6``
^^^^^^^^^^^

Table of saved nodes.

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

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


------------

.. 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)

