Merge pull request #444 from modelix/docs/modelql-write-support

MODELIX-716 Document write capabilities of typed ModelQL

docs/global/modules/core/pages/howto/modelql-writing.adoc

@@ -0,0 +1,53 @@
+= How-To write via ModelQL
+
+== Writing with the type-safe ModelQL API
+
+The extensions generated by `model-api-gen-gradle` also include functions for write access.
+These can be called on receivers that are instances of `IMonoStep`.
+
+[NOTE]
+--
+Specify the link:../reference/component-model-api-gen-gradle.adoc#model-api-gen-gradle_attributes_modelqlKotlinDir[modelqlKotlinDir] property to enable the generation.
+--
+
+For properties, references and single-valued child links use the `set`-functions.
+
+[source,kotlin]
+--
+client.query { root ->
+    root.children("classes").ofConcept(C_ClassConcept)
+        .member
+        .ofConcept(C_StaticMethodDeclaration)
+        .first()
+        .setName("myNewMethodName".asMono())
+}
+--
+
+To add a new child to multi-valued child links use the generated `addTo`-functions.
+The index parameter is optional: by default the child will be appended at the end.
+In case the target type of the child link is not abstract, the concept parameter can be omitted, because a default value will have been generated.
+
+[source,kotlin]
+--
+client.query { root ->
+    root.children("classes").ofConcept(C_ClassConcept)
+        .first()
+        .addToMember(C_StaticMethodDeclaration, index=1)
+}
+--
+
+To remove a node, you will need to use the untyped API by calling `.untyped().remove()` on the typed node you want to remove.
+
+[source,kotlin]
+--
+client.query { root ->
+    root.children("classes").ofConcept(C_ClassConcept)
+        .first()
+        .untyped()
+        .remove()
+}
+--
+
+== Writing with the untyped ModelQL API
+
+The untyped API is similar to the `INode` API (see `model-api`) and can be accessed by calling `.untyped()`.

docs/global/modules/core/partials/nav-howto.adoc

@@ -3,3 +3,4 @@
 * xref:core:howto/usage-light-model-client.adoc[]
 * xref:core:howto/testing-against-model-api.adoc[]
 * xref:core:howto/modelql.adoc[]
+* xref:core:howto/modelql-writing.adoc[]