GrGen.NET v4.4 API: the libGr class library (the type exact interface gets generated)
Welcome to the GrGen.NET v4.4 API documentation

This is an introduction into the Application Programming Interface of the GrGen.NET v4.4 (4.4.4) system, i.e. the libGr and the assemblies generated from the model and rule specifications. We'll have a look at the

From the input file Foo.grg the grgen.exe compiler generates the output files FooModel.cs for the model and FooActions.cs for the actions,
Note:

If you work on the API level it is helpful to keep the generated source code which normally is thrown away after it was compiled into the assemblies lgsp-FooModel.dll and lgsp-FooActions.dll. Use the -keep option when you call grgen.exe to do so.

Interface to the model and host graph

The generated FooModel.cs opens the namespace de.unika.ipd.grGen.Model_Foo containing all the generated entities. It contains for every node or edge class Bar an interface IBar, which offers C# properties giving access to the attributes, and is inheriting in the same way as specified in the model file. This builds the exact interface of the model, it is implemented by a sealed class Bar with generated code and with code from the lgsp backend. Furtheron the namespace contains a model class FooGraphModel implementing the interface de.unika.ipd.grGen.libGr.IGraphModel, which supports iteration over the entities defined in the model using further, generic(i.e. inexact) interfaces from libGr. Finally, the namespace contains a class FooGraph which defines an LGSPGraph of a model equivalent to FooGraphModel; it contains convenience functions to easily create nodes and edges of exact type in the graph. In addition, a class FooNamedGraph is available, which defines an LGSPNamedGraph of a model equivalent to FooGraphModel; the named graph offers persistent names for all its graph elements, otherwise it is identical to an LGSPGraph. The naming requires about the same memory as an unnamed graph, but under normal circumstances the named graph is the recommended one to use (and is the one which will be used if employed by the shell).

Note:

If you want to use the type-safe interface, use the interface IBar, and the CreateNodeBar-methods of FooGraph or the CreateNode-method of Bar.

If you want to use the generic interface, your entry point is the IGraphModel, with INodeModel.GetType("Bar") returning a NodeType, used in IGraph.AddNode(NodeType) returning an INode.

Interface to the rules

The generated file FooActions.cs opens the namespace de.unika.ipd.grGen.Action_Foo containing all the generated entities. It contains for every rule or test bar

Moreover the namespace contains an action class FooActions implementing the abstract class de.unika.ipd.grGen.libGr.BaseActions (in fact de.unika.ipd.grGen.lgsp.LGSPActions), which supports iteration over the entities defined in the actions using further, generic(i.e. inexact) interfaces from libGr. Additionally, at runtime it contains the instances of the actions singletons, as member bar of the exact type IAction_bar.
Note:

If you want to use the type-safe interface, your entry point is the member bar of type IAction_bar from FooActions (or Action_bar.Instance). Actions are used with named parameters of exact types.

If you want to use the generic interface, your entry point is the method GetAction("bar") of the interface BaseActions implemented by FooActions returning an IAction. Actions are used with object-arrays for parameter passing.

Interface to the graph processing environment

The interface IGraphProcessingEnvironment implemented by the LGSPGraphProcessingEnvironment class offers all the additional functionality of GrGen.NET exceeding what is offered by the graph and the actions. It is constructed as LGSPGraphProcessingEnvironment given the graph and the actions. It offers execution of the sequences and variable handling, combining actions into transformations (the former regarding control flow, the latter regarding data flow). Further on, the environment offers driver or helper objects for transaction management, deferred sequence execution, graph change recording, and emitting.

Examples

There are several examples available in the examples-api folder of the GrGen.NET-distribution:

If you want to work with GrGen.NET at API level you should get VisualStudio or MonoDevelop and have a look at them (or the other GrGen.NET code delivered with the source distribution; have a look at the How to build section in the manual if you want to build GrGen.NET on your own). In the following are a few further examples given as starting points.

Example 1

