feat: adds random.any() expression function.

Author: outofcoffee

core/expression/src/main/java/io/gatehill/imposter/expression/eval/RandomEvaluator.kt

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2023.
+ * Copyright (c) 2023-2024.
  *
  * This file is part of Imposter.
  *
@@ -80,15 +80,31 @@ object RandomEvaluator : ExpressionEvaluator<String> {
             it.split("=").let { parts -> parts[0] to parts[1] }
         }
         val type = randomConfig.substringBefore("(")
-        val length = args["length"]?.toInt()
+        val length = args["length"]?.toInt() ?: 1
         val uppercase = args["uppercase"].toBoolean()
 
+        // the chars string must be enclosed in double quotes
+        val chars = args["chars"]?.let {
+            if (!it.startsWith("\"") || !it.endsWith("\"")) {
+                LOGGER.warn("chars string must be enclosed in double quotes")
+                return null
+            }
+            it.substring(1, it.length - 1)
+        }
+
         val random = when (type) {
-            "alphabetic" -> getRandomString(length!!, alphabetUpper + alphabetLower)
-            "alphanumeric" -> getRandomString(length!!, alphabetUpper + alphabetLower + numbers)
-            "numeric" -> getRandomString(length!!, numbers.toList())
+            "alphabetic" -> getRandomString(length, alphabetUpper + alphabetLower)
+            "alphanumeric" -> getRandomString(length, alphabetUpper + alphabetLower + numbers)
+            "any" -> {
+                if (chars == null) {
+                    LOGGER.warn("chars string must be provided for random type 'any'")
+                    return null
+                }
+                getRandomString(length, chars.toList())
+            }
+            "numeric" -> getRandomString(length, numbers.toList())
             "uuid" -> UUID.randomUUID().toString()
-            else -> run {
+            else -> {
                 LOGGER.warn("Could not parse random expression: $randomConfig")
                 return null
             }
@@ -97,6 +113,6 @@ object RandomEvaluator : ExpressionEvaluator<String> {
     }
 
     private fun getRandomString(length: Int, allowedChars: List<Char>) = (1..length)
-        .map { allowedChars.random() }
-        .joinToString("")
+            .map { allowedChars.random() }
+            .joinToString("")
 }

core/expression/src/test/java/io/gatehill/imposter/expression/eval/RandomEvaluatorTest.kt

@@ -1,3 +1,46 @@
+/*
+ * Copyright (c) 2024.
+ *
+ * This file is part of Imposter.
+ *
+ * "Commons Clause" License Condition v1.0
+ *
+ * The Software is provided to you by the Licensor under the License, as
+ * defined below, subject to the following condition.
+ *
+ * Without limiting other conditions in the License, the grant of rights
+ * under the License will not include, and the License does not grant to
+ * you, the right to Sell the Software.
+ *
+ * For purposes of the foregoing, "Sell" means practicing any or all of
+ * the rights granted to you under the License to provide to third parties,
+ * for a fee or other consideration (including without limitation fees for
+ * hosting or consulting/support services related to the Software), a
+ * product or service whose value derives, entirely or substantially, from
+ * the functionality of the Software. Any license notice or attribution
+ * required by the License must also include this Commons Clause License
+ * Condition notice.
+ *
+ * Software: Imposter
+ *
+ * License: GNU Lesser General Public License version 3
+ *
+ * Licensor: Peter Cornish
+ *
+ * Imposter is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Lesser General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Imposter is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with Imposter.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
 package io.gatehill.imposter.expression.eval
 
 import org.hamcrest.MatcherAssert.assertThat
@@ -37,6 +80,25 @@ class RandomEvaluatorTest {
         assertContainsOnly(result, RandomEvaluator.alphabetLower + RandomEvaluator.numbers + listOf('-'))
     }
 
+    @Test
+    fun `generates from list of chars`() {
+        val result = RandomEvaluator.eval("""random.any(chars="abc", length=5)""", emptyMap<String, Any>())
+        assertThat(result, hasLength(5))
+        assertContainsOnly(result, listOf('a', 'b', 'c'))
+    }
+
+    @Test
+    fun `returns null for invalid chars string`() {
+        val result = RandomEvaluator.eval("""random.any(chars=notquoted, length=5)""", emptyMap<String, Any>())
+        Assert.assertNull(result)
+    }
+
+    @Test
+    fun `returns null for invalid random type`() {
+        val result = RandomEvaluator.eval("random.invalid()", emptyMap<String, Any>())
+        Assert.assertNull(result)
+    }
+
     private fun assertContainsOnly(
         actual: String?,
         allowed: List<Char>

docs/templates.md

@@ -231,47 +231,75 @@ Example config:
 # part of your configuration file
 
 resources:
-- path: /now
+- path: /number
   method: POST
   response:
-    content: "An integer is ${random.numeric}"
+    content: "An integer is ${random.numeric()}"
+    template: true
+
+- path: /chars
+  method: POST
+  response:
+    content: "A random string is ${random.alphabetic(length=5)}"
     template: true
 ```
 
-Example request:
+Example requests:
 
 ```
-$ curl http://localhost:8080/now
+$ curl http://localhost:8080/number
+An integer is 4
 
-An integer is 42
+$ curl http://localhost:8080/chars
+A random string is abcde
 ```
 
 Valid random functions:
 
-| Syntax                  | Example                    | Example value                            |
-|-------------------------|----------------------------|------------------------------------------|
-| `random.alphabetic()`   | `${random.alphabetic()}`   | `"i"`                                    |
-| `random.alphanumeric()` | `${random.alphanumeric()}` | `"i"` or `"42"`                          |
-| `random.numeric()`      | `${random.numeric()}`      | `"42"`                                   |
-| `random.uuid()`         | `${random.uuid()}`         | `"e1a4fba9-33eb-4241-84cf-472f90639c37"` |
+| Syntax                    | Example                         | Example value                            |
+|---------------------------|---------------------------------|------------------------------------------|
+| `random.alphabetic()`     | `${random.alphabetic()}`        | `"i"`                                    |
+| `random.alphanumeric()`   | `${random.alphanumeric()}`      | `"i"` or `"42"`                          |
+| `random.any(chars="...")` | `${random.any(chars="abc123")}` | `"a"` or `"1"`                           |
+| `random.numeric()`        | `${random.numeric()}`           | `"42"`                                   |
+| `random.uuid()`           | `${random.uuid()}`              | `"e1a4fba9-33eb-4241-84cf-472f90639c37"` |
 
 > Note: the syntax for `random` is slightly different to the other placeholder types. These are functions, not properties, so are called with parentheses.
 
 #### Customise length
 
 Customise the length of the generated value by passing `length=NUM` argument into the function.
 
-For example: `${random.alphabetic(length=5)}`
+For example: `${random.alphabetic(length=5)}` will generate a 5-character alphabetic string.
+
+> The default length is 1.
 
 This applies to the following functions:
 
 - alphabetic
 - alphanumeric
+- any
 - numeric
 
 #### Uppercase
 
-Convert the generated value to uppercase by passing `uppercase=true` argument 
+Convert the generated value to uppercase by passing `uppercase=true` argument into the function.
+
+For example: `${random.alphabetic(uppercase=true)}` will generate an uppercase alphabetic character.
+
+> You can combine `length` and `uppercase` arguments.
+> 
+> For example: `${random.alphabetic(length=5, uppercase=true)}` will generate a 5-character uppercase alphabetic string.
+
+#### Generate from a set of characters
+
+Generate a value from a set of characters by passing `chars="..."` argument into the `random.any()` function.
+
+For example: `${random.any(chars="abc123")}` will generate a value from the set of characters `a`, `b`, `c`, `1`, `2`, `3`.
+
+> You can also use the `length` and `uppercase` arguments with `random.any()`.
+>
+> For example: `${random.any(chars="xyz", length=5, uppercase=true)}` will generate a 5-character uppercase value from the set of characters `x`, `y`, `z`.
 
 ### Items in a Store