Roxygen: how to set a default parameter including backslash ('\') to functions

Question

I use Roxygen to generate Rd files of my packages under development, but I have some problems with functions with default parameter set to '\n', e.g.:

  lineCount <- function(text, sep='\n') {
       ...
   }

Which purpose is to count new line ('\n') characters in a string. The problem is that R CMD check gives a warning about:

Codoc mismatches from documentation object 'lineCount':
lineCount
  Code: function(text, sep = "\n")
  Docs: function(text, sep = " ")
  Mismatches in argument default values:
    Name: 'sep' Code: "\n" Docs: " "

The problem seems to me that caused by writing to the Rd file (writing to standard LaTeX files via cat() always requires to double escape characters for some purpose, e.g.: \\newline - as I experienced). If I put an extra backslash to the separator, like:

  lineCount <- function(text, sep='\\n') {
       ...
   }

The problem still presists, as in the code it looks like '\\n', but in the docs (Rd files) it looks '\n'.

Is there an easy solution for my problem? May be an extra tag in Roxygen which could define how to write the function's params to the Rd file? Sorry if asked too obvious a question, but I am lost after Google-ing for a while.

---

History: http://permalink.gmane.org/gmane.comp.lang.r.roxygen/24

---

UPDATE: use roxygen2!

Idio

It's a straightforward bug in roxygen, and shouldn't need any extra configuration. From what I here roxygen development is set up to take off again in the near future, so hopefully it will be fixed soon. – Schuck

Thanks Hadley, that makes clear things. – Idio

Could you try only counting "\" as opposed to counting "\n"? – Gudrin

I'm now experiencing similar problem with non-ASCII chars, e.g. param="\u279B". (using roxygen2 v6.0.1) – Sesquipedalian

I found a nice workaround using intToUtf8(), see my answer below ... – Sesquipedalian

Answer 1

I also ran into problems with too much escaped " and vanishing \t. I ended up changing the parse.formals function in roxygen's Rd2.R as follows:

  parse.formals <- function(partitum) {
    formals <- partitum$formals
    if (!is.null(formals)) {
      formals <- lapply(formals, trim)
      formals <- lapply(formals, paste, collapse=" ")
      name.defaults <- zip.c(names(formals), formals)
      args <-
        do.call(paste, c(Map(function(name.default) {
          name <- car(name.default)
          default <- cadr(name.default)
          if (! is.character (default)) {  # too much escaped. 
                                           # Not sure when escaping is needed. 
                                           # param = c ("x", "y", "z") works now
            default <- gsubfn("\"(.*)\"",
                              function(x)
                              sprintf("\"%s\"", gsub("\"", "\\\\\"", x)),
                              as.character(default))
          }
          default <- gsub ("\t", "\\\\t", default) # the tabs and newlines are already
          default <- gsub ("\n", "\\\\n", default) # tab and newline here.
          if (is.null.string(default))
            name
          else
            sprintf('%s=%s', name, default)
        },
                             name.defaults),
                         sep=', '))

      append.Rd(usageTag(parse.function.name(partitum), args))
    }
  }

Hope that helps and doesn't break anything else.

Tomfool

Thanks @Tomfool for the modification, it seems to work inmy case (+1). Posting a nice and elegant patch to the developers might be a good idea also :) – Idio

I'd do that, no problem - however I'm really not sure about unwanted side effects here. I guess there was a reason why the " were escaped. I'll suggest escaping the tab and newlines, though. BTW: seems to me something happened to the project - for the last months the mailing list and bug & feature tracker show no activity from the developers. So let's hope for Hadley's near future. – Tomfool

That is right. Though I see frequent updates made by @Schuck on github.com/klutometis/roxygen – Idio

I know of Hadley's branch. However, afaik he forked off quite a while ago both his and the original roxygen meanwhile saw quite some improvements (original wrt S4 - which is the stuff I need, Hadley's in speed). I had a short look at his some weeks ago, but unfortunately I don't have the time to understand both systems and merge the S4 stuff with his. However, Hadley, if you read here: of course you're also welcome to patches. just let me know. – Tomfool

Sorry, I was confused - Now with roxygen2 all is going to be well, I hope :-) – Tomfool

Answer 2

I came across this problem also, i.e. I had split="\+" and split="\|" in various functions.

The .Rd files actually also represent these as split="\+" and split="\|", but then whatever reads .Rd files in R CMD check turned them into split="+" and split="\|", and caused the error.

If the .Rd files had split="\\+" and split="\\|" it would then get read correctly.

My solution was to run this on the /man/ directory with the .Rd files, just before R CMD check:

perl -e 's/("\\\|")/"\\\\\|"/g;' -pi $(find BioGeoBEARS/man -type f)

perl -e 's/("\\+")/"\\\\+"/g;' -pi $(find BioGeoBEARS/man -type f)

Took a bit of trial and error, but it works!

Cheers! Nick

Cartogram

Answer 3

I had the same problem. I ended-up overriding default usage field as produced by roxygen from the source code with @usage. E.g. the R source file contains

#' @usage sourceall(dir = getwd(), pattern = ".*\\\\.R", ...)
sourceall <- function( dir=getwd(), pattern=".*\\.R", ... )
{
    blah blah
}

Switzerland

Answer 4

I experienced similar problem with roxygen2 v6.0.1.

# this caused errors in R CMD check (non-ASCII chars)
f <- function(x, y, chr = "\u279B")

# this was ok
f <- function(x, y, chr = intToUtf8(0x279B))

In your case, with the newline character, it should also work:

lineCount <- function(text, sep = intToUtf8(10))

Sesquipedalian

Answer 5

Well, frack me, the comment box escapes backslash characters! I refuse to add to the madness and add backslashes to escape the blackslashes in the perl code which escape the backslashes in the .Rd files which escape the backlashes in R.

Just double all backslashes.

Or hmm code tags:

perl -e 's/("\\\\\|")/"\\\\\\\\\|"/g;' -pi $(find BioGeoBEARS/man -type f)

perl -e 's/("\\\\\+")/"\\\\\\\\\+"/g;' -pi $(find BioGeoBEARS/man -type f)

Yeah that's good.

Cartogram