Merge branch 'master' into dependabot/maven/impl/snakeyaml/org.yaml-s…

…nakeyaml-2.0

core/pom.xml

@@ -17,5 +17,10 @@
       <groupId>${project.groupId}</groupId>
       <artifactId>mmm-base</artifactId>
     </dependency>
+    <dependency>
+      <groupId>${project.groupId}</groupId>
+      <artifactId>mmm-scanner</artifactId>
+      <optional>true</optional>
+    </dependency>
   </dependencies>
 </project>

core/src/main/java/io/github/mmm/marshall/AbstractStructuredProcessor.java

@@ -0,0 +1,37 @@
+/* Copyright (c) The m-m-m Team, Licensed under the Apache License, Version 2.0
+ * http://www.apache.org/licenses/LICENSE-2.0 */
+package io.github.mmm.marshall;
+
+/**
+ * Abstract base implementation of {@link StructuredReader}.
+ */
+public abstract class AbstractStructuredProcessor implements StructuredProcessor {
+
+  private final StructuredFormat format;
+
+  /** The {@link MarshallingConfig}. */
+  protected final MarshallingConfig config;
+
+  /** @see MarshallingConfig#OPT_ENUM_FORMAT */
+  protected final EnumFormat enumFormat;
+
+  /**
+   * The constructor.
+   *
+   * @param format the {@link #getFormat() format}.
+   */
+  public AbstractStructuredProcessor(StructuredFormat format) {
+
+    super();
+    this.format = format;
+    this.config = format.getConfig();
+    this.enumFormat = this.config.get(MarshallingConfig.OPT_ENUM_FORMAT);
+  }
+
+  @Override
+  public StructuredFormat getFormat() {
+
+    return this.format;
+  }
+
+}

core/src/main/java/io/github/mmm/marshall/AbstractStructuredReader.java

@@ -17,38 +17,32 @@
 import java.util.Map;
 
 import io.github.mmm.base.number.NumberType;
+import io.github.mmm.marshall.impl.EnumMapping;
+import io.github.mmm.marshall.impl.EnumMappings;
 
 /**
  * Abstract base implementation of {@link StructuredReader}.
  */
-public abstract class AbstractStructuredReader implements StructuredReader {
-
-  private final StructuredFormat format;
-
-  /** The {@link MarshallingConfig}. */
-  protected final MarshallingConfig config;
+public abstract class AbstractStructuredReader extends AbstractStructuredProcessor implements StructuredReader {
 
   /** @see #readName() */
   protected String name;
 
+  /** @see #getState() */
+  protected State state;
+
   private String comment;
 
+  private boolean done;
+
   /**
    * The constructor.
    *
    * @param format the {@link #getFormat() format}.
    */
   public AbstractStructuredReader(StructuredFormat format) {
 
-    super();
-    this.format = format;
-    this.config = format.getConfig();
-  }
-
-  @Override
-  public StructuredFormat getFormat() {
-
-    return this.format;
+    super(format);
   }
 
   @Override
@@ -57,13 +51,6 @@ public String getName() {
     return this.name;
   }
 
-  /**
-   * @see #getState()
-   */
-  protected State state;
-
-  private boolean done;
-
   @Override
   public State getState() {
 
@@ -187,6 +174,30 @@ public Boolean readValueAsBoolean() {
     }
   }
 
+  @Override
+  public <E extends Enum<E>> E readValueAsEnum(Class<E> enumType) {
+
+    EnumMapping<E> mapping = EnumMappings.get().getMapping(enumType);
+    if (isStringValue()) {
+      String stringValue = readValueAsString();
+      E e = mapping.fromString(stringValue);
+      if ((e == null) && (stringValue != null)) {
+        throw error("The string value '" + stringValue + "' is not an enum of type " + enumType.getName());
+      }
+      return e;
+    } else {
+      Integer ordinalValue = readValueAsInteger();
+      if (ordinalValue == null) {
+        return null;
+      }
+      E e = mapping.fromOrdinal(ordinalValue);
+      if ((e == null) && (ordinalValue != null)) {
+        throw error("The integer value '" + ordinalValue + "' is not an ordinal of enum type " + enumType.getName());
+      }
+      return e;
+    }
+  }
+
   @Override
   public Long readValueAsLong() {
 
@@ -402,7 +413,7 @@ public Object readValue(boolean recursive) {
         value = map;
       } else {
         expect(State.VALUE, State.START_ARRAY, State.START_OBJECT);
-        throw new IllegalStateException();
+        throw errorIllegalState();
       }
     }
     return value;
@@ -490,13 +501,21 @@ public void skipValue() {
           case NAME:
             break;
           case DONE:
-            throw new IllegalStateException();
+            errorIllegalState();
         }
         next();
       }
     }
   }
 
