Eliminate tag registry in favour of S3 method

Author: hadley

NAMESPACE

@@ -74,9 +74,62 @@ S3method(roclet_preprocess,roclet_namespace)
 S3method(roclet_process,roclet_namespace)
 S3method(roclet_process,roclet_rd)
 S3method(roclet_process,roclet_vignette)
-S3method(roclet_tags,roclet_namespace)
-S3method(roclet_tags,roclet_rd)
-S3method(roclet_tags,roclet_vignette)
+S3method(roxy_tag_parse,default)
+S3method(roxy_tag_parse,roxy_tag_aliases)
+S3method(roxy_tag_parse,roxy_tag_author)
+S3method(roxy_tag_parse,roxy_tag_backref)
+S3method(roxy_tag_parse,roxy_tag_concept)
+S3method(roxy_tag_parse,roxy_tag_describeIn)
+S3method(roxy_tag_parse,roxy_tag_description)
+S3method(roxy_tag_parse,roxy_tag_details)
+S3method(roxy_tag_parse,roxy_tag_docType)
+S3method(roxy_tag_parse,roxy_tag_encoding)
+S3method(roxy_tag_parse,roxy_tag_eval)
+S3method(roxy_tag_parse,roxy_tag_evalNamespace)
+S3method(roxy_tag_parse,roxy_tag_evalRd)
+S3method(roxy_tag_parse,roxy_tag_example)
+S3method(roxy_tag_parse,roxy_tag_examples)
+S3method(roxy_tag_parse,roxy_tag_export)
+S3method(roxy_tag_parse,roxy_tag_exportClass)
+S3method(roxy_tag_parse,roxy_tag_exportMethod)
+S3method(roxy_tag_parse,roxy_tag_exportPattern)
+S3method(roxy_tag_parse,roxy_tag_exportS3Method)
+S3method(roxy_tag_parse,roxy_tag_family)
+S3method(roxy_tag_parse,roxy_tag_field)
+S3method(roxy_tag_parse,roxy_tag_format)
+S3method(roxy_tag_parse,roxy_tag_import)
+S3method(roxy_tag_parse,roxy_tag_importClassesFrom)
+S3method(roxy_tag_parse,roxy_tag_importFrom)
+S3method(roxy_tag_parse,roxy_tag_importMethodsFrom)
+S3method(roxy_tag_parse,roxy_tag_include)
+S3method(roxy_tag_parse,roxy_tag_includeRmd)
+S3method(roxy_tag_parse,roxy_tag_inherit)
+S3method(roxy_tag_parse,roxy_tag_inheritDotParams)
+S3method(roxy_tag_parse,roxy_tag_inheritParams)
+S3method(roxy_tag_parse,roxy_tag_inheritSection)
+S3method(roxy_tag_parse,roxy_tag_keywords)
+S3method(roxy_tag_parse,roxy_tag_md)
+S3method(roxy_tag_parse,roxy_tag_method)
+S3method(roxy_tag_parse,roxy_tag_name)
+S3method(roxy_tag_parse,roxy_tag_noMd)
+S3method(roxy_tag_parse,roxy_tag_noRd)
+S3method(roxy_tag_parse,roxy_tag_note)
+S3method(roxy_tag_parse,roxy_tag_order)
+S3method(roxy_tag_parse,roxy_tag_param)
+S3method(roxy_tag_parse,roxy_tag_rawNamespace)
+S3method(roxy_tag_parse,roxy_tag_rawRd)
+S3method(roxy_tag_parse,roxy_tag_rdname)
+S3method(roxy_tag_parse,roxy_tag_references)
+S3method(roxy_tag_parse,roxy_tag_return)
+S3method(roxy_tag_parse,roxy_tag_section)
+S3method(roxy_tag_parse,roxy_tag_seealso)
+S3method(roxy_tag_parse,roxy_tag_slot)
+S3method(roxy_tag_parse,roxy_tag_source)
+S3method(roxy_tag_parse,roxy_tag_template)
+S3method(roxy_tag_parse,roxy_tag_templateVar)
+S3method(roxy_tag_parse,roxy_tag_title)
+S3method(roxy_tag_parse,roxy_tag_usage)
+S3method(roxy_tag_parse,roxy_tag_useDynLib)
 export(block_get_tag)
 export(block_get_tag_value)
 export(block_get_tags)
@@ -106,6 +159,7 @@ export(roclet_process)
 export(roclet_tags)
 export(roxy_block)
 export(roxy_tag)
+export(roxy_tag_parse)
 export(roxy_tag_warning)
 export(roxygenise)
 export(roxygenize)

NEWS.md

@@ -1,5 +1,16 @@
 # roxygen2 (development version)
 
