.. _cpp-rule/Rule:

**********************************************************
rule/Rule.hpp
**********************************************************
.. default-domain:: cpp
.. default-role:: cpp:expr

.. py:currentmodule:: mod
.. cpp:namespace:: mod


Class ``rule::Rule``
--------------------------------------------------------------------------------------------------------------------------------

.. class:: rule::Rule
    

    Model of a transformation rule in the Double Pushout formalism.
    See :ref:`cpp-rule/GraphInterface` for the documentation for the
    graph interface for this class.


Synopsis
^^^^^^^^

.. code-block:: c++
    
    struct MOD_DECL Rule {
        class Vertex;
        class Edge;
        class VertexIterator;
        class VertexRange;
        class EdgeIterator;
        class EdgeRange;
        class IncidentEdgeIterator;
        class IncidentEdgeRange;
    public:
        class LeftGraph;
        class ContextGraph;
        class RightGraph;
    private:
        Rule(Rule&&) = delete;
        Rule &operator=(Rule&&) = delete;
    private:
        Rule(std::unique_ptr<lib::Rules::Real> r);
    public:
        ~Rule();
        unsigned int getId() const;
        MOD_DECL friend std::ostream &operator<<(std::ostream &s, const Rule &r);
        const lib::Rules::Real &getRule() const;
    public: // graph interface
        std::size_t numVertices() const;
        VertexRange vertices() const;
        std::size_t numEdges() const;
        EdgeRange edges() const;
        LeftGraph getLeft() const;
        ContextGraph getContext() const;
        RightGraph getRight() const;
    public:
        std::shared_ptr<Rule> makeInverse() const;
        std::pair<std::string, std::string> print() const;
        std::pair<std::string, std::string> print(const graph::Printer &first, const graph::Printer &second) const;
        void printTermState() const;
        std::string getGMLString(bool withCoords = false) const;
        std::string printGML(bool withCoords = false) const;
        const std::string &getName() const;
        void setName(std::string name);
        boost::optional<LabelType> getLabelType() const;
        std::size_t getNumLeftComponents() const;
        std::size_t getNumRightComponents() const;
        std::size_t isomorphism(std::shared_ptr<Rule> r, std::size_t maxNumMatches, LabelSettings labelSettings) const;
        std::size_t monomorphism(std::shared_ptr<Rule> r, std::size_t maxNumMatches, LabelSettings labelSettings) const;
        bool isomorphicLeftRight(std::shared_ptr<Rule> r, LabelSettings labelSettings) const;
        Vertex getVertexFromExternalId(int id) const;
        int getMinExternalId() const;
        int getMaxExternalId() const;
    public:
        static std::shared_ptr<Rule> ruleGMLString(const std::string &data, bool invert);
        static std::shared_ptr<Rule> ruleGML(const std::string &file, bool invert);
        static std::shared_ptr<Rule> makeRule(std::unique_ptr<lib::Rules::Real> r);
        static std::shared_ptr<Rule> makeRule(std::unique_ptr<lib::Rules::Real> r, std::map<int, std::size_t> externalToInternalIds);
    private:
        struct Pimpl;
        std::unique_ptr<Pimpl> p;
    };

Details
^^^^^^^

.. cpp:namespace-push:: rule::Rule

.. function:: unsigned int getId() const

    :returns: the unique instance id among all :class:`Rule` instances.
.. function:: std::size_t numVertices() const

    :returns: the number of vertices in the rule.
.. function:: VertexRange vertices() const

    :returns: a range of all vertices in the rule.
.. function:: std::size_t numEdges() const

    :returns: the number of edges in the rule.
.. function:: EdgeRange edges() const

    :returns: a range of all edges in the rule.
.. function:: LeftGraph getLeft() const

    :returns: a proxy object representing the left graph of the rule.
.. function:: ContextGraph getContext() const

    :returns: a proxy object representing the context graph of the rule.
.. function:: RightGraph getRight() const

    :returns: a proxy object representing the rule graph of the rule.
.. function:: std::shared_ptr<Rule> makeInverse() const

        :returns: a rule representing the inversion of this rule.
        :raises: :class:`LogicError` if inversion is not possible (due to matching constraints).
