more descriptive error when unknown Legolas.Schema is encountered (#28)

Project.toml

@@ -1,7 +1,7 @@
 name = "Legolas"
 uuid = "741b9549-f6ed-4911-9fbf-4a1c0c97f0cd"
 authors = ["Beacon Biosignals, Inc."]
-version = "0.3.0"
+version = "0.3.1"
 
 [deps]
 Arrow = "69666777-d1a9-59fb-9406-91d4454c9d45"

src/rows.jl

@@ -84,14 +84,35 @@ Return the `Legolas.Schema` instance that corresponds to the parent of the given
 @inline schema_parent(::Type{<:Schema}) = nothing
 @inline schema_parent(schema::Schema) = schema_parent(typeof(schema))
 
-"""
-    schema_qualified_string(::Legolas.Schema{name,version})
+Base.show(io::IO, schema::Schema) = print(io, "Schema(\"$(schema_name(schema))@$(schema_version(schema))\")")
 
-Return this `Legolas.Schema`'s fully qualified schema identifier string. This string is
-serialized as the `\"$LEGOLAS_SCHEMA_QUALIFIED_METADATA_KEY\"`` field value in table
-metadata for table written via [`Legolas.write`](@ref).
-"""
-function schema_qualified_string end
+#####
+##### methods overloaded by `@row`
+#####
+
+struct UnknownSchemaError <: Exception
+    schema::Legolas.Schema
+end
+
+function Base.showerror(io::IO, e::UnknownSchemaError)
+    print(io, """
+              encountered unknown `Legolas.Schema` type: $(e.schema)
+
+              This generally indicates that this schema has not been defined (i.e.
+              the schema's corresponding `@row` statement has not been executed) in
+              the current Julia session.
+
+              In practice, this can arise if you try to read a Legolas table with a
+              prescribed schema, but haven't actually loaded the schema definition
+              (or commonly, haven't loaded the dependency that contains the schema
+              definition - check the versions of loaded packages/modules to confirm
+              your environment is as expected).
+
+              Note that if you're in this particular situation, you can still load
+              the raw Arrow table as-is via `Arrow.Table`.
+              """)
+    return nothing
+end
 
 # Note that there exist very clean generic implementations of `transform`/`validate`:
 #
@@ -112,7 +133,7 @@ function schema_qualified_string end
 # unnecessarily for schemas with a few ancestors, while the "hardcoded" versions
 # generated by the current implementation of the `@row` macro (see below) do not.
 
-function transform end
+transform(s::Legolas.Schema; fields...) = throw(UnknownSchemaError(s))
 
 function _transform end
 
@@ -127,7 +148,7 @@ Specifically, `tables_schema` is considered to comply with `legolas_schema` if:
 - every non-`>:Missing` field required by `legolas_schema` is present in `tables_schema`.
 - `T <: S` for each field `f::T` in `tables_schema` that matches a required `legolas_schema` field `f::S`.
 """
-function validate end
+validate(::Tables.Schema, s::Legolas.Schema) = throw(UnknownSchemaError(s))
 
 function _validate end
 
@@ -141,7 +162,14 @@ function validate_expected_field(schema::Tables.Schema, name::Symbol, ::Type{T})
     return nothing
 end
 
-Base.show(io::IO, schema::Schema) = print(io, "Schema(\"$(schema_name(schema))@$(schema_version(schema))\")")
+"""
+    schema_qualified_string(::Legolas.Schema{name,version})
+
+Return this `Legolas.Schema`'s fully qualified schema identifier string. This string is
+serialized as the `\"$LEGOLAS_SCHEMA_QUALIFIED_METADATA_KEY\"`` field value in table
+metadata for table written via [`Legolas.write`](@ref).
+"""
+schema_qualified_string(s::Legolas.Schema) = throw(UnknownSchemaError(s))
 
 #####
 ##### Row

test/runtests.jl

@@ -108,6 +108,9 @@ end
 
     t = [(a="a", c=1, b="b"), Baz(a=1, b=2)] # not a valid Tables.jl table
     @test_throws ErrorException Legolas.validate(t, Schema("baz", 1))
+
+    t = Arrow.tobuffer((a=[1, 2], b=[3, 4]); metadata=Dict(Legolas.LEGOLAS_SCHEMA_QUALIFIED_METADATA_KEY => "haha@3"))
+    @test_throws Legolas.UnknownSchemaError Legolas.read(t)
 end
 
 @testset "miscellaneous Legolas.Schema / Legolas.Row tests" begin
@@ -133,6 +136,10 @@ end
 
     long_row = Row(Schema("bar", 1), (x=1, y=2, z=zeros(100, 100)))
     @test length(sprint(show, long_row; context=(:limit => true))) < 200
+
+    @test_throws Legolas.UnknownSchemaError Legolas.transform(Legolas.Schema("imadethisup@3"); a = 1, b = 2)
+    @test_throws Legolas.UnknownSchemaError Legolas.validate(Tables.Schema((:a, :b), (Int, Int)), Legolas.Schema("imadethisup@3"))
+    @test_throws Legolas.UnknownSchemaError Legolas.schema_qualified_string(Legolas.Schema("imadethisup@3"))
 end
 
 @testset "isequal, hash" begin