Normally you want to use the type-safe interface of the generated code as it is much more convenient. Only if your application must get along with models and actions unknown before it is compiled you have to fall back to the generic interface. An extensive example showing how to cope with the latter is shipped with GrGen.NET in form of the GrShell. Here we'll show a short example on how to use GrGen.NET with the type-safe API; further examples are given in the examples-api folder of the GrGen.NET-distribution. We'll start with including the namespaces of the libGr and the lgsp backend shipped with GrGen.NET, plus the namespaces of our actions and models, generated from Foo.grg.

CopyC#
using de.unika.ipd.grGen.libGr;
using de.unika.ipd.grGen.lgsp;
using de.unika.ipd.grGen.Action_Foo;
using de.unika.ipd.grGen.Model_Foo;
Then we create a graph with model bound at generation time and create actions to operate on this graph. Afterwards we create a single node of type Bar in the graph and save it to the variable b. Finally we apply the action bar(Bar x) : (Bar) to the graph with b as input receiving the output as well. The rule is taken from the actions via the member named as the action.
CopyC#
FooGraph graph = new FooGraph();
FooActions actions = new FooActions(graph);
Bar b = graph.CreateNodeBar();
actions.bar.Apply(graph, b, ref b); // input of type Bar, output of type Bar
We could create a named graph instead offering persistent names for its graph elements:
CopyC#
FooNamedGraph graph = new FooNamedGraph();

Example 2

This is an example doing mostly the same as the previous example, in a slightly more complicated way allowing for more control. Here we create the model separate from the graph, then the graph with a model not bound at generation time. We create the actions to apply on the graph, and a single node of type Bar in the graph, which we assign again to a variable b. Then we get the action from the actions and save it to an action variable bar; afterwards we use the action for finding all available matches of bar with input b -- which is different from the first version -- and remember the found matches in the matches variable with its exact type. Finally we take the first match from the matches and execute the rewrite with it. We could have inspected the nodes and edges of the match or their attributes before (using element names prefixed with node_/edge_ or attribute names to get exactly typed entities).

CopyC#
IGraphModel model = new FooGraphModel();
LGSPGraph graph = new LGSPGraph(model);
FooActions actions = new FooActions(graph);
Bar b = Bar.CreateNode(graph);
IAction_bar bar = Action_bar.Instance;
IMatchesExact<Rule_bar.IMatch_bar matches> = bar.Match(graph, 0, b);
bar.Modify(graph, matches.First);
We could create a named graph instead offering persistent names for its graph elements:
CopyC#
LGSPGraph graph = new LGSPNamedGraph(model);

Example 3

While C# allows input arguments values to be of a subtype of the declared interface parameter type (OO), it requires that the argument variables for the out parameters are of exactly the type declared (non-OO). Although a variable of a supertype would be fully sufficient -- the variable is only assigned. So for node class Bla extends Bar; and action bar(Bar x) : (Bla) from the rules file rules Foo.grg we can't use a desired target variable of type Bar as out-argument, but are forced to introduce a temporary variable of type Bla and assign this variable to the desired target variable after the call.

CopyC#
using de.unika.ipd.grGen.libGr;
using de.unika.ipd.grGen.lgsp;
using de.unika.ipd.grGen.Action_Foo;
using de.unika.ipd.grGen.Model_Foo;
FooGraph graph = new FooGraph();
FooActions actions = new FooActions(graph);
Bar b = graph.CreateNodeBar();
IMatchesExact<Rule_bar.IMatch_bar> matches = actions.bar.Match(graph, 1, b);
//actions.bar.Modify(graph, matches.First, out b); // wont work, needed:
Bla bla = null; 
actions.bar.Modify(graph, matches.First, out bla);
b = bla;

Example 4

For all but the simplest transformations you'll end up constructing a graph processing environment from the graph and the actions constructed until now, executing a graph rewrite sequence on the graph processing environment:

CopyC#
LGSPGraphProcessingEnvironment procEnv = new LGSPGraphProcessingEnvironment(graph, actions);
procEnv.ApplyGraphRewriteSequence("<(::x)=foo && (::y)=bar(::x) | bla(::y)>");

See Also