Add example yaml value type.

Author: RezzedUp

config-values-bukkit/src/main/java/community/leaf/configvalues/bukkit/ExampleYamlValue.java

@@ -0,0 +1,18 @@
+/*
+ * Copyright © 2021, RezzedUp <https://github.com/LeafCommunity/ConfigValues>
+ *
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ */
+package community.leaf.configvalues.bukkit;
+
+import com.rezzedup.util.constants.types.TypeCapture;
+
+public interface ExampleYamlValue<V> extends DefaultYamlValue<V>
+{
+    static TypeCapture<ExampleYamlValue<?>> type()
+    {
+        return YamlValues.EXAMPLE_TYPE;
+    }
+}

config-values-bukkit/src/main/java/community/leaf/configvalues/bukkit/YamlValue.java

@@ -100,5 +100,7 @@ interface Builder<V>
         YamlValue<V> maybe();
 
         DefaultYamlValue<V> defaults(V value);
+        
+        ExampleYamlValue<V> example(V value);
     }
 }

config-values-bukkit/src/main/java/community/leaf/configvalues/bukkit/YamlValues.java

@@ -30,6 +30,8 @@ final class YamlValues
 
     static final TypeCapture<DefaultYamlValue<?>> DEFAULT_TYPE = new TypeCapture<>() {};
 
+    static final TypeCapture<ExampleYamlValue<?>> EXAMPLE_TYPE = new TypeCapture<>() {};
+    
     //
     //  Builders
     //
@@ -74,6 +76,12 @@ public DefaultYamlValue<V> defaults(V def)
         {
             return new DefaultImpl<>(key, accessor, migrations, def);
         }
+    
+        @Override
+        public ExampleYamlValue<V> example(V example)
+        {
+            return new ExampleImpl<>(key, accessor, migrations, example);
+        }
     }
 
     //
@@ -120,4 +128,12 @@ static class DefaultImpl<V> extends MaybeImpl<V> implements DefaultYamlValue<V>
         @Override
         public V getDefaultValue() { return def; }
     }
+    
+    static class ExampleImpl<V> extends DefaultImpl<V> implements ExampleYamlValue<V>
+    {
+        ExampleImpl(String key, YamlAccessor<V> accessor, @NullOr List<Migration> migrations, V example)
+        {
+            super(key, accessor, migrations, example);
+        }
+    }
 }

config-values-bukkit/src/main/java/community/leaf/configvalues/bukkit/data/YamlDataFile.java

@@ -8,6 +8,7 @@
 package community.leaf.configvalues.bukkit.data;
 
 import community.leaf.configvalues.bukkit.DefaultYamlValue;
+import community.leaf.configvalues.bukkit.ExampleYamlValue;
 import community.leaf.configvalues.bukkit.YamlValue;
 import community.leaf.configvalues.bukkit.migrations.Migration;
 import org.bukkit.configuration.ConfigurationSection;
@@ -38,6 +39,7 @@ public class YamlDataFile implements UpdatableYamlDataSource
     private int reloads = 0;
     private boolean isLoaded = false;
     private boolean isUpdated = false;
+    private boolean isNewlyCreated = false;
     private @NullOr Exception invalid = null;
     private @NullOr Runnable reloadHandler = null;
 
@@ -68,6 +70,8 @@ public YamlDataFile(Path directoryPath, String name, Consumer<Exception> excepti
     @Override
     public void updated(boolean state) { this.isUpdated = state; }
 
+    public boolean isNewlyCreated() { return isNewlyCreated; }
+    
     public boolean isInvalid() { return invalid != null; }
 
     public @NullOr Exception getInvalidReason() { return invalid; }
@@ -107,7 +111,11 @@ public final void reload()
 
     public void save()
     {
+        boolean pre = Files.isRegularFile(getFilePath());
         write(getFilePath(), toYamlString(), exceptions);
+        boolean post = Files.isRegularFile(getFilePath());
+        
+        this.isNewlyCreated = !pre && post;
     }
 
     public void backupThenSave(Path backupsDirectoryPath, String additionalNameInfo)
@@ -127,6 +135,11 @@ public void backupThenSave(Path backupsDirectoryPath, String additionalNameInfo)
         save();
     }
 
+    public void backupThenSave(Path backupsDirectoryPath)
+    {
+        backupThenSave(backupsDirectoryPath, "");
+    }
+    
     public String header()
     {
         @NullOr String header = data.options().header();
@@ -184,8 +197,15 @@ public void defaultValues(List<YamlValue<?>> defaults)
         for (YamlValue<?> value : defaults)
         {
             migrate(value, data);
-            if (!(value instanceof DefaultYamlValue<?>)) { continue; }
-            setAsDefaultIfUnset((DefaultYamlValue<?>) value);
+            
+            if (value instanceof DefaultYamlValue<?>)
+            {
+                // Successfully loaded values from disk already, don't set example value.
+                // Examples should only be set when the file is created for the first time.
+                if (value instanceof ExampleYamlValue<?> && isLoaded) { continue; }
+                
+                setAsDefaultIfUnset((DefaultYamlValue<?>) value);
+            }
         }
     }
 

examples/config-values-example-bukkit/src/main/java/community/leaf/examples/configvalues/bukkit/Config.java

@@ -3,6 +3,7 @@
 import com.rezzedup.util.constants.Aggregates;
 import com.rezzedup.util.constants.annotations.AggregatedResult;
 import community.leaf.configvalues.bukkit.DefaultYamlValue;
+import community.leaf.configvalues.bukkit.ExampleYamlValue;
 import community.leaf.configvalues.bukkit.migrations.Migration;
 import community.leaf.configvalues.bukkit.YamlValue;
 import community.leaf.configvalues.bukkit.data.YamlDataFile;
@@ -25,6 +26,9 @@ public class Config extends YamlDataFile
             )
             .defaults("Hello world.");
 
+    public static final ExampleYamlValue<String> EXAMPLE_MESSAGE =
+        YamlValue.ofString("messages.example").example("I only get set once!");
+    
     @AggregatedResult
     private static final List<YamlValue<?>> VALUES = Aggregates.list(Config.class, YamlValue.type());