Skip to content

Commit

Permalink
chore: Add comments to generated code
Browse files Browse the repository at this point in the history
  • Loading branch information
@krlmlr
krlmlr committed Jan 12, 2024
1 parent 463381e commit fcba8b2
Show file tree
Hide file tree
Showing 6 changed files with 334 additions and 0 deletions.
11 changes: 11 additions & 0 deletions R/spec-meta-bind-.R
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,15 @@ test_select_bind_expr <- function(
force(arrow)
force(bind)

caller <- sys.function(-1)
caller_src <- utils::getSrcref(caller)
caller_ref <- paste0("<R/", utils::getSrcFilename(caller_src), ":", utils::getSrcLocation(caller_src), ">")

roxygen_bits <- grep("#' .*$", as.character(caller_src), value = TRUE)
docstring <- gsub("^ +#' *", "", roxygen_bits)

header <- c(caller_ref, docstring)

cast_fun <- enquo(cast_fun)
has_cast_fun <- !quo_is_null(cast_fun)
cast_fun_expr <- if (has_cast_fun) expr({
Expand Down Expand Up @@ -49,6 +58,8 @@ test_select_bind_expr <- function(
})

expr({
!!!header

!!skip_dbitest_expr
!!skip_expr
placeholder_funs <- !!placeholder_funs_expr
Expand Down
72 changes: 72 additions & 0 deletions R/spec-meta-bind-arrow-stream.R
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,11 @@

spec_meta_arrow_stream_bind <- list(
arrow_stream_bind_return_value = function(ctx, con) {
# <R/spec-meta-bind-expr.R:18>
# @return
# `dbBind()` returns the result set,
# invisibly,
# for queries issued by [dbSendQuery()] or [dbSendQueryArrow()] and
placeholder_funs <- get_placeholder_funs(ctx)
is_null_check <- ctx$tweaks$is_null_check
for (placeholder_fun in placeholder_funs) {
Expand Down Expand Up @@ -33,6 +38,9 @@ spec_meta_arrow_stream_bind <- list(
}
},
arrow_stream_bind_too_many = function(ctx, con) {
# <R/spec-meta-bind-expr.R:53>
# @section Failure modes:
# Binding too many
placeholder_funs <- get_placeholder_funs(ctx)
is_null_check <- ctx$tweaks$is_null_check
for (placeholder_fun in placeholder_funs) {
Expand All @@ -56,6 +64,8 @@ spec_meta_arrow_stream_bind <- list(
}
},
arrow_stream_bind_not_enough = function(ctx, con) {
# <R/spec-meta-bind-expr.R:72>
# or not enough values,
placeholder_funs <- get_placeholder_funs(ctx)
is_null_check <- ctx$tweaks$is_null_check
for (placeholder_fun in placeholder_funs) {
Expand All @@ -76,6 +86,8 @@ spec_meta_arrow_stream_bind <- list(
}
},
arrow_stream_bind_wrong_name = function(ctx, con) {
# <R/spec-meta-bind-expr.R:86>
# or parameters with wrong names
placeholder_funs <- get_placeholder_funs(ctx, requires_names = TRUE)
is_null_check <- ctx$tweaks$is_null_check
for (placeholder_fun in placeholder_funs) {
Expand All @@ -95,6 +107,9 @@ spec_meta_arrow_stream_bind <- list(
}
},
arrow_stream_bind_named_param_unnamed_placeholders = function(ctx, con) {
# <R/spec-meta-bind-expr.R:118>
# If the placeholders in the query are named,
# all parameter values must have names
placeholder_funs <- get_placeholder_funs(ctx, requires_names = TRUE)
is_null_check <- ctx$tweaks$is_null_check
for (placeholder_fun in placeholder_funs) {
Expand All @@ -114,6 +129,8 @@ spec_meta_arrow_stream_bind <- list(
}
},
arrow_stream_bind_named_param_empty_placeholders = function(ctx, con) {
# <R/spec-meta-bind-expr.R:134>
# (which must not be empty
placeholder_funs <- get_placeholder_funs(ctx, requires_names = TRUE)
is_null_check <- ctx$tweaks$is_null_check
for (placeholder_fun in placeholder_funs) {
Expand All @@ -137,6 +154,9 @@ spec_meta_arrow_stream_bind <- list(
}
},
arrow_stream_bind_unnamed_param_named_placeholders = function(ctx, con) {
# <R/spec-meta-bind-expr.R:166>
# and vice versa,
# otherwise an error is raised.
placeholder_funs <- get_placeholder_funs(ctx, requires_names = FALSE)
is_null_check <- ctx$tweaks$is_null_check
for (placeholder_fun in placeholder_funs) {
Expand All @@ -156,6 +176,9 @@ spec_meta_arrow_stream_bind <- list(
}
},
arrow_stream_bind_premature_clear = function(ctx, con) {
# <R/spec-meta-bind-expr.R:187>
# Calling `dbBind()` on a result set already cleared by [dbClearResult()]
# also raises an error.
placeholder_funs <- get_placeholder_funs(ctx)
is_null_check <- ctx$tweaks$is_null_check
for (placeholder_fun in placeholder_funs) {
Expand All @@ -172,6 +195,10 @@ spec_meta_arrow_stream_bind <- list(
}
},
arrow_stream_bind_multi_row = function(ctx, con) {
# <R/spec-meta-bind-expr.R:200>
# @section Specification:
# The elements of the `params` argument do not need to be scalars,
# vectors of arbitrary length
placeholder_funs <- get_placeholder_funs(ctx)
is_null_check <- ctx$tweaks$is_null_check
for (placeholder_fun in placeholder_funs) {
Expand All @@ -194,6 +221,12 @@ spec_meta_arrow_stream_bind <- list(
}
},
arrow_stream_bind_multi_row_zero_length = function(ctx, con) {
# <R/spec-meta-bind-expr.R:211>
# (including length 0)
# are supported.
# For queries, calling `dbFetch()` binding such parameters returns
# concatenated results, equivalent to binding and fetching for each set
# of values and connecting via [rbind()].
skip_if_not_dbitest(ctx, "1.7.99.12")
placeholder_funs <- get_placeholder_funs(ctx)
is_null_check <- ctx$tweaks$is_null_check
Expand All @@ -216,6 +249,9 @@ spec_meta_arrow_stream_bind <- list(
}
},
arrow_stream_bind_repeated = function(ctx, con) {
# <R/spec-meta-bind-expr.R:239>
# `dbBind()` also accepts repeated calls on the same result set
# for both queries
placeholder_funs <- get_placeholder_funs(ctx)
is_null_check <- ctx$tweaks$is_null_check
for (placeholder_fun in placeholder_funs) {
Expand Down Expand Up @@ -243,6 +279,9 @@ spec_meta_arrow_stream_bind <- list(
}
},
arrow_stream_bind_repeated_untouched = function(ctx, con) {
# <R/spec-meta-bind-expr.R:265>
# even if no results are fetched between calls to `dbBind()`,
# for both queries
placeholder_funs <- get_placeholder_funs(ctx)
is_null_check <- ctx$tweaks$is_null_check
for (placeholder_fun in placeholder_funs) {
Expand All @@ -266,6 +305,9 @@ spec_meta_arrow_stream_bind <- list(
}
},
arrow_stream_bind_named_param_shuffle = function(ctx, con) {
# <R/spec-meta-bind-expr.R:296>
# If the placeholders in the query are named,
# their order in the `params` argument is not important.
placeholder_funs <- get_placeholder_funs(ctx, requires_names = TRUE)
is_null_check <- ctx$tweaks$is_null_check
for (placeholder_fun in placeholder_funs) {
Expand All @@ -289,6 +331,9 @@ spec_meta_arrow_stream_bind <- list(
}
},
arrow_stream_bind_integer = function(ctx, con) {
# <R/spec-meta-bind-expr.R:312>
# At least the following data types are accepted on input (including [NA]):
# - [integer]
placeholder_funs <- get_placeholder_funs(ctx)
is_null_check <- ctx$tweaks$is_null_check
for (placeholder_fun in placeholder_funs) {
Expand All @@ -315,6 +360,8 @@ spec_meta_arrow_stream_bind <- list(
}
},
arrow_stream_bind_numeric = function(ctx, con) {
# <R/spec-meta-bind-expr.R:322>
# - [numeric]
placeholder_funs <- get_placeholder_funs(ctx)
is_null_check <- ctx$tweaks$is_null_check
for (placeholder_fun in placeholder_funs) {
Expand All @@ -341,6 +388,8 @@ spec_meta_arrow_stream_bind <- list(
}
},
arrow_stream_bind_logical = function(ctx, con) {
# <R/spec-meta-bind-expr.R:331>
# - [logical] for Boolean values
placeholder_funs <- get_placeholder_funs(ctx)
is_null_check <- ctx$tweaks$is_null_check
for (placeholder_fun in placeholder_funs) {
Expand All @@ -366,6 +415,8 @@ spec_meta_arrow_stream_bind <- list(
}
},
arrow_stream_bind_character = function(ctx, con) {
# <R/spec-meta-bind-expr.R:340>
# - [character]
placeholder_funs <- get_placeholder_funs(ctx)
is_null_check <- ctx$tweaks$is_null_check
for (placeholder_fun in placeholder_funs) {
Expand Down Expand Up @@ -397,6 +448,8 @@ spec_meta_arrow_stream_bind <- list(
}
},
arrow_stream_bind_character_escape = function(ctx, con) {
# <R/spec-meta-bind-expr.R:349>
# (also with special characters such as spaces, newlines, quotes, and backslashes)
placeholder_funs <- get_placeholder_funs(ctx)
is_null_check <- ctx$tweaks$is_null_check
for (placeholder_fun in placeholder_funs) {
Expand Down Expand Up @@ -432,6 +485,9 @@ spec_meta_arrow_stream_bind <- list(
}
},
arrow_stream_bind_factor = function(ctx, con) {
# <R/spec-meta-bind-expr.R:358>
# - [factor] (bound as character,
# with warning)
placeholder_funs <- get_placeholder_funs(ctx)
is_null_check <- ctx$tweaks$is_null_check
for (placeholder_fun in placeholder_funs) {
Expand Down Expand Up @@ -463,6 +519,8 @@ spec_meta_arrow_stream_bind <- list(
}
},
arrow_stream_bind_date = function(ctx, con) {
# <R/spec-meta-bind-expr.R:370>
# - [Date]
skip_if(!isTRUE(ctx$tweaks$date_typed))
placeholder_funs <- get_placeholder_funs(ctx)
is_null_check <- ctx$tweaks$is_null_check
Expand Down Expand Up @@ -493,6 +551,8 @@ spec_meta_arrow_stream_bind <- list(
}
},
arrow_stream_bind_date_integer = function(ctx, con) {
# <R/spec-meta-bind-expr.R:380>
# (also when stored internally as integer)
skip_if(!isTRUE(ctx$tweaks$date_typed))
placeholder_funs <- get_placeholder_funs(ctx)
is_null_check <- ctx$tweaks$is_null_check
Expand Down Expand Up @@ -523,6 +583,8 @@ spec_meta_arrow_stream_bind <- list(
}
},
arrow_stream_bind_timestamp = function(ctx, con) {
# <R/spec-meta-bind-expr.R:390>
# - [POSIXct] timestamps
skip_if(!isTRUE(ctx$tweaks$timestamp_typed))
placeholder_funs <- get_placeholder_funs(ctx)
is_null_check <- ctx$tweaks$is_null_check
Expand Down Expand Up @@ -553,6 +615,8 @@ spec_meta_arrow_stream_bind <- list(
}
},
arrow_stream_bind_timestamp_lt = function(ctx, con) {
# <R/spec-meta-bind-expr.R:406>
# - [POSIXlt] timestamps
skip_if(!isTRUE(ctx$tweaks$timestamp_typed))
placeholder_funs <- get_placeholder_funs(ctx)
is_null_check <- ctx$tweaks$is_null_check
Expand Down Expand Up @@ -583,6 +647,8 @@ spec_meta_arrow_stream_bind <- list(
}
},
arrow_stream_bind_time_seconds = function(ctx, con) {
# <R/spec-meta-bind-expr.R:422>
# - [difftime] values
skip_if(!isTRUE(ctx$tweaks$time_typed))
placeholder_funs <- get_placeholder_funs(ctx)
is_null_check <- ctx$tweaks$is_null_check
Expand Down Expand Up @@ -613,6 +679,8 @@ spec_meta_arrow_stream_bind <- list(
}
},
arrow_stream_bind_time_hours = function(ctx, con) {
# <R/spec-meta-bind-expr.R:433>
# (also with units other than seconds
skip_if(!isTRUE(ctx$tweaks$time_typed))
placeholder_funs <- get_placeholder_funs(ctx)
is_null_check <- ctx$tweaks$is_null_check
Expand Down Expand Up @@ -643,6 +711,8 @@ spec_meta_arrow_stream_bind <- list(
}
},
arrow_stream_bind_time_minutes_integer = function(ctx, con) {
# <R/spec-meta-bind-expr.R:444>
# and with the value stored as integer)
skip_if(!isTRUE(ctx$tweaks$time_typed))
placeholder_funs <- get_placeholder_funs(ctx)
is_null_check <- ctx$tweaks$is_null_check
Expand Down Expand Up @@ -673,6 +743,8 @@ spec_meta_arrow_stream_bind <- list(
}
},
arrow_stream_bind_blob = function(ctx, con) {
# <R/spec-meta-bind-expr.R:467>
# - objects of type [blob::blob]
skip_if(isTRUE(ctx$tweaks$omit_blob_tests))
placeholder_funs <- get_placeholder_funs(ctx)
is_null_check <- ctx$tweaks$is_null_check
Expand Down
Loading

0 comments on commit fcba8b2

Please sign in to comment.