feat: experimental `$sql()` method for LazyFrame and DataFrame

[eitsupi]

Same as pola-rs/polars#15783

[eitsupi]

Hmmm, there seems to be errors in building the website. Perhaps a problem with the < escaping process?

[eitsupi]

I checked altdoc:::.rd2qmd("man/DataFrame_sql.Rd", ".", "."). The output qmd file has this:

# Apply transformations to a DataFrame using SQL, aliasing "self" to "frame".
df1$sql(
  query = r"(
SELECT
a,
(a \% 2 == 0) AS a_is_even,
CONCAT_WS(':', b, b) AS b_b,
EXTRACT(year FROM c) AS year,
0::float AS 'zero'
FROM frame
)",
  table_name = "frame"
)

\% should be replaced to %.

[eitsupi]

It seems that this is a bug of tools::parse_Rd().

[eitsupi]

In /tmp/test.Rd

\examples{
a <- "\%"
b <- "
\%
"
c <- r"(
\%
)"
}

> tools::parse_Rd("/tmp/test.Rd")
\examples{
a <- "%"
b <- "
%
"
c <- r"(
\%
)"
}

[eitsupi]

Apparently this is a bug in roxygen2. The following Rd file is fine, so no % escaping is needed here.

\examples{
a <- "\%"
b <- "
%
"
c <- r"(
%
)"
}

I opened an issue r-lib/roxygen2#1616

[eitsupi]

For now, we can use MOD(x, 2) instead of x % 2 to avoid using % in examples.

[eitsupi]

This is a new experimental method addition that does not affect existing code. So merging.