User exception classes, unified exception class architecture

docs/OOP.md

@@ -720,6 +720,23 @@ Notes and limitations (current version):
 - `name` and `ordinal` are read‑only properties of an entry.
 - `entries` is a read‑only list owned by the enum type.
 
+## Exception Classes
+
+You can define your own exception classes by inheriting from the built-in `Exception` class. User-defined exceptions are regular classes and can have their own properties and methods.
+
+```lyng
+class MyError(val code, m) : Exception(m)
+
+try {
+    throw MyError(500, "Internal Server Error")
+}
+catch(e: MyError) {
+    println("Error " + e.code + ": " + e.message)
+}
+```
+
+For more details on error handling, see the [Exceptions Handling Guide](exceptions_handling.md).
+
 ## fields and visibility
 
 It is possible to add non-constructor fields:

docs/exceptions_handling.md

@@ -128,9 +128,9 @@ Serializable class that conveys information about the exception. Important membe
 
 | name              | description                                            |
 |-------------------|--------------------------------------------------------|
-| message           | String message                                         |
-| stackTrace        | lyng stack trace, list of `StackTraceEntry`, see below |
-| printStackTrace() | format and print stack trace using println()           |
+| message           | String message                                           |
+| stackTrace()      | lyng stack trace, list of `StackTraceEntry`, see below   |
+| printStackTrace() | format and print stack trace using println()             |
 
 ## StackTraceEntry
 
@@ -150,24 +150,103 @@ class StackTraceEntry(
 
 # Custom error classes
 
-_this functionality is not yet released_
+You can define your own exception classes by inheriting from the built-in `Exception` class. This allows you to create specific error types for your application logic and catch them specifically.
+
+## Defining a custom exception
+
+To define a custom exception, create a class that inherits from `Exception`:
+
+```lyng
+class MyUserException : Exception("something went wrong")
+```
+
+You can also pass the message dynamically:
+
+```lyng
+class MyUserException(m) : Exception(m)
+
+throw MyUserException("custom error message")
+```
+
+If you don't provide a message to the `Exception` constructor, the class name will be used as the default message:
+
+```lyng
+class SimpleException : Exception
+
+val e = SimpleException()
+assertEquals("SimpleException", e.message)
+```
+
+## Throwing and catching custom exceptions
+
+Custom exceptions are thrown using the `throw` keyword and can be caught using `catch` blocks, just like standard exceptions:
+
+```lyng
+class ValidationException(m) : Exception(m)
+
+try {
+    throw ValidationException("Invalid input")
+}
+catch(e: ValidationException) {
+    println("Caught validation error: " + e.message)
+}
+catch(e: Exception) {
+    println("Caught other exception: " + e.message)
+}
+```
+
+Since user exceptions are real classes, inheritance works as expected:
+
+```lyng
+class BaseError : Exception
+class DerivedError : BaseError
+
+try {
+    throw DerivedError()
+}
+catch(e: BaseError) {
+    // This will catch DerivedError as well
+    assert(e is DerivedError)
+}
+```
+
+## Accessing extra data
+
+You can add your own fields to custom exception classes to carry additional information:
+
+```lyng
+class NetworkException(m, val statusCode) : Exception(m)
+
+try {
+    throw NetworkException("Not Found", 404)
+}
+catch(e: NetworkException) {
+    println("Error " + e.statusCode + ": " + e.message)
+}
+```
 
 # Standard exception classes
 
 | class                      | notes                                                 |
 |----------------------------|-------------------------------------------------------|
-| Exception                  | root of al throwable objects                          |
+| Exception                  | root of all throwable objects                         |
 | NullReferenceException     |                                                       |
 | AssertionFailedException   |                                                       | 
 | ClassCastException         |                                                       |
 | IndexOutOfBoundsException  |                                                       |
 | IllegalArgumentException   |                                                       | 
+| IllegalStateException      |                                                       |
+| NoSuchElementException     |                                                       |
 | IllegalAssignmentException | assigning to val, etc.                                |
 | SymbolNotDefinedException  |                                                       |
 | IterationEndException      | attempt to read iterator past end, `hasNext == false` |
 | IllegalAccessException     | attempt to access private members or like             |
-| UnknownException           | unexpected kotlin exception caught                    |
-|                            |                                                       |
+| UnknownException           | unexpected internal exception caught                  |
+| NotFoundException          |                                                       |
+| IllegalOperationException  |                                                       |
+| UnsetException             | access to uninitialized late-init val                 |
+| NotImplementedException    | used by `TODO()`                                      |
+| SyntaxError                |                                                       |
 
 
 ### Symbol resolution errors

docs/whats_new.md

@@ -139,6 +139,20 @@ var name by Observable("initial") { n, old, new ->
 
 The system features a unified interface (`getValue`, `setValue`, `invoke`) and a `bind` hook for initialization-time validation and configuration. See the [Delegation Guide](delegation.md) for more.
 
+### User-Defined Exception Classes
+You can now create custom exception types by inheriting from the built-in `Exception` class. Custom exceptions are real classes that can have their own fields and methods, and they work seamlessly with `throw` and `try-catch` blocks.
+
+```lyng
+class ValidationException(val field, m) : Exception(m)
+
+try {
+    throw ValidationException("email", "Invalid format")
+}
+catch(e: ValidationException) {
+    println("Error in " + e.field + ": " + e.message)
+}
+```
+
 ### Assign-if-null Operator (`?=`)
 The new `?=` operator provides a concise way to assign a value only if the target is `null`. It is especially useful for setting default values or lazy initialization.