0.2.9

- add pages documentation
- propagate jastAddList option to ragconnect
- add logIncremental to ragconnect

.gitlab-ci.yml

@@ -19,6 +19,15 @@ build:
   script:
     - ./gradlew assemble
 
+createDoc:
+  image: openjdk:11
+  stage: build
+  script:
+    - "./gradlew :run"
+  artifacts:
+    paths:
+      - "pages/doc/config.md"
+
 publish:
   image: openjdk:11
   stage: publish
@@ -26,3 +35,19 @@ publish:
     - "./gradlew publishPluginMavenPublicationToMavenRepository"
   only:
     - master
+
+pages:
+  image: python:3.8-buster
+  stage: publish
+  needs:
+    - createDoc
+  before_script:
+    - pip install -U mkdocs mkdocs-macros-plugin mkdocs-git-revision-date-localized-plugin
+  script:
+    - cd pages && mkdocs build
+  only:
+    - dev
+    - master
+  artifacts:
+    paths:
+      - public

build.gradle

@@ -4,7 +4,7 @@ plugins {
 }
 
 group 'org.jastadd.preprocessor'
-version '0.2.8'
+version '0.2.9'
 
 gradlePlugin {
     plugins {

pages/.gitignore

+/doc/config.md
+__pycache__

pages/custom_theme/footer.html

+{% block footer %}
+<p>{% if config.copyright %}
+    <small>{{ config.copyright }}<br></small>
+    {% endif %}
+<hr>
+Built with <a href="https://www.mkdocs.org/">MkDocs</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
+{% if page and page.meta and page.meta.git_revision_date_localized %}
+<small><br><i>Last updated {{ page.meta.git_revision_date_localized }}</i></small>
+{% endif %}
+</p>
+{% endblock %}

pages/doc/index.md

+# Gradle Plugin for JastAdd preprocessors
+
+This [Gradle plugin](https://git-st.inf.tu-dresden.de/jastadd/testing) is providing means to write Gradle tasks to invoke the two preprocessors [Relast]() and [RagConnect](https://jastadd.pages.st.inf.tu-dresden.de/ragconnect) as well as [JastAdd](http://jastadd.org/) itself.
+
+To use this plugin, add the following to your `build.gradle`:
+
+```groovy
+buildscript {
+    repositories {
+        mavenCentral()
+        maven {
+            name "gitlab-maven"
+            url "https://git-st.inf.tu-dresden.de/api/v4/groups/jastadd/-/packages/maven"
+        }
+    }
+    dependencies {
+        classpath 'org.jastadd.preprocessor:testing:0.2.8'
+    }
+}
+
+import org.jastadd.preprocessor.testing.plugin.PreprocessorPlugin
+import org.jastadd.preprocessor.testing.plugin.RagConnectTest
+
+apply plugin: PreprocessorPlugin
+```
+
+A typical usage (taken from tests used for RagConnect) looks as follows:
+
+```groovy
+task compileTreeIncremental(type: RagConnectTest) {
+    ragconnect {
+        outputDir = file('src/test/02-after-ragconnect/treeInc')
+        inputFiles = [file('src/test/01-input/tree/Test.relast'),
+                      file('src/test/01-input/tree/Test.connect')]
+        rootNode = 'Root'
+        logWrites = true
+    }
+    relast {
+        useJastAddNames = true
+        grammarName = 'src/test/03-after-relast/treeInc/treeInc'
+        serializer = 'jackson'
+    }
+    jastadd {
+        jastAddList = 'JastAddList'
+        packageName = 'treeInc.ast'
+        inputFiles = [file('src/test/01-input/tree/Test.jadd')]
+        extraOptions = ['--tracing=cache,flush',
+                        '--incremental=param',
+                        '--cache=all',
+                        '--rewrite=cnta',
+                        '--flush=full']
+    }
+}
+```
+
+Available options are listed at [configuration](/config).
+Notably, all options passed to JastAdd are also passed to the preprocessors, and generated files are handled correctly, e.g., generated aspects are passed to JastAdd automatically.
+
+The compilers to be used can be configured as follows:
+
+```groovy
+preprocessorTesting {
+    //noinspection GroovyAssignabilityCheck
+    relastCompilerLocation = '../libs/relast.jar'
+    ragconnectCompilerLocation = '../libs/ragconnect.jar'
+}
+```
+
+By default, the compilers are expected to be available in the classpath.

pages/main.py

+buildGradle = '../build.gradle'
+
+
+def get_version():
+    with open(buildGradle) as fd:
+        for line in fd.readlines():
+            # look for line `version 'Major.Minor.Patch'`
+            if line.startswith('version '):
+                return line[9:-2]
+    return '?'
+
+
+def define_env(env):
+    """
+    This is the hook for defining variables, macros and filters
+
+    - variables: the dictionary that contains the environment variables
+    - macro: a decorator function, to declare a macro.
+    """
+    env.conf['site_name'] = 'Gradle Plugin RelastTest ' + get_version()
+
+
+if __name__ == '__main__':
+    print(get_version())

pages/mkdocs.yml

+site_name: Gradle Plugin RelastTest
+nav:
+  - using.md
+  - API documentation: ragdoc/index.html
+theme:
+  name: readthedocs
+  custom_dir: custom_theme/
+plugins:
+  - search
+  - git-revision-date-localized:
+      type: datetime
+      timezone: Europe/Berlin
+      locale: en
+      fallback_to_build_date: True
+  - macros
+repo_url: https://git-st.inf.tu-dresden.de/jastadd/preprocessors/coverage-generator
+site_dir: ../public

src/main/java/org/jastadd/preprocessor/testing/doc/DocumentationCreator.java

+package org.jastadd.preprocessor.testing.doc;
+
+import org.gradle.api.tasks.Input;
+import org.gradle.api.tasks.InputFiles;
+import org.gradle.api.tasks.Optional;
+import org.gradle.api.tasks.OutputDirectory;
+import org.jastadd.preprocessor.testing.plugin.Description;
+import org.jastadd.preprocessor.testing.plugin.JastAddConfiguration;
+import org.jastadd.preprocessor.testing.plugin.RagConnectConfiguration;
+import org.jastadd.preprocessor.testing.plugin.RelastConfiguration;
+
+import java.io.BufferedWriter;
+import java.io.IOException;
+import java.lang.reflect.Method;
+import java.nio.file.Files;
+import java.nio.file.Paths;
+import java.nio.file.StandardOpenOption;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+import java.util.PriorityQueue;
+
+public class DocumentationCreator {
+  private static final String HEADER = "# Configuration options\n\n";
+  private static final List<Map.Entry<String, Class<?>>> entitiesToBeDocumented = new ArrayList<>() {{
+    add(Map.entry("RagConnect Configuration", RagConnectConfiguration.class));
+    add(Map.entry("Relast Configuration", RelastConfiguration.class));
+    add(Map.entry("JastAdd Configuration", JastAddConfiguration.class));
+  }};
+  private static final String outputFile = "pages/doc/config.md";
+
+  public static void main(String[] args) {
+    new DocumentationCreator().run();
+  }
+
+  protected void run() {
+    PriorityQueue<String[]> options = new PriorityQueue<>((e1, e2) -> {
+      if (e1[1].equals("Yes")) {
+        if (e2[1].equals("Yes")) {
+          return e1[0].compareTo(e2[0]);
+        }
+        return -1;
+      }
+      if (e2[1].equals("Yes")) {
+        return 1;
+      }
+      return e1[0].compareTo(e2[0]);
+    });
+    try(BufferedWriter writer = Files.newBufferedWriter(Paths.get(outputFile),
+        StandardOpenOption.CREATE, StandardOpenOption.TRUNCATE_EXISTING)) {
+      writer.write(HEADER);
+      for (Map.Entry<String, Class<?>> entry : entitiesToBeDocumented) {
+        options.clear();
+        writer.write("## " + entry.getKey() + "\n\n");
+        writer.write("Name | Required? | Corresponding parameter | Description\n");
+        writer.write("--- | --- | --- | ---\n");
+        for (Method method : entry.getValue().getMethods()) {
+          if (method.isAnnotationPresent(Input.class) ||
+              method.isAnnotationPresent(InputFiles.class) ||
+              method.isAnnotationPresent(OutputDirectory.class)) {
+            String name = nameOfOption(method.getName());
+            String required = method.isAnnotationPresent(Optional.class) ? "No" : "Yes";
+            final String parameter, description;
+            if (method.isAnnotationPresent(Description.class)) {
+              Description descriptionAnnotation = method.getAnnotation(Description.class);
+              if (descriptionAnnotation.skip()) {
+                continue;
+              }
+              if (descriptionAnnotation.correspondingParameter().isBlank()) {
+                parameter = "";
+              } else {
+                parameter = "`" + descriptionAnnotation.correspondingParameter() + "`";
+              }
+              description = descriptionAnnotation.value();
+            } else {
+              parameter = "";
+              description = "_not provided_";
+            }
+            options.add(new String[]{name, required, parameter, description});
+          }
+        }
+        while(!options.isEmpty()) {
+          String[] option = options.poll();
+          String toWrite = String.format("%s | %s | %s | %s%n", (Object[]) option);
+          writer.write(toWrite);
+        }
+        writer.write("\n\n");
+      }
+    } catch (IOException e) {
+      e.printStackTrace();
+    }
+  }
+
+  private String nameOfOption(String methodName) {
+    if (methodName == null || methodName.isEmpty()) { return methodName; }
+    final String s;
+    if (methodName.startsWith("get")) {
+      s = methodName.substring(3);
+    } else if (methodName.startsWith("is")) {
+      s = methodName.substring(2);
+    } else {
+      throw new RuntimeException("Unknown prefix in method " + methodName);
+    }
+    return Character.toLowerCase(s.charAt(0)) + s.substring(1);
+  }
+}

src/main/java/org/jastadd/preprocessor/testing/plugin/Description.java

+package org.jastadd.preprocessor.testing.plugin;
+
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+
+@Retention(RetentionPolicy.RUNTIME)
+public @interface Description {
+  String value();
+  String correspondingParameter() default "";
+  boolean skip() default false;
+}

src/main/java/org/jastadd/preprocessor/testing/plugin/JastAddConfiguration.java

@@ -15,20 +15,24 @@ import java.util.List;
  */
 public interface JastAddConfiguration {
 
+  @Description(value = "Package name of AST files", correspondingParameter = "--package")
   @Input
   String getPackageName();
   void setPackageName(String packageName);
 
+  @Description(value = "Name of the List class", correspondingParameter = "--List")
   @Optional
   @Input
   String getJastAddList();
   void setJastAddList(String jastAddList);
 
+  @Description(value = "Do not run JastAdd")
   @Optional
   @Input
   boolean isSkipRun();
   void setSkipRun(boolean skipRun);
 
+  @Description(value = "Add more options not directly supported")
   @Optional
   @Input
   List<String> getExtraOptions();
@@ -37,19 +41,25 @@ public interface JastAddConfiguration {
     return getExtraOptions() != null ? getExtraOptions() : Collections.emptyList();
   }
 
+  @Description(value = "Add new input files to be processed")
   @Optional
   @InputFiles
   List<File> getInputFiles();
   void setInputFiles(List<File> inputFiles);
 
+  @Description(value = "Output directory (defaults to `src/test/java-gen`)", correspondingParameter = "--o")
   @Optional
   @OutputDirectory
   File getOutputDir();
   void setOutputDir(File outputDir);
+
+  @Description(value = "_only used internally_", skip = true)
   @OutputDirectory
   default File getOutputDirOrDefault() {
     return getOutputDir() != null ? getOutputDir() : Paths.get("src", "test", "java-gen").toFile();
   }
+
+  @Description(value = "_only used internally_", skip = true)
   @OutputDirectory
   default File getPackageOutputDir() {
     return getOutputDirOrDefault().toPath().resolve(getPackageName().replace('.', File.separatorChar)).toFile();

src/main/java/org/jastadd/preprocessor/testing/plugin/RagConnectConfiguration.java

@@ -14,35 +14,54 @@ import java.util.List;
  */
 public interface RagConnectConfiguration {
 
+  @Description(value = "Sets the root node", correspondingParameter = "--rootNode")
   @Input
   String getRootNode();
   void setRootNode(String rootNode);
 
+  @Description(value = "Sets the output directory", correspondingParameter = "--o")
   @Input
   String getOutputDir();
   void setOutputDir(String outputDir);
 
+  @Description(value = "Add new input files to be processed")
   @InputFiles
   List<File> getInputFiles();
   void setInputFiles(List<File> inputFiles);
 
+  @Description(value = "Log read endpoints", correspondingParameter = "--logReads")
   @Optional
   @Input
   boolean isLogReads();
   void setLogReads(boolean logReads);
 
+  @Description(value = "Log write endpoints", correspondingParameter = "--logWrites")
   @Optional
   @Input
   boolean isLogWrites();
   void setLogWrites(boolean logWrites);
 
+  @Description(value = "Log incremental activities", correspondingParameter = "--logIncremental")
+  @Optional
+  @Input
+  boolean isLogIncremental();
+  void setLogIncremental(boolean loggIncremental);
+
+  @Description(value = "Be more verbose during compilation", correspondingParameter = "--verbose")
   @Optional
   @Input
   boolean isVerbose();
   void setVerbose(boolean verbose);
 
+  @Description(value = "Set protocols to be used", correspondingParameter = "--protocols")
   @Optional
   @Input
   List<String> getProtocols();
   void setProtocols(List<String> protocols);
+
+  @Description(value = "Add more options not directly supported")
+  @Optional
+  @Input
+  List<String> getAdditionalOptions();
+  void setAdditionalOptions(List<String> additionalOptions);
 }

src/main/java/org/jastadd/preprocessor/testing/plugin/RagConnectTest.java

@@ -108,12 +108,18 @@ public abstract class RagConnectTest extends RelastTest {
         if (getRagconnect().isLogWrites()) {
           args.add("--logWrites");
         }
+        if (getRagconnect().isLogIncremental()) {
+          args.add("--logIncremental");
+        }
         if (getRagconnect().isVerbose()) {
           args.add("--verbose");
         }
         if (getRagconnect().getProtocols() != null && !getRagconnect().getProtocols().isEmpty()) {
           args.add("--protocols=" + String.join(",", getRagconnect().getProtocols()));
         }
+        if (getJastadd().getJastAddList() != null) {
+          args.add("--jastAddList=" + getJastadd().getJastAddList());
+        }
         args.addAll(getJastadd().getExtraOptionsOrDefault());
         args.addAll(getRagconnect().getInputFiles());
         javaExecSpec.args(args);

src/main/java/org/jastadd/preprocessor/testing/plugin/RelastConfiguration.java

@@ -14,40 +14,48 @@ import java.util.List;
  */
 public interface RelastConfiguration {
 
+  @Description(value = "Use JastAdd like API for relations", correspondingParameter = "--useJastAddNames")
   @Optional
   @Input
   boolean isUseJastAddNames();
   void setUseJastAddNames(boolean useJastAddNames);
 
+  @Description(value = "Name of resulting grammar (can be a path)", correspondingParameter = "--grammarName")
   @Input
   String getGrammarName();
   void setGrammarName(String grammarName);
 
+  @Description(value = "Add new input files to be processed")
   @Optional
   @InputFiles
   List<File> getInputFiles();
   void setInputFiles(List<File> inputFiles);
 
+  @Description(value = "Do not write any files", correspondingParameter = "--file")
   @Optional
   @Input
   boolean isNoWriteToFile();
   void setNoWriteToFile(boolean noWriteToFile);
 
+  @Description(value = "Do not generate resolverHelper", correspondingParameter = "--resolverHelper")
   @Optional
   @Input
   boolean isNoResolverHelper();
   void setNoResolverHelper(boolean noResolverHelper);
 
+  @Description(value = "Class to be used for relations", correspondingParameter = "--listClass")
   @Optional
   @Input
   String getListClass();
   void setListClass(String listClass);
 
+  @Description(value = "Activate serialization, and set its implementation", correspondingParameter = "--serializer")
   @Optional
   @Input
   String getSerializer();
   void setSerializer(String serializer);
 
+  @Description(value = "Be more verbose during compilation")
   @Optional
   @Input
   boolean isVerbose();