+  /**
+   * @return nothing, just to ensure exit you may throw result of this method.
+   */
+  protected RuntimeException errorIllegalState() {
+
+    return error("Illegal state");
+  }
+
   /**
    * @param message the error message.
    * @return nothing, just to ensure exit you may throw result of this method.
@@ -513,10 +532,19 @@ protected RuntimeException error(String message) {
    */
   protected RuntimeException error(String message, Throwable cause) {
 
-    if (this.name != null) {
-      message = message + "(at property '" + this.name + "')";
+    throw new IllegalStateException(appendContextDetails(message), cause);
+  }
+
+  /**
+   * @param message the message to report (e.g. error or warning).
+   * @return the given {@code message} with contextual details appended (e.g. the line number in the content to parse).
+   */
+  protected String appendContextDetails(String message) {
+
+    if (this.name == null) {
+      return message;
     }
-    throw new IllegalStateException(message, cause);
+    return message + "(at property '" + this.name + "')";
   }
 
   /**

core/src/main/java/io/github/mmm/marshall/AbstractStructuredScannerReader.java

@@ -0,0 +1,52 @@
+/* Copyright (c) The m-m-m Team, Licensed under the Apache License, Version 2.0
+ * http://www.apache.org/licenses/LICENSE-2.0 */
+package io.github.mmm.marshall;
+
+import io.github.mmm.scanner.CharStreamScanner;
+
+/**
+ * {@link AbstractStructuredReader} that {@link #readValue() reads values} as {@link Object}.
+ */
+@SuppressWarnings("exports")
+public abstract class AbstractStructuredScannerReader extends AbstractStructuredValueReader {
+
+  /** The {@link CharStreamScanner} to read from. */
+  protected final CharStreamScanner reader;
+
+  /**
+   * The constructor.
+   *
+   * @param scanner the {@link CharStreamScanner} to read from.
+   * @param format the {@link #getFormat() format}.
+   */
+  public AbstractStructuredScannerReader(CharStreamScanner scanner, StructuredFormat format) {
+
+    super(format);
+    this.reader = scanner;
+  }
+
+  @Override
+  protected String appendContextDetails(String message) {
+
+    StringBuilder sb = new StringBuilder(message);
+    sb.append('(');
+    if (this.name != null) {
+      sb.append("at property '");
+      sb.append(this.name);
+      sb.append("' ");
+    }
+    sb.append("in line ");
+    sb.append(this.reader.getLine());
+    sb.append(" and column ");
+    sb.append(this.reader.getColumn());
+    sb.append(')');
+    return sb.toString();
+  }
+
+  @Override
+  public void close() {
+
+    this.reader.close();
+  }
+
+}

core/src/main/java/io/github/mmm/marshall/AbstractStructuredWriter.java

@@ -5,17 +5,12 @@
 /**
  * Abstract base implementation of {@link StructuredWriter}.
  */
-public abstract class AbstractStructuredWriter implements StructuredWriter {
+public abstract class AbstractStructuredWriter extends AbstractStructuredProcessor implements StructuredWriter {
 
   static final String XML_COMMENT_DASHES = "--";
 
   static final String XML_COMMENT_DASHES_ESCAPED = "\\-_-/";
 
-  private final StructuredFormat format;
-
-  /** The {@link MarshallingConfig}. */
-  protected final MarshallingConfig config;
-
   /** @see #writeValueAsNull() */
   protected final boolean writeNullValues;
 
@@ -32,9 +27,7 @@ public abstract class AbstractStructuredWriter implements StructuredWriter {
    */
   public AbstractStructuredWriter(StructuredFormat format) {
 
-    super();
-    this.format = format;
-    this.config = format.getConfig();
+    super(format);
     this.writeNullValues = this.config.get(MarshallingConfig.OPT_WRITE_NULL_VALUES).booleanValue();
     this.indentation = normalizeIndentation(this.config.get(MarshallingConfig.OPT_INDENTATION));
   }
@@ -57,12 +50,6 @@ protected String escapeXmlComment(String currentComment) {
     return currentComment.replace(XML_COMMENT_DASHES, XML_COMMENT_DASHES_ESCAPED);
   }
 
-  @Override
-  public StructuredFormat getFormat() {
-
-    return this.format;
-  }
-
   @Override
   public void writeName(String newName, int newId) {
 
@@ -73,4 +60,18 @@ public void writeName(String newName, int newId) {
     this.name = newName;
   }
 
+  @Override
+  public void writeValueAsEnum(Enum<?> value) {
+
+    if (value == null) {
+      writeValueAsNull();
+      return;
+    }
+    if (this.enumFormat == EnumFormat.ORDINAL) {
+      writeValueAsInteger(Integer.valueOf(value.ordinal()));
+    } else {
+      writeValueAsString(this.enumFormat.toString(value));
+    }
+  }
+
 }

core/src/main/java/io/github/mmm/marshall/EnumFormat.java

@@ -0,0 +1,52 @@
+/* Copyright (c) The m-m-m Team, Licensed under the Apache License, Version 2.0
+ * http://www.apache.org/licenses/LICENSE-2.0 */
+package io.github.mmm.marshall;
+
+import io.github.mmm.base.text.CaseHelper;
+import io.github.mmm.base.text.CaseSyntax;
+
+/**
+ * {@link Enum} with the available formats how to serialize an {@link Enum}.
+ */
+public enum EnumFormat {
+
+  /** Write {@link Enum} as {@link Enum#ordinal() ordinal}. */
+  ORDINAL,
+
+  /** Write {@link Enum} as {@link Enum#name() name}. */
+  NAME,
+
+  /** Write {@link Enum} as {@link Enum#toString() toString representation}. */
+  TO_STRING,
+
+  /** Like {@link #TO_STRING} but in {@link CaseHelper#toLowerCase(String) lowercase}. */
+  TO_STRING_LOWER_CASE,
+
+  /** Like {@link #TO_STRING} but in {@link CaseSyntax#TRAIN_CASE train-case}. */
+  TO_STRING_TRAIN_CASE;
+
+  /**
+   * @param e the {@link Enum} value.
+   * @return the corresponding {@link String} representation according to this format.
+   */
+  public String toString(Enum<?> e) {
+
+    if (e == null) {
+      return null;
+    }
+    switch (this) {
+      case ORDINAL:
+        return null;
+      case NAME:
+        return e.name();
+      case TO_STRING:
+        return e.toString();
+      case TO_STRING_LOWER_CASE:
+        return CaseHelper.toLowerCase(e.toString());
+      case TO_STRING_TRAIN_CASE:
+        return CaseSyntax.TRAIN_CASE.convert(e.toString());
+    }
+    return null;
+  }
+
+}

core/src/main/java/io/github/mmm/marshall/MarshallingConfig.java

@@ -42,6 +42,12 @@ public final class MarshallingConfig extends ConfigMap {
    */
   public static final ConfigOption<Boolean> OPT_UNQUOTED_PROPERTIES = new ConfigOption<>("unquoted-properties", null);
 
+  /**
+   * {@link ConfigOption} to configure how {@link Enum} values are mapped. By default the {@link Enum#ordinal() ordinal}
+   * is written while reading supports both ordinal and {@link Enum#toString() to-string}.
+   */
+  public static final ConfigOption<EnumFormat> OPT_ENUM_FORMAT = new ConfigOption<>("enum-format", EnumFormat.ORDINAL);
+
   /** Immutable instance of {@link MarshallingConfig} with the default values. */
   public static final MarshallingConfig DEFAULTS = new MarshallingConfig(Collections.emptyMap());
 

core/src/main/java/io/github/mmm/marshall/StructuredProcessor.java

@@ -0,0 +1,21 @@
+/* Copyright (c) The m-m-m Team, Licensed under the Apache License, Version 2.0
+ * http://www.apache.org/licenses/LICENSE-2.0 */
+package io.github.mmm.marshall;
+
+/**
+ * Base interface for {@link StructuredReader} and {@link StructuredWriter}.
+ *
+ * @since 1.0.0
+ */
+public abstract interface StructuredProcessor extends AutoCloseable {
+
+  @Override
+  void close();
+
+  /**
+   * @return the owning {@link StructuredFormat} that {@link StructuredFormat#reader(java.io.InputStream) created} this
+   *         writer.
+   */
+  StructuredFormat getFormat();
+
+}