.. function:: std::pair<std::string, std::string> print() const
              std::pair<std::string, std::string> print(const graph::Printer &first, const graph::Printer &second) const

    Print the rule, using either the default options or the options in `first` and `second`.
    If `first` and `second` are the same, only one depiction will be made.

    :returns: a pair of filename prefixes for the PDF-files that will be compiled in post-processing.
        The actual names can be obtained by appending ``_L.pdf``, ``_K.pdf``, and ``_R.pdf`` for
        respectively the left side, context, and right side graphs.
        If `first` and `second` are the same, the two file prefixes are equal.
.. function:: void printTermState() const

    Print the term state for the rule.
.. function:: std::string getGMLString(bool withCoords = false) const

    :returns: the :ref:`GML <rule-gml>` representation of the rule,
              optionally with generated 2D coordinates.
    :throws: :any:`LogicError` when coordinates are requested, but
             none can be generated.
.. function:: std::string printGML(bool withCoords = false) const

    Print the rule in :ref:`GML <rule-gml>` format,
    optionally with generated 2D coordinates.

    :returns: the filename of the printed GML file.
    :throws: :any:`LogicError` when coordinates are requested, but
             none can be generated.
.. function:: const std::string &getName() const
              void setName(std::string name)

    Access the name of the rule.
.. function:: boost::optional<LabelType> getLabelType() const

    :returns: the intended label type for this rule, or nothing if no specific label type is intended.
.. function:: std::size_t getNumLeftComponents() const

    :returns: the number of connected components in the left graph.
.. function:: std::size_t getNumRightComponents() const

    :returns: the number of connected components in the right graph.
.. function:: std::size_t isomorphism(std::shared_ptr<Rule> r, std::size_t maxNumMatches, LabelSettings labelSettings) const

    :returns: the number of isomorphisms found between `r` and this graph, but at most `maxNumMatches`.
.. function:: std::size_t monomorphism(std::shared_ptr<Rule> r, std::size_t maxNumMatches, LabelSettings labelSettings) const

    :returns: the number of monomorphism from this rule to subgraphs of `r`, though at most `maxNumMatches`.
.. function:: bool isomorphicLeftRight(std::shared_ptr<Rule> r, LabelSettings labelSettings) const

    :returns: whether the left-hand sides are isomorphic and the right-hand sides are isomorphic.
.. function:: Vertex getVertexFromExternalId(int id) const

    If the rule was not loaded from an external data format, then this function
    always return a null descriptor.

    .. note:: In general there is no correlation between external and internal ids.

    :returns: the vertex descriptor for the given external id.
              The descriptor is null if the external id was not used.
.. function:: int getMinExternalId() const
              int getMaxExternalId() const

    If the rule was not loaded from an external data format, then these functions
    always return 0. Otherwise, return the minimum/maximum external id from which
    non-null vertices can be obtained from :cpp:func:`getVertexFromExternalId`.
    If no such minimum and maximum exists, then 0 will be returned.
.. function:: static std::shared_ptr<Rule> ruleGMLString(const std::string &data, bool invert)

    Load a rule from a :ref:`GML <rule-gml>` string, and store either that rule or its inverse.
    The name of the rule is the one specified in the GML string, though when ``invert=True``
    the string ", inverse" is appended to the name.

    .. note::

        If the GML string specifies matching constraints it is not possible to invert the rule.
        There is however a configuration option to ignore matching constraints when inverting rules.

    :returns: the loaded (possibly inverted) rule.
    :throws: :class:`InputError` on bad data and when inversion fails due to constraints.
.. function:: static std::shared_ptr<Rule> ruleGML(const std::string &file, bool invert)
    
    Read `file` and pass the contents to :cpp:func:`ruleGMLString`.

    :returns: the loaded (possibly inverted) rule.
    :throws: :class:`InputError` on bad data and when inversion fails due to constraints.
.. function:: static std::shared_ptr<Rule> makeRule(std::unique_ptr<lib::Rules::Real> r)
              static std::shared_ptr<Rule> makeRule(std::unique_ptr<lib::Rules::Real> r, std::map<int, std::size_t> externalToInternalIds)

    :returns: a rule wrapping the given internal rule object. If an id mapping is given, it will be used for the :cpp:func:`getVertexFromExternalId` function.

.. cpp:namespace-pop::