Add assert-related testing functions, findFirst/findFirstOrNull methods, and expand documentation.

lynglib/src/commonMain/kotlin/net/sergeych/lyng/Script.kt

@@ -204,7 +204,19 @@ class Script(
                     )
             }
             addFn("assertThrows") {
-                val code = requireOnlyArg<Statement>()
+                val code: Statement
+                val expectedClass: ObjClass?
+                when(args.size) {
+                    1 -> {
+                        code = requiredArg<Statement>(0)
+                        expectedClass = null
+                    }
+                    2 -> {
+                        code = requiredArg<Statement>(1)
+                        expectedClass = requiredArg<ObjClass>(0)
+                    }
+                    else -> raiseIllegalArgument("Expected 1 or 2 arguments, got ${args.size}")
+                }
                 val result = try {
                     code.execute(this)
                     null
@@ -213,7 +225,15 @@ class Script(
                 } catch (_: ScriptError) {
                     ObjNull
                 }
-                result ?: raiseError(ObjAssertionFailedException(this, "Expected exception but nothing was thrown"))
+                if( result == null ) raiseError(ObjAssertionFailedException(this, "Expected exception but nothing was thrown"))
+                expectedClass?.let {
+                    if( result !is ObjException)
+                        raiseError("Expected $expectedClass, got $result")
+                    if (result.exceptionClass != expectedClass) {
+                        raiseError("Expected $expectedClass, got ${result.exceptionClass}")
+                    }
+                }
+                result
             }
 
             addFn("dynamic") {

lynglib/src/commonTest/kotlin/ScriptTest.kt

@@ -4270,4 +4270,18 @@ class ScriptTest {
         assertEquals(51, r.toInt())
     }
 
+    @Test
+    fun testFirstInEnum() = runTest {
+        eval("""
+            enum E {
+                one, two, three 
+            }
+            println(E.entries)
+            assertEquals( E.two, E.entries.findFirst { 
+                println(it.name)
+                it.name in ["aaa", "two"] 
+            } ) 
+            
+        """.trimIndent())
+    }
 }

lynglib/stdlib/lyng/root.lyng

@@ -1,8 +1,8 @@
 package lyng.stdlib
-    
+
 /*
-   Wrap a builder into a zero-argument thunk that computes once and caches the result.
-   The first call invokes builder() and stores the value; subsequent calls return the cached value.
+Wrap a builder into a zero-argument thunk that computes once and caches the result.
+The first call invokes builder() and stores the value; subsequent calls return the cached value.
 */
 fun cached(builder) {
     var calculated = false
@@ -37,9 +37,33 @@ fun Iterable.drop(n) {
 fun Iterable.first() {
     val i = iterator()
     if( !i.hasNext() ) throw NoSuchElementException()
-    i.next().also { i.cancelIteration() }
+        i.next().also { i.cancelIteration() }
 }
 
+/*
+Return the first element that matches the predicate or throws
+NuSuchElementException
+*/
+fun Iterable.findFirst(predicate) {
+    for( x in this ) {
+        if( predicate(x) )
+            break x
+    }
+    else throw NoSuchElementException()
+}
+
+/*
+return the first element matching the predicate or null
+*/
+fun Iterable.findFirstOrNull(predicate) {
+    for( x in this ) {
+        if( predicate(x) )
+            break x
+    }
+    else null
+}
+
+
 /* Return the last element or throw if the iterable is empty. */
 fun Iterable.last() {
     var found = false
@@ -49,7 +73,7 @@ fun Iterable.last() {
         found = true
     }
     if( !found ) throw NoSuchElementException()
-    element
+        element
 }
 
 /* Emit all but the last N elements of this iterable. */
@@ -58,7 +82,7 @@ fun Iterable.dropLast(n) {
     val buffer = RingBuffer(n)
     flow {
         for( item in list ) {
-            if( buffer.size == n ) 
+            if( buffer.size == n )
                 emit( buffer.first() )
             buffer += item
         }
@@ -129,7 +153,7 @@ fun Iterable.minOf( lambda ) {
     minimum
 }
 
-/* Maximum value of the given function applied to elements of the collection. */    
+/* Maximum value of the given function applied to elements of the collection. */
 fun Iterable.maxOf( lambda ) {
     val i = iterator()
     var maximum = lambda( i.next() )
@@ -172,10 +196,10 @@ fun List.sort() {
 
 /* Represents a single stack trace element. */
 class StackTraceEntry(
-    val sourceName: String,
-    val line: Int,
-    val column: Int,
-    val sourceString: String
+        val sourceName: String,
+        val line: Int,
+        val column: Int,
+        val sourceString: String
 ) {
     /* Formatted representation: source:line:column: text. */
     fun toString() {
@@ -194,4 +218,3 @@ fun Exception.printStackTrace() {
 /* Compile this string into a regular expression. */
 fun String.re(): Regex { Regex(this) }
 
-