Improve on scalar object error

[DavisVaughan]

Closes #2061

@MilesMcBain it turns out we already have these two useful FAQ pages:

• https://vctrs.r-lib.org/reference/faq-error-scalar-type.html
• https://vctrs.r-lib.org/reference/howto-faq-fix-scalar-type-error.html

Mimicking some ideas from the Rust compiler, we can link directly to these with cli from the error message

We now throw 3 distinct error messages - @lionel- and @hadley this is your chance to critique these

library(vctrs)

# Scalar
x <- expression()
obj_check_vector(x)
#> Error:
#> ! `x` must be a vector, not an expression vector.
#> ℹ Read our FAQ about scalar types (`?faq_error_scalar_type`) to learn more.

# S3 list
x <- structure(list(), class = "my_list")
obj_check_vector(x)
#> Error:
#> ! `x` must be a vector, not a <my_list> object.
#> ✖ Detected incompatible S3 list. To be a vector, the object must explicitly inherit from <list> or should implement a `vec_proxy()` method. Class: <my_list>.
#> ℹ If this object comes from a package, please report this error to the package author.
#> ℹ Read our FAQ about creating vector types (`?howto_faq_fix_scalar_type_error`) to learn more.

# Incompatible data frame
x <- data_frame(a = 1)
class(x) <- c("data.frame", "my_df")
obj_check_vector(x)
#> Error:
#> ! `x` must be a vector, not a <data.frame> object.
#> ✖ Detected incompatible data frame subclass. To be a vector, the subclass must come before <data.frame> in the class, not after. Class: <data.frame/my_df>.
#> ℹ If this object comes from a package, please report this error to the package author.
#> ℹ Read our FAQ about creating vector types (`?howto_faq_fix_scalar_type_error`) to learn more.

Interactively, cli shows the links as clickable links

It's a bit annoying to improve on x must be a vector, not a <data.frame> object. without more work than I'm willing to put in, but I think the rest of the message clears up this edge case.

[DavisVaughan]

I created underscored aliases for these for use in the cli bullet. In cli's fallback case it shows ?faq_error_scalar_type which doesn't work well with - if you try and copy and paste it in an R console. We've also learned this in the past with ?rlang::args_dots_empty

[hadley]

I'd be tempted to write it like this, where the individual functions know if they're needed or not.

Suggested change

	message <- glue::glue("{arg} must be a vector, not {obj_type_friendly(x)}.")
	if (needs_incompatible_s3_list_bullets(x)) {
	message <- with_incompatible_s3_list_bullets(x, message)
	} else if (needs_incompatible_data_frame_bullets(x)) {
	message <- with_incompatible_data_frame_bullets(x, message)
	} else {
	message <- with_scalar_faq_bullet(message)
	}
	message <- c(
	glue::glue("{arg} must be a vector, not {obj_type_friendly(x)}."),
	incompatible_s3_list_bullets(x),
	incompatible_data_frame_bullets(x),
	scalar_faq_bullet()
	)

(probably tweaking the function names to make it clear they're only generated it needed)

[DavisVaughan]

Yea it's the last one that's the problem. I only want a scalar faq bullet if we don't have a more specific bullet to show first

[hadley]

incompatible_s3_list_bullets(x) %||%
  incompatible_data_frame_bullets(x) %||%
  scalar_faq_bullet()

?

[DavisVaughan]

Oh that's pretty good

[lionel-]

Nice!

[lionel-]

That message is a bit confusing to me. Maybe it's worth expanding a bit:

Suggested change

	"Detected incompatible data frame subclass.",
	"To be a vector, the subclass must come before {.cls data.frame} in the",
	"Detected unexpected data frame structure.",
	"A data frame is normally treated as vector but the detection was thrown off by an unexpected subclass ordering. To be compatible with vctrs, a data frame subclass must come before {.cls data.frame} in the",

[lionel-]

Here I think "incompatible" makes it seem like a valid structure, so "unexpected" is probably better

[DavisVaughan]

I've revised the data frame message in d4a7383 but I do think "incompatible" is still right. It's incompatible with vctrs. I don't want to mention vctrs in the error though, because this error could get thrown from any tidyverse function and the error_call won't mention a vctrs function.

What do you think of the new message?