yaml: update for core changes

zml2008 · zml2008 · commit deb89f0e3192 · 2020-10-22T20:36:23.000-07:00
diff --git a/format/yaml/src/main/java/org/spongepowered/configurate/yaml/ConfigurateScanner.java b/format/yaml/src/main/java/org/spongepowered/configurate/yaml/ConfigurateScanner.java
@@ -183,7 +183,7 @@ final class ConfigurateScanner implements Scanner { // Configurate: rename + pac
         // 32-bit Unicode (Supplementary characters are supported)
         ESCAPE_CODES.put(Character.valueOf('U'), 8);
     }
-    private final StreamReader reader;
+    final StreamReader reader; // Configurate: private -> package-private
     // Had we reached the end of the stream?
     private boolean done = false;
 
diff --git a/format/yaml/src/main/java/org/spongepowered/configurate/yaml/ScalarStyle.java b/format/yaml/src/main/java/org/spongepowered/configurate/yaml/ScalarStyle.java
@@ -19,22 +19,33 @@
 import org.checkerframework.checker.nullness.qual.Nullable;
 import org.yaml.snakeyaml.DumperOptions;
 
-import java.util.HashMap;
+import java.util.EnumMap;
 import java.util.Map;
 
 /**
  * Style that can be used to represent a scalar.
  */
 public enum ScalarStyle {
 
+    /**
+     * A double-quoted string.
+     *
+     * <p><pre>"hello world"</pre></p>
+     */
     DOUBLE_QUOTED(DumperOptions.ScalarStyle.DOUBLE_QUOTED),
+
+    /**
+     * A single-quoted string.
+     *
+     * <p><pre>'hello world'</pre></p>
+     */
     SINGLE_QUOTED(DumperOptions.ScalarStyle.SINGLE_QUOTED),
     UNQUOTED(DumperOptions.ScalarStyle.PLAIN),
     FOLDED(DumperOptions.ScalarStyle.FOLDED),
     LITERAL(DumperOptions.ScalarStyle.LITERAL)
     ;
 
-    private static final Map<DumperOptions.ScalarStyle, ScalarStyle> BY_SNAKE = new HashMap<>();
+    private static final Map<DumperOptions.ScalarStyle, ScalarStyle> BY_SNAKE = new EnumMap<>(DumperOptions.ScalarStyle.class);
     private final DumperOptions.ScalarStyle snake;
 
     ScalarStyle(final DumperOptions.ScalarStyle snake) {
diff --git a/format/yaml/src/main/java/org/spongepowered/configurate/yaml/Tag.java b/format/yaml/src/main/java/org/spongepowered/configurate/yaml/Tag.java
@@ -31,6 +31,11 @@
 @AutoValue
 public abstract class Tag {
 
+    /**
+     * Create a new builder for a {@link Tag}.
+     *
+     * @return a new builder
+     */
     public static Tag.Builder builder() {
         return new AutoValue_Tag.Builder();
     }
@@ -43,53 +48,88 @@ public static Tag.Builder builder() {
      *
      * @return tag uri, with `tag:` schema
      */
-    public abstract URI getUri();
+    public abstract URI uri();
 
     /**
      * The native type that maps to this tag.
      *
      * @return native type for tag
      */
-    public abstract Type getNativeType();
+    public abstract Type nativeType();
 
     /**
      * Pattern to test scalar values against when resolving this tag.
      *
      * @return match pattern
      * @apiNote See §3.3.2 of YAML 1.1 spec
      */
-    public abstract Pattern getTargetPattern();
+    public abstract Pattern targetPattern();
 
     /**
      * Whether this tag is a global tag with a full namespace or a local one.
      *
      * @return if this is a global tag
      */
-    public final boolean isGlobal() {
-        return getUri().getScheme().equals("tag");
+    public final boolean global() {
+        return uri().getScheme().equals("tag");
     }
 
+    /**
+     * A builder for {@link Tag Tags}.
+     */
     @AutoValue.Builder
     public abstract static class Builder {
 
-        public abstract Builder setUri(URI url);
-
-        public final Builder setUri(final String tagUrl) {
+        /**
+         * Set the URI used to refer to the tag.
+         *
+         * @param url canonical tag URI
+         * @return this builder
+         */
+        public abstract Builder uri(URI url);
+
+        /**
+         * Set the URI used to refer to the tag, parsing a new URL from
+         * the argument.
+         *
+         * @param tagUrl canonical tag URI
+         * @return this builder
+         */
+        public final Builder uri(final String tagUrl) {
             try {
                 if (tagUrl.startsWith("!")) {
-                    return this.setUri(new URI(tagUrl.substring(1)));
+                    return this.uri(new URI(tagUrl.substring(1)));
                 } else {
-                    return this.setUri(new URI(tagUrl));
+                    return this.uri(new URI(tagUrl));
                 }
             } catch (final URISyntaxException e) {
                 throw new RuntimeException(e);
             }
         }
 
-        public abstract Builder setNativeType(Type type);
-
-        public abstract Builder setTargetPattern(Pattern targetPattern);
-
+        /**
+         * The Java type that will be used to represent this value in the node
+         * structure.
+         *
+         * @param type type for the value
+         * @return this builder
+         */
+        public abstract Builder nativeType(Type type);
+
+        /**
+         * Pattern to match an undefined scalar string to this tag as an
+         * <em>implicit tag</em>.
+         *
+         * @param targetPattern pattern to match
+         * @return this builder
+         */
+        public abstract Builder targetPattern(Pattern targetPattern);
+
+        /**
+         * Create a new tag from the provided parameters.
+         *
+         * @return a new tag
+         */
         public abstract Tag build();
 
     }
diff --git a/format/yaml/src/main/java/org/spongepowered/configurate/yaml/TagRepository.java b/format/yaml/src/main/java/org/spongepowered/configurate/yaml/TagRepository.java
@@ -24,13 +24,15 @@
 import java.util.List;
 import java.util.Map;
 
+/**
+ * A collection of tags that are understood when reading a document.
+ */
 public final class TagRepository {
 
     private final List<Tag> tags;
     private final Map<Class<?>, Tag> byErasedType;
     private final Map<String, Tag> byName;
 
-
     /**
      * Create a new tag repository.
      *
@@ -45,19 +47,25 @@ public static TagRepository of(final List<Tag> tags) {
         this.tags = tags;
         this.byErasedType = UnmodifiableCollections.buildMap(map -> {
             for (final Tag tag : this.tags) {
-                map.put(erase(tag.getNativeType()), tag);
+                map.put(erase(tag.nativeType()), tag);
             }
         });
         this.byName = UnmodifiableCollections.buildMap(map -> {
             for (final Tag tag : this.tags) {
-                map.put(tag.getUri().toString(), tag);
+                map.put(tag.uri().toString(), tag);
             }
         });
     }
 
+    /**
+     * Determine the implicit tag for a scalar value.
+     *
+     * @param scalar scalar to test
+     * @return the first matching tag
+     */
     public @Nullable Tag forInput(final String scalar) {
         for (final Tag tag : this.tags) {
-            if (tag.getTargetPattern().matcher(scalar).matches()) {
+            if (tag.targetPattern().matcher(scalar).matches()) {
                 return tag;
             }
         }
diff --git a/format/yaml/src/main/java/org/spongepowered/configurate/yaml/Yaml11Tags.java b/format/yaml/src/main/java/org/spongepowered/configurate/yaml/Yaml11Tags.java
@@ -34,73 +34,113 @@ private static String yamlOrg(final String specific) {
         return "tag:yaml.org,2002:" + specific;
     }
 
-    // https://yaml.org/type/binary.html
+    /**
+     * A binary data tag.
+     *
+     * @see <a href="https://yaml.org/type/binary.html">tag:yaml.org,2002:binary</a>
+     */
     public static final Tag BINARY = Tag.builder()
-            .setUri(yamlOrg("binary"))
-            .setNativeType(byte[].class)
-            .setTargetPattern(Pattern.compile("base64 TODO"))
+            .uri(yamlOrg("binary"))
+            .nativeType(byte[].class)
+            .targetPattern(Pattern.compile("base64 TODO"))
             .build();
 
-    // https://yaml.org/type/bool.html
-    // Canonically these are y|n in YAML 1.1, but because YAML 1.2 moves to
-    // true|false only, we'll just use those
+    /**
+     * A boolean value.
+     *
+     * @implNote Canonically, these are y|n in YAML 1.1, but because YAML 1.2
+     *     will only support true|false, we will treat those as the default
+     *     output format.
+     * @see <a href="https://yaml.org/type/bool.html">tag:yaml.org,2002:bool</a>
+     */
     public static final Tag BOOL = Tag.builder()
-            .setUri(yamlOrg("bool"))
-            .setNativeType(Boolean.class)
-            .setTargetPattern(Pattern.compile("y|Y|yes|Yes|YES|n|N|no|No|NO"
+            .uri(yamlOrg("bool"))
+            .nativeType(Boolean.class)
+            .targetPattern(Pattern.compile("y|Y|yes|Yes|YES|n|N|no|No|NO"
                     + "|true|True|TRUE|false|False|FALSE"
                     + "|on|On|ON|off|Off|OFF"))
             .build();
 
-    // https://yaml.org/type/float.html
+    /**
+     * A floating-point number.
+     *
+     * @see <a href="https://yaml.org/type/float.html">tag:yaml.org,2002:float</a>
+     */
     public static final Tag FLOAT = Tag.builder()
-            .setUri(yamlOrg("float"))
-            .setNativeType(Double.class)
-            .setTargetPattern(Pattern.compile("[-+]?([0-9][0-9_]*)?\\.[0-9.]*([eE][-+][0-9]+)?" // base 10
+            .uri(yamlOrg("float"))
+            .nativeType(Double.class)
+            .targetPattern(Pattern.compile("[-+]?([0-9][0-9_]*)?\\.[0-9.]*([eE][-+][0-9]+)?" // base 10
                     + "|[-+]?[0-9][0-9_]*(:[0-5]?[0-9])+\\.[0-9]*" // base 60
                     + "|[-+]?\\.(inf|Inf|INF)" // infinity
                     + "|\\.(nan|NaN|NAN)")) // not a number
             .build();
 
-    // https://yaml.org/type/int.html
+    /**
+     * An integer.
+     *
+     * @see <a href="https://yaml.org/type/int.html">tag:yaml.org,2002:int</a>
+     */
     public static final Tag INT = Tag.builder()
-            .setUri(yamlOrg("int"))
-            .setNativeType(Long.class)
-            .setTargetPattern(Pattern.compile("[-+]?0b[0-1_]+" // base 2
+            .uri(yamlOrg("int"))
+            .nativeType(Long.class)
+            .targetPattern(Pattern.compile("[-+]?0b[0-1_]+" // base 2
                     + "|[-+]?0[0-7_]+" // base 8
                     + "|[-+]?(0|[1-9][0-9_]*)" // base 10
                     + "|[-+]?0x[0-9a-fA-F_]+" // base 16
                     + "|[-+]?[1-9][0-9_]*(:[0-5]?[0-9])+")) // base 60
             .build();
 
-    // https://yaml.org/type/merge.html
+    /**
+     * A mapping merge.
+     *
+     * <p>This will not be supported in Configurate until reference-type nodes
+     * are fully implemented.</p>
+     *
+     * @see <a href="https://yaml.org/type/merge.html">tag:yaml.org,2002:merge</a>
+     */
     public static final Tag MERGE = Tag.builder()
-            .setUri(yamlOrg("merge"))
-            .setNativeType(ConfigurationNode.class)
-            .setTargetPattern(Pattern.compile("<<"))
+            .uri(yamlOrg("merge"))
+            .nativeType(ConfigurationNode.class)
+            .targetPattern(Pattern.compile("<<"))
             .build();
 
-    // https://yaml.org/type/null.html
+    /**
+     * The value {@code null}.
+     *
+     * <p>Because Configurate has no distinction between a node with a
+     * {@code null} value, and a node that does not exist, this tag will most
+     * likely never be encountered in an in-memory representation.</p>
+     *
+     * @see <a href="https://yaml.org/type/null.html">tag:yaml.org,2002:null</a>
+     */
     public static final Tag NULL = Tag.builder()
-            .setUri(yamlOrg("null"))
-            .setNativeType(Void.class)
-            .setTargetPattern(Pattern.compile("~"
+            .uri(yamlOrg("null"))
+            .nativeType(Void.class)
+            .targetPattern(Pattern.compile("~"
                     + "|null|Null|NULL"
                     + "|$"))
             .build();
 
-    // https://yaml.org/type/str.html
+    /**
+     * Any string.
+     *
+     * @see <a href="https://yaml.org/type/str.html">tag:yaml.org,2002:str</a>
+     */
     public static final Tag STR = Tag.builder()
-            .setUri(yamlOrg("str"))
-            .setNativeType(String.class)
-            .setTargetPattern(Pattern.compile(".+")) // empty scalar is NULL
+            .uri(yamlOrg("str"))
+            .nativeType(String.class)
+            .targetPattern(Pattern.compile(".+")) // empty scalar is NULL
             .build();
 
-    // https://yaml.org/type/timestamp.html
+    /**
+     * A timestamp, containing date, time, and timezone.
+     *
+     * @see <a href="https://yaml.org/type/timestamp.html">tag:yaml.org,2002:timestamp</a>
+     */
     public static final Tag TIMESTAMP = Tag.builder()
-            .setUri(yamlOrg("timestamp"))
-            .setNativeType(ZonedDateTime.class)
-            .setTargetPattern(Pattern.compile("[0-9]{4}-[0-9]{2}-[0-9]{2}" // YYYY-MM-DD
+            .uri(yamlOrg("timestamp"))
+            .nativeType(ZonedDateTime.class)
+            .targetPattern(Pattern.compile("[0-9]{4}-[0-9]{2}-[0-9]{2}" // YYYY-MM-DD
                     + "|[0-9]{4}" // YYYY
                     + "-[0-9]{1,2}" // month
                     + "-[0-9]{1,2}" // day
diff --git a/format/yaml/src/main/java/org/spongepowered/configurate/yaml/YamlConfigurationLoader.java b/format/yaml/src/main/java/org/spongepowered/configurate/yaml/YamlConfigurationLoader.java
@@ -48,10 +48,25 @@
  */
 public final class YamlConfigurationLoader extends AbstractConfigurationLoader<CommentedConfigurationNode> {
 
+    /**
+     * The identifier for a YAML anchor that can be used to refer to the node
+     * this hint is set on.
+     */
     public static final RepresentationHint<String> ANCHOR_ID = RepresentationHint.of("anchor-id", String.class);
 
+    /**
+     * The YAML scalar style this node should attempt to use.
+     *
+     * <p>If the chosen scalar style would produce syntactically invalid YAML, a
+     * valid one will replace it.</p>
+     */
     public static final RepresentationHint<ScalarStyle> SCALAR_STYLE = RepresentationHint.of("scalar-style", ScalarStyle.class);
 
+    /**
+     * The YAML node style to use for collection nodes. A {@code null} value
+     * will instruct the emitter to fall back to the
+     * {@link Builder#nodeStyle()} setting.
+     */
     public static final RepresentationHint<NodeStyle> NODE_STYLE = RepresentationHint.of("node-style", NodeStyle.class);
 
     /**
diff --git a/format/yaml/src/main/java/org/spongepowered/configurate/yaml/YamlParser.java b/format/yaml/src/main/java/org/spongepowered/configurate/yaml/YamlParser.java
diff --git a/format/yaml/src/main/java/org/spongepowered/configurate/yaml/YamlVisitor.java b/format/yaml/src/main/java/org/spongepowered/configurate/yaml/YamlVisitor.java
diff --git a/format/yaml/src/test/java/org/spongepowered/configurate/yaml/YamlTest.java b/format/yaml/src/test/java/org/spongepowered/configurate/yaml/YamlTest.java

Original file line number	Diff line number	Diff line change
`@@ -183,7 +183,7 @@ final class ConfigurateScanner implements Scanner { // Configurate: rename + pac`
`183`	`183`	`// 32-bit Unicode (Supplementary characters are supported)`
`184`	`184`	`ESCAPE_CODES.put(Character.valueOf('U'), 8);`
`185`	`185`	`}`
`186`		`- private final StreamReader reader;`
	`186`	`+ final StreamReader reader; // Configurate: private -> package-private`
`187`	`187`	`// Had we reached the end of the stream?`
`188`	`188`	`private boolean done = false;`
`189`	`189`