Document the use of the input query as character strings

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: osmdata
 Title: Import 'OpenStreetMap' Data as Simple Features or Spatial Objects
-Version: 0.2.5.025
+Version: 0.2.5.026
 Authors@R: c(
     person("Mark", "Padgham", , "[email protected]", role = c("aut", "cre")),
     person("Bob", "Rudis", role = "aut"),

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}. May be be omitted,
-#'      in which case the attributes of the \link{data.frame} will not include
-#'      the 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. 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,13 +2,14 @@
 #' format.
 #'
 #' @param q An object of class `overpass_query` constructed with
-#'      \link{opq} and \link{add_osm_feature}. May be be omitted,
-#'      in which case the \link{osmdata} object will not include the
-#'      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. 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}.
+#'        or an object of class \pkg{xml2} returned from \link{osmdata_xml}.
 #' @param quiet suppress status messages.
 #'
 #' @return An object of class `osmdata` with the OSM components (points, lines,
@@ -22,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}.
+#'   \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) {