Add getting started for cd generator

.gitignore

@@ -5,6 +5,7 @@ gen/
 .settings/
 .classpath
 *.log
+*.pyc
 *.iml
 .idea/
 .gradle
@@ -14,6 +15,7 @@ gradlew
 gradlew.bat
 ~$*
 .intellijPlatform/
+docs_wd
 
 # AI
 .claude/**

README.md

@@ -39,7 +39,7 @@ Similarly, the IntelliJ plugin is provided as a `.zip` file and can be installed
 
 ## An Example Model
 
-The following example CD [`MyCompany`](doc/MyCompany.cd) illustrates the textual 
+The following example CD [`MyCompany`](docs/MyCompany.cd) illustrates the textual 
 syntax of CDs:
 ```
 package corp;
@@ -143,7 +143,7 @@ java -jar MCCD.jar -i src/MyLife.cd --path symbols -pp
 ```
 
 To try them out for yourself download and put the files
-[MyCompany.cd](doc/MyCompany.cd), [MyAddress.cd](doc/MyAddress.cd), and [MyLife.cd](doc/MyLife.cd) into your `src` directory. 
+[MyCompany.cd](docs/MyCompany.cd), [MyAddress.cd](docs/MyAddress.cd), and [MyLife.cd](docs/MyLife.cd) into your `src` directory. 
 The second command needs to be executed before the third.
 
 The possible options are:
@@ -177,12 +177,12 @@ The possible options are:
 | `--reference <file>`             | Parses the file as a reference CD and checks if the the input CD specified by `-i` is conform to it.                                                                                                                                                                                                                                                                                                                                                   |
 | `--map <string>`                 | Specifies the names of stereotypes that are used as incarnation mappings in the concrete model. Default: 'incarnates'                                                                                                                                                                                                                                                                                                                                  |
 | `--complete`                     | Completes a possible incomplete CD specified by `-i` such that it conforms to the reference CD specified by `--reference`.                                                                                                                                                                                                                                                                                                                             |
-| `--ref-param`                    | Specifies the conformance parameters to use for reference CD conformance checking and completion. Default: 'INHERITANCE, METHOD_OVERLOADING, SRC_TARGET_ASSOC_MAPPING, NAME_MAPPING, ALLOW_CARD_RESTRICTION, STEREOTYPE_MAPPING'                                                                                                                                                                                                                       |
+| `--ref-param`                    | Specifies the conformance parameters to use for reference CD conformance checking and completion. Default: 'INHERITANCE, METHOD_OVERLOADING, SRC_TARGET_ASSOC_MAPPING, NAME_MAPPING, ALLOW_CARD_RESTRICTION, STYPE_MAPPING'                                                                                                                                                                                                                       |
 | `--anytype`                      | Specifies the placeholder type name used for underspecified types in the reference CD specified by `--reference`. Default: 'anytype'.                                                                                                                                                                                                                                                                                                                  |
 
 ### Building the Tool from the Sources (if desired)
 
-As alternative to a download, 
+As an alternative to a download, 
 it is possible to build an executable JAR of the tool from the source files
 located in GitHub.
 Make sure you have installed the following dependencies:
@@ -239,7 +239,7 @@ all context conditions.
 
 If you want to try this out yourself, copy the `MCCD.jar` into a directory of 
 your choice. Then create a text file `src/MyExample.cd` 
-([also available here](doc/MyExample.cd)) in a `src` subdirectory of the
+([also available here](docs/MyExample.cd)) in a `src` subdirectory of the
 directory where `MCCD.jar` is located containing e.g. the following simple CD 
 (please note that, like in Java, filename and model name in the file have to be
 the same):
@@ -384,7 +384,7 @@ The CD languages are participating in the symbol exchange infrastructure.
 We import a symbol file defining type symbols that are used by a CD.
 
 Let us now consider the example `MyLife` from above.
-Please, copy the file [`MyLife.cd`](doc/MyLife.cd) and save it 
+Please, copy the file [`MyLife.cd`](docs/MyLife.cd) and save it 
 in a file `src/monticore/MyLife.cd`.
 
 Execute the following command for processing the file `MyLife.cd`:
@@ -402,7 +402,7 @@ the model:
 
 The missing class `Address` is currently not imported.
 `MyLife` already has an `import` statement to another class diagram 
-included ([available here](doc/MyAddress.cd)):
+included ([available here](docs/MyAddress.cd)):
 
 (content of src/MyAddress.cd)
 ```
@@ -474,7 +474,7 @@ java -jar MCCD.jar -i src/MyExample.cd --gen -o out
 Note that the option `--fieldfromrole` must be used with the appropriate
 argument in order to generate attributes for associations contained in the input CD. 
 Use the following commands in order to generate .java-files for the CD 
-`MyCompany`([available here](doc/MyCompany.cd)):
+`MyCompany`([available here](docs/MyCompany.cd)):
 
 ```shell
 java -jar MCCD.jar -i src/MyCompany.cd -o out --gen --fieldfromrole navigable
@@ -493,12 +493,12 @@ The option `--semdiff <file>` computes the semantic difference of the current
 CD in memory and the CD specified by the argument.
 
 For the following examples, download the files 
-[MyEmployees1.cd](doc/MyEmployees1.cd) and [MyEmployees2.cd](doc/MyEmployees2.cd) 
+[MyEmployees1.cd](docs/MyEmployees1.cd) and [MyEmployees2.cd](docs/MyEmployees2.cd) 
 and save them in
 `src`:
 
 ```shell
-java -jar MCCD.jar -i src/MyEmployees1.cd --semdiff scr/MyEmployees2.cd
+java -jar MCCD.jar -i src/MyEmployees1.cd --semdiff src/MyEmployees2.cd
 ```
 
 We can use the option `difflimit` to specify the maximum number of witnesses 
@@ -524,7 +524,7 @@ argument iff the two are semantically compatible
 The result is stored in memory as the current CD.
 
 For the following examples, download the files 
-[Teaching.cd](doc/Teaching.cd) and [Management.cd](doc/Management.cd) and 
+[Teaching.cd](docs/Teaching.cd) and [Management.cd](docs/Management.cd) and 
 save them in `src`:
 
 ```shell

cdlang/src/main/java/de/monticore/cd/codegen/decorators/AbstractMethodDecorator.java

@@ -1,13 +1,18 @@
 /* (c) https://github.com/MontiCore/monticore */
 package de.monticore.cd.codegen.decorators;
 
