| matchConcordance {tools} | R Documentation |
Concordance between source and target lines
Description
The Rd parser records locations in ‘.Rd’ files from
which components of the file are read. Output generators
Rd2HTML and Rd2latex can output
information about these locations as “concordances” between
source and output lines.
matchConcordance converts from output locations
to source locations. The "Rconcordance" method of
as.character produces
strings to embed in output files, and the default method of
as.Rconcordance
converts these back to objects that can be interpreted
by matchConcordance.
Usage
matchConcordance(linenum, concordance)
## S3 method for class 'Rconcordance'
as.character(x, targetfile = "", ...)
as.Rconcordance(x, ...)
followConcordance(concordance, prevConcordance)
Arguments
linenum |
One or more line numbers being queried. |
concordance |
The concordance data for the file containing the lines: an object
of class |
prevConcordance |
A concordance object retrieved from the current file. |
targetfile |
The output filename. |
x |
The object to convert: for |
... |
Further arguments passed to other methods. |
Details
The correspondence between target lines and source lines in Rd file conversion is not one to one. Often a single source line can lead to the generation of multiple output lines, and sometimes more than one source line triggers output on the same output line.
matchConcordance converts from target lines to
source lines. This can be used to help in understanding how
particular output lines
depend on the source, e.g. when an error is found in the
output file. When more than one line contributes
to the output, the last one will be returned.
The "Rconcordance" method of as.character converts a
concordance object
to strings suitable for embedding (e.g. in comments) in an
output file.
The default method of as.Rconcordance searches for strings matching the
pattern of as.character.Rconcordance output, then converts
those lines back to a single concordance.
followConcordance is used when a file is transformed
more than once. The first transformation records a
concordance in the file which is read as prevConcordance.
followConcordance chains this with the current
concordance, relating the final result to the original
source.
There are 3 kinds of objects used to hold concordances.
Objects of class "activeConcordance" are internal to tools; they
are used by Rd2HTML and Rd2latex while building the output
file and saving links to the source file.
Objects of class "Rconcordance" are visible to users.
They are list objects with the following three fields:
offsetThe number of lines of output before the first one corresponding to this concordance.
srcLineFor each line of output after the offset, the corresponding input file line number. There may be more lines of output than the length of
srcLine, in which case nothing can be inferred about the source of those lines.srcFileA vector of filenames of length 1 or the same length as
srcLinegiving the source file(s) for each output line.
Concordance strings are produced by the "Rconcordance" method of
as.character;
they are simply character vectors encoding the concordance data.
The default method of the as.concordance generic function
converts them to "Rconcordance" objects.
Value
matchConcordance returns a character array with one row
per input linenum entry and
two columns, "srcFile" and "srcLine".
For the "Rconcordance" method of as.character, a character
vector used (e.g. in Sweave) to embed
the concordance in a file.
For as.concordance, an "Rconcordance" object, or NULL
if no concordance strings are found.
Author(s)
Duncan Murdoch