1 files changed, 212 insertions, 0 deletions

diff --git a/subprojects/docs/src/learn/language/classes/index.md b/subprojects/docs/src/learn/language/classes/index.md
new file mode 100644
index 00000000..73108039
--- /dev/null
+++ b/subprojects/docs/src/learn/language/classes/index.md
@@ -0,0 +1,212 @@
+---
+SPDX-FileCopyrightText: 2024 The Refinery Authors
+SPDX-License-Identifier: EPL-2.0
+description: Metamodeling in Refinery
+sidebar_position: 0
+---
+
+# Classes and references
+
+Refinery supports _metamodeling_ to describe the desired structure of generated models.
+
+The metamodeling facilities are inspired by object-oriented software and the [Eclipse Modeling Foundation](https://eclipse.dev/modeling/emf/) (EMF) Core, a lightweight framework for data models.
+The textual syntax in Refinery for defining metamodels is largely compatible with [Xcore](https://wiki.eclipse.org/Xcore), a textual syntax for EMF metamodels.
+
+## Classes
+
+Classes are declared with the `class` keyword.
+
+Like in many programming languages, class members are specified between curly braces `{}`.
+If a class has no members, the declaration may be terminated with a `.` instead.
+
+```refinery
+% Class with no members.
+class Region {}
+
+% Alternative syntax without curly braces.
+class State.
+```
+
+By default, a _new object_ is added to the partial model to represent the instances of a class.
+For example, the new objects `Region::new` and `State::new` represent potential instances of the classes `Region` and `State`, respectively:
+
+import NewObjectsSimple from './NewObjectsSimple.svg';
+
+<NewObjectsSimple />
+
+As you can see, no new objects represent potential nodes that are instanceof of both `Region` and `State`.
+In fact, such instances are not permitted at all.
+Each node must the instance of a _single most-specific class:_
+
+import InvalidInstance from './InvalidInstance.svg';
+
+<InvalidInstance />
+
+### Inheritance
+
+Like in object-oriented programming languages, classes may declare _superclasses_ with the `extends` keyword.
+The inheritance hierarchy may not contain any cycles (a class cannot be a superclass of itself), but _multiple inheritance_ is allowed.
+
+Classes that can't be instantiated directly (i.e., a subclass must be instantiated instead) can be marked with the `abstract` keyword.
+Such classes do not have a _new object,_ since there are no direct instances to represent.
+
+```refinery
+abstract class CompositeElement.
+class Region.
+abstract class Vertex.
+abstract class RegularState extends Vertex.
+class State extends RegularState, CompositeElement.
+```
+
+Notice that the new object `State::new` is an instance of `CompositeElement`, `Vertex`, `RegularState`, and `State` as well.
+
+import NewObjectsWithInheritance from './NewObjectsWithInheritance.svg';
+
+<NewObjectsWithInheritance />
+
+## References
+
+The graph structure of model generated by Refinery is determined by the _references_ of the metamodel, which will appear as labeled edges between nodes (class instances).
+
+References are declared as class members by providing the _target type,_ and optional _multiplicity,_ and the name of the reference:
+
+```refinery
+class Vertex.
+class Transition {
+    Vertex[1] source
+    Vertex[1] target
+}
+```
+
+import ReferencesSimple from './ReferencesSimple.svg';
+
+<ReferencesSimple />
+
+You may add the `refers` keyword for compatibility with [Xcore](https://wiki.eclipse.org/Xcore). The following specification is equivalent:
+
+```refinery
+class Vertex.
+class Transition {
+    refers Vertex[1] source
+    refers Vertex[1] target
+}
+```
+
+### Opposite constraints
+
+The `opposite` keywords specifies that two references are in an _opposite_ relationship, i.e., if one reference is present in a direction, the other must be present between the same nodes in the opposite direction.
+
+```
+class Vertex {
+    Transition[] outgoingTransition opposite source
+    Transition[] incomingTransition opposite target
+}
+class Transition {
+    Vertex[1] source opposite outgoingTransition
+    Vertex[1] target opposite incomingTransition
+}
+```
+
+import ReferencesOppositeInstance from './ReferencesOppositeInstance.svg';
+
+<ReferencesOppositeInstance />
+
+Opposites must be declared in pairs: it is a specification error to declare the `opposite` for one direction but not the other.
+
+Unlike in EMF, references that are the `opposite` of themselves are also supported.
+These must always be present in both directions between two nodes.
+Thus, they correspond to undirected graph edges.
+
+```refinery
+class Person {
+    Person[] friend opposite friend
+}
+```
+
+import ReferencesOppositeSelf from './ReferencesOppositeSelf.svg';
+
+<ReferencesOppositeSelf />
+
+### Multiplicity
+
+_Multiplicity constrains_ can be provided after the reference type in square braces.
+They specify how many _outgoing_ references should exist for any given instance of the class.
+
+:::info
+
+To control the number of _incoming_ references, add an `opposite` reference with multiplicity constraint.
+
+:::
+
+A multiplicity constraint is of the form `[n..m]`, where the non-negative integer `n` is the _lower_ bound of outgoing references,
+and `m` is a positive integer or `*` corresponding to the _upper_ bound of outgoing references.
+The value of `*` represent a reference with _unbounded_ upper multiplicity.
+
+If `n` = `m`, the shorter form `[n]` may be used.
+The bound `[0..*]` may be abbreviated as `[]`.
+If the multiplicity constraint is omitted, the bound `[0..1]` is assumed.
+
+---
+
+In the following model, the node `v1` satisfies all multiplicity constraints of `outgoingTransition`.
+The node `v2` violates the lower bound constraint, while `v3` violates the upper bound constraint.
+All `Transition` instances satisfy the multiplicity constrains associated with `source`.
+
+```refinery
+class Vertex {
+    Transition[2..3] outgoingTransition opposite source
+}
+class Transition {
+    Vertex[1] source opposite outgoingTransition
+}
+```
+
+import MultiplicityConstraintsInstance from './MultiplicityConstraintsInstance.svg';
+
+<MultiplicityConstraintsInstance />
+
+### Containment hierarchy
+
+To structure models and ensure their connectedness, Refinery supports _containment_ constraints.
+
+References may be marked as _containment_ references with the `contains` keyword.
+
+Classes that are the _target type_ of at least one _containment_ reference are considered `contained`.
+An instance of a `contained` class must have exactly 1 incoming containment reference.
+Instances of classes that are not `contained` must _not_ have any incoming containment references.
+
+Containment references have to form a _forest_, i.e., they must not contain any cycles.
+The _roots_ of the forest are instances of classes that are not `contained`, while `contained` classes for the internal nodes and leaves of the trees.
+
+Opposites of _containment_ references have to be marked with the `container` keyword.
+They must not specify any multiplicity constraint, since the multiplicity is already implied by the containment hierarchy.
+
+---
+
+In the following model, the instances of `Region` are the roots of the containment hierarchy.
+The classes `Vertex` are `Transition` are both considered `contained`.
+
+```refinery
+class Region {
+    contains Vertex[] vertices opposite region
+}
+
+class Vertex {
+    container Region region opposite vertices
+    contains Transition[] outgoingTransition opposite source
+    Transition[] incomingTransition opposite target
+}
+
+class Transition {
+    container Vertex source opposite outgoingTransition
+    Vertex[1] target opposite incomingTransition
+}
+```
+
+Containment edges are show with **thick** lines:
+
+import ContainmentInstance from './ContainmentInstance.svg';
+
+<ContainmentInstance />
+
+Containment edges form trees, while non-containment references, such as `target`, may point across the containment hierarchy.