+import de.monticore.cd.codegen.TopDecorator;
 import de.monticore.cd.codegen.decorators.data.AbstractDecorator;
 import de.monticore.cd.methodtemplates.CD4C;
+import de.monticore.cd4code.CD4CodeMill;
 import de.monticore.cd4code._visitor.CD4CodeTraverser;
 import de.monticore.cd4codebasis._ast.ASTCDClass;
 import de.monticore.cd4codebasis._ast.ASTCDMethod;
 import de.monticore.cd4codebasis._visitor.CD4CodeBasisVisitor2;
 import de.monticore.generating.templateengine.TemplateHookPoint;
+import de.monticore.umlstereotype._ast.ASTStereoValue;
+import de.monticore.umlstereotype._ast.ASTStereotype;
+
 import java.util.Stack;
 
 /**
@@ -49,6 +54,16 @@ public void visit(ASTCDMethod method) {
 
         // And also mark the parent (class) as abstract
         decoratorData.getAsDecorated(classStack.peek()).getModifier().setAbstract(true);
+
+        // Add TOPTrafo.NEEDS_TOP_IDENTIFIER stereotype for improved error messages
+        if (!classStack.peek().getModifier().isAbstract()) {
+          ASTStereoValue astStereoValue = TopDecorator.NEEDS_TOP_STEREO_BUILDER.apply(
+              "In the class %s a method needs to be topped");
+          ASTStereotype astStereotype = CD4CodeMill.stereotypeBuilder().addValues(astStereoValue)
+              .build();
+          decoratorData.getAsDecorated(classStack.peek()).getModifier().setStereotype(
+              astStereotype);
+        }
       }
       else {
         // static methods can not be turned abstract:
@@ -57,8 +72,6 @@ public void visit(ASTCDMethod method) {
             decoratorData.getAsDecorated(method), new TemplateHookPoint(
                 "methods.EmptyBodyThrowError")));
       }
-      // We could add the TOPTrafo.NEEDS_TOP_IDENTIFIER stereotype for improved error messages,
-      // but we have to ensure quickFail is disabled during the TOPTrafo
     }
   }
 

cdlang/src/main/java/de/monticore/cdgen/CDGenTool.java

@@ -150,7 +150,7 @@ else if (!cmd.hasOption("i") || cmd.hasOption("h")) {
         }
       }
 
-      if (cmd.hasOption("o")) {
+      if (cmd.hasOption("o") || cmd.hasOption("pp")) {
         // Where to load additional templates from
         List<File> additionalTemplatePaths = cmd.hasOption("fp") ? Arrays.stream(cmd
             .getOptionValues("fp")).map(Paths::get).map(Path::toFile).collect(Collectors.toList())
@@ -182,7 +182,10 @@ else if (!cmd.hasOption("i") || cmd.hasOption("h")) {
                 // If required, we also output the symbol table of the *decorated* AST
                 this.createAndExportDecoratedSymbolTable(decorated, cmd.getOptionValue("sd"));
               }
-            }, asts);
+              if (cmd.hasOption("pp")) {
+                this.prettyPrint(decorated, Paths.get(cmd.getOptionValue("pp")).toString());
+              }
+            }, asts, cmd.hasOption("o"));
       }
     }
     catch (ParseException e) {
@@ -224,7 +227,7 @@ public void initializeDecConf(GlobalExtensionManagement glex, DecoratorConfig de
   public void decorateAndGenerate(GlobalExtensionManagement glex,
       Consumer<DecoratorConfig> initializeDecConf, GeneratorSetup setup,
       Runnable initDecoratedGlobalScope, Consumer<ASTCDCompilationUnit> postDecorate,
-      Collection<ASTCDCompilationUnit> asts) {
+      Collection<ASTCDCompilationUnit> asts, boolean doGenerate) {
     glex.setGlobalValue("cdPrinter", new CdUtilsPrinter());
     glex.setGlobalValue("mcTypeFacade", MCTypeFacade.getInstance()); // TODO: Remove from templates
     glex.setGlobalValue("cdGenService", new CDGenService());
@@ -274,7 +277,9 @@ public void decorateAndGenerate(GlobalExtensionManagement glex,
       topTransformer.addToTraverser(t);
       decorated.get().accept(t);
 
-      generator.generate(decorated.get());
+      if (doGenerate) {
+        generator.generate(decorated.get());
+      }
       Log.enableFailQuick(qf); // reset quick-fail
     }
   }
@@ -377,6 +382,9 @@ public Options addAdditionalOptions(Options options) {
         .argName("file").hasArg().desc(
             "Serializes the decorated symbol table of the given artifact.").build());
 
+    options.addOption(org.apache.commons.cli.Option.builder("pp").longOpt("prettyprint").argName(
+        "file").hasArg().desc("Pretty prints the decorated AST to the given file.").build());
+
     return options;
   }
 

cdlang/src/test/java/de/monticore/cd/cdgen/AbstractDecoratorTest.java

@@ -95,7 +95,9 @@ public TestResult doTest(ASTCDCompilationUnit cd) {
           tool.completeSymbolTable(decorated);
 
           results.add(new TestResult(decorated, decoratedScope));
-        }, List.of(cd));
+        }, List.of(cd),
+
+        true);
 
     System.out.println("Wrote CDGenTest results to " + outputDir.getAbsolutePath());
 

cdlang/src/test/java/de/monticore/cd/cdgen/AbstractMethodDecoratorTest.java

@@ -0,0 +1,74 @@
+/* (c) https://github.com/MontiCore/monticore */
+package de.monticore.cd.cdgen;
+
+import de.monticore.cd.codegen.DecoratorConfig;
+import de.monticore.cd4code.CD4CodeMill;
+import de.monticore.generating.GeneratorSetup;
+import de.monticore.generating.templateengine.GlobalExtensionManagement;
+import de.monticore.io.paths.MCPath;
+import de.monticore.runtime.junit.MCAssertions;
+import de.se_rwth.commons.logging.Log;
+import org.junit.jupiter.api.Assertions;
+import org.junit.jupiter.api.Test;
+
+import java.io.IOException;
+import java.util.Optional;
+
+public class AbstractMethodDecoratorTest extends AbstractDecoratorTest {
+
+  @Override
+  protected Optional<MCPath> getHandWrittenPath() {
+    // The path should point to the root of the handwritten source folder,
+    // not to the package folder itself.
+    return Optional.of(new MCPath("src/test/resources/de/monticore/cd/codegen/hwc"));
+  }
+
+  @Test
+  public void testNotTopped() throws IOException {
+    var opt = CD4CodeMill.parser().parse_String("""
+        classdiagram TestAbstractMethodDecoratorNotTopped {
+          abstract class Asset {
+            void process();
+          }
+
+          class Task extends Asset {
+            void process();
+          }
+        }
+        """);
+    Assertions.assertTrue(opt.isPresent());
+
+    super.doTest(opt.get());
+
+    MCAssertions.assertHasFinding(f -> f.getMsg().contains("0xC0FFEE00"));
+    Log.clearFindings();
+  }
+
+  @Test
+  public void testTopped() throws Exception {
+    var opt = CD4CodeMill.parser().parse_String("""
+        classdiagram TestAbstractMethodDecoratorTopped {
+          abstract class Asset {
+            void process();
+          }
+
+          class Task extends Asset {
+            void process();
+          }
+        }
+        """);
+    Assertions.assertTrue(opt.isPresent());
+
+    super.doTest(opt.get());
+
+    MCAssertions.assertNoFindings();
+  }
+
+  @Override
+  public void initializeDecConf(GlobalExtensionManagement glex, DecoratorConfig config,
+      GeneratorSetup setup) {
+    config.withCopyCreator().defaultApply();
+    config.withAbstractMethodSignatures().defaultApply();
+  }
+
+}

