From 7988899de13bf1b0d870d4e9722454752cecacdb Mon Sep 17 00:00:00 2001 From: =?utf8?q?Sebastian=20Ho=C3=9F?= Date: Wed, 13 Jul 2022 14:42:48 +0200 Subject: [PATCH] allow to specify front matter specific example code --- .../yosql/model/generator/MarkdownGenerator.java | 26 +++++----- .../src/main/resources/frontmatterSetting.md | 2 +- .../yosql/models/meta/ConfigurationSetting.java | 5 ++ .../java/wtf/metio/yosql/models/meta/data/Sql.java | 56 ++++++++++++++++++++++ 4 files changed, 76 insertions(+), 13 deletions(-) diff --git a/yosql-models/yosql-models-generator/src/main/java/wtf/metio/yosql/model/generator/MarkdownGenerator.java b/yosql-models/yosql-models-generator/src/main/java/wtf/metio/yosql/model/generator/MarkdownGenerator.java index c9617df1..60d130f0 100644 --- a/yosql-models/yosql-models-generator/src/main/java/wtf/metio/yosql/model/generator/MarkdownGenerator.java +++ b/yosql-models/yosql-models-generator/src/main/java/wtf/metio/yosql/model/generator/MarkdownGenerator.java @@ -17,6 +17,7 @@ import java.io.IOException; import java.io.StringWriter; import java.time.LocalDate; import java.util.Comparator; +import java.util.HashMap; import java.util.Map; import java.util.function.Function; @@ -60,18 +61,19 @@ final class MarkdownGenerator { .filter(s -> !s.name().equals(setting.name())) .sorted(Comparator.comparing(ConfigurationSetting::name)) .toList(); - return applyTemplate(settingTemplate, Map.of( - "group", group, - "setting", setting, - "yosqlVersion", yosqlVersion, - "currentDate", LocalDate.now().toString(), - "lower", LOWER_CASE, - "upper", UPPER_CASE, - "kebab", KEBAB_CASE, - "relatedSettings", relatedSettings, - "hasRelatedSettings", !relatedSettings.isEmpty(), - "hasExplanation", setting.explanation().isPresent() - )); + final var scopes = new HashMap(); + scopes.put("group", group); + scopes.put("setting", setting); + scopes.put("frontMatterExampleCode", setting.frontMatterExampleCode().orElse("configValue")); + scopes.put("yosqlVersion", yosqlVersion); + scopes.put("currentDate", LocalDate.now().toString()); + scopes.put("lower", LOWER_CASE); + scopes.put("upper", UPPER_CASE); + scopes.put("kebab", KEBAB_CASE); + scopes.put("relatedSettings", relatedSettings); + scopes.put("hasRelatedSettings", !relatedSettings.isEmpty()); + scopes.put("hasExplanation", setting.explanation().isPresent()); + return applyTemplate(settingTemplate, scopes); } private static String applyTemplate(final Mustache template, final Map scopes) { diff --git a/yosql-models/yosql-models-generator/src/main/resources/frontmatterSetting.md b/yosql-models/yosql-models-generator/src/main/resources/frontmatterSetting.md index 6d13e9b2..7d835f6d 100644 --- a/yosql-models/yosql-models-generator/src/main/resources/frontmatterSetting.md +++ b/yosql-models/yosql-models-generator/src/main/resources/frontmatterSetting.md @@ -47,7 +47,7 @@ generated: true In order to configure this option, place the following code in the front matter of your SQL statement: ```sql --- {{setting.name}}: configValue +-- {{setting.name}}: {{frontMatterExampleCode}} SELECT something FROM your_database_schema WHERE some_column = :some_value diff --git a/yosql-models/yosql-models-meta/src/main/java/wtf/metio/yosql/models/meta/ConfigurationSetting.java b/yosql-models/yosql-models-meta/src/main/java/wtf/metio/yosql/models/meta/ConfigurationSetting.java index b4bff43b..133dc17b 100644 --- a/yosql-models/yosql-models-meta/src/main/java/wtf/metio/yosql/models/meta/ConfigurationSetting.java +++ b/yosql-models/yosql-models-meta/src/main/java/wtf/metio/yosql/models/meta/ConfigurationSetting.java @@ -50,6 +50,11 @@ public interface ConfigurationSetting { Optional explanation(); /** + * @return Example code for the configuration value in the front matter section. + */ + Optional frontMatterExampleCode(); + + /** * @return The optional list of tags associated with this configuration setting. */ List tags(); diff --git a/yosql-models/yosql-models-meta/src/main/java/wtf/metio/yosql/models/meta/data/Sql.java b/yosql-models/yosql-models-meta/src/main/java/wtf/metio/yosql/models/meta/data/Sql.java index c6e64115..6d6e979b 100644 --- a/yosql-models/yosql-models-meta/src/main/java/wtf/metio/yosql/models/meta/data/Sql.java +++ b/yosql-models/yosql-models-meta/src/main/java/wtf/metio/yosql/models/meta/data/Sql.java @@ -259,9 +259,65 @@ public final class Sql extends AbstractConfigurationGroup { return ConfigurationSetting.builder() .setName(name) .setDescription(description) + .setExplanation("This list is empty by default and thus no annotations are added to generated methods.") .addImmutableMethods(immutableMethod(TypicalTypes.listOf(Annotation.class), name, description)) .setMergeCode(CodeBlock.of("$T.mergeAnnotations(first.$L(), second.$L())", Annotation.class, name, name)) .addTags(Tags.FRONT_MATTER) + .addExamples(ConfigurationExample.builder() + .setValue("your.own.Annotation") + .setDescription("In order to add an annotation to the generated methods, specify its fully-qualified name.") + .setResult(""" + package com.example.persistence; + + import your.own.Annotation; + + public class SomeRepository { + + @Annotation + public void someMethod() { + // ... some code + } + + // ... rest of generated code + + } + """) + .build()) + .addExamples(ConfigurationExample.builder() + .setValue("your.other.Annotation") + .setDescription("In order to add an annotation with some member, specify name of the annotation member, its value, and its type. The type defaults to `java.lang.String`.") + .setResult(""" + package com.example.persistence; + + import your.other.Annotation; + + public class SomeRepository { + + @Annotation(member = "value") + public void someMethod() { + // ... some code + } + + // ... rest of generated code + + } + """) + .build()) + .setFrontMatterExampleCode(""" + + -- - type: your.own.Annotation + -- members: + -- - key: someMember + -- value: this is your value + -- type: java.lang.String + -- - key: another + -- value: 5 + -- type: int + -- - type: your.other.Annotation + -- members: + -- - key: value + -- value: yep + -- - type: some.annotation.WithoutMembers""") .build(); } -- 2.11.4.GIT