#tonyfettes/any

#Overview

• Store values of any type and retrieve them with type safety
• Transform values between different types with compile-time guarantees
• Chain type-conditional operations on dynamic values
• Get informative error messages when type mismatches occur

#Installation

moon update
moon add tonyfettes/any

#Quick Start

// Store any value
let any = @any.of(42)

// Query type information
@json.inspect(any.type_name(), content="Int")

// Retrieve with type checking
let value : Int = any.to()
@json.inspect(value, content=42)

// Type mismatch raises TypeMismatch error
let value : Result[Bool, @any.TypeMismatch] = try! any.to()
@json.inspect(value, content={
  "Err": { "TypeMismatch": { "expect": "Bool", "actual": "Int" } },
})

#Core API

#Creating Any Values

#Any::of[T](value: T) -> Any

let int_any = @any.of(42)
@json.inspect((int_any.to() : Int))
let str_any = @any.of("hello")
@json.inspect((str_any.to() : String))
let arr_any = @any.of([1, 2, 3])
@json.inspect((arr_any.to() : Array[Int]))

let a0 = @any.of(42)
let a1 = @any.of(a0)
@json.inspect(physical_equal(a0, a1), content=true)

#Type Information

#Any::type_info(self: Any) -> TypeInfo

let any = @any.of([1, 2, 3])
let info = any.type_info()
@json.inspect(
  physical_equal(info.id(), @any.of([1]).type_info().id()),
  content=true,
)
@json.inspect(info.name(), content="Array[Int]")

#Any::type_id(self: Any) -> TypeId

let any = @any.of(42)
let id = any.type_id()
@json.inspect(physical_equal(id, @any.of(100).type_id()), content=true)

#Any::type_name(self: Any) -> String

let any = @any.of("hello")
@json.inspect(any.type_name())
let any = @any.of([1, 2, 3])
@json.inspect(any.type_name(), content="Array[Int]")
let any = @any.of(Some(42))
@json.inspect(any.type_name(), content="Int?")

#Retrieving Values

#Any::to[T](self: Any) -> T raise TypeMismatch

let any = @any.of(42)
let value : Int = any.to()
@json.inspect(value, content=42)
let wrong : Result[String, _] = try! any.to()
@json.inspect(wrong, content={
  "Err": { "TypeMismatch": { "expect": "String", "actual": "Int" } },
})

#Any::try_to[T](self: Any) -> T?

let any = @any.of([1, 2, 3])
let value : Array[Int]? = any.try_to()
@json.inspect(value is Some([1, 2, 3]), content=true)
let wrong : String? = any.try_to()
@json.inspect(wrong is None, content=true)

#Any::unsafe_coerce[T](self: Any) -> T

// Only use when you're absolutely certain about the type
let any = @any.of(42)
let value : Int = any.unsafe_coerce()
@json.inspect(value, content=42)

#Type Transformation

#Any::map[T, R](self: Any, f: (T) -> R raise?) -> Any raise?

fn any_to_int(any : @any.Any) -> Int raise {
  any
  .map((int : Int) => int) // If Int, return as-is
  .map((str : String) => @strconv.parse_int(str)) // If String, parse it
  .map((double : Double) => double.to_int()) // If Double, convert it
  .to() // Finally extract the Int
}

@json.inspect(any_to_int(@any.of(42)))
@json.inspect(any_to_int(@any.of("43")))
@json.inspect(any_to_int(@any.of(44.0)))

• Type-safe dispatching: Handle different types with different logic
• Fallthrough behavior: Non-matching types pass through unchanged
• Exhaustiveness checking: Chain maps to handle all possible types

let any = @any.of("hello")
any
.map((int : Int) => println("Int(\{int})"))
.map((str : String) => println("String(\{str})")) // This executes
.to() // Ensures all cases are handled

#Error Handling

#TypeMismatch

///|
pub suberror TypeMismatch {
  TypeMismatch(expect~ : TypeInfo, actual~ : TypeInfo)
}

• Show: Human-readable error messages
• ToJson: JSON serialization for structured error handling

let any = @any.of([1, 2, 3])
let result : Result[Bool, @any.TypeMismatch] = try! any.to()
@json.inspect(result, content={
  "Err": { "TypeMismatch": { "expect": "Bool", "actual": "Array[Int]" } },
})

TypeMismatch: expected type 'Bool' but found type 'Array[Int]'

{
  "TypeMismatch": {
    "expect": "Bool",
    "actual": "Array[Int]"
  }
}

#Best Practices

1. Prefer static typing: Use Any only when runtime type flexibility is necessary
2. Use try_to() for optional extraction: Allocates less than handling TypeMismatch exceptions
3. Chain map() for exhaustive handling: Ensures all expected types are covered
4. Avoid unsafe_coerce(): Only use when performance is critical and types are guaranteed

#License

#Contributing