Come sfuggire% in programmazione letterata roxygen?
-
23-09-2019 - |
Domanda
Il valore predefinito di un parametro di mia funzione contiene un "%". Questo sembra essere un problema per roxygen, produce un sacco di avvertimenti e di controllo R CMD non riesce quando si cerca di costruire la documentazione in lattice.
Come posso fare questa funzione (e la relativa documentazione) lavoro? Utilizzando %% o \% anziché% non aiuta.
#' Test escape \% from in-source documentation (roxygen).
#'
#' What happens when parameters contain special latex characters?
#'
#' @param x unsuspicious parameter
#' @param format sprintf format string (default "\%5.0f")
#'
#' @return formatted string
#' @export
#' @author Karsten Weinert
testroxy <- function(x, format = "%5.0f") {
sprintf(format,x)
}
Soluzione
#!/usr/bin/perl
use strict;
use File::Temp qw/tempfile/;
use File::Copy;
my $usage = <<EOD
$0 file1.Rd [file2.Rd ...]
When using roxygen to generate documentation for an R pacakge, if a default
argument has a percent sign in it then roxygen will copy it directly into
the .Rd file. Since .Rd is basically latex, this will be interpreted as a
comment and case the file to be parsed incorrectly.
For percent signs elsewhere in your documentation, for example in the
description of one of the parameters, you should use "\%" so parse_Rd
interprets it correctly.
But you cannot do this in the default arguments because they have to be
valid R code, too.
Since the .Rd files are automatically generated they should not have
any latex comments in them anyway.
This script escapes every unescaped % within the file.
The .Rd files are modified in place, since it would be easy to
generate them again with R CMD roxygen.
EOD
;
my $n_tot = 0;
my $n_file = @ARGV;
my $n_esc_file = 0;
foreach my $fn (@ARGV) {
print STDERR ' ' x 100, "\rWorking on $fn\t";
open my $fh, $fn or die "Couldn't open $fn: $!";
my ($tmp_fh, $tmp_fn) = tempfile();
my $n;
while(<$fh>) {
$n += s/(?<!\\)%/\\%/g; # if % is not preceded with backslash then replace it with '\%'
print $tmp_fh $_;
}
$n_tot += $n;
$n_esc_file ++ if $n;
print "Escaped $n '%'\n" if $n;
close $tmp_fh;
move($tmp_fn => $fn);
}
print "\n";
print "$n_file files parsed\n";
print "$n_esc_file contained at least one unescaped %\n";
print "$n_tot total % were escaped\n";
Questa è la mia soluzione poco elegante. Salvare lo script Perl come, ad esempio, escape_percents.pl, allora la sequenza sarebbe come questo:
R CMD roxygen my.package
perl escape_percents.pl my.package.roxygen/man/*.Rd
R CMD install my.package.roxygen
Questo può introdurre più problemi, per esempio se si dispone di codice di esempio utilizzando %% come l'operatore modulo, ma è stato utile per me.
Altri suggerimenti
Codice simile a quello in questione funziona per me senza un problema, e genera la documentazione corretta. Come dicono più commenti, la ragione deve essere che sto usando il pacchetto roxygen2. Quindi, basta usare roxygen2 e poi fuggire "%" nella documentazione usando una barra inversa:
#' The percentage sign is written in the documentation like this: \%.