+* `roclet_tags()` is no longer used; instead define a `roxy_tag_parse()` method.
+  If you tag is `@mytag`, then the class name associated with it is
+  `roxy_tag_mytag` so the method should be call `roxy_tag_parse.roxy_tag_mytag()`.
+  Note that there is no namespacing so if you're defining multiple new tags
+  I recommend using your package name as common prefix.
+  
+    This means that the `registry` argument is no longer needed and has been
+    removed.
+
+* `tag_two_part()` and `tag_words()` are now regular functions.
+
 * The internal `roxy_tag()` gains a new field: `raw`. This now always contains
   the raw string value parsed from the file. `val` is only set after the tag
   has been parsed.
@@ -172,11 +183,6 @@
 * `tag_markdown_restricted()` has been removed because it did exactly the
   same think as `tag_markdown()`.
 
-* Roclets have now aliases to all the tags that they define so that you can
-  do (e.g.) `?"@export"`. These help files are generally not that useful, but
-  they do now provide basic examples, and point you towards the vignettes the
-  provide full details.
-
 * Package documentation now converts ORCIDs into a useful link (#721).
 
 * Empty roxygen2 lines at the start of a block are now silently removed (#710).

R/block.R

@@ -74,13 +74,9 @@ print.roxy_block <- function(x, ...) {
 }
 
 block_create <- function(tokens, call, srcref,
-                         registry = list(),
                          global_options = list()) {
 
-  tags <- parse_tags(tokens,
-    registry = registry,
-    global_options = global_options
-  )
+  tags <- parse_tags(tokens, global_options = global_options)
   if (length(tags) == 0) return()
 
   roxy_block(tags,
@@ -91,17 +87,15 @@ block_create <- function(tokens, call, srcref,
 }
 
 block_set_env <- function(block, env,
-                          registry = list(),
                           global_options = list()
                           ) {
 
-  block <- block_evaluate(block, env, registry = registry, global_options = global_options)
+  block <- block_evaluate(block, env, global_options = global_options)
   block <- block_find_object(block, env)
   block
 }
 
 block_evaluate <- function(block, env,
-                           registry = list(),
                            global_options = list()
                            ) {
 
@@ -125,10 +119,7 @@ block_evaluate <- function(block, env,
     file = block$file,
     offset = block$line
   )
-  tags <- lapply(tokens, parse_tags,
-    registry = registry,
-    global_options = global_options
-  )
+  tags <- lapply(tokens, parse_tags, global_options = global_options)
 
   # Interpolate results back into original locations
   block_replace_tags(block, "eval", tags)
@@ -208,27 +199,21 @@ block_replace_tags <- function(block, tags, values) {
 
 # parsing -----------------------------------------------------------------
 
-parse_tags <- function(tokens, registry = list(), global_options = list()) {
+parse_tags <- function(tokens, global_options = list()) {
   markdown_activate(tokens, global_options = global_options)
 
   tokens <- parse_description(tokens)
-  compact(lapply(tokens, parse_tag, registry = registry))
+  compact(lapply(tokens, roxy_tag_parse))
 }
 
-parse_tag <- function(x, registry) {
-  stopifnot(is.roxy_tag(x))
-
-  if (identical(x$tag, "eval")) {
-    tag_code(x)
-  } else if (identical(x$tag, "include")) {
-    tag_value(x)
-  } else if (identical(x$tag, "order")) {
-    tag_value(x)
-  } else if (x$tag %in% ls(registry)) {
-    registry[[x$tag]](x)
-  } else {
-    roxy_tag_warning(x, "unknown tag")
-  }
+#' @export
+roxy_tag_parse.roxy_tag_eval <- function(x) {
+  tag_code(x)
+}
+
+#' @export
+roxy_tag_parse.roxy_tag_include <- function(x) {
+  tag_value(x)
 }
 
 parse_description <- function(tags) {

R/namespace.R

@@ -33,7 +33,6 @@ ns_tags <- c(
 #'
 #' @family roclets
 #' @export
-#' @eval tag_aliases(roclet_tags.roclet_namespace)
 #' @examples
 #' # The most common namespace tag is @@export, which declares that a function
 #' # is part of the external interface of your package
@@ -79,22 +78,29 @@ roclet_process.roclet_namespace <- function(x,
 }
 
 #' @export
-roclet_tags.roclet_namespace <- function(x) {
-  list(
-    evalNamespace = tag_code,
-    export = tag_words_line,
-    exportClass = tag_words(1),
-    exportS3Method = tag_words(min = 0, max = 2),
-    exportMethod = tag_words(1),
-    exportPattern = tag_words(1),
-    import = tag_words(1),
-    importClassesFrom = tag_words(2),
-    importFrom = tag_words(2),
-    importMethodsFrom = tag_words(2),
-    rawNamespace = tag_code,
-    useDynLib = tag_words(1)
-  )
-}
+roxy_tag_parse.roxy_tag_evalNamespace <- function(x) tag_code(x)
+#' @export
+roxy_tag_parse.roxy_tag_export <- function(x) tag_words_line(x)
+#' @export
+roxy_tag_parse.roxy_tag_exportClass <- function(x) tag_words(x, 1)
+#' @export
+roxy_tag_parse.roxy_tag_exportS3Method <- function(x) tag_words(x, min = 0, max = 2)
+#' @export
+roxy_tag_parse.roxy_tag_exportMethod <- function(x) tag_words(x, min = 1)
+#' @export
+roxy_tag_parse.roxy_tag_exportPattern <- function(x) tag_words(x, min = 1)
+#' @export
+roxy_tag_parse.roxy_tag_import <- function(x) tag_words(x, min = 1)
+#' @export
+roxy_tag_parse.roxy_tag_importClassesFrom <- function(x) tag_words(x, min = 2)
+#' @export
+roxy_tag_parse.roxy_tag_importFrom <- function(x) tag_words(x, min = 2)
+#' @export
+roxy_tag_parse.roxy_tag_importMethodsFrom <- function(x) tag_words(x, min = 2)
+#' @export
+roxy_tag_parse.roxy_tag_rawNamespace <- function(x) tag_code(x)
+#' @export
+roxy_tag_parse.roxy_tag_useDynLib <- function(x) tag_words(x, min = 1)
 
 #' @export
 roclet_output.roclet_namespace <- function(x, results, base_path, ...) {

R/parse.R

@@ -15,9 +15,6 @@
 #'    You can also set to `NULL` if you only want to get the tokenized code
 #'    blocks only. This suppresses evaluation of `@eval` tags, and will not
 #'    find the code object associated with each block.
-#' @param registry A roclet tag registry: this is a named list where the
-#'    name gives the tag and the value gives the parsing code. See the
-#'    `tag_` functions in [roxy_tag] for built-in options.
 #' @param global_options A list of global options:
 #'
 #'  * `wrap` Logical; should roxygen2 output be wrapped? `FALSE` by default.
@@ -27,13 +24,11 @@
 #' @keywords internal
 parse_package <- function(path = ".",
                           env = env_package(path),
-                          registry = default_tags(),
                           global_options = list()
                           ) {
 
   files <- package_files(path)
   list_of_blocks <- lapply(files, tokenize_file,
-    registry = registry,
     global_options = global_options
   )
 
@@ -42,7 +37,6 @@ parse_package <- function(path = ".",
   if (!is.null(env)) {
     blocks <- lapply(blocks, block_set_env,
       env = env,
-      registry = registry,
       global_options = global_options
     )
   }
@@ -55,20 +49,17 @@ parse_package <- function(path = ".",
 #' @rdname parse_package
 parse_file <- function(file,
                        env = env_file(file),
-                       registry = default_tags(),
                        global_options = list(),
                        srcref_path = NULL) {
 
   blocks <- tokenize_file(file,
-    registry = registry,
     global_options = global_options,
     srcref_path = srcref_path
   )
 
   if (!is.null(env)) {
     blocks <- lapply(blocks, block_set_env,
       env = env,
-      registry = registry,
       global_options = global_options
     )
   }
@@ -81,7 +72,6 @@ parse_file <- function(file,
 #' @rdname parse_package
 parse_text <- function(text,
                        env = env_file(file),
-                       registry = default_tags(),
                        global_options = list()) {
 
   file <- tempfile()
@@ -91,7 +81,6 @@ parse_text <- function(text,
   blocks <- parse_file(
     file,
     env = env,
-    registry = registry,
     global_options = global_options,
     srcref_path = "<text>"
   )
@@ -130,3 +119,8 @@ order_blocks <- function(blocks) {
   ord <- vapply(blocks, block_order, double(1))
   blocks[order(ord)]
 }
+
+#' @export
+roxy_tag_parse.roxy_tag_order <- function(x) {
+  tag_value(x)
+}

R/rd-template.R

@@ -34,10 +34,7 @@ process_templates <- function(block, base_path, global_options = list()) {
 
   results <- lapply(paths, template_eval, vars = list2env(vars))
   tokens <- lapply(results, tokenise_block, file = "TEMPLATE", offset = 0L)
-  tags <- lapply(tokens, parse_tags,
-    registry = roclet_tags.roclet_rd(list()),
-    global_options = global_options
-  )
+  tags <- lapply(tokens, parse_tags, global_options = global_options)
 
   # Insert templates back in the location where they came from
   block_replace_tags(block, "template", tags)