.. _py-dg/Builder: ********************************************************** dg/Builder ********************************************************** .. default-domain:: py .. py:currentmodule:: mod .. cpp:namespace:: mod .. class:: DGBuilder An RAII-style object obtained from :meth:`DG.build`. On destruction of an active builder object the owning :class:`DG` will be locked for further modifications. The object can be used as a context manager: .. code-block:: python dg = DG() with dg.build() as b: # b is a DGBuilder # b has now been destructed and dg is locked. Otherwise one can manually use ``del`` on the obtained builder to trigger the destruction. .. attribute:: dg The derivation graph this builder can modify. :type: DG .. attribute:: isActive Whether this object is associated with a :py:class:`DG`. :type: bool .. method:: addDerivation(d, graphPolicy=IsomorphismPolicy.Check) Adds a hyperedge corresponding to the given derivation to the associated :class:`DG`. If it already exists, only add the given rules to the edge. :param Derivations d: a derivation to add a hyperedge for. :param IsomorphismPolicy graphPolicy: the isomorphism policy for adding the given graphs. :returns: the hyperedge corresponding to the given derivation. :rtype: DGHyperEdge :raises: :class:`LogicError` if ``d.left`` or ``d.right`` is empty. :raises: :class:`LogicError` if a ``None``is in ``d.left``, ``d.right``, or ``d.rules``. :raises: :class:`LogicError` if ``graphPolicy == IsomorphismPolicy.Check`` and a given graph object is different but isomorphic to another given graph object or to a graph object already in the internal graph database in the associated derivation graph. .. method:: addHyperEdge(e, graphPolicy=IsomorphismPolicy.Check) Adds a hyperedge to the associated :class:`DG` from a copy of the given hyperedge (from a different :class:`DG`). If it already exists, only add the rules to the edge. :param DGHyperEdge e: a hyperedge to copy. :param IsomorphismPolicy graphPolicy: the isomorphism policy for adding the given graphs. :returns: the hyperedge corresponding to the copy of the given hyperedge. :rtype: DGHyperEdge :raises: :class:`LogicError` if ``e`` is a null edge. :raises: :class:`LogicError` if ``graphPolicy == IsomorphismPolicy.Check`` and a given graph object is different but isomorphic to another given graph object or to a graph object already in the internal graph database in the associated derivation graph. .. method:: execute(strategy, *, verbosity=2, ignoreRuleLabelTypes=False) Execute the given strategy (:ref:`dgStrat`) and as a side effect add vertices and hyperedges to the underlying derivation graph. :param DGStrat strategy: the strategy to execute. :param int verbosity: the level of verbosity of printed information during calculation. See :cpp:func:`dg::Builder::execute` for explanations of the levels. :param bool ignoreRuleLabelTypes: whether rules in the strategy should be checked beforehand for whether they have an associated :class:`LabelType` which matches the one in the underlying derivation graph. :returns: a proxy object for accessing the result of the execution. :rtype: DGExecuteResult :throws: :class:`LogicError` if a static "add" strategy has :attr:`IsomorphismPolicy.Check` as graph policy, and it tries to add a graph object isomorphic to an already known, but different, graph object in the database. This is checked before execution, so there is strong exception guarantee. :throws: :class:`LogicError` if a dynamic "add" strategy has :attr:`IsomorphismPolicy.Check` as graph policy, and it tries to add a graph object isomorphic to an already known, but different, graph object in the database. .. warning:: This is checked during execution, so while the basic exception guarantee is provided, there may be modifications to the underlying derivation graph. :throws: :class:`LogicError` if a dynamic "add" strategy is executed where a returned graph is ``None``. .. warning:: This is checked during execution, so while the basic exception guarantee is provided, there may be modifications to the underlying derivation graph. :throws: :class:`LogicError`: if ``ignoreRuleLabelTypes`` is ``False``, which is the default, and a rule in the given strategy has an associated :class:`LabelType` which is different from the one in the derivation graph. .. method:: apply(graphs, r, onlyProper=True, verbosity=0, graphPolicy=IsomorphismPolicy.Check) Compute direct derivations. :param graphs: the graphs constituting the left-hand side of the computed direct derivations. :type graphs: list[Graph] :param bool onlyProper: when ``True``, then all of ``graphs`` must be used in each direct derivation. :param Rule r: the rule to use for the direct derivations. :param int verbosity: the level of verbosity of printed information during calculation. See :cpp:func:`dg::Builder::apply` for explanations of the levels. :param IsomorphismPolicy graphPolicy: the isomorphism policy for adding the given graphs. :returns: a list of hyper edges representing the found direct derivations. The list may contain duplicates if there are multiple ways of constructing the same direct derivation when ignoring the specific match morphism. :rtype: list[DGHyperEdge] :raises: :class:`LogicError` if there is a ``None`` in ``graphs``. :raises: :class:`LogicError` if ``r`` is ``None``. :raises: :class:`LogicError` if ``graphPolicy == IsomorphismPolicy.Check`` and a given graph object is different but isomorphic to another given graph object or to a graph object already in the internal graph database in the associated derivation graph. .. method:: addAbstract(description) Add vertices and hyperedges based on the given abstract description. The description must adhere to the grammar described at :ref:`dg_abstract-desc`. For each vertex named in the description a graph object with a single vertex will be created. The label of that vertex and the name of the graph is set to the given identifier. :param str description: the description to parse into abstract derivations. :raises: :class:`InputError` if the description could not be parsed. .. method:: load(ruleDatabase, f, verbosity=2) Load and add a derivation graph dump. Use :func:`DG.load` to load a dump as a locked derivation graph. The label settings of this DG and the ones retrieved from the dump file must match. Vertices with graphs and hyperedges with rules are then added from the dump. Any graph in the dump which is isomorphic to a graph in the internal graph database of the DG is replaced by the given graph. The same procedure is done for the rules, but compared against the given rules. If a graph/rule is not found in the given lists, a new object is instantiated and used. See :cpp:func:`dg::DG::load` for an explanation of the verbosity levels. :param ruleDatabase: A list of rules used as explained above. :type ruleDatabase: list[Rule] :param f: a DG dump file to load. :type f: str or CWDPath :raises: :class:`LogicError` if there is a ``None`` in ``ruleDatabase``. :raises: :class:`LogicError` if the label settings of the dump does not match those of this DG. :raises: :class:`InputError` if the file can not be opened or its content is bad. .. class:: DGExecuteResult The result from calling :func:`DGBuilder.execute`. .. attribute:: subset universe (Read-only) Respectively the subset and the universe computed by the strategy execution (see also :ref:`dgStrat`). :type: list[Graph] .. method:: list(*, withUniverse=False) Output information from the execution of the strategy. :param bool withUniverse: The universe lists can be rather long. As default, they are omitted when listing.