Add examples of input query as character strings

NEWS.md

@@ -13,6 +13,7 @@
 - Mention key-only feature requests in README (#342 thanks to @joostschouppe)
 - Merge any columns in `osmdata_sf()` with mixed-case duplicated names (#348)
 - Set encoding to UTF-8 for tags and user names (#347)
+- Document the use of the input query as character strings for `osmdata_*()` (#349)
 
 
 0.2.5

R/get-osmdata-df.R

@@ -3,9 +3,10 @@
 #'
 #' @inheritParams osmdata_sp
 #' @param q An object of class `overpass_query` constructed with
-#'      \link{opq} and \link{add_osm_feature} or a string with a valid query.
+#'      \link{opq} and \link{add_osm_feature} or a string with a valid query, such
+#'      as `"(node(39.4712701,-0.3841326,39.4713799,-0.3839475);); out;"`.
 #'      May be be omitted, in which case the attributes of the \link{data.frame}
-#'      will not include the query.
+#'      will not include the query. See examples below.
 #' @param stringsAsFactors Should character strings in the 'data.frame' be
 #'      coerced to factors?
 #' @return A `data.frame` with id, type and tags of the the objects from the
@@ -27,6 +28,24 @@
 #' attr (hampi_df, "bbox")
 #' attr (hampi_df, "overpass_call")
 #' attr (hampi_df, "meta")
+#'
+#' # Complex query as a string (not possible with regular osmdata functions)
+#' q <- '[out:csv(::type, ::id, "name:ca", "wikidata")][timeout:50];
+#'     area["name"="Països Catalans"][boundary=political]->.boundaryarea;
+#'
+#'     rel(area.boundaryarea)[admin_level=8][boundary=administrative];
+#'     map_to_area -> .all_level_8_areas;
+#'
+#'     ( nwr(area.boundaryarea)["amenity"="townhall"];>;);
+#'     is_in;
+#'     area._[admin_level=8][boundary=administrative] -> .level_8_areas_with_townhall;
+#'
+#'     (.all_level_8_areas; - .level_8_areas_with_townhall;);
+#'     rel(pivot);
+#'     out tags;'
+#'
+#' no_townhall <- osmdata_data_frame (q)
+#' no_townhall
 #' }
 osmdata_data_frame <- function (q,
                                 doc,

R/get-osmdata-sc.R

@@ -16,6 +16,25 @@
 #' hampi_sf <- opq ("hampi india") %>%
 #'     add_osm_feature (key = "historic", value = "ruins") %>%
 #'     osmdata_sc ()
+#'
+#' # Complex query as a string (not possible with regular osmdata functions)
+#' q <- '[out:xml][timeout:50];
+#'     area["name"="Països Catalans"][boundary=political]->.boundaryarea;
+#'
+#'     rel(area.boundaryarea)[admin_level=8][boundary=administrative];
+#'     map_to_area -> .all_level_8_areas;
+#'
+#'     ( nwr(area.boundaryarea)["amenity"="townhall"];>;);
+#'     is_in;
+#'     area._[admin_level=8][boundary=administrative] -> .level_8_areas_with_townhall;
+#'
+#'     (.all_level_8_areas; - .level_8_areas_with_townhall;);
+#'     rel(pivot);
+#'     (._;>;);
+#'     out;'
+#'
+#' no_townhall <- osmdata_sc (q)
+#' no_townhall
 #' }
 osmdata_sc <- function (q, doc, quiet = TRUE) {
 
@@ -76,7 +95,7 @@ osmdata_sc <- function (q, doc, quiet = TRUE) {
     )
 
     has_tags <- c ("nodes", "relation_properties", "object")
-    obj [has_tags] <- lapply(obj [has_tags], function (x) {
+    obj [has_tags] <- lapply (obj [has_tags], function (x) {
         x [, c ("key", "value")] <- setenc_utf8 (x [, c ("key", "value")])
         x
     })

R/get-osmdata-sf.R

@@ -15,6 +15,25 @@
 #' hampi_sf <- opq ("hampi india") %>%
 #'     add_osm_feature (key = "historic", value = "ruins") %>%
 #'     osmdata_sf ()
+#'
+#' # Complex query as a string (not possible with regular osmdata functions)
+#' q <- '[out:xml][timeout:50];
+#'     area["name"="Països Catalans"][boundary=political]->.boundaryarea;
+#'
+#'     rel(area.boundaryarea)[admin_level=8][boundary=administrative];
+#'     map_to_area -> .all_level_8_areas;
+#'
+#'     ( nwr(area.boundaryarea)["amenity"="townhall"];>;);
+#'     is_in;
+#'     area._[admin_level=8][boundary=administrative] -> .level_8_areas_with_townhall;
+#'
+#'     (.all_level_8_areas; - .level_8_areas_with_townhall;);
+#'     rel(pivot);
+#'     (._;>;);
+#'     out;'
+#'
+#' no_townhall <- osmdata_sf (q)
+#' no_townhall
 #' }
 osmdata_sf <- function (q, doc, quiet = TRUE, stringsAsFactors = FALSE) { # nolint
 

R/get-osmdata-sp.R

@@ -2,9 +2,11 @@
 #' format.
 #'
 #' @param q An object of class `overpass_query` constructed with
-#'      \link{opq} and \link{add_osm_feature} or a string with a valid query.
+#'      \link{opq} and \link{add_osm_feature} or a string with a valid query, such
+#'      as `"(node(39.4712701,-0.3841326,39.4713799,-0.3839475);); out;"`.
+#'      39.4712701,-0.3841326,39.4713799,-0.3839475
 #'      May be be omitted, in which case the \link{osmdata} object will not
-#'      include the query.
+#'      include the query. See examples below.
 #' @param doc If missing, `doc` is obtained by issuing the overpass query,
 #'        `q`, otherwise either the name of a file from which to read data,
 #'        or an object of class \pkg{xml2} returned from \link{osmdata_xml}.
@@ -21,6 +23,25 @@
 #' hampi_sp <- opq ("hampi india") %>%
 #'     add_osm_feature (key = "historic", value = "ruins") %>%
 #'     osmdata_sp ()
+#'
+#' # Complex query as a string (not possible with regular osmdata functions)
+#' q <- '[out:xml][timeout:50];
+#'     area["name"="Països Catalans"][boundary=political]->.boundaryarea;
+#'
+#'     rel(area.boundaryarea)[admin_level=8][boundary=administrative];
+#'     map_to_area -> .all_level_8_areas;
+#'
+#'     ( nwr(area.boundaryarea)["amenity"="townhall"];>;);
+#'     is_in;
+#'     area._[admin_level=8][boundary=administrative] -> .level_8_areas_with_townhall;
+#'
+#'     (.all_level_8_areas; - .level_8_areas_with_townhall;);
+#'     rel(pivot);
+#'     (._;>;);
+#'     out;'
+#'
+#' no_townhall <- osmdata_sp (q)
+#' no_townhall
 #' }
 osmdata_sp <- function (q, doc, quiet = TRUE) {
 

R/get-osmdata-xml.R

@@ -3,7 +3,8 @@
 #' or a raw vector.
 #'
 #' @param q An object of class `overpass_query` constructed with
-#' \link{opq} and \link{add_osm_feature} or a string with a valid query.
+#'   \link{opq} and \link{add_osm_feature} or a string with a valid query, such
+#'   as `"(node(39.4712701,-0.3841326,39.4713799,-0.3839475);); out;"`. See examples below.
 #' @param filename If given, OSM data are saved to the named file
 #' @param quiet suppress status messages.
 #' @param encoding Unless otherwise specified XML documents are assumed to be
@@ -23,6 +24,24 @@
 #' q <- opq ("hampi india")
 #' q <- add_osm_feature (q, key = "historic", value = "ruins")
 #' osmdata_xml (q, filename = "hampi.osm")
+#'
+#' # Complex query as a string (not possible with regular osmdata functions)
+#' q <- '[out:xml][timeout:50];
+#'     area["name"="Països Catalans"][boundary=political]->.boundaryarea;
+#'
+#'     rel(area.boundaryarea)[admin_level=8][boundary=administrative];
+#'     map_to_area -> .all_level_8_areas;
+#'
+#'     ( nwr(area.boundaryarea)["amenity"="townhall"];>;);
+#'     is_in;
+#'     area._[admin_level=8][boundary=administrative] -> .level_8_areas_with_townhall;
+#'
+#'     (.all_level_8_areas; - .level_8_areas_with_townhall;);
+#'     rel(pivot);
+#'     out tags;'
+#'
+#' no_townhall <- osmdata_xml (q)
+#' no_townhall
 #' }
 osmdata_xml <- function (q, filename, quiet = TRUE, encoding) {