feat(attributes): Add a simple 'Only' helper to help with enums

This use case was recently encountered and there was no clear solution for it.
Adding it in Configy seems rather simple and would probably cover other users.

Author: Geod24

doc/FAQ.md

@@ -282,3 +282,26 @@ to be validated, one can implement a `void validate() const` method which throws
 an exception in the event of a validation failure.
 The library will rethrow this `Exception` with the file/line information pointing
 to the section itself, and not any individual field.
+
+### Limit the set of acceptable values / Use an `enum`
+
+Configy uses `std.conv : to` for converting `enum`, which means they always get converted
+to their symbolic name. The following two types will behave the same and expect values
+`APAC`, `EMEA`, and `Americas` in the YAML file.
+```D
+enum Location : string {
+  APAC     = "APAC",
+  EMEA     = "EMEA",
+  Americas = "North America",
+}
+
+enum Location2 {
+  APAC,
+  EMEA,
+  Americas,
+}
+```
+Symbolic names, unlike enum values, must be unique - Hence why they are not taken into account.
+To work around this, one may use `configy.attributes : Only`, which accepts a list of strings.
+`Location` would then be expressed as `Only!(["APAC", "EMEA", "North America"])` instead.
+It is also trivial to implement such a type if a project has specific needs.

source/configy/attributes.d

@@ -332,3 +332,72 @@ public interface ConfigParser (T)
     /// Internal use only
     protected const(Context) context () const @safe pure nothrow @nogc;
 }
+
+/*******************************************************************************
+
+    Specify that a field only accept a limited set of string values.
+
+    This is similar to how `enum` symbolic names are treated, however the `enum`
+    symbolic names may not contain spaces or special character.
+
+    Params:
+      Values = Permissible values (case sensitive)
+
+*******************************************************************************/
+
+public struct Only (string[] Values) {
+    public string value;
+
+    alias value this;
+
+    public static Only fromString (scope string str) {
+        import std.algorithm.searching : canFind;
+        import std.exception : enforce;
+        import std.format;
+
+        enforce(Values.canFind(str),
+            "%s is not a valid value for this field, valid values are: %(%s, %)"
+            .format(str, Values));
+        return Only(str);
+    }
+}
+
+///
+unittest {
+    import configy.attributes : Only, Optional;
+    import configy.read : parseConfigString;
+
+    static struct CountryConfig {
+        Only!(["France", "Malta", "South Korea"]) country;
+        // Compose with other attributes too
+        @Optional Only!(["citizen", "resident", "alien"]) status;
+    }
+    static struct Config {
+        CountryConfig[] countries;
+    }
+
+    auto conf = parseConfigString!Config(`countries:
+  - country: France
+    status: citizen
+  - country: Malta
+  - country: South Korea
+    status: alien
+`, "/dev/null");
+
+    assert(conf.countries.length == 3);
+    assert(conf.countries[0].country == `France`);
+    assert(conf.countries[0].status  == `citizen`);
+    assert(conf.countries[1].country == `Malta`);
+    assert(conf.countries[1].status  is null);
+    assert(conf.countries[2].country == `South Korea`);
+    assert(conf.countries[2].status  == `alien`);
+
+    import configy.exceptions : ConfigException;
+
+    try parseConfigString!Config(`countries:
+  - country: France
+    status: expatriate
+`, "/etc/config");
+    catch (ConfigException exc)
+        assert(exc.toString() == `/etc/config(2:12): countries[0].status: expatriate is not a valid value for this field, valid values are: "citizen", "resident", "alien"`);
+}