cdlang/src/test/java/de/monticore/cd/cdgen/DefaultCD2PojoDecoratorTest.java

@@ -33,7 +33,8 @@ public void testAll() throws Exception {
 
     super.doTest(opt.get());
 
-    MCAssertions.assertNoFindings();
+    //because the class diagram contains methods which are not topped by the TOP-Mechanism, we still get errors here
+    MCAssertions.assertHasFindingsStartingWith("0xC0FFEE00");
   }
 
   @Override

cdlang/src/test/resources/de/monticore/cd/codegen/hwc/TestAbstractMethodDecoratorTopped/Task.java

@@ -0,0 +1,8 @@
+package TestAbstractMethodDecoratorTopped;
+
+public class Task extends TaskTOP {
+  @Override
+  public void process() {
+    // Handwritten implementation
+  }
+}

cdtool/cdgradle/src/test/resources/cdgradle-it/src/main/java/MyCD/AbstractClassIml.java

@@ -0,0 +1,16 @@
+/* (c) https://github.com/MontiCore/monticore */
+package MyCD;
+
+public class AbstractClassIml extends AbstractClassImlTOP{
+
+  @Override
+  public void doY() {
+    System.out.println("Y");
+  }
+
+  @Override
+  public void doX() {
+    System.out.println("X");
+  }
+
+}